README.md1# Chapter 16: jevcrates — one post office for four towns 2 3Four projects ask [Jev](https://docs.typesafe.ai) questions: postjevsql (a 4Postgres extension), jevsnes (Jev plays a SNES game), jevhooks (Jev judges 5Claude Code hooks) and lmjtfy (the site you may be reading this on). Jev is 6TypeSafe AI's "System One" model. It does not write text. It answers typed 7questions (`Noul`, `Choice`, `Score`) with calibrated probabilities. This 8repository is the one copy of the code that asks it, and every one of those 9projects uses it. 10 11Think of it as a post office shared by four towns. Each town used to run its 12own: its own idea of how to address an envelope, how long to wait for a 13reply, and when to give up and send it again. Now there is one post office, 14and the towns differ only in the road the mail van takes (a raw HTTP/2 15connection, a Postgres backend, or a Cloudflare Worker's `fetch`). 16 17> **Aside.** If you come from JavaScript: a *crate* is a package (one 18> `Cargo.toml`, the way an npm package has one `package.json`), and this 19> repository is a *Cargo workspace*, which is what pnpm or npm workspaces 20> are to a monorepo. A *trait* is close to a TypeScript `interface`. The 21> crates here are libraries only; nothing in this repository is a program you 22> run. 23 24## Use it in your own project 25 26You do not need a GitHub account, or to clone anything by hand. Cargo fetches 27the crates straight from the lmjtfy site, which serves this repository: 28 29```toml 30[dependencies] 31jev-protocol = { git = "https://lmjtfy.fun/jevcrates.git", rev = "46514413a1e73ad848fc2b1f106cca83eaf081f1" } 32jev-http = { git = "https://lmjtfy.fun/jevcrates.git", rev = "46514413a1e73ad848fc2b1f106cca83eaf081f1" } 33tokio = { version = "1", features = ["macros", "rt-multi-thread"] } 34``` 35 36Pick the crates by where your code runs (the table below has the detail): 37 38- **A native program** (a CLI, a server, a bot): `jev-protocol` and `jev-http`. 39- **A Cloudflare Worker**: `jev-protocol` and `jev-worker`. 40- **Anywhere else**, with your own way of sending a request (a database's 41 HTTP, a sandbox): `jev-protocol` and `jev-client`, and implement its two 42 ports. 43 44`rev` pins the commit, so a new commit here never changes your build until 45you move it. The front page at <https://lmjtfy.fun/jevcrates.git> 46shows these lines with the latest commit filled in. 47 48Then, with `TYPESAFE_API_KEY` set: 49 50```rust 51use jev_http::Jev; 52use jev_protocol::{Json, ModelId, Noul, Questions}; 53 54#[tokio::main] 55async fn main() -> Result<(), Box<dyn std::error::Error>> { 56 // TYPESAFE_API_KEY from the environment; None when it is not set. 57 let Some(jev) = Jev::from_env("usejev", ModelId::pinned("jev-1.13.0")?) else { 58 return Err("set TYPESAFE_API_KEY".into()); 59 }; 60 let jev = jev?; 61 let mut questions = Questions::new(); 62 let good = questions.noul("good", Noul::new(Json::text("Is this a good retirement plan?")))?; 63 let state = Json::text("Put it all on red at the casino."); 64 let answered = jev.ask(&state, &questions, "trying it out").await?; 65 println!("p(yes) = {:.2}", answered.response.get(good).noul); 66 Ok(()) 67} 68``` 69 70`jev-http` keeps a spend ledger under `$XDG_STATE_HOME/jev` that every 71program on the machine shares, and refuses a request before sending it when 72the shared limits say so (chapter 20). The third argument to `ask` is why the 73money was spent, and it is written into that ledger. 74 75## How the crates fit 76 77The crates are split along one line: whether they do I/O. The two at the 78bottom never touch a network, a file or a clock, so they compile anywhere, 79WebAssembly included. The ones above them supply the network for one kind of 80host. 81 82```mermaid 83flowchart BT 84 protocol["jev-protocol<br/>what to ask, what came back"] 85 client["jev-client<br/>retries, timeouts, redials"] 86 worker["jev-worker<br/>a Cloudflare Worker's fetch"] 87 http["jev-http<br/>HTTP/2 on tokio + spend ledger"] 88 mock["jev-mock<br/>a fake Jev for tests"] 89 client --> protocol 90 worker --> client 91 http --> client 92 http -. "tests only" .-> mock 93``` 94 95| Crate | What it does | I/O | 96| --- | --- | --- | 97| [jev-protocol/](jev-protocol/) | The questions and answers, the exact request bytes, response verification, error classification, the retry policy and the price. | none; builds for wasm | 98| [jev-client/](jev-client/) | Runs the retry policy: budgets, per-attempt timeouts, never-sent redials, request ids. Reaches the world through two ports, `Transport` and `Runtime`. | none | 99| [jev-worker/](jev-worker/) | The two ports for a Cloudflare Worker (wasm32, workers-rs). No ledger. | network | 100| [jev-http/](jev-http/) | The two ports for a native process (HTTP/2 over pure-Rust TLS on tokio), and `Jev`, which has an on-disk spend ledger admit every request. | network, files | 101| [jev-mock/](jev-mock/) | A local HTTP/2 TLS stand-in for the endpoint, with fixture replay and recording. | loopback | 102 103Who uses what: postjevsql uses `jev-protocol`, `jev-client` and `jev-mock`, 104with its own Postgres transport. jevsnes and jevhooks use `jev-http`. lmjtfy's 105Worker uses `jev-worker`, and its `tools/eval` uses `jev-http`. 106 107> **Aside.** The crates moved here on 2026-10-01 from postjevsql 108> (`jev-protocol`, `jev-client`, `jev-mock`) and jevsnes (`jev`, `jev-http`), 109> with their git history, and the two protocol layers (`jev` and 110> `jev-protocol`) were merged into one. 111 112## Try it 113 114``` 115cargo test --workspace 116``` 117 118Every test runs offline. The ones that need a server start `jev-mock` on 119loopback; the retry tests run on a virtual clock and finish instantly. 120 121The chapters follow the stack from the bottom up: start with 122[jev-protocol](jev-protocol/), the vocabulary every other crate speaks. 123 124## For the people who maintain it 125 126### In this folder 127 128| Path | What | 129| --- | --- | 130| [jev-protocol/](jev-protocol/) | Chapter 17: the wire protocol, no I/O. | 131| [jev-client/](jev-client/) | Chapter 18: the retry policy, behind two ports. | 132| [jev-worker/](jev-worker/) | Chapter 19: the ports on a Cloudflare Worker. | 133| [jev-http/](jev-http/) | Chapter 20: the ports on tokio, and the spend ledger. | 134| [jev-mock/](jev-mock/) | Chapter 21: the fake endpoint for tests. | 135| [Cargo.toml](Cargo.toml) | The workspace: its members, and every dependency's version, declared once and inherited by the crates. | 136| [CLAUDE.md](CLAUDE.md) | What an agent working here must not break. | 137| [.gitignore](.gitignore) | Ignores `target/`, Cargo's build output. | 138 139All five crates are version `0.0.1`, edition 2024, `publish = false`, and 140licensed MIT OR Apache-2.0. 141 142← Previous: lmjtfy's third-party/ chapter · Next: [Chapter 17: jev-protocol](jev-protocol/) →