diff --git a/docs/00-overview/problem-statement.md b/70-docs/00-overview/problem-statement.md similarity index 100% rename from docs/00-overview/problem-statement.md rename to 70-docs/00-overview/problem-statement.md diff --git a/docs/00-overview/roadmap.md b/70-docs/00-overview/roadmap.md similarity index 98% rename from docs/00-overview/roadmap.md rename to 70-docs/00-overview/roadmap.md index 3bbf6fa4da1434b53280e70812d73a0110895d72..2bb63585f2ac3aa73af3eb31923354595c07bb8f 100644 --- a/docs/00-overview/roadmap.md +++ b/70-docs/00-overview/roadmap.md @@ -121,7 +121,7 @@ The point of disciplined v1 architecture is that these things are **stable** acr 2. **Provider abstraction** (`backend/providers/base.py`) — swap STT/TTS/LLM via config 3. **Faithfulness verifier** (`backend/faithfulness.py`) — same 4 gates, possibly more 4. **Persona prompt + citation grammar** — same, refined -5. **Eval methodology** (`docs/03-eval-plan.md`) — same harness, more gold data +5. **Eval methodology** (`70-docs/03-eval-plan.md`) — same harness, more gold data The "c-readiness commitments" in Doc 02 §7 are the contract. Every v2 feature is a commitment honored. diff --git a/docs/10-architecture/safety-architecture.md b/70-docs/10-architecture/safety-architecture.md similarity index 100% rename from docs/10-architecture/safety-architecture.md rename to 70-docs/10-architecture/safety-architecture.md diff --git a/docs/10-architecture/scoring-knowledge-graph.md b/70-docs/10-architecture/scoring-knowledge-graph.md similarity index 100% rename from docs/10-architecture/scoring-knowledge-graph.md rename to 70-docs/10-architecture/scoring-knowledge-graph.md diff --git a/docs/10-architecture/scoring-methodology.md b/70-docs/10-architecture/scoring-methodology.md similarity index 100% rename from docs/10-architecture/scoring-methodology.md rename to 70-docs/10-architecture/scoring-methodology.md diff --git a/docs/10-architecture/scoring-tie-breaker-rubric.md b/70-docs/10-architecture/scoring-tie-breaker-rubric.md similarity index 100% rename from docs/10-architecture/scoring-tie-breaker-rubric.md rename to 70-docs/10-architecture/scoring-tie-breaker-rubric.md diff --git a/docs/10-architecture/stack-rationale.md b/70-docs/10-architecture/stack-rationale.md similarity index 100% rename from docs/10-architecture/stack-rationale.md rename to 70-docs/10-architecture/stack-rationale.md diff --git a/docs/10-architecture/system-overview.md b/70-docs/10-architecture/system-overview.md similarity index 99% rename from docs/10-architecture/system-overview.md rename to 70-docs/10-architecture/system-overview.md index fef43ba8bae6cd784cf88c8bd09b6c9e0cdca517..8320980ee7d970ee186058cd69bb25ecdd49e056 100644 --- a/docs/10-architecture/system-overview.md +++ b/70-docs/10-architecture/system-overview.md @@ -281,7 +281,7 @@ insurance-sales-bot/ ├── data/ │ ├── insurers.json # 10 insurers metadata │ └── corpus_urls.md # output of corpus-discovery sub-agent -├── docs/ +├── 70-docs/ │ ├── 01-requirements.md │ ├── 02-architecture.md # THIS FILE │ ├── 03-eval-plan.md diff --git a/docs/20-data-pipeline/information-source-map.md b/70-docs/20-data-pipeline/information-source-map.md similarity index 100% rename from docs/20-data-pipeline/information-source-map.md rename to 70-docs/20-data-pipeline/information-source-map.md diff --git a/docs/20-data-pipeline/ingestion-policy.md b/70-docs/20-data-pipeline/ingestion-policy.md similarity index 100% rename from docs/20-data-pipeline/ingestion-policy.md rename to 70-docs/20-data-pipeline/ingestion-policy.md diff --git a/docs/30-engineering/discovery-script.md b/70-docs/30-engineering/discovery-script.md similarity index 98% rename from docs/30-engineering/discovery-script.md rename to 70-docs/30-engineering/discovery-script.md index bd062d1505f6881f987678fc4004199c8821e494..825be9409eaa7d48e1263d0ced5791cdd0d79b3d 100644 --- a/docs/30-engineering/discovery-script.md +++ b/70-docs/30-engineering/discovery-script.md @@ -132,7 +132,7 @@ This is the customer-protection framing. It tells the user honesty is **self-pro The questions live in `backend/needs_finder.py::GRAPH`. To add a new question: 1. Add a `Question(...)` entry with `id`, `prompt_en` (plain language + WHY), `prompt_hi` (Hindi rendering), `field` (which Profile attribute it sets), `is_core` (boolean — counts toward completeness), optional `condition` callable, optional `parser`. -2. Add a row in `docs/scorecard-knowledge-graph.md` Part B showing how the new input shifts weights. +2. Add a row in `70-docs/scorecard-knowledge-graph.md` Part B showing how the new input shifts weights. 3. Wire the shift into `_profile_tuned_weights()` in `backend/scorecard.py`. Drift between these three places breaks the transparency promise. Keep them in sync. diff --git a/docs/30-engineering/needs-analysis-flow.md b/70-docs/30-engineering/needs-analysis-flow.md similarity index 100% rename from docs/30-engineering/needs-analysis-flow.md rename to 70-docs/30-engineering/needs-analysis-flow.md diff --git a/docs/40-evaluation/eval-methodology.md b/70-docs/40-evaluation/eval-methodology.md similarity index 100% rename from docs/40-evaluation/eval-methodology.md rename to 70-docs/40-evaluation/eval-methodology.md diff --git a/docs/40-evaluation/known-issues.md b/70-docs/40-evaluation/known-issues.md similarity index 99% rename from docs/40-evaluation/known-issues.md rename to 70-docs/40-evaluation/known-issues.md index fefd8bc5b1d22ac2d593a25b8239213a000a99c5..73a820f9d6939887207c0c17beb32f984367e53a 100644 --- a/docs/40-evaluation/known-issues.md +++ b/70-docs/40-evaluation/known-issues.md @@ -203,7 +203,7 @@ progress prints. Document for future tooling. ## Quality-sprint cadence Every batch of fixes ships as one commit referencing the KI numbers it -closes. The audit run (`audit_results//report.md`) is the +closes. The audit run (`80-audit//report.md`) is the empirical signal for whether a fix is actually working in production. The standing ratio target: **for every 1 user-facing bug a reviewer diff --git a/docs/40-evaluation/quality-sprint-2026-05-14.md b/70-docs/40-evaluation/quality-sprint-2026-05-14.md similarity index 97% rename from docs/40-evaluation/quality-sprint-2026-05-14.md rename to 70-docs/40-evaluation/quality-sprint-2026-05-14.md index 382b9ac25ffb4a8435beb089c692d7c1ea087cea..e72e86d8c5f485e01070e2524be48478cce6a994 100644 --- a/docs/40-evaluation/quality-sprint-2026-05-14.md +++ b/70-docs/40-evaluation/quality-sprint-2026-05-14.md @@ -66,7 +66,7 @@ Plus the system-prompt reinforcement for KI-013 (rules 8 + 9 in `ADVISOR_SYSTEM_ - **Sample:** 100 personas × 30 turns = 3000 chat calls against live HF Space - **Concurrency:** 4 async workers with 2.0s/dispatch global rate limit (under NIM's 40 req/min cap) - **Expected wall time:** ~2 hours -- **Output:** `audit_results/full_20260514_145243/transcripts/.json` + `report.md` after analyzer pass +- **Output:** `80-audit/full_20260514_145243/transcripts/.json` + `report.md` after analyzer pass - **Resumable:** completed personas' JSONs persist; re-running the script skips them. The audit is the empirical truth-source for the quality sprint. Pre-sprint we expected: high refusal rate, infinite re-ask loops, demographic-mismatched recommendations. Post-sprint we expect: 0 infinite loops (KI-011 + KI-012 fixed), fact-find always asked before recommendations (KI-013), and verbose/casual/Hinglish styles handled gracefully (keyword fast-path in KI-011 fix). diff --git a/docs/60-decisions/ADR-001-vertical-slice-scope.md b/70-docs/60-decisions/ADR-001-vertical-slice-scope.md similarity index 79% rename from docs/60-decisions/ADR-001-vertical-slice-scope.md rename to 70-docs/60-decisions/ADR-001-vertical-slice-scope.md index 2e04383a77f9fc57ae1bdaa92b696765ebf4b75c..81d00b9d83849179908a410effa3c1d47b709b3b 100644 --- a/docs/60-decisions/ADR-001-vertical-slice-scope.md +++ b/70-docs/60-decisions/ADR-001-vertical-slice-scope.md @@ -26,8 +26,8 @@ Build the vertical slice. One category (Health) — but every architectural surf **Positive:** Demonstrates senior-engineer scoping discipline. Every part of the bot a BFSI buyer would audit (provenance, refusal, eval rigor) is real, not stubbed. -**Negative:** Life, Motor, and other categories are not covered. The seven "c-readiness commitments" in `docs/10-architecture/system-overview.md` §7 become real v2 work. +**Negative:** Life, Motor, and other categories are not covered. The seven "c-readiness commitments" in `70-docs/10-architecture/system-overview.md` §7 become real v2 work. ## Revisit at scale (v2) -Category expansion plan in `docs/00-overview/roadmap.md`. Each new category requires: (1) corpus acquisition, (2) per-category schema extension, (3) eval gold set, (4) scorecard sub-score weights. No core code changes. +Category expansion plan in `70-docs/00-overview/roadmap.md`. Each new category requires: (1) corpus acquisition, (2) per-category schema extension, (3) eval gold set, (4) scorecard sub-score weights. No core code changes. diff --git a/docs/60-decisions/ADR-002-health-category-vertical.md b/70-docs/60-decisions/ADR-002-health-category-vertical.md similarity index 100% rename from docs/60-decisions/ADR-002-health-category-vertical.md rename to 70-docs/60-decisions/ADR-002-health-category-vertical.md diff --git a/docs/60-decisions/ADR-003-curated-corpus.md b/70-docs/60-decisions/ADR-003-curated-corpus.md similarity index 100% rename from docs/60-decisions/ADR-003-curated-corpus.md rename to 70-docs/60-decisions/ADR-003-curated-corpus.md diff --git a/docs/60-decisions/ADR-004-hybrid-structured-vector.md b/70-docs/60-decisions/ADR-004-hybrid-structured-vector.md similarity index 100% rename from docs/60-decisions/ADR-004-hybrid-structured-vector.md rename to 70-docs/60-decisions/ADR-004-hybrid-structured-vector.md diff --git a/docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md b/70-docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md similarity index 100% rename from docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md rename to 70-docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md diff --git a/docs/60-decisions/ADR-006-sarvam-first-stack.md b/70-docs/60-decisions/ADR-006-sarvam-first-stack.md similarity index 100% rename from docs/60-decisions/ADR-006-sarvam-first-stack.md rename to 70-docs/60-decisions/ADR-006-sarvam-first-stack.md diff --git a/docs/60-decisions/ADR-007-illustrative-pricing.md b/70-docs/60-decisions/ADR-007-illustrative-pricing.md similarity index 97% rename from docs/60-decisions/ADR-007-illustrative-pricing.md rename to 70-docs/60-decisions/ADR-007-illustrative-pricing.md index edc83fccf9bfe645334ba917c3b97ea53346b55b..27af9c52d32dacb63e82c8671d043a1fe8ff699b 100644 --- a/docs/60-decisions/ADR-007-illustrative-pricing.md +++ b/70-docs/60-decisions/ADR-007-illustrative-pricing.md @@ -45,4 +45,4 @@ Buyers expect to see premium estimates. Indian insurers hide real pricing behind ## Revisit at scale -v2 path: B2B partnership with an aggregator (PolicyBazaar, Ditto, InsuranceDekho) or direct insurer APIs to get real quotes. See `docs/00-overview/roadmap.md` §v2.2. +v2 path: B2B partnership with an aggregator (PolicyBazaar, Ditto, InsuranceDekho) or direct insurer APIs to get real quotes. See `70-docs/00-overview/roadmap.md` §v2.2. diff --git a/docs/60-decisions/ADR-008-consultative-advisor-persona.md b/70-docs/60-decisions/ADR-008-consultative-advisor-persona.md similarity index 100% rename from docs/60-decisions/ADR-008-consultative-advisor-persona.md rename to 70-docs/60-decisions/ADR-008-consultative-advisor-persona.md diff --git a/docs/60-decisions/ADR-009-19-insurer-comprehensive-schema.md b/70-docs/60-decisions/ADR-009-19-insurer-comprehensive-schema.md similarity index 100% rename from docs/60-decisions/ADR-009-19-insurer-comprehensive-schema.md rename to 70-docs/60-decisions/ADR-009-19-insurer-comprehensive-schema.md diff --git a/docs/60-decisions/ADR-010-secret-handling.md b/70-docs/60-decisions/ADR-010-secret-handling.md similarity index 100% rename from docs/60-decisions/ADR-010-secret-handling.md rename to 70-docs/60-decisions/ADR-010-secret-handling.md diff --git a/docs/60-decisions/ADR-011-bge-local-embeddings.md b/70-docs/60-decisions/ADR-011-bge-local-embeddings.md similarity index 100% rename from docs/60-decisions/ADR-011-bge-local-embeddings.md rename to 70-docs/60-decisions/ADR-011-bge-local-embeddings.md diff --git a/docs/60-decisions/ADR-012-render-then-hf-space-deploy.md b/70-docs/60-decisions/ADR-012-render-then-hf-space-deploy.md similarity index 100% rename from docs/60-decisions/ADR-012-render-then-hf-space-deploy.md rename to 70-docs/60-decisions/ADR-012-render-then-hf-space-deploy.md diff --git a/docs/60-decisions/ADR-013-tailwind-shadcn-ui.md b/70-docs/60-decisions/ADR-013-tailwind-shadcn-ui.md similarity index 100% rename from docs/60-decisions/ADR-013-tailwind-shadcn-ui.md rename to 70-docs/60-decisions/ADR-013-tailwind-shadcn-ui.md diff --git a/docs/60-decisions/ADR-014-groq-llama-grader.md b/70-docs/60-decisions/ADR-014-groq-llama-grader.md similarity index 100% rename from docs/60-decisions/ADR-014-groq-llama-grader.md rename to 70-docs/60-decisions/ADR-014-groq-llama-grader.md diff --git a/docs/60-decisions/ADR-015-openapi-typescript-codegen.md b/70-docs/60-decisions/ADR-015-openapi-typescript-codegen.md similarity index 100% rename from docs/60-decisions/ADR-015-openapi-typescript-codegen.md rename to 70-docs/60-decisions/ADR-015-openapi-typescript-codegen.md diff --git a/docs/60-decisions/ADR-016-hybrid-brain-router.md b/70-docs/60-decisions/ADR-016-hybrid-brain-router.md similarity index 100% rename from docs/60-decisions/ADR-016-hybrid-brain-router.md rename to 70-docs/60-decisions/ADR-016-hybrid-brain-router.md diff --git a/docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md b/70-docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md similarity index 100% rename from docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md rename to 70-docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md diff --git a/docs/60-decisions/ADR-018-chunk-size-sweep-deferred.md b/70-docs/60-decisions/ADR-018-chunk-size-sweep-deferred.md similarity index 100% rename from docs/60-decisions/ADR-018-chunk-size-sweep-deferred.md rename to 70-docs/60-decisions/ADR-018-chunk-size-sweep-deferred.md diff --git a/docs/60-decisions/ADR-019-nim-single-provider-consolidation.md b/70-docs/60-decisions/ADR-019-nim-single-provider-consolidation.md similarity index 100% rename from docs/60-decisions/ADR-019-nim-single-provider-consolidation.md rename to 70-docs/60-decisions/ADR-019-nim-single-provider-consolidation.md diff --git a/docs/60-decisions/ADR-020-code-data-split-hf-dataset.md b/70-docs/60-decisions/ADR-020-code-data-split-hf-dataset.md similarity index 100% rename from docs/60-decisions/ADR-020-code-data-split-hf-dataset.md rename to 70-docs/60-decisions/ADR-020-code-data-split-hf-dataset.md diff --git a/docs/60-decisions/ADR-021-view-aware-system-prompt.md b/70-docs/60-decisions/ADR-021-view-aware-system-prompt.md similarity index 100% rename from docs/60-decisions/ADR-021-view-aware-system-prompt.md rename to 70-docs/60-decisions/ADR-021-view-aware-system-prompt.md diff --git a/docs/60-decisions/ADR-022-conversational-profile-updates.md b/70-docs/60-decisions/ADR-022-conversational-profile-updates.md similarity index 100% rename from docs/60-decisions/ADR-022-conversational-profile-updates.md rename to 70-docs/60-decisions/ADR-022-conversational-profile-updates.md diff --git a/docs/60-decisions/ADR-023-admin-panel-ip-gated.md b/70-docs/60-decisions/ADR-023-admin-panel-ip-gated.md similarity index 100% rename from docs/60-decisions/ADR-023-admin-panel-ip-gated.md rename to 70-docs/60-decisions/ADR-023-admin-panel-ip-gated.md diff --git a/docs/60-decisions/ADR-024-triple-mirror-code-and-data.md b/70-docs/60-decisions/ADR-024-triple-mirror-code-and-data.md similarity index 100% rename from docs/60-decisions/ADR-024-triple-mirror-code-and-data.md rename to 70-docs/60-decisions/ADR-024-triple-mirror-code-and-data.md diff --git a/docs/60-decisions/ADR-025-single-chroma-collection-with-metadata-partitioning.md b/70-docs/60-decisions/ADR-025-single-chroma-collection-with-metadata-partitioning.md similarity index 100% rename from docs/60-decisions/ADR-025-single-chroma-collection-with-metadata-partitioning.md rename to 70-docs/60-decisions/ADR-025-single-chroma-collection-with-metadata-partitioning.md diff --git a/docs/60-decisions/ADR-026-provider-load-balancing.md b/70-docs/60-decisions/ADR-026-provider-load-balancing.md similarity index 100% rename from docs/60-decisions/ADR-026-provider-load-balancing.md rename to 70-docs/60-decisions/ADR-026-provider-load-balancing.md diff --git a/docs/60-decisions/ADR-027-fact-find-llm-paraphraser.md b/70-docs/60-decisions/ADR-027-fact-find-llm-paraphraser.md similarity index 100% rename from docs/60-decisions/ADR-027-fact-find-llm-paraphraser.md rename to 70-docs/60-decisions/ADR-027-fact-find-llm-paraphraser.md diff --git a/docs/60-decisions/ADR-028-voice-ux-single-default-mode.md b/70-docs/60-decisions/ADR-028-voice-ux-single-default-mode.md similarity index 100% rename from docs/60-decisions/ADR-028-voice-ux-single-default-mode.md rename to 70-docs/60-decisions/ADR-028-voice-ux-single-default-mode.md diff --git a/docs/60-decisions/ADR-029-hnsw-bloat-tripwire.md b/70-docs/60-decisions/ADR-029-hnsw-bloat-tripwire.md similarity index 96% rename from docs/60-decisions/ADR-029-hnsw-bloat-tripwire.md rename to 70-docs/60-decisions/ADR-029-hnsw-bloat-tripwire.md index 3ab3d79b90790fae68fcdb2864b6581228ec589f..1d865742735036b34507d7803a90aa2a123ee2ff 100644 --- a/docs/60-decisions/ADR-029-hnsw-bloat-tripwire.md +++ b/70-docs/60-decisions/ADR-029-hnsw-bloat-tripwire.md @@ -2,7 +2,7 @@ **Status:** Accepted — 2026-05-14 **Owner:** Rohit Saraf -**Trigger incident:** D-001 in [`audit_results/ENTERPRISE_AUDIT.md`](../../audit_results/ENTERPRISE_AUDIT.md) +**Trigger incident:** D-001 in [`80-audit/ENTERPRISE_AUDIT.md`](../../80-audit/ENTERPRISE_AUDIT.md) ## Context @@ -57,7 +57,7 @@ All three layer-2 + layer-3 scripts live under `~/Library/Scripts/` (NOT `~/Docu ## Related -- D-001 in [`audit_results/ENTERPRISE_AUDIT.md`](../../audit_results/ENTERPRISE_AUDIT.md) +- D-001 in [`80-audit/ENTERPRISE_AUDIT.md`](../../80-audit/ENTERPRISE_AUDIT.md) - [`rag/ingest.py::_abort_if_hnsw_bloated`](../../rag/ingest.py) - `~/Library/Scripts/insurance-bot/check-vector-bloat.sh` - `~/Library/Scripts/cache-prevention/disk-free-tripwire.sh` diff --git a/docs/60-decisions/README.md b/70-docs/60-decisions/README.md similarity index 96% rename from docs/60-decisions/README.md rename to 70-docs/60-decisions/README.md index 4cf997c62146b530585e864f3553f52228127668..50e667abfd87cbbf6e78b5a2d5c2a06ac6e448cb 100644 --- a/docs/60-decisions/README.md +++ b/70-docs/60-decisions/README.md @@ -2,7 +2,7 @@ Each major technical or product decision is captured as a single ADR using a lightly adapted Michael Nygard template: **Status · Context · Decision · Alternatives · Consequences · Revisit-at-scale**. -ADR numbers map 1:1 to the original `D-NNN` entries that lived in the legacy `docs/decisions.md` (now split into individual files for easier review, citation, and supersession tracking). +ADR numbers map 1:1 to the original `D-NNN` entries that lived in the legacy `70-docs/decisions.md` (now split into individual files for easier review, citation, and supersession tracking). ## Index diff --git a/docs/60-decisions/legacy-decisions-monolith.md b/70-docs/60-decisions/legacy-decisions-monolith.md similarity index 100% rename from docs/60-decisions/legacy-decisions-monolith.md rename to 70-docs/60-decisions/legacy-decisions-monolith.md diff --git a/docs/ci-templates/eval-workflow.yml.template b/70-docs/ci-templates/eval-workflow.yml.template similarity index 100% rename from docs/ci-templates/eval-workflow.yml.template rename to 70-docs/ci-templates/eval-workflow.yml.template diff --git a/audit_results/ENTERPRISE_AUDIT.md b/80-audit/ENTERPRISE_AUDIT.md similarity index 100% rename from audit_results/ENTERPRISE_AUDIT.md rename to 80-audit/ENTERPRISE_AUDIT.md diff --git a/audit_results/README.md b/80-audit/README.md similarity index 94% rename from audit_results/README.md rename to 80-audit/README.md index bef2b23cd42a99b5a85239af0fdbbb2512d170dd..c1b5a3c8f7710cf1f3f94d7243470d07076bd7a8 100644 --- a/audit_results/README.md +++ b/80-audit/README.md @@ -1,4 +1,4 @@ -# `audit_results/` — Audit output + production-readiness register +# `80-audit/` — Audit output + production-readiness register Two artefact classes coexist here: @@ -19,7 +19,7 @@ Status emoji: ✅ fixed · ⚠️ partial · 🟡 improving · 🔴 open. ## Run-directory layout ``` -audit_results/ +80-audit/ ├── ENTERPRISE_AUDIT.md └── / ├── transcripts/ @@ -55,7 +55,7 @@ audit_results/ ## How runs flow into the register 1. `python tools/audit/run_audit.py` writes per-persona transcripts. -2. `python tools/audit/analyze.py audit_results//` rolls up `report.md` + `summary.json`. +2. `python tools/audit/analyze.py 80-audit//` rolls up `report.md` + `summary.json`. 3. New defects → new `D-NNN` row in `ENTERPRISE_AUDIT.md`. 4. Fixes → status flipped, run re-executed as `postfix_…`, evidence linked. diff --git a/CLAUDE.md b/CLAUDE.md index eede8489ef64ccaf6a8d0e2f2ccbb9fee6634add..d7f2765d04ef4cc85647d2c1724b85b01bcb3db8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md — project memory for AI assistants -This file is read by Claude Code (and any compatible AI tool) at the start of a session in this repo. Keep it under ~200 lines and focused on **stable, non-obvious facts a new contributor would need**. For change history, look at git log, `audit_results/ENTERPRISE_AUDIT.md`, and `docs/60-decisions/`. +This file is read by Claude Code (and any compatible AI tool) at the start of a session in this repo. Keep it under ~200 lines and focused on **stable, non-obvious facts a new contributor would need**. For change history, look at git log, `80-audit/ENTERPRISE_AUDIT.md`, and `70-docs/60-decisions/`. ## Project at a glance @@ -63,8 +63,8 @@ Three independent safety layers against ChromaDB HNSW bloat: ## What to read for what - **System tour:** `README.md` (the master entry). -- **Decisions with alternatives:** `docs/60-decisions/ADR-*.md` (28 ADRs as of 2026-05-14). -- **Production-readiness defect register:** `audit_results/ENTERPRISE_AUDIT.md`. +- **Decisions with alternatives:** `70-docs/60-decisions/ADR-*.md` (28 ADRs as of 2026-05-14). +- **Production-readiness defect register:** `80-audit/ENTERPRISE_AUDIT.md`. - **Data lineage:** `kb/AUDIT_TRAIL.md`. - **Tests:** `tests/test_routing_regression.py` (15 tests pinning routing + load-balance invariants). diff --git a/README.md b/README.md index ceae19f8388881c43bda7a29bad6fb9ab516d05c..b710019ab2909e2ad60ebdf392d02891ec484fd9 100644 --- a/README.md +++ b/README.md @@ -67,13 +67,13 @@ If a question refuses unexpectedly, that's the safe failure mode — open `logs/ A take-home is a sample of how the engineer thinks under constraint. Three things this submission is meant to signal: -1. **Scope to a vertical slice, not a demo.** [ADR-001](docs/60-decisions/ADR-001-vertical-slice-scope.md) explicitly chose vertical slice over single-document RAG or full-platform. The build's 7 commitments — per-insurer adapters, category-agnostic schema, pluggable extraction, schema-driven filter UI, provider-agnostic STT/TTS/LLM, eval harness that scales linearly, stateless services — make v2 (life / motor insurance) a data + config change, not a rewrite. +1. **Scope to a vertical slice, not a demo.** [ADR-001](70-docs/60-decisions/ADR-001-vertical-slice-scope.md) explicitly chose vertical slice over single-document RAG or full-platform. The build's 7 commitments — per-insurer adapters, category-agnostic schema, pluggable extraction, schema-driven filter UI, provider-agnostic STT/TTS/LLM, eval harness that scales linearly, stateless services — make v2 (life / motor insurance) a data + config change, not a rewrite. 2. **Hallucination defense and refusal as product features.** BFSI deployments get fined for mis-selling; the bot is biased toward refusal over confident wrong answers. The 4 faithfulness gates + cross-check retry + 3 Indic drift checks + audit log are the BFSI-compliance-grade version of "we shipped a chatbot." When the eval shows a headline accuracy below 100% because the gates are aggressive, the right response is to soften the gates carefully — not to ship a higher number by relaxing the verifier. 3. **Honest model picks — Sarvam where Sarvam is uniquely strong, open-weights frontier for reasoning.** Sarvam Saarika v2.5 STT, Bulbul v2 TTS, and Sarvam-M Indic translation are *non-substitutable* — no closed-source frontier matches them on Indian voice or Hinglish. Reasoning is a different problem; the brain runs a fallback chain whose primary rotates 50/50 between **NIM Qwen 3-Next 80B** and **Groq Llama-3.3-70B** (ADR-026 — 2× sustained throughput across two free-tier providers), with the judge on **Mistral Large 3 675B** for non-circular grading. A Sarvam customer deploying this stack gets a product that *uses Sarvam exactly where Sarvam beats the world* and uses MIT-licensed frontier weights for everything else — open-weights only, $0 inference, single API key per provider for the entire non-voice stack. -The rest is craftsmanship. The 8-section KB ([`kb/`](kb/)) is regeneratable from primary sources in <40 minutes for <$2 cold. Every numeric value in every reviewer-facing artifact traces to a source PDF + page + clause. Every architectural decision is in [`docs/60-decisions/`](docs/60-decisions/) with alternatives and revisit-at-scale notes. Every production-readiness defect is in [`audit_results/ENTERPRISE_AUDIT.md`](audit_results/ENTERPRISE_AUDIT.md). The repo is structured so a new engineer joining on Monday could ship v1.1 by Friday. +The rest is craftsmanship. The 8-section KB ([`kb/`](kb/)) is regeneratable from primary sources in <40 minutes for <$2 cold. Every numeric value in every reviewer-facing artifact traces to a source PDF + page + clause. Every architectural decision is in [`70-docs/60-decisions/`](70-docs/60-decisions/) with alternatives and revisit-at-scale notes. Every production-readiness defect is in [`80-audit/ENTERPRISE_AUDIT.md`](80-audit/ENTERPRISE_AUDIT.md). The repo is structured so a new engineer joining on Monday could ship v1.1 by Friday. --- @@ -111,15 +111,15 @@ A **voice-first conversational advisor** that: | Cross-policy comparison | ✓ live (DuckDB structured + Chroma vectors) | | Personalised scorecards | ✓ live (profile RAG — profile becomes a vector chunk) | | Refusal precision (refuse > mis-cite) | ✓ live (Gate 1-4) | -| Regulatory grounding (IRDAI) | ✓ live (after Playwright rescue past Akamai bot protection — [ADR-017](docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md)) | -| Admin LLM control panel | ✓ live (in-app tab, IP+password gated — [ADR-023](docs/60-decisions/ADR-023-admin-panel-ip-gated.md)) | +| Regulatory grounding (IRDAI) | ✓ live (after Playwright rescue past Akamai bot protection — [ADR-017](70-docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md)) | +| Admin LLM control panel | ✓ live (in-app tab, IP+password gated — [ADR-023](70-docs/60-decisions/ADR-023-admin-panel-ip-gated.md)) | ### 2.4 Explicit non-goals (v1) -- **Real-time quotes** — premiums are illustrative bands with disclaimer ([ADR-007](docs/60-decisions/ADR-007-illustrative-pricing.md)). +- **Real-time quotes** — premiums are illustrative bands with disclaimer ([ADR-007](70-docs/60-decisions/ADR-007-illustrative-pricing.md)). - **Medical advice** — bot answers coverage questions, never clinical ones (persona rule 4). - **Token-streaming LLM responses** — replies arrive as full messages today; token-by-token SSE is a v2 roadmap item. -- **Life / motor insurance** — v1 is health-only; v2 generalises ([ADR-002](docs/60-decisions/ADR-002-health-category-vertical.md)). +- **Life / motor insurance** — v1 is health-only; v2 generalises ([ADR-002](70-docs/60-decisions/ADR-002-health-category-vertical.md)). - **Sentiment classifier on raw scraped reviews** — IRDAI complaint numbers are primary-source; sentiment labels are curated snippet roll-ups, not LLM-extracted. --- @@ -556,28 +556,28 @@ Every LLM role is served by a **fallback chain** of candidate models (`backend/p Per-call budgets: brain `20s × 35s total`, fast-brain `12s × 22s total`, judge `30s × 75s total`. The per-link timeout is dynamically clipped to remaining budget so a single fallback can never blow past the chain ceiling. -**Provider load balancing.** The brain chain primary rotates 50/50 per call between NIM Qwen and Groq Llama-3.3 (`_balanced_brain_chain` in `backend/providers/nvidia_nim_llm.py`). Spreads load across two independent rate caps (NIM 40 req/min + Groq's separate quota) — effectively 2× sustained brain throughput. See [`ADR-026`](docs/60-decisions/ADR-026-provider-load-balancing.md). +**Provider load balancing.** The brain chain primary rotates 50/50 per call between NIM Qwen and Groq Llama-3.3 (`_balanced_brain_chain` in `backend/providers/nvidia_nim_llm.py`). Spreads load across two independent rate caps (NIM 40 req/min + Groq's separate quota) — effectively 2× sustained brain throughput. See [`ADR-026`](70-docs/60-decisions/ADR-026-provider-load-balancing.md). ### 4.4 Major design decisions (the short list) | Decision | Choice | Detail | |---|---|---| -| Scope shape | Vertical slice, one category | [ADR-001](docs/60-decisions/ADR-001-vertical-slice-scope.md) | -| Category | Health | [ADR-002](docs/60-decisions/ADR-002-health-category-vertical.md) | -| Corpus origin | Curated, not user-upload | [ADR-003](docs/60-decisions/ADR-003-curated-corpus.md) | -| Retrieval | Hybrid structured + vector | [ADR-004](docs/60-decisions/ADR-004-hybrid-structured-vector.md) | -| Frontend stack | Next.js 14 + FastAPI | [ADR-005](docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md) | -| Pricing | Illustrative, never quote | [ADR-007](docs/60-decisions/ADR-007-illustrative-pricing.md) | -| Persona | Consultative advisor (IFA) | [ADR-008](docs/60-decisions/ADR-008-consultative-advisor-persona.md) | -| Embeddings | Local BGE-small | [ADR-011](docs/60-decisions/ADR-011-bge-local-embeddings.md) | -| LLM provider | NIM single provider | [ADR-019](docs/60-decisions/ADR-019-nim-single-provider-consolidation.md) | -| Code vs data | Two-repo + HF Dataset | [ADR-020](docs/60-decisions/ADR-020-code-data-split-hf-dataset.md) | -| View-aware chat | system prompt injection | [ADR-021](docs/60-decisions/ADR-021-view-aware-system-prompt.md) | -| Profile updates in chat | LLM extractor | [ADR-022](docs/60-decisions/ADR-022-conversational-profile-updates.md) | -| Admin panel | IP+password gated, in-app tab | [ADR-023](docs/60-decisions/ADR-023-admin-panel-ip-gated.md) | -| Resilience | Triple-mirror code + data | [ADR-024](docs/60-decisions/ADR-024-triple-mirror-code-and-data.md) | - -Every D-NNN in the legacy decisions log is now a stand-alone ADR — see [`docs/60-decisions/README.md`](docs/60-decisions/README.md) for the full 24-entry index. +| Scope shape | Vertical slice, one category | [ADR-001](70-docs/60-decisions/ADR-001-vertical-slice-scope.md) | +| Category | Health | [ADR-002](70-docs/60-decisions/ADR-002-health-category-vertical.md) | +| Corpus origin | Curated, not user-upload | [ADR-003](70-docs/60-decisions/ADR-003-curated-corpus.md) | +| Retrieval | Hybrid structured + vector | [ADR-004](70-docs/60-decisions/ADR-004-hybrid-structured-vector.md) | +| Frontend stack | Next.js 14 + FastAPI | [ADR-005](70-docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md) | +| Pricing | Illustrative, never quote | [ADR-007](70-docs/60-decisions/ADR-007-illustrative-pricing.md) | +| Persona | Consultative advisor (IFA) | [ADR-008](70-docs/60-decisions/ADR-008-consultative-advisor-persona.md) | +| Embeddings | Local BGE-small | [ADR-011](70-docs/60-decisions/ADR-011-bge-local-embeddings.md) | +| LLM provider | NIM single provider | [ADR-019](70-docs/60-decisions/ADR-019-nim-single-provider-consolidation.md) | +| Code vs data | Two-repo + HF Dataset | [ADR-020](70-docs/60-decisions/ADR-020-code-data-split-hf-dataset.md) | +| View-aware chat | system prompt injection | [ADR-021](70-docs/60-decisions/ADR-021-view-aware-system-prompt.md) | +| Profile updates in chat | LLM extractor | [ADR-022](70-docs/60-decisions/ADR-022-conversational-profile-updates.md) | +| Admin panel | IP+password gated, in-app tab | [ADR-023](70-docs/60-decisions/ADR-023-admin-panel-ip-gated.md) | +| Resilience | Triple-mirror code + data | [ADR-024](70-docs/60-decisions/ADR-024-triple-mirror-code-and-data.md) | + +Every D-NNN in the legacy decisions log is now a stand-alone ADR — see [`70-docs/60-decisions/README.md`](70-docs/60-decisions/README.md) for the full 24-entry index. --- @@ -617,7 +617,7 @@ data/reviews/.json (IRDAI complaints/10K kb/policies/.md (markdown writeup; regen via rag/build_kb.py) ``` -Full per-stage detail: [`docs/20-data-pipeline/ingestion-policy.md`](docs/20-data-pipeline/ingestion-policy.md). +Full per-stage detail: [`70-docs/20-data-pipeline/ingestion-policy.md`](70-docs/20-data-pipeline/ingestion-policy.md). ### 5.3 Storage topology @@ -674,7 +674,7 @@ Honest current numbers (2026-05-12 run on 25 questions): | Metric | Value | Comment | |---|---|---| -| Factual accuracy | 40.0% | See [`audit_results/ENTERPRISE_AUDIT.md`](audit_results/ENTERPRISE_AUDIT.md) for the post-fix baseline + per-question-type breakdown | +| Factual accuracy | 40.0% | See [`80-audit/ENTERPRISE_AUDIT.md`](80-audit/ENTERPRISE_AUDIT.md) for the post-fix baseline + per-question-type breakdown | | Citation accuracy | 50.0% | Same | | Refusal precision | 44.4% | Same | | Blocked by faithfulness | 12 / 25 | Gates working; aggressively biased toward refusal | @@ -685,10 +685,10 @@ The headline number reflects an aggressive gate posture (refuse > mis-cite) — ## 7. Document ecosystem guide -The repo's documentation lives in `docs/`, organised into 8 numbered buckets. Numeric prefixes sort buckets in reading order; files inside each bucket use `kebab-case` for URL safety and grep-friendliness. +The repo's documentation lives in `70-docs/`, organised into 8 numbered buckets. Numeric prefixes sort buckets in reading order; files inside each bucket use `kebab-case` for URL safety and grep-friendliness. ``` -docs/ +70-docs/ ├── 00-overview/ ← "what is this and why does it exist" ├── 10-architecture/ ← "how it works" (deep dives) ├── 20-data-pipeline/ ← "where the knowledge comes from" @@ -698,7 +698,7 @@ docs/ ├── 60-decisions/ ← Architecture Decision Records (ADRs 001-028) └── 70-reference/ ← Schemas, glossary, indexes -audit_results/ ← Production-readiness audit + defect register +80-audit/ ← Production-readiness audit + defect register ├── ENTERPRISE_AUDIT.md ← Master defect log (severity, evidence, fix status) └── full_/ ← Per-run audit transcripts + analyzed reports ``` @@ -707,22 +707,22 @@ audit_results/ ← Production-readiness audit + defect register | Bucket | What's there now | What to read for what | |---|---|---| -| `00-overview/` | [`problem-statement.md`](docs/00-overview/problem-statement.md), [`roadmap.md`](docs/00-overview/roadmap.md) | Start here for product context, requirements, success criteria, v2 plan | -| `10-architecture/` | [`system-overview.md`](docs/10-architecture/system-overview.md), [`stack-rationale.md`](docs/10-architecture/stack-rationale.md), [`safety-architecture.md`](docs/10-architecture/safety-architecture.md), [`scoring-methodology.md`](docs/10-architecture/scoring-methodology.md), [`scoring-knowledge-graph.md`](docs/10-architecture/scoring-knowledge-graph.md), [`scoring-tie-breaker-rubric.md`](docs/10-architecture/scoring-tie-breaker-rubric.md) | How the system is built; the why behind each stack choice; how scoring works | -| `20-data-pipeline/` | [`ingestion-policy.md`](docs/20-data-pipeline/ingestion-policy.md), [`information-source-map.md`](docs/20-data-pipeline/information-source-map.md) | How PDFs become chunks; where every source URL lives + audit status | -| `30-engineering/` | [`needs-analysis-flow.md`](docs/30-engineering/needs-analysis-flow.md), [`discovery-script.md`](docs/30-engineering/discovery-script.md) | How the fact-find loop works; discovery script for new contributors | -| `40-evaluation/` | [`eval-methodology.md`](docs/40-evaluation/eval-methodology.md) | Gold-Q&A design, grader choice, results interpretation | +| `00-overview/` | [`problem-statement.md`](70-docs/00-overview/problem-statement.md), [`roadmap.md`](70-docs/00-overview/roadmap.md) | Start here for product context, requirements, success criteria, v2 plan | +| `10-architecture/` | [`system-overview.md`](70-docs/10-architecture/system-overview.md), [`stack-rationale.md`](70-docs/10-architecture/stack-rationale.md), [`safety-architecture.md`](70-docs/10-architecture/safety-architecture.md), [`scoring-methodology.md`](70-docs/10-architecture/scoring-methodology.md), [`scoring-knowledge-graph.md`](70-docs/10-architecture/scoring-knowledge-graph.md), [`scoring-tie-breaker-rubric.md`](70-docs/10-architecture/scoring-tie-breaker-rubric.md) | How the system is built; the why behind each stack choice; how scoring works | +| `20-data-pipeline/` | [`ingestion-policy.md`](70-docs/20-data-pipeline/ingestion-policy.md), [`information-source-map.md`](70-docs/20-data-pipeline/information-source-map.md) | How PDFs become chunks; where every source URL lives + audit status | +| `30-engineering/` | [`needs-analysis-flow.md`](70-docs/30-engineering/needs-analysis-flow.md), [`discovery-script.md`](70-docs/30-engineering/discovery-script.md) | How the fact-find loop works; discovery script for new contributors | +| `40-evaluation/` | [`eval-methodology.md`](70-docs/40-evaluation/eval-methodology.md) | Gold-Q&A design, grader choice, results interpretation | | `50-operations/` | (operational runbooks — to be filled) | How to run, deploy, debug | -| `60-decisions/` | 28 ADRs + [`README.md`](docs/60-decisions/README.md) index + `legacy-decisions-monolith.md` archive | The full decision history with alternatives and supersession tracking | +| `60-decisions/` | 28 ADRs + [`README.md`](70-docs/60-decisions/README.md) index + `legacy-decisions-monolith.md` archive | The full decision history with alternatives and supersession tracking | | `70-reference/` | (schemas + glossary — to be filled) | BFSI terms, insurer slug map, citation grammar | -| `audit_results/` | [`ENTERPRISE_AUDIT.md`](audit_results/ENTERPRISE_AUDIT.md) + per-run audit transcripts | Production-readiness defect register with severity, evidence, fix status. Multi-persona simulation transcripts from the audit runner. | +| `80-audit/` | [`ENTERPRISE_AUDIT.md`](80-audit/ENTERPRISE_AUDIT.md) + per-run audit transcripts | Production-readiness defect register with severity, evidence, fix status. Multi-persona simulation transcripts from the audit runner. | ### 7.2 Root-level documents | File | Purpose | |---|---| | `README.md` (this file) | Master entry point + executive bible | -| `ARCHITECTURE.md` | One-page diagram + index into `docs/10-architecture/` | +| `ARCHITECTURE.md` | One-page diagram + index into `70-docs/10-architecture/` | | `QUICKSTART.md` | Run-locally-in-5-minutes guide (see §8 below) | | `Dockerfile` | Production build — pulls dataset at build time, serves Next.js + FastAPI | | `entrypoint.sh` | Docker entrypoint — boots both processes | @@ -732,10 +732,10 @@ audit_results/ ← Production-readiness audit + defect register ### 7.3 Navigation shortcuts - **Reviewer with 20 minutes:** read this README end-to-end. -- **Engineer joining the project:** read [`docs/00-overview/problem-statement.md`](docs/00-overview/problem-statement.md) → [`docs/10-architecture/system-overview.md`](docs/10-architecture/system-overview.md) → [`docs/60-decisions/README.md`](docs/60-decisions/README.md) → trace `backend/orchestrator.py`. -- **Compliance auditor:** read [`docs/10-architecture/safety-architecture.md`](docs/10-architecture/safety-architecture.md) → `logs/hallucinations.jsonl` → [`kb/AUDIT_TRAIL.md`](kb/AUDIT_TRAIL.md). -- **Production readiness reviewer:** read [`audit_results/ENTERPRISE_AUDIT.md`](audit_results/ENTERPRISE_AUDIT.md) for the master defect register (severity-tagged, with evidence + fix status) and [`audit_results/full_/report.md`](audit_results/) for the latest persona-simulation findings. -- **Replicating the data pipeline:** read [`docs/20-data-pipeline/ingestion-policy.md`](docs/20-data-pipeline/ingestion-policy.md) → trace `rag/extract.py` + `rag/ingest.py`. +- **Engineer joining the project:** read [`70-docs/00-overview/problem-statement.md`](70-docs/00-overview/problem-statement.md) → [`70-docs/10-architecture/system-overview.md`](70-docs/10-architecture/system-overview.md) → [`70-docs/60-decisions/README.md`](70-docs/60-decisions/README.md) → trace `backend/orchestrator.py`. +- **Compliance auditor:** read [`70-docs/10-architecture/safety-architecture.md`](70-docs/10-architecture/safety-architecture.md) → `logs/hallucinations.jsonl` → [`kb/AUDIT_TRAIL.md`](kb/AUDIT_TRAIL.md). +- **Production readiness reviewer:** read [`80-audit/ENTERPRISE_AUDIT.md`](80-audit/ENTERPRISE_AUDIT.md) for the master defect register (severity-tagged, with evidence + fix status) and [`80-audit/full_/report.md`](80-audit/) for the latest persona-simulation findings. +- **Replicating the data pipeline:** read [`70-docs/20-data-pipeline/ingestion-policy.md`](70-docs/20-data-pipeline/ingestion-policy.md) → trace `rag/extract.py` + `rag/ingest.py`. --- @@ -770,7 +770,7 @@ cp -R rag/_hf_dataset_backup/rag/* rag/ # corpus/, extracted/, vectors/ ```bash cp .env.example .env -# Edit .env and fill in the 8 keys (see docs/60-decisions/ADR-010-secret-handling.md): +# Edit .env and fill in the 8 keys (see 70-docs/60-decisions/ADR-010-secret-handling.md): # SARVAM_API_KEY, VOYAGE_API_KEY, NVIDIA_NIM_API_KEY, HF_TOKEN, # ADMIN_PASSWORD, ADMIN_IP_ALLOWLIST, GROQ_API_KEY, OPENROUTER_API_KEY chmod 600 .env @@ -872,7 +872,7 @@ This section is written so a fresh **Claude Code** session pointed at an empty d ### 10.2 Build sequence -1. **Corpus acquisition** — use `tools/` agent crawl + Playwright fallback (see [ADR-017](docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md)) to fetch 19 insurers' PDFs + 18 regulatory PDFs into `rag/corpus/`. +1. **Corpus acquisition** — use `tools/` agent crawl + Playwright fallback (see [ADR-017](70-docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md)) to fetch 19 insurers' PDFs + 18 regulatory PDFs into `rag/corpus/`. 2. **Structured extraction** — `rag/extract.py` runs fast-brain chain (Nemotron 30B / Qwen 80B / Groq Llama-3.3 fallback) over each PDF with the 62-field Pydantic schema. Output to `rag/extracted/.json`. @@ -897,7 +897,7 @@ This section is written so a fresh **Claude Code** session pointed at an empty d A new Claude Code session should ingest these to bootstrap understanding: 1. **This README** — entire project context. -3. **[`docs/60-decisions/`](docs/60-decisions/)** — 24 ADRs covering every meaningful decision. +3. **[`70-docs/60-decisions/`](70-docs/60-decisions/)** — 24 ADRs covering every meaningful decision. 4. **[`backend/orchestrator.py`](backend/orchestrator.py)** — the single file that defines a turn. 5. **[`backend/faithfulness.py`](backend/faithfulness.py)** — the 4-gate verifier. 6. **[`backend/persona.py`](backend/persona.py)** — the system prompt + message builder. @@ -929,4 +929,4 @@ Code: https://github.com/rohitsar567/insurance-sales-bot Data: https://github.com/rohitsar567/insurance-sales-bot-data Contact: rohitsar567@gmail.com -If you're reviewing this for Sarvam: thank you for your time. Every architectural choice is in [`docs/60-decisions/`](docs/60-decisions/) with alternatives and reasoning. Every refusal in the demo is logged in `logs/hallucinations.jsonl` with the failing gate. The project is structured so a new engineer could ship v1.1 by Friday. +If you're reviewing this for Sarvam: thank you for your time. Every architectural choice is in [`70-docs/60-decisions/`](70-docs/60-decisions/) with alternatives and reasoning. Every refusal in the demo is logged in `logs/hallucinations.jsonl` with the failing gate. The project is structured so a new engineer could ship v1.1 by Friday. diff --git a/backend/README.md b/backend/README.md index 539a7831b3bd077b78502569787a08d190be059e..4bc38de80bd8e200d8240c4bca61a7a47c80b7f8 100644 --- a/backend/README.md +++ b/backend/README.md @@ -14,21 +14,21 @@ FastAPI + Pydantic service that fronts every chat turn. The HTTP entry point is | File | Role | Related ADR | | --- | --- | --- | -| `needs_finder.py` | 9-slot fact-find graph (`GRAPH`) + slot detection from free text. | [ADR-027](../docs/60-decisions/ADR-027-fact-find-llm-paraphraser.md) | +| `needs_finder.py` | 9-slot fact-find graph (`GRAPH`) + slot detection from free text. | [ADR-027](../70-docs/60-decisions/ADR-027-fact-find-llm-paraphraser.md) | | `question_paraphraser.py` | LLM rewrite of the canonical slot question so each session sounds fresh; verifier rejects off-slot drift. Cached per `(session_id, slot_id)`. | ADR-027 | | `fact_find_normalizer.py` | LLM-driven free-text → slot-value coercion (e.g. "32 lakh" → `3200000`). Goes through `NimChainLLM`, not a single client (KI-033). | — | -| `profile_extractor.py` | LLM extractor that pulls profile updates out of conversational asides ("by the way, my dad has diabetes"). Chain-pattern, never a hardcoded model. | [ADR-022](../docs/60-decisions/ADR-022-conversational-profile-updates.md) | +| `profile_extractor.py` | LLM extractor that pulls profile updates out of conversational asides ("by the way, my dad has diabetes"). Chain-pattern, never a hardcoded model. | [ADR-022](../70-docs/60-decisions/ADR-022-conversational-profile-updates.md) | | `profile_store.py` | **NEW (KI-040).** Persistent named-profile JSON store under `data/profiles/`. O(1) name-keyed lookup; mirrors into `profile_rag` on every save. | — | | `profile_rag.py` | Embeds the user's profile as a Chroma chunk so the brain sees it alongside policy chunks for "what's best for me?" turns. | — | | `session_state.py` | In-memory session map; tracks fact-find progress + chat history per `session_id`. | | `faithfulness.py` | 4-gate hallucination guard (retrieval floor → citation integrity → regex numeric grounding → LLM judge). Blocks land in `logs/hallucinations.jsonl`. | — | | `scorecard.py` | Pure-function 6-sub-score scorer over the 62-field extracted JSON. No LLM. | — | -| `translator.py` | Sarvam-M Indic ↔ English translator wrapper. | [ADR-006](../docs/60-decisions/ADR-006-sarvam-first-stack.md) | +| `translator.py` | Sarvam-M Indic ↔ English translator wrapper. | [ADR-006](../70-docs/60-decisions/ADR-006-sarvam-first-stack.md) | | `translation_check.py` | Post-hoc detector for mixed-script replies; flags Hinglish leakage. | — | -| `persona.py` | The consultative-advisor system prompt + view-aware prompt overlays. | [ADR-008](../docs/60-decisions/ADR-008-consultative-advisor-persona.md), [ADR-021](../docs/60-decisions/ADR-021-view-aware-system-prompt.md) | +| `persona.py` | The consultative-advisor system prompt + view-aware prompt overlays. | [ADR-008](../70-docs/60-decisions/ADR-008-consultative-advisor-persona.md), [ADR-021](../70-docs/60-decisions/ADR-021-view-aware-system-prompt.md) | | `voice_format.py` | Strips markdown / lists / bullet glyphs so TTS sounds natural. | — | -| `premium_calculator.py` | Looks up `data/premiums/illustrative_premiums.json` + applies the documented scaling factors. Never claims a real quote. | [ADR-007](../docs/60-decisions/ADR-007-illustrative-pricing.md) | -| `security.py` | Request rate-limiting, input sanitisation, admin-IP allowlist. | [ADR-023](../docs/60-decisions/ADR-023-admin-panel-ip-gated.md) | +| `premium_calculator.py` | Looks up `data/premiums/illustrative_premiums.json` + applies the documented scaling factors. Never claims a real quote. | [ADR-007](../70-docs/60-decisions/ADR-007-illustrative-pricing.md) | +| `security.py` | Request rate-limiting, input sanitisation, admin-IP allowlist. | [ADR-023](../70-docs/60-decisions/ADR-023-admin-panel-ip-gated.md) | | `admin.py` | Admin-only routes (live LLM-health, usage rollups, hallucination tail). | ADR-023 | | `llm_health.py` | Lightweight probe that pings each provider and writes `data/llm_health.json` for the admin tab. | — | @@ -40,6 +40,6 @@ FastAPI + Pydantic service that fronts every chat turn. The HTTP entry point is - **System tour:** root `README.md` - **Stable contracts a new contributor must know:** root `CLAUDE.md` -- **Decisions with alternatives:** `docs/60-decisions/ADR-*.md` +- **Decisions with alternatives:** `70-docs/60-decisions/ADR-*.md` - **Routing invariants:** `tests/test_routing_regression.py` -- **Defect register:** `audit_results/ENTERPRISE_AUDIT.md` +- **Defect register:** `80-audit/ENTERPRISE_AUDIT.md` diff --git a/backend/main.py b/backend/main.py index abac4515fcf4a8276ca6b2a382ff52790ff855cb..01e00a941a7a5116c770cd35fe9f38cbaeaea410 100644 --- a/backend/main.py +++ b/backend/main.py @@ -1150,7 +1150,7 @@ async def policy_scorecard( """Compute the 6-sub-score A-F scorecard for an extracted policy. Now also pulls insurer-level reviews (IRDAI claim ratio + complaints) into - the Claim Experience sub-score. See docs/scorecard-methodology.md. + the Claim Experience sub-score. See 70-docs/scorecard-methodology.md. """ import json as _json diff --git a/backend/providers/README.md b/backend/providers/README.md index af3e41366b1f01c243e5f4dd5d3fc773301b8b7f..38a8aa1afb044b211718d2f7b090d7f5b180c4d0 100644 --- a/backend/providers/README.md +++ b/backend/providers/README.md @@ -7,13 +7,13 @@ Every external model is fronted by a small typed client here. The orchestrator a | File | Provider | Role | Notes | | --- | --- | --- | --- | | `base.py` | — | Abstract `LLM`, `STT`, `TTS`, `Embeddings` Protocols. Every concrete client conforms. | — | -| `nvidia_nim_llm.py` | NVIDIA NIM | Core chain runner — `NimChainLLM(chain=[...])` walks a fallback ladder under a wall-clock budget. Exposes `get_brain_llm()`, `get_fast_brain_llm()`, `get_judge_llm()`. Also home of `_balanced_brain_chain()` (50/50 NIM ↔ Groq rotator). | [ADR-019](../../docs/60-decisions/ADR-019-nim-single-provider-consolidation.md), [ADR-026](../../docs/60-decisions/ADR-026-provider-load-balancing.md) | -| `groq_llm.py` | Groq | Single-call Llama-3.3-70B client. Used as the 50% load-balance primary for the brain chain, never standalone. | [ADR-026](../../docs/60-decisions/ADR-026-provider-load-balancing.md) | +| `nvidia_nim_llm.py` | NVIDIA NIM | Core chain runner — `NimChainLLM(chain=[...])` walks a fallback ladder under a wall-clock budget. Exposes `get_brain_llm()`, `get_fast_brain_llm()`, `get_judge_llm()`. Also home of `_balanced_brain_chain()` (50/50 NIM ↔ Groq rotator). | [ADR-019](../../70-docs/60-decisions/ADR-019-nim-single-provider-consolidation.md), [ADR-026](../../70-docs/60-decisions/ADR-026-provider-load-balancing.md) | +| `groq_llm.py` | Groq | Single-call Llama-3.3-70B client. Used as the 50% load-balance primary for the brain chain, never standalone. | [ADR-026](../../70-docs/60-decisions/ADR-026-provider-load-balancing.md) | | `openrouter_llm.py` | OpenRouter | Multi-model fallback rung (DeepSeek-V3 etc.) for chains; rarely the primary in production. | — | -| `sarvam_llm.py` | Sarvam-M | Indic-aware LLM; on the judge / translator fallback chains and used by `backend/translator.py`. | [ADR-006](../../docs/60-decisions/ADR-006-sarvam-first-stack.md) | +| `sarvam_llm.py` | Sarvam-M | Indic-aware LLM; on the judge / translator fallback chains and used by `backend/translator.py`. | [ADR-006](../../70-docs/60-decisions/ADR-006-sarvam-first-stack.md) | | `sarvam_stt.py` | Sarvam Saarika v2.5 | Speech-to-text (10 Indic languages + English). | ADR-006 | | `sarvam_tts.py` | Sarvam Bulbul v2 | Text-to-speech; returns base64 WAV the frontend mounts in the in-DOM `