# Vast GPU (kilka godzin) — runbook do trenowania + eksportu modelu

Cel: używać Vast (GPU) jako **krótkiej sesji treningowej** (kilka godzin), a wynik (wagi/adapter) zapisać trwałe i wersjonowane.

W tym projekcie Vast:
- **nie dostaje sekretów tradingowych**,
- nie ma dostępu do kluczy,
- zwraca tylko `trade_intent`/predykcje.

---

## 1) Najważniejsza zasada przy krótkim wynajmie

Vast jest “ephemeral”. Żeby nie stracić pracy:

- wszystko musi być **reproducible** (konfig + kod + seed),
- model output musi być **mały** i łatwy do przeniesienia (preferuj LoRA/adaptery),
- checkpointy i final artifacts muszą być **uploadowane** poza maszynę (Gitea packages/S3/scp).

---

## 2) Co potrzebujemy mieć gotowe przed startem sesji

### 2.1 Kod i entrypoint

W repo powinien istnieć “one command training”, np.:
- `python -m train ...` albo `bash scripts/train.sh ...`

Zasada: komenda sama:
- pobiera dataset (albo czyta lokalny plik),
- trenuje,
- zapisuje `artifacts/`,
- robi upload.

### 2.2 Dataset (krótki transfer)

Dla sesji “kilka godzin” unikaj wielkich transferów.

Rekomendacja:
- zbuduj dataset jako plik (np. `jsonl`/`parquet`) i spakuj (`zstd`),
- trzymaj wersję datasetu (hash) i loguj ją do metryk.

Źródło danych (rekomendowane u nas):
- `Postgres/Timescale` w k3s → eksport do pliku (offline), potem upload.

### 2.3 Bazowy model

Masz 2 ścieżki:
- pobierasz z internetu (HF) na Vast (szybko, ale zależy od sieci),
- albo trzymasz bazę w swoim storage i ściągasz kontrolowanie.

Na start preferuj LoRA na umiarkowanym modelu i krótkiej sekwencji.

---

## 3) Co uruchamiamy na Vast

### 3.1 Kontener

Najprościej: jeden Docker image z zależnościami (PyTorch + libs).
Obraz powinien być **pinned** (digest) i gotowy do uruchomienia bez `pip install` w trakcie.

### 3.2 Konfiguracja treningu (config file)

Trzymaj config jako plik (np. YAML/JSON) i loguj go do artifactów:
- `model_name`, `model_version`
- `dataset_version` (hash)
- `seq_len`, `batch_size`, `grad_accum`, `lr`
- `lora_r`, `lora_alpha`, `lora_dropout` (jeśli LoRA)
- `seed`

### 3.3 Output

Preferowane outputy:
- LoRA adapter (mały): `adapter.safetensors` + config
- metryki treningu: `metrics.json`
- walidacja: `eval_report.json`

Opcjonalnie:
- export do ONNX/TensorRT jeśli planujesz inference poza GPU (zależne od modelu).

---

## 4) Gdzie trzymamy artefakty (żeby nie zniknęły)

Opcje (w kolejności prostoty):

1) **scp na VPS/k3s** (na start najprostsze)
2) **Gitea Packages** (jeśli chcesz wersjonować jako “package”)
3) **S3/MinIO** (najbardziej skalowalne)

Minimalne wymaganie: zawsze zapisuj `model_version` i `dataset_version` obok wag.

---

## 5) Jak to łączy się z executor / UI

Model na Vast zwraca `trade_intent` (patrz `doc/drift-perp-contract.md`).
Executor w k3s:
- buduje features z DB,
- woła predictor,
- waliduje gates,
- loguje:
  - `decision_id`, `model_version`, `features_hash`, `intent`,
  - outcome (fill/exit).

Jeśli Vast jest niedostępny:
- executor przechodzi w `observe/off` (nie handluje),
- UI nadal pokazuje warstwy rynku (DLOB/ticki).

---

## 6) Checklist “kilka godzin” (operacyjnie)

- [ ] Vast instance: GPU + wystarczająco VRAM + szybki disk.
- [ ] Pull docker image (pinned).
- [ ] Download dataset (jedna komenda).
- [ ] Train (z logowaniem metryk co N kroków).
- [ ] Eval (krótki).
- [ ] Export adapter/weights.
- [ ] Upload artifacts (scp / packages / S3).
- [ ] Zapisz `model_version` do DB/config (k3s) przed użyciem.