Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,117 @@
+---
+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