Metadata-Version: 2.4
Name: roost-client
Version: 0.1.0
Summary: Report AI agents into Roost — heartbeat, runs, cost, and human-in-the-loop approvals.
Project-URL: Homepage, https://github.com/Gregbenn7/roost
Project-URL: Repository, https://github.com/Gregbenn7/roost
Project-URL: Issues, https://github.com/Gregbenn7/roost/issues
Author: Greg Bennett
License: MIT
Keywords: ai-agents,control-plane,observability,roost
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# roost-client (Python)

Report any AI agent into [Roost](../../README.md). Standard library only — no dependencies.

```bash
pip install roost-client
```

```python
from roost_client import Roost

roost = Roost(
    url="https://xxxx.supabase.co",   # your Roost / Supabase project URL
    api_key="rsk_...",                # from Roost → Settings → API keys
    slug="lead-enricher",
)

# 1. Register on boot (idempotent)
roost.register(name="Lead Enricher", job_title="Enrichment", department="Sales", runtime="custom")

# 2. Heartbeat while alive
stop = roost.start_heartbeat(15)

# 3. A run per task
run = roost.start_run(trigger="cron")
try:
    roost.log("Enriched 12 leads", run=run)
    roost.end_run(run, status="success", cost_usd=0.08, summary="Enriched 12 leads")
except Exception as e:
    roost.end_run(run, status="error", error_message=str(e))

# 4. Gate anything irreversible behind a human
if roost.request_approval(action_label="Spend $50 on ads", payload={"budget": 50}):
    ...  # a human clicked Approve

stop()
```

- `start_heartbeat` runs a daemon thread and returns a `stop()` callable.
- `request_approval` **blocks** until a human decides, it expires, or `timeout` elapses; returns `True` only on an explicit approve.
- Pass `on_error=...` so transport errors are reported instead of raised (telemetry should never crash your agent).

MIT.
