Initial MarketMind commit (Corrected Author)

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+output/
+*.pyc
+.pytest_cache/
+.env

README.md

@@ -0,0 +1,156 @@
+---
+title: MarketMind
+emoji: ⚡
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+---
+
+# MarketMind
+
+**Multi-Agent Financial Market Simulation**
+*AMD Developer Hackathon | Track 1: AI Agents & Agentic Workflows | May 2026*
+
+A multi-agent financial market simulation where competing LLM agents with distinct trading charters interact inside a continuous double auction (limit order book). The system does not predict markets — it *is* a market. 
+
+**The research question:** 
+> When a financial market is populated entirely by competing LLM agents with heterogeneous beliefs and strategies, does it self-organize toward efficiency — or does it bubble, crash, or fragment?
+
+---
+
+## 🏗 Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   MarketMind System                 │
+│                                                     │
+│  ┌──────────────┐    ┌──────────────────────────┐   │
+│  │  Order Book  │◄───│     Agent Dispatcher     │   │
+│  │  (CDA Engine)│    │  (round-robin tick loop) │   │
+│  └──────┬───────┘    └──────────────────────────┘   │
+│         │                        ▲                  │
+│         │  market state          │ orders           │
+│         ▼                        │                  │
+│  ┌──────────────────────────────────────────────┐   │
+│  │              Agent Pool (5 agents)           │   │
+│  │                                              │   │
+│  │  [Momentum]  [MeanRev]  [Fundamental]        │   │
+│  │  [MarketMaker]  [NoiseTrader]                │   │
+│  │                                              │   │
+│  │  Each agent = LLM prompt + charter config    │   │
+│  └──────────────────────────────────────────────┘   │
+│         │                                           │
+│         │  inference requests                       │
+│         ▼                                           │
+│  ┌──────────────────────────────────────────────┐   │
+│  │     vLLM Server (AMD MI300X, ROCm)           │   │
+│  │     Qwen2.5-7B-Instruct                      │   │
+│  │     Concurrent batched requests              │   │
+│  └──────────────────────────────────────────────┘   │
+│         │                                           │
+│         ▼                                           │
+│  ┌──────────────────────────────────────────────┐   │
+│  │     Metrics Engine + Dashboard               │   │
+│  │     Price series / spread / volatility /     │   │
+│  │     crash detector / regime classifier       │   │
+│  └──────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔬 Experiments & Findings
+
+We ran three core experiments to observe emergent market behavior based solely on varying the agent composition. All experiments ran for 200 ticks.
+
+### Experiment A — Baseline (Equal Mix)
+*2 Momentum, 1 Mean-Reversion, 1 Fundamental, 1 Market Maker, 1 Noise*
+- **Hypothesis:** Prices stay near fair value. Market is relatively efficient.
+- **Result:** Validated. The market stayed largely efficient, oscillating tightly around the Fundamental agent's anchor price (100.0). The Fundamental agent emerged as the most profitable, while Momentum agents lost capital trading against noise.
+
+### Experiment B — Momentum Overload (Bubble Test)
+*4 Momentum, 1 Market Maker, 1 Noise (No Fundamental Anchor)*
+- **Hypothesis:** Price trends away from fair value → bubble formation.
+- **Result:** Validated. Without a fundamental anchor to fade the moves, momentum agents bought into each other's flow. Price skyrocketed from 100 to over 200 in 200 ticks, creating a massive, unstable bubble. 
+
+### Experiment C — No Market Maker (Liquidity Test)
+*2 Momentum, 1 Mean-Reversion, 1 Fundamental, 1 Noise (No Market Maker)*
+- **Hypothesis:** Spreads widen dramatically, liquidity fragmentation, possible crash.
+- **Result:** Validated. Without a dedicated liquidity provider continuously quoting both sides, the order book rapidly dried up. The spread widened dramatically, and trade volume collapsed compared to the baseline.
+
+---
+
+## 🚀 AMD MI300X Hardware Advantage & Setup
+
+MarketMind utilizes **vLLM on ROCm** on the AMD Developer Cloud. By dispatching 5–6 agents simultaneously each tick using `asyncio.gather`, we max out concurrent inference streams. 
+
+The **MI300X's massive 192GB HBM3 memory** means we never page-out the model weights between agent calls, maintaining exceptionally low latency despite heavy parallel throughput.
+
+### Local Setup Instructions (AMD Developer Cloud)
+
+```bash
+# 1. Provision AMD MI300X Instance and install vLLM
+pip install vllm
+
+# 2. Launch vLLM Inference Server
+python -m vllm.entrypoints.openai.api_server \
+  --model Qwen/Qwen2.5-7B-Instruct \
+  --dtype float16 \
+  --max-model-len 2048 \
+  --tensor-parallel-size 1 \
+  --port 8000
+```
+
+### Benchmarking
+We provide a standalone benchmark script to measure the MI300X's concurrency speedup:
+```bash
+python experiments/benchmark_vllm.py --url http://localhost:8000/v1
+```
+*(Insert your benchmark latency and throughput results here before submission!)*
+
+---
+
+## 🌐 Hugging Face Spaces Deployment
+
+As part of the AMD Developer Hackathon requirements, **MarketMind is fully optimized for 1-click deployment to Hugging Face Spaces**.
+
+### Premium Glassmorphic UI
+The root `app.py` features a stunning, custom-styled Streamlit interface tailored specifically for the HF Hub. It uses transparent Plotly charts, dynamic regime badging, and a premium dark-themed gradient background.
+
+### Live Serverless HF API Integration
+Because HF Spaces typically run on basic CPU tiers by default, the app contains an integrated **Live Hugging Face API Mode**. Users can:
+1. Paste their Hugging Face API Token directly into the dashboard.
+2. The UI natively bridges the Simulation Engine to the `api-inference.huggingface.co/v1/` endpoint using the OpenAI SDK format.
+3. Live models (like `meta-llama/Llama-3.2-3B-Instruct`) will directly drive the financial agents over the API without requiring a dedicated GPU inside the space itself.
+
+**To deploy your own Space:**
+1. Create a new Streamlit Space on Hugging Face.
+2. Push this repository's root directly to the space.
+3. Streamlit will automatically find `app.py` and `requirements.txt` and launch the platform.
+
+---
+
+## 💻 Local Quickstart
+
+### Prerequisites
+```bash
+pip install -r requirements.txt
+```
+
+### Run Simulation Offline (No LLM Required)
+You can run the simulation locally using the deterministic offline heuristic mode.
+```bash
+python run_simulation.py --ticks 200
+```
+
+### Run Streamlit Dashboard
+Visualize the live simulation playback and change agent parameters in real-time.
+```bash
+streamlit run dashboard/app.py
+```
+
+---
+*Built for the AMD Developer Hackathon | Track 1: AI Agents & Agentic Workflows*

agents/__init__.py

@@ -0,0 +1 @@
+# agents package

agents/base_agent.py

@@ -0,0 +1,83 @@
+"""
+Base Agent — abstract class for all trading agents.
+
+Each agent holds a charter (system prompt), position state, and cash.
+On each tick, the simulation calls agent.observe() with market state
+and the agent returns an Order (or None for hold).
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from engine.order_book import Order, Side
+
+
+@dataclass
+class AgentState:
+    """Mutable state tracked per agent across ticks."""
+    position: int = 0        # net units held (positive = long, negative = short)
+    cash: float = 10_000.0   # starting cash
+    total_pnl: float = 0.0   # realized PnL
+    trades_count: int = 0
+
+
+class BaseAgent(ABC):
+    """
+    Abstract trading agent.
+
+    Subclasses must implement:
+        - charter: property returning the system prompt string
+        - agent_type: property returning a human-readable type name
+    """
+
+    def __init__(self, agent_id: str, initial_cash: float = 10_000.0):
+        self.agent_id = agent_id
+        self.state = AgentState(cash=initial_cash)
+        self.price_history: list[float] = []
+
+    @property
+    @abstractmethod
+    def charter(self) -> str:
+        """System prompt defining this agent's trading strategy."""
+        ...
+
+    @property
+    @abstractmethod
+    def agent_type(self) -> str:
+        """Human-readable agent type name (e.g., 'Momentum')."""
+        ...
+
+    def update_price_history(self, price: float):
+        """Called each tick to track price history for the agent's context window."""
+        self.price_history.append(price)
+
+    def update_fair_value(self, new_fv: float):
+        """
+        Called each tick by the simulation to broadcast true macroeconomic value drifts.
+        Most agents ignore this (it's private info), but Fundamental agents use it.
+        """
+        pass
+
+    def record_trade(self, side: Side, price: float, quantity: int):
+        """
+        Update agent state after a trade execution.
+        Called by the simulation loop when a trade involves this agent.
+        """
+        if side == Side.BUY:
+            self.state.position += quantity
+            self.state.cash -= price * quantity
+        elif side == Side.SELL:
+            self.state.position -= quantity
+            self.state.cash += price * quantity
+        self.state.trades_count += 1
+
+    def mark_to_market(self, current_price: float) -> float:
+        """Calculate total PnL: cash + position value - initial cash."""
+        position_value = self.state.position * current_price
+        return self.state.cash + position_value - 10_000.0
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.agent_type}(id={self.agent_id}, "
+            f"pos={self.state.position}, cash={self.state.cash:.2f})"
+        )

agents/fundamental_agent.py

@@ -0,0 +1,28 @@
+"""
+Fundamental Agent — trades based on private fair value estimate.
+
+Charter: Buys below fair value, sells above. Patient, slow to act.
+"""
+
+from agents.base_agent import BaseAgent
+from inference.prompt_templates import get_fundamental_charter
+
+
+class FundamentalAgent(BaseAgent):
+
+    def __init__(self, agent_id: str, fair_value: float = 100.0, initial_cash: float = 10_000.0):
+        super().__init__(agent_id, initial_cash)
+        self.fair_value = fair_value
+
+    def update_fair_value(self, new_fv: float):
+        """Called by the simulation engine if the asset's true value drifts."""
+        self.fair_value = new_fv
+
+    @property
+    def charter(self) -> str:
+        # Re-evaluate dynamically in case fair_value changed
+        return get_fundamental_charter(self.fair_value)
+
+    @property
+    def agent_type(self) -> str:
+        return "Fundamental"

agents/market_maker_agent.py

@@ -0,0 +1,20 @@
+"""
+Market Maker Agent — provides liquidity by quoting both sides.
+
+Charter: Posts bid below mid, ask above mid. Manages inventory risk.
+Per spec, this agent is called twice per tick (bid + ask).
+"""
+
+from agents.base_agent import BaseAgent
+from inference.prompt_templates import MARKET_MAKER_CHARTER
+
+
+class MarketMakerAgent(BaseAgent):
+
+    @property
+    def charter(self) -> str:
+        return MARKET_MAKER_CHARTER
+
+    @property
+    def agent_type(self) -> str:
+        return "MarketMaker"

agents/mean_reversion_agent.py

@@ -0,0 +1,19 @@
+"""
+Mean Reversion Agent — fades moves away from rolling mean.
+
+Charter: Uses z-score thresholds against 10-tick rolling average.
+"""
+
+from agents.base_agent import BaseAgent
+from inference.prompt_templates import MEAN_REVERSION_CHARTER
+
+
+class MeanReversionAgent(BaseAgent):
+
+    @property
+    def charter(self) -> str:
+        return MEAN_REVERSION_CHARTER
+
+    @property
+    def agent_type(self) -> str:
+        return "MeanReversion"

agents/momentum_agent.py

@@ -0,0 +1,19 @@
+"""
+Momentum Agent — buys into rising prices, sells into falling.
+
+Charter: Short memory window, high turnover, trend-following.
+"""
+
+from agents.base_agent import BaseAgent
+from inference.prompt_templates import MOMENTUM_CHARTER
+
+
+class MomentumAgent(BaseAgent):
+
+    @property
+    def charter(self) -> str:
+        return MOMENTUM_CHARTER
+
+    @property
+    def agent_type(self) -> str:
+        return "Momentum"

agents/noise_trader.py

@@ -0,0 +1,19 @@
+"""
+Noise Trader — acts on random signals to create market friction.
+
+Charter: Random buy/sell within 1% of mid, small quantities.
+"""
+
+from agents.base_agent import BaseAgent
+from inference.prompt_templates import NOISE_TRADER_CHARTER
+
+
+class NoiseTrader(BaseAgent):
+
+    @property
+    def charter(self) -> str:
+        return NOISE_TRADER_CHARTER
+
+    @property
+    def agent_type(self) -> str:
+        return "NoiseTrader"

app.py

