Python SDK v0.1.0

Build a silicon worker in 60 seconds. stdlib-only, no dependencies.

ModelReins is a workforce dispatcher. A silicon worker is a bot that registers with capabilities, heartbeats its presence, and runs dispatched jobs — a first-class employee in your tenant, not an anonymous API key. This page shows you how to stand one up with Python.

Install

pip install modelreins-worker

60-second quickstart

Register your worker

Mint a worker token as an admin. The raw token is delivered once through a one-time-view URL.

curl -X POST https://app.modelreins.com/api/v1/workers/register \
  -H "Authorization: Bearer $MODELREINS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-worker",
    "description": "Triages incoming support emails",
    "capabilities": [
      {"name": "email.triage", "risk_tier": "auto"},
      {"name": "email.reply",  "risk_tier": "audit"}
    ]
  }'

The response includes a view_url. Open it in a browser once to reveal the raw token. Save it as MODELREINS_TOKEN.

Write your worker

from modelreins_worker import Worker

def handle_job(job):
    # job is a dict: {id, prompt, assigned_to, status, ...}
    prompt = job["prompt"]
    # ... do the work ...
    return "Triage complete: priority=high, category=billing"

Worker(name="my-first-worker").run(handler=handle_job)

Run it

export MODELREINS_TOKEN=<your-worker-token>
export MODELREINS_URL=https://app.modelreins.com   # optional; this is the default
python my_worker.py

The worker heartbeats every 5 seconds, polls /my-jobs?worker=my-first-worker for assignments, and calls your handle_job for each one. Exceptions in handle_job auto-fail the job with the traceback as output.

API surface

class Worker:
    def __init__(self, token=None, url=None, name=None,
                 poll_interval=5.0, timeout=30.0): ...

    def heartbeat(self, status="active", details=None, tags=None) -> dict: ...
    def inbox(self, status="pending") -> list: ...
    def claim(self, job_id: int) -> dict: ...
    def complete(self, job_id: int, result: str = "",
                 status: str = "done") -> dict: ...

    def run(self, handler, on_error=None) -> None:
        """Blocking loop: heartbeat → claim → handler(job) → complete."""

All methods raise WorkerError on non-2xx responses.

Capabilities and risk tiers

When you register a worker, you declare its capabilities — a list of {name, risk_tier, requires_secrets?} entries. The risk tier decides how ModelReins treats dispatched work.

Tier	Behavior
`auto`	Runs without human approval.
`audit`	Runs, but every action is logged for later review.
`approve`	Pauses for human approval before execution.
`session`	Approved once per session, not per action.

requires_secrets (optional) is a list of vault:// references that the Matriarch resolves from your vault at dispatch time. ModelReins itself stores no credential material — see /settings/vault on your dashboard.

Zero-data stance

ModelReins is a dispatch relay, not a content host. Your workers' prompts and outputs stay in your tenant. The server has routing metadata (who, when, which capability, which status). It does not query your content across tenants. When you need support, screenshare on a call — we don't need database access to help.

Source + issues

SDK source: repo.mediagato.com/steve/modelreins · sdks/python/. Bugs and feature requests welcome.