bridzik/rl/DESIGN.md

# RL bot pre bridzik — navrh (2026-07-01)

Ciel: naucit sa principy self-play reinforcement learningu (v duchu AlphaGo Zero)
na praktickom priklade — natrenovat sietovy policy pre hranie bridziku. Zamerne
zjednodusene oproti AlphaGo Zero: bez MCTS (skryta informacia neumoznuje priamy
prehladavaci strom), cisty self-play policy gradient (PPO/REINFORCE) nad `bridzik.py`
enginom.

## Kluc: `Round` je nezavisla epizoda

Bodovanie (`Round.get_points_summary`) je cisto lokalne pre jedno kolo — nezavisi
od predoslych ani nasledujucich kol, len od tipu a poctu kopiek v danom kole.
Netreba teda simulovat cely `Bridzik`/`Series` state machine na trening — staci
instanciovat `Round(round_number, first_player, shuffler)` priamo, opakovane,
s roznymi `round_number` (0-7, teda 8 az 1 karta v ruke). Kazdy `Round` je
samostatna self-play epizoda.

Vyhody:
- jednoduchsi self-play loop (ziadne series/game bookkeeping)
- vela nezavislych epizod, jednoduchá paralelizacia

**Curriculum vs. uniformne samplovanie (bod 4).** Povodny napad "zacat na
`round_number=7`" je zavadzajuci: pri 1 karte je tip masked na {0,1} a jedina
karta je vynutena — nula card-play rozhodnuti, ziadne ucenie, len smoke-test.
Realne ucenie je v kolach `round_number` 0-3 (6-8 kariet). Preto:
- `round_number` je aj tak v observacii, takze **default = uniformne samplovat
  `round_number` 0-7** a nechat siet zdielat vahy naprieč velkostami ruk.
- Ak curriculum, tak **od tazkych (viac kariet) k lahsim**, nie naopak; alebo
  aspon uniformne s miernym zvyhodnenim tazsich kol.
- `round_number=7` drzat len ako sanity/smoke test pipeline, nie ako trening.

## 1. State encoding (observation)

Spolocne pre guess aj play fazu, budovane z `Round` objektu pre daneho hraca:

- **vlastna ruka** — 32-dim multi-hot (4 farby x 8 hodnot)
- **round_number** — one-hot (8) alebo normalizovane cislo (urcuje velkost ruk)
- **tipy vsetkych 4 hracov** — 4x (flag "uz tipoval" + normalizovana hodnota)
- **vlastny tip** (po tipnuti) — kriticke pre play fazu (viem, ci este potrebujem
  vyhrat kopku, alebo sa jej mam vyhybat)
- **kolko kopiek uz kazdy hrac vyhral v tomto kole** — 4 scalars, odvodene
  z dokoncenych `Stash` objektov v `self.stashes`
- **aktualna kopka v procese** — 4 sloty (karta alebo prazdne) + `first_player`
  aktualnej kopky
- **uz odohrane/videne karty v tomto kole** — 32-dim multi-hot (bod 1). KRITICKE:
  bez toho observacia NIE JE Markovovska. Pri viac kartach (round_number 0-2)
  su dve rovnake ruky s rovnakou aktualnou kopkou, ale roznou historiou uz
  odohranych kariet, rozne stavy s roznym optimalnym tahom (vies, ci este visi
  eso/cerven). Bez tejto zlozky sa siet nemoze naucit card-counting a strop hry
  ostane nizky. Kodovat karty odohrane v predoslych dokoncenych `Stash`-och
  (mimo tvojej ruky a mimo aktualnej rozohranej kopky).
- **(volitelne, neskor — bod 8) znama neúčasť supperov vo farbe (voids)** —
  ked supper neprizna vynasanu farbu, prezradi void → per-hrac x per-farba
  flag. Silna informacia, ale nechat na neskorsie rozsirenie.

**Egocentricka rotacia (bod 2) — povinny invariant.** Aby parameter sharing
medzi 4 sedadlami fungoval, VSETKY 4-hracske vektory (tipy, pocty vyhranych
kopiek, sloty aktualnej kopky, `first_player`) musia byt rotovane tak, ze
"ja" = index 0 a ostatni relativne (+1, +2, +3 v smere hry). Toto zapisat do
`encoding.py` ako tvrdy invariant + unit test — je to najpravdepodobnejsie
miesto tichej chyby, ktora pokazi ucenie.

