### Run a Poker Game with Setup and Start APIs

Source: https://context7.com/ishikota/pypokerengine/llms.txt

Use setup_config to define game rules and start_poker to execute the game. Register multiple AI players and run multi-round tournaments with configurable stack sizes and blind amounts. This example demonstrates setting up a game with an aggressive player.

```python
from pypokerengine.api.game import setup_config, start_poker
from pypokerengine.players import BasePokerPlayer

class AggressivePlayer(BasePokerPlayer):
    def declare_action(self, valid_actions, hole_card, round_state):
        raise_action = valid_actions[2]
        amount = raise_action["amount"]
        if isinstance(amount, dict):
            return "raise", amount["min"]  # Minimum raise
        return "call", valid_actions[1]["amount"]

    def receive_game_start_message(self, game_info): pass
    def receive_round_start_message(self, round_count, hole_card, seats): pass
    def receive_street_start_message(self, street, round_state): pass
    def receive_game_update_message(self, action, round_state): pass
    def receive_round_result_message(self, winners, hand_info, round_state): pass

# Setup game configuration
config = setup_config(
    max_round=10,           # Number of rounds to play
    initial_stack=100,      # Starting chip count per player
    small_blind_amount=5,   # Small blind amount
    ante=0                  # Ante amount (optional)
)

# Register players (minimum 2, no maximum specified)
config.register_player(name="player1", algorithm=AggressivePlayer())
config.register_player(name="player2", algorithm=AggressivePlayer())
config.register_player(name="player3", algorithm=AggressivePlayer())

# Optional: Set blind structure for tournament-style increases
config.set_blind_structure({
    5: {"ante": 5, "small_blind": 10},   # Round 5: ante=5, SB=10
    10: {"ante": 10, "small_blind": 20}  # Round 10: ante=10, SB=20
})

# Start the game (verbose: 0=silent, 1=basic, 2=detailed)
game_result = start_poker(config, verbose=1)

# Result format:
# {
#   'rule': {'ante': 0, 'blind_structure': {}, 'max_round': 10,
#            'initial_stack': 100, 'small_blind_amount': 5},
#   'players': [
#     {'stack': 150, 'state': 'participating', 'name': 'player1', 'uuid': 'xxx'},
#     {'stack': 50, 'state': 'participating', 'name': 'player2', 'uuid': 'yyy'},
#     {'stack': 100, 'state': 'participating', 'name': 'player3', 'uuid': 'zzz'}
#   ]
# }
```

--------------------------------

### Setup and Start Poker Game with Custom Players

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/estimate_card_strength.md

Configures and starts a poker game using PyPokerEngine, registering custom player algorithms like 'FishPlayer' and 'HonestPlayer'. It prints the final player stacks after the game concludes.

```python
>>> from pypokerengine.api.game import setup_config, start_poker
>>> config = setup_config(max_round=10, initial_stack=100, small_blind_amount=5)
>>> config.register_player(name="fish_player", algorithm=FishPlayer())
>>> config.register_player(name="honest_player", algorithm=HonestPlayer())
>>> game_result = start_poker(config, verbose=1)
>>> for player_info in game_result["players"]:
...     print player_info
...
{'stack': 145, 'state': 'participating', 'name': 'fish_player', 'uuid': 'dziwzwkoqadaobrjxrfwog'}
{'stack': 55, 'state': 'participating', 'name': 'honest_player', 'uuid': 'lcyzcxzbkuzvoyzlkommyt'}
```

--------------------------------

### Game Start Information Display

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/participate_in_the_game.md

This output shows the initial game setup, including the number of players, rounds, starting stack, and blind amounts.

```text
-- Game start (UUID = qrnewmfzuyacjscxpfftgy) --
======================================================================
-- rule --
  - 2 players game
  - 10 round
  - start stack = 100
  -        ante = 0
  - small blind = 5
======================================================================
Enter some key to continue ... <ENTER>
```

--------------------------------

### Start Poker Game with Custom Players

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/simulate_the_game_by_emulator.md

Configure and start a poker game simulation using pypokerengine. This example registers a FishPlayer and an EmulatorPlayer, then runs the game, displaying debug information and the final outcome.

```python
>>> from pypokerengine.api.game import setup_config, start_poker
>>> config = setup_config(max_round=10, initial_stack=100, small_blind_amount=5)
>>> config.register_player(name="fish_player", algorithm=FishPlayer())
>>> config.register_player(name="emulator_player", algorithm=EmulatorPlayer())
>>> game_result = start_poker(config, verbose=1)
```

--------------------------------

### Setup and Start Poker Game

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/participate_in_the_game.md

Configure game rules, register players (AI and human), and initiate the poker game. Set verbose to 0 to disable console output during gameplay.

```python
from pypokerengine.api.game import setup_config, start_poker

config = setup_config(max_round=10, initial_stack=100, small_blind_amount=5)
config.register_player(name="fish_player", algorithm=FishPlayer())
config.register_player(name="human_player", algorithm=ConsolePlayer())
game_result = start_poker(config, verbose=0)  # verbose=0 because game progress is visualized by ConsolePlayer
```

