feat: Roast Review V5 Phase 1 - credibility leaks fixed

- Rebranded from 'production-grade' to 'production-shaped prototype'
- Fixed .gitignore invalid glob (removed 'indexes,eval}')
- ruff check src api tests passes (0 errors, E402 ignored for tests)
- Fixed B017 (broad pytest.raises) in test_comprehensive.py
- API startup: removed index loading from startup event (deferred to first query)
- Health check: VectorStore instantiation wrapped in try/except, no longer crashes on missing indices
- Docker: SECRET_KEY uses ${SECRET_KEY:?...} for fail-fast validation
- Added 'Known Limits' section to README (7 honest limitations)
- Fixed unused HTTPException import in api/main.py

163 tests passing (93 unit + 70 integration)

Author: DeryFerd

.gitignore

@@ -62,4 +62,3 @@ roast_review*.md
 
 # Stale files
 server.log
-"indexes,eval}"

README.md

@@ -1,6 +1,6 @@
 # Cost-Aware Agentic RAG
 
-Production-grade Agentic RAG system for SEC 10-K Financial Document Analysis with cost-aware model routing. Uses a trained ML classifier to route queries by complexity, hybrid retrieval with RRF fusion, cross-encoder reranking, and a LangGraph-based agentic loop with self-reflection.
+Production-shaped Agentic RAG prototype for SEC 10-K Financial Document Analysis with cost-aware model routing. Uses a trained ML classifier to route queries by complexity, hybrid retrieval with RRF fusion, cross-encoder reranking, and a LangGraph-based agentic loop with self-reflection.
 
 ## Architecture
 
@@ -392,6 +392,16 @@ curl -X POST http://localhost:8001/query/stream \
   -d '{"query": "What are Tesla'\''s main risk factors?"}'
 ```
 
+## Known Limits
+
+- **Cost model is approximate** — Token costs use per-million-token rates from public Ollama pricing. Actual costs may vary by deployment.
+- **Upload status is in-memory** — Server restart loses pending upload status. Production would use persistent queue.
+- **File-based auth** — Admin users and sessions stored in JSON files. Suitable for demo, not enterprise multi-tenant.
+- **Single-process retrieval** — No distributed search or horizontal scaling. ChromaDB and BM25 are local.
+- **Eval harness is offline** — Golden set has 20 entries. Online eval with production traffic not yet implemented.
+- **Agent loop is bounded** — Max 2 reflection iterations. No human-in-the-loop approval or tool budget enforcement.
+- **No persistent deployment** — Docker builds locally. No cloud deployment, load balancer, or auto-scaling.
+
 ## License
 
 MIT

api/main.py

@@ -4,9 +4,10 @@
 
 import logging
 import sys
+import time
 from pathlib import Path
 
-from fastapi import FastAPI, HTTPException, Request
+from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import HTMLResponse
 from fastapi.staticfiles import StaticFiles
@@ -32,9 +33,11 @@
 
 logger = logging.getLogger(__name__)
 
+_startup_time = time.perf_counter()
+
 app = FastAPI(
     title="Cost-Aware Agentic RAG",
-    description="Production-grade RAG for SEC 10-K Financial Analysis",
+    description="Production-shaped Agentic RAG prototype for SEC 10-K Financial Analysis",
     version="0.1.0",
 )
 
@@ -59,17 +62,13 @@
 
 @app.on_event("startup")
 async def startup_event():
-    """Initialize admin user, tracing, and load indices on startup."""
+    """Initialize admin user and tracing on startup.
+
+    Index loading is deferred to first query for fast startup.
+    """
     setup_tracing()
     init_admin()
-
-    try:
-        from src.retrieval.hybrid import HybridRetriever
-        retriever = HybridRetriever()
-        retriever.load_indices()
-        logger.info("Indices loaded successfully")
-    except Exception as e:
-        logger.warning(f"Could not load indices: {e}")
+    logger.info("Startup complete in %.1fs", time.perf_counter() - _startup_time)
 
     # FastAPI OTel middleware (if opentelemetry-instrumentation-fastapi is installed)
     try:
@@ -140,26 +139,26 @@ def cost_optimization_page(request: Request) -> HTMLResponse:
 # ── Health Check ─────────────────────────────────────────────────────
 @app.get("/health", response_model=HealthResponse)
 def health() -> HealthResponse:
+    doc_count = 0
+    if settings.raw_dir.exists():
+        for company_dir in settings.raw_dir.iterdir():
+            if company_dir.is_dir():
+                for year_dir in company_dir.iterdir():
+                    if year_dir.is_dir():
+                        for _f in year_dir.glob("*.txt"):
+                            doc_count += 1
+
+    chunk_count = 0
     try:
-        doc_count = 0
-        if settings.raw_dir.exists():
-            for company_dir in settings.raw_dir.iterdir():
-                if company_dir.is_dir():
-                    for year_dir in company_dir.iterdir():
-                        if year_dir.is_dir():
-                            for _f in year_dir.glob("*.txt"):
-                                doc_count += 1
-
         from src.retrieval.vector_store import VectorStore
         vs = VectorStore()
         chunk_count = vs.count()
+    except Exception:
+        pass
 
-        return HealthResponse(
-            status="ok",
-            document_count=doc_count,
-            chunk_count=chunk_count,
-            version="0.1.0",
-        )
-    except Exception as e:
-        logger.error(f"Health check failed: {e}")
-        raise HTTPException(status_code=503, detail=f"Service unavailable: {e}") from e
+    return HealthResponse(
+        status="ok",
+        document_count=doc_count,
+        chunk_count=chunk_count,
+        version="0.1.0",
+    )