RL: encoding observacii, akcne masky a Round prostredie

Zaklad RL vrstvy (rl/DESIGN.md): egocentricky rotovana observacia
(ruka, videne karty, tipy, kopka, dedukovane voidy -- 233 dim), masky
legalnych tipov/kariet zrkadliace pravidla enginu a RoundEnv (jedno kolo
= jedna self-play epizoda). Fuzz-testy vynucuju zhodu masiek s enginom.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

rl/DESIGN.md

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

rl/encoding.py

@@ -0,0 +1,168 @@
+"""Observation a action-mask encoding nad `Round` objektom z `bridzik.py`.
+
+Ciste funkcie bez externych zavislosti (ziadny numpy/torch) -- vystupy su
+obycajne zoznamy floatov/boolov, konverzia na tenzory je vecou volajuceho.
+
+Tvrdy invariant (viz rl/DESIGN.md): VSETKY 4-hracske zlozky observacie su
+egocentricky rotovane -- "ja" (parameter `player`) je vzdy index 0, ostatni
+hraci +1/+2/+3 v smere hry. Bez tejto rotacie parameter sharing medzi
+sedadlami nefunguje.
+
+Masky zrkadlia pravidla enginu: maska NIKDY nesmie povolit akciu, ktoru by
+`Round.add_player_guess` / `Round.play_card` odmietli, a naopak. Tuto zhodu
+vynucuje fuzz-test v tests/test_encoding.py.
+"""
+
+from bridzik import Card, Card_colors, Card_values, ROUNDS_PER_SERIES
+
+# Kanonicke poradie farieb a hodnot = poradie deklaracie v enum-och.
+COLORS = list(Card_colors)   # HEARTS, LEAVES, ACORNS, BELLS
+VALUES = list(Card_values)   # C7, C8, C9, C10, LOWER, UPPER, KING, ACE
+
+N_CARDS = 32
+N_GUESS_ACTIONS = 9          # tipy 0..8
+N_PLAY_ACTIONS = N_CARDS     # jedna akcia = jedna karta
+
+_COLOR_INDEX = {color: i for i, color in enumerate(COLORS)}
+_VALUE_INDEX = {value: i for i, value in enumerate(VALUES)}
+
+# Layout observacie -- offsety su sucast verejneho kontraktu (testy aj siet
+# sa na ne odkazuju menom, nie magickym cislom).
+OFF_HAND = 0                          # 32 multi-hot: vlastna ruka
+OFF_SEEN = OFF_HAND + N_CARDS         # 32 multi-hot: karty z dokoncenych kopiek
+OFF_ROUND = OFF_SEEN + N_CARDS        # 8 one-hot: round_number
+OFF_PHASE = OFF_ROUND + ROUNDS_PER_SERIES   # 1 flag: 1.0 = tipovacia faza
+OFF_GUESSES = OFF_PHASE + 1           # 4 x (flag "uz tipoval", tip/8), rel. poradie
+OFF_TRICKS = OFF_GUESSES + 8          # 4 x (vyhrane kopky / 8), rel. poradie
+OFF_STASH = OFF_TRICKS + 4            # 4 x 32 one-hot: aktualna kopka, rel. poradie
+OFF_STASH_LEADER = OFF_STASH + 4 * N_CARDS  # 4 one-hot: rel. first_player kopky
+OFF_VOIDS = OFF_STASH_LEADER + 4      # 4 hraci x 4 farby: dedukovane voidy, rel. poradie
+OBS_DIM = OFF_VOIDS + 16              # = 233
+
+
+def card_index(card: Card) -> int:
+    """Index karty 0..31: farba (blok po 8) + hodnota."""
+    return _COLOR_INDEX[card.color] * 8 + _VALUE_INDEX[card.value]
+
+
+def index_card(index: int) -> Card:
+    """Inverzia card_index."""
+    return Card(COLORS[index // 8], VALUES[index % 8])
+
+
+def relative_seat(seat: int, player: int) -> int:
+    """Egocentricka rotacia: `player` -> 0, dalsi v smere hry -> 1, 2, 3."""
+    return (seat - player) % 4
+
+
+def deduce_voids(rnd) -> dict:
+    """Isto-dedukovane chybajuce farby hracov z priebehu kola.
+
+    Follow-suit pravidlo prezradza: kto nepriznal vynasanu farbu, uz ju nema;
+    kto pri tom nezahral ani cerven (tromf), nema ani tu. Vynasajuci hrac
+    neprezradza nic. Vracia dict seat -> set(Card_colors). Kedze karty pocas
+    kola len ubudaju, raz dedukovany void plati do konca kola.
+    """
+    voids = {seat: set() for seat in range(4)}
+    for stash in rnd.stashes:
+        first = stash.get_first_card()
+        if first is None:
+            continue
+        for seat, card in stash.get_cards().items():
+            if seat == stash.first_player:
+                continue
+            if card.color != first.color:
+                voids[seat].add(first.color)
+                if card.color != Card_colors['HEARTS']:
+                    voids[seat].add(Card_colors['HEARTS'])
+    return voids
+
+
+def encode_observation(rnd, player: int) -> list:
+    """Observacia kola z pohladu hraca `player` (OBS_DIM floatov v [0, 1]).
+
+    Funguje v oboch fazach (tipovanie aj hra) aj na terminalnom stave;
+    necita get_active_player(), takze sa da zavolat pre lubovolneho hraca
+    kedykolvek.
+    """
+    obs = [0.0] * OBS_DIM
+
+    for card in rnd.player_cards[player]:
+        obs[OFF_HAND + card_index(card)] = 1.0
+
+    # Dokoncene kopky -> "videne karty"; jedina pripadna nedokoncena kopka
+    # (posledna) je aktualna rozohrana a koduje sa do slotov nizsie.
+    current_stash = None
+    for stash in rnd.stashes:
+        if stash.is_completed():
+            for card in stash.get_cards().values():
+                obs[OFF_SEEN + card_index(card)] = 1.0
+        else:
+            current_stash = stash
+
+    obs[OFF_ROUND + rnd.round_number] = 1.0
+    obs[OFF_PHASE] = 0.0 if rnd.is_guessing_completed() else 1.0
+
+    for seat, guess in rnd.guesses.items():
+        rel = relative_seat(seat, player)
+        obs[OFF_GUESSES + 2 * rel] = 1.0
+        obs[OFF_GUESSES + 2 * rel + 1] = guess / 8
+
+    tricks = rnd.get_stashes_winner_summary()
+    for seat in range(4):
+        obs[OFF_TRICKS + relative_seat(seat, player)] = tricks[seat] / 8
+
+    if current_stash is not None:
+        for seat, card in current_stash.get_cards().items():
+            rel = relative_seat(seat, player)
+            obs[OFF_STASH + rel * N_CARDS + card_index(card)] = 1.0
+        obs[OFF_STASH_LEADER + relative_seat(current_stash.first_player, player)] = 1.0
+
+    for seat, banned in deduce_voids(rnd).items():
+        rel = relative_seat(seat, player)
+        for color in banned:
+            obs[OFF_VOIDS + rel * 4 + _COLOR_INDEX[color]] = 1.0
+
+    return obs
+
+
+def guess_mask(rnd) -> list:
+    """Maska legalnych tipov (N_GUESS_ACTIONS boolov) pre aktivneho tipujuceho.
+
+    Zrkadli Round.add_player_guess: tip 0..(8 - round_number); poslednemu
+    (stvrtemu) tipujucemu je navyse zakazana hodnota, pri ktorej by sucet
+    tipov vysiel presne na pocet kopiek v kole.
+    """
+    max_guess = 8 - rnd.round_number
+    mask = [g <= max_guess for g in range(N_GUESS_ACTIONS)]
+    if len(rnd.guesses) == 3:
+        forbidden = max_guess - sum(rnd.guesses.values())
+        if 0 <= forbidden <= max_guess:
+            mask[forbidden] = False
+    return mask
+
+
+def legal_cards(hand: list, first_card) -> list:
+    """Karty z `hand`, ktore smie hrac zahrat do kopky vynasanej `first_card`.
+
+    Zrkadli follow-suit logiku Round.play_card: povinna farba prvej karty
+    kopky; ak ju hrac nema, povinna cervena (tromf); ak nema ani tu,
+    lubovolna karta. Pri vynasani (`first_card is None`) lubovolna karta.
+    """
+    if first_card is None:
+        return list(hand)
+    same_color = [c for c in hand if c.color == first_card.color]
+    if same_color:
+        return same_color
+    hearts = [c for c in hand if c.color == Card_colors['HEARTS']]
+    return hearts if hearts else list(hand)
+
+
+def play_mask(rnd, player: int) -> list:
+    """Maska legalnych kariet (N_PLAY_ACTIONS boolov) pre hraca `player`."""
+    stash = rnd.get_last_stash()
+    first_card = stash.get_first_card() if stash is not None else None
+    mask = [False] * N_PLAY_ACTIONS
+    for card in legal_cards(rnd.player_cards[player], first_card):
+        mask[card_index(card)] = True
+    return mask

rl/env.py

@@ -0,0 +1,70 @@
+"""Self-play prostredie nad jednym `Round`-om (viz rl/DESIGN.md).
+
+Jedno kolo = jedna epizoda. Prostredie je multi-agentne a tahove: v kazdom
+kroku je na tahu prave jeden hrac (`Decision.player`), akciu zan doda
+volajuci (zdielana siet, heuristika, ...). Odmena je sparse a terminalna --
+`Round.get_points_summary()` pre vsetkych 4 hracov naraz na konci kola.
+
+Akcie: v tipovacej faze index tipu 0..8, v hracej faze index karty 0..31
+(kanonicke cislovanie z rl/encoding.py). Legalne akcie urcuje
+`Decision.mask`; nelegalna akcia prebuble ako BridzikException z enginu.
+"""
+
+from random import Random
+from typing import NamedTuple
+
+from bridzik import Round, ROUNDS_PER_SERIES
+from rl.encoding import encode_observation, guess_mask, index_card, play_mask
+
+PHASE_GUESS = 'guess'
+PHASE_PLAY = 'play'
+
+
+class Decision(NamedTuple):
+    """Jeden rozhodovaci bod: kto je na tahu, v akej faze, co vidi a co smie."""
+    player: int
+    phase: str
+    obs: list
+    mask: list
+
+
+class RoundEnv:
+    def __init__(self, rng: Random = None):
+        self.rng = rng if rng is not None else Random()
+        self.round = None
+
+    def reset(self, round_number: int = None, first_player: int = None) -> Decision:
+        """Zacne novu epizodu; nezadane parametre sa sampluju uniformne."""
+        if round_number is None:
+            round_number = self.rng.randrange(ROUNDS_PER_SERIES)
+        if first_player is None:
+            first_player = self.rng.randrange(4)
+        self.round = Round(round_number, first_player, shuffler=self.rng.shuffle)
+        return self._decision()
+
+    def step(self, action: int):
+        """Vykona akciu hraca na tahu.
+
+        Vracia (decision, rewards, done): pocas kola (Decision, None, False),
+        na konci kola (None, [body 4 hracov], True).
+        """
+        if self.round is None or self.round.is_completed():
+            raise RuntimeError('Epizoda nebezi -- najprv zavolaj reset().')
+        player = self.round.get_active_player()
+        if not self.round.is_guessing_completed():
+            self.round.add_player_guess(player, action)
+        else:
+            self.round.play_card(player, index_card(action))
+        if self.round.is_completed():
+            return None, self.round.get_points_summary(), True
+        return self._decision(), None, False
+
+    def _decision(self) -> Decision:
+        player = self.round.get_active_player()
+        if not self.round.is_guessing_completed():
+            return Decision(player, PHASE_GUESS,
+                            encode_observation(self.round, player),
+                            guess_mask(self.round))
+        return Decision(player, PHASE_PLAY,
+                        encode_observation(self.round, player),
+                        play_mask(self.round, player))