Enhance API and Streamlit UI with new timeout handling and telemetry adjustments

- Added configurable HTTP read timeout in Streamlit app, allowing users to set a maximum wait time for requests.
- Updated API to disable telemetry for Chroma to prevent errors with posthog capture.
- Introduced legacy query endpoint for backward compatibility with older clients.
- Updated dependencies in pyproject.toml and requirements.txt to include posthog with version constraints.
- Enhanced vector store initialization to disable telemetry and ensure proper client settings.
- Improved user feedback in the Streamlit UI regarding request timeouts and API connection status.

api/main.py

@@ -1,3 +1,8 @@
+import os
+
+# Before any route imports that touch Chroma: disable product telemetry (avoids posthog capture() errors in logs).
+os.environ.setdefault("ANONYMIZED_TELEMETRY", "FALSE")
+
 from fastapi import FastAPI
 
 from api.config import get_settings
@@ -11,6 +16,7 @@ app.include_router(audit.router)
 app.include_router(ingest.router)
 app.include_router(jobs.router)
 app.include_router(query.router)
+app.include_router(query.legacy_query_router)
 
 
 @app.on_event("startup")

api/routes/query.py

@@ -116,3 +116,12 @@ async def summarise_endpoint(payload: SummariseRequest) -> QueryResponse:
     except Exception as exc:
         raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)) from exc
     return response
+
+
+legacy_query_router = APIRouter(tags=["query"])
+
+
+@legacy_query_router.post("/query", response_model=QueryResponse)
+async def query_post_compat(payload: QueryRequest) -> QueryResponse:
+    """Same behavior as POST /query/ask; kept for older clients and docs that used POST /query."""
+    return await ask_endpoint(payload)

pyproject.toml

