# lofeodo/pokerrl architecture

> Architecture diagram of the GitHub repository lofeodo/pokerrl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lofeodo/pokerrl
- Repository: https://github.com/lofeodo/pokerrl

## Overview

##### Main Components Identification
- Data Ingestion & Extraction: Represent the scripts (like src/extract.py and related utilities) that download, extract, and preprocess the raw IRC Poker Database. This is the entry point for hand data (“hands.json”) which the README describes.
- Data Browsing & Exploration: Include the module (src/browse.py) that allows users to interactively view the extracted hands. This could be a stand-alone console-based interface.
- Poker Engine / Game Simulation: Identify central engines for poker-hand evaluation and game-state management. For instance, modules found in the CFRCode and src/Essai directories such as CFRNode.py, deck.py, handEvaluator.py, pokerAgent.py, pokerGameState.py, and surrounding modules that implement CFR strategies (e.g., depthLimitedCFR.py, depthLimitedSolver.py, selfPlay.py).
- Strategy & Model Components:
- CFR Training & Self-Play: Emphasize components responsible for agent training (train.py, selfPlay.py) which likely implement self-play routines and CFR-based game solving.
- Blueprint Files & Pickled Objects: Show that pre-computed strategies or blueprints (my_blueprint.pkl, blueprint.pkl, blueprint_strategy.pkl, enhanced_blueprint_strategy.pkl) are used as configuration or initialization for simulation/training.
- Advanced Model and Learning Modules (under “models”):
- BayesianHoldem: A model layer that appears to implement a Bayesian strategy for poker decision making.
- PyStack: A complex subsystem that includes a directory for data generation, a GUI (with client and server code), game simulation components, lookahead algorithms, neural network training routines, and associated helper classes. Note that it also contains several scripts (in models/PyStack/scripts) for distributing work, converting data formats, training neural nets, and running CFR routines.
- Benchmarking scripts: For performance evaluation of advanced strategies (such as in models/benchmarking).

##### Relationships and Interactions
- Data Flow: Begin with raw data ingestion from external sources → extraction (via extract.py) transforms data into the “hands.json” format → the hands are then available for interactive exploration (browse.py) and as input into simulation/training modules.
- Simulation Engine Flow: The game engine modules (CFRCode/src/Essai) process poker hands, evaluate states, and run self-play simulations. The results of these simulations might be used to generate or update blueprints (pickle files) and feed into agent training.
- External Dependencies and Environment Setup: Mark the environment (requirements.txt, environment.yml) and configuration tools (pyproject.toml) that support the entire pipeline.

