State Logger

The alf_core.utils.state_logger module provides classes for logging and tracking the state of active learning tasks during execution. Loggers can write task state to different backends (e.g., terminal output, files, databases) and are called at key points during task execution to record progress and results.

Each logger exposes two entry points: log records per-round state (metrics, training history, predictions, and the acquisition batch), while log_summary records only a set of scalar end-of-experiment metrics — such as the experiment_summary emitted by DesignTask — without touching round-level state.

For FileStateLogger these write to separate files so each stays single-schema: log appends a row per round to metrics.csv with an explicit leading round column, while log_summary appends summary rows to summary.csv (which has no round column, as summary metrics are not tied to any one acquisition round).

class alf_core.utils.state_logger.FileStateLogger(output_path, upload_function=None)

Bases: StateLogger

Logger that saves certain components of the state to a file. This includes the metrics, the acquisition batch, the data splits, and the predictions.

log(state, round_name=None)

Log data from the task state to the logger destination.

Parameters:

• state (State) – State object to log

• round_name (str | None) – Name of the current round in the task, depending on the task type e.g. “initial_train_round”, “supervised evaluation”, “zero-shot evaluation”, or the round number for design tasks.

Return type:

None

log_summary(metrics, round_name)

Write summary metrics to summary.csv.

Unlike log, this does not add a round column because summary rows are not associated with a specific acquisition round. Summary metrics are written to a separate file so metrics.csv stays single-schema (one round per row).

Parameters:

• metrics (dict[str, float]) – Mapping of summary metric name to value.

• round_name (str) – Label for the summary entry; unused by the file logger but kept for interface symmetry with TerminalStateLogger.

Return type:

None

class alf_core.utils.state_logger.StateLogger

Bases: ABC

Abstract base class for state loggers.

Subclasses must implement log. They may also override _log_training_history to capture per-epoch training metrics.

Per-epoch metrics are available as state.round_metrics.training_history, a list[SurrogateEpochMetrics] populated by the surrogate’s get_epoch_metrics() after each training round. SurrogateEpochMetrics carries epoch, train_loss, and val_loss, plus an additional_metrics dict for model-specific metrics (e.g. train_spearman, val_spearman, train_mse, val_mse). The list is empty when the surrogate does not override get_epoch_metrics().

abstractmethod log(state, round_name=None)

Log data from the task state to the logger destination.

state.round_metrics.training_history contains a list[SurrogateEpochMetrics] with per-epoch training metrics for this round. Override _log_training_history to capture them.

Parameters:

• state (State) – State object to log

• round_name (str | None) – Name of the current round in the task, depending on the task type e.g. “initial_train_round”, “supervised evaluation”, “zero-shot evaluation”, or the round number for design tasks.

Return type:

None

abstractmethod log_summary(metrics, round_name)

Log a set of end-of-experiment summary metrics.

Unlike log, this records only the given scalar metrics (e.g. the aggregate experiment_summary emitted by DesignTask) and does not touch round-level state such as predictions or acquisition batches.

Parameters:

• metrics (dict[str, float]) – Mapping of summary metric name to value.

• round_name (str) – Label for the summary entry, e.g. “experiment_summary”.

Return type:

None

class alf_core.utils.state_logger.TerminalStateLogger

Bases: StateLogger

Logger that outputs metrics to the terminal.

log(state, round_name=None)

Log metrics in the task state to the terminal.

Parameters:

• state (State) – State object with metrics to log

• round_name (str | None) – Name of the current round in the task, depending on the task type e.g. “initial_train_round”, “supervised evaluation”, “zero-shot evaluation”, or the round number for design tasks.

Return type:

None

log_summary(metrics, round_name)

Log summary metrics to the terminal.

Parameters:

• metrics (dict[str, float]) – Mapping of summary metric name to value.

• round_name (str) – Label for the summary entry, e.g. “experiment_summary”.

Return type:

None