README.md

---
license: apache-2.0
tags:
  - finance
  - world-model
  - diffusion
  - causal-inference
  - scenario-generation
  - indian-markets
language:
  - en
pipeline_tag: other
---

# Horizon v1 — Causal Financial World Model

The first causal world model for financial markets achieving Pearl Level 3 (counterfactual reasoning).

## What This Model Does

Generate realistic multi-asset market scenarios from natural language descriptions:

```python
from horizon.inference.scenario_engine import ScenarioEngine

engine = ScenarioEngine.from_checkpoint("model.pt")
result = engine.generate(
    description="RBI cuts repo rate by 50bp amid slowing growth",
    instruments=["NIFTY50", "BANKNIFTY", "HDFCBANK", "INFY", "TATASTEEL"],
    n_scenarios=1000,
    horizon_days=21,
)
# result.paths: (1000, 21, 5) daily log-returns
# result.prices: (1000, 22, 5) price paths
# result.var_95, result.expected_shortfall_95
```

## Architecture

- **Base**: Diffusion Transformer (DiT-1D), 172M parameters
  - d_model=768, 16 axial attention blocks, 12 heads
  - Alternating time-axis / asset-axis attention
  - adaLN-Zero conditioning + cross-attention to event tokens
- **Causal Layer**: Backdoor-adjusted guidance with explicit causal graph
  - 14 market nodes, 18 directed edges
  - Per-channel guidance masking (prevents placebo bleed)
  - Empirical calibration from 42 RBI rate events
- **Counterfactual**: DDIM inversion (100-step, 0.975 roundtrip correlation)
- **NL Interface**: 3-tier parser (regex → LLM → heuristic)

## Key Results

### CausalFinBench (Novel Benchmark)
| Tier | Tests | Result |
|------|-------|--------|
| A: World Properties | 5/5 | Consistency, Asymmetry, Compositionality, CF Coherence, Robustness |
| B: Causal Validity | 3/3 | Placebo 100%, Real effects 100%, Sensitivity monotonic |
| C: Natural Experiments | 1/1 | 42/42 RBI rate decisions — 100% direction match |

### Calibration
| Intervention | Model Effect | Historical Actual |
|---|---|---|
| RBI rate cut | +0.40% | +0.41% (2.4% error) |
| RBI rate hike | -0.31% | -0.35% |
| India VIX spike | -0.72% | — |
| FII selling | -0.49% | — |
| Global risk-off | -0.44% | — |

### Pearl's Causal Ladder
- **Level 1 (Association)**: Base DiT generates statistically valid paths
- **Level 2 (Intervention)**: do-operator via causal graph surgery + guided sampling
- **Level 3 (Counterfactual)**: DDIM inversion + action + prediction (verified on June 4, 2024 election)

## Training Data

- 50 Nifty50 constituents × 26 years (2000-2026)
- 1.05M real news headlines from QLake
- 48 macro series (repo rate, CPI, VIX, yields, commodities, FX)
- 317,650 training windows

## World Model Properties (5/5 PASS)

1. **Consistency**: Same intervention + same noise → identical output
2. **Causal Asymmetry**: do(rate_cut) ≠ do(nifty_rally) — different mechanisms (corr=0.47)
3. **Compositionality**: Combined interventions produce combined effects (56% of linear sum)
4. **Counterfactual Coherence**: Inversion roundtrip at 0.975 correlation
5. **Robustness**: Extreme interventions (±10σ) remain finite and reasonable

## Limitations

- **5 instruments per call** (can generate correlated paths for any 5 Nifty50 stocks)
- **Causal graph is hand-specified** (not learned from data)
- **Magnitude calibration** fitted from historical events — may not generalize to unprecedented scenarios
- **NL understanding via external parsing** — model itself does not natively understand text (v2 will fix this)
- **No options/derivatives pricing** (equity paths only)

## Usage Requirements

- PyTorch >= 2.0
- ~700MB disk for checkpoint
- GPU recommended for inference (<30s on A100 for 1000 paths)
- CPU inference: ~20 minutes for 1000 paths

## Citation

```bibtex
@software{horizon_v1_2026,
  title={Horizon: A Causal Financial World Model for Indian Markets},
  author={QuantHive Research},
  year={2026},
  url={https://huggingface.co/QuantHive-Research-Tech/horizon-v1}
}
```

## License

Apache 2.0