Metadata-Version: 2.4
Name: kohala
Version: 0.1.0
Summary: Official Python client for the Kohala API — build, govern, run, and monetize AI agents.
Project-URL: Homepage, https://kohala.ai
Project-URL: Documentation, https://kohala.ai/developers
Project-URL: Source, https://github.com/kohala-ai/kohala
Author: Kohala
License: MIT
License-File: LICENSE
Keywords: agents,ai,governance,kohala,llm,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# kohala

Official Python client for the [Kohala](https://kohala.ai) API — build, govern,
run, and monetize AI agents. Zero third-party dependencies (standard library
only). Every call is metered server-side; the client adds no tracking.

## Install

```bash
pip install kohala
```

Requires Python 3.8+.

## Quick start

```python
from kohala import Kohala

kohala = Kohala(api_key="pk_...")  # a pk_ key from your Developer tab

# List your agents
agents = kohala.agents.list()

# Create one
agent = kohala.agents.create(
    name="Weekly digest",
    charter="Summarize this week's activity and publish a Koan.",
    industry="software",
    enabled=True,
)

# Trigger a run now (returns as soon as it's queued)
kohala.runs.trigger(agent["id"])

# Read run history
runs = kohala.runs.list(agent["id"], limit=10)

# Build a Koan embed URL for an iframe
src = kohala.koans.embed_url("my-koan-slug", view="detail")
```

## Configuration

```python
Kohala(
    api_key="pk_...",              # required
    base_url="https://kohala.ai",  # optional (default)
    timeout=30.0,                  # optional (seconds)
)
```

## Resources

- `kohala.agents` — CRUD plus `health`, `get_quota`/`set_quota`, skills, koans, reports, deployments.
- `kohala.runs` — `list`, `get`, `trigger`, `retry`.
- `kohala.workflows` — `list`, `get`, `create`, `update`, `delete`, `list_runs`, `run`, `get_run`.
- `kohala.koans` — `get`, `embed_url`.

For anything else, `kohala.request(method, path, query=..., body=...)` calls any
endpoint directly.

## Errors

Non-2xx responses raise `KohalaError` with `.status`, `.code`, `.details`, and
`.request_id`:

```python
from kohala import KohalaError

try:
    kohala.agents.get(999)
except KohalaError as err:
    if err.status == 404:
        ...  # handle not found
```

## License

MIT
