decision-toolkit 0.3.1__tar.gz → 0.4.1__tar.gz

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/CHANGELOG.md

@@ -1,8 +1,32 @@
 # Changelog
 
-All notable changes to this project are documented here. Version `0.3.1` is
+All notable changes to this project are documented here. Version `0.4.1` is
 published on PyPI.
 
+## [0.4.1] — 2026-10-21
+
+Catalog presentation patch: every variant now carries its REST alias
+(`id@variant`) in `dtk models list`, `--json` and `dtk models variants`. Model
+cards include copy-paste loading examples for library, CLI and REST for every
+variant. No model or runtime changes.
+
+## [0.4.0] — 2026-10-21
+
+REST variant-selection correction. Quantizations are selected through standard
+model aliases (`id@variant`), not a non-standard `variant` body field. The same
+REST process can load two variants of one base model in separate registry slots.
+
+### Fixed
+
+- Removed `variant` from System One and OpenAI request bodies; standard clients
+  now see only the public request fields.
+- Added `catalog-id@variant` model aliases to `/v1/models` and
+  `/v1/models/{id}`. The standard `model` field selects the alias.
+- Registry keys and slots are per alias, so `laya-multilingual@fp16` and
+  `laya-multilingual@fp32` load independently and concurrently.
+- Updated README, REST, variants, examples and CLI help so REST never shows a
+  variant field in a standard request body.
+
 ## [0.3.1] — 2026-10-21
 
 Catalog UX patch: `dtk models list` now prints one row per variant, with
@@ -192,6 +216,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.4.1]: https://pypi.org/project/decision-toolkit/0.4.1/
+[0.4.0]: https://pypi.org/project/decision-toolkit/0.4.0/
 [0.3.1]: https://pypi.org/project/decision-toolkit/0.3.1/
 [0.3.0]: https://pypi.org/project/decision-toolkit/0.3.0/
 [0.2.1]: https://pypi.org/project/decision-toolkit/0.2.1/

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: decision-toolkit
-Version: 0.3.1
+Version: 0.4.1
 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.3.1 on PyPI)
+uv pip install decision-toolkit              # library + CLI (0.4.1 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.3.1/>. See
+PyPI: <https://pypi.org/project/decision-toolkit/0.4.1/>. 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.
 
@@ -211,6 +211,9 @@ adapters (there is no generic "any ONNX" adapter).
 | `open-jev-deberta-v3-large` | `open-jev` | **m0** — Open-Jev DeBERTa v3 large repro; 0.854 in-domain (241 ms) | `fp16`* (884 MB); `fp32` (1758 MB); `q4` (487 MB); `q4f16` (357 MB) |
 | `strands-decider-2b` | `strands-decider` | **m0** — reference fixture match (719 ms) | `q4f16`* (1114 MB); `q8` (1821 MB) |
 
+Each variant has a REST alias in the form `id@variant`; `dtk models list` prints
+the alias next to every variant.
+
 **Only `m0` models are in the catalog.** Researched-but-unavailable models
 (planned, conversion pending, broken exports) are listed in
 [docs/ROADMAP.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/ROADMAP.md) and are not downloadable through the toolkit.
@@ -248,11 +251,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")`. 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.
+From Python: `DecisionModel("gliner2.5-multi", variant="fp32")`. In REST,
+quantizations are **model aliases**: use `"model": "gliner2.5-multi@fp32"` in the
+standard `model` field. The base id uses the server/persisted default. There is
+no `variant` field in the request body; `/v1/models` lists both the base model
+and every alias, and two aliases can be loaded concurrently.
 
 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.3.1 → decision_toolkit-0.4.1}/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.3.1 on PyPI)
+uv pip install decision-toolkit              # library + CLI (0.4.1 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.3.1/>. See
+PyPI: <https://pypi.org/project/decision-toolkit/0.4.1/>. 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,6 +173,9 @@ adapters (there is no generic "any ONNX" adapter).
 | `open-jev-deberta-v3-large` | `open-jev` | **m0** — Open-Jev DeBERTa v3 large repro; 0.854 in-domain (241 ms) | `fp16`* (884 MB); `fp32` (1758 MB); `q4` (487 MB); `q4f16` (357 MB) |
 | `strands-decider-2b` | `strands-decider` | **m0** — reference fixture match (719 ms) | `q4f16`* (1114 MB); `q8` (1821 MB) |
 
