Repository

Run it yourself

Everything is in github.com/jahrfm/trading-components — code, the runs/*.json audit trail for all 45 backtests, and the HANDOFF that records every decision and caveat. The framework is pure Python (pandas/numpy/scipy + ccxt, yfinance, cot_reports), stdlib-adjacent, and runs on any machine.

Layout

Repo structure

trading-components/
├── trading-tools-eval/          # the whole evaluation framework
│   ├── src/
│   │   ├── config.py            # symbols, timeframes, cost schedule, regime periods, WF windows
│   │   ├── data/                # bybit.py (ccxt) · yfinance_source.py · cot.py (CFTC) · schema.py
│   │   ├── backtest/            # engine.py (no-lookahead) · costs.py · walkforward.py · sweep.py
│   │   ├── evaluation/          # metrics.py · significance.py · pass_bar.py · regime_split.py · regime_filter_eval.py
│   │   └── signals/             # one module per tool, grouped by element (16 families)
│   ├── scripts/                 # one run_<tool>.py per tool → writes runs/<tool>.json
│   ├── runs/                    # 46 JSON audit files (45 backtests + multiple-testing correction)
│   ├── tests/                   # 85 unit tests across 9 modules (engine, costs, metrics, pass bars, …)
│   ├── data/cache/              # parquet cache, regenerable (gitignored)
│   ├── HANDOFF.md               # the full project record: results table, caveats, known issues, methodology
│   ├── pyproject.toml           # pytest config
│   └── requirements.txt
├── site/                        # this website (static, no build step)
│   ├── index.html … repo.html
│   ├── assets/                  # style.css · site.js · results_data.json (generated)
│   └── scripts/build_results_data.py   # regenerates the results dataset from runs/
└── handoff_prompt.md            # the original task brief
Setup

From zero to a backtest in five commands

git clone git@github.com:jahrfm/trading-components.git
cd trading-components/trading-tools-eval
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# run one tool end-to-end (Trend / Moving Average Crossover):
python scripts/run_moving_average_crossover.py

# run the whole test suite:
python -m pytest tests/

The first run pulls and caches market data (a full BTCUSDT 1h history takes ~10 min against Bybit rate limits; daily data is fast). Keep data/cache/ between runs — it's gitignored and regenerable.

Dependencies

The stack

PackageUsed for
ccxt ≥ 4.3Bybit v5 perp OHLCV + funding history (public endpoints, no key)
yfinance ≥ 0.2.40Traditional-market OHLCV (SPY, QQQ, TLT, GLD, VIX, …)
pandas / numpy / scipyData frames, vectorized engine, Spearman IC, stats
pyarrowParquet cache
archGARCH conditional-volatility estimation
hmmlearnHidden Markov Model regime classifier
cot_reportsCFTC Commitment of Traders report (free, no auth)
pytest85-test suite
Extending

Adding a new tool

  1. Fetch the element page + "— Tools" sub-database from the master Notion spec.
  2. Triage data availability first — check for a free source before assuming blocked (CFTC COT is the template), and ask before building a nontrivial new fetcher.
  3. Pick the closest of the 20 methodology patterns documented in HANDOFF.md (simple directional, continuous/IC, regime-filter classifier, risk-input overlay, portfolio-construction allocation, execution-input forecast-error, comparative hypothesis, …).
  4. Run locally, review the JSON summary, then write Test Status + Result Summary to Notion — the user reviews every write-back.
Standing invitation to be stricter: several "Validated (marginal)" results pass only because the regime-filter / risk-input bars use OR logic. Re-running those with an AND bar would likely relabel HMM, ATR, Kelly, and friends Rejected — the HANDOFF explicitly leaves that call open.
Status

Complete as scoped — with optional next steps

The project is complete: all 18 elements covered, multiple-testing correction run (zero status changes). Nothing further is required. Natural extensions, when the user asks: