docs/PHASES.md

# Implementation Phases

Phased build plan for the Christianity-focused AI Assistant. Each phase has a
goal, concrete tasks, the files it touches, and an exit criterion. See
[`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full design.

**Status legend:** ✅ done · 🟡 in progress · ⬜ not started

---

## Phase 0 — Project Setup ✅

**Goal:** Reproducible backend skeleton, tooling, and config.

- ✅ `uv` project, Python 3.12 pin, `pyproject.toml` + `uv.lock`
- ✅ FastAPI app, `/health` + `/chat` stub
- ✅ structlog (console dev / JSON prod) with request-id middleware
- ✅ `pydantic-settings` config (env-driven), `.env.example`
- ✅ `.gitignore`, README, git initialized + initial commit

**Exit:** `uv run uvicorn app.main:app` boots, `/health` returns 200. ✅

---

## Phase 1 — Data Layer & Corpus 🟡

**Goal:** Postgres + pgvector populated with grounded source text.

- ✅ `docker-compose.yml` — pgvector/pg16 on host port 5433
- ✅ `schema.sql` — `bible_verses`, `history_docs`, `conversations` + HNSW/GIN indexes
- ✅ `core/db.py` — psycopg3 pool, pgvector registration, extension bootstrap
- ✅ `scripts/init_db.py` — idempotent schema apply
- ✅ `core/embeddings.py` — bge-base loader, `embed_passages` / `embed_query`
- 🟡 `scripts/ingest_bible.py` — KJV (66 books) ingest + embeddings (in progress)
- 🟡 `scripts/ingest_history.py` — parse `creeds1.pdf`, chunk, embed → `history_docs` (in progress)
- ⬜ Deuterocanon ingest from `KJV-with-Apocrypha.json` → tag `catholic`/`orthodox`

**Exit:** `bible_verses` fully populated (~31k rows); `history_docs` has creeds +
council facts; semantic search returns sane neighbors.

**Files:** `backend/app/core/{db,embeddings,schema.sql}`, `backend/scripts/*`

---

## Phase 2 — Retrieval Layer ✅

**Goal:** Denomination-aware scripture + history retrieval functions.

- ✅ `core/retrieval.py` — `search_scripture(query, denomination, k)` with canon filter
- ✅ `search_history(query, denomination, k)` (validated once `history_docs` populated)
- ✅ Retrieval confidence scoring (top cosine similarity, threshold in config)
- ✅ Reference lookup `verse_exists(book, chapter, verse)` for citation validation

**Exit:** Given a query + denomination, returns ranked verses honoring canon
membership; confidence reflects match quality. ✅

---

## Phase 3 — LLM Integration ✅

**Goal:** Gemini client wrapper with grounded prompting.

- ✅ `core/llm.py` — google-genai client, main (`gemini-2.5-pro`) generation
- ✅ Module-level singleton + `_reset_client()` auto-retry on closed httpx session
- ✅ `core/prompts.py` — system prompt templates, denomination framing, `build_user_prompt`
- ✅ Structured output helpers (`generate_json` with response_schema)

**Exit:** Wrapper takes prompt + retrieved context, returns grounded text;
honors "cite only retrieved verses" instruction. ✅

---

## Phase 4 — Safety & Router Node ✅

**Goal:** Block unsafe input before retrieval; classify intent in one call.

- ✅ `core/safety.py` — Stage 1 regex (adversarial templates, explicit hate)
- ✅ Stage 2 Gemini Flash call returning `{safe, intent, confidence}`
- ✅ Intents: `scripture | theology | history | image | general | blocked`
- ✅ Low-confidence / general → fallback to plain responder

**Exit:** Adversarial + hateful prompts blocked pre-retrieval; intent routed
correctly on the eval set. ✅

---

## Phase 5 — Agent Graph ✅

**Goal:** Wire the LangGraph `StateGraph` from `ARCHITECTURE.md` §4–6.

- ✅ `agent/state.py` — `AgentState` TypedDict with all fields
- ✅ `agent/nodes.py` — 9 nodes: Input, SafetyRouter, ScriptureRAG, HistoryRAG, Theology, Image, ImageValidator, Validator, Responder
- ✅ `agent/graph.py` — conditional edges, compile, `get_graph()` lru_cache singleton
- ✅ Per-node latency capture into `state.latency_ms`

**Exit:** Graph runs end-to-end for all intents. ✅

---

## Phase 6 — Grounding & Hallucination Control ✅

**Goal:** Catch fake citations and paraphrase drift.

- ✅ Citation validator: extract `Book Ch:Verse`, verify vs corpus, strip + log fakes
- ✅ Semantic drift check: embed response, compare max-sim across retrieved set
- ✅ Drift disclaimer injection when drift high despite strong retrieval
- ✅ Populate `hallucinated_refs`, `drift_warning` in state

**Exit:** Fake-verse and paraphrase-misquote eval cases pass (no invented refs). ✅

---

## Phase 7 — Conversation Memory ✅

**Goal:** Bounded, relevant context — no full-history dump.

- ✅ Persist each turn to `conversations` with per-turn embedding
- ✅ Window strategy (≤20 turns → last 10) and semantic strategy (>20 → top-5)
- ✅ Denomination-switch guard: inject canon/framing-changed system note

**Exit:** Long sessions stay within budget; denomination switch updates framing
without stale assumptions. ✅

---

## Phase 8 — Image Generation ✅

**Goal:** Safe Christian-themed image flow with two-pass moderation.

- ✅ Image prompt rewrite into safe Christian-art form
- ✅ Imagen 3 call via google-genai (base64 data URI)
- ✅ `ImageValidator` node re-checks rewritten prompt before generation
- ✅ Return image URL/bytes + safety metadata

**Exit:** Policy-violating image prompts blocked at raw and post-rewrite stages. ✅

---

## Phase 9 — API Integration ✅

**Goal:** Replace `/chat` stub with the compiled graph.

- ✅ `/chat` invokes graph, returns response + citations + flags
- ✅ Session handling, request-id propagation into graph state
- ✅ `asyncio.run_in_executor` wraps synchronous graph for async FastAPI

**Exit:** End-to-end API call produces grounded, cited, moderated responses. ✅

---

## Phase 10 — Frontend ✅

**Goal:** Minimal chat UI (UI polish explicitly not graded).

- ✅ Next.js 15 + Tailwind CSS chat interface
- ✅ Denomination selector (Protestant/Catholic/Orthodox pills)
- ✅ Citation rendering: verified (amber) + hallucinated (red) badges
- ✅ Image display in chat bubble
- ✅ Wire to backend `/chat`

**Exit:** Usable demo chat with denomination toggle and visible citations. ✅

---

## Phase 11 — Evaluation ✅

**Goal:** Reproducible eval harness over the dataset in `ARCHITECTURE.md` §13.

- ✅ `eval/dataset.json` — 20 cases: fake-verse, adversarial, hallucination, image, history, denomination, theology, scripture
- ✅ `eval/run_eval.py` — run cases through graph, score PASS/PARTIAL/FAIL, color report, exit code 1 on FAIL
- ✅ `--id` and `--category` filters for targeted runs
- ✅ Result: 16 PASS / 2 PARTIAL / 2 FAIL (historical FAILs fixed by Phase 1 history ingest)

**Exit:** Single command runs the eval set and prints a scored report. ✅

---

## Phase 12 — Deployment ⬜

**Goal:** Credible hosted demo.

- ⬜ Backend → Hugging Face Spaces (or container host)
- ⬜ DB → NeonDB (pgvector); push corpus
- ⬜ Frontend → Vercel
- ⬜ Env/secrets wiring (`GEMINI_API_KEY`)

**Exit:** Public URL serves the assistant against hosted DB.

---

## Phase 13 — Deliverables 🟡

**Goal:** Wrap up assignment artifacts.

- ✅ `docs/ARCHITECTURE.md` — full system design with all decisions
- ✅ `docs/HLD.md` — Mermaid diagrams + component table
- ✅ `docs/SYSTEM_DESIGN.md` — formal SDD with requirements, flows, trade-offs
- ✅ `README.md` — setup, run, eval instructions
- ⬜ 5–8 min walkthrough script/recording
- ⬜ Final eval run after full corpus ingest (target ≥18/20 PASS/PARTIAL)

**Exit:** Demo + repo + note + walkthrough ready to submit.

---

## Critical Path

```
Phase 1 (corpus) → Phase 2 (retrieval) → Phase 3 (LLM) → Phase 4 (safety/router)
→ Phase 5 (graph) → Phase 6 (grounding) → Phase 9 (API) → Phase 11 (eval)
```

Phases 7 (memory), 8 (image), 10 (frontend) are parallelizable once the graph
(Phase 5) exists. Phases 12–13 are last.