+Each variant has a REST alias in the form `id@variant`; `dtk models list` prints
+the alias next to every variant.
+
 **Only `m0` models are in the catalog.** Researched-but-unavailable models
 (planned, conversion pending, broken exports) are listed in
 [docs/ROADMAP.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/ROADMAP.md) and are not downloadable through the toolkit.
@@ -210,11 +213,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")`. 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.
+From Python: `DecisionModel("gliner2.5-multi", variant="fp32")`. In REST,
+quantizations are **model aliases**: use `"model": "gliner2.5-multi@fp32"` in the
+standard `model` field. The base id uses the server/persisted default. There is
+no `variant` field in the request body; `/v1/models` lists both the base model
+and every alias, and two aliases can be loaded concurrently.
 
 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.3.1 → decision_toolkit-0.4.1}/docs/CLI.md

@@ -151,6 +151,9 @@ are already downloaded.
 | `open-jev-deberta-v3-large` | `fp16`*, `fp32`, `q4`, `q4f16` | fp16 / fp32 / q4 / q4-fp16 | 883.5 / 1757.9 / 486.7 / 357.0 MB |
 | `strands-decider-2b` | `q4f16`*, `q8` | q4-fp16 / int8 | 1113.6 / 1821.4 MB |
 
+Each row is also addressable over REST as `model = "<id>@<variant>"`; the alias
+is printed by `dtk models list` and by `dtk models variants <id>`.
+
 ```bash
 # inspect, including the exact download command for each variant
 dtk models list --quant

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/EXAMPLES.md

@@ -165,7 +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.
+Use the model alias `id@variant` for a specific quantization; the base id uses
+the server's default. There is no `variant` field in the request body.
 
 ### Model per request and auth
 
@@ -176,8 +177,7 @@ curl -s http://127.0.0.1:8000/v1/systemone \
   -H "Authorization: Bearer secret" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "gliner2.5-decide",
-    "variant": "q4f16",
+    "model": "gliner2.5-multi@fp32",
     "state": "I want my money back.",
     "questions": {
       "intent": {"type": "choice", "instructions": "What is the request?",

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/RELEASE.md

@@ -10,7 +10,9 @@ 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; `0.2.1`
 changed the public documentation URLs to this repository's Pages site; `0.3.0`
-added the Laya multilingual, Open-Jev DeBERTa v3 large and Strands Decider ONNX models; `0.3.1` made the catalog list one row per variant with exact commands.
+added the Laya multilingual, Open-Jev DeBERTa v3 large and Strands Decider ONNX models; `0.3.1` made the catalog list one row per variant with exact commands; `0.4.0`
+replaced the non-standard REST `variant` body field with standard model aliases
+(`id@variant`).
 
 ## Local build and verification
 
@@ -37,7 +39,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.3.1-py3-none-any.whl
+  dist/decision_toolkit-0.4.1-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
@@ -48,7 +50,7 @@ With inference and server extras:
 
 ```bash
 uv pip install --python /tmp/dtk-wheel/bin/python \
-  "dist/decision_toolkit-0.3.1-py3-none-any.whl[onnx,server,tracing]"
+  "dist/decision_toolkit-0.4.1-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
@@ -82,8 +84,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.3.1 -m "decision-toolkit 0.3.1"
-   git push origin v0.3.1
+   git tag -a v0.4.1 -m "decision-toolkit 0.4.1"
+   git push origin v0.4.1
    ```
 
 5. `.github/workflows/release.yml` builds once, publishes to **TestPyPI**, then
@@ -132,9 +134,9 @@ to TestPyPI without publishing to PyPI or creating a GitHub release.
 
 ## Published release
 
-`0.3.1` is published through Trusted Publishing on 2026-10-21:
+`0.4.1` is published through Trusted Publishing on 2026-10-21:
 
-<https://pypi.org/project/decision-toolkit/0.3.1/>
+<https://pypi.org/project/decision-toolkit/0.4.1/>
 
 `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
@@ -144,7 +146,9 @@ published to TestPyPI only; `0.1.5` fixed TestPyPI resolution; `0.1.6` added
 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; `0.2.1` changed the public documentation URLs; `0.3.0`
