games.utils.recursion_config¶

Recursion configuration utilities for game agents.

This module provides utilities to properly configure recursion limits for game agents to prevent recursion errors during gameplay.

Classes¶

RecursionConfig

Configuration helper for managing recursion limits in game agents.

Module Contents¶

class games.utils.recursion_config.RecursionConfig¶

Configuration helper for managing recursion limits in game agents.

classmethod configure_runnable(runnable_config=None, game_name=None, game_type='standard', enable_analysis=False, num_players=2, thread_id=None)¶

Configure or update a runnable config with appropriate recursion limit.

Parameters:

  • runnable_config (dict[str, Any] | None) – Existing config to update (creates new if None)

  • game_name (str | None) – Specific game name

  • game_type (str) – Type of game

  • enable_analysis (bool) – Whether analysis is enabled

  • num_players (int) – Number of players

  • thread_id (str | None) – Thread ID to use (generates if None)

Returns:

Updated runnable configuration

Return type:

dict[str, Any]

Examples

>>> # Create new config for chess
>>> config = RecursionConfig.configure_runnable(
...     game_name="chess",
...     enable_analysis=True
... )
>>> print(config["configurable"]["recursion_limit"])  # 720

>>> # Update existing config
>>> existing = {"configurable": {"thread_id": "abc123"}}
>>> updated = RecursionConfig.configure_runnable(
...     runnable_config=existing,
...     game_type="complex"
... )
>>> print(updated["configurable"]["recursion_limit"])  # 800
classmethod get_recursion_limit(game_name=None, game_type='standard', enable_analysis=False, num_players=2, custom_limit=None)¶

Get the appropriate recursion limit for a game.

Parameters:

  • game_name (str | None) – Specific game name (e.g., “chess”, “checkers”)

  • game_type (str) – Type of game (“simple”, “standard”, “complex”, “extreme”)

  • enable_analysis (bool) – Whether analysis is enabled (adds overhead)

  • num_players (int) – Number of players (more players = higher limit)

  • custom_limit (int | None) – Override with custom limit

Returns:

Recommended recursion limit

Return type:

int

Examples

>>> # Simple game
>>> limit = RecursionConfig.get_recursion_limit(game_type="simple")
>>> print(limit)  # 300

>>> # Chess with analysis
>>> limit = RecursionConfig.get_recursion_limit(
...     game_name="chess",
...     enable_analysis=True
... )
>>> print(limit)  # 720 (600 + 20% for analysis)

>>> # Multi-player game
>>> limit = RecursionConfig.get_recursion_limit(
...     game_type="complex",
...     num_players=4
... )
>>> print(limit)  # 960 (800 + 20% for extra players)
classmethod validate_recursion_limit(limit, game_name=None, game_type='standard')¶

Validate if a recursion limit is appropriate.

Parameters:

  • limit (int) – The recursion limit to validate

  • game_name (str | None) – Specific game name

  • game_type (str) – Type of game

Returns:

Tuple of (is_valid, message)

Return type:

tuple[bool, str]

Examples

>>> valid, msg = RecursionConfig.validate_recursion_limit(
...     100, game_type="complex"
... )
>>> print(valid, msg)  # False, "Limit too low..."