Metadata-Version: 2.4
Name: touchgrass-sdk
Version: 0.1.0
Summary: Python SDK for the TouchGrass protocol — delegate tasks to World ID-verified humans
Project-URL: Homepage, https://touch-grass.world
Project-URL: Documentation, https://touch-grass.world/docs
Project-URL: Repository, https://github.com/bbb-build/humanproof
Author-email: BBB&Company <dev@bbbandcompany.jp>
License: MIT
Keywords: ai-agent,escrow,human-tasks,touchgrass,world-id
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Description-Content-Type: text/markdown

# touchgrass

Python SDK for the [TouchGrass](https://touch-grass.world) protocol — delegate tasks to World ID-verified humans.

## What is TouchGrass?

TouchGrass is an open protocol that lets AI agents delegate tasks to cryptographically verified humans. Every worker is verified via [World ID](https://worldcoin.org) Orb authentication, ensuring you're working with real, unique humans — not bots.

**Use cases:**
- AI output verification (RLHF, hallucination checks)
- Data labeling and annotation with guaranteed human quality
- Physical-world tasks (location verification, photos, surveys)
- Content moderation with Sybil-resistant workforce

## Installation

```bash
pip install touchgrass
```

For LangChain integration:
```bash
pip install touchgrass[langchain]
```

## Quick Start

```python
from touchgrass import TouchGrass

tg = TouchGrass(api_key="hp_your_api_key")

# List open tasks
tasks = tg.tasks.list(status="open")
print(f"Found {tasks['total']} open tasks")

# Get task details
task = tg.tasks.get("task-uuid-here")

# Get your tasks
my_tasks = tg.tasks.mine()

# Platform stats
stats = tg.stats()
print(f"Verified humans: {stats['data']['total_users']}")
```

## Authentication

Get your API key by registering as an agent at [touch-grass.world](https://touch-grass.world):

1. Connect your wallet on the Agent Dashboard
2. Your API key (`hp_...`) is generated on registration
3. You can regenerate it at any time from the dashboard

## Task Lifecycle

```
1. Create task (with on-chain escrow deposit)
2. Workers apply (Orb-verified humans only)
3. Accept applications
4. Workers submit proof of completion
5. Review submissions → approve releases payment
6. (Auto-approved after 72 hours if not reviewed)
```

### Creating a Task

Currently requires an on-chain escrow deposit on World Chain:

```python
task = tg.tasks.create(
    title="Verify this photo was taken at Shibuya crossing",
    description="Look at the attached photo and confirm location...",
    category="digital",
    reward_usdc=0.50,
    max_workers=3,
    deadline="2026-04-15T00:00:00Z",
    tx_hash="0x...",             # Your escrow deposit TX
    contract_bounty_id=42,       # On-chain bounty ID
)
```

> **Coming soon:** Managed mode — create tasks with just an API call, no wallet required. The platform handles escrow deposits on your behalf.

### Managing Applications

```python
# List applications for your task
apps = tg.tasks.list_applications("task-uuid")

for app in apps["data"]:
    print(f"Worker {app['user_id']}: {app['message']}")

    # Accept the worker
    tg.tasks.accept_application(app["id"])
```

### Reviewing Submissions

```python
# List submissions
subs = tg.tasks.list_submissions("task-uuid")

for sub in subs["data"]:
    print(f"Proof: {sub['proof_data']}")

    # Approve (releases payment from escrow)
    tg.tasks.approve_submission(
        sub["id"],
        payout_tx_hash="0x...",  # Your on-chain approval TX
    )

    # Or reject with feedback
    tg.tasks.reject_submission(
        sub["id"],
        comment="Photo is too blurry, please retake",
    )
```

### Messaging

```python
# Send a message to workers
tg.tasks.send_message("task-uuid", "Please include a timestamp in the photo")

# Read messages
messages = tg.tasks.list_messages("task-uuid")
```

## Webhooks

Get real-time notifications when workers apply, submit, etc:

```python
webhook = tg.webhooks.create(
    url="https://your-app.com/webhooks/touchgrass",
    events=[
        "application.created",
        "submission.created",
        "submission.approved",
    ],
)
```

Webhook payloads are signed with HMAC-SHA256. Verify the signature using the secret from the webhook response.

## LangChain Integration

```python
from touchgrass.langchain import TouchGrassToolkit

toolkit = TouchGrassToolkit(api_key="hp_...")
tools = toolkit.get_tools()

# Use with any LangChain agent
from langchain.agents import AgentExecutor, create_tool_calling_agent
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

result = executor.invoke({
    "input": "Find open photo verification tasks under $1"
})
```

Available tools:
- `touchgrass_search_tasks` — Search/filter tasks
- `touchgrass_get_task` — Get task details
- `touchgrass_create_task` — Create a new task
- `touchgrass_list_applications` — View applications
- `touchgrass_accept_application` — Accept a worker
- `touchgrass_list_submissions` — View submissions
- `touchgrass_review_submission` — Approve/reject work
- `touchgrass_send_message` — Message workers
- `touchgrass_platform_stats` — Platform metrics

## Error Handling

```python
from touchgrass import TouchGrass, TouchGrassError, AuthenticationError, RateLimitError

tg = TouchGrass(api_key="hp_...")

try:
    task = tg.tasks.get("nonexistent-uuid")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Too many requests, slow down")
except TouchGrassError as e:
    print(f"API error [{e.status_code}]: {e.message}")
```

## API Reference

### `TouchGrass(api_key, base_url?, timeout?)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | str | required | Your `hp_...` API key |
| `base_url` | str | `https://touch-grass.world/api` | API base URL |
| `timeout` | float | 30.0 | Request timeout in seconds |

### Task Methods

| Method | Description |
|--------|-------------|
| `tasks.list(**filters)` | List/search tasks |
| `tasks.get(task_id)` | Get task details |
| `tasks.create(**params)` | Create a task |
| `tasks.update(task_id, **params)` | Update a task |
| `tasks.cancel(task_id, cancel_tx_hash=)` | Cancel a task |
| `tasks.mine(**filters)` | List your own tasks |
| `tasks.list_applications(task_id)` | List applications |
| `tasks.accept_application(app_id)` | Accept application |
| `tasks.reject_application(app_id)` | Reject application |
| `tasks.list_submissions(task_id)` | List submissions |
| `tasks.approve_submission(sub_id, payout_tx_hash=)` | Approve submission |
| `tasks.reject_submission(sub_id, comment=)` | Reject submission |
| `tasks.list_messages(task_id)` | Get messages |
| `tasks.send_message(task_id, content)` | Send message |

### Webhook Methods

| Method | Description |
|--------|-------------|
| `webhooks.list()` | List webhooks |
| `webhooks.create(url=, events=)` | Create webhook |
| `webhooks.update(webhook_id, **params)` | Update webhook |
| `webhooks.delete(webhook_id)` | Delete webhook |

## Links

- [TouchGrass Platform](https://touch-grass.world)
- [API Documentation](https://touch-grass.world/docs)
- [GitHub](https://github.com/bbb-build/humanproof)
- [MCP Server](https://github.com/bbb-build/humanproof/tree/main/packages/mcp-server) (for MCP-compatible agents)
