Refactor: Extract TournamentExecutor Class For Efficiency

Jan 19, 2026 by Editorial Team 58 views

Hey guys! Today, we're diving deep into a refactoring proposal aimed at making our AI tournament code cleaner, more maintainable, and less prone to bugs. The main goal? To extract a TournamentExecutor class. Let's break it down!

Problem: Code Duplication

Currently, the resume_experiment_background function in flask_app/routes/experiment_routes.py is doing the same thing as AITournamentRunner.run_tournament() in experiments/run_ai_tournament.py. This is not ideal because duplicated code is a recipe for disaster. Imagine you fix a bug in one place but forget to fix it in the other – nightmare scenario, right? Specifically, the duplication includes:

Game creation and controller setup: Both functions set up the game environment and the AI controllers that play the game.
Hand execution loop: They both manage the loop that runs each hand of the tournament.
State saving and checkpoint logic: Saving the game state and creating checkpoints to resume the tournament later.
Reset handling for eliminated players: Managing what happens when players are knocked out of the tournament and need to be reset or removed.

Having all this logic in two places means more work, more chances for errors, and a harder time keeping things consistent. It's like trying to manage two separate gardens with the same tools – inefficient and risky!

Proposed Solution: TournamentExecutor Class

To tackle this duplication, the idea is to create a TournamentExecutor class. This class will encapsulate all the core logic needed to run a tournament. Think of it as a dedicated gardener who knows exactly how to manage the tournament garden. Here’s a sneak peek at what it might look like:

class TournamentExecutor:
    """Executes a single tournament, handling hand loops, saves, and resets."""
    
    def __init__(
        self,
        state_machine: PokerStateMachine,
        controllers: Dict[str, AIPlayerController],
        memory_manager: AIMemoryManager,
        config: ExecutorConfig,
    ):
        ...
    
    def run_to_completion(self) -> TournamentResult:
        """Run tournament until completion or pause."""
        ...
    
    def run_single_hand(self) -> HandResult:
        """Execute one hand of the tournament."""
        ...

This class will handle the nitty-gritty of running the tournament, including:

Initialization: Setting up the tournament with the necessary components like the game state machine, AI controllers, memory manager, and configuration.
Running to completion: Executing the tournament until it's finished or paused, managing the main game loop.
Executing a single hand: Running one hand of the tournament, including dealing cards, managing bets, and determining the winner.

Both AITournamentRunner and resume_experiment_background will use this class. This way, we have one central place for all the tournament execution logic. It's like having a single, well-organized toolbox instead of two messy drawers!

Benefits: Why This Matters

So, why go through all this trouble? Here’s why extracting the TournamentExecutor class is a great idea:

Single source of truth: With all the tournament execution logic in one place, we avoid inconsistencies and ensure that changes are applied uniformly. This is crucial for maintaining the integrity of our tournaments and avoiding unexpected behavior. No more wondering which version of the code is the correct one!
Easier testing: We can test the TournamentExecutor class in isolation, making it easier to identify and fix bugs. Unit testing becomes much more straightforward, allowing us to verify that each component of the tournament execution logic works as expected. Think of it as testing each tool in the toolbox separately to make sure it works perfectly.
Cleaner resume logic: Resuming a tournament becomes much simpler. We just create the TournamentExecutor with the loaded state and call run_to_completion(). No more duplicated code for loading and restarting tournaments. This makes the resume process more reliable and less prone to errors.
Reduced duplication: We estimate that this refactoring will eliminate about 100-150 lines of code. That's a significant reduction, making the codebase smaller, easier to understand, and less prone to bugs. Less code means less to maintain and fewer potential issues to worry about.

Files Affected: Where the Changes Happen

This refactoring will primarily affect two files:

experiments/run_ai_tournament.py: This file will be modified to extract the TournamentExecutor class. The AITournamentRunner will then use this class to run the tournament.
flask_app/routes/experiment_routes.py: This file will be updated to use the TournamentExecutor class in the resume logic, ensuring that resuming tournaments is consistent and efficient.

Related: Context and Background

