ai-server

name: ai-server description: Conventions for the opentrons-ai-server FastAPI service — project structure, uv dependency management, settings, testing, Docker, and deployment. Use when working with files in opentrons-ai-server/ or discussing the AI server API.

AI Server Instructions

Overview

opentrons-ai-server is a standalone FastAPI service for Opentrons AI — protocol generation, chat completions, and related AI features. It is not part of the monorepo build system; it has its own dependency management, CI workflows, and deployment pipeline.

Deployed environments: staging (staging.opentrons.ai) and prod (ai.opentrons.com), running on AWS ECS Fargate behind CloudFront.

API Endpoints

The server exposes four chat endpoints that return JSON responses:

All endpoints require a Bearer token in Authorization. Setting "fake": true in the request body bypasses the LLM and returns a canned response from api/domain/fake_responses.py — useful for local development without Anthropic API calls.

Package Manager — uv

This project uses uv for Python dependency management (not pipenv, pip-tools, or poetry).

Key Commands

make setup                    # Install all deps (uv sync --frozen)
uv add <package>              # Add production dep
uv add --dev <package>        # Add dev-only dep
uv remove <package>           # Remove dep
uv lock                       # Re-resolve after manual pyproject.toml edits
uv run <command>              # Run inside the managed venv

After changing deps, commit both pyproject.toml and uv.lock.

Project Structure

opentrons-ai-server/
├── api/ # Application source code
│ ├── handler/ # FastAPI app, routes, middleware (fast.py entrypoint)
│ ├── domain/ # Business logic — LLM prediction (Anthropic, OpenAI)
│ ├── models/ # Pydantic request/response models
│ ├── services/ # File processing and other services
│ ├── integration/ # External integrations (Auth0, Google Sheets, AWS)
│ ├── constants/ # Shared constants
│ ├── data/ # Static data files
│ ├── storage/ # Stored API docs, indexes
│ ├── utils/ # API docs sync, curation, metadata helpers
│ └── settings.py # Pydantic Settings — all env vars and secrets
├── tests/
│ ├── conftest.py # Pytest fixtures and --env option
│ ├── helpers/ # Client, token helpers for live testing
│ └── test\_\*.py # Unit and live tests
├── deploy.py # ECS Fargate deployment script
├── Dockerfile
├── Makefile
├── pyproject.toml
└── uv.lock

Configuration & Settings

All runtime configuration lives in api/settings.py via pydantic-settings:

• Locally: values come from a .env file (gitignored)
• Deployed: values come from AWS Secrets Manager, loaded into ECS by deploy.py
• Every new env var or secret must be added as a field on the Settings class
• Secrets use SecretStr type; non-secret vars are plain strings with defaults
• Always import settings via the get_settings() singleton (not Settings() directly) to avoid re-parsing .env on every import

Notable settings:

• allowed_origins — comma-separated CORS origins (must be explicit; wildcard * is invalid with allow_credentials=True)
• request_timeout_seconds — request timeout in seconds (default "300"); production proxies must be configured to allow at least this duration
• anthropic_max_tokens — stored as a string, cast to int when used

Generate a template .env from defaults: make gen-env

Tool Configuration

All config is in pyproject.toml — no separate config files:

Line length: 140. Target: Python 3.12. Mypy is in strict mode.

Makefile Targets

All targets run from opentrons-ai-server/.

Development

Running Locally

Deployment

Docker Build

The container does not use uv internally:

1. make build calls make gen-requirements → uv export --no-hashes --no-dev -o requirements.txt
2. Dockerfile installs with plain pip
3. Copies api/ source and Opentrons API docs synced under api/storage/api_docs/docs/v2
4. Entrypoint: uvicorn api.handler.fast:app (3 workers, port 8000)

Docker build context is the repo root (not opentrons-ai-server/). Run make sync-api-docs before building so Python API docs from the pinned DOCS_TAG Makefile variable are present under api/storage/api_docs/docs/v2.

Python API docs curation

The helper model that selects relevant docs reads api/storage/api_docs/api_docs_struct.md. Rich <about> routing text is not taken from synced markdown alone; it comes from committed curation.

make sync-api-docs              # regenerate api_docs_struct.md from curated about file
make check-api-docs-curation    # fail if curated entries and synced docs diverge

Full details: opentrons-ai-server/docs/API_DOCS_CURATION.md

Testing

• Unit tests (@pytest.mark.unit): run offline → make unit-test
• Live tests (@pytest.mark.live): run against a real server → make live-test ENV=local
• The --env pytest option selects the target environment (local/staging/prod)
• Test helpers in tests/helpers/ handle Auth0 token caching and HTTP client setup

Authentication

Auth0 JWT verification via api/integration/auth.py. Config: auth0_domain, auth0_api_audience, auth0_issuer, auth0_algorithms in Settings.

Code Conventions

• Formatting and linting: ruff only (no black). make format to auto-fix
• Type annotations: required everywhere — mypy strict mode
• Pydantic models for all request/response schemas (in api/models/)
• Structured logging via structlog
• Import sorting handled by ruff's I rule (isort-compatible)

Adding a New Env Var or Secret

1. Add the field to the Settings class in api/settings.py (use SecretStr for secrets)
2. Add the value to your local .env file
3. Before deploying: add the value in AWS Secrets Manager under the environment's secret name
4. Re-deploy — the deploy script maps Settings fields to ECS container env vars automatically