kohala

Official Python client for the Kohala 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

pip install kohala

Requires Python 3.8+.

Quick start

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

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.

  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.

Errors

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

from kohala import KohalaError

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

License

MIT