Getting started

Run it (Docker)

You need Docker with Compose and your own Anthropic API key in your environment. The key is passed through by docker/docker-compose.yml; nothing in this repository stores one.

export ANTHROPIC_API_KEY=...
docker compose -f docker/docker-compose.yml run --rm agent ask "how many customers are there?"

Use run --rm agent ask ..., not exec: the image entrypoint is db-agent, so the agent container exits when it has no command. run also starts Postgres and waits until it is healthy. The first start seeds Pagila from docker/init-db/; Postgres is published on host port 5433.

Charts are written to chart.vega.json in the container's working directory. Keep them by mounting a directory:

docker compose -f docker/docker-compose.yml run --rm -v "$PWD/out":/out -w /out \
  agent ask "top 5 customers by total payment amount"

db-agent ask exits with code 1 if the run failed (hop or retry ceiling, malformed model response), 0 otherwise.

Stop and remove everything, including the database volume:

docker compose -f docker/docker-compose.yml down -v

Develop

Python 3.12+.

python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest tests/unit tests/integration tests/test_smoke.py

Integration tests start their own postgres:16 with testcontainers, so a Docker daemon must be running; they never call the Anthropic API.

To use the agent from Python or a local shell, start Postgres (docker compose -f docker/docker-compose.yml up -d postgres) and set:

export AGENT_DATABASE_URL=postgresql+asyncpg://agent_ro:agentpassword@localhost:5433/pagila
export ANTHROPIC_API_KEY=...
db-agent ask "how many films are in the catalog?"

Evaluation

The harness in eval/ is built but has not been run against the live model; no results are recorded in this repository. See eval/README.md in the repository root.

Docs

pip install -r requirements-docs.txt
mkdocs serve