Crate openoutcry 

OpenOutcry — the trading-agent environment

A leak-free, point-in-time market environment with a dead-simple, language-agnostic agent contract: the harness sends an MarketObservation, the agent returns a Decision, repeat. Look-ahead is structurally impossible — Dataset never hands out a future bar — and trajectories are recompute-from-raw-decisions, so an agent cannot lie about its returns.

M0 — extraction scaffold

This crate currently re-exports the point-in-time simulator that already lives in sharpebench-sim, promoting it from “the benchmark’s internal engine” to a standalone environment whose public reason to exist is “run an agent in a market.” The Gym-style reset/step lifecycle, the frozen CONTRACT_VERSION, the WASM/npm + Python surfaces, and the ecosystem wiring land in later milestones (see specs/SPEC-trading-agent-env.md). v0.1 depends on sharpebench-sim; the gl-sim-core extraction is a follow-up refactor, not a blocker.

Re-exports

pub use contract::CONTRACT_VERSION;

pub use scenario_gen::generate_scenario;

pub use scenario_gen::level_seed;

pub use scenario_gen::train_test_split;

pub use scenario_gen::DistributionMode;

pub use scenario_gen::ScenarioSpec;

pub use vec_env::BatchStep;

pub use vec_env::LaneConfig;

pub use vec_env::VecTradingEnv;

pub use mandate::mandate_breach;

pub use mandate::sample_mandate;

pub use mandate::Mandate;

pub use mandate::MandateStyle;

pub use exec_noise::perturb as perturb_action;

pub use exec_noise::ExecNoise;

pub use lob_market::Fill;

pub use lob_market::LadderSnapshot;

pub use lob_market::OrderBook;

pub use lob_market::OrderKind;

pub use lob_market::RestingOrder;

pub use lob_market::Side;

pub use market::clear_bar;

pub use market::AgentFill;

pub use market::ClearResult;

pub use market::MarketClearing;

pub use market::MarketParams;

Modules

contract

The frozen wire contract version.

exec_noise

Execution-noise perturbation — the determinism-sensitive core of the trading analog of ALE sticky actions, moved down from the Python ExecutionNoiseWrapper.

lob_market

Deterministic continuous-double-auction limit-order book (M3) — price-time priority.

mandate

Per-scenario trading mandates — MiniGrid’s Mission pattern for trading.

market

Endogenous price-impact shared-book market (M2) — the flagship multi-agent engine.

scenario_gen

Seeded procedural scenario generation — Procgen’s (start_level, num_levels) integer-seed-interval model, ported to the trading environment.

vec_env

Vectorized, batched environment — gym3’s “vectorized-first” design ported to the trading env. A VecTradingEnv holds B independent TradingEnv lanes (each a distinct seed/scenario/window) and steps them as a batch.

Structs

AgentTrajectory

An agent’s full captured trajectory: every (window × seed) run’s raw decisions. Serde-(de)serializable to JSON; this is the on-disk artifact a separate verifier ingests to recompute the score from raw decisions alone.

BuyAndHold

Equal-weight buy-and-hold across all symbols — the baseline every agent must beat.

CostModel

Basis-point transaction cost model.

Dataset

A point-in-time price dataset.

Decision

What the agent returns.

DecisionStep

One captured decision step of a single backtest run: the agent’s raw output at one point-in-time observation. This is the persisted artifact — it holds the agent’s Decision (orders, sizing, conviction, reasoning) tagged with the observation it was made against, and deliberately stores no returns, NAV, or any self-reported metric. The score is recomputed by replaying these decisions through the engine, never read from the agent’s word.

EnvState

An O(1), serializable snapshot of a TradingEnv’s mutable state — the time cursor plus the full [Book] (holdings, cash, RNG cursor, decision trace, prior NAV). Everything an env needs to resume an exact trajectory; the immutable config (frozen data, window, costs, seed) lives in the env and is not copied.

