Crate openoutcry

Expand description

§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;

Modules§

contract: The frozen wire contract version.

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