@@ -14,6 +14,8 @@ dependencies = [
     "langchain-anthropic==0.1.15",
     "langchain-ollama==0.1.3",
     "chromadb==0.5.0",
+    # Chroma 0.5 calls posthog.capture(distinct_id, event, props); posthog 6+ removed that API (breaks telemetry + spams stderr).
+    "posthog>=3.7.0,<4",
     "openai==1.30.1",
     "anthropic==0.28.1",
     "pydantic-settings==2.3.4",

rag/vector_store.py

@@ -2,10 +2,13 @@ from pathlib import Path
 from uuid import uuid4
 
 import chromadb
+from chromadb.config import Settings
 from langchain_chroma import Chroma
 from langchain_core.documents import Document
 from langchain_core.embeddings import Embeddings
 
+_CHROMA_CLIENT_SETTINGS = Settings(anonymized_telemetry=False)
+
 
 def get_vector_store(
     persist_directory: str,
@@ -17,6 +20,7 @@ def get_vector_store(
         collection_name=collection_name,
         embedding_function=embedding_function,
         persist_directory=persist_directory,
+        client_settings=_CHROMA_CLIENT_SETTINGS,
     )
 
 
@@ -28,12 +32,12 @@ def add_documents(vector_store: Chroma, chunks: list[Document]) -> list[str]:
 
 def list_collection_names(persist_directory: str) -> list[str]:
     Path(persist_directory).mkdir(parents=True, exist_ok=True)
-    client = chromadb.PersistentClient(path=persist_directory)
+    client = chromadb.PersistentClient(path=persist_directory, settings=_CHROMA_CLIENT_SETTINGS)
     return sorted(c.name for c in client.list_collections())
 
 
 def delete_collection(persist_directory: str, collection_name: str) -> None:
     Path(persist_directory).mkdir(parents=True, exist_ok=True)
-    client = chromadb.PersistentClient(path=persist_directory)
+    client = chromadb.PersistentClient(path=persist_directory, settings=_CHROMA_CLIENT_SETTINGS)
     client.delete_collection(name=collection_name)
 

requirements.txt

@@ -9,6 +9,7 @@ langchain-text-splitters==0.2.0
 langchain-anthropic==0.1.15
 langchain-ollama==0.1.3
 chromadb==0.5.0
+posthog>=3.7.0,<4
 openai==1.30.1
 anthropic==0.28.1
 pymupdf==1.24.3

streamlit_app.py

@@ -10,15 +10,44 @@ import httpx
 import streamlit as st
 
 DEFAULT_API_BASE = os.environ.get("DOC_AUDI_API_BASE", "http://127.0.0.1:8000")
-HTTP_TIMEOUT = httpx.Timeout(120.0, connect=10.0)
+
+
+def _http_read_timeout_seconds() -> float:
+    raw = os.environ.get("DOC_AUDI_HTTP_READ_TIMEOUT", "600")
+    try:
+        read_s = float(raw)
+    except ValueError:
+        read_s = 600.0
+    return max(60.0, min(read_s, 3600.0))
+
+
+def _http_timeout() -> httpx.Timeout:
+    """LLM + embeddings can exceed a few minutes on CPU or cold Ollama; Streamlit uses this, not Uvicorn."""
+    read_s = _http_read_timeout_seconds()
+    return httpx.Timeout(connect=20.0, read=read_s, write=120.0, pool=30.0)
+
+
+def _fmt_timeout_hint() -> str:
+    cap = int(_http_read_timeout_seconds())
+    return (
+        f"The UI stops waiting after **{cap}s** per request (set **DOC_AUDI_HTTP_READ_TIMEOUT** to raise it, max 3600). "
+        "Ensure `ollama serve` is running; cold models or CPU inference can exceed a few minutes."
+    )
 
 
 def _api_base() -> str:
-    return (st.session_state.get("api_base") or DEFAULT_API_BASE).rstrip("/")
+    """Resolve API base URL. Whitespace-only sidebar input must not win over default (breaks httpx)."""
+    raw = st.session_state.get("api_base")
+    if raw is None:
+        return DEFAULT_API_BASE.rstrip("/")
+    s = str(raw).strip()
+    if not s:
+        return DEFAULT_API_BASE.rstrip("/")
+    return s.rstrip("/")
 
 
 def _client() -> httpx.Client:
-    return httpx.Client(base_url=_api_base(), timeout=HTTP_TIMEOUT)
+    return httpx.Client(base_url=_api_base(), timeout=_http_timeout())
 
 
 def _fmt_api_error(exc: httpx.HTTPStatusError) -> str:
@@ -42,6 +71,30 @@ def _fmt_api_error(exc: httpx.HTTPStatusError) -> str:
     return f"HTTP {exc.response.status_code}"
 
 
+def _post_query_ask(client: httpx.Client, *, question: str, collection_name: str) -> httpx.Response:
+    """Milestone 8 uses POST /query/ask; older servers only expose POST /query."""
+    body = {"question": question.strip(), "collection_name": collection_name}
+    r = client.post("/query/ask", json=body)
+    if r.status_code == 404:
+        r = client.post("/query", json=body)
+    return r
+
+
+def _get_audit_logs(client: httpx.Client, *, limit: int, offset: int) -> httpx.Response:
+    params = {"limit": limit, "offset": offset}
+    r = client.get("/audit/logs", params=params)
+    if r.status_code == 404:
+        r = client.get("/audit", params=params)
+    return r
+
+
+def _get_audit_event_detail(client: httpx.Client, event_id: str) -> httpx.Response:
+    r = client.get(f"/audit/logs/{event_id}")
+    if r.status_code == 404:
+        r = client.get(f"/audit/{event_id}")
+    return r
+
+
 def _health_check() -> tuple[bool, str]:
     try:
         with _client() as c:
@@ -51,6 +104,8 @@ def _health_check() -> tuple[bool, str]:
             return True, str(data)
     except httpx.ConnectError as e:
         return False, f"Cannot connect to {_api_base()}: {e}"
+    except httpx.TimeoutException as e:
+        return False, f"Timed out: {e}. {_fmt_timeout_hint()}"
     except httpx.HTTPStatusError as e:
         return False, _fmt_api_error(e)
     except Exception as e:
@@ -59,15 +114,25 @@ def _health_check() -> tuple[bool, str]:
 
 def main() -> None:
     st.set_page_config(page_title="doc-audi-ai", layout="wide")
-    st.title("doc-audi-ai")
-    st.caption("Ingest, query, and audit via the FastAPI backend.")
-
     if "api_base" not in st.session_state:
         st.session_state.api_base = DEFAULT_API_BASE
 
+    st.title("doc-audi-ai")
+    st.caption("Ingest, query, and audit via the FastAPI backend.")
+    st.caption(f"Requests go to: `{_api_base()}`")
+
     with st.sidebar:
         st.subheader("Backend")
-        st.text_input("API base URL", key="api_base")
+        st.text_input(
+            "API base URL",
+            key="api_base",
+            placeholder=DEFAULT_API_BASE,
+            help=f"Default: {DEFAULT_API_BASE}. Clear the field to use the default.",
+        )
+        st.caption(
+            f"Ask/Summarise wait up to **{int(_http_read_timeout_seconds())}s** per request "
+            "(env `DOC_AUDI_HTTP_READ_TIMEOUT`, range 60–3600)."
+        )
         if st.button("Test connection"):
             ok, msg = _health_check()
             if ok:
@@ -254,18 +319,36 @@ def main() -> None:
                 st.warning("Enter a question.")
             else:
                 try:
-                    with _client() as c:
-                        r = c.post("/query/ask", json={"question": question.strip(), "collection_name": q_col})
-                        r.raise_for_status()
-                        ans = r.json()
-                    st.success(ans.get("message", ""))
+                    with st.spinner(
+                        "Calling the API (embeddings + LLM can take several minutes on a slow machine; "
+                        "ensure Ollama is running). Timeout is controlled by DOC_AUDI_HTTP_READ_TIMEOUT…"
+                    ):
+                        with _client() as c:
+                            r = _post_query_ask(
+                                c,
+                                question=question,
+                                collection_name=q_col,
+                            )
+                            r.raise_for_status()
+                            ans = r.json()
+                    msg = ans.get("message") or ""
+                    st.success(msg if msg else "Request completed.")
                     if ans.get("answer"):
                         st.markdown("### Answer")
                         st.markdown(ans["answer"])
+                    else:
+                        st.warning(
+                            "The API returned no **answer** text. "
+                            "Check the collection has ingested chunks, LLM env, and expand **Raw response** below."
+                        )
                     src = ans.get("sources") or []
                     if src:
                         with st.expander(f"Sources ({len(src)})"):
                             st.json(src)
+                    else:
+                        st.caption("No sources in this response (empty retrieval or model returned nothing).")
+                    with st.expander("Raw response (debug)"):
+                        st.json(ans)
                 except httpx.HTTPStatusError as e:
                     st.error(_fmt_api_error(e))
                 except httpx.ConnectError as e:
@@ -282,22 +365,32 @@ def main() -> None:
                 body: dict[str, Any] = {"collection_name": s_col}
                 if focus.strip():
                     body["focus"] = focus.strip()
-                with _client() as c:
-                    r = c.post("/query/summarise", json=body)
-                    r.raise_for_status()
-                    ans = r.json()
-                st.success(ans.get("message", ""))
+                with st.spinner("Calling summarise (can take 1–2 minutes on a cold model)…"):
+                    with _client() as c:
+                        r = c.post("/query/summarise", json=body)
+                        r.raise_for_status()
+                        ans = r.json()
+                msg = ans.get("message") or ""
+                st.success(msg if msg else "Request completed.")
                 if ans.get("answer"):
                     st.markdown("### Summary")
                     st.markdown(ans["answer"])
+                else:
+                    st.warning("No summary text in the response; see **Raw response** below.")
                 src = ans.get("sources") or []
                 if src:
                     with st.expander(f"Sources ({len(src)})"):
                         st.json(src)
+                with st.expander("Raw response (debug)"):
+                    st.json(ans)
             except httpx.HTTPStatusError as e:
                 st.error(_fmt_api_error(e))
             except httpx.ConnectError as e:
                 st.error(f"Connection failed: {e}")
+            except httpx.ReadTimeout as e:
+                st.error(f"Read timed out: {e}\n\n{_fmt_timeout_hint()}")
+            except httpx.TimeoutException as e:
+                st.error(f"Request timed out: {e}\n\n{_fmt_timeout_hint()}")
             except Exception as e:
                 st.exception(e)
 
@@ -311,7 +404,11 @@ def main() -> None:
         if st.button("List audit events", key="btn_audit_list"):
             try:
                 with _client() as c:
-                    r = c.get("/audit/logs", params={"limit": int(a_limit), "offset": int(a_offset)})
+                    r = _get_audit_logs(
+                        c,
+                        limit=int(a_limit),
+                        offset=int(a_offset),
+                    )
                     r.raise_for_status()
                     payload = r.json()
                 events = payload.get("events", [])
@@ -340,7 +437,7 @@ def main() -> None:
         if st.button("Load detail", key="btn_audit_detail") and ev_id:
             try:
                 with _client() as c:
-                    r = c.get(f"/audit/logs/{ev_id}")
+                    r = _get_audit_event_detail(c, ev_id)
                     r.raise_for_status()
                     st.json(r.json())
             except httpx.HTTPStatusError as e:

uv.lock

@@ -585,6 +585,7 @@ dependencies = [
     { name = "langchain-text-splitters" },
     { name = "onnxruntime", marker = "platform_machine == 'x86_64' and sys_platform == 'darwin'" },
     { name = "openai" },
+    { name = "posthog" },
     { name = "pydantic-settings" },
     { name = "pymupdf" },
     { name = "python-multipart" },
@@ -611,6 +612,7 @@ requires-dist = [
     { name = "langchain-text-splitters", specifier = "==0.2.0" },
     { name = "onnxruntime", marker = "platform_machine == 'x86_64' and sys_platform == 'darwin'", specifier = "==1.23.2" },
     { name = "openai", specifier = "==1.30.1" },
+    { name = "posthog", specifier = ">=3.7.0,<4" },
     { name = "pydantic-settings", specifier = "==2.3.4" },
     { name = "pymupdf", specifier = "==1.24.3" },
     { name = "python-multipart", specifier = "==0.0.9" },
@@ -1655,6 +1657,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a0/0f/59204bf136d1201f8d7884cfbaf7498c5b4674e87a4c693f9bde63741ce1/mmh3-5.2.1-cp314-cp314t-win_arm64.whl", hash = "sha256:dfd51b4c56b673dfbc43d7d27ef857dd91124801e2806c69bb45585ce0fa019b", size = 40391, upload-time = "2026-03-05T15:55:56.697Z" },
 ]
 
+[[package]]
+name = "monotonic"
+version = "1.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ea/ca/8e91948b782ddfbd194f323e7e7d9ba12e5877addf04fb2bf8fca38e86ac/monotonic-1.6.tar.gz", hash = "sha256:3a55207bcfed53ddd5c5bae174524062935efed17792e9de2ad0205ce9ad63f7", size = 7615, upload-time = "2021-08-11T14:37:28.79Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/67/7e8406a29b6c45be7af7740456f7f37025f0506ae2e05fb9009a53946860/monotonic-1.6-py2.py3-none-any.whl", hash = "sha256:68687e19a14f11f26d140dd5c86f3dba4bf5df58003000ed467e0e2a69bca96c", size = 8154, upload-time = "2021-04-09T21:58:05.122Z" },
+]
+
 [[package]]
 name = "mpmath"
 version = "1.3.0"
@@ -1869,7 +1880,7 @@ name = "nvidia-cudnn-cu12"
 version = "8.9.2.26"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ff/74/a2e2be7fb83aaedec84f391f082cf765dfb635e7caa9b49065f73e4835d8/nvidia_cudnn_cu12-8.9.2.26-py3-none-manylinux1_x86_64.whl", hash = "sha256:5ccb288774fdfb07a7e7025ffec286971c06d8d7b4fb162525334616d7629ff9", size = 731725872, upload-time = "2023-06-01T19:24:57.328Z" },
@@ -1896,9 +1907,9 @@ name = "nvidia-cusolver-cu12"
 version = "11.4.5.107"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
-    { name = "nvidia-cusparse-cu12" },
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-cusparse-cu12", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-nvjitlink-cu12", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/bc/1d/8de1e5c67099015c834315e333911273a8c6aaba78923dd1d1e25fc5f217/nvidia_cusolver_cu12-11.4.5.107-py3-none-manylinux1_x86_64.whl", hash = "sha256:8a7ec542f0412294b15072fa7dab71d31334014a69f953004ea7a118206fe0dd", size = 124161928, upload-time = "2023-04-19T15:51:25.781Z" },
@@ -1909,7 +1920,7 @@ name = "nvidia-cusparse-cu12"
 version = "12.1.0.106"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-nvjitlink-cu12", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/65/5b/cfaeebf25cd9fdec14338ccb16f6b2c4c7fa9163aefcf057d86b9cc248bb/nvidia_cusparse_cu12-12.1.0.106-py3-none-manylinux1_x86_64.whl", hash = "sha256:f3b50f42cf363f86ab21f720998517a659a48131e8d538dc02f8768237bd884c", size = 195958278, upload-time = "2023-04-19T15:51:49.939Z" },