-added the three new ONNX decision models; `0.3.1` made the catalog list one row per variant.
+added the three new ONNX decision models; `0.3.1` made the catalog list one row per variant; `0.4.0` moved REST variant
+selection to standard model aliases; `0.4.1` exposed aliases in the catalog and
+per-variant loading examples in every model card.
 
 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.3.1 → decision_toolkit-0.4.1}/docs/REST.md

@@ -49,25 +49,25 @@ limitations listed below.
 Toolkit-only metadata is under `x_decision_toolkit`, never mixed into standard
 fields. `/v1/decision-models` is the rich, non-standard catalog endpoint.
 
-## Variants (local extension)
-
-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.
+## Variants as model aliases
+
+Neither TypeSafe nor OpenAI has a `variant` request field. The toolkit therefore
+publishes each quantization as a **model alias**:
+
+```json
+{"model": "gliner2.5-multi@fp32", "state": "...", "questions": {...}}
+```
+
+The `model` field is the standard field. `gliner2.5-multi` uses the server's
+default (or the persisted `dtk models use` selection); `gliner2.5-multi@fp32`
+selects that exact variant. Both aliases are listed by `/v1/models`, and the
+registry loads them in separate slots, so two variants of one base model can be
+used by the same server process.
+
+`/v1/models/gliner2.5-multi@fp32`, `/v1/decision-models`, `/v1/info` and `/ready`
+expose the alias, variant, default, cached state and current selection. The
+response metadata under `x_decision_toolkit.variant` is an extension; the
+request body remains standard. See [Variants and quantization](VARIANTS.md).
 
 ## System One (TypeSafe API schema 0.2.0)
 

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/VARIANTS.md

@@ -18,23 +18,23 @@ have not passed the catalog gates are not exposed as variants.
 A `*` marks the default variant. It is used when `--variant` is omitted and no
 other variant was selected with `dtk models use`.
 