##### Architectural Patterns & Design Principles
- Reusability & Extensibility: The directory structure (with multiple “blueprint” files and similar modules across CFRCode and src/Essai) suggests a design where components can be extended or replaced. Indicate the possibility of plugging in different algorithms (CFR, Bayesian, NN-based) for the poker agent.
- Pipelines: For the training modules (evident in PyStack and training_scripts), show how a pipeline might transform raw game data through structured steps (data generation, conversion, training) to yield improved strategies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Handling Subgraph
    subgraph "Data Handling"
        RawData["Raw IRC Poker Data"]:::external
        DataExtract["Data Extraction (src/extract.py)"]:::data
        HandsData["Hands Data (hands.json)"]:::datastore
        DataBrowse["Data Browsing (src/browse.py)"]:::data
        RawData -->|"ingests"| DataExtract
        DataExtract -->|"produces"| HandsData
        HandsData -->|"browsed by"| DataBrowse
    end

    %% Simulation and Training Subgraph
    subgraph "Simulation & Training"
        subgraph "CFR Based Simulation"
            CFRCode["Primary CFR Engine (CFRCode)"]:::engine
            Essai["Alternate CFR Engine (src/Essai)"]:::engine
            CFRCode -->|"outputs"| Blueprint["Blueprint & Strategy Files"]:::strategy
            Essai -->|"outputs"| Blueprint
        end
        SelfPlay["Self-Play & Training"]:::training
        DataBrowse -->|"feeds into"| SelfPlay
        Blueprint -->|"updates"| SelfPlay
    end

    %% Advanced Models and Learning Subgraph
    subgraph "Advanced Model & Learning"
        Bayesian["BayesianHoldem Model (models/BayesianHoldem)"]:::model
        subgraph "PyStack System (models/PyStack)"
            PyStackData["Data Generation"]:::pystack
            PyStackGUI["GUI"]:::pystack
            PyStackGame["Game Simulation"]:::pystack
            PyStackLookahead["Lookahead Algorithms"]:::pystack
            PyStackNN["Neural Network Training"]:::pystack
            PyStackTerminal["Terminal Equity"]:::pystack
            PyStackTree["Tree Structures"]:::pystack
            PyStackData -->|"feeds"| PyStackGUI
            PyStackGUI -->|"controls"| PyStackGame
            PyStackGame -->|"analyzes"| PyStackLookahead
            PyStackLookahead -->|"triggers"| PyStackNN
            PyStackNN -->|"evaluates"| PyStackTerminal
            PyStackTerminal -->|"structures"| PyStackTree
        end
        Bench["Benchmarking Suite (models/benchmarking)"]:::benchmark
        SelfPlay -->|"informs"| Bayesian
        SelfPlay -->|"supports"| PyStackGUI
        PyStackGUI -->|"benchmarks via"| Bench
    end

    %% External Dependencies
    Config["Configuration & Dependencies"]:::config
    DataExtract -->|"requires"| Config
    Bayesian -->|"configured by"| Config
    PyStackGame -->|"configured by"| Config

    %% Click Events
    click DataExtract "https://github.com/lofeodo/pokerrl/blob/main/src/extract.py"
    click DataBrowse "https://github.com/lofeodo/pokerrl/blob/main/src/browse.py"
    click CFRCode "https://github.com/lofeodo/pokerrl/tree/main/CFRCode/"
    click Essai "https://github.com/lofeodo/pokerrl/tree/main/src/Essai/"
    click Blueprint "https://github.com/lofeodo/pokerrl/blob/main/CFRCode/my_blueprint.pkl"
    click Bayesian "https://github.com/lofeodo/pokerrl/blob/main/models/BayesianHoldem/BayesianHoldem.py"
    click PyStackData "https://github.com/lofeodo/pokerrl/tree/main/models/PyStack/src/DataGeneration"
    click PyStackGUI "https://github.com/lofeodo/pokerrl/tree/main/models/PyStack/src/GUI"
    click PyStackGame "https://github.com/lofeodo/pokerrl/tree/main/models/PyStack/src/Game"
    click PyStackLookahead "https://github.com/lofeodo/pokerrl/tree/main/models/PyStack/src/Lookahead"
    click PyStackNN "https://github.com/lofeodo/pokerrl/tree/main/models/PyStack/src/NnTraining"
    click PyStackTerminal "https://github.com/lofeodo/pokerrl/tree/main/models/PyStack/src/TerminalEquity"
    click PyStackTree "https://github.com/lofeodo/pokerrl/tree/main/models/PyStack/src/Tree"
    click Bench "https://github.com/lofeodo/pokerrl/blob/main/models/benchmarking/DeepStackBenchmark.py"
    click Config "https://github.com/lofeodo/pokerrl/blob/main/environment.yml"

    %% Class Definitions for Coloring
    classDef external fill:#FFE4B5,stroke:#C71585,stroke-width:2px;
    classDef data fill:#F0E68C,stroke:#BDB76B,stroke-width:2px;
    classDef datastore fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef engine fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef training fill:#98FB98,stroke:#006400,stroke-width:2px;
    classDef strategy fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef model fill:#DDA0DD,stroke:#8B008B,stroke-width:2px;
    classDef pystack fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
    classDef benchmark fill:#F5DEB3,stroke:#DEB887,stroke-width:2px;
    classDef config fill:#FFFACD,stroke:#FFD700,stroke-width:2px;
```
