PHANTOM/lab

MOS (Money Operating System)

Research-grade quote-control simulator for studying dynamic pricing and market making policies. The system models pricing as a closed loop of Quote → Arrival → Execution → Position, enabling controlled experimentation with demand models, inventory constraints, and reward shaping.

Core Loop

1. Quote – the policy posts prices (one-sided or two-sided depending on the mechanism).
2. Arrival – a population model generates purchase opportunities or market orders.
3. Execution – an execution model decides whether an arrival converts at the quoted price.
4. Position – inventory/position limits censor fills and generate holding/shortage costs.
5. Observation & Reward – censored fills and aggregate metrics are exposed to the agent, while objectives turn metrics into a scalar reward.

Each stage is pluggable via light-weight protocols so you can swap in alternative mechanisms, demand models, or objectives without rewriting the rest of the simulator.

Package Layout

Module	Purpose
lab.outlet	Core simulation engine, domain types, pricing mechanisms, objectives.
lab.population	Demand arrival models, execution probability models, competitor/market dynamics.
lab.experiments	Rollout utilities, baseline policies, and off-policy evaluation helpers.
lab.config	Convenience factories for preconfigured retail and market-making environments.

Preconfigured Scenarios

Retail Dynamic Pricing

• Mechanism: posted prices with margin and delta constraints.
• Arrivals: browsing sessions with contamination support (scrapers).
• Execution: elasticity model with competitor cross-effects.
• Position: inventory tracking with holding and shortage costs.
• Market: reactive competitor that can trigger price wars.
• Objective: PnL minus volatility, holding cost, and lost opportunity penalties.

from lab.config import make_retail_platform
from lab.experiments import rollout, fixed_price_policy

platform = make_retail_platform()
policy = fixed_price_policy(platform.instruments.refs)
result = rollout(platform, policy, n_steps=100)
print(result.total_pnl)

Market Making

• Mechanism: two-sided quoting with bid/ask spreads.
• Arrivals: Hawkes order flow for clustered demand.
• Execution: Avellaneda–Stoikov style intensity model.
• Position: inventory risk limits and quadratic penalty objective.
• Market: geometric Brownian motion mid-price process.
• Objective: PnL plus spread capture minus inventory risk.

from lab.config import make_market_making_platform
from lab.experiments import rollout

platform = make_market_making_platform()
mm_policy = lambda obs, t: (platform.instruments.refs, 1.0)
result = rollout(platform, mm_policy, n_steps=200, seed=42)
print(result.total_pnl)

Extending the Simulator

• Implement lab.outlet.protocols.Mechanism or ArrivalModel to introduce new pricing domains or demand processes.
• Compose objectives with lab.outlet.objectives.factory.make_composite to study alternate reward formulations.
• Use lab.experiments.compare_policies to benchmark candidate policies across multiple random seeds.

Comprehensive API documentation lives in lab/docs (build with make html).