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

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

@@ -1,8 +1,27 @@
 # Changelog
 
-All notable changes to this project are documented here. Version `0.4.1` is
+All notable changes to this project are documented here. Version `0.4.3` is
 published on PyPI.
 
+## [0.4.3] — 2026-10-21
+
+Documentation and help UX improvements. Added a Quickstart, Installation guide,
+Models/cache guide, Library guide, Troubleshooting, FAQ, Glossary and Recipes;
+reorganized the documentation navigation around user tasks; added CLI option
+tables and examples; corrected the README REST alias text; clarified that the
+server extra is installed as `[onnx,server]`. The CLI now suggests the exact
+download/use commands for an empty cache, marks current/cached catalog rows, and
+reports user-facing catalog counts in `dtk doctor`. Public model metadata uses
+`available` instead of an internal status label. No inference, model, or catalog
+content changes.
+
+## [0.4.2] — 2026-10-21
+
+Documentation cleanup: removed internal project language (`m0`, phase numbers,
+waitlist), removed the public catalog proposal and roadmap pages, and rewrote
+the model-card index for users. Every model card now includes library, CLI and
+REST snippets for every variant. No runtime changes.
+
 ## [0.4.1] — 2026-10-21
 
 Catalog presentation patch: every variant now carries its REST alias