--------------------------------

### Install PyPokerEngine

Source: https://github.com/ishikota/pypokerengine/blob/master/README.md

Install the PyPokerEngine library using pip. This library supports Python 2.7 and Python 3.5+.

```bash
pip install PyPokerEngine
```

--------------------------------

### Start Poker Game with Configuration

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/simulate_the_game_by_emulator.md

Initiates a poker game with specified configurations for rounds, initial stacks, and blinds. Registers player algorithms before starting the game. Use this for a standard game run.

```python
from pypokerengine.api.game import setup_config, start_poker
>>> config = setup_config(max_round=10, initial_stack=100, small_blind_amount=5)
>>> config.register_player(name="fish_player", algorithm=FishPlayer())
>>> config.register_player(name="honest_player", algorithm=HonestPlayer())
>>> game_result = start_poker(config, verbose=1)
```

--------------------------------

### Sample hole_card for receive_round_start_message

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

The player's two private cards at the start of a round. Example shows two cards.

```json
['C2', 'HQ']
```

--------------------------------

### Start New Round with Initial Game State

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/documentation/about_emulator.md

Manually starts a new round using the `emulator.start_new_round` method with a pre-generated initial game state. This is necessary before running simulations.

```python
game_state, events = emulator.start_new_round(initial_game_state)
```

--------------------------------

### Setup Emulator for Reinforcement Learning

Source: https://github.com/ishikota/pypokerengine/blob/master/README.md

This snippet demonstrates how to set up the Emulator class for Reinforcement Learning by registering game information and AI player models. It's used within a custom player class that inherits from BasePokerPlayer.

```python
from pypokerengine.players import BasePokerPlayer
from pypokerengine.api.emulator import Emulator
from pypokerengine.utils.game_state_utils import restore_game_state

from mymodule.poker_ai.player_model import SomePlayerModel

class RLPLayer(BasePokerPlayer):

    # Setup Emulator object by registering game information
    def receive_game_start_message(self, game_info):
        player_num = game_info["player_num"]
        max_round = game_info["rule"]["max_round"]
        small_blind_amount = game_info["rule"]["small_blind_amount"]
        ante_amount = game_info["rule"]["ante"]
        blind_structure = game_info["rule"]["blind_structure"]
        
        self.emulator = Emulator()
        self.emulator.set_game_rule(player_num, max_round, small_blind_amount, ante_amount)
        self.emulator.set_blind_structure(blind_structure)
        
        # Register algorithm of each player which used in the simulation.
        for player_info in game_info["seats"]["players"]:
            self.emulator.register_player(player_info["uuid"], SomePlayerModel())

    def declare_action(self, valid_actions, hole_card, round_state):
        game_state = restore_game_state(round_state)
        # decide action by using some simulation result
        # updated_state, events = self.emulator.apply_action(game_state, "fold")
        # updated_state, events = self.emulator.run_until_round_finish(game_state)
        # updated_state, events = self.emulator.run_until_game_finish(game_state)
        if self.is_good_simulation_result(updated_state):
            return # you would declare CALL or RAISE action
        else:
            return "fold", 0
    

```

--------------------------------

### Generate Initial Game State

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/documentation/about_emulator.md

Example of generating a clean, initial GameState object using the `emulator.generate_initial_game_state` method.

```python
initial_game_state = emulator.generate_initial_game_state(players_info)
```

--------------------------------

### Play a Poker Game with Custom AIs

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/index.md

Set up and start a poker game using the PyPokerEngine API. Configure game rules, register AI players, and initiate the game.

```python
from pypokerengine.api.game import setup_config, start_poker

config = setup_config(max_round=10, initial_stack=100, small_blind_amount=5)
config.register_player(name="p1", algorithm=FishPlayer())
config.register_player(name="p2", algorithm=FishPlayer())
config.register_player(name="p3", algorithm=FishPlayer())
game_result = start_poker(config, verbose=1)
```

--------------------------------

### receive_street_start_message Callback Arguments

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

Arguments for the receive_street_start_message method, called at the start of each street (preflop, flop, turn, river).

