feat(agent): bootstrap FastAPI agent service

.pre-commit-config.yaml

@@ -19,14 +19,32 @@ repos:
         language: system
         files: ^backend/.*\.py$
         pass_filenames: false
+      - id: agent-ruff-check
+        name: agent ruff check
+        entry: sh -c 'cd agent && uv run ruff check --fix'
+        language: system
+        files: ^agent/.*\.py$
+        pass_filenames: false
+      - id: agent-ruff-format
+        name: agent ruff format
+        entry: sh -c 'cd agent && uv run ruff format'
+        language: system
+        files: ^agent/.*\.py$
+        pass_filenames: false
+      - id: agent-ty
+        name: agent ty check
+        entry: sh -c 'cd agent && uv run ty check .'
+        language: system
+        files: ^agent/.*\.py$
+        pass_filenames: false
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:
       - id: trailing-whitespace
-        files: ^(backend|mcp)/
+        files: ^(backend|agent|mcp)/
       - id: end-of-file-fixer
-        files: ^(backend|mcp)/
+        files: ^(backend|agent|mcp)/
       - id: check-merge-conflict
         args: [--assume-in-merge]
-        files: ^(backend|mcp)/
+        files: ^(backend|agent|mcp)/

Makefile

@@ -1,5 +1,6 @@
 DOCKER_COMMAND = docker compose -f docker-compose.yml
 DOCKER_EXEC = $(DOCKER_COMMAND) exec app
+DOCKER_EXEC_AGENT = $(DOCKER_COMMAND) exec agent
 ALEMBIC_CMD = uv run alembic
 
 help:	## Show this help.
@@ -48,3 +49,19 @@ downgrade:  ## Revert the last migration
 
 reset_db:  ## Truncate all tables in the database (WARNING: deletes all data)
 	$(DOCKER_EXEC) uv run python scripts/reset_database.py
+
+agent-test:  ## Run agent tests.
+	cd agent && uv run pytest -v --cov=app
+
+agent-migrate:  ## Apply all agent migrations
+	$(DOCKER_EXEC_AGENT) $(ALEMBIC_CMD) upgrade head
+
+agent-create_migration:  ## Create a new agent migration. Use 'make agent-create_migration m="Description of the change"'
+	@if [ -z "$(m)" ]; then \
+		echo "Error: You must provide a migration description using 'm=\"Description\"'"; \
+		exit 1; \
+	fi
+	$(DOCKER_EXEC_AGENT) $(ALEMBIC_CMD) revision --autogenerate -m "$(m)"
+
+agent-downgrade:  ## Revert the last agent migration
+	$(DOCKER_EXEC_AGENT) $(ALEMBIC_CMD) downgrade -1

agent/.python-version

@@ -0,0 +1 @@
+3.13

agent/Dockerfile

@@ -0,0 +1,38 @@
+FROM python:3.13-slim AS builder
+
+    RUN apt-get update && \
+    apt-get install -y --no-install-recommends build-essential libpq-dev && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+    RUN pip install --no-cache-dir --upgrade pyopenssl
+
+    COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+    WORKDIR /root_project
+
+    COPY uv.lock pyproject.toml ./
+    COPY . .
+
+    ENV VIRTUAL_ENV=/opt/venv
+    RUN uv venv $VIRTUAL_ENV
+    ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+    RUN uv sync --locked --no-dev
+
+FROM python:3.13-slim
+
+    RUN apt-get update && \
+    apt-get install -y --no-install-recommends libpq5 && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+    WORKDIR /root_project
+
+    COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+    COPY --from=builder /opt/venv /opt/venv
+    COPY --from=builder /root_project /root_project
+    ENV VIRTUAL_ENV=/opt/venv
+    ENV PATH="/opt/venv/bin:$PATH"
+    ENV UV_PROJECT_ENVIRONMENT=/opt/venv
+
+    EXPOSE 8000

agent/README.md

