Polish RAGForge UI and fix evaluation matching

CHANGELOG.md

@@ -1,84 +1,59 @@
 # Changelog
 
-RAGForge used iterative numbered releases during development. v2.0.0 is the final planned portfolio release.
+## v2.0.1
 
-## v2.0.0 - Final
+- simplified the product UI and removed benchmark/grade marketing from the landing and evaluation screens
+- rewrote the README and evaluation notes around system behavior, methodology, and limitations
+- fixed numeric answer-key matching so labels such as `5 min` cannot match `15 minutes`
+- changed Quick evaluation so skipped scale/context checks are reported as not run rather than as release readiness
+- allowed semantic or hierarchical retrieval for the source-localization planner case, since both are valid strategies
+- renamed version-specific context-ablation labels to neutral experimental names
 
-- polished product UI and final README/docs hierarchy
-- aligned the multi-hop Hard Mode case with the recommended Auto + Balanced semantic route
-- added final release verification tooling and CI consistency checks
-- fixed duplicate runtime-header presentation and cleaned architecture documentation
-- preserved the v1.9 adaptive retrieval, context-budget, compression, scale-stress and release-readiness architecture
+## v2.0.0
 
-## v1.9 - Scale and release readiness
+- consolidated the UI, documentation, architecture diagram, and release tooling
+- aligned the multi-source Hard Mode comparison with the recommended Auto + Balanced path
+- added release consistency checks and CI verification
 
-- adaptive retrieval depth by corpus size
-- dynamic 2-5 chunk focused context budgets
-- focused sentence compression
-- 1x/5x/20x deterministic distractor-scale stress harness
-- prompt/context token economics
-- workspace diagnostics and release-readiness checklist
+## v1.9
 
-## v1.8 - Context budget optimization
+- added scale-aware retrieval depth and adaptive focused context budgets
+- added focused sentence selection and synthetic distractor scale stress
+- added prompt/context telemetry and workspace diagnostics
 
-- focused post-retrieval pruning
-- context/prompt telemetry
-- grounded-absence hardening
-- zero-Gemini context-budget ablation
+## v1.8
 
-## v1.7 - Evaluation correctness and adaptive efficiency
+- added focused context pruning and context-budget ablation
 
-- Markdown-safe source cards and graphical node latency waterfall
-- grounded absence and improved citation scoring/repair
-- evaluation run provenance
-- measured small-corpus reranker skip policy
+## v1.7
 
-## v1.6 - Hard Mode and analytical synthesis
+- improved evaluator correctness, citation handling, source rendering, and runtime provenance
+- adopted the measured small-corpus reranker skip policy
 
-- `insight_synthesis` / `analytical` path
-- `[T#]` table citations
-- harder robustness benchmark
-- chunk-level reranker labels
-- optional profile benchmark and node latency summaries
+## v1.6
 
-## v1.5 - Evaluation history and adaptive retrieval
+- added analytical corpus synthesis, structured table evidence, harder robustness cases, and chunk-level reranker evaluation
 
-- saved Quick/Standard/Deep reports
-- incremental Deep evaluation
-- typed Text2SQL scoring
-- zero-call citation repair
-- adaptive reranking
+## v1.5
 
-## v1.4 - Evaluation and API observability
+- added reusable Quick/Standard/Deep reports, incremental Deep evaluation, typed Text2SQL checks, and adaptive reranking
 
-- proper evaluation score cards and quality gates
-- fixed retrieval AP metrics
-- API/architecture runtime inspection
-- cache-bypassed evaluation timing
+## v1.4
 
-## v1.3 - Component evaluation
+- expanded evaluation metrics, cache-bypassed timing, Architecture/API inspection, and quota-aware evaluation
 
-- retrieval, citation, planner, SQL and latency metrics
-- reranker ablation
-- optional Deep judge
+## v1.3
 
-## v1.2 - UX/lifecycle hardening
+- introduced component-level evaluation and reranker ablation
 
-- browser session continuity
-- lazy demo recovery
-- explicit abstention and workspace preflight
-- indexing/query progress improvements
+## v1.2
 
-## v1.1 - Semantic routing redesign
+- hardened session lifecycle, lazy corpus recovery, progress UI, and explicit abstention
 
-- schema-constrained semantic query analysis
-- source-profile index
-- global/hierarchical retrieval
-- correction before conditional web fallback
+## v1.1
 
-## v1.0 - Initial production-style RAGForge
+- introduced semantic query planning, source profiles, global/hierarchical retrieval, and correction-before-web policy
 
-- FastAPI + Gradio + LangGraph
-- hybrid dense/BM25 retrieval
-- reranking, HyDE, multi-query, CRAG, Self-RAG
-- Text2SQL, Ask-the-Web, citations, guardrails and Docker/Hugging Face deployment
+## v1.0
+
+- initial FastAPI + Gradio + LangGraph application with hybrid retrieval, Text2SQL, web search, citations, and Docker deployment

README.md

@@ -10,178 +10,176 @@ pinned: false
 
 # RAGForge
 
-**RAGForge v2.0.0 - final portfolio release.**
+RAGForge is a retrieval application for asking questions across documents, structured tables, and web sources. It combines local hybrid search with query routing, read-only Text2SQL, optional web research, source-linked answers, and an evaluation suite that exposes how the system reached a result.
 
-RAGForge is an evidence-first RAG system for **documents, structured tables, and the web**. It combines hybrid retrieval, semantic query planning, source-balanced and hierarchical search, analytical synthesis, read-only Text2SQL, corrective retrieval, conditional web research, explicit citations, adaptive context budgeting, and a built-in evaluation harness in one Dockerized FastAPI + Gradio application.
+The project is designed to make RAG behavior inspectable. The UI shows the selected route, retrieved evidence, context-budget decisions, model calls, and per-node latency instead of presenting only a chat response.
 
-The project is designed as a production-style portfolio system rather than a claim of production SaaS readiness. It makes retrieval decisions, evidence quality, citation provenance, evaluation tradeoffs, and runtime limitations visible instead of hiding them behind a chat box.
+## What it does
 
-## Verified pre-final benchmark
+A question can be routed to one of several paths:
 
-The final release preserves the runtime architecture measured in the user-verified **v1.9 Standard** run. v2.0 changes benchmark alignment, UI, documentation, and release tooling; it does not claim a new provider-backed benchmark result before deployment.
+- **Documents** - dense + BM25 retrieval with reciprocal-rank fusion
+- **Data (SQL)** - read-only SQL over uploaded CSV/XLS/XLSX tables in DuckDB
+- **Web** - external search when the question genuinely requires current or external information
+- **Hybrid** - local evidence plus web evidence when both are needed
+- **Overview / analysis** - source-balanced retrieval for corpus summaries and analytical synthesis
 
-| Metric | Verified result |
-|---|---:|
-| Deterministic quality | **0.994 / Grade A** |
-| Answer accuracy | **100%** |
-| Source Recall@5 | **100%** |
-| Citation validity / coverage | **100% / 100%** |
-| Planner route / task / strategy | **100% / 100% / 100%** |
-| Text2SQL pass | **100%** |
-| Corpus overview pass | **100%** |
-| Adaptive context Recall@5 | **100%** |
-| Median adaptive context reduction | **41%** |
-| Evidence compression signal retention | **100%** |
-| Additional evidence-token reduction | **58%** |
-| Synthetic scale stress | **1,724 chunks / 24 sources** |
-| Scale-stress Recall@5 | **100%** |
-| Release readiness | **READY** |
-| Pipeline latency p50 / p95 | **1.79 s / 5.07 s** |
+The default `Auto` route uses a structured planner to decide the knowledge scope, task type, retrieval strategy, and whether web access is relevant.
 
-See [`docs/FINAL_RESULTS.md`](docs/FINAL_RESULTS.md) for the full measured baseline, methodology caveats, and optimization findings.
+## Retrieval and context handling
 
-## Why RAGForge
+The document path uses:
 
-Most RAG demos collapse several different questions into one similarity search. RAGForge separates them:
+- FastEmbed dense embeddings with embedded Qdrant
+- BM25 lexical retrieval
+- reciprocal-rank fusion
+- source-profile retrieval for source-first and corpus-wide queries
+- an adaptive cross-encoder policy rather than always paying reranking cost
+- retrieval depth that grows with corpus size
+- a focused context budget that retains more evidence when retrieval is ambiguous
+- local sentence selection for focused lookups before the evidence is sent to the generation model
 
-1. **What does the user mean?** A schema-constrained semantic planner identifies knowledge scope, task type, freshness, and retrieval strategy.
-2. **Where should the evidence come from?** Session-local documents, structured tables, the external web, or a mixed path.
-3. **How much evidence should reach generation?** Retrieval depth and generation context are adapted to corpus scale, retrieval confidence, source ambiguity, and task breadth.
-4. **Is the answer actually grounded?** Citations, evidence grading, grounded absence handling, optional Self-RAG verification, and transparent traces make the decision inspectable.
-5. **Did an optimization help?** The bundled benchmark separately measures retrieval, routing, SQL, citations, robustness, latency, context economics, and scale stress.
+Broad overview, comparison, and insight queries keep wider context. Focused lookups can use a smaller evidence set when the retrieval signal is clear.
 
-That distinction is why a query such as **“What is the current corpus about?”** stays local, while **“Compare our NIST document with the latest guidance online”** can legitimately become a hybrid document + web task.
+Source cards always keep the original retrieved text. Context compression only changes the copy passed to generation.
 
-## Core capabilities
+## Grounding and citations
 
-### Semantic planning and routing
+Generated answers refer back to the source cards returned with the response. Document, structured-table, and web evidence use separate source identifiers so the UI can distinguish where a claim came from.
 
-- `corpus`, `external`, `mixed`, and `structured_data` knowledge scopes
-- task types for fact lookup, overview, comparison, cross-document synthesis, aggregation, insight synthesis, and follow-up
-- retrieval strategies: `semantic`, `global`, `hierarchical`, `analytical`, `table`, and `none`
-- independent document and web queries
-- explicit `required | useful | irrelevant` web relevance
-- conversation-aware query rewriting
-- manual Auto / Documents / Web / Hybrid / Data(SQL) overrides
+The pipeline also includes:
 
-### Retrieval
+- citation normalization and conservative local repair
+- evidence sufficiency checks
+- calibrated handling of information that is absent from the corpus
+- optional corrective retrieval
+- optional bounded faithfulness revision
+- a full execution trace for each answer
 
-- local FastEmbed dense embeddings with embedded Qdrant
-- BM25 lexical retrieval
-- reciprocal-rank fusion
-- source-profile index for source-first hierarchical retrieval
-- source-balanced global retrieval for corpus overviews
-- analytical document + DuckDB table evidence
-- adaptive cross-encoder reranker policy
-- corpus-scale adaptive retrieval depth
-- dynamic 2-5 chunk focused context budgets
-- deterministic focused sentence compression after retrieval
+## Structured data
 
-### Grounded generation
+CSV, XLS, and XLSX files are indexed for retrieval and also loaded into an isolated in-memory DuckDB database.
 
-- document citations as `[D#]`
-- structured table citations as `[T#]`
-- web citations as `[W#]`
-- deterministic citation normalization and conservative repair
-- grounded-absence handling for genuinely missing information
-- optional CRAG correction loop
-- optional bounded Self-RAG-style verification and revision
-- confidence and complete pipeline trace
+The Text2SQL path:
 
-### Structured data
+1. generates a single query,
+2. validates that it is read-only,
+3. blocks mutation and administrative statements,
+4. applies row limits,
+5. executes the query in DuckDB, and
+6. returns the resulting scalar or table.
 
-CSV/XLS/XLSX content is both indexed as text and loaded into an isolated in-memory DuckDB database. The Text2SQL path:
+The benchmark evaluates the computed values directly instead of relying on how a table happens to be rendered as text.
 
-- generates a single read-only query
-- validates `SELECT` / CTE-only SQL
-- blocks mutation/admin statements
-- enforces row limits
-- returns typed scalar/table results
-- is independently evaluated against expected computed values
+## Web research
 
-### Ask-the-Web
+RAGForge can use DuckDuckGo, Tavily, or Gemini Search. Web search is planned separately from local retrieval, and allowing web fallback is not the same thing as deciding that the web is relevant.
 
-- DuckDuckGo keyless fallback
-- optional Tavily
-- optional Gemini Search grounding path
-- independently planned web queries
-- parallel fetch + main-text extraction
-- SSRF-oriented URL checks
-- local reranking and cited synthesis
-- web permission is separate from web relevance, so a weak local retrieval does not automatically leak a private corpus query to the internet
+This matters for private/local questions: weak document retrieval by itself does not cause the query to be sent to the internet.
 
-### File support
+## Supported files
 
-PDF, TXT, Markdown, DOCX, PPTX, CSV, XLS/XLSX, JSON, HTML, XML/YAML, code/text formats, common images, and ZIP archives.
+PDF, TXT, Markdown, DOCX, PPTX, CSV, XLS/XLSX, JSON, HTML, XML/YAML, common code/text formats, images, and ZIP archives are supported.
 
-ZIP ingestion includes path-traversal, file-count, size, and extension controls. Optional Gemini OCR can transcribe scanned PDFs/images.
+ZIP ingestion includes path-traversal, file-count, size, and extension checks. Optional Gemini OCR can be enabled for scanned PDFs and images.
 
 ## Architecture
 
 ```mermaid
 flowchart TD
-    U[User / API] --> G[Input and upload guardrails]
-    G --> P{Semantic QueryPlan}
-    P -->|structured| SQL[Read-only DuckDB Text2SQL]
-    P -->|external| W[Ask-the-Web]
-    P -->|corpus or mixed| R{Retrieval strategy}
+    U[User or API] --> G[Input and upload checks]
+    G --> P{Query planner}
 
-    R -->|semantic| C[Chunk index]
+    P -->|structured data| SQL[Read-only DuckDB Text2SQL]
+    P -->|external| W[Web search]
+    P -->|documents or mixed| R{Retrieval strategy}
+
+    R -->|semantic| C[Chunk retrieval]
     R -->|global| GB[Source-balanced retrieval]
-    R -->|hierarchical| SP[Source-profile index]
-    R -->|analytical| AN[Documents + deterministic table evidence]
+    R -->|hierarchical| SP[Source-profile retrieval]
+    R -->|analytical| AN[Documents + table evidence]
     SP --> C
 
-    C --> D[Dense FastEmbed / Qdrant]
+    C --> D[Dense search]
     C --> B[BM25]
     D --> F[RRF]
     B --> F
-    F --> RR{Adaptive reranker policy}
+    F --> RR[Adaptive reranker policy]
     RR --> RD[Scale-aware retrieval depth]
-    RD --> CB{Adaptive context budget}
-    CB --> EC[Focused evidence compression]
+    RD --> CB[Adaptive context budget]
+    CB --> EC[Focused sentence selection]
 
-    GB --> EG{Evidence grade}
+    GB --> EG{Evidence sufficient?}
     AN --> EG
     EC --> EG
-    EG -->|sufficient| A[Grounded Gemini generation]
-    EG -->|weak first attempt| CR[Correct retrieval]
+    EG -->|yes| A[Grounded generation]
+    EG -->|retry local| CR[Correct retrieval]
     CR --> R
-    EG -->|external relevant| W
-    EG -->|unsupported local| AB[Abstain]
+    EG -->|web relevant| W
+    EG -->|unsupported| AB[Abstain]
     W --> A
 
-    A --> V{Optional Self-RAG audit}
-    V -->|revise once| RV[Bounded revision]
-    RV --> V
-    V --> O[Cited answer + sources + trace]
+    A --> V[Optional faithfulness check]
+    V --> O[Answer + sources + trace]
     SQL --> O
     AB --> O
-
-    O -. cache-bypassed benchmark .-> EV[Evaluation harness]
-    EV --> Q[Quality + robustness]
-    EV --> EFF[Context / compression / latency]
-    EV --> ST[1x / 5x / 20x scale stress]
-    Q --> READY[Release readiness]
-    EFF --> READY
-    ST --> READY
 ```
 