```APIDOC
## receive_street_start_message(self, street, round_state)

### Description
This method is called at the beginning of each street (preflop, flop, turn, river). It provides the name of the current street and the overall round state.

### Method
`receive_street_start_message`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **street** (str) - Required - The name of the current street (e.g., 'preflop', 'flop', 'turn', 'river').
- **round_state** (dict) - Required - The current state of the poker round, including round count, dealer position, blinds, community cards, seat information, pot details, and action histories.

### Request Example
```json
{
  "street": "preflop",
  "round_state": {
    "round_count": 1,
    "dealer_btn": 0,
    "small_blind_pos": 1,
    "big_blind_pos": 2,
    "next_player": 0,
    "small_blind_amount": 10,
    "street": "preflop",
    "community_card": [],
    "seats": [
      {"stack": 95, "state": "participating", "name": "p1", "uuid": "ftwdqkystzsqwjrzvludgi"},
      {"stack": 85, "state": "participating", "name": "p2", "uuid": "bbiuvgalrglojvmgggydyt"},
      {"stack": 75, "state": "participating", "name": "p3", "uuid": "zkbpehnazembrxrihzxnmt"}
    ],
    "pot": {"main": {"amount": 45}, "side": [] },
    "action_histories": {
      "preflop": [
        {"action": "ANTE", "amount": 5, "uuid": "bbiuvgalrglojvmgggydyt"},
        {"action": "ANTE", "amount": 5, "uuid": "zkbpehnazembrxrihzxnmt"},
        {"action": "ANTE", "amount": 5, "uuid": "ftwdqkystzsqwjrzvludgi"},
        {"action": "SMALLBLIND", "amount": 10, "add_amount": 10, "uuid": "bbiuvgalrglojvmgggydyt"},
        {"action": "BIGBLIND", "amount": 20, "add_amount": 10, "uuid": "zkbpehnazembrxrihzxnmt"}
      ]
    }
  }
}
```

### Response
#### Success Response (200)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Process Game Events with Emulator

Source: https://context7.com/ishikota/pypokerengine/llms.txt

This snippet demonstrates how to set up a game, run it to completion, and iterate through all generated events to process different game states like new streets, player actions, round finishes, and game finishes. Ensure all necessary players and game rules are configured before starting.

```python
from pypokerengine.api.emulator import Emulator, Event
from pypokerengine.players import BasePokerPlayer

class DummyPlayer(BasePokerPlayer):
    def declare_action(self, valid_actions, hole_card, round_state):
        return "call", valid_actions[1]["amount"]
    def receive_game_start_message(self, game_info): pass
    def receive_round_start_message(self, round_count, hole_card, seats): pass
    def receive_street_start_message(self, street, round_state): pass
    def receive_game_update_message(self, action, round_state): pass
    def receive_round_result_message(self, winners, hand_info, round_state): pass

# Setup game
emulator = Emulator()
emulator.set_game_rule(player_num=2, max_round=3, small_blind_amount=5, ante_amount=0)
emulator.register_player("p1", DummyPlayer())
emulator.register_player("p2", DummyPlayer())

players_info = {"p1": {"name": "A", "stack": 100}, "p2": {"name": "B", "stack": 100}}
game_state = emulator.generate_initial_game_state(players_info)
game_state, events = emulator.start_new_round(game_state)

# Run complete game and process all events
game_state, all_events = emulator.run_until_game_finish(game_state)

for event in all_events:
    event_type = event["type"]

    if event_type == Event.NEW_STREET:
        # New betting round started
        street = event["street"]  # 'preflop', 'flop', 'turn', 'river'
        community = event["round_state"]["community_card"]
        print(f"Street: {street}, Community: {community}")

    elif event_type == Event.ASK_PLAYER:
        # Player's turn to act
        uuid = event["uuid"]
        valid_actions = event["valid_actions"]
        print(f"Player {uuid} to act: {[a['action'] for a in valid_actions]}")

    elif event_type == Event.ROUND_FINISH:
        # Round completed
        winners = event["winners"]
        for winner in winners:
            print(f"Round winner: {winner['uuid']} (stack: {winner['stack']})")

    elif event_type == Event.GAME_FINISH:
        # Game completed
        print("Final results:")
        for player in event["players"]:
            print(f"  {player['uuid']}: {player['stack']} chips")

```

--------------------------------

### Sample game_info for receive_game_start_message

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

Information provided at the start of a game, including player count, rule configurations (ante, blind structure, max rounds, initial stack), and initial seat assignments.

```json
{
  'player_num': 3,
  'rule': {
    'ante': 5,
    'blind_structure': {
      5 : { "ante": 10, "small_blind": 20 },
      7 : { "ante": 15, "small_blind": 30 }
    },
    'max_round': 10,
    'initial_stack': 100,
    'small_blind_amount': 10
  },
  'seats': [
    {'stack': 100, 'state': 'participating', 'name': 'p1', 'uuid': 'ftwdqkystzsqwjrzvludgi'},
    {'stack': 100, 'state': 'participating', 'name': 'p2', 'uuid': 'bbiuvgalrglojvmgggydyt'},
    {'stack': 100, 'state': 'participating', 'name': 'p3', 'uuid': 'zkbpehnazembrxrihzxnmt'}
  ]
}
```

--------------------------------

### Play AI vs AI Poker Game in Python

Source: https://github.com/ishikota/pypokerengine/blob/master/README.md

Set up and start a poker game with multiple AI players. Configure game rules like max rounds and initial stack, then register players and initiate the game.

```python
from pypokerengine.api.game import setup_config, start_poker

