Image Hopper initial release

BASE-MODEL-LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Dockerfile

@@ -0,0 +1,12 @@
+# CUDA 12.8.1 base matching torch 2.8.0+cu128, pinned by digest.
+FROM nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04@sha256:24c8e3581ea6330038b0d374920721983312627f8adbfcf390bdb4b399d280ed
+ENV DEBIAN_FRONTEND=noninteractive PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 TOKENIZERS_PARALLELISM=false HF_HOME=/models HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential python3.12 python3.12-venv python3.12-dev libgl1 libglib2.0-0 && rm -rf /var/lib/apt/lists/*
+RUN python3.12 -m venv /opt/venv
+ENV PATH=/opt/venv/bin:$PATH VIRTUAL_ENV=/opt/venv
+WORKDIR /app
+COPY requirements.lock requirements.lock.sha256 /app/
+RUN sha256sum -c requirements.lock.sha256 && python -m pip install --no-cache-dir -r requirements.lock
+COPY . /app
+EXPOSE 8080
+ENTRYPOINT ["python", "-m", "open_decisions.image_jev.release.server", "--host", "0.0.0.0", "--port", "8080", "--offline", "--adapter", "adapter"]

LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,8 @@
+Image Hopper
+
+This release uses the Qwen/Qwen3.5-9B base model at the revision recorded in
+RELEASE-MANIFEST.json. The base model is made available under the Apache
+License, Version 2.0. Its weights are not redistributed in this bundle.
+
+The Image Hopper server code and calibration artifact are made available under
+the Apache License, Version 2.0.

README.md

@@ -0,0 +1,90 @@
+---
+license: apache-2.0
+base_model: Qwen/Qwen3.5-9B
+pipeline_tag: image-text-to-text
+tags:
+- image-decisions
+- calibration
+- multiple-choice
+---
+
+# Image Hopper
+
+Image Hopper answers multiple-choice and yes/no questions about images with a calibrated probability for every option,
+in one forward pass and without generating text. It is built on `Qwen/Qwen3.5-9B`
+(revision `c202236235762e1c871ad0ccb60c8ee5ba337b9a`) and is designed for the Image JevBench `/v1/systemone` contract.
+
+## How it works
+
+- **One base, two routes.** A fixed text rule (`router-rules/v1`) reads only the question and option text. Questions
+  about on-screen elements (markers, buttons, menus, windows, …) or geometry (angles, triangles, circles, lengths, …)
+  use a LoRA adapter; every other question uses the unmodified base model. Both routes share one loaded model and one
+  forward pass.
+- **Readout.** Options are lettered A, B, C, …; the answer distribution is the FP32 softmax of the next-token logits
+  for those letters at the last prompt position.
+- **Calibration.** Logits are divided by a temperature chosen by route and answer type (fitted by maximum likelihood
+  with shrinkage toward a global temperature). Calibration never changes which option ranks first.
+- **Images** use the base processor's native resolution route; up to four images per request.
+
+| Route / answer type | Temperature |
+|---|---:|
+| default / 4-option | 1.2338 |
+| default / 5-marker | 1.9765 |
+| default / yes/no | 1.3353 |
+| screen_geometry / 4-option | 3.1396 |
+| screen_geometry / 5-marker | 1.3292 |
+| screen_geometry / yes/no | 0.6572 |
+
+## Training and calibration data
+
+The adapter (LoRA r64, one epoch, about 5,900 examples) was trained on real images with their datasets' own labels —
+desktop screenshots from GroundCUA (training applications only), document pages from DocLayNet, industrial-defect
+photos from VisA and openly licensed photo collections — plus original procedural renders (charts, documents, tables,
+geometry, interface mock-ups). No benchmark items were used for training or calibration, and every training image was
+checked against the benchmark's reference images for near-duplicates.
+
+| Source | Licence of admitted material |
+|---|---|
+| GroundCUA (training applications) | MIT |
+| DocLayNet | CDLA-Permissive-1.0 |
+| Visual Anomaly (VisA) | CC BY 4.0 |
+| Amazon Berkeley Objects | CC BY 4.0 |
+| Public Domain 12M | CDLA-Permissive-2.0 metadata; admitted images public domain or CC0 |
+| AgriFreshNET | CC BY 4.0 |
+| SHARD shelf-management dataset | CC BY 4.0 |
+| PHELE physical-hazards dataset | CC BY 4.0 |
+| Original procedural renders | Apache-2.0 (ours) |
+
+The default-route temperatures were fitted on a held-out calibration split of our own data; the screen/geometry
+temperatures on held-out real screenshots and geometry diagrams that were never used for training.
+
+## Usage
+
+    pip install -r requirements.txt
+    python -m open_decisions.image_jev.release.server --offline --adapter adapter --port 8080
+
+`POST /v1/systemone`:
+
+    {"images": ["data:image/png;base64,..."],
+     "questions": {"decision": {"type": "choice", "instructions": "Which shelf is empty?",
+       "criteria": {"top": "Top shelf", "bottom": "Bottom shelf"}}}}
+
+The response has `model`, token `usage` and `answers`; a `choice` answer holds the selected option and a probability
+per option, a `noul` answer holds P(yes).
+
+## Evaluation
+
+Image JevBench results will be added here once the benchmark maintainer publishes them.
+
+## Intended use and limitations
+
+For research and evaluation of image-grounded decisions where callers supply the options. Not a safety system or a
+substitute for human review in high-impact decisions. Weak at dense counting; the adapter route is specialised for
+screens and geometry; probabilities cover only the supplied options (no abstain answer); calibration reflects our
+data mix and may transfer imperfectly; evaluated on English questions with thinking mode off. Native-resolution cost
+and latency grow with image size.
+
+## Licence
+
+Code, adapter and calibration: Apache-2.0. The base model `Qwen/Qwen3.5-9B` is Apache-2.0 and is not redistributed
+here. See `LICENSE`, `BASE-MODEL-LICENSE` and `NOTICE`; third-party data licences as listed above.

RELEASE-MANIFEST.json

@@ -0,0 +1,54 @@
+{
+  "adapter": {
+    "path": "adapter",
+    "tree_sha256": "1e87a9966f77622d9b70b874364adc7ac1990b78735b5e08168d68106715d341"
+  },
+  "base_model": {
+    "fine_tuned": true,
+    "repo": "Qwen/Qwen3.5-9B",
+    "revision": "c202236235762e1c871ad0ccb60c8ee5ba337b9a"
+  },
+  "calibration": {
+    "artifact_sha256": "fc29b120cf2ac00d1917c3712fcd2293b5be3c4746de7d4640b41c3cce251501",
+    "fit": null,
+    "identity_sha256": "9ca8772bb7207d3dbbedc42f7cbd933f30fe7c2367c682e5a01acd2bf8303c78"
+  },
+  "code": {
+    "dirty": false,
+    "git_commit": "b94f0c4507c2463f6569974cfbb36a05ccdbb764"
+  },
+  "files": {
+    "BASE-MODEL-LICENSE": "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4",
+    "Dockerfile": "904c4630d2b50f577e3e6cf0e9d71f25c06e4fb64ef1a41238b299ba0c8a5d7a",
+    "LICENSE": "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4",
+    "NOTICE": "1d5e63ea05ed3c846593f1f4185b4355a25b2b25682bccac24995e094141b6c7",
+    "README.md": "2b1b313bcf80dff7aaeea5904c82d3adec8e0c8079a42a28093f7538c794b8b9",
+    "adapter/README.md": "bb29528044c9409e183ce924e4ea6f29f2b705d749287781b8ff2777b5209a55",
+    "adapter/adapter_config.json": "4f6e55c1d151070a6e8444feff44bdcfbe4b87e14c3fde855f69159066162487",
+    "adapter/adapter_model.safetensors": "6201fcb1c08144e465a03fd6f5355c4394b3bffaad659440fa64063dd4f71509",
+    "base-model-files.json": "d5009e4769f367557296b7b233824b3045e3cebee1a703f6419f2ff23ad53318",
+    "calibration.json": "bfb674b8ae7b2ba5293fd7c87706d1628d0455505794091d3e50d32a5378e685",
+    "open_decisions/__init__.py": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "open_decisions/image_jev/__init__.py": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "open_decisions/image_jev/release/__init__.py": "4a29d6b23b6021c0cc27d3fa5163ebbede7ab531b1a13814dfddf1fedcd71af4",
+    "open_decisions/image_jev/release/predictor.py": "b4a469714f2cfb5b6cf8551975dc76e2b6139b6dae61b1ebcc4f31335dddb407",
+    "open_decisions/image_jev/release/server.py": "3815ab07ca929b9e226b0a73521b2dc6cc6c426da1d0d8942ab9e372163f3ca9",
+    "open_decisions/image_jev/release/smoke.py": "80c6ed250089724a332ea0341ad6324757b19a5407d219f539d28bcdf7864ea4",
+    "open_decisions/image_jev/router.py": "e99db6dde898e7f7be4babcec2f4e545eedff51b04db8c7fe98e47e884a27c47",
+    "open_decisions/image_jev/speed.py": "5671a56aa16d4647dca8f3c360e83f98747641d7722ae184110806375448c5cb",
+    "open_decisions/image_jev/vision.py": "f9e988cae5184b09b0ebacec7f9baeb3db06e971862c18229dea1ee5034e2be2",
+    "open_decisions/scoring/__init__.py": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "open_decisions/scoring/prompt.py": "131916c014979500e5d2daceb94817a8942de8148966d3309c8ecbc8547027ee",
+    "requirements.lock": "974e3a19773d67b4de84842ffa4a3a537e2886240cdfb97d94216159804aa7e2",
+    "requirements.lock.sha256": "e2c447dea2405d458599f08d91d6d8ae774f85b7074de331a431a1ef43b7829a",
+    "requirements.txt": "321bb81a1bd43b4858cf724d22944ac3e5e93504a9bf231be88b6752b437a63c"
+  },
+  "image_route": "native",
+  "manifest_sha256": "1403eee576ec886cf6c3bcd2dbb02761fd9cd9200af118d2fff05da6eb4ecbd3",
+  "measurement_artifact": null,
+  "name": "HopitAI/image-hopper",
+  "scorer": "one-prefill-option-letter",
+  "status": "owner-review",
+  "system_kind": "routed",
+  "version": "image-jev-release/v1"
+}

adapter/README.md

@@ -0,0 +1,207 @@
+---
+base_model: Qwen/Qwen3.5-9B
+library_name: peft
+pipeline_tag: text-generation
+tags:
+- base_model:adapter:Qwen/Qwen3.5-9B
+- lora
+- transformers
+---
+
+# Model Card for Model ID
+
+<!-- Provide a quick summary of what the model is/does. -->
+
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+
+
+- **Developed by:** [More Information Needed]
+- **Funded by [optional]:** [More Information Needed]
+- **Shared by [optional]:** [More Information Needed]
+- **Model type:** [More Information Needed]
+- **Language(s) (NLP):** [More Information Needed]
+- **License:** [More Information Needed]
+- **Finetuned from model [optional]:** [More Information Needed]
+
+### Model Sources [optional]
+
+<!-- Provide the basic links for the model. -->
+
+- **Repository:** [More Information Needed]
+- **Paper [optional]:** [More Information Needed]
+- **Demo [optional]:** [More Information Needed]
+
+## Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+
+[More Information Needed]
+
+### Downstream Use [optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+
+[More Information Needed]
+
+### Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+
+[More Information Needed]
+
+## Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+[More Information Needed]
+
+### Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+
+## How to Get Started with the Model
+
+Use the code below to get started with the model.
+
+[More Information Needed]
+
+## Training Details
+
+### Training Data
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+[More Information Needed]
+
+### Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+#### Preprocessing [optional]
+
+[More Information Needed]
+
+
+#### Training Hyperparameters
+
+- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+
+#### Speeds, Sizes, Times [optional]
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+[More Information Needed]
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card if possible. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+[More Information Needed]
+
+#### Summary
+
+
+
+## Model Examination [optional]
+
+<!-- Relevant interpretability work for the model goes here -->
+
+[More Information Needed]
+
+## Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type:** [More Information Needed]
+- **Hours used:** [More Information Needed]
+- **Cloud Provider:** [More Information Needed]
+- **Compute Region:** [More Information Needed]
+- **Carbon Emitted:** [More Information Needed]
+
+## Technical Specifications [optional]
+
+### Model Architecture and Objective
+
+[More Information Needed]
+
+### Compute Infrastructure
+
+[More Information Needed]
+
+#### Hardware
+
+[More Information Needed]
+
+#### Software
+
+[More Information Needed]
+
+## Citation [optional]
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+**BibTeX:**
+
+[More Information Needed]
+
+**APA:**
+
+[More Information Needed]
+
+## Glossary [optional]
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+[More Information Needed]
+
+## More Information [optional]
+
+[More Information Needed]
+
+## Model Card Authors [optional]
+
+[More Information Needed]
+
+## Model Card Contact
+
+[More Information Needed]
+### Framework versions
+
+- PEFT 0.21.0

adapter/adapter_config.json

@@ -0,0 +1,56 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": null,
+  "base_model_name_or_path": "Qwen/Qwen3.5-9B",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "kasa_config": null,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 128,
+  "lora_bias": false,
+  "lora_dropout": 0.0,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "monteclora_config": null,
+  "peft_type": "LORA",
+  "peft_version": "0.21.0",
+  "qalora_group_size": 16,
+  "r": 64,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": [
+    "down_proj",
+    "q_proj",
+    "up_proj",
+    "out_proj",
+    "o_proj",
+    "gate_proj",
+    "in_proj_z",
+    "in_proj_a",
+    "in_proj_b",
+    "in_proj_qkv",
+    "k_proj",
+    "v_proj"
+  ],
+  "target_parameters": null,
+  "task_type": "CAUSAL_LM",
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false,
+  "velora_config": null
+}

adapter/adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6201fcb1c08144e465a03fd6f5355c4394b3bffaad659440fa64063dd4f71509
+size 692529024

base-model-files.json

@@ -0,0 +1,24 @@
+{
+  "files": {
+    ".gitattributes": "34448b82c17d60fec9b65b1f093c115ddbaadc04beb1b0140b6bfed2e012a930",
+    "LICENSE": "bbedc3fda3305820b977265f01b8619d87570a6739de3a5582c3464840f1e57a",
+    "README.md": "c5f5a8c2dddab69cfbf05279235aa5fddb137939a06539c4c7637aa900fef6d0",
+    "chat_template.jinja": "a4aee8afcf2e0711942cf848899be66016f8d14a889ff9ede07bca099c28f715",
+    "config.json": "d0883072e01861ed0b2d47be3c16c36a8e81c224c7ffaa310c6558fb3f932b05",
+    "merges.txt": "a9d356d7bdf1ef4949e3e748e95b8e10ad9d4e2e838eddc38a0a7b6b94d1db8d",
+    "model.safetensors-00001-of-00004.safetensors": "db6f444b43d318c92f360a13a25561a6a65b10c0631b8ed305a426dbaa6c380e",
+    "model.safetensors-00002-of-00004.safetensors": "31c7d7e2dd5d207840b31cc59083c8f4c4718959149e0358c0364052bb9a0330",
+    "model.safetensors-00003-of-00004.safetensors": "7ec36ba3a4176a44c3c0876ad80c56a2f70c84bf008d82e9501df642f17dadec",
+    "model.safetensors-00004-of-00004.safetensors": "b62b0c4cd7e44edee103ee8f4fe225f246d5e768e07bfd5f25b63a8aa1fdd0c6",
+    "model.safetensors.index.json": "26d3539b516be613f39563617cb9d33b3f83d401298125be392c80cefb8f7fe5",
+    "preprocessor_config.json": "27225450ac9c6529872ee1924fcb0962ff5634834f817040f444118116f4e516",
+    "tokenizer.json": "5f9e4d4901a92b997e463c1f46055088b6cca5ca61a6522d1b9f64c4bb81cb42",
+    "tokenizer_config.json": "316230d6a809701f4db5ea8f8fc862bc3a6f3229c937c174e674ff3ca0a64ac8",
+    "video_preprocessor_config.json": "7768af27c1fafa9cc9011c1dc20067e03f8915e03b63504550e11d5066986d13",
+    "vocab.json": "ce99b4cb2983d118806ce0a8b777a35b093e2000a503ebde25853284c9dfa003"
+  },
+  "model_id": "Qwen/Qwen3.5-9B",
+  "revision": "c202236235762e1c871ad0ccb60c8ee5ba337b9a",
+  "source_manifest_sha256": "2b890ff314357c061b6fb1e69dcf530344bc036d3dd35a40ce234e4de5d4670e",
+  "source_manifest_version": "image-jev/read-results/v1"
+}

calibration.json

@@ -0,0 +1,39 @@
+{
+  "adapter_sha256": "1e87a9966f77622d9b70b874364adc7ac1990b78735b5e08168d68106715d341",
+  "artifact_sha256": "fc29b120cf2ac00d1917c3712fcd2293b5be3c4746de7d4640b41c3cce251501",
+  "base": {
+    "repo": "Qwen/Qwen3.5-9B",
+    "revision": "c202236235762e1c871ad0ccb60c8ee5ba337b9a"
+  },
+  "global_temperature": 1.474397718906407,
+  "image_route": "native",
+  "image_route_config_sha256": "ba61089ca8f811596a21354e679df307d8ad73f5593e7bd904e581d36c1fcb1c",
+  "regularization": 8.0,
+  "route_type_counts": {
+    "default": {
+      "4-option": 233,
+      "5-marker": 114,
+      "yes/no": 253
+    },
+    "screen_geometry": {
+      "4-option": 101,
+      "5-marker": 230,
+      "yes/no": 0
+    }
+  },
+  "route_type_temperatures": {
+    "default": {
+      "4-option": 1.2338173243557795,
+      "5-marker": 1.976517229898893,
+      "yes/no": 1.3352577388514966
+    },
+    "screen_geometry": {
+      "4-option": 3.1395652047002547,
+      "5-marker": 1.3292399584473866,
+      "yes/no": 0.6572106043305197
+    }
+  },
+  "rules_sha256": "dabf0df7a787f305d272b061b6e0fe01fde605c7c8ddbca2c3da9e2e162e5c75",
+  "rules_version": "router-rules/v1",
+  "version": "image-jev/router-calibration/v1"
+}

open_decisions/image_jev/release/__init__.py

@@ -0,0 +1,7 @@
+"""Fallback release of the frozen base model with route-bound temperature calibration.
+
+``predictor`` is the request contract and readout, ``server`` the HTTP wrapper,
+``bundle`` the release directory generator, ``measure_body`` the board-style
+measurement manifest body builder.  Only ``predictor``, ``server`` and ``smoke``
+are shipped inside the release bundle.
+"""

open_decisions/image_jev/release/predictor.py

@@ -0,0 +1,586 @@
+"""Request contract, calibration and readout for Image Hopper releases.
+
+The model path is exactly the one evaluated in stage 2 (``deploy/modal_image_jev.py``
+``TorchPredictor`` on the native arm): :func:`vision.prepare_native` (processor-default
+resolution, no pixel budget), one prefill with a last-position vocabulary projection
+(:func:`vision.last_position_logits`), an FP32 softmax over the displayed option letters, and
+a per-answer-type (or route x answer-type) temperature from the bound calibration artifact.
+The routed system keeps its LoRA attached and enables it only for the registered text cues.
+Temperature scaling never changes the selected option.
+
+Wire format (TypeSafe ``/v1/systemone`` style, as used by published image submissions)::
+
+    {"state": <string or object, optional>,
+     "images": ["data:image/png;base64,...", ...],          # or bare base64
+     "questions": {"decision": {"type": "choice", "instructions": "...",
+                                "criteria": {"<name>": "<description>", ...}}}}
+
+Response::
+
+    {"model": NAME, "usage": {"input_tokens": n, "output_tokens": 0},
+     "answers": {"decision": {"type": "choice", "choice": "<name>",
+                              "probabilities": {"<name>": p, ...}}}}
+
+``noul`` (yes/no) questions answer ``{"type": "noul", "noul": P(yes)}``.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import json
+import math
+from contextlib import nullcontext
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+from open_decisions.image_jev import router, vision
+from open_decisions.image_jev.speed import AdapterSwitch, NativeCache, PhaseTimer
+
+
+BASE_REPO = "Qwen/Qwen3.5-9B"
+BASE_REVISION = "c202236235762e1c871ad0ccb60c8ee5ba337b9a"
+IMAGE_ROUTE = "native"
+CALIBRATION_VERSION = "image-jev/calibration/v2"
+# Same buckets as train.calibration.answer_type for requests without an explicit answer type
+# (two options -> yes/no, four -> 4-option, five -> 5-marker); other counts use the global
+# temperature.  Every evaluated item had 2, 4 or 5 options.
+TYPE_BUCKET_BY_OPTION_COUNT = {2: "yes/no", 4: "4-option", 5: "5-marker"}
+MAX_IMAGES = 4
+NOUL_OPTIONS = ({"name": "yes", "description": "Yes."}, {"name": "no", "description": "No."})
+CONTEXT_POLICIES = ("prepend", "ignore")
+_CALIBRATION_FIELDS = {
+    "artifact_sha256", "checkpoint_sha256", "global_temperature", "image_route",
+    "image_route_config_sha256", "regularization", "routing_config_sha256", "type_counts",
+    "type_temperatures", "validation", "version",
+}
+_ROUTED_CALIBRATION_FIELDS = {
+    "adapter_sha256", "artifact_sha256", "base", "global_temperature", "image_route",
+    "image_route_config_sha256", "regularization", "route_type_counts",
+    "route_type_temperatures", "rules_sha256", "rules_version", "version",
+}
+
+
+class RequestError(ValueError):
+    """A malformed or unsupported request (HTTP 400)."""
+
+
+def _compact(value: Any) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()
+
+
+def _temperature(value: Any, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{name} must be a number")
+    value = float(value)
+    if not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be finite and positive")
+    return value
+
+
+@dataclass(frozen=True)
+class Calibration:
+    """The route-bound temperature map (``image-jev/calibration/v2``) as served."""
+
+    global_temperature: float
+    type_temperatures: Mapping[str, float]
+    artifact_sha256: str
+    identity_sha256: str
+
+    @classmethod
+    def from_artifact(cls, value: Mapping[str, Any], *,
+                      checkpoint_sha256: str | None = "") -> "Calibration":
+        if not isinstance(value, Mapping) or set(value) != _CALIBRATION_FIELDS:
+            raise ValueError("calibration artifact fields differ from image-jev/calibration/v2")
+        body = {key: item for key, item in value.items() if key != "artifact_sha256"}
+        if value["artifact_sha256"] != hashlib.sha256(_compact(body)).hexdigest():
+            raise ValueError("calibration artifact hash differs")
+        if value["version"] != CALIBRATION_VERSION:
+            raise ValueError("calibration artifact version differs")
+        if value["image_route"] != IMAGE_ROUTE:
+            raise ValueError("calibration was not fitted on the native image route")
+        if value["image_route_config_sha256"] != vision.IMAGE_ROUTE_CONFIG_SHA256[IMAGE_ROUTE]:
+            raise ValueError("calibration image-route configuration differs")
+        if value["routing_config_sha256"] != vision.ROUTING_CONFIG_SHA256:
+            raise ValueError("calibration routing configuration differs")
+        checkpoint = value["checkpoint_sha256"]
+        if not isinstance(checkpoint, str) or (checkpoint and
+                                               (len(checkpoint) != 64 or any(
+                                                   char not in "0123456789abcdef"
+                                                   for char in checkpoint))):
+            raise ValueError("calibration checkpoint_sha256 must be empty or a lowercase SHA-256")
+        if checkpoint_sha256 is not None and checkpoint != checkpoint_sha256:
+            target = "frozen base" if checkpoint_sha256 == "" else "selected adapter"
+            raise ValueError(f"calibration is not bound to the {target}")
+        temperatures = value["type_temperatures"]
+        if not isinstance(temperatures, Mapping):
+            raise ValueError("type_temperatures must be an object")
+        return cls(
+            global_temperature=_temperature(value["global_temperature"], "global_temperature"),
+            type_temperatures={
+                str(key): _temperature(item, f"type_temperatures[{key!r}]")
+                for key, item in temperatures.items()
+            },
+            artifact_sha256=str(value["artifact_sha256"]),
+            identity_sha256=hashlib.sha256(_compact(dict(value))).hexdigest(),
+        )
+
+    @classmethod
+    def load(cls, path: str | Path, *, checkpoint_sha256: str | None = "") -> "Calibration":
+        try:
+            value = json.loads(Path(path).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise ValueError(f"cannot load calibration {path}: {error}") from error
+        return cls.from_artifact(value, checkpoint_sha256=checkpoint_sha256)
+
+    def temperature(self, n_options: int) -> float:
+        bucket = TYPE_BUCKET_BY_OPTION_COUNT.get(int(n_options))
+        if bucket is None:
+            return self.global_temperature
+        return self.type_temperatures.get(bucket, self.global_temperature)
+
+
+@dataclass(frozen=True)
+class RoutedCalibration:
+    """Serving view of ``image-jev/router-calibration/v1``."""
+
+    global_temperature: float
+    route_type_temperatures: Mapping[str, Mapping[str, float]]
+    artifact_sha256: str
+    identity_sha256: str
+    adapter_sha256: str
+    base: Mapping[str, str]
+    rules_sha256: str
+
+    @classmethod
+    def from_artifact(
+        cls, value: Mapping[str, Any], *, adapter_sha256: str | None = None,
+        base: Mapping[str, str] | None = None,
+    ) -> "RoutedCalibration":
+        if not isinstance(value, Mapping) or set(value) != _ROUTED_CALIBRATION_FIELDS:
+            raise ValueError("routed calibration artifact fields differ")
+        body = {key: item for key, item in value.items() if key != "artifact_sha256"}
+        if value["artifact_sha256"] != hashlib.sha256(_compact(body)).hexdigest():
+            raise ValueError("routed calibration artifact hash differs")
+        if value["version"] != "image-jev/router-calibration/v1":
+            raise ValueError("routed calibration artifact version differs")
+        if value["rules_version"] != router.RULES_VERSION \
+                or value["rules_sha256"] != router.RULES_SHA256:
+            raise ValueError("routed calibration rules binding differs")
+        if value["image_route"] != IMAGE_ROUTE \
+                or value["image_route_config_sha256"] != vision.IMAGE_ROUTE_CONFIG_SHA256[IMAGE_ROUTE]:
+            raise ValueError("routed calibration image-route binding differs")
+        if adapter_sha256 is not None and value["adapter_sha256"] != adapter_sha256:
+            raise ValueError("routed calibration adapter binding differs")
+        if base is not None and value["base"] != dict(base):
+            raise ValueError("routed calibration base binding differs")
+        if (
+            not isinstance(value["adapter_sha256"], str)
+            or len(value["adapter_sha256"]) != 64
+            or any(char not in "0123456789abcdef" for char in value["adapter_sha256"])
+        ):
+            raise ValueError("routed calibration adapter hash is invalid")
+        if not isinstance(value["base"], Mapping) or set(value["base"]) != {"repo", "revision"}:
+            raise ValueError("routed calibration base pin differs")
+        route_temperatures = value["route_type_temperatures"]
+        route_counts = value["route_type_counts"]
+        if not isinstance(route_temperatures, Mapping) or set(route_temperatures) != set(router.ROUTES):
+            raise ValueError("routed calibration routes differ")
+        if not isinstance(route_counts, Mapping) or set(route_counts) != set(router.ROUTES):
+            raise ValueError("routed calibration count routes differ")
+        checked = {}
+        for route_name in router.ROUTES:
+            values = route_temperatures[route_name]
+            counts = route_counts[route_name]
+            if (
+                not isinstance(values, Mapping)
+                or set(values) != set(TYPE_BUCKET_BY_OPTION_COUNT.values())
+                or not isinstance(counts, Mapping)
+                or set(counts) != set(TYPE_BUCKET_BY_OPTION_COUNT.values())
+            ):
+                raise ValueError("routed calibration temperatures must be objects")
+            if any(
+                isinstance(count, bool) or not isinstance(count, int) or count < 0
+                for count in counts.values()
+            ):
+                raise ValueError("routed calibration counts are invalid")
+            checked[route_name] = {
+                str(kind): _temperature(item, f"route_type_temperatures[{route_name}][{kind}]")
+                for kind, item in values.items()
+            }
+        return cls(
+            global_temperature=_temperature(value["global_temperature"], "global_temperature"),
+            route_type_temperatures=checked,
+            artifact_sha256=str(value["artifact_sha256"]),
+            identity_sha256=hashlib.sha256(_compact(dict(value))).hexdigest(),
+            adapter_sha256=str(value["adapter_sha256"]), base=dict(value["base"]),
+            rules_sha256=str(value["rules_sha256"]),
+        )
+
+    def temperature(self, n_options: int, route_name: str) -> float:
+        if route_name not in router.ROUTES:
+            raise ValueError("unknown routed calibration route")
+        bucket = TYPE_BUCKET_BY_OPTION_COUNT.get(int(n_options))
+        if bucket is None:
+            return self.global_temperature
+        return self.route_type_temperatures[route_name].get(bucket, self.global_temperature)
+
+
+def serving_calibration_from_artifact(
+    value: Mapping[str, Any], *, checkpoint_sha256: str | None = "",
+    adapter_sha256: str | None = None, base: Mapping[str, str] | None = None,
+) -> Calibration | RoutedCalibration:
+    if not isinstance(value, Mapping):
+        raise ValueError("calibration artifact must be an object")
+    if value.get("version") == "image-jev/router-calibration/v1":
+        return RoutedCalibration.from_artifact(
+            value, adapter_sha256=adapter_sha256, base=base
+        )
+    return Calibration.from_artifact(value, checkpoint_sha256=checkpoint_sha256)
+
+
+@dataclass(frozen=True)
+class Question:
+    qid: str
+    kind: str
+    instructions: str
+    options: tuple[dict[str, str], ...]
+    route_instructions: str | None = None
+
+
+def _image_source(value: Any, index: int):
+    if not isinstance(value, str) or not value:
+        raise RequestError(f"image {index} must be a non-empty data URI or base64 string")
+    if value.startswith("data:"):
+        return value
+    if (len(value) // 4) * 3 > vision.MAX_IMAGE_BYTES + 2:
+        raise RequestError(f"image {index} exceeds {vision.MAX_IMAGE_BYTES} bytes")
+    try:
+        return base64.b64decode(value, validate=True)
+    except (binascii.Error, ValueError):
+        raise RequestError(f"image {index} is neither a data URI nor valid base64") from None
+
+
+def _images(body: Mapping[str, Any]) -> list:
+    raw = body.get("images")
+    state = body.get("state")
+    if raw is None and isinstance(state, Mapping):
+        raw = state.get("images", state.get("image"))
+    if isinstance(raw, str):
+        raw = [raw]
+    if not isinstance(raw, list) or not raw:
+        raise RequestError("request needs at least one image in 'images'")
+    if len(raw) > MAX_IMAGES:
+        raise RequestError(f"at most {MAX_IMAGES} images per request")
+    return [_image_source(value, index) for index, value in enumerate(raw)]
+
+
+def _context(state: Any) -> str | None:
+    if state is None:
+        return None
+    if isinstance(state, str):
+        return state.strip() or None
+    if isinstance(state, Mapping):
+        rest = {key: value for key, value in state.items() if key not in {"image", "images"}}
+        return json.dumps(rest, ensure_ascii=False, sort_keys=True) if rest else None
+    raise RequestError("state must be a string or an object")
+
+
+def _options(criteria: Any) -> tuple[dict[str, str], ...]:
+    if isinstance(criteria, Mapping):
+        values = [{"name": str(name), "description": str(text)} for name, text in criteria.items()]
+    elif isinstance(criteria, list):
+        values = []
+        for index, option in enumerate(criteria):
+            if isinstance(option, str):
+                values.append({"name": option, "description": option})
+            elif isinstance(option, Mapping) and "name" in option:
+                values.append({"name": str(option["name"]),
+                               "description": str(option.get("description", option["name"]))})
+            else:
+                raise RequestError(f"criteria[{index}] must be text or an object with a name")
+    else:
+        raise RequestError("choice criteria must be an object or a list")
+    names = [value["name"] for value in values]
+    if not 2 <= len(values) <= len(vision.hopper_prompt.LETTERS):
+        raise RequestError("choice questions need 2 to 26 options")
+    if len(set(names)) != len(names) or any(not name for name in names):
+        raise RequestError("option names must be unique and non-empty")
+    return tuple(values)
+
+
+def parse_request(body: Any, *, context_policy: str = "prepend") -> tuple[list, list[Question]]:
+    """Validate a ``/v1/systemone`` body into images and questions (no model work)."""
+    if context_policy not in CONTEXT_POLICIES:
+        raise ValueError(f"context_policy must be one of {CONTEXT_POLICIES}")
+    if not isinstance(body, Mapping):
+        raise RequestError("request body must be a JSON object")
+    questions = body.get("questions")
+    if not isinstance(questions, Mapping) or not questions:
+        raise RequestError("request needs a non-empty 'questions' object")
+    images = _images(body)
+    context = _context(body.get("state")) if context_policy == "prepend" else None
+    parsed = []
+    for qid, spec in questions.items():
+        if not isinstance(spec, Mapping):
+            raise RequestError(f"question {qid!r} must be an object")
+        kind = spec.get("type", "choice")
+        instructions = spec.get("instructions")
+        if not isinstance(instructions, str) or not instructions.strip():
+            raise RequestError(f"question {qid!r} needs non-empty instructions")
+        if context:
+            instructions = f"{context}\n\n{instructions}"
+        if kind == "choice":
+            options = _options(spec.get("criteria"))
+        elif kind == "noul":
+            options = NOUL_OPTIONS
+        else:
+            raise RequestError(f"question {qid!r}: unsupported type {kind!r} (choice or noul)")
+        parsed.append(Question(str(qid), kind, instructions, options, str(spec["instructions"])))
+    return images, parsed
+
+
+def _length(value: Any) -> int:
+    shape = getattr(value, "shape", None)
+    if shape is not None:
+        return int(shape[-1])
+    first = value[0] if value and isinstance(value[0], (list, tuple)) else value
+    return len(first)
+
+
+class Predictor:
+    """One prefill per question; calibrated option probabilities in the board's shape."""
+
+    def __init__(self, model, processor, calibration: Calibration | RoutedCalibration, *, model_name: str,
+                 context_policy: str = "prepend", max_input_tokens: int | None = None,
+                 inference_context: Callable[[], Any] | None = None,
+                 adapter_context: Callable[[str], Any] | None = None,
+                 synchronize: Callable[[], Any] | None = None, forward_call=None) -> None:
+        if context_policy not in CONTEXT_POLICIES:
+            raise ValueError(f"context_policy must be one of {CONTEXT_POLICIES}")
+        self.model, self.processor, self.calibration = model, processor, calibration
+        self.model_name = model_name
+        self.context_policy = context_policy
+        self.max_input_tokens = max_input_tokens
+        self._inference_context = inference_context
+        self._adapter_context = adapter_context
+        self._synchronize = synchronize
+        self._forward_call = forward_call
+        self._cache = NativeCache(processor)
+        try:
+            self.device = next(model.parameters()).device
+        except (StopIteration, AttributeError):
+            self.device = None
+
+    def _read(self, images: Sequence, question: Question, *, loaded_images=None, timer=None) -> tuple[list[float], int]:
+        example = {"question": question.instructions, "options": list(question.options),
+                   "images": list(images)}
+        try:
+            prepared = vision.prepare_native(example, self.processor, loaded_images=loaded_images,
+                                             cache=self._cache, timer=timer, device=self.device)
+        except (TypeError, ValueError) as error:
+            raise RequestError(str(error)) from error
+        tokens = _length(prepared.input_ids)
+        if self.max_input_tokens is not None and tokens > self.max_input_tokens:
+            raise RequestError(
+                f"processed request has {tokens} tokens, above the configured "
+                f"{self.max_input_tokens}-token limit"
+            )
+        with timer.phase("route_adapter_switch"):
+            route_name = None
+            if isinstance(self.calibration, RoutedCalibration):
+                route_name = router.route(
+                    question.route_instructions or question.instructions, question.options
+                )
+                temperature = self.calibration.temperature(len(question.options), route_name)
+            else:
+                temperature = self.calibration.temperature(len(question.options))
+            route_context = (
+                self._adapter_context(route_name) if self._adapter_context is not None
+                else nullcontext()
+            )
+        inference_context = (
+            self._inference_context() if self._inference_context is not None else nullcontext()
+        )
+        with route_context:
+            with inference_context:
+                logits = vision.last_position_logits(
+                    self.model, prepared, timer=timer, forward_call=self._forward_call)
+                with timer.phase("readout_calibration"):
+                    probabilities = vision.option_probs(
+                        logits, prepared.letter_token_ids, temperature=temperature)
+        with timer.phase("readout_calibration"):
+            total = math.fsum(probabilities)
+            return [value / total for value in probabilities], tokens
+
+    def __call__(self, body: Any, *, phase_seconds=None) -> dict[str, Any]:
+        timer = PhaseTimer(phase_seconds, self._synchronize)
+        with timer.phase("decode_load"):
+            images, questions = parse_request(body, context_policy=self.context_policy)
+        return self.predict_questions(images, questions, timer=timer)
+
+    def predict_questions(self, images, questions, *, timer=None) -> dict[str, Any]:
+        timer = timer or PhaseTimer()
+        with timer.phase("decode_load"):
+            try:
+                loaded = [vision._load_image(source, exif_transpose=False) for source in images]
+                loaded = [image if image.mode == "RGB" else image.convert("RGB") for image in loaded]
+            except (TypeError, ValueError) as error:
+                raise RequestError(str(error)) from error
+        answers, input_tokens = {}, 0
+        for question in questions:
+            probabilities, tokens = self._read(images, question, loaded_images=loaded, timer=timer)
+            with timer.phase("response_build"):
+                input_tokens += tokens
+                names = [option["name"] for option in question.options]
+                # Exact ties go to the first option, as the harness's scorer breaks them.
+                top = max(range(len(names)), key=lambda index: (probabilities[index], -index))
+                if question.kind == "noul":
+                    answers[question.qid] = {"type": "noul", "noul": probabilities[0]}
+                else:
+                    answers[question.qid] = {
+                        "type": "choice", "choice": names[top],
+                        "probabilities": dict(zip(names, probabilities, strict=True)),
+                    }
+        with timer.phase("response_build"):
+            return {"model": self.model_name,
+                    "usage": {"input_tokens": input_tokens, "output_tokens": 0},
+                    "answers": answers}
+
+
+def file_sha256(path: str | Path) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def tree_sha256(path: str | Path) -> str:
+    """Hash a local adapter as sorted relative paths and file-byte hashes."""
+    root = Path(path)
+    rows = [
+        {"path": item.relative_to(root).as_posix(), "sha256": file_sha256(item)}
+        for item in sorted(root.rglob("*")) if item.is_file()
+    ]
+    if not rows:
+        raise ValueError("adapter directory is empty")
+    return hashlib.sha256(_compact(rows)).hexdigest()
+
+
+def verify_snapshot(snapshot: str | Path, expected: Mapping[str, str]) -> dict[str, str]:
+    """Hash every file listed for the pinned base revision; refuse any difference."""
+    root = Path(snapshot)
+    failures = []
+    for name, digest in sorted(expected.items()):
+        path = root / name
+        if not path.is_file():
+            failures.append(f"missing {name}")
+        elif file_sha256(path) != digest:
+            failures.append(f"hash differs: {name}")
+    if failures:
+        raise RuntimeError("base model snapshot differs from the pinned revision: "
+                           + "; ".join(failures))
+    return dict(expected)
+
+
+def check_fast_path() -> None:
+    """Qwen3.5's linear-attention layers need these kernels; the fallback is far slower."""
+    missing = []
+    for module in ("fla", "causal_conv1d"):
+        try:
+            __import__(module)
+        except ImportError:
+            missing.append(module)
+    if missing:
+        raise RuntimeError(
+            "fast linear-attention kernels unavailable (" + ", ".join(missing) + "); install "
+            "flash-linear-attention and causal-conv1d from requirements.txt, or pass "
+            "--allow-slow-path"
+        )
+
+
+def load_predictor(*, calibration_path: str | Path, model_name: str,
+                   model_cache: str | None = None, offline: bool = False,
+                   adapter_path: str | Path | None = None,
+                   base_hashes_path: str | Path | None = None, device: str = "cuda",
+                   context_policy: str = "prepend", max_input_tokens: int | None = None,
+                   allow_slow_path: bool = False) -> tuple[Predictor, dict[str, Any]]:
+    """Load the pinned frozen base in bf16 and return the predictor and its provenance."""
+    import platform
+
+    import torch
+    import transformers
+    from huggingface_hub import snapshot_download
+    from transformers import AutoProcessor
+
+    if not allow_slow_path:
+        check_fast_path()
+    adapter = None if adapter_path is None else Path(adapter_path)
+    adapter_sha256 = "" if adapter is None else tree_sha256(adapter)
+    try:
+        calibration_value = json.loads(Path(calibration_path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot load calibration {calibration_path}: {error}") from error
+    base_pin = {"repo": BASE_REPO, "revision": BASE_REVISION}
+    calibration = serving_calibration_from_artifact(
+        calibration_value, checkpoint_sha256=adapter_sha256,
+        adapter_sha256=adapter_sha256 or None, base=base_pin,
+    )
+    routed = isinstance(calibration, RoutedCalibration)
+    if routed and adapter is None:
+        raise ValueError("routed calibration requires the screen_geometry adapter")
+    snapshot = Path(snapshot_download(BASE_REPO, revision=BASE_REVISION, cache_dir=model_cache,
+                                      local_files_only=offline))
+    verified = None
+    if base_hashes_path is not None:
+        listing = json.loads(Path(base_hashes_path).read_text(encoding="utf-8"))
+        if listing.get("model_id") != BASE_REPO or listing.get("revision") != BASE_REVISION:
+            raise RuntimeError("base-model hash listing is for a different model or revision")
+        verified = len(verify_snapshot(snapshot, listing["files"]))
+    processor = AutoProcessor.from_pretrained(str(snapshot), trust_remote_code=False, use_fast=True)
+    auto_model = getattr(transformers, "AutoModelForMultimodalLM", None) or getattr(
+        transformers, "AutoModelForImageTextToText")
+    model = auto_model.from_pretrained(str(snapshot), torch_dtype=torch.bfloat16,
+                                       device_map=device, trust_remote_code=False, attn_implementation="sdpa")
+    if adapter is not None:
+        from peft import PeftModel
+
+        loaded = PeftModel.from_pretrained(
+            model, str(adapter), **({"adapter_name": router.SCREEN_GEOMETRY} if routed else {})
+        )
+        model = loaded if routed else loaded.merge_and_unload()
+    model = model.eval()
+    adapter_context = AdapterSwitch(model) if routed else None
+    predictor = Predictor(model, processor, calibration, model_name=model_name,
+                          context_policy=context_policy, max_input_tokens=max_input_tokens,
+                          inference_context=torch.inference_mode,
+                          adapter_context=adapter_context,
+                          synchronize=(torch.cuda.synchronize if str(device).startswith("cuda") else None))
+    provenance = {
+        "base_repo": BASE_REPO, "base_revision": BASE_REVISION,
+        "base_files_verified": verified,
+        "adapter": None if adapter is None else {"path": str(adapter), "sha256": adapter_sha256},
+        "image_route": IMAGE_ROUTE,
+        "image_route_config_sha256": vision.IMAGE_ROUTE_CONFIG_SHA256[IMAGE_ROUTE],
+        "calibration_artifact_sha256": calibration.artifact_sha256,
+        "calibration_identity_sha256": calibration.identity_sha256,
+        "system_kind": "routed" if routed else "single-route",
+        "router_rules_version": router.RULES_VERSION if routed else None,
+        "router_rules_sha256": router.RULES_SHA256 if routed else None,
+        "adapter_switching": "PEFT layer enable/disable on route transition" if routed else None,
+        "precision": "bfloat16", "attention": "sdpa", "processor_use_fast": True, "scorer": "one-prefill-option-letter",
+        "context_policy": context_policy, "max_input_tokens": max_input_tokens,
+        "torch_version": torch.__version__, "transformers_version": transformers.__version__,
+        "python_version": platform.python_version(),
+    }
+    return predictor, provenance
+
+
+__all__ = [
+    "BASE_REPO", "BASE_REVISION", "Calibration", "RoutedCalibration", "Predictor", "Question", "RequestError",
+    "TYPE_BUCKET_BY_OPTION_COUNT", "check_fast_path", "load_predictor", "parse_request",
+    "serving_calibration_from_artifact", "tree_sha256", "verify_snapshot",
+]

open_decisions/image_jev/release/server.py

@@ -0,0 +1,118 @@
+"""HTTP server for the frozen-base image decision release.
+
+  POST /v1/systemone   TypeSafe-style request (see ``predictor``), JSON response
+  GET  /health         model, pinned base revision and calibration identity
+
+Single-threaded on purpose: one GPU, one request at a time, as published image
+submissions are served.  Any ``Authorization`` header is ignored.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, Callable, Mapping
+
+from open_decisions.image_jev.release.predictor import CONTEXT_POLICIES, RequestError
+
+MAX_BODY_BYTES = 128 * 1024 * 1024
+DEFAULT_NAME = "image-hopper"
+
+
+def handler(predict: Callable[[Any], dict], health: Mapping[str, Any], *, phase_timing=False):
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *args):  # quiet; the harness measures latency itself
+            pass
+
+        def _send(self, status: int, value: Mapping[str, Any]) -> None:
+            payload = json.dumps(value, ensure_ascii=False).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.end_headers()
+            self.wfile.write(payload)
+
+        def do_GET(self):
+            if self.path == "/health":
+                self._send(200, dict(health))
+            else:
+                self._send(404, {"error": "not found"})
+
+        def do_POST(self):
+            if self.path != "/v1/systemone":
+                self._send(404, {"error": "not found"})
+                return
+            try:
+                length = int(self.headers.get("Content-Length", "0"))
+            except ValueError:
+                length = -1
+            if not 0 < length <= MAX_BODY_BYTES:
+                self._send(400, {"error": "missing or oversized request body"})
+                return
+            try:
+                body = json.loads(self.rfile.read(length))
+                if phase_timing:
+                    seconds = {}
+                    result = predict(body, phase_seconds=seconds)
+                    result["phase_seconds"] = seconds
+                else:
+                    result = predict(body)
+                self._send(200, result)
+            except (json.JSONDecodeError, RequestError) as error:
+                self._send(400, {"error": str(error)})
+            except Exception as error:  # noqa: BLE001 - report, keep serving
+                self._send(500, {"error": f"{type(error).__name__}: {error}"})
+
+    return Handler
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--calibration", default="calibration.json")
+    parser.add_argument("--adapter", default=None,
+                        help="optional local adapter directory; calibration must bind its tree hash")
+    parser.add_argument("--base-hashes", default="base-model-files.json",
+                        help="hash listing of the pinned base snapshot; '' skips the check")
+    parser.add_argument("--model-cache", default=None, help="Hugging Face cache directory")
+    parser.add_argument("--offline", action="store_true", help="never download; use the cache")
+    parser.add_argument("--name", default=DEFAULT_NAME)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8080)
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument("--context-policy", choices=CONTEXT_POLICIES, default="prepend",
+                        help="how request 'state' text reaches the prompt")
+    parser.add_argument("--max-input-tokens", type=int, default=None,
+                        help="refuse (HTTP 400) requests above this many processed tokens")
+    parser.add_argument("--allow-slow-path", action="store_true")
+    parser.add_argument("--phase-timing", action="store_true",
+                        help="diagnostic synchronized phase_seconds in responses; default off")
+    return parser
+
+
+def main(argv=None) -> int:
+    from open_decisions.image_jev.release.predictor import load_predictor
+
+    args = build_parser().parse_args(argv)
+    predictor, provenance = load_predictor(
+        calibration_path=args.calibration, model_name=args.name, model_cache=args.model_cache,
+        adapter_path=args.adapter,
+        offline=args.offline, base_hashes_path=args.base_hashes or None, device=args.device,
+        context_policy=args.context_policy, max_input_tokens=args.max_input_tokens,
+        allow_slow_path=args.allow_slow_path,
+    )
+    health = {"model": args.name, **provenance}
+    print(json.dumps(health, indent=2, sort_keys=True), file=sys.stderr)
+    server = HTTPServer((args.host, args.port), handler(predictor, health, phase_timing=args.phase_timing))
+    print(f"serving {args.name} on http://{args.host}:{args.port}/v1/systemone", file=sys.stderr)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

open_decisions/image_jev/release/smoke.py

@@ -0,0 +1,223 @@
+"""Local smoke test with a fake processor and model (CPU, no weights, no network).
+
+Checks the request contract end to end through the real HTTP handler: native image
+preparation, the one-prefill readout, the per-answer-type temperature, the response
+shape, and refusal of malformed requests.  Run from the bundle root::
+
+    python -m open_decisions.image_jev.release.smoke --calibration calibration.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import io
+import json
+import math
+from pathlib import Path
+
+LETTER_BASE = 1000
+VOCABULARY = 1100
+
+
+class FakeTokenizer:
+    def encode(self, text, add_special_tokens=False):
+        return [LETTER_BASE + ord(text) - ord("A")]
+
+
+class FakeProcessor:
+    """Shapes like the real processor's output; one token per prompt character."""
+
+    def __init__(self):
+        self.tokenizer = FakeTokenizer()
+
+    def apply_chat_template(self, messages, **kwargs):
+        assert kwargs.get("enable_thinking") is False
+        return "\n".join(message["content"] for message in messages)
+
+    def __call__(self, *, text, images, padding, return_tensors):
+        import torch
+
+        ids = torch.tensor([[ord(char) % 256 for char in text[0]]], dtype=torch.long)
+        pixels = torch.stack([
+            torch.tensor(list(image.convert("L").resize((4, 4)).tobytes()), dtype=torch.float32)
+            for image in images
+        ])
+        grid = torch.tensor([[1, 2, 2]] * len(images), dtype=torch.long)
+        return {"input_ids": ids, "pixel_values": pixels, "image_grid_thw": grid}
+
+
+def _fake_model():
+    import torch
+
+    class FakeModel(torch.nn.Module):
+        """Letter k gets logit -0.5 k: option A always leads, by a fixed margin."""
+
+        def __init__(self):
+            super().__init__()
+            self.anchor = torch.nn.Parameter(torch.zeros(1))
+            self.calls = 0
+
+        def forward(self, input_ids, pixel_values, image_grid_thw, use_cache=False,
+                    return_dict=True, logits_to_keep=None, **_kwargs):
+            assert logits_to_keep == 1 and use_cache is False
+            self.calls += 1
+            logits = torch.full((input_ids.shape[0], 1, VOCABULARY), -50.0)
+            for index in range(26):
+                logits[:, 0, LETTER_BASE + index] = -0.5 * index
+            return _Output(logits=logits + self.anchor)
+
+    return FakeModel().eval()
+
+
+class _Output(dict):
+    """Model output readable both as a mapping and by attribute, like transformers' outputs."""
+
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError as error:
+            raise AttributeError(name) from error
+
+
+def _png() -> str:
+    from PIL import Image
+
+    buffer = io.BytesIO()
+    Image.new("RGB", (64, 48), (90, 140, 200)).save(buffer, format="PNG")
+    return "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode("ascii")
+
+
+def _expected(n_options: int, temperature: float) -> list[float]:
+    weights = [math.exp(-0.5 * index / temperature) for index in range(n_options)]
+    total = sum(weights)
+    return [weight / total for weight in weights]
+
+
+class _MemoryConnection:
+    """Minimal socket facade for one BaseHTTPRequestHandler exchange."""
+
+    def __init__(self, request: bytes):
+        self.request = io.BytesIO(request)
+        self.response = io.BytesIO()
+
+    def makefile(self, mode, _buffering=None):
+        return self.request if "r" in mode else self.response
+
+    def sendall(self, value):
+        self.response.write(value)
+
+    def close(self):
+        pass
+
+
+def _exchange(handler_type, method: str, path: str, body=None) -> tuple[int, dict]:
+    payload = b"" if body is None else json.dumps(body).encode("utf-8")
+    headers = [f"{method} {path} HTTP/1.1", "Host: smoke"]
+    if body is not None:
+        headers += ["Content-Type: application/json", f"Content-Length: {len(payload)}"]
+    request = ("\r\n".join(headers) + "\r\n\r\n").encode("ascii") + payload
+    connection = _MemoryConnection(request)
+    handler_type(connection, ("127.0.0.1", 1), object())
+    head, raw_body = connection.response.getvalue().split(b"\r\n\r\n", 1)
+    status = int(head.splitlines()[0].split()[1])
+    return status, json.loads(raw_body)
+
+
+def run(calibration_path: str | Path) -> dict:
+    from open_decisions.image_jev import router
+    from open_decisions.image_jev.release.predictor import (
+        Predictor, RoutedCalibration, serving_calibration_from_artifact,
+    )
+    from open_decisions.image_jev.release.server import handler
+
+    # The fake model validates the readout for either frozen-base or adapter bundles. The
+    # bundle builder/server perform the real checkpoint-binding check.
+    artifact = json.loads(Path(calibration_path).read_text(encoding="utf-8"))
+    calibration = serving_calibration_from_artifact(
+        artifact, checkpoint_sha256=None, adapter_sha256=None, base=None
+    )
+    model = _fake_model()
+    predictor = Predictor(model, FakeProcessor(), calibration, model_name="smoke")
+    handler_type = handler(predictor, {"model": "smoke"})
+
+    def post(body) -> tuple[int, dict]:
+        return _exchange(handler_type, "POST", "/v1/systemone", body)
+
+    image = _png()
+    checks = {}
+    try:
+        status, health = _exchange(handler_type, "GET", "/health")
+        assert status == 200 and health == {"model": "smoke"}
+        checks["health_shape"] = True
+
+        status, body = post({
+            "state": "", "images": [image],
+            "questions": {
+                "four": {"type": "choice", "instructions": "Which shelf is fullest?",
+                         "criteria": {"top": "Top shelf", "middle": "Middle shelf",
+                                      "bottom": "Bottom shelf", "none": "All equal"}},
+                "three": {"type": "choice", "instructions": "Pick one.",
+                          "criteria": ["red", "green", "blue"]},
+                "binary": {"type": "noul", "instructions": "Is the item damaged?"},
+            },
+        })
+        assert status == 200, body
+        assert set(body) == {"model", "usage", "answers"} and body["model"] == "smoke"
+        assert set(body["usage"]) == {"input_tokens", "output_tokens"}
+        answers = body["answers"]
+        assert set(answers) == {"four", "three", "binary"}
+        assert set(answers["four"]) == {"type", "choice", "probabilities"}
+        assert set(answers["binary"]) == {"type", "noul"}
+        four = answers["four"]["probabilities"]
+        assert list(four) == ["top", "middle", "bottom", "none"]
+        assert answers["four"]["choice"] == "top"
+        four_temperature = (
+            calibration.temperature(4, router.DEFAULT)
+            if isinstance(calibration, RoutedCalibration) else calibration.temperature(4)
+        )
+        for name, got, want in zip(four, four.values(), _expected(4, four_temperature)):
+            assert abs(got - want) < 1e-6, (name, got, want)
+        three = answers["three"]["probabilities"]
+        for got, want in zip(three.values(), _expected(3, calibration.global_temperature)):
+            assert abs(got - want) < 1e-6
+        binary_temperature = (
+            calibration.temperature(2, router.DEFAULT)
+            if isinstance(calibration, RoutedCalibration) else calibration.temperature(2)
+        )
+        want_yes = _expected(2, binary_temperature)[0]
+        assert abs(answers["binary"]["noul"] - want_yes) < 1e-6
+        assert body["usage"]["output_tokens"] == 0 and body["usage"]["input_tokens"] > 0
+        assert model.calls == 3
+        checks["calibrated_probabilities"] = True
+        checks["systemone_response_shape"] = True
+
+        bare = image.split(",", 1)[1]
+        status, body = post({"images": [bare], "questions": {"d": {
+            "instructions": "Pick.", "criteria": {"a": "A", "b": "B"}}}})
+        assert status == 200 and set(body["answers"]["d"]["probabilities"]) == {"a", "b"}
+        checks["bare_base64_image"] = True
+
+        for bad in ({"questions": {"d": {"instructions": "x", "criteria": ["a", "b"]}}},
+                    {"images": [image], "questions": {"d": {"type": "score", "instructions": "x"}}},
+                    {"images": [image], "questions": {"d": {"instructions": "x", "criteria": ["a"]}}}):
+            status, body = post(bad)
+            assert status == 400 and "error" in body, (bad, status, body)
+        checks["malformed_requests_refused"] = True
+    finally:
+        pass
+    return {"ok": True, "checks": checks,
+            "calibration_identity_sha256": calibration.identity_sha256}
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--calibration", default="calibration.json")
+    args = parser.parse_args(argv)
+    print(json.dumps(run(args.calibration), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

open_decisions/image_jev/router.py

@@ -0,0 +1,121 @@
+"""Deterministic text-only router registered as ``router-rules/v1``.
+
+Only the question and visible option text are inspected.  Source metadata,
+board categories, images, and conversation state are intentionally absent
+from this API.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+RULES_VERSION = "router-rules/v1"
+SCREEN_GEOMETRY = "screen_geometry"
+DEFAULT = "default"
+ROUTES = (SCREEN_GEOMETRY, DEFAULT)
+
+GUI_TARGET_CUES = (
+    "marker", "click", "tap", "button", "icon", "menu", "toolbar", "tab",
+    "window", "dialog", "element", "on screen", "screenshot", "cursor", "link",
+    "field",
+)
+GEOMETRY_CUES = (
+    "angle", "triangle", "circle", "radius", "diameter", "perimeter", "area of",
+    "length of", "parallel", "perpendicular", "polygon", "quadrilateral", "chord",
+    "tangent", "arc", "degrees", "°", "find x", "find y", r"\triangle",
+)
+LITERAL_CUES = ("°", r"\triangle")
+
+RULE_DEFINITION = {
+    "version": RULES_VERSION,
+    "input": "question+option-text-only",
+    "case_sensitive": False,
+    "matching": {
+        "word_and_phrase_cues": "unicode-word-boundaries",
+        "literal_cues": list(LITERAL_CUES),
+    },
+    "screen_geometry": {
+        "gui_target_cues": list(GUI_TARGET_CUES),
+        "geometry_cues": list(GEOMETRY_CUES),
+    },
+    "fallback": DEFAULT,
+    "ambiguous": DEFAULT,
+}
+
+
+def _canonical_bytes(value: Any) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+RULES_SHA256 = hashlib.sha256(_canonical_bytes(RULE_DEFINITION)).hexdigest()
+
+
+def _pattern(cue: str) -> re.Pattern[str]:
+    # Every non-literal registered cue consists of words separated by spaces.
+    # Lookarounds make phrases boundary-aware at both ends without ASCII-only
+    # ``\b`` behaviour ("tablet" must not match "tab", for example).
+    return re.compile(r"(?<!\w)" + re.escape(cue) + r"(?!\w)", re.IGNORECASE)
+
+
+_WORD_PATTERNS = tuple(
+    _pattern(cue)
+    for cue in (*GUI_TARGET_CUES, *GEOMETRY_CUES)
+    if cue not in LITERAL_CUES
+)
+
+
+def _option_text(option: Any) -> str | None:
+    if isinstance(option, str):
+        return option
+    if isinstance(option, Mapping):
+        # These are the two visible fields accepted by the benchmark and
+        # /v1/systemone contracts.  Metadata fields are deliberately ignored.
+        values = []
+        for key in ("name", "description", "text"):
+            value = option.get(key)
+            if value is not None:
+                if not isinstance(value, str):
+                    return None
+                values.append(value)
+        return " ".join(values) if values else None
+    return None
+
+
+def route(question: str, options: Sequence[Any]) -> str:
+    """Return the registered route, failing ambiguous/malformed inputs closed.
+
+    Matching is case-insensitive.  Word cues and multi-word phrases require
+    word boundaries; ``°`` and ``\\triangle`` are matched literally.
+    """
+    if not isinstance(question, str) or isinstance(options, (str, bytes)):
+        return DEFAULT
+    try:
+        option_values = list(options)
+    except TypeError:
+        return DEFAULT
+    visible = []
+    for option in option_values:
+        value = _option_text(option)
+        if value is None:
+            return DEFAULT
+        visible.append(value)
+    text = "\n".join((question, *visible)).casefold()
+    if any(cue.casefold() in text for cue in LITERAL_CUES):
+        return SCREEN_GEOMETRY
+    if any(pattern.search(text) for pattern in _WORD_PATTERNS):
+        return SCREEN_GEOMETRY
+    return DEFAULT
+
+
+__all__ = [
+    "DEFAULT", "GEOMETRY_CUES", "GUI_TARGET_CUES", "LITERAL_CUES", "ROUTES",
+    "RULES_SHA256", "RULES_VERSION", "RULE_DEFINITION", "SCREEN_GEOMETRY", "route",
+]

open_decisions/image_jev/speed.py

@@ -0,0 +1,164 @@
+"""Serial inference helpers; no model imports or GPU synchronization when untimed."""
+from __future__ import annotations
+
+from contextlib import contextmanager, nullcontext
+from time import perf_counter
+
+PHASES = ("decode_load", "processor_preprocess", "tokenise_chat_template",
+          "route_adapter_switch", "h2d_copy", "forward", "readout_calibration", "response_build")
+
+
+class PhaseTimer:
+    def __init__(self, seconds=None, synchronize=None):
+        self.seconds, self.synchronize = seconds, synchronize
+        if seconds is not None:
+            seconds.update(dict.fromkeys(PHASES, 0.0))
+
+    def phase(self, name):
+        return self._phase(name) if self.seconds is not None else nullcontext()
+
+    @contextmanager
+    def _phase(self, name):
+        if self.synchronize is not None:
+            self.synchronize()
+        started = perf_counter()
+        try:
+            yield
+        finally:
+            if self.synchronize is not None:
+                self.synchronize()
+            self.seconds[name] += perf_counter() - started
+
+
+class AdapterSwitch:
+    """Keep PEFT's selected adapter fixed; toggle layers only on route transitions.
+
+    Owns adapter state for a serial reader. Do not mutate adapters externally.
+    """
+    def __init__(self, model):
+        from open_decisions.image_jev import router
+        self.model = model
+        self.layers = model.base_model
+        model.set_adapter(router.SCREEN_GEOMETRY)
+        self.route = router.SCREEN_GEOMETRY
+
+    def __call__(self, route):
+        from open_decisions.image_jev import router
+        if route not in router.ROUTES:
+            raise ValueError("unknown adapter route")
+        if route != self.route:
+            if route == router.SCREEN_GEOMETRY:
+                self.layers.enable_adapter_layers()
+            else:
+                self.layers.disable_adapter_layers()
+            self.route = route
+        return nullcontext()
+
+
+def move_to_device(value, device):
+    if device is None or not hasattr(value, "to"):
+        return value
+    if getattr(value, "device", None) == device:
+        return value
+    # Pin only CUDA-bound host tensors. Already-device pixels need no copy.
+    if getattr(device, "type", str(device).split(":")[0]) == "cuda":
+        if getattr(getattr(value, "device", None), "type", None) == "cpu":
+            value = value.pin_memory()
+        return value.to(device, non_blocking=True)
+    return value.to(device)
+
+
+class NativeCache:
+    """Per-processor caches for the immutable letter ids and chat shell."""
+    def __init__(self, processor):
+        self.processor = processor
+        self.tokenizer = CachedTokenizer(processor.tokenizer)
+        processor.tokenizer = self.tokenizer
+        self.letters = None
+        self.shell = None
+
+    def prompt(self, user):
+        from open_decisions.image_jev.vision import IMAGE_SYSTEM
+        processor = self.processor
+        if not hasattr(processor, "apply_chat_template"):
+            return user
+        def render(text):
+            return processor.apply_chat_template(
+                [{"role": "system", "content": IMAGE_SYSTEM}, {"role": "user", "content": text}],
+                tokenize=False, add_generation_prompt=True, enable_thinking=False)
+        if self.shell is None:
+            marker = "IMAGE_HOPPER_STATIC_SHELL_56"
+            sample = render(marker)
+            parts = sample.split(marker)
+            # Verify the shell against the actual first request (templates may inspect content).
+            self.shell = tuple(parts) if len(parts) == 2 and "".join((parts[0], user, parts[1])) == render(user) else False
+        if self.shell is False:
+            return render(user)
+        self.tokenizer.configure(*self.shell)
+        return self.shell[0] + user + self.shell[1]
+
+    def letter_ids(self, count):
+        from open_decisions.scoring.prompt import letter_token_ids
+        if self.letters is None:
+            self.letters = letter_token_ids(self.processor.tokenizer)
+        return self.letters[:count]
+
+
+class CachedTokenizer:
+    """Cache Qwen chat tokens only at isolated added-special-token boundaries.
+
+    Unknown kwargs, tokenizer families and shapes use the original tokenizer.
+    The first full encoding also verifies exact token-id equality.
+    """
+    def __init__(self, tokenizer):
+        self.original = tokenizer
+        self.parts = None
+        self.timer = PhaseTimer()
+
+    def __getattr__(self, name):
+        return getattr(self.original, name)
+
+    def configure(self, prefix, suffix):
+        if self.parts is not None or not getattr(self.original, "is_fast", False):
+            return
+        if "Qwen" not in type(self.original).__name__ or "<|im_start|>" not in prefix:
+            return
+        boundary = prefix.rfind("<|im_start|>") + len("<|im_start|>")
+        prefix = prefix[:boundary]
+        if not suffix.startswith("<|im_end|>"):
+            return
+        tokens = {str(token): token for token in self.original.added_tokens_decoder.values()}
+        for key in ("<|im_start|>", "<|im_end|>"):
+            token = tokens.get(key)
+            if token is None or not token.special or token.lstrip or token.rstrip:
+                return
+        if self.original.num_special_tokens_to_add(pair=False):
+            return
+        self.parts = (prefix, suffix, self.original.encode(prefix, add_special_tokens=False),
+                      self.original.encode(suffix, add_special_tokens=False), False)
+
+    def __call__(self, text, **kwargs):
+        with self.timer.phase("tokenise_chat_template"):
+            allowed = {"padding", "return_attention_mask", "return_token_type_ids", "add_special_tokens", "return_tensors"}
+            if (not self.parts or set(kwargs) - allowed or kwargs.get("return_token_type_ids") or
+                    not isinstance(text, list) or len(text) != 1 or not isinstance(text[0], str)):
+                return self.original(text, **kwargs)
+            prefix, suffix, before, after, verified = self.parts
+            value = text[0]
+            if not value.startswith(prefix) or not value.endswith(suffix):
+                return self.original(text, **kwargs)
+            middle = value[len(prefix):-len(suffix)]
+            ids = before + self.original.encode(middle, add_special_tokens=False) + after
+            if not verified:
+                reference = self.original(text, **kwargs)
+                expected = reference["input_ids"]
+                if hasattr(expected, "tolist"):
+                    expected = expected.tolist()
+                if expected != [ids]:
+                    self.parts = False
+                    return reference
+                self.parts = (prefix, suffix, before, after, True)
+                return reference
+            return self.original.pad({"input_ids": [ids]}, padding=kwargs.get("padding", False),
+                                     return_attention_mask=kwargs.get("return_attention_mask"),
+                                     return_tensors=kwargs.get("return_tensors"))

open_decisions/image_jev/vision.py

@@ -0,0 +1,521 @@
+"""Shared image preparation and option readout for Image JevBench.
+
+This module is deliberately the only path from source images to processor inputs.  Training and
+serving should both call :func:`prepare_for_route`; keeping resize, prompt and readout decisions
+here makes a route or budget change visible and versioned instead of an accidental processor
+configuration change.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import io
+import json
+import hashlib
+import inspect
+import math
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+from PIL import Image, ImageOps, UnidentifiedImageError
+
+from open_decisions.image_jev.speed import PhaseTimer, move_to_device
+
+# One source for option rendering in training and serving (no fallback path that could drift);
+# tests/test_image_jev_vision.py checks it against the public hopper_decisions copy when that is importable.
+from open_decisions.scoring import prompt as hopper_prompt
+
+
+FACTOR = 32
+MIN_PIXELS = 65_536
+MAX_PIXELS = 16_777_216
+MAX_IMAGE_BYTES = 20 * 1024 * 1024
+MAX_IMAGE_PIXELS = 20_000_000
+BUDGET_VERSION = "b1"
+BUDGETS = MappingProxyType({"photo": 160, "scene": 224, "document": 384, "dense": 768})
+ROUTING_VERSION = "image-jev/content-routing/v1"
+ROUTING_CONFIG = MappingProxyType({
+    "version": ROUTING_VERSION,
+    "inputs": "decoded-oriented-rgb-pixels-only",
+    "policy": "conservative-document",
+    "content_class": "document",
+})
+ROUTING_CONFIG_SHA256 = hashlib.sha256(
+    json.dumps(dict(ROUTING_CONFIG), sort_keys=True, separators=(",", ":")).encode("utf-8")
+).hexdigest()
+IMAGE_ROUTE_VERSION = "image-jev/image-route/v1"
+IMAGE_ROUTES = ("native", "capped")
+IMAGE_ROUTE_CONFIG_SHA256 = MappingProxyType({
+    route: hashlib.sha256(json.dumps(
+        {"version": IMAGE_ROUTE_VERSION, "image_route": route},
+        sort_keys=True, separators=(",", ":"),
+    ).encode("utf-8")).hexdigest()
+    for route in IMAGE_ROUTES
+})
+
+IMAGE_SYSTEM = ("You make decisions about supplied images. Inspect every image and reply with the letter of the "
+                "correct option and nothing else. Do not produce reasoning.")
+VISION_TOKEN = "<|vision_start|><|image_pad|><|vision_end|>"
+
+
+@dataclass(frozen=True)
+class PreparedInput:
+    """The complete model input produced identically for training and serving."""
+
+    input_ids: Any
+    pixel_values: Any
+    image_grid_thw: Any
+    resize_records: list[dict[str, Any]]
+    letter_token_ids: list[int]
+    prompt: str
+    routing_config_sha256: str = ROUTING_CONFIG_SHA256
+    # transformers >= 5.x Qwen-VL needs this for multimodal RoPE; returned by the processor beside input_ids.
+    mm_token_type_ids: Any = None
+    image_route: str = "capped"
+
+    @property
+    def ids(self):
+        """Short alias used by call sites that name language inputs ``ids``."""
+        return self.input_ids
+
+    @property
+    def pixels(self):
+        """Short alias for the processor's image tensor."""
+        return self.pixel_values
+
+    @property
+    def records(self):
+        """Short alias for the resize audit records."""
+        return self.resize_records
+
+    @property
+    def image_route_config_sha256(self):
+        """Registered identity of the native/capped preparation choice."""
+        return IMAGE_ROUTE_CONFIG_SHA256[self.image_route]
+
+
+def smart_resize(height: int, width: int, factor: int = FACTOR, min_pixels: int = MIN_PIXELS,
+                 max_pixels: int = MAX_PIXELS) -> tuple[int, int]:
+    """Qwen2-VL/Qwen3-VL's ``smart_resize``, with Qwen3.5-4B image defaults.
+
+    The arithmetic and its boundary behavior intentionally track Transformers exactly, including
+    its rejection only when the absolute aspect ratio is *greater than* 200.
+    """
+    if max(height, width) / min(height, width) > 200:
+        raise ValueError(
+            f"absolute aspect ratio must be smaller than 200, got {max(height, width) / min(height, width)}"
+        )
+    h_bar = round(height / factor) * factor
+    w_bar = round(width / factor) * factor
+    if h_bar * w_bar > max_pixels:
+        beta = math.sqrt((height * width) / max_pixels)
+        h_bar = max(factor, math.floor(height / beta / factor) * factor)
+        w_bar = max(factor, math.floor(width / beta / factor) * factor)
+    elif h_bar * w_bar < min_pixels:
+        beta = math.sqrt(min_pixels / (height * width))
+        h_bar = math.ceil(height * beta / factor) * factor
+        w_bar = math.ceil(width * beta / factor) * factor
+    return h_bar, w_bar
+
+
+def image_tokens(height: int, width: int, factor: int = FACTOR) -> int:
+    """Merged image-token count after the model processor's normal smart resize."""
+    resized_h, resized_w = smart_resize(height, width, factor=factor)
+    return (resized_h // factor) * (resized_w // factor)
+
+
+def budget_pixels(content_class: str) -> int:
+    """Return the explicit pixel-area budget for a named content class."""
+    try:
+        return BUDGETS[content_class] * FACTOR * FACTOR
+    except (KeyError, TypeError):
+        raise ValueError(f"unknown image content class {content_class!r}; expected one of {tuple(BUDGETS)}") from None
+
+
+def route_content(img: Image.Image) -> str:
+    """Conservatively route every image to ``document`` for now.
+
+    Content routing is a later measured experiment.  Any future classifier must use only observable
+    image content, never benchmark ids, source names, family names or other hidden metadata.
+    """
+    if not isinstance(img, Image.Image):
+        raise TypeError("classify_content expects a PIL.Image.Image")
+    return "document"
+
+
+# Compatibility name for callers that only need the returned class.  All
+# consumers route through ``route_content`` and bind ROUTING_CONFIG_SHA256.
+classify_content = route_content
+
+
+def _scaled_size(width: int, height: int, long_edge: int) -> tuple[int, int]:
+    """Largest-edge parameterisation of a whole-image, aspect-preserving integer size."""
+    if width >= height:
+        return long_edge, max(1, min(height, round(height * long_edge / width)))
+    return max(1, min(width, round(width * long_edge / height))), long_edge
+
+
+def _budgeted_size(width: int, height: int, token_budget: int) -> tuple[int, int]:
+    """A whole-image size whose default processor result meets ``token_budget``."""
+    if image_tokens(height, width) <= token_budget:
+        return width, height
+
+    # Prefer the processor's own factor-aligned target.  This makes its subsequent smart resize a
+    # no-op and ensures LANCZOS, rather than a second processor interpolation, sets the final pixels.
+    target_h, target_w = smart_resize(height, width, max_pixels=token_budget * FACTOR * FACTOR)
+    while (target_h // FACTOR) * (target_w // FACTOR) > token_budget:
+        if target_w >= target_h and target_w > FACTOR:
+            target_w -= FACTOR
+        elif target_h > FACTOR:
+            target_h -= FACTOR
+        else:
+            break
+    try:
+        aligned_tokens = image_tokens(target_h, target_w)
+    except ValueError:
+        aligned_tokens = token_budget + 1
+    if target_w <= width and target_h <= height and aligned_tokens <= token_budget:
+        return target_w, target_h
+
+    # A source edge shorter than one factor can make the aligned target an upscale.  Search actual
+    # image sizes in that edge case; the saved pixels still enforce the budget even if a later
+    # processor is constructed with its native 16M maximum.
+    low, high = 1, max(width, height)
+    best = None
+    while low <= high:
+        middle = (low + high) // 2
+        candidate = _scaled_size(width, height, middle)
+        try:
+            fits = image_tokens(candidate[1], candidate[0]) <= token_budget
+        except ValueError:
+            fits = False
+        if fits:
+            best = candidate
+            low = middle + 1
+        else:
+            high = middle - 1
+    if best is None:  # Unreachable for accepted (<=200:1) inputs and the smallest 160-token budget.
+        raise ValueError(f"image aspect ratio cannot fit the {token_budget}-token budget")
+    return best
+
+
+def resize_for_budget(img: Image.Image, content_class: str) -> tuple[Image.Image, dict[str, Any]]:
+    """Convert to RGB and, if necessary, LANCZOS-downscale the whole image to its named budget."""
+    if not isinstance(img, Image.Image):
+        raise TypeError("resize_for_budget expects a PIL.Image.Image")
+    token_budget = budget_pixels(content_class) // (FACTOR * FACTOR)
+    orig_size = img.size
+    new_size = _budgeted_size(*orig_size, token_budget)
+    converted = img.convert("RGB")
+    resized = converted if new_size == orig_size else converted.resize(new_size, Image.Resampling.LANCZOS)
+    tokens = image_tokens(resized.height, resized.width)
+    if tokens > token_budget:  # Keep a hard invariant next to the operation that enforces it.
+        raise RuntimeError(f"resize produced {tokens} image tokens for a {token_budget}-token budget")
+    record = {"content_class": content_class, "budget_version": BUDGET_VERSION,
+              "orig_size": orig_size, "new_size": resized.size, "image_tokens": tokens}
+    return resized, record
+
+
+def _normalise_options(options) -> list[dict[str, str]]:
+    normalised = []
+    for index, option in enumerate(options):
+        if isinstance(option, str):
+            normalised.append({"name": option, "description": option})
+        elif isinstance(option, dict) and "name" in option and "description" in option:
+            normalised.append({"name": str(option["name"]), "description": str(option["description"])})
+        elif isinstance(option, (tuple, list)) and len(option) == 2:
+            normalised.append({"name": str(option[0]), "description": str(option[1])})
+        else:
+            raise ValueError(f"option {index} must be text, a (name, description) pair, or a mapping with those keys")
+    if not 2 <= len(normalised) <= len(hopper_prompt.LETTERS):
+        raise ValueError("image decisions require 2 to 26 options")
+    return normalised
+
+
+def render_prompt(question: str, options, n_images: int) -> str:
+    """Render the image decision user turn with explicit letter-description pairs and thinking off."""
+    if not isinstance(question, str) or not question:
+        raise ValueError("question must be non-empty text")
+    if not isinstance(n_images, int) or isinstance(n_images, bool) or n_images < 1:
+        raise ValueError("n_images must be a positive integer")
+    normalised = _normalise_options(options)
+    shown = hopper_prompt.option_lines({"kind": "choice", "options": normalised})
+    payload = {"question": question,
+               "options": [{"letter": hopper_prompt.LETTERS[i], "description": text}
+                           for i, (_, text) in enumerate(shown)]}
+    images = "\n".join(f"IMAGE {i + 1}\n{VISION_TOKEN}" for i in range(n_images))
+    return (f"{images}\n\n{json.dumps(payload, ensure_ascii=False)}\n\n"
+            "Reply with one option letter only; do not produce reasoning.")
+
+
+def _decode_data_uri(uri: str) -> bytes:
+    try:
+        header, encoded = uri.split(",", 1)
+    except ValueError:
+        raise ValueError("bad image data URI: missing comma") from None
+    if not header.startswith("data:image/") or not header.endswith(";base64"):
+        raise ValueError("bad image data URI: expected data:image/...;base64,...")
+    # Reject an oversized payload before allocating its decoded representation.  Padding means the
+    # estimate can exceed the true size by at most two bytes, so an exact check follows decoding.
+    if (len(encoded) // 4) * 3 > MAX_IMAGE_BYTES + 2:
+        raise ValueError(f"image exceeds {MAX_IMAGE_BYTES} bytes")
+    try:
+        raw = base64.b64decode(encoded, validate=True)
+    except (binascii.Error, ValueError):
+        raise ValueError("bad image data URI: invalid base64 payload") from None
+    if len(raw) > MAX_IMAGE_BYTES:
+        raise ValueError(f"image exceeds {MAX_IMAGE_BYTES} bytes")
+    return raw
+
+
+def _image_bytes(source) -> bytes:
+    if isinstance(source, (bytes, bytearray, memoryview)):
+        raw = bytes(source)
+        if len(raw) > MAX_IMAGE_BYTES:
+            raise ValueError(f"image exceeds {MAX_IMAGE_BYTES} bytes")
+        return raw
+    if isinstance(source, str) and source.startswith("data:"):
+        return _decode_data_uri(source)
+    if isinstance(source, (str, os.PathLike)):
+        path = Path(source)
+        try:
+            size = path.stat().st_size
+        except OSError as error:
+            raise ValueError(f"cannot read image path {path}: {error}") from error
+        if size > MAX_IMAGE_BYTES:
+            raise ValueError(f"image exceeds {MAX_IMAGE_BYTES} bytes: {path}")
+        try:
+            raw = path.read_bytes()
+        except OSError as error:
+            raise ValueError(f"cannot read image path {path}: {error}") from error
+        if len(raw) > MAX_IMAGE_BYTES:  # The file may have changed between stat and read.
+            raise ValueError(f"image exceeds {MAX_IMAGE_BYTES} bytes: {path}")
+        return raw
+    raise TypeError("each image must be bytes, a filesystem path, or a base64 image data URI")
+
+
+def _load_image(source, *, exif_transpose: bool = True) -> Image.Image:
+    raw = _image_bytes(source)
+    try:
+        with Image.open(io.BytesIO(raw)) as opened:
+            width, height = opened.size
+            if width * height > MAX_IMAGE_PIXELS:
+                raise ValueError(f"image exceeds {MAX_IMAGE_PIXELS} pixels: {width}x{height}")
+            opened.load()
+            ready = ImageOps.exif_transpose(opened) if exif_transpose else opened
+            # A loaded image owns its pixels after the file closes.
+            return ready
+    except ValueError:
+        raise
+    except (UnidentifiedImageError, OSError, SyntaxError) as error:
+        raise ValueError(f"cannot decode image: {error}") from error
+
+
+def _output_field(output, name: str):
+    if isinstance(output, dict):
+        value = output.get(name)
+    else:
+        value = getattr(output, name, None)
+    if value is None:
+        raise ValueError(f"processor output is missing {name!r}")
+    return value
+
+
+def _prepare(example: dict, processor, *, image_route: str,
+             content_class: str | None = None, loaded_images=None, cache=None,
+             timer=None, device=None) -> PreparedInput:
+    """Prepare one decision after validating an explicit registered image route."""
+    if image_route not in IMAGE_ROUTES:
+        raise ValueError(f"image_route must be one of {IMAGE_ROUTES}, got {image_route!r}")
+    try:
+        question, options = example["question"], example["options"]
+    except (KeyError, TypeError) as error:
+        raise ValueError("example must contain question and options") from error
+    sources = example.get("images")
+    if sources is None and "image" in example:
+        sources = [example["image"]]
+    if not isinstance(sources, (list, tuple)) or not sources:
+        raise ValueError("example must contain a non-empty images list")
+
+    normalised = _normalise_options(options)
+    if content_class is not None:
+        raise ValueError("content_class overrides are forbidden; routing uses observable image content")
+    # The historical native read path used decoded pixel order directly. Keep
+    # that exact behavior while capped retains its established EXIF transpose.
+    timer = timer or PhaseTimer()
+    with timer.phase("decode_load"):
+        loaded = loaded_images if loaded_images is not None else [
+            _load_image(source, exif_transpose=image_route == "capped") for source in sources
+        ]
+    with timer.phase("processor_preprocess"):
+        ready_images, records = [], []
+        for image in loaded:
+            routed_class = route_content(image)
+            if image_route == "capped":
+                ready, record = resize_for_budget(image, routed_class)
+            else:
+                ready = image if image.mode == "RGB" else image.convert("RGB")
+                record = {
+                    "image_route": "native",
+                    "content_class": routed_class,
+                    "orig_size": image.size,
+                    "new_size": ready.size,
+                    "image_tokens": image_tokens(ready.height, ready.width),
+                }
+            ready_images.append(ready)
+            records.append(record)
+
+    with timer.phase("tokenise_chat_template"):
+        user = render_prompt(question, normalised, len(ready_images))
+        if cache is not None:
+            prompt = cache.prompt(user)
+        elif hasattr(processor, "apply_chat_template"):
+            messages = [{"role": "system", "content": IMAGE_SYSTEM}, {"role": "user", "content": user}]
+            prompt = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True,
+                                                   enable_thinking=False)
+        else:
+            prompt = user
+        tokenizer = getattr(processor, "tokenizer", None)
+        if tokenizer is None:
+            raise ValueError("processor must expose its tokenizer for option-letter readout")
+        token_ids = (cache.letter_ids(len(normalised)) if cache is not None else
+                     hopper_prompt.letter_token_ids(tokenizer)[:len(normalised)])
+    # Fast torch image processors accept device; slow/PIL processors do not.
+    image_processor = getattr(processor, "image_processor", None)
+    fast = image_processor is not None and (
+        getattr(image_processor, "backend", None) == "torch" or
+        "Fast" in type(image_processor).__name__ or
+        any(base.__name__ == "BaseImageProcessorFast" for base in type(image_processor).__mro__))
+    kwargs = {"images_kwargs": {"device": device}} if fast and device is not None else {}
+    if cache is not None:
+        cache.tokenizer.timer = timer
+    token_before = timer.seconds["tokenise_chat_template"] if timer.seconds is not None else 0.0
+    with timer.phase("processor_preprocess"):
+        output = processor(text=[prompt], images=ready_images, padding=True, return_tensors="pt", **kwargs)
+    if timer.seconds is not None:
+        timer.seconds["processor_preprocess"] -= timer.seconds["tokenise_chat_template"] - token_before
+    return PreparedInput(input_ids=_output_field(output, "input_ids"),
+                         pixel_values=_output_field(output, "pixel_values"),
+                         image_grid_thw=_output_field(output, "image_grid_thw"),
+                         resize_records=records, letter_token_ids=token_ids, prompt=prompt,
+                         mm_token_type_ids=(output.get("mm_token_type_ids") if isinstance(output, dict)
+                                            else getattr(output, "mm_token_type_ids", None)),
+                         image_route=image_route)
+
+
+def prepare(example: dict, processor, content_class: str | None = None) -> PreparedInput:
+    """Prepare the existing capped route shared by capped training and serving."""
+    return _prepare(example, processor, image_route="capped", content_class=content_class)
+
+
+def prepare_native(example: dict, processor, **kwargs) -> PreparedInput:
+    """Prepare processor-default full-resolution images without budget resizing."""
+    return _prepare(example, processor, image_route="native", **kwargs)
+
+
+def prepare_for_route(example: dict, processor, route: str) -> PreparedInput:
+    """Dispatch one example through exactly one registered image route."""
+    if route == "native":
+        return prepare_native(example, processor)
+    if route == "capped":
+        return prepare(example, processor)
+    raise ValueError(f"image_route must be one of {IMAGE_ROUTES}, got {route!r}")
+
+
+def last_position_logits(model, prepared, *, timer=None, forward_call=None):
+    """Run exactly one last-position vocabulary projection for every local reader."""
+    try:
+        device = next(model.parameters()).device
+    except (StopIteration, AttributeError):
+        device = None
+
+    timer = timer or PhaseTimer()
+
+    def move(value):
+        return move_to_device(value, device)
+
+    with timer.phase("h2d_copy"):
+        kwargs = {
+            "input_ids": move(prepared.input_ids),
+            "pixel_values": move(prepared.pixel_values),
+            "image_grid_thw": move(prepared.image_grid_thw),
+            "use_cache": False,
+            **({"mm_token_type_ids": move(prepared.mm_token_type_ids)}
+               if getattr(prepared, "mm_token_type_ids", None) is not None else {}),
+            "return_dict": True,
+        }
+    readout_kwargs = getattr(model, "_image_last_position_kwargs", None)
+    if readout_kwargs is None:
+        parameters = inspect.signature(model.forward).parameters
+        if "logits_to_keep" in parameters or any(
+            parameter.kind == parameter.VAR_KEYWORD for parameter in parameters.values()
+        ):
+            readout_kwargs = {"logits_to_keep": 1}
+        elif "num_logits_to_keep" in parameters:
+            readout_kwargs = {"num_logits_to_keep": 1}
+        else:
+            raise ValueError("model does not expose a last-position logits readout")
+        model._image_last_position_kwargs = readout_kwargs
+    kwargs.update(readout_kwargs)
+    with timer.phase("forward"):
+        output = model(**kwargs) if forward_call is None else forward_call(lambda: model(**kwargs))
+    logits = output["logits"] if isinstance(output, dict) else output.logits
+    if logits.ndim != 3 or logits.shape[0] != 1 or logits.shape[1] != 1:
+        raise ValueError("model must return exactly [1, 1, vocabulary] logits")
+    return logits[0, 0, :]
+
+
+def calibrated_read(model, prepared: PreparedInput, *, temperature: float) -> tuple[list[float], list[float]]:
+    """Return raw and checkpoint-artifact-calibrated option probabilities."""
+    logits = last_position_logits(model, prepared)
+    import torch
+
+    raw = option_log_probs(logits, prepared.letter_token_ids, validate_finite=False).exp()
+    calibrated = option_log_probs(logits, prepared.letter_token_ids, temperature,
+                                  validate_finite=False).exp()
+    values = torch.stack((raw, calibrated)).detach().cpu().tolist()
+    if not all(math.isfinite(value) for row in values for value in row):
+        raise ValueError("option probabilities are non-finite")
+    return values[0], values[1]
+
+
+def option_log_probs(logits_last, letter_token_ids: list[int], temperature: float = 1.0, *,
+                     validate_finite: bool = True):
+    """Differentiable FP32 log-softmax over the served option-letter rows.
+
+    Training uses this function directly and :func:`option_probs` is only its
+    exponentiated, detached presentation form.  Keeping selection, validation,
+    dtype conversion and temperature here prevents a train/serve readout fork.
+    """
+    import torch
+
+    if not math.isfinite(temperature) or temperature <= 0:
+        raise ValueError("temperature must be finite and greater than zero")
+    if not letter_token_ids:
+        raise ValueError("letter_token_ids must not be empty")
+    logits = torch.as_tensor(logits_last)
+    if logits.ndim != 1:
+        raise ValueError("logits_last must be a one-dimensional vocabulary vector")
+    if any(isinstance(index, bool) or not isinstance(index, int) or not 0 <= index < logits.numel()
+           for index in letter_token_ids):
+        raise ValueError("letter_token_ids must be valid vocabulary indices")
+    try:
+        selected = logits[list(letter_token_ids)].to(dtype=torch.float32) / temperature
+    except (IndexError, TypeError) as error:
+        raise ValueError("letter_token_ids must be valid vocabulary indices") from error
+    log_probabilities = torch.log_softmax(selected, dim=-1)
+    if validate_finite and not bool(torch.isfinite(log_probabilities).all()):
+        raise ValueError("option probabilities are non-finite")
+    return log_probabilities
+
+
+def option_probs(logits_last, letter_token_ids: list[int], temperature: float = 1.0) -> list[float]:
+    """FP32 softmax over only the displayed option-letter logits."""
+    values = option_log_probs(logits_last, letter_token_ids, temperature, validate_finite=False).exp().detach().cpu().tolist()
+    if not all(math.isfinite(value) for value in values):
+        raise ValueError("option probabilities are non-finite")
+    return values

open_decisions/scoring/prompt.py

@@ -0,0 +1,37 @@
+"""How an example becomes a prompt. Shared by every backend, so it imports no ML framework."""
+
+from __future__ import annotations
+
+LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+SYSTEM = ("You make decisions about a document under a policy. Read only what is written in the document. "
+          "Reply with the letter of the correct option and nothing else.")
+ANSWERABLE = "Does the document state every fact that the policy needs in order to decide this case?"
+YES_NO = [("yes", "yes"), ("no", "no")]
+
+
+def option_lines(example):
+    """(label, text shown) per option, in the example's order."""
+    if example["kind"] == "noul":
+        return [("true", "true"), ("false", "false")]
+    return [(o["name"], o["name"] if o["name"] == o["description"] else f"{o['name']}: {o['description']}")
+            for o in example["options"]]
+
+
+def user_prompt(example, question, options):
+    listing = "\n".join(f"{LETTERS[i]}. {text}" for i, (_, text) in enumerate(options))
+    document = f"DOCUMENT\n{example['document']}\n\n" if example["document"] else ""  # bare questions have none
+    return (f"POLICY\n{example['policy']}\n\n{document}"
+            f"QUESTION\n{question}\n\nOPTIONS\n{listing}")
+
+
+def prompt_ids(tokenizer, user):
+    messages = [{"role": "system", "content": SYSTEM}, {"role": "user", "content": user}]
+    ids = tokenizer.apply_chat_template(messages, add_generation_prompt=True, enable_thinking=False)
+    return list(ids if isinstance(ids, list) else ids["input_ids"])  # some tokenizer versions return a mapping
+
+
+def letter_token_ids(tokenizer):
+    ids = [tokenizer.encode(letter, add_special_tokens=False) for letter in LETTERS]
+    if any(len(i) != 1 for i in ids):
+        raise ValueError("Every option letter must be a single token for this tokenizer.")
+    return [i[0] for i in ids]

requirements.lock

@@ -0,0 +1,93 @@
+# Generated from the captured training-image freeze; do not edit.
+# python: 3.12.6
+# torch-cuda: 12.8
+# freeze-sha256: 1470ee9c425f71586f73783ba29b540ec224a9687eb612761a347bf7b56f3194
+accelerate==1.15.0
+aiohappyeyeballs==2.4.3
+aiohttp==3.10.8
+aiosignal==1.3.1
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.15.1
+apache-tvm-ffi==0.1.12
+attrs==24.2.0
+causal-conv1d @ https://github.com/Dao-AILab/causal-conv1d/releases/download/v1.7.0/causal_conv1d-1.7.0%2Bcu12torch2.8cxx11abiTRUE-cp312-cp312-linux_x86_64.whl#sha256=a1fcd5d022b67ddfc9e1c291f890004c1c081a03d66b532f6eebe31219168e0e
+certifi==2024.8.30
+click==8.5.0
+cloudpickle==3.1.2
+einops==0.8.2
+fastapi==0.142.2
+filelock==4.0.8
+fla-core==0.5.2
+flash-linear-attention==0.5.2
+frozenlist==1.4.1
+fsspec==2026.9.0
+grpclib==0.4.7
+h11==0.16.0
+h2==4.1.0
+hf-xet==1.6.0
+hpack==4.0.0
+httpcore==1.0.9
+httpx==0.28.1
+huggingface_hub==1.33.0
+hyperframe==6.0.1
+idna==3.10
+Jinja2==3.1.6
+markdown-it-py==4.2.0
+MarkupSafe==3.0.3
+mdurl==0.1.2
+ml_dtypes==0.6.0
+mpmath==1.3.0
+multidict==6.1.0
+networkx==3.7
+ninja==1.13.2
+numpy==2.5.3
+nvidia-cublas-cu12==12.8.4.1
+nvidia-cuda-cupti-cu12==12.8.90
+nvidia-cuda-nvrtc-cu12==12.8.93
+nvidia-cuda-runtime-cu12==12.8.90
+nvidia-cudnn-cu12==9.10.2.21
+nvidia-cufft-cu12==11.3.3.83
+nvidia-cufile-cu12==1.13.1.3
+nvidia-curand-cu12==10.3.9.90
+nvidia-cusolver-cu12==11.7.3.90
+nvidia-cusparse-cu12==12.5.8.93
+nvidia-cusparselt-cu12==0.7.1
+nvidia-nccl-cu12==2.27.3
+nvidia-nvjitlink-cu12==12.8.93
+nvidia-nvtx-cu12==12.8.90
+opentelemetry-api==1.45.0
+packaging==26.3
+peft==0.21.0
+pillow==12.3.0
+pip==24.3.1
+protobuf==5.29.2
+psutil==7.2.2
+pydantic==2.13.5
+pydantic_core==2.46.5
+Pygments==2.21.0
+python-multipart==0.0.32
+PyYAML==6.0.3
+regex==2026.9.29
+rich==15.0.0
+safetensors==0.8.0
+setuptools==84.0.0
+shellingham==1.5.4
+starlette==1.7.0
+sympy==1.14.0
+tilelang==0.1.15
+tokenizers==0.23.2
+torch==2.8.0
+torch_c_dlpack_ext==0.1.5
+torchvision==0.23.0
+tqdm==4.70.1
+transformers==5.17.0
+triton==3.4.0
+typer==0.27.2
+typing-inspection==0.4.4
+typing_extensions==4.16.0
+uv==0.5.14
+uvicorn==0.54.0
+wheel==0.45.1
+yarl==1.13.1
+z3-solver==4.15.4.0

requirements.lock.sha256

@@ -0,0 +1 @@
+974e3a19773d67b4de84842ffa4a3a537e2886240cdfb97d94216159804aa7e2  requirements.lock

requirements.txt

@@ -0,0 +1,18 @@
+# Direct dependencies at the exact versions of the evaluated image (Python 3.12, Linux x86_64, CUDA 12.8).
+# requirements.lock is the complete freeze.
+torch==2.8.0
+torchvision==0.23.0
+transformers==5.17.0
+tokenizers==0.23.2
+safetensors==0.8.0
+accelerate==1.15.0
+huggingface_hub==1.33.0
+hf-xet==1.6.0
+pillow==12.3.0
+numpy==2.5.3
+flash-linear-attention==0.5.2
+fla-core==0.5.2
+causal-conv1d @ https://github.com/Dao-AILab/causal-conv1d/releases/download/v1.7.0/causal_conv1d-1.7.0%2Bcu12torch2.8cxx11abiTRUE-cp312-cp312-linux_x86_64.whl#sha256=a1fcd5d022b67ddfc9e1c291f890004c1c081a03d66b532f6eebe31219168e0e
+triton==3.4.0
+einops==0.8.2
+peft==0.21.0