This issue was spotted during a code review of the experiment-manager branch. To address the immediate duplication, a quick fix (make_experiment_owner_id helper) was implemented. However, the complete extraction of the TournamentExecutor class is a more comprehensive refactor that addresses the underlying problem of code duplication. This ensures that our codebase remains maintainable and scalable in the long run.

Deep Dive into TournamentExecutor

Let's explore the TournamentExecutor class in more detail. This class is designed to be the central component for managing and executing AI tournaments. By encapsulating all the core logic, it ensures consistency, reduces redundancy, and simplifies testing.

Initialization

The __init__ method of the TournamentExecutor class is responsible for setting up the tournament environment. It takes several key parameters:

state_machine: A PokerStateMachine instance that manages the state of the poker game. This includes tracking player positions, card dealing, betting rounds, and determining the winner of each hand.
controllers: A dictionary of AIPlayerController instances, where each controller represents an AI player in the tournament. The keys of the dictionary are player identifiers, allowing the executor to map actions to specific players.
memory_manager: An AIMemoryManager instance that handles the storage and retrieval of AI player memory. This is crucial for allowing AI players to learn and adapt their strategies over the course of the tournament.
config: An ExecutorConfig instance that provides configuration parameters for the tournament, such as the number of hands to play, the blind structure, and other game settings.

During initialization, the TournamentExecutor sets up the necessary data structures, initializes the AI controllers, and prepares the game state for the first hand.

Running to Completion

The run_to_completion method is the heart of the TournamentExecutor class. It orchestrates the execution of the tournament from start to finish. The method includes the following steps:

Main Game Loop: The method enters a loop that continues until the tournament is completed or paused. The loop iterates over each hand of the tournament.
Hand Execution: For each hand, the method calls the run_single_hand method to execute one hand of the tournament. The run_single_hand method returns a HandResult object that contains information about the outcome of the hand.
State Saving: After each hand, the method saves the current state of the tournament. This includes the game state, the AI player memories, and any other relevant data. The state is saved to a persistent storage, allowing the tournament to be resumed later if needed.
Checkpoint Logic: The method also implements checkpoint logic to create periodic checkpoints of the tournament state. Checkpoints are used to provide a fallback in case the tournament is interrupted or encounters an error. The frequency of checkpoints is determined by the configuration parameters.
Pause Handling: The method checks for pause signals during the main game loop. If a pause signal is received, the method saves the current state and exits the loop, allowing the tournament to be resumed later.

Executing a Single Hand

The run_single_hand method is responsible for executing one hand of the tournament. This method includes the following steps:

Dealing Cards: The method deals cards to each player in the tournament. The cards are dealt according to the rules of the poker game.
Betting Rounds: The method manages the betting rounds for the hand. This includes collecting bets from players, tracking the pot size, and determining when the betting round is over.
AI Player Actions: The method invokes the AI controllers to determine the actions of the AI players. The AI controllers use the current game state and their internal memory to make decisions about whether to bet, call, raise, or fold.
Determining the Winner: After the final betting round, the method determines the winner of the hand. This includes evaluating the hands of each player and awarding the pot to the player with the best hand.
Hand Result: The method returns a HandResult object that contains information about the outcome of the hand. This includes the winner of the hand, the pot size, and any other relevant data.

Benefits Revisited

To recap, extracting the TournamentExecutor class brings several key benefits:

Single Source of Truth: Consolidating the tournament execution logic into a single class ensures that there is only one place to maintain and update the code. This reduces the risk of inconsistencies and errors.
Easier Testing: The TournamentExecutor class can be tested in isolation, making it easier to verify that each component of the tournament execution logic works correctly.
Cleaner Resume Logic: Resuming a tournament becomes much simpler, as the TournamentExecutor can be initialized with the loaded state and then run to completion.
Reduced Duplication: The refactoring eliminates approximately 100-150 lines of duplicated code, making the codebase smaller, easier to understand, and less prone to bugs.

By implementing this refactoring, we can significantly improve the maintainability, scalability, and reliability of our AI tournament system. It’s a win-win for everyone involved!

Conclusion

Alright, that's the plan! Extracting the TournamentExecutor class is a solid move towards cleaner, more maintainable code. By reducing duplication and centralizing logic, we're setting ourselves up for easier testing, cleaner resume logic, and a more robust system overall. Let's get to it and make our AI tournaments even better!