Skip to content
OmniLoop

TrainingLoop API

TrainingLoop is the recommended integration path for OmniLoop. It derives the dashboard schema from your existing config dataclass (meaning no YAML to maintain), coerces incoming mutations to the correct type, and binds each one back to the live object it controls. This eliminates the need to hand-write a schema, a mutation if-ladder, and a telemetry payload and keep all three in sync.

When to use

Section titled “When to use”

Use TrainingLoop when you have a Python-based loop driven by a configuration object (like a dataclass or SimpleNamespace) and want to seamlessly bind dashboard sliders to both your configuration and live application objects (such as a PyTorch optimizer).

Constructor

Section titled “Constructor”

Create a TrainingLoop instance using from_dataclass:

from omniloop import TrainingLoop


loop = TrainingLoop.from_dataclass(
    cfg.ppo,                                      # your existing config object
    tunable=["learning_rate", "entropy_coef", "clip_param"],
    bind={"learning_rate": optimizer},            # writes optimizer.param_groups[*]["lr"]
    bounds={"learning_rate": (1e-5, 1e-2, 1e-5)}, # optional slider-range overrides
    journal="run.omni",                           # optional: record for replay
)

Parameters

Section titled “Parameters”
Parameter Type Description
cfg Any Configuration object (dataclass, SimpleNamespace, or any object with attributes).
tunable list[str] List of attribute names to expose as sliders in the dashboard.
bind dict Maps parameter names to live objects. Targets can be a torch-style optimizer, a callable fn(value), or an (obj, "attr") tuple.
bounds dict Maps parameter names to (min, max, step) tuples, overriding default slider ranges.
journal str Optional path for .omni journal recording (enables replay).
hash_every int Checkpoint hash interval for divergence detection (default 0 = disabled).
freeze_on_exception bool Whether to halt the loop instead of crashing on exception (default True).
tracker Tracker Optional injectable tracker instance.

The Main Loop

Section titled “The Main Loop”

Wrap your per-iteration logic in a with loop.tick(): block.

for it in range(num_iterations):
    with loop.tick():                              # halt/step barrier + apply edits
        train_one_iteration(...)
        loop.log(reward_mean=r, policy_loss=pl)    # read-only dashboard readouts

The tick() context manager:

  1. Blocks execution if the dashboard has halted the loop.
  2. Applies any pending parameter edits from the dashboard to both your config and the bound live object (e.g., updating cfg.learning_rate and the optimizer’s state).
  3. Publishes a telemetry frame when the block exits.

Other Methods

Section titled “Other Methods”
  • loop.log(**kwargs): Add read-only readouts to the current telemetry frame.
  • loop.add_sink(callable): Attach additional telemetry sinks (e.g., RerunSink).
  • loop.export_tuned_config("tuned.yaml"): Export the final configured state after live tuning.
  • loop.close(): Finalize the journal and clean up resources.