Raw SDK Primitives

While the TrainingLoop API provides a convenient wrapper, it is a thin layer over the OmniLoop SDK primitives. You can call these primitives directly for full control over your execution flow and telemetry.

When to use

Use the raw primitives when:

You need to integrate OmniLoop into an execution flow you cannot easily restructure (e.g., a C++ engine calling into Python).
You need fine-grained control over exactly what gets published and when.
You do not have a centralized configuration dataclass to derive a schema from.

Basic Usage

When using raw primitives, you must manually define your parameter schema, block on halts, poll for mutations, and publish telemetry.

import json
from omniloop import tracker, load_param_schema

# 1. Define schema
load_param_schema("my_params.yaml")   # or use declare_param(...)

for epoch in range(num_epochs):
    # 2. Pause point: block if the dashboard has halted the loop
    tracker.wait_if_halted()

    # 3. Apply dashboard edits
    mutations = tracker.get_mutations()
    if "learning_rate" in mutations:
        lr = float(mutations["learning_rate"])

    # ... your application logic ...

    # 4. Publish telemetry
    tracker.publish_telemetry_raw(json.dumps({
        "learning_rate": lr,
        "reward_mean": reward_mean,
        # ... other state ...
    }))

Core Methods

Method	Description
`tracker.wait_if_halted()`	Blocks execution until the loop is resumed via the dashboard. Call once per iteration.
`tracker.get_mutations() -> dict`	Returns parameter edits from the dashboard since the last call. Keys are parameter names; values are strings.
`tracker.publish_telemetry_raw(json_str)`	Publishes a JSON-encoded state snapshot to the shared-memory channel.
`tracker.register_variable_pointer(name, addr, var_type)`	Register a raw memory pointer for zero-copy reflection.

Advanced & Diagnostic Methods

Method	Description
`tracker.add_watchpoint(name, condition, threshold)`	Arms a conditional halt (e.g., halt if a metric exceeds a threshold).
`tracker.set_watch_all_nonfinite(bool)`	Automatically halts the loop on any `NaN` or `inf` value.
`tracker.stats() -> dict`	Returns IPC health counters.
`tracker.dump_flight_recorder(path)`	Dumps the black box ring buffer to disk.
`tracker.set_flight_recorder_capacity(n)`	Sets the capacity of the ring buffer.
`tracker.state_hash(exclude=[...]) -> int`	Hashes the registry’s canonical state to help detect divergence.

Session Isolation

If you run multiple concurrent instances of your application, you must isolate their OmniLoop sessions to prevent IPC collisions.

Set the OMNILOOP_SESSION_ID environment variable before starting your process.
Alternatively, use the CLI wrapper which handles this automatically:

omniloop up --session my_run