Metadata-Version: 2.4
Name: humanrail
Version: 0.1.0
Summary: Official Python SDK for HumanRail — route tasks to vetted human workers when AI hits its limits.
Project-URL: Homepage, https://humanrail.dev
Project-URL: Documentation, https://docs.humanrail.dev
Project-URL: Repository, https://github.com/prime001/humanrail-sdk
Project-URL: Issues, https://github.com/prime001/humanrail-sdk/issues
Author-email: HumanRail <contact@humanrail.dev>
License-Expression: MIT
Keywords: ai-agents,escalation,hitl,human-in-the-loop,humanrail,langchain,task-routing
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# HumanRail Python SDK

Official Python client library for the [HumanRail](https://humanrail.dev) API.

Route tasks to vetted human workers when your AI hits its limits. Verified results. Instant payouts. One API call.

## Installation

```bash
pip install humanrail
```

Requires Python 3.12+.

## Quick Start

```python
import os
from humanrail import EscalationClient

client = EscalationClient(api_key=os.environ["HUMANRAIL_API_KEY"])

task = client.tasks.create(
    idempotency_key="order-12345-refund",
    task_type="refund_eligibility",
    risk_tier="medium",
    sla_seconds=300,
    payload={
        "orderId": "order-12345",
        "reason": "Item arrived damaged",
    },
    output_schema={
        "type": "object",
        "required": ["eligible", "reason_code"],
        "properties": {
            "eligible": {"type": "boolean"},
            "reason_code": {"type": "string", "enum": ["approved", "denied_policy", "needs_review"]},
        },
    },
    payout={"currency": "USD", "max_amount": 0.50},
)

result = client.tasks.wait_for_completion(task.id, timeout=600)
print(result.output)
# {"eligible": True, "reason_code": "approved"}
```

### Async Usage

```python
from humanrail import AsyncEscalationClient

async_client = AsyncEscalationClient(api_key=os.environ["HUMANRAIL_API_KEY"])
task = await async_client.tasks.acreate(...)
result = await async_client.tasks.await_for_completion(task.id)
```

## Features

- Synchronous and async clients
- Automatic retries with exponential backoff
- Webhook signature verification (HMAC-SHA256)
- Idempotency support
- Typed responses with Pydantic models
- OpenTelemetry tracing

## Documentation

- [API Docs](https://docs.humanrail.dev)
- [SDK Guide](https://docs.humanrail.dev/sdk/python)
- [Examples](https://github.com/prime001/humanrail-sdk/tree/main/python/examples)

## License

MIT - see [LICENSE](https://github.com/prime001/humanrail-sdk/blob/main/LICENSE)
