Skip to content

Local Development

Prerequisites

  • Python 3.11 or newer
  • venv
  • access to Supabase, Pinecone, and OpenAI credentials
  • optional psql access if you plan to apply SQL locally or against a non-production database

Environment setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
cp .env.example .env

Populate .env with real values for:

  • Supabase URL and service-role key
  • Supabase JWT secret
  • Pinecone API key and index name
  • OpenAI API key and model overrides if needed

Database setup

This repo does not include an active migration runner script in scripts/. Use SQL tooling directly.

Recommended order for a fresh environment:

  1. apply db/bootstrap.sql
  2. apply every file in db/migrations/ in lexical order

Example with psql:

psql "$DATABASE_URL" -f db/bootstrap.sql
for f in db/migrations/*.sql; do
  psql "$DATABASE_URL" -f "$f"
done

Running the API

Option 1, directly:

uvicorn app.main:app --reload --port 8000

Option 2, Docker:

docker compose up --build

Health check:

curl http://localhost:8000/health

Validation workflow

Run the backend checks that are actually wired in this repo:

ruff check .
pytest
python postman/check_sync.py
mkdocs build

Use postman/check_sync.py whenever API routes change. CI enforces this in .github/workflows/postman-sync-guard.yml.

Local notes

  • The API constructs external clients at import time, so missing env vars often fail fast.
  • Rate limiting and metrics are in-memory; local restarts reset both.
  • Background ingestion dispatch uses FastAPI background tasks. It does not require a separate worker process locally because the repo does not define one.