config = setup_config(max_round=10, initial_stack=100, small_blind_amount=5)
config.register_player(name="p1", algorithm=FishPlayer())
config.register_player(name="p2", algorithm=FishPlayer())
config.register_player(name="p3", algorithm=FishPlayer())
game_result = start_poker(config, verbose=1)

```

--------------------------------

### Create a Simple AI Player in Python

Source: https://github.com/ishikota/pypokerengine/blob/master/README.md

Define a poker AI by subclassing BasePokerPlayer and implementing the declare_action method. This example AI always chooses to call.

```python
from pypokerengine.players import BasePokerPlayer

class FishPlayer(BasePokerPlayer):

    def declare_action(self, valid_actions, hole_card, round_state):
        call_action_info = valid_actions[1]
        action, amount = call_action_info["action"], call_action_info["amount"]
        return action, amount

    def receive_game_start_message(self, game_info):
        pass

    def receive_round_start_message(self, round_count, hole_card, seats):
        pass

    def receive_street_start_message(self, street, round_state):
        pass

    def receive_game_update_message(self, action, round_state):
        pass

    def receive_round_result_message(self, winners, hand_info, round_state):
        pass

```

--------------------------------

### New Street Start Information

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/participate_in_the_game.md

Indicates the start of a new street (e.g., preflop) in the poker round, showing community cards and pot status.

```text
-- New street start (UUID = qrnewmfzuyacjscxpfftgy) --
======================================================================
-- street --
  - preflop
======================================================================
Enter some key to continue ...

```

--------------------------------

### receive_round_start_message Callback Arguments

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

Arguments for the receive_round_start_message method, called at the start of each new round.

```APIDOC
## receive_round_start_message(self, round_count, hole_card, seats)

### Description
This method is called at the beginning of each new round. It provides the round number, the player's hole cards, and the current state of the seats.

### Method
`receive_round_start_message`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **round_count** (int) - Required - The current round number.
- **hole_card** (list of str) - Required - The player's two hole cards for this round.
- **seats** (list of dict) - Required - The current state of each player's seat, including stack size and participation status.

### Request Example
```json
{
  "round_count": 2,
  "hole_card": ["C2", "HQ"],
  "seats": [
    {"stack": 135, "state": "participating", "name": "p1", "uuid": "ftwdqkystzsqwjrzvludgi"},
    {"stack": 80, "state": "participating", "name": "p2", "uuid": "bbiuvgalrglojvmgggydyt"},
    {"stack": 40, "state": "participating", "name": "p3", "uuid": "zkbpehnazembrxrihzxnmt"}
  ]
}
```

### Response
#### Success Response (200)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Sample seats for receive_round_start_message

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

The state of each player's seat at the start of a round, including their current stack, participation status, name, and unique identifier.

```json
[
  {'stack': 135, 'state': 'participating', 'name': 'p1', 'uuid': 'ftwdqkystzsqwjrzvludgi'},
  {'stack': 80, 'state': 'participating', 'name': 'p2', 'uuid': 'bbiuvgalrglojvmgggydyt'},
  {'stack': 40, 'state': 'participating', 'name': 'p3', 'uuid': 'zkbpehnazembrxrihzxnmt'}
]
```

--------------------------------

### Sample hole_card for declare_action

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

Represents the two private cards dealt to a player. Example shows two cards.

```json
['CA', 'DK']
```

--------------------------------

### Round 1 Start and Player Information

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/participate_in_the_game.md

Displays the beginning of Round 1, including hole cards for players and their current state and stack.

```text
-- Round 1 start (UUID = qrnewmfzuyacjscxpfftgy) --
======================================================================
-- hole card --
  - ['CA', 'D2']
-- players information --
  - 0 : fish_player (vhchlzkojrabhiomwdbpem) => state : participating, stack : 90
  - 1 : human_player (qrnewmfzuyacjscxpfftgy) => state : participating, stack : 95
======================================================================
Enter some key to continue ... <ENTER>
```

--------------------------------

### Create a Simple Poker AI Player

Source: https://context7.com/ishikota/pypokerengine/llms.txt

Implement the BasePokerPlayer class to create a poker AI. The declare_action method is the core decision-making function. This example shows an AI that always calls.

```python
from pypokerengine.players import BasePokerPlayer

class SimpleCallPlayer(BasePokerPlayer):
    """AI that always calls - good starting point for poker AI development"""

    def declare_action(self, valid_actions, hole_card, round_state):
        # valid_actions format:
        # [
        #   {'action': 'fold', 'amount': 0},
        #   {'action': 'call', 'amount': 10},
        #   {'action': 'raise', 'amount': {'max': 100, 'min': 20}}
        # ]
        call_action = valid_actions[1]
        return call_action["action"], call_action["amount"]

    def receive_game_start_message(self, game_info):
        # game_info contains: player_num, rule (max_round, initial_stack,
        # small_blind_amount, ante, blind_structure), seats
        self.player_num = game_info["player_num"]

    def receive_round_start_message(self, round_count, hole_card, seats):
        # hole_card format: ['CA', 'DK'] (C=Club, D=Diamond, H=Heart, S=Spade)
        # seats: list of player info with stack, state, name, uuid
        pass

    def receive_street_start_message(self, street, round_state):
        # street: 'preflop', 'flop', 'turn', 'river'
        pass

    def receive_game_update_message(self, new_action, round_state):
        # new_action: {'player_uuid': 'xxx', 'action': 'raise', 'amount': 30}
        pass

    def receive_round_result_message(self, winners, hand_info, round_state):
        # winners: list of winner info with stack, state, name, uuid
        # hand_info: list of hand evaluation for each player
        pass
```

