Metadata-Version: 2.4
Name: modelreins-worker
Version: 0.2.0
Summary: ModelReins silicon-worker SDK — stdlib-only HTTP client.
Author-email: Mediagato <steve@mediagato.com>
License: MIT
Project-URL: Homepage, https://modelreins.com
Project-URL: Documentation, https://modelreins.com/docs/sdk/python
Project-URL: Repository, https://repo.mediagato.com/steve/modelreins
Keywords: modelreins,ai,agent,worker,orchestration,dispatch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# modelreins-worker

The Python SDK for building **silicon workers** on [ModelReins](https://modelreins.com).

ModelReins is an AI workforce dispatcher. A *silicon worker* is a bot that registers with capabilities, heartbeats its presence, and runs dispatched jobs — treated as a first-class employee in your tenant, not an anonymous API key.

**stdlib-only.** No `requests`, no `httpx` — just `urllib`. ~150 LOC.

## Install

```bash
pip install modelreins-worker
```

## 60-second quickstart

### 1. Register your worker

Mint a worker token (admin or master-token required, one-time-view URL returned):

```bash
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": "Handles triage on new support emails",
    "capabilities": [
      {"name": "email.triage", "risk_tier": "auto"},
      {"name": "email.reply",  "risk_tier": "audit"}
    ]
  }'
```

Response includes `view_url` — open it once to reveal the raw token. Save it as `MODELREINS_TOKEN`.

### 2. Write your worker

```python
from modelreins_worker import Worker

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

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

### 3. Run it

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

The worker will heartbeat every 5s, poll `/my-jobs?worker=my-first-worker` for pending assignments, and call your `handle_job` for each one. Exceptions in `handle_job` auto-mark the job `failed` with the traceback as output.

## API surface

```python
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 + risk tiers

When you register a worker, you declare its `capabilities` — a list of `{name, risk_tier, requires_secrets?}` entries.

Risk tiers:

| tier | behavior |
|---|---|
| `auto` | runs without human approval |
| `audit` | runs, but every action is logged for later review |
| `approve` | waits for human approval before execution |
| `session` | approved once per session, not per action |

`requires_secrets` (optional) is a list of `vault://...` refs that the Director will resolve from your vault at dispatch time. ModelReins itself holds no credential material — see `/settings/vault` on your tenant 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 — and at the policy level will not — query your content across tenants. See the threat model at `https://modelreins.com/security` (coming soon).

## License

MIT.
