adgtk.utils.logs

Logging utility functions for configuring and managing loggers.

class adgtk.utils.logs.RoleColorFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

Formats based on role. Sets the color.

ROLE_COLORS = {'ai': '\x1b[92m', 'default': '\x1b[0m', 'error': '\x1b[91m', 'human': '\x1b[94m', 'system': '\x1b[95m', 'tool': '\x1b[96m'}

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

adgtk.utils.logs.clear_agent_logs(experiment_name: str) → None

Clears the agent dedicated log folder for an experiment

Args:

experiment_name (str): The experiment to clear

adgtk.utils.logs.clear_llm_logs(experiment_name: str) → None

Clears the LLM dedicated log folder for an experiment

Args:

experiment_name (str): The experiment to clear

adgtk.utils.logs.create_llm_logger(logfile: str, logger_name: str, experiment_name: str, log_level: int = 20, log_to_console: bool = True, log_propagate: bool = False, mode: Literal['a', 'w'] = 'a') → Logger

Configure and return a logger with role-based color formatting that writes to a specified log file and optionally logs to the console.

Args:

logfile (str): Name of the log file to create or append to. logger_name (str): Name of the logger instance. log_level (int, optional): Logging level (e.g., logging.INFO,

logging.DEBUG). Defaults to logging.INFO.

log_to_console (bool, optional): Whether to also log messages

to the console (stdout). Defaults to True.

subdir (Literal[“framework”, “runs”, “common”], optional):

Subdirectory (under ‘logs/’) to store the log file. Defaults to “framework”.

experiment_name (Optional[str], optional): Name of the experiment

(required if subdir is “runs”). Defaults to None.

log_propagate (bool, optional): Whether the logger should propagate

messages to ancestor loggers. Defaults to False.

mode (Literal[“a”, “w”], optional): File mode for the log file

(“a” for append, “w” for write). Defaults to “a”.

Returns:

logging.Logger: Configured logger instance with role-based color formatting.

adgtk.utils.logs.create_logger(logfile: str, logger_name: str, log_level: int = 20, log_to_console: bool = False, subdir: Literal['framework', 'runs', 'common', 'agent'] = 'framework', experiment_name: str | None = None, log_propagate: bool = False, mode: Literal['a', 'w'] = 'a') → Logger

Configure and return a logger that writes to a specified log file and optionally logs to the console.

This function removes any existing file handlers for the logger, adds a new file handler with the specified log level and format, and optionally adds a console handler. It also ensures that the necessary directories for logging are created.

Args:

logfile (str): Name of the log file to create or append to. logger_name (str): Name of the logger instance. log_level (int, optional): Logging level (e.g., logging.INFO,

logging.DEBUG). Defaults to logging.INFO.

log_to_console (bool, optional): Whether to also log messages

to the console (stdout). Defaults to False.

subdir (Literal[“framework”, “runs”, “common”], optional):

Subdirectory (under ‘logs/’) to store the log file. Defaults to “framework”.

experiment_name (Optional[str], optional): Name of the experiment

(required if subdir is “runs”). Defaults to None.

log_propagate (bool, optional): Whether the logger should propagate

messages to ancestor loggers. Defaults to False.

mode (Literal[“a”, “w”], optional): File mode for the log file

(“a” for append, “w” for write). Defaults to “a”.

Returns:

logging.Logger: Configured logger instance.

Raises:

ValueError: If experiment_name is not provided when subdir

is set to “runs”.

adgtk.utils.logs.get_scenario_logger() → Logger

Retrieve the logger for the current scenario.

This utility function ensures that the scenario logger is easily accessible and helps maintain clarity in experimentation code.

If no active scenario is running, it creates a logger using the framework directory.

Returns:

logging.Logger: The logger instance for the current scenario.

adgtk.utils.logs.set_logfile(logfile: str, logger_name: str, log_level: int = 20, log_to_console: bool = False, subdir: Literal['framework', 'runs', 'common', 'agent'] = 'framework', experiment_name: str | None = None, log_propagate: bool = True, mode: Literal['a', 'w'] = 'a') → Logger

[DEPRECATED] Configure and return a logger that writes to a specified log file and optionally logs to the console.

This function is deprecated as of version 0.2. Use create_logger instead. It retains the same functionality as create_logger.

Args:

logfile (str): Name of the log file to create or append to. logger_name (str): Name of the logger instance. log_level (int, optional): Logging level (e.g., logging.INFO,

logging.DEBUG). Defaults to logging.INFO.

log_to_console (bool, optional): Whether to also log messages

to the console (stdout). Defaults to False.

subdir (Literal[“framework”, “runs”, “common”], optional):

Subdirectory (under ‘logs/’) to store the log file. Defaults to “framework”.

experiment_name (Optional[str], optional): Name of the experiment

(required if subdir is “runs”). Defaults to None.

log_propagate (bool, optional): Whether the logger should propagate

messages to ancestor loggers. Defaults to True.

mode (Literal[“a”, “w”], optional): File mode for the log file

(“a” for append, “w” for write). Defaults to “a”.

Returns:

logging.Logger: Configured logger instance.

Raises:

ValueError: If experiment_name is not provided when subdir

is set to “runs”.

Warnings:

DeprecationWarning: This function is deprecated. Use create_logger instead.