Logger

Stage-aware logging (eval, drift, cl) with pluggable metrics backends, selected by [logging] backend.

Logger

Unified logging interface combining metrics tracking and console output.

class apeiron.logger.logger.Logger[source]

Bases: object

Unified logger with metrics tracking (WandB/MLflow) and console output.

__init__(verbosity='INFO', backend='wandb', csv_path=None)[source]

Initialize unified logger.

Parameters:
  • verbosity (str) – Console level (DEBUG, INFO, INFO:n, WARNING, ERROR, CRITICAL)

  • backend (Literal['wandb', 'mlflow', 'none']) – Metrics backend to use (“wandb”, “mlflow”, or “none”)

  • csv_path (str | Path | None) – Save metrics to CSV at this path (disabled if None)

property backend: Literal['wandb', 'mlflow', 'none']

Get the current metrics backend.

init(cfg, project='basesim-framework', name=None, tags=None, notes=None, group=None, **kwargs)[source]

Initialize wandb run with config.

Parameters:
stage(name)[source]

Set current stage (‘eval’, ‘drift’, or ‘cl’).

Parameters:

name (Literal['eval', 'drift', 'cl'])

Return type:

None

property step: int
property current_stage: Literal['eval', 'drift', 'cl'] | None
get_stage_step(stage)[source]
Parameters:

stage (Literal['eval', 'drift', 'cl'])

Return type:

int

log(metrics, step=None, commit=True, prefix=True, increment=True)[source]

Log metrics with stage-aware prefixing.

Parameters:
Return type:

None

save(file_path, base_path=None, policy='now')[source]

Save file to wandb.

Parameters:
Return type:

None

to_dataframe()[source]

Convert metrics to DataFrame.

Return type:

DataFrame | None

to_csv(csv_path=None)[source]

Save metrics to CSV.

Parameters:

csv_path (str | Path | None)

Return type:

Path | None

finish(exit_code=None, save_csv=True)[source]

Finish wandb run and save CSV.

Parameters:
  • exit_code (int | None)

  • save_csv (bool)

Return type:

Path | None