-The detailed Mermaid source lives in [`docs/architecture.mmd`](docs/architecture.mmd).
+The full architecture diagram is in [`docs/architecture.mmd`](docs/architecture.mmd).
+
+## Evaluation
+
+The Evaluation tab runs a transparent benchmark stored in [`evals/demo_benchmark.json`](evals/demo_benchmark.json). The goal is to diagnose specific parts of the system rather than to claim a general RAG accuracy score.
+
+### Quick
+
+A small deployment smoke test covering a subset of QA, routing, overview, SQL, robustness, and abstention cases. It intentionally does **not** run the larger context, compression, or scale-stress ablations.
+
+### Standard
+
+Runs the full deterministic suite:
+
+- focused QA
+- route / task / retrieval-strategy planning
+- corpus overview
+- Text2SQL
+- abstention
+- robustness cases
+- retrieval and reranker ablation
+- context-budget comparison
+- sentence-compression comparison
+- node latency
+- synthetic distractor scale stress
+
+### Deep
+
+Reuses a compatible Standard result when possible and adds a small LLM-judge sample for answer faithfulness, relevance, completeness, and citation support.
+
+### Interpreting the benchmark
+
+The bundled benchmark is intentionally small: five source files, one structured table, and a 90-chunk base corpus. It is useful for regression testing and for comparing design choices, not for making claims about general enterprise performance.
+
+The scale-stress harness expands the retrieval index with deterministic distractor copies so retrieval behavior can be checked at a larger index size without spending additional model calls. That is still a synthetic stress test, not a substitute for a real large-corpus evaluation.
+
+During the final v2.0 acceptance run, the evaluation suite exposed a useful benchmark bug: one generated Sev-1 answer said `15 minutes` even though the source says `5 minutes`, and the old answer matcher incorrectly accepted it because `5 min` appeared inside `15 minutes`. v2.0.1 fixes answer matching at token/phrase boundaries and changes the benchmark version so older saved results are not silently reused.
 
-## Quick start
+Context-budget and compression tables should likewise be read as engineering comparisons: they show how much evidence reached generation and whether labeled answer evidence was retained on this benchmark. They are not general claims that a fixed percentage of tokens can always be removed safely.
+
+See [`docs/FINAL_RESULTS.md`](docs/FINAL_RESULTS.md) for the detailed validation notes and caveats.
+
+## Running the project
 
 ### Hugging Face Spaces
 
-1. Create a **Docker** Space.
-2. Copy this repository into the Space root.
-3. Add `GEMINI_API_KEY` in **Settings -> Secrets**.
+1. Create a Docker Space.
+2. Copy the repository into the Space root.
+3. Add `GEMINI_API_KEY` under **Settings -> Secrets**.
 4. Optionally add `TAVILY_API_KEY` and `APP_API_TOKEN`.
 5. Push the repository.
-6. Open the Space with **Use bundled demo files** enabled.
-7. Use the recommended **Auto + Balanced** profile.
+6. Open the Space and leave **Use bundled demo files** enabled for the demo corpus.
+7. Start with `Auto` + `Balanced`.
 
-The bundled demo corpus can be indexed explicitly or initialized lazily on the first non-Web question.
+The demo corpus can be indexed explicitly or initialized lazily on the first local question.
 
 ### Local Docker
 
@@ -195,7 +193,7 @@ docker run --rm -p 7860:7860 --env-file .env ragforge
 
 Open `http://localhost:7860`.
 
-### Python development
+### Development
 
 ```bash
 python -m pip install -r requirements-dev.txt
@@ -203,77 +201,45 @@ make verify
 make run
 ```
 
-`make verify` runs linting, tests, Python compilation, and the final release-consistency check.
+`make verify` runs linting, tests, Python compilation, and release-consistency checks.
 
-## Recommended demo flow
-
-Start with the bundled corpus and **Auto + Balanced**:
+## Suggested demo questions
 
 ```text
 What is the Sev-1 acknowledgement target?
 ```
 
-This demonstrates focused retrieval, adaptive context budgeting, sentence compression, a citation, and the latency waterfall.
+Focused document retrieval with a short cited answer.
 
 ```text
 What is the collection about?
 ```
 
-This demonstrates source-balanced global retrieval and document + table citations.
+Corpus-wide source-balanced retrieval, including the structured support table.
 
 ```text
 What exactly does this collection reveal? Identify important trends and caveats.
 ```
 
-This demonstrates `insight_synthesis -> analytical` retrieval with `[D#]` and `[T#]` evidence.
+Analytical synthesis across documents and structured data.
 
 ```text
 Which support tier has the shortest first-response SLA?
 ```
 
-This demonstrates semantic routing into read-only Text2SQL.
-
-A short portfolio/demo script is available in [`docs/PORTFOLIO_GUIDE.md`](docs/PORTFOLIO_GUIDE.md).
-
-## Evaluation
-
-RAGForge treats evaluation as part of the application rather than a notebook afterthought.
+Routes to the read-only Text2SQL path.
 
-### Quick
-
-Small smoke test for deployment sanity.
-
-### Standard
-
-Full deterministic suite covering:
-
-- focused QA
-- route/task/strategy planning
-- web-use precision and recall
-- corpus overview
-- typed Text2SQL
-- abstention
-- Hard Mode robustness
-- retrieval + reranker ablation
-- adaptive context-budget ablation
-- evidence-compression ablation
-- node latency
-- synthetic 1x / 5x / 20x scale stress
-- release-readiness checklist
-
-### Deep
-
-Reuses a compatible saved Standard baseline when possible and adds a small calibrated Gemini judge sample. This keeps free-tier request pressure bounded.
-
-Evaluation uses rolling request pacing and honors provider 429 retry guidance. Saved Quick/Standard/Deep runs can be compared without rerunning them.
+```text
+Compare our NIST document with the latest NIST AI risk guidance online.
+```
 
-See [`docs/EVALUATION.md`](docs/EVALUATION.md).
+Demonstrates the mixed local + web route.
 
 ## REST API
 
 FastAPI exposes Swagger at `/docs` and OpenAPI at `/openapi.json`.
 
-Key endpoints:
+Common endpoints:
 
 ```text
 GET   /api/health
@@ -290,7 +256,7 @@ GET   /api/v1/evaluation/history/{session_id}
 GET   /metrics
 ```
 
-Example:
+Example query:
 
 ```bash
 curl -X POST "$BASE_URL/api/v1/query" \
@@ -302,69 +268,56 @@ curl -X POST "$BASE_URL/api/v1/query" \
   }'
 ```
 
-See [`docs/ARCHITECTURE_API.md`](docs/ARCHITECTURE_API.md).
+See [`docs/ARCHITECTURE_API.md`](docs/ARCHITECTURE_API.md) for the complete API notes.
 
-## Security model and honest limitations
+## Security and limitations
 
-RAGForge demonstrates defense-in-depth controls for archive ingestion, retrieved prompt injection, SQL safety, SSRF-oriented web fetching, session isolation, secrets, and rate limiting. It is **not** a compliance-certified multi-tenant service.
+RAGForge includes controls for archive ingestion, retrieved prompt injection, SQL safety, session isolation, secrets, rate limiting, and web-fetch URL checks. It is not a compliance-certified multi-tenant service.
 
 Important limitations:
 
-- workspace/vector/SQL state is process-local and ephemeral on a standard Space
-- browser persistence stores only an opaque workspace ID and does not make server data durable
-- large production deployments need durable tenant state, storage-level tenant filters, worker isolation, external vector/database infrastructure, and stronger egress controls
-- prompt-injection detection remains heuristic
-- token counts in traces are estimates for engineering comparison, not provider billing records
-- the 1,724-chunk scale result is a deterministic synthetic distractor stress test, not a substitute for a real enterprise corpus benchmark
-- free-tier Gemini quotas and data-use terms depend on the active provider project/tier
+- workspace, vector, and SQL state are process-local and ephemeral on a standard Hugging Face Space
+- browser persistence stores an opaque workspace ID, not durable server state
+- prompt-injection detection is heuristic
+- trace token counts are engineering estimates, not provider billing records
+- the bundled benchmark is a regression suite over a small demo corpus
+- the larger scale result uses synthetic distractors rather than a real enterprise dataset
+- production multi-tenant deployment would require durable storage, stronger tenant isolation, external database/vector infrastructure, and stricter network controls
 
 See [`SECURITY.md`](SECURITY.md).
 
-## Repository map
+## Repository layout
 
 ```text
 src/ragforge/
-  pipeline.py              LangGraph RAG orchestration
-  llm.py                   Gemini planning/generation/judging
+  pipeline.py              pipeline orchestration
+  llm.py                   Gemini planning and generation
   retrieval.py             dense + BM25 + RRF + reranking
   context_budget.py        adaptive retrieval/context policy
-  evidence_compression.py  focused local sentence compression
-  workspace.py             session corpus, indexes, SQL, eval history
-  evaluation.py            benchmark + diagnostics + readiness
-  stress_eval.py           zero-Gemini scale-stress harness
+  evidence_compression.py  focused sentence selection
+  workspace.py             sessions, indexes, SQL, evaluation history
+  evaluation.py            benchmark and diagnostics
+  stress_eval.py           local synthetic scale-stress harness
   sql_agent.py             read-only Text2SQL
-  web_search.py            external research path
-  security.py              ingestion/query/web guardrails
+  web_search.py            external search path
+  security.py              ingestion/query/web checks
   ui.py                    Gradio application
-  api.py                   FastAPI surface
+  api.py                   FastAPI API
 
 evals/
-  demo_benchmark.json      transparent benchmark labels
+  demo_benchmark.json
 
 docs/
-  FINAL_RESULTS.md         verified pre-final benchmark
-  PORTFOLIO_GUIDE.md       demo and interview walkthrough
-  EVALUATION.md            evaluation methodology
-  ARCHITECTURE_API.md      architecture/API reference
-  FEATURE_MATRIX.md        feature inventory
-  QUERY_PLANNING.md        planner semantics
-  UX_LIFECYCLE.md          session/UI lifecycle
-  RESUME_BULLETS.md        concise project bullets
+  FINAL_RESULTS.md
+  PORTFOLIO_GUIDE.md
+  EVALUATION.md
+  ARCHITECTURE_API.md
+  FEATURE_MATRIX.md
+  QUERY_PLANNING.md
+  UX_LIFECYCLE.md
 ```
 
-## Final project status
-
-**v2.0.0 is the final planned feature release.** Future work should be driven by a genuinely larger real-world corpus or deployment requirement, not by adding more RAG acronyms.
-
-The measured engineering conclusions are already useful:
-
-- source recall is saturated on the demo benchmark, so context economics mattered more than another retriever
-- the cross-encoder reranker was hundreds of times slower on the small demo with no measured source/chunk ranking gain, so runtime policy skips it there
-- adaptive context budgeting and sentence compression reduced generation input while preserving benchmark recall/signals
-- generation dominates latency, making prompt/context reduction more valuable than micro-optimizing millisecond retrieval
-- evaluation exposed multiple evaluator/UI bugs during development, demonstrating why the benchmark itself needed to be audited as carefully as the RAG pipeline
-
-For project history, see [`CHANGELOG.md`](CHANGELOG.md).
+Development history is kept in [`CHANGELOG.md`](CHANGELOG.md); it is intentionally separate from the main product documentation.
 
 ## License
 

docs/EVALUATION.md

@@ -1,363 +1,108 @@
-# RAGForge evaluation - v2.0 final
+# Evaluation
 