--------------------------------

### Event Objects from Emulator Simulation

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/documentation/about_emulator.md

Example of event objects returned by `emulator.start_new_round`. Events provide information about occurrences during simulation, such as new streets or player actions.

```python
>>> game_state, events = emulator.start_new_round(initial_state)
>>> events
[
  {
   'type': 'event_new_street',
   'street': 'preflop',
   'round_state': ...
  },
  {
   'type': 'event_ask_player',
   'uuid': 'uuid-1',
   'valid_actions': [{'action': 'fold', 'amount': 0}, ...]
  }
]
```

--------------------------------

### Initialize and Run Emulator Simulation

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/documentation/about_emulator.md

Demonstrates the common usage of Emulator: setting game rules, setting up the initial game state, and running a simulation step.

```python
from pypokerengine.api.emulator import Emulator

# 1. Set game settings on emulator
emulator = Emulator()
emulator.set_game_rule(nb_player, final_round, sb_amount, ante)
emulator.set_game_rule(player_num=3, max_round=10, small_blind_amount=5, ante_amount=1)

# 2. Setup GameState object
players_info = {
    "uuid-1": { "name": "player1", "stack": 100 },
    "uuid-2": { "name": "player2", "stack": 100 },
    "uuid-3": { "name": "player3", "stack": 80 }
}
initial_state = emulator.generate_initial_game_state(players_info)
game_state, events = emulator.start_new_round(initial_state)

# 3. Run simulation and get updated GameState object
updated_state, events = emulator.apply_action(game_state, "call", 10)
```

--------------------------------

### Initialize Emulator with Game Settings

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/simulate_the_game_by_emulator.md

Sets up the Emulator object with core game rules such as the number of players, maximum rounds, small blind amount, and ante amount. This is the first step before registering players or simulating game states.

```python
from pypokerengine.api.emulator import Emulator

emulator = Emulator()
emulator.set_game_rule(nb_player=2, max_round=10, sb_amount=5, ante_amount=0)
```

--------------------------------

### Initialize and Use Emulator for RL

Source: https://context7.com/ishikota/pypokerengine/llms.txt

Use the Emulator class for step-by-step game simulation, essential for reinforcement learning. Register player models, set game rules, and manipulate game states.

```python
from pypokerengine.api.emulator import Emulator
from pypokerengine.players import BasePokerPlayer

class DummyPlayer(BasePokerPlayer):
    """Required for Emulator player registration"""
    def declare_action(self, valid_actions, hole_card, round_state):
        return valid_actions[1]["action"], valid_actions[1]["amount"]  # Always call
    def receive_game_start_message(self, game_info): pass
    def receive_round_start_message(self, round_count, hole_card, seats): pass
    def receive_street_start_message(self, street, round_state): pass
    def receive_game_update_message(self, action, round_state): pass
    def receive_round_result_message(self, winners, hand_info, round_state): pass

# Initialize emulator with game rules
emulator = Emulator()
emulator.set_game_rule(
    player_num=3,
    max_round=10,
    small_blind_amount=5,
    ante_amount=1
)

# Register player models for simulation
emulator.register_player("uuid-1", DummyPlayer())
emulator.register_player("uuid-2", DummyPlayer())
emulator.register_player("uuid-3", DummyPlayer())

# Create initial game state
players_info = {
    "uuid-1": {"name": "player1", "stack": 100},
    "uuid-2": {"name": "player2", "stack": 100},
    "uuid-3": {"name": "player3", "stack": 80}
}
initial_state = emulator.generate_initial_game_state(players_info)

# Start a new round (required before applying actions)
game_state, events = emulator.start_new_round(initial_state)

# Apply individual actions for RL training
game_state, events = emulator.apply_action(game_state, "call", 10)
game_state, events = emulator.apply_action(game_state, "raise", 20)
game_state, events = emulator.apply_action(game_state, "fold", 0)

# Or run until round/game finishes
game_state, events = emulator.run_until_round_finish(game_state)
game_state, events = emulator.run_until_game_finish(game_state)

# Events contain game progression info:
# - event_new_street: New betting round started
# - event_ask_player: Player's turn to act
# - event_round_finish: Round completed with winners
# - event_game_finish: Game completed
for event in events:
    if event["type"] == "event_round_finish":
        print(f"Round winner: {event['winners']}")
    elif event["type"] == "event_game_finish":
        print(f"Final standings: {event['players']}")
```

