Bango

Python AI backend (FastAPI) — B2B API for the Bango platform.

See plans/ for architecture and decisions. plans/10-starter-stack.md is the canonical list of stack picks.

Quick start

# Install dependencies (creates .venv)
uv sync

# Run the app locally
uv run uvicorn app.main:app --reload

# In another shell:
curl http://localhost:8000/healthz

Layout

app/
  api/v1/          FastAPI routers (versioned)
  core/            Config, logging, middleware, security (config + logging + request-ID today)
  schemas/         Pydantic request/response models
  db/              SQLAlchemy models + async session       (wired in step 5)
  services/        Business logic; route handlers call into here
  workers/         Background jobs (arq)                   (wired in step 10)
  ai/
    clients/       LLMClient protocol + OpenAIClient       (wired in step 9)
    prompts/       Versioned prompt library
    agents/        Agent workflows (only if/when needed)
    rag/           Chunking + embeddings + vector search   (deferred)
  main.py          App factory
tests/
  unit/
  integration/
plans/             Architecture plans (numbered markdown)

Empty __init__.py files in db/, services/, workers/, ai/* are placeholders — they document where future code lands per the bootstrap order in plans/10-starter-stack.md.

Development

uv run ruff check .          # lint
uv run ruff format .         # format
uv run mypy app              # type check
uv run pytest                # tests

Docker

docker compose up --build

Brings up the app, Postgres (with pgvector), and Redis.