fix demo mode query routing isolation

Route Streamlit demo queries through the in-process orchestrator to avoid localhost API startup races on Spaces, while preserving non-demo HTTP behavior. Add readiness polling for embedded FastAPI startup and test coverage for demo vs non-demo routing paths.

Made-with: Cursor

README.md

@@ -31,6 +31,7 @@ Citation-aware RAG system for ingesting documents and generating grounded answer
 ### Option 1 — Try online (no install)
 
 Open the [Hugging Face Spaces demo](https://huggingface.co/spaces/vampokala/doc-ingestion). Sample documents about RAG, vector databases, and BM25 are pre-loaded. Paste your OpenAI, Anthropic, or Gemini key in the sidebar.
+In hosted demo mode (`DOC_PROFILE=demo`), Streamlit executes queries in-process through the shared orchestrator so demo usage is not blocked by localhost API startup races.
 
 ---
 
@@ -79,6 +80,8 @@ PYTHONPATH=. streamlit run src/web/streamlit_app.py
 PYTHONPATH=. python -m src.query "What is RAG?"
 ```
 
+Note: non-demo local mode keeps the standard split architecture (Streamlit calls FastAPI over HTTP), so running both API and UI processes is still required.
+
 ---
 
 ## Features

spaces/README.md

@@ -27,6 +27,7 @@ A live demo of **Doc-Ingestion**, a citation-aware Retrieval-Augmented Generatio
 - **Uploads are disabled** — this demo runs on pre-ingested sample documents only.
 - **No persistence** — embeddings are stored in-memory and reset on each Space restart.
 - **Cloud LLM only** — Ollama (local model) is not available in this hosted environment.
+- **Demo query path** — Streamlit runs demo queries in-process via `RAGOrchestrator`; FastAPI is still started for health/metrics and API compatibility.
 
 ## Run locally with full features
 
@@ -45,6 +46,7 @@ docker compose -f docker/docker-compose.yml up
 ```
 
 Open http://localhost:8501 for the UI.
+For standard local development (non-demo), keep running FastAPI and Streamlit as separate processes.
 
 ## Source code
 

spaces/app.py

@@ -14,6 +14,8 @@ import threading
 import time
 from pathlib import Path
 
+import requests
+
 logging.basicConfig(level=logging.INFO)
 
 # Ensure repo root is importable regardless of where HF Spaces runs this.
@@ -45,11 +47,28 @@ def _start_api() -> None:
     uvicorn.run(fastapi_app, host="127.0.0.1", port=8000, log_level="warning")
 
 
+def _wait_for_api_ready(timeout_seconds: float = 20.0) -> bool:
+    """Poll the local health endpoint until API is ready or timeout elapses."""
+    deadline = time.time() + timeout_seconds
+    url = "http://127.0.0.1:8000/health"
+    while time.time() < deadline:
+        try:
+            resp = requests.get(url, timeout=1.5)
+            if resp.ok:
+                logging.info("FastAPI ready on %s", url)
+                return True
+        except Exception:
+            pass
+        time.sleep(0.5)
+    logging.warning("FastAPI did not become ready within %.1f seconds", timeout_seconds)
+    return False
+
+
 _api_thread = threading.Thread(target=_start_api, daemon=True)
 _api_thread.start()
 
-# Give the API a moment to bind before Streamlit renders its first page.
-time.sleep(3)
+# Wait for API readiness, but keep demo UI available even if API startup is slow.
+_wait_for_api_ready()
 
 # Hand off to the main Streamlit app.
 from src.web.streamlit_app import main  # noqa: E402

src/web/streamlit_app.py

@@ -6,6 +6,7 @@ import os
 
 import requests
 import streamlit as st
+from src.core.rag_orchestrator import QueryRequest, QueryResponse, RAGOrchestrator
 from src.utils.config import load_config, provider_api_key_env
 from src.web.ingestion_service import run_ingest, save_uploaded_files
 
@@ -34,6 +35,74 @@ _DEMO_QUESTIONS = [
 ]
 
 
+@st.cache_resource(show_spinner=False)
+def _get_demo_orchestrator() -> RAGOrchestrator:
+    """Build one orchestrator per Streamlit process for demo in-process querying."""
+    return RAGOrchestrator(load_config("config.yaml"))
+
+
+def _normalize_orchestrator_response(out: QueryResponse) -> dict:
+    retrieved = []
+    for item in out.retrieved:
+        legacy = item.to_legacy_dict()
+        retrieved.append(
+            {
+                "id": legacy["id"],
+                "score": float(legacy.get("score") or 0.0),
+                "source": str(legacy.get("source") or "hybrid"),
+                "confidence": float(legacy.get("confidence") or 0.0),
+                "metadata": dict(legacy.get("metadata") or {}),
+                "preview": (legacy.get("text") or "")[:240],
+            }
+        )
+
+    truthfulness = None
+    if out.truthfulness is not None:
+        truthfulness = {
+            "nli_faithfulness": out.truthfulness.nli_faithfulness,
+            "citation_groundedness": out.truthfulness.citation_groundedness,
+            "uncited_claims": out.truthfulness.uncited_claims,
+            "score": out.truthfulness.score,
+        }
+
+    return {
+        "query": out.query,
+        "provider": out.provider,
+        "model": out.model,
+        "answer": out.answer,
+        "processing_time_ms": out.processing_time_ms,
+        "cached": out.cached,
+        "validation_issues": out.validation_issues,
+        "citations": out.citations,
+        "retrieved": retrieved,
+        "truthfulness": truthfulness,
+    }
+
+
+def _run_query_in_demo_mode(payload: dict) -> dict:
+    """Run query through shared orchestrator instead of localhost HTTP API."""
+    orchestrator = _get_demo_orchestrator()
+    req = QueryRequest(
+        query_text=str(payload.get("query", "")),
+        top_k=int(payload.get("top_k", 5)),
+        use_llm=bool(payload.get("use_llm", True)),
+        use_rerank=bool(payload.get("use_rerank", True)),
+        stream=bool(payload.get("stream", False)),
+        provider=str(payload.get("provider") or "") or None,
+        model=str(payload.get("model") or "") or None,
+        provider_api_key=str(payload.get("provider_api_key") or "") or None,
+        include_citations=bool(payload.get("include_citations", True)),
+    )
+    out = orchestrator.run(req)
+    return _normalize_orchestrator_response(out)
+
+
+def _run_query_via_api(payload: dict, headers: dict) -> dict:
+    resp = requests.post(f"{API_BASE_URL}/query", json=payload, headers=headers, timeout=120)
+    resp.raise_for_status()
+    return resp.json()
+
+
 def _truthfulness_badge(score: float) -> str:
     """Return a coloured emoji label for a truthfulness score in [0, 1]."""
     if score >= 0.8:
@@ -212,18 +281,20 @@ def _render_query_tab() -> None:
             headers["X-API-Key"] = resolved_api_key
         with st.spinner("Running retrieval and generation..."):
             try:
-                resp = requests.post(f"{API_BASE_URL}/query", json=payload, headers=headers, timeout=120)
-                resp.raise_for_status()
-                data = resp.json()
-            except requests.HTTPError:
+                if _DEMO_MODE:
+                    data = _run_query_in_demo_mode(payload)
+                else:
+                    data = _run_query_via_api(payload, headers)
+            except requests.HTTPError as exc:
                 msg = "Request failed."
                 try:
-                    err = resp.json()
+                    err = exc.response.json() if exc.response is not None else {}
                     detail = err.get("detail")
                     if detail:
                         msg = f"Request failed: {detail}"
                 except Exception:
-                    msg = f"Request failed: {resp.status_code} {resp.reason}"
+                    if exc.response is not None:
+                        msg = f"Request failed: {exc.response.status_code} {exc.response.reason}"
                 st.error(msg)
                 return
             except Exception as exc:

tests/unit/test_streamlit_demo_routing.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import src.web.streamlit_app as streamlit_app
+
+
+class _DummyRetrieval:
+    def to_legacy_dict(self):
+        return {
+            "id": "chunk-1",
+            "score": 0.91,
+            "source": "hybrid",
+            "confidence": 0.88,
+            "metadata": {"title": "doc.md"},
+            "text": "Demo preview text",
+        }
+
+
+def test_run_query_in_demo_mode_uses_inprocess_orchestrator(monkeypatch):
+    captured = {}
+
+    class _FakeOrchestrator:
+        def run(self, req):
+            captured["provider"] = req.provider
+            captured["model"] = req.model
+            captured["provider_api_key"] = req.provider_api_key
+            return SimpleNamespace(
+                query=req.query_text,
+                provider=req.provider or "openai",
+                model=req.model or "gpt-4o-mini",
+                answer="demo answer",
+                processing_time_ms=12.3,
+                cached=False,
+                validation_issues=[],
+                citations=[{"chunk_id": "chunk-1", "resolved": True, "verification_score": 0.9}],
+                retrieved=[_DummyRetrieval()],
+                truthfulness=SimpleNamespace(
+                    nli_faithfulness=0.8,
+                    citation_groundedness=0.9,
+                    uncited_claims=0,
+                    score=0.85,
+                ),
+            )
+
+    monkeypatch.setattr(streamlit_app, "_get_demo_orchestrator", lambda: _FakeOrchestrator())
+
+    out = streamlit_app._run_query_in_demo_mode(
+        {
+            "query": "what is rag?",
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "provider_api_key": "provider-key",
+            "top_k": 5,
+            "include_citations": True,
+        }
+    )
+
+    assert captured["provider"] == "openai"
+    assert captured["model"] == "gpt-4o-mini"
+    assert captured["provider_api_key"] == "provider-key"
+    assert out["answer"] == "demo answer"
+    assert out["provider"] == "openai"
+    assert out["retrieved"][0]["id"] == "chunk-1"
+    assert out["truthfulness"]["score"] == 0.85
+
+
+def test_run_query_via_api_uses_http_post(monkeypatch):
+    captured = {}
+
+    class _Resp:
+        def raise_for_status(self):
+            return None
+
+        def json(self):
+            return {"answer": "ok"}
+
+    def _fake_post(url, json, headers, timeout):
+        captured["url"] = url
+        captured["json"] = json
+        captured["headers"] = headers
+        captured["timeout"] = timeout
+        return _Resp()
+
+    monkeypatch.setattr(streamlit_app.requests, "post", _fake_post)
+
+    payload = {"query": "hello"}
+    headers = {"Content-Type": "application/json", "X-API-Key": "k"}
+    out = streamlit_app._run_query_via_api(payload, headers)
+
+    assert out["answer"] == "ok"
+    assert captured["url"] == f"{streamlit_app.API_BASE_URL}/query"
+    assert captured["json"] == payload
+    assert captured["headers"] == headers
+    assert captured["timeout"] == 120