TOMIC 2.0 — V1 Tools

Portable regime-snapshot tooling. Everything runs relative to the bundle root (parent of this directory); copying the bundle directory deploys it.

Setup (fresh machine)

1. Python 3.10+ and numpy: pip install -r requirements.txt
2. Tiingo key: export TIINGO_API_KEY=... OR put the key in a file and point config.json at it (cp config.example.json config.json). Key file default: ~/.config/okf_bundles/tiingo.key (chmod 600).
3. Nothing else. FRED (VIX and VIX3M) needs no key.

Daily run

python3 regime_snapshot.py            # snapshot for today, appends journal record
python3 regime_snapshot.py --no-append   # dry run
python3 har_forecast.py --ticker SPY --asof YYYY-MM-DD   # forecast only

Exit codes: 0 = full snapshot (label computed); 2 = fail-closed (data missing or stale: any input older than max_input_age_business_days in regime_config.json counts as missing; data-missing record journaled, no label).

What it does

• har_forecast.py: Tiingo EOD closes -> daily RV proxy -> rolling HAR-RV fit (Corsi 2009) -> ex-ante 30-day vol forecast, no lookahead. Replaces the placeholder garch_forecast input of the attested EV computations.
• regime_snapshot.py: VIX and VIX3M (same-date FRED closes), HAR forecast -> three regime axes -> hysteresis-confirmed label -> v1-schema record in ../96-journal/regime.jsonl. State (confirmation history) lives in ../96-journal/regime-state.json — keep it beside the journal when syncing machines.
• IV30 is currently the VIX (PROVISIONAL proxy). Canonical IV30 arrives with the ThetaData fetcher (V1b).

Known environment quirk

FRED rejects custom User-Agents and HTTP/2 from some hosts (hangs). The transport therefore: urllib first, then curl fallback with --http1.1, and no custom UA. If you mirror this pattern, keep that ordering.