jevify 0.1.0__tar.gz

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

@@ -0,0 +1,54 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - name: Sync (core + dev group)
+        run: uv sync --locked --group dev
+      - name: Lint
+        run: uv run ruff check . && uv run ruff format --check .
+      - name: Test (unit, guards, sdk acceptance; live tests skip without a backend)
+        run: uv run pytest -m "not live and not encoder"
+      - name: Install as a tool and run it from another directory
+        run: |
+          uv tool install .
+          cd "${RUNNER_TEMP}"
+          jevify --version
+
+  encoder:
+    name: encoder extra (ubuntu, py3.12, cpu torch)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Sync (core + dev group)
+        run: uv sync --locked --group dev
+      - name: Add the encoder extra with CPU-only torch
+        run: |
+          uv pip install --index-url https://download.pytorch.org/whl/cpu torch
+          uv pip install transformers safetensors
+      - name: Test the in-process kinds (downloads small public models)
+        run: uv run --no-sync pytest -m encoder

jevify-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# INV-10: nothing large or secret enters the tree. This file is the chokepoint
+# for that rule (ADR-0001). Extend it; do not work around it.
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Model weights and caches. jevify owns no weights (INV-1); a local download
+# for an in-process adapter lives in the cache, never in git.
+.cache/
+models/
+*.safetensors
+*.gguf
+*.pt
+*.bin
+
+# Raw run outputs. Scorecard summaries derived from them are committed under
+# docs/evidence/ (ADR-0005); the raw per-decision files stay here.
+runs/
+
+# Secrets and local environment
+.env
+.env.*
+*.token
+
+# Recorded suite frames (Doom screenshots): regenerated by tools/, hashes pinned in the manifest
+suites/*/frames/
+_vizdoom.ini

jevify-0.1.0/AGENTS.md

@@ -0,0 +1,122 @@
+# Agent notes — jevify
+
+Instructions for coding agents (Claude, Codex, Grok, Cursor, and others)
+working in this repository. These rules are **mandatory** unless the user
+explicitly overrides them for a task.
+
+This file governs **how** work is done here. **What** the project is lives in
+[`docs/00-invariants.md`](docs/00-invariants.md): purpose, vocabulary, the
+numbered invariants, the design criteria and the score-semantics contract.
+That document ranks above every ADR and above this file. Read it before
+changing anything. Decisions that constrain future work are ADRs under
+`docs/adr/`, indexed in [`docs/adr/README.md`](docs/adr/README.md).
+
+Four principles bind every change, restated here for a project that started
+empty: Always Works, test-driven development, SOLID, and one authoritative
+path per process.
+
+## A. Always Works™ — proof before done
+
+**"Should work" ≠ "does work."** Before marking any change complete, prove
+it with evidence you personally observed in this session, not with
+assumptions, not with "the build succeeded", and not with a result from an
+earlier state of the tree.
+
+| Change type | Minimum proof |
+|---|---|
+| Code | The test suite runs green against the **working tree**, in the interpreter and dependency set the project pins. |
+| Anything that runs, serves, loads or scores | Run it and observe its output. A passing unit test is not a running program. |
+| A number in a document | Comes from a run whose command, inputs and their hashes, model revisions and software versions are recorded next to it. Re-derive; do not copy from memory. |
+| Docs only | No runtime required; still re-read for accuracy against the tree. |
+| Config, CI, scripts | Execute the path that changed. |
+
+**The stale-artifact trap.** Anything cached is evidence about the past:
+a built image, a downloaded checkpoint, a feature cache, a saved run, a
+result file. Before a cached thing counts as proof, show that it
+corresponds to the working tree (rebuild it, or compare a recorded hash or
+revision). A green result on a stale artifact is a silent false green.
+
+**Name what is unproven.** When done, state plainly which paths were
+exercised and which were not. A claim of completion that hides an untested
+path is a defect in the claim, not in the code.
+
+## B. Test-driven development — new behavior is test-first
+
+Do not write production code for a new feature, a bug fix with a known
+reproduction, or a new module until a failing test names the behavior.
+
+| Rule | Detail |
+|---|---|
+| **Red → green → refactor** | Write one failing test; write the minimum code that passes; only then improve structure. |
+| **Vertical slices** | One seam, one behavior at a time. Do not bulk-write a suite of imagined tests and then implement everything. |
+| **Agree the seam first** | Before the first test, state the public interface under test: a function, a Protocol, an HTTP path, a CLI command. Tests hit that seam only. |
+| **No private tests** | Do not assert on private helpers, internal call counts or implementation structure. Prefer fakes at port seams. |
+| **Independent expected values** | Assertions use known literals or domain rules, never a recomputation of the algorithm under test. |
+| **Where tests live** | `tests/`, runnable from a clean checkout with one documented command. |
+| **When TDD does not apply** | Pure renames, docs, configuration, mechanical refactors with no behavior change. Existing tests still run (principle A). |
+
+Measured results are tests too. An experiment has a protocol written and
+hashed **before** the run, a fixed evaluation set, and no post-hoc tuning
+against the test split. A result that was selected on the test set is not
+a result.
+
+## C. SOLID — deep modules behind narrow seams
+
+Prefer **deep modules** (small interface, large behavior) over shallow
+pass-through wrappers. Vocabulary for structure: *module, interface,
+implementation, depth, seam, adapter, port, composition root.*
+
+| Principle | In this repository |
+|---|---|
+| **S** — Single responsibility | One reason to change per module. A module that mixes core logic with a vendor client, a model runtime or a transport has two. |
+| **O** — Open/closed | Extend by adding an adapter or a new caller of a deep module. Do not fork a spine and edit the copy. |
+| **L** — Liskov | Every adapter of a port is substitutable, including test fakes. A fake that honors less of the Protocol than production is a lying test. |
+| **I** — Interface segregation | Focused Protocols. No object that callers use ten percent of. |
+| **D** — Dependency inversion | Core logic depends on **ports** (Protocols), never on concrete adapters, model libraries, HTTP clients or files. One composition root wires adapters into the core; nothing else constructs infrastructure. |
+
+**The deletion test.** If deleting a module only moves lines around and no
+complexity concentrates anywhere, it was shallow. Do not add more of those.
+
+Anti-patterns to reject on sight:
+
+- Implementing first and "adding tests later".
+- Core logic typed against a concrete runtime, client or store instead of a port.
+- A blanket `except Exception` that swallows a failure without logging it and naming its contract.
+- Weakening an invariant in production code to make a test pass.
+- Drive-by changes: reformatting unrelated files, wide renames without need, scope beyond the task.
+- Docs drift: changing a public seam without updating the document that describes it in the same change.
+
+## D. Honor all chokepoints — one authoritative path per singular process
+
+Guarantees held by discipline (comments, naming conventions, hand-mirrored
+copies) drift, and the second copy of a process is the one written without
+the guards.
+
+**A singular process has exactly one implementation.** Anything that looks
+like a second implementation must be one of:
+
+- a **call** into the one authoritative function or module (the chokepoint);
+- a **derived view** computed from the one authoritative registry, never a hand-maintained parallel table;
+- a **pinned mirror**, where a copy is physically unavoidable (another language, another runtime, a serialized payload): a test loads both sides from one fixture or compares them field by field, so drift turns red.
+
+Corollaries, each load-bearing:
+
+1. **Guards travel with the chokepoint, not the caller.** A rule such as "validate before scoring" or "wrap transport exceptions" lives inside the shared function so the next caller inherits it by construction.
+2. **Registries over string literals.** When control flow branches on a family of magic strings, the family gets one registry carrying the strings and their attributes; consumers derive. Wire and record formats are frozen by canary tests; a registry refactors ownership, never compatibility.
+3. **Enforcement is a ratchet test, not a review habit.** A chokepoint ships with a structure guard (an AST scan, an import ban, a fixture comparison) whose failure message names the chokepoint to use. Guards are anti-accident, not anti-adversary, and say so.
+4. **Comments that say "keep in sync with X" are defects.** Replace each with a call, a derivation or a pinned mirror, or document why the sync cannot be structural, dated, with the guard that watches it.
+
+**In a new project the first implementation is the chokepoint.** Create it
+deliberately the moment a process gets its second caller, not after its
+fourth copy. The review question, answerable mechanically: *which
+chokepoint does this go through?* If none fits, the change either creates
+one or documents why the process is genuinely plural.
+
+## House rules
+
+- **Secrets** never enter files, logs, tests or chat. Credentials on this host come from the operator's secret store; pipe them into the consumer, never into the tree.
+- **Local state** stays out of git: downloaded weights, caches, run outputs, generated data. `.gitignore` is the chokepoint for that rule; extend it, do not work around it.
+- **One intent per commit and per PR.** Small, reviewable diffs.
+- **Decisions are recorded.** A choice that constrains future work becomes an ADR under `docs/adr/`, indexed in `docs/adr/README.md`, whose status column is the ledger. Superseding an ADR updates both its row and its header.
+- **Honest claims.** No document, README line, scorecard or API response claims more than the recorded evidence shows. The claims contract is `docs/00-invariants.md` §5; copy that exceeds it is a defect on the same footing as a failing test.
+- **Vocabulary.** Use the terms defined in `docs/00-invariants.md` §2 and no synonyms: state, question, answer, semantics label, readout, adapter, port, probe, recipe, warm, evaluate, suite, scorecard, backend.

jevify-0.1.0/LICENSE

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

jevify-0.1.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.5
+Name: jevify
+Version: 0.1.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
+License-Expression: MIT
+License-File: LICENSE
+Keywords: decisions,evaluation,logprobs,openai-compatible,readout
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.12
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: encoder
+Requires-Dist: safetensors>=0.4; extra == 'encoder'
+Requires-Dist: torch>=2.4; extra == 'encoder'
+Requires-Dist: transformers>=4.51; extra == 'encoder'
+Provides-Extra: games
+Requires-Dist: numpy>=1.26; extra == 'games'
+Requires-Dist: vizdoom>=1.3; extra == 'games'
+Description-Content-Type: text/markdown
+
+# jevify
+
+**Make any model you already have answer typed questions in one pass, the way
+Jev does, and measure how well it does.**
+
+[![CI](https://github.com/fidecastro/jevify/actions/workflows/ci.yml/badge.svg)](https://github.com/fidecastro/jevify/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/jevify.svg)](https://pypi.org/project/jevify/)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](https://github.com/fidecastro/jevify/blob/main/LICENSE)
+[![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
+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
+parsing, one request per question. The result comes back in the exact shape
+of TypeSafe's Jev API, so the unmodified `typesafe-sdk` works against it.
+
+jevify owns no weights and trains nothing. A **recipe** says how a model is
+asked, a **probe** proves what the deployment can do, and a **scorecard**
+says how it did, with the command, hashes and raw file that produced every
+number.
+
+```text
+   state (text, images)          one warm request, cached prefix
+        │
+        ├── "Which team handles this?"  ──►  {billing: 0.94, support: 0.05, sales: 0.01}
+        ├── "How urgent?"               ──►  {low: 0.05, medium: 0.10, high: 0.85}
+        └── "Threatens to cancel."      ──►  p(true) = 0.95
+                                              each ≈ 30–140 ms on a local GPU
+```
+
+## Quickstart
+
+```sh
+uv tool install jevify                # or: pipx install jevify
+git clone https://github.com/fidecastro/jevify && cd jevify
+
+# 1. point a recipe at your server (copy the nearest one under recipes/)
+jevify probe recipes/gemma-4-e4b-it.llamacpp.yaml
+
+# 2. ask
+jevify ask recipes/gemma-4-e4b-it.llamacpp.yaml \
+  --state "Customer: I was charged twice. Fix it today or I cancel." \
+  --choice "dept:Which team should handle this?=billing,support,sales" \
+  --score  "urgency:How urgent is this?=low,medium,high" \
+  --noul   "cancel:The customer threatens to cancel." \
+  [--image screenshot.png]
+
+# 3. serve Jev's API and use the stock SDK
+jevify serve recipes/gemma-4-e4b-it.llamacpp.yaml --port 8600
+```
+
+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.
+
+## How it works
+
+1. **Recipe.** A hashed YAML file: the endpoint, the prompt template (chat
+   messages or a raw prompt with the model's own control tokens), the answer
+   token spellings, and the readout policy. The only way a model is ever
+   asked.
+2. **Probe.** `jevify probe` measures the deployment: dialect (vLLM,
+   llama.cpp, generic), context, which logprob rungs it honours, whether
+   thinking is really off, whether an image really adds tokens, how much of a
+   warmed prefix a question reuses. The findings are written into the recipe.
+3. **Warm, then ask.** The state goes once; each question is a short suffix
+   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.
+   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
+   states, permuted options) and writes a scorecard. `jevify calibrate` fits
+   temperatures and refuses tables it cannot defend.
+
+## Model kinds
+
+| 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 |
+| `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 |
+
+The in-process kinds need `uv tool install 'jevify[encoder]'`.
+
+## Results
+
+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.
+
+**policy-29**, the diagnostic suite carried over from the author's earlier experiments (choice only):
+
+| Recipe | Kind | Accuracy | Median latency | Scorecard |
+|---|---|---|---|---|
+| `gemma-4-e4b-it.llamacpp` | endpoint | 29/29 | 28 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/gemma-4-e4b-it.llamacpp--policy-29.md) |
+| `ternary-bonsai-2-27b.llamacpp` | endpoint | 29/29 | 99 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/ternary-bonsai-2-27b.llamacpp--policy-29.md) |
+| `deepseek-v4-flash-vision-exp-keys.vllm` | endpoint | 28/29 | 428 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/deepseek-v4-flash-vision-exp-keys.vllm--policy-29.md) |
+| `qwen3-vl-reranker-8b.llamacpp` | endpoint | 26/29 | 68 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/qwen3-vl-reranker-8b.llamacpp--policy-29.md) |
+| `qwen3-vl-reranker-2b.llamacpp` | endpoint | 21/29 | 49 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/qwen3-vl-reranker-2b.llamacpp--policy-29.md) |
+| `qwen3-embedding-0.6b.local` | embedding | 19/29 | 8 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/qwen3-embedding-0.6b.local--policy-29.md) |
+| `bart-large-mnli.local` | encoder | 15/29 | 7 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/bart-large-mnli.local--policy-29.md) |
+
+**policy-hard-52**, written for jevify before any model saw it: instruction
+flips, negations, two-threshold policies, distractors, and long transcripts
+with the decisive line buried (`tools/author_policy_hard.py`):
+
+| Recipe | Accuracy | Flips | Thresholds | Long states | Scorecard |
+|---|---|---|---|---|---|
+| `deepseek-v4-flash-vision-exp-keys.vllm` | 47/52 | 6/9 | 16/18 | 12/12 | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/deepseek-v4-flash-vision-exp-keys.vllm--policy-hard-52.md) |
+| `ternary-bonsai-2-27b.llamacpp` | 46/52 | 6/9 | 15/18 | 12/12 | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/ternary-bonsai-2-27b.llamacpp--policy-hard-52.md) |
+| `gemma-4-e4b-it.llamacpp` | 45/52 | 5/9 | 16/18 | 12/12 | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/gemma-4-e4b-it.llamacpp--policy-hard-52.md) |
+| `qwen3-vl-reranker-2b.llamacpp` | 34/52 | 3/9 | 9/18 | 12/12 | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/qwen3-vl-reranker-2b.llamacpp--policy-hard-52.md) |
+| `bart-large-mnli.local` | 28/52 | 3/9 | 8/18 | 12/12 | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/bart-large-mnli.local--policy-hard-52.md) |
+| `qwen3-embedding-0.6b.local` | 24/52 | 3/9 | 8/18 | 6/12 | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/qwen3-embedding-0.6b.local--policy-hard-52.md) |
+
+Every generative model misses the same inverted instructions ("the action the
+customer asked NOT to take"), a weakness the author's earlier experiments found across model
+generations. Negations in the state and long transcripts are solved.
+
+**doom-frames-41**, 164 questions over 41 ViZDoom screenshots at 640×480,
+every label from the engine's labels buffer or a fixed expert rule
+(`tools/record_doom_suite.py`; frames regenerate byte-identically and their
+hashes are pinned in the manifest):
+
+| Recipe | Enemy visible | Enemy count | Enemy side | Expert button | Median latency | Scorecard |
+|---|---|---|---|---|---|---|
+| `deepseek-v4-flash-vision-exp-keys.vllm` | 0.88 | 0.83 | 0.56 | 0.24 | 672 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/deepseek-v4-flash-vision-exp-keys.vllm--doom-frames-41.md) |
+| `ternary-bonsai-2-27b.llamacpp` | 0.93 | 0.85 | 0.37 | 0.24 | 97 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/ternary-bonsai-2-27b.llamacpp--doom-frames-41.md) |
+| `gemma-4-e4b-it.llamacpp` | 0.78 | 0.49 | 0.41 | 0.20 | 36 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/gemma-4-e4b-it.llamacpp--doom-frames-41.md) |
+| `qwen3-vl-reranker-2b.llamacpp` | 0.10 | 0.56 | 0.41 | 0.10 | 64 ms | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/qwen3-vl-reranker-2b.llamacpp--doom-frames-41.md) |
+
+Presence and count are perception; the expert button asks the model to agree
+with a rule it is not told, so that column is a floor for a scripted policy,
+not a skill score. Enemy side is where the vision models diverge most.
+
+**long-state-24**, one decisive customer line at the start, middle or end of
+a filler transcript of about 2k, 8k, 16k or 32k tokens
+(`tools/author_long_state.py`). This is the suite the warm step exists for:
+the state is sent once, and each question then costs only its own tokens.
+
+| Recipe | 2k | 8k | 16k | 32k | Warm at 32k | Per question after warm | Scorecard |
+|---|---|---|---|---|---|---|---|
+| `deepseek-v4-flash-vision-exp-keys.vllm` | 6/6 | 6/6 | 6/6 | 6/6 | 20 s | 359 ms, 31,232 tokens cached | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/deepseek-v4-flash-vision-exp-keys.vllm--long-state-24.md) |
+| `ternary-bonsai-2-27b.llamacpp` | 6/6 | 6/6 | 6/6 | 6/6 | 13 s | 136 ms, 33,946 tokens cached | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/ternary-bonsai-2-27b.llamacpp--long-state-24.md) |
+| `gemma-4-e4b-it.llamacpp` | 6/6 | context | context | context | | 37 ms at 2k | [summary](https://github.com/fidecastro/jevify/blob/main/docs/evidence/gemma-4-e4b-it.llamacpp--long-state-24.md) |
+
+"context" means the launch's slot context was shorter than the state and the
+case recorded a context error, which is the finding for that launch (Gemma
+was launched with two 8k slots; Bonsai first ran with two 16k slots and
+failed 16k and 32k the same way, then with one 64k slot for the row above). No model that could read the state missed
+the decisive line at any position.
+
+These suites rank models; they do not measure calibration, which is why
+`jevify calibrate` refused to write a table for any of them.
+
+## Play Doom
+
+`tools/play_doom.py` lets a recipe play ViZDoom from screenshots: one frame
+per decision, one question per frame, the chosen button pressed, a video with
+the decision and its latency burned in. `tools/record_doom_suite.py` records
+the frozen perception suite the same way. Both need `uv sync --extra games`
+and ffmpeg.
+
+## Work with your agent
+
+jevify is written to be operated through a coding agent. Point yours at
+[`SKILL.md`](https://github.com/fidecastro/jevify/blob/main/SKILL.md): the workflow, recipe anatomy per kind, how to read
+`x_jevify`, and what a result may claim. Typical asks:
+
+- "Write a recipe for the model behind `http://host:8000/v1`, probe it, and
+  tell me which readout rung it landed on and why."
+- "Run `policy-hard-52` against this recipe with controls and read me the
+  scorecard against the claims contract."
+- "Serve this recipe and show me an unmodified typesafe-sdk call against it."
+
+## Repository map
+
+| Path | What it holds |
+|---|---|
+| [`jevify/`](https://github.com/fidecastro/jevify/blob/main/jevify) | The package: domain, ports, adapters (endpoint, embedding, encoder, rerank), recipes, evaluation, Jev API, CLI |
+| [`recipes/`](https://github.com/fidecastro/jevify/blob/main/recipes) | One recipe per model deployment, with its probe results and launch line |
+| [`suites/`](https://github.com/fidecastro/jevify/blob/main/suites) | Frozen, hashed suites and their manifests |
+| [`docs/evidence/`](https://github.com/fidecastro/jevify/blob/main/docs/evidence) | Committed scorecards, one per recipe and suite |
+| [`docs/00-invariants.md`](https://github.com/fidecastro/jevify/blob/main/docs/00-invariants.md) | What jevify is and refuses to be; the claims contract. Ranks above everything else |
+| [`docs/adr/`](https://github.com/fidecastro/jevify/blob/main/docs/adr/README.md) | The decision ledger |
+| [`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 |
+
+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
+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
+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.
+
+## Licence
+
+[MIT](https://github.com/fidecastro/jevify/blob/main/LICENSE).