Zamerne vynechane: priebezne skore/standings naprieč hrou — kedze odmena je
per-round nezavisla, optimalne rozhodnutie v danom kole na standings nezavisi.

**Velkost observacie (bod 5).** Povodny odhad ~80-100 floatov je podstrelený.
Ak sa 4 sloty aktualnej kopky koduju one-hot (4x32=128) + ruka 32 + videne
karty 32 + tipy/pocty/round_number/first_player, realny `input_dim` je skor
~200. Nie je to problem, len podla toho nastavit vstupnu vrstvu siete.

## 2. Akcny priestor + maskovanie

- **Guess**: 9 kategorii (0-8), maskovane na `0..(8-round_number)`; pre 4.
  (posledneho) tipujuceho naviac zamaskovat hodnotu, ktora by sposobila
  `BridzikException` (sucet tipov = pocet kopiek) — vypocitatelne vopred
  z `self.guesses`. Zakazana hodnota = `(8-round_number) - sum(3 tipov)`;
  ak vyjde mimo `0..(8-round_number)`, je uz aj tak nelegalna a nemaskuje sa
  nic navyse (osetrit rozsah).
- **Play card**: 32 kategorii (rovnaka indexacia farba+hodnota ako hand-encoding),
  maskovane na karty, ktore hrac realne ma A splnaju follow-suit pravidlo
  (rovnaka logika ako v `Round.play_card`: farba prvej karty v kopke, inak
  povinna cervena ak ju hrac ma).

## 3. Sieť

Zdielany "trup" (2 hidden layers, ~128-256 neuronov, ReLU) nad observation
vektorom (~80-100 floatov), s troma vystupmi:

- guess head (9 logitov)
- play head (32 logitov)
- value head (1 scalar) — odhad ocakavanej odmeny do konca kola (baseline
  pre actor-critic)

`input_dim` nastavit podla realnej velkosti observacie (~200, viz bod 5
v sekcii 1), nie podla povodneho ~80-100.

Fazovy flag v observacii + maskovanie urcuje, ktora hlava je pouzitelna
v danom kroku (guess a play fazy sa nikdy neprelinaju).

## 4. Odmena a trening

- Odmena = 0 pocas kola; na konci kola kazdy hrac dostane
  `points_summary[player]` (0 alebo `10+guess`) ako terminalnu odmenu za
  VSETKY svoje rozhodnutia v danom kole (guess + vsetky `play_card` tahy).
  Sparse terminal reward, ziadne discountovanie netreba — `gamma=1` (bod 9),
  kolo ma max 9 rozhodnuti na hraca: round 0 = 1 tip + 8 kariet.
- Algoritmus: self-play PPO (prip. najprv jednoduchsie REINFORCE + baseline),
  jedna zdielana siet hra vsetkych 4 hracov v kazdom `Round` (parameter
  sharing, rovnaky princip ako AlphaGo Zero).
- **Normalizacia odmeny (bod 7).** `10+guess` je v rozsahu 10-18 a lisi sa
  per kolo; pri miesanych `round_number` to zvysuje varianciu policy gradientu.
  Standardizovat advantage per batch (odcitat priemer, delit std) — bezna
  PPO praktika, tu je nutnejsia kvoli rozne velkym odmenam.
- Paralelizacia: `Round` instancie su nezavisle bez shared state, self-play
  generovanie sa da paralelizovat cez multiprocessing naprieč jadrami CPU
  (pripadne batchovanim viacerych epizod naraz cez sietovy forward).

**Caveat: hra nie je zero-sum (bod 3).** Je to 4-hracska general-sum hra —
viacero hracov moze naraz trafit tip a vsetci skoruju, zaroven sa o kopky
sutazi (`sum(kopky) = pocet kopiek`). Self-play so zdielanymi vahami preto
NEMA konvergencne zaruky ako AlphaGo Zero (2-hracska zero-sum); skonverguje
k *nejakemu* equilibriu, nie nutne k optimu, a moze oscilovat. Na ucebny
ciel to staci, ale: (a) nepredavat si to ako "AlphaZero-grade optimalitu",
(b) sledovat progres proti FIXNYM baseline-om (sekcia 5), nie len podla
self-play reward, ktory sa hybe s protihracom.

