STS — Shadow Trading System (Public Skeleton)

STS is a shadow-mode trading system skeleton designed to demonstrate how a live decision pipeline can be built with strict governance, risk isolation, and reproducibility, without exposing any proprietary trading logic or alpha.

This repository intentionally focuses on system architecture, not strategy.

---

What this repository is

• A live shadow trading pipeline (no real orders are sent)
• Deterministic, auditable decision flow
• Explicit market gating (e.g. OOD / freeze / cooldown)
• Daily monitoring & summary generation
• Public-safe mock cluster model for demonstration

You can run this repo end-to-end and observe how signals, states, and summaries are produced — even without any trained model.

---

What this repository is NOT

• ❌ No trading strategy or alpha is included
• ❌ No predictive model is provided
• ❌ Not a “how to make money” project
• ❌ Not connected to any live broker or account

All real models, features, and data pipelines are deliberately excluded.

---

Architecture overview

Market Data (public candles)
        ↓
Market / OOD Gate
        ↓
Decision Layer (Shadow Only)
        ↓
Risk & Cooldown Layer
        ↓
Signals / Equity / Trades (log only)
        ↓
Daily Summary & Monitoring

Key design principles:

• Shadow-first: observe before acting
• Freeze by default: FLAT is a valid state
• Explicit reasons: every FLAT / block has a reason
• Replaceable adapters: broker & model are swappable

---

Quick demo (mock mode, safe FLAT)

This demo runs the system using public market candles and a mock cluster model that always returns OOD, ensuring no trades are generated.

1) Run shadow process

python -u src/live_shadow_v0.py   --inst BTC-USDT   --bar 15m   --out-dir reports/live/demo_cluster_mock   --poll-sec 60   --cluster-model data/models/cluster/cluster_model_v2_derived.joblib

The model path does not need to exist.
The system will automatically fall back to MockClusterModel.

2) Generate daily summary

python -u src/summarize_live_daily.py   --baseline-dir reports/live/demo_cluster_mock   --cluster-dir reports/live/demo_cluster_mock   --out-daily-dir reports/live/_daily

Outputs:

reports/live/_daily/
  daily_baseline_YYYYMMDD.json
  daily_cluster_YYYYMMDD.json
  daily_compare_YYYYMMDD.json

---

Repository structure

src/
  live_shadow_v0.py        # core shadow decision engine
  summarize_live_daily.py # daily monitoring / reporting
  risk_sizing_v0.py       # offline sizing utility
  mock_cluster_model.py   # public-safe demo stub

scripts/
  shadow_start.bat
  shadow_start_cluster.bat
  shadow_stop.bat

docs/
  DECISIONS.md   # feature freeze & governance
  V3_SCOPE.md    # explicitly defined future scope
  INCIDENTS.md   # incident & anomaly notes

reports/
  samples/       # sample outputs (no real data)

---

Design philosophy

This project treats doing nothing as a valid outcome.

A system that stays FLAT under uncertainty is preferred to one that forces trades without justification.

---

License & usage

This repository is provided for educational and architectural reference. You are free to reuse the system design, but no trading logic or performance claims are implied.

---

Author

Built by Seana Hsu
Focus areas: live trading systems, decision governance, risk-aware architecture.