-## Final benchmark alignment
-
-v2.0 preserves the v1.9 deterministic evaluation architecture and bumps the benchmark to `2.0` because the multi-hop comparison Hard Mode case is now executed through the recommended `Auto + Balanced` semantic route. The case must resolve to `documents -> comparison -> hierarchical` and still satisfy the answer/retrieval labels. This prevents Fast mode's intentionally cheap fallback from being treated as the reference behavior for a multi-source reasoning test.
-
-The last provider-backed user-verified Standard baseline is documented in [`FINAL_RESULTS.md`](FINAL_RESULTS.md).
-
-## v1.9 scale, compression and readiness evaluation
-
-v1.9 keeps the normal Standard Gemini request count unchanged while adding local ablations around the expensive generation context. The context-budget table now compares **Full top-k**, **v1.8 fixed top-3**, and **v1.9 adaptive budget**. Adaptive selection uses corpus scale, retrieval confidence, score separation and source ambiguity, with focused budgets between two and five chunks.
-
-The **Evidence compression** table compares adaptive context with and without query-focused sentence compression. It reports additional token reduction and a deterministic answer-signal-retention rate; source records themselves are never rewritten.
-
-The **Scale stress** table expands the demo corpus with deterministic long-document distractor clones at roughly 1x, 5x and 20x scale, reuses the already-computed embedding vectors, and runs the real Qdrant/BM25/RRF path. It measures source ranking, adaptive-pruned recall, retrieval latency, budget size and index-build time without model or embedding API calls. A stress-harness failure is isolated from the primary benchmark and marks release readiness incomplete rather than crashing Standard.
-
-The **Release readiness** table is a transparent checklist, not a replacement metric. Standard/Deep require configured thresholds for answer/source quality, citations, planning/web policy, Text2SQL, Hard Mode, overview behavior, adaptive-budget recall, compression retention and largest-scale stress recall. Quick intentionally omits local ablation/stress gates instead of treating skipped work as a pass.
-
-Node-latency summaries are now pacing-corrected: deliberate evaluation sleep is subtracted proportionally from nodes that issued Gemini calls. Raw traces retain wall time, and evaluation continues to report wall latency and pacing wait separately.
-
-
-## v1.8 context-budget evaluation
-
-v1.8 adds a zero-Gemini **Context budget** ablation because the v1.7 Standard run showed 100% source Recall@5/Hit@1/MRR but only about 47% source Precision@5 on focused QA. That pattern means retrieval was finding the right source reliably while still sending avoidable distractors into generation.
-
-The ablation compares:
-
-- **Full top-k** - the original six-chunk focused retrieval context.
-- **Focused pruning** - the same ranking with a three-chunk safety floor, enabled only for local `fact_lookup`/`followup` work using semantic or hierarchical retrieval.
-
-It reports source Precision@5, Recall@5, Hit@1, MRR, median context chunks, distinct sources, characters, estimated tokens and reduction percentage. A diagnostic only endorses the pruning policy when recall is preserved while precision improves. Broad overview, insight, comparison and cross-document tasks are excluded from runtime pruning and keep their breadth.
-
-Focused benchmark rows also expose whether pruning actually ran, the pre/post context token estimate, whether the corpus manifest was included and the estimated generation-prompt tokens. This lets latency changes be interpreted alongside model-input changes instead of provider noise alone.
-
-### Grounded absence robustness
-
-The missing-answer Hard Mode case now accepts either a successful natural-language absence match or an explicit pipeline `grounded_absence=true` trace signal. This makes evaluator correctness independent of one exact surface form and allows the Hard Mode table to show both mechanisms.
-
-
-
-## v1.7 evaluator correctness and provenance
-
-v1.7 changes benchmark semantics where the v1.6 report exposed evaluator artifacts rather than RAG failures. Citation coverage is Markdown-aware: short numbered/bulleted factual items count, headings and generic list introductions do not. Missing-answer cases use a grounded-absence matcher that accepts natural uncertainty language instead of a single canned phrase. Global overviews include table evidence so `[T#]` citations are part of the actual returned source set.
-
-Saved reports now carry a `run_id` and `server_boot_id`. A fresh run is reported as fresh, while loading/reusing a saved run explicitly reports zero new Gemini requests. Programmatic updates to the saved-run selector no longer trigger a second UI callback that can overwrite fresh-run status.
-
-Profile benchmarking also emits `profile_summary` rows (accuracy, citation quality, median latency, LLM-call count and reranker rate) plus an evidence-scoped profile recommendation. Evaluation diagnostics additionally surface context-efficiency when recall is high but source precision is low, and identify the dominant node-latency bottleneck.
-
-## v1.6 hard-mode and analytical evaluation
-
-The original demo benchmark reached near-saturation on the bundled corpus. v1.6 therefore makes the benchmark harder instead of treating a 0.99 score as proof of general RAG quality. Standard/Deep now add a **Hard Mode** suite covering:
-
-- paraphrases that change surface wording without changing the answer;
-- distractor mentions of a second source;
-- missing-answer questions where the system should state that the corpus does not specify a value;
-- multi-hop comparisons requiring two sources;
-- `insight_synthesis` questions that require broad source coverage plus `[T#]` table evidence;
-- a filtered/min structured-data case;
-- local “current” wording that must not trigger the web;
-- prompt-injection detection.
-
-The deterministic score now assigns 5% weight to hard-mode pass rate. A pass rate below 75% caps the grade at B, and below 50% caps it at C.
-
-### Chunk-level reranker metrics
-
-The RRF vs cross-encoder ablation still reports source-level metrics, but selected QA cases now carry auditable `chunk_must_contain` labels. Only those labeled cases contribute to `chunk_hit@1` and `chunk_mrr`, avoiding artificial inflation from unlabeled cases. This directly tests whether reranking improves the evidence chunk *within* the right file.
-
-### Optional profile benchmark
-
-A separate opt-in evaluation compares Fast, Balanced and Agentic on a focused case plus a multi-source case. It reports answer-key accuracy, citation validity/coverage, service latency, estimated graph LLM calls, reranker use and corrective-retrieval use. The switch is off by default because profile benchmarking intentionally spends extra Gemini calls.
-
-### Node latency summary
-
-Evaluation aggregates per-node timings from QA, overview and hard-mode graph traces into mean/p50/p95 rows. This complements the per-query inspector waterfall and helps identify whether latency is dominated by planning, retrieval, generation, grading or verification.
-
-### Evaluation history
-
-The latest Quick/Standard/Deep result remains directly reusable. v1.6 also archives timestamped reports inside the ephemeral workspace and exposes history rows with grade, deterministic score, citation coverage, hard-mode pass rate, p50 latency, Gemini requests and deltas versus the previous run at the same depth.
-
-# Evaluation architecture - retained v1.5 foundations
-
-RAGForge evaluates retrieval, orchestration, generation, structured-data behavior and runtime efficiency separately. The benchmark is intentionally small and transparent; it is a regression suite for the bundled demo corpus, not a claim about general RAG performance.
-
-## Why v1.5 changed the evaluator
-
-The v1.3 benchmark surfaced four evaluator/system issues during real Hugging Face runs:
-
-1. source AP@5 could exceed 1.0 because repeated chunks from the same relevant PDF were counted as separate relevant sources;
-2. running Standard followed by Deep could report near-zero pipeline latency because the response cache returned benchmark answers immediately;
-3. a high weighted score could still show grade A while Text2SQL passed only half of its cases;
-4. the auxiliary LLM judge could award perfect citation-support scores to answers with weak or missing citations.
-
-v1.4 fixed those issues, and v1.4.1 hardened the benchmark for free-tier API quotas with rolling RPM pacing, provider-aware 429 backoff, request telemetry, lower-call Text2SQL evaluation and sampled Deep judging.
-
-v1.5 uses the next deployed benchmark run to tighten three remaining areas:
-
-1. **evaluation reuse** - Quick/Standard/Deep reports are cached per workspace and can be switched/compared without rerunning the benchmark;
-2. **incremental Deep** - a compatible saved Standard report becomes the deterministic Deep baseline, so Deep normally adds only the representative judge calls instead of repeating the whole Standard suite;
-3. **typed Text2SQL checks** - scalar DuckDB outputs are compared as booleans/numerics/text rather than through Markdown rendering, preventing correct SQL from failing a fragile string matcher.
-
-The same run also showed a repeatable reranker tradeoff: identical source-level metrics with multi-second reranker latency on the tiny demo corpus. v1.5 therefore keeps the explicit ablation while the runtime adopts an adaptive reranking policy.
-
-## Benchmark data
-
-The labels live in `evals/demo_benchmark.json` and include:
-
-- focused QA with expected answer terms and relevant source files,
-- one multi-source retrieval case,
-- corpus-overview cases with route/task/strategy and minimum source coverage,
-- semantic-planner cases with expected route, task, strategy and web policy,
-- Text2SQL lookup/aggregation cases,
-- empty-workspace abstention checks.
+RAGForge includes a small, transparent regression suite in `evals/demo_benchmark.json`. It is designed to diagnose parts of the system separately rather than reduce everything to one headline score.
 
 ## Evaluation levels
 
 ### Quick
 
-A deployment smoke test. It runs a small subset of focused QA, planner, overview and SQL cases plus lifecycle abstention. Quick intentionally skips the reranker ablation and Deep judge.
+Quick is a deployment smoke test. It runs a subset of:
 
-### Standard
+- focused QA,
+- query planning,
+- corpus overview,
+- Text2SQL,
+- robustness cases, and
+- empty-workspace abstention.
 
-Runs the full deterministic benchmark and a retrieval ablation comparing:
+Quick intentionally skips the larger context-budget, sentence-compression, reranker, and scale-stress ablations. The UI reports those sections as **not run** rather than turning skipped work into a readiness result.
 
-- Hybrid RRF
-- Hybrid RRF + local cross-encoder reranker
+### Standard
 
-This is the recommended default for portfolio demonstrations because the core metrics are deterministic and auditable.
+Standard runs the full deterministic suite:
+
+- focused QA answer checks,
+- source-level retrieval metrics,
+- planner route / task / strategy labels,
+- corpus overview behavior,
+- Text2SQL computed-value checks,
+- abstention,
+- hard-mode robustness,
+- RRF vs reranker ablation,
+- full vs fixed vs adaptive context budgets,
+- focused sentence-compression checks,
+- node latency, and
+- synthetic distractor scale stress.
 
 ### Deep
 
-Adds Gemini evaluation of a representative labeled subset of generated answers for:
-
-- faithfulness,
-- answer relevance,
-- completeness,
-- citation support,
-- overall quality and pass/fail.
-
-If a compatible Standard report is already saved for the same workspace corpus, benchmark version and model, RAGForge reuses that deterministic baseline and issues only the sampled judge calls. From scratch Deep can still run the full benchmark. The judge remains auxiliary: its citation score is conservatively bounded by deterministic citation validity and coverage, so an answer with no citations cannot receive perfect citation-support credit.
-
-## Saved evaluation history
-
-Each workspace stores the latest Quick, Standard and Deep report with:
-
-- evaluation depth,
-- model,
-- benchmark version,
-- workspace/corpus version,
-- UTC save time.
-
-The Evaluation tab can switch among saved runs and renders a side-by-side comparison table. Saved reports are separate from the RAG response cache. They remain available across a normal browser refresh while the current Space container/workspace lives. If the corpus changes, older reports remain viewable but are marked stale and are not reused for a fresh run.
-
-`Reuse saved evaluation` is enabled by default. Running an already-compatible depth can therefore consume zero Gemini requests. When Deep has no saved Deep result but does have a compatible Standard result, it performs an incremental judge-only upgrade.
-
-## Cache and history policy
-
-Benchmark queries call the pipeline with:
-
-```python
-use_cache=False
-record_history=False
-```
-
-This has two effects:
-
-1. reported pipeline latency reflects actual execution rather than a prior cached answer;
-2. benchmark questions do not alter the session's conversational history and therefore do not change later planner behavior.
-
-The report exposes `cache_bypassed: true` to make this methodology explicit.
-
-## Source-level retrieval metrics
-
-RAG retrieval can return many chunks from one file. v1.4 deduplicates source names before source-level ranking metrics are computed.
-
-### Source Hit@1
-
-Whether the first distinct returned source is relevant.
-
-### Source Precision@5
-
-Among the distinct sources represented in the top-five chunk window, what fraction are relevant?
-
-### Source Recall@5
-
-What fraction of labeled relevant files appear among those sources?
-
-### Source MRR
-
-Reciprocal rank of the first relevant distinct source.
-
-### Source AP@5
-
-Average precision over distinct relevant files within the top-five window. Each relevant file can contribute at most once, so AP is mathematically bounded to `[0, 1]`.
-
-### Source nDCG@5
-
-Binary source relevance with logarithmic rank discounting, normalized against the ideal source ordering.
-
-### Duplicate-source rate@5
-
-The fraction of top-five retrieved chunks that repeat a source already present in that window. This is not inherently bad for focused questions, but it makes long-document domination visible.
-
-## Retrieval ablation
-
-Standard and Deep retrieve the same QA set twice:
-
-1. Hybrid RRF without the cross-encoder;
-2. Hybrid RRF with the cross-encoder.
-
-The table compares source Recall@5, Hit@1, MRR, AP@5, nDCG@5, duplicate-source rate and median retrieval latency.
-
-The diagnostics layer flags a reranker when it adds a large latency multiplier without improving source MRR. That is a benchmark-specific recommendation, not a universal claim that reranking is unnecessary.
-
-## Generation and citation metrics
-
-### Answer-key accuracy
-
-Transparent expected-term checks for focused demo questions.
-
-### Citation validity
-
-Fraction of citation labels such as `[D2]` or `[W3]` that correspond to sources actually returned by the pipeline.
-
-### Citation coverage
-
-Sentence-level proxy for how many substantive factual statements include at least one citation.
-
-The generation prompt also requires every substantive factual paragraph or list item to include a valid citation when evidence is present. v1.5 adds a conservative deterministic repair pass: uncited substantive units receive a citation only when one returned evidence item has clear lexical support. Ambiguous units are left unchanged. This improves citation completeness without adding another model request.
-
-## Planner and web-policy metrics
-
-The planner is measured independently on:
-
-- route accuracy,
-- task-type accuracy,
-- retrieval-strategy accuracy,
-- web-use precision,
-- web-use recall,
-- unnecessary-web rate.
-
-Task labels are intentionally separate from route. For example, a direct value lookup from a CSV can be `task_type=fact_lookup` while still using `route=sql` and `retrieval_strategy=table`. A min/max computation across rows is `aggregation`.
-
-## Text2SQL evaluation
-
-The planner suite already evaluates whether Auto mode chooses `route=sql` and `retrieval_strategy=table`. The Text2SQL component suite therefore avoids duplicating that model call. For each SQL benchmark case it:
-
-1. gives the DuckDB table schema and user question to Gemini;
-2. validates the generated statement as a single read-only `SELECT`/CTE;
-3. executes it in DuckDB;
-4. checks the computed result against a transparent typed scalar when one is labeled, otherwise falls back to answer-key terms.
-
-For example, `weekend_support` is evaluated as the boolean `true`, not by searching a rendered Markdown table for a particular spelling. This keeps SQL-generation correctness separate from formatting quirks. The component test still uses one model call per case while routing is measured independently in the planner suite.
-
-## Lifecycle abstention
-
-Explicit empty `Documents` and `Data (SQL)` requests must terminate through the `abstain` node with zero estimated LLM calls. Lifecycle failures are not treated as weak retrieval.
-
-## Latency and efficiency
-
-The report includes:
-
-- pipeline service latency p50/p95,
-- planner service latency p50/p95,
-- per-case wall latency and deliberate pacing wait,
-- total evaluation wall time,
-- actual Gemini requests issued through RAGForge's gateway,
-- configured evaluation RPM target,
-- surfaced 429 retry count and provider-directed retry wait,
-- mean estimated pipeline LLM calls,
-- correction rate and runtime web-use rate,
-- Deep judge latency when applicable.
-
-Service latency subtracts deliberate quota-pacing sleep so the benchmark does not make the normal interactive pipeline look slower merely because the evaluation is being rate-limited. `llm_calls_estimate` remains graph-derived and is useful for pipeline comparisons; `gemini_requests` is the gateway-level count for the evaluation run and can be higher when a provider retry occurs.
+Deep reuses a compatible Standard result when possible and adds a small LLM-judge sample. The judge covers faithfulness, relevance, completeness, and citation support, but deterministic citation failures cannot be overridden by the judge.
 
-## Quota-safe evaluation
+## Answer matching
 
-Standard and Deep default to a conservative target of **12 Gemini requests per minute**. The UI exposes this target because active rate limits vary by project/model. The process-local ledger also records recent interactive requests, so starting an evaluation immediately after manual testing does not pretend the previous minute was empty.
+Focused QA uses labeled answer phrases from the benchmark file. Matching is boundary-aware: numeric or alphanumeric labels cannot pass by appearing inside a different token. For example, a `5 min` answer key does not match `15 minutes`.
 
-When quota-safe pacing is enabled, requests are smoothed across the minute rather than sent in a burst. If Gemini still surfaces a 429, RAGForge parses provider retry guidance when available, waits for that interval (plus small jitter) and performs only bounded retries. Structured-output code does not immediately fall back to a second plain-JSON request on transient 429/5xx errors.
+This rule was added after a real v2.0 evaluation exposed exactly that false positive.
 
-Set the API/GUI target below the active RPM shown for your project. `target_rpm=0` disables deliberate pacing, but bounded provider-aware retries remain.
+## Retrieval metrics
 
-## Quality-gated grade
+Source-level retrieval deduplicates repeated chunks from the same file before computing:
 
-The deterministic weighted score is still shown for orientation, but the letter grade is additionally subject to subsystem gates.
+- Precision@5,
+- Recall@5,
+- Hit@1,
+- MRR,
+- AP@5, and
+- nDCG@5.
 
-Examples:
+Selected cases also include chunk-content labels for chunk Hit@1 and chunk MRR in the reranker ablation.
 
-- route/web-policy accuracy below 90% caps the grade at C;
-- Text2SQL below 75% caps the grade at B;
-- citation validity below 90% caps the grade at B;
-- citation coverage below 80% caps the grade at B;
-- planner task accuracy below 75% caps the grade at B.
+A source-localization question may legitimately use either direct semantic retrieval or source-first hierarchical retrieval; benchmark cases can declare more than one accepted strategy when both are valid.
 
-This prevents a strong retrieval score from hiding a serious production weakness elsewhere.
+## Citation checks
 
-## Diagnostic findings
+Citation validity asks whether cited source IDs were actually returned with the answer. Citation coverage checks whether substantive factual units have citations. The parser is Markdown-aware so headings and list introductions are not counted as unsupported factual claims, while factual list items are.
 
-Each Standard/Deep report contains structured diagnostics. Current checks can highlight:
+Structured table evidence and web evidence are validated against their returned source records in the same way as document evidence.
 
