| # System Design Document (SDD) |
|
|
| **System:** Christianity-Focused AI Assistant |
| **Version:** 1.0 |
| **Companion docs:** [`HLD.md`](./HLD.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md), [`PHASES.md`](./PHASES.md) |
|
|
| --- |
|
|
| ## 1. Introduction |
|
|
| ### 1.1 Scope |
| A full-stack AI assistant for Christianity-related Q&A, content, and image |
| generation. It grounds answers in a verified scripture and church-history |
| corpus, is aware of denominational differences (Catholic / Protestant / |
| Orthodox), and enforces safety and anti-hallucination controls as explicit |
| pipeline stages. |
|
|
| ### 1.2 Goals |
| - Accurate, cited, scripture-grounded answers. |
| - No fabricated verses, references, or historical claims. |
| - Denomination-correct canon and framing. |
| - Robust refusal of adversarial, hateful, or manipulative requests. |
| - Safe Christian-themed image generation. |
|
|
| ### 1.3 Non-Goals |
| - UI polish (explicitly not graded). |
| - Exhaustive multi-translation coverage (public-domain KJV/WEB + deuterocanon only). |
| - Real-time multi-user scale (single-instance demo target). |
|
|
| --- |
|
|
| ## 2. Requirements |
|
|
| ### 2.1 Functional |
| | ID | Requirement | |
| | :-- | :-- | |
| | F1 | Answer Christianity questions grounded in retrieved scripture | |
| | F2 | Cite verses as `Book Chapter:Verse`, validated against the corpus | |
| | F3 | Generate Christian content (prayers, reflections, explanations) | |
| | F4 | Generate Christian-themed images via a safe prompt pipeline | |
| | F5 | Maintain conversation memory across turns | |
| | F6 | Apply denomination-aware canon, retrieval, and framing | |
| | F7 | Moderate input and output for safety | |
| | F8 | Detect and correct fake verses and paraphrase misquotes | |
| | F9 | Ground or abstain on non-scripture historical claims | |
| | F10 | Handle difficult/contested theology by naming the tradition | |
|
|
| ### 2.2 Non-Functional |
| | ID | Requirement | Target | |
| | :-- | :-- | :-- | |
| | N1 | Text response latency | ~2.0–2.6 s | |
| | N2 | Image response latency | ~5–8 s | |
| | N3 | Observability | structured logs with request-id per request | |
| | N4 | Reproducibility | pinned deps (uv.lock), idempotent ingestion | |
| | N5 | Cost control | local embeddings, single combined safety+router call | |
| | N6 | Safety | adversarial/hate prompts blocked before generation | |
| | N7 | Data licensing | public-domain text only | |
|
|
| --- |
|
|
| ## 3. Architecture Overview |
|
|
| Layered, agent-orchestrated system. Requests enter FastAPI, run through a |
| LangGraph state machine (safety → routing → retrieval → generation → |
| validation → response), backed by PostgreSQL + pgvector and Gemini APIs. See |
| [`HLD.md`](./HLD.md) §2–4 for context and flow diagrams. |
|
|
| --- |
|
|
| ## 4. Component Design |
|
|
| ### 4.1 Backend API (`app/main.py`, `app/api/routes.py`) |
| - FastAPI app, lifespan-managed. |
| - Middleware binds `request_id` to structlog contextvars for the request. |
| - Endpoints: `GET /health`, `POST /chat` (graph invocation — Phase 9). |
| - Interface: `ChatRequest{session_id, message, denomination}` → |
| `ChatResponse{session_id, response, citations[], flagged}`. |
|
|
| ### 4.2 Configuration (`app/config.py`) |
| - `pydantic-settings`, env-driven, `lru_cache` singleton. |
| - Holds model names, DB URL, thresholds (rag_top_k, retrieval/drift), memory params. |
|
|
| ### 4.3 Logging (`app/logging_config.py`) |
| - structlog: console renderer (dev) / JSON (prod), level + format from config. |
| - contextvars merge → request-id appears on every line. |
| |
| ### 4.4 Data Layer (`app/core/db.py`, `schema.sql`) |
| - psycopg3 `ConnectionPool`; pgvector registered per connection. |
| - One-time extension bootstrap before pool open (avoids CREATE EXTENSION race). |
| - Schema: `bible_verses`, `history_docs`, `conversations`; HNSW (vectors) + GIN (canon). |
| |
| ### 4.5 Embeddings (`app/core/embeddings.py`) |
| - bge-base-en-v1.5 via sentence-transformers, lazy-loaded singleton. |
| - `embed_passages` (corpus, no instruction) / `embed_query` (retrieval instruction). |
| - Normalized vectors → cosine = dot product. |
| |
| ### 4.6 Retrieval (`app/core/retrieval.py`) |
| - `search_scripture` / `search_history`: cosine search, canon filter in SQL (`@>`), |
| returns rows + top-similarity confidence. |
| - `verse_exists(book, chapter, verse)`: citation-validation primitive. |
|
|
| ### 4.7 LLM (`app/core/llm.py` — Phase 3) |
| - google-genai client; Gemini Pro for generation, Flash for classification. |
| - Prompt templates enforce retrieval-first citing + denomination framing. |
|
|
| ### 4.8 Safety + Router (`app/core/safety.py` — Phase 4) |
| - Stage 1 regex; Stage 2 Flash returns `{safe, intent, confidence}`. |
|
|
| ### 4.9 Agent Graph (`app/agent/*` — Phase 5) |
| - `AgentState` TypedDict; nodes for input, safety+router, scripture/history RAG, |
| theology, image, image-validator, validator, responder; conditional edges. |
| |
| ### 4.10 Image (Phase 8) |
| - Prompt rewrite → Imagen 3 → post-rewrite re-validation node. |
| |
| --- |
| |
| ## 5. Data Design |
| |
| ### 5.1 Entities |
| - **bible_verses** — `(book, chapter, verse)` unique; `text_kjv`, `text_web`, |
| `denomination_canon[]`, `embedding VECTOR(768)`. |
| - **history_docs** — `source`, `title`, `content`, `denomination_scope[]`, `embedding`. |
| - **conversations** — `session_id`, `role`, `content`, `denomination`, |
| `embedding` (semantic memory), `created_at`. |
| |
| ### 5.2 Indexes |
| - HNSW `vector_cosine_ops` on all embedding columns (static corpora, recall-first). |
| - GIN on `denomination_canon` / `denomination_scope`. |
| - Btree on `(book, chapter, verse)` and `(session_id, created_at)`. |
| |
| ### 5.3 Canon model |
| All 66 KJV books tagged `{protestant, catholic, orthodox}`. Deuterocanon (from |
| `KJV-with-Apocrypha.json`) tagged `{catholic, orthodox}` only. Retrieval filters |
| by the active denomination so canon scope is enforced at the data layer. |
| |
| --- |
| |
| ## 6. Key Flows |
| |
| ### 6.1 Grounded text answer |
| input → regex/Flash safety+intent → (scripture|history|theology) retrieval → |
| Gemini generation with injected context → citation validation + drift check → |
| responder formats cited answer. |
| |
| ### 6.2 Fake-verse handling |
| Query references `John 4:99` → retrieval finds no such verse / model instructed |
| not to invent → citation validator confirms non-existence → response states the |
| verse does not exist. |
| |
| ### 6.3 Historical claim |
| "Council of Nicaea in 200 AD" → history RAG retrieves council facts (325 AD) → |
| model corrects date or, if low retrieval confidence, abstains. |
| |
| ### 6.4 Image generation |
| prompt → pre-routing safety → rewrite to safe Christian-art form → |
| ImageValidator re-checks rewritten prompt → Imagen 3 → return with metadata. |
| |
| ### 6.5 Memory |
| ≤20 turns: load last 10 (window). >20: embed query, fetch top-5 past turns |
| (semantic). Denomination switch injects a framing-changed system note. |
| |
| --- |
| |
| ## 7. Cross-Cutting Concerns |
| |
| ### 7.1 Safety |
| Defense in depth across seven layers (see [`HLD.md`](./HLD.md) §6). Safety runs |
| before retrieval/generation; image path is double-moderated. |
| |
| ### 7.2 Hallucination control |
| Retrieval-first prompting + citation regex validation + semantic drift check + |
| separate history grounding. Fakes are stripped and logged in `hallucinated_refs`. |
| |
| ### 7.3 Observability |
| Per-request `request_id`, per-node latency in `state.latency_ms`, structured |
| JSON logs in prod. Supports the evaluation rubric's logging signal. |
| |
| ### 7.4 Configuration & secrets |
| Env-driven; `GEMINI_API_KEY` never committed; `.env` gitignored. |
| |
| --- |
| |
| ## 8. Reliability & Scalability |
| |
| - **Stateless backend** — session state lives in Postgres; horizontally scalable. |
| - **Connection pooling** — psycopg3 pool (1–10) bounds DB connections. |
| - **Static corpora** — embeddings precomputed offline; query-time cost = 1 embed + 1 vector search. |
| - **Bottlenecks** — Gemini generation (~2 s) and Imagen (~3–5 s) dominate latency; embedding is local and cheap. |
| - **Failure modes** — Gemini error → safe fallback message; retrieval empty → abstain; image unsafe → block. |
| |
| --- |
| |
| ## 9. Trade-offs & Alternatives |
| |
| | Decision | Chosen | Alternative | Why | |
| | :-- | :-- | :-- | :-- | |
| | Vector store | pgvector in Postgres | dedicated vector DB | small corpus, less ops | |
| | Embeddings | local bge-base | hosted embedding API | free, no rate limits for bulk | |
| | Safety+Router | one Flash call | separate calls | fewer round-trips, lower cost | |
| | LLM | Gemini Pro/Flash | open HF model | quality + simplicity for this build | |
| | Bible source | structured JSON | PDF | reliable verse-level parsing | |
| |
| --- |
| |
| ## 10. Risks & Mitigations |
| |
| | Risk | Mitigation | |
| | :-- | :-- | |
| | Paraphrase hallucination (correct ref, wrong wording) | semantic drift check vs retrieved set | |
| | Post-rewrite unsafe image | second validation node after rewrite | |
| | Stale denomination framing after switch | memory denomination guard | |
| | Non-scripture fabrication | history corpus + abstain on low confidence | |
| | Copyright exposure | public-domain text only (KJV/WEB + KJV Apocrypha) | |
| | Embedding cost/latency on free tier | local model, corpus precomputed offline | |
| |
| --- |
| |
| ## 11. Open Items / Future Work |
| |
| - Deuterocanon ingest + canon-scoped retrieval validation (Catholic/Orthodox). |
| - History corpus ingestion from `creeds1.pdf` + council sources. |
| - Evaluation harness with scored PASS/PARTIAL/FAIL over the dataset. |
| - Frontend, deployment, and walkthrough (Phases 10, 12, 13). |
| |
