Project README

Overview

• Purpose: FastAPI API scaffold with Docker Compose, uv, and async Postgres access.
• Scope: API + Postgres with Alembic migrations; LLM integration remains a stub.
• Audience: Project collaborators.

Structure

• app/ FastAPI application package
• Dockerfile API container build
• docker-compose.yml Local orchestration
• .python-version Python version for uv
• pyproject.toml Python project metadata and dependencies
• uv.lock Dependency lockfile (generated by uv)

Setup

• Install uv: https://docs.astral.sh/uv/getting-started/installation/
• Create the local environment and lockfile:
  • uv sync
• Configure database env vars:
  • cp .env.db.example .env.db
  • Update POSTGRES_PASSWORD in .env.db
• Configure API auth:
  • cp .env.api.example .env.api
  • Update API_TOKEN in .env.api

Run

• Local dev:
  • uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
• Docker:
  • docker compose up --build -d
• Verify:
  • curl http://localhost:8000/health
  • curl http://localhost:8000/
  • docker compose exec db pg_isready -U texet -d texet
  • curl http://localhost:8000/db/health
  • curl -H "Authorization: Bearer <API_TOKEN>" -H "Content-Type: application/json" -X POST http://localhost:8000/chat -d '{"user_id":"u1","message":"hello"}'

Migrations

• Migrations use Alembic and the DATABASE_URL from the running Compose stack.
• Define or update models in app/models.py, then generate a migration.
• Create a new migration:
  • make migration name=add_speakers
• Apply migrations:
  • make migrate
• If running locally (outside Docker), set DATABASE_URL before running Alembic.

LLM Integration

• Not wired yet.

Dependencies

• Add a package:
  • uv add <package>
• Upgrade a package:
  • uv lock --upgrade-package <package>

Tests

• Ensure the DB is running:
  • docker compose up -d db
• Run the connection test inside the Compose network (uses DATABASE_URL_TEST pointing at db):
  • docker compose run --rm api uv run pytest tests/test_db_connection.py
• The test database is texet_test inside the same Postgres container.
• Tests apply Alembic migrations to texet_test before running.
• Run chat endpoint tests:
  • uv run pytest tests/test_chat_endpoint.py
• Run all tests with coverage (local):
  • uv run pytest --cov
• Run all tests with coverage (Docker):
  • docker compose run --rm api uv run pytest --cov

Quality Checks

• Lint:
  • uv run ruff check .
• Format:
  • uv run ruff format .
• Type check:
  • uv run mypy
• Vulnerability audit:
  • uv run pip-audit
• Combined:
  • uv run ruff check . && uv run ruff format . && uv run mypy && uv run pip-audit

Make Targets

• make start builds and starts the stack.
• make stop stops and removes the stack (including volumes).
• make test runs the full test suite with coverage (requires make start first).
• make clean runs linting, formatting, type checks, and vulnerability audit (requires make start first).
• make migration name=... creates a new Alembic revision (requires make start first).
• make migrate applies Alembic migrations (requires make start first).

Notes