property url: str | None
property verbosity: str
debug(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

info(msg, level=0, *args, **kwargs)[source]

Log at INFO:level tier (0=standard, 1+=more verbose).

Parameters:
Return type:

None

warning(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

error(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

critical(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

exception(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

apeiron.logger.logger.get_logger(verbosity='INFO', backend='wandb', csv_path=None)[source]

Get or create the default Logger instance.

Parameters:
  • verbosity (str) – Console level (DEBUG, INFO, INFO:n, WARNING, ERROR, CRITICAL)

  • backend (Literal['wandb', 'mlflow', 'none']) – Metrics backend to use (“wandb”, “mlflow”, or “none”)

  • csv_path (str | Path | None) – Save metrics to CSV at this path (disabled if None)

Returns:

Logger instance

Return type:

Logger

apeiron.logger.logger.reset_logger()[source]

Reset the default logger instance. Useful for testing.

Return type:

None

apeiron.logger.logger.configure_backend(cfg)[source]

Configure and return the logging backend from apeiron.config.

Parameters:

cfg (Config | None)

Return type:

Literal[‘wandb’, ‘mlflow’, ‘none’]

Console output

Console logging interface with verbosity control.

class apeiron.logger.console_logger.Colors[source]

Bases: object

ANSI color codes for terminal output.

RESET = '\x1b[0m'
RED = '\x1b[31m'
YELLOW = '\x1b[33m'
BLUE = '\x1b[34m'
GREEN = '\x1b[32m'
WHITE = '\x1b[37m'
class apeiron.logger.console_logger.StepFilter[source]

Bases: Filter

Filter that adds step information to log records.

__init__(get_step)[source]

Initialize a filter.

Initialize with the name of the logger which, together with its children, will have its events allowed through the filter. If no name is specified, allow every event.

Parameters:

get_step (Callable[[], int])

filter(record)[source]

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

Parameters:

record (LogRecord)

Return type:

bool

class apeiron.logger.console_logger.ColoredFormatter[source]

Bases: Formatter

Formatter that adds colors to log levels.

LEVEL_COLORS = {'CRITICAL': '\x1b[31m', 'DEBUG': '\x1b[37m', 'ERROR': '\x1b[31m', 'WARNING': '\x1b[33m'}
__init__(*args, **kwargs)[source]

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

format(record)[source]

Format log record with colored level name.

Parameters:

record (LogRecord)

Return type:

str

class apeiron.logger.console_logger.ConsoleLogger[source]

Bases: object

Console logging with tiered INFO verbosity (INFO:0 to INFO:9).

LEVEL_MAP = {'CRITICAL': 50, 'DEBUG': 10, 'ERROR': 40, 'INFO': 20, 'WARNING': 30}
__init__(verbosity='INFO', get_step=None)[source]

Initialize console logger with tiered INFO verbosity support.

Parameters:
  • verbosity (str) – Console level (DEBUG, INFO, INFO:n, WARNING, ERROR, CRITICAL)

  • get_step (Callable[[], int] | None) – Callback to get current step for display (defaults to returning 0)

property verbosity: str
debug(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

info(msg, level=0, *args, **kwargs)[source]

Log at INFO:level tier (0=standard, 1+=more verbose).

Parameters:
Return type:

None

warning(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

error(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

critical(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

exception(msg, *args, **kwargs)[source]
Parameters:

msg (str)

Return type:

None

Metrics backends

Weights & Biases logging interface for metrics tracking.

class apeiron.logger.wandb_logger.WandBLogger[source]

Bases: object

WandB metrics logger with stage-aware step tracking.

Tracks global step and per-stage steps (eval/step, drift/step, cl/step).

__init__(enabled=True, csv_path=None)[source]

Initialize WandB logger.

Parameters:
  • enabled (bool) – Enable WandB logging

  • csv_path (str | Path | None) – Save metrics to CSV at this path (disabled if None)

property step: int
property current_stage: Literal['eval', 'drift', 'cl'] | None
stage(name)[source]

Set current stage (‘eval’, ‘drift’, or ‘cl’).

Parameters:

name (Literal['eval', 'drift', 'cl'])

Return type:

None

get_stage_step(stage)[source]
Parameters:

stage (Literal['eval', 'drift', 'cl'])

Return type:

int

init(cfg, project='basesim-framework', name=None, tags=None, notes=None, group=None, **kwargs)[source]

Initialize wandb run with config.

Parameters:
Return type:

wandb.sdk.wandb_run.Run | None

log(metrics, step=None, commit=True, prefix=True, increment=True)[source]

Log metrics with auto-prefixing by current stage.

Parameters:
  • metrics (dict[str, Any]) – Metric name/value pairs

  • step (int | None) – Override global step (None = use internal counter)

  • commit (bool) – Commit immediately to wandb

  • prefix (bool) – Auto-prefix metrics with current stage (skips keys with “/”)

  • increment (bool) – Increment step counters

Return type:

None

save(file_path, base_path=None, policy='now')[source]

Save file to wandb.

Parameters:
Return type:

None

to_dataframe()[source]

Convert metrics to long-format DataFrame (step, metric, value).

Return type:

DataFrame | None

to_csv(csv_path=None)[source]

Save metrics to CSV in long format (step, metric, value).

Parameters:

csv_path (str | Path | None)

Return type:

Path | None

finish(exit_code=None, save_csv=True)[source]

Finish wandb run and optionally save CSV.

Parameters:
  • exit_code (int | None)

  • save_csv (bool)

Return type:

Path | None

property url: str | None

MLflow logging interface for metrics tracking.

class apeiron.logger.mlflow_logger.MLFlowLogger[source]

Bases: object

MLflow metrics logger with stage-aware step tracking.

Mirrors WandBLogger interface for drop-in replacement. Tracks global step and per-stage steps (eval/step, drift/step, cl/step).

__init__(enabled=True, csv_path=None)[source]

Initialize MLflow logger.

Parameters:
  • enabled (bool) – Enable MLflow logging

  • csv_path (str | Path | None) – Save metrics to CSV at this path (disabled if None)

property step: int
property current_stage: Literal['eval', 'drift', 'cl'] | None
stage(name)[source]

Set current stage (‘eval’, ‘drift’, or ‘cl’).

Parameters:

name (Literal['eval', 'drift', 'cl'])

Return type:

None

get_stage_step(stage)[source]
Parameters:

stage (Literal['eval', 'drift', 'cl'])

Return type:

int

init(cfg, project='basesim-framework', name=None, tags=None, notes=None, group=None, **kwargs)[source]

Initialize MLflow run with config.

Parameters:
  • cfg (Config) – Configuration object

  • project (str) – MLflow experiment name

  • name (str | None) – Run name

  • tags (list[str] | None) – List of tags

  • notes (str | None) – Run description

  • group (str | None) – Group name (stored as tag)

  • **kwargs – Additional arguments (ignored for MLflow compatibility)

Returns:

MLflow ActiveRun object or None if disabled

Return type:

mlflow.ActiveRun | None

log(metrics, step=None, commit=True, prefix=True, increment=True)[source]

Log metrics with auto-prefixing by current stage.

Parameters:
  • metrics (dict[str, Any]) – Metric name/value pairs

  • step (int | None) – Override global step (None = use internal counter)

  • commit (bool) – Ignored (MLflow commits immediately)

  • prefix (bool) – Auto-prefix metrics with current stage (skips keys with “/” or “.”)

  • increment (bool) – Increment step counters

Return type:

None

save(file_path, base_path=None, policy='now')[source]

Save file as MLflow artifact.

Parameters:
  • file_path (str | Path) – Path to file to save

  • base_path (str | Path | None) – Ignored (MLflow doesn’t use base_path)

  • policy (Literal['now', 'live', 'end']) – Ignored (MLflow saves immediately)

Return type:

None

to_dataframe()[source]

Convert metrics to long-format DataFrame (step, metric, value).

Return type:

DataFrame | None

to_csv(csv_path=None)[source]

Save metrics to CSV in long format (step, metric, value).

Parameters:

csv_path (str | Path | None)

Return type:

Path | None

finish(exit_code=None, save_csv=True)[source]

Finish MLflow run and optionally save CSV.

Parameters:
  • exit_code (int | None) – Exit code (non-zero marks run as failed)

  • save_csv (bool) – Whether to save metrics to CSV

Returns:

Path to saved CSV or None

Return type:

Path | None

property url: str | None

Get URL to the MLflow run UI.