refactor: extract citation pipeline from api deps into src/citations

[KostasCherv]

Motivation

Provenance/citation selection is a signature explainability feature of chat answers, yet it lived as ~350 lines of underscore-private functions inside src/api/deps.py — a dependency-injection/shared-helpers module. Worse, src/evals/regression_gate.py cross-imported the underscore-private _select_chat_citations, coupling the eval gate to a private symbol of a DI module. This PR gives the pipeline its own module with a public API.

What moved

New module src/citations.py (pure code motion — function bodies unchanged, leading underscores dropped):

• build_rag_citations, filter_relevant_rag_chunks
• build_web_citations, build_workspace_fallback_citations
• build_wikipedia_citations, build_open_library_citations, build_arxiv_tool_citations
• merge_citations, iter_nested_dicts, normalize_tool_result
• has_tool_or_web_citations, select_chat_citations, build_tool_citations
• _TOOL_SOURCE_TYPES constant

All call sites updated to the public names (no backwards-compat aliases needed): src/evals/regression_gate.py, src/api/routers/sessions.py, src/api/routers/rag_chat.py, src/api/routers/rag_agents.py, tests/test_citations.py.

What stayed in deps.py

Request models, billing/quota helpers, RAG validation error mapping, and the agent tool-calling loop (_run_agent_loop, AgentLoopResult, _invoke_tool_raw_result, _generate_suggestions, stream/trace helpers). The agent loop now imports build_tool_citations / merge_citations / normalize_tool_result from src.citations.

Follow-ups

• Move _run_agent_loop and its helpers to src/api/agent_loop.py. Not done here because ~40 test sites patch src.api.routers.*._run_agent_loop; moving it cleanly means renaming the import in four routers plus all patch targets — a mechanical but noisy change better done alone.
• Split src/db/supabase_store.py and src/rag.py — both are oversized and are candidates for the same treatment.

Verification

• uv run ruff check src tests — All checks passed
• uv run mypy src — Success: no issues found in 70 source files
• uv run python -m pytest tests/ -q — 575 passed
• uv run python -m src.evals.regression_gate — 20/20 (100%)

Zero behavior change intended; diff is 381 insertions / 378 deletions, all code motion + renames.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cortex	Ready	Preview, Comment	Jul 14, 2026 2:28pm