TraceRAG backend + demo graphs

.dockerignore

@@ -0,0 +1,23 @@
+# Keep the image lean — but DO ship graphs/ (the read-only demo data).
+__pycache__/
+**/__pycache__/
+*.pyc
+.env
+.env.*
+.venv/
+venv/
+# scratch / local-only DBs (the demo graphs live in graphs/ and are kept)
+memory.lbug
+memory.lbug.*
+_*.lbug
+*.lbug.wal
+*.lbug-shm
+# debug + result artifacts
+_*.out.txt
+results*.csv
+backups/
+.pytest_cache/
+# offline ingestion inputs — not needed by the running server (114 MB CSV etc.)
+datasets/
+Dockerfile
+.dockerignore

.env.example

@@ -0,0 +1,16 @@
+# Copy to .env and fill in. The real .env is gitignored.
+OPENROUTER_API_KEY=sk-or-v1-your_key_here
+
+# Optional:
+# OPENROUTER_MODEL=anthropic/claude-3-haiku
+# OPENROUTER_MODEL=google/gemini-flash-1.5
+
+# Neon Postgres (chat history + trace logs). Distinct from the .lbug RAG store.
+# Use the pooled connection string from the Neon dashboard; keep sslmode=require.
+APP_DATABASE_URL=postgresql://USER:PASSWORD@HOST/DB?sslmode=require
+
+# Sentry error tracking + performance monitoring (optional; unset = disabled).
+# DSN: Sentry → Project → Settings → Client Keys (DSN).
+# SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
+# SENTRY_ENVIRONMENT=production
+# SENTRY_TRACES_SAMPLE_RATE=0.1   # dev=1.0; scale down in prod to cap cost/overhead

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.lbug filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,37 @@
+# TraceRAG backend — Hugging Face Spaces (Docker SDK), single warm instance.
+FROM python:3.11-slim
+
+# Build deps for any source-built wheels (as root).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential && \
+    rm -rf /var/lib/apt/lists/*
+
+# HF Spaces convention: run as uid 1000 with a writable home.
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    HF_HOME=/home/user/.cache/huggingface \
+    TRACERAG_DB_PATH=/home/user/app/graphs/fastapi__fastapi.lbug
+WORKDIR /home/user/app
+
+# Python deps first so this layer caches across code changes.
+# Install CPU-only torch up front — otherwise sentence-transformers pulls the
+# CUDA build (~1 GB of GPU libs) that's useless on CPU-only Spaces.
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Pre-pull the runtime models so the first request isn't a cold download:
+# MiniLM embedder + spaCy small model. GLiNER is ingest-only, so it is skipped.
+RUN python -m spacy download en_core_web_sm && \
+    python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# App code + the baked-in, read-only demo graphs.
+COPY --chown=user . .
+
+EXPOSE 7860
+# One worker: the in-memory rate limiter + single-file LadybugDB require it.
+CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -1,11 +1,19 @@
 ---
-title: TraceRAG Backend
-emoji: 🐨
-colorFrom: green
+title: TraceRAG API
+emoji: 🐞
+colorFrom: indigo
 colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
-short_description: observability tool using knowledge graph RAG
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# TraceRAG — Backend API
+
+GraphRAG retrieval engine (FastAPI + LadybugDB). This Space serves the backend
+for the [TraceRAG Studio](https://github.com/Kcodess2807/GraphOps-Studio) frontend.
+
+Runs as a single warm container (Docker SDK). The demo graphs are baked into the
+image; secrets (LLM keys, Postgres URL, Clerk) are supplied via Space **Settings → Secrets**.
+
+See `../DEPLOY.md` in the repo for the full deployment guide.

api.py

@@ -0,0 +1,487 @@
+"""FastAPI backend for the dashboard."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from dataclasses import asdict
+from pathlib import Path
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from slowapi.errors import RateLimitExceeded
+from slowapi import _rate_limit_exceeded_handler
+
+from tracerag import config
+from tracerag.db import TraceDB
+from tracerag.router import TraceRouter, shutdown_embed_executor
+from tracerag.integrations.langchain import format_page_content
+
+from auth import get_current_user
+from cache import LRUCache
+from database import init_db
+from ratelimit import limiter, LLM_RATE_LIMIT
+from routers import history
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("tracerag.api")
+
+# Error tracking + performance monitoring. No-op when SENTRY_DSN is unset, so
+# dev runs are unaffected. Initialized before the app is created so Sentry's
+# auto-enabled FastAPI/Starlette/asyncio/threading integrations hook in — the
+# asyncio + threading ones are what capture errors raised inside our async
+# routes and the embed ThreadPoolExecutor (they re-raise via future.result()).
+if config.SENTRY_ENABLED:
+    import sentry_sdk
+
+    sentry_sdk.init(
+        dsn=config.SENTRY_DSN,
+        environment=config.SENTRY_ENVIRONMENT,
+        traces_sample_rate=config.SENTRY_TRACES_SAMPLE_RATE,
+        send_default_pii=False,  # don't ship request bodies / auth headers to Sentry
+    )
+    logger.info(
+        "Sentry enabled (env=%s, traces_sample_rate=%.2f)",
+        config.SENTRY_ENVIRONMENT, config.SENTRY_TRACES_SAMPLE_RATE,
+    )
+
+_state: dict = {}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Startup: open the DB + warm models. Shutdown: drain pools, flush to disk."""
+    # ---- startup --------------------------------------------------------------
+    db = TraceDB(config.DB_PATH)
+    db.init_schema()
+    _state["db"] = db
+    _state["db_path"] = str(config.DB_PATH)
+    _state["router"] = TraceRouter(db)
+
+    # Cold-boot warmup: pull model weights into RAM and spin up the embed-executor
+    # threads + spaCy pipeline, so the first real UI query skips the cold-start
+    # latency spike. Runs off the event loop and never blocks boot on failure.
+    try:
+        await asyncio.to_thread(_state["router"].warm)
+        logger.info("Warmup complete (embedder + executor threads + spaCy primed).")
+    except Exception as exc:  # noqa: BLE001 — warmup is best-effort
+        logger.warning("Router warmup skipped (%s).", exc)
+
+    # history is optional; api still boots without it
+    try:
+        init_db()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Postgres history disabled (%s).", exc)
+
+    logger.info("TraceRAG STUDIO API ready (db=%s)", config.DB_PATH)
+    try:
+        yield
+    finally:
+        # ---- graceful shutdown ------------------------------------------------
+        # Close BOTH the original and the currently-active DB: a graph hot-swap
+        # replaces _state["db"] with a new TraceDB, so the active one would
+        # otherwise leak its pooled connections. close() drains every leased
+        # connection and lets LadybugDB flush its WAL to disk (idempotent, so
+        # closing an already-swapped-out handle is a safe no-op).
+        for handle in {db, _state.get("db")}:  # set dedupes when no swap happened
+            if handle is None:
+                continue
+            try:
+                handle.close()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("DB close failed during shutdown: %s", exc)
+        # Join the embed executor's worker threads (let in-flight encodes finish).
+        try:
+            shutdown_embed_executor(wait=True)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Embed executor shutdown failed: %s", exc)
+        logger.info("TraceRAG shutdown complete (pools drained, flushed to disk).")
+
+
+app = FastAPI(title="TraceRAG STUDIO API", version="0.1.0", lifespan=lifespan)
+
+# Rate limiting: slowapi reads the limiter off app.state, and the handler turns
+# the library's RateLimitExceeded into a clean HTTP 429 (+ Retry-After header).
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+app.include_router(history.router)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=config.CORS_ORIGINS,  # "*" by default; lock to the frontend in prod
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+class TraceRequest(BaseModel):
+    query: str
+    top_k: int | None = None
+    session_id: str | None = None  # set -> persist this execution
+
+
+class SubgraphRequest(BaseModel):
+    node_ids: list[str]
+
+
+@app.post("/api/trace")
+async def trace(
+    req: TraceRequest,
+    user_id: str = Depends(get_current_user),  # require a valid token
+) -> dict:
+    """Run the router and return the full trace for visualization."""
+    router: TraceRouter = _state["router"]
+    # aroute offloads the blocking hybrid retrieval (DB pool + embed pool) off
+    # the event loop, so concurrent requests no longer serialize on one thread.
+    response = await router.aroute(req.query, top_k=req.top_k or config.TOP_K_VECTOR)
+    payload = asdict(response)
+    # rendered context the generation model would receive
+    for node, result in zip(response.results, payload["results"]):
+        result["page_content"] = format_page_content(node)
+    payload["context"] = router.build_context(response.results)
+    if req.session_id:
+        # Ownership check (write-side IDOR): only persist into a session that
+        # belongs to the authenticated user. Unknown session → 404; someone
+        # else's session → 403. A query with no session_id stays anonymous.
+        # Postgres calls are blocking → run them off the loop too.
+        owner = await asyncio.to_thread(history.session_owner, req.session_id)
+        if owner is None:
+            raise HTTPException(status_code=404, detail="session not found")
+        if owner != user_id:
+            raise HTTPException(status_code=403, detail="not your session")
+        payload["trace_id"] = await asyncio.to_thread(
+            history.persist_trace,
+            session_id=req.session_id,
+            query=req.query,
+            execution_plan=payload["trace_log"],
+            graph_payload=payload["results"],
+        )
+    return payload
+
+
+@app.post("/api/subgraph")
+async def subgraph(req: SubgraphRequest) -> dict:
+    """Requested nodes plus their 1-hop neighbors and edges."""
+    db: TraceDB = _state["db"]
+    # blocking DB read -> offload so the loop stays free under concurrency
+    return await asyncio.to_thread(db.subgraph, req.node_ids)
+
+
+class SummarizeRequest(BaseModel):
+    key: str           # cache key (doc id / node id)
+    text: str
+
+
+# bounded so a long-running server can't leak memory; LRU evicts cold snippets
+_SUMMARY_CACHE: LRUCache[str, str] = LRUCache(capacity=512)
+
+
+@app.post("/api/summarize")
+@limiter.limit(LLM_RATE_LIMIT)  # per-user cap; needs the `request` param below
+def summarize(
+    request: Request,  # required by slowapi to read the rate-limit key
+    req: SummarizeRequest,
+    _user: str = Depends(get_current_user),  # require a valid token (LLM = billed)
+) -> dict:
+    """One-sentence LLM summary of a node's snippet, cached by key."""
+    key = req.key or req.text[:64]
+    cached = _SUMMARY_CACHE.get(key)
+    if cached is not None:
+        return {"summary": cached, "cached": True}
+    text = (req.text or "").strip()
+    if not text:
+        return {"summary": "", "cached": False}
+    try:
+        client = _state.get("llm")
+        if client is None:
+            from tracerag.llm import make_client
+
+            client = make_client()
+            _state["llm"] = client
+        resp = client.chat.completions.create(
+            model=config.OPENROUTER_MODEL,
+            messages=[{
+                "role": "user",
+                "content": (
+                    "Summarize this engineering note in one concise sentence "
+                    "(max 25 words): what changed and why. Reply with only the "
+                    "sentence.\n\n" + text
+                ),
+            }],
+            temperature=0,
+        )
+        summary = (resp.choices[0].message.content or "").strip()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("summarize failed for %s: %s", key, exc)
+        return {"summary": "", "cached": False, "error": str(exc)}
+    _SUMMARY_CACHE.set(key, summary)
+    return {"summary": summary, "cached": False}
+
+
+# swap the active .lbug without restarting; router models stay warm
+def _graphs_dir() -> Path:
+    return config.PROJECT_ROOT / "graphs"
+
+
+def _graph_label(path: Path) -> str:
+    stem = path.stem
+    if path.resolve() == config.DB_PATH.resolve():
+        return f"{stem} (default)"
+    return stem.replace("__", "/")  # pallets__flask -> pallets/flask
+
+
+def discover_graphs() -> list[Path]:
+    """Selectable .lbug files: the configured default plus graphs/*."""
+    paths: list[Path] = []
+    if config.DB_PATH.exists():
+        paths.append(config.DB_PATH)
+    gdir = _graphs_dir()
+    if gdir.exists():
+        paths.extend(sorted(gdir.glob("*.lbug")))
+    seen: set[Path] = set()
+    out: list[Path] = []
+    for p in paths:
+        rp = p.resolve()
+        if rp not in seen:
+            seen.add(rp)
+            out.append(p)
+    return out
+
+
+class SwitchGraphRequest(BaseModel):
+    id: str  # the graph's file name
+
+
+@app.get("/api/graphs")
+def list_graphs() -> dict:
+    active = _state.get("db_path")
+    active_rp = Path(active).resolve() if active else None
+    graphs = [
+        {
+            "id": p.name,
+            "label": _graph_label(p),
+            "active": active_rp is not None and p.resolve() == active_rp,
+        }
+        for p in discover_graphs()
+    ]
+    return {"graphs": graphs, "active": Path(active).name if active else None}
+
+
+@app.post("/api/graphs/switch")
+def switch_graph(req: SwitchGraphRequest) -> dict:
+    """Hot-swap the active graph; id must be one of the discovered files."""
+    target = next((p for p in discover_graphs() if p.name == req.id), None)
+    if target is None:
+        raise HTTPException(status_code=404, detail=f"unknown graph: {req.id}")
+
+    old = _state.get("db")
+    new_db = TraceDB(target)
+    new_db.init_schema()
+    # re-point router at the new connection, keep warm models
+    _state["db"] = new_db
+    _state["db_path"] = str(target)
+    _state["router"].db = new_db
+    _SUMMARY_CACHE.clear()  # snippets differ per graph
+    if old is not None and old is not new_db:
+        try:
+            old.close()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("closing previous graph failed: %s", exc)
+
+    logger.info("Switched active graph -> %s", target)
+    return {
+        "active": target.name,
+        "label": _graph_label(target),
+        "nodes": new_db.count_nodes(),
+    }
+
+
+# per-entity-type question templates
+_SUGGESTION_TEMPLATES: dict[str, str] = {
+    "Person": "What did {label} work on?",
+    "Team": "What does {label} own?",
+    "Service": "What depends on {label}?",
+    "Library": "What changed in {label}?",
+    "Tool": "What is {label} used for?",
+    "PR": "What is related to {label}?",
+    "Ticket": "What is linked to {label}?",
+}
+_SUGGESTION_DEFAULT = "What is related to {label}?"
+
+
+@app.get("/api/suggestions")
+def suggestions(limit: int = 5) -> dict:
+    """Example questions built from the active graph's hub entities."""
+    db: TraceDB = _state["db"]
+    try:
+        hubs = db.top_entities(limit=limit * 4)  # over-fetch, then diversify
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("top_entities failed: %s", exc)
+        return {"suggestions": []}
+
+    out: list[dict] = []
+    seen_types: dict[str, int] = {}
+    # one question per type, in degree order
+    for ent in hubs:
+        etype = ent.get("type") or ""
+        label = (ent.get("label") or "").strip()
+        if not label or seen_types.get(etype, 0) >= 1:
+            continue
+        tmpl = _SUGGESTION_TEMPLATES.get(etype, _SUGGESTION_DEFAULT)
+        out.append({"query": tmpl.format(label=label), "entity": label, "type": etype})
+        seen_types[etype] = seen_types.get(etype, 0) + 1
+        if len(out) >= limit:
+            break
+    # backfill by degree if we still have room
+    if len(out) < limit:
+        used = {s["query"] for s in out}
+        for ent in hubs:
+            label = (ent.get("label") or "").strip()
+            if not label:
+                continue
+            tmpl = _SUGGESTION_TEMPLATES.get(ent.get("type") or "", _SUGGESTION_DEFAULT)
+            q = tmpl.format(label=label)
+            if q in used:
+                continue
+            out.append({"query": q, "entity": label, "type": ent.get("type") or ""})
+            used.add(q)
+            if len(out) >= limit:
+                break
+    return {"suggestions": out}
+
+
+class AnswerRequest(BaseModel):
+    query: str
+    context: str
+
+
+# bounded LRU shared by the blocking and streaming answer endpoints below
+_ANSWER_CACHE: LRUCache[str, str] = LRUCache(capacity=512)
+
+
+def _answer_key(query: str, context: str) -> str:
+    return f"{query}\n#{hash(context)}"
+
+
+def _answer_prompt(query: str, context: str) -> str:
+    """Grounded-answer prompt shared by the blocking and streaming endpoints."""
+    return (
+        "You are answering a teammate's question about an engineering "
+        "knowledge graph. Use ONLY the context below. Answer in 2-3 "
+        "plain sentences a non-expert can follow, naming the specific "
+        "PRs / people / components involved. If the context does not "
+        "contain the answer, say so plainly rather than guessing.\n\n"
+        f"Question: {query}\n\nContext:\n{context}"
+    )
+
+
+def _answer_client():
+    """Lazily build and cache the OpenRouter client."""
+    client = _state.get("llm")
+    if client is None:
+        from tracerag.llm import make_client
+
+        client = make_client()
+        _state["llm"] = client
+    return client
+
+
+@app.post("/api/answer")
+@limiter.limit(LLM_RATE_LIMIT)  # per-user cap; needs the `request` param below
+def answer(
+    request: Request,  # required by slowapi to read the rate-limit key
+    req: AnswerRequest,
+    _user: str = Depends(get_current_user),  # require a valid token (LLM = billed)
+) -> dict:
+    """Plain-language answer grounded in the retrieved context, cached per (query, context)."""
+    key = _answer_key(req.query, req.context)
+    cached = _ANSWER_CACHE.get(key)
+    if cached is not None:
+        return {"answer": cached, "cached": True}
+    context = (req.context or "").strip()
+    if not context:
+        return {"answer": "No supporting context was retrieved for this query.",
+                "cached": False}
+    try:
+        resp = _answer_client().chat.completions.create(
+            model=config.OPENROUTER_MODEL,
+            messages=[{"role": "user", "content": _answer_prompt(req.query, context)}],
+            temperature=0,
+        )
+        text = (resp.choices[0].message.content or "").strip()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("answer failed: %s", exc)
+        return {"answer": "", "cached": False, "error": str(exc)}
+    _ANSWER_CACHE.set(key, text)
+    return {"answer": text, "cached": False}
+
+
+@app.post("/api/answer/stream")
+@limiter.limit(LLM_RATE_LIMIT)  # same per-user cap — the streaming twin hits the
+                               # same billing API, so it must be capped too
+def answer_stream(
+    request: Request,  # required by slowapi to read the rate-limit key
+    req: AnswerRequest,
+    _user: str = Depends(get_current_user),  # require a valid token (LLM = billed)
+) -> StreamingResponse:
+    """Same answer as /api/answer, streamed token-by-token as plain UTF-8 chunks."""
+
+    def gen():
+        key = _answer_key(req.query, req.context)
+        cached = _ANSWER_CACHE.get(key)
+        if cached is not None:
+            yield cached
+            return
+        context = (req.context or "").strip()
+        if not context:
+            yield "No supporting context was retrieved for this query."
+            return
+        parts: list[str] = []
+        try:
+            stream = _answer_client().chat.completions.create(
+                model=config.OPENROUTER_MODEL,
+                messages=[{"role": "user", "content": _answer_prompt(req.query, context)}],
+                temperature=0,
+                stream=True,
+            )
+            for chunk in stream:
+                # guard every level; providers differ
+                delta = ""
+                try:
+                    delta = chunk.choices[0].delta.content or ""
+                except (AttributeError, IndexError):
+                    delta = ""
+                if delta:
+                    parts.append(delta)
+                    yield delta
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("answer stream failed: %s", exc)
+            if not parts:
+                yield "Sorry — the answer could not be generated right now."
+            return
+        full = "".join(parts).strip()
+        if full:
+            _ANSWER_CACHE.set(key, full)
+
+    # no-store + disable proxy buffering so chunks flush immediately
+    return StreamingResponse(
+        gen(),
+        media_type="text/plain; charset=utf-8",
+        headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+    )
+
+
+@app.get("/api/health")
+def health() -> dict:
+    db: TraceDB = _state["db"]
+    return {"status": "ok", "nodes": db.count_nodes()}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run("api:app", host="127.0.0.1", port=8000, reload=True)

auth.py

@@ -0,0 +1,180 @@
+"""Clerk session-token verification for FastAPI (networkless JWT verification).
+
+Clerk issues short-lived RS256 JWTs. RS256 is *asymmetric*: Clerk signs with a
+private key it never shares, and publishes the matching PUBLIC key at a JWKS
+(JSON Web Key Set) endpoint. We fetch those public keys once, cache them, and
+verify each incoming token's signature locally — no network round-trip per
+request. If the signature + claims check out, the token's `sub` claim is a
+Clerk user id we can trust (it could not have been forged without Clerk's
+private key).
+
+Dev escape hatch: when CLERK_ISSUER is unset we skip verification entirely and
+return a fixed dev user id, so local development without Clerk env vars is never
+locked out. Configured => enforce; unconfigured => warn-and-allow.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import jwt
+from fastapi import Header, HTTPException, Request, status
+from jwt import PyJWKClient, PyJWKClientError
+
+from tracerag import config
+
+logger = logging.getLogger("tracerag.auth")
+
+# PyJWKClient fetches the JWKS once and caches the signing keys in-process,
+# only re-fetching when it sees a token signed by an unknown `kid` (key id) —
+# which is exactly how it transparently handles Clerk rotating its keys.
+# Built lazily as a singleton so we don't hit the network at import time.
+_jwk_client: PyJWKClient | None = None
+_warned_dev_bypass = False
+
+
+def _get_jwk_client() -> PyJWKClient:
+    global _jwk_client
+    if _jwk_client is None:
+        _jwk_client = PyJWKClient(config.CLERK_JWKS_URL, cache_keys=True)
+    return _jwk_client
+
+
+def _extract_bearer(authorization: str | None) -> str:
+    """Pull the raw JWT out of an `Authorization: Bearer <token>` header."""
+    if not authorization:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing Authorization header.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    # partition splits on the FIRST space: "Bearer" | " " | "<token>"
+    scheme, _, token = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authorization header must be 'Bearer <token>'.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return token
+
+
+def _verify_token(token: str) -> dict:
+    """Verify the signature and the standard claims; return the decoded payload.
+
+    Two distinct failure classes, surfaced differently:
+      - we couldn't resolve a signing key (JWKS unreachable / unknown kid)
+      - the token itself is bad (expired, wrong issuer, tampered signature)
+    """
+    # --- Step 1: find the PUBLIC key that matches this token's `kid` header. ---
+    # PyJWKClient reads the unverified header (just the kid, not the payload) and
+    # hands back the corresponding public key from Clerk's JWKS.
+    try:
+        signing_key = _get_jwk_client().get_signing_key_from_jwt(token)
+    except PyJWKClientError as exc:
+        # Couldn't fetch/match a key — a server/config problem, not a forged
+        # token. Log loudly; still answer 401 so we never leak internals.
+        logger.warning("JWKS key resolution failed: %s", exc)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not resolve token signing key.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    except jwt.DecodeError as exc:
+        # Header itself was malformed (not a real JWT).
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Malformed token: {exc}",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # --- Step 2: verify signature AND the registered claims in one call. ---
+    # jwt.decode() does ALL of the following atomically and raises if any fails:
+    #   * RS256 signature matches `signing_key`        -> token is authentic
+    #   * `exp` (expiry) is in the future              -> token still valid
+    #   * `nbf`/`iat` not in the future (with leeway)  -> token already active
+    #   * `iss` equals our Clerk instance              -> minted by OUR Clerk
+    #   * the `require` claims are all present          -> well-formed session
+    try:
+        claims = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["RS256"],          # PIN the algorithm — never accept
+                                           # 'none'/HS256, which would let an
+                                           # attacker self-sign a token.
+            issuer=config.CLERK_ISSUER,    # `iss` must equal our Clerk instance.
+            leeway=5,                      # tolerate ≤5s of clock skew on exp/nbf.
+            options={
+                "require": ["exp", "iat", "sub"],  # must be present or reject.
+                "verify_aud": False,       # Clerk session tokens carry no `aud`;
+                                           # we authorize via `azp` below instead.
+            },
+        )
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token expired.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    except jwt.InvalidTokenError as exc:
+        # Catch-all for bad signature, wrong issuer, missing required claim, etc.
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Invalid token: {exc}",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # --- Step 3: optional `azp` (authorized party) check. ---
+    # `azp` is the origin the token was minted for. Verifying it against an
+    # allow-list stops a token issued for some other site from being replayed
+    # against our API. Skipped entirely if CLERK_AUTHORIZED_PARTIES is unset.
+    if config.CLERK_AUTHORIZED_PARTIES:
+        azp = claims.get("azp")
+        if azp and azp not in config.CLERK_AUTHORIZED_PARTIES:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Token authorized-party (azp) is not allowed.",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+    return claims
+
+
+def get_current_user(
+    request: Request,
+    authorization: str | None = Header(default=None),
+) -> str:
+    """FastAPI dependency → the verified Clerk user id (`sub`).
+
+    Add `user_id: str = Depends(get_current_user)` to any route to (a) require a
+    valid token and (b) receive the trustworthy user id. Routes should rely on
+    THIS value, never on a client-supplied user_id — that's what closes IDOR.
+
+    Side effect: stashes the resolved id on `request.state.user_id`. This is the
+    bridge that lets slowapi's key_func rate-limit per USER — the key_func only
+    receives the Request, not this dependency's return value, but FastAPI
+    resolves dependencies BEFORE the rate-limit decorator runs, so by then
+    request.state.user_id is populated. See ratelimit.py.
+    """
+    user_id = _resolve_user_id(authorization)
+    request.state.user_id = user_id
+    return user_id
+
+
+def _resolve_user_id(authorization: str | None) -> str:
+    """Verify the token (or dev-bypass) and return the user id."""
+    # Dev-bypass: no Clerk configured → don't verify, return a fixed dev user so
+    # local testing isn't blocked. Warn once so it can't silently ship to prod.
+    if not config.CLERK_ENABLED:
+        global _warned_dev_bypass
+        if not _warned_dev_bypass:
+            logger.warning(
+                "CLERK_ISSUER unset — auth is in DEV-BYPASS mode; every request "
+                "runs as '%s'. Do NOT deploy without setting CLERK_ISSUER.",
+                config.DEV_USER_ID,
+            )
+            _warned_dev_bypass = True
+        return config.DEV_USER_ID
+
+    token = _extract_bearer(authorization)
+    claims = _verify_token(token)
+    return claims["sub"]  # the Clerk user id — safe to trust post-verification.

cache.py

@@ -0,0 +1,67 @@
+"""A tiny bounded LRU (Least-Recently-Used) cache backed by OrderedDict.
+
+Why not functools.lru_cache? These caches are SHARED between two endpoints (the
+blocking and the streaming answer handlers read *and* write the same store),
+they need an explicit `cached` flag in the HTTP response, and they must support
+a per-graph .clear() when the active graph is hot-swapped. A decorator gives you
+none of those. ~25 lines of OrderedDict buys all of it with O(1) get/set/evict
+and a hard memory ceiling, which is the whole point — the old plain-dict caches
+grew without bound and leaked memory on a long-running server.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Generic, Optional, TypeVar
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class LRUCache(Generic[K, V]):
+    """Fixed-capacity cache that evicts the least-recently-used entry first.
+
+    The eviction policy IS the OrderedDict's ordering: we keep the *oldest*
+    (least-recently-used) entry on the left and the *most-recently-used* on the
+    right. Every read or write moves the touched key to the right, so whatever
+    has drifted to the far left is, by definition, the coldest entry — and that's
+    exactly what we drop when we're over capacity.
+    """
+
+    def __init__(self, capacity: int = 256) -> None:
+        if capacity <= 0:
+            raise ValueError("LRUCache capacity must be positive")
+        self.capacity = capacity
+        self._store: "OrderedDict[K, V]" = OrderedDict()
+
+    def get(self, key: K) -> Optional[V]:
+        """Return the value (and mark it most-recently-used), or None on miss."""
+        if key not in self._store:
+            return None
+        # A successful read counts as "use": promote the key to the right end so
+        # it survives the next eviction. This is what makes it LRU and not FIFO.
+        self._store.move_to_end(key)
+        return self._store[key]
+
+    def __contains__(self, key: K) -> bool:
+        # Note: membership does NOT promote — only get()/set() count as a "use".
+        return key in self._store
+
+    def set(self, key: K, value: V) -> None:
+        """Insert/overwrite a value, then evict oldest entries past capacity."""
+        if key in self._store:
+            # Overwriting an existing key still counts as a use → promote it.
+            self._store.move_to_end(key)
+        self._store[key] = value
+        # Evict from the LEFT (oldest) until we're back within the ceiling.
+        # last=False pops the first-inserted / least-recently-used item; a normal
+        # popitem() would pop the newest, which is the opposite of what we want.
+        while len(self._store) > self.capacity:
+            self._store.popitem(last=False)
+
+    def clear(self) -> None:
+        """Drop everything — used when the active graph changes (snippets differ)."""
+        self._store.clear()
+
+    def __len__(self) -> int:
+        return len(self._store)

database.py

@@ -0,0 +1,54 @@
+"""SQLModel engine and session dependency for the Postgres history store."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Iterator
+from pathlib import Path
+
+from sqlmodel import Session, SQLModel, create_engine
+
+logger = logging.getLogger("tracerag.database")
+
+# load .env so APP_DATABASE_URL is available; no-op if absent
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv(Path(__file__).resolve().parent / ".env")
+except ImportError:  # pragma: no cover
+    pass
+
+_engine = None  # lazily created
+
+
+def get_engine():
+    """Return the process-wide SQLModel engine, creating it on first use."""
+    global _engine
+    if _engine is None:
+        url = os.getenv("APP_DATABASE_URL")
+        if not url:
+            raise RuntimeError(
+                "APP_DATABASE_URL is not set. Add your Neon connection string "
+                "(postgresql://USER:PASSWORD@HOST/DB?sslmode=require) to .env."
+            )
+        _engine = create_engine(url, echo=False, pool_pre_ping=True)
+    return _engine
+
+
+def init_db() -> None:
+    """Create the history tables if they don't exist (idempotent)."""
+    # import models so their tables register before create
+    from models import ChatSession, TraceLog, User  # noqa: F401
+    from sqlalchemy.orm import configure_mappers
+
+    # validate relationships at startup, not on first query
+    configure_mappers()
+    SQLModel.metadata.create_all(get_engine())
+    logger.info("Postgres history schema ready.")
+
+
+def get_session() -> Iterator[Session]:
+    """FastAPI dependency yielding a session, closed afterwards."""
+    with Session(get_engine()) as session:
+        yield session

graphs/apache__kafka.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eadcec16587cc7fb693d08c433b8ae5b23399b747d96a0081129fc16139d87a7
+size 4182016

graphs/encode__httpx.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:104ae0ce36ed1a5e8184bd0ee3e963ff93cdb20a88ec4dc91f2becea0e2ed4bc
+size 2469888

graphs/encode__starlette.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0e31168dacb81c2bdf01cd51c7a2e0d27526e6393c0a2682f4055545f0623ead
+size 2752512

graphs/encode__uvicorn.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e448cbece67fa179048a5024a6a60e43a61f6fbe4d4da9cc0c9044fe72b455e5
+size 1777664

graphs/fastapi__fastapi.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2118082f932d55bc68bc5628f8f04bb5c9c84af701e21904e625e3e692dfece8
+size 2351104

graphs/huggingface__transformers.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5a259f404ea050e140cb449af8d492ecaa66bf18cc37f958c6ce537fe59d08e0
+size 2301952

graphs/langchain-ai__langchain.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:93da5499622a6acfe0a3658f55621e6d2f2fb366adbfa1110a61c5cbe98a8ffd
+size 2023424

graphs/openai__openai-python.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:64edace5e78b359c308dbd4b8287c7f8b66f1db36aa428ae6b89152e75c75c59
+size 1404928

graphs/pallets__click.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2982d2ea449c3f47eaf810e59d23b36ae464b90028f9ce5cdd5d1241702e4d96
+size 1589248

graphs/pallets__flask.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6d4f77883333fc432ef92b22988c0aee0bb451e6eaa17e07796810a36f127644
+size 1523712

graphs/psf__requests.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0ac54923dae6f7baaae9de459c40e3146a19232e49c9b7be497635c511f033db
+size 1613824

graphs/pydantic__pydantic.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7ca527aa2ff1d7a3a843488cdb09962fa7353f15ded354a0c64f6399c913bae2
+size 1953792

graphs/tiangolo__typer.lbug

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a7ae9ad07103e943be40610741899c42809b45e339fb413e7755104e43237ef1
+size 2617344

models.py

@@ -0,0 +1,47 @@
+"""SQLModel tables for the Postgres history store (users, sessions, traces)."""
+
+# no `from __future__ import annotations`: it breaks SQLModel relationship targets
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from sqlalchemy import Column, JSON
+from sqlmodel import Field, Relationship, SQLModel
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _new_id() -> str:
+    return str(uuid4())
+
+
+class User(SQLModel, table=True):
+    # Clerk user id from the frontend, not auto-generated
+    id: str = Field(primary_key=True)
+    email: str = Field(unique=True, index=True)
+    created_at: datetime = Field(default_factory=_utcnow)
+
+    sessions: list["ChatSession"] = Relationship(back_populates="user")
+
+
+class ChatSession(SQLModel, table=True):
+    id: str = Field(default_factory=_new_id, primary_key=True)
+    user_id: str = Field(foreign_key="user.id", index=True)
+    title: str = Field(default="New Chat")
+    created_at: datetime = Field(default_factory=_utcnow)
+
+    user: User | None = Relationship(back_populates="sessions")
+    traces: list["TraceLog"] = Relationship(back_populates="session")
+
+
+class TraceLog(SQLModel, table=True):
+    id: str = Field(default_factory=_new_id, primary_key=True)
+    session_id: str = Field(foreign_key="chatsession.id", index=True)
+    query: str
+    execution_plan: dict = Field(default_factory=dict, sa_column=Column(JSON))
+    graph_payload: dict | list = Field(default_factory=dict, sa_column=Column(JSON))
+    created_at: datetime = Field(default_factory=_utcnow)
+
+    session: ChatSession | None = Relationship(back_populates="traces")

ratelimit.py

@@ -0,0 +1,54 @@
+"""Per-user rate limiting for the LLM (billed) endpoints, built on slowapi.
+
+slowapi wraps the `limits` library. A limit like "10/minute" is a FIXED-WINDOW
+counter by default: one count per (key, 60s window). It's cheap and perfect for
+"stop a single user from hammering a paid API", with one caveat — the window
+boundary allows a short burst (10 at :59 + 10 at 1:01 = 20 in ~2s). For a smooth
+limit with no boundary burst, switch to the moving-window strategy (see below).
+
+The interesting design choice here is the KEY: we rate-limit per authenticated
+USER, not per IP. The default slowapi key_func (get_remote_address) keys by IP,
+which would make a whole office behind one NAT share a single bucket. Instead our
+key_func reads request.state.user_id — which get_current_user populates during
+dependency resolution, before this key_func is ever called (see auth.py).
+"""
+
+from __future__ import annotations
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from starlette.requests import Request
+
+
+def _user_key(request: Request) -> str:
+    """Bucket key = the authenticated user id, falling back to client IP.
+
+    By the time slowapi calls this, FastAPI has already run get_current_user
+    (a dependency on the limited routes), so request.state.user_id is set. The
+    IP fallback only matters for routes that have no auth dependency — it keeps
+    the key_func total so slowapi never crashes on a missing attribute.
+    """
+    user_id = getattr(request.state, "user_id", None)
+    if user_id:
+        return f"user:{user_id}"
+    return f"ip:{get_remote_address(request)}"
+
+
+# The process-wide limiter.
+#
+# storage_uri: omitted → defaults to IN-MEMORY storage. That's correct for a
+# single uvicorn worker. With --workers N each process keeps its OWN counter, so
+# the effective limit becomes N × the configured rate. When you scale to
+# multi-worker / multi-instance, point all of them at a shared store:
+#
+#     limiter = Limiter(
+#         key_func=_user_key,
+#         storage_uri="redis://localhost:6379",   # shared counter across workers
+#         strategy="moving-window",                # smooth limit, no boundary burst
+#     )
+#
+# strategy: omitted → "fixed-window" (the simple counter described above).
+limiter = Limiter(key_func=_user_key)
+
+# Single source of truth for the LLM-endpoint rate, applied via @limiter.limit().
+LLM_RATE_LIMIT = "10/minute"

requirements.txt

@@ -0,0 +1,55 @@
+# --- Storage Core ---
+ladybug
+
+# ---Embeddings (local, 384-dim) ---
+sentence-transformers>=2.7.0   # all-MiniLM-L6-v2 -> FLOAT[384]
+
+# --- Entity extraction (GLiNER primary, spaCy fallback) ---
+gliner>=0.2.0
+# PIN: onnxruntime 1.18+ (incl. 1.26) fails "DLL load failed ... initialization
+# routine failed" on Windows/Anaconda boxes lacking the newer MSVC runtime,
+# which silently demotes GLiNER to the spaCy fallback (type pollution). 1.17.1
+# loads against the installed runtime. Do not bump without re-verifying import.
+onnxruntime==1.17.1
+spacy>=3.7.0
+
+# --- Deep Merge LLM (local) ---
+openai>=1.40.0                 # OpenRouter client (deep-merge + intent + judge)
+python-dotenv>=1.0.0           # load OPENROUTER_API_KEY from .env
+
+# --- Data / numerics ---
+numpy>=1.26.0
+pandas>=2.1.0                  # conn.execute(...).get_as_df()
+
+# --- Loaders (generic ingest) ---
+python-frontmatter>=1.1.0      # .md front-matter parsing
+pypdf>=4.0.0                   # .pdf loader
+
+# --- Benchmark ---
+tiktoken>=0.7.0                # context-window token counting
+
+# --- Integrations ---
+langchain-core>=0.2.0          # BaseRetriever subclass
+
+# --- API (TraceRAG STUDIO dashboard) ---
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+
+# --- History store (Neon Postgres via SQLModel) ---
+sqlmodel>=0.0.16              # User / ChatSession / TraceLog tables
+psycopg2-binary>=2.9.9        # Postgres driver for the postgresql:// engine
+
+# --- Auth (Clerk session-token verification) ---
+# [crypto] pulls in `cryptography` for RS256 signature verification; PyJWKClient
+# (fetches + caches Clerk's public JWKS) ships in the base PyJWT package.
+PyJWT[crypto]>=2.8.0
+
+# --- Ops / testing ---
+tqdm>=4.66.0                  # ingest progress bars
+aiohttp>=3.9.0                 # scripts/stress_test.py load generator
+slowapi>=0.1.9                 # FastAPI rate limiting (see api.py hardening)
+requests>=2.31.0              # scripts/ingest_github.py live PR connector
+
+# --- Observability ---
+sentry-sdk[fastapi]>=2.0.0    # error tracking + perf monitoring (opt-in via SENTRY_DSN)
+

routers/history.py

@@ -0,0 +1,170 @@
+"""Chat-history endpoints backed by Postgres via SQLModel."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlmodel import Session, select
+
+from auth import get_current_user
+from database import get_engine, get_session
+from models import ChatSession, TraceLog, User
+
+logger = logging.getLogger("tracerag.history")
+
+router = APIRouter(prefix="/api", tags=["history"])
+
+
+class SessionUpsert(BaseModel):
+    # user_id is intentionally NOT trusted from the body anymore — the real user
+    # id comes from the verified token (get_current_user). Kept optional purely
+    # for backward-compat with the existing frontend payload; it is ignored.
+    user_id: str | None = None
+    email: str | None = None           # required only on first sight of a user
+    title: str = "New Chat"
+    session_id: str | None = None      # set -> rename that session instead of creating
+
+
+class SessionRead(BaseModel):
+    id: str
+    user_id: str
+    title: str
+    created_at: datetime
+
+
+class TraceRead(BaseModel):
+    id: str
+    session_id: str
+    query: str
+    execution_plan: dict
+    graph_payload: dict | list
+    created_at: datetime
+
+
+def _ensure_user(db: Session, user_id: str, email: str | None) -> User:
+    """Get the user by id, creating the row on first sight.
+
+    Email is best-effort, not a hard requirement: dev-bypass has none, and
+    Clerk's email can lag the user id on first load — blocking "new chat" on a
+    missing email made history silently break. Fall back to a deterministic
+    per-user placeholder (unique, so no constraint clash) and use the real
+    address whenever the client supplies it.
+    """
+    user = db.get(User, user_id)
+    if user is None:
+        placeholder = f"{user_id}@users.tracerag.local"
+        candidate = email or placeholder
+        # The email column is unique. If this address is already held by a
+        # DIFFERENT id (e.g. a real-Clerk row vs. the dev-bypass "dev-user"),
+        # claiming it would 500. Fall back to the per-id placeholder, which only
+        # this id can ever own.
+        clash = db.exec(select(User).where(User.email == candidate)).first()
+        if clash is not None and clash.id != user_id:
+            candidate = placeholder
+        user = User(id=user_id, email=candidate)
+        db.add(user)
+        db.flush()  # surface any remaining unique violations before committing
+    return user
+
+
+def session_owner(session_id: str) -> str | None:
+    """Return the user_id that owns a session, or None if it doesn't exist.
+
+    Opens its own DB session (like persist_trace) so it can be called from the
+    /api/trace endpoint, which has no injected `db` dependency. Used to verify
+    ownership before persisting a trace into a session — closes the write-side
+    IDOR (writing your trace into someone else's session).
+    """
+    try:
+        with Session(get_engine()) as db:
+            chat = db.get(ChatSession, session_id)
+            return chat.user_id if chat is not None else None
+    except Exception as exc:  # noqa: BLE001 — DB hiccup shouldn't 500 the query
+        logger.warning("session_owner lookup failed for %s: %s", session_id, exc)
+        return None
+
+
+def persist_trace(
+    session_id: str,
+    query: str,
+    execution_plan: dict,
+    graph_payload: dict | list,
+) -> str | None:
+    """Save one execution to Postgres; returns the new trace id or None on failure."""
+    try:
+        with Session(get_engine()) as db:
+            log = TraceLog(
+                session_id=session_id,
+                query=query,
+                execution_plan=execution_plan,
+                graph_payload=graph_payload,
+            )
+            db.add(log)
+            db.commit()
+            db.refresh(log)
+            return log.id
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("persist_trace failed for session %s: %s", session_id, exc)
+        return None
+
+
+@router.post("/sessions", response_model=SessionRead)
+def create_or_rename_session(
+    body: SessionUpsert,
+    user_id: str = Depends(get_current_user),  # verified id, NOT body.user_id
+    db: Session = Depends(get_session),
+) -> ChatSession:
+    if body.session_id:
+        chat = db.get(ChatSession, body.session_id)
+        if chat is None:
+            raise HTTPException(status_code=404, detail="session not found")
+        # ownership check: you can only rename a session that is yours
+        if chat.user_id != user_id:
+            raise HTTPException(status_code=403, detail="not your session")
+        chat.title = body.title
+    else:
+        # create the user row (if new) and the session under the TOKEN's user id
+        _ensure_user(db, user_id, body.email)
+        chat = ChatSession(user_id=user_id, title=body.title)
+        db.add(chat)
+    db.commit()
+    db.refresh(chat)
+    return chat
+
+
+@router.get("/sessions", response_model=list[SessionRead])
+def list_sessions(
+    user_id: str = Depends(get_current_user),  # scope strictly to the caller
+    db: Session = Depends(get_session),
+) -> list[ChatSession]:
+    # Only ever return the authenticated user's own sessions. A client can no
+    # longer pass someone else's id to read their history (closes the IDOR).
+    stmt = (
+        select(ChatSession)
+        .where(ChatSession.user_id == user_id)
+        .order_by(ChatSession.created_at.desc())
+    )
+    return list(db.exec(stmt))
+
+
+@router.get("/sessions/{session_id}/traces", response_model=list[TraceRead])
+def session_traces(
+    session_id: str,
+    user_id: str = Depends(get_current_user),
+    db: Session = Depends(get_session),
+) -> list[TraceLog]:
+    chat = db.get(ChatSession, session_id)
+    if chat is None:
+        raise HTTPException(status_code=404, detail="session not found")
+    # ownership check: you can only read traces from a session that is yours
+    if chat.user_id != user_id:
+        raise HTTPException(status_code=403, detail="not your session")
+    stmt = (
+        select(TraceLog)
+        .where(TraceLog.session_id == session_id)
+        .order_by(TraceLog.created_at.asc())
+    )
+    return list(db.exec(stmt))

scripts/audit_data.py

@@ -0,0 +1,136 @@
+"""Data-integrity linter for the TraceRAG graph.
+
+    python scripts/audit_data.py [--db memory.lbug] [--alias-threshold 0.85] [--json report.json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from tracerag import config                      # noqa: E402
+from tracerag.db import TraceDB                   # noqa: E402
+
+logger = logging.getLogger("tracerag.audit")
+
+_OWNABLE_TYPES = ("Service", "Repo", "Ticket", "PR", "Tool")
+_OWNER_TYPES = ("Person", "Team")
+
+
+def find_orphaned_nodes(db: TraceDB) -> list[dict]:
+    """Entities with no RELATES_TO edges (isolated in the entity graph)."""
+    rows = db._records(db.execute(
+        f"MATCH (e:{config.NODE_TABLE}) "
+        f"OPTIONAL MATCH (e)-[r:{config.REL_TABLE}]-(:{config.NODE_TABLE}) "
+        f"RETURN e.id AS id, e.label AS label, e.type AS type, count(r) AS degree;"
+    ))
+    return [r for r in rows if int(r["degree"]) == 0]
+
+
+def find_conflicting_edges(db: TraceDB) -> list[dict]:
+    """Ownable nodes linked to more than one distinct Person/Team."""
+    rows = db._records(db.execute(
+        f"MATCH (a:{config.NODE_TABLE})-[:{config.REL_TABLE}]-(b:{config.NODE_TABLE}) "
+        f"WHERE a.type IN $ownable AND b.type IN $owners "
+        f"RETURN a.id AS aid, a.label AS alabel, a.type AS atype, "
+        f"b.label AS owner, b.type AS owner_type;",
+        {"ownable": list(_OWNABLE_TYPES), "owners": list(_OWNER_TYPES)},
+    ))
+    grouped: dict[str, dict] = {}
+    for r in rows:
+        g = grouped.setdefault(r["aid"], {
+            "id": r["aid"], "label": r["alabel"], "type": r["atype"], "owners": set()
+        })
+        g["owners"].add(f'{r["owner"]} ({r["owner_type"]})')
+    conflicts = []
+    for g in grouped.values():
+        if len(g["owners"]) > 1:
+            g["owners"] = sorted(g["owners"])
+            conflicts.append(g)
+    return conflicts
+
+
+def find_alias_drift(db: TraceDB, threshold: float) -> list[dict]:
+    """Separate nodes with near-duplicate embeddings (cosine >= threshold)."""
+    rows = db._records(db.execute(
+        f"MATCH (e:{config.NODE_TABLE}) "
+        f"RETURN e.id AS id, e.label AS label, e.type AS type, e.embedding AS emb;"
+    ))
+    rows = [r for r in rows if r.get("emb") is not None]
+    if len(rows) < 2:
+        return []
+    mat = np.asarray([r["emb"] for r in rows], dtype=np.float32)  # pre-normalized
+    sims = mat @ mat.T
+    pairs = []
+    for i in range(len(rows)):
+        for j in range(i + 1, len(rows)):
+            s = float(sims[i, j])
+            if s >= threshold:
+                pairs.append({
+                    "a": rows[i]["label"], "a_type": rows[i]["type"],
+                    "b": rows[j]["label"], "b_type": rows[j]["type"],
+                    "similarity": round(s, 4),
+                })
+    pairs.sort(key=lambda p: p["similarity"], reverse=True)
+    return pairs
+
+
+def _section(title: str, items: list, render) -> None:
+    print(f"\n{'=' * 70}\n {title}  ({len(items)} found)\n{'-' * 70}")
+    if not items:
+        print("  (none)")
+        return
+    for it in items[:40]:
+        print("  " + render(it))
+    if len(items) > 40:
+        print(f"  ... and {len(items) - 40} more")
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="TraceRAG data-integrity linter.")
+    p.add_argument("--db", type=Path, default=config.DB_PATH)
+    p.add_argument("--alias-threshold", type=float, default=config.DEEP_MERGE_THRESHOLD,
+                   help="Cosine >= this between distinct nodes flags alias drift.")
+    p.add_argument("--json", type=Path, default=None, help="Also write the report as JSON.")
+    args = p.parse_args(argv)
+    logging.basicConfig(level=logging.WARNING)
+
+    db = TraceDB(args.db)
+    try:
+        total_nodes = db.count_nodes()
+        orphaned = find_orphaned_nodes(db)
+        conflicts = find_conflicting_edges(db)
+        drift = find_alias_drift(db, args.alias_threshold)
+    finally:
+        db.close()
+
+    print(f"\nTraceRAG data audit — {args.db}  ({total_nodes} entities)")
+    _section("ORPHANED NODES (0 RELATES_TO edges)", orphaned,
+             lambda r: f'{r["label"]!r} ({r["type"]})  id={r["id"]}')
+    _section("CONFLICTING OWNERSHIP (>1 Person/Team)", conflicts,
+             lambda c: f'{c["label"]!r} ({c["type"]}) -> {", ".join(c["owners"])}')
+    _section(f"ALIAS DRIFT (cosine >= {args.alias_threshold})", drift,
+             lambda d: f'{d["similarity"]}  {d["a"]!r} ({d["a_type"]})  ~  {d["b"]!r} ({d["b_type"]})')
+
+    summary = {
+        "db": str(args.db), "total_nodes": total_nodes,
+        "orphaned": orphaned, "conflicts": conflicts, "alias_drift": drift,
+    }
+    print(f"\n{'=' * 70}\n SUMMARY: {len(orphaned)} orphaned | "
+          f"{len(conflicts)} ownership conflicts | {len(drift)} alias-drift pairs\n")
+    if args.json:
+        args.json.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+        print(f"Wrote JSON report -> {args.json}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/benchmark.py

@@ -0,0 +1,216 @@
+"""LLM-as-a-judge benchmark for the TraceRAG pipeline.
+
+    python -m scripts.benchmark --db memory.lbug --out results.csv
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import logging
+import os
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from tracerag import config                                  # noqa: E402
+from tracerag.db import TraceDB                               # noqa: E402
+from tracerag.router import TraceRouter                       # noqa: E402
+from tracerag.llm import make_client                          # noqa: E402
+
+logger = logging.getLogger("tracerag.benchmark")
+
+JUDGE_CONTEXT_CHARS = int(os.getenv("TRACERAG_JUDGE_CHARS", "100000"))
+JUDGE_SLEEP_SEC = float(os.getenv("TRACERAG_JUDGE_SLEEP", "1"))
+
+
+@dataclass(frozen=True)
+class TestQuery:
+    query: str
+    category: str
+
+
+TEST_SET: list[TestQuery] = [
+    # semantic / conceptual
+    TestQuery("Explain the ShopFlow commerce platform architecture.", "semantic"),
+    TestQuery("What is the responsibility of the PaymentService?", "semantic"),
+    TestQuery("How does the AuthLayer handle login and JWT issuance?", "semantic"),
+    TestQuery("What is the role of the InventoryService?", "semantic"),
+    TestQuery("Summarize the ShopFlow microservices and what each one does.", "semantic"),
+    # relational / multi-hop
+    TestQuery("What was incident INC-4471 about?", "relational"),
+    TestQuery("Which component was affected in incident INC-4480?", "relational"),
+    TestQuery("Who is the tech lead and owning team for PaymentService?", "relational"),
+    TestQuery("What does payment-service depend on?", "relational"),
+    TestQuery("What is related to PR #847?", "relational"),
+]
+
+
+def approx_tokens(text: str) -> int:
+    """Cheap token estimate: words * 1.3."""
+    return int(len(text.split()) * 1.3)
+
+
+def baseline_context(db: TraceDB, node_ids: list[str]) -> str:
+    """Pure-vector control: concatenate the unique chunk texts of the top-k hits."""
+    docs_by_entity = db.documents_for_entities(node_ids)
+    seen, parts = set(), []
+    for nid in node_ids:
+        for d in docs_by_entity.get(nid, []):
+            text = (d.get("content") or "").strip()
+            if text and text not in seen:
+                seen.add(text)
+                parts.append(text)
+    return "\n\n".join(parts)
+
+
+def _safe_vector_search(db: TraceDB, embedding: list[float], k: int) -> list[dict]:
+    try:
+        return db.vector_search(embedding, k=k)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("baseline vector_search returned nothing (%s)", exc)
+        return []
+
+
+def judge_sufficient(client, query: str, context: str) -> tuple[int, str]:
+    """LLM-as-judge: is the context relevant to answering the query? -> (1/0, raw)."""
+    prompt = (
+        f"Does the provided context contain facts relevant to answering the query? "
+        f"Reply YES if it includes information that helps answer it (even partially, "
+        f"or via connected relationships); reply NO only if the context is completely "
+        f"unrelated or off-topic.\n\n"
+        f"Note: The context contains SYSTEM TRACES (hard factual relationships "
+        f"between engineering entities) followed by standard DOCUMENT CHUNKS. Treat "
+        f"the traces as absolute facts.\n\n"
+        f"Output YES or NO as the very first word of your reply.\n\n"
+        f"Query: {query}\n\n"
+        f"Context:\n{context if context.strip() else '(no context retrieved)'}"
+    )
+    try:
+        resp = client.chat.completions.create(
+            model=config.OPENROUTER_MODEL,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0,
+        )
+        answer = resp.choices[0].message.content.strip().upper()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Judge LLM failed (%s); scoring as 0.", exc)
+        return 0, f"ERROR: {exc}"
+    return (1 if answer.startswith("YES") else 0), answer
+
+
+def run(db_path: Path, out_path: Path, k: int) -> list[dict]:
+    db = TraceDB(db_path)
+    db.init_schema()
+    router = TraceRouter(db)
+    client = make_client()
+
+    rows: list[dict] = []
+    try:
+        for tq in TEST_SET:
+            # hybrid (router) arm
+            resp = router.route(tq.query, top_k=k)
+            context = router.build_context(resp.results)
+            intent = resp.trace_log.get("intent", {})
+            tokens = approx_tokens(context)
+
+            # pure-vector baseline arm
+            embedding = router.embed_query(tq.query)
+            baseline_ids = [h["id"] for h in _safe_vector_search(db, embedding, k)
+                            if h.get("id")]
+            baseline_tokens = approx_tokens(baseline_context(db, baseline_ids))
+            reduction = (
+                (1 - tokens / baseline_tokens) * 100 if baseline_tokens else 0.0
+            )
+
+            verdict, raw = judge_sufficient(
+                client, tq.query, context[:JUDGE_CONTEXT_CHARS]
+            )
+            time.sleep(JUDGE_SLEEP_SEC)
+
+            rows.append({
+                "query": tq.query,
+                "category": tq.category,
+                "intent_type": intent.get("type"),
+                "alpha": intent.get("alpha"),
+                "beta": intent.get("beta"),
+                "num_docs": len(resp.results),
+                "context_tokens": tokens,
+                "baseline_tokens": baseline_tokens,
+                "token_reduction_pct": round(reduction, 1),
+                "judge": verdict,
+                "judge_raw": raw,
+            })
+            logger.info("[%-10s] judge=%d tokens=%4d baseline=%4d reduction=%5.1f%%  %s",
+                        tq.category, verdict, tokens, baseline_tokens, reduction, tq.query)
+    finally:
+        db.close()
+
+    _write_csv(rows, out_path)
+    return rows
+
+
+def _write_csv(rows: list[dict], out_path: Path) -> None:
+    fields = ["query", "category", "intent_type", "alpha", "beta", "num_docs",
+              "context_tokens", "baseline_tokens", "token_reduction_pct",
+              "judge", "judge_raw"]
+    with out_path.open("w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fields)
+        writer.writeheader()
+        writer.writerows(rows)
+    logger.info("Wrote %d rows -> %s", len(rows), out_path)
+
+
+def print_summary(rows: list[dict]) -> None:
+    header = (f"{'Category':<12}{'Queries':>9}{'Hybrid Tok':>12}"
+              f"{'Baseline Tok':>14}{'Reduction':>11}{'Accuracy':>11}")
+    width = len(header)
+
+    def line(label: str, group: list[dict]) -> None:
+        n = len(group)
+        if not n:
+            return
+        hyb = sum(r["context_tokens"] for r in group) / n
+        base = sum(r["baseline_tokens"] for r in group) / n
+        red = sum(r["token_reduction_pct"] for r in group) / n
+        acc = sum(r["judge"] for r in group) / n
+        print(f"{label:<12}{n:>9}{hyb:>12.1f}{base:>14.1f}{red:>10.1f}%{acc:>11.1%}")
+
+    print("\n" + "=" * width)
+    print(header)
+    print("-" * width)
+    for category in ("semantic", "relational"):
+        line(category, [r for r in rows if r["category"] == category])
+    print("-" * width)
+    line("OVERALL", rows)
+    print("=" * width + "\n")
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="TraceRAG LLM-as-judge benchmark.")
+    p.add_argument("--db", type=Path, default=config.DB_PATH)
+    p.add_argument("--out", type=Path, default=config.RESULTS_CSV)
+    p.add_argument("--k", type=int, default=config.TOP_K_VECTOR,
+                   help="Top-k entities retrieved per query.")
+    p.add_argument("-v", "--verbose", action="store_true")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s  %(levelname)-7s %(name)s  %(message)s",
+    )
+    for noisy in ("httpx", "httpcore", "openai", "sentence_transformers"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+    rows = run(args.db, args.out, args.k)
+    print_summary(rows)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/ingest.py

@@ -0,0 +1,182 @@
+"""Headless ingest entry point.
+
+    python -m scripts.ingest --datasets datasets --db memory.lbug
+    python scripts/ingest.py --reset
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from tracerag import config                       # noqa: E402
+from tracerag.db import TraceDB                    # noqa: E402
+from tracerag.extract import EntityExtractor       # noqa: E402
+from tracerag.curation import CurationEngine, IngestStats  # noqa: E402
+
+logger = logging.getLogger("tracerag.ingest")
+
+
+@dataclass(frozen=True)
+class Document:
+    doc_id: str
+    text: str
+    meta: dict
+
+
+def load_documents(datasets_dir: Path) -> Iterator[Document]:
+    if not datasets_dir.exists():
+        logger.warning("Datasets dir does not exist: %s", datasets_dir)
+        return
+
+    for path in sorted(datasets_dir.rglob("*")):
+        if not path.is_file():
+            continue
+        suffix = path.suffix.lower()
+        rel = path.relative_to(datasets_dir).as_posix()
+        try:
+            if suffix in (".md", ".markdown"):
+                yield _load_markdown(path, rel)
+            elif suffix == ".json":
+                yield from _load_json(path, rel)
+            elif suffix == ".pdf":
+                yield _load_pdf(path, rel)
+            else:
+                logger.debug("Skipping unsupported file: %s", rel)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Failed to load %s: %s", rel, exc)
+
+
+def _load_markdown(path: Path, rel: str) -> Document:
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    meta, body = {}, raw
+    try:
+        import frontmatter
+
+        post = frontmatter.loads(raw)
+        meta, body = dict(post.metadata), post.content
+    except Exception:  # noqa: BLE001
+        pass
+    return Document(doc_id=rel, text=body, meta=meta)
+
+
+def _load_json(path: Path, rel: str) -> Iterator[Document]:
+    # arrays -> one Document per record
+    data = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    records = data if isinstance(data, list) else [data]
+    for i, rec in enumerate(records):
+        if isinstance(rec, dict):
+            text = "\n".join(f"{k}: {v}" for k, v in _flatten(rec).items())
+            doc_id = f"{rel}#{rec.get('key', rec.get('id', i))}"
+        else:
+            text, doc_id = str(rec), f"{rel}#{i}"
+        yield Document(doc_id=doc_id, text=text, meta={"source_file": rel})
+
+
+def _load_pdf(path: Path, rel: str) -> Document:
+    from pypdf import PdfReader
+
+    reader = PdfReader(str(path))
+    text = "\n".join((page.extract_text() or "") for page in reader.pages)
+    return Document(doc_id=rel, text=text, meta={"pages": len(reader.pages)})
+
+
+def _flatten(obj: dict, prefix: str = "") -> dict:
+    out: dict = {}
+    for k, v in obj.items():
+        key = f"{prefix}{k}"
+        if isinstance(v, dict):
+            out.update(_flatten(v, f"{key}."))
+        elif isinstance(v, list):
+            out[key] = ", ".join(str(x) for x in v)
+        else:
+            out[key] = v
+    return out
+
+
+def ingest_text(
+    engine: CurationEngine,
+    extractor: EntityExtractor,
+    doc_id: str,
+    text: str,
+    source: str | None = None,
+) -> IngestStats:
+    """Run one text blob through extraction -> curation -> graph write.
+
+    Callers must invoke ``db.build_vector_index()`` once after the final document.
+    """
+    entities = extractor.extract(text)
+    return engine.ingest(doc_id, text, entities, source=source)
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="TraceRAG headless ingest.")
+    p.add_argument("--datasets", type=Path, default=config.DATASETS_DIR)
+    p.add_argument("--db", type=Path, default=config.DB_PATH)
+    p.add_argument("--reset", action="store_true",
+                   help="Delete the existing .lbug file before ingesting.")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Extract and report entities without writing.")
+    p.add_argument("-v", "--verbose", action="store_true")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s  %(levelname)-7s %(name)s  %(message)s",
+    )
+    for noisy in ("httpx", "httpcore", "openai", "sentence_transformers"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    if args.reset:
+        # remove the .lbug file plus its .wal/.lock/.tmp sidecars
+        for p in sorted(args.db.parent.glob(args.db.name + "*")):
+            logger.info("Reset: removing %s", p)
+            p.unlink()
+
+    extractor = EntityExtractor()
+    db = TraceDB(args.db)
+    db.init_schema()
+    engine = None if args.dry_run else CurationEngine(db)
+
+    totals = IngestStats()
+    try:
+        for doc in load_documents(args.datasets):
+            entities = extractor.extract(doc.text)
+            logger.info("%-40s  %3d entities", doc.doc_id, len(entities))
+
+            if args.dry_run:
+                totals.docs += 1
+                totals.entities += len(entities)
+                continue
+
+            stats = engine.ingest(doc.doc_id, doc.text, entities)
+            totals.merge(stats)
+            logger.debug("  %s", stats)
+
+        if not args.dry_run:
+            db.build_vector_index()
+
+        logger.info(
+            "Done. %d docs, %d entities | created=%d fast=%d deep_yes=%d "
+            "deep_no=%d ollama=%d | rel=%d mentions=%d | nodes_in_db=%d",
+            totals.docs, totals.entities, totals.created, totals.fast_merged,
+            totals.deep_merged_yes, totals.deep_merged_no, totals.ollama_calls,
+            totals.relates_edges, totals.mentions_edges, db.count_nodes(),
+        )
+    finally:
+        db.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/ingest_github.py

@@ -0,0 +1,195 @@
+"""Pull closed GitHub PRs into the TraceRAG graph.
+
+    python scripts/ingest_github.py --repo langchain-ai/langchain
+    python scripts/ingest_github.py --repo owner/repo --limit 100 --reset
+
+Set GITHUB_TOKEN in .env to raise the rate limit from 60/hr to 5000/hr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import re
+import sys
+from pathlib import Path
+
+import requests
+from tqdm import tqdm
+
+_SCRIPTS = Path(__file__).resolve().parent
+sys.path.insert(0, str(_SCRIPTS.parent))
+sys.path.insert(0, str(_SCRIPTS))
+
+from tracerag import config                       # noqa: E402
+from tracerag.db import TraceDB                    # noqa: E402
+from tracerag.extract import EntityExtractor       # noqa: E402
+from tracerag.curation import CurationEngine, IngestStats  # noqa: E402
+from ingest import ingest_text                     # noqa: E402
+
+logger = logging.getLogger("tracerag.github")
+
+GITHUB_API = "https://api.github.com"
+_PER_PAGE = 100  # GitHub's max page size
+
+
+_MD_IMAGE = re.compile(r"!\[[^\]]*\]\([^)]*\)")
+_HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+_WS = re.compile(r"\s+")
+
+
+def clean_pr_body(body: str | None) -> str:
+    """Strip markdown images and HTML comments; collapse whitespace."""
+    if not body:
+        return ""
+    t = _MD_IMAGE.sub(" ", body)
+    t = _HTML_COMMENT.sub(" ", t)
+    return _WS.sub(" ", t).strip()
+
+
+def assemble_text(pr: dict) -> tuple[str, str]:
+    """Build (doc_id, clean text blob) the existing pipeline can parse."""
+    number = pr.get("number")
+    title = (pr.get("title") or "").strip()
+    author = (pr.get("user") or {}).get("login") or "unknown"
+    # rstrip trailing periods/spaces so we don't emit "...client.."
+    body = clean_pr_body(pr.get("body")).rstrip(". ")
+    text = f"PR #{number} merged by {author}. Title: {title}. Description: {body}."
+    return f"pr-{number}", text
+
+
+def fetch_merged_prs(repo: str, limit: int, token: str | None) -> list[dict]:
+    """Page through closed PRs, keeping only merged ones (merged_at != null), until limit."""
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    merged: list[dict] = []
+    page = 1
+    while len(merged) < limit:
+        resp = requests.get(
+            f"{GITHUB_API}/repos/{repo}/pulls",
+            headers=headers,
+            params={"state": "closed", "per_page": _PER_PAGE, "page": page},
+            timeout=30,
+        )
+        if resp.status_code != 200:
+            raise RuntimeError(
+                f"GitHub API {resp.status_code} for {repo}: {resp.text[:200]}"
+            )
+        batch = resp.json()
+        if not batch:
+            break
+        merged.extend(pr for pr in batch if pr.get("merged_at"))
+        page += 1
+    return merged[:limit]
+
+
+def repo_db_path(repo: str, graphs_dir: Path) -> Path:
+    """Per-repo .lbug file, e.g. pallets/flask -> graphs/pallets__flask.lbug."""
+    slug = re.sub(r"[^a-z0-9_]+", "-", repo.lower().replace("/", "__"))
+    return graphs_dir / f"{slug}.lbug"
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Ingest closed GitHub PRs into TraceRAG.")
+    p.add_argument("--repo", nargs="+", required=True,
+                   help='One or more repos, e.g. "pallets/flask psf/requests".')
+    p.add_argument("--limit", type=int, default=50,
+                   help="Max MERGED PRs to ingest per repo (protects rate limits).")
+    p.add_argument("--db", type=Path, default=None,
+                   help="Override output file (single-repo only; otherwise one "
+                        "per-repo file is created under --graphs-dir).")
+    p.add_argument("--graphs-dir", type=Path, default=None,
+                   help="Directory for per-repo .lbug files (default backend/graphs).")
+    p.add_argument("--reset", action="store_true",
+                   help="Delete each target .lbug (+ sidecars) before ingesting.")
+    p.add_argument("-v", "--verbose", action="store_true")
+    return p.parse_args(argv)
+
+
+def ingest_repo(
+    repo: str, db_path: Path, limit: int, reset: bool,
+    token: str | None, extractor: EntityExtractor,
+) -> None:
+    """Fetch + ingest one repo's merged PRs into its own .lbug file."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    if reset:
+        for p in sorted(db_path.parent.glob(db_path.name + "*")):
+            logger.info("[%s] reset: removing %s", repo, p.name)
+            p.unlink()
+
+    logger.info("[%s] fetching up to %d merged PRs", repo, limit)
+    prs = fetch_merged_prs(repo, limit, token)
+    logger.info("[%s] fetched %d merged PRs -> %s", repo, len(prs), db_path.name)
+
+    db = TraceDB(db_path)
+    db.init_schema()
+    engine = CurationEngine(db)
+    totals, skipped = IngestStats(), 0
+    try:
+        for pr in tqdm(prs, total=len(prs), desc=f"{repo}", unit="pr"):
+            doc_id, text = assemble_text(pr)
+            if not text.strip():
+                skipped += 1
+                continue
+            totals.merge(
+                ingest_text(engine, extractor, doc_id, text, source=pr.get("html_url"))
+            )
+        db.build_vector_index()
+        logger.info(
+            "[%s] done. %d PRs (%d skipped) | %d entities | "
+            "created=%d fast=%d deep_yes=%d deep_no=%d llm=%d | "
+            "rel=%d mentions=%d | nodes_in_db=%d",
+            repo, totals.docs, skipped, totals.entities, totals.created,
+            totals.fast_merged, totals.deep_merged_yes, totals.deep_merged_no,
+            totals.ollama_calls, totals.relates_edges, totals.mentions_edges,
+            db.count_nodes(),
+        )
+    finally:
+        db.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s  %(levelname)-7s %(name)s  %(message)s",
+    )
+    for noisy in ("httpx", "httpcore", "openai", "urllib3", "sentence_transformers"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    token = os.getenv("GITHUB_TOKEN")
+    if not token:
+        logger.warning("GITHUB_TOKEN not set — unauthenticated requests are capped "
+                       "at 60/hr. Add it to .env to raise the limit.")
+
+    repo_root = config.PROJECT_ROOT.parent
+    graphs_dir = args.graphs_dir or (config.PROJECT_ROOT / "graphs")
+    if not graphs_dir.is_absolute():
+        graphs_dir = repo_root / graphs_dir
+
+    if args.db and len(args.repo) > 1:
+        logger.warning("--db is ignored with multiple repos; using per-repo files.")
+
+    extractor = EntityExtractor()
+    for repo in args.repo:
+        if args.db and len(args.repo) == 1:
+            db_path = args.db if args.db.is_absolute() else (repo_root / args.db)
+        else:
+            db_path = repo_db_path(repo, graphs_dir)
+        try:
+            ingest_repo(repo, db_path, args.limit, args.reset, token, extractor)
+        except Exception as exc:  # noqa: BLE001
+            logger.error("[%s] FAILED: %s", repo, exc)
+
+    logger.info("Batch complete. Graphs in %s", graphs_dir)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/ingest_jira_api.py

@@ -0,0 +1,201 @@
+"""Ingest real Jira tickets straight from a public Jira REST API.
+
+Pulls issues for one project (default: Apache Kafka on issues.apache.org),
+maps each to the same text shape the CSV pipeline uses, and runs them through
+the existing extraction -> curation -> graph pipeline.
+
+    # see what would be ingested, no DB / no GLiNER:
+    python scripts/ingest_jira_api.py --project KAFKA --limit 20 --dry-run
+
+    # build a fresh graph the dropdown will auto-discover:
+    python scripts/ingest_jira_api.py --project KAFKA --limit 150 \
+        --db graphs/apache__kafka.lbug --reset
+
+Any public Jira works via --base, e.g. Apache SPARK / LUCENE / FLINK, or
+Hyperledger, etc. Requires no auth for public instances.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+_SCRIPTS = Path(__file__).resolve().parent
+sys.path.insert(0, str(_SCRIPTS.parent))
+sys.path.insert(0, str(_SCRIPTS))
+
+from tracerag import config                       # noqa: E402
+from tracerag.db import TraceDB                    # noqa: E402
+from tracerag.extract import EntityExtractor       # noqa: E402
+from tracerag.curation import CurationEngine, IngestStats  # noqa: E402
+from ingest import ingest_text                     # noqa: E402
+from ingest_kaggle_jira import clean_jira_text     # noqa: E402  (reuse markup stripper)
+
+logger = logging.getLogger("tracerag.jira_api")
+
+DEFAULT_BASE = "https://issues.apache.org/jira"
+_FIELDS = "key,summary,issuetype,status,priority,assignee,reporter,components,labels,description"
+_PAGE = 100  # Jira caps maxResults at 100 for most instances
+
+
+def _name(obj: dict | None, key: str = "name") -> str:
+    """Safely pull a display string out of a nested Jira field object."""
+    if not isinstance(obj, dict):
+        return ""
+    return str(obj.get(key) or "").strip()
+
+
+def assemble_text(issue: dict) -> tuple[str, str]:
+    """Build (doc_id, clean text blob) from one Jira REST issue record."""
+    f = issue.get("fields") or {}
+    key = str(issue.get("key") or "").strip()
+
+    parts: list[str] = []
+    summary = str(f.get("summary") or "").strip()
+    if key or summary:
+        parts.append(f"Ticket {key}: {summary}.".strip())
+
+    for label, val in (
+        ("Type", _name(f.get("issuetype"))),
+        ("Status", _name(f.get("status"))),
+        ("Priority", _name(f.get("priority"))),
+    ):
+        if val:
+            parts.append(f"{label}: {val}.")
+
+    assignee = _name(f.get("assignee"), "displayName")
+    if assignee:
+        parts.append(f"Assigned to {assignee}.")
+    reporter = _name(f.get("reporter"), "displayName")
+    if reporter:
+        parts.append(f"Reported by {reporter}.")
+
+    components = ", ".join(
+        c.get("name", "") for c in (f.get("components") or []) if c.get("name")
+    )
+    if components:
+        parts.append(f"Component: {components}.")
+    labels = ", ".join(l for l in (f.get("labels") or []) if l)
+    if labels:
+        parts.append(f"Labels: {labels}.")
+
+    desc = clean_jira_text(str(f.get("description") or ""))
+    if desc:
+        parts.append(f"Description: {desc}")
+
+    return key, " ".join(parts)
+
+
+def fetch_issues(base: str, jql: str, limit: int) -> list[dict]:
+    """Page through the Jira search API until `limit` issues are collected."""
+    out: list[dict] = []
+    start = 0
+    while len(out) < limit:
+        page_size = min(_PAGE, limit - len(out))
+        params = urllib.parse.urlencode(
+            {"jql": jql, "startAt": start, "maxResults": page_size, "fields": _FIELDS}
+        )
+        url = f"{base.rstrip('/')}/rest/api/2/search?{params}"
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        logger.info("GET %s (have %d/%d)", url.split("?")[0], len(out), limit)
+        with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310 (trusted host)
+            data = json.loads(resp.read().decode("utf-8"))
+        issues = data.get("issues") or []
+        if not issues:
+            break
+        out.extend(issues)
+        total = data.get("total", 0)
+        start += len(issues)
+        if start >= total:
+            break
+    return out[:limit]
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Ingest Jira tickets from a public REST API.")
+    p.add_argument("--project", default="KAFKA", help="Jira project key, e.g. KAFKA, SPARK.")
+    p.add_argument("--base", default=DEFAULT_BASE, help="Jira base URL.")
+    p.add_argument("--jql", default=None,
+                   help="Override the JQL (default: project=<PROJECT> ORDER BY created DESC).")
+    p.add_argument("--limit", type=int, default=150, help="Number of issues to ingest.")
+    p.add_argument("--db", type=Path, default=config.DB_PATH)
+    p.add_argument("--reset", action="store_true",
+                   help="Delete the existing .lbug (+ sidecars) before ingesting.")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Fetch + assemble + print samples; no GLiNER, no DB writes.")
+    p.add_argument("-v", "--verbose", action="store_true")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s  %(levelname)-7s %(name)s  %(message)s",
+    )
+    for noisy in ("httpx", "httpcore", "openai", "sentence_transformers", "urllib3"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    jql = args.jql or f"project={args.project} ORDER BY created DESC"
+    logger.info("Fetching up to %d issues | %s | %s", args.limit, args.base, jql)
+    issues = fetch_issues(args.base, jql, args.limit)
+    logger.info("Fetched %d issues", len(issues))
+
+    if args.dry_run:
+        shown = 0
+        empty = 0
+        for issue in issues:
+            doc_id, text = assemble_text(issue)
+            if not text.strip():
+                empty += 1
+                continue
+            if shown < 5:
+                logger.info("--- %s ---\n%s", doc_id, text[:400])
+                shown += 1
+        logger.info("DRY RUN: %d ingestable, %d empty, of %d fetched",
+                    len(issues) - empty, empty, len(issues))
+        return 0
+
+    if args.reset:
+        for p in sorted(args.db.parent.glob(args.db.name + "*")):
+            logger.info("Reset: removing %s", p)
+            p.unlink()
+
+    extractor = EntityExtractor()
+    db = TraceDB(args.db)
+    db.init_schema()
+    engine = CurationEngine(db)
+
+    totals = IngestStats()
+    skipped = 0
+    try:
+        for i, issue in enumerate(issues):
+            doc_id, text = assemble_text(issue)
+            if not text.strip():
+                skipped += 1
+                continue
+            totals.merge(ingest_text(engine, extractor, doc_id or f"issue-{i}", text))
+            if (i + 1) % 25 == 0:
+                logger.info("  ingested %d/%d", i + 1, len(issues))
+
+        db.build_vector_index()
+        logger.info(
+            "Done. %d issues ingested (%d skipped) | %d entities | "
+            "created=%d fast=%d deep_yes=%d deep_no=%d llm=%d | "
+            "rel=%d mentions=%d | nodes_in_db=%d",
+            totals.docs, skipped, totals.entities, totals.created, totals.fast_merged,
+            totals.deep_merged_yes, totals.deep_merged_no, totals.ollama_calls,
+            totals.relates_edges, totals.mentions_edges, db.count_nodes(),
+        )
+    finally:
+        db.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/ingest_kaggle_jira.py

@@ -0,0 +1,163 @@
+"""Batch-ingest a Jira CSV export into the TraceRAG graph.
+
+    python scripts/ingest_kaggle_jira.py --file datasets/GFG_FINAL.csv --limit 100
+    python scripts/ingest_kaggle_jira.py --file datasets/GFG_FINAL.csv --reset
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import re
+import sys
+from pathlib import Path
+
+import pandas as pd
+from tqdm import tqdm
+
+_SCRIPTS = Path(__file__).resolve().parent
+sys.path.insert(0, str(_SCRIPTS.parent))
+sys.path.insert(0, str(_SCRIPTS))
+
+from tracerag import config                       # noqa: E402
+from tracerag.db import TraceDB                    # noqa: E402
+from tracerag.extract import EntityExtractor       # noqa: E402
+from tracerag.curation import CurationEngine, IngestStats  # noqa: E402
+from ingest import ingest_text                     # noqa: E402
+
+logger = logging.getLogger("tracerag.kaggle")
+
+# pandas suffixes repeated columns with .1/.2/... in wide exports
+_COMPONENT_COLS = ["Component/s", "Component/s.1", "Component/s.2", "Component/s.3"]
+_LABEL_COLS = ["Labels"] + [f"Labels.{i}" for i in range(1, 7)]
+
+
+_CODE_BLOCK = re.compile(r"\{code(:[^}]*)?\}.*?\{code\}", re.DOTALL | re.IGNORECASE)
+_NOFORMAT = re.compile(r"\{noformat\}.*?\{noformat\}", re.DOTALL | re.IGNORECASE)
+_HTML_TAG = re.compile(r"<[^>]+>")
+_MD_LINK = re.compile(r"\[([^\]]+)\]\([^)]+\)")    # [text](url) -> text
+_JIRA_LINK = re.compile(r"\[([^|\]]+)\|[^\]]+\]")  # [text|url]  -> text
+_BRACE_MACRO = re.compile(r"\{[^}]*\}")            # leftover {quote}/{panel}/{color}
+_URL = re.compile(r"https?://\S+")
+_WS = re.compile(r"\s+")
+
+
+def clean_jira_text(raw: str) -> str:
+    """Strip HTML, markdown/Jira links, {code}/{noformat}/{macro} blocks and URLs."""
+    if not raw:
+        return ""
+    t = _CODE_BLOCK.sub(" ", raw)
+    t = _NOFORMAT.sub(" ", t)
+    t = _HTML_TAG.sub(" ", t)
+    t = _MD_LINK.sub(r"\1", t)
+    t = _JIRA_LINK.sub(r"\1", t)
+    t = _BRACE_MACRO.sub(" ", t)
+    t = _URL.sub(" ", t)
+    return _WS.sub(" ", t).strip()
+
+
+def _combine(row: pd.Series, cols: list[str]) -> str:
+    """Join distinct, non-empty values from a set of (possibly repeated) columns."""
+    seen, out = set(), []
+    for c in cols:
+        v = str(row.get(c, "")).strip()
+        if v and v.lower() != "nan" and v not in seen:
+            seen.add(v)
+            out.append(v)
+    return ", ".join(out)
+
+
+def assemble_text(row: pd.Series) -> tuple[str, str]:
+    """Build (doc_id, clean text blob) the existing pipeline can parse."""
+    def f(col: str) -> str:
+        v = str(row.get(col, "")).strip()
+        return "" if v.lower() == "nan" else v
+
+    key = f("Issue key")
+    parts: list[str] = []
+    summary = f("Summary")
+    if key or summary:
+        parts.append(f"Ticket {key}: {summary}.".strip())
+    for label, col in (("Type", "Issue Type"), ("Status", "Status"),
+                       ("Priority", "Priority"), ("Project", "Project name")):
+        if f(col):
+            parts.append(f"{label}: {f(col)}.")
+    if f("Assignee"):
+        parts.append(f"Assigned to {f('Assignee')}.")
+    if f("Reporter"):
+        parts.append(f"Reported by {f('Reporter')}.")
+    components = _combine(row, _COMPONENT_COLS)
+    if components:
+        parts.append(f"Component: {components}.")
+    labels = _combine(row, _LABEL_COLS)
+    if labels:
+        parts.append(f"Labels: {labels}.")
+    desc = clean_jira_text(f("Description"))
+    if desc:
+        parts.append(f"Description: {desc}")
+    return key, " ".join(parts)
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Ingest a Jira CSV export into TraceRAG.")
+    p.add_argument("--file", type=Path, required=True, help="Path to the Jira CSV.")
+    p.add_argument("--limit", type=int, default=None,
+                   help="Ingest only the first N rows (for quick tests).")
+    p.add_argument("--db", type=Path, default=config.DB_PATH)
+    p.add_argument("--reset", action="store_true",
+                   help="Delete the existing .lbug (+ sidecars) before ingesting.")
+    p.add_argument("-v", "--verbose", action="store_true")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s  %(levelname)-7s %(name)s  %(message)s",
+    )
+    for noisy in ("httpx", "httpcore", "openai", "sentence_transformers"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    if args.reset:
+        for p in sorted(args.db.parent.glob(args.db.name + "*")):
+            logger.info("Reset: removing %s", p)
+            p.unlink()
+
+    logger.info("Reading %s", args.file)
+    df = pd.read_csv(args.file, low_memory=False).fillna("")
+    if args.limit:
+        df = df.head(args.limit)
+    logger.info("Loaded %d rows, %d columns", len(df), df.shape[1])
+
+    extractor = EntityExtractor()
+    db = TraceDB(args.db)
+    db.init_schema()
+    engine = CurationEngine(db)
+
+    totals = IngestStats()
+    skipped = 0
+    try:
+        for i, row in tqdm(df.iterrows(), total=len(df), desc="ingesting jira", unit="ticket"):
+            doc_id, text = assemble_text(row)
+            if not text.strip():
+                skipped += 1
+                continue
+            totals.merge(ingest_text(engine, extractor, doc_id or f"row-{i}", text))
+
+        db.build_vector_index()
+        logger.info(
+            "Done. %d rows ingested (%d skipped) | %d entities | "
+            "created=%d fast=%d deep_yes=%d deep_no=%d llm=%d | "
+            "rel=%d mentions=%d | nodes_in_db=%d",
+            totals.docs, skipped, totals.entities, totals.created, totals.fast_merged,
+            totals.deep_merged_yes, totals.deep_merged_no, totals.ollama_calls,
+            totals.relates_edges, totals.mentions_edges, db.count_nodes(),
+        )
+    finally:
+        db.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/profile_route.py

@@ -0,0 +1,74 @@
+"""Profile TraceRouter.route() latency phase-by-phase.
+
+    python scripts/profile_route.py --db graphs/pallets__flask.lbug
+    python scripts/profile_route.py --db graphs/pydantic__pydantic.lbug -q "what changed in validation"
+
+LadybugDB is single-writer, so point --db at a graph the running server isn't serving.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from tracerag.db import TraceDB           # noqa: E402
+from tracerag.router import TraceRouter   # noqa: E402
+
+# mix of marker and keyword-less queries to exercise both LLM and LLM-free phases
+DEFAULT_QUERIES = [
+    "who reviewed the async changes",        # relational marker -> no intent LLM
+    "what did the maintainers work on",      # keyword-less -> intent LLM fires
+    "explain the recent changes",            # semantic marker -> no intent LLM
+]
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Profile route() latency per phase.")
+    p.add_argument("--db", type=Path, default=Path("graphs/pallets__flask.lbug"))
+    p.add_argument("-q", "--query", action="append",
+                   help="Query to run (repeatable). Defaults to a built-in mix.")
+    p.add_argument("--top-k", type=int, default=10)
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    for noisy in ("httpx", "httpcore", "openai", "sentence_transformers",
+                  "numexpr.utils", "gliner", "sentence_transformers.SentenceTransformer"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    try:
+        db = TraceDB(args.db)
+    except Exception as exc:  # noqa: BLE001
+        print(f"[profile] could not open {args.db}: {exc}")
+        print("[profile] is the uvicorn server serving this same graph? "
+              "Point --db at a different graphs/*.lbug or stop the server.")
+        return 1
+
+    router = TraceRouter(db)
+    print(f"[profile] db={args.db}  nodes={db.count_nodes()}")
+    print("[profile] warming embedder (one-time model load)...")
+    t = time.perf_counter()
+    router.embed_query("warmup")
+    print(f"[profile] embedder warm in {(time.perf_counter() - t) * 1000:.0f} ms\n")
+
+    queries = args.query or DEFAULT_QUERIES
+    try:
+        for q in queries:
+            t = time.perf_counter()
+            resp = router.route(q, top_k=args.top_k)
+            wall = (time.perf_counter() - t) * 1000
+            print(f"  >> '{q}'  wall={wall:.0f} ms, {len(resp.results)} results\n")
+    finally:
+        db.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/ratelimit_test.py

@@ -0,0 +1,186 @@
+"""Burst test that verifies the slowapi per-user rate limit on /api/answer.
+
+Unlike scripts/stress_test.py (which THROTTLES with a semaphore to measure
+graceful degradation), this script does the opposite: it fires every request at
+the *same instant* -- a thundering herd -- to prove the limiter admits exactly N
+and blocks the rest in a single fixed window.
+
+    Expected for --burst 25 --limit 10:  10 x HTTP 200  +  15 x HTTP 429
+
+------------------------------------------------------------------------------
+HOW TO RUN
+------------------------------------------------------------------------------
+1. The server MUST run single-worker (uvicorn's default). slowapi's in-memory
+   counter is per-process; with --workers N the burst is split across N
+   independent buckets and far more than `limit` requests pass. So:
+
+       uvicorn api:app --port 8000            # (no --workers flag)
+
+2. Mode B -- dev-bypass (DEFAULT, for CI): leave CLERK_ISSUER unset on the
+   server. Every request maps to the synthetic 'dev-user', so all 25 share one
+   bucket. No token needed:
+
+       python scripts/ratelimit_test.py
+
+3. Mode A -- real Clerk JWT (manual end-to-end check): grab a fresh session
+   token from the browser (it's short-lived, ~60s) and pass it:
+
+       python scripts/ratelimit_test.py --token "eyJhbGci..."
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import time
+from collections import Counter
+
+import aiohttp
+
+
+async def _fire(
+    session: aiohttp.ClientSession,
+    url: str,
+    payload: dict,
+    timeout: float,
+    start_gun: asyncio.Event,
+    idx: int,
+) -> dict:
+    """One request that waits at the barrier, then fires the instant it opens.
+
+    The `await start_gun.wait()` is the concurrency barrier: every worker parks
+    here until the main coroutine fires the starting gun, so all `burst` requests
+    leave the line on the SAME event-loop tick instead of trickling out as each
+    task gets scheduled. That true simultaneity is what makes this a real burst
+    test of the fixed window (a semaphore would serialize them and hide the seam).
+    """
+    await start_gun.wait()
+    t0 = time.perf_counter()
+    try:
+        # NOTE: aiohttp does NOT raise on 4xx/5xx unless raise_for_status=True,
+        # which we deliberately omit -- a 429 is the EXPECTED result here, not an
+        # error. We just read the status code off the response.
+        async with session.post(url, json=payload, timeout=timeout) as resp:
+            await resp.read()  # drain the body so the connection is freed
+            return {"idx": idx, "status": resp.status,
+                    "latency": time.perf_counter() - t0}
+    except asyncio.TimeoutError:
+        # graceful: a slow/blocked request becomes a recorded outcome, not a crash
+        return {"idx": idx, "status": "timeout",
+                "latency": time.perf_counter() - t0}
+    except aiohttp.ClientError as exc:
+        return {"idx": idx, "status": f"error:{type(exc).__name__}",
+                "latency": time.perf_counter() - t0}
+
+
+async def run(url: str, token: str | None, burst: int, limit: int,
+              timeout: float) -> bool:
+    """Fire `burst` simultaneous requests; return True if the limit held exactly."""
+    # --- identity: one token (or dev-bypass) => one rate-limit bucket ---
+    headers: dict[str, str] = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+        mode = "Mode A -- real Clerk JWT (--token)"
+    else:
+        # No header -> server runs every request as the synthetic 'dev-user',
+        # so the whole burst still shares ONE bucket. Perfect for CI.
+        mode = "Mode B -- dev-bypass (synthetic 'dev-user', no token)"
+
+    # Empty context deliberately: /api/answer returns 200 instantly for empty
+    # context WITHOUT calling the LLM. The rate-limit decorator runs BEFORE the
+    # endpoint body, so the 429s still fire -- we prove the limiter for zero LLM
+    # cost. (Set a real context only if you want to exercise the answer path.)
+    payload = {"query": "rate-limit burst probe", "context": ""}
+
+    expected_pass = limit
+    expected_block = burst - limit
+
+    print(f"Bursting {burst} simultaneous requests at {url}")
+    print(f"  {mode}")
+    print(f"  expecting {expected_pass} x 200 and {expected_block} x 429\n")
+    print("  [!] Server MUST be single-worker (uvicorn default, NO --workers N)")
+    print("      - slowapi's in-memory bucket is per-process; multiple workers")
+    print("      mean multiple buckets and more than `limit` requests pass.\n")
+
+    start_gun = asyncio.Event()
+
+    async with aiohttp.ClientSession(headers=headers) as session:
+        # Create all tasks first. Each immediately parks on `start_gun.wait()`.
+        tasks = [
+            asyncio.create_task(_fire(session, url, payload, timeout, start_gun, i))
+            for i in range(burst)
+        ]
+        # Yield control so EVERY task gets scheduled and reaches the barrier
+        # before we fire. Without this beat, set() could race ahead of tasks
+        # that haven't hit `await start_gun.wait()` yet.
+        await asyncio.sleep(0.1)
+
+        wall_start = time.perf_counter()
+        start_gun.set()                      # FIRE: all `burst` requests go now
+        results = await asyncio.gather(*tasks)
+        wall = time.perf_counter() - wall_start
+
+    # --- tally outcomes ---
+    statuses = Counter(r["status"] for r in results)
+    n_200 = statuses.get(200, 0)
+    n_429 = statuses.get(429, 0)
+    lat = sorted(r["latency"] for r in results)
+
+    print("=" * 60)
+    print(f"{'Status / outcome':<28}{'count':>10}")
+    print("-" * 60)
+    for status, n in sorted(statuses.items(), key=lambda kv: str(kv[0])):
+        print(f"{str(status):<28}{n:>10}")
+    print("-" * 60)
+    print(f"wall time            {wall:>8.3f}s")
+    print(f"200 (admitted)       {n_200:>8} / expected {expected_pass}")
+    print(f"429 (blocked)        {n_429:>8} / expected {expected_block}")
+    if lat:
+        print(f"latency min/max      {lat[0]:.3f} / {lat[-1]:.3f} s")
+    print("=" * 60)
+
+    # --- verdict ---
+    passed = (n_200 == expected_pass and n_429 == expected_block)
+    if passed:
+        print(f"\n[PASS] Limiter held exactly: {expected_pass}x200, "
+              f"{expected_block}x429. The 429 path is working.")
+        return True
+
+    print("\n[FAIL] Counts did not match. Likely causes, in order:")
+    # Diagnostics ranked by how often each is the real culprit.
+    if n_200 > expected_pass:
+        print(f"  - {n_200} passed (> {expected_pass}). Either the server is "
+              f"running MULTIPLE WORKERS (each with its own in-memory bucket),")
+        print(f"    or -- far less likely at this speed -- the burst straddled a "
+              f"60s fixed-window boundary. Re-run; if it persists it's workers.")
+    if any(str(s).startswith(("error", "timeout")) for s in statuses):
+        print("  - Hard failures (timeout/conn-error) present -- is the server up "
+              "at this URL, and is the timeout high enough?")
+    if n_200 == 0 and n_429 == 0:
+        print("  - Nothing got through at all -- check the URL and that the API "
+              "is actually listening.")
+    if n_429 == 0 and n_200 < burst:
+        print("  - No 429s seen -- is slowapi actually wired (app.state.limiter + "
+              "@limiter.limit on /api/answer)?")
+    return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Verify the per-user rate limit on /api/answer.")
+    p.add_argument("--url", default="http://127.0.0.1:8000/api/answer")
+    p.add_argument("--token", default=None,
+                   help="Clerk JWT for Mode A; omit for Mode B dev-bypass.")
+    p.add_argument("--burst", type=int, default=25,
+                   help="total simultaneous requests (default 25)")
+    p.add_argument("--limit", type=int, default=10,
+                   help="the server's per-minute cap, i.e. expected 200s (default 10)")
+    p.add_argument("--timeout", type=float, default=30.0)
+    args = p.parse_args(argv)
+
+    ok = asyncio.run(run(args.url, args.token, args.burst, args.limit, args.timeout))
+    # exit code 0 on PASS, 1 on FAIL -- so CI (GitHub Actions) fails the job loudly.
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/stress_graph.py

@@ -0,0 +1,225 @@
+# -*- coding: utf-8 -*-
+"""Direct stress test of the GraphRAG retrieval core against ONE graph.
+
+Hammers TraceRouter.route() concurrently (no HTTP, no auth, no answer-LLM) with
+a battery of valid + adversarial + fuzz queries to surface crashes, injection
+issues, encoding bugs, latency outliers, thread-safety problems, and correctness
+regressions on a new graph before it goes on camera.
+
+    python scripts/stress_graph.py --db graphs/apache__kafka.lbug \
+        --iterations 400 --concurrency 16
+
+Hermetic: the intent-classifier LLM fallback is stubbed, so no billed calls and
+no network — what's measured is purely vector + graph retrieval over the graph.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+import traceback
+from collections import Counter, defaultdict
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from tracerag import config                     # noqa: E402
+from tracerag.db import TraceDB                  # noqa: E402
+from tracerag.router import TraceRouter          # noqa: E402
+
+# (label, query, category, expect_hits)
+#   valid    -> must return results; we also spot-check correctness
+#   offdomain-> should gracefully return few/none, never crash
+#   fuzz     -> must NOT crash; result count irrelevant
+BATTERY: list[tuple[str, str, str, bool]] = [
+    # --- valid relational (the real demo questions) ---
+    ("hero",        "What is related to KAFKA-20688?", "valid", True),
+    ("ticket2",     "What is related to KAFKA-20570?", "valid", True),
+    ("person1",     "What did Matthias J. Sax work on?", "valid", True),
+    ("person2",     "What did Alieh Saeedi work on?", "valid", True),
+    ("person_acc",  "What did José Armando García Sancio work on?", "valid", True),
+    ("lib1",        "What is connected to Kafka Streams?", "valid", True),
+    ("lib2",        "What is related to streams?", "valid", True),
+    ("kip",         "What is KIP-1301 about?", "valid", True),
+    # --- semantic (intent stubbed, exercises vector arm) ---
+    ("sem1",        "Explain the recent RocksDB state-store changes.", "valid", True),
+    ("sem2",        "How does Kafka handle exactly-once semantics?", "valid", True),
+    # --- off-domain: should degrade gracefully ---
+    ("off1",        "How does the payment gateway handle refunds?", "offdomain", False),
+    ("off2",        "Best recipe for sourdough bread", "offdomain", False),
+    ("off3",        "What is the capital of France?", "offdomain", False),
+    # --- fuzz / adversarial: must not crash ---
+    ("empty",       "", "fuzz", False),
+    ("spaces",      "          ", "fuzz", False),
+    ("one_char",    "a", "fuzz", False),
+    ("digits",      "1234567890", "fuzz", False),
+    ("emoji",       "🔥🔥 what is related to streams 🔥🔥", "fuzz", False),
+    ("accents",     "Què està relacionat amb José Armando García Sancio?", "fuzz", False),
+    ("cypher_inj",  "x'); MATCH (n) DETACH DELETE n; //", "fuzz", False),
+    ("sql_inj",     "Robert'); DROP TABLE Entity;-- ", "fuzz", False),
+    ("tmpl_inj",    "{{7*7}} ${jndi:ldap://x} <script>alert(1)</script>", "fuzz", False),
+    ("path_trav",   "../../../../etc/passwd related to KAFKA", "fuzz", False),
+    ("nullbyte",    "KAFKA-20688\x00\x00 related to", "fuzz", False),
+    ("ctrl_chars",  "rel\tated\r\n to\x07 streams", "fuzz", False),
+    ("very_long",   ("KAFKA related to streams " * 2000), "fuzz", False),
+    ("unicode_zw",  "what​ is​ related​ to​ streams", "fuzz", False),
+    ("quotes",      "\"'`related`'\" to 'streams'", "fuzz", False),
+]
+
+
+def stub_intent(router: TraceRouter) -> None:
+    """Make intent classification hermetic: never hit the network/LLM."""
+    w = config.ROUTER_WEIGHTS_CONCEPTUAL
+    router._classify_intent_llm = lambda q: (w["vector"], w["graph"], "semantic")
+
+
+def correctness_checks(router: TraceRouter, log: list[str]) -> int:
+    """Single-threaded spot-checks. Returns number of FAILURES."""
+    fails = 0
+    resp = router.route("What is related to KAFKA-20688?")
+    labels = {(r.label or "") for r in resp.results}
+    log.append("hero result labels: " + repr(sorted(l for l in labels if l)[:15]))
+    if "KAFKA-20688" not in labels:
+        log.append("  FAIL: hero query did not surface KAFKA-20688 itself")
+        fails += 1
+    # at least one real human / component neighbor should ride along
+    if len(resp.results) < 3:
+        log.append("  FAIL: hero query returned < 3 results (%d)" % len(resp.results))
+        fails += 1
+
+    resp2 = router.route("What did Matthias J. Sax work on?")
+    if not resp2.results:
+        log.append("  FAIL: person query returned 0 results")
+        fails += 1
+
+    # accented name must round-trip with no replacement char
+    resp3 = router.route("What did José Armando García Sancio work on?")
+    joined = " ".join((r.label or "") for r in resp3.results)
+    if "�" in joined:
+        log.append("  FAIL: accented-name query produced U+FFFD in results")
+        fails += 1
+    log.append("correctness failures: %d" % fails)
+    return fails
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Direct GraphRAG retrieval stress test.")
+    p.add_argument("--db", type=Path, default=Path("graphs/apache__kafka.lbug"))
+    p.add_argument("--iterations", type=int, default=400)
+    p.add_argument("--concurrency", type=int, default=16)
+    p.add_argument("--timeout", type=float, default=20.0, help="Per-call soft budget (s).")
+    args = p.parse_args(argv)
+
+    if not args.db.exists():
+        print("ERROR: graph not found:", args.db)
+        return 2
+
+    print("Loading %s ..." % args.db)
+    db = TraceDB(args.db)
+    db.init_schema()
+    router = TraceRouter(db)
+    stub_intent(router)
+    try:
+        router.warm()
+    except Exception as exc:  # noqa: BLE001
+        print("warm() skipped:", exc)
+
+    log: list[str] = []
+    print("Running correctness checks ...")
+    corr_fails = correctness_checks(router, log)
+
+    n = args.iterations
+    jobs = [BATTERY[i % len(BATTERY)] for i in range(n)]
+
+    lat_by_cat: dict[str, list[float]] = defaultdict(list)
+    empty_by_cat: dict[str, int] = defaultdict(int)
+    errors: list[tuple[str, str, str]] = []   # (category, query[:60], traceback-last-line)
+    slow: list[tuple[float, str]] = []
+    statuses: Counter = Counter()
+
+    def one(job: tuple[str, str, str, bool]) -> dict:
+        _label, query, cat, _expect = job
+        t0 = time.perf_counter()
+        try:
+            resp = router.route(query)
+            dt = time.perf_counter() - t0
+            return {"cat": cat, "dt": dt, "n": len(resp.results), "query": query, "err": None}
+        except Exception:  # noqa: BLE001 — capture, don't abort the run
+            dt = time.perf_counter() - t0
+            tb = traceback.format_exc().strip().splitlines()[-1]
+            return {"cat": cat, "dt": dt, "n": -1, "query": query, "err": tb}
+
+    print("Hammering: %d calls, concurrency=%d ...\n" % (n, args.concurrency))
+    wall0 = time.perf_counter()
+    with ThreadPoolExecutor(max_workers=args.concurrency) as pool:
+        futs = [pool.submit(one, j) for j in jobs]
+        for f in as_completed(futs):
+            r = f.result()
+            if r["err"]:
+                statuses["error"] += 1
+                errors.append((r["cat"], r["query"][:60], r["err"]))
+            else:
+                statuses["ok"] += 1
+                lat_by_cat[r["cat"]].append(r["dt"])
+                if r["n"] == 0:
+                    empty_by_cat[r["cat"]] += 1
+                if r["dt"] > args.timeout:
+                    slow.append((r["dt"], r["query"][:60]))
+    wall = time.perf_counter() - wall0
+
+    all_lat = sorted(v for vs in lat_by_cat.values() for v in vs)
+
+    def pct(pp: float) -> float:
+        return all_lat[min(len(all_lat) - 1, int(len(all_lat) * pp))] if all_lat else 0.0
+
+    # ---- write full detail (UTF-8) ----
+    detail = list(log)
+    detail.append("")
+    detail.append("=== latency by category (count, p50, p90, max) ===")
+    for cat, vs in sorted(lat_by_cat.items()):
+        s = sorted(vs)
+        detail.append("  %-10s n=%-4d p50=%.3f p90=%.3f max=%.3f empty=%d" % (
+            cat, len(s), s[len(s)//2], s[min(len(s)-1, int(len(s)*0.9))], s[-1],
+            empty_by_cat.get(cat, 0)))
+    detail.append("")
+    detail.append("=== errors (%d) ===" % len(errors))
+    for cat, q, tb in errors[:40]:
+        detail.append("  [%s] %r -> %s" % (cat, q, tb))
+    Path("scripts/_stress_graph.out.txt").write_text("\n".join(detail), encoding="utf-8")
+
+    # ---- console summary (ASCII-safe) ----
+    bar = "=" * 60
+    print(bar)
+    print("STRESS SUMMARY  db=%s" % args.db.name)
+    print(bar)
+    print("calls            %d (ok=%d, error=%d)" % (n, statuses["ok"], statuses["error"]))
+    print("wall time        %.2fs   throughput %.0f calls/s" % (wall, n / wall if wall else 0))
+    print("latency p50/p90  %.3f / %.3f s" % (pct(.5), pct(.9)))
+    print("latency p99/max  %.3f / %.3f s" % (pct(.99), all_lat[-1] if all_lat else 0))
+    print("correctness      %s (%d failures)" % ("PASS" if corr_fails == 0 else "FAIL", corr_fails))
+    print("empty results    valid=%d offdomain=%d fuzz=%d" % (
+        empty_by_cat.get("valid", 0), empty_by_cat.get("offdomain", 0),
+        empty_by_cat.get("fuzz", 0)))
+    print("slow (> %.0fs)     %d" % (args.timeout, len(slow)))
+    print(bar)
+
+    hard_fail = statuses["error"] > 0 or corr_fails > 0 or empty_by_cat.get("valid", 0) > 0
+    if statuses["error"]:
+        print("\n[!] %d calls threw exceptions (crash/injection/thread-safety):" % statuses["error"])
+        for cat, q, tb in errors[:8]:
+            print("    [%s] %r" % (cat, q))
+            print("        %s" % tb)
+    if empty_by_cat.get("valid", 0):
+        print("\n[!] %d VALID demo queries returned ZERO results -- not demo-safe."
+              % empty_by_cat["valid"])
+    if not hard_fail:
+        print("\n[ok] No crashes. Correctness passed. Every valid query returned hits.")
+        print("     Fuzz/injection inputs degraded gracefully (no exceptions).")
+    print("\nFull detail -> scripts/_stress_graph.out.txt")
+    db.close()
+    return 1 if hard_fail else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/stress_test.py

@@ -0,0 +1,93 @@
+"""Async load test for the TraceRAG FastAPI endpoint.
+
+Start the API first (uvicorn api:app --port 8000), then:
+
+    python scripts/stress_test.py --requests 200 --concurrency 25
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import time
+from collections import Counter
+
+import aiohttp
+
+QUERIES = [
+    "What was incident INC-4471 about?",
+    "What is the responsibility of the PaymentService?",
+    "Who is the tech lead and owning team for PaymentService?",
+    "What does payment-service depend on?",
+    "How does the AuthLayer handle login and JWT issuance?",
+    "Explain the ShopFlow commerce platform architecture.",
+    "What is related to PR #847?",
+    "Which component was affected in incident INC-4480?",
+]
+
+
+async def _one(session, url, query, sem, timeout) -> dict:
+    async with sem:
+        start = time.perf_counter()
+        try:
+            async with session.post(url, json={"query": query}, timeout=timeout) as resp:
+                await resp.read()  # drain
+                return {"status": resp.status, "latency": time.perf_counter() - start}
+        except asyncio.TimeoutError:
+            return {"status": "timeout", "latency": time.perf_counter() - start}
+        except aiohttp.ClientError as exc:
+            return {"status": f"error:{type(exc).__name__}", "latency": time.perf_counter() - start}
+
+
+async def run(url: str, total: int, concurrency: int, timeout: float) -> None:
+    sem = asyncio.Semaphore(concurrency)
+    print(f"Hammering {url}\n  {total} requests, concurrency={concurrency}, "
+          f"timeout={timeout}s\n")
+    wall_start = time.perf_counter()
+    async with aiohttp.ClientSession() as session:
+        tasks = [
+            _one(session, url, QUERIES[i % len(QUERIES)], sem, timeout)
+            for i in range(total)
+        ]
+        results = await asyncio.gather(*tasks)
+    wall = time.perf_counter() - wall_start
+
+    statuses = Counter(r["status"] for r in results)
+    ok = [r["latency"] for r in results if r["status"] == 200]
+    lat = sorted(r["latency"] for r in results)
+
+    def pct(p: float) -> float:
+        return lat[min(len(lat) - 1, int(len(lat) * p))] if lat else 0.0
+
+    print("=" * 60)
+    print(f"{'Status / outcome':<28}{'count':>10}")
+    print("-" * 60)
+    for status, n in sorted(statuses.items(), key=lambda kv: str(kv[0])):
+        print(f"{str(status):<28}{n:>10}")
+    print("-" * 60)
+    print(f"wall time            {wall:>8.2f}s")
+    print(f"throughput           {total / wall:>8.1f} req/s")
+    print(f"success (200)        {len(ok):>8} / {total}")
+    print(f"latency p50/p90/p99  {pct(.5):.3f} / {pct(.9):.3f} / {pct(.99):.3f} s")
+    print(f"latency max          {(lat[-1] if lat else 0):.3f} s")
+    print("=" * 60)
+    if any(str(s).startswith(("error", "timeout")) or s in (500, 502) for s in statuses):
+        print("\n[!] Hard failures present (5xx/timeout/conn-error): the worker may "
+              "not be degrading gracefully — check for crashes or DB read-locks.")
+    if statuses.get(429) or statuses.get(503):
+        print("\n[ok] Server shed load with 429/503 under pressure (graceful).")
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="TraceRAG async load test.")
+    p.add_argument("--url", default="http://127.0.0.1:8000/api/trace")
+    p.add_argument("--requests", type=int, default=100)
+    p.add_argument("--concurrency", type=int, default=20)
+    p.add_argument("--timeout", type=float, default=30.0)
+    args = p.parse_args(argv)
+    asyncio.run(run(args.url, args.requests, args.concurrency, args.timeout))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tracerag/__init__.py

@@ -0,0 +1,3 @@
+"""Local-first GraphRAG curation and debugging layer."""
+
+__version__ = "0.1.0"

tracerag/config.py

@@ -0,0 +1,155 @@
+"""Central configuration for TraceRAG."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# load local .env if present; real env vars still win
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv(PROJECT_ROOT / ".env")
+except ImportError:
+    pass
+
+DB_PATH = Path(os.getenv("TRACERAG_DB_PATH", PROJECT_ROOT / "memory.lbug"))
+DATASETS_DIR = Path(os.getenv("TRACERAG_DATASETS_DIR", PROJECT_ROOT / "datasets"))
+RESULTS_CSV = Path(os.getenv("TRACERAG_RESULTS_CSV", PROJECT_ROOT / "results.csv"))
+
+
+EMBED_MODEL = os.getenv("TRACERAG_EMBED_MODEL", "all-MiniLM-L6-v2")
+EMBED_DIM = 384  # must match the FLOAT[384] schema column
+
+# Concurrency: LadybugDB parallelizes reads across connections (it releases the
+# GIL in C++), so a small pool of read connections removes the single-connection
+# convoy seen under load. Writes stay on one dedicated connection (single-writer).
+DB_POOL_SIZE = int(os.getenv("TRACERAG_DB_POOL_SIZE", "10"))
+DB_POOL_TIMEOUT = float(os.getenv("TRACERAG_DB_POOL_TIMEOUT", "15"))  # s to wait for a free conn
+# Embedding is CPU-heavy; bound concurrent encodes so they can't starve request
+# threads. torch releases the GIL during encode, so threads (not processes) suffice.
+EMBED_WORKERS = int(os.getenv("TRACERAG_EMBED_WORKERS", "4"))
+# Query-side entity extraction (spaCy) is GIL-bound; cache results so repeated
+# queries skip it. 0 disables (ingest path). Bounded LRU — no unbounded growth.
+QUERY_EXTRACT_CACHE = int(os.getenv("TRACERAG_QUERY_EXTRACT_CACHE", "512"))
+# Cap query length before retrieval. spaCy work grows with input size, so an
+# oversized query is a CPU-DoS (a 50 KB query stalled a worker for ~90s in
+# testing). Real questions are short; truncate the rest. Guards embed + extract.
+MAX_QUERY_CHARS = int(os.getenv("TRACERAG_MAX_QUERY_CHARS", "2000"))
+
+# CORS allow-list. "*" (default) accepts any origin — fine for local/dev. In
+# production set CORS_ORIGINS to your frontend origin(s), comma-separated,
+# e.g. "https://tracerag.vercel.app".
+CORS_ORIGINS = [
+    o.strip() for o in os.getenv("CORS_ORIGINS", "*").split(",") if o.strip()
+] or ["*"]
+
+# Sentry error tracking + performance monitoring. Fully optional: unset DSN =
+# disabled, so local/dev runs are untouched. traces_sample_rate is 1.0 (trace
+# everything) in dev; scale down in production (e.g. 0.1) to cap overhead/cost.
+SENTRY_DSN = os.getenv("SENTRY_DSN")
+SENTRY_ENABLED = bool(SENTRY_DSN)
+SENTRY_ENVIRONMENT = os.getenv("SENTRY_ENVIRONMENT", "development")
+SENTRY_TRACES_SAMPLE_RATE = float(os.getenv("SENTRY_TRACES_SAMPLE_RATE", "1.0"))
+
+
+OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")
+OPENROUTER_BASE_URL = os.getenv("OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1")
+OPENROUTER_MODEL = os.getenv("OPENROUTER_MODEL", "anthropic/claude-3-haiku")
+OPENROUTER_SITE_URL = os.getenv("OPENROUTER_SITE_URL",
+                                "https://github.com/Kcodess2807/TraceRAG")
+OPENROUTER_APP_TITLE = os.getenv("OPENROUTER_APP_TITLE", "TraceRAG")
+
+# groq for the latency-critical router intent call; falls back to openrouter if unset
+GROQ_API_KEY = os.getenv("GROQ_API_KEY")
+GROQ_BASE_URL = os.getenv("GROQ_BASE_URL", "https://api.groq.com/openai/v1")
+GROQ_MODEL = os.getenv("GROQ_MODEL", "llama-3.1-8b-instant")
+
+
+# --- Clerk auth (backend token verification) ---
+# CLERK_ISSUER is your Clerk instance URL, e.g. https://your-app.clerk.accounts.dev
+# (production: your custom Clerk domain). Leave it UNSET for local dev and the API
+# runs in dev-bypass mode — no token required. Set it and auth is enforced.
+CLERK_ISSUER = os.getenv("CLERK_ISSUER")
+# JWKS = Clerk's published public keys. Defaults to the standard well-known path
+# under the issuer; override only if you proxy it somewhere else.
+CLERK_JWKS_URL = os.getenv("CLERK_JWKS_URL") or (
+    f"{CLERK_ISSUER.rstrip('/')}/.well-known/jwks.json" if CLERK_ISSUER else None
+)
+# Optional allow-list of authorized parties (the `azp` claim = the frontend
+# origin a token was minted for). Comma-separated, e.g. "http://localhost:5173".
+CLERK_AUTHORIZED_PARTIES = tuple(
+    p.strip()
+    for p in os.getenv("CLERK_AUTHORIZED_PARTIES", "").split(",")
+    if p.strip()
+)
+# Auth is enforced only when an issuer is configured.
+CLERK_ENABLED = bool(CLERK_ISSUER)
+# The user id every request runs as in dev-bypass mode (Clerk unconfigured).
+DEV_USER_ID = os.getenv("TRACERAG_DEV_USER_ID", "dev-user")
+
+
+# two-tier curation thresholds (cosine sim): >=fast auto-merge, >=deep ask llm, else new node
+FAST_MERGE_THRESHOLD = float(os.getenv("TRACERAG_FAST_MERGE", "0.92"))
+DEEP_MERGE_THRESHOLD = float(os.getenv("TRACERAG_DEEP_MERGE", "0.85"))
+GREY_ZONE_LOW = DEEP_MERGE_THRESHOLD  # backward-compat alias
+
+CURATION_TOP_K = int(os.getenv("TRACERAG_CURATION_TOP_K", "5"))
+
+
+# hybrid router weights (vector + graph = 1)
+ROUTER_WEIGHTS_CONCEPTUAL = {"vector": 0.80, "graph": 0.20}
+ROUTER_WEIGHTS_RELATIONAL = {"vector": 0.15, "graph": 0.85}
+
+RELATIONAL_QUERY_MARKERS = (
+    "who", "whom", "whose", "which", "what caused", "caused by", "because of",
+    "related to", "connected to", "depends on", "owns", "owned by", "between",
+    "path from", "linked to", "responsible for", "which pr", "which ticket",
+)
+
+SEMANTIC_QUERY_MARKERS = (
+    "explain", "architecture", "overview", "summary", "summarise", "summarize",
+    "describe", "what is", "how does", "concept", "definition", "purpose of",
+)
+
+TOP_K_VECTOR = int(os.getenv("TRACERAG_TOP_K_VECTOR", "10"))
+TOP_K_GRAPH = int(os.getenv("TRACERAG_TOP_K_GRAPH", "10"))
+
+GRAPH_SEED_TOP_N = int(os.getenv("TRACERAG_GRAPH_SEED_TOP_N", "3"))
+GRAPH_SEED_MIN_SIM = float(os.getenv("TRACERAG_GRAPH_SEED_MIN_SIM", "0.35"))
+GRAPH_NEIGHBOR_K = int(os.getenv("TRACERAG_GRAPH_NEIGHBOR_K", "5"))
+GRAPH_MAX_HOPS = int(os.getenv("TRACERAG_GRAPH_MAX_HOPS", "2"))
+MAX_DEGREE = int(os.getenv("TRACERAG_MAX_DEGREE", "10"))  # skip hub nodes above this degree
+
+
+GLINER_MODEL = os.getenv("TRACERAG_GLINER_MODEL", "urchade/gliner_medium-v2.1")
+SPACY_MODEL = os.getenv("TRACERAG_SPACY_MODEL", "en_core_web_sm")
+
+ENTITY_LABELS = ["Person", "Service", "Library", "Ticket", "PR", "Team", "Tool"]
+
+# spaCy fallback over-extracts, so allow/block lists keep only high-signal labels
+SPACY_ALLOWED_LABELS = ("PERSON", "ORG", "PRODUCT", "GPE",
+                        "TICKET", "PULL_REQUEST", "SERVICE")
+SPACY_BLOCKED_LABELS = ("CARDINAL", "DATE", "TIME", "PERCENT", "MONEY",
+                        "QUANTITY", "ORDINAL")
+MIN_ENTITY_CHARS = int(os.getenv("TRACERAG_MIN_ENTITY_CHARS", "3"))
+
+GLINER_THRESHOLD = float(os.getenv("TRACERAG_GLINER_THRESHOLD", "0.55"))
+
+# word-based sliding window so long docs don't drop entities past gliner's limit
+GLINER_WINDOW_WORDS = int(os.getenv("TRACERAG_GLINER_WINDOW_WORDS", "300"))
+GLINER_WINDOW_OVERLAP = int(os.getenv("TRACERAG_GLINER_WINDOW_OVERLAP", "50"))
+
+CHUNK_SIZE = int(os.getenv("TRACERAG_CHUNK_SIZE", "1200"))
+CHUNK_OVERLAP = int(os.getenv("TRACERAG_CHUNK_OVERLAP", "150"))
+
+
+# ladybugdb schema (kùzu-compatible cypher ddl)
+NODE_TABLE = "Entity"
+REL_TABLE = "RELATES_TO"          # entity -> entity, same-window co-occurrence
+DOC_TABLE = "Document"           # source doc node, no embedding
+MENTIONS_TABLE = "MENTIONS"      # document -> entity
+VECTOR_INDEX = "idx_entity_embedding"
+VECTOR_METRIC = "cosine"

tracerag/curation.py

@@ -0,0 +1,217 @@
+"""Two-tier curation: fast-merge by similarity, deep-merge via LLM, else mint new id."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from dataclasses import dataclass
+from itertools import combinations
+
+from . import config
+from .db import TraceDB
+from .extract import ExtractedEntity, sliding_window_words
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class IngestStats:
+    docs: int = 0
+    entities: int = 0
+    created: int = 0
+    fast_merged: int = 0
+    deep_merged_yes: int = 0
+    deep_merged_no: int = 0
+    ollama_calls: int = 0
+    relates_edges: int = 0
+    mentions_edges: int = 0
+
+    def merge(self, other: "IngestStats") -> None:
+        for f in field_names():
+            setattr(self, f, getattr(self, f) + getattr(other, f))
+
+
+def field_names() -> list[str]:
+    return [f.name for f in IngestStats.__dataclass_fields__.values()]
+
+
+def slugify(text: str) -> str:
+    """Canonical readable id, e.g. 'PaymentService Service' -> 'paymentservice-service'."""
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug or "entity"
+
+
+class CurationEngine:
+    """Embeds entities, resolves them against the graph, and commits nodes/edges."""
+
+    def __init__(self, db: TraceDB, embed_model: str = config.EMBED_MODEL) -> None:
+        self.db = db
+        self.embed_model = embed_model
+        self._embedder = None
+        self._llm = None
+        # in-memory dedup index: the DB's HNSW index can't be queried mid-ingest
+        self._ids: list[str] = []
+        self._labels: list[str] = []
+        self._types: list[str] = []
+        self._vecs: list[list[float]] = []
+        self._index_loaded = False
+
+    def _get_embedder(self):
+        if self._embedder is None:
+            from sentence_transformers import SentenceTransformer
+
+            logger.info("Loading embedder: %s", self.embed_model)
+            self._embedder = SentenceTransformer(self.embed_model)
+        return self._embedder
+
+    def _embed(self, text: str) -> list[float]:
+        vec = self._get_embedder().encode(text, normalize_embeddings=True)
+        return [float(x) for x in vec]
+
+    def _get_llm(self):
+        if self._llm is None:
+            from .llm import make_client
+
+            self._llm = make_client()
+        return self._llm
+
+    def _ensure_index_loaded(self) -> None:
+        if self._index_loaded:
+            return
+        rows = self.db.execute(
+            f"MATCH (e:{config.NODE_TABLE}) RETURN e.id AS id, e.label AS label, "
+            f"e.type AS type, e.embedding AS emb;"
+        ).get_as_df().to_dict("records")
+        for r in rows:
+            if r["emb"] is not None:
+                self._add_to_index(r["id"], r["label"], r["type"], list(r["emb"]))
+        self._index_loaded = True
+        if rows:
+            logger.info("Pre-loaded %d existing nodes into dedup index", len(rows))
+
+    def _add_to_index(self, node_id: str, label: str, ntype: str,
+                      embedding: list[float]) -> None:
+        self._ids.append(node_id)
+        self._labels.append(label)
+        self._types.append(ntype)
+        self._vecs.append(embedding)
+
+    def ingest(
+        self,
+        doc_id: str,
+        text: str,
+        entities: list[ExtractedEntity],
+        source: str | None = None,
+    ) -> IngestStats:
+        stats = IngestStats(docs=1, entities=len(entities))
+        if not entities:
+            return stats  # no entities -> nothing worth storing for retrieval
+        self._ensure_index_loaded()
+
+        resolved = [self._resolve(ent, stats) for ent in entities]
+        self._build_chunks_and_edges(doc_id, text, entities, resolved, stats, source)
+        return stats
+
+    def _resolve(self, ent: ExtractedEntity, stats: IngestStats) -> str:
+        embedding = self._embed(ent.text)
+        hits = self._search(embedding)
+        top = hits[0] if hits else None
+
+        if top and top["similarity"] >= config.FAST_MERGE_THRESHOLD:
+            stats.fast_merged += 1
+            return top["id"]
+
+        if top and top["similarity"] >= config.DEEP_MERGE_THRESHOLD:
+            stats.ollama_calls += 1
+            if self._ask_same_entity(ent.text, top["label"]):
+                stats.deep_merged_yes += 1
+                return top["id"]
+            stats.deep_merged_no += 1
+
+        node_id = self._mint_id(ent)
+        self.db.upsert_node(node_id, ent.text, ent.type, embedding)
+        self._add_to_index(node_id, ent.text, ent.type, embedding)
+        stats.created += 1
+        return node_id
+
+    def _search(self, embedding: list[float]) -> list[dict]:
+        """Cosine search over the in-memory index (normalized, so cosine == dot)."""
+        if not self._vecs:
+            return []
+        import numpy as np
+
+        mat = np.asarray(self._vecs, dtype=np.float32)
+        q = np.asarray(embedding, dtype=np.float32)
+        sims = mat @ q
+        top = np.argsort(-sims)[: config.CURATION_TOP_K]
+        return [
+            {"id": self._ids[i], "label": self._labels[i],
+             "type": self._types[i], "similarity": float(sims[i])}
+            for i in top
+        ]
+
+    def _ask_same_entity(self, extracted_text: str, canonical_label: str) -> bool:
+        prompt = (
+            f"Are '{extracted_text}' and '{canonical_label}' the exact same "
+            f"entity? Answer ONLY YES or NO."
+        )
+        try:
+            resp = self._get_llm().chat.completions.create(
+                model=config.OPENROUTER_MODEL,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0,
+            )
+            answer = resp.choices[0].message.content.strip().upper()
+        except Exception as exc:  # noqa: BLE001 — fail safe: do not merge
+            logger.warning("Deep-merge LLM failed (%s); treating as NO.", exc)
+            return False
+        return answer.startswith("YES")
+
+    def _mint_id(self, ent: ExtractedEntity) -> str:
+        base = slugify(f"{ent.text} {ent.type}")
+        if not self.db.node_exists(base):
+            return base
+        # slug collision between distinct entities: disambiguate with a short text hash
+        suffix = hashlib.sha1(ent.text.encode()).hexdigest()[:6]
+        candidate = f"{base}-{suffix}"
+        n = 2
+        while self.db.node_exists(candidate):
+            candidate = f"{base}-{suffix}-{n}"
+            n += 1
+        return candidate
+
+    def _build_chunks_and_edges(
+        self,
+        doc_id: str,
+        text: str,
+        entities: list[ExtractedEntity],
+        resolved: list[str],
+        stats: IngestStats,
+        source: str | None = None,
+    ) -> None:
+        seen_pairs: set[tuple[str, str]] = set()
+        for idx, win in enumerate(sliding_window_words(text)):
+            win_end = win.offset + len(win.text)
+            members = [
+                resolved[i]
+                for i, e in enumerate(entities)
+                if e.start >= win.offset and e.end <= win_end
+            ]
+            if not members:
+                continue  # don't store chunks that surface no entities
+
+            # path keeps source provenance (PR url when given, else doc id) for citation
+            chunk_id = f"{doc_id}#w{idx}"
+            self.db.upsert_document(chunk_id, content=win.text, path=source or doc_id)
+
+            for entity_id in members:
+                self.db.add_mention(chunk_id, entity_id)
+                stats.mentions_edges += 1
+
+            for a, b in combinations(sorted(set(members)), 2):
+                if a == b or (a, b) in seen_pairs:
+                    continue
+                seen_pairs.add((a, b))
+                self.db.add_relationship(a, b)
+                stats.relates_edges += 1

tracerag/db.py

@@ -0,0 +1,401 @@
+"""LadybugDB connection and schema management. LadybugDB is a Kuzu fork, same API."""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator, Sequence
+
+import ladybug as lb
+
+from . import config
+
+logger = logging.getLogger(__name__)
+
+
+class TraceDB:
+    """Wrapper over LadybugDB with a read-connection pool.
+
+    LadybugDB (a Kuzu fork) parallelizes reads across *separate* connections — it
+    releases the GIL in C++ — but a single connection serializes everything. So:
+
+      * reads lease one of N pooled connections (``_fetch`` / ``_lease``), giving
+        true read concurrency under load;
+      * writes/DDL go through one dedicated connection under a lock, matching the
+        engine's single-writer model (ingestion is single-threaded anyway).
+    """
+
+    def __init__(
+        self, db_path: str | Path = config.DB_PATH, *, pool_size: int | None = None
+    ) -> None:
+        self.db_path = str(db_path)
+        self._db = lb.Database(self.db_path)
+        self._closed = False
+
+        # dedicated write/DDL connection (single-writer); guarded by a lock
+        self._write_lock = threading.Lock()
+        self._write_conn = self._new_connection()
+
+        # bounded pool of read connections; reads parallelize across them
+        self._pool_size = max(1, config.DB_POOL_SIZE if pool_size is None else pool_size)
+        self._pool: "queue.Queue" = queue.Queue(maxsize=self._pool_size)
+        self._read_conns: list = []  # kept for clean shutdown
+        for _ in range(self._pool_size):
+            conn = self._new_connection()
+            self._read_conns.append(conn)
+            self._pool.put(conn)
+        logger.info(
+            "Opened LadybugDB at %s (read pool=%d)", self.db_path, self._pool_size
+        )
+
+    # ---- connection plumbing -------------------------------------------------
+
+    def _new_connection(self):
+        """Create a connection with the VECTOR extension loaded (per-connection)."""
+        conn = lb.Connection(self._db)
+        self._load_vector_on(conn)
+        return conn
+
+    @staticmethod
+    def _load_vector_on(conn) -> None:
+        """LOAD the VECTOR extension on a connection; INSTALL once if missing."""
+        try:
+            conn.execute("LOAD VECTOR;")
+        except Exception:  # noqa: BLE001 — not installed yet on this machine
+            try:
+                conn.execute("INSTALL VECTOR;")
+                conn.execute("LOAD VECTOR;")
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("VECTOR extension unavailable: %s", exc)
+
+    def _load_vector_extension(self) -> None:
+        """Reload VECTOR on the write connection (used before index rebuilds)."""
+        self._load_vector_on(self._write_conn)
+
+    @contextmanager
+    def _lease(self) -> Iterator[Any]:
+        """Borrow a read connection from the pool, returning it on exit."""
+        if self._closed:
+            raise RuntimeError("TraceDB is closed")
+        conn = self._pool.get(timeout=config.DB_POOL_TIMEOUT)
+        try:
+            yield conn
+        finally:
+            self._pool.put(conn)
+
+    def execute(self, query: str, params: dict[str, Any] | None = None):
+        """Write/DDL path: runs on the single write connection under a lock.
+
+        Reads should use ``_fetch`` so they fan out across the pool; this is kept
+        for schema, upserts and index builds (and any caller that ignores the
+        result). The returned result must be consumed before the next write.
+        """
+        with self._write_lock:
+            return self._write_conn.execute(query, params or {})
+
+    def _fetch(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
+        """Read path: lease a pooled connection, run, materialize, release.
+
+        Materializing (``get_as_df``) inside the lease is required — the result
+        is bound to its connection, so it must be consumed before the connection
+        goes back to the pool.
+        """
+        with self._lease() as conn:
+            return self._records(conn.execute(query, params or {}))
+
+    def init_schema(self) -> None:
+        self.execute(
+            f"CREATE NODE TABLE IF NOT EXISTS {config.NODE_TABLE} ("
+            f"id STRING PRIMARY KEY, label STRING, type STRING, "
+            f"embedding FLOAT[{config.EMBED_DIM}]);"
+        )
+        self.execute(
+            f"CREATE NODE TABLE IF NOT EXISTS {config.DOC_TABLE} ("
+            f"id STRING PRIMARY KEY, path STRING, content STRING);"
+        )
+        self.execute(
+            f"CREATE REL TABLE IF NOT EXISTS {config.REL_TABLE} ("
+            f"FROM {config.NODE_TABLE} TO {config.NODE_TABLE}, confidence DOUBLE);"
+        )
+        self.execute(
+            f"CREATE REL TABLE IF NOT EXISTS {config.MENTIONS_TABLE} ("
+            f"FROM {config.DOC_TABLE} TO {config.NODE_TABLE});"
+        )
+        # HNSW index built later via build_vector_index(); a live index blocks embedding writes
+        logger.info("Schema ready (node=%s, rel=%s)",
+                    config.NODE_TABLE, config.REL_TABLE)
+
+    def build_vector_index(self) -> None:
+        """(Re)build the HNSW index over current embeddings; call after ingestion."""
+        self._load_vector_extension()
+        try:
+            self.execute(
+                f"CALL DROP_VECTOR_INDEX('{config.NODE_TABLE}', "
+                f"'{config.VECTOR_INDEX}');"
+            )
+        except Exception:  # noqa: BLE001 — no index to drop on first build
+            pass
+        self.execute(
+            f"CALL CREATE_VECTOR_INDEX('{config.NODE_TABLE}', "
+            f"'{config.VECTOR_INDEX}', 'embedding', metric := '{config.VECTOR_METRIC}');"
+        )
+        logger.info("Built vector index %s", config.VECTOR_INDEX)
+
+    def upsert_node(
+        self,
+        node_id: str,
+        label: str,
+        node_type: str,
+        embedding: Sequence[float],
+    ) -> None:
+        # no ON MATCH SET: never clobber a canonical node with a noisier surface form
+        self._check_dim(embedding)
+        self.execute(
+            f"MERGE (e:{config.NODE_TABLE} {{id: $id}}) "
+            f"ON CREATE SET e.label = $label, e.type = $type, e.embedding = $embedding",
+            {"id": node_id, "label": label, "type": node_type,
+             "embedding": list(embedding)},
+        )
+
+    def add_relationship(self, from_id: str, to_id: str, confidence: float = 1.0) -> None:
+        self.execute(
+            f"MATCH (a:{config.NODE_TABLE} {{id: $from_id}}), "
+            f"(b:{config.NODE_TABLE} {{id: $to_id}}) "
+            f"MERGE (a)-[r:{config.REL_TABLE}]->(b) ON CREATE SET r.confidence = $confidence",
+            {"from_id": from_id, "to_id": to_id, "confidence": confidence},
+        )
+
+    def upsert_document(
+        self, doc_id: str, content: str | None = None, path: str | None = None
+    ) -> None:
+        # documents are raw source, not canonical: refresh content on re-ingestion
+        self.execute(
+            f"MERGE (d:{config.DOC_TABLE} {{id: $id}}) "
+            f"ON CREATE SET d.path = $path, d.content = $content "
+            f"ON MATCH  SET d.path = $path, d.content = $content",
+            {"id": doc_id, "path": path or doc_id, "content": content or ""},
+        )
+
+    def add_mention(self, doc_id: str, entity_id: str) -> None:
+        self.execute(
+            f"MATCH (d:{config.DOC_TABLE} {{id: $doc_id}}), "
+            f"(e:{config.NODE_TABLE} {{id: $entity_id}}) "
+            f"MERGE (d)-[:{config.MENTIONS_TABLE}]->(e)",
+            {"doc_id": doc_id, "entity_id": entity_id},
+        )
+
+    def find_nodes_by_label(self, label: str) -> list[dict[str, Any]]:
+        """Exact, case-insensitive match of entities by their label."""
+        return self._fetch(
+            f"MATCH (e:{config.NODE_TABLE}) WHERE lower(e.label) = lower($label) "
+            f"RETURN e.id AS id, e.label AS label, e.type AS type;",
+            {"label": label},
+        )
+
+    def node_exists(self, node_id: str) -> bool:
+        rows = self._fetch(
+            f"MATCH (e:{config.NODE_TABLE} {{id: $id}}) RETURN e.id AS id LIMIT 1;",
+            {"id": node_id},
+        )
+        return len(rows) > 0
+
+    def vector_search(
+        self,
+        query_embedding: Sequence[float],
+        k: int = config.CURATION_TOP_K,
+    ) -> list[dict[str, Any]]:
+        """Top-k cosine neighbours via the HNSW index; similarity = 1 - distance."""
+        self._check_dim(query_embedding)
+        result = self._fetch(
+            f"CALL QUERY_VECTOR_INDEX('{config.NODE_TABLE}', "
+            f"'{config.VECTOR_INDEX}', $q, {int(k)}) "
+            f"RETURN node.id AS id, node.label AS label, node.type AS type, "
+            f"distance ORDER BY distance;",
+            {"q": list(query_embedding)},
+        )
+        rows = []
+        for r in result:
+            distance = float(r["distance"])
+            rows.append({
+                "id": r["id"], "label": r["label"], "type": r["type"],
+                "distance": distance, "similarity": 1.0 - distance,
+            })
+        return rows
+
+    def neighbors(self, node_id: str, k: int = config.TOP_K_GRAPH) -> list[dict[str, Any]]:
+        """One-hop graph neighbours, strongest edge first (deterministic order)."""
+        return self._fetch(
+            f"MATCH (a:{config.NODE_TABLE} {{id: $id}})"
+            f"-[r:{config.REL_TABLE}]-(b:{config.NODE_TABLE}) "
+            f"RETURN b.id AS id, b.label AS label, b.type AS type, "
+            f"r.confidence AS confidence "
+            f"ORDER BY r.confidence DESC, b.id ASC "
+            f"LIMIT $k;",
+            {"id": node_id, "k": k},
+        )
+
+    def node_degree(self, node_id: str) -> int:
+        """Distinct one-hop neighbour count — used to detect hub super-nodes."""
+        rows = self._fetch(
+            f"MATCH (a:{config.NODE_TABLE} {{id: $id}})"
+            f"-[r:{config.REL_TABLE}]-(b:{config.NODE_TABLE}) "
+            f"RETURN count(DISTINCT b.id) AS d;",
+            {"id": node_id},
+        )
+        return int(rows[0]["d"]) if rows else 0
+
+    def expand_frontier(
+        self, node_ids: list[str], k: int, max_degree: int
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Batched 1-hop expansion of a whole frontier in one query (avoids N+1)."""
+        if not node_ids:
+            return {}
+        rows = self._fetch(
+            f"MATCH (a:{config.NODE_TABLE}) WHERE a.id IN $ids "
+            f"OPTIONAL MATCH (a)-[r:{config.REL_TABLE}]-(b:{config.NODE_TABLE}) "
+            f"RETURN a.id AS from_id, b.id AS to_id, b.label AS label, "
+            f"b.type AS type, r.confidence AS confidence;",
+            {"ids": list(node_ids)},
+        )
+        grouped: dict[str, list[dict[str, Any]]] = {}
+        for r in rows:
+            if r["to_id"] is None:  # isolated node
+                continue
+            grouped.setdefault(r["from_id"], []).append({
+                "id": r["to_id"], "label": r["label"], "type": r["type"],
+                "confidence": float(r["confidence"])
+                if r["confidence"] is not None else 1.0,
+            })
+        out: dict[str, list[dict[str, Any]]] = {}
+        for from_id, nbrs in grouped.items():
+            if len({n["id"] for n in nbrs}) > max_degree:
+                continue  # hub: reached but not traversed through
+            nbrs.sort(key=lambda n: (-n["confidence"], n["id"]))
+            out[from_id] = nbrs[:k]
+        return out
+
+    def documents_for_entities(self, entity_ids: list[str]) -> dict[str, list[dict]]:
+        """Chunk text of every Document mentioning the given entities, keyed by entity id."""
+        if not entity_ids:
+            return {}
+        rows = self._fetch(
+            f"MATCH (d:{config.DOC_TABLE})-[:{config.MENTIONS_TABLE}]->"
+            f"(e:{config.NODE_TABLE}) "
+            f"WHERE e.id IN $ids "
+            f"RETURN e.id AS entity_id, d.id AS doc_id, d.path AS path, "
+            f"d.content AS content;",
+            {"ids": entity_ids},
+        )
+        grouped: dict[str, list[dict]] = {}
+        for r in rows:
+            grouped.setdefault(r["entity_id"], []).append(
+                {"doc_id": r["doc_id"], "path": r["path"], "content": r["content"]}
+            )
+        return grouped
+
+    def subgraph(self, node_ids: list[str]) -> dict:
+        """Requested nodes plus their 1-hop neighbors and the edges among that set."""
+        if not node_ids:
+            return {"nodes": [], "edges": []}
+
+        # optional match so isolated requested nodes still appear
+        rows = self._fetch(
+            f"MATCH (a:{config.NODE_TABLE}) WHERE a.id IN $ids "
+            f"OPTIONAL MATCH (a)-[:{config.REL_TABLE}]-(b:{config.NODE_TABLE}) "
+            f"RETURN a.id AS a_id, a.label AS a_label, a.type AS a_type, "
+            f"b.id AS b_id, b.label AS b_label, b.type AS b_type;",
+            {"ids": node_ids},
+        )
+
+        requested = set(node_ids)
+        nodes: dict[str, dict] = {}
+
+        def _add(nid, label, ntype):
+            if nid is not None and nid not in nodes:
+                nodes[nid] = {"id": nid, "label": label, "type": ntype,
+                              "requested": nid in requested}
+
+        for r in rows:
+            _add(r["a_id"], r["a_label"], r["a_type"])
+            _add(r["b_id"], r["b_label"], r["b_type"])
+
+        # edges strictly between visible nodes
+        all_ids = list(nodes)
+        edge_rows = self._fetch(
+            f"MATCH (a:{config.NODE_TABLE})-[r:{config.REL_TABLE}]->"
+            f"(b:{config.NODE_TABLE}) "
+            f"WHERE a.id IN $ids AND b.id IN $ids "
+            f"RETURN a.id AS source, b.id AS target, r.confidence AS confidence;",
+            {"ids": all_ids},
+        ) if all_ids else []
+        edges = [
+            {"source": r["source"], "target": r["target"],
+             "confidence": r["confidence"]}
+            for r in edge_rows
+        ]
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+    def count_nodes(self) -> int:
+        rows = self._fetch(
+            f"MATCH (e:{config.NODE_TABLE}) RETURN count(e) AS n;")
+        return int(rows[0]["n"]) if rows else 0
+
+    def top_entities(self, limit: int = 12) -> list[dict[str, Any]]:
+        """Most-connected entities (highest distinct degree), with type."""
+        # aggregate via WITH before ordering; ordering by a.label alongside the aggregate
+        # fails in Kuzu ("Variable a is not in scope")
+        return self._fetch(
+            f"MATCH (a:{config.NODE_TABLE})-[r:{config.REL_TABLE}]-(b:{config.NODE_TABLE}) "
+            f"WITH a, count(DISTINCT b) AS degree "
+            f"RETURN a.id AS id, a.label AS label, a.type AS type, degree "
+            f"ORDER BY degree DESC, a.label ASC "
+            f"LIMIT $limit;",
+            {"limit": int(limit)},
+        )
+
+    @staticmethod
+    def _check_dim(embedding: Sequence[float]) -> None:
+        if len(embedding) != config.EMBED_DIM:
+            raise ValueError(
+                f"Embedding has {len(embedding)} dims, expected {config.EMBED_DIM}."
+            )
+
+    @staticmethod
+    def _records(result) -> list[dict[str, Any]]:
+        return result.get_as_df().to_dict(orient="records")
+
+    def close(self) -> None:
+        """Drain the read pool and close every connection (idempotent).
+
+        Safe across the hot-swap path: ``/api/graphs/switch`` builds a new
+        TraceDB and closes the old one, so each pool is owned by exactly one
+        TraceDB and never outlives it.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        handles = list(self._read_conns) + [self._write_conn, self._db]
+        for handle in handles:
+            try:
+                handle.close()
+            except Exception:  # noqa: BLE001
+                pass
+        logger.info("Closed LadybugDB at %s", self.db_path)
+
+    def __enter__(self) -> "TraceDB":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+
+def get_db(db_path: str | Path = config.DB_PATH, *, init: bool = True) -> TraceDB:
+    db = TraceDB(db_path)
+    if init:
+        db.init_schema()
+    return db

tracerag/extract.py

@@ -0,0 +1,261 @@
+"""Entity extraction: GLiNER (zero-shot) with spaCy fallback, over sliding windows."""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Iterator
+
+from . import config
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ExtractedEntity:
+    text: str          # surface form
+    type: str          # config.ENTITY_LABELS (or spaCy label in fallback)
+    score: float       # confidence in [0, 1]
+    start: int         # absolute char offset
+    end: int           # absolute char offset (exclusive)
+    source: str        # "gliner" | "spacy"
+
+
+@dataclass(frozen=True)
+class _WordWindow:
+    text: str
+    offset: int  # absolute char offset where this window begins
+
+
+def sliding_window_words(
+    text: str,
+    window: int = config.GLINER_WINDOW_WORDS,
+    overlap: int = config.GLINER_WINDOW_OVERLAP,
+) -> Iterator[_WordWindow]:
+    """Yield overlapping word windows tagged with their char offset."""
+    if overlap >= window:
+        raise ValueError("overlap must be smaller than window")
+
+    tokens = [(m.group(0), m.start()) for m in re.finditer(r"\S+", text)]
+    if not tokens:
+        return
+
+    step = window - overlap
+    for i in range(0, len(tokens), step):
+        chunk = tokens[i : i + window]
+        if not chunk:
+            break
+        start_char = chunk[0][1]
+        last_word, last_start = chunk[-1]
+        end_char = last_start + len(last_word)
+        yield _WordWindow(text=text[start_char:end_char], offset=start_char)
+        if i + window >= len(tokens):
+            break
+
+
+# spaCy/EntityRuler label -> domain type; anything not here is dropped
+_SPACY_LABEL_MAP = {
+    "PERSON": "Person",
+    "ORG": "Service",
+    "PRODUCT": "Tool",
+    "GPE": "Location",
+    "TICKET": "Ticket",
+    "PULL_REQUEST": "PR",
+    "SERVICE": "Service",
+}
+
+# patterns for an EntityRuler placed before the statistical ner, so the ruler wins
+_RULER_LABELS = frozenset({"TICKET", "PULL_REQUEST", "SERVICE"})
+_ENTITY_RULER_PATTERNS = [
+    # jira project key: INC-123, OPS-456, SRCTREEWIN-14221
+    {"label": "TICKET",
+     "pattern": [{"TEXT": {"REGEX": r"(?i)^[A-Z][A-Z0-9]+-\d+$"}}]},
+    # PR #402, PR 402
+    {"label": "PULL_REQUEST",
+     "pattern": [{"LOWER": "pr"}, {"TEXT": "#", "OP": "?"}, {"IS_DIGIT": True}]},
+    # payment-service as one token
+    {"label": "SERVICE",
+     "pattern": [{"TEXT": {"REGEX": r"(?i)^[a-z0-9]+-service$"}}]},
+    # payment-service split into ["payment", "-", "service"]
+    {"label": "SERVICE",
+     "pattern": [{"TEXT": {"REGEX": r"(?i)^[a-z0-9]+$"}},
+                 {"TEXT": "-"}, {"LOWER": "service"}]},
+]
+
+# leading/trailing markdown & list punctuation to trim off noisy spaCy spans
+_EDGE_JUNK = " \t\r\n-*#•|>:.,;"
+
+
+def clean_entity_text(raw: str) -> str | None:
+    """Sanitize an extracted surface form; return cleaned text or None to drop."""
+    if not raw:
+        return None
+    text = re.sub(r"\s+", " ", raw).strip().strip(_EDGE_JUNK).strip()
+    if len(text) < config.MIN_ENTITY_CHARS:
+        return None
+    if re.fullmatch(r"[\W_]+", text):          # only special chars
+        return None
+    if re.fullmatch(r"[\d.,%$]+", text):       # entirely numeric (2026, 1,000, 50%)
+        return None
+    if not text[0].isalnum():                  # starts with a special char (#, -, *)
+        return None
+    return text
+
+
+class EntityExtractor:
+    """Extracts domain entities. GLiNER first; degrades to spaCy if unavailable."""
+
+    def __init__(
+        self,
+        labels: list[str] | None = None,
+        threshold: float = config.GLINER_THRESHOLD,
+        prefer_gliner: bool = True,
+    ) -> None:
+        self.labels = labels or config.ENTITY_LABELS
+        self.threshold = threshold
+        # False at query time: linking only needs the ruler, gliner is ingest-only
+        self._prefer_gliner = prefer_gliner
+        self._gliner = None
+        self._spacy = None
+        self._gliner_failed = False
+        # Query-side extraction is a pure fn of the text and GIL-bound (spaCy),
+        # so cache it: repeated queries skip the pass entirely. Disabled for the
+        # ingest path (prefer_gliner=True), where every document text is unique.
+        self._cache_cap = 0 if prefer_gliner else config.QUERY_EXTRACT_CACHE
+        self._cache: "OrderedDict[str, list[ExtractedEntity]]" = OrderedDict()
+        self._cache_lock = threading.Lock()
+
+    def _get_gliner(self):
+        if not self._prefer_gliner:
+            return None
+        if self._gliner is None and not self._gliner_failed:
+            try:
+                from gliner import GLiNER
+
+                logger.info("Loading GLiNER model: %s", config.GLINER_MODEL)
+                self._gliner = GLiNER.from_pretrained(config.GLINER_MODEL)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("GLiNER unavailable (%s); using spaCy.", exc)
+                self._gliner_failed = True
+        return self._gliner
+
+    def _get_spacy(self):
+        if self._spacy is None:
+            import spacy
+
+            try:
+                logger.info("Loading spaCy model: %s", config.SPACY_MODEL)
+                # Entity linking needs only tok2vec + ruler + ner. Excluding the
+                # tagger/parser/lemmatizer cuts per-call CPU (and GIL-hold), which
+                # is what dominates query latency under concurrency.
+                nlp = spacy.load(
+                    config.SPACY_MODEL,
+                    exclude=["tagger", "parser", "lemmatizer", "attribute_ruler"],
+                )
+            except OSError as exc:
+                raise RuntimeError(
+                    f"spaCy model '{config.SPACY_MODEL}' not found. "
+                    f"Run: python -m spacy download {config.SPACY_MODEL}"
+                ) from exc
+            # ruler runs before ner so deterministic spans take priority
+            if "entity_ruler" not in nlp.pipe_names:
+                ruler = nlp.add_pipe("entity_ruler", before="ner")
+                ruler.add_patterns(_ENTITY_RULER_PATTERNS)
+            self._spacy = nlp
+        return self._spacy
+
+    def extract(self, text: str) -> list[ExtractedEntity]:
+        if not text or not text.strip():
+            return []
+        if self._cache_cap:
+            with self._cache_lock:
+                cached = self._cache.get(text)
+                if cached is not None:
+                    self._cache.move_to_end(text)
+                    return cached
+        model = self._get_gliner()
+        if model is not None:
+            result = self._extract_gliner(text, model)
+        else:
+            result = self._extract_spacy(text)
+        if self._cache_cap:
+            with self._cache_lock:
+                self._cache[text] = result
+                self._cache.move_to_end(text)
+                if len(self._cache) > self._cache_cap:
+                    self._cache.popitem(last=False)
+        return result
+
+    def _extract_gliner(self, text: str, model) -> list[ExtractedEntity]:
+        found: list[ExtractedEntity] = []
+        for win in sliding_window_words(text):
+            try:
+                preds = model.predict_entities(
+                    win.text, self.labels, threshold=self.threshold
+                )
+            except Exception as exc:  # noqa: BLE001 — skip bad window, keep doc
+                logger.warning("GLiNER failed on a window (%s); skipping.", exc)
+                continue
+            for p in preds:
+                # GLiNER's p["text"] corrupts multi-byte chars (José -> Jos�);
+                # re-slice the span from the source using its (correct) offsets.
+                raw = win.text[p["start"]:p["end"]] or p["text"]
+                clean = clean_entity_text(raw)
+                if clean is None:
+                    continue
+                found.append(ExtractedEntity(
+                    text=clean,
+                    type=p["label"],
+                    score=float(p.get("score", 1.0)),
+                    start=win.offset + p["start"],
+                    end=win.offset + p["end"],
+                    source="gliner",
+                ))
+        return self._dedupe(found)
+
+    def _extract_spacy(self, text: str) -> list[ExtractedEntity]:
+        nlp = self._get_spacy()
+        found: list[ExtractedEntity] = []
+        for win in sliding_window_words(text):
+            for ent in nlp(win.text).ents:
+                # whitelist high-signal labels, drop date/number/quantity noise
+                if ent.label_ not in config.SPACY_ALLOWED_LABELS:
+                    continue
+                if ent.label_ in config.SPACY_BLOCKED_LABELS:
+                    continue
+                if ent.label_ in _RULER_LABELS:
+                    clean = ent.text.strip()
+                    if not clean:
+                        continue
+                    # canonicalize ticket keys so case variants resolve to one node
+                    if ent.label_ == "TICKET":
+                        clean = clean.upper()
+                else:
+                    clean = clean_entity_text(ent.text)
+                    if clean is None:
+                        continue
+                found.append(ExtractedEntity(
+                    text=clean,
+                    type=_SPACY_LABEL_MAP.get(ent.label_, ent.label_),
+                    score=1.0,
+                    start=win.offset + ent.start_char,
+                    end=win.offset + ent.end_char,
+                    source="spacy",
+                ))
+        return self._dedupe(found)
+
+    @staticmethod
+    def _dedupe(entities: list[ExtractedEntity]) -> list[ExtractedEntity]:
+        # surface-level only (best score per text+type); semantic merge is curation's job
+        best: dict[tuple[str, str], ExtractedEntity] = {}
+        for e in entities:
+            if not e.text:
+                continue
+            key = (e.text.lower(), e.type)
+            cur = best.get(key)
+            if cur is None or e.score > cur.score:
+                best[key] = e
+        return sorted(best.values(), key=lambda e: (e.start, e.text))

tracerag/integrations/__init__.py

@@ -0,0 +1 @@
+"""Framework integrations."""

tracerag/integrations/langchain.py

@@ -0,0 +1,64 @@
+"""LangChain BaseRetriever backed by the TraceRouter."""
+
+from __future__ import annotations
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+
+from .. import config
+from ..db import TraceDB
+from ..router import RoutedNode, TraceRouter
+
+
+def format_page_content(node: RoutedNode, seen_chunk_ids: set[str] | None = None) -> str:
+    """Entity line + its chunk text, globally deduped by chunk id."""
+    seen = seen_chunk_ids if seen_chunk_ids is not None else set()
+    label, ntype = node.label or node.id, node.type or "Unknown"
+    content = f"Entity: {label} ({ntype})"
+    parts: list[str] = []
+    for d in node.documents:
+        cid = d.get("doc_id")
+        text = (d.get("content") or "").strip()
+        if not text:
+            continue
+        if cid not in seen:
+            seen.add(cid)
+            parts.append(text)
+        else:
+            parts.append(f"[Trace: {label} ({ntype}) -> {cid}]")
+    if parts:
+        content += "\n\nContext:\n" + "\n---\n".join(parts)
+    return content
+
+
+class TraceRAGRetriever(BaseRetriever):
+    """Retriever that wraps TraceRouter over the .lbug graph."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    router: TraceRouter
+    k: int = config.TOP_K_VECTOR
+
+    @classmethod
+    def from_db(cls, db: TraceDB, k: int = config.TOP_K_VECTOR) -> "TraceRAGRetriever":
+        return cls(router=TraceRouter(db), k=k)
+
+    def _get_relevant_documents(
+        self, query: str, *, run_manager: CallbackManagerForRetrieverRun
+    ) -> list[Document]:
+        response = self.router.route(query, top_k=self.k)
+        docs: list[Document] = []
+        seen_chunk_ids: set[str] = set()
+        for node in response.results:
+            docs.append(Document(
+                page_content=format_page_content(node, seen_chunk_ids),
+                metadata={
+                    "id": node.id,
+                    "score_total": node.score_total,
+                    "score_vector": node.score_vector,
+                    "score_graph": node.score_graph,
+                    "trace_log": response.trace_log,
+                },
+            ))
+        return docs

tracerag/llm.py

@@ -0,0 +1,32 @@
+"""Shared OpenRouter chat client."""
+
+from __future__ import annotations
+
+from . import config
+
+
+def make_client():
+    """Return an OpenAI client pointed at OpenRouter."""
+    from openai import OpenAI
+
+    return OpenAI(
+        base_url=config.OPENROUTER_BASE_URL,
+        api_key=config.OPENROUTER_API_KEY,
+        default_headers={
+            "HTTP-Referer": config.OPENROUTER_SITE_URL,
+            "X-Title": config.OPENROUTER_APP_TITLE,
+        },
+    )
+
+
+def make_intent_client() -> tuple[object, str]:
+    """Return (client, model) for intent; prefers Groq, falls back to OpenRouter."""
+    if config.GROQ_API_KEY:
+        from openai import OpenAI
+
+        client = OpenAI(
+            base_url=config.GROQ_BASE_URL,
+            api_key=config.GROQ_API_KEY,
+        )
+        return client, config.GROQ_MODEL
+    return make_client(), config.OPENROUTER_MODEL

tracerag/router.py

@@ -0,0 +1,341 @@
+"""Intent-based hybrid router: vector recall + graph traversal, fused by intent."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+
+from . import config
+from .db import TraceDB
+
+logger = logging.getLogger(__name__)
+
+# Dedicated, bounded pool for the CPU-heavy embedding step. torch releases the
+# GIL during encode, so threads parallelize; bounding the workers keeps a burst
+# of embeds from starving the request threads (or the FastAPI threadpool).
+# Module-level + lazy so it is shared across requests and survives graph swaps.
+_EMBED_EXECUTOR = ThreadPoolExecutor(
+    max_workers=config.EMBED_WORKERS, thread_name_prefix="embed"
+)
+
+
+def shutdown_embed_executor(wait: bool = True) -> None:
+    """Stop the shared embed executor, letting in-flight encodes finish first.
+
+    Called from the FastAPI lifespan shutdown so worker threads are joined
+    cleanly on Ctrl+C instead of being abandoned at interpreter exit.
+    """
+    _EMBED_EXECUTOR.shutdown(wait=wait)
+
+
+@dataclass
+class RoutedNode:
+    id: str
+    label: str | None
+    type: str | None
+    score_total: float
+    score_vector: float
+    score_graph: float
+    documents: list[dict] = field(default_factory=list)
+
+
+@dataclass
+class RouterResponse:
+    query: str
+    results: list[RoutedNode]
+    trace_log: dict
+
+
+class TraceRouter:
+    """Hybrid retriever: vector + graph, fused by query intent."""
+
+    def __init__(self, db: TraceDB, embed_model: str = config.EMBED_MODEL) -> None:
+        self.db = db
+        self.embed_model = embed_model
+        self._embedder = None
+        self._llm = None
+        self._intent_llm = None
+        self._extractor = None
+
+    def warm(self) -> None:
+        """Cold-boot warmup: load model weights into RAM and spin up the worker
+        threads, so the first real query skips the cold-start latency spike.
+
+        Routes through ``embed_query`` (not the raw embedder) so the bounded embed
+        executor's threads are created and the torch graph is traced; and through
+        the extractor so the spaCy pipeline is loaded into memory.
+        """
+        self.embed_query("warmup query")          # warms embedder + executor threads
+        try:
+            self._get_extractor().extract("warmup query")  # warms spaCy pipeline
+        except Exception as exc:  # noqa: BLE001 — never let warmup break boot
+            logger.debug("extractor warmup skipped (%s)", exc)
+
+    def _get_embedder(self):
+        if self._embedder is None:
+            from sentence_transformers import SentenceTransformer
+
+            logger.info("Loading embedder: %s", self.embed_model)
+            self._embedder = SentenceTransformer(self.embed_model)
+        return self._embedder
+
+    def _get_extractor(self):
+        if self._extractor is None:
+            from .extract import EntityExtractor
+
+            # query-side linking only needs the spaCy ruler; gliner is ingest-time
+            self._extractor = EntityExtractor(prefer_gliner=False)
+        return self._extractor
+
+    def _link_query_entities(self, query: str, meta: dict[str, dict]) -> list[str]:
+        """Extract query entities and match them to graph nodes by exact label."""
+        ids: list[str] = []
+        try:
+            entities = self._get_extractor().extract(query)
+        except Exception as exc:  # noqa: BLE001 — never let linking break a query
+            logger.debug("query entity extraction failed (%s)", exc)
+            return ids
+        for ent in entities:
+            for node in self.db.find_nodes_by_label(ent.text):
+                nid = node["id"]
+                meta.setdefault(nid, {"label": node["label"], "type": node["type"]})
+                ids.append(nid)
+        return list(dict.fromkeys(ids))
+
+    def _encode(self, text: str) -> list[float]:
+        vec = self._get_embedder().encode(text, normalize_embeddings=True)
+        return [float(x) for x in vec]
+
+    def embed_query(self, text: str) -> list[float]:
+        # Offload the encode to the dedicated bounded pool: concurrent embeds are
+        # isolated and capped, so a burst can't monopolize the request threads.
+        # .result() blocks the calling worker thread, never the event loop.
+        return _EMBED_EXECUTOR.submit(self._encode, text).result()
+
+    async def aroute(self, query: str, top_k: int | None = None) -> "RouterResponse":
+        """Async entry point: run the (blocking) hybrid route off the event loop.
+
+        The retrieval itself stays synchronous — its concurrency now comes from
+        the DB read pool (parallel graph/vector reads) and the bounded embed
+        pool. This wrapper just keeps the asyncio loop free so the API can serve
+        many requests at once without blocking.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.route, query, top_k)
+
+    def _get_llm(self):
+        if self._llm is None:
+            from .llm import make_client
+
+            self._llm = make_client()
+        return self._llm
+
+    def _get_intent_llm(self) -> tuple[object, str]:
+        if self._intent_llm is None:
+            from .llm import make_intent_client
+
+            self._intent_llm = make_intent_client()
+        return self._intent_llm
+
+    def _classify_intent(self, query: str) -> tuple[float, float, str]:
+        q = query.lower()
+        if any(m in q for m in config.RELATIONAL_QUERY_MARKERS):
+            w = config.ROUTER_WEIGHTS_RELATIONAL
+            return w["vector"], w["graph"], "relational"
+        if any(m in q for m in config.SEMANTIC_QUERY_MARKERS):
+            w = config.ROUTER_WEIGHTS_CONCEPTUAL
+            return w["vector"], w["graph"], "semantic"
+        return self._classify_intent_llm(query)
+
+    def _classify_intent_llm(self, query: str) -> tuple[float, float, str]:
+        prompt = (
+            "Reply with ONE word — RELATIONAL if the query traces a sequence of "
+            "events/people/links, else SEMANTIC.\n\n" + query
+        )
+        try:
+            # one token, short timeout: fail fast to SEMANTIC, never dominate latency
+            client, model = self._get_intent_llm()
+            resp = client.chat.completions.create(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0,
+                max_tokens=4,
+                timeout=6,
+            )
+            answer = (resp.choices[0].message.content or "").strip().upper()
+        except Exception as exc:  # noqa: BLE001 — default to semantic on failure
+            logger.warning("Intent LLM failed (%s); defaulting to semantic.", exc)
+            answer = "SEMANTIC"
+        if "RELATIONAL" in answer:
+            w = config.ROUTER_WEIGHTS_RELATIONAL
+            return w["vector"], w["graph"], "relational"
+        w = config.ROUTER_WEIGHTS_CONCEPTUAL
+        return w["vector"], w["graph"], "semantic"
+
+    def _vector_hits(
+        self, query: str, k: int, meta: dict[str, dict]
+    ) -> list[tuple[str, float]]:
+        """Top-k vector hits as an ordered (id, similarity) list, best first."""
+        embedding = self.embed_query(query)
+        try:
+            hits = self.db.vector_search(embedding, k=k)
+        except Exception as exc:  # noqa: BLE001 — empty index, etc.
+            logger.debug("vector_search returned nothing (%s)", exc)
+            return []
+        out: list[tuple[str, float]] = []
+        for h in hits:
+            nid = h["id"]
+            if nid is None:
+                continue
+            meta.setdefault(nid, {"label": h.get("label"), "type": h.get("type")})
+            out.append((nid, float(h["similarity"])))
+        return out
+
+    def _graph_stream(
+        self, seeds: list[str], meta: dict[str, dict]
+    ) -> tuple[dict[str, float], list[dict]]:
+        s_g: dict[str, float] = {seed: 1.0 for seed in seeds}
+        hops: list[dict] = []
+
+        # multiplicative BFS: path score = product of edge confidences
+        frontier: dict[str, float] = {seed: 1.0 for seed in seeds}
+        visited: set[str] = set(seeds)
+        for _ in range(config.GRAPH_MAX_HOPS):
+            if not frontier:
+                break
+            expanded = self.db.expand_frontier(
+                list(frontier), config.GRAPH_NEIGHBOR_K, config.MAX_DEGREE
+            )
+            next_frontier: dict[str, float] = {}
+            for node_id, acc in frontier.items():
+                for nb in expanded.get(node_id, []):
+                    to_id = nb["id"]
+                    conf = nb["confidence"]
+                    path_score = acc * conf
+                    hops.append({"from_id": node_id, "to_id": to_id, "confidence": conf})
+                    meta.setdefault(to_id, {"label": nb["label"], "type": nb["type"]})
+                    if path_score > s_g.get(to_id, 0.0):
+                        s_g[to_id] = path_score
+                    if to_id not in visited:
+                        visited.add(to_id)
+                        if path_score > next_frontier.get(to_id, 0.0):
+                            next_frontier[to_id] = path_score
+            frontier = next_frontier
+        return s_g, hops
+
+    def _attach_documents(self, results: list[RoutedNode]) -> None:
+        docs_by_entity = self.db.documents_for_entities([r.id for r in results])
+        for r in results:
+            r.documents = docs_by_entity.get(r.id, [])
+
+    def build_context(self, results: list[RoutedNode]) -> str:
+        """Assemble deduplicated context: cheap graph traces first, heavy text last."""
+        seen_chunk_ids: set[str] = set()
+        graph_traces: list[str] = []
+        text_chunks: list[str] = []
+
+        for node in results:
+            label = node.label or node.id
+            ntype = node.type or "Unknown"
+            graph_traces.append(f"- {label} ({ntype})")
+            for d in node.documents:
+                cid = d.get("doc_id")
+                text = (d.get("content") or "").strip()
+                if not text:
+                    continue
+                if cid not in seen_chunk_ids:
+                    seen_chunk_ids.add(cid)
+                    text_chunks.append(f"[{label}] {text}")
+                else:
+                    # duplicate chunk: keep the relationship fact, drop the text
+                    graph_traces.append(f"  [Trace: {label} ({ntype}) -> {cid}]")
+
+        sections: list[str] = []
+        if graph_traces:
+            sections.append("SYSTEM TRACES:\n" + "\n".join(graph_traces))
+        if text_chunks:
+            sections.append("DOCUMENT CHUNKS:\n" + "\n\n".join(text_chunks))
+        return "\n\n".join(sections)
+
+    def route(self, query: str, top_k: int | None = None) -> RouterResponse:
+        # Bound input size: spaCy/embedding cost scales with length, so an
+        # oversized query is a CPU-DoS. Real questions are short — truncate.
+        query = (query or "")[: config.MAX_QUERY_CHARS]
+        t0 = time.perf_counter()
+        alpha, beta, intent = self._classify_intent(query)
+        t_intent = time.perf_counter()
+        total_k = top_k if top_k is not None else config.TOP_K_VECTOR
+        meta: dict[str, dict] = {}
+
+        pool = self._vector_hits(query, config.TOP_K_VECTOR, meta)
+        t_vector = time.perf_counter()
+
+        # seeds: deterministic entity links first, then fuzzy cosine seeds
+        linked_seeds = self._link_query_entities(query, meta)
+        fuzzy_seeds = [
+            nid for nid, sv in sorted(pool, key=lambda kv: -kv[1])
+            if sv >= config.GRAPH_SEED_MIN_SIM
+        ][: config.GRAPH_SEED_TOP_N]
+        seeds = list(dict.fromkeys(linked_seeds + fuzzy_seeds))
+
+        # fallback: anchor on top vector hits so a relational query never idles at 0 hops
+        if not seeds and pool:
+            seeds = [
+                nid for nid, _ in sorted(pool, key=lambda kv: -kv[1])
+            ][: config.GRAPH_SEED_TOP_N]
+        t_seeds = time.perf_counter()
+
+        graph_scores, hops = self._graph_stream(seeds, meta)
+        t_graph = time.perf_counter()
+        seed_set = set(seeds)
+        graph_hits = sum(1 for nid in graph_scores if nid not in seed_set)
+
+        # dynamic throttle: more graph hits -> fewer bulky vector chunks
+        vector_k = max(2, total_k - graph_hits)
+        vector_scores = dict(pool[:vector_k])
+
+        results: list[RoutedNode] = []
+        for nid in set(vector_scores) | set(graph_scores):
+            sv = vector_scores.get(nid, 0.0)
+            sg = graph_scores.get(nid, 0.0)
+            info = meta.get(nid, {})
+            results.append(RoutedNode(
+                id=nid,
+                label=info.get("label"),
+                type=info.get("type"),
+                score_total=alpha * sv + beta * sg,
+                score_vector=sv,
+                score_graph=sg,
+            ))
+        results.sort(key=lambda r: r.score_total, reverse=True)
+        results = results[:total_k]
+
+        self._attach_documents(results)
+        t_docs = time.perf_counter()
+
+        logger.info(
+            "route timings (ms): intent=%.0f vector=%.0f seeds=%.0f graph=%.0f "
+            "assemble=%.0f | TOTAL=%.0f  [intent=%s seeds=%d hops=%d]",
+            (t_intent - t0) * 1000, (t_vector - t_intent) * 1000,
+            (t_seeds - t_vector) * 1000, (t_graph - t_seeds) * 1000,
+            (t_docs - t_graph) * 1000, (t_docs - t0) * 1000,
+            intent, len(seeds), len(hops),
+        )
+
+        trace_log = {
+            "intent": {"alpha": alpha, "beta": beta, "type": intent},
+            "execution_path": {
+                "linked_seeds": linked_seeds,
+                "vector_seeds": seeds,
+                "graph_hops": hops,
+            },
+            "metrics": {
+                "graph_hits": graph_hits,
+                "vector_k": vector_k,
+                "total_nodes_evaluated": len(vector_scores) + len(graph_scores),
+            },
+        }
+        return RouterResponse(query=query, results=results, trace_log=trace_log)