Feature/czar v2 8h price

[jefferythewind]

Summary

Adds volatility prediction support to AlloraMLWorkflow, integrates the CZAR directional loss function, and provides training scripts + deployed models for all mainnet-equivalent testnet topics.

Review guide

Core library (3 files, 248 lines) — please review carefully

• allora_forge_builder_kit/workflow.py — Adds target_type parameter ("log_return" | "volatility") and compute_volatility_target_polars() for computing std of 1-min log returns over the prediction horizon. Used by volatility topics 79–82.
• allora_forge_builder_kit/czar_loss.py (new) — CZAR (Composite Zero-Agnostic Returns) loss with gradient/hessian for custom LightGBM training. Penalizes wrong-sign predictions, softens near-zero returns, normalizes by local volatility. Exported as make_czar_objective, czar_loss, czar_gradient, czar_hessian.
• allora_forge_builder_kit/__init__.py — Exports the new CZAR symbols.

Tests (2 files, 146 lines)

• test_volatility_target.py — 8 tests covering volatility target computation, parameter validation, and target integrity.

Docs/config (3 files)

• README.md — Updated topic reference tables with new testnet topics 83, 84. Added volatility workflow example.
• AGENTS.md — Fixed paths to reflect testnet/ subfolder reorganization.
• .gitignore — Added **/runs/ for training artifacts.

Notebooks (38 files, ~14.5K lines) — example/illustration code, not mission-critical

Everything under notebooks/ demonstrates how to use the core library. These are training scripts for practitioners, not part of the package. Key additions:

• notebooks/testnet/topic_*/model_czar_v2.py — CZAR V2 training scripts with joint grid search over loss params × LightGBM hyperparams × feature configurations
• notebooks/testnet/topic_*/example.py — Baseline MSE training scripts per topic
• Volatility model variants (topics 79–82): deep lookback, multiscale, GARCH-calibrated
• notebooks/dashboard.sh — Convenience script for worker status

Reorganization

• All topic scripts moved from notebooks/topic_*/ → notebooks/testnet/topic_*/
• Removed notebooks/shared/ — deploy scripts stay at notebooks/ top level
• deploy_worker.py and topic 69/77 walkthroughs unchanged

Test suite

75 passed, 0 failed, 17 skipped.

---

Summary by cubic

Adds volatility targets to AlloraMLWorkflow and a CZAR loss for directional training, plus full example coverage for 8h price, 8h/24h log‑return, and 15‑min volatility topics. Updates tests and docs, exports CZAR APIs, and adds a worker dashboard script.

• New Features

  • AlloraMLWorkflow: new target_type ("log_return" default, "volatility" = std of 1‑min log returns over horizon) and compute_volatility_target_polars() for topics 79–82.
  • New czar_loss.py with make_czar_objective, gradient, and hessian for custom LightGBM training; exported via allora_forge_builder_kit/__init__.py.
  • Added 8 tests for volatility target computation; .gitignore now ignores **/runs/.

• Docs and Examples

  • Updated README.md, AGENTS.md, and skills/allora-model-builder/SKILL.md with volatility workflow and refreshed topic tables.
  • Reorganized notebooks/testnet/ with scripts for 38/41/42 (8h price, incl. CZAR models), 57/71/83/84 (8h log‑return), 61/62/63 (24h log‑return), and 79–82 (volatility, multiple variants).
  • Added notebooks/dashboard.sh for a quick worker dashboard.

^{Written for commit 4aee02b. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found

Architecture diagram

sequenceDiagram
    participant User as User/Practitioner
    participant WF as AlloraMLWorkflow
    participant CZAR as CZAR Loss Module
    participant LGBM as LightGBM Model
    participant DS as Data Source (Binance/Allora)
    participant Eval as PerformanceEvaluator
    participant Test as Test Suite

    Note over User,Test: VOLATILITY TARGET FLOW (NEW: topics 79-82)

    User->>WF: Initialize with target_type="volatility"
    WF->>WF: Validate target_type parameter
    WF->>DS: backfill() - fetch 1-min OHLCV data
    DS-->>WF: OHLCV DataFrame
    WF->>WF: stand_alone_features_from_1min_bars()
    WF->>WF: compute_volatility_target_polars()
    Note over WF: Compute std of forward 1-min log returns
    WF->>WF: Compute per-bar log returns
    WF->>WF: Shift log returns backward by 1
    WF->>WF: Reverse series, apply rolling_std, reverse back
    WF-->>User: DataFrame with "target" column (non-negative float)

    alt target_type="log_return" (default)
        WF->>WF: compute_target_polars() - log(close[t+H]/close[t])
    end

    Note over User,Test: CZAR DIRECTIONAL LOSS TRAINING (NEW: czar_loss.py)

    User->>CZAR: Import make_czar_objective()
    CZAR-->>User: objective function (gradient + hessian for LightGBM)

    User->>LGBM: Create LGBMRegressor(objective=czar_obj)
    LGBM->>CZAR: Call gradient() during training
    LGBM->>CZAR: Call hessian() during training
    Note over CZAR: Penalizes wrong-sign predictions
    Note over CZAR: Softens loss near zero returns
    Note over CZAR: Normalizes by local volatility (std)

    loop Per fold in TimeSeriesSplit CV
        LGBM->>LGBM: Train with CZAR objective
        LGBM-->>User: Predictions on test fold
    end

    User->>Eval: evaluate(y_true, y_pred)
    Eval-->>User: Performance report (DA, WRMSE, CZAR improvement, etc.)

    Note over User,Test: LOG-SPACE VOLATILITY PREDICTION (Model E approach)

    User->>User: Compute y_train_log = log(y_train + epsilon)
    User->>LGBM: Train model on log-transformed target
    LGBM->>LGBM: Fit in log-space
    User->>User: Compute bias_correction = exp(0.5 * var(residuals))
    User->>User: predict(nonce): exp(log_pred) * bias_correction

    Note over User,Test: TEST SUITE VALIDATION

    Test->>WF: Test volatility target computation
    Test->>WF: Verify manual calculation matches
    Test->>WF: Check trailing rows are null
    Test->>WF: Validate all targets non-negative
    Test->>WF: Test different horizon sizes
    Test->>WF: Test default target_type is log_return
    Test->>WF: Test invalid target_type raises ValueError

    Note over User,Test: DEPLOYMENT (volatility topics)

    User->>WF: get_live_features("btcusd")
    WF-->>User: Live feature vector
    User->>LGBM: model.predict(features)
    LGBM-->>User: Volatility prediction
    User->>User: max(0.0, vol) - ensure non-negative

Loading

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>