FinRAG backend

.dockerignore

@@ -0,0 +1,36 @@
+# Build context is the repo root (see backend/Dockerfile). Keep the image lean
+# and secret-free: ship only the backend source + the two runtime data artifacts.
+
+# Secrets — never bake keys into the image (use Fly secrets / env vars instead)
+.env
+.env.*
+!.env.example
+
+# Frontend deploys separately (Vercel)
+frontend/
+
+# Python / build cruft
+**/__pycache__/
+**/*.py[cod]
+backend/.venv/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Heavy data NOT needed at runtime (offline ingestion inputs + eval outputs).
+# data/duckdb/ and data/bm25_index.pkl are intentionally NOT ignored — the
+# runtime needs them and the Dockerfile COPYs them explicitly.
+data/raw/
+data/processed/
+data/*.json
+data/eval_results_*.json
+data/smoke_results.json
+
+# Repo meta
+.git/
+.github/
+docs/
+*.md
+PLAN.md
+infra/

.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
+*.duckdb filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,49 @@
+# FinRAG backend image — portable across hosts (Hugging Face Spaces, Render,
+# Cloud Run, local). Build context = repo ROOT (it needs backend/ + data/):
+#   docker build -t finrag-api .
+#
+# Image layout mirrors the dev tree so REPO_ROOT resolves identically:
+#   config.py at /app/backend/src/finrag/config.py → parents[3] == /app
+#   → DuckDB + BM25 (REPO_ROOT/data/...) live at /app/data. WORKDIR=/app keeps
+#   settings.duckdb_path ("./data/...") valid too.
+#
+# Port: listens on $PORT if the host injects one (Render/Cloud Run), else 8000.
+# On Hugging Face Spaces, declare `app_port: 8000` in the Space README frontmatter.
+
+# ---- builder: resolve + install deps into a venv (no ingestion/dev groups) ----
+FROM python:3.11-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:0.11.15 /uv /uvx /bin/
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
+WORKDIR /app/backend
+COPY backend/pyproject.toml backend/uv.lock ./
+RUN uv sync --frozen --no-install-project --no-dev
+COPY backend/ ./
+RUN uv sync --frozen --no-dev
+
+# ---- runtime: slim, non-root ----
+FROM python:3.11-slim AS runtime
+# libgomp1 covers numpy/rank-bm25's OpenMP dependency on slim.
+RUN apt-get update && apt-get install -y --no-install-recommends libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+RUN useradd -m -u 1000 appuser
+WORKDIR /app
+
+# Installed venv + editable project source (finrag → backend/src), then the two
+# runtime data artifacts (Qdrant vectors live in the cloud cluster, not here).
+COPY --from=builder --chown=appuser:appuser /app/backend /app/backend
+COPY --chown=appuser:appuser data/duckdb /app/data/duckdb
+COPY --chown=appuser:appuser data/bm25_index.pkl /app/data/bm25_index.pkl
+
+ENV PATH="/app/backend/.venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONIOENCODING=utf-8 \
+    PORT=8000
+USER appuser
+EXPOSE 8000
+
+# Healthcheck honors $PORT so it stays correct on any host.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=25s --retries=3 \
+  CMD python -c "import os,sys,urllib.request; p=os.environ.get('PORT','8000'); sys.exit(0 if urllib.request.urlopen(f'http://localhost:{p}/health',timeout=3).status==200 else 1)"
+
+# Shell form so ${PORT} expands at runtime.
+CMD ["sh", "-c", "uvicorn finrag.main:app --host 0.0.0.0 --port ${PORT:-8000}"]

README.md

@@ -1,10 +1,27 @@
 ---
-title: Finrag Api
-emoji: 🐠
-colorFrom: gray
-colorTo: green
+title: FinRAG API
+emoji: 📊
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 8000
 pinned: false
+short_description: Agentic RAG over SEC 10-K filings — cost-capped public demo backend
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FinRAG — backend (Hugging Face Space)
+
+This Space runs the **FinRAG** FastAPI backend as a Docker container. The chat
+frontend is hosted separately (Vercel) and calls this Space's URL. Full source,
+architecture, and the evaluation writeup live in the GitHub repo.
+
+**Endpoints:** `/health` · `/query` · `/answer` · `/agent` · `/agent/stream`
+
+**Guardrails are active** (this is a public demo on a funded key): a per-IP rate
+limit and a global daily question cap (the agent runs on Claude Haiku). Hit
+`/health` to see the remaining daily quota. For unlimited use, run it locally —
+see the GitHub README.
+
+> NOTE: this file is the **Space's** README (HF reads the frontmatter above for
+> the Docker SDK + port). It is intentionally separate from the GitHub repo's
+> README. Copy it to the Space repo root as `README.md`.

backend/.python-version

@@ -0,0 +1 @@
+3.11

backend/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "finrag"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Aryan Sharma", email = "aryan250403@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "anthropic>=0.40",
+    "cohere>=6.1.0",
+    "duckdb>=1.5.3",
+    "fastapi[standard]>=0.136.1",
+    "google-genai>=2.8.0",
+    "langgraph>=1.2.4",
+    "openai>=1.50",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.14.1",
+    "qdrant-client>=1.18.0",
+    "rank-bm25>=0.2.2",
+]
+
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.13",
+]
+# Offline ingestion only (parse.py). Pulls torch/transformers/onnxruntime via
+# unstructured[pdf] — multi-GB and slow — so it is deliberately OUT of the
+# runtime dependency set: the serving image (and `uv sync --no-dev`) skip it.
+# Build/refresh the corpus with:  uv sync --group ingestion
+ingestion = [
+    "unstructured[pdf]>=0.22.29",
+]
+
+  [tool.ruff]
+  line-length = 100
+  target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N"]
+# E: pycodestyle errors
+# F: pyflakes (unused imports, undefined names)
+# I: isort (import order)
+# B: bugbear (likely bugs)
+# UP: pyupgrade (modernize syntax)
+# N: pep8-naming

backend/src/finrag/agent/__init__.py

@@ -0,0 +1,13 @@
+"""FinRAG agent — LangGraph state machine over the Decision-15 tools.
+
+Public surface: `run_agent(question)` returns the final AgentState
+(answer + route + chunks + trace + usage). `main.py`'s /agent endpoint and the
+graph's own __main__ are the two callers.
+"""
+
+from __future__ import annotations
+
+from finrag.agent.graph import build_graph, get_agent, run_agent
+from finrag.agent.state import AgentState
+
+__all__ = ["run_agent", "get_agent", "build_graph", "AgentState"]

backend/src/finrag/agent/graph.py

@@ -0,0 +1,62 @@
+"""Wire the nodes into a LangGraph state machine.
+
+    START → plan ──(vector|both)──→ retrieve ─┐
+                  └──────(sql)────────────────┤
+                                              ↓
+                                agent(tool-loop) → END
+
+`plan` does rewrite+route in one call (free-tier request budget). The
+conditional edge is the one branch: sql-only questions skip vector retrieval
+and go straight to the tool-loop (the agent calls sql_query itself);
+vector/both questions pre-fetch chunks first.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from langgraph.graph import END, START, StateGraph
+
+from finrag.agent import nodes
+from finrag.agent.state import AgentState
+
+
+def _after_route(state: AgentState) -> str:
+    return "retrieve" if state.get("route") in ("vector", "both") else "agent"
+
+
+def build_graph():
+    g = StateGraph(AgentState)
+    g.add_node("plan", nodes.plan)
+    g.add_node("retrieve", nodes.retrieve)
+    g.add_node("agent", nodes.agent)
+
+    g.add_edge(START, "plan")
+    g.add_conditional_edges(
+        "plan", _after_route, {"retrieve": "retrieve", "agent": "agent"}
+    )
+    g.add_edge("retrieve", "agent")
+    g.add_edge("agent", END)
+    return g.compile()
+
+
+@lru_cache(maxsize=1)
+def get_agent():
+    """Compiled graph, built once per process (compilation is non-trivial)."""
+    return build_graph()
+
+
+def run_agent(question: str) -> AgentState:
+    return get_agent().invoke({"question": question, "trace": []})
+
+
+if __name__ == "__main__":
+    import json
+
+    final = run_agent("How did Apple's services revenue change in fiscal 2023, and by what percent?")
+    print("ROUTE :", final.get("route"))
+    print("ANSWER:", final.get("answer"))
+    print("USAGE :", final.get("usage"))
+    print("TRACE :")
+    for step in final.get("trace", []):
+        print("  -", json.dumps(step)[:200])

backend/src/finrag/agent/nodes.py

@@ -0,0 +1,227 @@
+"""The agent's LangGraph nodes.
+
+Flow: rewrite_query → route → (retrieve?) → agent(tool-loop+synthesis) → END.
+
+Design note: the handoff listed tool-loop and synthesize as separate steps, but
+with native function-calling they're one node by construction — the loop runs
+until the model stops emitting function_calls and produces its final text, and
+that terminal text *is* the synthesis. We still emit a distinct 'synthesize'
+trace event so the frontend (Decision 18) can render it as its own step.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from finrag.agent.state import AgentState
+from finrag.ingestion.facts import corpus_companies, corpus_years
+from finrag.llm import generate_text, run_tool_loop_stream, synthesize
+from finrag.llm.base import ToolCall, format_chunks_for_prompt
+from finrag.retrieval.rerank import rerank_search
+
+MAX_TOOL_ITERS = 5  # hard cap so a confused model can't loop forever
+
+
+@lru_cache(maxsize=1)
+def _corpus_grounding() -> str:
+    """Tell the model the exact known universe so vague references ('these three
+    companies', 'all of them') resolve to real corpus members instead of the
+    model guessing (it would otherwise pull in Microsoft/Google). Data-driven —
+    reads the loaded DuckDB, so it can never drift from what's queryable."""
+    companies = corpus_companies()
+    if not companies:  # corpus not loaded — emit nothing rather than a wrong claim
+        return ""
+    lo, hi = corpus_years()
+    span = f"fiscal years {lo}–{hi}" if lo and hi else "the available fiscal years"
+    listing = "; ".join(f"{name} ({ticker})" for ticker, name in companies)
+    return (
+        f"\n\nKNOWN CORPUS — the dataset contains EXACTLY these {len(companies)} "
+        f"companies, {span}: {listing}.\n"
+        "When the question refers to the companies without naming them ('these "
+        "companies', 'the three companies', 'all of them', 'each company'), it means "
+        "exactly this set — resolve the reference to these names. Never introduce a "
+        "company outside this set; if asked about one that isn't listed, say it is not "
+        "in the corpus rather than answering from general knowledge."
+    )
+
+
+def _stream_writer():
+    """LangGraph custom-stream writer when the graph is driven by
+    `graph.stream(..., stream_mode=[..., "custom"])` (the /agent/stream SSE
+    path); a no-op otherwise (plain invoke / direct call). The same agent node
+    therefore serves both /agent and /agent/stream without branching."""
+    try:
+        from langgraph.config import get_stream_writer
+
+        return get_stream_writer()
+    except Exception:
+        return lambda _data: None
+
+# ── Prompts ────────────────────────────────────────────────────────────────
+# rewrite + route merged into ONE call to save a request against the free-tier
+# 5-req/min cap (the agent is call-heavy). The route hint is also tightened:
+# segment-level figures (services/product revenue) live in narrative, not in
+# our top-level XBRL facts, so they must route to vector — this fixes the
+# earlier mis-route that answered "services revenue" with total revenue.
+_PLAN_SYSTEM = """You prepare a question about SEC 10-K filings for retrieval. Do two things:
+
+1. Rewrite it as a concise, self-contained search query: resolve vague references, and make the company and fiscal year explicit if implied.
+2. Classify what it needs:
+   - vector : qualitative/narrative content, OR segment-level figures like services/product/regional revenue (these live in the filing text, not the figures database)
+   - sql    : precise TOP-LEVEL financials (total revenue, net income, total assets, margins, multi-year or cross-company comparisons)
+   - both   : needs narrative AND exact top-level figures
+
+Output EXACTLY two lines, nothing else:
+QUERY: <rewritten query>
+ROUTE: <vector|sql|both>"""
+
+_AGENT_SYSTEM = """You are a financial analyst assistant answering questions about SEC 10-K filings.
+
+You have tools:
+- sql_query: get EXACT figures for TOP-LEVEL metrics only (total revenue, net income, total assets, margins). Prefer it for those over reading numbers from text. It does NOT have segment/product/regional figures (e.g. services revenue, iPhone revenue) — for those, read the value from the context chunks and cite [N]. If sql_query returns an error, fall back to the context.
+- calculator: do arithmetic (growth rates, margins, ratios). Extract numbers, then compute — never do multi-digit math in your head.
+- lookup_citation: re-fetch a chunk's full text by chunk_id if you need to quote it exactly. Pass the exact id shown as (id=...) in the chunk's header — never the [N] anchor.
+
+Rules:
+1. Ground every claim in the provided context chunks or tool results. If neither contains the answer, say so — do not use prior knowledge.
+2. A figure must actually match what was asked. If a tool returns a number for a different metric than the question, do not report it — use the context instead.
+3. Cite narrative facts from the context with [N], where N is the chunk index shown. Cite even when paraphrasing.
+4. Quote exact figures; never round unless asked.
+5. Be careful with fiscal vs calendar year (Apple's fiscal year ends in late September).
+6. Be concise — match the question's scope.
+7. Do not embellish. State only what the context or tool results actually support. Do not add provenance you cannot see (e.g. "as disclosed in the 10-K" when the figure came from the figures database), characterizations ("a record-setting profit", "strong performance"), or outside facts not present in the context/tool results. A correct figure with ungrounded commentary is still a faithfulness failure.
+"""
+
+
+def _parse_plan(raw: str, fallback_query: str) -> tuple[str, str]:
+    """Parse the two-line plan output into (rewritten_query, route)."""
+    query, route = fallback_query, "both"
+    for line in raw.splitlines():
+        s = line.strip()
+        low = s.lower()
+        if low.startswith("query:"):
+            query = s.split(":", 1)[1].strip() or fallback_query
+        elif low.startswith("route:"):
+            r = s.split(":", 1)[1].strip().lower()
+            if "both" in r:
+                route = "both"
+            elif "sql" in r:
+                route = "sql"
+            elif "vector" in r:
+                route = "vector"
+    return query, route
+
+
+def plan(state: AgentState) -> AgentState:
+    """One call that both rewrites the query and routes it. Emits two trace
+    events so the frontend still shows rewrite and route as distinct steps."""
+    original = state["question"]
+    # Ground the rewrite in the known corpus so "these 3 companies" expands to the
+    # real names here, before retrieval and the agent ever see the query.
+    raw = generate_text(_PLAN_SYSTEM + _corpus_grounding(), original, max_output_tokens=128)
+    rewritten, decision = _parse_plan(raw, original)
+    return {
+        "rewritten_query": rewritten,
+        "route": decision,
+        "trace": [
+            {
+                "node": "plan",
+                "type": "rewrite",
+                "data": {"original": original, "rewritten": rewritten},
+            },
+            {"node": "plan", "type": "route", "data": {"route": decision}},
+        ],
+    }
+
+
+def retrieve(state: AgentState) -> AgentState:
+    """Vector retrieval via the Day-2 funnel. Reached only when the route
+    includes vector (conditional edge in graph.py)."""
+    chunks = rerank_search(question=state["rewritten_query"], top_k=8)
+    return {
+        "chunks": chunks,
+        "trace": [
+            {
+                "node": "retrieve",
+                "type": "retrieve",
+                "data": {
+                    "n_chunks": len(chunks),
+                    "top": [
+                        {"chunk_id": c.chunk_id, "ticker": c.ticker, "fy": c.fiscal_year}
+                        for c in chunks[:3]
+                    ],
+                },
+            }
+        ],
+    }
+
+
+def agent(state: AgentState) -> AgentState:
+    """Provider-neutral tool-calling loop (Claude tool_use or Gemini function
+    calling, per llm_provider). Runs tools until a final text answer, surfacing
+    each tool call in the trace (the SQL/args are the demo payload)."""
+    chunks = state.get("chunks", [])
+    context = (
+        format_chunks_for_prompt(chunks)
+        if chunks
+        else "(no vector context retrieved — rely on tools)"
+    )
+    user_text = f"Question: {state['rewritten_query']}\n\nContext chunks:\n\n{context}"
+
+    # Push live events to the SSE stream (no-op under plain /agent). Tokens are
+    # the final answer forming; tool_call fires the instant a tool runs.
+    writer = _stream_writer()
+
+    def on_text(delta: str) -> None:
+        writer({"type": "token", "text": delta})
+
+    def on_tool_call(tc: ToolCall) -> None:
+        writer(
+            {
+                "type": "tool_call",
+                "node": "agent",
+                "data": {"tool": tc.tool, "args": tc.args, "result": tc.result},
+            }
+        )
+
+    result = run_tool_loop_stream(
+        _AGENT_SYSTEM + _corpus_grounding(),
+        user_text,
+        # 1024 truncated detailed multi-company answers mid-sentence (e.g. a risk
+        # comparison table got cut off). 4096 comfortably fits the longest answers
+        # we produce while staying well under Sonnet's output limit.
+        max_tokens=4096,
+        max_iters=MAX_TOOL_ITERS,
+        on_text=on_text,
+        on_tool_call=on_tool_call,
+    )
+
+    trace: list[dict] = [
+        {
+            "node": "agent",
+            "type": "tool_call",
+            "data": {"tool": tc.tool, "args": tc.args, "result": tc.result},
+        }
+        for tc in result.tool_calls
+    ]
+    usage = {"input_tokens": result.input_tokens, "output_tokens": result.output_tokens}
+    answer = result.answer
+
+    # Reliability floor: if the tool-loop yields no answer (e.g. a backend that
+    # intermittently botches a tool call), fall back to plain synthesis over the
+    # retrieved chunks — the proven /answer path, no tool-calling involved.
+    if not answer.strip() and chunks:
+        fb = synthesize(state["rewritten_query"], chunks)
+        answer = fb.answer
+        usage["input_tokens"] += fb.input_tokens
+        usage["output_tokens"] += fb.output_tokens
+        trace.append(
+            {
+                "node": "agent",
+                "type": "fallback",
+                "data": {"reason": "tool-loop produced no answer; synthesized from retrieved chunks"},
+            }
+        )
+
+    trace.append({"node": "agent", "type": "synthesize", "data": {"answer": answer}})
+    return {"answer": answer, "usage": usage, "trace": trace}

backend/src/finrag/agent/state.py

@@ -0,0 +1,25 @@
+"""LangGraph state for the FinRAG agent.
+
+The state is a TypedDict threaded through every node; each node returns a
+partial dict that LangGraph merges in. `trace` uses an additive reducer so
+every node *appends* its step (rather than overwriting) — that accumulated
+list is what Decision 18's frontend renders as the agent's visible reasoning.
+"""
+
+from __future__ import annotations
+
+import operator
+from typing import Annotated, Any, TypedDict
+
+from finrag.retrieval.vector import RetrievedChunk
+
+
+class AgentState(TypedDict, total=False):
+    question: str                 # raw user question
+    rewritten_query: str          # normalized, self-contained query
+    route: str                    # "vector" | "sql" | "both"
+    chunks: list[RetrievedChunk]  # vector context (empty for sql-only routes)
+    answer: str                   # final grounded answer
+    usage: dict[str, int]         # token totals across all agent LLM calls
+    # Additive: nodes append step records; the reducer concatenates them.
+    trace: Annotated[list[dict[str, Any]], operator.add]

backend/src/finrag/config.py

@@ -0,0 +1,53 @@
+# src/finrag/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pathlib import Path
+REPO_ROOT = Path(__file__).resolve().parents[3]
+# config.py → finrag/ → src/ → backend/ → REPO_ROOT
+
+class Settings(BaseSettings):
+    # Both provider keys are optional: the active one is decided by
+    # `llm_provider`, and we validate presence lazily at call time so a
+    # Gemini-only setup doesn't need an Anthropic key (and vice versa).
+    anthropic_api_key: str | None = None
+    gemini_api_key: str | None = None
+    cohere_api_key: str
+    qdrant_url: str = "http://localhost:6333"
+    qdrant_api_key: str | None = None
+    duckdb_path: str = "./data/duckdb/finrag.duckdb"
+    llm_mode: str = "cloud"
+    # Which backend the finrag.llm dispatchers use: "anthropic" | "gemini" | "local".
+    llm_provider: str = "anthropic"
+    # Anthropic model. Default = the eval-validated Sonnet; the public demo deploy
+    # overrides this to Haiku (CLAUDE_MODEL=claude-haiku-4-5-20251001) to cut the
+    # per-question cost ~10x behind the guardrails below.
+    claude_model: str = "claude-sonnet-4-6"
+
+    # ── Public-deploy guardrails (only bite when a real client calls) ──
+    # CORS allow-list, comma-separated. Dev defaults to the Next.js dev server;
+    # the prod deploy sets this to the exact Vercel origin (see docs/deploy.md).
+    allowed_origins: str = "http://localhost:3000,http://127.0.0.1:3000"
+    # Per-IP sliding-window limit on the PAID endpoints (/answer,/agent[,/stream]).
+    rate_limit_per_min: int = 8
+    # Global hard ceiling on paid questions per UTC day — the cost circuit-breaker.
+    # 300 Haiku agent-questions ≈ a couple of dollars worst case; past it the API
+    # returns 429 until midnight UTC instead of burning the key.
+    daily_question_cap: int = 300
+
+    @property
+    def allowed_origins_list(self) -> list[str]:
+        return [o.strip() for o in self.allowed_origins.split(",") if o.strip()]
+
+    # ── Local / edge provider (Ollama, OpenAI-compatible API on :11434) ──
+    # Used only when llm_provider == "local". base_url is the OpenAI-compat
+    # endpoint, so the same backend would target vLLM/llama.cpp/LM Studio by
+    # swapping this one value. local_use_tools is the kill-switch: True runs the
+    # real agentic tool-loop (tests whether a 3B model can drive it); False runs
+    # degraded synthesis-only over retrieved context (the documented fallback for
+    # small models whose tool-calling is unreliable — see docs/handoff.md Day 5).
+    local_model: str = "llama3.2:3b"
+    local_base_url: str = "http://localhost:11434/v1"
+    local_use_tools: bool = True
+
+    model_config = SettingsConfigDict(env_file=REPO_ROOT / ".env", extra="ignore")
+
+settings = Settings()  # validates at import time

backend/src/finrag/eval/dataset.py

@@ -0,0 +1,180 @@
+"""Day-4 evaluation set — the questions that make the system *provable*.
+
+Four tiers, each probing a distinct failure mode of an agentic RAG system:
+
+  factual   → sql route. One exact top-level figure. We assert the number
+              appears in the answer. Ground truth is read from our own
+              `financial_facts` table (correct-by-construction), so this tier
+              is really a regression check: does the agent route to sql and
+              report the figure *faithfully*, or hallucinate / mis-label it
+              (the exact bug that survived Day 2)?
+  narrative → vector route. Qualitative content. No numeric ground truth;
+              graded by the LLM judge on faithfulness + answer relevance, and
+              by a deterministic check that the answer actually cites [N].
+  multihop  → both + calculator. A figure that must be *computed* (YoY growth,
+              margin) or a cross-company comparison. Tests retrieval + tool use
+              + arithmetic end to end.
+  honesty   → unanswerable from the corpus (a company/year we don't have, or a
+              forward-looking number). The agent must DECLINE, not fabricate —
+              the single most important behaviour for a finance assistant.
+
+Ground truth for the numeric tiers is a `gt` callable resolved lazily against
+DuckDB, so this module imports without touching the DB and the numbers can
+never drift from what the agent can actually query.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from finrag.ingestion.facts import query
+
+# ── Tiers ────────────────────────────────────────────────────────────────
+FACTUAL = "factual"
+NARRATIVE = "narrative"
+MULTIHOP = "multihop"
+HONESTY = "honesty"
+
+
+@dataclass(frozen=True)
+class EvalCase:
+    id: str
+    tier: str
+    question: str
+    # Soft expectation — the plan node's route. We record match/mismatch but a
+    # mismatch isn't a hard failure (the agent can still answer correctly via a
+    # different path).
+    route_expected: str | None = None
+    # Numeric ground truth, resolved lazily from the DB at run time.
+    gt: Callable[[], float] | None = None
+    gt_kind: str = "currency"  # currency | per_share | percent
+    # Relative tolerance for currency/per_share; for percent it's the absolute
+    # percentage-point floor (combined with a 5% relative band in the matcher).
+    tol: float = 0.015
+    # For name-style answers ("which company…") and any case where a substring
+    # must appear (e.g. the right company name).
+    expect_substring: str | None = None
+    # Honesty tier: the agent must refuse / say it's not in the corpus.
+    must_decline: bool = False
+
+
+# ── Ground-truth helper ──────────────────────────────────────────────────
+def _v(ticker: str, line_item: str, fy: int, unit: str = "USD") -> float:
+    """The single authoritative value for a (ticker, line_item, year) from
+    financial_facts — the same table sql_query reads. LIMIT 1 because each of
+    our three filers resolves to one surviving GAAP concept per annual period
+    (see facts.py dedup); ordering by value desc is a stable tie-break."""
+    rows = query(
+        """
+        SELECT value FROM financial_facts
+        WHERE ticker = ? AND line_item = ? AND fiscal_year = ?
+          AND fiscal_period = 'FY' AND unit = ?
+        ORDER BY value DESC LIMIT 1
+        """,
+        [ticker, line_item, fy, unit],
+    )
+    if not rows:
+        raise LookupError(f"no fact for {ticker} {line_item} FY{fy} ({unit})")
+    return float(rows[0]["value"])
+
+
+def _yoy(ticker: str, line_item: str, y0: int, y1: int) -> float:
+    """Year-over-year percent growth from y0 to y1."""
+    a, b = _v(ticker, line_item, y0), _v(ticker, line_item, y1)
+    return (b - a) / a * 100.0
+
+
+def _margin(ticker: str, part: str, whole: str, fy: int) -> float:
+    """A margin in percent (e.g. gross_profit / revenue)."""
+    return _v(ticker, part, fy) / _v(ticker, whole, fy) * 100.0
+
+
+# ── The set ──────────────────────────────────────────────────────────────
+CASES: list[EvalCase] = [
+    # ─────────── FACTUAL (sql route, exact figure) ───────────
+    EvalCase("f01", FACTUAL, "What was Apple's net income in fiscal 2023?",
+             route_expected="sql", gt=lambda: _v("AAPL", "net_income", 2023)),
+    EvalCase("f02", FACTUAL, "What was Apple's total revenue in fiscal 2024?",
+             route_expected="sql", gt=lambda: _v("AAPL", "revenue", 2024)),
+    EvalCase("f03", FACTUAL, "How much did Tesla spend on research and development in fiscal 2023?",
+             route_expected="sql", gt=lambda: _v("TSLA", "rd_expense", 2023)),
+    EvalCase("f04", FACTUAL, "What were JPMorgan's total assets at the end of fiscal 2023?",
+             route_expected="sql", gt=lambda: _v("JPM", "total_assets", 2023)),
+    EvalCase("f05", FACTUAL, "What was Apple's operating income in fiscal 2022?",
+             route_expected="sql", gt=lambda: _v("AAPL", "operating_income", 2022)),
+    EvalCase("f06", FACTUAL, "What was Tesla's total revenue in fiscal 2024?",
+             route_expected="sql", gt=lambda: _v("TSLA", "revenue", 2024)),
+    EvalCase("f07", FACTUAL, "What was JPMorgan's net income in fiscal 2024?",
+             route_expected="sql", gt=lambda: _v("JPM", "net_income", 2024)),
+    EvalCase("f08", FACTUAL, "What was Apple's gross profit in fiscal 2023?",
+             route_expected="sql", gt=lambda: _v("AAPL", "gross_profit", 2023)),
+    EvalCase("f09", FACTUAL, "What was Tesla's diluted earnings per share in fiscal 2023?",
+             route_expected="sql", gt=lambda: _v("TSLA", "eps_diluted", 2023, "USD/shares"),
+             gt_kind="per_share"),
+    EvalCase("f10", FACTUAL, "What was JPMorgan's net interest income in fiscal 2024?",
+             route_expected="sql", gt=lambda: _v("JPM", "net_interest_income", 2024)),
+
+    # ─────────── NARRATIVE (vector route, faithfulness + citation) ───────────
+    EvalCase("n01", NARRATIVE, "How does Apple describe the risks to its supply chain in its 10-K?",
+             route_expected="vector"),
+    EvalCase("n02", NARRATIVE, "What does Tesla say about competition in the electric-vehicle market?",
+             route_expected="vector"),
+    EvalCase("n03", NARRATIVE, "How does JPMorgan describe credit risk in its filing?",
+             route_expected="vector"),
+    EvalCase("n04", NARRATIVE, "How does Apple characterize its Services business and what drives its growth?",
+             route_expected="vector"),
+    EvalCase("n05", NARRATIVE, "What risks does Tesla cite related to its dependence on key personnel?",
+             route_expected="vector"),
+    EvalCase("n06", NARRATIVE, "How does Apple describe foreign-currency exchange-rate risk?",
+             route_expected="vector"),
+    EvalCase("n07", NARRATIVE, "What does Tesla say about risks in ramping production and manufacturing?",
+             route_expected="vector"),
+    EvalCase("n08", NARRATIVE, "How does JPMorgan describe the regulatory and capital requirements it faces?",
+             route_expected="vector"),
+
+    # ─────────── MULTIHOP (sql + calculator; route left soft) ───────────
+    # route_expected is None: each of these is answerable from structured facts
+    # plus arithmetic, so the router legitimately picks `sql` over `both`. The
+    # tier tests multi-step reasoning (fetch figure(s) → compute), not the route.
+    EvalCase("m01", MULTIHOP, "By what percentage did Apple's net income change from fiscal 2022 to fiscal 2023?",
+             gt=lambda: _yoy("AAPL", "net_income", 2022, 2023), gt_kind="percent"),
+    EvalCase("m02", MULTIHOP, "By what percentage did Tesla's revenue grow from fiscal 2023 to fiscal 2024?",
+             gt=lambda: _yoy("TSLA", "revenue", 2023, 2024), gt_kind="percent"),
+    EvalCase("m03", MULTIHOP, "What was Apple's gross margin in fiscal 2023?",
+             gt=lambda: _margin("AAPL", "gross_profit", "revenue", 2023), gt_kind="percent"),
+    EvalCase("m04", MULTIHOP, "What was Tesla's net profit margin in fiscal 2023?",
+             gt=lambda: _margin("TSLA", "net_income", "revenue", 2023), gt_kind="percent"),
+    EvalCase("m05", MULTIHOP, "What was Apple's operating margin in fiscal 2024?",
+             gt=lambda: _margin("AAPL", "operating_income", "revenue", 2024), gt_kind="percent"),
+    EvalCase("m06", MULTIHOP, "Which of the three companies had the highest net income in fiscal 2023?",
+             expect_substring="Apple"),
+    EvalCase("m07", MULTIHOP, "By what percentage did JPMorgan's net income change from fiscal 2023 to fiscal 2024?",
+             gt=lambda: _yoy("JPM", "net_income", 2023, 2024), gt_kind="percent"),
+
+    # ─────────── HONESTY (must decline — outside the corpus) ───────────
+    EvalCase("h01", HONESTY, "What was Microsoft's net income in fiscal 2023?",
+             must_decline=True),
+    EvalCase("h02", HONESTY, "What was Apple's total revenue in fiscal 2019?",
+             must_decline=True),  # outside our FY2022–2024 span
+    EvalCase("h03", HONESTY, "How many employees does Amazon have according to its 10-K?",
+             must_decline=True),  # company not in corpus
+    EvalCase("h04", HONESTY, "What will Tesla's revenue be in fiscal 2026?",
+             must_decline=True),  # forward-looking, not in any filing
+    EvalCase("h05", HONESTY, "What was Google's operating margin in fiscal 2023?",
+             must_decline=True),  # company not in corpus
+]
+
+
+def cases_for(tier: str | None = None) -> list[EvalCase]:
+    return [c for c in CASES if tier is None or c.tier == tier]
+
+
+def one_per_tier() -> list[EvalCase]:
+    """A 4-case smoke subset — first case of each tier. Used to validate the
+    harness end to end before spending on a full run, and as the Gemini A/B
+    subset that fits the free-tier daily quota."""
+    out: list[EvalCase] = []
+    for tier in (FACTUAL, NARRATIVE, MULTIHOP, HONESTY):
+        out.append(cases_for(tier)[0])
+    return out

backend/src/finrag/eval/harness.py

@@ -0,0 +1,283 @@
+"""Day-4 eval harness — runs the agent over the tiered set, scores each answer,
+and reports per-tier + overall metrics. Provider-parametrized so the same run
+drives the Claude vs Gemini A/B.
+
+    uv run python -m finrag.eval.harness                  # full set, Claude
+    uv run python -m finrag.eval.harness --smoke          # 1 per tier (cheap)
+    uv run python -m finrag.eval.harness --tier factual   # one tier
+    uv run python -m finrag.eval.harness --provider gemini --smoke   # A/B subset
+
+The judge is always Claude (see metrics.py); only the *system under test* flips
+with --provider, so the grader is held constant across the A/B.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from finrag.config import settings
+from finrag.eval import dataset as ds
+from finrag.eval import metrics as mt
+from finrag.llm.base import format_chunks_for_prompt
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+OUT_DIR = REPO_ROOT / "data"
+
+# Rough public list prices ($/M tokens) for an order-of-magnitude cost number.
+# We only have the agent node's tokens (the plan call's usage isn't threaded
+# into state), so this is a floor, labelled as such in the report.
+_RATES = {"anthropic": (3.0, 15.0), "gemini": (0.10, 0.40), "local": (0.0, 0.0)}
+
+
+@dataclass
+class CaseResult:
+    id: str
+    tier: str
+    question: str
+    route_expected: str | None
+    route_actual: str | None = None
+    answer: str = ""
+    n_chunks: int = 0
+    n_tool_calls: int = 0
+    latency_ms: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    # tier-specific scores (None when not applicable)
+    correct: bool | None = None          # factual/multihop exact-match; honesty=declined
+    route_match: bool | None = None
+    citation_valid: bool | None = None   # narrative
+    faithfulness: float | None = None
+    relevance: float | None = None
+    context_precision: float | None = None
+    declined: bool | None = None         # honesty
+    notes: list[str] = field(default_factory=list)
+    error: str | None = None
+
+
+def _grounding_context(final: dict) -> str:
+    """Reconstruct what the agent was grounded on: retrieved chunks + every tool
+    result it saw. This is the context the faithfulness judge scores against."""
+    parts: list[str] = []
+    chunks = final.get("chunks") or []
+    if chunks:
+        parts.append(format_chunks_for_prompt(chunks))
+    for step in final.get("trace", []):
+        if step.get("type") == "tool_call":
+            d = step["data"]
+            parts.append(f"[tool:{d['tool']}] args={d.get('args')} -> {d.get('result')}")
+    return "\n\n".join(parts) if parts else "(no context — model answered without retrieval or tools)"
+
+
+def _chunk_listing(chunks: list) -> str:
+    lines = []
+    for i, c in enumerate(chunks, 1):
+        head = f"[{i}] {c.ticker} FY{c.fiscal_year} {getattr(c, 'section_title', '') or ''}".strip()
+        lines.append(f"{head}: {c.text[:200]}")
+    return "\n".join(lines)
+
+
+def run_case(case: ds.EvalCase, *, judge: bool = True) -> CaseResult:
+    from finrag.agent.graph import run_agent  # lazy: heavy import
+
+    r = CaseResult(id=case.id, tier=case.tier, question=case.question,
+                   route_expected=case.route_expected)
+    t0 = time.perf_counter()
+    try:
+        final = run_agent(case.question)
+    except Exception as e:  # a backend hiccup shouldn't abort the whole run
+        r.error = f"{type(e).__name__}: {e}"
+        r.latency_ms = int((time.perf_counter() - t0) * 1000)
+        return r
+    r.latency_ms = int((time.perf_counter() - t0) * 1000)
+
+    r.answer = final.get("answer", "") or ""
+    r.route_actual = final.get("route")
+    r.route_match = (case.route_expected is None) or (r.route_actual == case.route_expected)
+    chunks = final.get("chunks") or []
+    r.n_chunks = len(chunks)
+    r.n_tool_calls = sum(1 for s in final.get("trace", []) if s.get("type") == "tool_call")
+    usage = final.get("usage") or {}
+    r.input_tokens = usage.get("input_tokens", 0)
+    r.output_tokens = usage.get("output_tokens", 0)
+
+    # ── deterministic tier checks ──
+    if case.tier == ds.HONESTY:
+        declined = mt.looks_like_refusal(r.answer)
+        if judge and not declined:  # keyword backstop missed — ask the judge
+            verdict = mt.judge_refusal(case.question, r.answer)
+            declined = bool(verdict.get("declined", False))
+            if verdict.get("reason"):
+                r.notes.append(f"refusal-judge: {verdict['reason']}")
+        r.declined = declined
+        r.correct = declined
+    elif case.gt is not None:
+        try:
+            expected = case.gt()
+            r.correct = mt.number_hit(expected, case.gt_kind, r.answer, case.tol)
+            r.notes.append(f"expected≈{expected:.4g} ({case.gt_kind})")
+        except Exception as e:
+            r.notes.append(f"gt-error: {e}")
+    elif case.expect_substring is not None:
+        r.correct = case.expect_substring.lower() in r.answer.lower()
+        r.notes.append(f"expect substring '{case.expect_substring}'")
+
+    if case.tier == ds.NARRATIVE:
+        valid, bad = mt.citation_validity(r.answer, r.n_chunks)
+        r.citation_valid = valid
+        if bad:
+            r.notes.append(f"out-of-range citations: {bad}")
+
+    # ── LLM-judge layer ──
+    if judge and case.tier != ds.HONESTY:
+        context = _grounding_context(final)
+        f = mt.judge_faithfulness(context, r.answer)
+        r.faithfulness = f.get("faithfulness")
+        if f.get("unsupported_claims"):
+            r.notes.append(f"unsupported: {f['unsupported_claims']}")
+        rel = mt.judge_relevance(case.question, r.answer)
+        r.relevance = rel.get("relevance")
+        if chunks and case.tier in (ds.NARRATIVE, ds.MULTIHOP):
+            p = mt.judge_precision(case.question, _chunk_listing(chunks))
+            idxs = p.get("relevant_indices") or []
+            if r.n_chunks:
+                r.context_precision = len([i for i in idxs if 1 <= i <= r.n_chunks]) / r.n_chunks
+    # Honesty tier is scored only by `declined`/accuracy — judging "relevance" of
+    # a correct refusal is misleading (the judge penalizes not answering), so we
+    # skip it.
+
+    return r
+
+
+# ── Aggregation ────────────────────────────────────────────────────────────
+def _mean(vals: list[float | None]) -> float | None:
+    nums = [v for v in vals if v is not None]
+    return sum(nums) / len(nums) if nums else None
+
+
+def _rate(vals: list[bool | None]) -> float | None:
+    bs = [v for v in vals if v is not None]
+    return sum(1 for v in bs if v) / len(bs) if bs else None
+
+
+def aggregate(results: list[CaseResult]) -> dict:
+    tiers: dict[str, list[CaseResult]] = {}
+    for r in results:
+        tiers.setdefault(r.tier, []).append(r)
+
+    def block(rs: list[CaseResult]) -> dict:
+        return {
+            "n": len(rs),
+            "errors": sum(1 for r in rs if r.error),
+            "accuracy": _rate([r.correct for r in rs]),
+            "route_match": _rate([r.route_match for r in rs]),
+            "citation_valid": _rate([r.citation_valid for r in rs]),
+            "faithfulness": _mean([r.faithfulness for r in rs]),
+            "relevance": _mean([r.relevance for r in rs]),
+            "context_precision": _mean([r.context_precision for r in rs]),
+            "avg_latency_ms": int(_mean([float(r.latency_ms) for r in rs]) or 0),
+        }
+
+    return {
+        "overall": block(results),
+        "by_tier": {tier: block(rs) for tier, rs in sorted(tiers.items())},
+    }
+
+
+def _fmt(v) -> str:
+    if v is None:
+        return "  –  "
+    if isinstance(v, float):
+        return f"{v:5.2f}"
+    return str(v)
+
+
+def print_report(provider: str, results: list[CaseResult], agg: dict) -> None:
+    in_tok = sum(r.input_tokens for r in results)
+    out_tok = sum(r.output_tokens for r in results)
+    ri, ro = _RATES.get(provider, (0, 0))
+    cost = in_tok / 1e6 * ri + out_tok / 1e6 * ro
+
+    print(f"\n{'='*78}\n  EVAL REPORT — provider={provider}  ({len(results)} cases)\n{'='*78}")
+    print(f"  {'case':5} {'tier':9} {'ok':3} {'route':5} {'cite':4} {'faith':6} {'rel':6} {'prec':6} {'ms':6}")
+    print(f"  {'-'*72}")
+    for r in results:
+        ok = "ERR" if r.error else ("✓" if r.correct else ("·" if r.correct is None else "✗"))
+        print(f"  {r.id:5} {r.tier:9} {ok:3} "
+              f"{('✓' if r.route_match else '✗') if r.route_match is not None else '–':5} "
+              f"{('✓' if r.citation_valid else '✗') if r.citation_valid is not None else '–':4} "
+              f"{_fmt(r.faithfulness):6} {_fmt(r.relevance):6} {_fmt(r.context_precision):6} {r.latency_ms:6}")
+
+    print(f"\n  {'TIER':10} {'n':3} {'acc':6} {'route':6} {'cite':6} {'faith':6} {'rel':6} {'prec':6}")
+    print(f"  {'-'*60}")
+    for tier, b in agg["by_tier"].items():
+        print(f"  {tier:10} {b['n']:3} {_fmt(b['accuracy']):6} {_fmt(b['route_match']):6} "
+              f"{_fmt(b['citation_valid']):6} {_fmt(b['faithfulness']):6} "
+              f"{_fmt(b['relevance']):6} {_fmt(b['context_precision']):6}")
+    o = agg["overall"]
+    print(f"  {'-'*60}")
+    print(f"  {'OVERALL':10} {o['n']:3} {_fmt(o['accuracy']):6} {_fmt(o['route_match']):6} "
+          f"{_fmt(o['citation_valid']):6} {_fmt(o['faithfulness']):6} "
+          f"{_fmt(o['relevance']):6} {_fmt(o['context_precision']):6}")
+    print(f"\n  errors={o['errors']}  agent-tokens in={in_tok} out={out_tok}  "
+          f"approx-cost=${cost:.3f} (agent node only; excludes plan call)")
+    # tokens/sec is the edge-relevant throughput number for the local model.
+    # Derived from wall-clock latency (no separate decode timer), so it's a
+    # coarse end-to-end rate, not a pure-decode tok/s.
+    total_ms = sum(r.latency_ms for r in results)
+    if provider == "local" and total_ms:
+        print(f"  local throughput≈{out_tok / (total_ms / 1000):.1f} output tok/s "
+              f"(end-to-end, over {total_ms/1000:.1f}s wall)\n")
+    else:
+        print()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="FinRAG Day-4 eval harness")
+    ap.add_argument("--provider", default=None, help="anthropic | gemini (default: current setting)")
+    ap.add_argument("--tier", default=None, choices=[ds.FACTUAL, ds.NARRATIVE, ds.MULTIHOP, ds.HONESTY])
+    ap.add_argument("--smoke", action="store_true", help="one case per tier (cheap pipeline check / A/B subset)")
+    ap.add_argument("--limit", type=int, default=None)
+    ap.add_argument("--no-judge", action="store_true", help="skip LLM-judge metrics (deterministic only)")
+    ap.add_argument("--out", default=None, help="results JSON path")
+    args = ap.parse_args()
+
+    if args.provider:
+        settings.llm_provider = args.provider  # dispatcher reads this live
+    provider = (settings.llm_provider or "anthropic").lower()
+
+    if args.smoke:
+        cases = ds.one_per_tier()
+    else:
+        cases = ds.cases_for(args.tier)
+    if args.limit:
+        cases = cases[: args.limit]
+
+    print(f"Running {len(cases)} cases · provider={provider} · judge={not args.no_judge}")
+    results: list[CaseResult] = []
+    for i, case in enumerate(cases, 1):
+        print(f"  [{i:2}/{len(cases)}] {case.id} {case.tier:9} {case.question[:54]}…", flush=True)
+        r = run_case(case, judge=not args.no_judge)
+        results.append(r)
+        tag = "ERR" if r.error else ("✓" if r.correct else ("·" if r.correct is None else "✗"))
+        print(f"        → {tag}  route={r.route_actual}  {r.latency_ms}ms", flush=True)
+        if r.error:
+            print(f"        ! {r.error}")
+
+    agg = aggregate(results)
+    print_report(provider, results, agg)
+
+    out = Path(args.out) if args.out else OUT_DIR / f"eval_results_{provider}.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"provider": provider, "aggregate": agg, "cases": [asdict(r) for r in results]}
+    out.write_text(json.dumps(payload, indent=2))
+    print(f"  wrote {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

backend/src/finrag/eval/metrics.py

@@ -0,0 +1,183 @@
+"""Scoring for the Day-4 eval — two layers.
+
+Deterministic (no LLM, cheap, objective):
+  - number matching: does the answer state the ground-truth figure? Robust to
+    formatting ($96.995 billion / $96,995 million / 96.995B / -2.8%).
+  - citation validity: are the [N] anchors in the answer real (1..n_chunks)?
+  - refusal detection: keyword backstop for the honesty tier.
+
+LLM-judge (Claude, always — even when the *system under test* is Gemini, so the
+grader is held constant across the A/B; self-preference bias is named in the
+writeup):
+  - faithfulness: is every claim grounded in the provided context/tool results?
+  - answer relevance: does the answer actually address the question?
+  - context precision: what fraction of retrieved chunks are relevant?
+  - refusal judgement: did the agent appropriately decline?
+
+The judge is deliberately pinned to claude.generate_text (not the provider
+dispatcher) so the eval never grades an answer with the same model that wrote it
+when that model is the variable under test.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from finrag.llm.claude import generate_text as _claude_generate
+
+# ── Deterministic: number extraction ─────────────────────────────────────
+_SCALE = {
+    "trillion": 1e12, "tn": 1e12,
+    "billion": 1e9, "bn": 1e9,
+    "million": 1e6, "mn": 1e6,
+    "thousand": 1e3,
+}
+# $-led or scale-worded magnitudes. Plain bare integers (e.g. "2023") are NOT
+# matched as currency — they must carry a $ or a scale word to count.
+_CURRENCY_RE = re.compile(
+    r"\$\s?(-?\d[\d,]*(?:\.\d+)?)\s*(trillion|billion|million|thousand|tn|bn|mn)?"
+    r"|(-?\d[\d,]*(?:\.\d+)?)\s+(trillion|billion|million|thousand)",
+    re.IGNORECASE,
+)
+_PERCENT_RE = re.compile(r"(-?\d+(?:\.\d+)?)\s*(?:%|percent)", re.IGNORECASE)
+_DECIMAL_RE = re.compile(r"-?\d+\.\d+")
+
+
+def extract_currency(text: str) -> list[float]:
+    """All monetary magnitudes in `text`, normalized to absolute dollars."""
+    out: list[float] = []
+    for m in _CURRENCY_RE.finditer(text):
+        num = m.group(1) or m.group(3)
+        scale = (m.group(2) or m.group(4) or "").lower()
+        if num is None:
+            continue
+        try:
+            val = float(num.replace(",", ""))
+        except ValueError:
+            continue
+        out.append(val * _SCALE.get(scale, 1.0))
+    return out
+
+
+def extract_percentages(text: str) -> list[float]:
+    return [float(m.group(1)) for m in _PERCENT_RE.finditer(text)]
+
+
+def extract_decimals(text: str) -> list[float]:
+    return [float(m.group(0)) for m in _DECIMAL_RE.finditer(text)]
+
+
+def number_hit(expected: float, kind: str, text: str, tol: float) -> bool:
+    """Does `text` state `expected`? `tol` is a relative tolerance for currency
+    and per-share; for percent it's the absolute pp floor, OR'd with a 5%
+    relative band so both '44%' and '44.13%' match a 44.13 ground truth."""
+    if kind == "currency":
+        band = abs(expected) * tol
+        return any(abs(c - expected) <= band for c in extract_currency(text))
+    if kind == "per_share":
+        band = max(abs(expected) * tol, 0.01)
+        cands = extract_decimals(text) + extract_currency(text)
+        return any(abs(c - expected) <= band for c in cands)
+    if kind == "percent":
+        band = max(tol, abs(expected) * 0.05)
+        return any(abs(abs(c) - abs(expected)) <= band for c in extract_percentages(text))
+    raise ValueError(f"unknown gt_kind {kind!r}")
+
+
+# ── Deterministic: citations ──────────────────────────────────────────────
+_CITE_RE = re.compile(r"\[(\d+)\]")
+
+
+def citations(text: str) -> list[int]:
+    return [int(m.group(1)) for m in _CITE_RE.finditer(text)]
+
+
+def citation_validity(text: str, n_chunks: int) -> tuple[bool, list[int]]:
+    """True if the answer cites at least one chunk and every [N] is in range.
+    Returns (valid, out_of_range_anchors)."""
+    cites = citations(text)
+    if not cites:
+        return False, []
+    bad = [c for c in cites if c < 1 or c > n_chunks]
+    return (not bad), bad
+
+
+# ── Deterministic: refusal backstop ───────────────────────────────────────
+_REFUSAL_MARKERS = (
+    "not in the corpus", "not in the provided", "isn't in the corpus",
+    "is not in the corpus", "not available in", "cannot answer", "can't answer",
+    "do not have", "don't have", "not included in", "no information",
+    "not contain", "outside the", "not part of the corpus", "unable to",
+    "not found in", "not covered",
+)
+
+
+def looks_like_refusal(text: str) -> bool:
+    low = text.lower()
+    return any(m in low for m in _REFUSAL_MARKERS)
+
+
+# ── LLM judge ─────────────────────────────────────────────────��───────────
+def _judge_json(system: str, user: str, *, max_tokens: int = 400) -> dict:
+    """Call the Claude judge and parse its JSON verdict. Tolerant of code-fence
+    wrapping; returns {} on parse failure so a flaky judge degrades to a missing
+    score rather than crashing the whole run."""
+    raw = _claude_generate(system, user, max_output_tokens=max_tokens, temperature=0.0)
+    m = re.search(r"\{.*\}", raw, re.DOTALL)
+    if not m:
+        return {}
+    try:
+        return json.loads(m.group(0))
+    except json.JSONDecodeError:
+        return {}
+
+
+_FAITH_SYS = (
+    "You are a meticulous evaluator of financial question-answering. You are given "
+    "CONTEXT (retrieved filing excerpts and tool results) and an ANSWER. Judge "
+    "ONLY whether each factual claim in the ANSWER is supported by the CONTEXT — "
+    "not whether it is true in general. Ignore citation markers like [1]. "
+    'Reply with ONLY JSON: {"faithfulness": <float 0..1>, '
+    '"unsupported_claims": [<short strings>], "reason": "<one sentence>"}. '
+    "faithfulness is the fraction of claims supported by the context."
+)
+
+_RELEVANCE_SYS = (
+    "You evaluate whether an ANSWER addresses the QUESTION asked (relevance, not "
+    "correctness). A direct, on-topic answer scores 1.0; a partial or evasive one "
+    "lower; an off-topic one near 0. A correct refusal for an unanswerable "
+    "question is fully relevant (1.0). "
+    'Reply with ONLY JSON: {"relevance": <float 0..1>, "reason": "<one sentence>"}.'
+)
+
+_PRECISION_SYS = (
+    "You judge retrieval quality. Given a QUESTION and a numbered list of "
+    "retrieved CHUNKS (by index), decide which chunks are relevant to answering "
+    "the question. "
+    'Reply with ONLY JSON: {"relevant_indices": [<int>], "reason": "<one sentence>"}.'
+)
+
+_REFUSAL_SYS = (
+    "A QA system should DECLINE this question because the answer is NOT in its "
+    "corpus (the company, year, or forward-looking figure is unavailable). Given "
+    "the ANSWER, decide whether it appropriately declined / stated it cannot "
+    "answer from the available filings, rather than fabricating a figure. "
+    'Reply with ONLY JSON: {"declined": <true|false>, "reason": "<one sentence>"}.'
+)
+
+
+def judge_faithfulness(context: str, answer: str) -> dict:
+    return _judge_json(_FAITH_SYS, f"CONTEXT:\n{context}\n\nANSWER:\n{answer}")
+
+
+def judge_relevance(question: str, answer: str) -> dict:
+    return _judge_json(_RELEVANCE_SYS, f"QUESTION:\n{question}\n\nANSWER:\n{answer}")
+
+
+def judge_precision(question: str, chunks_listing: str) -> dict:
+    return _judge_json(_PRECISION_SYS, f"QUESTION:\n{question}\n\nCHUNKS:\n{chunks_listing}")
+
+
+def judge_refusal(question: str, answer: str) -> dict:
+    return _judge_json(_REFUSAL_SYS, f"QUESTION:\n{question}\n\nANSWER:\n{answer}")

backend/src/finrag/eval/smoke.py

@@ -0,0 +1,232 @@
+"""End-to-end smoke test for retrieval.
+
+Runs a fixed canary set of questions through `retrieval.vector.search` and
+flags structural breakage (zero results, filter violations, suspiciously
+low scores). Does NOT grade answer quality — that's Day 4's eval harness.
+
+Usage:
+    uv run python -m finrag.eval.smoke
+
+Exits with code 0 on full pass, 1 if any case fails. Useful in CI later.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from finrag.retrieval.rerank import rerank_search
+from finrag.retrieval.vector import RetrievedChunk
+
+# parse.py-style root resolution
+REPO_ROOT = Path(__file__).resolve().parents[4]
+RESULTS_PATH = REPO_ROOT / "data" / "smoke_results.json"
+
+# Smoke now hits rerank_search — same path as /query. Score is Cohere
+# Rerank v3's relevance_score in [0, 1]. A relevant top-1 is typically
+# > 0.5 for well-formed queries. < 0.1 means the reranker thinks none of
+# the candidates actually answer the query — usually a sign of retrieval
+# upstream returning irrelevant candidates.
+SCORE_FLOOR = 0.10
+
+
+# ── Canary cases ─────────────────────────────────────────────────────────
+class Case(BaseModel):
+    name: str
+    question: str
+    top_k: int = 5
+    ticker: str | None = None
+    fiscal_year: int | None = None
+    chunk_type: str | None = None
+    # Optional soft expectation — we don't fail the case if this doesn't
+    # match, but we surface it in output so you eyeball whether the right
+    # company is showing up in the top results.
+    expect_ticker_in_top: str | None = None
+
+
+CASES: list[Case] = [
+    Case(
+        name="01_aapl_services_revenue",
+        question="How did Apple's services revenue change in 2023?",
+        expect_ticker_in_top="AAPL",
+    ),
+    Case(
+        name="02_tsla_rnd_spend",
+        question="How much did Tesla spend on research and development?",
+        expect_ticker_in_top="TSLA",
+    ),
+    Case(
+        name="03_supply_chain_risks",
+        question="What are the risks related to supply chain disruptions?",
+    ),
+    Case(
+        name="04_jpm_net_interest_income",
+        question="What was JPMorgan's net interest income?",
+        expect_ticker_in_top="JPM",
+    ),
+    Case(
+        name="05_aapl_2024_filter",
+        question="total revenue",
+        ticker="AAPL",
+        fiscal_year=2024,
+        expect_ticker_in_top="AAPL",
+    ),
+    Case(
+        name="06_tables_only_filter",
+        question="income statement",
+        chunk_type="table",
+    ),
+    Case(
+        name="07_tsla_deliveries_multi_year",
+        question="How have Tesla vehicle deliveries changed year over year?",
+        expect_ticker_in_top="TSLA",
+        top_k=8,
+    ),
+    Case(
+        name="08_cross_company_ai",
+        question="risks related to artificial intelligence",
+        top_k=8,
+    ),
+]
+
+
+# ── Execution ─────────────────────────────────────────────────────────────
+class CaseResult(BaseModel):
+    name: str
+    passed: bool
+    reasons: list[str]
+    n_chunks: int
+    top_score: float | None
+    top_ticker: str | None
+    top_fiscal_year: int | None
+    duration_ms: int
+
+
+def _check_case(case: Case, chunks: list[RetrievedChunk]) -> CaseResult:
+    """Apply pass/fail rules to a case's results."""
+    reasons: list[str] = []
+
+    if not chunks:
+        reasons.append("returned zero chunks")
+        return CaseResult(
+            name=case.name,
+            passed=False,
+            reasons=reasons,
+            n_chunks=0,
+            top_score=None,
+            top_ticker=None,
+            top_fiscal_year=None,
+            duration_ms=0,  # filled in by caller
+        )
+
+    top = chunks[0]
+
+    # Score floor — catches embedder mismatches (e.g. wrong input_type).
+    if top.score < SCORE_FLOOR:
+        reasons.append(f"top score {top.score:.3f} below floor {SCORE_FLOOR}")
+
+    # Filter compliance — every returned chunk must satisfy any filter we set.
+    if case.ticker:
+        bad = [c for c in chunks if c.ticker != case.ticker]
+        if bad:
+            reasons.append(
+                f"ticker filter violated: {len(bad)}/{len(chunks)} chunks have "
+                f"ticker != {case.ticker}"
+            )
+    if case.fiscal_year:
+        bad = [c for c in chunks if c.fiscal_year != case.fiscal_year]
+        if bad:
+            reasons.append(
+                f"fiscal_year filter violated: {len(bad)}/{len(chunks)} chunks have "
+                f"fiscal_year != {case.fiscal_year}"
+            )
+    if case.chunk_type:
+        bad = [c for c in chunks if c.chunk_type != case.chunk_type]
+        if bad:
+            reasons.append(
+                f"chunk_type filter violated: {len(bad)}/{len(chunks)} chunks have "
+                f"chunk_type != {case.chunk_type}"
+            )
+
+    # Soft expectation — log only, don't fail
+    if case.expect_ticker_in_top:
+        top_tickers = {c.ticker for c in chunks[:3]}
+        if case.expect_ticker_in_top not in top_tickers:
+            reasons.append(
+                f"⚠ soft: expected {case.expect_ticker_in_top} in top-3 tickers, "
+                f"got {sorted(top_tickers)}"
+            )
+
+    # Only hard failures (filter violations, empty results, score floor)
+    # count toward `passed`. Soft warnings start with "⚠".
+    hard_failures = [r for r in reasons if not r.startswith("⚠")]
+
+    return CaseResult(
+        name=case.name,
+        passed=not hard_failures,
+        reasons=reasons,
+        n_chunks=len(chunks),
+        top_score=top.score,
+        top_ticker=top.ticker,
+        top_fiscal_year=top.fiscal_year,
+        duration_ms=0,
+    )
+
+
+def run_case(case: Case) -> CaseResult:
+    t0 = time.perf_counter()
+    chunks = rerank_search(
+        question=case.question,
+        top_k=case.top_k,
+        ticker=case.ticker,
+        fiscal_year=case.fiscal_year,
+        chunk_type=case.chunk_type,
+    )
+    elapsed_ms = int((time.perf_counter() - t0) * 1000)
+    result = _check_case(case, chunks)
+    result.duration_ms = elapsed_ms
+    return result
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────
+def main() -> int:
+    print(f"Running {len(CASES)} smoke cases against retrieval.search\n")
+
+    results: list[CaseResult] = []
+    for case in CASES:
+        r = run_case(case)
+        results.append(r)
+
+        status = "PASS" if r.passed else "FAIL"
+        top = f"{r.top_ticker} FY{r.top_fiscal_year} @ {r.top_score:.3f}" if r.top_score else "—"
+        print(f"  [{status}] {r.name:35s}  n={r.n_chunks}  top={top:24s}  {r.duration_ms}ms")
+        for reason in r.reasons:
+            print(f"          {reason}")
+
+    n_pass = sum(1 for r in results if r.passed)
+    n_total = len(results)
+    print(f"\n{n_pass}/{n_total} cases passed.")
+
+    # Persist results for future diffing / regression tracking
+    payload: dict[str, Any] = {
+        "summary": {
+            "passed": n_pass,
+            "total": n_total,
+            "all_passed": n_pass == n_total,
+        },
+        "cases": [r.model_dump() for r in results],
+    }
+    RESULTS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    RESULTS_PATH.write_text(json.dumps(payload, indent=2))
+    print(f"Wrote {RESULTS_PATH}")
+
+    return 0 if n_pass == n_total else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

backend/src/finrag/guardrails.py

@@ -0,0 +1,131 @@
+"""Cost/abuse guardrails for the public deploy.
+
+The agent endpoints call a funded Anthropic key, so a public URL without limits
+is an open invitation to burn money. Two independent defenses, both enforced as
+a FastAPI dependency on the paid endpoints (/answer, /agent, /agent/stream):
+
+  1. Per-IP sliding-window rate limit  → stops one client hammering the agent.
+  2. Global daily question cap          → the hard cost circuit-breaker; once the
+     day's paid questions hit the cap, every further request 429s until midnight
+     UTC, no matter who sends it. This is the line between "a few dollars" and
+     "a surprise bill."
+
+Both are in-process (a dict + a counter under one lock). That's correct for the
+single-instance Fly deploy we target; a multi-instance/multi-worker setup would
+need a shared store (Redis) instead — called out in docs/deploy.md, not hidden.
+
+Retrieval-only /query is intentionally NOT guarded here: it makes no LLM call
+(Cohere rerank only, ~$0.002) so it isn't the cost risk the cap exists for.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import defaultdict, deque
+from datetime import datetime, timezone
+
+from fastapi import HTTPException, Request
+
+from finrag.config import settings
+
+_WINDOW_SECONDS = 60.0
+
+_lock = threading.Lock()
+# ip -> timestamps of accepted paid requests within the last _WINDOW_SECONDS
+_hits: dict[str, deque[float]] = defaultdict(deque)
+# (utc_date_str, count) — the global daily paid-question tally
+_day: str = ""
+_day_count: int = 0
+
+
+def _client_ip(request: Request) -> str:
+    """Best-effort real client IP. Behind Fly's proxy the socket peer is the
+    proxy, so prefer the forwarded headers Fly/Vercel set; fall back to the
+    socket. X-Forwarded-For is a chain — the original client is the first hop."""
+    xff = request.headers.get("x-forwarded-for")
+    if xff:
+        return xff.split(",")[0].strip()
+    fly = request.headers.get("fly-client-ip")
+    if fly:
+        return fly.strip()
+    return request.client.host if request.client else "unknown"
+
+
+def _today_utc() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def _seconds_until_utc_midnight() -> int:
+    now = datetime.now(timezone.utc)
+    tomorrow = now.date().toordinal() + 1
+    midnight = datetime.fromordinal(tomorrow).replace(tzinfo=timezone.utc)
+    return max(1, int((midnight - now).total_seconds()))
+
+
+def enforce(request: Request) -> None:
+    """FastAPI dependency: raise 429 if this paid request breaches either the
+    per-IP rate limit or the global daily cap; otherwise record it and return.
+
+    Recording happens here (not after the call) so an in-flight burst can't slip
+    past the cap — we count on admission, which is the conservative choice for a
+    cost ceiling."""
+    global _day, _day_count
+    now = time.monotonic()
+    ip = _client_ip(request)
+
+    with _lock:
+        # ── global daily cap (reset on UTC date rollover) ──
+        today = _today_utc()
+        if today != _day:
+            _day, _day_count = today, 0
+        if _day_count >= settings.daily_question_cap:
+            raise HTTPException(
+                status_code=429,
+                detail=(
+                    "Daily demo limit reached. This is a cost-capped public "
+                    "demo; it resets at 00:00 UTC. Run it locally for unlimited "
+                    "use — see the repo README."
+                ),
+                headers={"Retry-After": str(_seconds_until_utc_midnight())},
+            )
+
+        # ── per-IP sliding window ──
+        bucket = _hits[ip]
+        cutoff = now - _WINDOW_SECONDS
+        while bucket and bucket[0] < cutoff:
+            bucket.popleft()
+        if len(bucket) >= settings.rate_limit_per_min:
+            retry = max(1, int(_WINDOW_SECONDS - (now - bucket[0])))
+            raise HTTPException(
+                status_code=429,
+                detail=(
+                    f"Rate limit: max {settings.rate_limit_per_min} questions/min. "
+                    f"Try again in ~{retry}s."
+                ),
+                headers={"Retry-After": str(retry)},
+            )
+
+        # Admitted — record against both limiters.
+        bucket.append(now)
+        _day_count += 1
+
+        # Opportunistic cleanup so idle IPs don't accumulate forever.
+        if len(_hits) > 4096:
+            for k in [k for k, v in _hits.items() if not v]:
+                del _hits[k]
+
+
+def cap_status() -> dict[str, int | str]:
+    """Snapshot for /health — lets the frontend show 'N questions left today'
+    and makes the cap observable without reading logs."""
+    with _lock:
+        today = _today_utc()
+        used = _day_count if today == _day else 0
+        cap = settings.daily_question_cap
+        return {
+            "daily_cap": cap,
+            "used_today": used,
+            "remaining_today": max(0, cap - used),
+            "resets_at": "00:00 UTC",
+        }

backend/src/finrag/ingestion/edgar.py

@@ -0,0 +1,229 @@
+import json
+import os
+import time
+from collections.abc import Iterator
+from datetime import date
+from pathlib import Path
+
+import httpx
+from pydantic import BaseModel
+
+# ── Paths ─────────────────────────────────────────────────────────────────
+# ← why: same trick as config.py — resolve to repo root so the script works
+#   regardless of CWD. edgar.py → ingestion/ → finrag/ → src/ → backend/ → ROOT
+REPO_ROOT = Path(__file__).resolve().parents[4]
+DATA_DIR = REPO_ROOT / "data" / "raw"
+
+# ── HTTP client ───────────────────────────────────────────────────────────
+# ← why: SEC requires a real contactable email. Fall back to yours so the
+#   script never accidentally runs with a placeholder; override via env in CI.
+USER_AGENT = os.getenv("SEC_USER_AGENT", "Aryan Sharma aryan250403@gmail.com")
+HTTP_HEADERS = {
+    "User-Agent": USER_AGENT,
+    "Accept-Encoding": "gzip, deflate",
+}
+client = httpx.Client(headers=HTTP_HEADERS, timeout=30.0)
+
+# ── Corpus config ─────────────────────────────────────────────────────────
+TARGET_TICKERS = ["AAPL", "TSLA", "JPM"]
+TARGET_YEARS = [2022, 2023, 2024]
+REQUEST_SLEEP_SECONDS = 0.2  # ← why: SEC allows 10 req/s; 5 req/s is polite.
+
+
+# ── Models ────────────────────────────────────────────────────────────────
+class Filing(BaseModel):
+    # ← why: every field here exists because some downstream stage needs it.
+    #   ticker/cik/accession give three independent identifiers.
+    #   filing_date vs period_of_report are *different things* and both matter.
+    #   sec_url is for citation rendering in the UI later.
+    ticker: str
+    company_name: str
+    cik: str
+    form: str
+    filing_date: date
+    period_of_report: date
+    fiscal_year: int
+    accession_number: str
+    accession_clean: str
+    primary_document: str
+    sec_url: str
+    out_dir: str  # relative to DATA_DIR
+
+    def metadata_dict(self) -> dict:
+        # ← why: pydantic's model_dump() emits dates as date objects; JSON
+        #   can't serialize those, so coerce to ISO strings explicitly.
+        d = self.model_dump()
+        d["filing_date"] = self.filing_date.isoformat()
+        d["period_of_report"] = self.period_of_report.isoformat()
+        return d
+
+
+# ── EDGAR API calls ───────────────────────────────────────────────────────
+def resolve_cik_map() -> dict[str, tuple[str, str]]:
+    """Return {ticker: (cik_str, company_name)} for the whole market.
+
+    ← why: SEC publishes the entire ticker→CIK map as one JSON file. Fetching
+       it once and resolving locally is cheaper than per-ticker lookups.
+    """
+    url = "https://www.sec.gov/files/company_tickers.json"
+    response = client.get(url)
+    response.raise_for_status()
+    data = response.json()
+    return {
+        entry["ticker"].upper(): (str(entry["cik_str"]), entry["title"])
+        for entry in data.values()
+    }
+
+
+def _iter_submission_pages(padded_cik: str) -> Iterator[dict]:
+    """Yield each 'recent'-shaped page from the submissions endpoint.
+
+    First yields filings.recent, then walks filings.files for older pages.
+    High-volume filers (banks, frequent 8-K issuers) overflow `recent` and
+    require pulling the paginated files to find 10-Ks more than ~1-2 yrs old.
+    """
+    url = f"https://data.sec.gov/submissions/CIK{padded_cik}.json"
+    response = client.get(url)
+    response.raise_for_status()
+    data = response.json()
+
+    yield data["filings"]["recent"]
+
+    for file_entry in data["filings"].get("files", []):
+        time.sleep(REQUEST_SLEEP_SECONDS)
+        file_url = f"https://data.sec.gov/submissions/{file_entry['name']}"
+        resp = client.get(file_url)
+        resp.raise_for_status()
+        yield resp.json()
+
+
+def list_10k_filings(
+    ticker: str, cik: str, company_name: str, target_years: list[int]
+) -> list[Filing]:
+    """Hit EDGAR's submissions endpoint and pull 10-Ks for the target years.
+
+    Walks paginated submission pages until every target year is found or
+    pages are exhausted.
+    """
+    padded_cik = cik.zfill(10)
+    remaining_years = set(target_years)
+    filings: list[Filing] = []
+
+    for page in _iter_submission_pages(padded_cik):
+        if not remaining_years:
+            break
+        for acc_num, form, filing_date_str, period_str, prim_doc in zip(
+            page["accessionNumber"],
+            page["form"],
+            page["filingDate"],
+            page["reportDate"],
+            page["primaryDocument"],
+        ):
+            if form != "10-K":
+                continue
+            if not period_str:
+                continue
+            period_of_report = date.fromisoformat(period_str)
+            fiscal_year = period_of_report.year
+            if fiscal_year not in remaining_years:
+                continue
+
+            accession_clean = acc_num.replace("-", "")
+            sec_url = (
+                f"https://www.sec.gov/Archives/edgar/data/{int(cik)}/"
+                f"{accession_clean}/{prim_doc}"
+            )
+            filings.append(
+                Filing(
+                    ticker=ticker,
+                    company_name=company_name,
+                    cik=cik,
+                    form=form,
+                    filing_date=date.fromisoformat(filing_date_str),
+                    period_of_report=period_of_report,
+                    fiscal_year=fiscal_year,
+                    accession_number=acc_num,
+                    accession_clean=accession_clean,
+                    primary_document=prim_doc,
+                    sec_url=sec_url,
+                    out_dir=f"{ticker}_{fiscal_year}",
+                )
+            )
+            remaining_years.discard(fiscal_year)
+    return filings
+
+
+def download_filing(filing: Filing, base_out_dir: Path) -> None:
+    """Download the primary 10-K HTML and write metadata.json alongside it."""
+    dir_path = base_out_dir / filing.out_dir
+    dir_path.mkdir(parents=True, exist_ok=True)
+
+    htm_path = dir_path / "filing.htm"
+    meta_path = dir_path / "metadata.json"
+
+    # ← why: idempotency. Existence of *both* artifacts means a clean prior run.
+    #   If only one exists, we redo to repair partial state.
+    if htm_path.exists() and meta_path.exists():
+        print(f"  ↳ skip   {filing.ticker} FY{filing.fiscal_year} (already on disk)")
+        return
+
+    print(f"  ↳ fetch  {filing.ticker} FY{filing.fiscal_year}  →  {filing.sec_url}")
+    response = client.get(filing.sec_url)
+    response.raise_for_status()
+    htm_path.write_bytes(response.content)
+    meta_path.write_text(json.dumps(filing.metadata_dict(), indent=2))
+
+
+def write_manifest(filings: list[Filing], base_out_dir: Path) -> None:
+    """Top-level index of everything we've downloaded.
+
+    ← why: lets later stages (parser, embedder) load the corpus by reading one
+       file instead of walking the tree.
+    """
+    manifest_path = base_out_dir / "manifest.json"
+    manifest = {
+        "filings": [
+            {
+                "ticker": f.ticker,
+                "fiscal_year": f.fiscal_year,
+                "period_of_report": f.period_of_report.isoformat(),
+                "path": f.out_dir,
+            }
+            for f in filings
+        ]
+    }
+    manifest_path.write_text(json.dumps(manifest, indent=2))
+
+
+# ── CLI entrypoint ────────────────────────────────────────────────────────
+def main() -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"Downloading to: {DATA_DIR}")
+    print(f"User-Agent: {USER_AGENT}\n")
+
+    ticker_map = resolve_cik_map()
+    all_filings: list[Filing] = []
+
+    for ticker in TARGET_TICKERS:
+        if ticker not in ticker_map:
+            raise ValueError(f"Ticker {ticker} not found in SEC ticker map")
+        cik, company_name = ticker_map[ticker]
+        print(f"[{ticker}] {company_name} (CIK {cik})")
+
+        filings = list_10k_filings(ticker, cik, company_name, TARGET_YEARS)
+        if len(filings) < len(TARGET_YEARS):
+            missing = set(TARGET_YEARS) - {f.fiscal_year for f in filings}
+            print(f"  ⚠ missing fiscal years: {sorted(missing)}")
+
+        for filing in filings:
+            download_filing(filing, DATA_DIR)
+            time.sleep(REQUEST_SLEEP_SECONDS)
+        all_filings.extend(filings)
+        print()
+
+    write_manifest(all_filings, DATA_DIR)
+    print(f"Done. {len(all_filings)} filings on disk.")
+
+
+if __name__ == "__main__":
+    main()

backend/src/finrag/ingestion/embed.py

@@ -0,0 +1,212 @@
+"""Embed parsed chunks with Cohere embed-v3 and upsert into Qdrant.
+
+Pipeline:
+    data/processed/*.jsonl  (Chunk objects)
+        ──▶  Cohere embed-v3 (input_type=search_document)
+        ──▶  Qdrant upsert into `finrag_chunks` collection
+
+Idempotent: re-running overwrites existing points by ID (deterministic hash).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+from typing import TypeVar
+
+import cohere
+from cohere.errors import TooManyRequestsError
+from qdrant_client import QdrantClient
+from qdrant_client.models import Distance, PointStruct, VectorParams
+
+from finrag.config import settings
+from finrag.ingestion.parse import PROCESSED_DIR, Chunk
+
+# ── Constants ─────────────────────────────────────────────────────────────
+# Cohere v3 is the asymmetric retrieval model. 1024-dim output, English.
+# Use `embed-multilingual-v3.0` if you want cross-language support; same dim.
+COHERE_MODEL = "embed-english-v3.0"
+EMBED_DIM = 1024
+COLLECTION_NAME = "finrag_chunks"
+
+# Cohere caps `texts=[...]` at 96 per request. Larger requests get 400'd.
+COHERE_BATCH_SIZE = 96
+# Qdrant upsert is fine with much larger batches; 256 keeps memory bounded
+# while amortizing the HTTP overhead.
+QDRANT_BATCH_SIZE = 256
+
+# Pacing for Cohere calls. Trial keys have two limits:
+#   - 100 calls/min  (call-based)
+#   - 100k tokens/min (token-based) ← this is the binding constraint at our chunk size
+# At ~300 tokens/chunk × 96 chunks/batch ≈ 29k tokens/batch. Steady-state, that
+# means we can do roughly 3 batches per rolling minute. 20s base sleep gives us
+# margin; bursts above that get caught by the retry handler below.
+COHERE_SLEEP_SECONDS = 20.0
+COHERE_RETRY_INITIAL_BACKOFF_SECONDS = 30.0
+COHERE_MAX_RETRIES = 5
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+T = TypeVar("T")
+
+
+def _batched(seq: Iterable[T], n: int) -> Iterator[list[T]]:
+    """Yield lists of size `n` from `seq`. Last batch may be shorter."""
+    buf: list[T] = []
+    for x in seq:
+        buf.append(x)
+        if len(buf) == n:
+            yield buf
+            buf = []
+    if buf:
+        yield buf
+
+
+def _read_all_chunks(processed_dir: Path) -> list[Chunk]:
+    chunks: list[Chunk] = []
+    for jsonl in sorted(processed_dir.glob("*.jsonl")):
+        for line in jsonl.read_text(encoding="utf-8").splitlines():
+            if line.strip():
+                chunks.append(Chunk.model_validate_json(line))
+    return chunks
+
+
+def _ensure_collection(qdrant: QdrantClient, name: str, dim: int) -> None:
+    """Create the collection if it doesn't exist. No-op otherwise.
+
+    Note: we *don't* recreate the collection on schema mismatch — that would
+    destroy data. If you change EMBED_DIM, delete the collection manually
+    via the dashboard or `qdrant.delete_collection(name)`.
+    """
+    existing = {c.name for c in qdrant.get_collections().collections}
+    if name in existing:
+        return
+    print(f"Creating Qdrant collection '{name}' (dim={dim}, distance=cosine)")
+    qdrant.create_collection(
+        collection_name=name,
+        vectors_config=VectorParams(size=dim, distance=Distance.COSINE),
+    )
+
+
+def _embed_batch(co: cohere.ClientV2, texts: list[str]) -> list[list[float]]:
+    """Embed a batch of texts with the document-side encoder.
+
+    The `input_type="search_document"` here is the asymmetric-retrieval flag.
+    The matching `search_query` lives in the /query endpoint (Decision 7).
+    Mixing the two destroys retrieval quality silently.
+    """
+    response = co.embed(
+        texts=texts,
+        model=COHERE_MODEL,
+        input_type="search_document",
+        embedding_types=["float"],
+    )
+    # V2 response shape: response.embeddings.float_ is list[list[float]]
+    return response.embeddings.float_
+
+
+def _embed_batch_with_retry(
+    co: cohere.ClientV2, texts: list[str]
+) -> list[list[float]]:
+    """Wrap _embed_batch with exponential backoff on 429 rate-limit errors.
+
+    Trial keys can hit either the call limit or the token limit; both surface
+    as TooManyRequestsError. We don't bother distinguishing — the right
+    response is the same: wait, then retry.
+    """
+    backoff = COHERE_RETRY_INITIAL_BACKOFF_SECONDS
+    for attempt in range(1, COHERE_MAX_RETRIES + 1):
+        try:
+            return _embed_batch(co, texts)
+        except TooManyRequestsError:
+            if attempt == COHERE_MAX_RETRIES:
+                raise
+            print(
+                f"  ⚠ rate-limited; sleeping {backoff:.0f}s "
+                f"(retry {attempt}/{COHERE_MAX_RETRIES - 1})"
+            )
+            time.sleep(backoff)
+            backoff *= 2
+    # Unreachable — loop either returns or raises.
+    raise RuntimeError("retry loop exited without resolving")
+
+
+def _chunk_to_point(chunk: Chunk, vector: list[float]) -> PointStruct:
+    """Convert a Chunk + its vector into a Qdrant point.
+
+    Point ID: convert our 16-hex chunk_id to uint64. Qdrant only accepts
+    UUID or unsigned int IDs, not arbitrary strings. The hex→int conversion
+    preserves determinism (same chunk → same ID across runs).
+    """
+    point_id = int(chunk.chunk_id, 16)
+    return PointStruct(
+        id=point_id,
+        vector=vector,
+        payload=chunk.model_dump(),
+    )
+
+
+# ── Core ──────────────────────────────────────────────────────────────────
+def embed_and_upsert(chunks: list[Chunk]) -> int:
+    """Embed all chunks and upsert into Qdrant. Returns count of points written."""
+    co = cohere.ClientV2(api_key=settings.cohere_api_key)
+    qdrant = QdrantClient(url=settings.qdrant_url, api_key=settings.qdrant_api_key)
+    _ensure_collection(qdrant, COLLECTION_NAME, EMBED_DIM)
+
+    qdrant_buf: list[PointStruct] = []
+    total_written = 0
+
+    for batch_idx, batch in enumerate(_batched(chunks, COHERE_BATCH_SIZE), start=1):
+        texts = [c.text for c in batch]
+        print(f"  ↳ embed  batch {batch_idx}  ({len(batch)} chunks)")
+        vectors = _embed_batch_with_retry(co, texts)
+
+        if len(vectors) != len(batch):
+            # Cohere should always return one vector per input; fail loud if not.
+            raise RuntimeError(
+                f"Cohere returned {len(vectors)} vectors for {len(batch)} inputs"
+            )
+
+        for chunk, vector in zip(batch, vectors):
+            qdrant_buf.append(_chunk_to_point(chunk, vector))
+
+        if len(qdrant_buf) >= QDRANT_BATCH_SIZE:
+            qdrant.upsert(collection_name=COLLECTION_NAME, points=qdrant_buf)
+            total_written += len(qdrant_buf)
+            print(f"  ↳ upsert {len(qdrant_buf):4d} points  (total {total_written})")
+            qdrant_buf = []
+
+        time.sleep(COHERE_SLEEP_SECONDS)
+
+    # Flush remaining points (final partial batch)
+    if qdrant_buf:
+        qdrant.upsert(collection_name=COLLECTION_NAME, points=qdrant_buf)
+        total_written += len(qdrant_buf)
+        print(f"  ↳ upsert {len(qdrant_buf):4d} points  (total {total_written}, tail)")
+
+    return total_written
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────
+def main() -> None:
+    chunks = _read_all_chunks(PROCESSED_DIR)
+    print(f"Loaded {len(chunks)} chunks from {PROCESSED_DIR}\n")
+    if not chunks:
+        print("No chunks found. Run `finrag.ingestion.parse` first.")
+        return
+
+    written = embed_and_upsert(chunks)
+
+    # Verify final state via Qdrant's own count
+    qdrant = QdrantClient(url=settings.qdrant_url, api_key=settings.qdrant_api_key)
+    info = qdrant.get_collection(COLLECTION_NAME)
+    print(
+        f"\nDone. {written} points written this run. "
+        f"Collection '{COLLECTION_NAME}' contains {info.points_count} total."
+    )
+
+
+if __name__ == "__main__":
+    main()

backend/src/finrag/ingestion/facts.py

@@ -0,0 +1,448 @@
+"""Fetch XBRL financial facts from SEC's Company Facts API and load into DuckDB.
+
+Why XBRL and not HTML table parsing:
+  SEC requires every filer to tag financial facts against the GAAP taxonomy.
+  The Company Facts API serves these as JSON — already structured, already
+  cross-filer-comparable. Parsing HTML tables ourselves would re-invent
+  this work and produce worse data.
+
+The result is a normalized `financial_facts` table that the agent (Day 3)
+will query via a `sql_query` tool — the structured side of the
+"structured + unstructured" fusion that's the project's headline
+differentiator.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import date
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import duckdb
+import httpx
+
+from finrag.ingestion.edgar import (
+    HTTP_HEADERS,
+    REQUEST_SLEEP_SECONDS,
+    TARGET_TICKERS,
+    TARGET_YEARS,
+)
+
+# ── Paths ─────────────────────────────────────────────────────────────────
+# facts.py → ingestion/ → finrag/ → src/ → backend/ → ROOT
+REPO_ROOT = Path(__file__).resolve().parents[4]
+DUCKDB_PATH = REPO_ROOT / "data" / "duckdb" / "finrag.duckdb"
+
+# ── HTTP ──────────────────────────────────────────────────────────────────
+# Same User-Agent contract as the EDGAR scraper — SEC enforces it on this
+# endpoint too. Reuse the headers module-level constant.
+client = httpx.Client(headers=HTTP_HEADERS, timeout=30.0)
+
+
+# ── Canonical line-item map ───────────────────────────────────────────────
+# Each entry maps our canonical key (what the agent will query on) to one
+# or more GAAP concept names. Multiple concepts per key absorb the
+# inconsistency in how filers tag the same financial idea.
+#
+# Curated list — these are the high-value items for finance Q&A. Adding
+# more is one line of code each; restraint is the design goal so the agent
+# sees a tight, well-documented schema rather than an XBRL data dump.
+CONCEPT_MAP: dict[str, list[str]] = {
+    # Income statement
+    "revenue": [
+        "Revenues",
+        "RevenueFromContractWithCustomerExcludingAssessedTax",
+        "SalesRevenueNet",
+    ],
+    "cost_of_revenue": [
+        "CostOfRevenue",
+        "CostOfGoodsAndServicesSold",
+        "CostOfGoodsSold",
+    ],
+    "gross_profit": ["GrossProfit"],
+    "rd_expense": ["ResearchAndDevelopmentExpense"],
+    "sga_expense": [
+        "SellingGeneralAndAdministrativeExpense",
+        "GeneralAndAdministrativeExpense",
+    ],
+    "operating_income": ["OperatingIncomeLoss"],
+    "net_income": ["NetIncomeLoss"],
+    # Balance sheet
+    "total_assets": ["Assets"],
+    "total_liabilities": ["Liabilities"],
+    "stockholders_equity": ["StockholdersEquity"],
+    "cash": ["CashAndCashEquivalentsAtCarryingValue", "Cash"],
+    "long_term_debt": ["LongTermDebt", "LongTermDebtNoncurrent"],
+    # Cash flow + capital
+    "capex": ["PaymentsToAcquirePropertyPlantAndEquipment"],
+    "operating_cash_flow": ["NetCashProvidedByUsedInOperatingActivities"],
+    # Per-share
+    "eps_basic": ["EarningsPerShareBasic"],
+    "eps_diluted": ["EarningsPerShareDiluted"],
+    # Banking-specific (for JPM)
+    "net_interest_income": ["InterestIncomeOperating", "InterestAndDividendIncomeOperating"],
+}
+
+# Reverse lookup: gaap concept → canonical key
+GAAP_TO_LINE_ITEM: dict[str, str] = {
+    concept: key for key, concepts in CONCEPT_MAP.items() for concept in concepts
+}
+
+
+# ── Schema ────────────────────────────────────────────────────────────────
+CREATE_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS financial_facts (
+    ticker            TEXT    NOT NULL,
+    company_name      TEXT    NOT NULL,
+    cik               TEXT    NOT NULL,
+    fiscal_year       INTEGER NOT NULL,
+    fiscal_period     TEXT    NOT NULL,
+    period_end_date   DATE    NOT NULL,
+    line_item         TEXT    NOT NULL,
+    gaap_concept      TEXT    NOT NULL,
+    value             DOUBLE  NOT NULL,
+    unit              TEXT    NOT NULL,
+    accession_number  TEXT,
+    form              TEXT,
+    filed_date        DATE,
+    PRIMARY KEY (ticker, fiscal_year, fiscal_period, line_item, gaap_concept)
+);
+"""
+
+
+# ── SEC ticker → (cik, company_name) ──────────────────────────────────────
+def _resolve_ticker_map() -> dict[str, tuple[str, str]]:
+    """Same lookup as edgar.py — duplicated here so this module stands alone."""
+    url = "https://www.sec.gov/files/company_tickers.json"
+    response = client.get(url)
+    response.raise_for_status()
+    data = response.json()
+    return {
+        entry["ticker"].upper(): (str(entry["cik_str"]), entry["title"])
+        for entry in data.values()
+    }
+
+
+# ── XBRL fetch ────────────────────────────────────────────────────────────
+def fetch_company_facts(cik: str) -> dict[str, Any]:
+    """Hit SEC's Company Facts API. One call returns everything XBRL-tagged
+    for that filer across their entire filing history."""
+    padded_cik = cik.zfill(10)
+    url = f"https://data.sec.gov/api/xbrl/companyfacts/CIK{padded_cik}.json"
+    response = client.get(url)
+    response.raise_for_status()
+    return response.json()
+
+
+# ── Extract → flat rows ──────────────────────────────────────────────────
+def extract_facts(
+    company_data: dict[str, Any],
+    ticker: str,
+    target_years: list[int],
+) -> list[dict[str, Any]]:
+    """Walk the XBRL JSON, keep annual (fp='FY') facts for concepts in
+    CONCEPT_MAP whose period falls in target_years, return flat row dicts.
+
+    Period identity is the XBRL `end` date — see the long comment below for why
+    the `fy`/`fp` fields are NOT a reliable period key (they describe the filing,
+    not the value, and conflate a filing's 3 comparative years).
+
+    Deduplication: SEC's XBRL feed contains every restatement and amendment, so
+    the same (period, concept, unit) appears across successive filings. We keep
+    the *most recently filed* value per logical fact (later restatements
+    supersede earlier ones), then collapse the unit dimension to match the
+    `financial_facts` PK (which has no unit column).
+    """
+    cik = str(company_data.get("cik", ""))
+    company_name = company_data.get("entityName", "")
+    facts_root = company_data.get("facts", {}).get("us-gaap", {})
+
+    # Period identity comes from the XBRL `end` date, NOT the `fy`/`fp` fields.
+    # `fy`/`fp` denote the fiscal year/period of the *filing* a datapoint was
+    # reported in; a single 10-K carries 3 comparative years that all share its
+    # `fy`. Keying on `fy` (as this code used to) collapsed those three periods
+    # into one PK and stored the wrong year's value — every annual figure ended
+    # up off by ~2 years. The `end` date is the true period.
+    #
+    # We keep only annual facts (fp == 'FY'): for all three target filers the
+    # fiscal year equals the calendar year of the period-end date (AAPL ends in
+    # late September, TSLA/JPM on Dec 31), so fiscal_year = period_end.year is
+    # exact. Quarterly facts are intentionally dropped — Apple's fiscal quarters
+    # straddle calendar years (Q1 FY2023 ends Dec 2022), so end.year would not
+    # equal fiscal_year for them. The dict key keeps `unit` (e.g. EPS in
+    # 'USD/shares' vs 'USD'); the unit dimension is collapsed below.
+    best: dict[tuple[str, date, str, str, str], dict[str, Any]] = {}
+
+    for gaap_concept, fact_block in facts_root.items():
+        line_item = GAAP_TO_LINE_ITEM.get(gaap_concept)
+        if line_item is None:
+            continue
+
+        for unit, datapoints in fact_block.get("units", {}).items():
+            for dp in datapoints:
+                if dp.get("fp") != "FY":  # annual figures only
+                    continue
+
+                end_str = dp.get("end")
+                if not end_str:
+                    continue
+                period_end = date.fromisoformat(end_str)
+                fiscal_year = period_end.year
+                if fiscal_year not in target_years:
+                    continue
+
+                filed_str = dp.get("filed")
+                filed_date_val = date.fromisoformat(filed_str) if filed_str else None
+
+                # Dedup on the true period; keep the most-recently-filed value
+                # (a later filing's restatement supersedes the original).
+                key = (ticker, period_end, line_item, gaap_concept, unit)
+                existing = best.get(key)
+                if existing is not None:
+                    existing_filed = existing["filed_date"]
+                    if existing_filed and filed_date_val and filed_date_val <= existing_filed:
+                        continue
+                    if existing_filed and not filed_date_val:
+                        continue
+
+                best[key] = {
+                    "ticker": ticker,
+                    "company_name": company_name,
+                    "cik": cik,
+                    "fiscal_year": fiscal_year,
+                    "fiscal_period": "FY",
+                    "period_end_date": period_end,
+                    "line_item": line_item,
+                    "gaap_concept": gaap_concept,
+                    "value": float(dp["val"]),
+                    "unit": unit,
+                    "accession_number": dp.get("accn"),
+                    "form": dp.get("form"),
+                    "filed_date": filed_date_val,
+                }
+
+    # Now collapse the unit dimension. The PK in financial_facts is
+    # (ticker, fiscal_year, fiscal_period, line_item, gaap_concept) — no unit.
+    # Pick the most recently filed unit; ties broken by lexicographic unit name
+    # (stable). fiscal_period is always 'FY' here.
+    by_pk: dict[tuple[str, int, str, str, str], dict[str, Any]] = {}
+    for row in best.values():
+        pk = (row["ticker"], row["fiscal_year"], "FY", row["line_item"], row["gaap_concept"])
+        existing = by_pk.get(pk)
+        if existing is None:
+            by_pk[pk] = row
+            continue
+        ex_filed = existing["filed_date"]
+        new_filed = row["filed_date"]
+        if new_filed and (not ex_filed or new_filed > ex_filed):
+            by_pk[pk] = row
+        elif new_filed == ex_filed and row["unit"] < existing["unit"]:
+            by_pk[pk] = row
+
+    return list(by_pk.values())
+
+
+# ── DuckDB write ──────────────────────────────────────────────────────────
+def _ensure_db() -> duckdb.DuckDBPyConnection:
+    DUCKDB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    con = duckdb.connect(str(DUCKDB_PATH))
+    con.execute(CREATE_TABLE_SQL)
+    return con
+
+
+def upsert_facts(con: duckdb.DuckDBPyConnection, rows: list[dict[str, Any]]) -> int:
+    """Idempotent insert: rows with matching primary key get replaced.
+
+    DuckDB doesn't have native INSERT ON CONFLICT REPLACE for all cases, so
+    we DELETE-then-INSERT inside a transaction. At our scale (~hundreds of
+    rows per company) this is fast and bulletproof.
+    """
+    if not rows:
+        return 0
+    con.begin()
+    try:
+        for r in rows:
+            con.execute(
+                """
+                DELETE FROM financial_facts
+                WHERE ticker = ?
+                  AND fiscal_year = ?
+                  AND fiscal_period = ?
+                  AND line_item = ?
+                  AND gaap_concept = ?
+                """,
+                [
+                    r["ticker"],
+                    r["fiscal_year"],
+                    r["fiscal_period"],
+                    r["line_item"],
+                    r["gaap_concept"],
+                ],
+            )
+        con.executemany(
+            """
+            INSERT INTO financial_facts (
+                ticker, company_name, cik, fiscal_year, fiscal_period,
+                period_end_date, line_item, gaap_concept, value, unit,
+                accession_number, form, filed_date
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            [
+                (
+                    r["ticker"],
+                    r["company_name"],
+                    r["cik"],
+                    r["fiscal_year"],
+                    r["fiscal_period"],
+                    r["period_end_date"],
+                    r["line_item"],
+                    r["gaap_concept"],
+                    r["value"],
+                    r["unit"],
+                    r["accession_number"],
+                    r["form"],
+                    r["filed_date"],
+                )
+                for r in rows
+            ],
+        )
+        con.commit()
+    except Exception:
+        con.rollback()
+        raise
+    return len(rows)
+
+
+# ── Query interface (for sanity + future agent tool) ─────────────────────
+def query(sql: str, params: list[Any] | None = None) -> list[dict[str, Any]]:
+    """Read-only DuckDB query helper. Returns rows as list of dicts.
+
+    Day 3's agent tool will be a thin wrapper around this with safety
+    guards (READ ONLY connection, LIMIT enforcement, query timeout).
+    """
+    con = duckdb.connect(str(DUCKDB_PATH), read_only=True)
+    try:
+        result = con.execute(sql, params or []).fetchall()
+        cols = [d[0] for d in con.description]
+        return [dict(zip(cols, row)) for row in result]
+    finally:
+        con.close()
+
+
+# ── Corpus introspection (for grounding the agent) ────────────────────────
+# The agent must never invent companies. These read the *actual* loaded data so
+# the known-universe it's told about can't drift from what's queryable. Cached —
+# the corpus is static within a process.
+@lru_cache(maxsize=1)
+def corpus_companies() -> list[tuple[str, str]]:
+    """Distinct (ticker, company_name) present in financial_facts, ticker-sorted."""
+    rows = query(
+        "SELECT DISTINCT ticker, company_name FROM financial_facts ORDER BY ticker"
+    )
+    return [(r["ticker"], r["company_name"]) for r in rows]
+
+
+@lru_cache(maxsize=1)
+def corpus_years() -> tuple[int | None, int | None]:
+    """(min, max) fiscal_year in the corpus, or (None, None) if empty."""
+    rows = query("SELECT MIN(fiscal_year) AS lo, MAX(fiscal_year) AS hi FROM financial_facts")
+    if rows and rows[0]["lo"] is not None:
+        return int(rows[0]["lo"]), int(rows[0]["hi"])
+    return None, None
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────
+def main() -> None:
+    print(f"DuckDB at: {DUCKDB_PATH}")
+    con = _ensure_db()
+
+    import time
+
+    ticker_map = _resolve_ticker_map()
+    total_rows = 0
+
+    for ticker in TARGET_TICKERS:
+        cik, _ = ticker_map[ticker]
+        print(f"\n[{ticker}] fetching XBRL company facts (CIK {cik})…")
+        try:
+            data = fetch_company_facts(cik)
+        except httpx.HTTPStatusError as e:
+            print(f"  ✗ {e}")
+            continue
+
+        rows = extract_facts(data, ticker, TARGET_YEARS)
+        written = upsert_facts(con, rows)
+        total_rows += written
+        print(f"  ↳ {written} fact rows written")
+        time.sleep(REQUEST_SLEEP_SECONDS)
+
+    con.close()
+    print(f"\nDone. {total_rows} total fact rows.\n")
+
+    # Sanity-check queries — actual demonstrations of the modal-split value.
+    print("=" * 60)
+    print("Sample queries")
+    print("=" * 60)
+
+    examples = [
+        (
+            "Apple's revenue, FY 2022–2024",
+            """
+            SELECT fiscal_year, fiscal_period, value/1e9 AS billions_usd, gaap_concept
+            FROM financial_facts
+            WHERE ticker = 'AAPL'
+              AND line_item = 'revenue'
+              AND fiscal_period = 'FY'
+              AND unit = 'USD'
+            ORDER BY fiscal_year;
+            """,
+        ),
+        (
+            "Tesla R&D spend, FY 2022–2024",
+            """
+            SELECT fiscal_year, value/1e9 AS billions_usd
+            FROM financial_facts
+            WHERE ticker = 'TSLA'
+              AND line_item = 'rd_expense'
+              AND fiscal_period = 'FY'
+            ORDER BY fiscal_year;
+            """,
+        ),
+        (
+            "Operating margin by company, FY 2023",
+            """
+            WITH p AS (
+              SELECT ticker, line_item, SUM(value) AS v
+              FROM financial_facts
+              WHERE fiscal_year = 2023 AND fiscal_period = 'FY'
+                AND line_item IN ('revenue', 'operating_income')
+                AND unit = 'USD'
+              GROUP BY ticker, line_item
+            )
+            SELECT
+              ticker,
+              MAX(CASE WHEN line_item='revenue' THEN v END)/1e9 AS revenue_b,
+              MAX(CASE WHEN line_item='operating_income' THEN v END)/1e9 AS op_inc_b,
+              MAX(CASE WHEN line_item='operating_income' THEN v END) * 1.0
+                / NULLIF(MAX(CASE WHEN line_item='revenue' THEN v END), 0) AS op_margin
+            FROM p
+            GROUP BY ticker
+            ORDER BY op_margin DESC NULLS LAST;
+            """,
+        ),
+    ]
+
+    for title, sql in examples:
+        print(f"\n  ▸ {title}")
+        rows = query(sql)
+        if not rows:
+            print("    (no rows)")
+            continue
+        for r in rows:
+            print("    ", {k: (round(v, 3) if isinstance(v, float) else v) for k, v in r.items()})
+
+
+if __name__ == "__main__":
+    main()

backend/src/finrag/ingestion/parse.py

@@ -0,0 +1,292 @@
+"""Parse downloaded 10-K HTML files into chunks ready for embedding.
+
+Pipeline:
+    data/raw/{TICKER}_{FY}/filing.htm + metadata.json
+        ──▶  partition_html  ──▶  list[Element]
+        ──▶  segment by Title, split tables off
+        ──▶  chunk_by_title within each section (narrative)
+        ──▶  emit table elements as their own chunks
+    data/processed/{TICKER}_{FY}.jsonl    (one Chunk per line)
+    data/processed/manifest.json
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+# NOTE: `unstructured` is imported lazily inside parse_filing() (see below), not
+# at module top. It's a heavy, ingestion-only dependency (torch/transformers via
+# unstructured[pdf]) kept OUT of the runtime image — but this module is imported
+# transitively at runtime for its constants (PROCESSED_DIR, Chunk), so a top-level
+# import would crash the server. Install it for ingestion with `uv sync --group ingestion`.
+
+# ── Paths ─────────────────────────────────────────────────────────────────
+# parse.py → ingestion/ → finrag/ → src/ → backend/ → ROOT
+REPO_ROOT = Path(__file__).resolve().parents[4]
+RAW_DIR = REPO_ROOT / "data" / "raw"
+PROCESSED_DIR = REPO_ROOT / "data" / "processed"
+
+# ── Chunking knobs (see Decision 5 discussion for reasoning) ──────────────
+# max:   hard ceiling. Stays comfortably under Cohere embed-v3's ~512 token limit.
+# new_after: soft target — lets natural breaks happen before reaching max.
+# combine_under: absorbs tiny stub chunks (lone section titles, footers).
+# overlap: only kicks in when a section is split mid-section due to length.
+MAX_CHARACTERS = 1500
+NEW_AFTER_N_CHARS = 1200
+COMBINE_TEXT_UNDER_N_CHARS = 200
+OVERLAP = 150
+
+
+# ── Models ────────────────────────────────────────────────────────────────
+class Chunk(BaseModel):
+    """One retrievable unit: either a narrative passage or a single table.
+
+    Every field after `chunk_type` is provenance — copied from the filing's
+    metadata.json so the chunk is self-contained when it lands in Qdrant.
+    The retriever can filter on any of these fields without joining back.
+    """
+
+    chunk_id: str          # deterministic SHA-256 hash, 16 hex chars
+    text: str              # the actual content to embed
+    chunk_type: str        # "narrative" | "table"
+    section_title: str | None
+    section_path: list[str]
+    # Filing provenance
+    ticker: str
+    company_name: str
+    fiscal_year: int
+    period_of_report: str  # ISO date string
+    accession_number: str
+    sec_url: str
+    # Position within document — currently a monotonic ordinal per filing.
+    # On Day 2+ this becomes the anchor for citation-viewer highlighting.
+    element_index: int
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+def _hash_chunk(ticker: str, fiscal_year: int, position: int, text: str) -> str:
+    """Stable ID. Including `text` means changing chunking params produces
+    new IDs rather than silently overwriting old vectors with new content."""
+    h = hashlib.sha256()
+    h.update(f"{ticker}|{fiscal_year}|{position}|".encode())
+    h.update(text.encode())
+    return h.hexdigest()[:16]
+
+
+def _load_filing_metadata(filing_dir: Path) -> dict[str, Any]:
+    return json.loads((filing_dir / "metadata.json").read_text())
+
+
+def _element_category(el: Any) -> str:
+    # Unstructured elements expose `.category`; fall back to class name.
+    return getattr(el, "category", type(el).__name__)
+
+
+def _table_text(el: Any) -> str:
+    """Prefer the HTML representation — preserves rows/columns for the
+    embedder. Falls back to flattened text if HTML isn't available."""
+    md = getattr(el, "metadata", None)
+    if md is not None:
+        html = getattr(md, "text_as_html", None)
+        if html:
+            return html
+    return el.text
+
+
+# ── Core ──────────────────────────────────────────────────────────────────
+def parse_filing(filing_dir: Path) -> list[Chunk]:
+    """Read a filing directory, return chunks ready for embedding."""
+    # Lazy import: keeps `unstructured` out of the runtime import path (it's only
+    # needed here, during offline ingestion). Clear hint if the group is missing.
+    try:
+        from unstructured.chunking.title import chunk_by_title
+        from unstructured.partition.html import partition_html
+    except ModuleNotFoundError as e:  # pragma: no cover
+        raise ModuleNotFoundError(
+            "Ingestion requires the 'unstructured' extra. Install it with "
+            "`uv sync --group ingestion` (it's excluded from the runtime image)."
+        ) from e
+
+    meta = _load_filing_metadata(filing_dir)
+    htm_path = filing_dir / "filing.htm"
+
+    # Stage 1 — atomize the HTML into typed elements.
+    # `partition_html` is slow on first run (downloads NLTK data); fast after.
+    elements = partition_html(filename=str(htm_path))
+
+    # Stage 2a — walk elements once, building two parallel structures:
+    #   - sections: a list of section buckets, each holding narrative elements
+    #   - tables: pulled out into their own stream with section context attached
+    #
+    # Why bucket by section ourselves rather than relying on chunk_by_title's
+    # implicit handling? Because we need clean `section_title` attribution per
+    # chunk, and Unstructured's CompositeElement doesn't always expose the
+    # underlying Title element reliably across versions.
+    sections: list[dict[str, Any]] = []
+    tables: list[dict[str, Any]] = []
+    current_section: dict[str, Any] | None = None
+
+    for idx, el in enumerate(elements):
+        category = _element_category(el)
+
+        if category == "Title":
+            # Start a new section bucket. The Title element itself goes in
+            # so chunk_by_title sees it as the leading boundary.
+            current_section = {
+                "title": el.text,
+                "elements": [el],
+            }
+            sections.append(current_section)
+        elif category == "Table":
+            tables.append(
+                {
+                    "idx": idx,
+                    "element": el,
+                    "section_title": current_section["title"] if current_section else None,
+                }
+            )
+        else:
+            # Anything else: NarrativeText, ListItem, Header, etc.
+            if current_section is None:
+                # Content before the first Title (cover page, etc.)
+                current_section = {"title": None, "elements": []}
+                sections.append(current_section)
+            current_section["elements"].append(el)
+
+    chunks: list[Chunk] = []
+    position = 0  # monotonic counter, used as element_index for stable IDs
+
+    # Stage 2b — chunk narrative *within* each section.
+    # By calling chunk_by_title per section, chunks never cross section
+    # boundaries — a guarantee we couldn't make with a single document-wide call.
+    for section in sections:
+        if not section["elements"]:
+            continue
+
+        composite_chunks = chunk_by_title(
+            section["elements"],
+            max_characters=MAX_CHARACTERS,
+            new_after_n_chars=NEW_AFTER_N_CHARS,
+            combine_text_under_n_chars=COMBINE_TEXT_UNDER_N_CHARS,
+            overlap=OVERLAP,
+        )
+
+        for cc in composite_chunks:
+            text = cc.text.strip()
+            if not text:
+                continue  # skip empty composite results
+            chunks.append(
+                Chunk(
+                    chunk_id=_hash_chunk(
+                        meta["ticker"], meta["fiscal_year"], position, text
+                    ),
+                    text=text,
+                    chunk_type="narrative",
+                    section_title=section["title"],
+                    section_path=[section["title"]] if section["title"] else [],
+                    ticker=meta["ticker"],
+                    company_name=meta["company_name"],
+                    fiscal_year=meta["fiscal_year"],
+                    period_of_report=meta["period_of_report"],
+                    accession_number=meta["accession_number"],
+                    sec_url=meta["sec_url"],
+                    element_index=position,
+                )
+            )
+            position += 1
+
+    # Stage 2c — emit tables as their own chunks.
+    # The text is the table's HTML (when available), which keeps cell/column
+    # structure visible to the embedder. Tables that are very large will get
+    # truncated by Cohere's 512-token limit — accepted, because Day 2's
+    # DuckDB extractor will handle these structurally anyway.
+    for tbl in tables:
+        text = _table_text(tbl["element"]).strip()
+        if not text:
+            continue
+        chunks.append(
+            Chunk(
+                chunk_id=_hash_chunk(
+                    meta["ticker"], meta["fiscal_year"], position, text
+                ),
+                text=text,
+                chunk_type="table",
+                section_title=tbl["section_title"],
+                section_path=[tbl["section_title"]] if tbl["section_title"] else [],
+                ticker=meta["ticker"],
+                company_name=meta["company_name"],
+                fiscal_year=meta["fiscal_year"],
+                period_of_report=meta["period_of_report"],
+                accession_number=meta["accession_number"],
+                sec_url=meta["sec_url"],
+                element_index=position,
+            )
+        )
+        position += 1
+
+    return chunks
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────
+def _write_chunks(chunks: list[Chunk], out_file: Path) -> None:
+    with out_file.open("w", encoding="utf-8") as f:
+        for c in chunks:
+            f.write(c.model_dump_json() + "\n")
+
+
+def _read_chunks(out_file: Path) -> list[Chunk]:
+    return [
+        Chunk.model_validate_json(line)
+        for line in out_file.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+
+
+def main() -> None:
+    PROCESSED_DIR.mkdir(parents=True, exist_ok=True)
+    filing_dirs = sorted(
+        d for d in RAW_DIR.iterdir() if d.is_dir() and (d / "metadata.json").exists()
+    )
+    print(f"Found {len(filing_dirs)} filings to parse.\n")
+
+    manifest_entries: list[dict[str, Any]] = []
+
+    for filing_dir in filing_dirs:
+        meta = _load_filing_metadata(filing_dir)
+        ticker = meta["ticker"]
+        fy = meta["fiscal_year"]
+        out_file = PROCESSED_DIR / f"{ticker}_{fy}.jsonl"
+
+        if out_file.exists():
+            chunks = _read_chunks(out_file)
+            print(f"  ↳ skip   {ticker} FY{fy} ({len(chunks)} chunks on disk)")
+        else:
+            print(f"  ↳ parse  {ticker} FY{fy}…", end="", flush=True)
+            chunks = parse_filing(filing_dir)
+            _write_chunks(chunks, out_file)
+            print(f" → {len(chunks)} chunks")
+
+        manifest_entries.append(
+            {
+                "ticker": ticker,
+                "fiscal_year": fy,
+                "chunks_total": len(chunks),
+                "chunks_narrative": sum(1 for c in chunks if c.chunk_type == "narrative"),
+                "chunks_table": sum(1 for c in chunks if c.chunk_type == "table"),
+                "path": out_file.relative_to(REPO_ROOT).as_posix(),
+            }
+        )
+
+    manifest_path = PROCESSED_DIR / "manifest.json"
+    manifest_path.write_text(json.dumps({"filings": manifest_entries}, indent=2))
+    total = sum(e["chunks_total"] for e in manifest_entries)
+    print(f"\nDone. {total} chunks across {len(manifest_entries)} filings.")
+    print(f"Manifest: {manifest_path}")
+
+
+if __name__ == "__main__":
+    main()

backend/src/finrag/llm/__init__.py

@@ -0,0 +1,109 @@
+"""LLM layer — provider-agnostic entry point.
+
+`main.py`, the tools, and the LangGraph nodes import only these dispatchers and
+the neutral result types; they never name a provider. Which backend runs is
+decided by `settings.llm_provider` ("anthropic" default | "gemini" | "local").
+
+Provider modules are imported lazily inside each dispatcher so a deploy with
+only one provider's SDK/key still works.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from finrag.config import settings
+from finrag.llm.base import SynthesisResult, ToolCall, ToolLoopResult
+from finrag.retrieval.vector import RetrievedChunk
+
+__all__ = [
+    "synthesize",
+    "generate_text",
+    "run_tool_loop",
+    "run_tool_loop_stream",
+    "SynthesisResult",
+    "ToolLoopResult",
+    "ToolCall",
+]
+
+
+def _provider() -> str:
+    return (settings.llm_provider or "anthropic").lower()
+
+
+def synthesize(question: str, chunks: list[RetrievedChunk]) -> SynthesisResult:
+    if _provider() == "gemini":
+        from finrag.llm.gemini import synthesize_gemini
+
+        return synthesize_gemini(question, chunks)
+    if _provider() == "local":
+        from finrag.llm.local import synthesize_local
+
+        return synthesize_local(question, chunks)
+    from finrag.llm.claude import synthesize_claude
+
+    return synthesize_claude(question, chunks)
+
+
+def generate_text(system_instruction: str, user_text: str, **kwargs) -> str:
+    """Single-shot text completion (planning, NL→SQL)."""
+    if _provider() == "gemini":
+        from finrag.llm.gemini import generate_text as _gt
+
+        return _gt(system_instruction, user_text, **kwargs)
+    if _provider() == "local":
+        from finrag.llm.local import generate_text as _gt
+
+        return _gt(system_instruction, user_text, **kwargs)
+    from finrag.llm.claude import generate_text as _gt
+
+    return _gt(system_instruction, user_text, **kwargs)
+
+
+def run_tool_loop(system: str, user_text: str, **kwargs) -> ToolLoopResult:
+    """Agentic tool-calling loop — Gemini function-calling or Claude tool_use."""
+    if _provider() == "gemini":
+        from finrag.llm.gemini import tool_loop
+
+        return tool_loop(system, user_text, **kwargs)
+    if _provider() == "local":
+        from finrag.llm.local import tool_loop
+
+        return tool_loop(system, user_text, **kwargs)
+    from finrag.llm.claude import tool_loop
+
+    return tool_loop(system, user_text, **kwargs)
+
+
+def run_tool_loop_stream(
+    system: str,
+    user_text: str,
+    *,
+    on_text: Callable[[str], None] = lambda _t: None,
+    on_tool_call: Callable[[ToolCall], None] = lambda _c: None,
+    **kwargs,
+) -> ToolLoopResult:
+    """Streaming agentic loop: emits text deltas (`on_text`) and live tool calls
+    (`on_tool_call`) as they happen, returning the same ToolLoopResult.
+
+    Only Claude implements true streaming. Gemini and the local backend stay
+    non-streaming alternates, so we run their plain loop and replay the result
+    through the callbacks once — the seam stays intact, the live demo just isn't
+    granular."""
+    if _provider() in ("gemini", "local"):
+        if _provider() == "local":
+            from finrag.llm.local import tool_loop
+        else:
+            from finrag.llm.gemini import tool_loop
+
+        result = tool_loop(system, user_text, **kwargs)
+        for tc in result.tool_calls:
+            on_tool_call(tc)
+        if result.answer:
+            on_text(result.answer)
+        return result
+    from finrag.llm.claude import tool_loop_stream
+
+    return tool_loop_stream(
+        system, user_text, on_text=on_text, on_tool_call=on_tool_call, **kwargs
+    )

backend/src/finrag/llm/base.py

@@ -0,0 +1,143 @@
+"""Provider-agnostic pieces shared by every synthesis backend.
+
+Lives in its own module (not __init__) so provider modules can import the
+shared types without a circular import through the dispatcher.
+
+`SynthesisResult` is the contract `main.py` depends on. Every provider maps
+its native response/usage onto this shape, so the HTTP layer and the future
+LangGraph nodes never learn which model actually answered.
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+from dataclasses import dataclass, field
+from typing import Any
+
+from finrag.retrieval.vector import RetrievedChunk
+
+# The grounding contract. Every rule exists because LLMs violate it by default:
+#   - "Use ONLY the context" → without this, the model fills gaps from memory
+#   - "[N] citations" → without this, citations come back as prose mentions
+#   - "Don't round numbers" → without this, $394,328M becomes "about $400 billion"
+#   - "Fiscal vs calendar year" → without this, Apple FY2024 (ended Sep 2024)
+#     gets conflated with calendar 2024
+# Provider-neutral: passed as Anthropic `system=` or Gemini `system_instruction`.
+SYSTEM_PROMPT = """You are a financial analyst assistant answering questions about SEC 10-K filings.
+
+Rules you must follow:
+
+1. **Grounding**: Answer ONLY using the provided context chunks. If the context does not contain the answer, say so explicitly — do not fill gaps from prior knowledge.
+
+2. **Citations**: Every factual claim must be followed by a citation in the form [N] where N is the chunk index from the provided context. Multiple supporting chunks: [1][3]. Cite even when paraphrasing.
+
+3. **Numbers**: Quote exact figures from the source. Do not round unless explicitly asked. If a chunk says "$394,328 million", write "$394,328 million" — not "$394 billion".
+
+4. **Fiscal year**: Be careful with fiscal vs calendar year. Apple's fiscal year ends in late September; Tesla and JPMorgan use calendar years. If the user says "2023", confirm which sense from context.
+
+5. **Brevity**: Match the question's scope. A "what was X" question gets one number with a citation. A "how did X change" question gets a comparison sentence. Do not over-explain.
+
+6. **Honest absence**: If the context doesn't answer the question, write "The provided context does not contain this information." Do not speculate.
+"""
+
+MAX_TOKENS = 1024
+
+
+@dataclass
+class SynthesisResult:
+    """What synthesis returns, regardless of provider.
+
+    The cache token fields stay in the contract even for providers that
+    don't surface caching at this scale (both Anthropic <1024-token prompts
+    and Gemini's <~1024-token prefixes report 0) — keeping them lets the
+    frontend and eval harness read one stable shape.
+    """
+
+    answer: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cache_creation_input_tokens: int  # tokens billed at cache-write rate
+    cache_read_input_tokens: int      # tokens served from cache (~10% cost)
+    stop_reason: str
+
+
+def format_chunks_for_prompt(chunks: list[RetrievedChunk]) -> str:
+    """Format retrieved chunks with [N] anchors and provenance headers.
+
+    The [N] anchor at the start of each chunk is what the model references in
+    its citations. Position is 1-based to match human-reading convention.
+
+    The id= in the header is the real chunk_id — the only handle the model can
+    pass to lookup_citation. Without it the model has nothing real to deref and
+    fabricates ids like 'chunk_5' (which used to crash the hex→uint64 lookup).
+    """
+    blocks: list[str] = []
+    for i, c in enumerate(chunks, start=1):
+        section = c.section_title or "unknown section"
+        # Mark table chunks so the model treats them as structured data and
+        # doesn't hallucinate cell positions.
+        kind_marker = " [table]" if c.chunk_type == "table" else ""
+        header = f"[{i}] {c.ticker} · FY{c.fiscal_year} · {section}{kind_marker}  (id={c.chunk_id})"
+        blocks.append(f"{header}\n{c.text}")
+    return "\n\n---\n\n".join(blocks)
+
+
+@dataclass
+class ToolCall:
+    """One tool invocation inside the agent loop, captured for the trace."""
+
+    tool: str
+    args: dict[str, Any]
+    result: Any
+
+
+@dataclass
+class ToolLoopResult:
+    """Provider-neutral result of an agentic tool-calling loop.
+
+    Both the Gemini (native function-calling) and Anthropic (tool_use)
+    implementations return this shape, so the agent node never learns which
+    backend ran the loop — the same seam idea as SynthesisResult.
+    """
+
+    answer: str
+    input_tokens: int
+    output_tokens: int
+    tool_calls: list[ToolCall] = field(default_factory=list)
+
+
+def json_safe(v: Any) -> Any:
+    """Coerce a tool result into JSON-serializable form for tool responses.
+
+    DuckDB rows can carry date/Decimal values; both providers' tool-result
+    channels want JSON scalars, so we stringify dates and float-ify Decimals.
+    """
+    if isinstance(v, dict):
+        return {k: json_safe(x) for k, x in v.items()}
+    if isinstance(v, (list, tuple)):
+        return [json_safe(x) for x in v]
+    if isinstance(v, (datetime.date, datetime.datetime)):
+        return v.isoformat()
+    if isinstance(v, decimal.Decimal):
+        return float(v)
+    return v
+
+
+def build_user_message(question: str, chunks: list[RetrievedChunk]) -> str:
+    """The per-query content: question + formatted context. Never cached."""
+    return f"Question: {question}\n\nContext:\n\n{format_chunks_for_prompt(chunks)}"
+
+
+def empty_result(model: str) -> SynthesisResult:
+    """Returned when retrieval found nothing — skip the paid API call entirely."""
+    return SynthesisResult(
+        answer="No relevant context retrieved. Try rephrasing your question.",
+        model=model,
+        input_tokens=0,
+        output_tokens=0,
+        cache_creation_input_tokens=0,
+        cache_read_input_tokens=0,
+        stop_reason="empty_context",
+    )

backend/src/finrag/llm/claude.py

@@ -0,0 +1,300 @@
+"""Anthropic (Claude) backend — synthesis, text completion, and the agent
+tool-loop via native `tool_use`.
+
+This is the default provider (see config.llm_provider). Claude's tool-calling
+is more reliable than flash-lite's (no malformed-call flakiness), which is why
+the agent runs on it. Gemini stays fully wired as the alternate (see
+[[gemini]]) so the eval harness can A/B either backend on identical retrieval.
+
+Prompt caching earns its keep here: with tool schemas in the request the
+cached prefix (tools + system) clears Anthropic's 1024-token floor, so the
+repeated calls in a tool-loop hit cache — unlike the tiny /answer prompt.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from functools import lru_cache
+
+import anthropic
+
+from finrag.config import settings
+from finrag.llm.base import (
+    MAX_TOKENS,
+    SYSTEM_PROMPT,
+    SynthesisResult,
+    ToolCall,
+    ToolLoopResult,
+    build_user_message,
+    empty_result,
+    json_safe,
+)
+from finrag.retrieval.vector import RetrievedChunk
+
+# Default (eval baseline) is Sonnet; the public deploy sets CLAUDE_MODEL=
+# claude-haiku-4-5-20251001 via env. Read through a helper so every call site
+# (synthesis, generate_text, tool-loop, stream) picks up the configured model
+# live — same pattern as the provider seam.
+def _claude_model() -> str:
+    return settings.claude_model or "claude-sonnet-4-6"
+
+
+# Back-compat alias for any module that imported the constant. Note: this binds
+# once at import; the live value is _claude_model(). Internal call sites use the
+# helper so an env override (prod Haiku) always takes effect.
+CLAUDE_MODEL = settings.claude_model or "claude-sonnet-4-6"
+
+# Statuses worth retrying: rate limit, transient server errors, overloaded.
+_RETRYABLE_STATUS = {429, 500, 503, 529}
+
+
+@lru_cache(maxsize=1)
+def get_anthropic_client() -> anthropic.Anthropic:
+    if not settings.anthropic_api_key:
+        raise RuntimeError(
+            "ANTHROPIC_API_KEY is not set. Add it to .env, or set "
+            "LLM_PROVIDER=gemini to use Gemini instead."
+        )
+    return anthropic.Anthropic(api_key=settings.anthropic_api_key)
+
+
+def _messages_create_with_retry(*, retries: int = 5, **kwargs):
+    """Single choke-point for Claude calls, with backoff on rate-limit /
+    overloaded / transient 5xx, honoring Retry-After when present."""
+    last: Exception | None = None
+    for i in range(retries):
+        try:
+            return get_anthropic_client().messages.create(**kwargs)
+        except anthropic.APIStatusError as e:
+            status = getattr(e, "status_code", None)
+            if status in _RETRYABLE_STATUS and i < retries - 1:
+                last = e
+                delay = 2.0 * (i + 1)
+                try:
+                    ra = e.response.headers.get("retry-after")
+                    if ra:
+                        delay = min(float(ra) + 1.0, 35.0)
+                except Exception:
+                    pass
+                time.sleep(delay)
+                continue
+            raise
+    raise last  # type: ignore[misc]
+
+
+def _cached_system(text: str) -> list[dict]:
+    """System block marked for prompt caching (ephemeral, 5-min TTL)."""
+    return [{"type": "text", "text": text, "cache_control": {"type": "ephemeral"}}]
+
+
+def generate_text(
+    system_instruction: str,
+    user_text: str,
+    *,
+    max_output_tokens: int = 512,
+    temperature: float = 0.0,
+) -> str:
+    """Single-shot text completion (planning, NL→SQL). Mirrors the Gemini
+    backend's generate_text so the dispatcher can pick either."""
+    resp = _messages_create_with_retry(
+        model=_claude_model(),
+        max_tokens=max_output_tokens,
+        system=system_instruction,
+        messages=[{"role": "user", "content": user_text}],
+        temperature=temperature,
+    )
+    return "".join(b.text for b in resp.content if b.type == "text")
+
+
+def synthesize_claude(question: str, chunks: list[RetrievedChunk]) -> SynthesisResult:
+    if not chunks:
+        return empty_result(CLAUDE_MODEL)
+
+    response = _messages_create_with_retry(
+        model=_claude_model(),
+        max_tokens=MAX_TOKENS,
+        system=_cached_system(SYSTEM_PROMPT),
+        messages=[{"role": "user", "content": build_user_message(question, chunks)}],
+    )
+    answer_text = "".join(b.text for b in response.content if b.type == "text")
+    usage = response.usage
+    return SynthesisResult(
+        answer=answer_text,
+        model=_claude_model(),
+        input_tokens=usage.input_tokens,
+        output_tokens=usage.output_tokens,
+        cache_creation_input_tokens=getattr(usage, "cache_creation_input_tokens", 0) or 0,
+        cache_read_input_tokens=getattr(usage, "cache_read_input_tokens", 0) or 0,
+        stop_reason=response.stop_reason or "unknown",
+    )
+
+
+def _anthropic_tools() -> list[dict]:
+    """ToolSpec registry → Anthropic tool schema. The ToolSpec.parameters are
+    already JSON-schema, which is exactly Anthropic's `input_schema` shape."""
+    from finrag.tools import TOOL_SPECS  # lazy: avoid llm↔tools import cycle
+
+    return [
+        {"name": s.name, "description": s.description, "input_schema": s.parameters}
+        for s in TOOL_SPECS
+    ]
+
+
+def tool_loop(
+    system: str,
+    user_text: str,
+    *,
+    max_tokens: int = 1024,
+    max_iters: int = 5,
+) -> ToolLoopResult:
+    """Run Claude with tools until it stops requesting them (or max_iters).
+
+    The tools+system prefix is cache_control'd, so each loop turn re-reads the
+    big prefix from cache instead of re-billing it at full rate.
+    """
+    from finrag.tools import dispatch  # lazy: avoid llm↔tools import cycle
+
+    tools = _anthropic_tools()
+    messages: list[dict] = [{"role": "user", "content": user_text}]
+    in_tok = out_tok = 0
+    calls: list[ToolCall] = []
+    answer = ""
+
+    for _ in range(max_iters):
+        resp = _messages_create_with_retry(
+            model=_claude_model(),
+            max_tokens=max_tokens,
+            system=_cached_system(system),
+            tools=tools,
+            messages=messages,
+            temperature=0.0,
+        )
+        in_tok += resp.usage.input_tokens
+        out_tok += resp.usage.output_tokens
+
+        if resp.stop_reason == "tool_use":
+            messages.append({"role": "assistant", "content": resp.content})
+            tool_results: list[dict] = []
+            for block in resp.content:
+                if block.type == "tool_use":
+                    result = json_safe(dispatch(block.name, dict(block.input)))
+                    calls.append(ToolCall(block.name, dict(block.input), result))
+                    tool_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": block.id,
+                            "content": json.dumps(result),
+                        }
+                    )
+            messages.append({"role": "user", "content": tool_results})
+            continue
+
+        answer = "".join(b.text for b in resp.content if b.type == "text")
+        break
+
+    return ToolLoopResult(answer=answer, input_tokens=in_tok, output_tokens=out_tok, tool_calls=calls)
+
+
+def _stream_one_turn(*, tools, messages, system, max_tokens, on_text, retries: int = 5):
+    """Open one streaming Claude turn: forward text deltas to `on_text` as they
+    arrive, then return the fully-assembled Message (content blocks + usage).
+
+    Retries only on a retryable status raised *before* any text was emitted — a
+    mid-stream restart would re-send tokens the client already saw."""
+    last: Exception | None = None
+    for i in range(retries):
+        emitted = False
+        try:
+            with get_anthropic_client().messages.stream(
+                model=_claude_model(),
+                max_tokens=max_tokens,
+                system=system,
+                tools=tools,
+                messages=messages,
+                temperature=0.0,
+            ) as stream:
+                for text in stream.text_stream:
+                    emitted = True
+                    on_text(text)
+                return stream.get_final_message()
+        except anthropic.APIStatusError as e:
+            status = getattr(e, "status_code", None)
+            if status in _RETRYABLE_STATUS and i < retries - 1 and not emitted:
+                last = e
+                delay = 2.0 * (i + 1)
+                try:
+                    ra = e.response.headers.get("retry-after")
+                    if ra:
+                        delay = min(float(ra) + 1.0, 35.0)
+                except Exception:
+                    pass
+                time.sleep(delay)
+                continue
+            raise
+    raise last  # type: ignore[misc]
+
+
+def tool_loop_stream(
+    system: str,
+    user_text: str,
+    *,
+    max_tokens: int = 1024,
+    max_iters: int = 5,
+    on_text: Callable[[str], None] = lambda _t: None,
+    on_tool_call: Callable[[ToolCall], None] = lambda _c: None,
+) -> ToolLoopResult:
+    """Streaming twin of `tool_loop`: identical control flow, but each turn is
+    consumed via the streaming API so the final answer's text reaches `on_text`
+    delta-by-delta, and each dispatched tool hits `on_tool_call` the moment it
+    runs (not just at the end). Returns the same ToolLoopResult, so the caller's
+    trace/usage handling is unchanged whether it streamed or not.
+
+    Note: `on_text` fires for any text a turn emits. With this agent's prompt at
+    temperature 0 the tool_use turns carry no preamble, so in practice on_text
+    only sees the final answer; the authoritative answer is still the returned
+    ToolLoopResult.answer (the last turn's text), not the streamed concatenation."""
+    from finrag.tools import dispatch  # lazy: avoid llm↔tools import cycle
+
+    tools = _anthropic_tools()
+    cached_system = _cached_system(system)
+    messages: list[dict] = [{"role": "user", "content": user_text}]
+    in_tok = out_tok = 0
+    calls: list[ToolCall] = []
+    answer = ""
+
+    for _ in range(max_iters):
+        final = _stream_one_turn(
+            tools=tools,
+            messages=messages,
+            system=cached_system,
+            max_tokens=max_tokens,
+            on_text=on_text,
+        )
+        in_tok += final.usage.input_tokens
+        out_tok += final.usage.output_tokens
+
+        if final.stop_reason == "tool_use":
+            messages.append({"role": "assistant", "content": final.content})
+            tool_results: list[dict] = []
+            for block in final.content:
+                if block.type == "tool_use":
+                    result = json_safe(dispatch(block.name, dict(block.input)))
+                    tc = ToolCall(block.name, dict(block.input), result)
+                    calls.append(tc)
+                    on_tool_call(tc)  # surface live, before the next turn runs
+                    tool_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": block.id,
+                            "content": json.dumps(result),
+                        }
+                    )
+            messages.append({"role": "user", "content": tool_results})
+            continue
+
+        answer = "".join(b.text for b in final.content if b.type == "text")
+        break
+
+    return ToolLoopResult(answer=answer, input_tokens=in_tok, output_tokens=out_tok, tool_calls=calls)

backend/src/finrag/llm/gemini.py

@@ -0,0 +1,326 @@
+"""Gemini synthesis backend — the default provider.
+
+Uses the unified `google-genai` SDK (NOT the legacy `google-generativeai`).
+Same job as claude.py: retrieve → synthesize a citation-grounded answer.
+Maps Gemini's `usage_metadata` onto the shared `SynthesisResult`.
+
+Why Gemini 2.5 Flash: the free tier zeroes out dev cost, and plain grounded
+synthesis (read chunks, cite [N], don't hallucinate) is an easy workload for
+it — this isn't reasoning-heavy. We disable "thinking" (budget=0) because
+synthesis needs determinism and speed, not a scratchpad; thinking would just
+burn output tokens and latency here.
+
+Caching note: Gemini's implicit context cache only kicks in above a ~1k-token
+prefix, and our system prompt is ~450 tokens, so cached_content_token_count
+stays 0. That's expected, not a bug — see [[base]] SynthesisResult docstring.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from functools import lru_cache
+
+from google import genai
+from google.genai import types
+
+from finrag.config import settings
+from finrag.llm.base import (
+    MAX_TOKENS,
+    SYSTEM_PROMPT,
+    SynthesisResult,
+    ToolCall,
+    ToolLoopResult,
+    build_user_message,
+    empty_result,
+    json_safe,
+)
+from finrag.retrieval.vector import RetrievedChunk
+
+# JSON-schema lowercase types → Gemini's uppercase Type enum values.
+_TYPE_MAP = {
+    "object": "OBJECT", "string": "STRING", "number": "NUMBER",
+    "integer": "INTEGER", "boolean": "BOOLEAN", "array": "ARRAY",
+}
+
+# flash-lite is the default: the agent makes ~5 calls/question and 2.5-flash's
+# free tier caps at only 20 requests/DAY, which an agentic workload exhausts in
+# ~4 questions. flash-lite has a far larger free daily quota (~1000/day) and
+# 15 req/min — enough to actually run and demo the agent for free. Quality is
+# marginally lower but fine for grounded synthesis + mechanical sub-tasks.
+# (3.5-flash resolves but 503s constantly on free tier; 2.5-flash is selectable
+# by editing this line if billing is enabled.)
+GEMINI_MODEL = "gemini-2.5-flash-lite"
+
+
+@lru_cache(maxsize=1)
+def get_gemini_client() -> genai.Client:
+    if not settings.gemini_api_key:
+        raise RuntimeError(
+            "GEMINI_API_KEY is not set. Add it to .env, or set "
+            "LLM_PROVIDER=anthropic to use Claude instead."
+        )
+    return genai.Client(api_key=settings.gemini_api_key)
+
+
+def _retry_delay(exc: Exception, attempt: int) -> float | None:
+    """Seconds to wait before retrying `exc`, or None if it's not retryable.
+
+    Two transient free-tier failures:
+      - 503 UNAVAILABLE ("high demand") → linear backoff 2s/4s/6s.
+      - 429 RESOURCE_EXHAUSTED (5 req/min cap) → honor the API's suggested
+        retryDelay (it tells us exactly when the per-minute window resets),
+        with a small buffer and a sane ceiling.
+    """
+    s = str(exc)
+    if "429" in s or "RESOURCE_EXHAUSTED" in s:
+        # Per-DAY quota won't reset within any sane wait — fail fast so the
+        # caller gets a clear error instead of blocking ~60s for nothing.
+        # Only the per-minute cap is worth waiting out.
+        if "PerDay" in s or "RequestsPerDay" in s:
+            return None
+        m = re.search(r"retry in ([0-9.]+)s", s) or re.search(
+            r"retryDelay['\"]?:?\s*['\"]?([0-9.]+)s", s
+        )
+        return min((float(m.group(1)) if m else 20.0) + 1.0, 35.0)
+    if "503" in s or "UNAVAILABLE" in s:
+        return 2.0 * (attempt + 1)
+    return None
+
+
+def _has_content(response: object) -> bool:
+    """True if the response carries at least one usable text/function_call part.
+
+    flash-lite intermittently returns a candidate with no parts (empty
+    response), especially on larger tool-laden prompts. Such a response isn't
+    an exception, so we detect it explicitly and retry.
+    """
+    cands = getattr(response, "candidates", None)
+    if not cands:
+        return False
+    cand = cands[0]
+    if not cand.content or not cand.content.parts:
+        return False
+    return any(
+        getattr(p, "text", None) or getattr(p, "function_call", None)
+        for p in cand.content.parts
+    )
+
+
+def generate_content_with_retry(
+    contents: object,
+    config: types.GenerateContentConfig,
+    *,
+    retries: int = 5,
+):
+    """Single choke-point for Gemini calls, with retry on 503, per-minute 429,
+    and empty (zero-part) responses.
+
+    The agent (Decision 16) makes several calls per question; on the free tier
+    any one can hit a transient 503, the per-minute 429, or a flash-lite empty
+    candidate. Centralizing retry here means synthesis, NL→SQL, planning, and
+    the tool-loop all inherit it, so a single blip doesn't abort the graph.
+    """
+    last: Exception | None = None
+    for i in range(retries):
+        try:
+            response = get_gemini_client().models.generate_content(
+                model=GEMINI_MODEL, contents=contents, config=config
+            )
+        except Exception as e:  # noqa: BLE001 — re-raised unless _retry_delay matches
+            delay = _retry_delay(e, i)
+            if delay is not None and i < retries - 1:
+                last = e
+                time.sleep(delay)
+                continue
+            raise
+        # Empty candidate → transient; retry a couple times before giving up.
+        if not _has_content(response) and i < retries - 1:
+            time.sleep(1.0)
+            continue
+        return response
+    raise last  # type: ignore[misc]
+
+
+def _config(
+    system_instruction: str,
+    *,
+    tools: list[types.Tool] | None = None,
+    max_output_tokens: int = MAX_TOKENS,
+    temperature: float = 0.0,
+) -> types.GenerateContentConfig:
+    """Shared config: thinking disabled (synthesis/routing want determinism)."""
+    return types.GenerateContentConfig(
+        system_instruction=system_instruction,
+        tools=tools,
+        max_output_tokens=max_output_tokens,
+        temperature=temperature,
+        thinking_config=types.ThinkingConfig(thinking_budget=0),
+    )
+
+
+def _extract_text(response: object) -> tuple[str, str]:
+    """Pull (text, finish_reason) out of a Gemini response defensively.
+
+    If the candidate was blocked (safety) or truncated, `.parts` may be empty;
+    `response.text` would warn/raise in that case, so we walk the parts.
+    """
+    text = ""
+    finish_reason = "unknown"
+    candidates = getattr(response, "candidates", None)
+    if candidates:
+        cand = candidates[0]
+        finish_reason = str(getattr(cand, "finish_reason", "unknown"))
+        if cand.content and cand.content.parts:
+            text = "".join(
+                p.text for p in cand.content.parts if getattr(p, "text", None)
+            )
+    return text, finish_reason
+
+
+def generate_text(
+    system_instruction: str,
+    user_text: str,
+    *,
+    max_output_tokens: int = 512,
+    temperature: float = 0.0,
+) -> str:
+    """Single-shot text completion — the building block for sub-LLM tasks
+    like NL→SQL, where we want raw text out, not a SynthesisResult.
+
+    (Lives on the Gemini backend for now; if LLM_PROVIDER swaps to Anthropic,
+    this is the one helper sql_query would need mirrored in claude.py.)
+    """
+    response = generate_content_with_retry(
+        user_text,
+        _config(
+            system_instruction,
+            max_output_tokens=max_output_tokens,
+            temperature=temperature,
+        ),
+    )
+    text, _ = _extract_text(response)
+    return text
+
+
+def synthesize_gemini(question: str, chunks: list[RetrievedChunk]) -> SynthesisResult:
+    if not chunks:
+        return empty_result(GEMINI_MODEL)
+
+    # system_instruction plays the role Anthropic's `system=` does — keeps
+    # grounding rules out of the user turn. temperature 0 → deterministic
+    # grounded extraction, not creativity.
+    response = generate_content_with_retry(
+        build_user_message(question, chunks),
+        _config(SYSTEM_PROMPT),
+    )
+
+    answer_text, finish_reason = _extract_text(response)
+
+    usage = response.usage_metadata
+    return SynthesisResult(
+        answer=answer_text,
+        model=GEMINI_MODEL,
+        input_tokens=getattr(usage, "prompt_token_count", 0) or 0,
+        output_tokens=getattr(usage, "candidates_token_count", 0) or 0,
+        # Gemini doesn't bill a separate cache-write tier the way Anthropic
+        # does; implicit caching just reports read tokens. Keep write at 0.
+        cache_creation_input_tokens=0,
+        cache_read_input_tokens=getattr(usage, "cached_content_token_count", 0) or 0,
+        stop_reason=finish_reason,
+    )
+
+
+# ── Agent tool-loop (native function calling) ─────────────────────────────
+def _to_schema(js: dict) -> types.Schema:
+    """One JSON-schema fragment → a genai Schema (recursively)."""
+    schema = types.Schema(type=_TYPE_MAP.get(js.get("type", "object"), "STRING"))
+    if "description" in js:
+        schema.description = js["description"]
+    if js.get("type") == "object":
+        schema.properties = {k: _to_schema(v) for k, v in js.get("properties", {}).items()}
+        if js.get("required"):
+            schema.required = list(js["required"])
+    if js.get("type") == "array" and "items" in js:
+        schema.items = _to_schema(js["items"])
+    return schema
+
+
+def _gemini_tool() -> types.Tool:
+    from finrag.tools import TOOL_SPECS  # lazy: avoid llm↔tools import cycle
+
+    return types.Tool(
+        function_declarations=[
+            types.FunctionDeclaration(
+                name=s.name, description=s.description, parameters=_to_schema(s.parameters)
+            )
+            for s in TOOL_SPECS
+        ]
+    )
+
+
+def _args_to_dict(args: object) -> dict:
+    """Convert a Gemini function_call.args (proto Map) to a plain dict."""
+    def conv(v):
+        if hasattr(v, "items"):
+            return {k: conv(x) for k, x in v.items()}
+        if isinstance(v, (list, tuple)):
+            return [conv(x) for x in v]
+        return v
+
+    return conv(args) if args else {}
+
+
+def tool_loop(
+    system: str,
+    user_text: str,
+    *,
+    max_tokens: int = 1024,
+    max_iters: int = 5,
+) -> ToolLoopResult:
+    """Run Gemini with tools until it stops requesting them (or max_iters).
+    Mirrors claude.tool_loop's signature/return so the dispatcher can pick."""
+    from finrag.tools import dispatch  # lazy: avoid llm↔tools import cycle
+
+    config = types.GenerateContentConfig(
+        system_instruction=system,
+        tools=[_gemini_tool()],
+        max_output_tokens=max_tokens,
+        temperature=0.0,
+        thinking_config=types.ThinkingConfig(thinking_budget=0),
+    )
+    contents: list[types.Content] = [
+        types.Content(role="user", parts=[types.Part(text=user_text)])
+    ]
+    in_tok = out_tok = 0
+    calls: list[ToolCall] = []
+    answer = ""
+
+    for _ in range(max_iters):
+        resp = generate_content_with_retry(contents, config)
+        um = resp.usage_metadata
+        in_tok += getattr(um, "prompt_token_count", 0) or 0
+        out_tok += getattr(um, "candidates_token_count", 0) or 0
+
+        cand = resp.candidates[0] if resp.candidates else None
+        if cand is None or not cand.content or not cand.content.parts:
+            break
+        parts = cand.content.parts
+        contents.append(cand.content)
+
+        fcs = [p.function_call for p in parts if getattr(p, "function_call", None)]
+        if not fcs:
+            answer = "".join(p.text for p in parts if getattr(p, "text", None))
+            break
+
+        response_parts: list[types.Part] = []
+        for fc in fcs:
+            args = _args_to_dict(fc.args)
+            result = json_safe(dispatch(fc.name, args))
+            calls.append(ToolCall(fc.name, args, result))
+            response_parts.append(
+                types.Part.from_function_response(name=fc.name, response=result)
+            )
+        contents.append(types.Content(role="user", parts=response_parts))
+
+    return ToolLoopResult(answer=answer, input_tokens=in_tok, output_tokens=out_tok, tool_calls=calls)

backend/src/finrag/llm/local.py

@@ -0,0 +1,229 @@
+"""Local / edge backend — Llama 3.2 3B via Ollama's OpenAI-compatible API.
+
+This is the third provider behind the seam (see [[gemini]], [[claude]]). It maps
+Ollama's responses onto the same `SynthesisResult`/`ToolLoopResult`, so no node,
+tool, or graph code learns a local model is answering — `llm_provider="local"`
+is the only switch.
+
+Why the OpenAI client (not Ollama's native API): Ollama exposes an
+OpenAI-compatible endpoint on :11434/v1, so the *same* code targets vLLM,
+llama.cpp, or LM Studio by changing `local_base_url`. That portability is the
+point of the edge story — the seam isn't Ollama-specific, it's "any
+OpenAI-compatible local server."
+
+The edge reality (the finding this variant exists to produce): a 3B model
+retrieves + synthesizes grounded answers fine, but its tool-calling is weak — it
+mis-forms or skips function calls that Claude handles reliably. So `tool_loop`
+honors `settings.local_use_tools`: True runs the real agentic loop (and we report
+how often it misfires); False degrades to synthesis-only over the provided
+context, which is what small local models can actually do dependably.
+
+No prompt caching here — local inference has no per-token cost or cache tier, so
+the cache fields on SynthesisResult stay 0 (same as Gemini, see [[base]]).
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+
+from openai import OpenAI
+
+from finrag.config import settings
+from finrag.llm.base import (
+    MAX_TOKENS,
+    SYSTEM_PROMPT,
+    SynthesisResult,
+    ToolCall,
+    ToolLoopResult,
+    build_user_message,
+    empty_result,
+    json_safe,
+)
+from finrag.retrieval.vector import RetrievedChunk
+
+
+@lru_cache(maxsize=1)
+def get_local_client() -> OpenAI:
+    """OpenAI client pointed at the local Ollama server. The api_key is a
+    required-but-ignored placeholder (Ollama doesn't auth). A clear error if the
+    daemon isn't up mirrors the missing-key errors on the cloud backends."""
+    return OpenAI(base_url=settings.local_base_url, api_key="ollama")
+
+
+def _model() -> str:
+    return settings.local_model
+
+
+def generate_text(
+    system_instruction: str,
+    user_text: str,
+    *,
+    max_output_tokens: int = 512,
+    temperature: float = 0.0,
+) -> str:
+    """Single-shot text completion (planning, NL→SQL). Mirrors the claude/gemini
+    backends so the dispatcher can pick any provider."""
+    resp = get_local_client().chat.completions.create(
+        model=_model(),
+        messages=[
+            {"role": "system", "content": system_instruction},
+            {"role": "user", "content": user_text},
+        ],
+        max_tokens=max_output_tokens,
+        temperature=temperature,
+    )
+    return resp.choices[0].message.content or ""
+
+
+def synthesize_local(question: str, chunks: list[RetrievedChunk]) -> SynthesisResult:
+    if not chunks:
+        return empty_result(_model())
+
+    resp = get_local_client().chat.completions.create(
+        model=_model(),
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": build_user_message(question, chunks)},
+        ],
+        max_tokens=MAX_TOKENS,
+        temperature=0.0,
+    )
+    choice = resp.choices[0]
+    usage = resp.usage
+    return SynthesisResult(
+        answer=choice.message.content or "",
+        model=_model(),
+        input_tokens=getattr(usage, "prompt_tokens", 0) or 0,
+        output_tokens=getattr(usage, "completion_tokens", 0) or 0,
+        # Local inference has no cache-billing tier; keep both at 0.
+        cache_creation_input_tokens=0,
+        cache_read_input_tokens=0,
+        stop_reason=choice.finish_reason or "unknown",
+    )
+
+
+# ── Agent tool-loop (OpenAI-style function calling) ──────────────────────────
+def _openai_tools() -> list[dict]:
+    """ToolSpec registry → OpenAI tool schema. ToolSpec.parameters are already
+    JSON-schema, which is exactly the `function.parameters` shape."""
+    from finrag.tools import TOOL_SPECS  # lazy: avoid llm↔tools import cycle
+
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": s.name,
+                "description": s.description,
+                "parameters": s.parameters,
+            },
+        }
+        for s in TOOL_SPECS
+    ]
+
+
+def _synthesis_only(system: str, user_text: str, max_tokens: int) -> ToolLoopResult:
+    """Degraded path: no tools offered, just grounded synthesis over the context
+    already embedded in `user_text`. This is what a 3B model does reliably, so we
+    benchmark it as the honest edge finding when tool-calling is off."""
+    resp = get_local_client().chat.completions.create(
+        model=_model(),
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user", "content": user_text},
+        ],
+        max_tokens=max_tokens,
+        temperature=0.0,
+    )
+    usage = resp.usage
+    return ToolLoopResult(
+        answer=resp.choices[0].message.content or "",
+        input_tokens=getattr(usage, "prompt_tokens", 0) or 0,
+        output_tokens=getattr(usage, "completion_tokens", 0) or 0,
+        tool_calls=[],
+    )
+
+
+def tool_loop(
+    system: str,
+    user_text: str,
+    *,
+    max_tokens: int = 1024,
+    max_iters: int = 5,
+) -> ToolLoopResult:
+    """Run the local model with tools until it stops requesting them (or
+    max_iters). Mirrors claude/gemini tool_loop's signature/return.
+
+    When settings.local_use_tools is False, skip tool-calling entirely and run
+    synthesis-only — the documented degraded mode for small models."""
+    if not settings.local_use_tools:
+        return _synthesis_only(system, user_text, max_tokens)
+
+    from finrag.tools import dispatch  # lazy: avoid llm↔tools import cycle
+
+    tools = _openai_tools()
+    messages: list[dict] = [
+        {"role": "system", "content": system},
+        {"role": "user", "content": user_text},
+    ]
+    in_tok = out_tok = 0
+    calls: list[ToolCall] = []
+    answer = ""
+
+    for _ in range(max_iters):
+        resp = get_local_client().chat.completions.create(
+            model=_model(),
+            messages=messages,
+            tools=tools,
+            max_tokens=max_tokens,
+            temperature=0.0,
+        )
+        msg = resp.choices[0].message
+        usage = resp.usage
+        in_tok += getattr(usage, "prompt_tokens", 0) or 0
+        out_tok += getattr(usage, "completion_tokens", 0) or 0
+
+        if msg.tool_calls:
+            # Re-send the assistant turn verbatim (content + the tool_calls it
+            # requested), then one tool message per call, keyed by tool_call_id.
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": msg.content or "",
+                    "tool_calls": [
+                        {
+                            "id": tc.id,
+                            "type": "function",
+                            "function": {
+                                "name": tc.function.name,
+                                "arguments": tc.function.arguments,
+                            },
+                        }
+                        for tc in msg.tool_calls
+                    ],
+                }
+            )
+            for tc in msg.tool_calls:
+                # 3B models sometimes emit malformed JSON args — treat as empty
+                # rather than crashing the loop (part of the weak-tool-calling story).
+                try:
+                    args = json.loads(tc.function.arguments or "{}")
+                except json.JSONDecodeError:
+                    args = {}
+                result = json_safe(dispatch(tc.function.name, args))
+                calls.append(ToolCall(tc.function.name, args, result))
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": json.dumps(result),
+                    }
+                )
+            continue
+
+        answer = msg.content or ""
+        break
+
+    return ToolLoopResult(
+        answer=answer, input_tokens=in_tok, output_tokens=out_tok, tool_calls=calls
+    )

backend/src/finrag/main.py

@@ -0,0 +1,226 @@
+import json
+from typing import Any
+
+from fastapi import Depends, FastAPI
+from fastapi.encoders import jsonable_encoder
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from finrag.agent import get_agent, run_agent
+from finrag.config import settings
+from finrag.guardrails import cap_status, enforce
+from finrag.llm import synthesize
+from finrag.retrieval.rerank import rerank_search
+from finrag.retrieval.vector import RetrievedChunk
+
+app = FastAPI(title="FinRAG", version="0.1.0")
+
+# CORS allow-list comes from settings: dev defaults to the Next.js dev server;
+# the prod deploy sets ALLOWED_ORIGINS to the exact Vercel origin (docs/deploy.md).
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins_list,
+    allow_credentials=True,
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+
+# ── Request / response models ─────────────────────────────────────────────
+class QueryRequest(BaseModel):
+    question: str = Field(..., min_length=1, max_length=1000)
+    top_k: int = Field(default=5, ge=1, le=50)
+    # Optional payload filters — agent (Day 3) will populate these dynamically
+    ticker: str | None = None
+    fiscal_year: int | None = None
+    chunk_type: str | None = Field(
+        default=None,
+        description="Filter to 'narrative' or 'table' chunks only.",
+    )
+
+
+class QueryResponse(BaseModel):
+    question: str
+    chunks: list[RetrievedChunk]
+
+
+class AnswerRequest(QueryRequest):
+    """Same filter shape as QueryRequest; answer endpoint just adds synthesis."""
+
+    pass
+
+
+class AnswerUsage(BaseModel):
+    """Surfaced so the frontend (and curious humans) can see prompt-caching
+    is working: cache_read_input_tokens should be > 0 on the second+ call."""
+
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cache_creation_input_tokens: int
+    cache_read_input_tokens: int
+    stop_reason: str
+
+
+class AnswerResponse(BaseModel):
+    question: str
+    answer: str
+    chunks: list[RetrievedChunk]
+    usage: AnswerUsage
+
+
+class AgentResponse(BaseModel):
+    question: str
+    answer: str
+    route: str
+    chunks: list[RetrievedChunk]
+    # Ordered node/tool steps the agent took — drives the frontend trace UI.
+    trace: list[dict[str, Any]]
+    usage: dict[str, int]
+
+
+# ── Routes ────────────────────────────────────────────────────────────────
+@app.get("/health")
+def health() -> dict[str, Any]:
+    """Liveness + observable guardrail state (so the cap is visible without
+    grepping logs, and the frontend can show 'N questions left today')."""
+    return {
+        "status": "ok",
+        "llm_mode": settings.llm_mode,
+        "provider": settings.llm_provider,
+        "rate_limit_per_min": settings.rate_limit_per_min,
+        **cap_status(),
+    }
+
+
+@app.post("/query", response_model=QueryResponse)
+def query(req: QueryRequest) -> QueryResponse:
+    """Three-stage retrieval: BM25 + dense (RRF-fused) → Cohere Rerank v3.
+
+    Returns the raw retrieved chunks. Used by the eval harness and for
+    inspecting retrieval quality in isolation.
+    """
+    chunks = rerank_search(
+        question=req.question,
+        top_k=req.top_k,
+        ticker=req.ticker,
+        fiscal_year=req.fiscal_year,
+        chunk_type=req.chunk_type,
+    )
+    return QueryResponse(question=req.question, chunks=chunks)
+
+
+@app.post("/answer", response_model=AnswerResponse, dependencies=[Depends(enforce)])
+def answer(req: AnswerRequest) -> AnswerResponse:
+    """Retrieve top-K with the Day-2 funnel, then synthesize a grounded
+    answer with Claude. Citations are returned as [N] inline references
+    pointing into the `chunks` array (1-based).
+
+    Day-3 agent + tool use (sql_query, calculator) lands in the next
+    decision. This endpoint will remain available as the "retrieval-only
+    synthesis" baseline so we can measure agent value-add against it.
+    """
+    chunks = rerank_search(
+        question=req.question,
+        top_k=req.top_k,
+        ticker=req.ticker,
+        fiscal_year=req.fiscal_year,
+        chunk_type=req.chunk_type,
+    )
+    result = synthesize(req.question, chunks)
+    return AnswerResponse(
+        question=req.question,
+        answer=result.answer,
+        chunks=chunks,
+        usage=AnswerUsage(
+            model=result.model,
+            input_tokens=result.input_tokens,
+            output_tokens=result.output_tokens,
+            cache_creation_input_tokens=result.cache_creation_input_tokens,
+            cache_read_input_tokens=result.cache_read_input_tokens,
+            stop_reason=result.stop_reason,
+        ),
+    )
+
+
+@app.post("/agent", response_model=AgentResponse, dependencies=[Depends(enforce)])
+def agent_endpoint(req: AnswerRequest) -> AgentResponse:
+    """Run the LangGraph agent: plan → (retrieve) → tool-loop → synthesize.
+
+    Unlike /answer (retrieval + plain synthesis), this routes the question,
+    optionally pulls vector context, and lets the model call tools
+    (sql_query, calculator, lookup_citation). Returns the answer plus the full
+    node/tool `trace` for the frontend to render. /answer stays as the baseline.
+    """
+    final = run_agent(req.question)
+    return AgentResponse(
+        question=req.question,
+        answer=final.get("answer", ""),
+        route=final.get("route", ""),
+        chunks=final.get("chunks", []),
+        trace=final.get("trace", []),
+        usage=final.get("usage", {}),
+    )
+
+
+def _sse(event: str, data: Any) -> str:
+    """One Server-Sent-Events frame. jsonable_encoder handles RetrievedChunk
+    (pydantic) and any dates/Decimals in tool results."""
+    return f"event: {event}\ndata: {json.dumps(jsonable_encoder(data))}\n\n"
+
+
+@app.post("/agent/stream", dependencies=[Depends(enforce)])
+def agent_stream(req: AnswerRequest) -> StreamingResponse:
+    """Streaming twin of /agent (Server-Sent Events). The client watches the
+    agent reason in real time:
+
+        event: rewrite | route | retrieve   planning milestones (per graph node)
+        event: tool_call                     each tool the moment it executes
+        event: token                         final-answer text deltas as generated
+        event: done                          full answer + route + chunks + usage + trace
+        event: error                         message, if the run raises mid-stream
+
+    Milestones come from LangGraph 'updates' (state deltas as each node finishes);
+    tokens and tool_calls come from the agent node's custom stream writer. Both
+    are pulled from one `graph.stream(stream_mode=["updates","custom"])` so they
+    arrive interleaved in true execution order. tool_call/synthesize trace items
+    are skipped in the 'updates' pass — they're already streamed live — but the
+    'done' frame still carries the complete trace for the final render."""
+
+    def event_gen():
+        graph = get_agent()
+        final: dict[str, Any] = {
+            "question": req.question,
+            "answer": "",
+            "route": "",
+            "chunks": [],
+            "usage": {},
+            "trace": [],
+        }
+        try:
+            for mode, chunk in graph.stream(
+                {"question": req.question, "trace": []},
+                stream_mode=["updates", "custom"],
+            ):
+                if mode == "custom":
+                    yield _sse(chunk.get("type", "custom"), chunk)
+                    continue
+                # mode == "updates": chunk is {node_name: state_delta}
+                for _node, delta in chunk.items():
+                    for ev in delta.get("trace", []):
+                        if ev.get("type") in ("rewrite", "route", "retrieve", "fallback"):
+                            yield _sse(ev["type"], ev)
+                    for key in ("answer", "route", "chunks", "usage"):
+                        if key in delta:
+                            final[key] = delta[key]
+                    final["trace"].extend(delta.get("trace", []))
+            yield _sse("done", final)
+        except Exception as e:  # don't 500 mid-stream — report and close cleanly
+            yield _sse("error", {"message": str(e)})
+
+    return StreamingResponse(
+        event_gen(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )

backend/src/finrag/retrieval/hybrid.py

@@ -0,0 +1,136 @@
+"""Hybrid retrieval: dense (Qdrant) + lexical (BM25) fused via RRF.
+
+Why RRF rather than score normalization: BM25 scores and cosine similarities
+are on different scales with different distributions. Normalizing them risks
+arbitrary calibration choices. RRF discards raw scores and uses *ranks*,
+which makes the fusion calibration-free and notably robust.
+
+Formula (Cormack, Clarke, Buettcher 2009):
+    RRF_score(d) = Σ over rankers r:  1 / (k + rank_r(d))
+    rank is 1-based; k=60 is the paper's value and works in practice.
+"""
+
+from __future__ import annotations
+
+from finrag.retrieval import lexical
+from finrag.retrieval.vector import (
+    RetrievedChunk,
+    payload_to_chunk,
+    retrieve_by_chunk_ids,
+    search as dense_search,
+)
+
+# Constants
+RRF_K = 60       # smoothing — paper default, do not tune without eval
+DEFAULT_K_EACH = 50  # candidates per retriever before fusion
+
+
+def _rrf_fuse(
+    ranked_lists: list[list[str]], k: int = RRF_K
+) -> dict[str, float]:
+    """Compute RRF scores given multiple ranked lists of chunk_ids.
+
+    Each list should be in retrieval-order (best first). A chunk_id absent
+    from a list contributes 0 from that ranker.
+    """
+    scores: dict[str, float] = {}
+    for ranks in ranked_lists:
+        for position, chunk_id in enumerate(ranks, start=1):
+            scores[chunk_id] = scores.get(chunk_id, 0.0) + 1.0 / (k + position)
+    return scores
+
+
+def hybrid_search(
+    question: str,
+    top_k: int = 5,
+    ticker: str | None = None,
+    fiscal_year: int | None = None,
+    chunk_type: str | None = None,
+    k_each: int = DEFAULT_K_EACH,
+) -> list[RetrievedChunk]:
+    """End-to-end hybrid retrieval.
+
+    Steps:
+      1. Run dense and BM25 in parallel-ish (sequential here; both fast).
+      2. RRF-fuse the two rank orderings into a single score per chunk_id.
+      3. Take top_k by fused score.
+      4. Hydrate any chunk_ids that came only from BM25 by batch-fetching
+         their payloads from Qdrant.
+      5. Return RetrievedChunk objects with `score` = the RRF fused score.
+
+    The score field is now the RRF score, not raw cosine or BM25. RRF scores
+    are small (typically 0.01-0.05 for top results) — don't compare them to
+    Day-1 cosine scores; they're on different scales.
+    """
+    # 1. Candidates from each retriever, both filter-aware so the candidate
+    #    pool already respects the user's scoping.
+    dense_chunks = dense_search(
+        question=question,
+        top_k=k_each,
+        ticker=ticker,
+        fiscal_year=fiscal_year,
+        chunk_type=chunk_type,
+    )
+    bm25_results = lexical.search(
+        query=question,
+        top_k=k_each,
+        ticker=ticker,
+        fiscal_year=fiscal_year,
+        chunk_type=chunk_type,
+    )
+
+    dense_ids = [c.chunk_id for c in dense_chunks]
+    bm25_ids = [cid for cid, _ in bm25_results]
+
+    # 2. RRF fuse
+    rrf_scores = _rrf_fuse([dense_ids, bm25_ids])
+
+    # 3. Top-K by fused score
+    top_ids = sorted(rrf_scores, key=rrf_scores.get, reverse=True)[:top_k]
+
+    # 4. Hydrate. Dense gave us full payloads; for BM25-only chunks, batch
+    #    fetch from Qdrant.
+    dense_map = {c.chunk_id: c for c in dense_chunks}
+    missing_ids = [cid for cid in top_ids if cid not in dense_map]
+    extra_payloads = retrieve_by_chunk_ids(missing_ids)
+
+    # 5. Build final list, score = RRF score
+    results: list[RetrievedChunk] = []
+    for cid in top_ids:
+        rrf_score = rrf_scores[cid]
+        if cid in dense_map:
+            # Reuse the dense RetrievedChunk; just swap the score for the
+            # fused one. model_copy keeps the object immutable-ish.
+            results.append(dense_map[cid].model_copy(update={"score": rrf_score}))
+        elif cid in extra_payloads:
+            results.append(payload_to_chunk(extra_payloads[cid], rrf_score))
+        else:
+            # Should not happen — a fused id with no source. Defensive skip.
+            continue
+    return results
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────
+def main() -> None:
+    """Compare dense-only, BM25-only, and hybrid on a few canary queries."""
+    queries = [
+        "How did Apple's services revenue change in 2023?",
+        "Tesla R&D expense fiscal 2023",
+        "SG&A expense",
+        "supply chain risk",
+    ]
+    for q in queries:
+        print(f"\n=== {q!r} ===")
+        print("  Dense top-3:")
+        for c in dense_search(q, top_k=3):
+            print(f"    {c.ticker} FY{c.fiscal_year}  score={c.score:.3f}  | {c.text[:60]}")
+        print("  BM25 top-3:")
+        for cid, score in lexical.search(q, top_k=3):
+            print(f"    {cid}  score={score:.3f}")
+        print("  Hybrid top-3:")
+        for c in hybrid_search(q, top_k=3):
+            print(f"    {c.ticker} FY{c.fiscal_year}  rrf={c.score:.4f}  | {c.text[:60]}")
+
+
+if __name__ == "__main__":
+    main()

backend/src/finrag/retrieval/lexical.py

@@ -0,0 +1,211 @@
+"""BM25 lexical retrieval over the same chunks indexed in Qdrant.
+
+Why this exists: dense embeddings (Cohere v3) lose exact-match signal on
+years, tickers, GAAP terminology, and dollar amounts — exactly the tokens
+that matter most in financial documents. BM25 catches these.
+
+This module is *not* a full retriever. It returns (chunk_id, score) pairs.
+The fusion + hydration into full RetrievedChunk objects happens in
+retrieval.hybrid (Decision 10).
+
+Pipeline:
+    build:  data/processed/*.jsonl  ──▶  tokenize  ──▶  BM25Okapi
+                                                          │
+                                                          ▼
+                                          pickled to data/bm25_index.pkl
+    load:   pickle load → ready to search
+"""
+
+from __future__ import annotations
+
+import pickle
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from rank_bm25 import BM25Okapi
+
+from finrag.ingestion.parse import PROCESSED_DIR, Chunk
+
+# parse.py → ingestion/ → finrag/ → src/ → backend/ → ROOT
+REPO_ROOT = Path(__file__).resolve().parents[4]
+INDEX_PATH = REPO_ROOT / "data" / "bm25_index.pkl"
+
+# Token regex: any run of alphanumeric chars including underscores. Drops
+# punctuation, splits on whitespace + symbols. Lowercased before splitting.
+# Critical: this exact function is also called on queries — the same vocab
+# must be used on both sides or no terms will match.
+_TOKEN_RE = re.compile(r"\w+")
+
+
+def tokenize(text: str) -> list[str]:
+    """Lowercase + simple word tokenization.
+
+    The same function runs on chunk text at index time and on user queries
+    at search time. Don't tweak one side without the other.
+    """
+    return _TOKEN_RE.findall(text.lower())
+
+
+# ── On-disk format ────────────────────────────────────────────────────────
+@dataclass
+class _BM25Bundle:
+    """What we pickle. Separated so we can version the schema later.
+
+    `chunks` is a list of (id, ticker, fiscal_year, chunk_type) tuples — the
+    minimal payload we need for post-search filtering and lookups. The full
+    chunk text/metadata lives in Qdrant; storing it twice would double disk
+    use and risk drift between stores.
+    """
+
+    bm25: BM25Okapi
+    # Parallel arrays — index `i` in `bm25` corresponds to chunks[i].
+    # We use a tuple-list rather than a dict because BM25Okapi indexes by
+    # position, not by chunk_id.
+    chunk_ids: list[str]
+    tickers: list[str]
+    fiscal_years: list[int]
+    chunk_types: list[str]
+
+
+# Pin __module__ so pickle records the dotted path "finrag.retrieval.lexical"
+# instead of "__main__" when this file is run via `python -m`. Without this,
+# the pickle is only loadable from the same entrypoint that built it.
+_BM25Bundle.__module__ = "finrag.retrieval.lexical"
+
+
+# ── Build ─────────────────────────────────────────────────────────────────
+def _load_all_chunks(processed_dir: Path) -> list[Chunk]:
+    chunks: list[Chunk] = []
+    for jsonl in sorted(processed_dir.glob("*.jsonl")):
+        for line in jsonl.read_text(encoding="utf-8").splitlines():
+            if line.strip():
+                chunks.append(Chunk.model_validate_json(line))
+    return chunks
+
+
+def build_index(processed_dir: Path = PROCESSED_DIR) -> _BM25Bundle:
+    """Build a BM25 index from all chunks in processed_dir and persist it."""
+    chunks = _load_all_chunks(processed_dir)
+    if not chunks:
+        raise RuntimeError(f"No chunks found in {processed_dir}")
+
+    print(f"Tokenizing {len(chunks)} chunks…")
+    tokenized = [tokenize(c.text) for c in chunks]
+
+    print("Building BM25Okapi index…")
+    # k1=1.5, b=0.75 are BM25's standard defaults. The rank_bm25 library
+    # exposes these as kwargs; leave them at defaults unless we have a
+    # specific reason — these are well-calibrated for English text and
+    # any tuning we'd do should be eval-driven, not guess-driven.
+    bm25 = BM25Okapi(tokenized)
+
+    bundle = _BM25Bundle(
+        bm25=bm25,
+        chunk_ids=[c.chunk_id for c in chunks],
+        tickers=[c.ticker for c in chunks],
+        fiscal_years=[c.fiscal_year for c in chunks],
+        chunk_types=[c.chunk_type for c in chunks],
+    )
+
+    INDEX_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with INDEX_PATH.open("wb") as f:
+        pickle.dump(bundle, f, protocol=pickle.HIGHEST_PROTOCOL)
+    print(f"Wrote {INDEX_PATH} ({INDEX_PATH.stat().st_size / 1024:.0f} KB)")
+
+    return bundle
+
+
+# ── Load + search ────────────────────────────────────────────────────────
+_cached_bundle: _BM25Bundle | None = None
+
+
+def load_index() -> _BM25Bundle:
+    """Load the pickled index from disk, caching in-process.
+
+    Module-level cache (not lru_cache) because the underlying BM25Okapi
+    object is heavyweight (~30 MB at our scale) — we want exactly one in
+    memory regardless of how many callers ask for it.
+    """
+    global _cached_bundle
+    if _cached_bundle is None:
+        if not INDEX_PATH.exists():
+            raise FileNotFoundError(
+                f"BM25 index not found at {INDEX_PATH}. "
+                "Run `uv run python -m finrag.retrieval.lexical` to build it."
+            )
+        with INDEX_PATH.open("rb") as f:
+            _cached_bundle = pickle.load(f)
+    return _cached_bundle
+
+
+def search(
+    query: str,
+    top_k: int = 50,
+    ticker: str | None = None,
+    fiscal_year: int | None = None,
+    chunk_type: str | None = None,
+) -> list[tuple[str, float]]:
+    """Return ranked (chunk_id, score) tuples for a query.
+
+    Filtering is post-ranking: we ask BM25 for top-N (where N > top_k to
+    leave headroom after filtering), then drop chunks that don't match.
+    This is fine at our scale (~4k chunks); at 1M+ you'd want a filter-
+    aware index structure or pre-shard by ticker.
+    """
+    bundle = load_index()
+    tokens = tokenize(query)
+    if not tokens:
+        return []
+
+    # get_scores returns one score per indexed document, in index order
+    scores = bundle.bm25.get_scores(tokens)
+
+    # Build candidate list — over-fetch to allow for filter attrition.
+    # 4x is a heuristic; if filters are tight (e.g. one ticker × one year),
+    # we may want more — but unbounded over-fetch defeats the purpose.
+    candidate_count = top_k * 4 if (ticker or fiscal_year or chunk_type) else top_k
+    candidate_count = min(candidate_count, len(scores))
+
+    # argpartition is O(n) vs argsort's O(n log n) — meaningful at scale.
+    # We get the top-K unordered, then sort just those K.
+    top_indices = np.argpartition(-scores, candidate_count - 1)[:candidate_count]
+    # Sort the candidates by descending score
+    top_indices = top_indices[np.argsort(-scores[top_indices])]
+
+    results: list[tuple[str, float]] = []
+    for i in top_indices:
+        if ticker and bundle.tickers[i] != ticker:
+            continue
+        if fiscal_year and bundle.fiscal_years[i] != fiscal_year:
+            continue
+        if chunk_type and bundle.chunk_types[i] != chunk_type:
+            continue
+        results.append((bundle.chunk_ids[i], float(scores[i])))
+        if len(results) >= top_k:
+            break
+
+    return results
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────
+def main() -> None:
+    build_index()
+
+    # Sanity check: run a couple of test queries
+    print("\nSanity-check queries:")
+    for q in [
+        "services revenue 2023",
+        "iPhone net sales",
+        "SG&A expense",
+        "Tesla R&D",
+    ]:
+        results = search(q, top_k=3)
+        print(f"\n  Q: {q!r}")
+        for chunk_id, score in results:
+            print(f"    {chunk_id}  score={score:.3f}")
+
+
+if __name__ == "__main__":
+    main()

backend/src/finrag/retrieval/rerank.py

@@ -0,0 +1,146 @@
+"""Final-stage reranking via Cohere Rerank v3 (cross-encoder).
+
+The reranker fixes the failure modes hybrid retrieval can't:
+  - Lexical accidents (BM25 dragging an entity-mismatched chunk to the top
+    because keyword co-occurrence happens to be high)
+  - Query-document interaction blindness (bi-encoders can't see "Apple" in
+    the query and "Tesla" in the candidate at the same time)
+
+Flow:
+    hybrid_search(top_k=N_CANDIDATES) ──▶ list of RetrievedChunk
+                                              │
+                                              ▼
+                                  Cohere Rerank v3
+                                  (rerank-english-v3.0)
+                                              │
+                                              ▼
+                                  Reordered, top_k chosen
+                                  score = relevance_score (0–1)
+"""
+
+from __future__ import annotations
+
+import time
+
+from cohere.errors import TooManyRequestsError
+
+from finrag.retrieval.hybrid import hybrid_search
+from finrag.retrieval.vector import RetrievedChunk, get_cohere_client
+
+RERANK_MODEL = "rerank-english-v3.0"
+
+# Default candidate-pool size fed to the reranker. 50 is the sweet spot:
+# wide enough that the reranker can rescue chunks ranked 20+ by hybrid,
+# narrow enough to stay under Rerank v3's pricing tier (1 search unit per
+# 100 docs) and latency budget (~200–400ms at 50 docs).
+DEFAULT_CANDIDATES = 50
+
+# Trial-key safety net — same pattern as ingestion/embed.py
+RERANK_RETRY_INITIAL_BACKOFF_SECONDS = 5.0
+RERANK_MAX_RETRIES = 4
+
+
+def _rerank_with_retry(
+    query: str, documents: list[str], top_n: int
+) -> list[tuple[int, float]]:
+    """Call Cohere Rerank v3 with exponential-backoff retry on 429s.
+
+    Returns list of (original_index, relevance_score) in reranker order.
+    """
+    co = get_cohere_client()
+    backoff = RERANK_RETRY_INITIAL_BACKOFF_SECONDS
+
+    for attempt in range(1, RERANK_MAX_RETRIES + 1):
+        try:
+            response = co.rerank(
+                model=RERANK_MODEL,
+                query=query,
+                documents=documents,
+                top_n=top_n,
+            )
+            return [(r.index, r.relevance_score) for r in response.results]
+        except TooManyRequestsError:
+            if attempt == RERANK_MAX_RETRIES:
+                raise
+            print(
+                f"  ⚠ rerank rate-limited; sleeping {backoff:.0f}s "
+                f"(retry {attempt}/{RERANK_MAX_RETRIES - 1})"
+            )
+            time.sleep(backoff)
+            backoff *= 2
+    raise RuntimeError("rerank retry loop exited without resolving")
+
+
+def rerank_search(
+    question: str,
+    top_k: int = 5,
+    ticker: str | None = None,
+    fiscal_year: int | None = None,
+    chunk_type: str | None = None,
+    candidates: int = DEFAULT_CANDIDATES,
+) -> list[RetrievedChunk]:
+    """Hybrid retrieval + cross-encoder rerank. The user-facing default.
+
+    The `score` field on returned chunks is the rerank relevance_score
+    (0–1, semantically meaningful) — *not* the RRF score from the hybrid
+    stage. You can compare these across queries: 0.85 means "strongly
+    relevant" no matter what was asked.
+    """
+    # 1. Get a wide candidate pool from hybrid fusion. Pass the same filters
+    #    through — scoping should happen before rerank, not after.
+    pool = hybrid_search(
+        question=question,
+        top_k=candidates,
+        ticker=ticker,
+        fiscal_year=fiscal_year,
+        chunk_type=chunk_type,
+    )
+    if not pool:
+        return []
+
+    # If we have fewer candidates than top_k, no reranking is meaningful —
+    # just return what we have.
+    if len(pool) <= top_k:
+        return pool
+
+    # 2. Cross-encoder rerank
+    documents = [c.text for c in pool]
+    ranked = _rerank_with_retry(
+        query=question,
+        documents=documents,
+        top_n=top_k,
+    )
+
+    # 3. Reassemble in rerank order with the rerank score replacing RRF
+    return [
+        pool[orig_idx].model_copy(update={"score": rel_score})
+        for orig_idx, rel_score in ranked
+    ]
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────
+def main() -> None:
+    """Side-by-side: hybrid (RRF only) vs hybrid+rerank, same queries."""
+    queries = [
+        "How did Apple's services revenue change in 2023?",
+        "Tesla R&D expense fiscal 2023",
+        "SG&A expense",
+        "JPMorgan net interest income",
+        "supply chain risk",
+    ]
+    for q in queries:
+        print(f"\n=== {q!r} ===")
+        print("  Hybrid (RRF only) top-3:")
+        for c in hybrid_search(q, top_k=3):
+            print(
+                f"    {c.ticker} FY{c.fiscal_year}  rrf={c.score:.4f}  | {c.text[:60]}"
+            )
+        print("  Hybrid + Rerank v3 top-3:")
+        for c in rerank_search(q, top_k=3):
+            print(
+                f"    {c.ticker} FY{c.fiscal_year}  rel={c.score:.3f}  | {c.text[:60]}"
+            )
+
+
+if __name__ == "__main__":
+    main()

backend/src/finrag/retrieval/vector.py

@@ -0,0 +1,187 @@
+"""Dense vector retrieval over the Qdrant `finrag_chunks` collection.
+
+This is the minimal Day-1 retriever: embed the query with Cohere v3
+(`search_query` side of the asymmetric pair) and run a single nearest-
+neighbor search with optional payload filtering. Hybrid (BM25 + dense)
+and reranking come on Day 2.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import cohere
+from pydantic import BaseModel
+from qdrant_client import QdrantClient
+from qdrant_client.models import (
+    FieldCondition,
+    Filter,
+    MatchValue,
+)
+
+from finrag.config import settings
+from finrag.ingestion.embed import COHERE_MODEL, COLLECTION_NAME
+
+
+# ── Public response model ─────────────────────────────────────────────────
+class RetrievedChunk(BaseModel):
+    """One chunk surfaced by the retriever, with its similarity score.
+
+    All payload fields from the Chunk we indexed are copied through — so the
+    caller (or eventually, the agent/frontend) has everything it needs to
+    render a citation without joining back against another store.
+    """
+
+    chunk_id: str
+    score: float
+    text: str
+    chunk_type: str
+    section_title: str | None
+    ticker: str
+    company_name: str
+    fiscal_year: int
+    period_of_report: str
+    accession_number: str
+    sec_url: str
+
+
+# ── Clients (one per process, cached) ─────────────────────────────────────
+# lru_cache on a no-arg function is the canonical "singleton per process"
+# pattern for FastAPI. Avoids re-creating TLS connections on every request.
+@lru_cache(maxsize=1)
+def get_cohere_client() -> cohere.ClientV2:
+    return cohere.ClientV2(api_key=settings.cohere_api_key)
+
+
+@lru_cache(maxsize=1)
+def get_qdrant_client() -> QdrantClient:
+    return QdrantClient(
+        url=settings.qdrant_url,
+        api_key=settings.qdrant_api_key,
+    )
+
+
+# ── Query embedding ───────────────────────────────────────────────────────
+def embed_query(text: str) -> list[float]:
+    """Embed a user query using the query-side encoder.
+
+    The matching `search_document` lives in ingestion/embed.py. Mismatching
+    these two silently degrades retrieval quality — there's no error, just
+    worse results. See Decision 6's notes on asymmetric retrieval.
+    """
+    co = get_cohere_client()
+    response = co.embed(
+        texts=[text],
+        model=COHERE_MODEL,
+        input_type="search_query",
+        embedding_types=["float"],
+    )
+    return response.embeddings.float_[0]
+
+
+# ── Filter builder ────────────────────────────────────────────────────────
+def _build_filter(
+    ticker: str | None = None,
+    fiscal_year: int | None = None,
+    chunk_type: str | None = None,
+) -> Filter | None:
+    """Translate simple kwarg filters into Qdrant's filter grammar.
+
+    Treats falsy values (None, "", 0) as "not provided" — important because
+    JSON clients (notably Swagger UI) often send "" for unset string fields
+    instead of omitting them, and we don't want to filter for ticker == "".
+    """
+    conditions: list[FieldCondition] = []
+    if ticker:
+        conditions.append(
+            FieldCondition(key="ticker", match=MatchValue(value=ticker))
+        )
+    if fiscal_year:
+        conditions.append(
+            FieldCondition(key="fiscal_year", match=MatchValue(value=fiscal_year))
+        )
+    if chunk_type:
+        conditions.append(
+            FieldCondition(key="chunk_type", match=MatchValue(value=chunk_type))
+        )
+    return Filter(must=conditions) if conditions else None
+
+
+# ── Payload → RetrievedChunk ──────────────────────────────────────────────
+def payload_to_chunk(payload: dict, score: float) -> RetrievedChunk:
+    """Convert a Qdrant payload + score into a RetrievedChunk.
+
+    Shared by dense search and the hybrid retriever's hydration step — keeps
+    the mapping in one place so adding a field to the model means editing
+    one function, not three.
+    """
+    return RetrievedChunk(
+        chunk_id=payload["chunk_id"],
+        score=score,
+        text=payload["text"],
+        chunk_type=payload["chunk_type"],
+        section_title=payload.get("section_title"),
+        ticker=payload["ticker"],
+        company_name=payload["company_name"],
+        fiscal_year=payload["fiscal_year"],
+        period_of_report=payload["period_of_report"],
+        accession_number=payload["accession_number"],
+        sec_url=payload["sec_url"],
+    )
+
+
+# ── Retrieval ─────────────────────────────────────────────────────────────
+def search(
+    question: str,
+    top_k: int = 5,
+    ticker: str | None = None,
+    fiscal_year: int | None = None,
+    chunk_type: str | None = None,
+) -> list[RetrievedChunk]:
+    """Dense-only retrieval: embed the question, search Qdrant, return chunks.
+
+    Kept available for direct testing and the eval harness's comparison runs.
+    The user-facing /query endpoint uses hybrid_search instead.
+    """
+    qdrant = get_qdrant_client()
+    query_vector = embed_query(question)
+    query_filter = _build_filter(ticker, fiscal_year, chunk_type)
+
+    response = qdrant.query_points(
+        collection_name=COLLECTION_NAME,
+        query=query_vector,
+        query_filter=query_filter,
+        limit=top_k,
+        with_payload=True,
+    )
+    return [payload_to_chunk(p.payload, p.score) for p in response.points]
+
+
+def retrieve_by_chunk_ids(chunk_ids: list[str]) -> dict[str, dict]:
+    """Batch-fetch payloads by chunk_id (used by hybrid hydration).
+
+    Returns a dict {chunk_id: payload}. Qdrant stores point IDs as uint64
+    (the hex chunk_id converted), so we convert on the way in and dereference
+    via the payload's own chunk_id field on the way out.
+
+    Ids that aren't valid 16-hex chunk_ids (e.g. a value the agent hallucinated
+    like 'chunk_5') are silently dropped rather than raising — a malformed id is
+    just a miss, so callers see it as not-found, not a crash.
+    """
+    if not chunk_ids:
+        return {}
+    qdrant = get_qdrant_client()
+    point_ids: list[int] = []
+    for cid in chunk_ids:
+        try:
+            point_ids.append(int(cid, 16))
+        except ValueError:
+            continue  # not a hex chunk_id → treat as not-found
+    if not point_ids:
+        return {}
+    points = qdrant.retrieve(
+        collection_name=COLLECTION_NAME,
+        ids=point_ids,
+        with_payload=True,
+    )
+    return {p.payload["chunk_id"]: p.payload for p in points}

backend/src/finrag/tools/__init__.py

@@ -0,0 +1,127 @@
+"""Agent tools — provider-neutral registry.
+
+Each tool is a plain Python function (independently testable) plus a `ToolSpec`
+describing its name, when-to-use text, and JSON-schema parameters. The spec is
+deliberately NOT in any vendor's tool format: Decision 16 adapts these into
+LangChain/LangGraph tools (which bind to Gemini or Claude alike), keeping the
+provider seam from Decision 14 intact. Hardwiring Anthropic's tool_use shape
+here — as the original handoff assumed — would have undone that.
+
+`dispatch(name, args)` is the single call site the agent loop uses to run a
+tool by name; it returns the tool's dict result unchanged.
+
+Three tools, by design — see [[project_finrag_overview]]:
+  calculator       — arithmetic, safe-eval        (pure fn)
+  lookup_citation  — re-fetch a chunk from Qdrant  (read-only)
+  sql_query        — NL → SQL over DuckDB facts     (sub-LLM; added next)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from finrag.tools.calculator import calculator
+from finrag.tools.citation import lookup_citation
+from finrag.tools.sql import sql_query
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    # JSON-schema "object" describing the args. Both Gemini and Anthropic
+    # accept this shape (modulo a thin adapter), as does LangChain.
+    parameters: dict[str, Any]
+    fn: Callable[..., dict[str, Any]]
+
+
+TOOL_SPECS: list[ToolSpec] = [
+    ToolSpec(
+        name="calculator",
+        description=(
+            "Evaluate an arithmetic expression over numeric literals "
+            "(+ - * / // % ** and parentheses). Use for growth rates, margins, "
+            "sums, and ratios instead of doing mental math. Extract the numbers "
+            "from context first, then pass an expression like "
+            "'(383285 - 394328) / 394328 * 100'."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "expression": {
+                    "type": "string",
+                    "description": "Arithmetic expression over numeric literals only.",
+                }
+            },
+            "required": ["expression"],
+        },
+        fn=calculator,
+    ),
+    ToolSpec(
+        name="lookup_citation",
+        description=(
+            "Re-fetch the full text and provenance of a single retrieved chunk "
+            "by its chunk_id. Use when you need to quote an exact figure or "
+            "re-read a chunk you cited earlier."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "chunk_id": {
+                    "type": "string",
+                    "description": (
+                        "The chunk_id of a previously retrieved chunk — the exact "
+                        "value shown as (id=...) in that chunk's header. Do not "
+                        "use the [N] anchor or invent an id."
+                    ),
+                }
+            },
+            "required": ["chunk_id"],
+        },
+        fn=lookup_citation,
+    ),
+    ToolSpec(
+        name="sql_query",
+        description=(
+            "Query exact financial figures (revenue, net income, R&D, margins, "
+            "multi-year or cross-company comparisons) from the structured "
+            "financial_facts database. Pass a natural-language description of "
+            "the numbers you need; SQL is generated and run for you. Prefer this "
+            "over reading figures out of text chunks when precision matters."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "natural_language": {
+                    "type": "string",
+                    "description": "Plain-language description of the figures to fetch.",
+                }
+            },
+            "required": ["natural_language"],
+        },
+        fn=sql_query,
+    ),
+]
+
+# name → spec, for O(1) dispatch.
+TOOL_REGISTRY: dict[str, ToolSpec] = {spec.name: spec for spec in TOOL_SPECS}
+
+
+def dispatch(name: str, args: dict[str, Any]) -> dict[str, Any]:
+    """Run tool `name` with keyword `args`. Returns the tool's dict result.
+
+    Unknown tool names return an error dict (not a raise) so a hallucinated
+    tool call degrades gracefully inside the agent loop.
+    """
+    spec = TOOL_REGISTRY.get(name)
+    if spec is None:
+        return {"error": f"Unknown tool {name!r}. Available: {list(TOOL_REGISTRY)}"}
+    try:
+        return spec.fn(**args)
+    except TypeError as e:
+        # Wrong/missing args from the model — surface as data, not a crash.
+        return {"error": f"Bad arguments for {name!r}: {e}"}
+
+
+__all__ = ["ToolSpec", "TOOL_SPECS", "TOOL_REGISTRY", "dispatch"]

backend/src/finrag/tools/calculator.py

@@ -0,0 +1,91 @@
+"""calculator(expression) — arithmetic on figures the model pulled from context.
+
+Why this exists: LLMs are unreliable at multi-digit arithmetic (growth rates,
+margins, sums across years). Far better to have the model *extract* the numbers
+and delegate the math to real code.
+
+Why not eval(): `eval("__import__('os').system('...')")` is remote code
+execution. A figure could even arrive via a prompt-injected chunk. So we parse
+to an AST and walk it, permitting ONLY numeric literals and arithmetic
+operators — every other node type (names, calls, attributes, subscripts)
+raises. This is an allowlist, not a blocklist: anything we didn't explicitly
+permit is rejected by default.
+"""
+
+from __future__ import annotations
+
+import ast
+import operator
+from typing import Any
+
+# Allowlisted operators → their implementing functions. Anything not here
+# (e.g. bitwise, matmul) is rejected.
+_BIN_OPS: dict[type[ast.operator], Any] = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+    ast.Mod: operator.mod,
+    ast.Pow: operator.pow,
+}
+_UNARY_OPS: dict[type[ast.unaryop], Any] = {
+    ast.UAdd: operator.pos,
+    ast.USub: operator.neg,
+}
+
+# Guardrail: cap exponent magnitude so `10 ** 10**9` can't pin a CPU / OOM.
+_MAX_EXPONENT = 1000
+
+
+def _eval_node(node: ast.AST) -> float:
+    if isinstance(node, ast.Expression):
+        return _eval_node(node.body)
+    if isinstance(node, ast.Constant):
+        if isinstance(node.value, bool) or not isinstance(node.value, (int, float)):
+            raise ValueError(f"Only numeric literals allowed, got {node.value!r}")
+        return float(node.value)
+    if isinstance(node, ast.UnaryOp):
+        op = _UNARY_OPS.get(type(node.op))
+        if op is None:
+            raise ValueError(f"Operator {type(node.op).__name__} not allowed")
+        return op(_eval_node(node.operand))
+    if isinstance(node, ast.BinOp):
+        op = _BIN_OPS.get(type(node.op))
+        if op is None:
+            raise ValueError(f"Operator {type(node.op).__name__} not allowed")
+        left, right = _eval_node(node.left), _eval_node(node.right)
+        if isinstance(node.op, ast.Pow) and abs(right) > _MAX_EXPONENT:
+            raise ValueError(f"Exponent {right} exceeds limit {_MAX_EXPONENT}")
+        return op(left, right)
+    # Any other node — Name, Call, Attribute, Subscript, etc. — is rejected.
+    raise ValueError(f"Expression element {type(node).__name__} not allowed")
+
+
+def calculator(expression: str) -> dict[str, Any]:
+    """Evaluate an arithmetic `expression` and return the numeric result.
+
+    Supports + - * / // % ** and parentheses over numeric literals only.
+    Returns {"result": <float>} on success or {"error": <message>} on failure
+    — tools return errors as data (not exceptions) so the agent can read the
+    message and retry rather than crashing the graph.
+    """
+    try:
+        tree = ast.parse(expression, mode="eval")
+        result = _eval_node(tree)
+        return {"result": result}
+    except ZeroDivisionError:
+        return {"error": "division by zero"}
+    except (ValueError, SyntaxError) as e:
+        return {"error": str(e)}
+
+
+if __name__ == "__main__":
+    # Sanity: valid arithmetic, plus rejection of an injection attempt.
+    for expr in [
+        "(383285 - 394328) / 394328 * 100",   # YoY % change
+        "200583 + 85200",                       # iPhone + Services
+        "2 ** 4000",                            # exponent guard
+        "__import__('os').system('echo pwned')",  # must be rejected
+    ]:
+        print(f"{expr!r:50s} -> {calculator(expr)}")

backend/src/finrag/tools/citation.py

@@ -0,0 +1,37 @@
+"""lookup_citation(chunk_id) — re-fetch one full chunk from Qdrant by id.
+
+Why the agent needs this: retrieval hands the model a working set, but during
+reasoning it may want to pull a specific chunk back in full — to quote an exact
+figure, or to re-read a chunk it cited earlier in a longer tool loop. This is
+the read-only "dereference a citation" primitive.
+
+Thin wrapper over retrieval.vector.retrieve_by_chunk_ids — no new Qdrant
+plumbing, just the single-id ergonomics and a not-found path that returns data
+rather than raising (so the agent can recover).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from finrag.retrieval.vector import payload_to_chunk, retrieve_by_chunk_ids
+
+
+def lookup_citation(chunk_id: str) -> dict[str, Any]:
+    """Return the full chunk for `chunk_id`, or an error dict if absent.
+
+    The score is 1.0 — it's an exact id fetch, not a similarity match; the
+    field exists only to reuse the RetrievedChunk shape the rest of the
+    system already speaks.
+    """
+    payloads = retrieve_by_chunk_ids([chunk_id])
+    payload = payloads.get(chunk_id)
+    if payload is None:
+        return {"error": f"No chunk found with id {chunk_id!r}"}
+    return {"chunk": payload_to_chunk(payload, score=1.0).model_dump()}
+
+
+if __name__ == "__main__":
+    # A real id from the AAPL FY2023 net-sales table chunk (seen in /answer).
+    print(lookup_citation("d899f2e938bec647"))
+    print(lookup_citation("deadbeefdeadbeef"))  # not-found path

backend/src/finrag/tools/sql.py

@@ -0,0 +1,152 @@
+"""sql_query(natural_language) — NL → SQL over the DuckDB financial_facts table.
+
+This is the structured half of the project's "structured + unstructured"
+thesis: precise numbers (revenue, margins, multi-year trends) come from XBRL
+facts in DuckDB, not from prose chunks. The agent calls this when a question
+wants exact figures or cross-year/cross-company comparison.
+
+Pipeline: question → sub-LLM writes SQL (schema in its prompt) → safety guard →
+read-only execute → rows. The generated SQL is returned alongside the rows so
+the frontend can show it verbatim (Decision 18 — half the demo's wow factor).
+
+Security: a model writing SQL is an injection surface. Two layers of defense:
+  1. read-only DuckDB connection (finrag.ingestion.facts.query) — blocks writes.
+  2. statement guard below — single statement, must start SELECT/WITH, and a
+     blocklist rejects DDL/DML and DuckDB's file-reading table functions
+     (read_csv etc.) that a read-only conn would otherwise still allow.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from finrag.ingestion.facts import CONCEPT_MAP, query
+from finrag.llm import generate_text  # provider-neutral dispatcher
+
+MAX_ROWS = 100  # cap returned rows so a broad query can't flood the context
+
+_LINE_ITEMS = ", ".join(sorted(CONCEPT_MAP))
+
+# The sub-LLM's contract. It sees the exact schema + the canonical line_item
+# vocabulary (pulled live from CONCEPT_MAP so it can never drift from the
+# loader) + the conventions that make queries correct against this data.
+_SQL_SYSTEM_PROMPT = f"""You translate questions about company financials into a single DuckDB SQL SELECT.
+
+Table: financial_facts
+Columns:
+  ticker TEXT            -- e.g. 'AAPL', 'TSLA', 'JPM'
+  company_name TEXT
+  fiscal_year INTEGER    -- e.g. 2023
+  fiscal_period TEXT     -- 'FY' for full year; quarters are 'Q1'..'Q4'
+  period_end_date DATE
+  line_item TEXT         -- canonical metric; one of: {_LINE_ITEMS}
+  gaap_concept TEXT      -- raw XBRL concept
+  value DOUBLE           -- the figure
+  unit TEXT              -- 'USD' for money, 'USD/shares' for EPS, 'shares', etc.
+
+Rules:
+- Output ONLY the SQL. No prose, no markdown fences, no trailing semicolon.
+- SELECT only. Never write/modify data.
+- For money metrics filter unit = 'USD'. For annual figures filter fiscal_period = 'FY'.
+- Use the canonical line_item values above — not raw GAAP concepts.
+- Prefer explicit columns; add ORDER BY for multi-row/trend results.
+- This table holds only TOP-LEVEL figures. If the question asks for a metric
+  that is NOT in the line_item list above — e.g. a segment/product/regional
+  figure such as services revenue, iPhone revenue, or Americas sales — do NOT
+  substitute a different metric. Output exactly: NO_QUERY
+
+Examples:
+Q: Apple's revenue in fiscal 2023
+SELECT fiscal_year, value FROM financial_facts
+WHERE ticker = 'AAPL' AND line_item = 'revenue' AND fiscal_period = 'FY' AND unit = 'USD' AND fiscal_year = 2023
+
+Q: Tesla R&D spend over the last three years
+SELECT fiscal_year, value FROM financial_facts
+WHERE ticker = 'TSLA' AND line_item = 'rd_expense' AND fiscal_period = 'FY' ORDER BY fiscal_year
+"""
+
+# Tokens that must never appear in a generated query. Word-boundary matched so
+# they catch statements/functions but not substrings of column names.
+_FORBIDDEN = re.compile(
+    r"\b(insert|update|delete|drop|alter|create|attach|detach|copy|install|"
+    r"load|pragma|set|call|export|read_csv|read_parquet|read_json|read_text|"
+    r"read_blob|glob|system)\b",
+    re.IGNORECASE,
+)
+
+
+def _clean_sql(raw: str) -> str:
+    """Strip markdown fences / stray prose the model may wrap around the SQL."""
+    s = raw.strip()
+    if s.startswith("```"):
+        # remove ```sql ... ``` fencing
+        s = re.sub(r"^```[a-zA-Z]*\n?", "", s)
+        s = re.sub(r"\n?```$", "", s).strip()
+    return s.rstrip(";").strip()
+
+
+def _guard(sql: str) -> str | None:
+    """Return an error string if `sql` is unsafe, else None."""
+    if not sql:
+        return "empty query"
+    # Reject multiple statements (only one trailing-stripped statement allowed).
+    if ";" in sql.rstrip(";"):
+        return "multiple statements are not allowed"
+    head = sql.lstrip("(").lstrip().lower()
+    if not (head.startswith("select") or head.startswith("with")):
+        return "only SELECT/WITH queries are allowed"
+    if _FORBIDDEN.search(sql):
+        return "query contains a disallowed keyword or function"
+    return None
+
+
+def sql_query(natural_language: str) -> dict[str, Any]:
+    """Answer a structured-data question by generating and running SQL.
+
+    Returns {"sql": <str>, "rows": [...], "row_count": n, "truncated": bool}
+    on success, or {"sql": <str?>, "error": <msg>} on failure — the SQL is
+    included even on error so the agent/UI can show what was attempted.
+    """
+    sql = _clean_sql(generate_text(_SQL_SYSTEM_PROMPT, natural_language))
+
+    # The sub-LLM signals "this metric isn't in the structured table" rather
+    # than silently substituting a different line_item (which previously made
+    # the agent report total revenue as "services revenue").
+    if sql.upper().startswith("NO_QUERY"):
+        return {
+            "sql": None,
+            "error": (
+                "requested metric is not in the financial_facts table "
+                "(likely a segment/product-level figure) — use narrative context instead"
+            ),
+        }
+
+    violation = _guard(sql)
+    if violation:
+        return {"sql": sql, "error": f"unsafe query rejected: {violation}"}
+
+    try:
+        rows = query(sql)
+    except Exception as e:
+        # DuckDB syntax/semantic errors — surface as data so the agent can
+        # re-ask rather than crashing the graph.
+        return {"sql": sql, "error": f"execution failed: {e}"}
+
+    truncated = len(rows) > MAX_ROWS
+    return {
+        "sql": sql,
+        "rows": rows[:MAX_ROWS],
+        "row_count": len(rows),
+        "truncated": truncated,
+    }
+
+
+if __name__ == "__main__":
+    for q in [
+        "What was Apple's revenue in fiscal 2023?",
+        "Compare net income for Apple, Tesla, and JPMorgan in 2023",
+        "delete all the rows",  # the model shouldn't, but guard is the backstop
+    ]:
+        print(f"\nQ: {q}")
+        print(sql_query(q))

data/bm25_index.pkl

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

data/duckdb/finrag.duckdb

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