-- incomplete citation coverage,
-- task-taxonomy misses,
-- failed Text2SQL cases,
-- reranker latency with no measurable source-ranking gain.
+## Text2SQL
 
-The UI renders these findings directly above the detailed tables, while the raw JSON keeps them machine-readable for CI/API use.
+SQL generation is evaluated independently from natural-language answer generation. The benchmark:
 
-## API
+1. generates validated read-only SQL,
+2. executes it in DuckDB, and
+3. compares the computed scalar result using typed boolean, numeric, or text matching.
 
-The benchmark can be run programmatically:
+## Context-budget ablation
 
-```text
-POST /api/v1/evaluate/demo
-```
+Standard compares:
 
-The request body accepts `target_rpm` (default `12`; use `0` to disable deliberate pacing) and `reuse_saved` (default `true`).
+- **Full top-k** - all retrieved candidates used as generation context;
+- **Fixed 3-chunk budget** - a deliberately tight focused baseline; and
+- **Adaptive budget** - a 2-5 chunk focused budget chosen from retrieval confidence, score separation, source ambiguity, and corpus scale.
 
-Benchmark metadata is available without running the benchmark:
+The purpose is to check whether model input can be reduced without losing the labeled source.
 
-```text
-GET /api/v1/evaluation/benchmark
-```
+## Sentence-compression ablation
 
-Saved run inventory and reports are available through:
+Focused evidence can be reduced to query-relevant sentences after context budgeting. The ablation checks whether labeled answer evidence remains present and records the resulting context-size change. Original source cards are never rewritten.
 
-```text
-GET /api/v1/evaluation/saved/{session_id}
-GET /api/v1/evaluation/saved/{session_id}/{level}
-```
+## Synthetic scale stress
 
-The API rejects the demo benchmark when the required bundled demo sources are not present in the workspace.
+The stress harness clones long-document distractor chunks and reuses their existing vectors to exercise the real Qdrant + BM25 + RRF path at larger index sizes without extra Gemini or embedding calls.
 
-## Extending evaluation
+It is a retrieval regression test, not a replacement for evaluation on a real large corpus.
 
-Useful next steps for a larger corpus include:
+## Latency and request pacing
 
-- chunk-level relevance labels,
-- frozen web snapshots for reproducible hybrid evaluation,
-- contradiction and multi-hop cases,
-- unanswerable questions with semantic sufficiency labels,
-- adversarial retrieved prompt-injection documents,
-- repeated judge runs with variance/confidence intervals,
-- Fast vs Balanced vs Agentic profile comparison,
-- latency/cost budgets as explicit pass/fail constraints.
+Evaluation bypasses the response cache. Service latency excludes deliberate quota-pacing sleep, while wall time and pacing wait are reported separately.
 
+All Gemini calls in a run can share a rolling request pacer. Saved Quick, Standard, and Deep reports can be reopened without spending new requests, and Deep can reuse Standard as its deterministic baseline.
 
-## v1.5.1 saved-report and export behavior
+## Acceptance checks
 
-Evaluation reports are normalized to plain JSON at the workspace boundary. This prevents
-Pydantic/Gradio root wrappers from leaking into the UI or saved-report API when a user switches
-between Quick, Standard and Deep. The Raw evaluation report is rendered as formatted JSON in a
-copy-ready code view.
+Standard and Deep include a threshold checklist for the major benchmark subsystems. It is an engineering convenience, not a product-quality certification and not a substitute for the underlying tables.
 
-Every evaluation table can be prepared as CSV, TSV or Markdown from the currently selected saved
-run. The export panel supports Focused QA, Semantic planner, Corpus overview, Text2SQL, Retrieval
-ablation, Abstention and Compare saved runs. Export files live under the ephemeral workspace
-evaluation directory and disappear with the Hugging Face Space runtime.
+## Benchmark scope
 
-Citation evaluation accepts both one-ID-per-bracket syntax such as `[D1] [D2]` and grouped model
-syntax such as `[D1, D2]`. Runtime answer rendering normalizes grouped citations and removes
-duplicate trailing citation sets. The deterministic zero-call citation repair skips list-introduction
-or preamble lines ending in `:` so it does not attach a source merely because a broad introductory
-sentence overlaps many evidence snippets.
+The bundled corpus is deliberately small. High percentages on this suite mean the current implementation passes these labeled regression cases. They should not be read as general accuracy estimates for arbitrary documents, industries, or enterprise-scale deployments.

docs/FEATURE_MATRIX.md

@@ -46,7 +46,7 @@ The table below describes the final planned portfolio release. Future changes sh
 | Focused evidence compression | deterministic query-relevant sentence selection for generator context only | reduces prompt load without mutating source cards or spending another LLM call |
 | Scale stress | 1x/5x/20x long-document distractor cloning with precomputed vector reuse | tests retrieval/budget robustness around ~1000 chunks without Gemini or re-embedding cost |
 | Workspace diagnostics | corpus scale/capacity, index readiness, TTL/idle, estimated vector memory | makes demo operational limits explicit before they become silent failures |
-| Release readiness | transparent threshold checklist over quality, safety, efficiency and scale robustness | summarizes ship/no-ship evidence without hiding component metrics |
+| Acceptance checks | transparent threshold checklist over quality, safety, efficiency and scale robustness | summarizes ship/no-ship evidence without hiding component metrics |
 | Evaluation | transparent v1.9 benchmark + Markdown-aware citation claims + grounded-absence robustness + source/chunk ranking metrics + hard-mode + adaptive-context/compression/scale ablations + planner/web policy + typed Text2SQL + pacing-corrected node latency + calibrated Deep judge | separates retrieval, orchestration, context economics, scale robustness, analysis and generation failures |
 | Saved evaluation history | latest Quick/Standard/Deep cache plus timestamped archived runs and deltas | allows instant run switching and lightweight within-workspace regression tracking without consuming Gemini quota again |
 | Evaluation report serialization | JSON-safe normalization at save/load/UI/API boundaries + formatted raw JSON view | prevents `root={...}` wrapper leakage and keeps fresh/restored reports identical |

docs/FINAL_RESULTS.md

@@ -1,88 +1,63 @@
-# Final measured results
-
-This page records the **user-verified v1.9 Standard benchmark** immediately before the v2.0 final productization release. v2.0 preserves the measured runtime architecture but changes benchmark alignment for one multi-hop Hard Mode case, plus UI/docs/release tooling. Therefore these numbers are presented as the verified pre-final baseline rather than silently relabeled as a v2.0 provider-backed run.
-
-## Quality
-
-| Metric | Result |
-|---|---:|
-| Deterministic quality | 0.994 (Grade A) |
-| Answer accuracy | 100% |
-| Source Precision@5 | 48% |
-| Source Recall@5 | 100% |
-| Hit@1 | 100% |
-| MRR | 1.000 |
-| AP@5 | 1.000 |
-| nDCG@5 | 1.000 |
-| Citation validity | 100% |
-| Citation coverage | 100% |
-| Corpus overview pass | 100% |
-| Text2SQL pass | 100% |
-| Planner route/task/strategy | 100% / 100% / 100% |
-| Web precision/recall | 100% / 100% |
-| Hard Mode | 88% |
-| Release readiness | READY (100% critical gates) |
-
-The single v1.9 Hard Mode miss was the multi-hop Acme-vs-OrbitPay timing comparison. That case was being executed through Fast mode's cheap fallback even though the application recommendation is Auto + Balanced for semantic multi-source reasoning. v2.0 aligns that case with the recommended route and explicitly requires `comparison -> hierarchical` planning.
-
-## Context economics
-
-| Configuration | Precision@5 | Recall@5 | Median chunks | Median context tokens | Reduction |
-|---|---:|---:|---:|---:|---:|
-| Full top-k | 47.2% | 100% | 6 | 2,101 | 0% |
-| v1.8 fixed top-3 | 50.0% | 100% | 3 | 977 | 54.9% |
-| v1.9 adaptive budget | 48.1% | 100% | 4 | 1,099 | 41.0% |
+# Benchmark notes
+
+This document records the main observations from the bundled RAGForge regression suite. The suite uses a five-source demo corpus with one structured table and a 90-chunk base index. It is intended for regression testing and design comparisons, not as a claim about general RAG accuracy.
+
+## Final acceptance note
+
+The v2.0 deployment run exposed a bug in the benchmark itself. A focused QA generation answered the Sev-1 acknowledgement question with `15 minutes`, while the source states `5 minutes`. The old matcher accepted that answer because one accepted phrase was `5 min`, which appeared as a substring of `15 minutes`.
+
+v2.0.1 changes answer matching to respect token/phrase boundaries and bumps the benchmark version. Saved v2.0 results should therefore be treated as historical rather than authoritative v2.0.1 results.
+
+The same run confirmed that the multi-source Acme-vs-OrbitPay timing comparison now follows the intended `Auto + Balanced` comparison path and returns both required time windows correctly.
 
-The final runtime keeps adaptive budgeting rather than the globally tighter fixed top-3 policy because it retains extra safety margin for ambiguous and larger-corpus cases.
+## Retrieval and context observations
 
-## Evidence compression
+The last full Standard run before the matcher fix showed strong source recall on the demo cases, but lower source precision. That pattern motivated context selection rather than another retrieval layer: retrieve enough evidence to keep the relevant source, then reduce what reaches generation.
 
-| Configuration | Answer-signal retention | Median evidence tokens | Additional reduction |
+The context ablation compared three policies:
+
+| Policy | Median chunks sent to generation | Source Recall@5 | Median estimated context tokens |
 |---|---:|---:|---:|
-| Adaptive context only | 100% | 1,056 | 0% |
-| Adaptive + sentence compression | 100% | 503 | 58% |
+| Full top-k | 6 | 100% | 2,101 |
+| Fixed 3-chunk budget | 3 | 100% | 977 |
+| Adaptive budget | 4 | 100% | 1,099 |
+
+The adaptive policy remains the runtime default because it keeps more safety margin for ambiguous queries than a global fixed-three rule.
+
+## Sentence compression
 
-Compression modifies only the generation copy of retrieved evidence. Source cards and citation provenance retain the original retrieved chunks.
+Focused sentence selection is applied after the context budget. In the latest ablation, labeled answer evidence was retained in all nine focused cases while the selected evidence was reduced further before generation.
 
-## Scale stress
+This result is specific to the bundled benchmark. It should be read as evidence that the local compression policy is safe for these cases, not as a universal token-reduction guarantee.
 
-The zero-Gemini synthetic stress harness reused existing long-document vectors and exercised the real hybrid retriever with distractor clones.
+## Synthetic scale stress
 
-| Scale | Chunks | Sources | Recall@5 | Hit@1 | MRR | Adaptive-pruned Recall@5 | Retrieval median |
-|---|---:|---:|---:|---:|---:|---:|---:|
-| Base | 90 | 5 | 100% | 100% | 1.000 | 100% | 5.5 ms |
-| +4x long-doc distractors | 434 | 9 | 100% | 100% | 1.000 | 100% | 7.5 ms |
-| +19x long-doc distractors | 1,724 | 24 | 100% | 87.5% | 0.938 | 100% | 48.2 ms |
+The scale harness reuses existing vectors and adds deterministic distractor copies so the real dense + BM25 + RRF retrieval path can be tested at larger index sizes without additional model calls.
+
+| Scale | Chunks | Sources | Source Recall@5 | Hit@1 | MRR |
+|---|---:|---:|---:|---:|---:|
+| Base | 90 | 5 | 100% | 100% | 1.000 |
+| +4x long-document distractors | 434 | 9 | 100% | 100% | 1.000 |
+| +19x long-document distractors | 1,724 | 24 | 100% | 87.5% | 0.938 |
 
-This is evidence that Recall@5 remained robust under synthetic distractor scale. It is not a substitute for a real enterprise corpus benchmark.
+The largest synthetic run retained Recall@5, while ranking quality at the very top weakened slightly. This is useful as a regression signal, but a real large-corpus upload is still needed before making stronger scale claims.
 
-## Reranker ablation
+## Reranker tradeoff
 
-The demo benchmark repeatedly found no source- or chunk-level ranking gain from the cross-encoder on the small corpus while retrieval latency increased by orders of magnitude. v1.9 measured roughly a **290x** retrieval-time multiplier in the explicit ablation.
+On the bundled corpus, the cross-encoder reranker repeatedly added multi-second retrieval cost without improving labeled source- or chunk-level ranking metrics. The runtime therefore skips it for the measured small-corpus case and leaves it available for larger or harder workloads.
 
-RAGForge therefore keeps the reranker available but skips it under the measured small-corpus policy. Larger corpora remain eligible because the demo does not prove the reranker is universally unnecessary.
+## Latency
 
-## Runtime
+Generation remains the dominant part of service latency. That is why recent optimization work focused on context size and prompt inputs rather than shaving milliseconds from retrieval.
 
-| Metric | Result |
-|---|---:|
-| Pipeline p50 | 1.79 s |
-| Pipeline p95 | 5.07 s |
-| Planner p50 | 1.71 s |
-| Planner p95 | 1.84 s |
-| Mean estimated LLM calls | 0.76 |
-| Standard Gemini requests | 36 |
-| Evaluation target | 12 RPM |
-| 429 retries | 0 |
+The evaluation UI separates service latency from deliberate request pacing, so a quota-safe Standard run can take several minutes wall-clock without making the pipeline itself appear artificially slow.
 
-Generation remained the dominant node by a wide margin, which motivated context/prompt optimization rather than further millisecond-scale retrieval tuning.
+## How to use these results
 
-## Interpretation
+The benchmark is most useful for three things:
 
-The final engineering conclusions are more important than the headline grade:
+1. catching regressions in routing, retrieval, grounding, SQL, and missing-information behavior;
+2. comparing runtime policies such as reranking, context budgets, and sentence compression; and
+3. exposing measurement bugs in the evaluator itself.
 
-- retrieval recall is strong enough that **context selection** is now the more useful optimization surface
-- deterministic evaluation caught several bugs in the evaluator itself, including invalid AP calculations, missing table-citation sources, false citation-coverage failures, and missing-answer false negatives
-- measured reranker cost changed runtime policy rather than remaining a decorative architecture component
-- benchmark request pacing made evaluation repeatable under a 15-RPM free-tier project without 429 failures
-- the project exposes limitations rather than treating a synthetic stress run as proof of production scale
+For a final deployment result, rerun Standard after installing v2.0.1 so the stricter numeric answer matcher is used.

docs/MIGRATION_2.0.1.md

@@ -0,0 +1,21 @@
+# Upgrade to RAGForge v2.0.1
+
+v2.0.1 is a small correctness and presentation patch over v2.0.0.
+
+## What changed
+
+- landing and evaluation UI copy is simplified and historical benchmark badges are removed
+- evaluation summaries are scoped to the bundled benchmark instead of presenting grade/readiness cards
+- Quick no longer reports acceptance/readiness results for ablations it does not run
+- answer-key matching is boundary-aware, fixing numeric substring false positives such as `5 min` matching `15 minutes`
+- the source-localization planner case accepts both semantic and hierarchical retrieval
+- context-budget experiment names no longer contain development-version labels
+- README and evaluation documentation are rewritten around behavior, methodology, and limitations
+
+## Benchmark compatibility
+
+The benchmark version is `2.0.1`. Existing `2.0` saved evaluation reports remain historical but are not reused as current results because answer-matching semantics changed.
+
+## Upgrade
+
+Apply the patch over v2.0.0, then run Quick. Run Standard once if you want a new authoritative benchmark result under the corrected matcher.

