player-coach-core 1.0.1

Adversarial quality loop for trading decisions

Crucible Player-Coach

An adversarial quality loop for trading decisions. A CoachAgent challenges and refines a PlayerAgent's proposals before execution. Every proposal, rejection, revision, and approval is recorded as a structured artifact.

Part of the Crucible project series — see also crucible-ewm.

---

How it works

The PlayerAgent proposes trading actions given the current market state. The CoachAgent evaluates every proposal against a formal constraint schema — mechanically, against numbers, not vaguely. If the proposal violates a constraint, the Coach rejects it with a specific critique. The Player revises and resubmits. This continues for up to three rounds.

The result is not just a trading decision. It is a structured artifact: every proposal, every rejection, every revision, every approval — recorded, validated, and queryable.

---

Installation

# Core infrastructure
pip install player-coach-core

# With LLM agents
pip install player-coach-core[llm]

# With Streamlit dashboard
pip install player-coach-core[dashboard]

Requires ANTHROPIC_API_KEY for LLM agents.

---

Quick start

from player_coach.agents.player import PlayerAgent
from player_coach.agents.coach import CoachAgent
from player_coach.artifacts.writer import ArtifactWriter
from player_coach.constraints.schema import ConstraintSchema
from player_coach.loop.coach_loop import CoachLoop
import json
from pathlib import Path

constraints = ConstraintSchema.from_dict(
    json.loads(Path("examples/constraints/moderate.json").read_text())
)

loop = CoachLoop(
    player=PlayerAgent(),
    coach=CoachAgent(),
    artifact_writer=ArtifactWriter("artifacts"),
)

artifact = loop.run(
    world_state={
        "symbol": "AMZN", "price": 185.0,
        "sma5": 183.0, "sma10": 180.0,
        "volume": 45_000_000, "position": "flat",
        "volatility_regime": "medium", "session": "NY_open",
    },
    constraints=constraints,
)

print(f"Outcome: {artifact['outcome']}")
print(f"Rounds:  {artifact['rounds_taken']}")

---

Dashboard

A four-page Streamlit app for running and reviewing player-coach exchanges.

streamlit run dashboard/app.py

Trade Review — Run a live exchange. Player and Coach characters animate with streaming speech bubbles. Round cards show proposals, verdicts, violations, and critique.

Constraints — Configure the Coach's constraint schema. Load presets, adjust sliders, export JSON, or push directly to the Trade Review page.

History — Browse past exchanges from SQLite. Filter by outcome. Select any row to inspect rounds and replay with animation.

Settings — BYOK API key entry and validation. Key lives in session memory only, never stored.

---

Constraint schema

{
  "max_position_pct": 0.15,
  "max_single_trade_pct": 0.05,
  "max_leverage": 1.5,
  "max_drawdown_pct": 0.10,
  "max_daily_loss_pct": 0.02,
  "consistency_rule_pct": 0.50,
  "trading_cutoff_time": "16:20",
  "allowed_symbols": ["AMZN", "MSFT", "TSLA", "BTC-USD"],
  "max_open_positions": 3,
  "min_risk_reward": 1.5,
  "max_rounds": 3,
  "abort_on_violations": ["max_leverage", "max_drawdown_pct"]
}

Five presets in examples/constraints/: conservative, moderate, aggressive, strict, futures_compatible.

---

Architecture

Component	Role
PlayerAgent	Proposes 1–3 actions given world state. Claude Haiku, max_tokens=512.
CoachAgent	Evaluates proposals against constraint schema. max_tokens=1024.
CoachLoop	Orchestrates exchange. Up to 3 rounds. Writes artifact to disk and SQLite.
circuit_breakers	MLL, daily loss limit, consistency rule, trading cutoff — pure functions.
ConstraintDeriver	Derives constraint schema from ewm-core evidence policy.
BacktestRunner	Replays CoachLoop over historical trading days via yfinance.
DatabaseStore	SQLite persistence for exchanges, rounds, strategies, portfolio snapshots.

---

Circuit breakers

Four hard stops checked before every round, in priority order:

1. MLL breached — peak drawdown exceeded, account terminated
2. Daily loss limit — today's loss too large, skip today
3. Consistency rule — today's gain exceeds fraction of cumulative, skip today
4. Trading cutoff — market hours ended, skip today

---

Related

Repo	What
crucible-ewm	Observable agent trajectories, evidence policy, ewm-core
beyond-tokens	Constrained LLM planning on AWS Bedrock

---

Essays

Essay	Description
Essay 8a — Theory (coming soon)	Adversarial quality in agent systems
Essay 8b — Implementation (coming soon)	How player-coach works

Published on Substack.

---

Project status

v1.0.0 — complete. Backend, dashboard, tests, and PyPI package all shipped.

Backlog: AWS AgentCore deployment — PlayerAgent and CoachAgent as separate Lambda functions, Step Functions orchestration, artifacts to S3.