-| Model | Variant | Quantization | Size | Role | Download |
-| --- | --- | --- | ---: | --- | --- |
-| `gliner2.5-multi` | `fp16` * | fp16 encoder + fp32 classifier | 577.1 MB | default | `dtk models download gliner2.5-multi --variant fp16` |
-| `gliner2.5-multi` | `fp32` | fp32 encoder + fp32 classifier | 1131.9 MB | quality | `dtk models download gliner2.5-multi --variant fp32` |
-| `gliner2.5-decide` | `q4f16` * | q4/fp16 | 523.5 MB | default | `dtk models download gliner2.5-decide --variant q4f16` |
-| `laya` | `q8` * | int8 | 527.9 MB | default | `dtk models download laya --variant q8` |
-| `julia-1` | `fp32` * | fp32 | 618.2 MB | default | `dtk models download julia-1 --variant fp32` |
-| `opendecider-nano` | `q8f16` * | int8/fp16 | 468.8 MB | default | `dtk models download opendecider-nano --variant q8f16` |
-| `opendecider-nano` | `fp16` | fp16 | 791.9 MB | quality | `dtk models download opendecider-nano --variant fp16` |
-| `laya-multilingual` | `fp16` * | fp16 | 681.8 MB | default | `dtk models download laya-multilingual --variant fp16` |
-| `laya-multilingual` | `fp32` | fp32 | 1325.6 MB | quality | `dtk models download laya-multilingual --variant fp32` |
-| `open-jev-deberta-v3-large` | `fp16` * | fp16 | 883.5 MB | default | `dtk models download open-jev-deberta-v3-large --variant fp16` |
-| `open-jev-deberta-v3-large` | `fp32` | fp32 | 1757.9 MB | quality | `dtk models download open-jev-deberta-v3-large --variant fp32` |
-| `open-jev-deberta-v3-large` | `q4` | q4 | 486.7 MB | edge | `dtk models download open-jev-deberta-v3-large --variant q4` |
-| `open-jev-deberta-v3-large` | `q4f16` | q4/fp16 | 357.0 MB | edge | `dtk models download open-jev-deberta-v3-large --variant q4f16` |
-| `strands-decider-2b` | `q4f16` * | q4/fp16 | 1113.6 MB | default | `dtk models download strands-decider-2b --variant q4f16` |
-| `strands-decider-2b` | `q8` | int8 | 1821.4 MB | quality | `dtk models download strands-decider-2b --variant q8` |
+| Model | Variant | REST alias | Quantization | Size | Role | Download |
+| --- | --- | --- | --- | ---: | --- | --- |
+| `gliner2.5-multi` | `fp16` * | `gliner2.5-multi@fp16` | fp16 | 577.1 MB | default | `dtk models download gliner2.5-multi --variant fp16` |
+| `gliner2.5-multi` | `fp32` | `gliner2.5-multi@fp32` | fp32 | 1131.9 MB | quality | `dtk models download gliner2.5-multi --variant fp32` |
+| `gliner2.5-decide` | `q4f16` * | `gliner2.5-decide@q4f16` | q4/fp16 | 523.5 MB | default | `dtk models download gliner2.5-decide --variant q4f16` |
+| `laya` | `q8` * | `laya@q8` | int8 | 527.9 MB | default | `dtk models download laya --variant q8` |
+| `julia-1` | `fp32` * | `julia-1@fp32` | fp32 | 618.2 MB | default | `dtk models download julia-1 --variant fp32` |
+| `opendecider-nano` | `q8f16` * | `opendecider-nano@q8f16` | int8/fp16 | 468.8 MB | default | `dtk models download opendecider-nano --variant q8f16` |
+| `opendecider-nano` | `fp16` | `opendecider-nano@fp16` | fp16 | 791.9 MB | quality | `dtk models download opendecider-nano --variant fp16` |
+| `laya-multilingual` | `fp16` * | `laya-multilingual@fp16` | fp16 | 681.8 MB | default | `dtk models download laya-multilingual --variant fp16` |
+| `laya-multilingual` | `fp32` | `laya-multilingual@fp32` | fp32 | 1325.6 MB | quality | `dtk models download laya-multilingual --variant fp32` |
+| `open-jev-deberta-v3-large` | `q4f16` | `open-jev-deberta-v3-large@q4f16` | q4/fp16 | 357.0 MB | edge | `dtk models download open-jev-deberta-v3-large --variant q4f16` |
+| `open-jev-deberta-v3-large` | `fp16` * | `open-jev-deberta-v3-large@fp16` | fp16 | 883.5 MB | default | `dtk models download open-jev-deberta-v3-large --variant fp16` |
+| `open-jev-deberta-v3-large` | `q4` | `open-jev-deberta-v3-large@q4` | q4 | 486.7 MB | edge | `dtk models download open-jev-deberta-v3-large --variant q4` |
+| `open-jev-deberta-v3-large` | `fp32` | `open-jev-deberta-v3-large@fp32` | fp32 | 1757.9 MB | quality | `dtk models download open-jev-deberta-v3-large --variant fp32` |
+| `strands-decider-2b` | `q4f16` * | `strands-decider-2b@q4f16` | q4/fp16 | 1113.6 MB | default | `dtk models download strands-decider-2b --variant q4f16` |
+| `strands-decider-2b` | `q8` | `strands-decider-2b@q8` | int8 | 1821.4 MB | quality | `dtk models download strands-decider-2b --variant q8` |
 
 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
@@ -45,8 +45,8 @@ the parity, hash and license gates for this catalog.
 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);
+1. an explicit per-call variant in the library or CLI
+   (`DecisionModel(..., variant=...)`, `--variant`);
 2. the CLI/server configuration (`dtk models use`, or `dtk serve --variant`);
 3. the catalog default marked with `*`.
 
@@ -54,17 +54,18 @@ precedence is:
 | --- | --- | --- |
 | 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 |
+| REST | `"model": "gliner2.5-multi@fp32"` (model alias) | base model id; server `--variant`/persisted 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
+`variant` is **not** part of TypeSafe or OpenAI, and standard REST clients must
+not send it. They select only `model`; the local server chooses the quantization
+from `--variant` or the 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
+The variant must have been downloaded before a library call or REST alias
 loads it. An unknown variant returns a model-not-found error; a known but
 missing cache entry returns a model-not-downloaded error.
 
@@ -162,14 +163,18 @@ from decision_toolkit import DecisionModel
 model = DecisionModel("gliner2.5-multi", variant="fp32")
 ```
 
-From REST, send the variant in the request body:
+For REST, select a quantization through the standard `model` field using the
+alias `id@variant`:
 
 ```json
