docs: add rpc/dlob/candles notes

doc/vast-gpu-runbook.md

@@ -0,0 +1,123 @@
+# 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.
+