Build and train through Rust or Python, run baselines and replay trajectories in Node, or connect an agent in any language through the JSON contract.
Quick start · Surfaces · How the suite fits · Guarantees · Documentation
SharpeArena owns the trajectory-producing half of the Sharpe suite. It gives an
agent a point-in-time Observation, validates the returned Decision, advances
one frozen market step, and records enough state to replay the result. The
sibling SharpeBench product
scores that trajectory for luck, significance, reliability, and process
discipline.
Important
SharpeArena makes future data unavailable at the environment boundary. It is
not a process sandbox. Run trusted local code here, or use SharpeBench's
digest-pinned --image path when an entrant needs container isolation.
pip install sharpearena gives you the Rust-backed engine plus Gymnasium, the
scalar and vector environment, and the registered difficulty IDs. It is one
route among several over the same engine; see
Choose an interface for PettingZoo, verifiers,
Minari, MCP, TorchRL, and the JSON agent contract.
pip install sharpearenaimport sharpearena
env = sharpearena.SharpeArenaEnv(n_symbols=4, n_days=120, seed=1)
observation, info = env.reset(seed=1)
observation, reward, terminated, truncated, info = env.step(
env.action_space.sample()
)Difficulty and held-out bands are also registered with Gymnasium:
import gymnasium
import sharpearena
env = gymnasium.make("SharpeArena/Hard-v1")
vector_env = gymnasium.make_vec("SharpeArena/Hard-v1", num_envs=8)Vector reset(seed=k) rebuilds lanes on consecutive seeds; a list selects each
lane directly. A positive max_episode_steps cap truncates executed steps using
the selected autoreset mode. See the Gymnasium guide for
literal eval seeds, reset semantics and reproducible run configuration.
cargo add sharpearenause sharpearena::{Agent, BuyAndHold, CostModel, Dataset, TradingEnv, Window};
let data = Dataset::synthetic(4, 120, 1);
let mut env = TradingEnv::new(
data,
Window { start: 20, end: 120 },
CostModel::default(),
7,
);
let mut agent = BuyAndHold;
let mut observation = env.reset();
loop {
let decision = agent.decide(&observation);
let step = env.step(decision);
observation = step.observation;
if step.done {
break;
}
}npm install @general-liquidity/sharpearenaimport { runBaseline } from "@general-liquidity/sharpearena";
const run = runBaseline({
agent: "momentum",
dataset: { synthetic: { n_symbols: 4, n_days: 120, seed: 1 } },
seed: 7,
});
console.log(run.returns.length, run.cost);| Surface | Install | Best for |
|---|---|---|
| Rust | cargo add sharpearena |
The deterministic environment, scenario generation, vector stepping, execution, market clearing, and governed wire contract. |
| Python | pip install sharpearena |
Gymnasium and the scalar/vector environment, plus optional extras for PettingZoo, verifiers, Minari, MCP, and local-model tooling. See Choose an interface. |
| npm | npm i @general-liquidity/sharpearena |
Named baselines, synthetic data, replay, stress suites, walk-forward windows, and regime tags under Node or Bun. |
| JSON contract | stdin/stdout or POST /decide |
The observation/decision protocol for an external runner; not a standalone Arena CLI. |
Package-specific usage lives beside each distribution: the Rust crate, Python package, and npm package.
The Python package is the surface above; underneath it, several interfaces sit
over the same engine, and Gymnasium is one of them, not the only one. Six are
optional extras (pip install "sharpearena[pettingzoo,verifiers,minari,mcp,sb3,torchrl]");
Ray/RLlib is a seventh, version-bounded extra installed separately
(pip install "sharpearena[ray]"). A short, runnable example for every row below
except Gymnasium (see Quick start) is in
the interface examples.
Each row's actual test coverage differs; none of them has been used to produce a reported benchmark result yet. The support status table states, per interface, what is contract-tested, what is only specified, and what is not supported (CleanRL) or ruled out (PufferLib, EnvPool), with the evidence for each. The HUD and Harbor routes are local feasibility work rather than supported integrations: each ran on one host with a deterministic agent and no model call, and each records what its evidence does not cover. Read the integration inventory for what exists and where, and the contract map for which module owns each contract clause.
Every interface above with an upstream project of its own carries that project's
logo. The three without one, the JSON contract, the SharpeBench bridge and the
functional view, have no third party behind them to credit. A logo says who
built the thing this package talks to, and nothing about how far that route is
supported here, which the column beside it and the support-status table state in
words. docs/assets/logos/ records where each file came
from and what governs its use. Each project is its own trademark holder, and
none of them endorses this one.
agent (any language)
│ Observation → Decision
▼
SharpeArena
point-in-time scenario · execution · process trace · effective config
│ validated, append-only field artifact
▼
SharpeBench
deflation · pass^k · significance · process/mandate gates · attestation
The relationship is directed, not cyclic. SharpeArena uses the small published
SharpeBench protocol, simulator, and scoring crates so both products share one
execution model. SharpeBench does not depend on the full SharpeArena package.
sharpearena-compile-bench refuses incomplete grids, failed cells, coordinate
collisions, conflicting completions, and invalid return hashes before producing
ordinary SharpeBench submissions. Its companion manifest preserves validated
per-request latency, token, reasoning-token, and retry summaries as a
rank-neutral operational profile. Those diagnostics describe how a field ran;
they cannot change a SharpeBench score or eligibility verdict.
- Point-in-time access: the environment owns the cursor and exposes no
future-bar API. Causal wrappers and
LookaheadGuardpreserve that boundary. - Failure is not a hold on checked field paths: malformed output, transport loss, timeouts, and invalid symbols become typed failed cells rather than scoreable empty decisions. Low-level unchecked backtests remain available for compatibility and do not make that guarantee.
- Replay from decisions: returns and score inputs are recomputed from recorded decisions and frozen inputs rather than trusted from an agent. Step labels and observation IDs are evidence metadata, not replay inputs.
- Known arm identity: evidence producers compare requested configuration with values read back from the environment that consumed it.
- Operational accounting without rank leakage: local-field evidence records
every model-call duration and its observation source; bridge manifests report
nearest-rank p50/p95 latency, token totals, reasoning-token availability, and
retries with
rank_input: false. - Cross-surface compatibility: canonical pre-hash JSON, native/WASM/npm/
Python parity tests, and
SPEC_HASHturn wrapper/engine drift into a refusal. - Closed inputs: schemas, typed boundary errors, unknown-field rejection, and path-containment checks prevent ambiguous caller input.
- Reproducible releases: provenance binds source and evidence; package smoke tests install the built wheel and npm tarball outside the repository.
Read the precise scopes and non-claims in Integrity and security.
- single-agent and vectorized point-in-time environments;
- Gymnasium, PettingZoo, RLVR/
verifiers, and offline-RL workflows; - portfolio, execution, market-making, shared-impact, and limit-order-book tasks;
- procedural, held-out, sealed-seed, real-data, and regime-transfer evaluations;
- deterministic local-model fields with resumable journals and strict faults;
- append-only prospective forecasts with frozen settlement contracts and raw evidence export;
- host-counted strategy-search trials with a closed, non-executable DSL;
- a separate paper-only forward arm with deny-first risk checks and persistent reconciliation state.
The complete, current inventory is in the capability map.
An agent receives point-in-time market state and returns target-weight orders:
{
"date": "2025-01-02",
"cash": 1.0,
"symbols": [
{ "symbol": "AAPL", "close_history": [187.2, 188.0, 190.4] }
],
"portfolio": []
}{
"orders": [
{ "symbol": "AAPL", "action": "buy", "target_weight": 0.5 }
]
}CONTRACT_VERSION governs additive wire evolution; JSON Schemas and
bidirectional conformance tests guard the Rust types. See the
agent contract guide,
contract directory, and
governance rules.
The committed paper separates two evidence strata. Historical calibration and falsification experiments use deterministic reference policies; F1 records package version 0.9.0, while most other historical artifacts do not serialize a runtime version. A later, now-superseded engineering pilot sealed three already-cached local model snapshots before 24 Binance Spot candle outcomes existed, then resolved all contracts on exact common support. It validates the protocol plumbing only. Its older convenience-sample checkpoints are excluded from the paper's model evidence and from any benchmark or comparative claim. Forecast quality cannot change trading rank. No model weights are part of the repository or downloaded by CI.
Results, non-results, and finite-grid limits are summarized in
Evidence and current status. Exact commands, fixed seeds,
JSON artifacts, figures, and provenance live under paper/.
Note
“Leak-free” describes the point-in-time information boundary. It does not claim Docker/microVM containment, protection from a malicious kernel-level entrant, or a hosted multi-tenant service.
The determinism-critical path is Rust and forbids unsafe. Python and
TypeScript adapt the same engine to their ecosystems rather than reimplementing
the market model.
sharpebench-protocol + sharpebench-sim + sharpebench-core
│
sharpearena (Rust)
/ | \
WASM / npm pyo3 / Python Rust API
See Architecture for package ownership, compatibility, effective configuration, and release topology.
| I want to… | Read |
|---|---|
| Understand the package and trust boundaries | Architecture · Integrity and security |
| See the full feature inventory | Capability map |
| Interpret the current results honestly | Evidence and current status · EVALUATION.md |
| Train an agent | Gymnasium guide · Training guide |
| Connect an external agent | Agent contract |
| Check what's tested, specified, or ruled out per interface | Support status |
| Commit and export prospective forecasts | Prospective forecast evidence |
| Run local open-weight models | Local-agent architecture · Model matrix |
| Operate or publish a release | RELEASING.md |
| Browse everything | Documentation map |

