crucible-quant 0.1.0__tar.gz

crucible_quant-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: python -m pip install -e ".[dev,report]"   # report extra so the tearsheet tests run
+      - name: Run tests
+        run: python -m pytest -q
+      - name: Run quickstart (smoke test)
+        run: python examples/quickstart.py

crucible_quant-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: Release
+
+# Tag-triggered publish to PyPI via Trusted Publishing (OIDC — no stored tokens).
+# Push a tag that matches the pyproject version, e.g.:
+#     git tag v0.1.0 && git push origin v0.1.0
+# Or run manually (workflow_dispatch) to publish the current build to TestPyPI.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish a manual run"
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Guard — tag must match pyproject version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          echo "tag=v$TAG  pyproject=$VER"
+          test "$TAG" = "$VER" || { echo "::error::tag v$TAG does not match pyproject version $VER"; exit 1; }
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    # tag push -> PyPI; manual run -> PyPI only if explicitly chosen
+    if: github.event_name == 'push' || inputs.target == 'pypi'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

crucible_quant-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# venv
+.venv/
+venv/
+env/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

crucible_quant-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
+adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-14
+
+Initial release — the capital-free trading-edge evaluation core.
+
+### Added
+- **`crucible.edge`** — the capital-free core (numpy/pandas only):
+  - `TradeLog` — the one schema everything speaks (`r` in R-multiples, plus
+    optional `mfe` / `mae` / `bars_held` / `prob` / `entry_date` / `exit_date`).
+  - Edge metrics — `expectancy`, `profit_factor`, `payoff_ratio`, `win_rate`,
+    `sqn`, and the excursion family (`excursion_ratio`, `e_ratio`,
+    `time_asymmetry`, `exit_efficiency`), assembled by `edge_report`.
+  - Honesty layer — `bootstrap_ci`, `p_value_positive`, `reality_check`
+    (HELD / FRAGILE / FAIL), and `random_entry_null`.
+  - `barrier_trades` — a generic OHLC + entry-signal → `TradeLog` simulator, and
+    `random_entries` for the null model.
+- **`crucible.validation`** — does the edge survive out of sample:
+  - `holdout` — leakage-controlled early-train / late-confirm split.
+  - `walk_forward` — anchored/rolling Pardo walk-forward with per-fold
+    Walk-Forward Efficiency, stitching OOS slices into one `TradeLog`.
+  - `permutation` — `sign_permutation_pvalue`, `sidak_correction`, and
+    `whites_reality_check` (max-statistic across every variant searched).
+- **`crucible.report`** (behind the `[report]` extra) — `tearsheet()` writes a
+  self-contained HTML page (verdict banner, metric scorecard, R-multiple
+  distribution, cumulative R, MFE/MAE excursion, bootstrap expectancy), and
+  `cumulative_r()`. Capital-free — charts summed R, never an equity curve.
+- **`crucible.strategies`** — `ma_cross`, `macd_cross` example signals.
+- Examples: `quickstart.py`, `validation.py`, `tearsheet.py` (synthetic, no
+  network), and `real_data_yfinance.py` (real prices via the `[examples]` extra).
+- CI across Python 3.9–3.12; tag-triggered PyPI release via Trusted Publishing.
+
+[Unreleased]: https://github.com/mspinola/crucible/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mspinola/crucible/releases/tag/v0.1.0

