decision-toolkit 0.1.6__tar.gz → 0.2.0__tar.gz

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/CHANGELOG.md

@@ -1,8 +1,53 @@
 # Changelog
 
-All notable changes to this project are documented here. Version `0.1.6` is
+All notable changes to this project are documented here. Version `0.2.0` is
 published on PyPI.
 
+## [0.2.0] — 2026-10-20
+
+REST conformance correction. The previous documentation called the TypeSafe
+contract "System One 1.14"; that version was not real. The public TypeSafe API
+schema is `0.2.0`. This release aligns the request/response shapes and error
+behavior with the published schemas, documents unsupported vision/assets as an
+explicit text-only limitation, and removes invented OpenAI response fields.
+
+### Fixed
+
+- System One is now pinned to the published TypeSafe API schema `0.2.0`, not
+  the invented `1.14` label. `/v1/info` reports `0.2.0`.
+- System One accepts rich instructions/criteria, the standard `assets` field,
+  one-level scores and non-negative `output_tokens`; schema validation returns
+  `422` with a FastAPI-style `detail` array. Assets/images return `501` because
+  the catalog is text-only.
+- OpenAI Decisions responses now expose the public `model`, `answers` and
+  `usage` fields (including usage details), without invented `id`, `object`,
+  `created_at`, `status` or `safety_identifier` fields. Toolkit metadata remains
+  namespaced under `x_decision_toolkit`.
+- `variant` is explicitly documented as a local extension, not a TypeSafe or
+  OpenAI field. Standard clients select a model and omit it.
+
+## [0.1.7] — 2026-10-20
+
+Variant consistency release. The selected quantization now agrees across the
+library, CLI and REST API, including catalog defaults, persisted `dtk models
+use` selections, per-call overrides, readiness/info metadata and response
+payloads.
+
+### Fixed
+
+- `DecisionModel.variant` reports the explicit, persisted or catalog-default
+  variant before and after resolution, without inheriting another model's
+  selection.
+- The REST registry resolves the catalog default for a configured model and
+  honors the persisted variant for the current model. `/v1/info`, `/ready`,
+  `/v1/models` and `/v1/decision-models` expose the effective default and
+  `current_variant`.
+- REST responses echo the selected variant under `x_decision_toolkit.variant`;
+  a fixed injected model rejects a conflicting request variant.
+- Added cross-surface tests for library resolution, CLI pass-through, registry
+  defaults and System One/OpenAI REST requests, plus documentation for selection
+  precedence.
+
 ## [0.1.6] — 2026-10-20
 
 Variant catalog and selection release. `dtk models list` now exposes every
@@ -106,7 +151,7 @@ README correction. No code or model behavior changed.
 
 ### Phase 2 — REST
 
-- Versioned System One 1.14 and OpenAI Decisions beta projections.
+- Versioned System One and OpenAI Decisions beta projections.
 - Bearer auth, per-request model/variant, usage, standard error envelope.
 - OpenAI-shaped `/v1/models`, rich `/v1/decision-models`, readiness `503`.
 - Request ids, access logs, body limits, CORS and timeouts.
@@ -116,6 +161,8 @@ README correction. No code or model behavior changed.
 - Typed `DecisionModel` API with lifecycle, batching, async, usage, warnings,
   normalized confidence, capabilities, structured events and atomic model store.
 
+[0.2.0]: https://pypi.org/project/decision-toolkit/0.2.0/
+[0.1.7]: https://pypi.org/project/decision-toolkit/0.1.7/
 [0.1.6]: https://pypi.org/project/decision-toolkit/0.1.6/
 [0.1.5]: https://pypi.org/project/decision-toolkit/0.1.5/
 [0.1.4]: https://test.pypi.org/project/decision-toolkit/0.1.4/

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: decision-toolkit
-Version: 0.1.6
+Version: 0.2.0
 Summary: Local-first toolkit for open-weights decision models: one ONNX engine, one adapter per model contract, typed choice/yes-no/score decisions with probabilities on CPU.
 Project-URL: Homepage, https://github.com/gia-uh/decision-toolkit
 Project-URL: Repository, https://github.com/gia-uh/decision-toolkit
