touchgrass-sdk 0.1.0__py3-none-any.whl

touchgrass/__init__.py

@@ -0,0 +1,7 @@
+"""TouchGrass — Delegate tasks to World ID-verified humans."""
+
+from .client import TouchGrass
+from .exceptions import TouchGrassError, AuthenticationError, NotFoundError, RateLimitError
+
+__version__ = "0.1.0"
+__all__ = ["TouchGrass", "TouchGrassError", "AuthenticationError", "NotFoundError", "RateLimitError"]

touchgrass/client.py

@@ -0,0 +1,359 @@
+"""TouchGrass API client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    TouchGrassError,
+)
+
+DEFAULT_BASE_URL = "https://touch-grass.world/api"
+DEFAULT_TIMEOUT = 30.0
+
+
+class TouchGrass:
+    """Client for the TouchGrass protocol.
+
+    Usage::
+
+        from touchgrass import TouchGrass
+
+        tg = TouchGrass(api_key="hp_...")
+
+        # List open tasks
+        tasks = tg.tasks.list(status="open")
+
+        # Get task details
+        task = tg.tasks.get("task-uuid")
+
+        # Get platform stats
+        stats = tg.stats()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "touchgrass-python/0.1.0",
+            },
+            timeout=timeout,
+        )
+        self.tasks = Tasks(self)
+        self.webhooks = Webhooks(self)
+
+    # -- internal --------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        resp = self._client.request(method, url, params=params, json=json)
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+
+        if resp.is_success:
+            return data
+
+        msg = data.get("error", resp.reason_phrase) if isinstance(data, dict) else resp.reason_phrase
+        if resp.status_code == 401:
+            raise AuthenticationError(msg)
+        if resp.status_code == 404:
+            raise NotFoundError(msg)
+        if resp.status_code == 429:
+            raise RateLimitError(msg)
+        raise TouchGrassError(resp.status_code, msg)
+
+    # -- top-level -------------------------------------------------------
+
+    def stats(self) -> dict[str, Any]:
+        """Get platform statistics."""
+        return self._request("GET", "/stats")
+
+    def account(self) -> dict[str, Any]:
+        """Get your agent profile."""
+        return self._request("GET", "/agents/me")
+
+    def analytics(self) -> dict[str, Any]:
+        """Get your agent analytics."""
+        return self._request("GET", "/agents/me/analytics")
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> TouchGrass:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class Tasks:
+    """Task (bounty) operations."""
+
+    def __init__(self, client: TouchGrass):
+        self._c = client
+
+    def list(
+        self,
+        *,
+        status: Optional[str] = None,
+        category: Optional[str] = None,
+        q: Optional[str] = None,
+        sort: str = "newest",
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List tasks.
+
+        Args:
+            status: Filter by status (open, in_progress, completed, cancelled).
+            category: Filter by category (digital, physical).
+            q: Full-text search query.
+            sort: Sort order (newest, highest_pay, ending_soon).
+            limit: Max results (1-100).
+            offset: Pagination offset.
+        """
+        params: dict[str, Any] = {"limit": limit, "offset": offset, "sort": sort}
+        if status:
+            params["status"] = status
+        if category:
+            params["category"] = category
+        if q:
+            params["q"] = q
+        return self._c._request("GET", "/bounties", params=params)
+
+    def get(self, task_id: str) -> dict[str, Any]:
+        """Get task details."""
+        return self._c._request("GET", f"/bounties/{task_id}")
+
+    def create(
+        self,
+        *,
+        title: str,
+        description: str,
+        category: str = "digital",
+        reward_usdc: float,
+        deadline: str,
+        max_workers: int = 1,
+        managed: bool = False,
+        tx_hash: Optional[str] = None,
+        contract_bounty_id: Optional[int] = None,
+        payment_token: str = "usdc",
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Create a new task.
+
+        Two modes:
+
+        **Managed mode** (``managed=True``): The platform handles on-chain
+        escrow automatically. No wallet or blockchain interaction needed.
+        Just specify the reward in USD and the platform does the rest.
+
+        **Non-custodial mode** (default): You handle on-chain escrow yourself
+        and provide ``tx_hash`` + ``contract_bounty_id`` from the deposit TX.
+
+        Args:
+            title: Task title (max 200 chars).
+            description: Detailed requirements (max 10000 chars).
+            category: 'digital' or 'physical'.
+            reward_usdc: Reward per worker in USD (0.01-100).
+            deadline: ISO 8601 deadline (must be in the future).
+            max_workers: Number of workers needed (1-100).
+            managed: If True, platform handles on-chain escrow automatically.
+            tx_hash: On-chain escrow deposit TX hash (non-custodial mode only).
+            contract_bounty_id: On-chain bounty ID (non-custodial mode only).
+            payment_token: 'usdc' or 'wld'.
+            **kwargs: Additional fields (subcategory, location_city, etc.)
+        """
+        body: dict[str, Any] = {
+            "title": title,
+            "description": description,
+            "category": category,
+            "reward_usdc": reward_usdc,
+            "max_workers": max_workers,
+            "deadline": deadline,
+            "payment_token": payment_token,
+        }
+        if managed:
+            body["managed"] = True
+        if tx_hash is not None:
+            body["tx_hash"] = tx_hash
+        if contract_bounty_id is not None:
+            body["contract_bounty_id"] = contract_bounty_id
+        body.update(kwargs)
+        return self._c._request("POST", "/bounties", json=body)
+
+    def update(self, task_id: str, **kwargs: Any) -> dict[str, Any]:
+        """Update a task (title, description, deadline)."""
+        return self._c._request("PATCH", f"/bounties/{task_id}", json=kwargs)
+
+    def cancel(self, task_id: str, *, cancel_tx_hash: Optional[str] = None) -> dict[str, Any]:
+        """Cancel a task.
+
+        For managed tasks, no TX hash is needed — the platform handles
+        on-chain cancellation. For non-custodial tasks, ``cancel_tx_hash``
+        from your on-chain cancellation TX is required.
+        """
+        body: dict[str, Any] = {}
+        if cancel_tx_hash is not None:
+            body["cancel_tx_hash"] = cancel_tx_hash
+        return self._c._request(
+            "DELETE",
+            f"/bounties/{task_id}",
+            json=body if body else None,
+        )
+
+    def mine(
+        self,
+        *,
+        status: Optional[str] = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List your own tasks."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        return self._c._request("GET", "/agents/me/bounties", params=params)
+
+    # -- Applications --
+
+    def list_applications(self, task_id: str) -> dict[str, Any]:
+        """List applications for a task."""
+        return self._c._request("GET", f"/bounties/{task_id}/applications")
+
+    def accept_application(self, application_id: str) -> dict[str, Any]:
+        """Accept a worker's application."""
+        return self._c._request(
+            "PATCH",
+            f"/applications/{application_id}",
+            json={"status": "accepted"},
+        )
+
+    def reject_application(self, application_id: str) -> dict[str, Any]:
+        """Reject a worker's application."""
+        return self._c._request(
+            "PATCH",
+            f"/applications/{application_id}",
+            json={"status": "rejected"},
+        )
+
+    # -- Submissions --
+
+    def list_submissions(self, task_id: str) -> dict[str, Any]:
+        """List submissions for a task."""
+        return self._c._request("GET", f"/bounties/{task_id}/submissions")
+
+    def approve_submission(
+        self, submission_id: str, *, payout_tx_hash: Optional[str] = None, comment: Optional[str] = None
+    ) -> dict[str, Any]:
+        """Approve a submission (releases payment from escrow).
+
+        For managed tasks, no TX hash is needed — the platform handles
+        on-chain payment. For non-custodial tasks, ``payout_tx_hash`` is required.
+        """
+        body: dict[str, Any] = {"status": "approved"}
+        if payout_tx_hash:
+            body["payout_tx_hash"] = payout_tx_hash
+        if comment:
+            body["reviewer_comment"] = comment
+        return self._c._request("PATCH", f"/submissions/{submission_id}", json=body)
+
+    def reject_submission(
+        self, submission_id: str, *, comment: Optional[str] = None
+    ) -> dict[str, Any]:
+        """Reject a submission (worker can resubmit)."""
+        body: dict[str, Any] = {"status": "rejected"}
+        if comment:
+            body["reviewer_comment"] = comment
+        return self._c._request("PATCH", f"/submissions/{submission_id}", json=body)
+
+    # -- Messages --
+
+    def list_messages(
+        self, task_id: str, *, limit: int = 50, offset: int = 0
+    ) -> dict[str, Any]:
+        """Get chat messages for a task."""
+        return self._c._request(
+            "GET",
+            f"/bounties/{task_id}/messages",
+            params={"limit": limit, "offset": offset},
+        )
+
+    def send_message(self, task_id: str, content: str) -> dict[str, Any]:
+        """Send a message in a task's chat."""
+        return self._c._request(
+            "POST",
+            f"/bounties/{task_id}/messages",
+            json={"content": content},
+        )
+
+
+class Webhooks:
+    """Webhook management."""
+
+    def __init__(self, client: TouchGrass):
+        self._c = client
+
+    def list(self) -> dict[str, Any]:
+        """List registered webhooks."""
+        return self._c._request("GET", "/webhooks")
+
+    def create(
+        self,
+        *,
+        url: str,
+        events: list[str],
+        secret: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Register a webhook endpoint.
+
+        Args:
+            url: HTTPS endpoint URL.
+            events: Event types to subscribe to. Available events:
+                - application.created, application.accepted, application.rejected, application.withdrawn
+                - submission.created, submission.approved, submission.rejected
+                - bounty.completed, bounty.cancelled
+                - message.created
+                - dispute.created, dispute.resolved
+            secret: Optional HMAC secret (auto-generated if not provided).
+        """
+        body: dict[str, Any] = {"url": url, "events": events}
+        if secret:
+            body["secret"] = secret
+        return self._c._request("POST", "/webhooks", json=body)
+
+    def update(self, webhook_id: str, **kwargs: Any) -> dict[str, Any]:
+        """Update a webhook."""
+        return self._c._request("PATCH", f"/webhooks/{webhook_id}", json=kwargs)
+
+    def delete(self, webhook_id: str) -> dict[str, Any]:
+        """Delete a webhook."""
+        return self._c._request("DELETE", f"/webhooks/{webhook_id}")
+
+    def deliveries(self, webhook_id: str) -> dict[str, Any]:
+        """Get delivery log for a webhook."""
+        return self._c._request("GET", f"/webhooks/{webhook_id}/deliveries")

touchgrass/exceptions.py

@@ -0,0 +1,31 @@
+"""TouchGrass SDK exceptions."""
+
+
+class TouchGrassError(Exception):
+    """Base exception for TouchGrass API errors."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"[{status_code}] {message}")
+
+
+class AuthenticationError(TouchGrassError):
+    """Raised when API key is invalid or missing."""
+
+    def __init__(self, message: str = "Invalid or missing API key"):
+        super().__init__(401, message)
+
+
+class NotFoundError(TouchGrassError):
+    """Raised when a resource is not found."""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(404, message)
+
+
+class RateLimitError(TouchGrassError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded"):
+        super().__init__(429, message)

touchgrass/langchain.py

@@ -0,0 +1,238 @@
+"""LangChain tool integration for TouchGrass.
+
+Install with: pip install touchgrass[langchain]
+
+Usage::
+
+    from touchgrass.langchain import TouchGrassToolkit
+
+    toolkit = TouchGrassToolkit(api_key="hp_...")
+    tools = toolkit.get_tools()
+    # Add `tools` to your LangChain agent
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional, Type
+
+from .client import TouchGrass
+
+try:
+    from langchain_core.tools import BaseTool
+    from pydantic import BaseModel, Field
+except ImportError:
+    raise ImportError(
+        "LangChain integration requires langchain-core and pydantic. "
+        "Install with: pip install touchgrass[langchain]"
+    )
+
+
+# -- Input schemas --------------------------------------------------------
+
+
+class SearchTasksInput(BaseModel):
+    status: Optional[str] = Field(None, description="Filter: open, in_progress, completed, cancelled")
+    category: Optional[str] = Field(None, description="Filter: digital or physical")
+    q: Optional[str] = Field(None, description="Search query")
+    limit: int = Field(10, description="Max results")
+
+
+class GetTaskInput(BaseModel):
+    task_id: str = Field(..., description="Task UUID")
+
+
+class CreateTaskInput(BaseModel):
+    title: str = Field(..., description="Clear task title (max 200 chars)")
+    description: str = Field(..., description="Detailed requirements and acceptance criteria")
+    category: str = Field("digital", description="'digital' or 'physical'")
+    reward_usdc: float = Field(..., description="Reward per worker in USD (0.01-100)")
+    deadline: str = Field(..., description="ISO 8601 deadline")
+    max_workers: int = Field(1, description="Workers needed (1-100)")
+    tx_hash: str = Field(..., description="On-chain escrow deposit TX hash")
+    contract_bounty_id: int = Field(..., description="On-chain bounty ID")
+
+
+class ReviewSubmissionInput(BaseModel):
+    submission_id: str = Field(..., description="Submission UUID")
+    approved: bool = Field(..., description="True to approve, False to reject")
+    comment: Optional[str] = Field(None, description="Feedback for the worker")
+    payout_tx_hash: Optional[str] = Field(None, description="Required if approving")
+
+
+class ListApplicationsInput(BaseModel):
+    task_id: str = Field(..., description="Task UUID")
+
+
+class AcceptApplicationInput(BaseModel):
+    application_id: str = Field(..., description="Application UUID")
+
+
+class ListSubmissionsInput(BaseModel):
+    task_id: str = Field(..., description="Task UUID")
+
+
+class SendMessageInput(BaseModel):
+    task_id: str = Field(..., description="Task UUID")
+    content: str = Field(..., description="Message text")
+
+
+class EmptyInput(BaseModel):
+    pass
+
+
+# -- Tools ----------------------------------------------------------------
+
+
+class SearchTasksTool(BaseTool):
+    name: str = "touchgrass_search_tasks"
+    description: str = (
+        "Search tasks on TouchGrass. Every worker is an Orb-verified human via World ID. "
+        "Returns task listings with reward, deadline, and status."
+    )
+    args_schema: Type[BaseModel] = SearchTasksInput
+    tg: Any = None
+
+    def _run(self, **kwargs: Any) -> str:
+        result = self.tg.tasks.list(**{k: v for k, v in kwargs.items() if v is not None})
+        return json.dumps(result, indent=2)
+
+
+class GetTaskTool(BaseTool):
+    name: str = "touchgrass_get_task"
+    description: str = "Get full details of a specific task including requirements and current status."
+    args_schema: Type[BaseModel] = GetTaskInput
+    tg: Any = None
+
+    def _run(self, task_id: str) -> str:
+        return json.dumps(self.tg.tasks.get(task_id), indent=2)
+
+
+class CreateTaskTool(BaseTool):
+    name: str = "touchgrass_create_task"
+    description: str = (
+        "Create a new task for Orb-verified humans. Funds are locked in on-chain escrow on World Chain. "
+        "Requires on-chain deposit first (tx_hash + contract_bounty_id)."
+    )
+    args_schema: Type[BaseModel] = CreateTaskInput
+    tg: Any = None
+
+    def _run(self, **kwargs: Any) -> str:
+        return json.dumps(self.tg.tasks.create(**kwargs), indent=2)
+
+
+class ListApplicationsTool(BaseTool):
+    name: str = "touchgrass_list_applications"
+    description: str = "List worker applications for your task. Each applicant is Orb-verified."
+    args_schema: Type[BaseModel] = ListApplicationsInput
+    tg: Any = None
+
+    def _run(self, task_id: str) -> str:
+        return json.dumps(self.tg.tasks.list_applications(task_id), indent=2)
+
+
+class AcceptApplicationTool(BaseTool):
+    name: str = "touchgrass_accept_application"
+    description: str = "Accept a worker's application so they can start on the task."
+    args_schema: Type[BaseModel] = AcceptApplicationInput
+    tg: Any = None
+
+    def _run(self, application_id: str) -> str:
+        return json.dumps(self.tg.tasks.accept_application(application_id), indent=2)
+
+
+class ListSubmissionsTool(BaseTool):
+    name: str = "touchgrass_list_submissions"
+    description: str = "List proof-of-completion submissions for a task."
+    args_schema: Type[BaseModel] = ListSubmissionsInput
+    tg: Any = None
+
+    def _run(self, task_id: str) -> str:
+        return json.dumps(self.tg.tasks.list_submissions(task_id), indent=2)
+
+
+class ReviewSubmissionTool(BaseTool):
+    name: str = "touchgrass_review_submission"
+    description: str = (
+        "Approve or reject a submission. Approval releases payment from escrow to the worker. "
+        "Auto-approved after 72 hours if not reviewed."
+    )
+    args_schema: Type[BaseModel] = ReviewSubmissionInput
+    tg: Any = None
+
+    def _run(
+        self,
+        submission_id: str,
+        approved: bool,
+        comment: Optional[str] = None,
+        payout_tx_hash: Optional[str] = None,
+    ) -> str:
+        if approved:
+            if not payout_tx_hash:
+                return json.dumps({"error": "payout_tx_hash required for approval"})
+            result = self.tg.tasks.approve_submission(
+                submission_id, payout_tx_hash=payout_tx_hash, comment=comment
+            )
+        else:
+            result = self.tg.tasks.reject_submission(submission_id, comment=comment)
+        return json.dumps(result, indent=2)
+
+
+class SendMessageTool(BaseTool):
+    name: str = "touchgrass_send_message"
+    description: str = "Send a message to a worker in a task's chat thread."
+    args_schema: Type[BaseModel] = SendMessageInput
+    tg: Any = None
+
+    def _run(self, task_id: str, content: str) -> str:
+        return json.dumps(self.tg.tasks.send_message(task_id, content), indent=2)
+
+
+class PlatformStatsTool(BaseTool):
+    name: str = "touchgrass_platform_stats"
+    description: str = (
+        "Get TouchGrass platform statistics: total verified users, active tasks, "
+        "completed tasks, and total USD paid out."
+    )
+    args_schema: Type[BaseModel] = EmptyInput
+    tg: Any = None
+
+    def _run(self) -> str:
+        return json.dumps(self.tg.stats(), indent=2)
+
+
+# -- Toolkit --------------------------------------------------------------
+
+
+class TouchGrassToolkit:
+    """LangChain toolkit for TouchGrass.
+
+    Usage::
+
+        from touchgrass.langchain import TouchGrassToolkit
+
+        toolkit = TouchGrassToolkit(api_key="hp_...")
+        tools = toolkit.get_tools()
+
+        # Use with any LangChain agent
+        from langchain.agents import AgentExecutor
+        agent = AgentExecutor(agent=..., tools=tools)
+    """
+
+    def __init__(self, api_key: str, base_url: str = "https://touch-grass.world/api"):
+        self.tg = TouchGrass(api_key=api_key, base_url=base_url)
+
+    def get_tools(self) -> list[BaseTool]:
+        """Return all TouchGrass tools for use in a LangChain agent."""
+        tool_classes = [
+            SearchTasksTool,
+            GetTaskTool,
+            CreateTaskTool,
+            ListApplicationsTool,
+            AcceptApplicationTool,
+            ListSubmissionsTool,
+            ReviewSubmissionTool,
+            SendMessageTool,
+            PlatformStatsTool,
+        ]
+        return [cls(tg=self.tg) for cls in tool_classes]

touchgrass_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+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)

touchgrass_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+touchgrass/__init__.py,sha256=iVSMBZ6nLhgTT8YS3x7SzZJyszgzEeBvNrtW49VcRRo,314
+touchgrass/client.py,sha256=e2es79DqIKmE5kXnrwKwYF5DycRzNdrAoNTqAdEAXgk,11819
+touchgrass/exceptions.py,sha256=yD1s9ekvDpx5Y336WNhyaIowisluPTTETFc4_JJleEs,888
+touchgrass/langchain.py,sha256=VOPgEG742prMOgjFtLf7ENHzOkxOkhLS74zVhREvOiw,8033
+touchgrass_sdk-0.1.0.dist-info/METADATA,sha256=ai4A-2QMZ9eW2rixvj9Du_Yo80muULOrqTio1EsTWco,7975
+touchgrass_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+touchgrass_sdk-0.1.0.dist-info/RECORD,,

touchgrass_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any