--------------------------------

### Sample valid_actions for declare_action

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

This shows the possible actions a player can take and the associated betting amounts. The 'raise' action includes minimum and maximum bet limits.

```json
[
  {'action': 'fold', 'amount': 0},
  {'action': 'call', 'amount': 0},
  {'action': 'raise', 'amount': {'max': 95, 'min': 20}}
]
```

--------------------------------

### receive_game_start_message Callback Arguments

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

Arguments for the receive_game_start_message method, called at the beginning of a new game.

```APIDOC
## receive_game_start_message(self, game_info)

### Description
This method is called once at the beginning of a game. It provides information about the game rules and initial seat assignments.

### Method
`receive_game_start_message`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **game_info** (dict) - Required - Contains details about the game, including player count, rules (ante, blind structure, max rounds, initial stack, small blind amount), and initial seat assignments.

### Request Example
```json
{
  "game_info": {
    "player_num": 3,
    "rule": {
      "ante": 5,
      "blind_structure": {
        "5": {"ante": 10, "small_blind": 20},
        "7": {"ante": 15, "small_blind": 30}
      },
      "max_round": 10,
      "initial_stack": 100,
      "small_blind_amount": 10
    },
    "seats": [
      {"stack": 100, "state": "participating", "name": "p1", "uuid": "ftwdqkystzsqwjrzvludgi"},
      {"stack": 100, "state": "participating", "name": "p2", "uuid": "bbiuvgalrglojvmgggydyt"},
      {"stack": 100, "state": "participating", "name": "p3", "uuid": "zkbpehnazembrxrihzxnmt"}
    ]
  }
}
```

### Response
#### Success Response (200)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Simulate Game State with Emulator

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/simulate_the_game_by_emulator.md

Use emulator methods to progress game simulation and retrieve updated game states and events. Choose between step-by-step, round-by-round, or full game simulation.

```python
>>> emulator.set_game_rule(nb_player, max_round=10, sb_amount=5, ante_amount=0)
>>> next_turn_state, events = emulator.apply_action(current_state, 'call', 10)
>>> round_finish_state, events = emulator.run_until_round_finish(current_state)
>>> game_finish_state, events = emulator.run_until_game_finish(current_state)
```

```python
>>> current_state['round_count'], current_state['street'], current_state['next_player']
(1, 0, 0)  # street_flg == 0 means PREFLOP
```

```python
>>> next_turn_state['round_count'], next_turn_state['street'], next_turn_state['next_player']
(1, 0, 1)
```

```python
>>> round_finish_state['round_count'], round_finish_state['street'], round_finish_state['next_player']
(1, 5, 0)  # street_flg == 5 means SHOWDOWN
```

```python
>>> game_finish_state['round_count'], game_finish_state['street'], game_finish_state['next_player']
(10, 5, 0)  # simulation is finished at 10 round because we set max_round=10
```

--------------------------------

### Generate Possible Actions with Emulator

Source: https://context7.com/ishikota/pypokerengine/llms.txt

Use `Emulator.generate_possible_actions` to retrieve a list of legal actions for the current player in a given game state. This is essential for implementing action selection logic and ensuring valid moves.

```python
from pypokerengine.api.emulator import Emulator, Action

# Setup emulator
emulator = Emulator()
emulator.set_game_rule(player_num=2, max_round=5, small_blind_amount=10, ante_amount=0)

# Create and start game
players_info = {
    "player-1": {"name": "Hero", "stack": 100},
    "player-2": {"name": "Villain", "stack": 100}
}
initial_state = emulator.generate_initial_game_state(players_info)
game_state, events = emulator.start_new_round(initial_state)

# Get valid actions for current player
possible_actions = emulator.generate_possible_actions(game_state)
# Returns:
# [
#   {'action': 'fold', 'amount': 0},
#   {'action': 'call', 'amount': 20},
#   {'action': 'raise', 'amount': {'min': 40, 'max': 100}}
# ]

print("Legal actions:")
for action_info in possible_actions:
    action = action_info["action"]
    amount = action_info["amount"]
    if action == Action.FOLD:
        print(f"  - Fold")
    elif action == Action.CALL:
        print(f"  - Call: {amount}")
    elif action == Action.RAISE:
        print(f"  - Raise: min={amount['min']}, max={amount['max']}")

# Apply a valid action
if possible_actions[2]["amount"]["max"] >= 50:
    game_state, events = emulator.apply_action(game_state, "raise", 50)
else:
    game_state, events = emulator.apply_action(game_state, "call", possible_actions[1]["amount"])
```

--------------------------------

### Create a Basic Poker AI Player

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/index.md

Implement the BasePokerPlayer class to define your AI's decision-making logic. The declare_action method is crucial for determining the AI's move.

```python
from pypokerengine.players import BasePokerPlayer

