Add System One typed batch API and matching fine-tuning inputs

FINETUNING.md

@@ -1,5 +1,7 @@
 # Fine-tune on your data
 
+Already using System One requests? [Convert the same state/questions/criteria into training rows](SYSTEM_ONE.md#fine-tune-with-the-same-inputs) with separate hard or soft targets and shared source-component IDs.
+
 The included CLI trains the existing Choice, Noul and Score paths without adding new parameters. It supports hard or soft labels, deterministic scheduling, full-input admission, DEV checkpoint selection and optimizer/RNG resume. Token embedding, embedding normalization and type embedding remain frozen. The other 486 parameter tensors are trainable when their type is present.
 
 Provide your own TRAIN and DEV JSONL. The CLI rejects shared IDs, shared normalized full inputs and same-source components where supplied. It does not prove semantic independence; use an appropriate development split and do not train on a release/test set.

PACKAGE_MANIFEST.json

@@ -1,6 +1,6 @@
 {
-  "bytes_excluding_this_manifest": 2327383853,
-  "file_count_excluding_this_manifest": 96,
+  "bytes_excluding_this_manifest": 2327409686,
+  "file_count_excluding_this_manifest": 102,
   "files": {
     ".gitattributes": {
       "bytes": 753,
@@ -23,8 +23,8 @@
       "sha256": "00862d0a49c69c406b7dbfa890f95f09a34680568309d1cc0571733abe7b933c"
     },
     "FINETUNING.md": {
-      "bytes": 3629,
-      "sha256": "33c76f3490f283d9e189eeb4190c0297795329b56546271a52b80cd503dd2ec0"
+      "bytes": 3842,
+      "sha256": "2874eedec3b19462552a35e0dc99af29c456b3a2f8096cc61344b92e4cc6db41"
     },
     "LICENSE": {
       "bytes": 11358,
@@ -75,13 +75,21 @@
       "sha256": "7e275e73c18b756a20b886272750b58416ead2c345b12393e162050231aa8f64"
     },
     "README.md": {
-      "bytes": 4184,
-      "sha256": "ac04717649be2e2e35355e882cb867c675c684651bccd8ed33235ecf3ae0e9c8"
+      "bytes": 4416,
+      "sha256": "dd76e4f9879defc462441f899974140e9a65a6361f26dff883fcedfc473381af"
     },
     "RUNTIME_UPDATE.json": {
       "bytes": 1087,
       "sha256": "0a77c012fe1bd23c5f1a06c106c1a29ae5ee156248db218fbbc6d631d1c5aff4"
     },
+    "SYSTEM_ONE.md": {
+      "bytes": 5735,
+      "sha256": "414e12680a6ec2dbbbc660d1f6ba0d601fa941388476a62696b7f5e8a3e11ef9"
+    },
+    "SYSTEM_ONE_VALIDATION.json": {
+      "bytes": 2583,
+      "sha256": "24c28a2b8c448507f26e116a7f6a6d4e40fb8eaae0384e6bee421a105e415e0a"
+    },
     "TECHNICAL_VALIDATION.json": {
       "bytes": 1547,
       "sha256": "fcfd2ce54f623325f268a702fc0c06044447e651dad665d6430e92d48f8e7353"
@@ -95,8 +103,8 @@
       "sha256": "5c95cf851a9480e6037bc190d0deee87da35576489362262ad4151bafbb96990"
     },
     "USAGE.md": {
-      "bytes": 3142,
-      "sha256": "13205f6361ce04807b4de0a13c3b6128c0b89e81f2422177d7a04c4b19a67f8e"
+      "bytes": 4589,
+      "sha256": "581e65562cdf35d8eac544640b984e6267d86e3b46adcaf1a00bd9d9c5af247c"
     },
     "VALIDATION.md": {
       "bytes": 2120,
@@ -182,9 +190,13 @@
       "bytes": 5751,
       "sha256": "87dd485127fea7b80ad19300c0d6d95a92b7c2b6bd5b62c99bdc9201b681c9fe"
     },
+    "decision_finetune/system_one.py": {
+      "bytes": 1784,
+      "sha256": "9b8e7cf14dafedb9bfc9f174db64be9f8c311cca3c48eba0c90f55a3bbd62c19"
+    },
     "decision_inference/__init__.py": {
-      "bytes": 193,
-      "sha256": "198b3c64fd20764d3d53489306cb16da9ecb04e6e98a002c5a6ee42f18707f87"
+      "bytes": 282,
+      "sha256": "8199829090f1a3ca5fe59aec1a6dce2beb57026c301d2c87d8c5b1c960981e66"
     },
     "decision_inference/_auto.py": {
       "bytes": 1325,
@@ -194,6 +206,10 @@
       "bytes": 3026,
       "sha256": "85b8349cdf08a3550027606b3108778955f84d66c52fa11dd908ea50311e69e5"
     },
+    "decision_inference/_system_one.py": {
+      "bytes": 10690,
+      "sha256": "d2ef9aa1d0badcf168065a782f8a96316045455a676c08bdb5dd384a651e2194"
+    },
     "decision_inference/profile.py": {
       "bytes": 2071,
       "sha256": "7e732fb3a9be93922a2e7e94920d9c75be7a3d07fbc3d88b1c2056bd374008f7"
@@ -222,6 +238,10 @@
       "bytes": 1242,
       "sha256": "9b72d89237808e0019521ab4e42635007c39d20ea200d98afa9fdca6e49ae400"
     },
+    "examples/system-one.json": {
+      "bytes": 692,
+      "sha256": "0b8320ecbeded8c3229dccc52f5045f00e8d1968183bc9d1371d24e949925dcf"
+    },
     "infer.py": {
       "bytes": 2373,
       "sha256": "6313bfd5e295d5dc3d9b6ded5f85cda75cf1da8ed4b2dbae32f619a76021e410"
@@ -385,6 +405,10 @@
     "source-metadata/VELA_LICENSE_SOURCE_README.md": {
       "bytes": 2046,
       "sha256": "817df5015d443e6a9e6bbc870d8bd4f0f5c0d48e29b8f50f665319609838f7ef"
+    },
+    "systemone.py": {
+      "bytes": 2368,
+      "sha256": "8ce311c5651f1b0c1bc99d5a4ccaa6c7878b5c509256e4668a2191ad8c35e2e3"
     }
   },
   "language_scope": "English typed-decisions specialist",
@@ -402,6 +426,7 @@
   },
   "parameter_tensors": 489,
   "parameters": 571909635,
+  "public_non_native_bytes_excluding_this_manifest": 5150475,
   "publication": {
     "download_access": "public_ungated",
     "new_contribution_license": "Apache-2.0",
@@ -415,6 +440,20 @@
   "schema": "decision.public-distribution.v1",
   "status": "READY_FOR_ROOT_PUBLICATION",
   "subject_manifest_sha256": "f288d873999832a3f37c6a7c4268c2ab309691e621794dbf7acab891acbbb7e6",
+  "system_one_api": {
+    "default_physical_batch_limit": 8,
+    "entry": "decision_inference.SystemOne",
+    "finetune_conversion": "decision_finetune.system_one.system_one_training_rows",
+    "max_batch_decisions": 512,
+    "max_questions": 128,
+    "max_request_bytes": 2097152,
+    "max_requests": 128,
+    "optional_auto_capacity": 32,
+    "request": "state/model/questions",
+    "response": "model/answers/usage",
+    "validation": "SYSTEM_ONE_VALIDATION.json",
+    "weights_unchanged": true
+  },
   "technical_validation": "TECHNICAL_VALIDATION.json",
   "training_provenance": "TRAINING_PROVENANCE.json"
 }

README.md

@@ -54,9 +54,11 @@ Lex is evaluated as an English specialist on these four workflows. For broader m
 
 ## Make it yours
 
+**One state. Many decisions.** Use the [System One API](SYSTEM_ONE.md) to submit up to 128 typed questions, or batch the same questions across independent contexts. Results return under your original question IDs.
+
 Run the [Python examples](USAGE.md), or adapt Lex to your own labels and rubrics with the included [fine-tuning CLI](FINETUNING.md). Both hard and soft training labels are supported, with checkpoint resume.
 
-The complete 1,024-token budget includes context, instructions, all candidates and special tokens. Overlength requests return an error. Native Choice and Score support 2–255 candidates or ordered levels; the Studio adapter uses 2–10 Score levels.
+The complete 1,024-token budget includes context, instructions, all candidates and special tokens. Overlength requests return an error. Native Choice and Score support 2–255 candidates or ordered levels; the System One and Studio interfaces use 2–10 Score levels.
 
 ## Architecture
 

SYSTEM_ONE.md

@@ -0,0 +1,129 @@
+# One state. Many decisions.
+
+Decision uses the [System One API format](https://docs.typesafe.ai/api): supply
+`state`, `model` and a map of typed `questions`; receive an `answers` map under
+the same question IDs. Noul returns the probability of yes, Choice selects from
+your named options, and Score evaluates an ordered rubric.
+
+```python
+from decision_inference import SystemOne
+
+# native is your loaded Decision checkpoint; see USAGE.md for loading.
+client = SystemOne(native, batching="auto")
+result = client.system_one(
+    state={"message": "Please refund the duplicate charge. I need this fixed today."},
+    questions={
+        "refund_requested": {
+            "type": "noul",
+            "instructions": "Does the customer explicitly request a refund?",
+        },
+        "team": {
+            "type": "choice",
+            "instructions": "Which team should handle this request?",
+            "criteria": {"Billing": "Charges and refunds", "Support": "Technical problems"},
+        },
+        "urgency": {
+            "type": "score",
+            "instructions": "How urgent is the request?",
+            "criteria": ["No deadline", "Needed soon", "Needed today"],
+        },
+    },
+)
+print(result["answers"])
+```
+
+`client.evaluate(request)` accepts the complete JSON request object, including
+`model`. A client is bound to its loaded checkpoint; a mismatched model is an
+error. Public Kai/Lex names are inferred from their verified native manifest.
+For your own fine-tune, use `SystemOne(native, model="my-decision-model")`.
+
+## Batch the questions or the contexts
+
+One request accepts **up to 128 questions**. For one set of questions across many
+independent contexts, use `client.batch`:
+
+```python
+questions = {
+    "refund_requested": {
+        "type": "noul",
+        "instructions": "Does the customer explicitly request a refund?",
+    }
+}
+results = client.batch([
+    {"model": client.model, "state": message, "questions": questions}
+    for message in messages
+])
+# results[i] corresponds to messages[i]; question IDs can repeat across requests.
+```
+
+`batch` is a Decision Python extension around ordinary System One requests. It
+accepts up to 128 requests and 512 total decisions, with a combined 2 MiB input
+limit. Responses preserve request order and question order. The entire batch
+must pass validation and complete-input token admission before any forward.
+An overlength or malformed input fails the call without partial answers.
+
+The default uses physical batches of up to eight. `batching="auto"` uses the
+released padding-aware scheduler: up to 32 consecutive same-type decisions when
+that adds no padding; otherwise it keeps B8. FP32 rounding can vary with physical
+batch shape. Each state/question pair still has its own encoder computation.
+One API call does not imply one forward or a shared state activation cache.
+
+## Typed fields
+
+| Type | `criteria` | Answer |
+|---|---|---|
+| `noul` | Optional `true` / `false` descriptions | `type`, `noul` |
+| `choice` | 2–255 named options; descriptions may be null | `type`, `choice`, `probabilities`, `confidence` |
+| `score` | 2–10 ordered level descriptions | `type`, `score`, `legend`, `probabilities`, `confidence` |
+
+State, instructions and descriptions accept strings, JSON objects or arrays.
+Structured values become deterministic compact JSON with sorted object keys;
+array order, Choice option order and Score level order are preserved. Question
+IDs are bookkeeping only. Choice names are part of the semantic input, including
+when their description is null. Score levels are indexed from zero; `score`
+preserves the native probability-weighted FP32 expectation. Structured Score
+descriptions appear as JSON strings in `legend`.
+
+Every complete state/question/candidate sequence must fit **1,024 tokens**.
+Nothing is truncated. The token count includes the repeated state for each
+question; `usage.input_tokens` sums these complete sequences and
+`usage.output_tokens` is zero because the model returns scores without generating
+text. These are local computation counts, not TypeSafe billing counts.
+
+Decision's `confidence` is the largest candidate probability, matching its native
+runtime. It is not calibrated correctness. TypeSafe does not specify its own
+formula in the [confidence documentation](https://docs.typesafe.ai/confidence),
+so thresholds should not be transferred between models without validation.
+The shared request/answer schema does not claim identical weights, confidence
+values, hosted service limits or SDK behavior.
+
+## Fine-tune with the same inputs
+
+Use the same conversion for training so structured inputs, option names and
+criteria have identical semantics at training and inference time:
+
+```python
+import json
+from pathlib import Path
+from decision_finetune.system_one import system_one_training_rows
+
+request = json.loads(Path("examples/system-one.json").read_text())
+rows = system_one_training_rows(
+    request,  # the same model/state/questions object used for inference
+    targets={
+        "refund_requested": {"probability": 1.0},
+        "team": {"choice_id": "Billing"},
+        "urgency": {"probabilities": [0.0, 0.0, 1.0]},
+    },
+    request_id="ticket-1001",
+    source_id="support-tickets",
+    component_id="customer-42",
+)
+```
+
+Save the rows as JSONL for the existing [fine-tuning CLI](FINETUNING.md). Targets
+stay separate from state, instructions and criteria. Related examples share a
+source/component ID and stay in one split; the CLI checks component and exact
+input overlap. Optional `hard_target_ids` supplies separate evaluation labels
+under the same question IDs. Noul supports soft yes probabilities; Choice and
+Score support complete soft distributions in the original candidate order.

SYSTEM_ONE_VALIDATION.json

@@ -0,0 +1,66 @@
+{
+  "all_reference_outputs_exact": true,
+  "api_source": {
+    "bytes": 10690,
+    "sha256": "d2ef9aa1d0badcf168065a782f8a96316045455a676c08bdb5dd384a651e2194"
+  },
+  "complete_input_tokens": 1024,
+  "coverage": [
+    "Noul, Choice and Score",
+    "128 questions",
+    "128 contexts and 512 decisions",
+    "question rename and reorder",
+    "irrelevant question insertion",
+    "single and multi-context agreement",
+    "default B8 and opt-in padding-aware B32",
+    "late invalid input before any forward",
+    "same training and inference input encoding"
+  ],
+  "cross_batch_tolerance": 2e-05,
+  "device": "AMD GPU / ROCm",
+  "limits": "Technical compatibility validation on synthetic unlabeled cases; not evidence of accuracy, calibration or latency gains.",
+  "max_decisions_per_batch": 512,
+  "max_questions_per_request": 128,
+  "max_requests_per_batch": 128,
+  "models": {
+    "Kai": {
+      "all_489_parameters_and_66_buffers_unchanged": true,
+      "cross_case_checks": 713,
+      "forward_calls": 242,
+      "forward_rows": 2756,
+      "hard_flips": 0,
+      "invalid_input_checks": 7,
+      "invalid_input_forward_calls": 0,
+      "max_probability_error": 2.0563602447509766e-06,
+      "max_score_error": 2.980232238769531e-07,
+      "native_manifest_sha256": "da603662bc57e89ccfb51c972ed9c1f2825f267597353cf1337df9117a3dfabe",
+      "result_sha256": "8cb3bc435e36b79d96b60058e9b4c57b9996dcb8a55a1cd3faf6c7324e7f917c",
+      "same_physical_reference_outputs_exact": true
+    },
+    "Lex": {
+      "all_489_parameters_and_66_buffers_unchanged": true,
+      "cross_case_checks": 713,
+      "forward_calls": 242,
+      "forward_rows": 2756,
+      "hard_flips": 0,
+      "invalid_input_checks": 7,
+      "invalid_input_forward_calls": 0,
+      "max_probability_error": 1.1324882507324219e-06,
+      "max_score_error": 7.152557373046875e-07,
+      "native_manifest_sha256": "f288d873999832a3f37c6a7c4268c2ab309691e621794dbf7acab891acbbb7e6",
+      "result_sha256": "e94c5f1109f15005415a48623602d5255b38bd33451b55c758a0db0c16f68191",
+      "same_physical_reference_outputs_exact": true
+    }
+  },
+  "optimizer_updates": 0,
+  "performance_benchmark": false,
+  "quality_evaluation": false,
+  "reference": "Independent System One mapping using the original Studio single-question conversion and native predictor; identical physical batches.",
+  "status": "PASS_AMD_SYSTEM_ONE_API",
+  "total_forward_calls": 484,
+  "training_conversion_source": {
+    "bytes": 1784,
+    "sha256": "9b8e7cf14dafedb9bfc9f174db64be9f8c311cca3c48eba0c90f55a3bbd62c19"
+  },
+  "weights_unchanged": true
+}

USAGE.md

@@ -7,12 +7,53 @@ hf download llm-semantic-router/Decision-1.0-Lex --local-dir Decision-1.0-Lex
 cd Decision-1.0-Lex
 ```
 
-Use `--local-dir` to materialize ordinary files for the native loader. Install the pinned Python dependencies from `requirements.txt` in your compatible ROCm environment before running the examples.
+Use `--local-dir` to materialize ordinary files for the native loader. Use the compatible ROCm/Python environment described below.
 
 This initial release bundles the verified native under `native/`, the public Python API. Run the following commands from the complete distribution root in a compatible environment. `PACKAGE_MANIFEST.json` records the exact payload; do not add files inside `native/` because its loader checks the complete file roster.
 
 Use an existing compatible AMD ROCm environment. The verified source pins Transformers 4.57.6; tested companion versions were Python 3.12.13, tokenizers 0.22.2 and safetensors 0.8.0. Actual validation used a ROCm PyTorch 2.12 development build, not a promised generic wheel installation. Choose a matching supported ROCm/PyTorch installation for your host; this release does not supply an installer or a CPU/NVIDIA inference path. Do not upgrade an active environment in place.
 
+## System One: parallel typed questions
+
+Use the standard `state / model / questions` request shape. The response contains
+`model`, an `answers` map under the same question IDs, and `usage`.
+
+```bash
+ROCR_VISIBLE_DEVICES=0 python systemone.py \
+  --input examples/system-one.json --output answers.json --batching auto
+```
+
+```python
+from decision_runtime import load_native
+from decision_inference import SystemOne
+
+native = load_native(
+    "native",
+    expected_manifest_sha256="f288d873999832a3f37c6a7c4268c2ab309691e621794dbf7acab891acbbb7e6",
+    device="cuda:0",
+)
+client = SystemOne(native, batching="auto")
+answers = client.system_one(
+    state="Please refund the duplicate charge. I need this fixed today.",
+    questions={
+        "refund": {"type": "noul", "instructions": "Is a refund requested?"},
+        "urgent": {"type": "noul", "instructions": "Does the customer specify a deadline?"},
+    },
+)["answers"]
+```
+
+Up to 128 questions per request. `client.batch(requests)` combines independent
+contexts with up to 512 total decisions. Each complete state/question/candidate
+sequence must fit 1,024 tokens; validation happens before the first forward.
+Default physical batching is B8; `auto` opts into the released homogeneous,
+padding-aware B32 scheduler. [Fields, batching and the matching fine-tuning
+conversion](SYSTEM_ONE.md).
+
+## Native records
+
+The original native JSONL interface remains available for applications that
+need logits, explicit candidate IDs or arbitrary ordered Score values.
+
 ```bash
 export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"
 export PYTHONDONTWRITEBYTECODE=1

decision_finetune/system_one.py

@@ -0,0 +1,34 @@
+"""Keep System One inference and fine-tuning input semantics identical."""
+import copy
+import json
+
+
+def system_one_training_rows(request, targets, *, request_id, source_id,
+                             component_id, hard_target_ids=None):
+    """Convert a typed request plus separate native targets to training rows.
+
+    targets is keyed by question ID. Noul uses {'probability': p_yes}, Choice
+    {'choice_id': label} or {'probabilities': [...]}, Score {'probabilities': [...]}.
+    The caller assigns shared source/component IDs across related examples so
+    existing TRAIN/DEV validation can reject component overlap.
+    """
+    from decision_inference._system_one import system_one_records
+    from .data import semantics
+    for value in (request_id, source_id, component_id):
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("Explicit nonempty request/source/component IDs required")
+    rows = system_one_records(request)
+    qids = {row["question"]["id"] for row in rows}
+    if not isinstance(targets, dict) or set(targets) != qids:
+        raise ValueError("Exactly one target per question ID is required")
+    if hard_target_ids is not None and (not isinstance(hard_target_ids, dict) or set(hard_target_ids) != qids):
+        raise ValueError("Hard evaluation labels must cover exactly the question IDs")
+    for i, row in enumerate(rows):
+        qid = row["question"]["id"]
+        row.update(id=json.dumps([request_id, i], ensure_ascii=False, separators=(",", ":")),
+                   source_id=source_id, component_id=component_id,
+                   target=copy.deepcopy(targets[qid]))
+        if hard_target_ids is not None:
+            row["hard_target_id"] = hard_target_ids[qid]
+        semantics(row)
+    return rows

decision_inference/__init__.py

@@ -1,5 +1,5 @@
 from .profile import Complete1KCollator, MAX_INPUT_TOKENS, predict_1k
-
 from ._auto import predict_auto_1k
+from ._system_one import SystemOne, system_one_records
 
-__all__ = ["Complete1KCollator", "MAX_INPUT_TOKENS", "predict_1k", "predict_auto_1k"]
+__all__ = ["Complete1KCollator", "MAX_INPUT_TOKENS", "predict_1k", "predict_auto_1k", "SystemOne", "system_one_records"]

decision_inference/_system_one.py

@@ -0,0 +1,217 @@
+"""System One request/answer schema over complete-input Decision inference.
+
+Pure input conversion is shared with fine-tuning. Question IDs are bookkeeping;
+Choice labels are semantic. No chat prompts, generated JSON, or cross-call cache.
+"""
+import copy
+import json
+import math
+
+MAX_QUESTIONS = 128
+MAX_REQUESTS = 128
+MAX_DECISIONS = 512
+MAX_REQUEST_BYTES = 2 * 1024 * 1024
+PUBLIC_MODELS = {
+    "Decision-1.0-Kai": "da603662bc57e89ccfb51c972ed9c1f2825f267597353cf1337df9117a3dfabe",
+    "Decision-1.0-Lex": "f288d873999832a3f37c6a7c4268c2ab309691e621794dbf7acab891acbbb7e6",
+}
+
+
+def _identifier(value, label):
+    if not isinstance(value, str) or not value.strip() or len(value) > 128:
+        raise ValueError(label + " must be a nonempty string of at most 128 characters")
+    return value
+
+
+def _json(value):
+    # JSON objects must have string keys: never silently coerce Python keys.
+    def check(item):
+        if isinstance(item, dict):
+            if not all(isinstance(k, str) for k in item):
+                raise ValueError("JSON object keys must be strings")
+            for v in item.values():
+                check(v)
+        elif isinstance(item, list):
+            for v in item:
+                check(v)
+        elif item is not None and not isinstance(item, (str, bool, int, float)):
+            raise ValueError("Only JSON values are supported")
+    try:
+        check(value)
+        return json.dumps(value, ensure_ascii=False, sort_keys=True,
+                          separators=(",", ":"), allow_nan=False)
+    except (TypeError, RecursionError, UnicodeError) as exc:
+        raise ValueError("Invalid JSON content") from exc
+
+
+def _content(value, label):
+    if isinstance(value, str):
+        if not value.strip():
+            raise ValueError(label + " must not be empty")
+        return value
+    if isinstance(value, (dict, list)):
+        return _json(value)
+    raise ValueError(label + " must be text, an object, or an array")
+
+
+def system_one_records(request):
+    """Validate one wire request and return native rows, without loading a model.
+
+    Full token admission occurs in predict_1k before the first model forward.
+    External record IDs should be made unique when combining training examples.
+    """
+    if not isinstance(request, dict) or set(request) != {"model", "state", "questions"}:
+        raise ValueError("A request contains exactly model, state and questions")
+    _identifier(request["model"], "Model")
+    if len(_json(request).encode("utf-8")) > MAX_REQUEST_BYTES:
+        raise ValueError("Request exceeds 2 MiB; no input is truncated")
+    state = _content(request["state"], "State")
+    questions = request["questions"]
+    if not isinstance(questions, dict) or not 1 <= len(questions) <= MAX_QUESTIONS:
+        raise ValueError("Provide 1..128 named questions")
+    rows = []
+    for index, (qid, item) in enumerate(questions.items()):
+        _identifier(qid, "Question ID")
+        if (not isinstance(item, dict) or set(item) - {"type", "instructions", "criteria"}
+                or not {"type", "instructions"} <= set(item)):
+            raise ValueError(qid + ": use type, instructions and optional criteria")
+        kind = item["type"]
+        if kind not in ("noul", "choice", "score"):
+            raise ValueError(qid + ": type must be noul, choice or score")
+        q = {"id": qid, "type": kind.capitalize(),
+             "text": _content(item["instructions"], qid + ".instructions")}
+        criteria = item.get("criteria")
+        if kind == "choice":
+            if not isinstance(criteria, dict) or not 2 <= len(criteria) <= 255:
+                raise ValueError(qid + ": Choice requires 2..255 named options")
+            q["options"] = []
+            for name, description in criteria.items():
+                _identifier(name, "Choice option")
+                text = name if description is None else name + ": " + _content(description, qid + ".criteria")
+                q["options"].append({"id": name, "text": text})
+        elif kind == "score":
+            if not isinstance(criteria, list) or not 2 <= len(criteria) <= 10:
+                raise ValueError(qid + ": Score requires 2..10 ordered levels")
+            q["levels"] = [{"id": str(i), "value": i, "text": _content(v, qid + ".criteria")}
+                           for i, v in enumerate(criteria)]
+        elif "criteria" in item:
+            if not isinstance(criteria, dict) or set(criteria) - {"false", "true"}:
+                raise ValueError(qid + ": Noul criteria accept false and true only")
+            for key in ("false", "true"):
+                if key in criteria:
+                    q[key + "_criterion"] = _content(criteria[key], qid + ".criteria." + key)
+        rows.append({"id": "systemone:" + str(index), "state_text": state, "question": q})
+    return rows
+
+
+def _answer(row, prediction):
+    q = row["question"]
+    kind = q["type"].lower()
+    ids = (["no", "yes"] if kind == "noul" else
+           [v["id"] for v in q["options" if kind == "choice" else "levels"]])
+    if (prediction.get("id") != row["id"] or prediction.get("question_id") != q["id"]
+            or prediction.get("type") != q["type"] or prediction.get("candidate_ids") != ids
+            or type(prediction.get("input_tokens")) is not int
+            or not 1 <= prediction["input_tokens"] <= 1024
+            or type(prediction.get("state_tokens_original")) is not int
+            or prediction["state_tokens_original"] < 0
+            or prediction["state_tokens_original"] != prediction.get("state_tokens_kept")):
+        raise RuntimeError("Prediction identity or complete-input profile mismatch")
+    p = prediction.get("probabilities")
+    if (not isinstance(p, list) or len(p) != len(ids)
+            or not all(type(v) in (int, float) and math.isfinite(v) and 0 <= v <= 1 for v in p)
+            or abs(sum(p) - 1) > 2e-5):
+        raise RuntimeError("Invalid prediction probabilities")
+    answer = {"type": kind}
+    if kind == "noul":
+        if prediction.get("probability") != p[1]:
+            raise RuntimeError("Native Noul probability mismatch")
+        answer["noul"] = p[1]
+        return answer
+    best = ids[max(range(len(p)), key=p.__getitem__)]
+    if prediction.get("choice_id") != best or prediction.get("confidence") != max(p):
+        raise RuntimeError("Native Choice/confidence mismatch")
+    answer.update(probabilities=dict(zip(ids, p)), confidence=prediction["confidence"])
+    if kind == "choice":
+        answer["choice"] = best
+    else:
+        score = prediction.get("score")
+        if (type(score) not in (int, float) or not math.isfinite(score)
+                or abs(score - sum(i * v for i, v in enumerate(p))) > 2e-5):
+            raise RuntimeError("Native ordinal Score mismatch")
+        # Preserve native FP32 arithmetic, not a new CPU reduction.
+        answer["score"] = score
+        answer["legend"] = {v["id"]: v["text"] for v in q["levels"]}
+    return answer
+
+
+class SystemOne:
+    """Local System One API for a loaded Kai, Lex or compatible fine-tune.
+
+    evaluate(request) accepts the HTTP body shape; system_one(**request) is its
+    Python equivalent. batch(requests) flattens independent states into GPU
+    batches and restores the original request/question order. B8 is the default;
+    batching='auto' opts into the published homogeneous padding-aware B32 path.
+    """
+    def __init__(self, native, *, model=None, batching="default"):
+        if model is None:
+            model = next((name for name, sha in PUBLIC_MODELS.items()
+                          if sha == native.manifest_sha256), None)
+        _identifier(model, "Model (required for a custom fine-tune)")
+        # Do not let a different loaded checkpoint claim a published identity.
+        if model in PUBLIC_MODELS and native.manifest_sha256 != PUBLIC_MODELS[model]:
+            raise ValueError("Loaded checkpoint does not match the public model name")
+        if batching not in ("default", "auto"):
+            raise ValueError("batching must be default or auto")
+        self.native, self.model, self.batching = native, model, batching
+
+    def system_one(self, *, state, questions, model=None):
+        return self.evaluate({"model": self.model if model is None else model,
+                              "state": state, "questions": questions})
+
+    def evaluate(self, request):
+        return self.batch([request])[0]
+
+    def batch(self, requests):
+        if not isinstance(requests, list) or not 1 <= len(requests) <= MAX_REQUESTS:
+            raise ValueError("Provide 1..128 request objects")
+        if len(_json(requests).encode("utf-8")) > MAX_REQUEST_BYTES:
+            raise ValueError("Combined request exceeds 2 MiB")
+        # Detach mutable caller inputs before conversion/admission/inference.
+        requests = copy.deepcopy(requests)
+        groups = []
+        for request in requests:
+            rows = system_one_records(request)
+            if request["model"] != self.model:
+                raise ValueError("Request model does not match this loaded model")
+            groups.append(rows)
+        count = sum(map(len, groups))
+        if count > MAX_DECISIONS:
+            raise ValueError("Provide at most 512 decisions in one batch")
+        records, slots = [], []
+        # Question-major order permits the same question across many states to
+        # share a physical batch; external IDs never decide caching or grouping.
+        for qi in range(max(map(len, groups))):
+            for ri, group in enumerate(groups):
+                if qi < len(group):
+                    row = group[qi]
+                    row["id"] = f"systemone:{ri}:{qi}"
+                    records.append(row)
+                    slots.append((ri, qi))
+        if self.batching == "auto":
+            from ._auto import predict_auto_1k
+            predictions = predict_auto_1k(self.native, records)
+        else:
+            from ._request import predict_1k
+            predictions = predict_1k(self.native, records, batch_size=8)
+        if len(predictions) != len(records):
+            raise RuntimeError("Incomplete model result; no partial answers returned")
+        values = [[None] * len(group) for group in groups]
+        tokens = [0] * len(groups)
+        for row, prediction, (ri, qi) in zip(records, predictions, slots):
+            values[ri][qi] = _answer(row, prediction)
+            tokens[ri] += prediction["input_tokens"]
+        return [{"model": self.model,
+                 "answers": {row["question"]["id"]: answer for row, answer in zip(group, values[ri])},
+                 "usage": {"input_tokens": tokens[ri], "output_tokens": 0}}
+                for ri, group in enumerate(groups)]

examples/system-one.json

@@ -0,0 +1,29 @@
+{
+  "model": "Decision-1.0-Lex",
+  "state": {
+    "message": "Please refund the duplicate charge. I need this fixed today."
+  },
+  "questions": {
+    "refund_requested": {
+      "type": "noul",
+      "instructions": "Does the customer explicitly request a refund?"
+    },
+    "team": {
+      "type": "choice",
+      "instructions": "Which team should handle this request?",
+      "criteria": {
+        "Billing": "Charges and refunds",
+        "Support": "Technical problems"
+      }
+    },
+    "urgency": {
+      "type": "score",
+      "instructions": "How urgent is the request?",
+      "criteria": [
+        "No deadline",
+        "Needed soon",
+        "Needed today"
+      ]
+    }
+  }
+}

systemone.py

@@ -0,0 +1,53 @@
+"""Run one System One request, or a batch of requests, on a local Decision model."""
+import argparse
+import json
+from pathlib import Path
+
+NATIVE_MANIFEST_SHA256 = 'f288d873999832a3f37c6a7c4268c2ab309691e621794dbf7acab891acbbb7e6'
+
+
+def _unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError('Duplicate JSON object key: ' + key)
+        result[key] = value
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Decision System One: typed parallel questions on AMD')
+    parser.add_argument('--native', default=str(Path(__file__).resolve().parent / 'native'))
+    parser.add_argument('--manifest-sha256', default=NATIVE_MANIFEST_SHA256)
+    parser.add_argument('--model', help='Explicit name for a compatible custom fine-tune')
+    parser.add_argument('--input', required=True, help='JSON request or array of request objects')
+    parser.add_argument('--output', required=True, help='Fresh response JSON file')
+    parser.add_argument('--batching', choices=('default', 'auto'), default='default')
+    args = parser.parse_args()
+    payload = Path(args.input).read_bytes()
+    if len(payload) > 2 * 1024 * 1024:
+        raise ValueError('Input file exceeds 2 MiB')
+    request = json.loads(payload, object_pairs_hook=_unique_object)
+    if Path(args.output).exists():
+        raise ValueError('Output must be fresh')
+    import torch
+    from decision_runtime import load_native
+    from decision_inference import SystemOne
+    if torch.version.hip is None or not torch.cuda.is_available() or torch.cuda.device_count() != 1:
+        raise RuntimeError('Expose exactly one AMD ROCm GPU')
+    torch.cuda.set_device(0)
+    torch.set_num_threads(2)
+    torch.backends.cuda.matmul.allow_tf32 = False
+    torch.backends.cudnn.allow_tf32 = False
+    torch.backends.mha.set_fastpath_enabled(False)
+    native = load_native(args.native, expected_manifest_sha256=args.manifest_sha256, device='cuda:0')
+    client = SystemOne(native, model=args.model, batching=args.batching)
+    result = client.batch(request) if isinstance(request, list) else client.evaluate(request)
+    with Path(args.output).open('x', encoding='utf-8') as stream:
+        json.dump(result, stream, ensure_ascii=False, allow_nan=False, indent=2)
+        stream.write('\n')
+
+
+if __name__ == '__main__':
+    main()
+