haive.core.common.logging_config

Logging Configuration Module.

This module provides utilities for configuring and managing logging throughout the Haive framework. It includes customizable log levels, formatters, and specialized logging for games and agents with rich console output support.

The module is designed to create a consistent logging experience across different components while allowing for flexibility in output formats and verbosity levels.

Typical usage example:

from haive.core.common.logging_config import get_game_logger, LogLevel

# Create a logger with default settings logger = get_game_logger(“my_game”)

# Log messages at different levels logger.info(“Game starting”) logger.debug(“Detailed state information”)

# Log game-specific events logger.turn_start(“Player 1”, turn_number=1) logger.dice_roll(“Player 1”, die1=3, die2=4, total=7) logger.player_move(“Player 1”, from_pos=0, to_pos=7)

# Change log level dynamically logger.setLevel(logging.DEBUG)

Classes

GameLogger	Enhanced logger for game agents with rich formatting and game-specific methods.
LogFormat	Log output format enumeration.
LogLevel	Logging level enumeration.

Functions

get_game_logger(name[, level, format])

Get a configured game logger instance.

Module Contents

class haive.core.common.logging_config.GameLogger(name, level = LogLevel.INFO, format = LogFormat.RICH if RICH_AVAILABLE else LogFormat.SIMPLE, enable_file_logging = False, log_file = None)

Enhanced logger for game agents with rich formatting and game-specific methods.

This logger extends standard Python logging with game-specific logging methods and support for rich console output. It provides specialized methods for logging game events like turns, dice rolls, player moves, and property actions with appropriate formatting and icons.

It also includes performance tracking capabilities for monitoring operation durations and configurable verbosity levels that can be changed at runtime.

name

Logger name (usually module or game name)

level

Current logging level

format

Output format being used

enable_file_logging

Whether logging to file is enabled

log_file

Path to the log file if file logging is enabled

logger

The underlying Python logger instance

Initialize the game logger with the specified configuration.

Parameters:

• name (str) – Logger name (usually module or game name)

• level (LogLevel) – Logging level to control verbosity

• format (LogFormat) – Output format for log messages

• enable_file_logging (bool) – Whether to log to a file in addition to console

• log_file (str | None) – Path to log file (auto-generated with timestamp if not provided)

critical(msg, **kwargs)

Log a critical message.

Parameters:

• msg (str) – Message to log

• **kwargs – Additional logging parameters

Return type:

None

debug(msg, **kwargs)

Log a debug message.

Parameters:

• msg (str) – Message to log

• **kwargs – Additional logging parameters

Return type:

None

decision(player_name, decision_type, choice, reasoning='')

Log a player decision.

Parameters:

• player_name (str) – Name of the player making the decision

• decision_type (str) – Type of decision being made

• choice (str) – The decision that was made

• reasoning (str) – Optional explanation for the decision (logged at debug level)

Return type:

None

dice_roll(player_name, die1, die2, total)

Log a dice roll event.

Parameters:

• player_name (str) – Name of the player who rolled

• die1 (int) – Value of the first die

• die2 (int) – Value of the second die

• total (int) – Sum of both dice

Return type:

None

error(msg, **kwargs)

Log an error message.

Parameters:

• msg (str) – Message to log

• **kwargs – Additional logging parameters

Return type:

None

game_event(event_type, description, **kwargs)

Log a general game event.

Parameters:

• event_type (str) – Type of event

• description (str) – Description of what happened

• **kwargs – Additional event details (logged at debug level)

Return type:

None

game_state_summary(state)

Display a summary of the current game state.

This method produces a rich table or formatted log output showing the current state of all players.

Parameters:

state (dict[str, Any]) – Dictionary containing the game state with at least a “players” key

Return type:

None

info(msg, **kwargs)

Log an info message.

Parameters:

• msg (str) – Message to log

• **kwargs – Additional logging parameters

Return type:

None

performance_end(operation)

End timing an operation and log the duration.

Call this at the end of an operation you started timing with performance_start(). The duration is only logged at DEBUG level.

Parameters:

operation (str) – Name of the operation to end timing

Return type:

None

performance_start(operation)

Start timing an operation for performance tracking.

Call this at the beginning of an operation you want to time.

Parameters:

operation (str) – Name of the operation to time

Return type:

None

player_move(player_name, from_pos, to_pos, passed_go=False)

Log player movement on the game board.

Parameters:

• player_name (str) – Name of the player who moved

• from_pos (int) – Starting position

• to_pos (int) – Ending position

• passed_go (bool) – Whether the player passed GO during the move

Return type:

None

property_action(action, player_name, property_name, amount=None, **kwargs)

Log property-related actions.

Parameters:

• action (str) – Type of action (e.g., “buy”, “rent”, “mortgage”)

• player_name (str) – Name of the player performing the action

• property_name (str) – Name of the property involved

• amount (int | None) – Amount of money involved (if applicable)

• **kwargs – Additional action details

Return type:

None

set_level(level)

Change the logging level at runtime.

Parameters:

level (LogLevel) – New logging level to use

Return type:

None

turn_start(player_name, turn_number, **kwargs)

Log the start of a player’s turn.

Parameters:

• player_name (str) – Name of the player whose turn is starting

• turn_number (int) – Current turn number

• **kwargs – Additional turn information to log

Return type:

None

warning(msg, **kwargs)

Log a warning message.

Parameters:

• msg (str) – Message to log

• **kwargs – Additional logging parameters

Return type:

None

class haive.core.common.logging_config.LogFormat

Bases: str, enum.Enum

Log output format enumeration.

This enum defines available formatting options for log output. It inherits from str for easy use in string contexts.

SIMPLE

Basic text output with just the message

DETAILED

Include timestamps, logger name, and level with the message

JSON

JSON formatted logs for machine parsing

RICH

Enhanced console output with colors and formatting (requires rich library)

Initialize self. See help(type(self)) for accurate signature.

class haive.core.common.logging_config.LogLevel

Bases: str, enum.Enum

Logging level enumeration.

This enum defines standard logging levels plus a SILENT level for suppressing most log output. Since it inherits from str, it can be used directly in string contexts.

DEBUG

Detailed information, typically of interest only when diagnosing problems

INFO

Confirmation that things are working as expected

WARNING

Indication that something unexpected happened, or may happen

ERROR

Due to a more serious problem, the software has not been able to perform a function

CRITICAL

A serious error, indicating that the program itself may be unable to continue running

SILENT

No logging except critical errors

Initialize self. See help(type(self)) for accurate signature.

haive.core.common.logging_config.get_game_logger(name, level=None, format=None)

Get a configured game logger instance.

This function creates a GameLogger with settings from environment variables or the provided parameters. Environment variables take precedence over the function parameters if both are provided.

Environment variables:

• GAME_LOG_LEVEL: Logging level (DEBUG, INFO, etc.)

• GAME_LOG_FORMAT: Logging format (simple, detailed, json, rich)

• GAME_LOG_TO_FILE: Whether to log to file (“true” or “false”)

Parameters:

• name (str) – Logger name (usually module or game name)

• level (str | None) – Override log level (environment variable takes precedence)

• format (str | None) – Override format (environment variable takes precedence)

Returns:

Configured GameLogger instance ready for use

Return type:

GameLogger