# jepa-fx-risk

Research project exploring JEPA (Joint Embedding Predictive Architecture) as a framework for latent representation learning applied to FX trading risk management.

**Primary hypothesis:** JEPA embeddings trained on FX time-series will produce latent market-state representations that are structurally separable by regime without explicit regime labels, measurable by silhouette score on k-means clusters validated against held-out realised-volatility regime labels.

**Current phase:** Phase 0 — SSL Feasibility Gate (not yet started)

**Brain wing:** `jepa-fx` — query via `brain_query wing=jepa-fx`

---

## Architecture

This is a **Go-first, Python-minimal** research project.

| Layer | Language | Rationale |
|---|---|---|
| Data pipeline | Go | Type-safe, fast, no dependency hell |
| Experiment runner | Go | CLI tooling, reproducible invocations |
| Evaluation harness | Go | Silhouette, linear probe, collapse diagnostics |
| Model training | Python + PyTorch | TS-JEPA requires it; kept minimal and isolated |

## Structure

```
specs/          experiment specs (one per phase)
src/            Go packages: pipeline, eval, cmd
model/          Python: TS-JEPA training loop only
experiments/    one directory per run (gitignored except summaries)
results/        tracked: metric tables, key figures
data/           gitignored; see data/README.md for download instructions
notebooks/      EDA only; outputs stripped before commit
docs/           ADRs and research notes
```

## Quick start

```bash
task data:fetch          # download DUKASCopy G10 tick data
task pipeline:build      # build Go data pipeline
task check               # lint + vet + test
task experiment:run -- --spec specs/phase-0-ssl-feasibility.md
```

## Phases

| Phase | Goal | Status |
|---|---|---|
| 0 | SSL feasibility gate — MAE baseline on FX data | 🔲 Not started |
| 1 | JEPA representation PoC — silhouette > 0.35 | 🔲 Not started |
| 2 | Regime detection validation — recall > 70%, lead > 5d | 🔲 Not started |
| 3 | Distributional forecasting — VaR passes Kupiec | 🔲 Not started |
| 4 | Multi-pair transfer — exotic pair improvement | 🔲 Not started |

## Key constraints

- **Training cutoff:** 2023-01-01 — all post-2023 data is sealed for final evaluation
- **Training data:** 2008–2022, all G10 pairs, DUKASCopy
- **Out of scope:** options pricing, directional alpha, live trading, exotic pairs (Phases 1–3)
- **End-state:** publishable research result — not institutional deployment

## Related

- Brain wing: `wiki/jepa-fx/` — decisions, hypotheses, failure modes
- Synthesis document: `JEPA_FX_Risk_Synthesis.docx` (session 2026-05-27)