Bot Framework Architecture

# Bot Framework Architecture

Module architecture for the bot framework in the Rust `super_marvin` project.

---

## Strategy Registry (14 types)

| Registration Name | Generation | Description |
|---|---|---|
| `g1_short_stack_preflop` | Gen 1 | Push/fold preflop (≤25 BB) |
| `g1_big_stack_preflop` | Gen 1 | Hand-grouping preflop (≥25 BB) |
| `g1_short_stack_preflop_sng` | Gen 1 | SNG-specific push/fold |
| `g1_fold_micro_stack` | Gen 1 | Fold when micro-stacked in SNG |
| `g1_steal_from_inactive` | Gen 1 | Steal blinds from sitting-out players |
| `g1_sage_endgame` | Gen 1 | Nash HU push/fold (13×13 tables) |
| `g1_push_or_fold` | Gen 1 | Push or fold preflop |
| `g1_blind_steal` | Gen 1 | Blind steal preflop |
| `g1_blind_resteal` | Gen 1 | Blind resteal preflop |
| `g1_postflop_rules` | Gen 1 | Static rules postflop |
| `g2_postflop_rollout` | Gen 2 | Original EHS postflop baseline |
| `g2_postflop_rollout_v4` | Gen 2 | Nut-aware postflop (trap + draw call + raise safety) + MC multi-way equity — **cash production** |
| `g2_nash_icm` | Gen 2 | Nash/ICM push/fold for SNG |
| `g3_postflop_rollout` | **Gen 3** | Range-aware postflop with MC multi-way equity, weighted decision scoring |

## Gen 2 V4 — Production Cash Strategy

**File:** `holdem_bots/src/cash/rollout_postflop_v4.rs` (~100 lines, thin wrapper)

### Equity Computation (hybrid dispatch in `RolloutPostFlopBase::compute_potential_mc`)
- **Heads-up (1 opponent):** Exhaustive enumeration (exact, trie-optimized)
- **Multi-way (2+ opponents):** `compute_multiway_uniform` — Monte Carlo with partial Fisher-Yates dealing, true multi-way equity against strongest opponent

### Decision Logic
All decision logic lives in `RolloutPostFlopBase` (`get_first_in_action`, `get_raised_pot_action`, `would_check_first_in`, etc.). V4 is a thin wrapper that computes equity then delegates.

### Production Fixes (inherited from V3, validated via A/B testing)
1. **F1: Check-raise trap protection** — rope-a-dope suppressed when `would_check_first_in()` is true
2. **F4: OTB draw-based call** — `adj_ppot > 0.25` call condition, disabled in true HU (2-seat tables)
3. **F7: Draw safety gate on raises** — non-nut draws blocked when `npot > npot_raise_ceiling`

### MC Parameters
- `mc_samples`: 10,000 default (quick tests), 20,000 (sweeps), 50,000 (production configs)
- `mc_seed`: 42 (reproducibility)
- See "MC Sample Count Guidelines" note for accuracy/speed tradeoffs

### V4 vs V3 Benchmark (10K hands, 5v5, 10 seeds)
V4 wins **6/10 seeds**, average edge **+0.34 BB/hand per seat**. V3 removed — V4 is the new production baseline.

### History
- **V2** (dropped): Nut-aware draw quality, hardcoded constants
- **V3** (dropped, superseded by V4): V2 + F1/F4/F7 fixes, exhaustive equity, 80 sweepable thresholds
- **V4** (current production): V3 decision logic + MC multi-way equity, 82 thresholds (incl. mc_samples/mc_seed)

id: 659da65d964344fc89e6b4eafac0098c
parent_id: 2c8da247905946c3aa19eb4936e16323
created_time: 2026-05-31T10:37:02.827Z
updated_time: 2026-06-15T08:01:58.662Z
is_conflict: 0
latitude: 0.00000000
longitude: 0.00000000
altitude: 0.0000
author: 
source_url: 
is_todo: 0
todo_due: 0
todo_completed: 0
source: joplin-desktop
source_application: net.cozic.joplin-desktop
application_data: 
order: 1780223822827
user_created_time: 2026-05-31T10:37:02.827Z
user_updated_time: 2026-06-15T08:01:58.662Z
encryption_cipher_text: 
encryption_applied: 0
markup_language: 1
is_shared: 0
share_id: 
conflict_original_id: 
master_key_id: 
user_data: 
deleted_time: 0
type_: 1