FlashAlpha Cookbook

Production Python recipes for gamma exposure, dealer positioning, SVI vol surfaces, VRP, 0DTE, and unusual flow — powered by the FlashAlpha API.

Every recipe is a jupytext-paired (.py + .ipynb) file with executed outputs committed. Open any recipe in Colab via its badge, or pip install flashalpha and run the .py directly.

pip install flashalpha matplotlib numpy
export FLASHALPHA_API_KEY="your_key_here"
python notebooks/tier-a-hooks/01-gex-dashboard.py

Catalog

See COOKBOOK.md for the full catalog (added in Phase 1+).

Phase 0 ships the foundation and one canonical recipe: 01-gex-dashboard.

Authoring a new recipe

python -m scripts.new_recipe \
  --slug 02-gamma-flip-cross-index \
  --title "Find Today's Gamma Flip Across Indexes" \
  --tier free \
  --tier-dir tier-a-hooks

This creates a paired (.py, .ipynb) skeleton with frontmatter, CTA cells, and a starter code block. Fill in the body, run it once against live API to record the cassette:

python -m scripts.record_cassettes notebooks/tier-a-hooks/02-gamma-flip-cross-index.ipynb

Then pytest will replay it from cassette on every PR.

See docs/superpowers/specs/2026-05-25-flashalpha-cookbook-design.md for the full spec.

Test layers

Layer	What it checks	When it runs
0 Secrets	gitleaks + auth-header scrub + regex sweep over code & outputs	pre-commit + PR
1 Structural	frontmatter schema, CTA UTMs, slug ↔ file, AST scan, link 200s	PR
2 Execution	papermill + vcrpy cassette replay; runtime + call budgets	PR
3 Golden	DataFrame & chart snapshots for backtest recipes	nightly (Phase 6+)
4 Tier static	endpoints_used ⊆ tier (endpoint_tiers.yaml)	PR
5 Funnel sanity	UTM rendering, link 200s, weekly stats	weekly (Phase 8)

Repository structure

• notebooks/tier-{a,b,c,d,e,f,g}-*/ — recipes by tier
• cookbook_tools/ — shared Python helpers (Pydantic schema, tier-map, CTA renderer)
• scripts/ — CLI tools (new_recipe.py, scrub_outputs.py, record_cassettes.py, sync_tier_map.py)
• tests/ — Layer 0/1/2/4 test suites + cassettes
• endpoint_tiers.yaml — mirror of API tier middleware (scripts/sync_tier_map.py to regenerate)
• docs/superpowers/{specs,plans}/ — design + implementation docs

License

MIT. See LICENSE.