@@ -59,7 +59,7 @@ and CLI. `dtk --help` and every subcommand help also include runnable examples.
 ## Installation
 
 ```bash
-uv pip install decision-toolkit              # library + CLI (0.1.6 on PyPI)
+uv pip install decision-toolkit              # library + CLI (0.2.0 on PyPI)
 uv pip install "decision-toolkit[onnx]"      # + onnxruntime, tokenizers (the model runtime)
 uv pip install "decision-toolkit[server]"    # + REST server (FastAPI)
 ```
@@ -67,7 +67,7 @@ uv pip install "decision-toolkit[server]"    # + REST server (FastAPI)
 The project is managed with [uv](https://docs.astral.sh/uv/) and ships a committed `uv.lock`. Published
 wheels remain compatible with `pip` for environments that do not use uv.
 
-PyPI: <https://pypi.org/project/decision-toolkit/0.1.6/>. See
+PyPI: <https://pypi.org/project/decision-toolkit/0.2.0/>. See
 [docs/RELEASE.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/RELEASE.md)
 for the Trusted Publishing flow and clean-install checks.
 
@@ -173,12 +173,16 @@ dtk serve --model gliner2.5-multi --warmup \
   --log-format json
 ```
 
-Endpoints: `POST /v1/systemone` (System One 1.14), `POST /v1/decisions`
+Endpoints: `POST /v1/systemone` (TypeSafe System One), `POST /v1/decisions`
 (OpenAI Decisions beta), `GET /v1/models` (OpenAI shape),
 `GET /v1/decision-models` (rich catalog), `GET /v1/info`, `GET /health`,
-`GET /ready`. Requests may select `model` and `variant`; failures use the OpenAI
-`{"error": {...}}` envelope and every response carries `x-request-id`.
-`TYPESAFE_BASE_URL=http://localhost:8000` makes existing System One clients work.
+`GET /ready`. Requests select `model`; `variant` is a documented local extension,
+not part of either public API. System One request validation uses the TypeSafe
+`422 {"detail": [...]}` shape; OpenAI Decisions uses its
+`{"error": {...}}` envelope. Every response carries `x-request-id`.
+A standard System One client that sends `model`, `state` and `questions` can
+point at `http://localhost:8000`; image/asset and `box` requests are outside the
+current text-only subset.
 See [docs/REST.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/REST.md) for the pinned contracts, limits, auth and
 the standard-evolution process.
 
@@ -241,9 +245,11 @@ dtk models current --json          # {"current": "...", "variant": "fp32"}
 dtk decide --model gliner2.5-multi --variant fp16 --state "..." --q 'cat=choice:a|b'
 ```
 
-From Python: `DecisionModel("gliner2.5-multi", variant="fp32")`. The variant
-must already be downloaded. If a variant is omitted, the catalog default is
-used unless `dtk models use` selected another one.
+From Python: `DecisionModel("gliner2.5-multi", variant="fp32")`. REST selects
+the same way with `"variant": "fp32"` in the request body and returns the choice
+under `x_decision_toolkit.variant`. The variant must already be downloaded. If a
+variant is omitted, the catalog default is used unless `dtk models use` selected
+another one.
 
 A variant becomes default only after passing the parity gate (top-1 ≥ 99%,
 mean |Δp| ≤ 0.02, accuracy delta ≤ 1 pp against the fp32 build on a fixed

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/README.md

@@ -21,7 +21,7 @@ and CLI. `dtk --help` and every subcommand help also include runnable examples.
 ## Installation
 
 ```bash
-uv pip install decision-toolkit              # library + CLI (0.1.6 on PyPI)
+uv pip install decision-toolkit              # library + CLI (0.2.0 on PyPI)
 uv pip install "decision-toolkit[onnx]"      # + onnxruntime, tokenizers (the model runtime)
 uv pip install "decision-toolkit[server]"    # + REST server (FastAPI)
 ```
@@ -29,7 +29,7 @@ uv pip install "decision-toolkit[server]"    # + REST server (FastAPI)
 The project is managed with [uv](https://docs.astral.sh/uv/) and ships a committed `uv.lock`. Published
 wheels remain compatible with `pip` for environments that do not use uv.
 
-PyPI: <https://pypi.org/project/decision-toolkit/0.1.6/>. See
+PyPI: <https://pypi.org/project/decision-toolkit/0.2.0/>. See
 [docs/RELEASE.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/RELEASE.md)
 for the Trusted Publishing flow and clean-install checks.
 
@@ -135,12 +135,16 @@ dtk serve --model gliner2.5-multi --warmup \
   --log-format json
 ```
 
-Endpoints: `POST /v1/systemone` (System One 1.14), `POST /v1/decisions`
+Endpoints: `POST /v1/systemone` (TypeSafe System One), `POST /v1/decisions`
 (OpenAI Decisions beta), `GET /v1/models` (OpenAI shape),
 `GET /v1/decision-models` (rich catalog), `GET /v1/info`, `GET /health`,
-`GET /ready`. Requests may select `model` and `variant`; failures use the OpenAI
-`{"error": {...}}` envelope and every response carries `x-request-id`.
-`TYPESAFE_BASE_URL=http://localhost:8000` makes existing System One clients work.
+`GET /ready`. Requests select `model`; `variant` is a documented local extension,
+not part of either public API. System One request validation uses the TypeSafe
+`422 {"detail": [...]}` shape; OpenAI Decisions uses its
+`{"error": {...}}` envelope. Every response carries `x-request-id`.
+A standard System One client that sends `model`, `state` and `questions` can
+point at `http://localhost:8000`; image/asset and `box` requests are outside the
+current text-only subset.
 See [docs/REST.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/REST.md) for the pinned contracts, limits, auth and
 the standard-evolution process.
 
@@ -203,9 +207,11 @@ dtk models current --json          # {"current": "...", "variant": "fp32"}
 dtk decide --model gliner2.5-multi --variant fp16 --state "..." --q 'cat=choice:a|b'
 ```
 
-From Python: `DecisionModel("gliner2.5-multi", variant="fp32")`. The variant
-must already be downloaded. If a variant is omitted, the catalog default is
-used unless `dtk models use` selected another one.
+From Python: `DecisionModel("gliner2.5-multi", variant="fp32")`. REST selects
+the same way with `"variant": "fp32"` in the request body and returns the choice
+under `x_decision_toolkit.variant`. The variant must already be downloaded. If a
+variant is omitted, the catalog default is used unless `dtk models use` selected
+another one.
 
 A variant becomes default only after passing the parity gate (top-1 ≥ 99%,
 mean |Δp| ≤ 0.02, accuracy delta ≤ 1 pp against the fp32 build on a fixed

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/docs/CORE.md

@@ -1,7 +1,7 @@
 # Core programmatic API (phase 1)
 
 The programmatic API is the **superset**: the most expressive layer of the
-toolkit. The REST server is a standards-compliant projection of a subset of
+toolkit. The REST server is a documented, conformance-tested projection of a subset of
 this API, and the CLI is our own operational subset. Nothing in this document
 belongs to a wire contract.
 

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/docs/EXAMPLES.md

@@ -132,6 +132,7 @@ dtk serve --model gliner2.5-multi --warmup --port 8000
 curl -s http://127.0.0.1:8000/v1/systemone \
   -H "Content-Type: application/json" \
   -d '{
+    "model": "gliner2.5-multi",
     "state": "Meeting with Acme: 10% discount, sign next week.",
     "questions": {
       "cat": {
@@ -150,6 +151,7 @@ curl -s http://127.0.0.1:8000/v1/systemone \
 curl -s http://127.0.0.1:8000/v1/decisions \
   -H "Content-Type: application/json" \
   -d '{
+    "model": "gliner2.5-multi",
     "input": "Please change my seat to an aisle.",
     "questions": [{
       "type": "choice",
@@ -163,6 +165,8 @@ curl -s http://127.0.0.1:8000/v1/decisions \
   }' | jq
 ```
 
+`variant` is a decision-toolkit extension; omit it for a standard client.
+
 ### Model per request and auth
 
 ```bash

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/docs/RELEASE.md

@@ -6,7 +6,9 @@ file was written, so the name was available). The first release was `0.1.0`;
 `0.1.3` added release verification and docs publication; `0.1.4` migrated
 package management and builds to uv but was published to TestPyPI only; `0.1.5`
 fixed TestPyPI verification for uv; `0.1.6` added complete variant visibility
-and selection in the CLI and documentation.
+and selection in the CLI and documentation; `0.1.7` aligned variant selection
+across the library, CLI and REST API; `0.2.0` corrected the REST conformance
+claims and wire shapes to the published TypeSafe and OpenAI schemas.
 
 ## Local build and verification
 
@@ -33,7 +35,7 @@ Clean install test (no `PYTHONPATH`):
 ```bash
 uv venv --python 3.12 /tmp/dtk-wheel
 uv pip install --python /tmp/dtk-wheel/bin/python \
-  dist/decision_toolkit-0.1.6-py3-none-any.whl
+  dist/decision_toolkit-0.2.0-py3-none-any.whl
 uv pip check --python /tmp/dtk-wheel/bin/python
 /tmp/dtk-wheel/bin/dtk --version
 /tmp/dtk-wheel/bin/dtk models list --json
@@ -44,7 +46,7 @@ With inference and server extras:
 
 ```bash
 uv pip install --python /tmp/dtk-wheel/bin/python \
-  "dist/decision_toolkit-0.1.6-py3-none-any.whl[onnx,server,tracing]"
+  "dist/decision_toolkit-0.2.0-py3-none-any.whl[onnx,server,tracing]"
 /tmp/dtk-wheel/bin/dtk decide --model gliner2.5-decide ...
 /tmp/dtk-wheel/bin/dtk serve --model gliner2.5-decide --warmup --port 8016
 curl -s http://127.0.0.1:8016/health
@@ -78,8 +80,8 @@ No long-lived PyPI token is needed; the workflow uses GitHub OIDC
 4. Create and push an annotated tag:
 
    ```bash
-   git tag -a v0.1.6 -m "decision-toolkit 0.1.6"
-   git push origin v0.1.6
+   git tag -a v0.2.0 -m "decision-toolkit 0.2.0"
+   git push origin v0.2.0
    ```
 
 5. `.github/workflows/release.yml` builds once, publishes to **TestPyPI**, then
@@ -128,16 +130,18 @@ to TestPyPI without publishing to PyPI or creating a GitHub release.
 
 ## Published release
 
-`0.1.6` is published through Trusted Publishing on 2026-10-20:
+`0.2.0` is published through Trusted Publishing on 2026-10-20:
 
-<https://pypi.org/project/decision-toolkit/0.1.6/>
+<https://pypi.org/project/decision-toolkit/0.2.0/>
 
 `0.1.0` was the first release; `0.1.1` refreshed the PyPI description; `0.1.2`
 validated the OIDC TestPyPI → PyPI flow; `0.1.3` added post-publish install
 verification and the GitHub Pages documentation site; `0.1.4` moved the
 development, build, CI, release and documentation environments to uv but was
 published to TestPyPI only; `0.1.5` fixed TestPyPI resolution; `0.1.6` added
-complete variant/quantization visibility and selection.
+complete variant/quantization visibility and CLI selection; `0.1.7` aligned
+selection across library, CLI and REST; `0.2.0` corrected the REST conformance
+claims and wire shapes.
 
 The tag-triggered workflow remains the preferred path for future releases once
 the TestPyPI/PyPI trusted publishers and protected environments are configured.

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/docs/REST.md

@@ -1,37 +1,42 @@
 # REST projection (phase 2)
 
-REST is a **standards-compliant projection** of the programmatic core, not a
-second implementation. The core remains the superset; the server selects a
-subset, maps it to a pinned wire contract, and adds transport concerns (auth,
-request ids, limits, CORS, logging).
+REST is a **documented projection** of the programmatic core, not a second
+implementation. The core remains the superset; the server selects a supported
+subset, maps it to the published wire contracts, and adds transport concerns
+(auth, request ids, limits, CORS, logging).
 
 ```
 Programmatic core (superset)
-        │  pure projection + conformance
+        │  pure projection + conformance tests
         ▼
-REST (subset; System One 1.14 + OpenAI Decisions beta)
+REST (supported subset; TypeSafe System One + OpenAI Decisions beta)
 ```
 
+Compatibility is tested against the published shapes, not against a local
+invention. The current models are text-only, so image/assets and `box` requests
+are explicitly rejected rather than silently approximated.
+
 The wire models live in `decision_toolkit/contracts/`, the multi-model registry
 in `decision_toolkit/registry.py`, and `server.py` contains only transport and
 FastAPI glue.
 
 ## Pinned contracts
 
-| Contract | Version | Module |
-| --- | --- | --- |
-| System One (TypeSafe-compatible) | `1.14` | `contracts/systemone_v1.py` |
-| OpenAI Decisions | `beta` | `contracts/openai_decisions_beta.py` |
+| Contract | Version | Reference | Module |
+| --- | --- | --- | --- |
+| TypeSafe System One | API schema `0.2.0` | <https://docs.typesafe.ai/api> | `contracts/systemone_v1.py` |
+| OpenAI Decisions | `beta` | <https://developers.openai.com/api/docs/guides/decisions> | `contracts/openai_decisions_beta.py` |
 
-`GET /v1/info` exposes both versions. The reference for System One is the
-TypeSafe 1.14 API as implemented by llama.cpp's `POST /v1/systemone`; the
-OpenAI dialect is the beta Decisions shape already translated by the toolkit.
+`GET /v1/info` exposes both versions. "System One 1.14" was an incorrect label
+in earlier documentation; the published TypeSafe API schema is `0.2.0`. The
+implementation targets that schema and the published OpenAI beta shape, with the
+limitations listed below.
 
 ## Endpoints
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `POST` | `/v1/systemone` | System One 1.14 decision. |
+| `POST` | `/v1/systemone` | TypeSafe System One decision. |
 | `POST` | `/v1/decisions` | OpenAI Decisions beta decision. |
 | `GET` | `/v1/models` | OpenAI model-list shape. |
 | `GET` | `/v1/models/{id}` | One model in the OpenAI shape. |
@@ -44,12 +49,33 @@ OpenAI dialect is the beta Decisions shape already translated by the toolkit.
 Toolkit-only metadata is under `x_decision_toolkit`, never mixed into standard
 fields. `/v1/decision-models` is the rich, non-standard catalog endpoint.
 
-## System One 1.14
+## Variants (local extension)
 
-Request:
+Neither TypeSafe nor OpenAI has a `variant` request field: the public APIs select
+a model by name. Quantization is a **decision-toolkit extension**:
+
+- Request `variant` wins when a local client sends it.
+- Otherwise, a server started with `dtk serve --variant` uses that default.
+- Otherwise, the variant selected with `dtk models use` is used when the server
+  is serving the current model.
+- Otherwise, the catalog default (the `*` variant in `dtk models list`) is used.
+
+Standard clients should omit `variant`; they work with the server default. A
+standard-only integration can run one server per variant, or use the server's
+`--variant` setting. The selected variant is exposed in the namespaced
+`x_decision_toolkit.variant` extension, never in a standard field.
+`/v1/models`, `/v1/models/{id}`, `/v1/decision-models`, `/v1/info` and `/ready`
+expose the configured catalog variants, the default, cached variants, and the
+current selection. See [Variants and quantization](VARIANTS.md) for the catalog
+and download/select commands.
+
+## System One (TypeSafe API schema 0.2.0)
+
+Request (standard fields, plus the optional local `model` routing extension):
 
 ```json
 {
+  "model": "gliner2.5-multi",
   "state": "I was charged twice and nobody replied.",
   "questions": {
     "route": {
@@ -88,9 +114,9 @@ Response:
       "confidence": 0.4
     }
   },
-  "usage": {"input_tokens": 239, "output_tokens": 0},
+  "usage": {"input_tokens": 239, "output_tokens": 12},
   "x_decision_toolkit": {
-    "spec": "1.14",
+    "spec": "0.2.0",
     "request_id": "req-123",
     "variant": "fp16",
     "adapter": "gliner2",
@@ -105,16 +131,23 @@ Response:
 
 Standard fields:
 
-- `usage.output_tokens` is **always 0** (decisions generate no text).
+- `usage.output_tokens` is a non-negative count. The current core reports the
+  tokenizer count of the serialized answers (it may be non-zero); do not assume
+  it is always zero.
 - `usage.input_tokens` comes from the core token accounting.
 - The full core usage, including the explicit `estimated` flag, is under
   `x_decision_toolkit.usage`.
-- `choice` requires a non-empty criteria object; `score` needs 2–10 levels;
-  `noul` may omit criteria. Invalid bodies return `400`.
-- `files`/`images` accept data URLs only. Text-only models return `501` with
-  `code: "multimodal_not_supported"`; malformed/non-data URLs return `400`.
-- `model` and `variant` are optional routing extensions for a multi-model local
-  server. An unqualified request uses the configured default model.
+- `choice` requires a non-empty criteria object; System One `score` accepts
+  `1`–`10` ordered levels; `noul` may omit criteria.
+- Request-schema and question-validation failures return `422` with the
+  FastAPI-style `{"detail": [...]}` body used by the TypeSafe schema. Model
+  lookup, capability and transport failures keep their HTTP status and the
+  documented error envelope.
+- Standard `assets` are accepted by the schema but return `501` because the
+  current catalog is text-only. Legacy `files`/`images` fields are local
+  extensions; valid data URLs also return `501`, malformed values return `422`.
+- `model` is optional only as a local convenience; standard clients send it.
+  `variant` is a local extension, not part of the TypeSafe schema.
 
 ## OpenAI Decisions beta
 
@@ -130,9 +163,7 @@ Request:
     {"type": "score", "name": "urgency", "instructions": "How urgent?",
      "levels": [{"label": "low"}, {"label": "high"}]}
   ],
-  "safety_identifier": "user-hash",
-  "model": "gliner2.5-multi",
-  "variant": "fp16"
+  "model": "gliner2.5-multi"
 }
 ```
 
@@ -140,10 +171,6 @@ Response:
 
 ```json
 {
-  "id": "req-123",
-  "object": "response",
-  "created_at": 1790000000,
-  "status": "completed",
   "model": "gliner2.5-multi",
   "answers": [
     {"type": "predicate", "name": "refund", "probability": 0.93},
@@ -156,8 +183,13 @@ Response:
                        {"value": 1, "label": "high", "probability": 0.8}],
      "confidence": 0.8}
   ],