docs/PORTFOLIO_GUIDE.md

@@ -1,116 +1,86 @@
-# Portfolio and interview guide
+# Demo guide
 
-## 2-minute demo
+This page is a short walkthrough for showing RAGForge without turning the demo into a feature checklist.
 
-Use the bundled corpus with **Auto + Balanced**.
+## Suggested demo
 
-### 1. Focused retrieval
+Use the bundled corpus with `Auto` + `Balanced`.
 
-Ask:
+### Focused document question
 
 ```text
 What is the Sev-1 acknowledgement target?
 ```
 
-Show:
+Show the answer, the returned source, and the Pipeline Inspector. The useful point is that retrieval can start broad enough for safety while the generation context is reduced when the evidence is clear.
 
-- one-sentence grounded answer with `[D1]`
-- semantic route / fact lookup
-- adaptive context budget
-- evidence sentence compression
-- reranker skipped with an explicit policy reason
-- node latency waterfall
-
-Talking point: RAGForge separates retrieval depth from generation context. It can retrieve broadly enough for safety, then reduce what reaches the model.
-
-### 2. Global corpus overview
-
-Ask:
+### Corpus overview
 
 ```text
 What is the collection about?
 ```
 
-Show:
-
-- source-balanced global retrieval
-- all five source families represented
-- `[D#]` document citations and `[T#]` table evidence
-- broad tasks bypass focused pruning/compression
-
-Talking point: long PDFs do not dominate simply because they create more chunks.
+Show that the result covers the different source files rather than being dominated by the long PDF. The support table should appear as structured evidence rather than being treated only as raw CSV text.
 
-### 3. Analytical synthesis
-
-Ask:
+### Cross-source analysis
 
 ```text
 What exactly does this collection reveal? Identify important trends and caveats.
 ```
 
-Show:
-
-- `insight_synthesis -> analytical`
-- deterministic DuckDB table evidence combined with document evidence
-- quantitative table claims cited as `[T#]`
-
-Talking point: the analytical route is different from a generic document overview and can reason across text + structured data.
+This demonstrates the analytical path, which combines document evidence with deterministic table summaries before generation.
 
-### 4. Text2SQL
-
-Ask:
+### Structured data
 
 ```text
 Which support tier has the shortest first-response SLA?
 ```
 
-Show the SQL route and typed result.
-
-Talking point: routing and SQL execution are independently evaluated. The SQL path is restricted to validated read-only queries.
+Show that the planner sends the question to the read-only SQL path and that the query/result are inspectable.
 
-### 5. Evaluation
+### Evaluation
 
-Open Standard evaluation results and show:
+Open a Standard result and show one or two tables rather than the whole report. The most useful examples are:
 
-- component metrics instead of one opaque score
-- context-budget and compression ablations
-- scale stress
-- node latency
-- release readiness
+- retrieval vs reranking,
+- full vs fixed vs adaptive context budgets,
+- sentence-compression signal retention,
+- node latency, and
+- synthetic scale stress.
 
-Talking point: evaluation findings changed runtime policy. For example, the small-corpus reranker is skipped because the ablation showed large latency cost without measured ranking gain.
+The main point is that evaluation changed runtime policy. Components are not enabled just because they are common RAG techniques.
 
-## 30-second architecture explanation
+## Short architecture explanation
 
-> RAGForge first uses a schema-constrained planner to decide whether the question needs documents, SQL, the web, or a mixed path. Document retrieval can be semantic, source-balanced global, hierarchical source-to-chunk, or analytical document-plus-table retrieval. Dense and BM25 results are fused with RRF, then an adaptive policy decides retrieval depth, reranking, context budget, and focused sentence compression. Evidence is graded before generation, CRAG can retry retrieval, web search is conditional rather than automatic, and answers return explicit document/table/web citation IDs plus a full execution trace.
+RAGForge first decides whether a question belongs to documents, structured data, the web, or a mixed path. Document retrieval can be direct semantic search, source-balanced global search, source-first hierarchical search, or analytical document-plus-table retrieval. Dense and lexical results are fused, then runtime policies decide retrieval depth, reranking, and how much evidence reaches generation. The answer returns its sources and an execution trace so those choices can be inspected.
 
-## Strong engineering tradeoffs to discuss
+## Engineering tradeoffs worth discussing
 
 ### Reranking
 
-The implementation contains a cross-encoder, but the runtime does not blindly pay for it. The demo ablation showed no source/chunk gain at small scale while adding multi-second retrieval latency, so the policy skips it there and preserves it for larger/harder workloads.
+The project includes a cross-encoder, but the small demo benchmark did not show a ranking improvement that justified its multi-second cost. The runtime therefore skips it for the measured small-corpus case and keeps it available for larger/harder workloads.
 
-### Context precision vs recall
+### Context size
 
-The demo reached 100% Recall@5 with modest Precision@5. Instead of lowering top-k globally, RAGForge retrieves enough candidates, then applies a generation-specific adaptive context budget. That preserves recall while reducing model input.
+Source recall was strong while precision was modest. Instead of globally lowering retrieval depth, RAGForge separates retrieval from generation context and uses an adaptive evidence budget for focused questions.
 
-### Free-tier evaluation
+### Evaluation cost
 
-A full benchmark can exceed provider RPM limits if every component fires immediately. RAGForge uses a rolling request pacer, honors retry guidance, stores reports, and lets Deep reuse Standard so evaluation itself is operationally realistic.
+A full benchmark can hit free-tier RPM limits. Evaluation uses a rolling request pacer, stores completed reports, and lets Deep reuse a compatible Standard baseline.
 
-### Evaluation bugs are real bugs
+### Evaluator correctness
 
-During development, the evaluator itself produced invalid AP values, missed grouped citations, penalized list citations, and misclassified correct missing-information answers. Fixing the measurement system was part of the engineering work.
+The benchmark itself is tested and versioned. During development it exposed bugs in AP calculation, citation parsing, missing-information scoring, and numeric answer matching. A benchmark result is only useful if the measurement code is also trustworthy.
 
-## Honest limitations to mention
+## Limitations to mention
 
-- standard Hugging Face runtime state is ephemeral
-- no durable multi-tenant storage or distributed vector infrastructure
-- prompt-injection filtering is heuristic defense-in-depth
-- synthetic 1,724-chunk stress is not an enterprise-scale proof
-- token telemetry is estimated, not provider billing data
-- provider model quotas and privacy terms depend on the active tier/project
+- state is ephemeral on a standard Hugging Face Space
+- there is no durable multi-tenant storage layer
+- prompt-injection filtering is heuristic
+- the larger retrieval test uses synthetic distractors
+- trace token counts are estimates rather than billing records
+- production deployment would need stronger tenant isolation, durable storage, and external infrastructure
 
-## Resume-ready one-liner
+## Resume description
 
-> Built RAGForge, a Dockerized FastAPI/Gradio agentic RAG system with semantic routing, hybrid + hierarchical retrieval, analytical document/table synthesis, read-only Text2SQL, conditional web research, adaptive context compression, cited answers, and an evaluation suite spanning robustness, citation quality, retrieval ablations, scale stress, latency, and release-readiness gates.
+> Built a FastAPI/Gradio RAG system that routes questions across documents, structured data, and web search, combines dense and lexical retrieval, returns source-linked answers, and includes regression tests for retrieval, routing, SQL, robustness, latency, and context-selection policies.

docs/RESUME_BULLETS.md

@@ -6,7 +6,7 @@
 
 ## Measured supporting result
 
-- On the user-verified v1.9 Standard baseline, achieved 100% answer accuracy, Recall@5, citation validity/coverage, planner route/task/strategy accuracy and Text2SQL pass; adaptive context budgeting preserved 100% Recall@5 while reducing median context by 41%, with sentence compression retaining 100% labeled answer signals and cutting selected evidence tokens by a further 58%.
+- Built a transparent regression suite for retrieval, routing, citation grounding, Text2SQL, robustness, latency, context selection, and synthetic scale stress; used its ablations to drive runtime policies such as small-corpus reranker skipping and adaptive generation context.
 
 - Extended RAGForge with an **Insight Synthesis** path that semantically distinguishes collection overviews from trend/pattern analysis, combines source-balanced document evidence with deterministic DuckDB descriptive context, and grounds structured claims with `[T#]` citations.
 - Evolved the evaluation suite into a **hard-mode robustness benchmark** covering paraphrase, distractors, missing answers, multi-hop reasoning, local freshness semantics, analytical synthesis, structured filtering and prompt-injection checks; added hard-mode quality gates.
@@ -46,5 +46,5 @@
 ## v1.9 scale / efficiency bullets
 
 - Generalized evaluation-driven context pruning into a **corpus-aware retrieval budget**: dynamically expanded candidate depth with corpus scale, selected 2-5 evidence chunks from ranking confidence/ambiguity, and applied zero-LLM sentence compression while preserving broad multi-source synthesis paths.
-- Built **zero-Gemini scale and context ablations** that stress the real hybrid retriever at roughly 1x/5x/20x long-document distractor scale, compare full/fixed/adaptive context policies, validate answer-signal retention, and gate release readiness on quality/robustness thresholds.
+- Built **zero-Gemini scale and context ablations** that stress the real hybrid retriever at roughly 1x/5x/20x long-document distractor scale, compare full/fixed/adaptive context policies, validate answer-signal retention, and gate acceptance checks on quality/robustness thresholds.
 - Added **prompt-economics and operational observability** including estimated generation input/output tokens, cited-evidence utilization, pace-corrected node latency, workspace capacity/index-memory diagnostics and a release-readiness checklist exposed in Gradio and FastAPI.

docs/architecture.mmd

@@ -55,7 +55,7 @@ flowchart TD
     EV --> ST[1x / 5x / 20x scale stress]
     EV --> LAT[Service node latency]
     EV --> DJ[Optional calibrated Deep judge]
-    RM --> READY[Quality gates + release readiness]
+    RM --> READY[Quality gates + acceptance checks]
     CTX --> READY
     PL --> READY
     CIT --> READY

evals/README.md

@@ -1,8 +1,8 @@
-# RAGForge benchmark - v2.0 final
+# RAGForge demo benchmark
 
-The final benchmark keeps the v1.9 retrieval/context/compression/scale methodology and changes one Hard Mode reference path: `hard_multihop_time_compare` now runs under `Auto + Balanced` and explicitly expects `documents -> comparison -> hierarchical`. This matches the recommended semantic runtime instead of using Fast mode as the reference for a multi-source comparison.
+The benchmark covers retrieval, routing, context policies, structured data, robustness, and scale stress. The multi-source Hard Mode comparison runs through the recommended Auto + Balanced path: `hard_multihop_time_compare` now runs under `Auto + Balanced` and explicitly expects `documents -> comparison -> hierarchical`. This matches the recommended semantic runtime instead of using Fast mode as the reference for a multi-source comparison.
 
-## v1.9 local ablations and scale stress
+## Local ablations and scale stress
 
 Standard/Deep add three zero-Gemini evaluation surfaces: a three-way full-vs-fixed-vs-adaptive context budget, focused sentence-compression signal retention, and a 1x/5x/20x synthetic long-document distractor stress harness. These are regression/engineering tests for the bundled demo, not claims of universal large-corpus performance. The release-readiness table applies explicit thresholds to the underlying metrics and marks missing Standard/Deep stress evidence as incomplete rather than silently passing it.
 
@@ -53,4 +53,4 @@ Citation coverage is Markdown-aware, missing-answer cases accept natural grounde
 
 Standard/Deep now add a deterministic `context_budget_ablation` table. It compares the original six-chunk focused context with the adaptive three-chunk safety floor and reports source Precision@5, Recall@5, Hit@1, MRR, median chunks/sources/chars, estimated tokens and reduction percentage. The ablation issues no Gemini requests.
 
-The missing-answer Hard Mode row also exposes `missing_answer_match` and `grounded_absence`. Either calibrated signal can satisfy the missing-information decision, avoiding false failures caused by one exact wording.
+The missing-answer Hard Mode row also exposes `missing_answer_match` and `grounded_absence`. Either calibrated signal can satisfy the missing-information decision, avoiding false failures caused by one exact wording.

evals/demo_benchmark.json

