Quickstart

Get a Khwan brain running around your own model in a few minutes.

Install


pip install khwan

The Python client is a thin HTTP wrapper — no engine code, no heavy dependencies. It talks to the hosted Khwan API at https://api.khwan.ai.

Get an API key

Create an account and open your Khwan dashboard.

Create an API key

Generate a key — it looks like kwk_live_xxxxxxxx. Keep it secret; treat it like a password.

Pick an end-user id

Choose a stable user_id for each of your end users (for example their internal account id). It identifies the user on each request; it does not give each user a separate brain. To isolate brains, use cores.

Your Khwan API key (kwk_...) authenticates you to Khwan. It is not your model provider’s key. Khwan never sees your Anthropic / OpenAI key in the BYOM flow.

The three-step loop

Khwan’s core is a prepare → your model → record loop:


from khwan import Khwan
import anthropic
 
# 1. Connect. `user_id` identifies the end user on each request.
kw = Khwan(api_key="kwk_live_xxx", user_id="alice")
 
# Your own model + your own key — Khwan never sees this.
llm = anthropic.Anthropic(api_key="sk-ant-...")
 
def my_own_llm(messages):
    # messages is a standard [{role, content}] array from Khwan.
    system = next((m["content"] for m in messages if m["role"] == "system"), "")
    chat   = [m for m in messages if m["role"] != "system"]
    r = llm.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system=system,
        messages=chat,
    )
    return r.content[0].text
 
# --- the loop ---
 
# STEP 1: prepare — Khwan builds the brief (memory + constitution + coherence). No LLM.
turn = kw.prepare("remember I prefer short answers in Thai")
 
# Optional: Khwan can gate a turn (e.g. a constitutional violation).
if not turn.allowed:
    print("blocked:", turn.reason)
else:
    # STEP 2: call YOUR model with the prepared messages.
    answer = my_own_llm(turn.messages)
 
    # STEP 3: record — hand the answer back so Khwan persists + learns.
    kw.record(turn, answer)
 
    print(answer)

That’s the entire integration. Run it again with a follow-up input and Khwan will already remember the preference it just learned.

Next turn: memory in action


turn   = kw.prepare("what did I ask you to remember?")
answer = my_own_llm(turn.messages)   # the system prompt now carries the Thai preference
kw.record(turn, answer)

Isolate a core (optional)

A core is a fully isolated brain — its own memory, identity, and learning. Point a client at one with core; omit it for the account’s default core. Quota stays pooled at the account level.


client1 = Khwan(api_key="kwk_live_xxx", user_id="alice", core="client1")

The client sends this as the X-Khwan-Core header. Two clients on different cores never share memory. Create and manage cores in the dashboard or via the API.

Point at another instance (on-prem)

Same code, different base URL:


kw = Khwan(
    api_key="kwk_...",
    user_id="alice",
    base_url="https://khwan.internal.acme.com",
)

Where to go next

Bring Your Own Model — turn.messages in depth, plus OpenAI and Ollama examples.
API Reference — the underlying REST endpoints.