-  "usage": {"input_tokens": 92, "output_tokens": 0, "total_tokens": 92},
-  "safety_identifier": "user-hash",
+  "usage": {
+    "input_tokens": 92,
+    "output_tokens": 12,
+    "total_tokens": 104,
+    "input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0},
+    "output_tokens_details": {"reasoning_tokens": 0}
+  },
   "x_decision_toolkit": {
     "spec": "beta",
     "request_id": "req-123",
@@ -166,15 +198,20 @@ Response:
     "latency_ms": 350.1,
     "truncated": false,
     "warnings": [],
-    "usage": {"input_tokens": 92, "output_tokens": 10, "total_tokens": 102, "estimated": true}
+    "usage": {"input_tokens": 92, "output_tokens": 12, "total_tokens": 104, "estimated": true}
   }
 }
 ```
 
-- Original choice values (numbers, booleans, strings) are echoed back, not the
-  internal System One labels.
+- The public beta response fields are `model`, `answers` and `usage`; there is
+  no invented `id`, `object`, `created_at`, `status` or `safety_identifier`.
+- Original choice values are echoed back, not the internal System One labels.
+  The published beta accepts string/boolean values; the toolkit also accepts
+  numbers as a local extension.
 - Duplicate question names return `400`.
-- Images in `input` return `501` (`multimodal_not_supported`).
+- Images in `input` return `501` (`multimodal_not_supported`); the published
+  beta supports inline images, but the current catalog has no vision model.
+- `variant` is a local extension; standard clients omit it.
 - OpenAI SDK clients can list models (`client.models.list()`) and parse the
   error envelope (`{"error": {message, type, param, code}}`).
 
@@ -206,9 +243,11 @@ A model is not "ready" merely because it is configured:
 
 ## Limits and transport
 
-- 1–128 questions.
-- 1–255 choice options; 2–10 score levels.
-- 8 files/images maximum (the current catalog supports 0).
+- 1–128 questions (local limit; the TypeSafe schema has no maximum).
+- 1–255 choice options; 1–10 System One score levels; OpenAI score levels
+  require at least 2.
+- 8 legacy files/images maximum (the current catalog supports 0); standard
+  `assets` and images are rejected with `501`.
 - Request body limit (`--max-body-mb`, default 16) returns `413`.
 - Per-decision timeout (`--timeout`, default 120 s) returns `504`.
 - CORS origins are explicit (`--cors-origin`, repeatable).
@@ -219,22 +258,22 @@ A model is not "ready" merely because it is configured:
 
 ## Error mapping
 
-All errors use `{"error": {"message", "type", "param", "code"}}`.
+`/v1/systemone` request-validation failures follow the TypeSafe schema:
+`422` with `{"detail": [...]}`. `/v1/decisions` validation and toolkit domain
+errors use the OpenAI envelope
+`{"error": {"message", "type", "param", "code"}}`.
 
-| Condition | HTTP | code |
+| Condition | System One | OpenAI Decisions |
 | --- | --- | --- |
-| Invalid question/body | `400` | `invalid_question` / `invalid_request` |
-| Unsupported capability (`box`, assets) | `400` | `unsupported_capability` |
-| Unknown model | `404` | `model_not_found` |
-| Model not downloaded | `503` | `model_not_downloaded` |
-| Adapter unavailable | `503` | `adapter_not_available` |
-| Adapter not implemented | `501` | `adapter_not_implemented` |
-| Images/audio unsupported | `501` | `multimodal_not_supported` |
-| Truncation in strict mode | `400` | `truncated_input` |
-| Body too large | `413` | `request_too_large` |
-| Missing/invalid bearer | `401` | `authentication_error` |
-| Timeout | `504` | `timeout` |
-| Backend failure | `500` | `backend_failure` / `adapter_error` |
+| Request-schema validation | `422` + `detail` | `400` + error envelope |
+| Toolkit question validation | `422` + `detail` | `400` + error envelope |
+| Unknown model | `404` | `404` |
+| Model not downloaded | `503` | `503` |
+| Unsupported `box` / assets / images | `501` | `501` |
+| Truncation in strict mode | `400` | `400` |
+| Body too large | `413` | `413` |
+| Missing/invalid bearer | `401` | `401` |
+| Timeout | `504` | `504` |
 
 The CLI/REST never parse error strings to decide behavior; they use the stable
 `code`.
@@ -261,16 +300,17 @@ Adding a new spec version means adding a new module, not editing the old one.
 
 ## Compatibility matrix (current)
 
-| Feature | System One 1.14 | OpenAI Decisions beta |
+| Feature | System One (TypeSafe 0.2.0) | OpenAI Decisions beta |
 | --- | --- | --- |
 | `choice` / `noul` / `score` | yes | `choice` / `predicate` / `score` |
 | `box` | typed by core; rejected by current text models | no |
 | Text state | yes | `input` string |
 | JSON state | yes | message/string `input` |
-| Images | `501` for current models | `501` for current models |
-| Usage | `input_tokens` + `output_tokens=0` | input/output/total |
-| Per-request model/variant | extension | `model` + `variant` extension |
-| Errors | OpenAI-style envelope | OpenAI envelope |
+| Images/assets | `501` for current models | `501` for current models |
+| Usage | `input_tokens` + non-negative `output_tokens` | input/output/total + details |
+| Per-request model | standard field; optional local default | standard field; optional local default |
+| `variant` | local extension | local extension |
+| Validation errors | `422` + `detail` | `400` + envelope |
 | Auth / CORS / limits | server-level | server-level |
 
 ## Running
@@ -287,8 +327,8 @@ at `http://localhost:8000/v1`.
 
 ## Testing
 
