Metadata-Version: 2.4
Name: humanlatch
Version: 0.1.0
Summary: Python SDK for proposing AI-driven actions to a HumanLatch control plane.
Author: VerdictLayer
License: MIT
Project-URL: Homepage, https://humanlatch.verdictlayer.com
Project-URL: Documentation, https://humanlatch.verdictlayer.com/developers
Project-URL: Repository, https://github.com/verdictlayer/humanlatch
Project-URL: Issues, https://github.com/verdictlayer/humanlatch/issues
Keywords: ai,approval,policy,human-in-the-loop,agent,automation
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
Description-Content-Type: text/markdown

# HumanLatch Python SDK

Python SDK for sending AI-driven capability proposals to a HumanLatch control plane.

Use this SDK when your agent, service, robot controller, or automation needs to ask:

- Can I run this action automatically?
- Do I need a human approval first?
- Is this blocked by policy?

The SDK works against either:

- self-hosted HumanLatch CE
- a remotely hosted HumanLatch API

## Install

```bash
pip install humanlatch
```

## Create a Client

```python
from humanlatch import HumanLatchClient

client = HumanLatchClient(
    base_url="https://your-humanlatch.example.com",
    workspace_id="your-workspace-id",
    api_key="hl_your_key_here",
)
```

Use `token` for user-authenticated flows or `api_key` for agent/service integrations.

## Core Flow

```python
from humanlatch import HumanLatchClient

client = HumanLatchClient(
    base_url="https://your-humanlatch.example.com",
    workspace_id="your-workspace-id",
    api_key="hl_your_key_here",
)

result = client.propose_action(
    action_type="support.refund.issue",
    target="order-10428",
    summary="Issue a refund above the autonomous threshold",
    payload={
        "amount": 850,
        "currency": "USD",
        "customer_id": "cust_2041",
    },
    context={
        "environment": "production",
        "requested_by": "agent:support-bot",
        "domain": "chatbot",
    },
)

if client.is_approved(result):
    issue_refund()
elif client.requires_approval(result):
    final = client.wait_for_decision(result["id"], interval_seconds=2.0, timeout_seconds=30.0)
    if client.is_approved(final):
        issue_refund()
else:
    raise RuntimeError(f"Blocked by HumanLatch policy: {result['status']}")
```

## Additional Methods

```python
client.list_actions(status="pending_approval", limit=50)
client.get_action("action-id")
client.approve_action("action-id", note="Approved by supervisor")
client.reject_action("action-id", note="Unsafe during shift handoff")
client.cancel_action("action-id")
```

## Integration Model

Before your system performs a sensitive capability, it asks HumanLatch for a decision:

- `approved_auto`: execute now
- `pending_approval`: wait for human approval
- `blocked`: do not execute

That same control plane works for:

- infrastructure agents
- support bots
- warehouse robots
- manufacturing lines
- internal copilots