class FishPlayer(BasePokerPlayer):

    def declare_action(self, valid_actions, hole_card, round_state):
        call_action_info = valid_actions[1]
        action, amount = call_action_info["action"], call_action_info["amount"]
        return action, amount

    def receive_game_start_message(self, game_info):
        pass

    def receive_round_start_message(self, round_count, hole_card, seats):
        pass

    def receive_street_start_message(self, street, round_state):
        pass

    def receive_game_update_message(self, action, round_state):
        pass

    def receive_round_result_message(self, winners, hand_info, round_state):
        pass
```

--------------------------------

### Sample round_state for declare_action

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

Detailed state of the current poker round, including round number, dealer position, blinds, community cards, player states, pot details, and action history.

```json
{
  'round_count': 2,
  'dealer_btn': 1,
  'small_blind_pos': 2,
  'big_blind_pos': 0,
  'next_player': 0,
  'small_blind_amount': 10,
  'street': 'turn',
  'community_card': ['DJ', 'H6', 'S6', 'H5'],
  'seats': [
    {'stack': 95, 'state': 'participating', 'name': 'p1', 'uuid': 'ftwdqkystzsqwjrzvludgi'},
    {'stack': 20, 'state': 'participating', 'name': 'p2', 'uuid': 'bbiuvgalrglojvmgggydyt'},
    {'stack': 0, 'state': 'allin', 'name': 'p3', 'uuid': 'zkbpehnazembrxrihzxnmt'}
  ],
  'pot': {
    'main': {'amount': 165},
    'side': [{'amount': 20, 'eligibles': ['ftwdqkystzsqwjrzvludgi', 'bbiuvgalrglojvmgggydyt']}]
  },
  'action_histories': {
    'preflop': [
      {'action': 'ANTE', 'amount': 5, 'uuid': 'zkbpehnazembrxrihzxnmt'},
      {'action': 'ANTE', 'amount': 5, 'uuid': 'ftwdqkystzsqwjrzvludgi'},
      {'action': 'ANTE', 'amount': 5, 'uuid': 'bbiuvgalrglojvmgggydyt'},
      {'action': 'SMALLBLIND', 'amount': 10, 'add_amount': 10, 'uuid': 'zkbpehnazembrxrihzxnmt'},
      {'action': 'BIGBLIND', 'amount': 20, 'add_amount': 10, 'uuid': 'ftwdqkystzsqwjrzvludgi'},
      {'action': 'CALL', 'amount': 20, 'uuid': 'bbiuvgalrglojvmgggydyt', 'paid': 20},
      {'action': 'RAISE', 'amount': 30, 'add_amount': 10, 'paid': 20, 'uuid': 'zkbpehnazembrxrihzxnmt'},
      {'action': 'CALL', 'amount': 30, 'uuid': 'ftwdqkystzsqwjrzvludgi', 'paid': 10},
      {'action': 'CALL', 'amount': 30, 'uuid': 'bbiuvgalrglojvmgggydyt', 'paid': 10}
    ],
    'flop': [
      {'action': 'CALL', 'amount': 0, 'uuid': 'zkbpehnazembrxrihzxnmt', 'paid': 0},
      {'action': 'RAISE', 'amount': 30, 'add_amount': 30, 'paid': 30, 'uuid': 'ftwdqkystzsqwjrzvludgi'},
      {'action': 'CALL', 'amount': 30, 'uuid': 'bbiuvgalrglojvmgggydyt', 'paid': 30},
      {'action': 'CALL', 'amount': 20, 'uuid': 'zkbpehnazembrxrihzxnmt', 'paid': 20}
     ],
    'turn': []
  }
}
```

--------------------------------

### Sample round_state for receive_street_start_message

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

The state of the poker round at the beginning of a new street. Includes round count, dealer, blinds, community cards, player seats, pot details, and action history up to that point.

```json
{
  'round_count': 1,
  'dealer_btn': 0,
  'small_blind_pos': 1,
  'big_blind_pos': 2,
  'next_player': 0,
  'small_blind_amount': 10,
  'street': 'preflop',
  'community_card': [],
  'seats': [
    {'stack': 95, 'state': 'participating', 'name': 'p1', 'uuid': 'ftwdqkystzsqwjrzvludgi'},
    {'stack': 85, 'state': 'participating', 'name': 'p2', 'uuid': 'bbiuvgalrglojvmgggydyt'},
    {'stack': 75, 'state': 'participating', 'name': 'p3', 'uuid': 'zkbpehnazembrxrihzxnmt'}
   ],
  'pot': {'main': {'amount': 45}, 'side': [] },
  'action_histories': {
    'preflop': [
      {'action': 'ANTE', 'amount': 5, 'uuid': 'bbiuvgalrglojvmgggydyt'},
      {'action': 'ANTE', 'amount': 5, 'uuid': 'zkbpehnazembrxrihzxnmt'},
      {'action': 'ANTE', 'amount': 5, 'uuid': 'ftwdqkystzsqwjrzvludgi'},
      {'action': 'SMALLBLIND', 'amount': 10, 'add_amount': 10, 'uuid': 'bbiuvgalrglojvmgggydyt'},
      {'action': 'BIGBLIND', 'amount': 20, 'add_amount': 10, 'uuid': 'zkbpehnazembrxrihzxnmt'}
    ]
  }
}
```

--------------------------------

### Print Game Result in Python

Source: https://github.com/ishikota/pypokerengine/blob/master/README.md

Display the final game result, including rule configurations and player statistics, after a PyPokerEngine game simulation.

```python
>>> print game_result
{
  'rule': {'ante': 0, 'blind_structure': {}, 'max_round': 10, 'initial_stack': 100, 'small_blind_amount': 5},
  'players': [
    {'stack': 150, 'state': 'participating', 'name': 'p1', 'uuid': 'ijaukuognlkplasfspehcp'},
    {'stack': 30, 'state': 'participating', 'name': 'p2', 'uuid': 'uadjzyetdwsaxzflrdsysj'},
    {'stack': 120, 'state': 'participating', 'name': 'p3', 'uuid': 'tmnkoazoqitkzcreihrhao'}
  ]
}

