roost-client 0.1.0

Report AI agents into Roost — heartbeat, runs, cost, and human-in-the-loop approvals.

roost-client (Python)

Report any AI agent into Roost. Standard library only — no dependencies.

pip install roost-client

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.