About this handbook
Supercast is a library for building forecasting agents that produce explicit probabilities, preserve their evidence and revisions, and learn from resolved outcomes. It supplies numerical methods and enforceable record contracts. The agent using it supplies domain knowledge, verified sources, model calls, and the judgment that connects observations to assumptions.
The handbook follows a forecast from question design to evaluation. You can read it in order or follow a narrower path:
| Your task | Start here |
|---|---|
| Produce a first binary forecast | A first forecast |
| Assess a proposed forecasting question | Question design |
| Update a probability from new evidence | Bayesian updates |
| Combine forecasters | Panels, then aggregation |
| Evaluate a track record | Scoring, calibration, validation |
| Choose which evidence to obtain | Indicators and decisions |
The companion Engineering Reference covers installation, Rust types, the JSON protocol, every operation, SQLite, errors, and release procedures. Both books are built into the local release and work without an external documentation service.
What a primitive can guarantee
A probability value can reject NaN or a number greater than one. A journal can reject a revision that cites the wrong predecessor. A bootstrap can keep observations from the same event cluster together. Those are properties of the software and its supplied inputs.
A primitive cannot prove that two articles have independent information, a reference class transfers to the present case, or a likelihood was honestly elicited. The handbook separates these modeling obligations from the computations so the agent can report both.
Supercast follows the thirteen method areas in the Superforecasting Skills Pack: question design, reference classes, decomposition, Bayesian updates, counterevidence, conditional indicators, elicitation, aggregation, update ledgers, scoring, calibration, validation, and the integrated workflow. Its software tests do not establish elite forecasting ability; that requires a prospective, appropriately controlled record.
Conventions used throughout
Probabilities are numbers between zero and one, not percentages. Timestamps are UTC Unix seconds. Binary Brier uses the one-component convention on a zero-to-one scale. Logarithms are natural logs; information gain is in nats. Examples involving product launches are synthetic and make no claim about real release outcomes.
Rust examples are compiled and run by the documentation gate. The JSON reference examples are executed against the actual command-line process. Both kinds of examples are maintained with the source code.