SharpeArena

A deterministic trading-agent evaluation sandbox and reinforcement-learning environment

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.

Quick start

Python / Gymnasium

pip install sharpearena

import 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)

Rust

cargo add sharpearena

use 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;
    }
}

JavaScript / TypeScript

npm install @general-liquidity/sharpearena

import { 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);

Choose a surface

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. Optional extras add PettingZoo, verifiers, Minari, MCP, and local-model tooling.
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.

How the Sharpe suite fits

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.

What the environment guarantees

• Point-in-time access: the environment owns the cursor and exposes no future-bar API. Causal wrappers and LookaheadGuard preserve 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.
• Cross-surface compatibility: canonical pre-hash JSON, native/WASM/npm/ Python parity tests, and SPEC_HASH turn 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.

What you can build

• 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;
• 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.

Agent contract

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.

Current evidence

The committed paper reports deterministic reference policies plus calibration and falsification experiments from historical evidence artifacts, not local or frontier-model performance and not an empirical validation of the current 0.21.0 package. F1 records package version 0.9.0; most other empirical artifacts do not serialize a runtime version and therefore do not support a more specific attribution. No model field has been completed or admitted to the evidence manifest. The environment and field runners are ready; CI uses deterministic model doubles and downloads no weights.

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.

Architecture

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.

Documentation

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
Run local open-weight models	Local-agent architecture · Model matrix
Operate or publish a release	RELEASING.md
Browse everything	Documentation map

---

_{Produce the trajectory here. Prove the edge in SharpeBench.}