# jepa-fx-risk

## Identity

- **Name**: jepa-fx-risk
- **Owner**: Mathias
- **Client**: personal / research
- **Repo**: gitea.d-ma.be/mathias/jepa-fx-risk
- **Status**: active
- **Brain wing**: `jepa-fx` (`wiki/jepa-fx/`)

## Purpose

Research project. Not a product. The "user" is future-self and research readers. Success is a reproducible, publishable result — not deployment.

## Stack

- **Primary language**: Go 1.24+ (pipeline, eval harness, CLI, experiment runner)
- **ML layer**: Python 3.12 + PyTorch (TS-JEPA training loop only — isolated in `model/`)
- **Build**: Task (Taskfile.yml)
- **Target infra**: koala (Arch + Blackwell GPU, training), iguana (Mac Studio M2, dev)
- **MCP**: brain (knowledge), gitea (version control)

## Research context

**Primary hypothesis:**
> JEPA embeddings trained on FX time-series will produce latent market-state representations structurally separable by regime without explicit labels, measurable by silhouette score > 0.35 on k-means clusters vs. realised-volatility regime labels, on held-out data including at least one structural break.

**Current phase:** Phase 0 — SSL Feasibility Gate

**Training cutoff:** 2023-01-01 (hard — never look at post-2023 data during development)

**Out of scope:** options pricing, directional alpha, live/paper trading, exotic pairs (Phases 1–3)

**Brain wing for prior decisions and failure modes:** `brain_query wing=jepa-fx`

## Conventions

### Scientific discipline
- Every experiment has a spec in `specs/` before any code runs
- Hypotheses are falsifiable and have quantitative acceptance criteria
- Null results are recorded and published — not discarded
- Training cutoff is sacred — post-2023 data never informs any design decision
- Results reported with baselines; no cherry-picking

### Code style
- Go: `gofumpt`, `golangci-lint` with project config; table-driven tests; `testify`
- Errors: `fmt.Errorf("context: %w", err)` — no naked returns
- Python: `ruff` for lint; type hints throughout; `pytest` for tests
- No Jupyter notebooks for anything reproducible — notebooks are EDA scratch only

### Git
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `experiment:`, `result:`
- Branch: `feat/`, `experiment/phase-N-description`, `fix/`
- Every experiment run gets a git tag: `exp/YYYYMMDD-short-description`
- PRs: one concern per PR; description explains *why* not *what*

### Experiment discipline
- One spec per phase in `specs/` — written before any implementation
- Each run recorded in `experiments/YYYYMMDD-HHMMSS-description/`
- Metric summaries committed to `results/summaries/` — large outputs gitignored
- `task check` must pass before any commit

### Security / data
- No raw FX data committed (gitignored) — see `data/README.md` for reproducible download
- No API keys or tokens in code — env vars only
- Training data and results stay local — nothing to cloud unless explicitly decided

## Agent instructions

When acting as a coding agent on this project:

1. Read this file and all `SKILL.md` files in `.skills/` before starting work
2. Run `brain_query wing=jepa-fx` to load current decisions and failure modes
3. Run `task check` before every commit (lint + vet + test)
4. Check `DECISIONS.md` before making any architecture or methodology choice
5. Every experiment needs a spec in `specs/` — no specless experiments
6. Never touch post-2023 data during development; it is sealed
7. Record null results honestly — do not iterate until metrics pass without noting it
8. When adding a Python dependency, justify it; prefer pure Go alternatives