--- hip: 1332 title: Kai — The Decision Model and the Decision Plane author: Hanzo AI type: Standards Track category: Core capability: decisions status: Draft implementation-rust: partial created: 2026-09-25 requires: HIP-0004, HIP-0010, HIP-0043, HIP-0106, HIP-0113, HIP-0124, HIP-1190, HIP-1220, HIP-1322, HIP-1330 --- # HIP-1332: Kai — The Decision Model and the Decision Plane ## Abstract Kai is Hanzo's decision model. It turns heterogeneous evidence into calibrated, typed, mutually consistent decisions, many at once. It does not generate text, and it holds no authority: deterministic policy, solvers and humans do. Decision inference is a primitive beside generation, retrieval, forecasting, perception, solving and policy: ```text Zen generates: open reasoning, code, language Kai decides: bounded judgment, decision state Enso routes: each operation to Kai or Zen (HIP-0510) Embed retrieves TS forecasts Vision perceives Audio hears Graph structures Solver proves Policy governs ``` Hanzo Decision composes them into versioned Decision Programs, served at `POST /v1/decisions`. Kai's native output is Decision Program state, not prose: ```text evidence → adapters → shared evidence → program graph → parallel Kai inference → freeze confident nodes, refine the rest → constraints + policy → human → Decision Package ``` Inside Enso, Kai is the in-process controller for model, context, tools, reasoning budget, stopping and escalation. ## Motivation Generative models are asked two kinds of question. Open ones: reason, write, explain, plan. Bounded ones: which model, which tool, which file, is the evidence sufficient, how severe, did the last step make progress, which option meets the constraints, does a human approve. The second kind has a known answer space. Generating prose for it costs tokens, latency and context, needs a parser, and is not reproducible. Hanzo separates decision from generation: Zen stays for open work; Kai takes bounded judgment. ## Specification ### §1 Vocabulary Normative terms. **Hanzo Decision**: the capability and API. **Kai**: the decision model. **Zen**: the generative family. **Enso**: the router family (HIP-0510); it routes each operation to Kai or Zen. **Decision Program**: a versioned, executable description of a decision. **Decision Package**: the reproducible record of one program run. **Evidence**: anything a program may read. **Adapter**: maps one modality into evidence. **Policy**: deterministic authority. **Decision Plane**: the runtime subsystem that evaluates bounded decisions with Kai. Laya and Jev are baselines, not platform vocabulary. ### §2 One Kai There is one model line, `hanzoai/kai`. Language, domain, modality or hardware MUST NOT spawn separate product families (`kai-english`, `kai-agent`, `kai-sensor`, …). New checkpoints, adapters, quantizations and training stages are revisions of the one line; each MUST be identified by an immutable revision or digest, and every Decision Package MUST record it. ### §3 Encoder Kai's text encoder is mmBERT-base, initialized from the Laya multilingual weights: one encoder for every language, 8K positions, smaller than the ModernBERT-large encoder of the English baseline. The served build, kai-1, reads 1,024 tokens of question and state together. Whether it keeps that baseline's English accuracy is an empirical question the harness (§18) MUST answer. ### §4 Evidence Everything a decision reads is Evidence: ```rust Evidence { id, modality, source, time, payload, provenance, uncertainty, metadata } ``` Modalities include text, code, document, image, video, audio, waveform, series, telemetry, point cloud, radar, thermal, geospatial, table, graph, SysML, simulation, tool output, agent trace, human assertion, model output, and `Custom(name)` (e.g. `CAN-J1939`, `MIL-STD-1553`). Evidence MUST keep enough metadata to say what was observed and where it came from; modalities MAY add unit, sample rate, frame, sensor identity, calibration, quality, error bound, language, timing, schema or model revision. #### §4.1 Adapters Each modality reaches the shared evidence space through an adapter. A new source SHOULD need a new adapter, never a new Decision Program API. Evidence is encoded once per changed evidence state. #### §4.2 Sensors Numeric sensor data MUST NOT have to be serialized as prose. An observation SHOULD keep value, unit, channel, time, rate, sensor, frame, uncertainty, calibration, quality and provenance, so 43.2 °C, 43.2 psi and 43.2 mm/s differ and an expired calibration weakens the evidence. The interface MUST extend to sensors nobody listed. #### §4.3 Time Raw series MAY pass through a temporal adapter. Kai SHOULD read temporal state: current value, window, trend, derivative, anomaly score, baseline deviation, forecast, quality. Forecasting is a separate model's job; its forecasts are evidence. #### §4.4 Audio and video Audio MUST carry both speech content and acoustic signal; a transcript alone does not conform where sound is evidence (alarms, machinery, vibration). Video SHOULD reach Kai as events from frames and clips, retrieved before deciding, never as unbounded frame tokens. #### §4.5 Engineering models SysML is evidence. A model SHOULD compile into the engineering knowledge graph or a Decision Program, not be flattened to prose, and a decision MUST trace back to the element ids and model revision it used. ### §5 Decision Programs A program MAY hold objectives, options, constraints, assumptions, risks, bias checks, evidence, provenance, typed variables, dependency edges, deterministic, Kai, Zen, graph, simulation and solver nodes, policy gates, human approvals and refresh rules. The model is part of the program, not the program. ### §6 Typed variables Kai MUST support: **choice** (one of a set; the distribution exposed where practical); **score** (ordinal; modeled as ordered, not as unordered classes); **predicate** (a calibrated boolean); **defer** (abstain: insufficient evidence, out of distribution, conflict, human judgment required). Kai MUST NOT be made to invent certainty. ### §7 Large choice sets Kai MUST NOT depend on packing every option into one shared prompt. Large sets use candidate retrieval, then independent option scoring, then joint refinement where needed; candidate representations MAY be compiled and cached per program version. Targets span 10 to 100,000+ candidates; these are scale targets, not results. kai-1's measured accuracy at 1,000 options and more is near zero (§18). ### §8 Joint decoding Kai SHALL predict many program variables in one execution, from one encoding of the evidence; it MUST NOT need one full encoder pass per variable. With variables `Z = {z_1 … z_n}`, each in its own domain `D_i`, Kai models `p(Z_M | E, Z_¬M, G)`: the masked subset `M` given evidence `E`, the visible variables and the program graph `G`. ### §9 Refinement and dependencies Parallel does not mean committed independently. Kai SHOULD predict all unresolved variables, freeze confident ones, refine uncertain or dependent ones, then project onto constraints. Independent branches resolve in the same wave; a node waits only for its parents, so the number of waves follows graph depth, not variable count. ### §10 Constraints and policy Hard requirements (equations, optimization, SAT/SMT, schemas, physical bounds, business rules, security restrictions) MUST be enforced outside the model. Kai MAY inform a solver and MUST NOT override one. Policy is authoritative: actions join on `ALLOW < ASK < DENY`, so a learned model can tighten a verdict and MUST NOT weaken a deterministic denial. ### §11 Conflict Conflicting evidence is a valid state (telemetry normal, video shows damage; simulation passes, test fails; requirement ≤ 500 kg, model 530 kg). Kai MUST be trained and evaluated on cases whose correct answer is `evidence_conflict = true`, `decision_ready = false`, `human_review = true`. ### §12 Decision Packages A material run MAY produce a Decision Package holding the program and version, result and alternatives, objectives, constraints, assumptions, risks, bias checks, evidence, provenance, source hashes, model and calibration revisions, distributions, solver and policy results, overrides, approvals, sensitivity, flip conditions, trace and a reproduction manifest. The question a package answers is whether the decision can be inspected, replayed, refreshed and reproduced. #### §12.1 What flips the decision The runtime SHALL compute sensitivity itself: vary objectives, constraints, assumptions, evidence, forecasts, risks, cost, schedule or confidence, and report the boundary where the result changes. Zen MAY describe those results and MUST NOT invent them. #### §12.2 Refresh When evidence changes, only affected nodes recompute. A refreshed package keeps the previous and new result, changed evidence, assumptions and constraints, affected nodes, boundaries crossed and new approvals. ### §13 Enso Kai SHALL be native to Enso: `enso.decide("agent.preflight@4", state)` runs in process, with no network hop when co-resident; `/v1/decisions` serves external callers. Kai MAY control model and provider, context and retrieval depth, tools and skills (HIP-1322), reasoning budget, decoding strategy (autoregressive, speculative, parallel draft, block diffusion, verification depth), cache retention, progress, completion, retry, escalation and human approval. Enso routes each operation: a bounded decision goes to Kai; generation, or a decision Kai defers, goes to Zen. #### §13.1 Modes Every program runs `shadow` (Kai decides and logs; behaviour unchanged), `advisory` or `enforced`, set per program. Kai MUST start in shadow. #### §13.2 Minimum sufficient compute Routing supervision SHOULD target the cheapest model that succeeds, not the largest. A cost-aware objective MAY take the form `L = L_failure + λ·C_compute + μ·C_latency` under a quality constraint. Context reduction counts only when downstream quality holds. #### §13.3 Customer programs Organizations MAY define their own programs (typed questions, options, thresholds) and specialize Kai on validated outcomes through adapters, never a full model per tenant. Stable programs SHOULD compile to a plan: question and candidate representations, indexes, graph, thresholds, calibration and policy bindings, reused per request. #### §13.4 Learning Production traffic MUST NOT change weights synchronously. Traces go to a buffer, then offline training, benchmark, shadow, and a controlled promotion; every promoted checkpoint has an immutable version. ### §14 Personalized decisions Recommendation, routing, UI, workflow and notification choices are one primitive: state, evidence, candidates and policy in, a typed decision out. Kai MAY adapt at global, domain, tenant, cohort, session and user scope, layered: base model, domain adapter, tenant adapter, user preference state. Per-user adaptation SHOULD be state and lightweight adapters, not a checkpoint per user. Preference state is probabilistic and revisable: each value keeps its prior, its current estimate and a confidence. #### §14.1 Commerce A catalog compiles to a product graph: category, attributes, variants, price, inventory, compatibility, merchant, signals. Recommendation is a large choice (§7): eligibility and retrieval, Kai ranking, joint refinement. A program such as `commerce.recommend` (intent, price sensitivity, novelty, best product, needs clarification) makes each recommendation inspectable, and its flip conditions computable (§12.1). Zen explains a ranking; it does not produce one. #### §14.2 Outcomes and consent Interactions are graded supervision: a skipped impression is weak, a click or comparison medium, a purchase strong, a purchase kept stronger, a return or refund negative. Counterfactual replay targets the product that served the user best, not the most popular one. Every trace carries source, consent scope, tenant, retention and allowed use, and policy, not model code, decides `may_personalize`, `may_train_tenant` and `may_train_global`. Identifiable per-user behaviour MUST NOT reach global training without that permission. #### §14.3 Autopilot A business runs on bounded decisions followed by generation and execution. Kai decides who, what, when, why and through which channel: enrichment (industry, size, role, interest, intent, budget, urgency, channel, readiness; each typed, scored, deferrable), lead fit and intent, next action, offer, cadence, handoff to a human, stop. Zen writes the message; Enso routes each step; Policy decides whether contact is permitted (consent, opt-outs, caps, quiet hours, jurisdiction, age, suppression, sensitive attributes), so Kai may prefer SMS and policy may still forbid it. Each program (`marketing.*`, `sales.*`, `commerce.*`) owns its outcome metrics (replies, qualified meetings, pipeline, purchases, unsubscribes, cost per qualified lead) and is evaluated counterfactually, then in shadow and A/B, before it acts. Supervision is the action with the best downstream outcome, not the previous model's choice. Programs, modes, thresholds, adapters and data-use policy are configured in Hanzo Cloud, where decisions mounts as an app (HIP-0106), and signals arrive natively from product analytics (HIP-1190), insights and commerce (HIP-1220): no export step between the data and the decision. ### §15 Training Three stages on one checkpoint line: - **A, decisions**: harness train splits, MASSIVE, CLINC150, XNLI, SST-5, large choice sets with hard negatives, order and label perturbations, agent control, coding decisions (file, symbol, test, failure category, continue, done, commit-ready), tool and skill selection. Outcome labels (tests, CI, diffs, accepted edits) are preferred over preferences. - **B, adapters**: the encoder frozen or nearly so; sensors, time series, audio, image, video, graph, SysML, simulation. Public sources (HAR, CWRU, C-MAPSS, MIMII, UCR/UEA, Monash, NASA battery) under their licences. - **C, programs**: whole programs with random and structured masks, dependencies, corrupted visible values, contradictions, missing evidence, `defer`, cross-modal cases. Engineering data MAY be generated: requirements, components, interfaces, parameters, constraints and verification cases, then controlled mutations with exact labels and expected decision changes, compiled to programs. Multilingual training SHOULD target decision invariance across languages (parallel examples, code-switching, low-resource sampling, balanced batches) and MUST report per-language results. Training and evaluation data MUST stay separate; a test set is never trained on. Every build is barriered against every evaluation item: an equal content unit, an instance key, a near duplicate (5-gram Jaccard ≥ 0.5) or contained spans exclude a training record. A stage MAY name a benchmark's official train split in `official`; there only the item itself (equal unit or key) is excluded, since a templated benchmark's train and test states are near by construction. A result under `official` MUST say so and MUST name the baseline trained on the same split. A specialist trained on another encoder (for example the English ModernBERT-large of the Laya typed-decisions baseline) MAY serve as a teacher for the one line. It is never served (§2). ### §16 Training infrastructure The trainer SHOULD span Hanzo's heterogeneous fleet (Metal, CUDA, ROCm) and MUST support resume, versioned data, model revision tracking and optimizer-state recovery. A run MUST NOT be the only copy of its own progress. A full stage SHOULD start only when resume works, every device build it uses is validated, and its data build is versioned. A run on another encoder is not the Kai lineage, whatever it cost. The trainer is local SGD with an outer Nesterov step: `train fit --listen` coordinates and trains, `train join` adds a machine at any time, and deltas are summed in join order. One run spans Metal (M4 Max), CUDA (GB10) and ROCm (Radeon 8060S) workers; on a 2% pilot, CUDA and Metal agree on mean validation accuracy (0.500 against 0.504 over 48 suites). A unified-memory worker MUST keep its micro-batch within the OS memory guard (`--scale`). ### §17 API `POST /v1/decisions`, with questions: ```json {"model": "kai", "state": {}, "questions": {}} ``` or a program and evidence: ```json {"model": "kai", "program": "agent.preflight@4", "evidence": [], "state": {}} ``` A response carries the decision id, program and version, model revision, typed answers, probabilities, calibration revision, usage and trace link. The request is the Decisions shape Jev clients send. ### §18 Evaluation Rehosted weights are not an improvement. Every gain names its source (runtime, architecture, training, calibration, retrieval, modality, joint decoding). Baselines: Laya, Jev, Zen used as a decision model, static rules, embedding retrieval. Axes are reported apart: - quality: accuracy, ranking, ordinal error, Brier, log loss, ECE, abstention; - generalization: held-out domains, languages, paraphrase, relabelling, reordering; - cardinality: small, Banking77, CLINC150, 1K, 10K, 100K+, recall@K apart from reranking; - robustness: permutation, irrelevant options, contradiction, missing evidence, OOD; - runtime: CPU and GPU latency, throughput, memory, batch scaling, load time; - joint decoding: decisions per pass, rounds, program consistency, constraint violations. Documentation MUST NOT turn a target into a claim. Measured on the frozen harness (`hanzoai/benchmarks` `decision/` at `2c74e2d`, Laya's own builders, one question set scored by one function for every backend). Kai is kai-1, the build `/v1/decisions` serves: stage a7's weights (`0834a74f…`) reading options to 512 tokens, plus one routed HelpSteer2 capability. It was measured on CUDA in BF16 and recorded 2026-10-03; production answers on CPU, where the harness has not been run. Each Kai figure is a run in the research record (`GET https://api.hanzo.ai/v1/research/runs?org=hanzo`, ids `-harness-kai-1.0834a74f-kai`). Jev is `typesafe/jev-1.13-20260917`. † marks a suite drawn from rows Laya trained on. | suite | Kai acc | Laya acc | Jev acc | Kai ECE | Jev ECE | |---|---|---|---|---|---| | AG News | 0.9425 | **0.9500** | 0.8600 | **0.033** | 0.102 | | DAIR emotion | **0.9350** | 0.5950 | 0.6025 | **0.018** | 0.280 | | Banking77 | **0.9075** | 0.4250 | 0.8350 | 0.074 | **0.073** | | support triage | 0.4400 | **0.5025** † | 0.3650 | **0.444** | 0.483 | | email spam | **0.9975** | **0.9975** | 0.9775 | **0.003** | 0.060 | | phishing | **0.9900** | 0.9825 † | 0.9000 | **0.010** | 0.039 | | jailbreak | 0.9175 | 0.7050 | **0.9400** | 0.074 | **0.047** | | toxicity | **0.8025** | 0.5300 | 0.6625 | 0.195 | **0.177** | | RAG relevance | **0.6800** | 0.6250 | 0.6200 | **0.028** | 0.279 | | routing | **1.0000** | 0.6391 | 0.9774 | **0.000** | 0.014 | | typed decisions | 0.7590 | 0.766 (Laya's typed checkpoint) | 0.7355 | 0.171 | **0.047** | | MASSIVE, 51 languages, macro | **0.9096** | 0.3822 | 0.8902 | **0.060** | 0.064 | | mean of 12 | **0.857** | — | 0.780 | **0.093** | 0.139 | Against Jev, Kai is more accurate on 11 of 12 suites and behind on jailbreak by 2.25 points (367 against 376 of 400); its calibration error is lower on 8 of 12, higher on Banking77, jailbreak, toxicity and typed decisions. Against the better of Laya and Jev per suite: 7 won, 1 tied (email spam), 4 behind (AG News, support triage, jailbreak, typed decisions). The two † suites are rows Laya trained on: all 400 of support triage, and of phishing 350 exactly and 50 contained (`decision/trained/overlap.json`, b7eb636). Held-out rows for them (`decision/held`) have not been run on kai-1, so no held-out comparison is claimed for the served build. On the cardinality suite (CUDA, F32), kai-1 answers 0.9675, 0.935, 0.9075 and 0.9075 at 4, 16, 77 and 150 options, against Jev's 0.905, 0.8525, 0.8425 and 0.940; at 1,000, 10,000 and 100,000 options it answers 0.005, 0 and 0, where Jev refuses. #### §18.1 Kai in the loop Enso SHALL support the study: does Kai remove generative compute at equal task success? Baseline B0: Zen does the work and its own control. Also B1 static routing, R1 Zen as its own router, and cumulative Kai conditions K1 model routing, K2 + context, K3 + tools and skills, K4 + progress and completion, K5 the full plane. Per successful task: GPU-seconds, prompt and generated tokens, KV-cache GB-seconds, peak VRAM, latency, model calls, agent steps, energy where measured, cost; `C_success = Σ C_task / successful tasks`. Routing regret against the cheapest successful model: `R = C_Kai − C_cheapest`. ### §19 Observability Every material decision SHOULD record decision and trace id, program and version, model revision, evidence references, answer, distribution, calibration revision, latency, device, usage, mode, override and downstream outcome: the record that debugging, calibration, training, replay and cost attribution all read. ### §20 Deployment Kai is served by Hanzo: `POST /v1/decisions` on api.hanzo.ai, on CPU. Its weights are not published and it is not offered for self-hosting. A conforming deployment MUST NOT require sending evidence to a third-party model provider. ### §21 Conformance A conforming system: treats Kai as a decision model, never an authority; types every decision; keeps uncertainty; supports `defer`; cannot let Kai weaken policy; keeps provenance sufficient for the application; versions programs; records the model revision in every material package; shares one encoding across a state's decisions; needs no generative call per bounded decision; serves `/v1/decisions`. Multimodal and joint decoding MAY be staged while this HIP is Draft. ### §22 Status Descriptive, not normative, as of Kai release v0.3.14, the release production serves. - **Landed**: - Decision Programs and Packages, what-flips analysis, SysML v2 import, the engineering knowledge graph, a cited JLTV powertrain trade, and refinement passes; - the Laya baseline served natively (21 states, 108/108 labels at parity); - the heterogeneous resumable trainer (§16); - the stage-A corpus and its barrier, with `official` splits (§15); - `POST /v1/decisions` on api.hanzo.ai, serving kai-1 on CPU at $0.021 per million input tokens, output free; - kai-1, measured beside Laya and Jev on the frozen harness (§18); score questions as a choice over their levels, trained with the ranked probability score; one routed capability; - the shipped programs pin `kai` at calibration `cal_47711d44267fdbdd`, so answers from kai-1 (`cal_e23c27a1f768bff7`) run them in `shadow`; - the structured selector: a program's MAP over each slot's top-K by bucket elimination (`kai::field`), and incremental encoding of a new chunk over cached keys and values. - **In progress**: - evidence adapters, the joint decoder, the Enso study. The served build answers each question of a request on its own. - **Not claimed**: - Kai ahead of Laya and Jev on every suite; - dependent multi-question programs, negated yes/no mirrors, 150 or more options, and calibration on typed decisions and jailbreak, where kai-1 is behind Jev; - multimodal accuracy; - Enso savings; - any end-to-end engineering or acquisition result. ## Rationale One large model can imitate every role here. It is not therefore the cheapest, most testable, most controllable or most auditable way to fill them. Hanzo splits intelligence into perception, retrieval, forecasting, decision, generation, mathematics, policy and execution, and composes them through Enso and Hanzo Decision, so generative compute is spent where generation is the work. The program tests four hypotheses, each unproven until measured: **H1** bounded decisions cost far less on a typed decision model than through generative routing, at equal task success; **H2** retrieval plus independent option scoring removes the cardinality limit of prompt-packed decision models; **H3** encoding evidence once and resolving variables jointly lowers cost as decisions per state grow; **H4** masked parallel prediction with dependency-aware refinement yields consistent program state without serial decision calls. ## Security Considerations Kai's output is untrusted probabilistic computation until the surrounding program accepts it. Anything security-relevant stays behind deterministic policy (§10), which Kai can tighten and never loosen. Evidence keeps its provenance, so a decision shows which sources it rested on and an injected or unsigned source can be weighed or refused. A deployment SHOULD be able to restrict evidence sources, external providers, data egress, model revisions, programs, action classes and tenant scope. Kai MUST NOT replace human acquisition or approval authority, and readiness claims MUST rest on demonstrated integrated capability, never on the architecture described here. ## References - HIP-0004 LLM gateway; HIP-0010 MCP; HIP-0043 inference engine; HIP-0113 engine provider runtime; HIP-0106 the cloud plugin contract; HIP-0124 bring your own provider; HIP-1190 product analytics; HIP-1220 commerce; HIP-1322 skills; HIP-1330 the agent loop. - `hanzoai/decision` `LLM.md` at `d419552`: architecture, crates, models, training. - Baselines: Laya 0.3.20 (typed decision models and runtime); Jev (typed decision API). - Data: mmBERT; MASSIVE; CLINC150; XNLI; SST-5; UCR/UEA; Monash; CWRU; NASA C-MAPSS; MIMII; NASA battery data. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).