Metadata-Version: 2.4
Name: kave-sdk
Version: 0.1.0
Summary: Kave Python SDK - control plane for AI agents
Requires-Python: >=3.11
Requires-Dist: grpcio>=1.80.0
Requires-Dist: protobuf>=6.30.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=4.2; extra == 'django'
Requires-Dist: djangorestframework>=3.14; extra == 'django'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
Description-Content-Type: text/markdown

# Kave Python SDK

Install:

```bash
uv add kave-sdk
pip install kave-sdk
```

Quickstart:

```python
from kave import SyncClient
from kave.control.v1 import control_pb2

with SyncClient("localhost:19090", token="kv_...") as kave:
    org = kave.ensure_organization(control_pb2.CreateOrganizationRequest(name="Acme", slug="acme"))
    print(org.id)
```

## Auth

Pass `token="..."` to add `Authorization: Bearer ...` on every RPC. Direct proto
RPCs are reachable through `client.control`, `client.runtime`, and `client.audit`.

## TLS

Use `SyncClient(addr="api.example.com:443", tls=True)` for system-root TLS, or
pass custom `grpc.ChannelCredentials` with `credentials=...`.

## Retry

Idempotent `List*`, `Get*`, and `Watch*` RPCs retry 3 times by default: 200 ms
base, 2x exponential backoff, +/-20% jitter, 5 s cap. Mutating RPCs do not retry.
Use `retry=NO_RETRY` or pass a `RetryPolicy` to customize.

## Async

```python
from kave import AsyncClient

async with AsyncClient("localhost:19090") as kave:
    async for agent in kave.aiter_agents(env_id):
        print(agent.name)
```

## Errors

SDK calls wrap gRPC failures in `KaveError`. Use predicates such as
`is_not_found(err)`, `is_permission_denied(err)`, and `is_unavailable(err)`.

## Django

Install `kave-sdk[django]`, add `kave.contrib.django` to `INSTALLED_APPS`, define
`KAVE = {...}`, and run `python manage.py kave_reconcile` on deploy.

See `examples/` and `../CONTRACT.md` for the full parity contract.