@@ -0,0 +1,565 @@
+"""
+MarketMind — Gradio Dashboard
+A premium trading terminal UI for multi-agent financial market simulation.
+Optimized for Hugging Face Spaces deployment.
+"""
+
+import sys
+import os
+import time
+import json
+import pandas as pd
+import numpy as np
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+import gradio as gr
+
+# Ensure imports work from this directory
+sys.path.insert(0, os.path.dirname(__file__))
+
+from engine.simulation import SimulationEngine, SimulationConfig
+from agents.momentum_agent import MomentumAgent
+from agents.mean_reversion_agent import MeanReversionAgent
+from agents.fundamental_agent import FundamentalAgent
+from agents.market_maker_agent import MarketMakerAgent
+from agents.noise_trader import NoiseTrader
+
+
+# ─── AGENT BUILDER ────────────────────────────────────────────────
+def build_agents(n_mom, n_mr, n_fund, n_noise, n_mm):
+    agents = []
+    for i in range(n_mom):
+        agents.append(MomentumAgent(f"momentum_{i+1}"))
+    for i in range(n_mr):
+        agents.append(MeanReversionAgent(f"meanrev_{i+1}"))
+    for i in range(n_fund):
+        agents.append(FundamentalAgent(f"fundamental_{i+1}", fair_value=100.0))
+    for i in range(n_noise):
+        agents.append(NoiseTrader(f"noise_{i+1}"))
+    for i in range(n_mm):
+        agents.append(MarketMakerAgent(f"marketmaker_{i+1}"))
+    return agents
+
+
+# ─── CHART BUILDERS ───────────────────────────────────────────────
+
+COLORS = {
+    "price": "#00d4ff",
+    "fair_value": "#ff3366",
+    "spread": "#ffaa00",
+    "volume": "#7c4dff",
+    "bg": "rgba(0,0,0,0)",
+    "grid": "rgba(255,255,255,0.04)",
+    "text": "#8892b0",
+    "agents": ["#00d4ff", "#00ff88", "#ff3366", "#ffaa00", "#7c4dff",
+               "#ff6b9d", "#c084fc", "#34d399", "#f87171", "#fbbf24"],
+}
+
+
+def build_main_chart(ticks_data):
+    """Build the primary price + volume + spread multi-panel chart."""
+    ticks = [r["tick"] for r in ticks_data]
+    prices = [r["mid_price"] if r["mid_price"] else 100.0 for r in ticks_data]
+    fair_vals = [r.get("true_fair_value", 100.0) for r in ticks_data]
+    spreads = [r["spread"] if r["spread"] else 0.0 for r in ticks_data]
+    volumes = [r["volume"] for r in ticks_data]
+    regimes = [r["regime"] for r in ticks_data]
+
+    fig = make_subplots(
+        rows=3, cols=1,
+        shared_xaxes=True,
+        vertical_spacing=0.03,
+        row_heights=[0.6, 0.2, 0.2],
+        subplot_titles=None,
+    )
+
+    # Price line
+    fig.add_trace(go.Scatter(
+        x=ticks, y=prices,
+        mode="lines",
+        line=dict(color=COLORS["price"], width=2.5),
+        name="Market Price",
+        fill="tozeroy",
+        fillcolor="rgba(0, 212, 255, 0.05)",
+    ), row=1, col=1)
+
+    # Fair value
+    fig.add_trace(go.Scatter(
+        x=ticks, y=fair_vals,
+        mode="lines",
+        line=dict(color=COLORS["fair_value"], width=1.5, dash="dot"),
+        name="Fair Value",
+    ), row=1, col=1)
+
+    # Regime color bands
+    regime_colors = {"Efficient": "rgba(0,255,136,0.06)",
+                     "Trending": "rgba(255,170,0,0.06)",
+                     "Volatile": "rgba(255,51,102,0.06)",
+                     "Crashed": "rgba(255,0,0,0.10)"}
+    prev_regime = regimes[0] if regimes else "Efficient"
+    band_start = ticks[0] if ticks else 0
+    for i, (t, reg) in enumerate(zip(ticks, regimes)):
+        if reg != prev_regime or i == len(ticks) - 1:
+            fig.add_vrect(
+                x0=band_start, x1=t,
+                fillcolor=regime_colors.get(prev_regime, "rgba(0,0,0,0)"),
+                layer="below", line_width=0, row=1, col=1,
+            )
+            band_start = t
+            prev_regime = reg
+
+    # Volume bars
+    fig.add_trace(go.Bar(
+        x=ticks, y=volumes,
+        marker_color=COLORS["volume"],
+        opacity=0.6,
+        name="Volume",
+    ), row=2, col=1)
+
+    # Spread
+    fig.add_trace(go.Scatter(
+        x=ticks, y=spreads,
+        mode="lines",
+        line=dict(color=COLORS["spread"], width=2),
+        fill="tozeroy",
+        fillcolor="rgba(255,170,0,0.08)",
+        name="Spread",
+    ), row=3, col=1)
+
+    # Layout
+    fig.update_layout(
+        template="plotly_dark",
+        paper_bgcolor=COLORS["bg"],
+        plot_bgcolor=COLORS["bg"],
+        font=dict(family="JetBrains Mono, monospace", color=COLORS["text"]),
+        height=620,
+        margin=dict(l=50, r=20, t=30, b=30),
+        legend=dict(
+            orientation="h", yanchor="bottom", y=1.02,
+            xanchor="right", x=1,
+            bgcolor="rgba(0,0,0,0)",
+            font=dict(size=11),
+        ),
+        showlegend=True,
+    )
+
+    for row in range(1, 4):
+        fig.update_xaxes(
+            gridcolor=COLORS["grid"], zeroline=False,
+            showticklabels=(row == 3), row=row, col=1,
+        )
+        fig.update_yaxes(
+            gridcolor=COLORS["grid"], zeroline=False,
+            row=row, col=1,
+        )
+
+    fig.update_yaxes(title_text="Price", row=1, col=1)
+    fig.update_yaxes(title_text="Vol", row=2, col=1)
+    fig.update_yaxes(title_text="Spread", row=3, col=1)
+    fig.update_xaxes(title_text="Tick", row=3, col=1)
+
+    return fig
+
+
+def build_pnl_chart(pnl_data, agents):
+    """Build the agent PnL leaderboard chart."""
+    fig = go.Figure()
+
+    agent_ids = [a.agent_id for a in agents]
+    for idx, aid in enumerate(agent_ids):
+        agent_rows = [r for r in pnl_data if r["agent_id"] == aid]
+        ticks = [r["tick"] for r in agent_rows]
+        pnls = [r["pnl"] for r in agent_rows]
+        fig.add_trace(go.Scatter(
+            x=ticks, y=pnls,
+            mode="lines",
+            line=dict(color=COLORS["agents"][idx % len(COLORS["agents"])], width=2),
+            name=aid,
+        ))
+
+    fig.update_layout(
+        template="plotly_dark",
+        paper_bgcolor=COLORS["bg"],
+        plot_bgcolor=COLORS["bg"],
+        font=dict(family="JetBrains Mono, monospace", color=COLORS["text"]),
+        height=350,
+        margin=dict(l=50, r=20, t=30, b=30),
+        legend=dict(
+            orientation="h", yanchor="bottom", y=1.02,
+            xanchor="right", x=1,
+            bgcolor="rgba(0,0,0,0)",
+            font=dict(size=10),
+        ),
+        yaxis_title="PnL ($)",
+        xaxis_title="Tick",
+        xaxis=dict(gridcolor=COLORS["grid"], zeroline=False),
+        yaxis=dict(gridcolor=COLORS["grid"], zeroline=False),
+    )
+
+    # Zero line
+    fig.add_hline(y=0, line_dash="dash", line_color="rgba(255,255,255,0.15)", line_width=1)
+
+    return fig
+
+
+def build_leaderboard(pnl_data, ticks_data):
+    """Build final leaderboard as a DataFrame."""
+    if not pnl_data or not ticks_data:
+        return pd.DataFrame()
+
+    last_tick = ticks_data[-1]["tick"]
+    final_rows = [r for r in pnl_data if r["tick"] == last_tick]
+
+    records = []
+    for r in sorted(final_rows, key=lambda x: x["pnl"], reverse=True):
+        pnl = r["pnl"]
+        emoji = "🟢" if pnl > 0 else "🔴" if pnl < 0 else "⚪"
+        records.append({
+            "": emoji,
+            "Agent": r["agent_id"],
+            "Type": r["agent_type"],
+            "PnL": f"${pnl:+,.2f}",
+            "Position": r["position"],
+            "Trades": r["trades"],
+        })
+
+    return pd.DataFrame(records)
+
+
+def build_stats_html(ticks_data, pnl_data, elapsed):
+    """Build the live stats panel as HTML."""
+    if not ticks_data:
+        return "<p>No data</p>"
+
+    last = ticks_data[-1]
+    first_price = ticks_data[0]["mid_price"] or 100.0
+    last_price = last["mid_price"] or 100.0
+    pct_change = ((last_price - first_price) / first_price) * 100
+    total_volume = sum(r["volume"] for r in ticks_data)
+    total_trades = sum(r["trade_count"] for r in ticks_data)
+    avg_spread = np.mean([r["spread"] for r in ticks_data if r["spread"]]) if ticks_data else 0
+    regime = last.get("regime", "Unknown")
+
+    regime_colors = {
+        "Efficient": "#00ff88",
+        "Trending": "#ffaa00",
+        "Volatile": "#ff3366",
+        "Crashed": "#ff0000",
+    }
+    rc = regime_colors.get(regime, "#8892b0")
+
+    return f"""
+    <div style="display:grid; grid-template-columns: 1fr 1fr; gap: 12px;">
+        <div class="stat-card">
+            <div class="stat-label">FINAL PRICE</div>
+            <div class="stat-value">${last_price:,.2f}</div>
+            <div class="stat-delta" style="color: {'#00ff88' if pct_change >= 0 else '#ff3366'};">
+                {pct_change:+.2f}%
+            </div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-label">REGIME</div>
+            <div class="stat-value" style="color: {rc};">{regime}</div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-label">TOTAL TRADES</div>
+            <div class="stat-value">{total_trades:,}</div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-label">VOLUME</div>
+            <div class="stat-value">{total_volume:,}</div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-label">AVG SPREAD</div>
+            <div class="stat-value">{avg_spread:.4f}</div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-label">SIM TIME</div>
+            <div class="stat-value">{elapsed:.1f}s</div>
+        </div>
+    </div>
+    """
+
+
+# ─── SIMULATION RUNNER ────────────────────────────────────────────
+
+def run_simulation(n_mom, n_mr, n_fund, n_noise, n_mm,
+                   num_ticks, warmup_ticks, volatility, use_llm, hf_token, hf_model,
+                   progress=gr.Progress()):
+    """Run the full simulation and return all visualization components."""
+    agents = build_agents(int(n_mom), int(n_mr), int(n_fund), int(n_noise), int(n_mm))
+    if not agents:
+        raise gr.Error("Add at least one agent to run the simulation.")
+
+    config = SimulationConfig(
+        num_ticks=int(num_ticks),
+        initial_price=100.0,
+        use_llm=use_llm,
+        vllm_base_url="https://api-inference.huggingface.co/v1" if use_llm else "http://localhost:8000/v1",
+        vllm_model=hf_model if use_llm else "Qwen/Qwen2.5-7B-Instruct",
+        log_to_csv=False,
+        base_volatility=volatility,
+        warmup_ticks=int(warmup_ticks),
+        enable_seed_liquidity=False, # pure LLM market
+        fee_per_trade=0.01
+    )
+
+    engine = SimulationEngine(agents, config)
+
+    if use_llm and hf_token and engine.llm_client:
+        import openai
+        engine.llm_client.client = openai.AsyncOpenAI(
+            base_url=config.vllm_base_url,
+            api_key=hf_token,
+        )
+
+    t0 = time.time()
+    
+    # Use generator to yield live updates
+    for tick in engine.run_generator():
+        progress(tick / int(num_ticks), desc=f"Running tick {tick}/{num_ticks}...")
+        
+        # Only yield UI updates every 10 ticks to prevent Gradio blocking
+        if tick % 10 == 0 or tick == int(num_ticks):
+            ticks_data = engine.csv_rows
+            pnl_data = engine.agent_pnl_rows
+            
+            main_chart = build_main_chart(ticks_data)
+            pnl_chart = build_pnl_chart(pnl_data, agents)
+            leaderboard = build_leaderboard(pnl_data, ticks_data)
+            stats_html = build_stats_html(ticks_data, pnl_data, time.time() - t0)
+            
+            yield main_chart, pnl_chart, leaderboard, stats_html
+
+
+# ─── CUSTOM CSS ───────────────────────────────────────────────────
+
+CUSTOM_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;800&family=JetBrains+Mono:wght@400;500&display=swap');
+
+/* ── Global ─────────────────────────────────────── */
+html, body {
+    background: #0a0b10 !important;
+}
+.gradio-container {
+    max-width: 100% !important;
+    font-family: 'Inter', sans-serif !important;
+    background: linear-gradient(160deg, #0a0b10 0%, #111827 50%, #0d1117 100%) !important;
+    min-height: 100vh;
+}
+.main {
+    background: transparent !important;
+}
+footer {
+    display: none !important;
+}
+
+/* ── Top Bar ────────────────────────────────────── */
+.title-bar {
+    background: linear-gradient(135deg, rgba(0,212,255,0.08), rgba(124,77,255,0.08));
+    border: 1px solid rgba(0,212,255,0.12);
+    border-radius: 16px;
+    padding: 24px 32px;
+    margin-bottom: 16px;
+    position: relative;
+    overflow: hidden;
+}
+.title-bar::before {
+    content: '';
+    position: absolute;
+    top: 0; left: 0; right: 0;
+    height: 2px;
+    background: linear-gradient(90deg, #00d4ff, #7c4dff, #ff3366);
+}
+.title-bar h1 {
+    margin: 0 0 4px 0;
+    font-size: 2em;
+    font-weight: 800;
+    background: linear-gradient(135deg, #00d4ff 0%, #7c4dff 50%, #ff3366 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    letter-spacing: -1px;
+}
+.title-bar p {
+    margin: 0;
+    color: #8892b0;
+    font-size: 0.95em;
+    max-width: 700px;
+}
+
+/* ── Stat Cards ─────────────────────────────────── */
+.stat-card {
+    background: rgba(17,24,39,0.7);
+    border: 1px solid rgba(255,255,255,0.06);
+    border-radius: 12px;
+    padding: 14px 16px;
+    text-align: center;
+}
+.stat-label {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 0.65em;
+    color: #5a6785;
+    letter-spacing: 1.5px;
+    text-transform: uppercase;
+    margin-bottom: 4px;
+}
+.stat-value {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 1.3em;
+    font-weight: 600;
+    color: #e2e8f0;
+}
+.stat-delta {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 0.85em;
+    font-weight: 500;
+}
+
+/* ── Panel Sections ─────────────────────────────── */
+.panel-header {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 0.75em;
+    color: #00d4ff;
+    letter-spacing: 2px;
+    text-transform: uppercase;
+    margin: 16px 0 8px 0;
+    padding-bottom: 6px;
+    border-bottom: 1px solid rgba(0,212,255,0.15);
+}
+
+/* ── Gradio Overrides ───────────────────────────── */
+.dark .block {
+    background: rgba(17,24,39,0.5) !important;
+    border: 1px solid rgba(255,255,255,0.05) !important;
+    border-radius: 12px !important;
+}
+.dark .label-wrap {
+    color: #8892b0 !important;
+}
+.dark input, .dark textarea, .dark select {
+    background: rgba(15,20,35,0.8) !important;
+    border: 1px solid rgba(255,255,255,0.08) !important;
+    color: #e2e8f0 !important;
+    border-radius: 8px !important;
+}
+.dark .primary {
+    background: linear-gradient(135deg, #00d4ff 0%, #7c4dff 100%) !important;
+    border: none !important;
+    font-weight: 600 !important;
+    letter-spacing: 0.5px !important;
+    transition: all 0.3s ease !important;
+    box-shadow: 0 4px 15px rgba(0,212,255,0.25) !important;
+}
+.dark .primary:hover {
+    box-shadow: 0 6px 25px rgba(0,212,255,0.4) !important;
+    transform: translateY(-1px) !important;
+}
+.dark table {
+    font-family: 'JetBrains Mono', monospace !important;
+    font-size: 0.85em !important;
+}
+
+/* ── Scrollbar ──────────────────────────────────── */
+::-webkit-scrollbar { width: 6px; }
+::-webkit-scrollbar-track { background: rgba(0,0,0,0.2); }
+::-webkit-scrollbar-thumb { background: rgba(0,212,255,0.3); border-radius: 3px; }
+"""
+
+
+# ─── GRADIO APP ───────────────────────────────────────────────────
+
+def create_app():
+    with gr.Blocks(
+        title="MarketMind | Multi-Agent Market Simulation",
+    ) as app:
+
+        # ── Title Bar ──
+        gr.HTML("""
+        <div class="title-bar">
+            <h1>⚡ MarketMind</h1>
+            <p>Multi-agent financial market simulation powered by LLM agents competing inside a 
+            continuous double auction. Adjust the agent composition to discover if the market 
+            self-organizes to efficiency — or collapses into chaos.</p>
+        </div>
+        """)
+
+        with gr.Row():
+            # ══════════════════════════════════════════════
+            # LEFT PANEL — Controls
+            # ══════════════════════════════════════════════
+            with gr.Column(scale=1, min_width=280):
+
+                gr.HTML('<div class="panel-header">⚙ Engine</div>')
+                use_llm = gr.Checkbox(label="Live LLM Mode", value=False,
+                                      info="Use HF Serverless API for live inference")
+                hf_token = gr.Textbox(label="HF Token", type="password",
+                                      placeholder="hf_...", visible=False)
+                hf_model = gr.Textbox(label="Model", value="meta-llama/Llama-3.2-3B-Instruct",
+                                      visible=False)
+
+                use_llm.change(
+                    lambda v: (gr.update(visible=v), gr.update(visible=v)),
+                    inputs=[use_llm],
+                    outputs=[hf_token, hf_model],
+                )
+
+                gr.HTML('<div class="panel-header">🧬 Agent Composition</div>')
+                n_mom = gr.Slider(0, 10, value=2, step=1, label="Momentum Traders")
+                n_mr = gr.Slider(0, 10, value=1, step=1, label="Mean Reversion")
+                n_fund = gr.Slider(0, 10, value=1, step=1, label="Fundamental")
+                n_noise = gr.Slider(0, 10, value=1, step=1, label="Noise Traders")
+                n_mm = gr.Slider(0, 5, value=1, step=1, label="Market Makers")
+
+                gr.HTML('<div class="panel-header">🔧 Parameters</div>')
+                num_ticks = gr.Slider(20, 500, value=150, step=10, label="Simulation Ticks")
+                warmup_ticks = gr.Slider(0, 50, value=15, step=5, label="Market Warm-up (Ticks)",
+                                         info="Establishing baseline before LLMs take over")
+                volatility = gr.Slider(0.0, 0.05, value=0.005, step=0.001,
+                                       label="Market Volatility")
+
+                run_btn = gr.Button("▶  Execute Simulation", variant="primary", size="lg")
+
+                # Stats panel (populated after simulation)
+                gr.HTML('<div class="panel-header">📊 Session Stats</div>')
+                stats_panel = gr.HTML("<p style='color:#5a6785;text-align:center;padding:20px;'>Run a simulation to see stats</p>")
+
+            # ══════════════════════════════════════════════
+            # RIGHT PANEL — Charts & Results
+            # ══════════════════════════════════════════════
+            with gr.Column(scale=3):
+
+                main_chart = gr.Plot(label="Market Overview", elem_classes=["chart-panel"])
+                pnl_chart = gr.Plot(label="Agent PnL Tracker")
+                leaderboard = gr.DataFrame(
+                    label="🏆 Final Leaderboard",
+                    interactive=False,
+                    wrap=True,
+                )
+
+        # ── Wire up the button ──
+        run_btn.click(
+            fn=run_simulation,
+            inputs=[n_mom, n_mr, n_fund, n_noise, n_mm,
+                    num_ticks, warmup_ticks, volatility, use_llm, hf_token, hf_model],
+            outputs=[main_chart, pnl_chart, leaderboard, stats_panel],
+        )
+
+    return app
+
+
+# ─── ENTRY POINT ──────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    app = create_app()
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        css=CUSTOM_CSS,
+        theme=gr.themes.Base(
+            primary_hue=gr.themes.colors.cyan,
+            secondary_hue=gr.themes.colors.purple,
+            neutral_hue=gr.themes.colors.slate,
+            font=gr.themes.GoogleFont("Inter"),
+            font_mono=gr.themes.GoogleFont("JetBrains Mono"),
+        ),
+    )

dashboard/__init__.py

@@ -0,0 +1 @@
+# dashboard package

dashboard/app.py

@@ -0,0 +1,154 @@
+"""
+MarketMind Streamlit Dashboard.
+
+Live playback of the market simulation.
+Lets the user dynamically change agent composition and watch the emergent behavior.
+"""
+
+import sys
+import os
+import time
+import pandas as pd
+import streamlit as st
+
+# Ensure we can import from the rest of the project
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from engine.simulation import SimulationEngine, SimulationConfig
+from agents.momentum_agent import MomentumAgent
+from agents.mean_reversion_agent import MeanReversionAgent
+from agents.fundamental_agent import FundamentalAgent
+from agents.market_maker_agent import MarketMakerAgent
+from agents.noise_trader import NoiseTrader
+from dashboard.plots import plot_price_chart, plot_agent_pnl, plot_spread
+
+st.set_page_config(page_title="MarketMind Simulation", layout="wide", page_icon="📈")
+
+
+def build_agents(n_mom: int, n_mr: int, n_fund: int, n_noise: int, n_mm: int) -> list:
+    """Build the agent pool based on slider inputs."""
+    agents = []
+    for i in range(n_mom):
+        agents.append(MomentumAgent(f"momentum_{i+1}"))
+    for i in range(n_mr):
+        agents.append(MeanReversionAgent(f"meanrev_{i+1}"))
+    for i in range(n_fund):
+        agents.append(FundamentalAgent(f"fundamental_{i+1}", fair_value=100.0))
+    for i in range(n_noise):
+        agents.append(NoiseTrader(f"noise_{i+1}"))
+    for i in range(n_mm):
+        agents.append(MarketMakerAgent(f"marketmaker_{i+1}"))
+    return agents
+
+
+def main():
+    st.title("📈 MarketMind: Agent-Based Market Simulation")
+    st.markdown("Observe emergent market behavior based on LLM agent composition.")
+
+    # Sidebar: Agent Composition
+    st.sidebar.header("⚙️ Agent Composition")
+    st.sidebar.markdown("Change the mix of traders to test market stability.")
+
+    n_mom = st.sidebar.slider("Momentum Traders", 0, 10, 2)
+    n_mr = st.sidebar.slider("Mean Reversion Traders", 0, 10, 1)
+    n_fund = st.sidebar.slider("Fundamental Traders (Anchor)", 0, 10, 1)
+    n_noise = st.sidebar.slider("Noise Traders", 0, 10, 1)
+    n_mm = st.sidebar.slider("Market Makers", 0, 5, 1)
+
+    st.sidebar.markdown("---")
+    num_ticks = st.sidebar.slider("Simulation Ticks", 50, 500, 150, step=50)
+    playback_speed = st.sidebar.slider("Playback Speed (ms)", 0, 200, 50, step=10)
+
+    if st.sidebar.button("🚀 Run Simulation", type="primary"):
+        run_simulation_and_play(n_mom, n_mr, n_fund, n_noise, n_mm, num_ticks, playback_speed)
+    else:
+        st.info("Configure your agents in the sidebar and click **Run Simulation**.")
+
+
+def run_simulation_and_play(n_mom, n_mr, n_fund, n_noise, n_mm, num_ticks, playback_speed):
+    # Setup
+    agents = build_agents(n_mom, n_mr, n_fund, n_noise, n_mm)
+    if not agents:
+        st.error("You need at least one agent to run a simulation!")
+        return
+
+    config = SimulationConfig(
+        num_ticks=num_ticks,
+        initial_price=100.0,
+        use_llm=False,  # Dashboard uses offline mode for fast iteration
+        log_to_csv=False,
+    )
+
+    engine = SimulationEngine(agents, config)
+    
+    with st.spinner(f"Running simulation offline ({num_ticks} ticks)..."):
+        engine.run()
+
+    # Pre-extract data for playback
+    ticks_data = engine.csv_rows
+    pnl_data = engine.agent_pnl_rows
+
+    st.success(f"Simulation generated! Playing back...")
+
+    # Layout for playback
+    col1, col2 = st.columns([3, 1])
+    
+    with col1:
+        price_placeholder = st.empty()
+        spread_placeholder = st.empty()
+    
+    with col2:
+        regime_placeholder = st.empty()
+        st.markdown("### Agent Leaderboard")
+        leaderboard_placeholder = st.empty()
+
+    # Data structures for incremental plotting
+    curr_ticks = []
+    curr_prices = []
+    curr_spreads = []
+    curr_pnls = {agent.agent_id: [] for agent in agents}
+
+    # Playback Loop
+    for tick_idx in range(len(ticks_data)):
+        tick_info = ticks_data[tick_idx]
+        t = tick_info["tick"]
+        
+        curr_ticks.append(t)
+        curr_prices.append(tick_info["mid_price"] if tick_info["mid_price"] is not None else 100.0)
+        curr_spreads.append(tick_info["spread"] if tick_info["spread"] is not None else 0.0)
+
+        # Update PnLs for this tick
+        tick_pnl_rows = [row for row in pnl_data if row["tick"] == t]
+        for row in tick_pnl_rows:
+            curr_pnls[row["agent_id"]].append(row["pnl"])
+
+        # Render charts every N ticks to save Streamlit rendering time (if very fast)
+        # or every tick if speed allows.
+        price_fig = plot_price_chart(curr_ticks, curr_prices, fair_value=100.0)
+        price_placeholder.plotly_chart(price_fig, use_container_width=True, key=f"p_{t}")
+
+        spread_fig = plot_spread(curr_ticks, curr_spreads)
+        spread_placeholder.plotly_chart(spread_fig, use_container_width=True, key=f"s_{t}")
+
+        # Update Regime
+        regime = tick_info["regime"]
+        color = "green" if regime == "Efficient" else "orange" if regime == "Trending" else "red"
+        regime_placeholder.markdown(f"### Market Regime: <span style='color:{color}'>{regime}</span>", unsafe_allow_html=True)
+
+        # Update Leaderboard
+        # Sort current agents by their latest PnL
+        current_leaderboard = sorted(
+            [{"Agent": row["agent_id"], "Type": row["agent_type"], "PnL": f"${row['pnl']:.2f}", "Pos": row["position"]} for row in tick_pnl_rows],
+            key=lambda x: float(x["PnL"].replace('$', '')),
+            reverse=True
+        )
+        df_leaderboard = pd.DataFrame(current_leaderboard)
+        leaderboard_placeholder.dataframe(df_leaderboard, use_container_width=True, hide_index=True)
+
+        # Pause for animation effect
+        if playback_speed > 0:
+            time.sleep(playback_speed / 1000.0)
+
+
+if __name__ == "__main__":
+    main()

dashboard/plots.py

@@ -0,0 +1,97 @@
+"""
+Plotly charting utilities for the Streamlit dashboard.
+
+Generates interactive charts for the live dashboard playback:
+1. Real-time price chart
+2. Agent PnL leaderboard
+3. Bid-ask spread chart
+"""
+
+import plotly.graph_objects as go
+
+
+def plot_price_chart(ticks: list[int], prices: list[float], true_fair_values: list[float] | None = None) -> go.Figure:
+    """Live price series with a dynamic fair value reference line."""
+    fig = go.Figure()
+    
+    fig.add_trace(go.Scatter(
+        x=ticks, y=prices,
+        mode="lines",
+        line=dict(color="#2196F3", width=2),
+        name="Mid Price"
+    ))
+    
+    # Fair value anchor line (dynamic)
+    if true_fair_values:
+        fig.add_trace(go.Scatter(
+            x=ticks,
+            y=true_fair_values,
+            mode="lines",
+            line=dict(color="#F44336", width=1, dash="dash"),
+            name="True Fair Value"
+        ))
+    
+    fig.update_layout(
+        title="Live Market Price",
+        xaxis_title="Tick",
+        yaxis_title="Price",
+        template="plotly_dark",
+        margin=dict(l=20, r=20, t=40, b=20),
+        height=300,
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)"
+    )
+    return fig
+
+
+def plot_agent_pnl(ticks: list[int], agent_pnls: dict[str, list[float]]) -> go.Figure:
+    """Agent PnL over time."""
+    fig = go.Figure()
+    
+    colors = ["#2196F3", "#4CAF50", "#F44336", "#FF9800", "#9C27B0", "#00BCD4"]
+    
+    for i, (agent_id, pnls) in enumerate(agent_pnls.items()):
+        fig.add_trace(go.Scatter(
+            x=ticks, y=pnls,
+            mode="lines",
+            line=dict(color=colors[i % len(colors)], width=2),
+            name=agent_id
+        ))
+        
+    fig.update_layout(
+        title="Agent PnL (Mark-to-Market)",
+        xaxis_title="Tick",
+        yaxis_title="PnL",
+        template="plotly_dark",
+        margin=dict(l=20, r=20, t=40, b=20),
+        height=300,
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)"
+    )
+    return fig
+
+
+def plot_spread(ticks: list[int], spreads: list[float]) -> go.Figure:
+    """Bid-ask spread over time."""
+    fig = go.Figure()
+    
+    fig.add_trace(go.Scatter(
+        x=ticks, y=spreads,
+        mode="lines",
+        line=dict(color="#FF9800", width=2),
+        fill="tozeroy",
+        name="Spread"
+    ))
+    
+    fig.update_layout(
+        title="Bid-Ask Spread",
+        xaxis_title="Tick",
+        yaxis_title="Spread",
+        template="plotly_dark",
+        margin=dict(l=20, r=20, t=40, b=20),
+        height=200,
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)"
+    )
+    return fig

engine/__init__.py

@@ -0,0 +1 @@
+# engine package

engine/market_state.py

@@ -0,0 +1,42 @@
+"""
+Market State Serializer.
+
+Converts order book snapshot + agent-specific state into a compact string
+that the LLM reads as its "user" message each tick.
+"""
+
+from engine.order_book import OrderBook
+
+
+def market_state_to_string(
+    book: OrderBook,
+    agent_id: str,
+    position: int,
+    cash: float,
+    price_history: list[float],
+) -> str:
+    """
+    Build the ~150-token market state string that agents receive each tick.
+
+    Includes: best bid, best ask, mid price, last trade price,
+    agent's position, agent's cash, last 10 prices.
+    """
+    snap = book.snapshot()
+
+    bb = f"{snap['best_bid']:.2f}" if snap['best_bid'] is not None else "none"
+    ba = f"{snap['best_ask']:.2f}" if snap['best_ask'] is not None else "none"
+    mid = f"{snap['mid_price']:.2f}" if snap['mid_price'] is not None else "none"
+    spread = f"{snap['spread']:.4f}" if snap['spread'] is not None else "none"
+    last_price = f"{snap['last_trade_price']:.2f}" if snap['last_trade_price'] is not None else "none"
+
+    # Last 10 prices, formatted compact
+    recent = price_history[-10:] if price_history else []
+    price_str = ", ".join(f"{p:.2f}" for p in recent) if recent else "none"
+
+    lines = [
+        f"Best Bid: {bb} | Best Ask: {ba} | Mid: {mid} | Spread: {spread}",
+        f"Last Trade: {last_price}",
+        f"Recent Prices (last {len(recent)}): [{price_str}]",
+        f"Your Position: {position} units | Your Cash: {cash:.2f}",
+    ]
+    return "\n".join(lines)

engine/metrics.py

@@ -0,0 +1,117 @@
+"""
+Metrics Engine.
+
+Computes price series, spread, volatility, crash detection, and per-agent PnL.
+Used by the simulation loop to track market health and by the dashboard for display.
+"""
+
+import math
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TickMetrics:
+    """Metrics snapshot for a single tick."""
+    tick: int
+    mid_price: float | None
+    best_bid: float | None
+    best_ask: float | None
+    spread: float | None
+    trade_count: int
+    volume: int  # total units traded this tick
+
+
+class MetricsEngine:
+    """
+    Accumulates per-tick metrics and computes derived signals.
+    """
+
+    def __init__(self, crash_threshold: float = 0.05, crash_window: int = 5):
+        self.tick_history: list[TickMetrics] = []
+        self.price_series: list[float] = []  # mid prices over time
+        self.crash_threshold = crash_threshold  # >5% drop
+        self.crash_window = crash_window         # in 5 ticks
+        self.crash_events: list[dict] = []
+
+    def record_tick(self, metrics: TickMetrics):
+        """Record metrics for one tick."""
+        self.tick_history.append(metrics)
+        if metrics.mid_price is not None:
+            self.price_series.append(metrics.mid_price)
+        self._check_crash()
+
+    def _check_crash(self):
+        """Detect crash: >threshold drop over crash_window ticks."""
+        if len(self.price_series) < self.crash_window + 1:
+            return
+        recent = self.price_series[-(self.crash_window + 1):]
+        pct_change = (recent[-1] - recent[0]) / recent[0]
+        if pct_change < -self.crash_threshold:
+            self.crash_events.append({
+                "tick": len(self.tick_history),
+                "drop_pct": pct_change * 100,
+                "from_price": recent[0],
+                "to_price": recent[-1],
+            })
+
+    def rolling_volatility(self, window: int = 10) -> float | None:
+        """Rolling standard deviation of mid prices over last `window` ticks."""
+        if len(self.price_series) < window:
+            return None
+        recent = self.price_series[-window:]
+        mean = sum(recent) / len(recent)
+        variance = sum((p - mean) ** 2 for p in recent) / len(recent)
+        return math.sqrt(variance)
+
+    def rolling_mean(self, window: int = 10) -> float | None:
+        """Rolling mean of mid prices."""
+        if len(self.price_series) < window:
+            return None
+        return sum(self.price_series[-window:]) / window
+
+    def classify_regime(self) -> str:
+        """
+        Simple regime classifier based on current market conditions.
+        Returns: "Efficient" | "Trending" | "Volatile" | "Crashed"
+        """
+        if self.crash_events and self.crash_events[-1]["tick"] >= len(self.tick_history) - 5:
+            return "Crashed"
+
+        vol = self.rolling_volatility()
+        if vol is None:
+            return "Efficient"
+
+        mean = self.rolling_mean()
+        if mean is None or mean == 0:
+            return "Efficient"
+
+        # Coefficient of variation
+        cv = vol / mean
+
+        if cv > 0.02:
+            return "Volatile"
+
+        # Check for trending: compare last 10 prices direction
+        if len(self.price_series) >= 10:
+            recent = self.price_series[-10:]
+            ups = sum(1 for i in range(1, len(recent)) if recent[i] > recent[i - 1])
+            downs = sum(1 for i in range(1, len(recent)) if recent[i] < recent[i - 1])
+            if ups >= 7 or downs >= 7:
+                return "Trending"
+
+        return "Efficient"
+
+    def summary(self) -> dict:
+        """Summary stats for reporting."""
+        return {
+            "total_ticks": len(self.tick_history),
+            "total_trades": sum(t.trade_count for t in self.tick_history),
+            "total_volume": sum(t.volume for t in self.tick_history),
+            "crash_events": len(self.crash_events),
+            "current_regime": self.classify_regime(),
+            "current_volatility": self.rolling_volatility(),
+            "price_range": (
+                (min(self.price_series), max(self.price_series))
+                if self.price_series else None
+            ),
+        }

engine/order_book.py

@@ -0,0 +1,248 @@
+"""
+Continuous Double Auction (CDA) Matching Engine.
+
+Implements a limit order book with price-time priority matching.
+This is the core market mechanism — all agent orders flow through here.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class Side(Enum):
+    BUY = "buy"
+    SELL = "sell"
+
+
+@dataclass
+class Order:
+    """A single limit order submitted by an agent."""
+    agent_id: str
+    side: Side
+    price: float
+    quantity: int
+    timestamp: int  # tick number — used for time priority
+
+    def __post_init__(self):
+        if self.quantity <= 0:
+            raise ValueError(f"Order quantity must be positive, got {self.quantity}")
+        if self.price <= 0:
+            raise ValueError(f"Order price must be positive, got {self.price}")
+
+
+@dataclass
+class Trade:
+    """A completed trade between two orders."""
+    tick: int
+    price: float
+    quantity: int
+    buyer_id: str
+    seller_id: str
+    aggressor_side: Side  # who crossed the spread
+
+    @property
+    def value(self) -> float:
+        return self.price * self.quantity
+
+
+class OrderBook:
+    """
+    Limit order book with price-time priority matching.
+
+    Bids sorted descending (best bid = highest price first).
+    Asks sorted ascending (best ask = lowest price first).
+    Within same price level, earlier orders match first (FIFO).
+    """
+
+    def __init__(self):
+        # Lists of Order, kept sorted after each insertion
+        self.bids: list[Order] = []  # sorted: highest price first, then earliest timestamp
+        self.asks: list[Order] = []  # sorted: lowest price first, then earliest timestamp
+        self.trade_log: list[Trade] = []
+        self._tick: int = 0
+
+    @property
+    def best_bid(self) -> Optional[float]:
+        """Highest bid price, or None if no bids."""
+        return self.bids[0].price if self.bids else None
+
+    @property
+    def best_ask(self) -> Optional[float]:
+        """Lowest ask price, or None if no asks."""
+        return self.asks[0].price if self.asks else None
+
+    @property
+    def mid_price(self) -> Optional[float]:
+        """Midpoint between best bid and best ask, or None if either side is empty."""
+        if self.best_bid is not None and self.best_ask is not None:
+            return (self.best_bid + self.best_ask) / 2.0
+        return None
+
+    @property
+    def spread(self) -> Optional[float]:
+        """Bid-ask spread, or None if either side is empty."""
+        if self.best_bid is not None and self.best_ask is not None:
+            return self.best_ask - self.best_bid
+        return None
+
+    def set_tick(self, tick: int):
+        """Advance the internal tick clock. Called by the simulation loop."""
+        self._tick = tick
+
+    def submit_order(self, order: Order) -> list[Trade]:
+        """
+        Submit an order to the book. Attempts to match immediately.
+        Any unmatched residual rests in the book.
+
+        Returns list of trades executed by this order (possibly empty).
+        """
+        trades: list[Trade] = []
+
+        if order.side == Side.BUY:
+            trades = self._match_buy(order)
+        elif order.side == Side.SELL:
+            trades = self._match_sell(order)
+
+        self.trade_log.extend(trades)
+        return trades
+
+    def _match_buy(self, buy_order: Order) -> list[Trade]:
+        """Match an incoming buy order against resting asks."""
+        trades: list[Trade] = []
+        remaining_qty = buy_order.quantity
+
+        while remaining_qty > 0 and self.asks:
+            best_ask_order = self.asks[0]
+
+            # Buy can only match if its price >= best ask price
+            if buy_order.price < best_ask_order.price:
+                break
+
+            # Determine fill quantity
+            fill_qty = min(remaining_qty, best_ask_order.quantity)
+            fill_price = best_ask_order.price  # price-time priority: passive order's price
+
+            trade = Trade(
+                tick=self._tick,
+                price=fill_price,
+                quantity=fill_qty,
+                buyer_id=buy_order.agent_id,
+                seller_id=best_ask_order.agent_id,
+                aggressor_side=Side.BUY,
+            )
+            trades.append(trade)
+
+            remaining_qty -= fill_qty
+            best_ask_order.quantity -= fill_qty
+
+            # Remove fully filled ask
+            if best_ask_order.quantity == 0:
+                self.asks.pop(0)
+
+        # Rest any unfilled portion in the bid book
+        if remaining_qty > 0:
+            resting_order = Order(
+                agent_id=buy_order.agent_id,
+                side=Side.BUY,
+                price=buy_order.price,
+                quantity=remaining_qty,
+                timestamp=buy_order.timestamp,
+            )
+            self._insert_bid(resting_order)
+
+        return trades
+
+    def _match_sell(self, sell_order: Order) -> list[Trade]:
+        """Match an incoming sell order against resting bids."""
+        trades: list[Trade] = []
+        remaining_qty = sell_order.quantity
+
+        while remaining_qty > 0 and self.bids:
+            best_bid_order = self.bids[0]
+
+            # Sell can only match if its price <= best bid price
+            if sell_order.price > best_bid_order.price:
+                break
+
+            # Determine fill quantity
+            fill_qty = min(remaining_qty, best_bid_order.quantity)
+            fill_price = best_bid_order.price  # passive order's price
+
+            trade = Trade(
+                tick=self._tick,
+                price=fill_price,
+                quantity=fill_qty,
+                buyer_id=best_bid_order.agent_id,
+                seller_id=sell_order.agent_id,
+                aggressor_side=Side.SELL,
+            )
+            trades.append(trade)
+
+            remaining_qty -= fill_qty
+            best_bid_order.quantity -= fill_qty
+
+            # Remove fully filled bid
+            if best_bid_order.quantity == 0:
+                self.bids.pop(0)
+
+        # Rest any unfilled portion in the ask book
+        if remaining_qty > 0:
+            resting_order = Order(
+                agent_id=sell_order.agent_id,
+                side=Side.SELL,
+                price=sell_order.price,
+                quantity=remaining_qty,
+                timestamp=sell_order.timestamp,
+            )
+            self._insert_ask(resting_order)
+
+        return trades
+
+    def _insert_bid(self, order: Order):
+        """Insert a bid order maintaining descending price, ascending timestamp order."""
+        import bisect
+        # For bids: we want descending price, ascending timestamp.
+        # bisect uses < operator, so we use a key that negates price but keeps timestamp positive.
+        bisect.insort(self.bids, order, key=lambda x: (-x.price, x.timestamp))
+
+    def _insert_ask(self, order: Order):
+        """Insert an ask order maintaining ascending price, ascending timestamp order."""
+        import bisect
+        # For asks: we want ascending price, ascending timestamp.
+        bisect.insort(self.asks, order, key=lambda x: (x.price, x.timestamp))
+
+    def cancel_agent_orders(self, agent_id: str):
+        """Remove all resting orders for a given agent. Used between ticks."""
+        self.bids = [o for o in self.bids if o.agent_id != agent_id]
+        self.asks = [o for o in self.asks if o.agent_id != agent_id]
+
+    def clear_book(self):
+        """Remove all resting orders. Used for book reset between experiments."""
+        self.bids.clear()
+        self.asks.clear()
+
+    def snapshot(self) -> dict:
+        """
+        Return a snapshot of the current order book state.
+        Used by market_state serializer to build the LLM prompt.
+        """
+        return {
+            "best_bid": self.best_bid,
+            "best_ask": self.best_ask,
+            "mid_price": self.mid_price,
+            "spread": self.spread,
+            "bid_depth": sum(o.quantity for o in self.bids),
+            "ask_depth": sum(o.quantity for o in self.asks),
+            "bid_levels": len(self.bids),
+            "ask_levels": len(self.asks),
+            "last_trade_price": self.trade_log[-1].price if self.trade_log else None,
+            "last_trade_qty": self.trade_log[-1].quantity if self.trade_log else None,
+            "total_trades": len(self.trade_log),
+        }
+
+    def __repr__(self) -> str:
+        bb = f"{self.best_bid:.2f}" if self.best_bid else "---"
+        ba = f"{self.best_ask:.2f}" if self.best_ask else "---"
+        sp = f"{self.spread:.4f}" if self.spread else "---"
+        return f"OrderBook(bid={bb}, ask={ba}, spread={sp}, bids={len(self.bids)}, asks={len(self.asks)})"

engine/simulation.py

@@ -0,0 +1,487 @@
+"""
+Simulation Engine — the core tick loop.
+
+Each tick:
+1. Build market state string for each agent
+2. Dispatch all agents concurrently (LLM or offline fallback)
+3. Collect orders from responses
+4. Submit orders to the order book (matching happens automatically)
+5. Update agent positions and cash from executed trades
+6. Record metrics
+7. Log to CSV
+"""
+
+import asyncio
+import csv
+import json
+import math
+import os
+import random
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from engine.order_book import OrderBook, Order, Side, Trade
+from engine.market_state import market_state_to_string
+from engine.metrics import MetricsEngine, TickMetrics
+from agents.base_agent import BaseAgent
+from agents.market_maker_agent import MarketMakerAgent
+from inference.vllm_client import VLLMClient, LLMResponse, parse_llm_output
+
+
+@dataclass
+class SimulationConfig:
+    """Configuration for a simulation run."""
+    num_ticks: int = 100
+    initial_price: float = 100.0
+    use_llm: bool = False          # False = offline deterministic mode
+    vllm_base_url: str = "http://localhost:8000/v1"
+    vllm_model: str = "Qwen/Qwen2.5-7B-Instruct"
+    output_dir: str = "output"
+    seed: int = 42
+    log_to_csv: bool = True
+    base_volatility: float = 0.005 # Random walk std dev for true fair value per tick
+    warmup_ticks: int = 15         # Ticks to run in offline mode before LLM takes over
+    enable_seed_liquidity: bool = False  # Turned off by default to allow pure LLM market
+    fee_per_trade: float = 0.01          # Transaction cost to prevent wash trading
+
+
+class SimulationEngine:
+    """
+    Core simulation loop.
+
+    Orchestrates: agents → LLM/offline → orders → order book → trades → metrics.
+    """
+
+    def __init__(self, agents: list[BaseAgent], config: SimulationConfig):
+        self.agents = agents
+        self.config = config
+        self.book = OrderBook()
+        self.metrics = MetricsEngine()
+        self.price_history: list[float] = [config.initial_price]
+        self.true_fair_value: float = config.initial_price
+        self.tick = 0
+
+        # LLM client (only initialized if use_llm=True)
+        self.llm_client: VLLMClient | None = None
+        if config.use_llm:
+            self.llm_client = VLLMClient(
+                base_url=config.vllm_base_url,
+                model=config.vllm_model,
+            )
+
+        # CSV logging
+        self.csv_rows: list[dict] = []
+        self.trade_rows: list[dict] = []
+        self.agent_pnl_rows: list[dict] = []
+
+        # Seed for reproducibility
+        random.seed(config.seed)
+
+        # Latency tracking for AMD benchmarking
+        self.latencies: list[float] = []
+
+    def run(self):
+        """Run the full simulation synchronously."""
+        for _ in self.run_generator():
+            pass
+
+    def run_generator(self):
+        """Run the simulation as a generator, yielding after each tick. Useful for live UIs."""
+        print(f"Starting simulation: {self.config.num_ticks} ticks, "
+              f"{'LLM' if self.config.use_llm else 'offline'} mode, "
+              f"{len(self.agents)} agents")
+        print(f"Initial price: {self.config.initial_price}")
+        print("-" * 60)
+
+        self._seed_book()
+
+        # Run the async loop synchronously step-by-step to yield
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        
+        try:
+            for tick in range(1, self.config.num_ticks + 1):
+                loop.run_until_complete(self._tick_logic(tick))
+                yield tick
+        finally:
+            loop.close()
+
+        if self.config.log_to_csv:
+            self._write_csvs()
+
+        self._print_summary()
+
+    async def _run_async(self):
+        """Async tick loop (Legacy)."""
+        for tick in range(1, self.config.num_ticks + 1):
+            await self._tick_logic(tick)
+
+    async def _tick_logic(self, tick: int):
+        """Logic for a single tick."""
+        self.tick = tick
+        self.book.set_tick(tick)
+
+        # --- Exogenous Volatility (Realism update) ---
+        # Drift the true macroeconomic fair value using a geometric random walk
+        drift = random.gauss(0, self.config.base_volatility)
+        self.true_fair_value *= (1 + drift)
+        self.true_fair_value = max(0.01, self.true_fair_value)  # Prevent negative/zero prices
+
+        # Broadcast new macroeconomic reality to agents (only Fundamental agents care)
+        for agent in self.agents:
+            agent.update_fair_value(self.true_fair_value)
+
+        # 1. Dispatch all agents, collect orders
+        orders = await self._dispatch_agents()
+
+        # 2. Process intentional cancellations (agents submit "cancel" in orders)
+        # The mandatory wipe is removed to create a true CDA
+
+        # 3. Refresh seed liquidity if enabled
+        if self.config.enable_seed_liquidity:
+            self.book.cancel_agent_orders("_seed")
+            self._refresh_seed_liquidity()
+
+        # 4. Submit orders to the book
+        tick_trades: list[Trade] = []
+        for order in orders:
+            if order.side == "cancel":
+                # Special case for explicit cancel
+                self.book.cancel_agent_orders(order.agent_id)
+            else:
+                trades = self.book.submit_order(order)
+                tick_trades.extend(trades)
+
+        # 5. Update agent states from trades
+        for trade in tick_trades:
+            self._apply_trade(trade)
+
+        # 6. Record mid price (always append to keep continuous series)
+        mid = self.book.mid_price
+        effective_price = mid if mid is not None else self.price_history[-1]
+        self.price_history.append(effective_price)
+        for agent in self.agents:
+            agent.update_price_history(effective_price)
+
+        # 7. Record metrics
+        tick_metrics = TickMetrics(
+            tick=tick,
+            mid_price=mid,
+            best_bid=self.book.best_bid,
+            best_ask=self.book.best_ask,
+            spread=self.book.spread,
+            trade_count=len(tick_trades),
+            volume=sum(t.quantity for t in tick_trades),
+        )
+        self.metrics.record_tick(tick_metrics)
+
+        # 8. CSV row
+        self._record_csv_row(tick, tick_metrics, tick_trades)
+
+        # Progress
+        if tick % 10 == 0 or tick == 1:
+            regime = self.metrics.classify_regime()
+            price_str = f"{mid:.2f}" if mid else "---"
+            spread_str = f"{self.book.spread:.4f}" if self.book.spread else "---"
+            print(f"  Tick {tick:4d} | Price: {price_str} | "
+                  f"Spread: {spread_str} | Trades: {len(tick_trades)} | "
+                  f"Regime: {regime}")
+
+    def _seed_book(self):
+        """Place initial orders so the book isn't empty on tick 1."""
+        p = self.config.initial_price
+        self.book.set_tick(0)
+        # Seed bid and ask around initial price
+        self.book.submit_order(Order("_seed", Side.BUY, round(p * 0.995, 2), 10, 0))
+        self.book.submit_order(Order("_seed", Side.SELL, round(p * 1.005, 2), 10, 0))
+
+    def _refresh_seed_liquidity(self):
+        """
+        Place thin background liquidity each tick.
+        Represents passive external market participants — prevents book
+        from fully drying up in experiments without a market maker.
+        """
+        p = self.price_history[-1]
+        self.book.submit_order(Order("_seed", Side.BUY, round(p * 0.993, 2), 3, self.tick))
+        self.book.submit_order(Order("_seed", Side.SELL, round(p * 1.007, 2), 3, self.tick))
+
+    async def _dispatch_agents(self) -> list[Order]:
+        """
+        Get orders from all agents for this tick.
+        Uses offline mode during warmup_ticks, then switches to LLM.
+        """
+        if self.config.use_llm and self.tick > self.config.warmup_ticks:
+            return await self._dispatch_llm()
+        else:
+            return self._dispatch_offline()
+
+    # ── LLM mode ──────────────────────────────────────────────────
+
+    async def _dispatch_llm(self) -> list[Order]:
+        """Dispatch agents via vLLM. Uses asyncio.gather for concurrency."""
+        assert self.llm_client is not None
+
+        requests: list[tuple[str, str, str]] = []
+        for agent in self.agents:
+            state_str = market_state_to_string(
+                self.book, agent.agent_id,
+                agent.state.position, agent.state.cash,
+                agent.price_history,
+            )
+            # All agents, including MarketMaker, now make a single batched call
+            requests.append((agent.agent_id, agent.charter, state_str))
+
+        t0 = time.perf_counter()
+        responses = await self.llm_client.batch_infer(requests)
+        batch_latency = (time.perf_counter() - t0) * 1000
+        self.latencies.append(batch_latency)
+
+        return self._responses_to_orders(responses)
+
+    # ── Offline mode (deterministic fallback) ─────────────────────
+
+    def _dispatch_offline(self) -> list[Order]:
+        """
+        Deterministic order generation based on agent charter logic.
+        No LLM needed — used for local dev and testing.
+        """
+        orders: list[Order] = []
+        # Fall back to last known price when book is empty
+        mid = self.book.mid_price or self.price_history[-1]
+
+        for agent in self.agents:
+            agent_orders = self._offline_agent_logic(agent, mid)
+            orders.extend(agent_orders)
+
+        return orders
+
+    def _offline_agent_logic(self, agent: BaseAgent, mid: float) -> list[Order]:
+        """Generate orders using simple heuristics matching each agent's charter."""
+        orders: list[Order] = []
+        # Prepend a cancel order so offline heuristics don't infinitely stack orders
+        orders.append(Order(agent.agent_id, "cancel", 1.0, 1, self.tick))
+
+        prices = agent.price_history[-10:] if agent.price_history else [mid]
+
+        agent_type = agent.agent_type
+
+        if agent_type == "Momentum":
+            if len(prices) >= 3:
+                trend = prices[-1] - prices[-3]
+                if trend > 0.1:
+                    price = round(mid * 1.002, 2)
+                    orders.append(Order(agent.agent_id, Side.BUY, price, random.randint(1, 5), self.tick))
+                elif trend < -0.1:
+                    price = round(mid * 0.998, 2)
+                    orders.append(Order(agent.agent_id, Side.SELL, price, random.randint(1, 5), self.tick))
+
+        elif agent_type == "MeanReversion":
+            if len(prices) >= 5:
+                mean = sum(prices) / len(prices)
+                variance = sum((p - mean) ** 2 for p in prices) / len(prices)
+                std = math.sqrt(variance) if variance > 0 else 0.01
+                z = (mid - mean) / std if std > 0 else 0
+                if z > 1.5:
+                    price = round(mid * 0.998, 2)
+                    orders.append(Order(agent.agent_id, Side.SELL, price, random.randint(1, 4), self.tick))
+                elif z < -1.5:
+                    price = round(mid * 1.002, 2)
+                    orders.append(Order(agent.agent_id, Side.BUY, price, random.randint(1, 4), self.tick))
+
+        elif agent_type == "Fundamental":
+            from agents.fundamental_agent import FundamentalAgent
+            if isinstance(agent, FundamentalAgent):
+                fv = agent.fair_value
+                gap = (mid - fv) / fv
+                if gap < -0.03:
+                    price = round(mid * 1.001, 2)
+                    orders.append(Order(agent.agent_id, Side.BUY, price, random.randint(1, 3), self.tick))
+                elif gap > 0.03:
+                    price = round(mid * 0.999, 2)
+                    orders.append(Order(agent.agent_id, Side.SELL, price, random.randint(1, 3), self.tick))
+
+        elif agent_type == "MarketMaker":
+            # Always post both sides
+            bid_price = round(mid * 0.995, 2)
+            ask_price = round(mid * 1.005, 2)
+            qty = 5
+            if abs(agent.state.position) > 20:
+                qty = 2  # reduce size when inventory is large
+            orders.append(Order(agent.agent_id, Side.BUY, bid_price, qty, self.tick))
+            orders.append(Order(agent.agent_id, Side.SELL, ask_price, qty, self.tick))
+
+        elif agent_type == "NoiseTrader":
+            # Random action
+            action = random.choice(["buy", "sell", "hold"])
+            if action == "buy":
+                price = round(mid * random.uniform(0.995, 1.005), 2)
+                orders.append(Order(agent.agent_id, Side.BUY, price, random.randint(1, 5), self.tick))
+            elif action == "sell":
+                price = round(mid * random.uniform(0.995, 1.005), 2)
+                orders.append(Order(agent.agent_id, Side.SELL, price, random.randint(1, 5), self.tick))
+
+        return orders
+
+    # ── Response → Order conversion ───────────────────────────────
+
+    def _responses_to_orders(self, responses: dict[str, LLMResponse]) -> list[Order]:
+        """Convert LLM responses to Order objects."""
+        orders: list[Order] = []
+
+        for req_id, resp in responses.items():
+            agent_id = req_id
+
+            if resp.action == "hold":
+                continue
+
+            items_to_process = []
+            if resp.action == "orders" and resp.orders:
+                items_to_process.extend(resp.orders)
+            else:
+                items_to_process.append({"action": resp.action, "price": resp.price, "quantity": resp.quantity})
+
+            for item in items_to_process:
+                action = item.get("action")
+                if action == "hold":
+                    continue
+
+                if action == "cancel":
+                    # We pass a dummy order with side="cancel" to signal the loop to cancel this agent's orders
+                    orders.append(Order(agent_id=agent_id, side="cancel", price=1.0, quantity=1, timestamp=self.tick))
+                    continue
+
+                side = Side.BUY if action == "buy" else Side.SELL
+                try:
+                    order = Order(
+                        agent_id=agent_id,
+                        side=side,
+                        price=item.get("price"),
+                        quantity=item.get("quantity"),
+                        timestamp=self.tick,
+                    )
+                    orders.append(order)
+                except ValueError:
+                    # Invalid price/quantity — skip
+                    continue
+
+        return orders
+
+    # ── Trade application ─────────────────────────────────────────
+
+    def _apply_trade(self, trade: Trade):
+        """Update agent states after a trade."""
+        buyer = self._find_agent(trade.buyer_id)
+        seller = self._find_agent(trade.seller_id)
+
+        if buyer:
+            buyer.record_trade(Side.BUY, trade.price, trade.quantity)
+            buyer.state.cash -= self.config.fee_per_trade * trade.quantity
+        if seller:
+            seller.record_trade(Side.SELL, trade.price, trade.quantity)
+            seller.state.cash -= self.config.fee_per_trade * trade.quantity
+
+        # Log trade
+        self.trade_rows.append({
+            "tick": trade.tick,
+            "price": trade.price,
+            "quantity": trade.quantity,
+            "buyer": trade.buyer_id,
+            "seller": trade.seller_id,
+            "aggressor": trade.aggressor_side.value,
+        })
+
+    def _find_agent(self, agent_id: str) -> BaseAgent | None:
+        """Find agent by ID. Returns None for seed orders."""
+        for agent in self.agents:
+            if agent.agent_id == agent_id:
+                return agent
+        return None  # seed orders have agent_id="_seed"
+
+    # ── CSV logging ───────────────────────────────────────────────
+
+    def _record_csv_row(self, tick: int, metrics: TickMetrics, trades: list[Trade]):
+        """Record a row for the tick-level CSV."""
+        self.csv_rows.append({
+            "tick": tick,
+            "mid_price": metrics.mid_price,
+            "best_bid": metrics.best_bid,
+            "best_ask": metrics.best_ask,
+            "spread": metrics.spread,
+            "trade_count": metrics.trade_count,
+            "volume": metrics.volume,
+            "regime": self.metrics.classify_regime(),
+            "true_fair_value": self.true_fair_value,
+        })
+
+        # Agent PnL snapshot
+        current_price = metrics.mid_price or self.config.initial_price
+        for agent in self.agents:
+            self.agent_pnl_rows.append({
+                "tick": tick,
+                "agent_id": agent.agent_id,
+                "agent_type": agent.agent_type,
+                "position": agent.state.position,
+                "cash": round(agent.state.cash, 2),
+                "pnl": round(agent.mark_to_market(current_price), 2),
+                "trades": agent.state.trades_count,
+            })
+
+    def _write_csvs(self):
+        """Write all logged data to CSV files."""
+        out = Path(self.config.output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+
+        self._write_csv(out / "ticks.csv", self.csv_rows)
+        self._write_csv(out / "trades.csv", self.trade_rows)
+        self._write_csv(out / "agent_pnl.csv", self.agent_pnl_rows)
+
+        print(f"\nCSVs written to {out}/")
+
+    @staticmethod
+    def _write_csv(path: Path, rows: list[dict]):
+        if not rows:
+            return
+        with open(path, "w", newline="") as f:
+            writer = csv.DictWriter(f, fieldnames=rows[0].keys())
+            writer.writeheader()
+            writer.writerows(rows)
+
+    # ── Summary ───────────────────────────────────────────────────
+
+    def _print_summary(self):
+        """Print end-of-simulation summary."""
+        print("\n" + "=" * 60)
+        print("SIMULATION COMPLETE")
+        print("=" * 60)
+
+        summary = self.metrics.summary()
+        print(f"  Ticks:         {summary['total_ticks']}")
+        print(f"  Total Trades:  {summary['total_trades']}")
+        print(f"  Total Volume:  {summary['total_volume']}")
+        print(f"  Crash Events:  {summary['crash_events']}")
+        print(f"  Final Regime:  {summary['current_regime']}")
+        if summary['price_range']:
+            lo, hi = summary['price_range']
+            print(f"  Price Range:   {lo:.2f} — {hi:.2f}")
+        if summary['current_volatility']:
+            print(f"  Volatility:    {summary['current_volatility']:.4f}")
+
+        # Agent leaderboard
+        current_price = self.price_history[-1] if self.price_history else self.config.initial_price
+        print(f"\n  Agent PnL Leaderboard (mark-to-market at {current_price:.2f}):")
+        print(f"  {'Agent':<25s} {'Type':<15s} {'Pos':>6s} {'Cash':>10s} {'PnL':>10s} {'Trades':>7s}")
+        print(f"  {'-'*25} {'-'*15} {'-'*6} {'-'*10} {'-'*10} {'-'*7}")
+
+        ranked = sorted(self.agents, key=lambda a: a.mark_to_market(current_price), reverse=True)
+        for agent in ranked:
+            pnl = agent.mark_to_market(current_price)
+            print(f"  {agent.agent_id:<25s} {agent.agent_type:<15s} "
+                  f"{agent.state.position:>6d} {agent.state.cash:>10.2f} "
+                  f"{pnl:>10.2f} {agent.state.trades_count:>7d}")
+
+        # Latency stats (for AMD benchmarking)
+        if self.latencies:
+            avg_lat = sum(self.latencies) / len(self.latencies)
+            print(f"\n  Avg batch latency: {avg_lat:.1f} ms")
+            print(f"  Throughput: {len(self.agents) / (avg_lat / 1000):.1f} decisions/sec")

experiments/__init__.py

@@ -0,0 +1 @@
+# experiments package

experiments/baseline_run.py

@@ -0,0 +1,54 @@
+"""
+Experiment A — Baseline Run.
+
+Agent composition: 2 momentum + 1 mean-reversion + 1 fundamental + 1 market maker + 1 noise.
+Hypothesis: Prices stay near fair value. Market is relatively efficient.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from engine.simulation import SimulationEngine, SimulationConfig
+from agents.momentum_agent import MomentumAgent
+from agents.mean_reversion_agent import MeanReversionAgent
+from agents.fundamental_agent import FundamentalAgent
+from agents.market_maker_agent import MarketMakerAgent
+from agents.noise_trader import NoiseTrader
+from experiments.plot_utils import plot_experiment
+
+
+def run():
+    agents = [
+        MomentumAgent("momentum_1"),
+        MomentumAgent("momentum_2"),
+        MeanReversionAgent("meanrev_1"),
+        FundamentalAgent("fundamental_1", fair_value=100.0),
+        MarketMakerAgent("marketmaker_1"),
+        NoiseTrader("noise_1"),
+    ]
+
+    config = SimulationConfig(
+        num_ticks=200,
+        initial_price=100.0,
+        use_llm=False,
+        output_dir="output/experiment_a_baseline",
+        seed=42,
+    )
+
+    engine = SimulationEngine(agents, config)
+    engine.run()
+
+    # Generate plots
+    plot_experiment(
+        engine,
+        title="Experiment A — Baseline (Equal Mix)",
+        output_dir=config.output_dir,
+        fair_value=100.0,
+    )
+
+    return engine
+
+
+if __name__ == "__main__":
+    run()

experiments/benchmark_vllm.py

@@ -0,0 +1,86 @@
+"""
+AMD MI300X Benchmarking Script.
+
+Demonstrates the advantage of concurrent inference on AMD MI300X.
+Runs a set of agent inferences sequentially vs. batched concurrently.
+
+Run this against the live vLLM server to generate numbers for the README.
+Usage: python experiments/benchmark_vllm.py --url http://localhost:8000/v1
+"""
+
+import argparse
+import asyncio
+import time
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from inference.vllm_client import VLLMClient
+from inference.prompt_templates import MOMENTUM_CHARTER
+
+
+async def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--url", type=str, default="http://localhost:8000/v1", help="vLLM server URL")
+    parser.add_argument("--model", type=str, default="Qwen/Qwen2.5-7B-Instruct", help="Model name")
+    parser.add_argument("--agents", type=int, default=5, help="Number of concurrent agents to simulate")
+    args = parser.parse_args()
+
+    client = VLLMClient(base_url=args.url, model=args.model)
+
+    # Dummy market state for benchmarking
+    dummy_state = """Best Bid: 99.50 | Best Ask: 100.50 | Mid: 100.00 | Spread: 1.0000
+Last Trade: 100.00
+Recent Prices (last 10): [100.00, 100.00, 100.00]
+Your Position: 0 units | Your Cash: 10000.00"""
+
+    requests = [(f"agent_{i}", MOMENTUM_CHARTER, dummy_state) for i in range(args.agents)]
+
+    print(f"Connecting to vLLM at {args.url}")
+    print(f"Model: {args.model}")
+    print(f"Agents: {args.agents}")
+    print("-" * 50)
+
+    # 1. Sequential Test
+    print("Running SEQUENTIAL inference...")
+    seq_latencies = []
+    t_start_seq = time.perf_counter()
+    for req_id, sys_prompt, user_msg in requests:
+        resp = await client.infer(sys_prompt, user_msg)
+        seq_latencies.append(resp.latency_ms)
+    t_end_seq = time.perf_counter()
+    
+    seq_total_time = t_end_seq - t_start_seq
+    seq_avg_latency = sum(seq_latencies) / len(seq_latencies)
+
+    # 2. Batched (Concurrent) Test
+    print("Running BATCHED ASYNC inference...")
+    t_start_batch = time.perf_counter()
+    responses = await client.batch_infer(requests)
+    t_end_batch = time.perf_counter()
+    
+    batch_total_time = t_end_batch - t_start_batch
+    batch_avg_latency = sum(r.latency_ms for r in responses.values()) / len(responses)
+
+    print("\n" + "=" * 50)
+    print("AMD MI300X BENCHMARK RESULTS")
+    print("=" * 50)
+    print(f"Sequential Total Time:   {seq_total_time:.3f} s")
+    print(f"Sequential Avg per Call: {seq_avg_latency:.1f} ms")
+    print(f"Sequential Throughput:   {args.agents / seq_total_time:.2f} calls/sec")
+    print("-" * 50)
+    print(f"Batched Total Time:      {batch_total_time:.3f} s")
+    print(f"Batched Avg per Call:    {batch_avg_latency:.1f} ms (internal server time)")
+    print(f"Batched Throughput:      {args.agents / batch_total_time:.2f} calls/sec")
+    print("-" * 50)
+    
+    if batch_total_time > 0:
+        speedup = seq_total_time / batch_total_time
+        print(f"🚀 Concurrency Speedup: {speedup:.2f}x")
+        print("\nConclusion:")
+        print("Thanks to MI300X 192GB HBM3 memory bandwidth, vLLM easily handles")
+        print("large concurrent batch sizes without severe latency degradation.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

experiments/momentum_heavy.py

@@ -0,0 +1,52 @@
+"""
+Experiment B — Momentum Overload.
+
+Agent composition: 4 momentum + 1 noise. No fundamental anchor, no market maker.
+Hypothesis: Price trends away from fair value → bubble formation.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from engine.simulation import SimulationEngine, SimulationConfig
+from agents.momentum_agent import MomentumAgent
+from agents.market_maker_agent import MarketMakerAgent
+from agents.noise_trader import NoiseTrader
+from experiments.plot_utils import plot_experiment
+
+
+def run():
+    agents = [
+        MomentumAgent("momentum_1"),
+        MomentumAgent("momentum_2"),
+        MomentumAgent("momentum_3"),
+        MomentumAgent("momentum_4"),
+        MarketMakerAgent("marketmaker_1"),
+        NoiseTrader("noise_1"),
+    ]
+
+    config = SimulationConfig(
+        num_ticks=200,
+        initial_price=100.0,
+        use_llm=False,
+        output_dir="output/experiment_b_momentum",
+        seed=42,
+    )
+
+    engine = SimulationEngine(agents, config)
+    engine.run()
+
+    # Generate plots
+    plot_experiment(
+        engine,
+        title="Experiment B — Momentum Overload (No Anchor)",
+        output_dir=config.output_dir,
+        fair_value=100.0,
+    )
+
+    return engine
+
+
+if __name__ == "__main__":
+    run()

experiments/no_market_maker.py

@@ -0,0 +1,52 @@
+"""
+Experiment C — No Market Maker.
+
+Agent composition: 2 momentum + 1 mean-reversion + 1 fundamental + 1 noise. No market maker.
+Hypothesis: Spreads widen dramatically, liquidity fragmentation, possible crash.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from engine.simulation import SimulationEngine, SimulationConfig
+from agents.momentum_agent import MomentumAgent
+from agents.mean_reversion_agent import MeanReversionAgent
+from agents.fundamental_agent import FundamentalAgent
+from agents.noise_trader import NoiseTrader
+from experiments.plot_utils import plot_experiment
+
+
+def run():
+    agents = [
+        MomentumAgent("momentum_1"),
+        MomentumAgent("momentum_2"),
+        MeanReversionAgent("meanrev_1"),
+        FundamentalAgent("fundamental_1", fair_value=100.0),
+        NoiseTrader("noise_1"),
+    ]
+
+    config = SimulationConfig(
+        num_ticks=200,
+        initial_price=100.0,
+        use_llm=False,
+        output_dir="output/experiment_c_no_mm",
+        seed=42,
+    )
+
+    engine = SimulationEngine(agents, config)
+    engine.run()
+
+    # Generate plots
+    plot_experiment(
+        engine,
+        title="Experiment C — No Market Maker (Liquidity Test)",
+        output_dir=config.output_dir,
+        fair_value=100.0,
+    )
+
+    return engine
+
+
+if __name__ == "__main__":
+    run()

experiments/plot_utils.py

@@ -0,0 +1,136 @@
+"""
+Plotting utilities for experiment results.
+
+Generates static PNG plots for each experiment:
+1. Price series with fair value line
+2. Bid-ask spread over time
+3. Agent PnL over time
+4. Trade volume per tick
+"""
+
+import os
+from pathlib import Path
+
+try:
+    import matplotlib
+    matplotlib.use("Agg")  # Non-interactive backend
+    import matplotlib.pyplot as plt
+    HAS_MPL = True
+except ImportError:
+    HAS_MPL = False
+
+
+def plot_experiment(engine, title: str, output_dir: str, fair_value: float = 100.0):
+    """
+    Generate all experiment plots and save to output_dir.
+    Falls back to text summary if matplotlib is not installed.
+    """
+    if not HAS_MPL:
+        print(f"[WARN] matplotlib not installed — skipping plots for {title}")
+        _text_summary(engine, title, output_dir)
+        return
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    _plot_price_series(engine, title, fair_value, out)
+    _plot_spread(engine, title, out)
+    _plot_agent_pnl(engine, title, out)
+    _plot_volume(engine, title, out)
+
+    print(f"Plots saved to {out}/")
+
+
+def _plot_price_series(engine, title: str, fair_value: float, out: Path):
+    """Mid price over time with fair value reference line."""
+    ticks = [m.tick for m in engine.metrics.tick_history if m.mid_price is not None]
+    prices = [m.mid_price for m in engine.metrics.tick_history if m.mid_price is not None]
+
+    fig, ax = plt.subplots(figsize=(12, 5))
+    ax.plot(ticks, prices, linewidth=1.5, color="#2196F3", label="Mid Price")
+    ax.axhline(y=fair_value, color="#F44336", linestyle="--", linewidth=1, alpha=0.7, label=f"Fair Value ({fair_value})")
+    ax.set_xlabel("Tick")
+    ax.set_ylabel("Price")
+    ax.set_title(f"{title}\nPrice Series")
+    ax.legend()
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    fig.savefig(out / "price_series.png", dpi=150)
+    plt.close(fig)
+
+
+def _plot_spread(engine, title: str, out: Path):
+    """Bid-ask spread over time."""
+    ticks = [m.tick for m in engine.metrics.tick_history if m.spread is not None]
+    spreads = [m.spread for m in engine.metrics.tick_history if m.spread is not None]
+
+    fig, ax = plt.subplots(figsize=(12, 4))
+    ax.fill_between(ticks, spreads, alpha=0.4, color="#FF9800")
+    ax.plot(ticks, spreads, linewidth=1, color="#E65100")
+    ax.set_xlabel("Tick")
+    ax.set_ylabel("Spread")
+    ax.set_title(f"{title}\nBid-Ask Spread")
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    fig.savefig(out / "spread.png", dpi=150)
+    plt.close(fig)
+
+
+def _plot_agent_pnl(engine, title: str, out: Path):
+    """Per-agent PnL over time."""
+    # Collect PnL per agent per tick
+    agent_data: dict[str, list[tuple[int, float]]] = {}
+
+    for row in engine.agent_pnl_rows:
+        key = f"{row['agent_id']} ({row['agent_type']})"
+        if key not in agent_data:
+            agent_data[key] = []
+        agent_data[key].append((row["tick"], row["pnl"]))
+
+    colors = ["#2196F3", "#4CAF50", "#F44336", "#FF9800", "#9C27B0", "#00BCD4", "#795548", "#607D8B"]
+    fig, ax = plt.subplots(figsize=(12, 5))
+
+    for i, (label, data) in enumerate(agent_data.items()):
+        ticks = [d[0] for d in data]
+        pnls = [d[1] for d in data]
+        color = colors[i % len(colors)]
+        ax.plot(ticks, pnls, linewidth=1.2, label=label, color=color)
+
+    ax.axhline(y=0, color="gray", linestyle="-", linewidth=0.5)
+    ax.set_xlabel("Tick")
+    ax.set_ylabel("PnL")
+    ax.set_title(f"{title}\nAgent PnL")
+    ax.legend(fontsize=8, loc="best")
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    fig.savefig(out / "agent_pnl.png", dpi=150)
+    plt.close(fig)
+
+
+def _plot_volume(engine, title: str, out: Path):
+    """Trade volume per tick."""
+    ticks = [m.tick for m in engine.metrics.tick_history]
+    volumes = [m.volume for m in engine.metrics.tick_history]
+
+    fig, ax = plt.subplots(figsize=(12, 3))
+    ax.bar(ticks, volumes, width=1.0, color="#4CAF50", alpha=0.7)
+    ax.set_xlabel("Tick")
+    ax.set_ylabel("Volume")
+    ax.set_title(f"{title}\nTrade Volume per Tick")
+    ax.grid(True, alpha=0.3, axis="y")
+    fig.tight_layout()
+    fig.savefig(out / "volume.png", dpi=150)
+    plt.close(fig)
+
+
+def _text_summary(engine, title: str, output_dir: str):
+    """Fallback text summary when matplotlib is unavailable."""
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    summary = engine.metrics.summary()
+    with open(out / "summary.txt", "w") as f:
+        f.write(f"{title}\n{'=' * len(title)}\n\n")
+        for k, v in summary.items():
+            f.write(f"{k}: {v}\n")
+    print(f"Text summary saved to {out}/summary.txt")

inference/__init__.py

@@ -0,0 +1 @@
+# inference package

inference/prompt_templates.py

@@ -0,0 +1,36 @@
+"""
+Charter prompt templates for all agent types.
+
+Each charter is the system prompt the LLM receives.
+Kept tight — every extra token costs latency on the MI300X.
+"""
+
+MOMENTUM_CHARTER = """You are a momentum trader. You buy when prices are rising and sell when they are falling.
+Look at the last 10 prices. If the trend is up, submit a buy slightly above mid.
+If the trend is down, submit a sell slightly below mid. If flat, hold.
+Respond only with valid JSON: {"action": "buy"|"sell"|"hold"|"cancel", "price": <float>, "quantity": <int 1-10>}"""
+
+MEAN_REVERSION_CHARTER = """You are a mean reversion trader. You believe prices revert to their rolling average.
+If current mid price is more than 1.5 std above the 10-tick mean, sell.
+If more than 1.5 std below, buy. Otherwise hold.
+Respond only with valid JSON: {"action": "buy"|"sell"|"hold"|"cancel", "price": <float>, "quantity": <int 1-10>}"""
+
+FUNDAMENTAL_CHARTER_TEMPLATE = """You are a fundamental value investor. Your private fair value estimate is {fair_value:.2f}.
+If mid price is more than 3% below fair value, buy. If more than 3% above, sell. Otherwise hold.
+Be patient — only act when the gap is significant.
+Respond only with valid JSON: {{"action": "buy"|"sell"|"hold"|"cancel", "price": <float>, "quantity": <int 1-10>}}"""
+
+MARKET_MAKER_CHARTER = """You are a market maker. Your job is to provide liquidity by always quoting both sides.
+Post a bid 0.5% below mid and an ask 0.5% above mid. Reduce quantity if your inventory exceeds 20 units.
+You must manage your resting orders; use "cancel" if needed.
+Respond only with valid JSON containing a list of orders: 
+{"orders": [{"action": "buy"|"sell"|"cancel", "price": <float>, "quantity": <int>}]}"""
+
+NOISE_TRADER_CHARTER = """You are a noise trader. You act on irrelevant signals.
+Randomly buy or sell at a price within 1% of mid, quantity between 1 and 5.
+Respond only with valid JSON: {"action": "buy"|"sell"|"hold"|"cancel", "price": <float>, "quantity": <int 1-10>}"""
+
+
+def get_fundamental_charter(fair_value: float) -> str:
+    """Build a fundamental agent charter with a specific fair value."""
+    return FUNDAMENTAL_CHARTER_TEMPLATE.format(fair_value=fair_value)

inference/vllm_client.py

@@ -0,0 +1,204 @@
+"""
+Async vLLM inference client.
+
+Wraps the OpenAI-compatible endpoint served by vLLM on AMD MI300X.
+All agent calls go through here, batched via asyncio.gather().
+"""
+
+import asyncio
+import json
+import time
+from dataclasses import dataclass
+
+import openai
+
+
+@dataclass
+class LLMResponse:
+    """Parsed response from the LLM."""
+    action: str       # "buy", "sell", "hold", "cancel"
+    price: float
+    quantity: int
+    raw_text: str
+    latency_ms: float
+    success: bool
+    orders: list[dict] = None  # Added for multiple orders
+
+
+# Default hold response for when LLM returns garbage
+HOLD_RESPONSE = LLMResponse(
+    action="hold", price=0.0, quantity=0,
+    raw_text="fallback_hold", latency_ms=0.0, success=False,
+    orders=[]
+)
+
+
+def parse_llm_output(raw: str) -> dict | None:
+    """
+    Parse the LLM's JSON output. Returns dict or None on failure.
+    Handles common LLM failure modes: markdown wrapping, trailing text.
+    """
+    text = raw.strip()
+
+    # Strip markdown code fences if present
+    if text.startswith("```"):
+        lines = text.split("\n")
+        # Remove first and last lines (```json and ```)
+        lines = [l for l in lines if not l.strip().startswith("```")]
+        text = "\n".join(lines).strip()
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        # Try to find JSON object in the text
+        start = text.find("{")
+        end = text.rfind("}")
+        if start != -1 and end != -1 and end > start:
+            try:
+                data = json.loads(text[start:end + 1])
+            except json.JSONDecodeError:
+                return None
+        else:
+            return None
+
+    if "orders" in data and isinstance(data["orders"], list):
+        parsed_orders = []
+        for o in data["orders"]:
+            action = o.get("action", "").lower()
+            if action not in ("buy", "sell", "hold", "cancel"):
+                continue
+            if action in ("hold", "cancel"):
+                parsed_orders.append({"action": action, "price": 0.0, "quantity": 0})
+            else:
+                try:
+                    price = float(o.get("price", 0))
+                    quantity = int(o.get("quantity", 0))
+                    if price > 0 and quantity > 0:
+                        parsed_orders.append({"action": action, "price": round(price, 2), "quantity": min(quantity, 10)})
+                except (ValueError, TypeError):
+                    continue
+        return {"orders": parsed_orders}
+
+    # Validate required fields
+    action = data.get("action", "").lower()
+    if action not in ("buy", "sell", "hold", "cancel"):
+        return None
+
+    if action in ("hold", "cancel"):
+        return {"action": action, "price": 0.0, "quantity": 0}
+
+    try:
+        price = float(data.get("price", 0))
+        quantity = int(data.get("quantity", 0))
+    except (ValueError, TypeError):
+        return None
+
+    if price <= 0 or quantity <= 0:
+        return None
+
+    # Clamp quantity to spec max
+    quantity = min(quantity, 10)
+
+    return {"action": action, "price": round(price, 2), "quantity": quantity}
+
+
+class VLLMClient:
+    """
+    Async client for vLLM's OpenAI-compatible API.
+
+    Usage:
+        client = VLLMClient(base_url="http://localhost:8000/v1")
+        responses = await client.batch_infer(requests)
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000/v1",
+        api_key: str = "EMPTY",
+        model: str = "Qwen/Qwen2.5-7B-Instruct",
+        max_tokens: int = 64,
+        temperature: float = 0.3,
+    ):
+        self.client = openai.AsyncOpenAI(base_url=base_url, api_key=api_key)
+        self.model = model
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+
+    async def infer(self, system_prompt: str, user_message: str) -> LLMResponse:
+        """Single inference call. Returns parsed LLMResponse."""
+        t0 = time.perf_counter()
+        try:
+            response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_message},
+                ],
+                response_format={"type": "json_object"},
+                max_tokens=self.max_tokens,
+                temperature=self.temperature,
+            )
+            raw_text = response.choices[0].message.content or ""
+            latency_ms = (time.perf_counter() - t0) * 1000
+
+            parsed = parse_llm_output(raw_text)
+            if parsed is None:
+                return LLMResponse(
+                    action="hold", price=0.0, quantity=0,
+                    raw_text=raw_text, latency_ms=latency_ms, success=False,
+                    orders=[]
+                )
+
+            if "orders" in parsed:
+                return LLMResponse(
+                    action="orders", price=0.0, quantity=0,
+                    raw_text=raw_text, latency_ms=latency_ms, success=True,
+                    orders=parsed["orders"]
+                )
+
+            return LLMResponse(
+                action=parsed["action"],
+                price=parsed["price"],
+                quantity=parsed["quantity"],
+                raw_text=raw_text,
+                latency_ms=latency_ms,
+                success=True,
+                orders=[]
+            )
+
+        except Exception as e:
+            latency_ms = (time.perf_counter() - t0) * 1000
+            return LLMResponse(
+                action="hold", price=0.0, quantity=0,
+                raw_text=f"ERROR: {e}", latency_ms=latency_ms, success=False,
+                orders=[]
+            )
+
+    async def batch_infer(
+        self, requests: list[tuple[str, str, str]]
+    ) -> dict[str, LLMResponse]:
+        """
+        Batch inference for multiple agents concurrently.
+
+        Args:
+            requests: list of (agent_id, system_prompt, user_message)
+
+        Returns:
+            dict mapping agent_id → LLMResponse
+        """
+        async def _call(agent_id: str, sys_prompt: str, user_msg: str):
+            resp = await self.infer(sys_prompt, user_msg)
+            return agent_id, resp
+
+        tasks = [_call(aid, sp, um) for aid, sp, um in requests]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        output: dict[str, LLMResponse] = {}
+        for result in results:
+            if isinstance(result, Exception):
+                # Shouldn't happen since infer() catches exceptions, but be safe
+                continue
+            agent_id, response = result
+            output[agent_id] = response
+
+        return output

requirements.txt

@@ -0,0 +1,14 @@
+# MarketMind — Dependencies
+# Core
+openai>=1.0.0          # vLLM OpenAI-compatible client
+
+# Dashboard
+gradio>=4.0.0
+plotly>=5.18.0
+
+# Data
+pandas>=2.1.0
+numpy>=1.24.0
+
+# Utilities
+sortedcontainers>=2.4.0  # SortedList for order book

run_simulation.py

@@ -0,0 +1,68 @@
+"""
+MarketMind — Entry Point.
+
+Run a multi-agent market simulation.
+
+Usage:
+    python run_simulation.py                    # offline mode, 100 ticks
+    python run_simulation.py --ticks 200        # offline, 200 ticks
+    python run_simulation.py --llm              # vLLM mode (requires server running)
+    python run_simulation.py --llm --url http://host:8000/v1
+"""
+
+import argparse
+import sys
+
+from engine.simulation import SimulationEngine, SimulationConfig
+from agents.momentum_agent import MomentumAgent
+from agents.mean_reversion_agent import MeanReversionAgent
+from agents.fundamental_agent import FundamentalAgent
+from agents.market_maker_agent import MarketMakerAgent
+from agents.noise_trader import NoiseTrader
+
+
+def build_default_agents() -> list:
+    """
+    Default agent composition: the baseline 5-agent mix.
+    Per spec Experiment A: 2 momentum + 1 mean-reversion + 1 fundamental + 1 noise.
+    Plus 1 market maker for liquidity.
+    """
+    return [
+        MomentumAgent("momentum_1"),
+        MomentumAgent("momentum_2"),
+        MeanReversionAgent("meanrev_1"),
+        FundamentalAgent("fundamental_1", fair_value=100.0),
+        MarketMakerAgent("marketmaker_1"),
+        NoiseTrader("noise_1"),
+    ]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="MarketMind Simulation")
+    parser.add_argument("--ticks", type=int, default=100, help="Number of simulation ticks")
+    parser.add_argument("--price", type=float, default=100.0, help="Initial price")
+    parser.add_argument("--llm", action="store_true", help="Use vLLM inference (requires server)")
+    parser.add_argument("--url", type=str, default="http://localhost:8000/v1", help="vLLM server URL")
+    parser.add_argument("--model", type=str, default="Qwen/Qwen2.5-7B-Instruct", help="Model name")
+    parser.add_argument("--output", type=str, default="output", help="Output directory for CSVs")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed for reproducibility")
+    args = parser.parse_args()
+
+    config = SimulationConfig(
+        num_ticks=args.ticks,
+        initial_price=args.price,
+        use_llm=args.llm,
+        vllm_base_url=args.url,
+        vllm_model=args.model,
+        output_dir=args.output,
+        seed=args.seed,
+    )
+
+    agents = build_default_agents()
+
+    engine = SimulationEngine(agents, config)
+    engine.run()
+
+
+if __name__ == "__main__":
+    main()