```

--------------------------------

### EmulatorPlayer Decision Logic

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/simulate_the_game_by_emulator.md

This Python pseudocode outlines the decision-making process for an EmulatorPlayer. It involves simulating outcomes for different actions (FOLD, CALL, MIN_RAISE, MAX_RAISE) and selecting the action that maximizes the player's stack.

```python
try_actions = [FOLD, CALL, MIN_RAISE, MAX_RAISE]
action_score = [0, 0, 0, 0]

for try_action in try_actions:
    # my_model <- setup my model to declare "try_action" anytime
    simulation_results = []
    for i in range(NB_SIMULATION):
        # updated_state <- run the simulation until current round finishes
        # result <- fetch stack of EmulatorPlayer in the updated_state
        simulation_results.append(result)
    # action_score <- average simulation_results

# best_action <- choose action which gets highest action_score
return best_action
```

--------------------------------

### Implement ConsolePlayer for Poker Game

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/participate_in_the_game.md

This class extends `BasePokerPlayer` to enable console interaction. It visualizes game states and prompts the user for actions. Note: Error handling for user input is omitted for simplicity.

```python
import pypokerengine.utils.visualize_utils as U

class ConsolePlayer(BasePokerPlayer):

    def declare_action(self, valid_actions, hole_card, round_state):
        print(U.visualize_declare_action(valid_actions, hole_card, round_state, self.uuid))
        action, amount = self._receive_action_from_console(valid_actions)
        return action, amount

    def receive_game_start_message(self, game_info):
        print(U.visualize_game_start(game_info, self.uuid))
        self._wait_until_input()

    def receive_round_start_message(self, round_count, hole_card, seats):
        print(U.visualize_round_start(round_count, hole_card, seats, self.uuid))
        self._wait_until_input()

    def receive_street_start_message(self, street, round_state):
        print(U.visualize_street_start(street, round_state, self.uuid))
        self._wait_until_input()

    def receive_game_update_message(self, new_action, round_state):
        print(U.visualize_game_update(new_action, round_state, self.uuid))
        self._wait_until_input()

    def receive_round_result_message(self, winners, hand_info, round_state):
        print(U.visualize_round_result(winners, hand_info, round_state, self.uuid))
        self._wait_until_input()

    def _wait_until_input(self):
        raw_input("Enter some key to continue ...")

    # FIXME: This code would be crash if receives invalid input.
    #        So you should add error handling properly.
    def _receive_action_from_console(self, valid_actions):
        action = raw_input("Enter action to declare >> ")
        if action == 'fold': amount = 0
        if action == 'call':  amount = valid_actions[1]['action']
        if action == 'raise':  amount = int(raw_input("Enter raise amount >> "))
        return action, amount
```

--------------------------------

### Sample street for receive_street_start_message

Source: https://github.com/ishikota/pypokerengine/blob/master/AI_CALLBACK_FORMAT.md

Indicates the current betting street in a poker round (e.g., 'preflop', 'flop', 'turn', 'river').

```json
'preflop'
```

--------------------------------

### Player Information Format for GameState

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/documentation/about_emulator.md

Specifies the required format for player information when generating an initial game state using `emulator.generate_initial_game_state`.

```python
players_info = {
  "uuid_of_player1": { "name": "name_of_player1", "stack": initial_stack_of_player1 },
  "uuid_of_player2": { "name": "name_of_player2", "stack": initial_stack_of_player2 },
  ...
}
```

--------------------------------

### Register Player Model with Emulator

Source: https://github.com/ishikota/pypokerengine/blob/master/docs/sources/tutorial/simulate_the_game_by_emulator.md

Registers a player model with the Emulator instance. The Emulator will then call the model's `declare_action` method during simulation to determine the player's move. Requires a player UUID and the model instance.

```python
p1_uuid = # uuid of player1. you would get this information from game_info object
p1_model = # setup model of player1
emulator.register_player(uuid1, p1_model)
```