batter

What batter is

Deterministic Python research engine behind Pancake's receipts. The math layer of usepancake.com, extracted as a standalone package so anyone can verify the formulas independently. batter takes a validated strategy spec, an EvidenceDataset, and a run config — and produces a canonical result envelope with a SHA-256ⓘ result hash identical across Ubuntu, macOS, and Windows on Python 3.12+.

Every Pancake receipt carries an engine_version field. That version points to this package. Any reader can reproduce the receipt by running batter at the stated version against the cited dataset and comparing hashes.

Install

Install from PyPI. The package ships as batter; the Python module is pancake_engine.

pip install batter

import pancake_engine

result = pancake_engine.run(spec=spec, dataset=evidence, config=config)
print(result.result_hash)   # SHA-256 hex — identical on every platform

Requires Python 3.12 or 3.13. Python 3.11 is permanently excluded — see py311-investigation for the technical rationale.

Role in the platform

When a Pancake receipt is computed, the pipeline runs in four stages:

1. Spec validation— the agent's strategy spec is canonicalized and hashed (spec_hash).
2. Tick evaluation — the spec is compiled to an IR, the EvidenceDataset rows are validated for structural invariants, and the position ledger is computed deterministically.
3. Metrics + bootstrap CIⓘ — batter computes all 12 formulas and the Monte Carlo bootstrap confidence interval using a PCG64ⓘ seeded RNG.
4. result_hash — a SHA-256ⓘ digest of the full output envelope. Same inputs → same hash on any platform.

The engine shim at lib/evidence-runner/ in the Pancake frontend calls batter over HTTP when PYTHON_ENGINE_URL is set; it falls back to the TypeScript runner for development. The TypeScript runner does not emit batter 0.4 CI fields — use the Python path for receipts with [CI: ...] values.

The 12 verified formulas

All 12 formulas were independently re-verified against published sources in the post-0.4.0 math audit (12/12 PASS). Reference implementations live in scripts/reverify/ in the pancake-production repo — each uses raw NumPy with no batter import, then asserts byte-equal or within published tolerance.

Determinism guarantees

Same (spec, dataset, config) → same result_hash across Ubuntu, macOS, and Windows on Python 3.12+. Determinism rests on canonical JSON serialization, a PCG64ⓘ seeded RNG, and Python 3.12+'s float accumulation semantics. Python 3.11 is permanently excluded: a C-level sum() precision change in CPython 3.12 (gh-100946) introduces a 1-ULP difference that propagates through bootstrap CIⓘ into a completely different SHA-256ⓘ hash. There is no userspace patch.

Cite batter

If you use batter in academic or independent research, please cite:

@software{mustopo2026batter,
  author       = {Mustopo, Michael},
  title        = {batter: Deterministic Python research engine for
                  prediction-market evidence-backed backtests},
  year         = {2026},
  version      = {0.4.2},
  url          = {https://usepancake.com/engine},
  repository   = {https://github.com/usepancake/batter},
  license      = {Apache-2.0},
  note         = {The math layer of usepancake.com. Produces canonical
                  SHA-256 result hashes reproducible across Ubuntu,
                  macOS, and Windows on Python 3.12+.}
}

Source & package

The engine is published under the Apache 2.0 license. The Methodology page documents the full verification boundary and math foundations in prose form.