## 5. Vyhodnotenie

- priemerne body/kolo oproti baseline (nahodny legalny hrac, Monte Carlo
  heuristicky tipper — pozri sekciu nizsie)
- presnost tipu (% kôl, kde sa tip presne trafil) — interpretovatelnejsia
  metrika nez surove body

## Alternativa/doplnok pre tipovaciu fazu: Monte Carlo namiesto siete

Kedze tipovanie je v podstate odhad pravdepodobnosti pri neznamom rozdeleni
zvysnych kariet, da sa riesit aj bez siete:

1. **Naivna MC simulacia** — vygenerovat vela nahodnych rozdeleni zvysnych
   kariet medzi ostatnych 3 hracov, odsimulovat kolo s jednoduchou heuristickou
   hracou strategiou, spocitat rozdelenie poctu vlastnych kopiek. POZOR: kedze
   bodujeme len presnu zhodu, spravny cieľ je **mod** rozdelenia, nie priemer.
   POZOR 2 (bod 6 — "discard pile"): `deal_starting_cards` zahodí prvych
   `4*round_number` kariet (`round_cards[4*round_number:]`), takze v kole NIE
   su rozdane vsetky karty. MC teda z `32 - vlastna_ruka` kariet rozdá kazdemu
   z 3 supperov len `(8-round_number)` kariet a **zvysok necha v neznamej kope
   mimo hru** — nerozdavat vsetko medzi supperov, inak nadhodnotis, kolko
   vysokych kariet/cervene supperi drzia.
2. **Silnejsia verzia** — rovnaky MC rollout, ale simulovat zvysok kola
   s uz natrenovanou card-play sietou namiesto naivnej heuristiky (analogia
   MCTS + value network v AlphaZero namiesto ciste nahodnych rolloutov).

Toto sa da pouzit ako rychly heuristicky baseline bez trenovania siete na
tipovanie vobec, alebo ako silnejsi hybrid s uz existujucou play sietou.

## Poradie implementacie

1. `rl/encoding.py` — cistě funkcie observation + mask (nad `Round` objektom),
   testovatelne izolovane. Uz tu zapracovat bod 1 (videne karty) a bod 2
   (egocentricka rotacia). Unit/property testy: maska NIKDY nepovoli tah, ktory
   `Round.play_card`/`add_player_guess` odmietne (fuzz-test proti enginu);
   rotacia je konzistentna pre vsetky 4 sedadla.
2. `rl/env.py` — step/reset wrapper okolo jedneho `Round` (nie celeho `Bridzik`)
3. **baseline hraci + evaluacny harness UZ TU** (nahodny legalny hrac, MC
   heuristicky tipper podla sekcie vyssie) — nech je metrika k dispozicii od
   prvej trenovacej epochy a da sa sledovat progres (bod 3: proti fixnym
   baseline-om, nie len self-play reward).
4. sieť (PyTorch, trup + 3 hlavy) — `input_dim` podla realnej velkosti obs (~200)
5. self-play generator (paralelne `Round` epizody)
6. PPO update krok (advantage standardizovat per batch — bod 7)
7. (neskor, volitelne) rozsirit na cely `Series`/`Bridzik` self-play, ak by
   sa ukazalo, ze cross-round dynamika (rotacia first_player a pod.) predsa
   len nieco mení — podla bodu 1 to nie je ocakavane

## Technologie

- **PyTorch** — samostatny `requirements-rl.txt`, oddeleny od zakladneho
  `requirements.txt` projektu
- vlastna mensia implementacia PPO (v duchu CleanRL) namiesto Stable-Baselines3/
  RLlib — nas pripad (multi-agent self-play so zdielanymi vahami, maskovanie
  akcii) sa bije s ich single-agent Gym abstrakciou viac, nez by pomohla