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:

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

3.5 KiB Raw Blame History Unescape Escape