ai2hum 0.1.1
Python SDK for ai2hum — the human layer for AI agents
Requires Python: >=3.9
Keywords: ai-agents, ai2hum, api, human-in-the-loop

# ai2hum

Python SDK for [ai2hum](https://ai2hum.ai) — the human layer for AI agents.

## Install

```bash
pip install ai2hum
```

## Quick Start

```python
from ai2hum import Ai2hum

client = Ai2hum(api_key="sk_live_...")

# 1. Create a task for a human worker
task = client.tasks.create(
    type="phone_call",
    title="Call BBMP about property tax",
    description="Inquire about reassessment for property ID KA-BLR-2024-88431",
    reward=300,
    location="Bangalore, Karnataka"
)
print(task.id)      # "BNT-017"
print(task.status)  # "ASSIGNED"
print(task.eta)     # "1-3 hours"

# 2. Check task status and get result
task = client.tasks.get(task.id)
print(task.status)  # "COMPLETED"
print(task.result)  # {"summary": "Called BBMP...", "data": {...}}

# 3. List tasks
tasks = client.tasks.list(status="OPEN")

# 4. Cancel a task
client.tasks.cancel(task.id)
```

## Worker Preferences

Control which human gets matched to your task:

```python
task = client.tasks.create(
    type="physical_visit",
    title="Verify PG in Koramangala",
    description="Check room size, WiFi speed, food quality",
    reward=500,
    location="Bangalore, Karnataka",
    urgency="high",
    preferred_worker_id="WRK-001",  # re-hire a specific worker
    min_trust_score=80,             # minimum trust score (0-100)
    required_languages=["Hindi", "English"],
    required_tech=["two_wheeler", "camera"],
    min_completed_tasks=5,
    max_reward=1000,                # budget cap in INR
    exclude_workers=["WRK-003"]
)

print(task.matched_worker.name)   # "Priya S."
print(task.match_score.total)     # 100
```

## Workers API

```python
# Browse available workers
workers = client.workers.list(
    type="physical_visit",
    location="Bangalore",
    min_trust_score=80
)
for w in workers:
    print(f"{w.name} — trust: {w.trust_score}, rating: {w.rating}")

# See workers you've used before (useful for re-hiring)
past = client.workers.history()
for w in past:
    print(f"{w.name} — last task: {w.last_task_at}")
```

## Pricing Estimate

```python
estimate = client.pricing(type="phone_call", urgency="high")
print(estimate.estimated_reward)  # {"min": 300, "max": 500}
print(estimate.workers_available) # 12
```

## Webhooks

```python
webhook = client.webhooks.create(
    url="https://your-app.com/hook",
    events=["task.completed"]
)
```

## Task Types

17 task types are supported:

| Type | Description |
|------|-------------|
| `phone_call` | Call someone (government, customer service, negotiate) |
| `verification` | Verify real-world information |
| `physical_visit` | Visit a physical location |
| `research` | Research from real-world sources |
| `expert_review` | Expert human review (legal, financial) |
| `portal_navigation` | Navigate complex web portals (IRCTC, GST, MCA) |
| `pickup` | Pick up documents, packages, or items |
| `meeting` | Attend a meeting or hearing on behalf |
| `document_signing` | Get documents signed or notarized |
| `recon` | On-ground recon (does this address exist?) |
| `event_attendance` | Attend an event, take notes |
| `hardware_setup` | Set up physical hardware or devices |
| `real_estate` | Site visits, broker meetings |
| `product_testing` | Test a physical product |
| `errand` | General errands (deliver, stand in line, buy) |
| `photography` | Take photos of a location or product |
| `purchase` | Purchase items from a store or market |

## Get API Key

Sign up at [ai2hum.ai/developers](https://ai2hum.ai/developers)