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

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

@@ -1,8 +1,20 @@
 # Changelog
 
-All notable changes to this project are documented here. Version `0.4.2` 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,
@@ -223,6 +235,7 @@ 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/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: decision-toolkit
-Version: 0.4.2
+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.2 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.2/>. 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.
 
@@ -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
@@ -217,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
 ```
 
@@ -312,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.2 → 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.2 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.2/>. 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.
 
@@ -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
@@ -179,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
 ```
 
@@ -274,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.2 → decision_toolkit-0.4.3}/docs/CLI.md

@@ -5,6 +5,31 @@ 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 |
@@ -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 |

{decision_toolkit-0.4.2 → 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

decision_toolkit-0.4.3/docs/FAQ.md

@@ -0,0 +1,159 @@
+# FAQ
+
+## Is this a generative LLM?
+
+No. The models score typed questions and return probabilities. They do not
+generate prose, explanations or chat turns, and there is no text parser between
+the model and the answer.
+
+## What does `noul` mean?
+
+`noul` is a yes/no question. Its result is the probability of `true`, plus the
+normalized confidence and metadata. The name avoids overloading “boolean” for a
+model score that is not a hard logical value.
+
+## What is the difference between `choice`, `noul` and `score`?
+
+- `choice`: pick one option from a list. The core has a multi-label flag, but
+  no model in the current catalog declares multi-label support.
+- `noul`: estimate the probability of yes versus no.
+- `score`: choose an ordered level such as `calm`, `annoyed`, `furious`; the
+  expected level is available separately.
+
+All three are validated against the selected model's capabilities.
+
+## Why probabilities instead of labels?
+
+A threshold can turn a probability into a label, but the probability preserves
+uncertainty and lets each application choose its own operating point. Use
+`classify(..., threshold=...)` when you want a label plus a `below_threshold`
+flag.
+
+Are the probabilities calibrated? Calibration evidence is measured per model
+and variant in [Benchmarks](BENCH.md); do not assume that a probability from one
+model is directly comparable with a probability from another.
+
+## Does it run offline?
+
+Yes, after the model is in the local cache. Only `dtk models download` needs the
+network. The library, CLI and REST server otherwise run locally. See
+[Models](MODELS.md#offline-workflow).
+
+## Does it download models implicitly?
+
+No. If a model or variant is missing, the call fails instead of downloading it.
+Run `dtk models download <id>` explicitly. This keeps startup deterministic and
+makes offline operation possible.
+
+## Do I need a GPU?
+
+No. The supported runtime is ONNX Runtime on CPU. GPU acceleration is not part
+of the documented path. Larger models need more RAM and take longer.
+
+## Which model should I start with?
+
+For general choice, yes/no and score decisions, start with
+`gliner2.5-multi` and its default variant. If your state is not English, start
+with `laya-multilingual`. Read [Models](MODELS.md#choosing-a-model) and the
+[model cards](models/README.md), then measure on a small labelled sample from
+your domain.
+
+## Which variant should I choose?
+
+Start with the catalog default. Try `fp32` when quality matters more than
+latency, and `q4`/`q4f16`/`q8` when memory or disk is tight. Verify quality on
+your own data before switching. The default is a sensible starting point, not a
+universal recommendation.
+
+## Can I download several variants of the same model?
+
+Yes. Variants coexist in the cache. Downloading one does not replace another;
+`dtk models use` selects the persistent default, and `--variant` selects one
+for a single command.
+
+## Can I load two variants at the same time?
+
+Yes, for example over REST with `gliner2.5-multi@fp16` and
+`gliner2.5-multi@fp32`. They occupy separate registry slots. The library can
+also hold separate `DecisionModel` instances. Do not assume their probability
+outputs are interchangeable without evaluation.
+
+## Can I mix models in one application?
+
+You can load different models in separate instances, but a decision is made by
+one model at a time. Different models have different adapters, calibration and
+behavior; do not average or compare their probabilities without measuring what
+that means for your task.
+
+## Does REST use the TypeSafe and OpenAI schemas?
+
+Yes. The server exposes System One at `/v1/systemone` and OpenAI Decisions at
+`/v1/decisions`, with the pinned request and response shapes documented in
+[REST](REST.md). Local extensions are namespaced.
+
+## How do I select a quantization in REST?
+
+Use a model alias in the standard `model` field:
+
+```json
+{"model": "gliner2.5-multi@fp32"}
+```
+
+There is no `variant` field in a System One or OpenAI request body. The base id
+uses the server's `--variant` or the persisted default.
+
+## Is the REST server authenticated?
+
+It can be. `dtk serve --api-key ...` requires a bearer token, and
+`DECISION_TOOLKIT_API_KEY` is an optional environment fallback. Without either,
+the server is unauthenticated. It is local-first infrastructure: bind it to
+localhost or put your own authenticated proxy/TLS in front of it when exposed.
+
+## Does the server store my states or decisions?
+
+No, not by default. It evaluates a request and returns a response; it does not
+create a decision database. State and question text are not used as metric
+labels. Application logs and your own proxy may still retain request metadata;
+review [Operations](OPERATIONS.md#pii-and-logging).
+
+## Can I use a custom ONNX model?
+
+Yes, with an explicit adapter and file map, using `DecisionModel.from_onnx(...)`
+or `dtk models import`. Custom models are not catalogued, do not receive hash
+verification or support, and do not get a guessed layout. See
+[Core API](CORE.md#custom-local-onnx) and [CLI](CLI.md#custom-models).
+
+## What licenses do the models have?
+
+The toolkit is MIT licensed. Each model has its own license, recorded in its
+model card; check the card and the upstream model page before redistribution.
+See [THIRD_PARTY_NOTICES](https://github.com/gia-uh/decision-toolkit/blob/main/THIRD_PARTY_NOTICES.md).
+
+## What Python versions are supported?
+
+Python 3.12 and 3.13. The package requires Python 3.12 or newer.
+
+## Is this ready for production?
+
+The 0.4.x line is usable, but still evolving. Pin the version you deploy, read
+the [changelog](https://github.com/gia-uh/decision-toolkit/blob/main/CHANGELOG.md),
+and use the operational limits and runbook in [Operations](OPERATIONS.md). The
+REST contracts are pinned; the core API can still change between minor releases.
+
+## Does it support images or assets?
+
+The core has typed support for assets and `box`, but every model currently in
+the catalog is text-only. The REST server rejects image/asset and `box` requests
+for this catalog. See [REST](REST.md#not-implemented-by-this-server).
+
+## Is it a vector database or search engine?
+
+No. It returns decisions for typed questions. It does not store vectors, index
+documents or provide a search UI.
+
+## How do I report a bug?
+
+Include the exact command or request, the output of `dtk doctor --json`, the
+toolkit version, the model and variant, and any error code. Redact state text
+that you cannot share. Use the repository issue tracker linked from the
+[home page](index.md).

decision_toolkit-0.4.3/docs/GLOSSARY.md

@@ -0,0 +1,36 @@
+# Glossary
+
+| Term | Meaning |
+|---|---|
+| **State** | The text or JSON value the model reasons over. In the library it can be a string, `State(text=...)` or a JSON-compatible object. |
+| **Question** | A typed request for one decision: `choice`, `noul` or `score`. |
+| **`choice`** | A question with a list of options and one selected option. The core has a multi-label flag, but no model in the current catalog declares it. |
+| **`noul`** | A yes/no question. The result is a probability of `true`, not a hard boolean. |
+| **`score`** | A question with ordered levels. The result includes the expected score, the most likely level and the level legend. |
+| **Criteria** | Descriptions or option definitions attached to a question. For `choice`, they tell the model what each option means. |
+| **Adapter** | The code that formats a state and typed questions for a specific model layout and reads its outputs. One adapter per model contract. |
+| **Catalog** | The models and pinned variants shipped with the toolkit. `dtk models list` shows it. |
+| **Variant** | One real, pinned ONNX build of a model. The variant name is passed to `--variant` or `variant=`. |
+| **Quantization** | The numeric format of a build, such as `fp16`, `fp32`, `q8`, `q4` or `q4f16`. It is related to, but not always identical to, the variant name. |
+| **Model alias** | The REST identifier `id@variant` used in the standard `model` field, for example `gliner2.5-multi@fp32`. |
+| **Default variant** | The catalog's preferred variant for a model, marked with `*` in `dtk models list`. Used when no explicit or persisted selection exists. |
+| **Current selection** | The model and variant stored by `dtk models use`; reported by `dtk models current`. |
+| **Model cache** | The local directory holding downloaded or imported model variants. It is independent from the HuggingFace cache. |
+| **Toolkit home** | The parent directory containing `config.json` and the model cache, by default `~/.local/share/decision-toolkit/`. |
+| **`cache_dir`** | The `config.json` value that points at the model cache. It may be absolute or relative to the toolkit home. |
+| **Model store** | The `ModelStore` API that owns download, import, selection, verification and resolution. |
+| **Strict mode** | A mode where truncation raises `TruncationError` instead of returning a truncated answer. |
+| **Truncation** | Shortening an input or output to fit a model context window. Answers expose `truncated` and `warnings`. |
+| **Confidence** | The normalized probability reported for the chosen answer. Its meaning is documented in [Core API](CORE.md#confidence). |
+| **Calibration** | How well predicted probabilities match observed frequencies. Evidence is measured per model and variant; see [Benchmarks](BENCH.md). |
+| **Warmup** | Loading the ONNX session before the first real request. Available in the library and with `dtk serve --warmup`. |
+| **Usage** | Token accounting attached to a decision: input, output, total and whether the count is estimated. |
+| **Request ID** | A correlation identifier attached to a decision and emitted in logs. Set it with `request_context(...)` or the CLI/REST request metadata. |
+| **System One** | The TypeSafe REST schema used by `POST /v1/systemone`. |
+| **OpenAI Decisions beta** | The OpenAI Decisions schema used by `POST /v1/decisions`. |
+| **Local extension** | A field or response extension namespaced by decision-toolkit, outside the public TypeSafe/OpenAI shapes. |
+| **`top_k`** | In one-label classification, the number of best alternatives to return (when the surface exposes it). |
+| **Threshold** | A probability cutoff used by `classify` to decide whether to return a label or mark the result as below threshold. |
+| **Custom model** | A local ONNX directory supplied by the user with an explicit adapter and file map. It is not a catalog entry and has no catalog guarantees. |
+| **REST server** | The optional FastAPI process started by `dtk serve`; it projects a subset of the core over HTTP. |
+| **CLI** | The `dtk` command, a thin operational surface over the core. |