decision-toolkit 0.1.0__tar.gz

decision_toolkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    env:
+      PYTHONPATH: src
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install test dependencies from source
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install \
+            pytest ruff PyYAML huggingface_hub fastapi httpx pydantic numpy openai
+      - name: Lint
+        run: ruff check src tests bench
+      - name: Unit and contract tests (source tree, no wheel)
+        run: pytest -q
+      - name: CLI smoke from source
+        run: |
+          python -m decision_toolkit --version
+          python -m decision_toolkit --home "$RUNNER_TEMP/dtk-home" doctor --json
+
+  audit:
+    name: dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install audit tool and runtime dependencies
+        run: |
+          python -m pip install --upgrade pip pip-audit
+          python -m pip install PyYAML huggingface_hub fastapi httpx pydantic numpy
+      - name: pip-audit
+        run: pip-audit

decision_toolkit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,85 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target (tag pushes always publish TestPyPI then PyPI)"
+        type: choice
+        options: [testpypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish-testpypi:
+    name: publish TestPyPI
+    if: startsWith(github.ref, 'refs/tags/v') || inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: publish PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --generate-notes --verify-tag

decision_toolkit-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Test caches
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# Local data
+*.local
+home/
+/models/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

decision_toolkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project are documented here. The project has not
+published a distribution artifact yet; versions are repository milestones.
+
+## [Unreleased]
+
+### Phase 6 — packaging
+
+- Added `py.typed`, project URLs, co-author metadata and sdist inclusion.
+- Wheel and sdist build successfully; `twine check` passes with current tooling.
+- Wheel installs in a clean venv with `[onnx,server,tracing]`; `dtk` and the
+  REST server work from the installed artifact.
+- Added a Trusted Publishing release workflow for TestPyPI → PyPI and GitHub
+  Releases.
+- No artifact has been uploaded yet; PyPI/TestPyPI publishing requires the
+  configured environments and approval.
+- Added `docs/RELEASE.md`.
+
+### Phase 5 — operations
+
+- Per-key rate limiting with `429` + `Retry-After` (disabled by default).
+- Bounded inference concurrency (`--max-concurrent`) with `503 server_busy`
+  instead of unbounded queueing.
+- Prometheus `/metrics`: HTTP, decision, token, model-load, rate-limit, busy,
+  inflight and model-cache metrics with low-cardinality labels.
+- Optional OpenTelemetry spans (`--tracing`) with a no-op fallback.
+- `bench/load.py` concurrent load probe and a versioned backpressure result.
+- Deterministic REST fuzz/negative corpus and PII sentinel tests.
+- `pip-audit` CI job; `docs/OPERATIONS.md` runbook.
+- Still no wheel/PyPI/tag.
+
+### Phase 4 — reproducibility
+
+- Pinned every catalog variant to a HuggingFace commit SHA.
+- Recorded SHA256 for every declared model file and external-data file.
+- `dtk models verify` now treats the catalog hashes as the source of truth and
+  also verifies `.onnx.data` files.
+- Model downloads reject files that do not match the pinned hashes.
+- Added a reproducible benchmark/calibration harness in `bench/` with versioned
+  results and a synthetic calibration suite.
+- Added source-only CI for Python 3.12/3.13 (lint, tests, CLI smoke; no wheel).
+- Added model-card reproducibility sections, `docs/BENCH.md`, contributing,
+  security and third-party notices.
+
+### Phase 3 — CLI
+
+- Consistent `--json`, quiet/verbose modes and exit codes (`0/1/2/3/130`).
+- JSON/YAML questions files, JSONL batching, custom `--adapter/--files`.
+- Variant-aware `use/current/delete` and strict `verify --all`.
+- `config get/set/list`, `version`, `completion`.
+- `serve --workers/--reload`, API key, CORS, log format and warmup.
+
+### Phase 2 — REST
+
+- Versioned System One 1.14 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.
+
+### Phase 1 — core
+
+- Typed `DecisionModel` API with lifecycle, batching, async, usage, warnings,
+  normalized confidence, capabilities, structured events and atomic model store.
+
+## [0.1.0] — unreleased
+
+The version is not tagged or packaged yet. Wheel/PyPI construction is deferred.

decision_toolkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+decision-toolkit is a curated runtime, not a mirror of model hubs. Changes that
+add a model or an adapter must bring **real evidence**, not a promising README.
+
+## Development setup (source only)
+
+There is no wheel/PyPI release yet. Work from the source tree:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install pytest ruff pip-audit PyYAML huggingface_hub fastapi httpx pydantic numpy
+# for real inference:
+pip install onnxruntime tokenizers
+PYTHONPATH=src pytest -q
+```
+
+The fast suite must not download models. Integration tests are opt-in:
+
+```bash
+PYTHONPATH=src pytest -m integration -o addopts="" -s
+```
+
+`tests/test_integration_gliner2.py` uses `DECISION_TOOLKIT_GLINER2_DIR` and
+never downloads.
+
+## Code rules
+
+- Keep inference logic in adapters; the CLI and REST call the core.
+- The core is the superset. Do not add wire-specific concepts to it.
+- The REST layer may only project core capabilities; if a standard needs
+  something, add it to the core first.
+- Every new error gets a stable `code` and a test for its HTTP/CLI mapping.
+- No silent truncation: mark `truncated`/`warnings` or fail in strict mode.
+- Logs carry model/variant/request id, not state/question content by default.
+
+## Model admission
+
+A model enters `CATALOG` only when it has:
+
+1. a clean commercial license;
+2. a real public ONNX export;
+3. an adapter contract implemented from that export;
+4. a **pinned commit SHA** and SHA256 for every declared file;
+5. measured parity against a named baseline;
+6. CPU latency measured on a known machine;
+7. a model card and reproducibility commands.
+
+Models that fail any gate belong in `docs/ROADMAP.md`, not in the catalog.
+
+## Bench evidence
+
+Re-run the harness when a model, adapter or quantized build changes:
+
+```bash
+PYTHONPATH=src python bench/run.py --suite bench/suites/smoke.jsonl \
+  --repeats 3 --output bench/results/YYYY-MM-DD-smoke.json
+```
+
+Do not overwrite an old result with a different machine silently; add a new
+dated file and record the environment. Latency is post-warmup and is not the
+same metric as the historical admission values in the model cards.
+
+## Tests and lint
+
+```bash
+ruff check src tests bench
+PYTHONPATH=src pytest -q
+PYTHONPATH=src pytest -q -m fuzz        # malformed REST corpus
+python -m decision_toolkit --version
+pip-audit                             # dependency scan (CI runs this)
+```
+
+CI runs these on Python 3.12 and 3.13 from source, plus `pip-audit`. It does
+**not** build a wheel; packaging is a later milestone. See
+[OPERATIONS.md](docs/OPERATIONS.md) for rate limits, metrics, tracing and the
+load probe.
+
+## Commits
+
+Use a short imperative subject. Mention the layer (`core`, `rest`, `cli`,
+`repro`, `docs`) and whether catalog evidence changed.

decision_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GIA-UH (Universidad de La Habana) and Syalia S.R.L.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

decision_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.5
+Name: decision-toolkit
+Version: 0.1.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
+Project-URL: Issues, https://github.com/gia-uh/decision-toolkit/issues
+Project-URL: Documentation, https://github.com/gia-uh/decision-toolkit/tree/main/docs
+Project-URL: Changelog, https://github.com/gia-uh/decision-toolkit/blob/main/CHANGELOG.md
+Author: Syalia S.R.L.
+Author-email: Yudivián Almeida Cruz <yudivian@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: classification,cpu,decision-models,jev,local-first,onnx,routing,system-one
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: huggingface-hub>=0.23
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: openai>=1.0; extra == 'dev'
+Requires-Dist: pip-audit>=2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: onnx
+Requires-Dist: numpy>=1.26; extra == 'onnx'
+Requires-Dist: onnxruntime>=1.18; extra == 'onnx'
+Requires-Dist: tokenizers>=0.19; extra == 'onnx'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: python-multipart>=0.0.9; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'server'
+Provides-Extra: tracing
+Requires-Dist: opentelemetry-api>=1.25; extra == 'tracing'
+Description-Content-Type: text/markdown
+
+# decision-toolkit
+
+Local-first toolkit around **open-weights decision models**: typed **choice /
+yes-no (`noul`) / score** questions over a state (text or JSON), answered with a
+**calibrated probability for every option** — no generated text, no parsing.
+
+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).
+
+**Examples:** [docs/EXAMPLES.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/EXAMPLES.md) covers the library, REST and
+CLI. `dtk --help` and every subcommand help also include runnable examples.
+
+## Installation
+
+```bash
+pip install decision-toolkit              # library + CLI (once v0.1.0 is on PyPI)
+pip install "decision-toolkit[onnx]"      # + onnxruntime, tokenizers (the model runtime)
+pip install "decision-toolkit[server]"    # + REST server (FastAPI)
+```
+
+Pre-release: the artifact is built and verified locally, but not uploaded yet.
+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.
+
+## Three ways to use it
+
+**1. As a library (primary interface)**
+
+```python
+from decision_toolkit import DecisionModel, choice, noul, score
+
+# download once: dtk models download gliner2.5-multi
+model = DecisionModel("gliner2.5-multi")
+
+answer = model.decide(
+    state="Meeting with Acme: we agreed a 10% discount and will sign next week.",
+    questions={
+        "cat": choice("What kind of record is this?", {
+            "meeting": "a meeting or call with topics, decisions and actions",
+            "tasks": "things to do, with dates or owners",
+            "contact": "a person's details: name, role, company, phone, email",
+            "idea": "an idea, reflection, observation or question",
+            "other": "a greeting, small talk or anything else",
+        }),
+        "urgent": noul("Does it need a reply today?"),
+    },
+)
+answer["cat"].choice          # 'meeting'
+answer["cat"].confidence      # 0.77
+answer["urgent"].noul         # probability of "true"
+```
+
+```python
+verdict = model.classify(
+    "Remind me: dentist next Tuesday at 9 am.",
+    {"reminder": "an event with a date or time",
+     "task": "a list of things to do",
+     "idea": "an idea or reflection"},
+    threshold=0.6,
+)
+verdict.label, verdict.confidence, verdict.below_threshold
+```
+
+The core is the **superset** of the surfaces. It also exposes lifecycle,
+usage, batch/async, capabilities and structured events:
+
+```python
+from decision_toolkit import DecisionModel, request_context, noul
+
+with DecisionModel("gliner2.5-multi", strict=True) as model:
+    model.warmup()
+    with request_context("req-42"):
+        decision = model.decide("Customer wants a refund today.",
+                                {"urgent": noul("Does it need a reply today?")})
+    batch = model.decide_many(["first state", "second state"],
+                              {"urgent": noul("Today?")})
+
+decision["urgent"].confidence       # normalized probability
+decision.usage.to_dict()            # input/output tokens + estimated flag
+decision.latency_ms                 # per-decision latency
+decision.request_id                 # 'req-42'
+decision.truncated, decision.warnings
+```
+
+`strict=True` turns silent truncation into `TruncationError`. Capabilities are
+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,
+logging events and the expressiveness inventory.
+
+**2. As a CLI**
+
+```bash
+dtk models list --adapter --quant                # catalog, variants and cache state
+dtk models variants gliner2.5-multi --json       # real variants (quant, size, role)
+dtk models download gliner2.5-multi --dry-run    # show the download first
+dtk models use gliner2.5-multi --variant fp16
+dtk models current --json                        # includes the current variant
+dtk decide --model gliner2.5-multi \
+    --state "Meeting with Acme: 10% discount, sign next week." \
+    --questions-file questions.yaml --json
+dtk decide --model gliner2.5-multi \
+    --input-jsonl states.jsonl --questions-file questions.yaml \
+    --output-jsonl decisions.jsonl --batch-size 32
+dtk classify --model gliner2.5-multi \
+    --text "Dentist next Tuesday at 9" --labels "reminder,task,idea" \
+    --threshold 0.6 --json
+dtk config list --json
+dtk models verify --all --json
+```
+
+`dtk` has consistent exit codes (`0` ok, `1` runtime, `2` usage, `3`
+verification), `--json` everywhere, quiet/verbose modes and no tracebacks for
+expected failures. See [docs/CLI.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/CLI.md) for questions files, JSONL
+batch, custom `--adapter/--files`, config and completion.
+
+**3. As a REST service (optional extra)**
+
+```bash
+pip install "decision-toolkit[server]"
+dtk serve --model gliner2.5-multi --warmup \
+  --api-key "$DECISION_TOOLKIT_API_KEY" \
+  --log-format json
+```
+
+Endpoints: `POST /v1/systemone` (System One 1.14), `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.
+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
+
+The catalog is **ours**, not a mirror of HuggingFace. A model enters only when it
+is understood and verified:
+
+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 | default variant |
+| --- | --- | --- | --- |
+| `gliner2.5-multi` | `gliner2` | **m0** — verified end-to-end (9/15, 353 ms) | `fp16` (577 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) |
+
+**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).
+
+## Variants and quantization
+
+A quantization is a **variant** of a model, with its real repo, files and role:
+
+```yaml
+gliner2.5-multi:
+  fp16:  encoder_fp16.onnx + classifier_fp32.onnx      # 577 MB  default
+  fp32:  encoder_fp32.onnx + classifier_fp32.onnx      # 1132 MB quality
+```
+
+- `dtk models download <id>` gets the **default** variant; `--variant fp32` gets
+  another.
+- 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
+  sample) and measuring latency on CPU.
+- Unverified variants are never default. No silent fallback.
+
+## Operations
+
+The server has bounded inference concurrency (`--max-concurrent`), an optional
+per-key rate limiter (`--rate-limit`, 429 + `Retry-After`), Prometheus metrics
+at `/metrics`, and optional OpenTelemetry spans (`--tracing`). Saturation
+returns 503 `server_busy` instead of building an unbounded queue. State and
+question text never become log/metric labels.
+
+```bash
+dtk serve --model gliner2.5-multi --warmup --max-concurrent 4 \
+  --rate-limit 120 --rate-window 60
+PYTHONPATH=src python bench/load.py --base-url http://127.0.0.1:8000 \
+  --concurrency 10 --requests 30
+```
+
+See [docs/OPERATIONS.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/OPERATIONS.md) for metric names, alerts, the
+runbook and the multi-worker caveat.
+
+## Reproducibility
+
+Every catalog variant is pinned to a real HuggingFace **commit SHA** and carries
+a **SHA256 per file**, including external `.onnx.data` files. Downloads reject
+mismatches and verification treats the catalog hashes as the source of truth:
+
+```bash
+dtk models verify --all --json    # exit 3 if any file/hash/session fails
+```
+
+Latency/parity/calibration evidence is reproducible with the harness in
+[`bench/`](https://github.com/gia-uh/decision-toolkit/tree/main/bench) and documented in [docs/BENCH.md](https://github.com/gia-uh/decision-toolkit/blob/main/docs/BENCH.md). CI runs
+lint, unit/contract tests and a CLI smoke from source on Python 3.12/3.13.
+
+There is **no wheel or PyPI release yet**; packaging is a later milestone. See
+[CHANGELOG.md](https://github.com/gia-uh/decision-toolkit/blob/main/CHANGELOG.md), [CONTRIBUTING.md](https://github.com/gia-uh/decision-toolkit/blob/main/CONTRIBUTING.md),
+[SECURITY.md](https://github.com/gia-uh/decision-toolkit/blob/main/SECURITY.md) and
+[THIRD_PARTY_NOTICES.md](https://github.com/gia-uh/decision-toolkit/blob/main/THIRD_PARTY_NOTICES.md).
+
+## Custom ONNX (at your own risk)
+
+You can run any ONNX file with an adapter you trust — outside the curated
+catalog:
+
+```python
+model = DecisionModel.from_onnx(
+    "./my-model",
+    adapter="gliner2",              # the layout you declare
+    files={"encoder": "encoder.onnx", "classifier": "classifier.onnx",
+           "tokenizer": "tokenizer.json"},
+)
+# no parity, no license check, no support
+```
+
+Third-party layouts can be registered in-process:
+
+```python
+from decision_toolkit import register_adapter
+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.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install pytest ruff PyYAML huggingface_hub fastapi httpx pydantic numpy
+PYTHONPATH=src pytest -q             # fast suite (no model downloads)
+PYTHONPATH=src pytest -m integration -o addopts=""   # real model, opt-in
+```
+
+No wheel or editable install is required while the project is pre-distribution.
+CI runs the same source-tree commands on Python 3.12/3.13. See
+[CONTRIBUTING.md](https://github.com/gia-uh/decision-toolkit/blob/main/CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/gia-uh/decision-toolkit/blob/main/LICENSE).