games.clue.config¶

Comprehensive configuration system for the Clue (Cluedo) mystery game agent.

This module defines the configuration system for the Clue game agent, providing complete control over game mechanics, AI behavior, analysis settings, and visualization options. The configuration system supports both casual and competitive gameplay modes with extensive customization options.

The configuration manages: - Game state schema and persistence - AI engine configurations and behavior - Analysis and reasoning settings - Visualization and UI options - Game flow and turn management - Solution generation and validation - Player interaction modes

Key Features:

  • Flexible game parameter configuration

  • Multiple AI difficulty levels

  • Comprehensive analysis and logging

  • Customizable visualization options

  • Solution pre-configuration for testing

  • Turn limit and timeout management

  • Player order customization

Examples

Basic configuration:

from haive.games.clue.config import ClueConfig

# Create default configuration
config = ClueConfig()
print(f"Game: {config.name} v{config.version}")
print(f"Max turns: {config.max_turns}")
print(f"Analysis enabled: {config.enable_analysis}")

Custom configuration:

from haive.games.clue.models import ClueSolution, ValidSuspect, ValidWeapon, ValidRoom

# Create custom game configuration
custom_solution = {
    "suspect": ValidSuspect.COLONEL_MUSTARD.value,
    "weapon": ValidWeapon.KNIFE.value,
    "room": ValidRoom.KITCHEN.value
}

config = ClueConfig(
    max_turns=15,
    first_player="player2",
    solution=custom_solution,
    enable_analysis=False,
    visualize=False
)

Configuration validation:

config = ClueConfig()

# Validate configuration
assert config.max_turns > 0
assert config.first_player in ["player1", "player2"]
assert config.state_schema == ClueState
assert isinstance(config.enable_analysis, bool)

The configuration system integrates seamlessly with the game engine and provides all necessary parameters for consistent and customizable gameplay experiences.

Classes¶

ClueConfig

Comprehensive configuration for the Clue game agent.

Module Contents¶

class games.clue.config.ClueConfig¶

Bases: haive.games.framework.base.config.GameConfig

Comprehensive configuration for the Clue game agent.

This class defines all configuration parameters for the Clue game agent, providing complete control over game mechanics, AI behavior, analysis settings, and visualization options. The configuration supports both casual and competitive gameplay modes with extensive customization.

The configuration manages game flow, player interactions, AI reasoning, solution generation, and performance optimization. It integrates with the game engine to provide consistent and customizable gameplay experiences.

name¶

Unique identifier for the game type. Used for logging, metrics, and game selection.

version¶

Version string for tracking implementation changes. Follows semantic versioning (major.minor.patch).

state_schema¶

Pydantic model class for game state management. Defines the structure and validation for game data.

enable_analysis¶

Whether to enable AI position analysis. Affects performance and decision-making quality.

visualize¶

Whether to enable game visualization. Controls UI rendering and display updates.

max_turns¶

Maximum number of turns before game timeout. Prevents infinite games and ensures completion.

first_player¶

Which player starts the game. Must be either “player1” or “player2”.

solution¶

Predetermined solution for testing and tutorials. If None, a random solution will be generated.

Examples

Default configuration:

config = ClueConfig()
assert config.name == "clue"
assert config.max_turns == 20
assert config.first_player == "player1"
assert config.enable_analysis == True
assert config.visualize == True
assert config.solution is None

Custom configuration:

from haive.games.clue.models import ValidSuspect, ValidWeapon, ValidRoom

# Create specific solution for testing
test_solution = {
    "suspect": ValidSuspect.COLONEL_MUSTARD.value,
    "weapon": ValidWeapon.KNIFE.value,
    "room": ValidRoom.KITCHEN.value
}

config = ClueConfig(
    max_turns=15,
    first_player="player2",
    solution=test_solution,
    enable_analysis=False,
    visualize=False
)

Performance optimization:

# High-performance configuration for batch processing
config = ClueConfig(
    enable_analysis=False,  # Disable analysis for speed
    visualize=False,        # Disable visualization for speed
    max_turns=10           # Shorter games for faster completion
)

Tutorial configuration:

# Educational configuration with predetermined solution
tutorial_solution = {
    "suspect": ValidSuspect.MISS_SCARLET.value,
    "weapon": ValidWeapon.CANDLESTICK.value,
    "room": ValidRoom.LIBRARY.value
}

config = ClueConfig(
    solution=tutorial_solution,
    max_turns=30,          # More turns for learning
    enable_analysis=True,   # Show AI reasoning
    visualize=True         # Show game progression
)

Note

The solution parameter accepts a dictionary with ‘suspect’, ‘weapon’, and ‘room’ keys. Values should be the string values from the corresponding enum classes, not the enum instances themselves.

classmethod benchmark_game(max_turns=10)¶

Create configuration for performance benchmarking.

Features: - Minimal turn limit for fast completion - Analysis disabled for performance - Visualization disabled for speed - Random solution generation

Parameters:

max_turns (int) – Maximum number of turns (default: 10).

Returns:

Benchmark game configuration.

Return type:

ClueConfig

Examples

Creating a benchmark game:

config = ClueConfig.benchmark_game()
assert config.max_turns == 10
assert config.enable_analysis == False
assert config.visualize == False
assert config.solution is None

Custom benchmark configuration:

config = ClueConfig.benchmark_game(max_turns=5)
assert config.max_turns == 5
classmethod casual_game(max_turns=25)¶

Create configuration for casual gameplay.

Features: - Extended turn limit for relaxed play - Analysis enabled for learning - Visualization enabled for engagement - Random solution generation

Parameters:

max_turns (int) – Maximum number of turns (default: 25).

Returns:

Casual game configuration.

Return type:

ClueConfig

Examples

Creating a casual game:

config = ClueConfig.casual_game()
assert config.max_turns == 25
assert config.enable_analysis == True
assert config.visualize == True
assert config.solution is None

Custom casual game:

config = ClueConfig.casual_game(max_turns=30)
assert config.max_turns == 30
classmethod competitive_game(max_turns=15)¶

Create configuration for competitive gameplay.

Features: - Reduced turn limit for faster games - Analysis disabled for challenge - Visualization optional for focus - Random solution generation

Parameters:

max_turns (int) – Maximum number of turns (default: 15).

Returns:

Competitive game configuration.

Return type:

ClueConfig

Examples

Creating a competitive game:

config = ClueConfig.competitive_game()
assert config.max_turns == 15
assert config.enable_analysis == False
assert config.visualize == False
assert config.solution is None

Tournament configuration:

config = ClueConfig.competitive_game(max_turns=12)
assert config.max_turns == 12
classmethod tutorial_game(solution_dict=None)¶

Create configuration for tutorial/educational gameplay.

Features: - Extended turn limit for learning - Analysis enabled for understanding - Visualization enabled for instruction - Predetermined solution for consistency

Parameters:

solution_dict (dict | None) – Specific solution dictionary. If None, uses Colonel Mustard example.

Returns:

Tutorial game configuration.

Return type:

ClueConfig

Examples

Creating a tutorial game:

config = ClueConfig.tutorial_game()
assert config.max_turns == 30
assert config.enable_analysis == True
assert config.visualize == True
assert config.solution is not None

Custom tutorial solution:

from haive.games.clue.models import ValidSuspect, ValidWeapon, ValidRoom

custom_solution = {
    "suspect": ValidSuspect.PROFESSOR_PLUM.value,
    "weapon": ValidWeapon.CANDLESTICK.value,
    "room": ValidRoom.LIBRARY.value
}
config = ClueConfig.tutorial_game(solution_dict=custom_solution)
assert config.solution == custom_solution