@@ -216,6 +235,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.3]: https://pypi.org/project/decision-toolkit/0.4.3/
+[0.4.2]: https://pypi.org/project/decision-toolkit/0.4.2/
 [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/

{decision_toolkit-0.4.1 → decision_toolkit-0.4.3}/CONTRIBUTING.md

@@ -76,9 +76,11 @@ uv run dtk --version
 uv run pip-audit                # dependency scan (CI runs this)
 ```
 
-CI runs these on Python 3.12 and 3.13, plus `pip-audit`. The tag-triggered
-release workflow builds and publishes the wheel with uv; see
-[RELEASE.md](docs/RELEASE.md). For rate limits, metrics, tracing and the load
+CI runs these on Python 3.12 and 3.13, plus `pip-audit`. `tests/test_help_examples.py`
+parses every example printed by `dtk --help` and checks referenced catalog
+models/variants; run the full examples against a populated cache before a
+release. The tag-triggered release workflow builds and publishes the wheel with
+uv; see [RELEASE.md](docs/RELEASE.md). For rate limits, metrics, tracing and the load
 probe see [OPERATIONS.md](docs/OPERATIONS.md).
 
 ## Commits

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: decision-toolkit
-Version: 0.4.1
+Version: 0.4.3
 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
@@ -50,24 +50,27 @@ One **ONNX engine** (`onnxruntime`), in-process, on CPU. One **adapter per model
 contract** (how a model is fed and read). Three thin surfaces over the same API:
 **library**, **CLI** and **REST**.
 
-Co-developed by [GIA-UH](https://github.com/gia-uh) and [Syalia S.R.L.](https://github.com/syalia-srl).
+**Co-developed by [GIA-UH](https://github.com/gia-uh) and [Syalia S.R.L.](https://github.com/syalia-srl).**
 
 **Documentation:** <https://gia-uh.github.io/decision-toolkit/>. Start with
-[Examples](https://gia-uh.github.io/decision-toolkit/EXAMPLES/) for the library, REST
+[Quickstart](https://gia-uh.github.io/decision-toolkit/QUICKSTART/) for the library, REST
 and CLI. `dtk --help` and every subcommand help also include runnable examples.
+See [Models](https://gia-uh.github.io/decision-toolkit/MODELS/) for the cache and
+variants, and [Troubleshooting](https://gia-uh.github.io/decision-toolkit/TROUBLESHOOTING/)
+when a command fails.
 
 ## Installation
 
 ```bash
-uv pip install decision-toolkit              # library + CLI (0.4.1 on PyPI)
+uv pip install decision-toolkit              # library + CLI; add [onnx] to run models
 uv pip install "decision-toolkit[onnx]"      # + onnxruntime, tokenizers (the model runtime)
-uv pip install "decision-toolkit[server]"    # + REST server (FastAPI)
+uv pip install "decision-toolkit[onnx,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.4.1/>. See
+PyPI: <https://pypi.org/project/decision-toolkit/0.4.3/>. 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,7 +138,7 @@ decision.truncated, decision.warnings
 validated before inference (`box`/assets are rejected by text-only models).
 Custom adapters can be registered with `register_adapter`; local ONNX models
 can be opened with `DecisionModel.from_onnx(...)`. See
-[docs/CORE.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/CORE.md) for the full phase 1 contract, error taxonomy,
+[docs/CORE.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/CORE.md) for the full API contract, error taxonomy,
 logging events and the expressiveness inventory.
 
 **2. As a CLI**
@@ -167,7 +170,7 @@ batch, custom `--adapter/--files`, config and completion.
 **3. As a REST service (optional extra)**
 
 ```bash
-uv pip install "decision-toolkit[server]"
+uv pip install "decision-toolkit[onnx,server]"
 dtk serve --model gliner2.5-multi --warmup \
   --api-key "$DECISION_TOOLKIT_API_KEY" \
   --log-format json
@@ -176,8 +179,9 @@ dtk serve --model gliner2.5-multi --warmup \
 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 select `model`; `variant` is a documented local extension,
-not part of either public API. System One request validation uses the TypeSafe
+`GET /ready`. Requests select `model`; quantization is selected with the model
+alias `id@variant` (for example `gliner2.5-multi@fp32`). There is no `variant`
+field in either public request body. 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
@@ -186,38 +190,26 @@ 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.
 
-## The catalog is curated
+## Models and variants
 
-The catalog is **ours**, not a mirror of HuggingFace. A model enters only when it
-is understood and verified:
+The catalog lists models that are runnable with the toolkit today. Every entry
+has a real ONNX export, verified files and measured behavior; nothing is listed
+as a placeholder.
 
-1. clean commercial license;
-2. an adapter whose contract we can implement **from a real export**;
-3. a real ONNX export on the Hub;
-4. measured parity against the original on a fixed sample;
-5. CPU-viable latency.
-
-Every variant points to files that exist. No placeholders, no speculative
-adapters (there is no generic "any ONNX" adapter).
-
-| id | adapter | status | variants (default *) |
+| id | adapter | verification | variants (default *) |
 | --- | --- | --- | --- |
-| `gliner2.5-multi` | `gliner2` | **m0** — verified end-to-end (9/15, 353 ms) | `fp16`* (577 MB); `fp32` (1132 MB) |
-| `gliner2.5-decide` | `gliner2-decide` | **m0** — fused export verified (refund 0.944, 912 ms; English-only) | `q4f16`* (524 MB) |
-| `laya` | `laya` | **m0** — verified against torch (Δp ≤ 0.005) | `q8`* (528 MB) |
-| `julia-1` | `julia` | **m0** — verified: 100/100 argmax parity, 329 ms | `fp32`* (618 MB) |
-| `opendecider-nano` | `opendecider` | **m0** — official build; prompt ported from pinned code (530 ms) | `q8f16`* (469 MB); `fp16` (792 MB) |
-| `laya-multilingual` | `laya` | **m0** — fused ONNX; upstream parity (37 ms) | `fp16`* (682 MB); `fp32` (1326 MB) |
-| `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) |
+| `gliner2.5-multi` | `gliner2` | verified end-to-end (9/15, 353 ms) | `fp16`* (577 MB); `fp32` (1132 MB) |
+| `gliner2.5-decide` | `gliner2-decide` | fused export verified (refund 0.944, 912 ms; English-only) | `q4f16`* (524 MB) |
+| `laya` | `laya` | verified against torch (Δp ≤ 0.005) | `q8`* (528 MB) |
+| `julia-1` | `julia` | verified: 100/100 argmax parity, 329 ms | `fp32`* (618 MB) |
+| `opendecider-nano` | `opendecider` | official build; prompt ported from pinned code (530 ms) | `q8f16`* (469 MB); `fp16` (792 MB) |
+| `laya-multilingual` | `laya` | fused ONNX; upstream parity (37 ms) | `fp16`* (682 MB); `fp32` (1326 MB) |
+| `open-jev-deberta-v3-large` | `open-jev` | Open-Jev DeBERTa v3 large reproduction; 0.854 in-domain (241 ms) | `fp16`* (884 MB); `fp32` (1758 MB); `q4` (487 MB); `q4f16` (357 MB) |
+| `strands-decider-2b` | `strands-decider` | 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.
-
 Per-model cards with the contract, measured evidence and known limitations:
 [docs/models](https://github.com/gia-uh/decision-toolkit/tree/main/docs/models).
 
@@ -229,7 +221,7 @@ own repo files, size and role. A `*` in the table above marks the default.
 
 ```bash
 dtk models list                      # one row per variant; * = default
-dtk models list --quant              # add the quantization labels
+dtk models list --quant              # accepted for compatibility; quant is always shown
 dtk models variants gliner2.5-multi  # full details for one model
 ```
 
@@ -257,7 +249,7 @@ 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%,
+A variant becomes default only after passing the verification criteria (top-1 ≥ 99%,
 mean |Δp| ≤ 0.02, accuracy delta ≤ 1 pp against the fp32 build on a fixed
 sample) and measuring latency on CPU. Unverified conversions are not catalogued
 and never become a silent fallback. See [Variants and quantization](https://gia-uh.github.io/decision-toolkit/VARIANTS/)
@@ -303,7 +295,7 @@ See [CHANGELOG.md](https://github.com/gia-uh/decision-toolkit/blob/main/CHANGELO
 
 ## Custom ONNX (at your own risk)
 
-You can run any ONNX file with an adapter you trust — outside the curated
+You can run any ONNX file with an adapter you trust — outside the
 catalog:
 
 ```python
@@ -324,7 +316,7 @@ register_adapter("my-layout", MyAdapter)
 ```
 
 Custom models do not appear in `dtk models list`; the toolkit never guesses a
-layout. If a model deserves support, it goes through curation.
+layout. If a model deserves support, it goes through catalog review.
 
 ## Development
 

{decision_toolkit-0.4.1 → decision_toolkit-0.4.3}/README.md

@@ -12,24 +12,27 @@ One **ONNX engine** (`onnxruntime`), in-process, on CPU. One **adapter per model
 contract** (how a model is fed and read). Three thin surfaces over the same API:
 **library**, **CLI** and **REST**.
 
-Co-developed by [GIA-UH](https://github.com/gia-uh) and [Syalia S.R.L.](https://github.com/syalia-srl).
+**Co-developed by [GIA-UH](https://github.com/gia-uh) and [Syalia S.R.L.](https://github.com/syalia-srl).**
 
 **Documentation:** <https://gia-uh.github.io/decision-toolkit/>. Start with
-[Examples](https://gia-uh.github.io/decision-toolkit/EXAMPLES/) for the library, REST
+[Quickstart](https://gia-uh.github.io/decision-toolkit/QUICKSTART/) for the library, REST
 and CLI. `dtk --help` and every subcommand help also include runnable examples.
+See [Models](https://gia-uh.github.io/decision-toolkit/MODELS/) for the cache and
+variants, and [Troubleshooting](https://gia-uh.github.io/decision-toolkit/TROUBLESHOOTING/)
+when a command fails.
 
 ## Installation
 
 ```bash
-uv pip install decision-toolkit              # library + CLI (0.4.1 on PyPI)
+uv pip install decision-toolkit              # library + CLI; add [onnx] to run models
 uv pip install "decision-toolkit[onnx]"      # + onnxruntime, tokenizers (the model runtime)
-uv pip install "decision-toolkit[server]"    # + REST server (FastAPI)
+uv pip install "decision-toolkit[onnx,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.4.1/>. See
+PyPI: <https://pypi.org/project/decision-toolkit/0.4.3/>. 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.
 
@@ -97,7 +100,7 @@ decision.truncated, decision.warnings
 validated before inference (`box`/assets are rejected by text-only models).
 Custom adapters can be registered with `register_adapter`; local ONNX models
 can be opened with `DecisionModel.from_onnx(...)`. See
-[docs/CORE.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/CORE.md) for the full phase 1 contract, error taxonomy,
+[docs/CORE.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/CORE.md) for the full API contract, error taxonomy,
 logging events and the expressiveness inventory.
 
 **2. As a CLI**
@@ -129,7 +132,7 @@ batch, custom `--adapter/--files`, config and completion.
 **3. As a REST service (optional extra)**
 
 ```bash
-uv pip install "decision-toolkit[server]"
+uv pip install "decision-toolkit[onnx,server]"
 dtk serve --model gliner2.5-multi --warmup \
   --api-key "$DECISION_TOOLKIT_API_KEY" \
   --log-format json
@@ -138,8 +141,9 @@ dtk serve --model gliner2.5-multi --warmup \
 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 select `model`; `variant` is a documented local extension,
-not part of either public API. System One request validation uses the TypeSafe
+`GET /ready`. Requests select `model`; quantization is selected with the model
+alias `id@variant` (for example `gliner2.5-multi@fp32`). There is no `variant`
+field in either public request body. 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
@@ -148,38 +152,26 @@ 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.
 
-## The catalog is curated
+## Models and variants
 
-The catalog is **ours**, not a mirror of HuggingFace. A model enters only when it
-is understood and verified:
+The catalog lists models that are runnable with the toolkit today. Every entry
+has a real ONNX export, verified files and measured behavior; nothing is listed
+as a placeholder.
 
-1. clean commercial license;
-2. an adapter whose contract we can implement **from a real export**;
-3. a real ONNX export on the Hub;
-4. measured parity against the original on a fixed sample;
-5. CPU-viable latency.
-
-Every variant points to files that exist. No placeholders, no speculative
-adapters (there is no generic "any ONNX" adapter).
-
-| id | adapter | status | variants (default *) |
+| id | adapter | verification | variants (default *) |
 | --- | --- | --- | --- |
-| `gliner2.5-multi` | `gliner2` | **m0** — verified end-to-end (9/15, 353 ms) | `fp16`* (577 MB); `fp32` (1132 MB) |
-| `gliner2.5-decide` | `gliner2-decide` | **m0** — fused export verified (refund 0.944, 912 ms; English-only) | `q4f16`* (524 MB) |
-| `laya` | `laya` | **m0** — verified against torch (Δp ≤ 0.005) | `q8`* (528 MB) |
-| `julia-1` | `julia` | **m0** — verified: 100/100 argmax parity, 329 ms | `fp32`* (618 MB) |
-| `opendecider-nano` | `opendecider` | **m0** — official build; prompt ported from pinned code (530 ms) | `q8f16`* (469 MB); `fp16` (792 MB) |
-| `laya-multilingual` | `laya` | **m0** — fused ONNX; upstream parity (37 ms) | `fp16`* (682 MB); `fp32` (1326 MB) |
-| `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) |
+| `gliner2.5-multi` | `gliner2` | verified end-to-end (9/15, 353 ms) | `fp16`* (577 MB); `fp32` (1132 MB) |
+| `gliner2.5-decide` | `gliner2-decide` | fused export verified (refund 0.944, 912 ms; English-only) | `q4f16`* (524 MB) |
+| `laya` | `laya` | verified against torch (Δp ≤ 0.005) | `q8`* (528 MB) |
+| `julia-1` | `julia` | verified: 100/100 argmax parity, 329 ms | `fp32`* (618 MB) |
+| `opendecider-nano` | `opendecider` | official build; prompt ported from pinned code (530 ms) | `q8f16`* (469 MB); `fp16` (792 MB) |
+| `laya-multilingual` | `laya` | fused ONNX; upstream parity (37 ms) | `fp16`* (682 MB); `fp32` (1326 MB) |
+| `open-jev-deberta-v3-large` | `open-jev` | Open-Jev DeBERTa v3 large reproduction; 0.854 in-domain (241 ms) | `fp16`* (884 MB); `fp32` (1758 MB); `q4` (487 MB); `q4f16` (357 MB) |
+| `strands-decider-2b` | `strands-decider` | 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.
-
 Per-model cards with the contract, measured evidence and known limitations:
 [docs/models](https://github.com/gia-uh/decision-toolkit/tree/main/docs/models).
 
@@ -191,7 +183,7 @@ own repo files, size and role. A `*` in the table above marks the default.
 
 ```bash
 dtk models list                      # one row per variant; * = default
-dtk models list --quant              # add the quantization labels
+dtk models list --quant              # accepted for compatibility; quant is always shown
 dtk models variants gliner2.5-multi  # full details for one model
 ```
 
@@ -219,7 +211,7 @@ 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%,
+A variant becomes default only after passing the verification criteria (top-1 ≥ 99%,
 mean |Δp| ≤ 0.02, accuracy delta ≤ 1 pp against the fp32 build on a fixed
 sample) and measuring latency on CPU. Unverified conversions are not catalogued
 and never become a silent fallback. See [Variants and quantization](https://gia-uh.github.io/decision-toolkit/VARIANTS/)
@@ -265,7 +257,7 @@ See [CHANGELOG.md](https://github.com/gia-uh/decision-toolkit/blob/main/CHANGELO
 
 ## Custom ONNX (at your own risk)
 
-You can run any ONNX file with an adapter you trust — outside the curated
+You can run any ONNX file with an adapter you trust — outside the
 catalog:
 
 ```python
@@ -286,7 +278,7 @@ register_adapter("my-layout", MyAdapter)
 ```
 
 Custom models do not appear in `dtk models list`; the toolkit never guesses a
-layout. If a model deserves support, it goes through curation.
+layout. If a model deserves support, it goes through catalog review.
 
 ## Development
 

{decision_toolkit-0.4.1 → decision_toolkit-0.4.3}/docs/BENCH.md

@@ -66,7 +66,7 @@ and
 The model cards retain the historical cold-start measurements used when each
 variant was admitted. The harness reports **post-warmup steady-state** latency,
 which is lower. Compare like with like: use the harness when comparing commits
-or machines; use the card values only as historical admission evidence.
+or machines; use the card values only as historical reference measurements.
 
 ## Adding a case
 

{decision_toolkit-0.4.1 → decision_toolkit-0.4.3}/docs/CLI.md

@@ -1,15 +1,40 @@
-# CLI (phase 3)
+# CLI
 
 `dtk` is our own operational surface. Unlike REST, it has **no external
 standard** to comply with: it is consistent with itself, script-friendly, and a
 thin adapter over the programmatic core. Inference logic never lives in the
 CLI.
 
+## Invocation
+
+```text
+dtk [global options] <command> [command options]
+```
+
+Global options must come **before** the command. This matters for `--home`:
+
+```bash
+dtk --home /data/dtk-home models list
+```
+
+| Global option | Meaning |
+| --- | --- |
+| `--home DIR` | Toolkit home (models cache + config). Default: `~/.local/share/decision-toolkit`. |
+| `-q, --quiet` | Suppress informational output. |
+| `-v, --verbose` | Debug logs and tracebacks on stderr. |
+| `--log-level LEVEL` | `DEBUG`, `INFO`, `WARNING` or `ERROR`. |
+| `--log-format FORMAT` | `text` or `json`. |
+| `--no-color` | Disable colors (accepted for scripts). |
+| `--version` | Print the toolkit version. |
+
+Only `dtk models download` uses the network. The model must already be cached
+for inference.
+
 ## Command map
 
 | Command | Purpose |
 | --- | --- |
-| `dtk models` | Inspect the local cache and the curated catalog. |
+| `dtk models` | Inspect the local cache and the model catalog. |
 | `dtk models list` | Every catalog variant, default (`*`) and cached variants (`--license`, `--quant`, `--adapter`). |
 | `dtk models variants <id>` | Every real variant of one model, with size, role and exact install command. |
 | `dtk models download <id>` | Download the default or `--variant` quantization (`--force`, `--dry-run`). |
@@ -26,6 +51,95 @@ CLI.
 | `dtk version` | Version information. |
 | `dtk completion` | Bash/zsh/fish completion snippet. |
 
+## Command options
+
+### Models
+
+`dtk models` without a subcommand lists the cached entries. `dtk models list`
+shows the catalog even when the cache is empty.
+
+| Command | Important options |
+| --- | --- |
+| `dtk models list` | `--quant`, `--adapter`, `--license`, `--json` |
+| `dtk models variants <id>` | `--json` |
+| `dtk models download <id>` | `--variant NAME`, `--revision REV`, `--force`, `--dry-run`, `--json` |
+| `dtk models use <id>` | `--variant NAME`, `--json` |
+| `dtk models current` | `--json` |
+| `dtk models delete <id>` | `--variant NAME`, `--all-variants`, `--yes`, `--json` |
+| `dtk models verify [id]` | `--variant NAME`, `--all`, `--json` |
+| `dtk models import <path>` | `--name NAME`, `--adapter NAME`, `--files ROLE=PATH`, `--json` |
+
+`download` does not activate a variant; `use` persists the selection.
+`--variant` on `decide`, `classify` or `serve` overrides it for one command.
+
+### Decide
+
+| Option | Meaning |
+| --- | --- |
+| `--model ID` | Catalog id or cached model path (default: current model). |
+| `--variant NAME` | Variant/quantization for this command. |
+| `-s, --state TEXT` | State as text. |
+| `--state-file FILE` | Read the state from a file (`-` for stdin; JSON files are sent as JSON). |
+| `--input-jsonl FILE` | Batch input, one state per line (`-` for stdin). |
+| `--q NAME=SPEC` | Repeatable shorthand question. |
+| `--questions-file FILE` | JSON/YAML question mapping. |
+| `--output-jsonl FILE` | Batch output (`-` for stdout). |
+| `--batch-size N` | JSONL chunk size (default 32). |
+| `--strict` | Fail instead of returning truncated answers. |
+| `--json` | Print JSON (the default output). |
+| `--pretty` | Indent JSON output. |
+
+### Classify
+
+| Option | Meaning |
+| --- | --- |
+| `--model ID` | Catalog id or cached model path. |
+| `--variant NAME` | Variant for this command. |
+| `-t, --text TEXT` | Text to classify. |
+| `--text-file FILE` | Read text from a file (`-` for stdin). |
+| `--labels L1,L2,...` | Comma-separated labels. |
+| `--labels-file FILE` | YAML `labels: {name: description}` mapping. |
+| `--instructions TEXT` | Custom question text. |
+| `--threshold FLOAT` | Flag results below it (default 0.5). |
+| `--top-k N` | Number of ranked labels to show (default 3). |
+| `--json` | Machine-readable output. |
+
+### Serve
+
+| Option | Meaning |
+| --- | --- |
+| `--model ID`, `--variant NAME` | Default model for the process. |
+| `--host HOST`, `--port PORT` | Bind address and port (default `127.0.0.1:8000`). |
+| `--workers N` | Uvicorn worker processes. |
+| `--reload` | Development reload; cannot combine with `--workers > 1`. |
+| `--api-key KEY` | Require `Authorization: Bearer <key>`. |
+| `--cors-origin ORIGIN` | Allow a browser origin; repeatable. |
+| `--max-body-mb N`, `--timeout SECONDS` | Request limits. |
+| `--max-models N` | Idle models kept loaded (LRU). |
+| `--max-concurrent N` | Bounded inference concurrency. |
+| `--rate-limit N`, `--rate-window SECONDS`, `--rate-burst N` | Per-key rate limit. |
+| `--no-metrics` | Disable `/metrics`. |
+| `--tracing` | Enable optional OpenTelemetry spans. |
+| `--warmup` | Warm the default model at startup. |
+| `--log-level`, `--log-format` | Server logging overrides. |
+
+See [Operations](OPERATIONS.md) for the semantics of these limits.
+
+### Config, doctor and completion
+
+```bash
+dtk config list --json
+dtk config get device
+dtk config set device cpu
+dtk config set cache_dir /data/dtk-models
+dtk doctor
+dtk doctor --json
+dtk completion bash
+```
+
+Writable config keys are `cache_dir`, `current`, `current_variant` and `device`.
+`home` is read-only; use `--home`.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -244,8 +358,7 @@ dtk serve --model gliner2.5-multi --warmup \
 - `--workers N` and `--reload` use an internal uvicorn factory; `--reload`
   is for development and cannot be combined with `--workers > 1`.
 - `--max-models`, `--max-body-mb`, `--timeout`, `--warmup`, `--api-key`,
-  `--cors-origin`, `--log-level` and `--log-format` are the server's phase 2
-  controls.
+  `--cors-origin`, `--log-level` and `--log-format` are server controls.
 - Custom `--adapter`/`--files` also apply to the server's default model.
 
 ## Completion
@@ -281,6 +394,6 @@ dtk doctor --json
   config), but still does not reimplement inference.
 - It does not have a compatibility obligation to System One/OpenAI; those are
   REST contracts.
-- Metrics/rate limiting are server-side phase 5 features; see
+- Metrics and rate limiting are server-side features; see
   [OPERATIONS.md](OPERATIONS.md). Wheel/PyPI releases are documented in
   [RELEASE.md](RELEASE.md).

{decision_toolkit-0.4.1 → decision_toolkit-0.4.3}/docs/CORE.md

@@ -1,4 +1,4 @@
-# Core programmatic API (phase 1)
+# Core API
 
 The programmatic API is the **superset**: the most expressive layer of the
 toolkit. The REST server is a documented, conformance-tested projection of a subset of
@@ -207,7 +207,7 @@ Events emitted by `decision_toolkit.*` loggers:
 Each event is a compact JSON object with `event`, `request_id`, model identity,
 variant, adapter, question count, token counts, latency, truncation and error
 code. State and question text are **not** logged by default. The CLI/REST
-layers configure formatting and destinations in later phases.
+layers configure formatting and destinations separately.
 
 ## Extensibility
 
@@ -254,9 +254,9 @@ Registration is in-process (no daemon, no plugin server).
 - `resolve(id, variant=...)`: local directory + role → file map + adapter for
   the core.
 
-## Phase 1 expressiveness inventory
+## Capabilities and limits
 
-This is the checklist against which the REST projection will be verified:
+The core exposes the following capabilities:
 
 | Capability | Core status |
 | --- | --- |
@@ -280,13 +280,12 @@ This is the checklist against which the REST projection will be verified:
 | Model store | atomic download, hashes, verify, import metadata |
 | Multi-label | capability flag + validation; no adapter yet |
 
-## Out of scope for phase 1
+## Not part of the core
 
-- REST contract projection and standard compliance — implemented in phase 2
-  (see [REST.md](REST.md)).
-- CLI workflows across the whole catalog — implemented in phase 3 (see
-  [CLI.md](CLI.md)).
-- Pin/hash enforcement and source CI are implemented in phase 4; wheel,
-  PyPI and distribution tagging are documented in [RELEASE.md](RELEASE.md).
-- Metrics server, rate limiting and load/fuzz testing are server-side phase 5
-  features; see [OPERATIONS.md](OPERATIONS.md).
+- REST contract projection and standard compliance are implemented in the
+  server; see [REST.md](REST.md).
+- CLI workflows across the catalog are implemented in [CLI.md](CLI.md).
+- Catalog pinning and source CI are implementation details; packaging is
+  documented in [RELEASE.md](RELEASE.md).
+- Metrics, rate limiting and load/fuzz testing are server-side features; see
+  [OPERATIONS.md](OPERATIONS.md).

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

@@ -1,13 +1,23 @@
 # Examples
 
-Runnable examples for the three surfaces. Models must already be cached:
+Runnable examples for the three surfaces. Models must already be cached; none
+of these examples downloads a model. For the shortest path from a fresh
+install, start with [Quickstart](QUICKSTART.md).
+
+The repository ships one small script that exercises the library end to end:
+
+| Script | What it shows |
+| --- | --- |
+| [`examples/quickstart.py`](https://github.com/gia-uh/decision-toolkit/blob/main/examples/quickstart.py) | Load a cached model, ask choice/yes-no/score questions and print probabilities. |
 
 ```bash
 dtk models download gliner2.5-multi
-# or from a source checkout managed with uv:
-uv run dtk models download gliner2.5-multi
+python examples/quickstart.py gliner2.5-multi
 ```
 
+The code blocks below cover the same surfaces and are the reference examples
+for the library, CLI and REST APIs.
+
 ## Library
 
 ```python