@@ -1,6 +1,6 @@
 {
-  "version": "2.0",
-  "description": "RAGForge v2.0 final benchmark with adaptive context budgets, evidence compression, scale stress, grounded absence, hard-mode robustness, release readiness, and a default-profile multi-hop comparison case.",
+  "version": "2.0.1",
+  "description": "RAGForge bundled benchmark for retrieval, routing, grounded answers, Text2SQL, robustness, context policies, and synthetic scale stress.",
   "qa_cases": [
     {
       "id": "qa_acme_sev1_ack",
@@ -214,7 +214,11 @@
       "route": "documents",
       "task": "fact_lookup",
       "strategy": "hierarchical",
-      "web_expected": false
+      "web_expected": false,
+      "strategy_any": [
+        "hierarchical",
+        "semantic"
+      ]
     },
     {
       "id": "plan_internal_comparison",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ragforge"
-version = "2.0.0"
+version = "2.0.1"
 description = "Production-style agentic RAG demo for Hugging Face Spaces"
 requires-python = ">=3.11"
 dependencies = []

scripts/release_check.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Dependency-free consistency checks for the final RAGForge release."""
+"""Dependency-free consistency checks for the RAGForge release."""
 
 from __future__ import annotations
 
@@ -8,8 +8,8 @@ import re
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[1]
-APP_VERSION = "2.0.0"
-BENCHMARK_VERSION = "2.0"
+APP_VERSION = "2.0.1"
+BENCHMARK_VERSION = "2.0.1"
 
 
 def read(path: str) -> str:
@@ -27,18 +27,23 @@ def main() -> None:
     api_py = read("src/ragforge/api.py")
     ui_py = read("src/ragforge/ui.py")
     readme = read("README.md")
+    metrics_py = read("src/ragforge/eval_metrics.py")
     benchmark = json.loads(read("evals/demo_benchmark.json"))
 
     require(f'version = "{APP_VERSION}"' in pyproject, "pyproject version mismatch")
     require(f'__version__ = "{APP_VERSION}"' in init_py, "package version mismatch")
     require(f'version="{APP_VERSION}"' in api_py, "FastAPI version mismatch")
-    require(f'RAGForge v{APP_VERSION}' in ui_py, "UI version mismatch")
+    require(f'`v{APP_VERSION}`' in ui_py, "runtime UI version mismatch")
     require(benchmark.get("version") == BENCHMARK_VERSION, "benchmark version mismatch")
 
     require("—" not in ui_py and "–" not in ui_py, "UI contains long dash glyphs")
-    require("Final portfolio release" in ui_py, "final UI hero missing")
-    require("Verified pre-final benchmark" in readme, "final benchmark section missing from README")
-    require("v2.0.0 is the final planned feature release" in readme, "final project status missing")
+    require("Final portfolio release" not in ui_py, "release-marketing copy remains in UI")
+    require("Pre-final readiness" not in ui_py, "readiness billboard remains in UI")
+    require("Verified v1.9 grade" not in ui_py, "historical grade billboard remains in UI")
+    require("[D#] [T#] [W#] citations" not in ui_py, "internal citation syntax remains in hero copy")
+    require("The results describe this demo benchmark only; they are not general accuracy claims." in ui_py, "evaluation scope note missing")
+    require("final portfolio release" not in readme.lower(), "README still reads like portfolio-release marketing")
+    require("_contains_expected_term" in metrics_py, "boundary-aware answer matcher missing")
 
     required_docs = [
         "CHANGELOG.md",
@@ -68,7 +73,10 @@ def main() -> None:
     require(multihop.get("expected_task") == "comparison", "multi-hop Hard Mode expected task mismatch")
     require(multihop.get("expected_strategy") == "hierarchical", "multi-hop Hard Mode expected strategy mismatch")
 
-    # Catch an earlier UI regression where the live runtime header was duplicated.
+    planner_cases = {case.get("id"): case for case in benchmark.get("planner_cases", [])}
+    source_lookup = planner_cases.get("plan_find_refund_file", {})
+    require(set(source_lookup.get("strategy_any", [])) == {"semantic", "hierarchical"}, "source-localization strategy alternatives missing")
+
     architecture_fn = re.search(
         r"def _architecture_snapshot\(.*?\n\s*return sid, runtime, curl, runtime_json",
         ui_py,
@@ -77,10 +85,7 @@ def main() -> None:
     require(architecture_fn is not None, "architecture snapshot function missing")
     require(architecture_fn.group(0).count("**RAGForge:**") == 1, "runtime header is duplicated")
 
-    print(
-        "RAGForge release check PASS - "
-        f"app {APP_VERSION}, benchmark {BENCHMARK_VERSION}, final docs/UI/benchmark aligned."
-    )
+    print(f"RAGForge release check PASS - app {APP_VERSION}, benchmark {BENCHMARK_VERSION}.")
 
 
 if __name__ == "__main__":

src/ragforge/__init__.py

@@ -1,3 +1,3 @@
 """RAGForge: production-style agentic retrieval augmented generation demo."""
 
-__version__ = "2.0.0"
+__version__ = "2.0.1"

src/ragforge/api.py

@@ -29,7 +29,7 @@ def _auth(authorization: Annotated[str | None, Header()] = None) -> None:
 
 
 def create_api() -> FastAPI:
-    app = FastAPI(title="RAGForge API", version="2.0.0")
+    app = FastAPI(title="RAGForge API", version="2.0.1")
 
     @app.get("/api/health")
     def health():

src/ragforge/eval_metrics.py

@@ -41,13 +41,32 @@ def percentile(values: list[float], q: float) -> float:
     return ordered[lo] + (ordered[hi] - ordered[lo]) * (pos - lo)
 
 
+def _contains_expected_term(answer: str, term: str) -> bool:
+    """Match a labeled answer term without accepting alphanumeric substrings.
+
+    Plain ``term in answer`` makes numeric labels unsafe: for example ``5 min``
+    is a substring of ``15 minutes``. Benchmark matching should recognize the
+    expected phrase as its own token/phrase while remaining tolerant of ordinary
+    whitespace differences.
+    """
+    text = re.sub(r"\s+", " ", (answer or "").casefold()).strip()
+    expected = re.sub(r"\s+", " ", (term or "").casefold()).strip()
+    if not expected:
+        return False
+    pattern = re.escape(expected).replace(r"\ ", r"\s+")
+    if expected[0].isalnum():
+        pattern = r"(?<![0-9A-Za-z])" + pattern
+    if expected[-1].isalnum():
+        pattern = pattern + r"(?![0-9A-Za-z])"
+    return re.search(pattern, text) is not None
+
+
 def answer_key_match(answer: str, case: dict[str, Any]) -> bool:
-    answer_l = answer.lower()
-    expected_all = [str(x).lower() for x in case.get("expected_all", [])]
-    expected_any = [str(x).lower() for x in case.get("expected_any", [])]
-    if expected_all and not all(term in answer_l for term in expected_all):
+    expected_all = [str(x) for x in case.get("expected_all", [])]
+    expected_any = [str(x) for x in case.get("expected_any", [])]
+    if expected_all and not all(_contains_expected_term(answer, term) for term in expected_all):
         return False
-    if expected_any and not any(term in answer_l for term in expected_any):
+    if expected_any and not any(_contains_expected_term(answer, term) for term in expected_any):
         return False
     return bool(expected_all or expected_any)
 

src/ragforge/evaluation.py

@@ -211,8 +211,8 @@ def _retrieval_ablation(workspace: Workspace, qa_cases: list[dict[str, Any]]) ->
 
 
 def _context_budget_ablation(workspace: Workspace, qa_cases: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    """Zero-Gemini comparison of full, v1.8 fixed and v1.9 adaptive budgets."""
-    labels = ("Full top-k", "v1.8 fixed top-3", "v1.9 adaptive budget")
+    """Zero-Gemini comparison of full, fixed, and adaptive context budgets."""
+    labels = ("Full top-k", "Fixed 3-chunk budget", "Adaptive budget")
     buckets: dict[str, list[dict[str, float]]] = {label: [] for label in labels}
     for case in qa_cases:
         plan = QueryPlan(
@@ -235,8 +235,8 @@ def _context_budget_ablation(workspace: Workspace, qa_cases: list[dict[str, Any]
         )
         variants = {
             "Full top-k": (hits, len(hits), "full"),
-            "v1.8 fixed top-3": (fixed.hits, fixed.target_chunks, fixed.reason),
-            "v1.9 adaptive budget": (adaptive.hits, adaptive.target_chunks, adaptive.reason),
+            "Fixed 3-chunk budget": (fixed.hits, fixed.target_chunks, fixed.reason),
+            "Adaptive budget": (adaptive.hits, adaptive.target_chunks, adaptive.reason),
         }
         full_chars = max(1, sum(len(hit.chunk.text or "") + len(hit.chunk.source or "") + 24 for hit in hits))
         for label, (variant, target, reason) in variants.items():
@@ -254,7 +254,7 @@ def _context_budget_ablation(workspace: Workspace, qa_cases: list[dict[str, Any]
                 "context_chars": float(chars),
                 "context_tokens_est": float((chars + 3) // 4),
                 "context_reduction_pct": float(max(0.0, 1.0 - chars / full_chars) * 100.0),
-                "adaptive_used": float(label == "v1.9 adaptive budget" and len(variant) < len(hits)),
+                "adaptive_used": float(label == "Adaptive budget" and len(variant) < len(hits)),
             })
 
     rows: list[dict[str, Any]] = []
@@ -413,7 +413,7 @@ def _planner_eval(
                 "task_correct": plan.task_type == case["task"],
                 "expected_strategy": case["strategy"],
                 "strategy": plan.retrieval_strategy,
-                "strategy_correct": plan.retrieval_strategy == case["strategy"],
+                "strategy_correct": plan.retrieval_strategy in set(case.get("strategy_any", [case["strategy"]])),
                 "expected_web": bool(case["web_expected"]),
                 "planned_web": planned_web,
                 "latency_ms": round(latency, 1),
@@ -985,7 +985,7 @@ def _diagnostics(
 
     context_budget_rows = context_budget_rows or []
     adaptive_row = next(
-        (row for row in context_budget_rows if row.get("configuration") == "v1.9 adaptive budget"), {}
+        (row for row in context_budget_rows if row.get("configuration") == "Adaptive budget"), {}
     )
     full_row = next((row for row in context_budget_rows if row.get("configuration") == "Full top-k"), {})
     if summary.get("source_recall@5", 0.0) >= 0.95 and summary.get("source_precision@5", 1.0) < 0.60:
@@ -1389,7 +1389,7 @@ def run_demo_eval(
     grade, quality_gates = _grade_with_gates(deterministic_score, metrics_for_gate)
 
     adaptive_budget_row = next(
-        (row for row in context_budget_rows if row.get("configuration") == "v1.9 adaptive budget"), {}
+        (row for row in context_budget_rows if row.get("configuration") == "Adaptive budget"), {}
     )
     compression_row = next(
         (row for row in compression_rows if row.get("configuration") == "Adaptive + sentence compression"), {}
@@ -1462,10 +1462,15 @@ def run_demo_eval(
     profile_recommendation = _profile_recommendation(profile_summary_rows)
     if profile_recommendation:
         summary["profile_recommendation"] = profile_recommendation
-    readiness_rows = _readiness_rows(summary, scale_stress_rows, compression_rows)
-    readiness_status, readiness_score = _readiness_summary(readiness_rows)
-    summary["release_readiness"] = readiness_status
-    summary["release_readiness_score"] = round(readiness_score, 3)
+    if level == "Quick":
+        readiness_rows = []
+        summary["release_readiness"] = "NOT RUN"
+        summary["release_readiness_score"] = None
+    else:
+        readiness_rows = _readiness_rows(summary, scale_stress_rows, compression_rows)
+        readiness_status, readiness_score = _readiness_summary(readiness_rows)
+        summary["release_readiness"] = readiness_status
+        summary["release_readiness_score"] = round(readiness_score, 3)
     diagnostics = _diagnostics(
         summary, ablation_rows, planner_rows, sql_rows, hard_rows, profile_summary_rows, node_latency_rows,
         context_budget_rows, compression_rows, scale_stress_rows
@@ -1528,7 +1533,7 @@ def run_demo_eval(
             "hard_mode": "Hard-mode cases cover paraphrase, distractors, missing answers, multi-hop comparison, analytical synthesis, structured filtering, local freshness semantics and prompt-injection detection.",
             "profile_benchmark": "Optional Fast/Balanced/Agentic comparison uses a small labeled subset because it intentionally spends additional Gemini requests.",
             "chunk_ablation": "Retrieval ablation reports source-level metrics plus chunk Hit@1/MRR for cases with explicit chunk-content labels.",
-            "context_budget": "Focused-query pruning is evaluated as a zero-Gemini ablation across full top-k, the v1.8 fixed top-3 policy and the v1.9 adaptive budget chosen from retrieval confidence, score separation and corpus scale.",
+            "context_budget": "Focused-query pruning is evaluated as a zero-Gemini ablation across full top-k, a fixed 3-chunk budget, and the adaptive budget chosen from retrieval confidence, score separation and corpus scale.",
             "evidence_compression": "Focused evidence compression selects query-relevant sentences after context budgeting and is evaluated by deterministic answer-signal retention plus token reduction; it never spends a Gemini request.",
             "scale_stress": "Scale stress reuses existing embedding vectors and clones long-document distractor chunks to exercise the real Qdrant + BM25 path at roughly 1x, 5x and 20x distractor scale without additional Gemini calls.",
             "release_readiness": "A transparent readiness checklist applies explicit thresholds to answer quality, grounding, routing, robustness, adaptive-budget recall, compression retention and largest-scale retrieval recall. It does not replace the underlying metrics.",

src/ragforge/ui.py

@@ -21,7 +21,7 @@ DEMO_DIR = ROOT / "demo_documents"
 
 CSS = """
 #hero {max-width: 1220px; margin: 0 auto 14px auto;}
-.hero-shell {padding: 20px 22px; border: 1px solid rgba(128,128,128,.22); border-radius: 16px; background: linear-gradient(135deg, rgba(99,102,241,.08), rgba(128,128,128,.03));}
+.hero-shell {padding: 20px 22px; border: 1px solid rgba(128,128,128,.22); border-radius: 14px; background: rgba(128,128,128,.025);}
 .hero-kicker {font-size: .78rem; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; opacity: .72;}
 .hero-title {font-size: 2.3rem; line-height: 1.05; font-weight: 780; margin: 5px 0 8px 0;}
 .hero-subtitle {font-size: 1rem; line-height: 1.55; max-width: 900px; opacity: .84;}
@@ -45,12 +45,15 @@ CSS = """
 .latency-track {height: 9px; border-radius: 999px; background: rgba(128,128,128,.18); overflow: hidden;}
 .latency-fill {height: 100%; min-width: 2px; border-radius: 999px; background: var(--primary-500, currentColor);}
 .latency-time {font-size: .84rem; text-align: right; opacity: .8;}
-.eval-card-grid {display: grid; grid-template-columns: repeat(5, minmax(105px, 1fr)); gap: 8px; margin: 8px 0 14px 0;}
-.eval-card {padding: 10px 12px; border: 1px solid rgba(128,128,128,.2); border-radius: 10px; background: rgba(128,128,128,.035);}
-.eval-card-label {font-size: .70rem; text-transform: uppercase; letter-spacing: .045em; opacity: .65;}
-.eval-card-value {font-size: 1.05rem; font-weight: 720; margin-top: 2px;}
+.eval-summary {margin: 8px 0 14px 0; padding: 14px 16px; border: 1px solid rgba(128,128,128,.20); border-radius: 12px; background: rgba(128,128,128,.025);}
+.eval-summary-title {font-size: 1.08rem; font-weight: 680; margin-bottom: 3px;}
+.eval-summary-scope {font-size: .86rem; opacity: .70; line-height: 1.45; margin-bottom: 10px;}
+.eval-summary-table {display: grid; grid-template-columns: minmax(140px, 190px) 1fr; row-gap: 7px; column-gap: 14px;}
+.eval-summary-row {display: contents;}
+.eval-summary-label {font-size: .86rem; font-weight: 620; opacity: .76;}
+.eval-summary-value {font-size: .90rem; line-height: 1.4;}
 .footer-note {text-align: center; opacity: .68; font-size: .82rem; padding: 15px 0 4px 0;}
-@media (max-width: 900px) {.baseline-grid,.eval-card-grid {grid-template-columns: repeat(2, minmax(120px, 1fr));}}
+@media (max-width: 900px) {.eval-summary-table {grid-template-columns: 1fr;} .eval-summary-row {display: block; margin-bottom: 8px;}}
 """
 
 
@@ -202,103 +205,72 @@ def _inspector_markdown(trace: dict[str, Any]) -> str:
 
 
 def _eval_summary_markdown(report: dict[str, Any]) -> str:
+    """Render a scoped benchmark summary without marketing-style grades or badges."""
     summary = report.get("summary", {}) if report else {}
     if not summary:
-        return "*Run an evaluation to see the score card.*"
-    cards = (
-        '<div class="eval-card-grid">'
-        f'<div class="eval-card"><div class="eval-card-label">Grade</div><div class="eval-card-value">{html.escape(str(summary.get("quality_grade", "-")))}</div></div>'
-        f'<div class="eval-card"><div class="eval-card-label">Answer accuracy</div><div class="eval-card-value">{float(summary.get("answer_accuracy", 0.0)):.0%}</div></div>'
-        f'<div class="eval-card"><div class="eval-card-label">Recall@5</div><div class="eval-card-value">{float(summary.get("source_recall@5", 0.0)):.0%}</div></div>'
-        f'<div class="eval-card"><div class="eval-card-label">Citation coverage</div><div class="eval-card-value">{float(summary.get("citation_coverage", 0.0)):.0%}</div></div>'
-        f'<div class="eval-card"><div class="eval-card-label">Release readiness</div><div class="eval-card-value">{html.escape(str(summary.get("release_readiness", "-")))}</div></div>'
-        '</div>'
-    )
-    lines = [
-        f"### Evaluation score card - {summary.get('evaluation_level', '-')} - grade {summary.get('quality_grade', '-')}",
-        cards,
-        f"**Deterministic quality:** `{float(summary.get('deterministic_quality_score', 0.0)):.3f}` - "
-        f"**answer accuracy:** `{float(summary.get('answer_accuracy', 0.0)):.0%}` - "
-        f"**source Precision@5:** `{float(summary.get('source_precision@5', 0.0)):.0%}` - "
-        f"**source Recall@5:** `{float(summary.get('source_recall@5', 0.0)):.0%}` - "
-        f"**Hit@1:** `{float(summary.get('source_hit@1', 0.0)):.0%}` - "
-        f"**MRR:** `{float(summary.get('source_mrr', 0.0)):.3f}` - "
-        f"**AP@5:** `{float(summary.get('source_ap@5', 0.0)):.3f}` - "
-        f"**nDCG@5:** `{float(summary.get('source_ndcg@5', 0.0)):.3f}`",
-        "",
-        f"**Citation validity:** `{float(summary.get('citation_validity', 0.0)):.0%}` - "
-        f"**citation coverage:** `{float(summary.get('citation_coverage', 0.0)):.0%}` - "
-        f"**overview pass:** `{float(summary.get('overview_pass_rate', 0.0)):.0%}` - "
-        f"**Text2SQL pass:** `{float(summary.get('text2sql_pass_rate', 0.0)):.0%}` - "
-        f"**hard-mode pass:** `{float(summary.get('hard_mode_pass_rate', 0.0)):.0%}`",
-        "",
-        f"**Planner route/task/strategy:** `{float(summary.get('planner_route_accuracy', 0.0)):.0%}` / "
-        f"`{float(summary.get('planner_task_accuracy', 0.0)):.0%}` / "
-        f"`{float(summary.get('planner_strategy_accuracy', 0.0)):.0%}` - "
-        f"**web precision/recall:** `{float(summary.get('web_use_precision', 0.0)):.0%}` / "
-        f"`{float(summary.get('web_use_recall', 0.0)):.0%}`",
-        "",
-        f"**Adaptive context policy:** Precision@5 `{float(summary.get('context_pruning_precision@5', 0.0)):.0%}` - "
-        f"Recall@5 `{float(summary.get('context_pruning_recall@5', 0.0)):.0%}` - "
-        f"target chunks p50 `{float(summary.get('adaptive_context_target_p50', 0.0)):.1f}` - "
-        f"median context reduction `{float(summary.get('context_pruning_token_reduction_pct', 0.0)):.0f}%`",
-        f"**Evidence compression:** signal retention `{float(summary.get('compression_signal_retention', 0.0)):.0%}` - "
-        f"additional reduction `{float(summary.get('compression_additional_reduction_pct', 0.0)):.0f}%` - "
-        f"runtime compression rate `{float(summary.get('focused_evidence_compression_rate', 0.0)):.0%}`",
-        f"**Focused context tokens p50:** `{float(summary.get('focused_context_tokens_before_p50', 0.0)):.0f} -> {float(summary.get('focused_context_tokens_after_p50', 0.0)):.0f}` - "
-        f"**generation prompt/total tokens p50:** `{float(summary.get('focused_generation_prompt_tokens_p50', 0.0)):.0f}` / "
-        f"`{float(summary.get('focused_generation_total_tokens_p50', 0.0)):.0f}` - "
-        f"**evidence utilization p50:** `{float(summary.get('focused_evidence_utilization_p50', 0.0)):.0%}`",
-        f"**Scale stress:** max `{int(summary.get('scale_stress_max_chunks', 0) or 0)}` chunks - "
-        f"Recall@5 `{float(summary.get('scale_stress_recall@5', 0.0)):.0%}` - "
-        f"adaptive-pruned recall `{float(summary.get('scale_stress_pruned_recall@5', 0.0)):.0%}`",
-        f"**Release readiness:** `{summary.get('release_readiness', '-')}` - "
-        f"`{float(summary.get('release_readiness_score', 0.0)):.0%}` critical checks passed",
-        "",
-        f"**Pipeline latency p50/p95:** `{float(summary.get('latency_p50_ms', 0.0)):.0f} ms` / "
-        f"`{float(summary.get('latency_p95_ms', 0.0)):.0f} ms` - "
-        f"**planner p50/p95:** `{float(summary.get('planner_latency_p50_ms', 0.0)):.0f} ms` / "
-        f"`{float(summary.get('planner_latency_p95_ms', 0.0)):.0f} ms` - "
-        f"**mean estimated LLM calls:** `{float(summary.get('mean_llm_calls_estimate', 0.0)):.2f}`",
-        "",
-        f"**Evaluation wall time:** `{float(summary.get('evaluation_wall_ms', 0.0)) / 1000:.1f} s` - "
-        f"**response cache bypassed:** `{bool(summary.get('cache_bypassed', False))}`",
-        "",
-        f"**Gemini request budget:** "
-        f"`{int(summary.get('evaluation_target_rpm', 0) or 0)} RPM` - "
-        f"**requests issued:** `{int(summary.get('gemini_requests', 0) or 0)}` - "
-        f"**deliberate pacing wait:** `{float(summary.get('pacing_sleep_ms', 0.0) or 0.0) / 1000:.1f} s` - "
-        f"**429 retries:** `{int(summary.get('rate_limit_retries', 0) or 0)}`",
+        return '<div class="eval-summary">Run an evaluation to see a summary.</div>'
+
+    level = str(summary.get("evaluation_level", "Evaluation"))
+    qa = report.get("focused_qa", []) or []
+    planner = report.get("semantic_planner", []) or []
+    overviews = report.get("corpus_overviews", []) or []
+    sql = report.get("text2sql", []) or []
+    hard = report.get("hard_mode", []) or []
+
+    qa_pass = sum(bool(row.get("answer_key_match")) for row in qa)
+    route_pass = sum(bool(row.get("route_correct")) for row in planner)
+    task_pass = sum(bool(row.get("task_correct")) for row in planner)
+    strategy_pass = sum(bool(row.get("strategy_correct")) for row in planner)
+    overview_pass = sum(bool(row.get("pass")) for row in overviews)
+    sql_pass = sum(bool(row.get("answer_key_match")) for row in sql)
+    hard_pass = sum(bool(row.get("pass")) for row in hard)
+
+    rows = [
+        ("Focused QA", f"{qa_pass}/{len(qa)} passed" if qa else "not run"),
+        ("Planner", (f"route {route_pass}/{len(planner)}, task {task_pass}/{len(planner)}, strategy {strategy_pass}/{len(planner)}" if planner else "not run")),
+        ("Corpus overview", f"{overview_pass}/{len(overviews)} passed" if overviews else "not run"),
+        ("Text2SQL", f"{sql_pass}/{len(sql)} passed" if sql else "not run"),
+        ("Hard mode", f"{hard_pass}/{len(hard)} passed" if hard else "not run"),
+        ("Retrieval", f"Recall@5 {float(summary.get('source_recall@5', 0.0)):.0%}; Precision@5 {float(summary.get('source_precision@5', 0.0)):.0%}"),
+        ("Service latency", f"p50 {float(summary.get('latency_p50_ms', 0.0)) / 1000:.2f}s; p95 {float(summary.get('latency_p95_ms', 0.0)) / 1000:.2f}s"),
+        ("Gemini requests", f"{int(summary.get('gemini_requests', 0) or 0)} at {int(summary.get('evaluation_target_rpm', 0) or 0)} RPM pacing"),
     ]
-    gates = summary.get("quality_gate_notes") or []
-    if gates:
-        lines += ["", "**Quality gates affecting the grade:**"] + [f"- {item}" for item in gates]
-    if "judge_overall" in summary:
-        lines += [
-            "",
-            f"**Deep judge:** faithfulness `{float(summary.get('judge_faithfulness', 0.0)):.3f}` - "
-            f"answer relevance `{float(summary.get('judge_answer_relevance', 0.0)):.3f}` - "
-            f"completeness `{float(summary.get('judge_completeness', 0.0)):.3f}` - "
-            f"citation support `{float(summary.get('judge_citation_support', 0.0)):.3f}` - "
-            f"overall `{float(summary.get('judge_overall', 0.0)):.3f}` - "
-            f"judge pass `{float(summary.get('judge_pass_rate', 0.0)):.0%}` - "
-            f"sampled cases `{int(summary.get('deep_judge_cases', 0) or 0)}`",
-        ]
-    if summary.get("profile_benchmark_enabled"):
-        lines.extend([
-            "",
-            f"**Profile benchmark:** `{int(summary.get('profile_benchmark_cases', 0) or 0)}` profile/case runs included.",
+
+    if level != "Quick":
+        adaptive_target = float(summary.get("adaptive_context_target_p50", 0.0) or 0.0)
+        before = float(summary.get("focused_context_tokens_before_p50", 0.0) or 0.0)
+        after = float(summary.get("focused_context_tokens_after_p50", 0.0) or 0.0)
+        compression_cases = report.get("evidence_compression_ablation", []) or []
+        compressed = next((r for r in compression_cases if r.get("configuration") == "Adaptive + sentence compression"), {})
+        retention = float(compressed.get("answer_signal_retention", 0.0) or 0.0)
+        compression_n = int(compressed.get("cases", 0) or 0)
+        scale_chunks = int(summary.get("scale_stress_max_chunks", 0) or 0)
+        scale_recall = float(summary.get("scale_stress_recall@5", 0.0) or 0.0)
+        rows.extend([
+            ("Context policy", f"median target {adaptive_target:.0f} chunks; estimated focused context {before:.0f} -> {after:.0f} tokens"),
+            ("Sentence compression", f"labeled answer signal retained in {int(round(retention * compression_n))}/{compression_n} cases" if compression_n else "not run"),
+            ("Synthetic scale stress", f"{scale_chunks:,} chunks; Recall@5 {scale_recall:.0%}" if scale_chunks else "not run"),
         ])
-        if summary.get("profile_recommendation"):
-            lines.extend(["", f"**Profile policy:** {summary.get('profile_recommendation')}"])
-    if summary.get("reused_standard_baseline"):
-        lines += [
-            "",
-            "**Evaluation reuse:** Deep reused the saved Standard deterministic baseline and ran only the sampled judge layer. "
-            f"Baseline Standard wall time: `{float(summary.get('deterministic_baseline_wall_ms', 0.0) or 0.0) / 1000:.1f} s`.",
-        ]
-    return "\n".join(lines)
+    else:
+        rows.append(("Extended ablations", "not run in Quick; use Standard for context, compression, and scale-stress checks"))
 
+    body = ''.join(
+        f'<div class="eval-summary-row"><div class="eval-summary-label">{html.escape(label)}</div>'
+        f'<div class="eval-summary-value">{html.escape(value)}</div></div>'
+        for label, value in rows
+    )
+    scope = (
+        "Smoke-test subset of the bundled demo benchmark."
+        if level == "Quick"
+        else "Bundled demo benchmark; scale stress uses synthetic distractor copies and is not a claim of enterprise-scale accuracy."
+    )
+    return (
+        '<div class="eval-summary">'
+        f'<div class="eval-summary-title">{html.escape(level)} evaluation</div>'
+        f'<div class="eval-summary-scope">{html.escape(scope)}</div>'
+        f'<div class="eval-summary-table">{body}</div>'
+        '</div>'
+    )
 
 def _eval_diagnostics_markdown(report: dict[str, Any]) -> str:
     diagnostics = report.get("diagnostics", []) if report else []
@@ -361,7 +333,7 @@ def _architecture_snapshot(session_id: str | None) -> tuple[str, str, str, dict[
     settings = get_settings()
     stats = ws.health_snapshot()
     runtime_json = {
-        "ragforge_version": "2.0.0",
+        "ragforge_version": "2.0.1",
         "workspace": stats,
         "models": {
             "generation": settings.default_model,
@@ -382,7 +354,7 @@ def _architecture_snapshot(session_id: str | None) -> tuple[str, str, str, dict[
     }
     runtime = (
         "### Live runtime\n"
-        f"**RAGForge:** `v2.0.0` - **workspace:** `{sid[:12]}...` - **status:** `{stats['status']}`\n\n"
+        f"**RAGForge:** `v2.0.1` - **workspace:** `{sid[:12]}...` - **status:** `{stats['status']}`\n\n"
         f"**Corpus:** `{stats['sources']}` sources - `{stats['chunks']}` chunks - "
         f"`{stats['source_profiles']}` source profiles - `{stats['tables']}` tables - "
         f"corpus version `{stats['version']}`\n\n"
@@ -438,7 +410,7 @@ EVAL_TABLE_KEYS = {
     "Context budget ablation": "context_budget_ablation",
     "Evidence compression": "evidence_compression_ablation",
     "Scale stress": "scale_stress",
-    "Release readiness": "release_readiness",
+    "Acceptance checks": "release_readiness",
     "Hard mode": "hard_mode",
     "Profile benchmark": "profile_benchmark",
     "Profile summary": "profile_summary",
@@ -454,7 +426,7 @@ def _eval_table_frame(ws, report: dict[str, Any], label: str) -> pd.DataFrame:
     if key == "__compare__":
         return _eval_comparison_frame(ws)
     if key == "__history__":
-        return pd.DataFrame(ws.evaluation_history_inventory())
+        return _eval_history_frame(ws)
     if not key:
         return pd.DataFrame()
     return _eval_frame(report, key)
@@ -479,16 +451,13 @@ def _eval_comparison_frame(ws) -> pd.DataFrame:
         rows.append(
             {
                 "depth": item["level"],
-                "grade": summary.get("quality_grade", "-"),
-                "deterministic_score": summary.get("deterministic_quality_score"),
                 "answer_accuracy": summary.get("answer_accuracy"),
-                "citation_coverage": summary.get("citation_coverage"),
+                "source_recall@5": summary.get("source_recall@5"),
+                "source_precision@5": summary.get("source_precision@5"),
+                "planner_strategy_accuracy": summary.get("planner_strategy_accuracy"),
                 "hard_mode_pass": summary.get("hard_mode_pass_rate"),
                 "text2sql_pass": summary.get("text2sql_pass_rate"),
-                "release_readiness": summary.get("release_readiness", ""),
                 "scale_stress_recall@5": summary.get("scale_stress_recall@5"),
-                "adaptive_context_reduction": summary.get("context_pruning_token_reduction_pct"),
-                "planner_task_accuracy": summary.get("planner_task_accuracy"),
                 "pipeline_p50_ms": summary.get("latency_p50_ms"),
                 "gemini_requests": summary.get("gemini_requests"),
                 "pacing_wait_s": round(float(summary.get("pacing_sleep_ms", 0.0) or 0.0) / 1000, 1),
@@ -501,6 +470,24 @@ def _eval_comparison_frame(ws) -> pd.DataFrame:
     return pd.DataFrame(rows)
 
 
+
+def _eval_history_frame(ws) -> pd.DataFrame:
+    rows = []
+    for row in ws.evaluation_history_inventory():
+        rows.append({
+            "saved_at": row.get("saved_at"),
+            "level": row.get("level"),
+            "benchmark": row.get("benchmark"),
+            "model": row.get("model"),
+            "workspace_version": row.get("workspace_version"),
+            "citation_coverage": row.get("citation_coverage"),
+            "hard_mode_pass": row.get("hard_mode_pass"),
+            "p50_ms": row.get("p50_ms"),
+            "gemini_requests": row.get("gemini_requests"),
+            "run_id": row.get("run_id"),
+        })
+    return pd.DataFrame(rows)
+
 def _saved_eval_status(ws) -> str:
     inventory = ws.evaluation_inventory()
     if not inventory:
@@ -509,7 +496,7 @@ def _saved_eval_status(ws) -> str:
     for item in inventory:
         stale = "" if item.get("current_corpus") else " (stale corpus)"
         run_id = item.get("run_id") or "legacy"
-        parts.append(f"`{item['level']}` grade {item.get('grade', '-')} - run `{run_id}`{stale}")
+        parts.append(f"`{item['level']}` - run `{run_id}`{stale}")
     return "**Saved runs:** " + " - ".join(parts)
 
 
@@ -532,33 +519,20 @@ def build_ui() -> gr.Blocks:
         gr.HTML(
             """
 <div id="hero" class="hero-shell">
-  <div class="hero-kicker">RAGForge v2.0.0 - Final portfolio release</div>
-  <div class="hero-title">Evidence-first RAG for documents, tables and the web</div>
+  <div class="hero-title">RAGForge</div>
   <div class="hero-subtitle">
-    Hybrid retrieval, semantic planning, analytical synthesis, read-only Text2SQL, conditional web research,
-    evidence citations, adaptive context budgets and a built-in evaluation harness in one Hugging Face Space.
+    Search and analyze documents, structured tables, and web sources in one workspace.
+    RAGForge routes each question to the appropriate retrieval path and keeps the supporting sources and execution trace visible.
   </div>
   <div class="hero-badges">
-    <span class="hero-badge">Auto + Balanced recommended</span>
-    <span class="hero-badge">Adaptive 2-5 chunk budgets</span>
-    <span class="hero-badge">[D#] [T#] [W#] citations</span>
-    <span class="hero-badge">Quick / Standard / Deep evals</span>
-    <span class="hero-badge">FastAPI + Gradio + LangGraph</span>
+    <span class="hero-badge">Hybrid document search</span>
+    <span class="hero-badge">Read-only Text2SQL</span>
+    <span class="hero-badge">Conditional web search</span>
+    <span class="hero-badge">Built-in evaluation</span>
   </div>
 </div>
             """
         )
-        gr.HTML(
-            """
-<div class="baseline-grid">
-  <div class="baseline-card"><div class="baseline-label">Verified answer accuracy</div><div class="baseline-value">100%</div></div>
-  <div class="baseline-card"><div class="baseline-label">Verified Recall@5</div><div class="baseline-value">100%</div></div>
-  <div class="baseline-card"><div class="baseline-label">Synthetic scale stress</div><div class="baseline-value">1,724 chunks</div></div>
-  <div class="baseline-card"><div class="baseline-label">Pre-final readiness</div><div class="baseline-value">READY</div></div>
-</div>
-<div class="section-note">Verified on the bundled v1.9 Standard benchmark. v2.0 keeps the measured retrieval/runtime architecture and finalizes benchmark alignment, UI, documentation and release tooling.</div>
-            """
-        )
 
         with gr.Tabs():
             with gr.Tab("Chat"):
@@ -862,19 +836,9 @@ def build_ui() -> gr.Blocks:
 
             with gr.Tab("Evaluation"):
                 gr.Markdown(
-                    "### Evaluation lab\n"
-                    "RAGForge evaluates retrieval, routing, analytical synthesis, citations, abstention, Text2SQL, hard-mode robustness, "
-                    "context economics and scale stress against the transparent benchmark in `evals/demo_benchmark.json`."
-                )
-                gr.HTML(
-                    """
-<div class="baseline-grid">
-  <div class="baseline-card"><div class="baseline-label">Verified v1.9 grade</div><div class="baseline-value">A / 0.994</div></div>
-  <div class="baseline-card"><div class="baseline-label">Citations</div><div class="baseline-value">100% / 100%</div></div>
-  <div class="baseline-card"><div class="baseline-label">Context reduction</div><div class="baseline-value">41% + 58%</div></div>
-  <div class="baseline-card"><div class="baseline-label">20x stress recall</div><div class="baseline-value">100%</div></div>
-</div>
-                    """
+                    "### Evaluation\n"
+                    "Run the bundled benchmark to inspect retrieval, routing, grounding, SQL behavior, robustness, latency, and context policies. "
+                    "The results describe this demo benchmark only; they are not general accuracy claims."
                 )
                 eval_level = gr.Radio(
                     ["Quick", "Standard", "Deep"],
@@ -923,7 +887,7 @@ def build_ui() -> gr.Blocks:
                 )
                 eval_btn = gr.Button("Run evaluation", variant="primary")
                 eval_status = gr.Markdown("Ready to evaluate.", elem_classes=["status-line"])
-                eval_scorecard = gr.Markdown("*Run an evaluation to see the score card.*")
+                eval_scorecard = gr.HTML('<div class="eval-summary">Run an evaluation to see a summary.</div>')
                 eval_diagnostics = gr.Markdown("*Diagnostics appear after an evaluation run.*")
                 with gr.Accordion("Saved evaluation runs", open=True):
                     eval_saved_status = gr.Markdown("*No saved evaluation runs for this workspace yet.*")
@@ -951,7 +915,7 @@ def build_ui() -> gr.Blocks:
                         eval_compression = gr.Dataframe(interactive=False, wrap=True)
                     with gr.Tab("Scale stress"):
                         eval_scale_stress = gr.Dataframe(interactive=False, wrap=True)
-                    with gr.Tab("Release readiness"):
+                    with gr.Tab("Acceptance checks"):
                         eval_readiness = gr.Dataframe(interactive=False, wrap=True)
                     with gr.Tab("Hard mode"):
                         eval_hard = gr.Dataframe(interactive=False, wrap=True)
@@ -1046,7 +1010,7 @@ def build_ui() -> gr.Blocks:
                         _eval_frame(report, "node_latency"),
                         _eval_frame(report, "abstention"),
                         _eval_comparison_frame(ws),
-                        pd.DataFrame(ws.evaluation_history_inventory()),
+                        _eval_history_frame(ws),
                         pretty_json(report),
                         _saved_eval_status(ws),
                         status_text,
@@ -1312,7 +1276,7 @@ The bundled benchmark evaluates separate failure surfaces rather than relying on
 - saved runs - Quick/Standard/Deep reports are kept per workspace with corpus/model/benchmark metadata
 - incremental Deep - a compatible Standard baseline can be reused so Deep adds only the sampled judge layer
 
-The letter grade uses quality gates so one weak subsystem cannot be hidden by a high weighted average elsewhere.
+Detailed metrics and acceptance checks are shown separately so a single aggregate score does not hide subsystem behavior.
                             """
                         )
 
@@ -1325,6 +1289,6 @@ The letter grade uses quality gates so one weak subsystem cannot be hidden by a
                 )
 
         gr.HTML(
-            '<div class="footer-note">RAGForge v2.0.0 - final portfolio release - evidence-first retrieval, transparent evaluation, explicit limitations.</div>'
+            '<div class="footer-note">RAGForge - document, table, and web retrieval with inspectable sources and evaluation.</div>'
         )
         return demo

tests/test_eval_metrics.py

@@ -37,6 +37,10 @@ def test_answer_key_supports_all_and_any():
     assert answer_key_match("Govern, Map, Measure, Manage", {"expected_all": ["govern", "map", "measure", "manage"]})
     assert answer_key_match("Enterprise is fastest", {"expected_any": ["enterprise", "business"]})
     assert not answer_key_match("Team is fastest", {"expected_any": ["enterprise"]})
+    # Numeric answer labels must not match inside a different number. This caught
+    # a real regression where "15 minutes" passed a "5 min" answer key.
+    assert answer_key_match("The target is 5 minutes.", {"expected_any": ["5 minutes", "5 min"]})
+    assert not answer_key_match("The target is 15 minutes.", {"expected_any": ["5 minutes", "5 min"]})
 
 
 def test_percentile_interpolates():

tests/test_evaluation_assets.py

@@ -5,7 +5,7 @@ from pathlib import Path
 def test_demo_benchmark_is_multilayer_and_auditable():
     path = Path("evals/demo_benchmark.json")
     data = json.loads(path.read_text(encoding="utf-8"))
-    assert data["version"] == "2.0"
+    assert data["version"] == "2.0.1"
     assert len(data["qa_cases"]) >= 9
     assert len(data["planner_cases"]) >= 10
     assert len(data["overview_cases"]) >= 2
@@ -49,7 +49,7 @@ def test_demo_evaluation_and_introspection_are_available_through_api():
     assert "/api/v1/session/{session_id}" in text
     assert "/api/v1/evaluation/saved/{session_id}" in text
     assert "/api/v1/evaluation/saved/{session_id}/{level}" in text
-    assert 'version="2.0.0"' in text
+    assert 'version="2.0.1"' in text
 
 
 def test_v15_evaluation_cache_and_incremental_deep_are_present():

tests/test_ui_copy.py

@@ -31,7 +31,7 @@ def test_ui_exposes_layered_evaluation_and_diagnostics():
         assert label in text
     assert '["Quick", "Standard", "Deep"]' in text
     assert "Diagnostic findings" in text
-    assert "Quality gates affecting the grade" in text
+    assert "Diagnostic findings" in text
 
 
 def test_architecture_api_tab_is_interactive_and_live():
@@ -48,13 +48,13 @@ def test_ui_has_quota_safe_evaluation_controls_and_score_card_spacing():
     text = Path("src/ragforge/ui.py").read_text(encoding="utf-8")
     assert "Quota-safe pacing" in text
     assert "Target Gemini requests per minute" in text
-    assert "Evaluation score card" in text
-    assert "Evaluation scorecard" not in text
+    assert "Run an evaluation to see a summary" in text
+    assert "Evaluation score card" not in text
 
 
 def test_architecture_snapshot_returns_complete_runtime_payload():
     text = Path("src/ragforge/ui.py").read_text(encoding="utf-8")
-    assert '"ragforge_version": "2.0.0"' in text
+    assert '"ragforge_version": "2.0.1"' in text
     assert "return sid, runtime, curl, runtime_json" in text
     assert "curl = f\ndef _eval_frame" not in text
 

tests/test_v16_features.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 def test_v16_benchmark_has_hard_mode_and_insight_plans():
     data = json.loads(Path("evals/demo_benchmark.json").read_text(encoding="utf-8"))
-    assert data["version"] == "2.0"
+    assert data["version"] == "2.0.1"
     assert len(data.get("hard_mode_cases", [])) >= 8
     insight = [c for c in data["planner_cases"] if c.get("task") == "insight_synthesis"]
     assert insight

tests/test_v19_features.py

@@ -112,7 +112,7 @@ def test_v19_evaluation_contains_scale_stress_compression_and_readiness():
     assert '"evidence_compression_ablation": compression_rows' in text
     assert '"release_readiness": readiness_rows' in text
     assert '"scale_stress": scale_stress_rows' in text
-    assert "v1.9 adaptive budget" in text
+    assert "Adaptive budget" in text
 
 
 def test_v19_api_and_ui_surface_operational_diagnostics_and_new_eval_tabs():
@@ -121,7 +121,7 @@ def test_v19_api_and_ui_surface_operational_diagnostics_and_new_eval_tabs():
     assert "/api/v1/session/{session_id}/diagnostics" in api
     assert 'with gr.Tab("Evidence compression")' in ui
     assert 'with gr.Tab("Scale stress")' in ui
-    assert 'with gr.Tab("Release readiness")' in ui
+    assert 'with gr.Tab("Acceptance checks")' in ui
     assert "Adaptive retrieval depth" in ui
     assert "Focused evidence sentence compression" in ui
 

tests/test_v20_final.py

@@ -4,19 +4,19 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 
 
-def test_v20_versions_and_final_release_assets_are_aligned():
-    assert 'version = "2.0.0"' in (ROOT / "pyproject.toml").read_text(encoding="utf-8")
-    assert '__version__ = "2.0.0"' in (ROOT / "src/ragforge/__init__.py").read_text(encoding="utf-8")
-    assert 'version="2.0.0"' in (ROOT / "src/ragforge/api.py").read_text(encoding="utf-8")
+def test_versions_and_release_assets_are_aligned():
+    assert 'version = "2.0.1"' in (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    assert '__version__ = "2.0.1"' in (ROOT / "src/ragforge/__init__.py").read_text(encoding="utf-8")
+    assert 'version="2.0.1"' in (ROOT / "src/ragforge/api.py").read_text(encoding="utf-8")
     benchmark = json.loads((ROOT / "evals/demo_benchmark.json").read_text(encoding="utf-8"))
-    assert benchmark["version"] == "2.0"
+    assert benchmark["version"] == "2.0.1"
     assert (ROOT / "CHANGELOG.md").is_file()
     assert (ROOT / "docs/FINAL_RESULTS.md").is_file()
     assert (ROOT / "docs/PORTFOLIO_GUIDE.md").is_file()
     assert (ROOT / "scripts/release_check.py").is_file()
 
 
-def test_v20_multihop_hard_case_uses_recommended_semantic_path():
+def test_multihop_hard_case_uses_recommended_semantic_path():
     benchmark = json.loads((ROOT / "evals/demo_benchmark.json").read_text(encoding="utf-8"))
     case = next(c for c in benchmark["hard_mode_cases"] if c["id"] == "hard_multihop_time_compare")
     assert case["mode"] == "Auto"
@@ -26,7 +26,13 @@ def test_v20_multihop_hard_case_uses_recommended_semantic_path():
     assert case["expected_strategy"] == "hierarchical"
 
 
-def test_v20_hard_mode_evaluator_honors_case_profile_and_plan_expectations():
+def test_source_localization_planner_case_accepts_two_reasonable_strategies():
+    benchmark = json.loads((ROOT / "evals/demo_benchmark.json").read_text(encoding="utf-8"))
+    case = next(c for c in benchmark["planner_cases"] if c["id"] == "plan_find_refund_file")
+    assert set(case["strategy_any"]) == {"semantic", "hierarchical"}
+
+
+def test_hard_mode_evaluator_honors_case_profile_and_plan_expectations():
     text = (ROOT / "src/ragforge/evaluation.py").read_text(encoding="utf-8")
     assert 'case_mode = str(case.get("mode") or "Documents")' in text
     assert 'case_profile = str(case.get("profile") or "Fast")' in text
@@ -35,23 +41,25 @@ def test_v20_hard_mode_evaluator_honors_case_profile_and_plan_expectations():
     assert '"evaluation_profile": cfg.profile' in text
 
 
-def test_v20_ui_is_productized_and_keeps_short_dash_constraint():
+def test_ui_reads_like_a_product_not_a_release_dashboard():
     text = (ROOT / "src/ragforge/ui.py").read_text(encoding="utf-8")
-    assert "Final portfolio release" in text
+    assert '<div class="hero-title">RAGForge</div>' in text
+    assert "Final portfolio release" not in text
+    assert "Pre-final readiness" not in text
+    assert "Verified v1.9 grade" not in text
+    assert "[D#] [T#] [W#] citations" not in text
+    assert "Acceptance checks" in text
+    assert "The results describe this demo benchmark only; they are not general accuracy claims." in text
     assert 'with gr.Tab("Chat")' in text
-    assert "Evaluation lab" in text
-    assert "Verified answer accuracy" in text
-    assert "Release readiness" in text
-    assert "footer-note" in text
     assert "—" not in text
     assert "–" not in text
 
 
-def test_v20_readme_leads_with_product_and_measured_results_not_release_diary():
+def test_readme_leads_with_product_and_scoped_evaluation():
     text = (ROOT / "README.md").read_text(encoding="utf-8")
-    assert "Verified pre-final benchmark" in text
-    assert "Core capabilities" in text
-    assert "Recommended demo flow" in text
-    assert "Final project status" in text
-    assert "What is new in v1.9" not in text
+    assert text.count("# RAGForge") == 1
+    assert "final portfolio release" not in text.lower()
+    assert "Interpreting the benchmark" in text
+    assert "not for making claims about general enterprise performance" in text
+    assert "15 minutes" in text and "5 minutes" in text
     assert "CHANGELOG.md" in text