Spec A: TheoremSearch backend for the librarian + mathematics as 9th default field

[jeremymanning]

Parent: #111. Type: spec-005 amendment (not a new spec dir — Q1 anticipated backend expansion).

Goal

Add TheoremSearch as a third candidate-source backend to the librarian agent (alongside Semantic Scholar + arXiv), and add mathematics as the 9th default field so llmXive can do math-theory projects. Output contract unchanged — TheoremSearch Candidates flow through the existing verify chain (URL resolves → title-overlap ≥0.7 → summary-grounded ≥0.5 → LLM relevance judge).

Scope (in)

1. mathematics as the 9th default field. Add to the librarian's DEFAULT_FIELDS (tests/phase2/test_librarian_cross_domain.py), the brainstorm agent's field enum, and any field-list constant. Brainstorm 5 seed math projects so the cross-domain test has math projects to run against (per maintainer answer Quantum Cognition in LLMs: Superposition States for Ambiguous Reasoning #3 on integrate theoremsearch #111).
2. src/llmxive/librarian/theoremsearch.py — TheoremSearchClient.search(term, *, limit=10) -> list[Candidate]:
   • POST https://api.theoremsearch.com/search with {query: term, limit: ...}
   • For each result where paper.source == "arXiv": extract paper.paper_id, strip the v\d+ suffix, call the librarian's existing ArxivClient.get_by_id(arxiv_id) for the full record, emit Candidate(backend=\"theoremsearch\", primary_pointer=arxiv_id, claimed_title=..., claimed_authors=..., claimed_year=..., claimed_venue=\"arXiv\", claimed_abstract=...).
   • Skip non-arXiv sources (ProofWiki, Stacks Project — no DOI/arXiv ID; reserved for Spec B per maintainer answer The Binding Problem in LLMs: Implementing Synchronized Oscillations for Feature Integration #4).
   • Token-bucket rate limiter (~1 req/2s, same pattern as ArxivClient).
   • Errors → TransientBackendError so the router falls through to SS+arXiv; the librarian never depends on TheoremSearch being up.
3. LLM math-classifier (src/llmxive/librarian/math_classifier.py or folded into query_extractor.py) — is_math_theory_question(term, idea_body_excerpt, *, model, ...) -> bool via a single LLM call ("Is this a pure-mathematics question about theorems, proofs, or formal mathematical structures? yes/no"). Fail-open to False. Cache the verdict per-project (per maintainer answer Neural Narrative Networks: Brain-Inspired Story Generation and Comprehension #2) — keyed by (project_id or question_hash, prompt_version) so re-runs are stable.
4. Wire into LibrarianAgent.invoke(), after the existing extracted-query searches:

   if field == \"mathematics\":
       candidates += TheoremSearchClient().search(term)        # always
   elif _is_math_theory_question(term, idea_body_excerpt):     # cached LLM classifier
       candidates += TheoremSearchClient().search(term)
   

   Thread new candidates into the existing merge → verify → judge chain (no chain changes — TheoremSearch Candidates carry arXiv IDs the verify chain already handles; merge_candidates dedups by primary_pointer).
5. Bump librarian prompt_version (the classifier is a new LLM call) → cache-invalidating; re-run cross-domain + PROJ-261/262 re-validation.
6. Tests: tests/phase2/test_theoremsearch.py (parser tests on recorded /search response — arXiv vs ProofWiki branching; real-API smoke gated on network; Candidate mapping; dedup), tests/phase2/test_math_classifier.py (parser + real-LLM smoke: math question → True, non-math → False), add a mathematics parametrization to test_librarian_cross_domain.py.
7. Docs: update agents/registry.yaml librarian entry comment (3 backends + math classifier), the diagnostic (notes/2026-05-07-spec-005-librarian-diagnostic.md), and specs/005-librarian-agent/spec.md Q1 clarification (it anticipated "future spec may expand the backend list" — this is that amendment).

Scope (out — deferred to Spec B, see #114)

• Theorem-statement artifacts (## Related theorems idea.md subsection)
• Non-arXiv TheoremSearch sources (ProofWiki, Stacks Project)
• The theorem_searcher agent itself

Verified API facts (from live probing — see #111)

• POST /search → {theorems: [{theorem_id, name, body, slogan, theorem_type, link, paper: {paper_id, source, title, authors, link, summary, journal_ref, primary_category, categories, citations, year, journal_published}, similarity, score, has_metadata}]}
• arXiv-sourced: paper.paper_id = versioned arXiv ID (1306.5434v2), paper.link = http://arxiv.org/abs/<id>, paper.year present, paper.source == \"arXiv\"
• No auth, no documented rate limits. OpenAPI at https://api.theoremsearch.com/openapi.json. MCP server at /mcp.
• Stability caveat: small academic project (uw-math-ai/TheoremSearch, 8 stars, no license, no SLA) — mitigated by the fall-through-to-SS+arXiv design.

Acceptance

• The librarian, invoked with field=\"mathematics\" on a real math arXiv question, returns ≥1 verified citation that came via the TheoremSearch backend (visible in verification_log / Candidate.backend).
• A non-math-field question that the classifier flags as math-theory also triggers the TheoremSearch path; a clearly-non-math question does not.
• Cross-domain test passes for all 9 fields (or skips mathematics cleanly if no math project is brainstormed yet — same pattern as the existing "no brainstormed projects found" skip).
• PROJ-261 + PROJ-262 re-validate verified under the new librarian version (no regression on non-math projects).
• All Phase 2 tests pass; ruff clean.

Constitution note

Per Principle I (single source of truth): TheoremSearch is a backend, not a competing agent. The librarian remains the single entry point and single verifier for literature search.

🤖 Generated with Claude Code

[jeremymanning]

✅ Spec 006 implemented — PR #117 (008-theoremsearch-backend → main).

All 40 tasks done; SC-A01..A09 all PASS under librarian v1.6.0.

Shipped:

• src/llmxive/librarian/theoremsearch.py — TheoremSearchClient (3rd backend): POSTs /search, resolves arXiv-sourced hits via the existing ArxivClient.get_by_id, re-tags backend="theoremsearch"; skips non-arXiv sources (ProofWiki/Stacks → deferred to Spec B: theorem_searcher agent — theorem-statement artifacts for math-theory projects #114); ~1 req/2s rate limit; errors → TransientBackendError so the librarian falls through to SS+arXiv (never depends on TheoremSearch being up).
• src/llmxive/librarian/math_classifier.py + agents/prompts/math_classifier.md — one LLM call gating TheoremSearch on non-{mathematics, statistics} fields; fail-open to false with a loud stderr diagnostic; per-project verdict cache keyed (project_id, librarian_prompt_version).
• LibrarianAgent.invoke() — project_id param; queries TheoremSearch unconditionally for field ∈ {mathematics, statistics} else gated by the classifier; threads hits into the unchanged merge → verify → judge chain; math_classifier audit object {invoked, verdict, error} in the result JSON; VerificationLog.backend field so TheoremSearch-sourced citations are identifiable.
• mathematics as the 9th default field (DEFAULT_FIELDS + cli.py default_fields + brainstorm prompt) + 5 seed math projects (PROJ-548..552).
• librarian prompt_version 1.5.0 → 1.6.0 (cache-invalidating).
• New tests: test_theoremsearch.py, test_math_classifier.py; test_librarian_cross_domain.py now 9 fields + math_classifier assertions.

Verification (under v1.6.0):

• Affected-test run: 59 passed, 1 skipped (real-LLM smoke needs LLMXIVE_REAL_TESTS=1).
• Full Phase 2 regression: 153 passed, 1 failed (transient arXiv 429 under suite load — passes in 6s in isolation), 1 skipped. ruff clean.
• 9-field cross-domain re-run (cache wiped): 9/9 PASS in 1:43:40. mathematics (PROJ-552): 14 verified, 6 from TheoremSearch (on-topic knot/braid-index theorem papers, resolving arXiv IDs), math_classifier={invoked:false}, zero ProofWiki/Stacks entries. The 8 pre-existing fields: no regression; classifier consulted, correctly says non-math, no errors.
• PROJ-261 + PROJ-262 re-validation under v1.6.0: both verified (validator validated, constitutions byte-unchanged) — specs/006-theoremsearch-backend/revalidation-results-v1.6.0.yaml.
• Diagnostic: notes/2026-05-07-spec-005-librarian-diagnostic.md (spec-006 amendment section).

Deferred: #114 (Spec B — theorem-statement artifacts, non-arXiv sources, standalone theorem_searcher agent), #116 (consolidate the duplicated default-field list).