SEA2

Retrieval-first agentic research with the full reliability stack: schema-enforced extract-then-verify, tiered verification (Tier 0–3), provenance DAG, conformal abstention. Clean rebuild of SEA committed to these reliability commitments from day one.

Status: Production-default since 2026-05-20 after winning the pre-registered au-token A/B vs SEA. SEA enters maintenance. See HANDOFF.md for the current state, open work, and full architecture pointers.

What this repo holds

The system — src/sea2/, tests/, scripts/, methodology docs in docs/. Per-project research outputs (final summaries, scorecards, operator ratings, project-specific corpora) live locally and are gitignored; see .gitignore.

Quick start

Prerequisites: Python 3.12, uv, Claude Code (for the producer/extract path), optionally a Google API key (for Tier 2 cross-family verifier).

git clone https://github.com/Loodt/sea2.git
cd sea2
uv sync --extra dev --extra gemini   # dev tools + Gemini Tier 2 backend

Create a .env in the repo root (already gitignored):

GOOGLE_API_KEY=<your-google-ai-studio-key>
# Optional dispatch defaults:
SEA2_TIER2_ENABLED=1
SEA2_TIER2_BACKEND=gemini

.env is auto-loaded by python-dotenv on import sea2, so scripts and tests pick it up without any extra plumbing. A real shell env var overrides the .env value.

Run the tests:

uv run pytest

Architecture in one screen

See CLAUDE.md for the architectural commitments (non-negotiable). The headline:

• Retrieval-first. Extract sees only chunks the retrieve stage admitted; never the open web.
• Schema-enforced. Pydantic validates every Finding at extraction; failures are events, not silent skips.
• Tiered verification.
  • Tier 0 — deterministic (URL resolves, DOI/arXiv, quote-supported, ledger consistency).
  • Tier 1 — local NLI entailment (optional, flagged).
  • Tier 2 — isolated cross-family LLM verifier on a 30% sample. Default backend swappable via SEA2_TIER2_BACKEND (anthropic or gemini).
  • Tier 3 — adversarial (trigger-gated).
• Provenance DAG. derivation.premises is a typed graph; cycles and orphans rejected at integrate.
• Code-enforced or nonexistent. No prompt-only mandates. Behavioral rules live in code.
• Fail loudly. No silent catch blocks. Lint enforces.
• One canonical counter. Metrics computed from the store on demand.

Where LLMs are used

Site	Default	Token volume
Extract (producer)	Claude Code CLI (subscription billing)	bulk of run
Tier 2 verifier	Gemini 2.5 Flash via google-genai (API tokens, cross-family)	small (~120 audits at 30% sample)
Tier 1 NLI	local transformers	$0
WebSearch retrieve	Claude Code's WebSearch	n/a

Tier 2 provider is generic — src/sea2/verification/tier2.py exposes _LLMTextClient, a 1-method protocol any new provider can implement in ~30 lines.

Documentation map

• CLAUDE.md — architectural commitments (non-negotiable).
• HANDOFF.md — current state, what's been built, open work, resume checklist.
• docs/sea-postmortem.md — audit of SEA components informing SEA2's port/re-derive/drop calls.
• docs/comparison-protocol.md — pre-registered 12-metric A/B comparison protocol (locked at 55f9498).
• docs/article-alignment-audit.md — alignment with the reliability spec.
• docs/anti-patterns.md — patterns SEA2 explicitly avoids.

Comparison verdict (au-token, 2026-05-20)

SEA2 won ≥7/12 metrics including operator confidence (M11). Per docs/comparison-protocol.md §3, SEA2 supersedes; SEA enters maintenance. The per-metric scorecard is a research output and lives locally only — see HANDOFF.md.