Model card: clearer summary, FAQ, related projects, JevBench result, model-index; add API reference, CITATION.cff, llms.txt

CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use Wald-Q4B, please cite it as below."
+type: software
+title: "Wald-Q4B v1.1: an open-weight 4B decision model with calibrated option probabilities"
+abstract: >-
+  Wald-Q4B is an open-weight 4B decision model built on Qwen3.5-4B-Base. Given a
+  state and typed questions (choice, yes/no, score), it returns a calibrated
+  probability for every option through a Jev-compatible POST /v1/systemone API,
+  in one pass or after an optional short thought. Weights and serving code are
+  Apache-2.0. Independent project; not affiliated with TypeSafe AI.
+authors:
+  - name: "Wald-4B authors"
+    alias: Harry19081
+    website: "https://huggingface.co/Harry19081"
+version: "v1.1"
+date-released: "2026-09-29"
+license: Apache-2.0
+url: "https://huggingface.co/Harry19081/Wald-4B"
+repository-code: "https://github.com/Harry19081/wald-4b"
+repository-artifact: "https://huggingface.co/Harry19081/Wald-4B"
+keywords:
+  - decision model
+  - calibrated probabilities
+  - tool selection
+  - agent routing
+  - classification
+  - Jev-compatible API
+  - Qwen3.5

MANIFEST.json

@@ -20,8 +20,8 @@
     "sha256": "953551e746a887044cc0ce65dec9b96ea3a763d69fda7d3a296f524bb37bca19"
   },
   "README.md": {
-    "bytes": 6659,
-    "sha256": "5124931bb00d7c1f28ab1f35b440f3837b1efd8e08ac9a6f9ac75f20ae1bdf5f"
+    "bytes": 16370,
+    "sha256": "0964da2ec2e05dfa5f46b0008c1fe912f5dddf50a5876cc8970dd3b2baa67cf9"
   },
   "RUNBOOK.md": {
     "bytes": 2718,
@@ -44,8 +44,8 @@
     "sha256": "e385b92e333eaaa9395a09daf26c09420645bee242456552a55500db45919bc7"
   },
   "docs/readmes/README.zh.md": {
-    "bytes": 6035,
-    "sha256": "7e9b1b096443066b801d9e144da275095fa70c109fdd46f48f9b14f862accef0"
+    "bytes": 13881,
+    "sha256": "bc2d14f2e64189657b2142fb19e54d94215be4751fcf30113a7cd30c37c40ef8"
   },
   "evaluation/benchmark-summary.json": {
     "bytes": 36014,
@@ -220,7 +220,19 @@
     "sha256": "ad20de47de5bbe7f72417f3d87e6f72aae7987fab913eb814b818e4a4bbc6e1e"
   },
   "model-info.json": {
-    "bytes": 2165,
-    "sha256": "f1766a5c20e9dad5da245ad06f68fd6dd39f93d87d44bd6820423e2e59eb6063"
+    "bytes": 3436,
+    "sha256": "4afd88d67874d61ddea72e4ceaf6e0ace4199f2ef5f87cb00fe5df4abc87f00b"
+  },
+  "llms.txt": {
+    "bytes": 2537,
+    "sha256": "a814eeca0112086b1740378a16173b27c86c240c5222abaaf7fa33287bdd71f1"
+  },
+  "CITATION.cff": {
+    "bytes": 1075,
+    "sha256": "4fab11f4e20a79e69a4ebbf23573abe3a8cd9a374bd5ab11e7e4206a4f070bf1"
+  },
+  "docs/api.md": {
+    "bytes": 6085,
+    "sha256": "e2e349bc9d17f01e0d52835f664808f94a6d9c88dd120ba49c9f25af47c235b8"
   }
 }

README.md

@@ -3,40 +3,131 @@ license: apache-2.0
 base_model: Qwen/Qwen3.5-4B-Base
 base_model_relation: finetune
 library_name: transformers
+pipeline_tag: text-generation
 language:
 - en
 tags:
 - decision-model
+- typed-decisions
 - calibration
-- typesafe
-- decision-index
-- wald-q4b
-- jev
-- decision-making
+- calibrated-probabilities
+- classification
 - tool-selection
+- tool-use
 - agent-routing
+- clarification
+- decision-index
+- jevbench
+- jev
+- jev-compatible
+- open-jev
+- typesafe-compatible
+- systemone
+- kev
+- laya
+- wald
+- wald-q4b
+- qwen3.5
+- 4b
+- vllm
 - reasoning
-pipeline_tag: text-generation
+model-index:
+- name: Wald-Q4B v1.1
+  results:
+  - task:
+      type: text-classification
+      name: Structured decisions (option probabilities)
+    dataset:
+      name: Decision Index 0.2.1, complete suite (150,317 requests)
+      type: decision-index
+      revision: 87d4650b42b377c0291a89c1f1a879f9b31082bf
+    metrics:
+    - type: balanced_skill_index
+      name: Balanced-skill index, effort high (author-run, not leaderboard-verified)
+      value: 54.59
+      verified: false
+    source:
+      name: 'Author-run with the official kit; submission PR #30 awaits maintainer validation'
+      url: https://github.com/apolinario/decision-index/pull/30
+  - task:
+      type: text-classification
+      name: Structured decisions (option probabilities)
+    dataset:
+      name: JevBench public set (231 items)
+      type: jevbench
+      split: public
+      revision: 9ec6f15a
+    metrics:
+    - type: accuracy
+      name: Accuracy, effort none (self-scored, 203/231)
+      value: 87.88
+      verified: false
+    - type: ece
+      name: Expected calibration error, 10 bins (self-scored)
+      value: 0.041
+      verified: false
+    - type: brier
+      name: Brier score (self-scored)
+      value: 0.188
+      verified: false
+    source:
+      name: 'Self-scored with the JevBench harness; row requested in jevbench issue #146'
+      url: https://github.com/fstandhartinger/jevbench/issues/146
 ---
 
 <div align="center">
   <h1>Wald-Q4B v1.1</h1>
   <p><strong>Decide directly. Think when needed. Return probabilities.</strong></p>
-  <p><a href="README.md">English</a> · <a href="docs/readmes/README.zh.md">简体中文</a></p>
+  <p><a href="https://huggingface.co/Harry19081/Wald-4B">English</a> · <a href="https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/readmes/README.zh.md">简体中文</a> · <a href="https://github.com/Harry19081/wald-4b">GitHub</a> · <a href="https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md">API</a></p>
 </div>
 
-**Wald-Q4B v1.1 is a self-hosted, open-weight alternative to Jev for structured decisions, with adjustable thinking effort and a TypeSafe-compatible `/v1/systemone` API.** Built on Qwen3.5-4B-Base, it supports tool selection, agent routing and option-probability scoring.
+**Wald-Q4B v1.1 is an open-weight 4B decision model: give it a state and a set of options, and it returns a calibrated probability for every option.** It is for developers who build agents and pipelines and need a fast, self-hosted component to pick a tool, route a request, classify an input or decide whether to ask the user. Unlike a chat model, it does not write an answer you have to parse. It reads the options in one pass (33 ms median on one RTX PRO 6000 with effort `none`) and can optionally think first. It serves a Jev-compatible `POST /v1/systemone` API, is built on Qwen3.5-4B-Base and is released under Apache-2.0.
 
