Fullhouse Poker Bot Research

中文版本 / Chinese README

This repository documents an end-to-end poker bot research project for the Fullhouse Hackathon No-Limit Texas Hold'em format. It covers rule-based strategy design, equity estimation, opponent profiling, field adaptation, ablation testing, validation, and packaging.

Project Snapshot

Item	Details
Domain	6-max 100BB No-Limit Texas Hold'em Swiss-format bot
Language	Primarily Python 3.10, with supporting JavaScript analysis scripts
Core interface	decide(game_state: dict) -> dict
Main engine	docs/official-fullhouse-engine/
Bot archive	docs/official-fullhouse-engine/bots/
Submission packages	提交/
Research records	docs/research-runs/, docs/dev-history/

Current Research Result

The final research line is the 13.x series, which used Qualification 1 match data to drive narrow fixes and cross-field validation. Representative versions for portfolio review are:

Version	Role	Summary
mybot_13_25_fold_to_raise_v1	Final candidate	Added opponent fold-to-raise tracking and gated bluff/steal adjustments.
mybot_13_24_gated_lucas_v1	Stable gated composite	Combined three Lucas-inspired improvements behind field-dependent gates.
mybot_13_17_board_filter_v1	Board-filter milestone	Added mathematical postflop board and range filtering.
mybot_13_6_field_adapt_v1	Mixed-field baseline	Added dynamic table-level VPIP/PFR field adaptation.
mybot_final_drawdiscipline_v1	Qualification 1 baseline	Independent Draw Discipline bot used as a stable reference.

What This Repository Demonstrates

• Iterative development from a baseline rule engine to multi-version strategy systems.
• Practical poker bot engineering: equity estimation, range modelling, opponent profiling, and risk gating.
• Experiment design with fixed seeds, Swiss rankings, A/B comparisons, ablations, and failure review.
• Evidence-gated decisions: several complex approaches were rejected or stopped when validation was weak.
• Public-facing documentation and privacy review for turning a competition workspace into a readable portfolio repository.

Repository Map

.
├── README.md                         # English public entry point
├── README.zh-CN.md                   # Chinese public entry point
├── docs/
│   ├── README.md                     # Documentation hub
│   ├── ARCHITECTURE.md               # System design
│   ├── DEVELOPMENT.md                # Development workflow
│   ├── RESEARCH_METHODOLOGY.md       # Experiment methodology
│   ├── REPRODUCIBILITY.md            # Reproduction notes
│   ├── PUBLICATION_REVIEW.md         # Public-release privacy review
│   ├── dev-history/                  # Version history
│   ├── research-runs/                # Experiment reports
│   └── official-fullhouse-engine/    # Engine and bot implementations
├── scripts/                          # Evaluation and analysis scripts
├── tools/                            # Research tools and dashboards
├── solver_external/                  # Optional solver assets
├── round1data/                       # Competition data snapshot
└── 提交/                             # Submission packages

Quick Start

The main bot workflow expects a Python 3.10 environment. If the bundled virtual environment is not available, recreate it from the official engine requirements first.

# Validate a bot
docs/official-fullhouse-engine/.venv310/Scripts/python.exe `
  docs/official-fullhouse-engine/sandbox/validator.py `
  docs/official-fullhouse-engine/bots/mybot_13_25_fold_to_raise_v1/bot.py --json

# Compile-check a bot
docs/official-fullhouse-engine/.venv310/Scripts/python.exe -m py_compile `
  docs/official-fullhouse-engine/bots/mybot_13_25_fold_to_raise_v1/bot.py

# Run a Swiss-style benchmark
docs/official-fullhouse-engine/.venv310/Scripts/python.exe scripts/swiss_massive_v2.py

Documentation

Document	Purpose
docs/README.md	Documentation hub and recommended reading order.
docs/ARCHITECTURE.md	Bot architecture, data flow, and design tradeoffs.
docs/DEVELOPMENT.md	Versioning, validation, packaging, and local workflow.
docs/RESEARCH_METHODOLOGY.md	Experiment design and promote/reject criteria.
docs/REPRODUCIBILITY.md	How to rerun core checks.
docs/PUBLICATION_REVIEW.md	Public-release privacy and safety review.
docs/PUBLIC_REPO_PLAN.md	Cleanup plan for public repository publishing.

Notes On Publication

This repository is a cleaned public portfolio version of a larger competition workspace. Private assistant state, local scratch data, portal snapshots, raw logs containing local paths, and other non-public artifacts were removed from the public history. The remaining history is intended to preserve meaningful development progression while avoiding personal email, real-name, and local-machine leakage.