OpSafari / hypoarena

# hypoarena
`hypoarena` is a **fully offline** scientific hypothesis-discovery workbench.
It decomposes the **mechanism layer** of generate–debate–evolve "AI co-scientist"
pipelines into individually testable components: a citation-bearing
hypothesis/evidence graph, a synthetic literature factory, span-level grounding
verification, pluggable agent adapters, Bradley–Terry / Elo tournaments,
paraphrase deduplication (TF-IDF, MinHash LSH), hypothesis evolution operators,
and Bayesian evidence accumulation.
At runtime the package depends only on NumPy. PyTorch (CPU-only) is an optional
extra used solely to demonstrate a small trainable ranker. Every default test
and example runs without network access, without calling real models, and
without downloading weights.
## Installation
 [code] 
## Quick start
 [code] 
This runs the complete pipeline offline over a synthetic corpus, prints whether
each planted causal chain was recovered, and writes `report.md` / `report.html`.
It is a mechanism demonstration and makes no claim about real scientific
discovery capability. A typical run reports every planted link (e.g.
`planted links: 6 recovered: 6 rate: 1.0` on the demo corpus) and ends with an
explicit note that it is a synthetic demonstration only.
## Common commands
| Command | Purpose |
| --- | --- |
| `make build` | Build a wheel with the local venv (`--no-isolation`) |
| `make test` | Fast test suite (excludes the `slow` mark) |
| `make test-all` | Full suite (includes `slow` / `model` tests) |
| `make format` / `make format-check` | ruff formatting and its check mode |
| `make lint` | ruff check + format --check |
| `make typecheck` | mypy static analysis |
| `make demo` | End-to-end offline demonstration |
## CLI
The `hypoarena` command-line tool exposes one subcommand per pipeline stage, in
pipeline order: `corpus`, `generate`, `verify`, `dedup`, `debate`, `rank`,
`evolve`, `accumulate`, `report`, and `demo`. All of them run offline over
synthetic corpora. One-shot demonstration:
 [code] 
Subcommand options, shared arguments, and exit codes are documented in
docs/cli.md.
### What each stage does
- **corpus** — generate a deterministic synthetic literature with planted causal
 chains, competing hypotheses, paraphrase clusters, and controllable noise
 (distractors, contradictory findings); every corpus carries a provenance hash.
- **generate / debate / evolve** — run the generate–debate–evolve loop over the
 pluggable agent protocol (propose / critique / revise) with scripted, replay,
 or loopback-mock agents; evolution operators (scope narrowing, variable
 substitution, mechanism crossover, claim decomposition) preserve graph
 validity by construction.
- **verify** — span-level grounding checks: citation existence, entity overlap,
 polarity consistency, and numeric agreement, with graded flags for ungrounded
 or weakly grounded claims. Adversarial fixtures (fabricated citations,
 drifted numbers, negation flips) must be caught.
- **dedup** — normalize