-**W**ait **A** bit, **L**ook, then **D**ecide. Also named after Abraham Wald, the pioneer of sequential analysis: stop when the evidence is enough.
+Wald-Q4B is an independent, self-hosted alternative to TypeSafe's hosted Jev API. It is not Jev, contains no Jev weights, and is not affiliated with or endorsed by TypeSafe AI. The Hugging Face repository is `Harry19081/Wald-4B` (earlier name: Wald-4B).
 
-Give Wald a state, a question and a set of options. It returns a probability for every option—useful for tool selection, routing, classification and deciding whether to ask for clarification. Choose how much it thinks with one `effort` setting. The answer stays a structured distribution at every level.
+**W**ait **A** bit, **L**ook, then **D**ecide. Also named after Abraham Wald, the pioneer of sequential analysis: stop when the evidence is enough.
 
 ## At a glance
 
-- **4B parameters**, built on Qwen3.5-4B-Base; BF16 weights.
-- **Adjustable thinking:** `none`, `low`, `medium`, `high`, or multiple thoughts with `high-k`.
-- **Decision Index 0.2.1: 54.59** on the complete suite with `high`; 150,317 requests, all successful.
-- **Self-hosted API:** `POST /v1/systemone`, up to 131,072 prompt tokens and 255 options per question.
+- **4B parameters**, built on Qwen3.5-4B-Base; BF16 weights (8.4 GB).
+- **Every option gets a probability.** Question types: `choice` (1–255 named options), `noul` (yes/no) and `score` (ordered levels).
+- **Adjustable thinking:** `none`, `low`, `medium`, `high`, or several thoughts with `high-k`.
+- **Decision Index 0.2.1: 54.59** on the complete suite with `high`; 150,317 requests, all successful. Author-run, pending maintainer validation.
+- **JevBench public set: 203/231** with `none`, ECE 0.041, p50 33 ms / p95 168 ms. Self-scored with JevBench's own harness.
+- **Self-hosted API:** `POST /v1/systemone`, up to 131,072 prompt tokens.
+
+## Quick start
+
+On a Linux machine with an NVIDIA GPU and [`uv`](https://docs.astral.sh/uv/):
+
+```sh
+hf download Harry19081/Wald-4B --revision v1.1 --local-dir ./Wald-Q4B
+cd Wald-Q4B
+EFFORT=none ./run.sh "$PWD"     # one pass, lowest latency
+# ./run.sh "$PWD"               # default: high, the evaluated Decision Index configuration
+```
+
+```sh
+curl http://localhost:8000/v1/systemone \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "state": "The customer wants to return a damaged kettle.",
+    "effort": "medium",
+    "questions": {
+      "route": {
+        "type": "choice",
+        "instructions": "Choose the support queue.",
+        "criteria": {
+          "returns": "Returns and refunds",
+          "delivery": "Delivery tracking",
+          "other": "Other enquiries"
+        }
+      }
+    }
+  }'
+```
+
+The answer for `route` contains the chosen key and a probability for each of `returns`, `delivery` and `other`. Request and response fields, yes/no and score questions, and a clarification example: [API reference](https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md). `GET /health` reports the effective policy. The server uses vLLM 0.30.0 and the included `wald-serve` package; Docker and exact evaluation settings are in [RUNBOOK.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/RUNBOOK.md). Generic text-generation calls do not reproduce the decision API's readout.
 
 ## Thinking effort
 
@@ -50,7 +141,7 @@ Start with `none` for direct decisions, `medium` for confidence-gated thinking,
 | **`high` (default)** | Every eligible question | Up to 512 tokens |
 | `high-k2` … `high-k8` | Multiple thoughts; average their answer distributions | Up to 512 tokens per thought |
 
-Thinking applies to questions with 2–26 options when context space permits. Larger option sets use grouped readout and a final winner comparison; if a thought cannot fit, the initial answer is kept. Increasing effort spends more computation; it does not guarantee a better answer. **54.59 applies to `high` only.**
+Thinking applies to questions with 2–26 options when context space permits. Larger option sets use grouped readout and a final winner comparison; if a thought cannot fit, the initial answer is kept. Increasing effort spends more computation; it does not guarantee a better answer. **54.59 applies to `high` only; 203/231 applies to `none` only.**
 
 Set the server default with `EFFORT=medium ./run.sh "$PWD"`, or override it per request with `"effort": "none"`.
 
@@ -58,64 +149,73 @@ Set the server default with `EFFORT=medium ./run.sh "$PWD"`, or override it per
 
 Wald first reads option-letter logits from a plain prompt and turns them into a probability distribution. If the effort policy asks for thinking, it generates a short thought and reads the options again. Bucketed temperature scaling calibrates the returned probabilities.
 
-v1.1 combines full-parameter decision training, LoRA refinement, short-thought distillation and RLCD. Training uses **WaldGen**, our generated decision corpus, together with public training datasets. [Data sources](PROVENANCE.md) · [Evaluation notes](CONTAMINATION.md)
+v1.1 combines full-parameter decision training, LoRA refinement, short-thought distillation and RLCD. Training uses **WaldGen**, our generated decision corpus, together with public training datasets. [Data sources](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md) · [Evaluation notes](https://huggingface.co/Harry19081/Wald-4B/blob/main/CONTAMINATION.md)
 
 ## Benchmarks
 
-| Benchmark | Configuration | Result |
-|---|---|---:|
-| **Decision Index 0.2.1 — complete suite** | v1.1 · `high` | **54.59** |
+| Benchmark | Configuration | Result | Status |
+|---|---|---:|---|
+| **Decision Index 0.2.1 — complete suite** | v1.1 · `high` | **54.59** | Author-run; [PR #30](https://github.com/apolinario/decision-index/pull/30) awaits maintainer validation |
+| **JevBench public set (231 items)** | v1.1 · `none` | **203/231** (87.9%) · ECE 0.041 · Brier 0.188 | Self-scored; [issue #146](https://github.com/fstandhartinger/jevbench/issues/146) asks the maintainers to measure it |
 
-150,317/150,317 requests succeeded, including HLE. Measured on one RTX PRO 6000 96 GB with the pinned reproduction kit. This is an author-run result; [submission #30](https://github.com/apolinario/decision-index/pull/30) awaits maintainer validation.
+**Decision Index:** 150,317/150,317 requests succeeded, including HLE. Measured on one RTX PRO 6000 96 GB with the pinned reproduction kit. [Full results](https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results/tree/805716601b2466be324ed6716407b4c3d9267faa/runs/wald-q4b-22d0-f7-full021) · [Per-benchmark scores](https://huggingface.co/Harry19081/Wald-4B/blob/main/evaluation/benchmark-summary.json) · [Reproduction guide](https://huggingface.co/Harry19081/Wald-4B/blob/main/RUNBOOK.md)
 
-[Full results](https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results/tree/805716601b2466be324ed6716407b4c3d9267faa/runs/wald-q4b-22d0-f7-full021) · [Per-benchmark scores](evaluation/benchmark-summary.json) · [Reproduction guide](RUNBOOK.md)
+**JevBench:** JevBench's own CLI (`fstandhartinger/jevbench` at `9ec6f15a`, `typesafe` adapter) against the packaged server on loopback, one request at a time, on one RTX PRO 6000. Easy 48/48, original 72/72, hard 83/111; no tokens generated. With `medium`: 205/231, p95 1.80 s. The public items were used as a development scoreboard (never as training data), so this is not a held-out result. The JevBench leaderboard publishes a score only after its maintainers run the model themselves.
 
 ### Latency
 
-A 32-request serial preflight of v1.1 `high` measured **821 ms median** on an RTX PRO 6000. This small preflight is not a full-suite latency result or the maintainer's admission test. Effort, context length, option count and concurrency all affect speed.
+With `none`, the JevBench run above measured **33 ms median and 168 ms p95** per decision. A 32-request serial preflight of `high` measured **821 ms median** on the same GPU; this small preflight is not a full-suite latency result or the Decision Index maintainers' admission test. Effort, context length, option count and concurrency all affect speed.
 
-## Serving
+## Related projects and how Wald compares
 
-On a Linux CUDA machine with `uv`:
+Several projects implement or approximate structured decisions with calibrated option probabilities. The names below belong to their owners; Wald is not affiliated with any of them.
 
-```sh
-hf download Harry19081/Wald-4B --revision v1.1 --local-dir ./Wald-Q4B
-cd Wald-Q4B
-./run.sh "$PWD"                 # default: high
-# EFFORT=medium ./run.sh "$PWD"  # confidence-gated thinking
-```
+- **[Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)** is TypeSafe AI's hosted decision model behind the `/v1/systemone` API; its weights are closed. Wald accepts the same request shape and runs on your own GPU.
+- **[Kev](https://github.com/jaredpalmer/kev)** by Jared Palmer is an open-weight project that adds a LoRA and a pointer head to Qwen3.5 base models (0.8B, 4B and 9B). Wald's request parsing adapts Kev's Apache-2.0 code ([NOTICE](https://huggingface.co/Harry19081/Wald-4B/blob/main/NOTICE)); Wald reads option letters from the language-model head instead of a separate head.
+- **[Laya](https://huggingface.co/convaiinnovations/laya)** ([code](https://github.com/NandhaKishorM/laya)) is an open-weight 421M ModernBERT-large encoder with a decision head. It is much smaller than Wald and reads up to 512 tokens.
 
-```sh
-curl http://localhost:8000/v1/systemone \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "state": "The customer wants to return a damaged kettle.",
-    "effort": "medium",
-    "questions": {
-      "route": {
-        "type": "choice",
-        "instructions": "Choose the support queue.",
-        "criteria": {
-          "returns": "Returns and refunds",
-          "delivery": "Delivery tracking",
-          "other": "Other enquiries"
-        }
-      }
-    }
-  }'
-```
+**JevBench public set, same 231 items (identical dataset hash), JevBench CLI, run by us:**
 
-`GET /health` reports the effective policy. The server uses vLLM 0.30.0 and the included `wald-serve` package. Docker and exact evaluation settings: [RUNBOOK.md](RUNBOOK.md). Generic text-generation calls do not reproduce the decision API's readout.
+| System | How it was run | Correct |
+|---|---|---:|
+| Wald-Q4B v1.1 · `none` | Self-hosted, RTX PRO 6000, 2026-09-29 | 203/231 |
+| Jev (`jev-1.13.0`) | TypeSafe's hosted API, 2026-09-25 | 200/231 |
+| Laya (English checkpoint `55cf4c4e`) | Self-hosted, NVIDIA L4, 2026-09-26 | 134/231 |
 
-## Limits
+A 3-item difference on 231 items is within run-to-run and sampling noise. The public items informed Wald's development, and 52 of the 231 states are longer than Laya's 512-token window.
+
+**Decision Index 0.2.1:**
+
+| System | Index | Source |
+|---|---:|---|
+| Jev (`jev-1.13.0`) | 57.91 | [Leaderboard](https://huggingface.co/spaces/multimodalart/jev-decision-index), maintainer-run (data of 2026-09-28) |
+| Wald-Q4B v1.1 · `high` | 54.59 | Author-run complete suite; not on the leaderboard yet ([PR #30](https://github.com/apolinario/decision-index/pull/30)) |
+| Kev 9B | 38.48 | Leaderboard, maintainer-run (data of 2026-09-28) |
+| Kev 4B | 34.64 | Leaderboard, maintainer-run (data of 2026-09-28) |
+
+Leaderboard rows are scored by the maintainers; Wald's number is self-run with the official kit and may change after validation.
+
+## FAQ
+
+**Is there an open-source alternative to Jev?** Wald-Q4B is one open-weight option: Apache-2.0 weights and serving code that you run yourself, with a Jev-compatible `/v1/systemone` API. Kev and Laya (above) are other open projects. Wald is independent and is not a TypeSafe release.
+
+**Can I use a Jev client with a self-hosted model?** Point the client at your own endpoint. The included server accepts `state` plus typed `questions` (`choice`, `noul`, `score`) at `POST /v1/systemone` and answers with TypeSafe's answer keys. It does not check API keys. See the [API reference](https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md).
 
-Confidence is not a guarantee of correctness; validate thresholds on your own task. Oversized prompts are rejected rather than truncated. Known exact training overlaps were filtered, but semantic overlap and pretraining contamination are not ruled out; development used visible benchmark samples. Source-text rights vary. See [evaluation notes](CONTAMINATION.md) and [source attribution](PROVENANCE.md).
+**How do I route tools or decide whether to ask the user?** Send the conversation or task as `state`. For tool routing, ask a `choice` question whose options are your tools. To decide whether to ask a clarifying question, ask a `noul` question such as "Is the request specific enough to act on without asking?" Act when the probability is high, ask when it is low, and set both thresholds on your own validation data. The model picks the tool; it does not write the tool's arguments.
 
-## Jev and agent integration
+**How calibrated are the probabilities?** On the JevBench public set with `none`, expected calibration error is 0.041 (10 bins) and the Brier score is 0.188. Temperatures were fitted on held-out rows of our own development data, with no JevBench items and with known Decision Index matches excluded. A confidence is not a guarantee; check calibration on your task.
 
-**Can I use it with a Jev-style client?** The included server accepts `state` and typed `questions` at `/v1/systemone`, including choice and yes/no decisions. Point your client to your own endpoint and check its supported schema in the [serving guide](RUNBOOK.md). Wald is an independent model, not Jev weights or a TypeSafe AI release.
+**Does it run on a single GPU or a laptop?** The shipped server needs one NVIDIA GPU on Linux (vLLM 0.30.0); the BF16 weights are 8.4 GB. The v1.1 measurements come from an RTX PRO 6000 96 GB; earlier builds of the same 4B architecture have also been served with vLLM on a 24 GB NVIDIA L4 at a 16K context limit. CPU, Apple Silicon and laptop setups are not supported by the shipped server and have not been tested.
 
-**Which effort should my agent use?** Use `none` for direct readout, `medium` for confidence-gated thinking, and `high` to reproduce the published score. All return option probabilities; you do not need to parse a generated answer.
+**Kev vs Wald, or Laya vs Wald?** All three are open-weight. Kev adds a pointer head and LoRA to Qwen3.5 base models; Laya is a small encoder with a decision head; Wald is a fully trained 4B decoder with optional thinking. Our same-protocol measurements are in the tables above. Choose on your own task, latency budget and hardware.
+
+**Can I fine-tune it for my task?** It is a standard Transformers checkpoint, so common LoRA tooling applies. For v1.0 we trained per-task LoRAs for $0.12–$1.81 of GPU time each; that tooling is not public yet, and those adapters are not validated on v1.1 ([v1.0 notes](https://huggingface.co/Harry19081/Wald-4B/blob/main/history/v1.0/README.md)).
+
+**What is the license?** Apache-2.0 for the weights and code. The base model, Qwen3.5-4B-Base, is also Apache-2.0. Some public training sources have their own terms or no stated licence; they are listed in [PROVENANCE.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md). The model and code licence does not grant rights in those texts.
+
+## Limits
+
+Confidence is not a guarantee of correctness; validate thresholds on your own task. Oversized prompts are rejected rather than truncated. Known exact training overlaps were filtered, but semantic overlap and pretraining contamination are not ruled out; development used visible benchmark samples. Source-text rights vary. See [evaluation notes](https://huggingface.co/Harry19081/Wald-4B/blob/main/CONTAMINATION.md) and [source attribution](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md).
 
 ## Versioning
 
@@ -124,8 +224,24 @@ Confidence is not a guarantee of correctness; validate thresholds on your own ta
 | **v1.1 — current** | `022D0-f7` | `high` |
 | [v1.0 — archive](https://huggingface.co/Harry19081/Wald-4B/tree/v1.0) | `021A0-f10` | `medium` |
 
-The v1.0 model card retains its XL, task-LoRA and latency reports. Those measurements belong to their documented builds.
+The v1.0 model card retains its XL, task-LoRA and latency reports, and the [v1.0 walkthrough slides](https://claude.ai/artifact/XfCHVaCuj9A5ectrpaWzV5) describe v1.0 only. Those measurements belong to their documented builds.
+
+## Citation
+
+Wald-Q4B v1.1 (2026), an open-weight 4B decision model with calibrated option probabilities. https://huggingface.co/Harry19081/Wald-4B
+
+```bibtex
+@misc{wald_q4b_2026,
+  title        = {Wald-Q4B v1.1: an open-weight 4B decision model with calibrated option probabilities},
+  author       = {{Wald-4B authors}},
+  year         = {2026},
+  howpublished = {\url{https://huggingface.co/Harry19081/Wald-4B}},
+  note         = {Revision v1.1}
+}
+```
+
+Machine-readable: [CITATION.cff](https://huggingface.co/Harry19081/Wald-4B/blob/main/CITATION.cff) · [llms.txt](https://huggingface.co/Harry19081/Wald-4B/blob/main/llms.txt) · [model-info.json](https://huggingface.co/Harry19081/Wald-4B/blob/main/model-info.json)
 
 ---
 
-[Machine-readable model facts](model-info.json) · Apache-2.0 for weights and code. [Third-party notices](NOTICE) · [Training-data usage notes](PROVENANCE.md)
+[Model](https://huggingface.co/Harry19081/Wald-4B) · [GitHub](https://github.com/Harry19081/wald-4b) · [Decision Index results](https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results) · Apache-2.0 for weights and code. [Third-party notices](https://huggingface.co/Harry19081/Wald-4B/blob/main/NOTICE) · [Training-data usage notes](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md)

docs/api.md

@@ -0,0 +1,148 @@
+# Wald-Q4B decision API
+
+Wald-Q4B's server, `wald-serve`, exposes one decision endpoint, `POST /v1/systemone`. Its request and answer shapes follow TypeSafe's `/v1/systemone` format, so clients written for Jev can point at a self-hosted Wald server. Wald is independent and is not affiliated with TypeSafe AI.
+
+Start the server with `./run.sh "$PWD"` in the downloaded model directory ([model card](https://huggingface.co/Harry19081/Wald-4B), [RUNBOOK.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/RUNBOOK.md)). It listens on port 8000 and does not check API keys.
+
+## Endpoints
+
+| Method and path | Purpose |
+|---|---|
+| `POST /v1/systemone` (also `POST /`) | Answer one or more typed questions about a state |
+| `GET /health` | Effective policy: effort, gate, thought budget, prompt format, context limit |
+| `GET /v1/models` | The served model name |
+
+## Request
+
+| Field | Type | Meaning |
+|---|---|---|
+| `state` | string, object, array or null | What the decision is about: a message, a conversation, a document, an agent trace. Objects and arrays are flattened to text with their field names kept. |
+| `questions` | object, at least one entry | Question id → question. Every question is answered about the same `state`. |
+| `effort` | string, optional | `none`, `low`, `medium`, `high` or `high-k2` … `high-k8`. Overrides the server default for this request. |
+| `model` | string, optional | Accepted for client compatibility; the server answers with the model it serves. |
+
+Each question has a `type`, optional `instructions` (any JSON, usually a sentence) and `criteria`:
+
+| `type` | `criteria` | Answer |
+|---|---|---|
+| `choice` | Object of 1–255 options: key → description (description may be null) | `choice` (the most probable key), `probabilities` (key → probability), `confidence` |
+| `noul` | Optional object with `true` and/or `false` descriptions | `noul`: the probability of yes |
+| `score` | Array of 1–255 ordered levels | `score` (expected level index), `probabilities` (level index → probability), `confidence` |
+
+Every answer also carries `mode`: `A` for a one-pass read, `B` for a read after a thought, `K` for grouped (knockout) reading of wide option sets.
+
+Prompts longer than the context limit (131,072 tokens by default) are rejected with HTTP 422, never truncated. A malformed request or unknown effort returns HTTP 400.
+
+## Example: route a tool call
+
+```sh
+curl http://localhost:8000/v1/systemone \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "state": {
+      "user": "What will the weather be in Lisbon tomorrow afternoon?",
+      "tools_available": ["web_search", "weather_api", "calendar"]
+    },
+    "effort": "none",
+    "questions": {
+      "tool": {
+        "type": "choice",
+        "instructions": "Which tool should the agent call next?",
+        "criteria": {
+          "web_search": "General web search",
+          "weather_api": "Forecast for a city and time",
+          "calendar": "Read or create calendar events",
+          "none": "Answer directly without a tool"
+        }
+      }
+    }
+  }'
+```
+
+Response shape (the numbers here are illustrative, not a measured output):
+
+```json
+{
+  "model": "wald-4b",
+  "answers": {
+    "tool": {
+      "type": "choice",
+      "choice": "weather_api",
+      "probabilities": {"web_search": 0.04, "weather_api": 0.94, "calendar": 0.0, "none": 0.02},
+      "confidence": 0.92,
+      "mode": "A"
+    }
+  },
+  "usage": {"input_tokens": 142, "output_tokens": 0},
+  "latency_s": 0.03
+}
+```
+
+For `choice`, `confidence` rescales the top probability so that 0 means uniform and 1 means certain: `(p_top − 1/K) / (1 − 1/K)` for K options.
+
+## Example: decide whether to ask the user
+
+Ask several questions about one state in a single request. Each question is read separately.
+
+```json
+{
+  "state": "User: book me a table for Friday",
+  "effort": "medium",
+  "questions": {
+    "specific_enough": {
+      "type": "noul",
+      "instructions": "Is the request specific enough to act on without asking a follow-up question?",
+      "criteria": {"true": "Enough detail to act", "false": "Needs clarification first"}
+    },
+    "urgency": {
+      "type": "score",
+      "instructions": "How urgent is this request?",
+      "criteria": ["low", "medium", "high"]
+    }
+  }
+}
+```
+
+Response shape (illustrative numbers):
+
+```json
+{
+  "model": "wald-4b",
+  "answers": {
+    "specific_enough": {"type": "noul", "noul": 0.08, "mode": "B"},
+    "urgency": {"type": "score", "score": 1.1, "probabilities": {"0": 0.15, "1": 0.6, "2": 0.25}, "confidence": 0.6, "mode": "A"}
+  },
+  "usage": {"input_tokens": 310, "output_tokens": 96},
+  "latency_s": 0.6
+}
+```
+
+A typical policy: act when `noul` is above a high threshold, ask the user when it is below a low one, and escalate the cases in between. Set both thresholds on validation data from your own task.
+
+## Choosing an effort
+
+| Effort | Use it for |
+|---|---|
+| `none` | Lowest latency. One pass, no generated tokens. |
+| `low` / `medium` | Think only when the top initial probability is below 0.5 / 0.7. |
+| `high` | Think on every eligible question. The published Decision Index score uses this setting. |
+| `high-k2` … `high-k8` | Several thoughts, averaged. Slowest. |
+
+Thinking applies to questions with 2–26 options when the context has room; otherwise the one-pass answer is returned.
+
+## Python client
+
+```python
+import requests
+
+r = requests.post("http://localhost:8000/v1/systemone", json={
+    "state": "Refund request for order 1182; the parcel arrived damaged.",
+    "effort": "none",
+    "questions": {"route": {"type": "choice", "criteria": {
+        "refunds": "Refunds and returns", "shipping": "Delivery problems", "other": "Anything else"}}},
+}, timeout=30)
+answer = r.json()["answers"]["route"]
+print(answer["choice"], answer["probabilities"])
+```
+
+Source: [`server/src/wald_serve/wire.py`](https://huggingface.co/Harry19081/Wald-4B/blob/main/server/src/wald_serve/wire.py) (request shapes) and [`server.py`](https://huggingface.co/Harry19081/Wald-4B/blob/main/server/src/wald_serve/server.py) (endpoints).

docs/readmes/README.zh.md

@@ -1,21 +1,56 @@
 <div align="center">
   <h1>Wald-Q4B v1.1</h1>
   <p><strong>直接决策，按需思考，返回概率。</strong></p>
-  <p><a href="../../README.md">English</a> · <a href="README.zh.md">简体中文</a></p>
+  <p><a href="https://huggingface.co/Harry19081/Wald-4B">English</a> · <a href="https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/readmes/README.zh.md">简体中文</a> · <a href="https://github.com/Harry19081/wald-4b">GitHub</a> · <a href="https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md">API</a></p>
 </div>
 
-**Wald-Q4B v1.1 是面向结构化决策、可自行部署的开放权重 Jev 替代方案。** 它基于 Qwen3.5-4B-Base，提供可调思考程度和 TypeSafe 兼容的 `/v1/systemone` API，可用于工具选择、agent 路由和选项概率评分。
+**Wald-Q4B v1.1 是一个开放权重的 4B 决策模型：给它一段状态和一组选项，它为每个选项返回校准过的概率。** 它面向构建 agent 和数据流水线的开发者：需要一个快速、可自行部署的组件来选择工具、路由请求、分类输入，或判断是否需要向用户澄清。和聊天模型不同，它不生成需要再解析的答案，而是一遍读出所有选项的概率（effort `none` 时单张 RTX PRO 6000 上中位延迟 33 ms），也可以先思考再回答。它提供与 Jev 兼容的 `POST /v1/systemone` API，基于 Qwen3.5-4B-Base，以 Apache-2.0 发布。
 
-**W**ait **A** bit, **L**ook, then **D**ecide：稍等一下，看清楚，再决定。名字也致敬序贯分析先驱 Abraham Wald：证据足够时就停止。
+Wald-Q4B 是 TypeSafe 托管 Jev API 之外、可自行部署的独立替代方案。它不是 Jev，不含 Jev 权重，与 TypeSafe AI 没有隶属或背书关系。Hugging Face 仓库为 `Harry19081/Wald-4B`（旧名 Wald-4B）。
 
-给 Wald 一段状态、一个问题和一组选项，它会返回每个选项的概率。可用于工具选择、请求路由、分类和判断是否需要向用户澄清。通过一个 `effort` 参数控制思考程度；无论选择哪个级别，答案都是结构化概率分布。
+**W**ait **A** bit, **L**ook, then **D**ecide：稍等一下，看清楚，再决定。名字也致敬序贯分析先驱 Abraham Wald：证据足够时就停止。
 
 ## 一览
 
-- **4B 参数**，基于 Qwen3.5-4B-Base，BF16 权重。
+- **4B 参数**，基于 Qwen3.5-4B-Base，BF16 权重（8.4 GB）。
+- **每个选项都有概率。** 题型：`choice`（1–255 个命名选项）、`noul`（是/否）、`score`（有序等级）。
 - **可调思考程度**：`none`、`low`、`medium`、`high`，以及多次思考的 `high-k`。
-- **完整 Decision Index 0.2.1：54.59**，使用 `high`，150,317 个请求全部成功。
-- **可自行部署**：`POST /v1/systemone`；每题最多 131,072 个提示 token、255 个选项。
+- **完整 Decision Index 0.2.1：54.59**，使用 `high`，150,317 个请求全部成功。作者自测，等待维护者验证。
+- **JevBench 公开集：203/231**，使用 `none`，ECE 0.041，p50 33 ms / p95 168 ms。用 JevBench 自己的评测工具自评。
+- **可自行部署的 API**：`POST /v1/systemone`，最多 131,072 个提示 token。
+
+## 快速开始
+
+在装有 NVIDIA GPU 和 [`uv`](https://docs.astral.sh/uv/) 的 Linux 机器上：
+
+```sh
+hf download Harry19081/Wald-4B --revision v1.1 --local-dir ./Wald-Q4B
+cd Wald-Q4B
+EFFORT=none ./run.sh "$PWD"     # 一遍读出，延迟最低
+# ./run.sh "$PWD"               # 默认 high，即 Decision Index 的评测配置
+```
+
+```sh
+curl http://localhost:8000/v1/systemone \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "state": "The customer wants to return a damaged kettle.",
+    "effort": "medium",
+    "questions": {
+      "route": {
+        "type": "choice",
+        "instructions": "Choose the support queue.",
+        "criteria": {
+          "returns": "Returns and refunds",
+          "delivery": "Delivery tracking",
+          "other": "Other enquiries"
+        }
+      }
+    }
+  }'
+```
+
+`route` 的答案包含选中的键，以及 `returns`、`delivery`、`other` 各自的概率。请求与响应字段、是非题和评分题、澄清判断示例见 [API 说明](https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md)。`GET /health` 返回当前生效策略。服务使用 vLLM 0.30.0 和仓库内的 `wald-serve`；Docker 与精确评测配置见 [RUNBOOK.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/RUNBOOK.md)。普通文本生成接口不会复现决策 API 的读出流程。
 
 ## 思考程度
 
@@ -29,7 +64,7 @@
 | **`high`（默认）** | 每个符合条件的问题 | 最多 512 token |
 | `high-k2` … `high-k8` | 多次思考，平均答案分布 | 每次最多 512 token |
 
-思考适用于 2–26 个选项且上下文空间足够的问题。更多选项采用分组读取，再比较各组优胜项；若放不下思考文本，则保留初次答案。提高 effort 会增加计算量，但不保证每道题都更准确。**54.59 仅对应 `high`。**
+思考适���于 2–26 个选项且上下文空间足够的问题。更多选项采用分组读取，再比较各组优胜项；若放不下思考文本，则保留初次答案。提高 effort 会增加计算量，但不保证每道题都更准确。**54.59 仅对应 `high`；203/231 仅对应 `none`。**
 
 通过 `EFFORT=medium ./run.sh "$PWD"` 设置服务默认值，也可在单次请求中传入 `"effort": "none"` 覆盖。
 
@@ -37,64 +72,73 @@
 
 Wald 先从普通文本提示末尾读取选项字母的 logits，得到初始概率。如果 effort 策略触发思考，就生成一段短思考，再读取选项。返回的概率经过分桶温度校准。
 
-v1.1 结合全参数决策训练、LoRA 精修、短思考蒸馏和 RLCD。训练使用我们的自生成决策语料 **WaldGen**，并混合公开训练数据。[数据来源](../../PROVENANCE.md) · [评测说明](../../CONTAMINATION.md)
+v1.1 结合全参数决策训练、LoRA 精修、短思考蒸馏和 RLCD。训练使用我们的自生成决策语料 **WaldGen**，并混合公开训练数据。[数据来源](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md) · [评测说明](https://huggingface.co/Harry19081/Wald-4B/blob/main/CONTAMINATION.md)
 
 ## 评测
 
-| 基准 | 配置 | 分数 |
-|---|---|---:|
-| **Decision Index 0.2.1 完整套件** | v1.1 · `high` | **54.59** |
+| 基准 | 配置 | 结果 | 状态 |
+|---|---|---:|---|
+| **Decision Index 0.2.1 完整套件** | v1.1 · `high` | **54.59** | 作者自测；[PR #30](https://github.com/apolinario/decision-index/pull/30) 等待维护者验证 |
+| **JevBench 公开集（231 题）** | v1.1 · `none` | **203/231**（87.9%）· ECE 0.041 · Brier 0.188 | 自评；[issue #146](https://github.com/fstandhartinger/jevbench/issues/146) 请维护者自行测量 |
 
-150,317/150,317 个请求全部成功，包含 HLE。在单张 RTX PRO 6000 96 GB 上使用固定版本的复现工具运行。这是作者自行测量的结果；[提交 #30](https://github.com/apolinario/decision-index/pull/30) 等待维护者验证。
+**Decision Index：** 150,317/150,317 个请求全部成功，包含 HLE。在单张 RTX PRO 6000 96 GB 上使用固定版本的复现工具运行。[完整结果](https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results/tree/805716601b2466be324ed6716407b4c3d9267faa/runs/wald-q4b-22d0-f7-full021) · [分项成绩](https://huggingface.co/Harry19081/Wald-4B/blob/main/evaluation/benchmark-summary.json) · [复现指南](https://huggingface.co/Harry19081/Wald-4B/blob/main/RUNBOOK.md)
 
-[完整结果](https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results/tree/805716601b2466be324ed6716407b4c3d9267faa/runs/wald-q4b-22d0-f7-full021) · [分项成绩](../../evaluation/benchmark-summary.json) · [复现指南](../../RUNBOOK.md)
+**JevBench：** 使用 JevBench 自己的命令行工具（`fstandhartinger/jevbench` @ `9ec6f15a`，`typesafe` 适配器），在单张 RTX PRO 6000 上通过本机回环逐条请求打包服务。easy 48/48、original 72/72、hard 83/111；不生成任何 token。`medium` 为 205/231，p95 1.80 s。公开题在开发中被用作计分板（从未作为训练数据），因此这不是留出集结果。JevBench 排行榜只在维护者自己跑过模型后才公布分数。
 
 ### 速度
 
-v1.1 `high` 在 RTX PRO 6000 上的 32 请求串行预检中，**中位延迟为 821 ms**。这只是小规模预检，不代表完整套件延迟或维护者的准入测试。effort、上下文长度、选项数量和并发都会影响速度。
+使用 `none` 时，上述 JevBench 运行的单次决策**中位延迟 33 ms、p95 168 ms**。`high` 在同一 GPU 上的 32 请求串行预检中，**中位延迟为 821 ms**；这只是小规模预检，不代表完整套件延迟或 Decision Index 维护者的准入测试。effort、上下文长度、选项数量和并发都会影响速度。
 
-## 部署与调用
+## 相关项目与对比
 
-在装有 `uv` 的 Linux CUDA 机器上：
+多个项目在做带校准选项概率的结构化决策。以下名称归各自所有者；Wald 与它们都没有隶属关系。
 
-```sh
-hf download Harry19081/Wald-4B --revision v1.1 --local-dir ./Wald-Q4B
-cd Wald-Q4B
-./run.sh "$PWD"                 # 默认 high
-# EFFORT=medium ./run.sh "$PWD"  # 按置信度触发思考
-```
+- **[Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)** 是 TypeSafe AI 通过 `/v1/systemone` API 提供的托管决策模型，权重不公开。Wald 接受相同的请求格式，运行在你自己的 GPU 上。
+- **[Kev](https://github.com/jaredpalmer/kev)** 是 Jared Palmer 的开放权重项目，在 Qwen3.5 基座（0.8B、4B、9B）上加 LoRA 和指针头。Wald 的请求解析改编自 Kev 的 Apache-2.0 代码（见 [NOTICE](https://huggingface.co/Harry19081/Wald-4B/blob/main/NOTICE)）；Wald 从语言模型头读取选项字母，不使用单独的头。
+- **[Laya](https://huggingface.co/convaiinnovations/laya)**（[代码](https://github.com/NandhaKishorM/laya)）是开放权重的 421M ModernBERT-large ���码器加决策头。它比 Wald 小得多，最多读取 512 个 token。
 
-```sh
-curl http://localhost:8000/v1/systemone \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "state": "The customer wants to return a damaged kettle.",
-    "effort": "medium",
-    "questions": {
-      "route": {
-        "type": "choice",
-        "instructions": "Choose the support queue.",
-        "criteria": {
-          "returns": "Returns and refunds",
-          "delivery": "Delivery tracking",
-          "other": "Other enquiries"
-        }
-      }
-    }
-  }'
-```
+**JevBench 公开集，同一批 231 题（数据集哈希相同），JevBench 命令行工具，由我们运行：**
 
-`GET /health` 返回当前生效策略。服务使用 vLLM 0.30.0 和仓库内的 `wald-serve`。Docker 与精确评测配置见[运行指南](../../RUNBOOK.md)。普通文本生成接口不会复现决策 API 的读出流程。
+| 系统 | 运行方式 | 答对 |
+|---|---|---:|
+| Wald-Q4B v1.1 · `none` | 自行部署，RTX PRO 6000，2026-09-29 | 203/231 |
+| Jev（`jev-1.13.0`） | TypeSafe 托管 API，2026-09-25 | 200/231 |
+| Laya（英文 checkpoint `55cf4c4e`） | 自行部署，NVIDIA L4，2026-09-26 | 134/231 |
 
-## 使用限制
+231 题上 3 题的差距在多次运行和抽样的噪声范围内。公开题影响过 Wald 的开发；231 题中有 52 题的状态超过 Laya 的 512 token 窗口。
+
+**Decision Index 0.2.1：**
+
+| 系统 | 指数 | 来源 |
+|---|---:|---|
+| Jev（`jev-1.13.0`） | 57.91 | [排行榜](https://huggingface.co/spaces/multimodalart/jev-decision-index)，维护者运行（2026-09-28 数据） |
+| Wald-Q4B v1.1 · `high` | 54.59 | 作者自测完整套件；尚未上榜（[PR #30](https://github.com/apolinario/decision-index/pull/30)） |
+| Kev 9B | 38.48 | 排行榜，维护者运行（2026-09-28 数据） |
+| Kev 4B | 34.64 | 排行榜，维护者运行（2026-09-28 数据） |
+
+排行榜各行由维护者评分；Wald 的分数是用官方工具自测的，验证后可能变化。
+
+## 常见问题
+
+**有开源的 Jev 替代品吗？** Wald-Q4B 是一个开放权重的选择：Apache-2.0 的权重和服务代码，自己部署，提供与 Jev 兼容的 `/v1/systemone` API。Kev 和 Laya（见上）是其他开放项目。Wald 是独立项目，不是 TypeSafe 的发布。
+
+**能用 Jev 客户端调用自部署模型吗？** 把客户端指向你自己的端点。内置服务在 `POST /v1/systemone` 接收 `state` 和带类型的 `questions`（`choice`、`noul`、`score`），按 TypeSafe 的答案键返回。服务不校验 API key。见 [API 说明](https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md)。
+
+**如何做工具路由，或判断是否需要向用户提问？** 把对话或任务作为 `state` 发送。工具路由：提一个 `choice` 问题，选项就是你的工具。是否澄清：提一个 `noul` 问题，例如“这个请求是否足够具体，可以不问就执行？”概率高就执行，概率低就提问，两个阈值都在你自己的验证数据上确定。模型只选工具，不生成工具参数。
 
-置信度不保证正确性，应在自己的任务上验证阈值。超过上下文限制的提示会被拒绝，不会截断。已过滤已知的严格训练重叠，但无法排除语义重叠和预训练污染；开发过程中使用了可见的基准样本。各来源文本的使用权不同，详见[评测说明](../../CONTAMINATION.md)与[来源声明](../../PROVENANCE.md)。
+**概率校准得怎么样？** 在 JevBench 公开集上使用 `none`，期望校准误差为 0.041（10 个分桶），Brier 分数为 0.188。温度是在我们自己开发数据的留出行上拟合的，不含 JevBench 题目，并排除了已知的 Decision Index 匹配项。置信度不是保证，请在你的任务上检查校准。
 
-## Jev 与 agent 集成
+**能在单张 GPU 或笔记本上运行吗？** 内置服务需要 Linux 上的一张 NVIDIA GPU（vLLM 0.30.0）；BF16 权重为 8.4 GB。v1.1 的测量来自 RTX PRO 6000 96 GB；同一 4B 架构的早期版本也曾用 vLLM 在 24 GB 的 NVIDIA L4 上以 16K 上下文上限运行。内置服务不支持 CPU、Apple Silicon 和笔记本环境，也没有测试过。
 
-**可以接入 Jev 风格的客户端吗？** 内置服务在 `/v1/systemone` 接收 `state` 和带类型的 `questions`，支持选择和是非决策。将客户端指向自建端点，并按[运行指南](../../RUNBOOK.md)核对支持的格式。Wald 是独立模型，不是 Jev 权重，也不属于 TypeSafe AI 官方发布。
+**Kev 和 Wald、Laya 和 Wald 怎么选？** 三者都开放权重。Kev 在 Qwen3.5 基座上加指针头和 LoRA；Laya 是带决策头的小型编码器；Wald 是完整训练的 4B 解码器，可选思考。我们在同一协议下的测量见上表。请根据你自己的任务、延迟预算和硬件选择。
 
-**Agent 应选哪个 effort？** 直接读取用 `none`，按置信度触发思考用 `medium`，复现公布分数用 `high`。它们都返回选项概率，无需从生成文本中解析答案。
+**能针对我的任务微调吗？** 它是标准的 Transformers checkpoint，常见的 LoRA 工具都适用。v1.0 时我们为单个任务训练 LoRA，每个花费 $0.12–$1.81 的 GPU 时间；这套工具尚未公开，这些 adapter 也未在 v1.1 上验证（[v1.0 说明](https://huggingface.co/Harry19081/Wald-4B/blob/main/history/v1.0/README.md)）。
+
+**许可证是什么？** 权重与代码为 Apache-2.0。基座 Qwen3.5-4B-Base 也是 Apache-2.0。部分公开训练数据有各自的条款或没有注明许可证，列在 [PROVENANCE.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md)。模型与代码的许可证不授予这些文本的权利。
+
+## 使用限制
+
+置信度不保证正确性，应在自己的任务上验证阈值。超过上下文限制的提示会被拒绝，不会截断。已过滤已知的严格训练重叠，但无法排除语义重叠和预训练污染；开发过程中使用了可见的基准样本。各来源文本的使用权不同，详见[评测说明](https://huggingface.co/Harry19081/Wald-4B/blob/main/CONTAMINATION.md)与[来源声明](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md)。
 
 ## 版本
 
@@ -103,8 +147,24 @@ curl http://localhost:8000/v1/systemone \
 | **v1.1 — 当前版本** | `022D0-f7` | `high` |
 | [v1.0 — 历史版本](https://huggingface.co/Harry19081/Wald-4B/tree/v1.0) | `021A0-f10` | `medium` |
 
-v1.0 模型卡保留其 XL、任务 LoRA 和延迟报告；这些测量属于各自注明的模型版本。
+v1.0 模型卡保留其 XL、任务 LoRA 和延迟报告，[v1.0 讲解幻灯片](https://claude.ai/artifact/XfCHVaCuj9A5ectrpaWzV5)只描述 v1.0。这些测量属于各自注明的模型版本。
+
+## 引用
+
+Wald-Q4B v1.1 (2026), an open-weight 4B decision model with calibrated option probabilities. https://huggingface.co/Harry19081/Wald-4B
+
+```bibtex
+@misc{wald_q4b_2026,
+  title        = {Wald-Q4B v1.1: an open-weight 4B decision model with calibrated option probabilities},
+  author       = {{Wald-4B authors}},
+  year         = {2026},
+  howpublished = {\url{https://huggingface.co/Harry19081/Wald-4B}},
+  note         = {Revision v1.1}
+}
+```
+
+机器可读：[CITATION.cff](https://huggingface.co/Harry19081/Wald-4B/blob/main/CITATION.cff) · [llms.txt](https://huggingface.co/Harry19081/Wald-4B/blob/main/llms.txt) · [model-info.json](https://huggingface.co/Harry19081/Wald-4B/blob/main/model-info.json)
 
 ---
 
-[机器可读模型信息](../../model-info.json) · 权重与代码：Apache-2.0。[第三方声明](../../NOTICE) · [训练数据使用说明](../../PROVENANCE.md)
+[模型](https://huggingface.co/Harry19081/Wald-4B) · [GitHub](https://github.com/Harry19081/wald-4b) · [Decision Index 结果](https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results) · 权重与代码：Apache-2.0。[第三方声明](https://huggingface.co/Harry19081/Wald-4B/blob/main/NOTICE) · [训练数据使用说明](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md)

llms.txt

@@ -0,0 +1,31 @@
+# Wald-Q4B v1.1
+
+> Open-weight 4B decision model. Given a state and typed questions (choice, yes/no, score), it returns a calibrated probability for every option through a Jev-compatible `POST /v1/systemone` API. Built on Qwen3.5-4B-Base; Apache-2.0 weights and serving code; self-hosted on one NVIDIA GPU with vLLM. Independent project, not affiliated with or endorsed by TypeSafe AI.
+
+Key facts:
+- Hugging Face repository: Harry19081/Wald-4B (current release tag `v1.1`; earlier name Wald-4B). GitHub: Harry19081/wald-4b.
+- Uses: tool selection, agent routing, classification, deciding whether to ask the user a clarifying question.
+- Effort levels: `none` (one pass, no generated tokens), `low`, `medium`, `high` (default), `high-k2`…`high-k8`.
+- JevBench public set (231 items), effort `none`: 203/231, ECE 0.041, p50 33 ms / p95 168 ms on one RTX PRO 6000. Self-scored with JevBench's harness; the public items were a development scoreboard, not held out. Leaderboard row requested in fstandhartinger/jevbench issue #146.
+- Decision Index 0.2.1 complete suite, effort `high`: 54.59 balanced-skill index. Author-run; submission apolinario/decision-index PR #30 awaits maintainer validation.
+
+## Docs
+
+- [Model card](https://huggingface.co/Harry19081/Wald-4B): what it is, benchmarks, comparisons with Jev, Kev and Laya, FAQ, limits
+- [API reference](https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md): request and response JSON with examples
+- [RUNBOOK.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/RUNBOOK.md): serving and exact evaluation settings
+- [Chinese model card](https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/readmes/README.zh.md)
+
+## Evidence
+
+- [Decision Index results dataset](https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results): untouched responses and scores
+- [Decision Index submission PR #30](https://github.com/apolinario/decision-index/pull/30)
+- [JevBench request issue #146](https://github.com/fstandhartinger/jevbench/issues/146)
+- [model-info.json](https://huggingface.co/Harry19081/Wald-4B/blob/main/model-info.json): machine-readable facts
+
+## Optional
+
+- [PROVENANCE.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/PROVENANCE.md): training-data sources and their terms
+- [CONTAMINATION.md](https://huggingface.co/Harry19081/Wald-4B/blob/main/CONTAMINATION.md): evaluation caveats
+- [CITATION.cff](https://huggingface.co/Harry19081/Wald-4B/blob/main/CITATION.cff)
+- [Server source](https://github.com/Harry19081/wald-4b/tree/main/server)

model-info.json

@@ -5,7 +5,7 @@
     "Wald-4B"
   ],
   "checkpoint": "022D0-f7",
-  "description": "Self-hosted open-weight decision model and independent Jev alternative with adjustable thinking effort and a TypeSafe-compatible /v1/systemone API.",
+  "description": "Open-weight 4B decision model that returns a calibrated probability for every option through a Jev-compatible POST /v1/systemone API; one pass or optional thinking; self-hosted. Independent, not affiliated with TypeSafe AI.",
   "base_model": "Qwen/Qwen3.5-4B-Base",
   "model_url": "https://huggingface.co/Harry19081/Wald-4B",
   "weights_revision": "50f94ecd5d6e7e8459e9c198ef811bfaba12a3fe",
@@ -72,7 +72,36 @@
     "zh": "docs/readmes/README.zh.md",
     "serving": "RUNBOOK.md",
     "sources": "PROVENANCE.md",
-    "evaluation_notes": "CONTAMINATION.md"
+    "evaluation_notes": "CONTAMINATION.md",
+    "api": "docs/api.md",
+    "citation": "CITATION.cff",
+    "llms": "llms.txt"
   },
-  "affiliation": "Independent; not affiliated with TypeSafe AI"
+  "affiliation": "Independent; not affiliated with TypeSafe AI",
+  "evaluations": [
+    {
+      "benchmark": "JevBench",
+      "split": "public",
+      "items": 231,
+      "effort": "none",
+      "correct": 203,
+      "accuracy": 0.8788,
+      "ece": 0.041,
+      "brier": 0.188,
+      "latency_p50_ms": 33,
+      "latency_p95_ms": 168,
+      "hardware": "NVIDIA RTX PRO 6000 96 GB",
+      "harness": "fstandhartinger/jevbench@9ec6f15a (jevbench.cli, typesafe adapter, serial, loopback)",
+      "status": "self-scored; public items were a development scoreboard, not held out; leaderboard measurement requested",
+      "request": "https://github.com/fstandhartinger/jevbench/issues/146"
+    }
+  ],
+  "links": {
+    "model": "https://huggingface.co/Harry19081/Wald-4B",
+    "github": "https://github.com/Harry19081/wald-4b",
+    "results_dataset": "https://huggingface.co/datasets/Harry19081/Wald-Q4B-decision-index-results",
+    "decision_index_submission": "https://github.com/apolinario/decision-index/pull/30",
+    "jevbench_request": "https://github.com/fstandhartinger/jevbench/issues/146",
+    "api": "https://huggingface.co/Harry19081/Wald-4B/blob/main/docs/api.md"
+  }
 }