Start a new research session from a natural-language goal. The engine runs the full Generation, Reflection, Elo tournament, Evolution and Meta-review loop in a detached process; this returns as soon as the session id exists. Poll session_status for progress. It runs for minutes to hours, so agree the scale with the user first: call estimate_cost.

Resume a paused or interrupted session. The engine reclaims expired task leases and continues where it stopped. Returns immediately; poll session_status.

Pause a running session. Workers drain and the loop sleeps until resumed.

Abort a session for good. The main loop exits at its next check.

List sessions newest first, with status, hypothesis count, top Elo and budget spent. Use this to find a session id the user refers to by topic.

Progress for one session: status, task counts by state, hypothesis counts by state, matches played, Elo spread, budget spent, and whether the final overview exists yet. This is the polling tool.

List a session's hypotheses ranked by Elo, with title, summary, state, matches played and dedup cluster. Bodies are omitted; use hypothesis_get.

One hypothesis in full: statement, detailed text, citations, Elo history, every review recorded against it, and its tournament matches. Read this before reviewing or ranking it.

Add a hypothesis to a session, in the same table Generation and Evolution write to. It enters as a draft, gets reviewed, and then competes in the tournament like any other. Set parent_ids when it derives from existing hypotheses, which is what makes it an Evolution result rather than a fresh idea. Recording is what makes a hypothesis real: an idea only described in chat is never reviewed, ranked, or seen by the meta-review.

Record a review against a hypothesis, in the same table and format the Reflection agent writes. Every factual claim in evidence needs a url and an excerpt you actually read. A 'full' review on a draft hypothesis also promotes it to reviewed. Do not report a review to the user without recording it first, or the tournament and meta-review will never see it.

Record the outcome of a head-to-head comparison between two hypotheses and apply the Elo update. Compare them on the paper's criteria (correctness, novelty, testability, and how well each survives its reviews) and give the rationale. Idempotent per (pair, round_id): recording the same pair twice under the same round moves no Elo.

Inject researcher feedback into a session. A running session picks it up on its next planning step; a paused one picks it up on resume. kind='pin' or 'rejection' with a target also moves that hypothesis's state.

The final research overview for a session: the meta-review synthesis of the ranked hypotheses. Only exists once the session has finalized.

Pre-flight size of a session under the current config: calls and tokens per agent, and how long it may run. On a metered API backend it also prices it. Run this before session_start and show the user.

Check the install: which LLM backend is configured, whether its credentials resolve, whether embeddings are real or the hash fallback, and where the database lives. Run this first when anything fails.