Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Python client

The miroir Python package (Python 3.11 or later) leases containers and runs episodes. The adapters build on it; use it directly for your own loop.

uv pip install miroir               # the client and the host CLI
uv pip install 'miroir[trl]'        # with the TRL adapter
uv pip install 'miroir[verifiers]'  # with the verifiers adapter

An episode

import datetime
import miroir
from miroir import Session

url, token = "http://127.0.0.1:8000", "secret"
task = miroir.tasks(url, "train", token)[0]

session = Session.lease([url], token, wait_busy=True)
try:
    start = session.reset(task["id"])
    today = datetime.date.fromisoformat(start["now"][:10])
    print(miroir.prompt(start, today))
    step = session.step("api_request", {"method": "GET", "path": "/invoices"})
    print(step["observation"]["result"]["status"])
    outcome = session.finish()
    print(outcome["reward"], miroir.metrics(outcome["record"]))
finally:
    session.close()

Session

CallDoes
Session.lease(urls, token=None, *, wait_busy, timeout_s=600)opens a session on a free, healthy container; urls is a list or the path of a URL file
reset(task_id, max_seconds=None, coworkers=False)starts an episode; returns the reset observation
step(tool, arguments)calls a tool; returns observation, reward and done
finish()submits if the episode still runs; returns reward, success, metadata and record
state()the env’s state frame
coworker_turns()the turns coworkers owe
coworker_reply(coworker, text)posts a coworker’s answer
close()frees the container

lease with wait_busy=False fails at once when every container is leased; otherwise it waits up to timeout_s.

Helpers

FunctionReturns
tasks(url, split="train", token=None)a split’s tasks, as the env lists them
tools(url, token=None, surface=None)the tools on a surface: api, mcp or code
prompt(task, today)the user prompt: the instruction, who the agent acts as, its step budget and today’s date
read_urls(path)the URLs of a file miroir pool writes
answer_coworkers(session, model)answers every owed coworker turn with a CoworkerModel
metrics(record)success, harm, the diagnostics and episode_s, to log
save_record(directory, record)appends a record to this process’s JSONL file there

CoworkerModel(base_url, model, api_key=None, temperature=None) is an OpenAI-compatible chat endpoint.

Errors

Everything raises MiroirError, with a code and a message. Codes include the env’s frame errors, NO_FREE_CONTAINER, CONNECTION_FAILED, CONNECTION_LOST, NOT_GRADED and COWORKER_FAILED.