-- System One contract tests cover the exact request/response fields, usage
-  `output_tokens=0`, invalid request matrix and image status codes.
+- System One contract tests cover the published request/response fields,
+  non-negative usage, the invalid request matrix and image/asset status codes.
 - OpenAI contract tests use the official `openai` Python SDK for
   `models.list()` and error-envelope parsing.
 - Equivalence tests send the same core decision through HTTP and compare

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/docs/VARIANTS.md

@@ -32,6 +32,34 @@ Models with a single row have only one catalogued, verified build. That does
 not mean other conversions do not exist upstream; it means they have not passed
 the parity, hash and license gates for this catalog.
 
+## One selection model across surfaces
+
+The same catalog variant is used by the library, CLI and REST API. Selection
+precedence is:
+
+1. an explicit per-call/per-request variant (`DecisionModel(..., variant=...)`,
+   `--variant`, or `"variant"` in a REST body);
+2. the CLI/server configuration (`dtk models use`, or `dtk serve --variant`);
+3. the catalog default marked with `*`.
+
+| Surface | Explicit selection | Default when omitted |
+| --- | --- | --- |
+| Library | `DecisionModel("gliner2.5-multi", variant="fp32")` | persisted variant for the current model, else catalog default |
+| CLI | `--variant fp32` | variant selected by `dtk models use`, else catalog default |
+| REST (local extension) | `"variant": "fp32"` in the request body | server `--variant`, else persisted variant for the current model, else catalog default |
+
+`DecisionModel.variant` and the CLI report the selected variant (`id@variant` in
+`dtk models current`). REST responses expose it under the namespaced
+`x_decision_toolkit.variant` extension; `/v1/decision-models` includes
+`current` and `current_variant`, plus all `variants` and `cached_variants`.
+`variant` is **not** part of TypeSafe or OpenAI; standard clients should omit it
+and rely on the server's `--variant`/persisted default. A server started with
+`--model`/`--variant` reports that default in `/v1/info` and `/ready`.
+
+The variant must have been downloaded before a library call or REST request
+loads it. An unknown variant returns a model-not-found error; a known but
+missing cache entry returns a model-not-downloaded error.
+
 ## Inspect the catalog
 
 ```bash

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/docs/index.md

@@ -18,7 +18,7 @@ PyPI: <https://pypi.org/project/decision-toolkit/>
 
 - [Examples](EXAMPLES.md) — library, REST and CLI.
 - [Core API](CORE.md) — the superset used by every surface.
-- [REST](REST.md) — System One 1.14 + OpenAI Decisions beta.
+- [REST](REST.md) — TypeSafe System One + OpenAI Decisions beta.
 - [CLI](CLI.md) — operational commands and batch workflows.
 - [Variants and quantization](VARIANTS.md) — every catalogued build and how to download/select it.
 - [Operations](OPERATIONS.md) — rate limits, metrics, tracing and runbook.

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "decision-toolkit"
-version = "0.1.6"
+version = "0.2.0"
 description = "Local-first toolkit for open-weights decision models: one ONNX engine, one adapter per model contract, typed choice/yes-no/score decisions with probabilities on CPU."
 readme = "README.md"
 requires-python = ">=3.12"

{decision_toolkit-0.1.6 → decision_toolkit-0.2.0}/src/decision_toolkit/__init__.py

@@ -7,7 +7,7 @@ questions with a calibrated probability for every option, on CPU.
 
 from __future__ import annotations
 
-__version__ = "0.1.6"
+__version__ = "0.2.0"
 
 from .adapters import register_adapter
 from .calibration import brier_score, expected_calibration_error, threshold_sweep