@@ -2378,17 +2389,19 @@ wheels = [
 
 [[package]]
 name = "posthog"
-version = "7.13.2"
+version = "3.25.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "backoff" },
     { name = "distro" },
+    { name = "monotonic" },
+    { name = "python-dateutil" },
     { name = "requests" },
-    { name = "typing-extensions" },
+    { name = "six" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/77/54/9c117beaa96519077cae355263712d705e560e8ee7ca4a35373438d1f4d2/posthog-7.13.2.tar.gz", hash = "sha256:a9fc322518bc7f42e24501a0df1072aa60bad6fba759cbe388d167b7e054b052", size = 195555, upload-time = "2026-04-30T09:01:26.08Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/85/a9/ec3bbc23b6f3c23c52e0b5795b1357cca74aa5cfb254213f1e471fef9b4d/posthog-3.25.0.tar.gz", hash = "sha256:9168f3e7a0a5571b6b1065c41b3c171fbc68bfe72c3ac0bfd6e3d2fcdb7df2ca", size = 75968, upload-time = "2025-04-15T21:15:45.552Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e9/8b/ec789af64ef3d85816a5c4ac8fe1e3c74d6e3bb9675c1325e3b1de4ddb14/posthog-7.13.2-py3-none-any.whl", hash = "sha256:e8ea9a7fa740b453533a76c0f3300b16120a3c27c19ab417cf0e69bb8c210fb6", size = 229762, upload-time = "2026-04-30T09:01:24.144Z" },
+    { url = "https://files.pythonhosted.org/packages/54/e2/c158366e621562ef224f132e75c1d1c1fce6b078a19f7d8060451a12d4b9/posthog-3.25.0-py2.py3-none-any.whl", hash = "sha256:85db78c13d1ecb11aed06fad53759c4e8fb3633442c2f3d0336bc0ce8a585d30", size = 89115, upload-time = "2025-04-15T21:15:43.934Z" },
 ]
 
 [[package]]