ExternalAgent

Drives an external agent subprocess over newline-delimited JSON.

HoldAgent

The do-nothing agent: always holds (empty orders). A trivial baseline, and the graceful fallback when an external agent process can’t be spawned mid-run — consistent with how the external transports already degrade to a hold on error.

HttpAgent

Drives an external agent over HTTP/1.1 — one request/response per decision.

MarketObservation

What the agent sees at one decision point.

Momentum

Cross-sectional momentum: equal-weight the symbols with positive trailing return.

Order

A single per-instrument instruction.

PositionState

The agent’s current holding in one instrument.

RandomAgent

A coin-flip “monkey”: a fully-invested, long-only portfolio with random weights each step. Seeded so it is reproducible. Run many of these to draw the luck floor — the distribution of outcomes from zero skill that a genuine agent must clear to be rank-eligible.

Run

One seed×window run of an agent: its per-period returns plus the decision trace and (optionally) per-decision confidences/outcomes.

RunTrajectory

One captured backtest run (a single window × seed): the ordered sequence of the agent’s raw decision steps, plus the (window, seed) coordinates needed to replay it through the identical point-in-time engine path.

Scenario

A named bundle of a dataset, the windows to evaluate over it, and the cost model — so “run my agent through the crisis suite under worst-case execution” is one object rather than three loose arguments.

StepInfo

Per-step side channel: the post-step NAV and the process events generated during the step (fills, sim-exploitation guards, captured rationale).

StepResult

The result of one environment step: the next point-in-time observation, this step’s portfolio return (the reward), whether the window is exhausted, and the per-step side channel.

SymbolSnapshot

Point-in-time data for one instrument.

TeamAgent

A trading team: several member agents whose target weights are averaged into one consensus decision (a symbol only one member likes is down-weighted by the whole team’s size). Modelled on the TradingAgents multi-agent firm — the team is scored as a unit while [sharpebench_core::attribute_roles] estimates each member’s load on the team outcome.

TradingEnv

A steppable, leak-free trading environment over a frozen dataset. The caller drives it: reset returns the first observation, then each step applies the supplied decision and advances one bar.

Window

A simulation window over the dataset’s date axis: steps [start, end).

Enums

Action

Discrete action label (sizing is carried by target_weight).

CostProfile

Execution-robustness profile: a named bundle of a CostModel plus a logical decision-to-fill delay (how many sim-bars an order waits before it becomes eligible to fill). Lets “score this agent under worst-case execution” be a single swappable axis rather than hand-tuned cost fields scattered per test.

Regime

Coarse market regime over a window.

Traits

Agent

Something that turns a point-in-time observation into trading orders.

Functions

replay_run

Replay one captured run’s raw decisions through the identical point-in-time engine to regenerate its Run. The frozen data and costs must match those the trajectory was captured against; the window and seed come from the artifact.

replay_submission

Replay a whole AgentTrajectory back into the sharpebench_core::AgentSubmission the scoring kernel consumes — recomputing every Run from raw decisions alone. This is the engine half of the separate-verifier path: the resulting submission is derived only from the persisted decisions + the frozen dataset, never from any metric the agent reported.

run_backtest

Run a single backtest of agent over window with seeded execution noise, returning an sharpebench_core::Run (per-period returns + decision trace). The closed-loop driver: it owns the decide → step loop, calling the same [step_once] body the open-loop crate::env::TradingEnv uses.

run_backtest_capture

Run a backtest while capturing the agent’s raw decisions. Returns the same Run run_backtest would produce, plus the RunTrajectory artifact (the per-step decisions + the window/seed coordinates needed to replay it).

tag_regime

Tag a window’s regime by the equal-weight average total return across symbols (>+3% = bull, < -3% = bear, else chop).

walk_forward

Generate disjoint-start walk-forward test windows of test length, stepping by step, after a warmup burn-in (so features have history). Each window is an out-of-sample slice [start, start + test).