Metadata-Version: 2.4
Name: pretium
Version: 0.4.2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering
Requires-Dist: pyarrow>=14 ; extra == 'arrow'
Requires-Dist: anthropic>=0.40 ; extra == 'claude'
Requires-Dist: pydantic>=2 ; extra == 'claude'
Requires-Dist: mcp>=2.0 ; extra == 'mcp'
Requires-Dist: numpy>=1.24 ; extra == 'rl'
Requires-Dist: gymnasium>=0.29 ; extra == 'rl'
Provides-Extra: arrow
Provides-Extra: claude
Provides-Extra: mcp
Provides-Extra: rl
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
License-File: NOTICE
Summary: Deterministic market simulation with a real limit order book.
Keywords: simulation,finance,market,orderbook,deterministic,backtesting
Home-Page: https://simoncoombes.github.io/pretium
Author: Simon Coombes
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/simoncoombes/pretium/releases
Project-URL: Documentation, https://simoncoombes.github.io/pretium
Project-URL: Homepage, https://simoncoombes.github.io/pretium
Project-URL: Repository, https://github.com/simoncoombes/pretium

# pretium

[![determinism](https://github.com/simoncoombes/pretium/actions/workflows/determinism.yml/badge.svg)](https://github.com/simoncoombes/pretium/actions/workflows/determinism.yml)
[![licence: MIT OR Apache-2.0](https://img.shields.io/badge/licence-MIT%20OR%20Apache--2.0-blue.svg)](#licence)
[![python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

A market simulator you can run a strategy against. Rust core, Python API.

Give it a seed and a list of companies. It runs a market forward: prices, a
limit order book, fills, and an economy that moves each day. Your orders match
against real depth, so your trades move the price.

Real market data cannot tell you what happens if you trade differently, or what
caused a move. This can, because it computed every price.

## Install

```
pip install pretium
```

Wheels for Linux, macOS and Windows on CPython 3.11+. No dependencies. The same
engine is a Rust crate: `cargo add pretium`.

The API can still change before 1.0. A published result cannot: new
coefficients ship as a new preset, so a run you cited last month replays this
month.

## First run

```python
import pretium as pt

universe = pt.Universe.random(40, seed=111)

spec = pt.StrategySpec.momentum(lookback_days=1.0, top_k=5)
scores = pt.evaluate({"mine": spec}, seed=7, universe=universe, days=10)

scores["mine"].return_pct            # what it made
scores["mine"].impact_bps            # what its own footprint cost
scores["mine"].strategy_fingerprint  # sha256, cite this
```

That is one market draw. It tells you as much about the seed as about the
strategy. `pt.rank` runs many seeds and compares them with a paired sign test.

## What you get

| | |
|---|---|
| `engine.truth()` | why each price moved: nine factors that sum to the move, to 1e-16 |
| counterfactual TCA | the same seed with your orders and without them |
| `pt.rank` | many seeds, paired sign tests |
| `RunManifest` | version, preset, seed, universe, macro, scenario. `reproduce()` stops on a mismatch |
| MCP server | eleven read-only tools for a coding agent |
| more | a Gymnasium environment, Arrow output, checkpoints, SEC EDGAR data, a browser build |

No historical dataset carries the labels `truth()` gives you. Real data shows
you that a stock fell. It never shows you that 60% of the fall was order flow.

To drive it from an agent:

```
pip install "pretium[mcp]"
claude mcp add pretium -- pretium-mcp
```

Strategies, universes and scenarios are data, so a tool argument cannot reach
code. Each result carries its own caveats. See
[the MCP page](https://simoncoombes.github.io/pretium/mcp.html).

## How real it is

`pt.facts.measure()` scores fourteen statistics against real-market bands. The
default preset, `pt-v14`, holds all fourteen at one year and at two years. It
holds all fourteen on a roster it never saw, and thirteen on new seeds.

Five of the fourteen were calibration targets, and the bands both tuned the
model and graded it. So this is a stated envelope, not a test against market
data that was held back.

Five limits are measured and written down:

| limit | what it means |
|---|---|
| horizon | one year is certified. Two and five years are measured, not certified |
| volatility memory | it decays too fast |
| scenario size | the response has the right sign, but one run cannot size it |
| macro crises | an inflation crisis or a policy crisis needs a scenario to drive it |
| roster | certification used a sector-balanced roster, which no real index is |

`pt.envelope.check()` refuses a question that falls outside a limit, and
[the realism envelope](https://simoncoombes.github.io/pretium/realism-envelope.html) says
what each one forbids.

Good results here do not predict real returns. The prices come from a known
model, so a strategy shaped like that model looks excellent and teaches you
nothing. A strategy that fails here tells you more. There is one venue, no
latency, and no counterparty that adapts to you.

## Same seed, same market

Each release builds five targets, runs one fixed simulation in each, and
compares digests. A disagreement stops the release. The crate ships its own
`exp`, `log`, `sin` and `cos`, so the platform libm cannot change a result.

`pt-v14` became the default on 2026-08-28. Name your preset and your run
replays exactly. Every preset from `pt-v1` on is still selectable.

```python
eng = pt.Engine(seed=42, universe=u, model="pt-v10")
```

## Examples

Ten [`examples/`](https://github.com/simoncoombes/pretium/tree/main/examples) in reading order, run by the test suite:

| | |
|---|---|
| [`00-a-year-in-one-market`](https://github.com/simoncoombes/pretium/blob/main/examples/00-a-year-in-one-market.ipynb) | Start here: one company, one year, two crises, one chart |
| [`01-first-simulation`](https://github.com/simoncoombes/pretium/blob/main/examples/01-first-simulation.ipynb) | Universe, engine, order book, determinism |
| [`02-evaluating-a-strategy`](https://github.com/simoncoombes/pretium/blob/main/examples/02-evaluating-a-strategy.ipynb) | Specs, baselines, ranking across seeds |
| [`03-why-did-the-price-move`](https://github.com/simoncoombes/pretium/blob/main/examples/03-why-did-the-price-move.ipynb) | The nine factors that sum to every move |
| [`04-how-realistic-is-this`](https://github.com/simoncoombes/pretium/blob/main/examples/04-how-realistic-is-this.ipynb) | The realism panel and the limits |
| [`05-training-an-agent`](https://github.com/simoncoombes/pretium/blob/main/examples/05-training-an-agent.ipynb) | The Gymnasium environment, and what size costs |
| [`06-execution-and-impact`](https://github.com/simoncoombes/pretium/blob/main/examples/06-execution-and-impact.ipynb) | TCA and the counterfactual run |
| [`07-research-workflow.py`](https://github.com/simoncoombes/pretium/blob/main/examples/07-research-workflow.py) | A whole study in one file. It runs in about five seconds |
| [`08-claude-agent.py`](https://github.com/simoncoombes/pretium/blob/main/examples/08-claude-agent.py) | An LLM agent trading the market through the harness |
| [`09-a-pandemic-shaped-market`](https://github.com/simoncoombes/pretium/blob/main/examples/09-a-pandemic-shaped-market.ipynb) | A real 2020-21 macro path, and which fields transmit |

## More

Full docs: [**simoncoombes.github.io/pretium**](https://simoncoombes.github.io/pretium/).

To contribute, see [CONTRIBUTING.md](https://github.com/simoncoombes/pretium/blob/main/CONTRIBUTING.md) and [RELEASING.md](https://github.com/simoncoombes/pretium/blob/main/RELEASING.md). One rule shapes the
rest: a change to the simulated trajectory is a breaking change, whatever its
size.

To cite the software, see [CITATION.cff](https://github.com/simoncoombes/pretium/blob/main/CITATION.cff). To cite a result, use its
`RunManifest`.

Licence: MIT OR Apache-2.0, at your option. See [LICENSE-MIT](https://github.com/simoncoombes/pretium/blob/main/LICENSE-MIT) and [LICENSE-APACHE](https://github.com/simoncoombes/pretium/blob/main/LICENSE-APACHE).

