Skip to content

TrackingConfig

gepa.optimize_anything.TrackingConfig(logger: LoggerProtocol | None = None, use_wandb: bool = False, wandb_api_key: str | None = None, wandb_init_kwargs: dict[str, Any] | None = None, wandb_attach_existing: bool = False, wandb_step_metric: str | None = None, use_mlflow: bool = False, mlflow_tracking_uri: str | None = None, mlflow_experiment_name: str | None = None, mlflow_attach_existing: bool = False, key_prefix: str = '') dataclass

Experiment tracking and logging (W&B, MLflow, or custom logger).

Attributes

logger: LoggerProtocol | None = None class-attribute instance-attribute

use_wandb: bool = False class-attribute instance-attribute

wandb_api_key: str | None = None class-attribute instance-attribute

wandb_init_kwargs: dict[str, Any] | None = None class-attribute instance-attribute

wandb_attach_existing: bool = False class-attribute instance-attribute

Attach to an already-active W&B run without managing its lifecycle.

When True, GEPA logs metrics and tables into the run that is already active in the process (wandb.run) — it will not call wandb.init() on entry or wandb.finish() on exit.

wandb_step_metric: str | None = None class-attribute instance-attribute

Custom x-axis metric name for wandb charts.

When set, GEPA uses wandb.define_metric to declare a custom x-axis for all its metrics, decoupling them from wandb's global monotonic step counter. The step value passed to log_metrics is injected as a regular metric (under this name) instead of being passed as step=.

Required when embedding GEPA inside a host training loop that manages its own wandb step counter. Without this, GEPA's step=1, 2, 3, ... collides with the host's step=100, 101, ..., causing wandb to drop GEPA's data.

Example::

TrackingConfig(
    use_wandb=True,
    wandb_attach_existing=True,
    wandb_step_metric="gepa/iteration",
)

use_mlflow: bool = False class-attribute instance-attribute

mlflow_tracking_uri: str | None = None class-attribute instance-attribute

mlflow_experiment_name: str | None = None class-attribute instance-attribute

mlflow_attach_existing: bool = False class-attribute instance-attribute

Attach to an already-active MLflow run without managing its lifecycle.

When True, GEPA logs into the run that is already active (via mlflow.active_run()) — it will not call mlflow.start_run() on entry or mlflow.end_run() on exit.

Use this when embedding GEPA inside a training loop that manages its own MLflow run::

import mlflow
with mlflow.start_run():          # caller owns this run
    result = optimize_anything(
        ...,
        config=GEPAConfig(
            tracking=TrackingConfig(
                use_mlflow=True,
                mlflow_attach_existing=True,
            )
        ),
    )
    mlflow.log_metric("train/loss", 0.1)  # still works

key_prefix: str = '' class-attribute instance-attribute

String prepended to every key/name logged to wandb and MLflow.

Applies uniformly to metric keys, config keys, summary keys, table names, and HTML artifact keys. Useful when running multiple GEPA optimizations in the same wandb/MLflow run to keep their data namespaced::

TrackingConfig(
    use_wandb=True,
    wandb_attach_existing=True,
    key_prefix="gepa/round2/",   # metrics become e.g. gepa/round2/val_score
)

Functions