generated from mathias/template-go-web
81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# 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
|