Repository navigation
Expand file tree
/
Copy pathinteractive.html
More file actions
1 lines (1 loc) · 11.7 KB
/
Copy pathinteractive.html
File metadata and controls
1 lines (1 loc) · 11.7 KB
1
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Explore the actual IntelliRAG web pipeline, its source files and its failure boundaries."><title>IntelliRAG | source to answer</title><style>*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:#f6f9f7;color:#242b31;font:16px/1.6 system-ui,sans-serif}main{max-width:1120px;margin:auto;padding:40px 24px 64px}header{max-width:780px}h1{font-size:clamp(30px,5vw,44px);line-height:1.15;letter-spacing:-.035em;margin:10px 0 16px}h2{font-size:24px;letter-spacing:-.02em;margin-top:40px}h3{font-size:20px;margin:0 0 12px}p{margin:12px 0}.eyebrow,small{color:#52616c}.eyebrow{font-size:12px;letter-spacing:.1em;font-weight:600}a{color:#246e62;text-underline-offset:3px}a:focus-visible,summary:focus-visible{outline:3px solid #246e62;outline-offset:4px}.overview{margin:28px 0;overflow:auto;border:1px solid #ccd8d4;border-radius:10px;background:white}.overview img{display:block;width:100%;min-width:650px}.caption{font-size:14px;color:#52616c}.lanes{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:16px;align-items:start}details{background:white;border:1px solid #ccd8d4;border-radius:8px;overflow:hidden}summary{padding:18px;min-height:90px;cursor:pointer;list-style-position:inside;font-weight:600}summary small{display:block;font-weight:400;margin-top:6px}.num{color:#246e62;font-size:12px;padding-right:8px}.detail{padding:0 18px 20px}.detail p{font-size:15px}code{font:13px/1.6 ui-monospace,monospace;overflow-wrap:anywhere}.sources{padding-top:10px;border-top:1px solid #e2e8e5}.sources a{display:block;padding:3px 0}.check{background:#f1f5f3;border-left:3px solid #246e62;padding:10px 12px;font-size:14px}.notice{background:white;padding:18px 20px;border:1px solid #ccd8d4;border-radius:8px}footer{border-top:1px solid #ccd8d4;margin-top:36px;padding-top:18px;color:#52616c;font-size:14px}@media(max-width:700px){main{padding:24px 16px 40px}.lanes{grid-template-columns:1fr}.overview img{min-width:650px}h2{margin-top:30px}summary{min-height:84px}}@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}}</style></head><body><main><header><p class="eyebrow">INTELLIRAG / WEB ARCHITECTURE</p><h1>Follow the evidence.<br>Then trust the answer.</h1><p>A source-to-answer map of the TypeScript web app. Open a stage to see its job, its failure boundary and the code that owns it.</p><p class="caption">Code inspected at <code>b431f76</code>, 17 October 2026. The Python platform is a separate implementation.</p></header><div class="notice"><strong>The short version</strong><p>Import sources once. On a question, check a revision-aware cache, retrieve and pack passages, then classify the evidence. An optional second-opinion gate can make the gate stricter. Return a model answer, cited extracts or an explanation of the gap.</p><p>No key is needed to read this page. It contacts no external services.</p></div><figure class="overview"><img src="web-pipeline.svg" alt="Source-to-answer architecture. A cache hit bypasses retrieval. The evidence gate and the optional second-opinion gate can lead to refusal. Evaluation is separate."></figure><p class="caption">Overview: solid arrows show the fresh-answer route; dashed arrows show bypass/alternative routes. On a phone, the full-width stage guide below carries every essential fact.</p><h2>Index on import</h2><div class="lanes"><details id="source"><summary><span class="num">01</span>Pin the source<small>Repository, file or issue URL</small></summary><div class="detail"><p>A repository root enumerates eligible files. A blob URL imports one file; an issue URL imports that issue. Source URI, path and revision make the evidence traceable. A successful import does not promise automatic refresh.</p><p class="check">Import one pinned README before widening to a whole repository.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/ingest.server.ts"><code>ingest.server.ts</code></a><a href="../../web/src/lib/rag/corpus.ts"><code>corpus.ts</code></a></div></div></details><details id="chunks"><summary><span class="num">02</span>Split into passages<small>Structure-aware text and code</small></summary><div class="detail"><p>Chunking preserves headings and code boundaries where possible. Each passage keeps its source identity. Approximate token counts guide packing; they are not provider billing tokens.</p><p class="check">Check that a condition and its exception survive the split.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/chunking.ts"><code>chunking.ts</code></a></div></div></details><details id="store"><summary><span class="num">03</span>Store text; optionally embed<small>Persistence is a configuration choice</small></summary><div class="detail"><p>Local development uses file-backed PGlite. DATABASE_URL selects Postgres for durable hosted storage. Vercel without Postgres uses process-local ephemeral data. Compatible embeddings are optional, not a prerequisite for keyword search.</p><p class="check">A cold start without durable storage can lose imported documents.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/store.server.ts"><code>store.server.ts</code></a><a href="../../web/src/lib/rag/memory.server.ts"><code>memory.server.ts</code></a></div></div></details></div><h2>Answer on request</h2><div class="lanes"><details id="cache"><summary><span class="num">04</span>Question + corpus + cache<small>A hit bypasses fresh retrieval</small></summary><div class="detail"><p>The selected corpus limits the search. Cache policy includes retrieval settings, model/runtime configuration and graph edits; source revisions are checked by the graph cache. A valid hit returns a stored answer with its citations and trace. Bypass cache when measuring retrieval quality.</p><p class="check">Corpus selection is not an authorization boundary.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/query.server.ts"><code>query.server.ts</code></a><a href="../../web/src/lib/rag/graphify/persist.server.ts"><code>graphify/persist.server.ts</code></a></div></div></details><details id="retrieve"><summary><span class="num">05</span>Retrieve, rank and pack<small>BM25; optional dense; bounded context</small></summary><div class="detail"><p>Keyword retrieval uses BM25. Dense retrieval requires compatible vectors. Hybrid fusion combines ranks with reciprocal rank fusion. The calibrated reranker is heuristic, not a trained cross-encoder. Context packing keeps at most three chunks within an approximate 1,400-token budget.</p><p class="check">Record evidence lost between candidate retrieval and final packing.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/retrieve-core.ts"><code>retrieve-core.ts</code></a><a href="../../web/src/lib/rag/ranking.ts"><code>ranking.ts</code></a><a href="../../web/src/lib/rag/bm25.ts"><code>bm25.ts</code></a></div></div></details><details id="gate"><summary><span class="num">06</span>Classify the evidence<small>Overlap is a signal, not proof</small></summary><div class="detail"><p>The lexical evidence gate checks whether the packed passages support the request. Insufficient evidence or no passages returns a deterministic refusal. Ambiguous evidence can still generate using an ambiguity-specific prompt, or return ordinary cited extracts when no generation provider is configured. A negative-not-found outcome has its own deterministic response path.</p><p class="check">Measure false refusals separately from unsupported answers.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/evidence.ts"><code>evidence.ts</code></a><a href="../../web/src/lib/rag/query.server.ts"><code>query.server.ts</code></a></div></div></details><details id="second-opinion"><summary><span class="num">07</span>Optional second-opinion gate<small>Only a positive gate is eligible</small></summary><div class="detail"><p>An optional server-side configuration enables the structured answer/refuse/clarify decision. A confident decision can change a positive gate to insufficient or ambiguous. Insufficient refuses; ambiguous still follows the alternate-prompt or cited-extracts path. The second-opinion gate never upgrades a refusal. Timeout, malformed output or low confidence leave the lexical result unchanged.</p><p class="check">Optional external decision call; off by default. Usage is not a dollar-cost estimate.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/query.server.ts"><code>query.server.ts</code></a></div></div></details><details id="answer"><summary><span class="num">08</span>Answer with source links<small>Configured model or cited extracts</small></summary><div class="detail"><p>With a generation provider, numbered passages guide a streamed answer. Without one, the app returns cited extracts. Citations map source numbers back to the selected chunks; a valid link does not prove that a passage supports a claim. Query traces keep the retrieval stages visible.</p><p class="check">Follow a citation and check the actual claim against its source.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/query.server.ts"><code>query.server.ts</code></a><a href="../../web/src/lib/rag/gemini.server.ts"><code>gemini.server.ts</code></a></div></div></details><details id="feedback"><summary><span class="num">09</span>Inspect and give feedback<small>Graph, trace and answer reuse</small></summary><div class="detail"><p>The interface exposes sources, retrieval traces and graph relationships. Feedback and graph preferences may affect later retrieval. Inferred relationships are not documentary facts. Stored answers can be reused through the revision/policy-aware cache.</p><p class="check">Keep user corrections separate from original source evidence.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/graphify/query.ts"><code>graphify/query.ts</code></a><a href="../../web/src/lib/rag/graphify/reflect.ts"><code>graphify/reflect.ts</code></a></div></div></details></div><h2>Evaluate separately</h2><div class="lanes"><details id="eval"><summary><span class="num">E</span>Evaluate on a separate path<small>Not an inline answer-approval step</small></summary><div class="detail"><p>The app evaluator calls the query pipeline and may use a configured model judge. Separately, the repo-support diagnostic calls retrieveFromRows directly against its frozen dataset. Both are separate from normal request handling. The committed p-queue diagnostic measured evidence retention without an LLM: 36.7% before, 70.0% after, versus 73.3% for plain BM25, on 15 answerable questions.</p><p class="check">These figures are not answer accuracy, production latency or proof of superiority.</p><div class="sources">Code entry points<a href="../../web/src/lib/rag/eval.server.ts"><code>eval.server.ts</code></a><a href="../../web/src/lib/rag/eval-data.ts"><code>eval-data.ts</code></a><a href="../../web/scripts/repo-support-eval.ts"><code>repo-support-eval.ts</code></a><a href="../../eval/repo-support/dataset.json"><code>dataset.json</code></a></div></div></details></div><h2>What this map does not claim</h2><div class="notice"><p>Dense retrieval and model generation depend on storage and provider setup. A citation is not proof of entailment. A graph edge is not proof of reasoning. The p-queue measurements are a narrow, first-party retrieval diagnostic, not generated-answer accuracy.</p><p><a href="web-rag-decisions.md">Design choices and tradeoffs</a> · <a href="../../eval/repo-support/README.md">Evaluation protocol and raw evidence</a> · <a href="../WEB.md">Deployment and acceptance runbook</a></p></div><footer>Documentation only. No trackers, external fonts, model calls or new dependencies. Expand each stage with a click, tap or Enter.</footer></main></body></html>