ducoterra
dbf2af26c6
Standardize on the .agents/ directory (shared with project skills): phases/, user_stories/, reports/, screenshots/, validate.sh, and phase-sessions/ + pipeline.log all move to .agents/ (git mv preserves history; runtime artifacts move alongside). Updates every reference in AGENTS.md, README.md, .gitignore, app docstrings, and test story headers. Historical KB content in data/ and the runtime pipeline.log transcript are left untouched.
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# Phase 01 — Infrastructure Foundation
|
|
|
|
**Story:** — (foundation; no user story)
|
|
**Context:** `.agents/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
|
|
1. `uv sync` — confirm all deps resolve from `uv.lock`.
|
|
2. `podman compose up -d db` — build the `db/` image (postgres:17 +
|
|
pgvector) and start the container; `podman compose ps` must show
|
|
`healthy`.
|
|
3. `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)`).
|
|
4. `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.)
|
|
5. `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.
|
|
6. 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):
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
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)
|