tests/test_agents_smoke.py

@@ -0,0 +1,52 @@
+"""Quick smoke test for all Phase 2 imports."""
+import sys
+sys.path.insert(0, ".")
+
+from engine.order_book import OrderBook, Order, Side, Trade
+from engine.market_state import market_state_to_string
+from engine.metrics import MetricsEngine, TickMetrics
+from agents.base_agent import BaseAgent, AgentState
+from agents.momentum_agent import MomentumAgent
+from agents.mean_reversion_agent import MeanReversionAgent
+from agents.fundamental_agent import FundamentalAgent
+from agents.market_maker_agent import MarketMakerAgent
+from agents.noise_trader import NoiseTrader
+from inference.prompt_templates import MOMENTUM_CHARTER, get_fundamental_charter
+from inference.vllm_client import VLLMClient, parse_llm_output
+
+# Instantiate each agent
+agents = [
+    MomentumAgent("mom_1"),
+    MomentumAgent("mom_2"),
+    MeanReversionAgent("mr_1"),
+    FundamentalAgent("fund_1", fair_value=100.0),
+    MarketMakerAgent("mm_1"),
+    NoiseTrader("noise_1"),
+]
+for a in agents:
+    print(f"  {a.agent_type:15s} id={a.agent_id}")
+
+# Verify fundamental charter has fair value
+f = FundamentalAgent("f_test", fair_value=42.50)
+assert "42.50" in f.charter, f"Fair value not in charter: {f.charter[:80]}"
+print("  Fundamental charter injection: OK")
+
+# Test JSON parser
+assert parse_llm_output('{"action":"buy","price":99.5,"quantity":3}') is not None
+assert parse_llm_output('```json\n{"action":"sell","price":101,"quantity":5}\n```') is not None
+assert parse_llm_output("garbage") is None
+assert parse_llm_output('{"action":"hold"}')["action"] == "hold"
+print("  LLM output parser: OK")
+
+# Test market state serializer
+book = OrderBook()
+book.set_tick(1)
+book.submit_order(Order("b1", Side.BUY, 99.0, 5, 1))
+book.submit_order(Order("s1", Side.SELL, 101.0, 5, 2))
+state_str = market_state_to_string(book, "m1", 0, 10000.0, [100.0, 99.5, 100.2])
+assert "Best Bid: 99.00" in state_str
+assert "Best Ask: 101.00" in state_str
+assert "Your Position: 0 units" in state_str
+print("  Market state serializer: OK")
+
+print("\nAll Phase 2 checks passed.")

