Metadata-Version: 2.4
Name: kaplaix
Version: 0.1.0
Summary: Python SDK for Kaplaix AI agent governance platform
Project-URL: Homepage, https://kaplaix.com
Project-URL: Documentation, https://docs.kaplaix.com
Author-email: Naoufal Fahem <fahem.naoufal@gmail.com>
License: MIT
Keywords: agents,ai,governance,kaplaix,llm,observability
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# kaplaix — Python SDK

Python SDK for instrumenting AI agents with [Kaplaix](https://kaplaix.io).

## Requirements

- Python >= 3.10
- `httpx` (installed automatically)

## Installation

```bash
pip install kaplaix
```

## Quick start

```python
from kaplaix import KaplaixClient

client = KaplaixClient(api_key="al_live_...")

with client.session(agent_id="my-agent") as session:
    session.log_tool_call("web_search", "sha256-of-args", response_status=200)
```

## Client options

| Parameter | Type | Default | Description |
|---|---|---|---|
| `api_key` | `str` | required | Tenant API key (`al_live_...`) |
| `base_url` | `str` | `https://api.kaplaix.io` | API base URL |
| `timeout_ms` | `float` | `10000` | Request timeout in milliseconds |
| `retries` | `int` | `3` | Retry attempts on transient errors (429, 502, 503, 504) |
| `metadata` | `SdkMetadata` | — | Optional environment metadata |

## Session

```python
session = client.session(
    agent_id="my-agent",
    session_id="optional-custom-id",  # any non-empty string; UUID generated if absent
)
```

Use as a context manager (calls `end()` automatically) or manage lifecycle explicitly.

## Event helpers

### Tool call

```python
session.log_tool_call(
    tool_name="database_query",
    arguments_hash="sha256-hex",   # hash of args — never log raw args
    response_status=200,           # optional HTTP status
    endpoint="/api/query",         # optional
)
```

### Data movement

```python
session.log_data_movement(
    operation="export",            # "read" | "write" | "delete" | "export"
    object_ids=["record-001"],
    diff_summary="Exported 1 record",  # optional
)
```

### Approval

```python
session.log_approval(
    approver_id="user-42",
    scope="delete:crm:customers:bulk",
    decision="rejected",           # "approved" | "rejected"
)
```

### Environment

```python
session.log_environment(
    is_sandbox=False,
    network_segment="prod-vpc",
    workspace="production-cluster",
)
```

### Raw event

```python
session.log_event(
    category="reasoning",
    payload={"summary": "Decided to proceed with deletion"},
)
```

## Retry behavior

The SDK retries on HTTP 429, 502, 503, and 504 using exponential backoff with full jitter. Non-retryable errors (4xx) are raised immediately.

## Error handling

```python
from kaplaix import KaplaixError, KaplaixNetworkError, KaplaixTimeoutError

try:
    session.log_tool_call("tool", "hash")
except KaplaixError as e:
    print(f"API error {e.status_code}: {e.body}")
except KaplaixTimeoutError:
    print("Request timed out")
except KaplaixNetworkError as e:
    print(f"Network error: {e.__cause__}")
```
