pokerkit 1.1.0

Core type aliases, traits, and constants for robopoker
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# pokerkit

Core type aliases, traits, and constants for robopoker.

`pokerkit` is the foundational crate of the robopoker workspace: the shared
vocabulary of domain types, the `(Version × Regime)` training configuration,
the `hyperparams!` singleton macro, and the generic action-translation engine
that maps arbitrary bet sizes onto a finite abstract action grid.

## Architecture

```mermaid
flowchart LR
  subgraph Aliases["Type aliases"]
    A1["Chips"]
    A2["Utility"]
    A3["Probability"]
    A4["Energy / Entropy"]
    A5["ID<T>"]
  end
  subgraph Config["Runtime config (OnceLock)"]
    C1["Version - V0..V3"]
    C2["Regime - Pluribus / Slumbot"]
    C3["Translation - Snap / Harmonic / Phargmax"]
  end
  subgraph Tools["Utilities"]
    T1["hyperparams! macro"]
    T2["Arbitrary / Unique traits"]
    T3["Summary metrics"]
  end
```

The crate defines the numeric vocabulary used across the workspace as thin
`f32`/`i16` aliases so intent is legible at call sites: `Chips` (stacks and
bets in big blinds), `Utility` (payoffs and regrets), `Probability` (strategy
weights), and `Energy`/`Entropy` (distances and temperatures). Training runs
are keyed by two orthogonal axes — `Version` (clustering abstraction) and
`Regime` (bet-sizing grid) — each a process-global `OnceLock` set once at
startup, together naming the database tables a run reads and writes.

### Action translation

```mermaid
flowchart LR
  raw["Raw bet size"] --> scalar["Scalar<A> (axis-tagged f64)"]
  lattice["Lattice<A, P> (sorted anchors + payloads)"] --> bracket
  scalar --> bracket["bracket -> Bracket(lo, hi)"]
  bracket -->|clamped| clamp["extreme anchor"]
  bracket -->|inside| ph["pharmonic p = (B-x)(1+A) / (B-A)(1+x)"]
  ph -->|Harmonic - sample| anchor["Anchor"]
  ph -->|Phargmax - p >= 0.5| anchor
  scalar -->|Snap - L1 nearest| anchor
  clamp --> anchor
  anchor --> payload["payload"] --> out["Translated::Snap(P)"]
```

Translation answers "which abstract action does an off-tree opponent bet
correspond to?" An observed size becomes a `Scalar<A>` (phantom-typed to an
axis like big blinds or pot fraction) and is located within a `Lattice<A, P>`,
a validated strictly-ascending list of anchor scalars each carrying a payload
`P`. `bracket` finds the surrounding `(lo, hi)` anchors (or clamps at an
extreme); the `Translation` policy then picks one: `Snap` takes the L1-nearest
anchor, while `Harmonic` and `Phargmax` apply the Ganzfried–Sandholm 2013
pseudo-harmonic weighting (randomized vs. deterministic argmax). The chosen
`Anchor` yields its payload as `Translated::Snap(P)`.