tests/test_order_book.py

@@ -0,0 +1,247 @@
+"""
+Unit tests for the CDA Order Book engine.
+
+Tests per Phase 1 spec:
+- Crossing orders execute correctly
+- Non-crossing orders rest in book
+- Price-time priority
+- Partial fills
+- Trade log accuracy
+"""
+
+import sys
+import os
+
+# Add parent to path so we can import marketmind
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from engine.order_book import OrderBook, Order, Side, Trade
+
+
+def test_non_crossing_orders_rest():
+    """Non-crossing orders should rest in the book without matching."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    # Bid at 99, Ask at 101 — no cross
+    bid = Order(agent_id="agent_a", side=Side.BUY, price=99.0, quantity=5, timestamp=1)
+    ask = Order(agent_id="agent_b", side=Side.SELL, price=101.0, quantity=5, timestamp=1)
+
+    trades_bid = book.submit_order(bid)
+    trades_ask = book.submit_order(ask)
+
+    assert trades_bid == [], "Non-crossing bid should not produce trades"
+    assert trades_ask == [], "Non-crossing ask should not produce trades"
+    assert book.best_bid == 99.0
+    assert book.best_ask == 101.0
+    assert book.mid_price == 100.0
+    assert book.spread == 2.0
+    assert len(book.bids) == 1
+    assert len(book.asks) == 1
+    print("✓ test_non_crossing_orders_rest")
+
+
+def test_crossing_orders_execute():
+    """When a buy crosses the ask, a trade should execute."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    # Resting ask at 100
+    ask = Order(agent_id="seller", side=Side.SELL, price=100.0, quantity=5, timestamp=1)
+    book.submit_order(ask)
+
+    # Incoming buy at 100 — crosses the ask
+    buy = Order(agent_id="buyer", side=Side.BUY, price=100.0, quantity=5, timestamp=2)
+    trades = book.submit_order(buy)
+
+    assert len(trades) == 1
+    t = trades[0]
+    assert t.price == 100.0
+    assert t.quantity == 5
+    assert t.buyer_id == "buyer"
+    assert t.seller_id == "seller"
+    assert t.aggressor_side == Side.BUY
+    # Both sides fully filled — book should be empty
+    assert len(book.bids) == 0
+    assert len(book.asks) == 0
+    print("✓ test_crossing_orders_execute")
+
+
+def test_partial_fill():
+    """A larger buy should partially fill against a smaller ask, with residual resting."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    # Resting ask: 3 units at 100
+    ask = Order(agent_id="seller", side=Side.SELL, price=100.0, quantity=3, timestamp=1)
+    book.submit_order(ask)
+
+    # Incoming buy: 5 units at 100 — should fill 3, rest 2
+    buy = Order(agent_id="buyer", side=Side.BUY, price=100.0, quantity=5, timestamp=2)
+    trades = book.submit_order(buy)
+
+    assert len(trades) == 1
+    assert trades[0].quantity == 3
+    assert len(book.asks) == 0  # ask fully consumed
+    assert len(book.bids) == 1  # residual buy rests
+    assert book.bids[0].quantity == 2
+    assert book.bids[0].agent_id == "buyer"
+    print("✓ test_partial_fill")
+
+
+def test_price_priority():
+    """Best price should match first (highest bid, lowest ask)."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    # Two bids at different prices
+    bid_low = Order(agent_id="bidder_low", side=Side.BUY, price=98.0, quantity=5, timestamp=1)
+    bid_high = Order(agent_id="bidder_high", side=Side.BUY, price=100.0, quantity=5, timestamp=2)
+    book.submit_order(bid_low)
+    book.submit_order(bid_high)
+
+    assert book.best_bid == 100.0, f"Best bid should be 100, got {book.best_bid}"
+
+    # Incoming sell at 99 — should match the 100 bid (better price), not the 98 bid
+    sell = Order(agent_id="seller", side=Side.SELL, price=99.0, quantity=3, timestamp=3)
+    trades = book.submit_order(sell)
+
+    assert len(trades) == 1
+    assert trades[0].buyer_id == "bidder_high"
+    assert trades[0].price == 100.0  # fills at passive order's price
+    assert trades[0].quantity == 3
+    print("✓ test_price_priority")
+
+
+def test_time_priority():
+    """At the same price level, earlier orders should fill first (FIFO)."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    # Two asks at same price, different timestamps
+    ask_early = Order(agent_id="early_seller", side=Side.SELL, price=100.0, quantity=5, timestamp=1)
+    ask_late = Order(agent_id="late_seller", side=Side.SELL, price=100.0, quantity=5, timestamp=2)
+    book.submit_order(ask_early)
+    book.submit_order(ask_late)
+
+    # Buy 3 at 100 — should match the earlier ask
+    buy = Order(agent_id="buyer", side=Side.BUY, price=100.0, quantity=3, timestamp=3)
+    trades = book.submit_order(buy)
+
+    assert len(trades) == 1
+    assert trades[0].seller_id == "early_seller"
+    print("✓ test_time_priority")
+
+
+def test_multi_level_fill():
+    """A large aggressive order should sweep through multiple price levels."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    # Ask book: 3 @ 100, 5 @ 101, 2 @ 102
+    book.submit_order(Order("s1", Side.SELL, 100.0, 3, 1))
+    book.submit_order(Order("s2", Side.SELL, 101.0, 5, 2))
+    book.submit_order(Order("s3", Side.SELL, 102.0, 2, 3))
+
+    # Buy 7 @ 102 — should eat through 100 and 101 levels
+    buy = Order(agent_id="buyer", side=Side.BUY, price=102.0, quantity=7, timestamp=4)
+    trades = book.submit_order(buy)
+
+    assert len(trades) == 2
+    assert trades[0].price == 100.0 and trades[0].quantity == 3  # first level
+    assert trades[1].price == 101.0 and trades[1].quantity == 4  # partial second level
+
+    # s2 should have 1 unit remaining at 101
+    assert len(book.asks) == 2
+    assert book.asks[0].price == 101.0
+    assert book.asks[0].quantity == 1
+    assert book.asks[1].price == 102.0
+    # No residual buy (7 filled: 3 + 4)
+    assert len(book.bids) == 0
+    print("✓ test_multi_level_fill")
+
+
+def test_trade_log():
+    """Trade log should accumulate all executed trades."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    book.submit_order(Order("s1", Side.SELL, 100.0, 5, 1))
+    book.submit_order(Order("b1", Side.BUY, 100.0, 3, 2))
+
+    book.set_tick(2)
+    book.submit_order(Order("s2", Side.SELL, 99.0, 2, 3))
+    book.submit_order(Order("b2", Side.BUY, 99.0, 2, 4))
+
+    assert len(book.trade_log) == 2
+    assert book.trade_log[0].tick == 1
+    assert book.trade_log[1].tick == 2
+    print("✓ test_trade_log")
+
+
+def test_snapshot():
+    """Snapshot should return correct book state."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    book.submit_order(Order("b1", Side.BUY, 99.0, 10, 1))
+    book.submit_order(Order("s1", Side.SELL, 101.0, 8, 2))
+
+    snap = book.snapshot()
+    assert snap["best_bid"] == 99.0
+    assert snap["best_ask"] == 101.0
+    assert snap["mid_price"] == 100.0
+    assert snap["spread"] == 2.0
+    assert snap["bid_depth"] == 10
+    assert snap["ask_depth"] == 8
+    assert snap["last_trade_price"] is None  # no trades yet
+    print("✓ test_snapshot")
+
+
+def test_cancel_agent_orders():
+    """Canceling an agent's orders should remove only their orders."""
+    book = OrderBook()
+    book.set_tick(1)
+
+    book.submit_order(Order("a1", Side.BUY, 99.0, 5, 1))
+    book.submit_order(Order("a2", Side.BUY, 98.0, 5, 2))
+    book.submit_order(Order("a1", Side.SELL, 102.0, 5, 3))
+
+    book.cancel_agent_orders("a1")
+
+    assert len(book.bids) == 1
+    assert book.bids[0].agent_id == "a2"
+    assert len(book.asks) == 0
+    print("✓ test_cancel_agent_orders")
+
+
+def test_self_trade_prevention_not_required():
+    """
+    Note: The spec doesn't require self-trade prevention.
+    Documenting that an agent CAN match against itself (this is fine in a simulation).
+    """
+    book = OrderBook()
+    book.set_tick(1)
+
+    book.submit_order(Order("same_agent", Side.SELL, 100.0, 5, 1))
+    trades = book.submit_order(Order("same_agent", Side.BUY, 100.0, 3, 2))
+
+    # Self-trade is allowed in this simulation
+    assert len(trades) == 1
+    assert trades[0].buyer_id == "same_agent"
+    assert trades[0].seller_id == "same_agent"
+    print("✓ test_self_trade (allowed in simulation)")
+
+
+if __name__ == "__main__":
+    test_non_crossing_orders_rest()
+    test_crossing_orders_execute()
+    test_partial_fill()
+    test_price_priority()
+    test_time_priority()
+    test_multi_level_fill()
+    test_trade_log()
+    test_snapshot()
+    test_cancel_agent_orders()
+    test_self_trade_prevention_not_required()
+    print("\n✅ All order book tests passed.")