Using the Python API

Most users run XReduce through the CLI - xreduce evaluate and xreduce profile cover the workflow end-to-end. The Python API is for when you need to embed XReduce inside your own code: a training loop, a custom inference harness, or a CI pipeline that needs more control than the CLI gives you.

The basic shape

The CLI loads a model, runs inference, and sends telemetry. The Python API exposes the same three steps so you can call them directly:

from xreduce import ModelRunner

runner = ModelRunner("config.yaml")

# Load your model however you want - XReduce doesn't care
# as long as it's ready to call.
model = load_your_model()
tokenizer = load_your_tokenizer()

# Run inference with telemetry captured automatically.
result = runner.run(
    model,
    "Your input text here",
    tokenizer,
)

print(runner.get_last_run_id())

The ModelRunner reads your config.yaml, wraps the call with telemetry capture, and sends results to your XReduce account. You get a run ID back that you can look up in the dashboard.

When to use it

• You're already in Python. Your agent or inference harness is a Python program, and shelling out to xreduce evaluate as a subprocess is the wrong shape. Call the API directly.
• You want per-request instrumentation. Measure a specific inference inside a larger pipeline rather than running a full benchmark sweep.
• You're running in CI. Wire XReduce into a build step that evaluates your model on every change.
• Your setup is nonstandard. Custom tokenizers, model wrappers, or inference patterns that the CLI's default path doesn't cover.

What we don't document publicly yet

The API has more surface area than the single call above - lower-level profiler controls, batch inference, custom telemetry attachment - but those interfaces are still stabilizing. We haven't published them as a public contract because we don't want to make commitments we'd have to break in the next few releases.

If you need to integrate XReduce deeply into your stack and the basic pattern above doesn't fit, reach out - we'll walk you through the interfaces that exist today and flag which ones are safe to build against.