Metadata-Version: 2.4
Name: aegis-idempotency
Version: 0.1.0
Summary: HTTP client for the AEGIS HITL Reliability Layer — exactly-once human-in-the-loop approvals for AI agents
Author-email: Cristian Amigo <cstamigo@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/cstamigo/aegis-hitl
Project-URL: Bug Tracker, https://github.com/cstamigo/aegis-hitl/issues
Keywords: hitl,idempotency,reliability,agents,ai
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Dynamic: license-file

# aegis-idempotency

> **Note:** The final distribution name on PyPI will be confirmed before publishing.
> The package import name is `aegis_hitl` regardless of the distribution name.

HTTP client for the [AEGIS HITL Reliability Layer](https://github.com/cstamigo/aegis-idempotency) —
exactly-once human-in-the-loop approvals for AI agents.

## Installation

```bash
pip install aegis-idempotency
```

## Quick Start

```python
import asyncio
from aegis_hitl import AegisClient

async def main():
    async with AegisClient(
        base_url="http://localhost:8000",
        tenant_id="my-tenant",
        thread_id="my-thread",
    ) as client:
        # Approve a pending agent action
        response = await client.approve("idempotency-key-001")
        print(response.status_code)  # 202

asyncio.run(main())
```

## API Reference

### `AegisClient(base_url, *, tenant_id, thread_id, timeout, client)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `base_url` | `str` | `"http://localhost:8000"` | AEGIS server URL |
| `tenant_id` | `str \| None` | `None` | Default tenant; override per call |
| `thread_id` | `str \| None` | `None` | Default thread; override per call |
| `timeout` | `float` | `10.0` | Request timeout in seconds |
| `client` | `httpx.AsyncClient \| None` | `None` | Inject an existing httpx client |

Must be used as an async context manager (`async with`).

### Methods

| Method | Endpoint | Description |
|--------|----------|-------------|
| `approve(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/approve` | Approve a pending action |
| `reject(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/reject` | Reject a pending action |
| `execute(action, idempotency_key, ...)` | `POST /hitl/{action}` | Generic approve/reject dispatcher |
| `get_status(request_id)` | `GET /hitl/status/{id}` | Query action status |

### Response Status Codes

| Code | Meaning |
|------|---------|
| `202` | Action processed successfully |
| `409` | Duplicate request (idempotency key already used) |
| `500` | Internal server error |

## Publishing

To publish to PyPI (when ready):

```bash
python -m build
twine check dist/*
twine upload dist/*  # requires PyPI account and token
```

> Warning: Confirm the distribution name availability on PyPI before uploading.