@@ -0,0 +1,57 @@
+# API
+
+A FastAPI application with PostgreSQL database support, containerized with Docker.
+
+## Prerequisites
+
+- Docker and Docker Compose
+- Python 3.12+ (for local development)
+
+## Setup
+
+1. **Create environment file**
+   ```bash
+   cp ./config/.env.example ./config/.env
+   # Edit .env file with your configuration
+   ```
+
+## Running the Application
+
+### Docker (Recommended)
+
+```bash
+# Start services
+docker compose up -d
+
+# Create migration
+docker compose exec app uv run alembic revision --autogenerate -m "Description"
+
+# Run migrations
+docker compose exec app uv run alembic upgrade head
+```
+
+### Local Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Start PostgreSQL locally
+
+# Create migration
+uv run alembic revision --autogenerate -m "Description"
+
+# Run migrations
+uv run alembic upgrade head
+
+# Start development server
+uv run fastapi run app/main.py --reload
+```
+
+### Access the application
+- API: http://localhost:8000
+- Swagger: http://localhost:8000/docs
+
+---
+
+This project was generated from the [Python AI Kit](https://github.com/the-momentum/python-ai-kit).

agent/alembic.ini

@@ -0,0 +1,39 @@
+[alembic]
+script_location = migrations
+prepend_sys_path = .
+version_path_separator = os
+sqlalchemy.url =
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

agent/app/api/__init__.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+from app.api.routes.v1 import v1_router
+
+head_router = APIRouter()
+head_router.include_router(v1_router)
+
+__all__ = ["head_router"]

agent/app/api/routes/v1/__init__.py

@@ -0,0 +1,10 @@
+from fastapi import APIRouter
+
+from app.api.routes.v1.chat import router as chat_router
+from app.api.routes.v1.session import router as session_router
+
+v1_router = APIRouter()
+v1_router.include_router(session_router)
+v1_router.include_router(chat_router)
+
+__all__ = ["v1_router"]

agent/app/api/routes/v1/chat.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+
+from app.integrations.celery.tasks.process_message import process_message
+from app.schemas.chat import ChatRequest, ChatTaskResponse
+from app.services.chat_session import ChatSessionService
+from app.utils.auth import CurrentUserId
+
+router = APIRouter(prefix="/chat", tags=["chat"])
+logger = logging.getLogger(__name__)
+
+ChatSessionServiceDep = Annotated[ChatSessionService, Depends(ChatSessionService)]
+
+
+@router.post("/{session_id}")
+async def send_message(
+    session_id: UUID,
+    body: ChatRequest,
+    current_user: CurrentUserId,
+    service: ChatSessionServiceDep,
+) -> ChatTaskResponse:
+    session, conversation = await service.get_active_session(session_id, current_user)
+
+    task = process_message.delay(
+        session_id=str(session.id),
+        conversation_id=str(conversation.id),
+        message=body.message,
+        callback_url=str(body.callback_url),
+    )
+
+    logger.info(f"Queued task {task.id} for session {session.id}")
+    return ChatTaskResponse(task_id=task.id)
+
+

agent/app/api/routes/v1/session.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from starlette import status
+
+from app.schemas.session import SessionCreateResponse, SessionDeactivateResponse, SessionRequest
+from app.services.chat_session import ChatSessionService
+from app.utils.auth import CurrentUserId
+
+router = APIRouter(prefix="/session", tags=["session"])
+logger = logging.getLogger(__name__)
+
+ChatSessionServiceDep = Annotated[ChatSessionService, Depends(ChatSessionService)]
+
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def create_or_get_session(
+    body: SessionRequest,
+    current_user: CurrentUserId,
+    service: ChatSessionServiceDep,
+) -> SessionCreateResponse:
+    session, conversation = await service.upsert_session(current_user, body.session_id)
+    return SessionCreateResponse(
+        session_id=session.id,
+        conversation_id=conversation.id,
+        created_at=session.created_at,
+    )
+
+
+@router.patch("/{session_id}")
+async def deactivate_session(
+    session_id: UUID,
+    current_user: CurrentUserId,
+    service: ChatSessionServiceDep,
+) -> SessionDeactivateResponse:
+    session = await service.deactivate_session(session_id, current_user)
+    return SessionDeactivateResponse(session_id=session.id)