Files

T

ducoterra 022da8e2bc feat: scaffold Brain of Reese — FastAPI RAG chat over Postgres 17 + pgvector

Foundation (phase 01, verified):
- FastAPI app: /api/health, /api/suggestions, /api/chat (placeholder),
  static frontend served locally (no CDN)
- Postgres 17 + pgvector via db/Containerfile + compose.yaml
  (podman compose up -d db), Alembic initial migration (documents,
  chunks with vector(768), query_log)
- LLM client targeting https://aipi.reeseapps.com/v1 (turbo/embed);
  scripts/llm_probe.py verified models + 768-dim embeddings live
- Conditional debugpy: imported only when DEBUGPY=1 (attach on demand,
  :5678); logging config for clean single-line logs
- Frontend shell: mobile-first chat + Sources pages, tokens, a11y baselines
- Tests: 24 unit+integration (99% coverage on app/), ruff + pyright clean,
  Playwright smoke E2E (3 tests) against a deterministic mock LLM
- Planning: .agent/PLAN.md (architecture + LOCKED decisions), AGENTS.md,
  6 user stories, 7 phase files (one story / one phase / one Playwright
  suite each)

2026-08-21 13:42:21 -04:00

2.4 KiB

Raw Blame History

Phase 01 — Infrastructure Foundation

Story: — (foundation; no user story) Context: .agent/PLAN.md §2–§5, §8–§10 · AGENTS.md

Goal

A verified, reproducible foundation: environment installs, Postgres 17 + pgvector running via podman compose up -d db, migrations applied, app booting with /api/health, lint/types clean, and the smoke E2E green. The scaffolding already exists in the repo — this phase verifies and completes it (fix gaps rather than rewrite).

Implementation steps

uv sync — confirm all deps resolve from uv.lock.
podman compose up -d db — build the db/ image (postgres:17 + pgvector) and start the container; podman compose ps must show healthy.
uv run alembic upgrade head — schema applied (documents, chunks, query_log, vector extension). Verify with psql -h localhost -U reese -d brain_of_reese -c '\d chunks' (embedding column vector(768)).
uv run python -m scripts.llm_probe — live aipi check: turbo + embed present, dim 768. (If the endpoint is unreachable, record it and continue; E2E uses the mock.)
DEBUGPY=0 uv run uvicorn app.main:app boots and serves /, /api/health, /api/suggestions (Ctrl-C to stop). Also verify DEBUGPY=1 prints the debugpy listen warning and the app stays responsive.
Fix anything broken in scaffold files (keep PLAN-conformant).

Testing & Quality

Unit + integration: uv run pytest — green.
Coverage: uv run pytest --cov=app --cov-report=term-missing — record the number; the >90% gate is enforced from the first feature phase onward (skeleton coverage should already be high).
Lint/types: uv run ruff check . and uv run pyright — zero errors.

Playwright Execution Phase

Run ONLY the smoke suite (verify the browser is installed first — uv run playwright install chromium if missing):

uv run pytest tests/e2e/test_smoke.py -v --no-cov

Expected: 3 passed (health, index page, placeholder round-trip).

Success criteria

podman compose up -d db → healthy
alembic upgrade head clean; vector(768) column present
app boots; /api/health db: up
unit + integration green; ruff + pyright clean
smoke E2E green in isolation
committed (see below)

Commit

git add -A && git commit --no-gpg-sign -m "chore(infra): verify foundation — pg17+pgvector, migrations, debugpy gating, smoke E2E"

2.4 KiB Raw Blame History