-{"model": "gliner2.5-multi", "variant": "fp32", "state": "...",
- "questions": {"cat": {"type": "choice", "instructions": "What kind?",
-                       "criteria": {"meeting": null, "other": null}}}}
+{"model": "gliner2.5-multi@fp32", "state": "...", "questions": {}}
 ```
 
+The base id (`gliner2.5-multi`) uses the server `--variant`/persisted default.
+`/v1/models` lists base models and every alias, and the registry can hold two
+aliases of the same base model in separate slots. Do not add a `variant` field
+to the request body.
+
 The variant must already be downloaded. If you name an unknown variant, the
 error lists the catalogued choices, for example:
 

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/models/gliner2.5-decide.md

@@ -54,6 +54,40 @@ in the toolkit; see [Variants and quantization](../VARIANTS.md).
 - Quantized q4f16; the fp16/fp32 builds may resolve the sentiment example differently.
 - The model card's examples are "potential outputs", not guarantees; validate on your data.
 
+## Loading each variant
+
+REST selects the quantization through the standard `model` field using the
+alias `gliner2.5-decide@variant`; there is no `variant` field in the request body.
+
+### `q4f16` (q4/fp16, default)
+
+**Library**
+
+```python
+from decision_toolkit import DecisionModel
+
+model = DecisionModel("gliner2.5-decide", variant="q4f16")
+```
+
+**CLI**
+
+```bash
+dtk models download gliner2.5-decide --variant q4f16
+dtk models use gliner2.5-decide --variant q4f16
+dtk decide --model gliner2.5-decide --variant q4f16 \
+  --state "..." --q 'urgent=noul:Is this urgent?'
+```
+
+**REST**
+
+```bash
+curl -s http://127.0.0.1:8000/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{"model": "gliner2.5-decide@q4f16", "state": "...",
+       "questions": {"urgent": {"type": "noul",
+                     "instructions": "Is this urgent?"}}}}'
+```
+
 ## Usage
 
 ```bash

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/models/gliner2.5-multi.md

@@ -55,6 +55,69 @@ makes it persistent. See [Variants and quantization](../VARIANTS.md).
 - English/multilingual tokenizer fallback: the run above used the raw `tokenizers` fallback; a `transformers` tokenizer may change scores slightly.
 - Benchmarked on a synthetic Spanish routing set; validate on your own data.
 
+## Loading each variant
+
+REST selects the quantization through the standard `model` field using the
+alias `gliner2.5-multi@variant`; there is no `variant` field in the request body.
+
+### `fp16` (fp16, default)
+
+**Library**
+
+```python
+from decision_toolkit import DecisionModel
+
+model = DecisionModel("gliner2.5-multi", variant="fp16")
+```
+
+**CLI**
+
+```bash
+dtk models download gliner2.5-multi --variant fp16
+dtk models use gliner2.5-multi --variant fp16
+dtk decide --model gliner2.5-multi --variant fp16 \
+  --state "..." --q 'urgent=noul:Is this urgent?'
+```
+
+**REST**
+
+```bash
+curl -s http://127.0.0.1:8000/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{"model": "gliner2.5-multi@fp16", "state": "...",
+       "questions": {"urgent": {"type": "noul",
+                     "instructions": "Is this urgent?"}}}}'
+```
+
+### `fp32` (fp32, quality)
+
+**Library**
+
+```python
+from decision_toolkit import DecisionModel
+
+model = DecisionModel("gliner2.5-multi", variant="fp32")
+```
+
+**CLI**
+
+```bash
+dtk models download gliner2.5-multi --variant fp32
+dtk models use gliner2.5-multi --variant fp32
+dtk decide --model gliner2.5-multi --variant fp32 \
+  --state "..." --q 'urgent=noul:Is this urgent?'
+```
+
+**REST**
+
+```bash
+curl -s http://127.0.0.1:8000/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{"model": "gliner2.5-multi@fp32", "state": "...",
+       "questions": {"urgent": {"type": "noul",
+                     "instructions": "Is this urgent?"}}}}'
+```
+
 ## Usage
 
 ```bash

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/models/julia-1.md

@@ -55,6 +55,40 @@ exists but was not validated and is not catalogued; see
 - Historical benchmarks used 1024 tokens; accuracy at 8k is not established by the export.
 - The tokenizer uses `<mask>/<bos>/<eos>`; both conventions are handled, but this checkpoint's tokenizer is the `<...>` one.
 
+## Loading each variant
+
+REST selects the quantization through the standard `model` field using the
+alias `julia-1@variant`; there is no `variant` field in the request body.
+
+### `fp32` (fp32, default)
+
+**Library**
+
+```python
+from decision_toolkit import DecisionModel
+
+model = DecisionModel("julia-1", variant="fp32")
+```
+
+**CLI**
+
+```bash
+dtk models download julia-1 --variant fp32
+dtk models use julia-1 --variant fp32
+dtk decide --model julia-1 --variant fp32 \
+  --state "..." --q 'urgent=noul:Is this urgent?'
+```
+
+**REST**
+
+```bash
+curl -s http://127.0.0.1:8000/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{"model": "julia-1@fp32", "state": "...",
+       "questions": {"urgent": {"type": "noul",
+                     "instructions": "Is this urgent?"}}}}'
+```
+
 ## Usage
 
 ```bash

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/models/laya-multilingual.md

