CoinGecko (BTC OHLCV)         alternative.me (Fear & Greed)
         │                              │
         └──────────────┬───────────────┘
                        ▼
             ┌─────────────────────┐
             │   data/loader.py    │  aligned daily features
             └─────────┬───────────┘
                       ▼
  ┌──────────────────────────────────────────┐
  │     5 independent signal modules         │  each → score in [-1, +1]
  │  momentum(0.30)  fear_greed(0.25)        │
  │  funding(0.15)   flows(0.15)   vol(0.15) │
  └──────────────────────┬───────────────────┘
                         ▼ weighted fusion
                  composite score
                         ▼ priority rules
  ┌──────────────────────────────────────────┐
  │   5-state regime classifier              │  CAPITULATION > EUPHORIA >
  │   (deterministic, no look-ahead)         │  RISK_OFF   > RISK_ON >
  └──────────────────────┬───────────────────┘                          > RANGE_BOUND
                         ▼
                target exposure + action
           ┌───────────────┴───────────────┐
           ▼                               ▼
    vectorized backtest                MCP tool: get_market_regime
    (no look-ahead, w/ costs)          (stdio, Agent Hub skill)

git clone https://github.com/aggreyeric/bnb-market-regime-oracle.git
cd bnb-market-regime-oracle
pip install -r requirements.txt

# Run full pipeline: fetch → classify → backtest → charts
python main.py

# Run tests (offline, no network needed)
PYTHONPATH=src python -m pytest tests/

# Run as MCP server
PYTHONPATH=src python -m market_regime_oracle.mcp_server

# Live MCP demo (30 seconds)
./scripts/demo.sh

docker compose up --build run    # full pipeline
docker compose up --build server # MCP server

market_regime_oracle/
├── src/market_regime_oracle/
│   ├── data/          # CoinGecko + alternative.me loaders
│   ├── signals/       # 5 signal modules (unit-tested)
│   ├── classifier/    # fusion → regime mapping
│   ├── backtest/      # vectorized engine, no look-ahead
│   ├── viz/           # equity/drawdown/regime charts
│   └── mcp_server.py  # MCP stdio server
├── tests/             # 24/24 passing
├── results/           # CSVs, metrics.json, PNG charts
├── scripts/demo.sh    # live MCP round-trip
├── Dockerfile
├── docker-compose.yml
└── README.md