feat(agent): bootstrap FastAPI agent service

.gitattributes

@@ -0,0 +1,10 @@
+# Default: normalize line endings to LF on commit
+* text=auto eol=lf
+
+# Shell scripts must always be LF
+*.sh text eol=lf
+
+# Windows-only files can keep CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf

.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)/

.vscode/settings.json

@@ -1,8 +1,7 @@
 {
-  "python.defaultInterpreterPath": "${workspaceFolder}/backend/.venv/bin/python",
+  "python.defaultInterpreterPath": "${workspaceFolder}/agent/.venv/bin/python",
   "python.analysis.extraPaths": [
-    "${workspaceFolder}/backend"
+    "${workspaceFolder}/agent"
   ],
   "makefile.configureOnOpen": false
-}
-
+}

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,39 @@
+FROM python:3.13-slim AS builder
+
+    RUN apt-get update && \
+    apt-get install -y --no-install-recommends build-essential libpq-dev git && \
+    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
+    ENV UV_PROJECT_ENVIRONMENT=/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 git && \
+    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/agent/deps.py

@@ -0,0 +1,19 @@
+"""Agent dependency types for pydantic-ai RunContext injection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from pygentic_ai.engines.base import BaseAgentDeps
+
+
+@dataclass
+class HealthAgentDeps(BaseAgentDeps):
+    """Dependencies injected into every tool call via RunContext.
+
+    Extends BaseAgentDeps (which carries language) with the resolved
+    user_id so tools never need to receive it as a model-supplied argument.
+    """
+
+    user_id: UUID | None = None

agent/app/agent/engines/guardrails.py

@@ -0,0 +1,38 @@
+"""Health guardrails agent — wraps pygentic-ai GuardrailsAgent."""
+
+from __future__ import annotations
+
+from pygentic_ai.engines.guardrails import GuardrailsAgent
+
+from app.agent.prompts.worker_prompts import WorkerType, build_worker_prompt
+from app.agent.utils.model_utils import get_llm
+
+_DEFAULT_SOFT_WORD_LIMIT = 150
+
+
+class HealthGuardrailsAgent(GuardrailsAgent):
+    """Output formatter and validator for health assistant responses.
+
+    Wraps pygentic-ai GuardrailsAgent with health-domain formatting
+    rules and the configured worker LLM from app settings.
+    """
+
+    def __init__(
+        self,
+        language: str = "English",
+        soft_word_limit: int | None = _DEFAULT_SOFT_WORD_LIMIT,
+    ) -> None:
+        vendor, model, api_key = get_llm(is_worker=True)
+        prompt = build_worker_prompt(
+            WorkerType.GUARDRAILS,
+            language=language,
+            soft_word_limit=soft_word_limit,
+        )
+
+        super().__init__(
+            llm_vendor=vendor,
+            llm_model=model,
+            api_key=api_key,
+            system_prompt=prompt,
+            language=language,
+        )

agent/app/agent/engines/reasoning.py

@@ -0,0 +1,68 @@
+"""Health-domain reasoning agent — wraps pygentic-ai BaseAgent."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from pydantic_ai import UsageLimits
+from pydantic_ai.messages import ModelMessage
+from pydantic_ai.run import AgentRunResult
+from pygentic_ai import BaseAgent
+
+from app.agent.deps import HealthAgentDeps
+from app.agent.prompts.agent_prompts import build_system_prompt
+from app.agent.utils.model_utils import get_llm
+from app.config import settings
+from app.schemas.agent import AgentMode
+from app.schemas.language import LANGUAGE_NAMES, Language
+
+
+class HealthReasoningAgent(BaseAgent):
+    """ReAct-style reasoning agent for the Open Wearables health domain.
+
+    Wraps pygentic-ai BaseAgent with health-specific instructions and
+    the configured LLM provider from app settings.
+
+    user_id is stored on the instance and injected into every tool call
+    via HealthAgentDeps / RunContext — the model never needs to supply it.
+    """
+
+    def __init__(
+        self,
+        user_id: UUID,
+        mode: AgentMode = AgentMode.GENERAL,
+        tools: list | None = None,
+        language: Language | None = None,
+    ) -> None:
+        self.user_id = user_id
+        vendor, model, api_key = get_llm()
+        lang_name = LANGUAGE_NAMES[language] if language else LANGUAGE_NAMES[Language.english]
+        instructions = build_system_prompt(mode, language)
+
+        super().__init__(
+            llm_vendor=vendor,
+            llm_model=model,
+            api_key=api_key,
+            tool_list=tools or [],
+            system_prompt=instructions,
+            language=lang_name,
+            deps_type=HealthAgentDeps,
+            usage_limits=UsageLimits(request_limit=settings.max_tool_calls),
+        )
+
+    async def generate_response(
+        self,
+        query: str,
+        chat_history: list[ModelMessage] | None = None,
+    ) -> AgentRunResult:
+        """Generate response, injecting user_id into deps for tool access."""
+        deps = HealthAgentDeps(language=self.language, user_id=self.user_id)
+        run_kwargs: dict[str, Any] = {
+            "user_prompt": query,
+            "message_history": chat_history or [],
+            "deps": deps,
+        }
+        if self.usage_limits:
+            run_kwargs["usage_limits"] = self.usage_limits
+        return await self.agent.run(**run_kwargs)