@@ -68,6 +68,69 @@ the full-precision build. Select one with
 - The adapter uses the fused graph path; the English split checkpoint remains a
   separate catalog entry (`laya`).
 
+## Loading each variant
+
+REST selects the quantization through the standard `model` field using the
+alias `laya-multilingual@variant`; there is no `variant` field in the request body.
+
+### `fp16` (fp16, default)
+
+**Library**
+
+```python
+from decision_toolkit import DecisionModel
+
+model = DecisionModel("laya-multilingual", variant="fp16")
+```
+
+**CLI**
+
+```bash
+dtk models download laya-multilingual --variant fp16
+dtk models use laya-multilingual --variant fp16
+dtk decide --model laya-multilingual --variant fp16 \
+  --state "..." --q 'urgent=noul:Is this urgent?'
+```
+
+**REST**
+
+```bash
+curl -s http://127.0.0.1:8000/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{"model": "laya-multilingual@fp16", "state": "...",
+       "questions": {"urgent": {"type": "noul",
+                     "instructions": "Is this urgent?"}}}}'
+```
+
+### `fp32` (fp32, quality)
+
+**Library**
+
+```python
+from decision_toolkit import DecisionModel
+
+model = DecisionModel("laya-multilingual", variant="fp32")
+```
+
+**CLI**
+
+```bash
+dtk models download laya-multilingual --variant fp32
+dtk models use laya-multilingual --variant fp32
+dtk decide --model laya-multilingual --variant fp32 \
+  --state "..." --q 'urgent=noul:Is this urgent?'
+```
+
+**REST**
+
+```bash
+curl -s http://127.0.0.1:8000/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{"model": "laya-multilingual@fp32", "state": "...",
+       "questions": {"urgent": {"type": "noul",
+                     "instructions": "Is this urgent?"}}}}'
+```
+
 ## Usage
 
 ```bash

{decision_toolkit-0.3.1 → decision_toolkit-0.4.1}/docs/models/laya.md

@@ -61,6 +61,40 @@ fp32 build; see [Variants and quantization](../VARIANTS.md).
 - **English checkpoint.** The multilingual checkpoint is a different model (mmBERT-base) and has no split public export yet.
 - q8 quantization; the fp32 build was not published in this repo.
 
+## Loading each variant
+
+REST selects the quantization through the standard `model` field using the
+alias `laya@variant`; there is no `variant` field in the request body.
+
+### `q8` (int8, default)
+
+**Library**
+
+```python
+from decision_toolkit import DecisionModel
+
+model = DecisionModel("laya", variant="q8")
+```
+
+**CLI**
+
+```bash
+dtk models download laya --variant q8
+dtk models use laya --variant q8
+dtk decide --model laya --variant q8 \
+  --state "..." --q 'urgent=noul:Is this urgent?'
+```
+
+**REST**
+
+```bash
+curl -s http://127.0.0.1:8000/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{"model": "laya@q8", "state": "...",
+       "questions": {"urgent": {"type": "noul",
+                     "instructions": "Is this urgent?"}}}}'
+```
+
 ## Usage
 
 ```bash