Skip to content
Try Hanzo
Language: English (United States)

How toUse Kai

Hanzo decision model · 0 output tokens

Send a state and typed questions to POST /v1/decisions with model: "kai". Kai answers each question with a probability for every answer it allows, and writes no text.

Models Kai Guide

POST /v1/decisions0 output tokens
churn_risknoul

Is this account at risk of churning?

state Customer email: Cancel my plan immediately. Your service was down during our product launch.
kai
"answers": {
  "churn_risk": { "noul": — }
},
"usage": { "output_tokens": 0 }

Get noul: P(true). kai-1.3, the default, does not read a noul’s criteria.

urgencyscore

Rate ticket urgency

lownormalhighcriticalstate Customer email: Cancel my plan immediately. Your service was down during our product launch.
kai
"answers": {
  "urgency": {
    "score": —,
    "legend": —,
    "probabilities": —
  }
},
"usage": { "output_tokens": 0 }

Get score (the expected level index), legend, probabilities by level index.

departmentchoice

Route ticket to appropriate team

executive_escalationssupportbillingstate Customer email: Cancel my plan immediately. Your service was down during our product launch.
kai
"answers": {
  "department": {
    "choice": —,
    "probabilities": —,
    "confidence": —
  }
},
"usage": { "output_tokens": 0 }

Get choice, probabilities (one per option, summing to 1), confidence.

Three question types

Questions

Name each question; its answer comes back under the same name.

  1. choice

    Send criteria: option → description, or a list of options.

    Get choice, probabilities (one per option, summing to 1), confidence.

  2. score

    Send criteria: the levels, lowest first.

    Get score (the expected level index), legend, probabilities by level index.

  3. noul

    Send instructions: a yes/no question.

    Get noul: P(true). kai-1.3, the default, does not read a noul’s criteria.

One request, three questions

Call it

Every response also carries id, model, usage (output_tokens is 0), routing (the checkpoint that answered: kai-1.3 for the model id kai), state_hash and latency_ms.

pip install hanzoai
# pip install hanzoai
import os
 
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi
from hanzoai.cloud.models.ai_decisions_request import AiDecisionsRequest
 
ai = AiApi(ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])))
decision = ai.post_decisions(AiDecisionsRequest.from_dict({
    "model": "kai",
    "state": {"ticket_id": 4821, "text": "Can I get an extension on my payment due date?"},
    "questions": {
        "team": {
            "type": "choice",
            "instructions": "Which team handles this?",
            "criteria": {"billing": "invoices and payments", "support": "technical issues"},
        },
        "is_churn_risk": {"type": "noul", "instructions": "Is the user churning?"},
    },
}))
 
print(decision.answers["team"].choice, decision.answers["team"].probabilities)
print(decision.answers["is_churn_risk"].noul)

On the frozen harness, kai-1.4 averaged 84.4% accuracy against Jev’s 76.6% across the 11 suites it leads, both models on the same questions. The runs →

What a request may hold

Limits

The model id kai answers from kai-1.3, the default. Ask for kai-1.4 by id for the unified version: one encoder and one head, trained on long states. Ask for kai-1.5 by id for the agentic preview: whether a tool fits a request, and whether to call one at all.
Up to 100 a request; 101 is refused with 422.
kai-1.3, the default, was trained on 1,024 tokens of state beside each question. Up to 32,768 is answered with routing.extrapolated: true and is unreliable: a fact at the end of a 3,982-token state read 0.507. kai-1.4 was trained on long states and marks no read up to 32,768 extrapolated. Past 32,768 the answer is 422 state_too_long.
One yes/no question takes <1 ms of server time at p50 in production on GPU (0.27 ms cached in process). Every response reports its own latency_ms.
$0.021 per million input tokens; output is free. Jev costs $0.042.
POST /v1/decisions
Questions
kai-1.3
routing.extrapolated: true

kai-1.3, the default, was trained on 1,024 tokens of state beside each question.

Price$0.021per million input tokens; output is free. Jev costs $0.042.

Composable Decision Recipes

Recipes & Blueprints

Modular Rust structs and TypeScript workflows that sit inside your pipelines: retail triage, industrial diagnostics, confidence routing, and agent loops.

recipes::retail

Shelf inventory triage, return fraud checks, and corporate pricing safety guardrails.

Change the URL, the key and the model

Coming from Jev

Kai takes the request body Jev takes. The same endpoint also serves typesafe/jev-1.13 with a Hanzo key, at Jev’s price.

# Jev on OpenRouter
# Kai on Hanzo: the same body
curl https://openrouter.ai/api/alpha/decisions \
curl https://api.hanzo.ai/v1/decisions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "typesafe/jev-1.13", "state": "…", "questions": {…}}'
  -d '{"model": "kai", "state": "…", "questions": {…}}'

What differs: Kai answers at most 100 questions a request, refuses a state past 32,768 tokens with 422, and kai-1.3, the default, ignores a noul’s criteria. OpenAI’s Decisions body (input and a list of questions) is refused.

Kai answers each question with a probability for every answer it allows, and writes no text.