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"

✅ Completion record (2026-08-21)

uv sync — env created (CPython 3.13), deps locked in uv.lock
podman compose up -d db — image brain-of-reese/db:pg17-vector built (fixed: base image needed postgresql-server-dev-17 before compiling pgvector), container healthy
alembic upgrade head — clean; \d chunks shows embedding vector(768), FK ON DELETE CASCADE, vector extension installed
scripts/llm_probe (live) — models: turbo, embed, lite, juggernaut, uncensored, openai/image; dims(embed): [768] — A6 confirmed
App boot: /api/health → {"status":"ok","db":"up"}; static frontend served locally; DEBUGPY=1 logs the listener and keeps serving, default run has no debugpy import
Placeholder /api/chat added (round-trip exercised end-to-end; replaced by SSE RAG in phase 03)
Quality: 24 unit+integration passed, 99�overage on app/, ruff check . clean, pyright 0 errors
E2E: uv run playwright install chromium done; test_smoke.py 3 passed in isolation
Commit: feat: scaffold Brain of Reese — FastAPI RAG chat over Postgres 17 + pgvector (--no-gpg-sign)

3.6 KiB Raw Blame History