jevify 0.1.0__tar.gz → 0.3.0__tar.gz

jevify-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,133 @@
+# ADR-0007: a published GitHub release is built here from its tag and sent
+# to PyPI by trusted publishing. No token is stored anywhere.
+name: publish
+
+on:
+  release:
+    types: [published]
+  # Dry run against an existing tag: builds, checks and compares, never publishes.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to build and check, e.g. v0.2.0"
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ inputs.tag || github.event.release.tag_name }}
+  cancel-in-progress: false
+
+env:
+  TAG: ${{ inputs.tag || github.event.release.tag_name }}
+
+jobs:
+  build:
+    name: build and check
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      attach: ${{ steps.compare.outputs.attach }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ env.TAG }}
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Tag matches the package version
+        id: version
+        run: |
+          version="$(uv version --short)"
+          if [ "v${version}" != "${TAG}" ]; then
+            echo "::error::tag ${TAG} does not match version ${version} in pyproject.toml"
+            exit 1
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+      - name: Build
+        run: uv build
+      - name: twine check
+        run: uvx twine check --strict dist/*
+      - name: Install the wheel as a tool and run it from another directory
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          uv tool install dist/*.whl
+          cd "${RUNNER_TEMP}"
+          got="$(jevify --version)"
+          if [ "${got}" != "jevify ${VERSION}" ]; then
+            echo "::error::installed wheel reports '${got}', expected 'jevify ${VERSION}'"
+            exit 1
+          fi
+      - name: Compare with the files attached to the release
+        id: compare
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          attached_names="$(gh release view "${TAG}" --json assets \
+            -q '.assets[].name | select(endswith(".whl") or endswith(".tar.gz"))')"
+          if [ -z "${attached_names}" ]; then
+            echo "No wheel or sdist attached to ${TAG}; this build is attached after publishing."
+            echo "attach=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          dir="${RUNNER_TEMP}/attached"
+          mkdir -p "${dir}"
+          gh release download "${TAG}" -p '*.whl' -p '*.tar.gz' -D "${dir}"
+          built="$(cd dist && sha256sum -- *.whl *.tar.gz)"
+          attached="$(cd "${dir}" && sha256sum -- *.whl *.tar.gz)"
+          if [ "${built}" != "${attached}" ]; then
+            echo "::error::the files attached to ${TAG} differ from this build of the tag"
+            echo "built:";    echo "${built}"
+            echo "attached:"; echo "${attached}"
+            exit 1
+          fi
+          echo "Attached files are byte-identical to this build:"
+          echo "${built}"
+          echo "attach=false" >> "$GITHUB_OUTPUT"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/jevify/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  attach:
+    name: attach build to the release
+    needs: [build, publish]
+    if: github.event_name == 'release' && needs.build.outputs.attach == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Upload wheel, sdist and SHA256SUMS
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          cd dist
+          sha256sum -- *.whl *.tar.gz > SHA256SUMS
+          cat SHA256SUMS
+          gh release upload "${TAG}" *.whl *.tar.gz SHA256SUMS

jevify-0.3.0/Makefile

@@ -0,0 +1,50 @@
+# Shortcuts for the two everyday jevify commands: `make ask` asks typed questions
+# about one state and prints the answer as JSON; `make serve` serves Jev's HTTP API
+# for one recipe. Values reach jevify through the environment, so a state may hold
+# spaces, quotes and apostrophes. `make help` lists the variables and the recipes.
+
+JEVIFY ?= uv run jevify
+HOST   ?= 127.0.0.1
+PORT   ?= 8600
+
+export RECIPE STATE CHOICE SCORE NOUL IMAGE RUNG HOST PORT
+
+.DEFAULT_GOAL := help
+.PHONY: help ask serve
+
+help:
+	@echo "make ask   RECIPE=<file> STATE=<text|@file> [CHOICE=...] [SCORE=...] [NOUL=...] [IMAGE=<png|jpg|webp>] [RUNG=<rung>]"
+	@echo "make serve RECIPE=<file> [HOST=$(HOST)] [PORT=$(PORT)]"
+	@echo ""
+	@echo "  CHOICE  id:question=option1,option2,...   one option from a menu"
+	@echo "  SCORE   id:question=level0,level1,...     a position on ordered levels, low to high"
+	@echo "  NOUL    id:statement                      the probability that the statement is true"
+	@echo "  Give at least one of CHOICE, SCORE, NOUL. For several of one type, call jevify ask directly."
+	@echo "  make reads \$$ in a value: write \$$\$$49.99 for \$$49.99, or put the text in a file and pass STATE=@path."
+	@echo "  HOST other than 127.0.0.1 needs JEVIFY_API_KEY set: clients must then send it as a bearer key."
+	@echo ""
+	@echo "Example:"
+	@echo "  make ask RECIPE=recipes/gemma-4-e4b-it.llamacpp.yaml \\"
+	@echo "    STATE=\"Customer: I was charged twice. Fix it today or I cancel.\" \\"
+	@echo "    CHOICE=\"dept:Which team should handle this?=billing,support,sales\" \\"
+	@echo "    SCORE=\"urgency:How urgent is this?=low,medium,high\" \\"
+	@echo "    NOUL=\"cancel:The customer threatens to cancel.\""
+	@echo ""
+	@echo "Recipes:"
+	@ls recipes/*.yaml | sed 's/^/  /'
+
+ask:
+	@test -n "$$RECIPE" || { echo "make ask: set RECIPE=recipes/<name>.yaml (make help lists them)" >&2; exit 2; }
+	@test -n "$$STATE" || { echo "make ask: set STATE=\"...\" (the text, or @path to a file)" >&2; exit 2; }
+	@set -- --state "$$STATE"; \
+	[ -z "$$CHOICE" ] || set -- "$$@" --choice "$$CHOICE"; \
+	[ -z "$$SCORE" ] || set -- "$$@" --score "$$SCORE"; \
+	[ -z "$$NOUL" ] || set -- "$$@" --noul "$$NOUL"; \
+	[ -z "$$IMAGE" ] || set -- "$$@" --image "$$IMAGE"; \
+	[ -z "$$RUNG" ] || set -- "$$@" --rung "$$RUNG"; \
+	$(JEVIFY) ask "$$RECIPE" "$$@"
+
+serve:
+	@test -n "$$RECIPE" || { echo "make serve: set RECIPE=recipes/<name>.yaml (make help lists them)" >&2; exit 2; }
+	@case "$$HOST" in 127.0.0.1|localhost|::1) ;; *) test -n "$$JEVIFY_API_KEY" || { echo "make serve: HOST=$$HOST opens the API to the network; export JEVIFY_API_KEY first" >&2; exit 2; } ;; esac
+	$(JEVIFY) serve "$$RECIPE" --host "$$HOST" --port "$$PORT"

{jevify-0.1.0 → jevify-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jevify
-Version: 0.1.0
+Version: 0.3.0
 Summary: Make a pretrained model you already have answer typed questions in one pass, and measure how well it does.
 Project-URL: Homepage, https://github.com/fidecastro/jevify
 Author: Felipe Infante de Castro
@@ -39,7 +39,8 @@ Jev does, and measure how well it does.**
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
 
 You bring a model behind an OpenAI-compatible endpoint (vLLM, llama.cpp,
-anything with logprobs) or a small model that runs in-process. jevify sends it
+TensorFold, anything that returns logprobs for a reply token or for the
+prompt) or a small model that runs in-process. jevify sends it
 a **state** once, then asks **typed questions** about it: a choice among
 options, a score on ordered levels, a yes/no with a probability. Each answer
 is read straight off the model's next-token distribution, no generation, no
@@ -81,10 +82,36 @@ jevify ask recipes/gemma-4-e4b-it.llamacpp.yaml \
 jevify serve recipes/gemma-4-e4b-it.llamacpp.yaml --port 8600
 ```
 
+Any model behind an OpenAI-compatible server works, not only the ones under
+`recipes/`: copy the nearest recipe, set `endpoint.base_url` and
+`model.name`, and run the probe, which re-verifies the answer token ids for
+that model and writes what it found into the file. vLLM and llama.cpp get
+their dialect extras; any other server is driven through the plain OpenAI
+surface. A server that refuses logprobs on the reply token but returns
+vLLM's `prompt_logprobs`, such as TensorFold's native server with
+GLM-5.3-Flash, is read through the `prompt_logprobs` rung on
+`/v1/completions`: with a raw-mode recipe (the template written out with the
+model's own control tokens), or with a chat-template recipe where the server
+also takes `messages` on that route, as TensorFold's does. The chat form is
+the one that carries images.
+
+`serve` binds to `127.0.0.1`. To reach it from other machines pass
+`--host 0.0.0.0`, and set `JEVIFY_API_KEY` first so that every request must
+carry that bearer key; to leave it running, detach it and keep its log:
+
+```sh
+jevify serve recipes/<name>.yaml --host 0.0.0.0 --port 8600 > ~/jevify.log 2>&1 &
+curl -s http://<this-host>:8600/health
+```
+
 Every answer carries Jev's fields (`choice`, `confidence`, `probabilities`,
 `score`, `legend`, `noul`) plus an `x_jevify` block naming the readout method,
 the cached tokens, the latency and the recipe hash that produced it.
 
+From a clone, `make ask` and `make serve` wrap the two commands;
+[`docs/playbook.md`](https://github.com/fidecastro/jevify/blob/main/docs/playbook.md)
+walks through them and explains every answer field.
+
 ## How it works
 
 1. **Recipe.** A hashed YAML file: the endpoint, the prompt template (chat
@@ -99,7 +126,9 @@ the cached tokens, the latency and the recipe hash that produced it.
    that reuses the server's prefix cache. A 32k-token state costs one warm and
    then a few hundred milliseconds per question.
 4. **Readout ladder.** Named-token logprobs, grammar with post-sampling
-   probabilities, top-k, equal bias, and a floored top-k as the last resort.
+   probabilities, top-k, prompt logprobs (each answer token appended to the
+   prompt and its logprob read back, for servers that give none on the reply
+   token), equal bias, and a floored top-k as the last resort.
    Auto walks down the proven rungs; the answer names the rung that read it
    and whether it was degraded.
 5. **Evidence.** `jevify eval` runs a frozen suite with controls (shuffled
@@ -110,7 +139,7 @@ the cached tokens, the latency and the recipe hash that produced it.
 
 | Kind | Talks to | Proven live with |
 |---|---|---|
-| `endpoint` | Any OpenAI-compatible server; dialect extras for vLLM and llama.cpp | DeepSeek-V4-Flash on vLLM; Ternary Bonsai 2 27B, Gemma 4 E4B and Qwen3-VL-Reranker 8B/2B on llama.cpp; text and images |
+| `endpoint` | Any OpenAI-compatible server that returns reply-token or prompt logprobs; dialect extras for vLLM and llama.cpp | DeepSeek-V4-Flash on vLLM; Ternary Bonsai 2 27B, Gemma 4 E4B and Qwen3-VL-Reranker 8B/2B on llama.cpp; text and images |
 | `embedding` | A `/v1/embeddings` route, or a model in-process | Qwen3-Embedding-0.6B in-process |
 | `encoder` | An NLI sequence-classification head in-process | facebook/bart-large-mnli in-process |
 | `rerank` | A `/v1/rerank` route | Fakes only |
@@ -123,6 +152,28 @@ Four frozen suites, every recipe on each, one run each, latencies per
 question on one machine on one day. Every row links to the scorecard that
 records the command, the recipe hash, the suite hash and the raw file digest.
 
+### Latency per question
+
+The median of each suite, combined across the suites a model ran; one run
+each. A question is one request that reads the answer off the next-token
+probabilities, after the state was sent once and cached.
+
+| Model | How it runs | Hardware | Latency per question |
+|---|---|---|---|
+| facebook/bart-large-mnli | in-process NLI classifier | RTX 4090 | 7–9 ms, avg 8 |
+| Qwen3-Embedding-0.6B | in-process embedding, cosine | RTX 4090 | 8–10 ms, avg 9 |
+| Gemma 4 E4B (Q8_0) | llama.cpp, chat | RTX 4090 | 28–37 ms, avg 32 |
+| Qwen3-VL-Reranker-2B (Q8_0) | llama.cpp, yes/no readout | RTX 4090 | 47–64 ms, avg 53 |
+| Qwen3-VL-Reranker-8B (Q8_0) | llama.cpp, yes/no readout | RTX 4090 | 68 ms (one suite) |
+| Ternary Bonsai 2 27B (PQ2_0) | llama.cpp (PrismML fork), raw prompt | RTX 4090 | 97–113 ms, avg 102 |
+| DeepSeek-V4-Flash | vLLM, chat | 2× DGX Spark, over LAN | 359–672 ms, avg 483 |
+
+Image questions cost the llama.cpp models nothing extra, since the frame is
+paid once in the warm; DeepSeek pays about half again on images. The two
+in-process models are the fastest and the least accurate.
+
+### Accuracy by suite
+
 **policy-29**, the diagnostic suite carried over from the author's earlier experiments (choice only):
 
 | Recipe | Kind | Accuracy | Median latency | Scorecard |
@@ -221,6 +272,8 @@ jevify is written to be operated through a coding agent. Point yours at
 | [`tools/`](https://github.com/fidecastro/jevify/blob/main/tools) | Suite authoring, the Doom recorder and player |
 | [`AGENTS.md`](https://github.com/fidecastro/jevify/blob/main/AGENTS.md) | The engineering principles that bind every change |
 | [`SKILL.md`](https://github.com/fidecastro/jevify/blob/main/SKILL.md) | How an agent operates jevify |
+| [`docs/playbook.md`](https://github.com/fidecastro/jevify/blob/main/docs/playbook.md) | How a person operates jevify: ask, read an answer, serve, add a model, fix common problems |
+| [`Makefile`](https://github.com/fidecastro/jevify/blob/main/Makefile) | `make ask` and `make serve` shortcuts; `make help` lists the variables and recipes |
 
 To work on jevify: `uv sync --group dev` (add `--extra encoder --extra
 games` as needed) and `uv run pytest`. Live and in-process tests skip unless
@@ -229,14 +282,21 @@ you opt in.
 ## Not yet
 
 Named so that nobody has to discover it: a direct-call control, so no
-"faster than generation" claim exists yet; a Doom player that survives (both
-models die within seconds of `deadly_corridor`); the rerank kind and the
+"faster than generation" claim exists yet; clearing Doom's `deadly_corridor`
+(in `defend_the_center` Bonsai's perception plus a fixed rule scores 10 kills
+in 16 seconds, but in the corridor even the rule fed the engine's own labels
+dies before the armour, so the corridor needs a policy with memory, not
+better perception); the rerank kind and the
 embedding route against a live server; a marker-slot encoder layout; the
 grammar rung on the PrismML llama.cpp fork, which accepts a grammar without
-constraining the reported probabilities; Windows. Choice menus on the
-endpoint kind are bounded by the single-token identifier alphabet the probe
-verifies (26 on the DeepSeek recipe); Jev's 255-option ceiling is not
-reachable there.
+constraining the reported probabilities; the `prompt_logprobs` rung on any
+server but TensorFold's native one with GLM-5.3-Flash, where it has been
+probed and asked by hand (raw and chat recipes, text and images) but no
+evaluation suite has been scored on it yet (that server skips its prefix
+cache for such requests, so every question reads the whole state again,
+images included, which the probe measures and notes); Windows. Choice menus on the endpoint kind are bounded by the
+single-token identifier alphabet the probe verifies (26 on the DeepSeek
+recipe); Jev's 255-option ceiling is not reachable there.
 
 ## Licence
 

{jevify-0.1.0 → jevify-0.3.0}/README.md

@@ -9,7 +9,8 @@ Jev does, and measure how well it does.**
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
 
 You bring a model behind an OpenAI-compatible endpoint (vLLM, llama.cpp,
-anything with logprobs) or a small model that runs in-process. jevify sends it
+TensorFold, anything that returns logprobs for a reply token or for the
+prompt) or a small model that runs in-process. jevify sends it
 a **state** once, then asks **typed questions** about it: a choice among
 options, a score on ordered levels, a yes/no with a probability. Each answer
 is read straight off the model's next-token distribution, no generation, no
@@ -51,10 +52,36 @@ jevify ask recipes/gemma-4-e4b-it.llamacpp.yaml \
 jevify serve recipes/gemma-4-e4b-it.llamacpp.yaml --port 8600
 ```
 
+Any model behind an OpenAI-compatible server works, not only the ones under
+`recipes/`: copy the nearest recipe, set `endpoint.base_url` and
+`model.name`, and run the probe, which re-verifies the answer token ids for
+that model and writes what it found into the file. vLLM and llama.cpp get
+their dialect extras; any other server is driven through the plain OpenAI
+surface. A server that refuses logprobs on the reply token but returns
+vLLM's `prompt_logprobs`, such as TensorFold's native server with
+GLM-5.3-Flash, is read through the `prompt_logprobs` rung on
+`/v1/completions`: with a raw-mode recipe (the template written out with the
+model's own control tokens), or with a chat-template recipe where the server
+also takes `messages` on that route, as TensorFold's does. The chat form is
+the one that carries images.
+
+`serve` binds to `127.0.0.1`. To reach it from other machines pass
+`--host 0.0.0.0`, and set `JEVIFY_API_KEY` first so that every request must
+carry that bearer key; to leave it running, detach it and keep its log:
+
+```sh
+jevify serve recipes/<name>.yaml --host 0.0.0.0 --port 8600 > ~/jevify.log 2>&1 &
+curl -s http://<this-host>:8600/health
+```
+
 Every answer carries Jev's fields (`choice`, `confidence`, `probabilities`,
 `score`, `legend`, `noul`) plus an `x_jevify` block naming the readout method,
 the cached tokens, the latency and the recipe hash that produced it.
 
+From a clone, `make ask` and `make serve` wrap the two commands;
+[`docs/playbook.md`](https://github.com/fidecastro/jevify/blob/main/docs/playbook.md)
+walks through them and explains every answer field.
+
 ## How it works
 
 1. **Recipe.** A hashed YAML file: the endpoint, the prompt template (chat
@@ -69,7 +96,9 @@ the cached tokens, the latency and the recipe hash that produced it.
    that reuses the server's prefix cache. A 32k-token state costs one warm and
    then a few hundred milliseconds per question.
 4. **Readout ladder.** Named-token logprobs, grammar with post-sampling
-   probabilities, top-k, equal bias, and a floored top-k as the last resort.
+   probabilities, top-k, prompt logprobs (each answer token appended to the
+   prompt and its logprob read back, for servers that give none on the reply
+   token), equal bias, and a floored top-k as the last resort.
    Auto walks down the proven rungs; the answer names the rung that read it
    and whether it was degraded.
 5. **Evidence.** `jevify eval` runs a frozen suite with controls (shuffled
@@ -80,7 +109,7 @@ the cached tokens, the latency and the recipe hash that produced it.
 
 | Kind | Talks to | Proven live with |
 |---|---|---|
-| `endpoint` | Any OpenAI-compatible server; dialect extras for vLLM and llama.cpp | DeepSeek-V4-Flash on vLLM; Ternary Bonsai 2 27B, Gemma 4 E4B and Qwen3-VL-Reranker 8B/2B on llama.cpp; text and images |
+| `endpoint` | Any OpenAI-compatible server that returns reply-token or prompt logprobs; dialect extras for vLLM and llama.cpp | DeepSeek-V4-Flash on vLLM; Ternary Bonsai 2 27B, Gemma 4 E4B and Qwen3-VL-Reranker 8B/2B on llama.cpp; text and images |
 | `embedding` | A `/v1/embeddings` route, or a model in-process | Qwen3-Embedding-0.6B in-process |
 | `encoder` | An NLI sequence-classification head in-process | facebook/bart-large-mnli in-process |
 | `rerank` | A `/v1/rerank` route | Fakes only |
@@ -93,6 +122,28 @@ Four frozen suites, every recipe on each, one run each, latencies per
 question on one machine on one day. Every row links to the scorecard that
 records the command, the recipe hash, the suite hash and the raw file digest.
 
+### Latency per question
+
+The median of each suite, combined across the suites a model ran; one run
+each. A question is one request that reads the answer off the next-token
+probabilities, after the state was sent once and cached.
+
+| Model | How it runs | Hardware | Latency per question |
+|---|---|---|---|
+| facebook/bart-large-mnli | in-process NLI classifier | RTX 4090 | 7–9 ms, avg 8 |
+| Qwen3-Embedding-0.6B | in-process embedding, cosine | RTX 4090 | 8–10 ms, avg 9 |
+| Gemma 4 E4B (Q8_0) | llama.cpp, chat | RTX 4090 | 28–37 ms, avg 32 |
+| Qwen3-VL-Reranker-2B (Q8_0) | llama.cpp, yes/no readout | RTX 4090 | 47–64 ms, avg 53 |
+| Qwen3-VL-Reranker-8B (Q8_0) | llama.cpp, yes/no readout | RTX 4090 | 68 ms (one suite) |
+| Ternary Bonsai 2 27B (PQ2_0) | llama.cpp (PrismML fork), raw prompt | RTX 4090 | 97–113 ms, avg 102 |
+| DeepSeek-V4-Flash | vLLM, chat | 2× DGX Spark, over LAN | 359–672 ms, avg 483 |
+
+Image questions cost the llama.cpp models nothing extra, since the frame is
+paid once in the warm; DeepSeek pays about half again on images. The two
+in-process models are the fastest and the least accurate.
+
+### Accuracy by suite
+
 **policy-29**, the diagnostic suite carried over from the author's earlier experiments (choice only):
 
 | Recipe | Kind | Accuracy | Median latency | Scorecard |
@@ -191,6 +242,8 @@ jevify is written to be operated through a coding agent. Point yours at
 | [`tools/`](https://github.com/fidecastro/jevify/blob/main/tools) | Suite authoring, the Doom recorder and player |
 | [`AGENTS.md`](https://github.com/fidecastro/jevify/blob/main/AGENTS.md) | The engineering principles that bind every change |
 | [`SKILL.md`](https://github.com/fidecastro/jevify/blob/main/SKILL.md) | How an agent operates jevify |
+| [`docs/playbook.md`](https://github.com/fidecastro/jevify/blob/main/docs/playbook.md) | How a person operates jevify: ask, read an answer, serve, add a model, fix common problems |
+| [`Makefile`](https://github.com/fidecastro/jevify/blob/main/Makefile) | `make ask` and `make serve` shortcuts; `make help` lists the variables and recipes |
 
 To work on jevify: `uv sync --group dev` (add `--extra encoder --extra
 games` as needed) and `uv run pytest`. Live and in-process tests skip unless
@@ -199,14 +252,21 @@ you opt in.
 ## Not yet
 
 Named so that nobody has to discover it: a direct-call control, so no
-"faster than generation" claim exists yet; a Doom player that survives (both
-models die within seconds of `deadly_corridor`); the rerank kind and the
+"faster than generation" claim exists yet; clearing Doom's `deadly_corridor`
+(in `defend_the_center` Bonsai's perception plus a fixed rule scores 10 kills
+in 16 seconds, but in the corridor even the rule fed the engine's own labels
+dies before the armour, so the corridor needs a policy with memory, not
+better perception); the rerank kind and the
 embedding route against a live server; a marker-slot encoder layout; the
 grammar rung on the PrismML llama.cpp fork, which accepts a grammar without
-constraining the reported probabilities; Windows. Choice menus on the
-endpoint kind are bounded by the single-token identifier alphabet the probe
-verifies (26 on the DeepSeek recipe); Jev's 255-option ceiling is not
-reachable there.
+constraining the reported probabilities; the `prompt_logprobs` rung on any
+server but TensorFold's native one with GLM-5.3-Flash, where it has been
+probed and asked by hand (raw and chat recipes, text and images) but no
+evaluation suite has been scored on it yet (that server skips its prefix
+cache for such requests, so every question reads the whole state again,
+images included, which the probe measures and notes); Windows. Choice menus on the endpoint kind are bounded by the
+single-token identifier alphabet the probe verifies (26 on the DeepSeek
+recipe); Jev's 255-option ceiling is not reachable there.
 
 ## Licence
 

{jevify-0.1.0 → jevify-0.3.0}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevify
-description: Operate jevify, the bring-your-own-model harness that makes a pretrained model answer Jev-shaped typed questions (choice, score, noul) over a shared state and measures how well it does. Use when asked to connect a model behind an OpenAI-compatible endpoint (vLLM, llama.cpp, others) or an in-process encoder or embedding model, write or probe a recipe, ask questions, run a suite, read a scorecard, calibrate, or serve Jev's API.
+description: Operate jevify, the bring-your-own-model harness that makes a pretrained model answer Jev-shaped typed questions (choice, score, noul) over a shared state and measures how well it does. Use when asked to connect a model behind an OpenAI-compatible endpoint (vLLM, llama.cpp, TensorFold, others) or an in-process encoder or embedding model, write or probe a recipe, ask questions, run a suite, read a scorecard, calibrate, or serve Jev's API.
 ---
 
 # Operating jevify
@@ -31,7 +31,9 @@ result.
    rows carry `images`, regenerate the frames with
    `uv run python tools/record_doom_suite.py` after `uv sync --extra games`),
    `long-state-24` (2k to 32k tokens). `tools/play_doom.py <recipe> --scenario
-   defend_the_center --policy perception` records a video of a recipe playing.
+   defend_the_center --policy perception` records a video of a recipe playing;
+   `--policy expert` replays the same rule from the engine's labels, the
+   ceiling any perception can reach with that rule.
    Raw decisions land in `runs/` (git-ignored); the summary in `docs/evidence/`
    (committed). Read the Markdown summary, then the `wrong` list in the JSON.
 5. **Serve**: `jevify serve recipes/<name>.yaml --port 8600`. Jev's SDK works
@@ -51,15 +53,37 @@ Every recipe has `schema_version: 1`, `model: {name, kind, revision}` and
 the rest.
 
 **`endpoint`** (any OpenAI-compatible server): `endpoint: {base_url,
-api_key_env, dialect: auto|vllm|llamacpp|generic, timeout_s}`, `template`
-and `answers`.
+api_key_env, dialect: auto|vllm|llamacpp|generic, timeout_s, extra_body,
+headers, headers_env}`, `template` and `answers`.
 - `template.mode: messages` sends chat messages; put thinking off in
   `template.kwargs` (`{thinking: false}` for DeepSeek, `{enable_thinking:
   false}` for Qwen3-class models; names are model-specific, the probe checks
   that no `<think>` token opens the answer).
+- `endpoint.extra_body` is merged into the top level of every request, for
+  servers that take a switch there rather than as a template argument. The
+  `generic` dialect sends no template arguments, so on Ollama's `/v1` route
+  a thinking model needs `extra_body: {reasoning_effort: none}` (`think:
+  false` is ignored there). A key jevify itself sets (`max_tokens`,
+  `logprobs`, `logit_bias`, ...) is refused when the backend is built, before
+  any request, so probe, ask, eval and serve all fail the same way. The
+  fields also reach the tokenize and template routes the probe uses.
+- `endpoint.headers` adds static HTTP headers to every request, for a router
+  or gateway that requires one (`{x-client-id: agenticApp}`). The values are
+  written in the recipe and hashed with it, so never put a secret there: a
+  bearer key goes in the env var that `api_key_env` names, and any other
+  secret header in `endpoint.headers_env` (header name to env var name, read
+  when the backend is built; an unset variable fails then). A static header
+  whose name looks like a credential (`key`, `token`, `secret`, `auth`,
+  `cookie`, ...) is refused when the recipe loads; `Content-Type` and
+  `Authorization` are refused when the backend is built. Every
+  endpoint-backed kind sends them (endpoint, rerank, embedding).
 - `template.mode: raw` sends a completion prompt you write with the model's
   own control tokens; use it when the chat template would not put the model
-  in its trained regime (the Qwen3-VL reranker recipe is the example).
+  in its trained regime (the Qwen3-VL reranker recipe is the example), and
+  for a server that refuses reply-token logprobs (TensorFold's native server
+  with GLM-5.3-Flash) when the state is text. The `prompt_logprobs` rung also
+  reads a messages-mode recipe where the server takes `messages` on
+  `/v1/completions` (TensorFold's does); that is the form that carries images.
 - `template.questions.choice_strategy`: `identifiers` (one request, options
   labelled A, B, C) or `per_option` (one yes/no request per option; needed
   for a model that never emits letters, such as a reranker).
@@ -67,8 +91,12 @@ and `answers`.
   the probe fills their ids.
 - `readout.rung: auto` walks the rungs the probe proved, strongest first:
   `named_token_logprobs` (vLLM with `logprob_token_ids`), `grammar`
-  (llama.cpp), `top_k`, `equal_bias`, `top_k_floor` (degraded, missing
-  labels floored and listed). A rung that cannot see every label hands the
+  (llama.cpp), `top_k`, `prompt_logprobs` (each answer spelling appended to
+  a raw prompt, or sent as the assistant's reply in messages mode, and read
+  back from vLLM-style `prompt_logprobs` rows, one
+  request more for every spelling the rows did not show; exact, off-menu mass
+  visible), `equal_bias`, `top_k_floor` (degraded, missing labels floored and
+  listed). A rung that cannot see every label hands the
   question to the next; the answer names the rung that read it. A pinned rung
   never walks: it fails loudly instead.
 
@@ -88,7 +116,10 @@ sequence-classification head; all three question types; semantics `readout`.
 ## Reading an answer
 
 Jev's fields come first (`choice`, `confidence`, `probabilities`; `score`,
-`legend`; `noul`). Everything jevify adds is under `x_jevify`:
+`legend`; `noul`). `confidence` is Jev's statistic, `(n × peak − 1) / (n − 1)`
+over the options or levels: 0 when uniform, 1 when certain, and the number
+TypeSafe's published thresholds refer to. Everything jevify adds is under
+`x_jevify`:
 
 | Field | Meaning |
 |---|---|
@@ -138,6 +169,20 @@ Jev's fields come first (`choice`, `confidence`, `probabilities`; `score`,
   checkpoint at the end of an earlier prompt, and a chat template closes the
   user turn right after the state. Use `template.mode: raw` so the warm prompt
   ends at the state boundary; the Bonsai recipe is the example.
+- **Probe notes "reply-token logprobs refused"**: the server gives no
+  logprobs on a generated token (TensorFold with GLM-5.3-Flash). The probe
+  then tries `prompt_logprobs`: a raw recipe on any such server, a chat
+  recipe where the server takes `messages` on `/v1/completions`; elsewhere a
+  chat recipe ends in "no readout is possible".
+- **"is not at the prompt row the probe measured"**: in messages mode the
+  server's template renders the answer turn differently than when the probe
+  ran (thinking switched on or off, a new template); re-run the probe.
+- **"did not come back as its own prompt token"**: the appended answer fuses
+  with the end of the raw template; end the template where the answer starts
+  a token of its own (after a newline, or before a leading-space spelling).
+- **Probe notes "prompt_logprobs requests reuse no cached prefix"**: the
+  server reads the whole state again for every question on that rung; keep
+  states short there, or serve the model where reply-token logprobs exist.
 - **Missing encoder extra**: the error names the install command.
 
 ## House rules that bind you here

{jevify-0.1.0 → jevify-0.3.0}/docs/00-invariants.md

@@ -126,7 +126,7 @@ API response may claim more than it permits.
 
 Rules that follow:
 
-- **Confidence** is a statistic of the returned distribution: one minus its normalized entropy for choice and score, distance from one half for noul. It is not an independent estimate that the decision is right, and copy may not describe it as one.
+- **Confidence** is Jev's statistic of the returned distribution: `(n × peak − 1) / (n − 1)` over the n options or levels for choice and score, so a uniform distribution scores 0 and a certain one scores 1 (TypeSafe's published definition). Jev's noul answers carry no confidence; jevify reports the distance of P(true) from one half, scaled to [0, 1], under `x_jevify` only. It is not an independent estimate that the decision is right, and copy may not describe it as one.
 - **"Faster"** may be claimed only against a measured direct call on the same backend, same model, same state, with the measurement in a scorecard.
 - **"Accuracy"** names its suite and the suite's hash. A suite whose expected answers came from a teacher model measures agreement with that teacher, and copy says so.
 - **A fine-tuned result is never compared with a zero-shot result in one table** without the words fine-tuned and zero-shot in the row.
@@ -150,6 +150,7 @@ number and the previous wording. The edit and the ADR land in the same commit.
 | Date | Invariant | ADR | Change |
 |---|---|---|---|
 | 2026-09-19 | all | ADR-0001 | Adopted. |
+| 2026-09-23 | §5, confidence rule | ADR-0003 D8 | Confidence is Jev's peak statistic, `(n × peak − 1) / (n − 1)`. Previous wording: "a statistic of the returned distribution: one minus its normalized entropy for choice and score, distance from one half for noul". The entropy statistic disagreed with Jev's published definition, so the SDK-facing `confidence` field did not carry Jev's meaning. |
 
 ## 8. Document map