crucible_quant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Spinola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crucible_quant-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: crucible-quant
+Version: 0.1.0
+Summary: Measure the raw mathematical edge of a trading signal — capital-free, with confidence intervals and a reality check.
+Project-URL: Homepage, https://github.com/mspinola/crucible
+Project-URL: Source, https://github.com/mspinola/crucible
+Author: Matt Spinola
+License: MIT
+License-File: LICENSE
+Keywords: backtesting,bootstrap,edge,expectancy,mae,mfe,quant,sqn,trading,walk-forward
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: yfinance>=0.2; extra == 'examples'
+Provides-Extra: ml
+Requires-Dist: scikit-learn>=1.2; extra == 'ml'
+Requires-Dist: xgboost>=1.7; extra == 'ml'
+Provides-Extra: report
+Requires-Dist: plotly>=5; extra == 'report'
+Description-Content-Type: text/markdown
+
+# crucible
+
+[![CI](https://github.com/mspinola/crucible/actions/workflows/ci.yml/badge.svg)](https://github.com/mspinola/crucible/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Measure the edge before you ever open a $100k account.**
+
+Most trading "edges" are artifacts of a small sample. `crucible.edge` takes a
+**trade log** and tells you — with a confidence interval and a p-value — whether
+the edge is real. No account, no position sizing, no equity curve. It's the thing
+you run *before* a backtester.
+
+```bash
+pip install crucible-quant              # core: metrics + stats + simulator (numpy/pandas only)
+pip install "crucible-quant[examples]"  # + yfinance, to run the demo below on real data
+```
+
+> Installed as **`crucible-quant`**, imported as **`crucible`** (`import crucible`).
+
+## 30-second example
+
+```python
+import yfinance as yf
+from crucible.edge import barrier_trades, edge_report, reality_check
+from crucible.strategies import ma_cross
+
+px = yf.download("ES=F", start="2010-01-01")       # any OHLC frame works
+entries = ma_cross(px, fast=20, slow=50)            # your signal: a boolean Series
+
+trades = barrier_trades(px, entries, side="long",   # signal -> trade log (in R)
+                        tp=2.0, sl=1.0, timeout=20)  # 2R target, 1R stop, 20-bar cap
+
+print(edge_report(trades))                          # the full capital-free scorecard
+print(reality_check(trades))                        # <-- the verdict
+```
+
+```
+======================================================
+ EDGE REPORT (capital-free)
+======================================================
+Trades              : 214
+Win rate            : 38.3 %
+------------------------------------------------------
+Expectancy          : +0.081 R      [PASS]
+Profit factor       : 1.34          [PASS]
+Payoff ratio        : 2.16          [INFO]
+SQN-100             : 1.72          [INFO]
+------------------------------------------------------
+Excursion ratio     : 1.28          [PASS]
+======================================================
+
+VERDICT (expectancy): +0.081 R   95% CI [-0.031, +0.196]
+                     p(edge>0) = 0.071        ->  FRAGILE
+  point positive, but the CI straddles zero — not distinguishable
+  from noise at this sample size. Do NOT size it up.
+```
+
+That `FRAGILE` block is the whole point: a positive expectancy that a backtester
+would have shown you as a rising equity curve is, at this sample size,
+**indistinguishable from noise**. crucible says so out loud.
+
+> Runnable versions live in [`examples/`](examples): `quickstart.py` and
+> `validation.py` use synthetic data (no network); `real_data_yfinance.py` pulls
+> real prices from Yahoo Finance (`pip install "crucible-quant[examples]"`) and runs the
+> full pipeline — try `python examples/real_data_yfinance.py --ticker QQQ`.
+
+## What's in the box
+
+- **`TradeLog`** — one documented schema (`r` in R-multiples, plus optional
+  `mfe` / `mae` / `bars_held` / `prob`). Everything speaks it.
+- **Edge metrics** — expectancy, profit factor, payoff ratio, SQN, and the
+  excursion family (MFE/MAE efficiency, E-ratio, time asymmetry, exit efficiency).
+- **The honesty layer** — `bootstrap_ci`, `p_value_positive`, `reality_check`
+  (HELD / FRAGILE / FAIL), and `random_entry_null` (did your signal beat
+  coin-flip timing on the same prices?).
+- **A generic barrier simulator** — `barrier_trades`: OHLC + a boolean entry
+  signal → a `TradeLog`. No instrument specifics.
+- **Example signals** — `ma_cross`, `macd_cross`. Demos, not endorsed edges.
+
+## Does the edge survive out of sample? — `crucible.validation`
+
+The pooled reality check tells you if an edge is real *on the whole history*.
+`crucible.validation` asks the harder question — does it hold on data the analysis
+never touched?
+
+```python
+from crucible.validation import holdout, walk_forward, sign_permutation_pvalue
+
+# 1. Early-train / late-confirm — leakage-controlled temporal split
+print(holdout(trades, "2019-01-01", embargo_weeks=8))    # verdict is the LATE period
+
+# 2. Sign-permutation p-value (Masters) — could the edge come from noise?
+print(sign_permutation_pvalue(trades))
+
+# 3. Pardo walk-forward — optimize params in-sample, confirm out-of-sample, stitch
+wf = walk_forward(px, ma_cross, param_grid={"fast": [10, 20], "slow": [50, 100]},
+                  is_days=365 * 3, oos_days=365)
+print(wf)                          # per-fold IS->OOS efficiency (WFE)
+print(reality_check(wf.stitched))  # the stitched-OOS verdict — the honest one
+```
+
+Also here: `sidak_correction` and `whites_reality_check` (max-statistic across every
+variant you searched) for when a grid search flatters the best result.
+See [`examples/validation.py`](examples/validation.py).
+
+## A shareable tearsheet — `crucible.report`
+
+```bash
+pip install "crucible-quant[report]"
+```
+
+```python
+from crucible.report import tearsheet
+tearsheet(trades, "sheet.html", title="SPY — 20/50 MA cross")
+```
+
+Writes a **self-contained** HTML page (plotly.js inlined, renders offline): the
+verdict banner, the metric scorecard, the R-multiple distribution, cumulative R,
+MFE/MAE excursion, and the bootstrap expectancy distribution behind the CI. Still
+capital-free — it charts summed **R**, never an equity curve. See
+[`examples/tearsheet.py`](examples/tearsheet.py).
+
+## What this is — and isn't
+
+✅ Trade-level edge metrics, excursion efficiency, bootstrap CIs, a random-entry
+reality check — all **capital-free**.
+
+❌ No capital, position sizing, commissions, CAGR, drawdown, or
+Monte-Carlo-on-equity. *If you want an equity curve, hand the `TradeLog` to
+[quantstats](https://github.com/ranaroussi/quantstats). crucible stops at the edge.*
+
+## Releasing
+
+Releases publish to PyPI via GitHub Actions using **Trusted Publishing** (OIDC —
+no API tokens are stored anywhere). Changes are tracked in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+**One-time setup** (maintainer, before the first publish):
+
+1. Create two GitHub environments — repo **Settings → Environments** — named
+   `pypi` and `testpypi`. (Add a required-reviewer rule on `pypi` for a manual
+   approval gate, if you want one.)
+2. Register a **pending Trusted Publisher** at
+   <https://pypi.org/manage/account/publishing/>:
+   PyPI project `crucible-quant`, owner `mspinola`, repo `crucible`, workflow
+   `release.yml`, environment `pypi`. Repeat on
+   <https://test.pypi.org/manage/account/publishing/> with environment
+   `testpypi` for dry runs.
+
+**Cutting a release:**
+
+1. Bump `version` in `pyproject.toml` and move the `CHANGELOG.md` entry from
+   *Unreleased* to the new version.
+2. (Optional dry run) **Actions → Release → Run workflow → `testpypi`**.
+3. Tag and push — the tag **must** match the `pyproject` version or the run fails:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0     # builds, twine-checks, publishes to PyPI
+   ```
+
+## License
+
+MIT

crucible_quant-0.1.0/README.md

@@ -0,0 +1,164 @@
+# crucible
+
+[![CI](https://github.com/mspinola/crucible/actions/workflows/ci.yml/badge.svg)](https://github.com/mspinola/crucible/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Measure the edge before you ever open a $100k account.**
+
+Most trading "edges" are artifacts of a small sample. `crucible.edge` takes a
+**trade log** and tells you — with a confidence interval and a p-value — whether
+the edge is real. No account, no position sizing, no equity curve. It's the thing
+you run *before* a backtester.
+
+```bash
+pip install crucible-quant              # core: metrics + stats + simulator (numpy/pandas only)
+pip install "crucible-quant[examples]"  # + yfinance, to run the demo below on real data
+```
+
+> Installed as **`crucible-quant`**, imported as **`crucible`** (`import crucible`).
+
+## 30-second example
+
+```python
+import yfinance as yf
+from crucible.edge import barrier_trades, edge_report, reality_check
+from crucible.strategies import ma_cross
+
+px = yf.download("ES=F", start="2010-01-01")       # any OHLC frame works
+entries = ma_cross(px, fast=20, slow=50)            # your signal: a boolean Series
+
+trades = barrier_trades(px, entries, side="long",   # signal -> trade log (in R)
+                        tp=2.0, sl=1.0, timeout=20)  # 2R target, 1R stop, 20-bar cap
+
+print(edge_report(trades))                          # the full capital-free scorecard
+print(reality_check(trades))                        # <-- the verdict
+```
+
+```
+======================================================
+ EDGE REPORT (capital-free)
+======================================================
+Trades              : 214
+Win rate            : 38.3 %
+------------------------------------------------------
+Expectancy          : +0.081 R      [PASS]
+Profit factor       : 1.34          [PASS]
+Payoff ratio        : 2.16          [INFO]
+SQN-100             : 1.72          [INFO]
+------------------------------------------------------
+Excursion ratio     : 1.28          [PASS]
+======================================================
+
+VERDICT (expectancy): +0.081 R   95% CI [-0.031, +0.196]
+                     p(edge>0) = 0.071        ->  FRAGILE
+  point positive, but the CI straddles zero — not distinguishable
+  from noise at this sample size. Do NOT size it up.
+```
+
+That `FRAGILE` block is the whole point: a positive expectancy that a backtester
+would have shown you as a rising equity curve is, at this sample size,
+**indistinguishable from noise**. crucible says so out loud.
+
+> Runnable versions live in [`examples/`](examples): `quickstart.py` and
+> `validation.py` use synthetic data (no network); `real_data_yfinance.py` pulls
+> real prices from Yahoo Finance (`pip install "crucible-quant[examples]"`) and runs the
+> full pipeline — try `python examples/real_data_yfinance.py --ticker QQQ`.
+
+## What's in the box
+
+- **`TradeLog`** — one documented schema (`r` in R-multiples, plus optional
+  `mfe` / `mae` / `bars_held` / `prob`). Everything speaks it.
+- **Edge metrics** — expectancy, profit factor, payoff ratio, SQN, and the
+  excursion family (MFE/MAE efficiency, E-ratio, time asymmetry, exit efficiency).
+- **The honesty layer** — `bootstrap_ci`, `p_value_positive`, `reality_check`
+  (HELD / FRAGILE / FAIL), and `random_entry_null` (did your signal beat
+  coin-flip timing on the same prices?).
+- **A generic barrier simulator** — `barrier_trades`: OHLC + a boolean entry
+  signal → a `TradeLog`. No instrument specifics.
+- **Example signals** — `ma_cross`, `macd_cross`. Demos, not endorsed edges.
+
+## Does the edge survive out of sample? — `crucible.validation`
+
+The pooled reality check tells you if an edge is real *on the whole history*.
+`crucible.validation` asks the harder question — does it hold on data the analysis
+never touched?
+
+```python
+from crucible.validation import holdout, walk_forward, sign_permutation_pvalue
+
+# 1. Early-train / late-confirm — leakage-controlled temporal split
+print(holdout(trades, "2019-01-01", embargo_weeks=8))    # verdict is the LATE period
+
+# 2. Sign-permutation p-value (Masters) — could the edge come from noise?
+print(sign_permutation_pvalue(trades))
+
+# 3. Pardo walk-forward — optimize params in-sample, confirm out-of-sample, stitch
+wf = walk_forward(px, ma_cross, param_grid={"fast": [10, 20], "slow": [50, 100]},
+                  is_days=365 * 3, oos_days=365)
+print(wf)                          # per-fold IS->OOS efficiency (WFE)
+print(reality_check(wf.stitched))  # the stitched-OOS verdict — the honest one
+```
+
+Also here: `sidak_correction` and `whites_reality_check` (max-statistic across every
+variant you searched) for when a grid search flatters the best result.
+See [`examples/validation.py`](examples/validation.py).
+
+## A shareable tearsheet — `crucible.report`
+
+```bash
+pip install "crucible-quant[report]"
+```
+
+```python
+from crucible.report import tearsheet
+tearsheet(trades, "sheet.html", title="SPY — 20/50 MA cross")
+```
+
+Writes a **self-contained** HTML page (plotly.js inlined, renders offline): the
+verdict banner, the metric scorecard, the R-multiple distribution, cumulative R,
+MFE/MAE excursion, and the bootstrap expectancy distribution behind the CI. Still
+capital-free — it charts summed **R**, never an equity curve. See
+[`examples/tearsheet.py`](examples/tearsheet.py).
+
+## What this is — and isn't
+
+✅ Trade-level edge metrics, excursion efficiency, bootstrap CIs, a random-entry
+reality check — all **capital-free**.
+
+❌ No capital, position sizing, commissions, CAGR, drawdown, or
+Monte-Carlo-on-equity. *If you want an equity curve, hand the `TradeLog` to
+[quantstats](https://github.com/ranaroussi/quantstats). crucible stops at the edge.*
+
+## Releasing
+
+Releases publish to PyPI via GitHub Actions using **Trusted Publishing** (OIDC —
+no API tokens are stored anywhere). Changes are tracked in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+**One-time setup** (maintainer, before the first publish):
+
+1. Create two GitHub environments — repo **Settings → Environments** — named
+   `pypi` and `testpypi`. (Add a required-reviewer rule on `pypi` for a manual
+   approval gate, if you want one.)
+2. Register a **pending Trusted Publisher** at
+   <https://pypi.org/manage/account/publishing/>:
+   PyPI project `crucible-quant`, owner `mspinola`, repo `crucible`, workflow
+   `release.yml`, environment `pypi`. Repeat on
+   <https://test.pypi.org/manage/account/publishing/> with environment
+   `testpypi` for dry runs.
+
+**Cutting a release:**
+
+1. Bump `version` in `pyproject.toml` and move the `CHANGELOG.md` entry from
+   *Unreleased* to the new version.
+2. (Optional dry run) **Actions → Release → Run workflow → `testpypi`**.
+3. Tag and push — the tag **must** match the `pyproject` version or the run fails:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0     # builds, twine-checks, publishes to PyPI
+   ```
+
+## License
+
+MIT

crucible_quant-0.1.0/examples/quickstart.py

@@ -0,0 +1,43 @@
+"""Runnable version of the README example — but on synthetic data so it needs no
+network or the [examples] extra. Swap the `make_prices()` call for
+`yfinance.download(...)` to run it on a real instrument.
+
+    python examples/quickstart.py
+"""
+import numpy as np
+import pandas as pd
+
+from crucible.edge import barrier_trades, edge_report, reality_check, random_entry_null, expectancy
+from crucible.strategies import ma_cross
+
+
+def make_prices(n=1500, seed=7):
+    rng = np.random.default_rng(seed)
+    rets = rng.normal(0.0004, 0.01, n)
+    close = 100 * np.cumprod(1 + rets)
+    open_ = np.r_[close[0], close[:-1]]
+    span = np.abs(rng.normal(0, 0.006, n)) * close
+    high = np.maximum(open_, close) + span
+    low = np.minimum(open_, close) - span
+    idx = pd.date_range("2015-01-01", periods=n, freq="B")
+    return pd.DataFrame({"Open": open_, "High": high, "Low": low, "Close": close}, index=idx)
+
+
+def main():
+    px = make_prices()
+    entries = ma_cross(px, fast=20, slow=50)
+    trades = barrier_trades(px, entries, side="long", tp=2.0, sl=1.0, timeout=20)
+
+    print(edge_report(trades))
+    print()
+    print(reality_check(trades))
+
+    null = random_entry_null(px, side="long", n_entries=trades.n, hold=20,
+                             tp=2.0, sl=1.0, n_sims=500)
+    pctile = float((null < expectancy(trades.r)).mean())
+    print(f"\nRandom-entry null: signal beats {pctile:.0%} of coin-flip-timed books "
+          f"(null mean E = {np.nanmean(null):+.3f} R).")
+
+
+if __name__ == "__main__":
+    main()

crucible_quant-0.1.0/examples/real_data_yfinance.py

@@ -0,0 +1,80 @@
+"""Run the full crucible pipeline on REAL market data pulled from Yahoo Finance.
+
+Requires the [examples] extra:
+
+    pip install "crucible-quant[examples]"
+    python examples/real_data_yfinance.py                 # SPY, 20/50 MA cross
+    python examples/real_data_yfinance.py --ticker QQQ --fast 10 --slow 30
+
+This needs network access, so it's intentionally NOT part of the test suite /
+CI — the synthetic examples/*.py are the smoke tests. It exists to show crucible
+reading a real OHLC frame and to let you kick a signal you actually care about.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+import pandas as pd
+
+from crucible.edge import barrier_trades, edge_report, reality_check
+from crucible.strategies import ma_cross
+from crucible.validation import holdout, walk_forward, sign_permutation_pvalue
+
+
+def load_ohlc(ticker: str, start: str) -> pd.DataFrame:
+    """Download a daily OHLC frame and normalize it to what crucible expects:
+    a DatetimeIndex with plain `Open/High/Low/Close` columns, split-adjusted."""
+    try:
+        import yfinance as yf
+    except ImportError:
+        sys.exit('yfinance not installed — run:  pip install "crucible-quant[examples]"')
+
+    df = yf.download(ticker, start=start, auto_adjust=True, progress=False)
+    if df is None or df.empty:
+        sys.exit(f"no data returned for {ticker!r} — check the symbol / network.")
+    # Newer yfinance returns MultiIndex columns (('Open','SPY'), ...) even for a
+    # single ticker; flatten to the price level.
+    if isinstance(df.columns, pd.MultiIndex):
+        df.columns = df.columns.get_level_values(0)
+    df = df.rename(columns=str.title)
+    return df[["Open", "High", "Low", "Close"]].dropna()
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="crucible on real Yahoo Finance data.")
+    p.add_argument("--ticker", default="SPY")
+    p.add_argument("--start", default="2005-01-01")
+    p.add_argument("--fast", type=int, default=20)
+    p.add_argument("--slow", type=int, default=50)
+    p.add_argument("--split", default="2018-01-01", help="holdout early/late boundary")
+    p.add_argument("--side", default="long", choices=["long", "short"])
+    args = p.parse_args()
+
+    px = load_ohlc(args.ticker, args.start)
+    print(f"{args.ticker}: {len(px)} bars, {px.index.min().date()} -> {px.index.max().date()}")
+
+    entries = ma_cross(px, fast=args.fast, slow=args.slow)
+    trades = barrier_trades(px, entries, side=args.side, tp=2.0, sl=1.0, timeout=20)
+    print(f"{args.fast}/{args.slow} MA cross ({args.side}): {trades.n} trades\n")
+
+    print(edge_report(trades))
+    print("\n1) POOLED reality check")
+    print("  ", str(reality_check(trades)).replace("\n", "\n   "))
+
+    print("\n2) EARLY/LATE HOLDOUT")
+    print("  ", str(holdout(trades, args.split, embargo_weeks=8, n_boot=3000)).replace("\n", "\n   "))
+
+    print(f"\n3) SIGN-PERMUTATION p-value: {sign_permutation_pvalue(trades):.3f}")
+
+    print("\n4) WALK-FORWARD (optimize fast/slow in-sample, confirm OOS)")
+    wf = walk_forward(px, ma_cross,
+                      param_grid={"fast": [10, 20, 30], "slow": [50, 100, 200]},
+                      side=args.side, is_days=365 * 4, oos_days=365, min_is_trades=5)
+    print("  ", str(wf).replace("\n", "\n   "))
+    print("\n   stitched OOS verdict:")
+    print("  ", str(reality_check(wf.stitched)).replace("\n", "\n   "))
+
+
+if __name__ == "__main__":
+    main()