Metadata-Version: 2.5
Name: kohala
Version: 0.3.3
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
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
import os

from kohala import Kohala

# Read the key from the environment — never hardcode or commit a pk_ key.
kohala = Kohala(api_key=os.environ["KOHALA_API_KEY"])

# 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=os.environ["KOHALA_API_KEY"],  # required — keep it out of source control
    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`.
- `kohala.users` — `create(email, password, tier="personal", team_name=None)` (`POST /api/v1/users`): programmatically create a personal- or business-tier account. Requires the superuser-granted "Can create users" flag on the key's account (ungranted callers get 403). Created accounts are born verified — no verification email — and can log in immediately. Business tier requires `team_name` and creates a new team with the user as its first member; Circle tier is invitation-only and not creatable.

  ```python
  created = kohala.users.create(
      email="new.hire@example.com",
      password="s3cure-pass",
      tier="business",
      team_name="Acme Coffee Co.",
  )
  ```

For anything else on the documented `/api/v1` surface,
`kohala.request(method, path, query=..., body=...)` calls the endpoint
directly with the same `pk_` key. Note the key's scope: it authenticates the
management API only — session-only account surfaces (profile, billing
settings, key management) are not reachable with a `pk_` key and stay in the
workspace UI.

## Mobile & Lani chat API

This client covers the `pk_`-key `/api/v1` surface. The cookie-free **Mobile
API** (`mk_` bearer tokens) — Lani chat, including document & image
attachments with server-side content extraction (`POST
/api/lani-meta/attachments`, `attachmentIds` on message sends (JSON wire names are camelCase), per-message
`attachments` arrays, and auth-gated downloads) — is a plain REST surface
authenticated per device, so call it with any HTTP client. Full reference:
[kohala.ai/platform/api](https://kohala.ai/platform/api).

## 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
