opendxp 0.1.0__tar.gz

opendxp-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+# Packages are large: they live outside the repository.
+/packages/
+*.onnx
+*.onnx.data
+*.gguf
+*.safetensors

opendxp-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0
+
+The first release of OpenDXP, the Open Decision Exchange Protocol, and its
+reference implementation.
+
+- The standard, `odxp/0.1`: packages (`odxp.json` and the files it names by
+  SHA-256), the `encoder-markers` and `causal-letters` profiles, calibration,
+  conformance files and compatibility levels, with JSON Schemas for every file.
+- Reference runtimes on ONNX Runtime and llama.cpp (CPU and GPU builds).
+  `--device auto` uses CUDA when available and the CPU otherwise; Core ML,
+  OpenVINO, QNN and DirectML are used when named.
+- `opendxp export` for Laya, Julia 1 and Decider; `opendxp conformance
+  generate` from the models' own code; `opendxp check`, `validate`, `run` and
+  `info`.
+- The OpenDXP 0.1 request set: 52 requests, 91 questions, 11 languages.

opendxp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to OpenDXP
+
+OpenDXP is a standard first and code second. A change to what a package means
+is a change to SPEC.md, the schemas and the reference runtime together.
+
+## What is most useful
+
+- **A model the profiles cannot describe.** Open an issue with the model, the
+  exact input construction of its own code, and what `template.json` or
+  `prompt.json` would need. This is how the standard grows.
+- **A converter** for another model family (Von, open-jev, Kev, Nimble, ...):
+  `src/opendxp/export/<family>.py`, a native adapter in `src/opendxp/native/`
+  that runs the model's own code, and the validation results.
+- **Another engine.** The standard is language-neutral. An engine in Rust,
+  Go or JavaScript that passes the conformance files of the published
+  packages is the strongest test of the spec; report where SPEC.md was
+  ambiguous.
+- **Backend results**: `opendxp check --device <backend>` on hardware we do not
+  have (CUDA, OpenVINO, QNN, DirectML, ROCm), with the report JSON.
+
+## Rules for changes
+
+1. **Normative changes** (anything in SPEC.md that uses MUST, SHOULD or MAY,
+   the schemas, `src/opendxp/spec.py`) need an issue first, and bump the
+   standard's version when they change what an existing package means.
+2. **Conformance files are generated by the model's own code**, never by the
+   reference runtime, and record which code and versions produced them. A
+   converter that needed model-specific logic in the runtime to pass has not
+   passed: move that logic into the declarative files or propose a spec change.
+3. **No invented numbers.** VALIDATION.md and the paper report only what a
+   report file in the repository or the packages supports.
+4. **Nothing in a package executes.** No templates with logic, no pickles, no
+   `trust_remote_code`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,onnx]"
+pytest                      # no downloads; a tokenizer is built in memory
+ruff check src tests scripts && ruff format --check src tests scripts
+```
+
+The request set lives in `scripts/build_requests.py`; run it to regenerate
+`src/opendxp/data/requests-0.1.jsonl`. Changing it changes the standard's
+conformance set: packages then need their conformance files regenerated.
+
+Commits: one logical change each, with a message that says what changed and
+why. Sign-off is not required. By contributing you agree that your
+contribution is licensed under Apache-2.0.

opendxp-0.1.0/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

opendxp-0.1.0/NOTICE

@@ -0,0 +1,21 @@
+OpenDXP, the Open Decision Exchange Protocol
+Copyright 2026 System One Models
+
+This product includes software derived from:
+
+- laya (convaiinnovations/laya), Apache-2.0: the input construction reproduced
+  declaratively in the Laya converter (laya/common.py build_sequence,
+  render_options, clamp_temperature, temp_bucket).
+- Julia 1 (SupersonicLabs/Julia-1, revision a85b127321d580d65176c89ced8273f305745d85),
+  Apache-2.0: the JuliaDecisionModel inference subset in opendxp/export/julia.py
+  (julia/model.py), the input construction reproduced in its template
+  (julia/data.py sequence()), and its inference path rebuilt in
+  opendxp/native/julia.py (model.py, data.py, router/engine.py, typed.py).
+- Decider (github.com/Mapika/decider at 23579f7a, decider-ai 1.6.0), Apache-2.0:
+  the prompt layout, labels, isolated score levels and temperatures reproduced
+  declaratively in the Decider converter (decider/prompt.py, prompt_fast.py,
+  systemone.py, temperature.py, engine_gguf.py), and its request rendering,
+  prompt construction and GGUF readout rebuilt in opendxp/native/decider.py.
+
+OpenDXP packages converted from these models carry the models' own weights and
+remain under the models' licences.

opendxp-0.1.0/PAPER.md

@@ -0,0 +1,74 @@
+# Paper outline
+
+Working title: **OpenDXP: a portable runtime standard for calibrated
+single-pass decision models**
+
+This file tracks the paper: its argument, its sections, and which experiments
+are done. Numbers come from [VALIDATION.md](VALIDATION.md) and are measured,
+never estimated.
+
+## The argument
+
+1. A new kind of model answers typed questions about a state (choose one of
+   these options, score on this scale, is this true) with a calibrated
+   probability for every option, in one forward pass. Laya, Julia 1 and
+   Decider are three of them, from three teams, with three architectures.
+2. Each ships its own inference code. Running, deploying or comparing them
+   means installing, trusting and wrapping each one. Formats such as ONNX and
+   GGUF carry the weights but not the rest: how the input is built from the
+   request, where the answer is read, how it is calibrated.
+3. OpenDXP puts the rest in the package as data (a template or a prompt, and
+   temperatures), so one engine runs every model with no code written for it
+   and nothing from the package executed.
+4. Faithfulness is testable: the package carries a conformance file of what
+   the model's own code answers, and an engine passes when it reproduces it
+   within 0.01 with the same decisions.
+5. Two profiles cover the models we know of: bidirectional encoders that
+   score a marker token per option, and causal language models read at an
+   answer letter.
+
+## Sections
+
+1. **Introduction.** System One models; the cost of one runtime per model;
+   the contribution: the standard, the conformance method, a reference
+   implementation and three conversions.
+2. **Background.** Calibrated classification and temperature scaling (Guo et
+   al., 2017); marker-based encoders (Laya, Julia 1); letter-probability
+   readout from language models (Decider); ONNX and GGUF as weight formats;
+   loading model code at run time (`trust_remote_code`) and why a standard
+   should not need it.
+3. **The standard.** Requests and answers; packages with nothing executable;
+   the two profiles; calibration as data; conformance files and the
+   comparison rule; compatibility levels.
+4. **Reference implementation.** Runtimes for both profiles on ONNX Runtime
+   and llama.cpp; converters that copy no weights (ONNX external data pointing
+   into the published safetensors); conformance generation from the models'
+   own code; the System One Engine and the registry, which run packages and
+   show the badge.
+5. **Evaluation.** The experiments below.
+6. **Discussion.** What the tolerance means; backend numerics; sharing
+   computation versus exactness; what 0.1 leaves open (SPEC.md 12).
+7. **Conclusion.**
+
+## Experiments
+
+| # | Question | Status |
+| --- | --- | --- |
+| E1 | Do packages reproduce their models' own answers on a CPU? | **Done.** 6 packages, 3 families, 52/52 cases each, all decisions equal, differences at the 4-decimal rounding floor. |
+| E2 | Does a declarative input description give the same tokens as the models' own code? | **Done.** Decider: 149/149 rows identical. Laya and Julia: input construction tested against their own code (tests/). |
+| E3 | Can a model's own ONNX export become a package without exporting again? | **Done.** Julia 1's published graph, renamed and pointed at its checkpoint: 52/52, and 100/100 on its authors' parity cases. |
+| E4 | Do packages stay faithful on accelerator backends? | **Partly.** Julia on Core ML passes (level 3). Decider on Metal keeps every decision but not the probabilities (max 0.036). CUDA, ROCm, OpenVINO, QNN, DirectML to do. |
+| E5 | What moves a causal model's probabilities? | **Done on one machine.** Flash attention off on the CPU: up to 0.014. Metal: 0.036 whatever the attention or cache settings. |
+| E6 | What does sharing the prompt prefix cost in faithfulness? | **Done on one machine.** CPU: 1.8x faster over the set, up to 0.018, and one near-tie decision of 91 changed; Metal: 1.6x faster, nothing added. To repeat on an x86 server. |
+| E7 | What does a package cost? | **Done on one machine.** 3 to 5 MB of graph per encoder package, no weight copies; load and latency per backend. Server numbers to do. |
+| E8 | Is 0.01 the right tolerance? | **To do.** The distribution of differences, and of decision flips, across backends and quantisations. |
+| E9 | Can someone else convert a model from the spec alone? | **To do.** A Laya Studio fine-tune and a model from outside the three families, converted by their authors. |
+
+## Before submission
+
+- E4, E6 and E7 on an x86 server CPU and at least one NVIDIA GPU.
+- E8 with quantised variants (int8 ONNX, Q4 GGUF) as derived packages.
+- E9 with at least one team outside System One Models.
+- Credit and permission: the model authors (Convai Innovations, Supersonic
+  Labs, Mark Marosi) are named for their models and asked before their
+  results are published.

opendxp-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: opendxp
+Version: 0.1.0
+Summary: OpenDXP, the Open Decision Exchange Protocol: a portable standard for calibrated single-pass decision models (reference implementation)
+Project-URL: Homepage, https://github.com/systemonemodels/opendxp
+Project-URL: Documentation, https://systemonemodels.tech/docs/opendxp
+Project-URL: Specification, https://github.com/systemonemodels/opendxp/blob/main/SPEC.md
+Project-URL: Validation, https://github.com/systemonemodels/opendxp/blob/main/VALIDATION.md
+Project-URL: Issues, https://github.com/systemonemodels/opendxp/issues
+Author-email: System One Models <ceo@systemonemodels.tech>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: calibration,conformance,decision-models,gguf,onnx,opendxp,system-one
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: numpy>=1.26
+Requires-Dist: tokenizers>=0.20
+Provides-Extra: dev
+Requires-Dist: onnx>=1.17; extra == 'dev'
+Requires-Dist: onnxruntime>=1.20; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: export
+Requires-Dist: onnx-ir>=0.1.15; extra == 'export'
+Requires-Dist: onnx>=1.17; extra == 'export'
+Requires-Dist: onnxscript>=0.5; extra == 'export'
+Requires-Dist: safetensors>=0.4; extra == 'export'
+Requires-Dist: torch>=2.6; extra == 'export'
+Requires-Dist: transformers>=5.2; extra == 'export'
+Provides-Extra: gguf
+Requires-Dist: llama-cpp-python<0.4,>=0.3.35; extra == 'gguf'
+Provides-Extra: laya
+Requires-Dist: laya==0.3.5; extra == 'laya'
+Provides-Extra: onnx
+Requires-Dist: onnxruntime>=1.20; extra == 'onnx'
+Description-Content-Type: text/markdown
+
+# OpenDXP
+
+**The Open Decision Exchange Protocol: a portable standard for calibrated single-pass decision models.**
+
+A System One model reads a state and answers typed questions (choice, score,
+noul) with a calibrated probability for every option, in one pass. Every such
+model ships its own inference code: Laya needs the `laya` package, Julia 1 its
+own package, Decider its own server. To run twenty models you install twenty
+runtimes, and to compare them you write twenty harnesses.
+
+OpenDXP makes the model a package that one engine runs without code written for
+it. A package declares which of two **profiles** it follows, carries its
+weights in a portable format (ONNX or GGUF), describes its input construction
+and calibration as data, and ships a **conformance file**: what the model's
+own code answers on a fixed set of requests. An engine that reproduces that
+file within 0.01 in probability, with the same decisions, runs the model
+faithfully.
+
+- [SPEC.md](https://github.com/systemonemodels/opendxp/blob/main/SPEC.md): the standard, version 0.1
+- [schemas/](https://github.com/systemonemodels/opendxp/tree/main/schemas): JSON Schemas for every file in a package
+- [VALIDATION.md](https://github.com/systemonemodels/opendxp/blob/main/VALIDATION.md): Laya, Julia 1 and Decider converted and checked
+- [badge/BADGE.md](https://github.com/systemonemodels/opendxp/blob/main/badge/BADGE.md): the "OpenDXP compatible" badge and its criteria
+- [PAPER.md](https://github.com/systemonemodels/opendxp/blob/main/PAPER.md): outline of the paper, and which experiments are done
+
+OpenDXP is open: the specification, the schemas and this reference
+implementation are Apache-2.0, and anyone may build an engine for it. The
+[System One Engine](https://systemonemodels.tech/docs/engine), which serves
+the live playgrounds on [System One Models](https://systemonemodels.tech),
+runs OpenDXP packages and shows which models are OpenDXP compatible.
+
+## The two profiles
+
+| Profile | Models | Weights | The engine reads |
+| --- | --- | --- | --- |
+| `encoder-markers` | Laya, Julia 1, Von, open-jev, GLiNER2.5-Decide | ONNX | `template.json`: how to build the token ids and one marker position per option |
+| `causal-letters` | Decider, Kev, Nimble, JevK5, lev | GGUF | `prompt.json`: the prompt pieces, the option labels and where the answer letter is read |
+
+ONNX runs through ONNX Runtime (CPU, CUDA, Core ML, OpenVINO, QNN, DirectML);
+GGUF through llama.cpp (CPU, Metal, CUDA, HIP, SYCL, Vulkan). The engine picks
+the device, not the model's author.
+
+## What is here
+
+The `opendxp` Python package (Python 3.11+) is the reference implementation:
+
+- **Reference runtimes** for both profiles. They read only the package and
+  contain nothing specific to any model. The encoder runtime runs on CUDA when
+  onnxruntime has it and on the CPU otherwise; Core ML, OpenVINO, QNN and
+  DirectML are used when named (`--device coreml`), and it compiles shape
+  buckets for providers that need fixed shapes. The causal runtime drives llama.cpp's low-level API, one
+  row per decode, with every layer on the GPU when the build has one.
+- **Converters** for Laya, Julia 1 and Decider (`opendxp export`).
+- **The models' own inference** for writing conformance files
+  (`opendxp.native`): Laya through the `laya` package; Julia 1 and Decider
+  through faithful rebuilds of their authors' code, checked on the authors'
+  published cases.
+- **Conformance tools**: `opendxp conformance generate` runs the model's own
+  code on the OpenDXP 0.1 request set (52 requests, 91 questions, 11 languages
+  including Nepali and Thai); `opendxp check` replays it through the reference
+  runtime and writes a JSON report.
+
+## Install
+
+```bash
+pip install "opendxp[onnx]"          # encoder-markers runtime (ONNX Runtime)
+pip install "opendxp[gguf]"          # causal-letters runtime (llama-cpp-python)
+pip install "opendxp[export,laya]"   # converters (torch, transformers, onnx, onnxscript, laya)
+```
+
+From a clone, for development:
+
+```bash
+pip install -e ".[dev]"             # tests and linting
+```
+
+## Use a package
+
+```python
+import opendxp
+
+model = opendxp.load("packages/laya-typed-decisions")      # device="auto": the best available
+out = model.predict(
+    "Customer: I was charged twice and still have no refund.",
+    {
+        "intent": {"type": "choice", "instructions": "What does the customer want?",
+                   "criteria": {"refund": None, "cancel order": None, "other": None}},
+        "urgency": {"type": "score", "instructions": "How urgent is this?",
+                    "criteria": ["low", "medium", "high"]},
+        "angry": {"type": "noul", "instructions": "The customer is angry."},
+    },
+)
+# {"answers": {"intent":  {"type": "choice", "choice": ..., "probabilities": {...}, "confidence": ...},
+#              "urgency": {"type": "score", "score": ..., "legend": {...}, "probabilities": {...}, ...},
+#              "angry":   {"type": "noul", "noul": ..., ...}},
+#  "usage": {"input_tokens": ..., "output_tokens": 0}}
+```
+
+From the shell: `opendxp run PACKAGE --request request.json [--device cpu|coreml|cuda|gpu]`.
+`opendxp info` lists this machine's backends.
+
+## Convert a model and check it
+
+```bash
+# 1. Convert: the package's graph references the checkpoint's weights, so it adds a few MB.
+opendxp export laya    ckpt/laya-typed-decisions   packages/laya-typed-decisions
+opendxp export julia   ckpt/julia-1                packages/julia-1
+opendxp export decider ckpt/decider-2b-gguf        packages/decider-2b
+
+# 2. Record what the model's own code answers (on the CPU).
+opendxp conformance generate packages/julia-1 --native ckpt/julia-1 --runtime julia
+
+# 3. Replay it through the reference runtime.
+opendxp check packages/julia-1                    # the reference: CPU
+opendxp check packages/julia-1 --device coreml    # a backend: Core ML
+opendxp validate packages/julia-1                 # schemas, parsers, coverage, hashes
+```
+
+`--runtime laya` uses the `laya` package (the `laya` extra);
+`julia` and `decider` use `opendxp.native` (with the `export` extra, and
+llama-cpp-python for Decider).
+
+## Make your model OpenDXP compatible
+
+1. **Pick the profile.** If your model scores a marker token per option with a
+   bidirectional encoder, it is `encoder-markers`. If it is a language model
+   that reads the probability of option letters after a prompt, it is
+   `causal-letters`.
+2. **Export the weights.** encoder-markers: ONNX with the signature in SPEC.md
+   5.4 (`input_ids`, `attention_mask`, `marker_positions`, `marker_mask`,
+   `question_type` → `option_logits`), dynamic dimensions named `batch`,
+   `tokens`, `options`. `opendxp.export.onnx_graph.export_graph` does this for
+   any torch module with that forward, and points the graph at your
+   `model.safetensors` instead of copying it. causal-letters: your GGUF file.
+3. **Describe the input as data.** Write `template.json` or `prompt.json`
+   (SPEC.md sections 5 and 6): the head and option texts, the special tokens,
+   the budgets and truncation rule, or the prompt pieces, labels and score
+   mode. If your input cannot be described this way, open an issue: that is
+   what the next version of the standard needs to know.
+4. **Declare calibration**: the temperatures your code applies, by type and
+   option count (section 7).
+5. **Generate conformance with your own code.** Add a native adapter in
+   `src/opendxp/native/` that loads your model with your package and returns
+   System One answers, then run `opendxp conformance generate`. The file records
+   which code produced it.
+6. **Check.** `opendxp check` must pass on the CPU (level 2, "OpenDXP compatible";
+   SPEC.md section 10). Put the report next to the package and the badge in
+   your model card.
+
+## Tests
+
+```bash
+pytest
+```
+
+The tests port the models' own input construction verbatim (Laya's
+`build_sequence`, Julia's `sequence()`, Decider's prompt builder) and require
+the declarative templates to give the same token ids, marker positions and
+refusals on hundreds of random requests. A toy ONNX graph with the standard
+signature exercises generate and check end to end. Nothing is downloaded.
+
+## Licence
+
+Apache-2.0. Converted packages carry the models' own weights and remain under
+the models' licences (see NOTICE).