Metadata-Version: 2.4
Name: lassare
Version: 0.3.0
Summary: Python SDK for the Lassare Gateway
Home-page: https://github.com/lassare-hq/sdk-python
Author: Lassare
Author-email: support@lassare.com
Project-URL: Documentation, https://docs.lassare.com/sdks/python
Project-URL: Bug Tracker, https://github.com/lassare-hq/feedback/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Lassare Python SDK

A Python client library for the Lassare Gateway.

**The SDK is designed to BLOCK agent execution until a human decision is made.**
This is the core purpose of Lassare - forcing agents to stop and wait for approval.

## Installation

```bash
pip install lassare
```

## Quick Start

```python
from lassare import LassareClient, PauseRequest, RequestStatus

# Initialize client with API key
client = LassareClient(api_key="lsk_prod_xxx...")

# Use as context manager for automatic connect/disconnect
with client:
    # This call BLOCKS until a human approves, rejects, or the request expires
    decision = client.pause_for_human(
        PauseRequest(
            project_id="proj_abc123",
            policy_id="pol_xyz789",
            payload={"amount": 50000, "destination": "new_account"},
            title="Approve large transaction",
            description="User requested withdrawal of $50,000 to new account",
        )
    )

    # Code only reaches here AFTER human decision
    if decision.status == RequestStatus.APPROVED:
        print(f"Approved by {decision.decided_by}")
        execute_transaction()
    elif decision.status == RequestStatus.REJECTED:
        print(f"Rejected: {decision.comment}")
        cancel_transaction()
    else:  # EXPIRED
        print("Request expired without decision")
        handle_timeout()
```

## Blocking Behavior

The `pause_for_human()` method **blocks** via WebSocket until a decision is made. This ensures your agent cannot proceed without human approval.

### With Timeout

```python
from lassare import DecisionTimeoutError

try:
    # Block for max 5 minutes (300 seconds)
    decision = client.pause_for_human(request, timeout=300)
except DecisionTimeoutError as e:
    print(f"No decision after {e.timeout_seconds}s")
```

### Non-Blocking

For cases where you need to create a request and return immediately:

```python
# Creates request and returns immediately (does not wait for decision)
response = client.create_approval_request(
    PauseRequest(
        project_id="proj_abc123",
        policy_id="pol_xyz789",
        payload={"amount": 50000},
        title="Approve transaction",
    )
)
print(f"Created request: {response.request_id}")
# Check status later with get_request_status() or use callbacks
```

## Policy-Based Routing

Use `policy_id` to route approval requests through policies configured in the Lassare Portal:

```python
decision = client.pause_for_human(
    PauseRequest(
        project_id="proj_abc123",
        policy_id="pol_default",  # Configured in Portal
        payload={"amount": 50000, "customer_id": "cust_123"},
        title="High-value transaction",
    )
)
```

Policies define:
- Which approvers receive notifications
- Notification channels (email, Slack, Microsoft Teams, webhooks)
- Urgency levels and escalation rules

## API Reference

### LassareClient

#### Constructor

```python
LassareClient(
    api_key="lsk_prod_xxx...",
    ws_url="wss://ws.lassare.com",  # optional, defaults to production
)
```

#### Methods

- `pause_for_human(request, timeout=3600)` - **BLOCKS** until decision
- `create_approval_request(request)` - Creates request, returns immediately
- `get_request_status(request_id)` - Get current status of a request
- `cancel_request(request_id)` - Cancel a pending request
- `connect()` / `disconnect()` - Manual connection management (or use `with` statement)

### Types

- `PauseRequest` - Request with `project_id`, `policy_id`, `payload`, `title`, etc.
- `DecisionResponse` - Response with `status`, `decided_by`, `comment`, `request_id`
- `RequestStatus` - Enum: `PENDING`, `APPROVED`, `REJECTED`, `EXPIRED`
- `Urgency` - Enum: `CRITICAL`, `STANDARD`, `EXTENDED`

## Documentation

For full documentation, visit [https://docs.lassare.com/sdks/python](https://docs.lassare.com/sdks/python)

## License

MIT
