caelum0x 41138e2780 feat(phase2): notebooks, all-docs end-to-end, native strategy-ensemble crate
- python-lab/notebooks: 6 runnable offline-safe notebooks (closes the last plan.md gap).

- docs: OpenAPI now covers all 56 routes (+/journal /ensemble /skills /version); new CLI.md + API.md; refreshed WHATS_NEW/PRIZE_MAP/FEATURE_MATRIX/PRODUCT_OVERVIEW/INDEX.

- crates/strategy-ensemble: native Rust ensemble meta-allocator (blend by regime, 9 tests, clippy-clean), registered in workspace.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-15 12:23:09 +03:00

3.7 KiB

Guardrail Alpha — Analysis Notebooks

Six Jupyter notebooks that load the agent's event log (data/guardrail_alpha.db) and run report (data/run_report.json) and render the research / submission analyses. They reuse the guardrail_lab package — they do not re-implement any analytics.

Notebook What it shows
01_universe_filtering.ipynb The 20-token BSC universe from configs/eligible_assets.bsc.json, with category breakdown.
02_signal_research.ipynb Regime classifications, time-in-regime, exposure multipliers, and per-asset scores (regime_analysis).
03_backtest_review.ipynb Backtest / experiment records from data/experiments/ and data/backtests/ compared side by side (experiments).
04_live_pnl_analysis.ipynb NAV curve + drawdown from the event log (metrics, drawdown).
05_trade_attribution.ipynb Per-asset attribution of confirmed swaps (attribution).
06_submission_charts.ipynb Headline submission tables: identity, performance, regime time, drawdown, attribution.

Offline-safe by design

These notebooks are 100% offline-safe and run with only the Python standard library plus guardrail_lab:

  • No network access — they read local SQLite + JSON only.
  • No heavy plotting deps — there is no matplotlib/plotly import. Tables are printed as aligned text and curves as ASCII sparklines, so the notebooks run even on a bare interpreter. (If you later install the optional plotting stack, guardrail_lab.charts / guardrail_lab.submission build richer HTML/PNG output from the same functions.)
  • Graceful degradation — when data/ is empty (no run yet), every cell prints a "run the agent / seed a demo first" hint instead of raising.

Each notebook starts with a bootstrap cell that walks up from the current working directory to the repo root (the folder containing python-lab/guardrail_lab), puts python-lab on sys.path, and resolves the data/config paths. As a result the notebooks work whether you launch Jupyter from the repo root or from python-lab/notebooks/. They prefer a real run and fall back to the seeded demo artifacts (data/demo_*) when present.

How to run

Jupyter (interactive)

From the repo root:

cd python-lab
pip install -r requirements.txt        # installs jupyter (one-time)
jupyter lab notebooks/                  # or: jupyter notebook notebooks/

Open any notebook and Run All. The first (bootstrap) cell prints the resolved repo root, event-log path, and run-report path.

Headless (no Jupyter needed)

Because the notebooks only use the stdlib + guardrail_lab, you can execute a notebook's code cells directly without Jupyter:

# From the repo root:
python3 -c "import json; nb=json.load(open('python-lab/notebooks/04_live_pnl_analysis.ipynb')); \
src=''.join(''.join(c['source']) for c in nb['cells'] if c['cell_type']=='code'); exec(src)"

Validate all notebooks are well-formed JSON:

python3 -c "import json,glob; [json.load(open(f)) for f in glob.glob('python-lab/notebooks/*.ipynb')]; \
print('nb json ok', len(glob.glob('python-lab/notebooks/*.ipynb')))"

Getting data to analyze

If data/ is empty, populate it first (then re-run any notebook):

# Seed a synthetic demo run (offline):
cd python-lab
python3 -m guardrail_lab.seed

# …or run the real agent (paper/live) which writes data/guardrail_alpha.db
# and data/run_report.json.

Regenerating the notebooks

The notebook JSON is generated from a single authoritative script so it is easy to keep consistent. To rebuild all six .ipynb files:

python3 python-lab/notebooks/_build_notebooks.py