KKmatch/KKOS AI/SDK
Developer SDK

Two files, three calls, one 11-dimension model.

A zero-dependency Web client and a standard-library-only Python client. No package to install, no build step, no vendor lock-in — just HTTP.

Quickstart

Run a session and get a model.

Both clients do the same three things: open a session, send turns, complete the session to build the model. The engine keeps the session server-side, so a turn is one small JSON POST.

Python · stdlib only
# pip install nothing
from kkos_client import KKOS

kk = KKOS(api_key="kk_live_...", token="<user token>")

model = kk.run_text_session([
    "I usually decide fast and say what I think.",
    "When someone hesitates, I push them to decide.",
    "I would rather hear a direct answer.",
])

for t in model["traits"]:
    print(t["name"], t["score"], t["confidence"])
Web · no build step
<script src="/sdk/kkos.js"></script>
<script>
  const kk = new KKOS({ token: userToken });

  const model = await kk.runTextSession([
    "I usually decide fast and say what I think.",
    "When someone hesitates, I push them to decide.",
    "I would rather hear a direct answer.",
  ]);

  kk.traits(model).forEach(t =>
    console.log(t.name, t.score, t.confidence));
</script>
Why the model is not at the top level. /mirror/complete returns {session_id, model_id, redirect, model} — the model sits under model. Call completeModel() to get it unwrapped, or traits(resp) to normalise the dimension list out of either shape.
Sessions require a user token. /mirror/start, /mirror/message and /mirror/complete are login-gated and need Authorization: Bearer <uid.ts.sig>. A platform API key on its own is enough for /health, /plans and /mirror/voices, but a session attempt with only a key returns 401 login_required. This is deliberate: a model is personal data, so it is never built for an anonymous caller.
Files

Four files, no dependencies.

kkos.jsBrowser client. UMD: works as a plain <script> or an ES module import. 1 file, 0 packages.
kkos_client.pyPython client. urllib only — drops into any Python 3.8+ project without touching requirements.
example.pyRunnable Python example: full session, printed model, automatic cleanup. python example.py
example-web.htmlRunnable browser example: paste a token, type three lines, see the model render. No build step.
Both examples are the same three calls. If you are wiring KKOS into a service, start from example.py; if you are wiring it into a product UI, start from example-web.html.
Reference

Every endpoint the SDK wraps.

All paths are relative to the base URL. The full OpenAPI schema is served at /openapi.json and rendered at /docs.html.

Method Path Client method Credential
GET/healthhealth()public
GET/api/v1/plansplans()public
GET/api/v1/mirror/voicesvoices()API key
POST/api/v1/mirror/startstart()user token
POST/api/v1/mirror/messagemessage()user token
POST/api/v1/mirror/completecomplete() · completeModel()user token
GET/api/v1/mirror/model/{id}get_model()API key
DELETE/api/v1/mirror/model/{id}delete_model()API key
POST/api/v1/mirror/model/{id}/regenerateregenerate_model()API key
POST/api/v1/mirror/comparecompare()API key
POST/api/v1/mirror/ttstts() · tts_to_file() · speak()API key
POST/api/v1/mirror/sttstt()API key
POST/api/v1/life-stageAPI key
GET/api/v1/auth/meme()user token
Errors are typed. Any non-2xx response raises KKOSError with status, payload, url and method, so you can branch on 401 (re-authenticate) versus 429 (back off) versus 5xx (retry) instead of parsing strings.
Verified run

What the example actually returns.

The block below is not illustrative — it is the response from an actual run on 2026-09-12, with three user turns taken verbatim from example.py. Desensitised: no session identifier, no user identifier.

Session: 3 user turns, text mode · overall_confidence 0.60 · model_version hm-v1 · 11/11 dimensions returned

Dimension Score Confidence Evidence returned by the engine
directness950.95“I usually decide fast and say what I think, even if it is blunt.”
communication_style900.90“I usually decide fast and say what I think, even if it is blunt.”
decision_style900.90“I usually decide fast”
uncertainty_response850.80“When someone around me hesitates, I tend to push them toward a decision.”
ai_interaction_style800.70Repeated direct-answer preference when interacting with AI.
conflict_style700.60“say what I think, even if it is blunt.”
engagement700.50Responded consistently to questions from the assistant.
trust_disclosure_pattern600.50Shared personal preferences quickly in conversation.
openness500.40They openly stated their preference for bluntness.
emotional_expression450.50The word “honestly” conveys sincerity but not emotion.
reflection_style250.50Statements are brief and conclusive rather than exploratory.

Summary returned: “The user strongly values directness and quick decisions, prefers blunt honesty over politeness, and tends to push others toward closure. Their communication is terse and conclusive…”

Cost of that run: 2 182 input tokens / 3 818 output tokens over 4 LLM calls, estimated $0.00262.

Run it twice and you will not get the same numbers. A repeat-modelling probe found a mean per-dimension standard deviation of 13.33 points, and 40% of models in our store return an explicit insufficient data reading instead of a score. Both findings are published, with the data files and the commands to reproduce them, in Effect Reports. Treat one dimension from one run as a sample, not a verdict.
Shape of one model

Eleven dimensions, drawn

Read off the same run the table above reports — an unedited transcript, not an illustration. The silhouette is what the engine returned; the numbers are in the table.

11 / 11 dimensions returned score range 25 – 95
95 highest — directness
25 lowest — reflection_style
confidence per dimension 0.40 is the floor the engine uses for “insufficient data”
0.60 overall_confidence
0.95 highest single dimension

Source: the verified run above — three turns, text mode, 2026-09-12, model_version hm-v1. Left radar: the eleven scores. Right bars: the confidence the engine attached to each of them. One run is a sample, not a verdict — the repeatability measurement is in the Effect Reports.

Scope

What the SDK deliberately does not do.

  • No realtime transport wrapper. The full-duplex voice channel is a WebSocket at /api/v1/mirror/evi. Both SDKs leave it to you rather than shipping a socket abstraction — see the docs page for the session-settings handshake.
  • No retries, no backoff, no caching. A turn is one POST; retry policy belongs to the caller, not to a 200-line client.
  • No key storage. Neither client persists credentials. The browser example keeps them in localStorage only because it is a demo — do not ship that pattern in production.
  • No accuracy claim. The SDK transports scores and confidences. Whether a score is correct is a separate and still-open question — see the Effect Reports.