Mastering TypeSafe Jev

A practical guide to bounded AI decisions with TypeSafe hosted Jev and self-hosted Kev.

Clone the book source code repository at https://github.com/udooz/mastering-jev-and-kev-book.git

Code computes. LLMs create. Jev decides. Fresh state proves the result.

What problem does this book solve?

Look inside almost any production application and you will find dozens of tiny judgments hiding in the code:

• Is this support ticket a fraud report or a billing question?
• Should this order go to the warehouse or to a human reviewer?
• Is this motor vibration normal, or should a technician look at it?

Teams usually solve these in one of two ways, and both hurt.

Way 1: a pile of if statements. It is fast and predictable, but it only handles what you thought of in advance. A customer writes “someone drained my account while I slept” and none of your keyword rules fire.

Way 2: ask a chat LLM. It understands the sentence, but it answers in free-form prose, takes seconds, costs real money per call, and may give a different answer tomorrow. Now you need a second program to parse the prose, and a third to check the parser.

⚠️ Watch Out A chat LLM is built to write. A routing decision needs to pick one option from a list, quickly, the same way every time. Using a writer to pick from a list is like hiring a novelist to press the elevator button.

This book teaches a third way: a System One decision model. You give it a piece of evidence and a short list of questions, and it returns a typed answer in milliseconds, such as “fraud: 0.93, urgency: 4, send to: secops_agent”. Your code then decides what to do with that answer.

💡 Mental Model: the smart if A System One model is an if statement that can read English (or sensor data). You still write the surrounding logic. The model only replaces the one line you could never write by hand: “if this sounds like fraud…”

The model family in this book comes in two flavours:

• Jev is a hosted decision API from TypeSafe.
• Kev is an open-source decision model you run on your own machine.

Both speak the same typed contract, so almost all the code you write works with either one.

How the book teaches

The design principle throughout the book is simple: code computes, models judge, people authorise consequential actions, and fresh observations verify results. Generative LLMs remain useful when the system needs writing, planning, or open-ended reasoning.

Every chapter follows the same rhythm:

1. The problem, and why the obvious approach fails.
2. One new idea at a time, with a code snippet.
3. A link to the complete source file, so you can run it and read it in full.
4. A mini-project and one more layer of a production-shaped system.

The book builds two capstones on one shared decision client:

Two appendices explain why a System One model beats a regular LLM for decisions (and how Jev works inside), and summarise both capstones’ use cases for readers who won’t read the code.

The third appendix provides overview of THX-01 model.

At a glance: 14 chapters (this introduction + 13 technical chapters) + 3 appendices · 2 installable packages · 48 automated tests (+1 live eval) · 12 runnable mini-projects across both parts, with 10-minute hands-on walk-throughs in Chapters 11–14.

The two capstones

Both capstones follow the same pattern: the model answers a few small questions, and ordinary code decides what to do next.

Capstone 1: Autonomous Incident & FinTech Triage Engine (Part I)

The story: a bank receives thousands of support and fraud reports a day. Each one must go to the right team, with the right urgency, without ever letting a prompt-injection attack move money.

Capstone 2: SmartPlant Decision Intelligence (Part II)

The story: a factory has hundreds of motors streaming vibration, temperature and current. Operators need a recommended action for each one, but the safety system (the PLC) must always stay in charge.

Appendix B has the actors, use cases, conceptual models and end-to-end journeys for both.

Contents

Part I: FinTech triage on cloud hosted Jev

Part II: SmartPlant on self-hosted Kev

Same DecisionClient, same circuit breaker, a new domain, and a decision model you host yourself.

Appendices

Suggested reading paths

What machine do I need?

Part I (Chapter 2 to 9) does not require GPU machines. You can run on a standard computer.

Part II needs GPU machine for Kev.

You can go with pay-per-use Cloud GPU Pod machine from https://www.runpod.io/. RTX 4090 Pod with 100GB Network storage disk is best option.

Setup

Step 1: understand the workspace

The repo is a uv workspace. Both capstones, capstone-project/src/triage (Part I) and smartplant-capstone/src/smartplant (Part II), are installed as editable packages into one shared .venv. The payoff is that every mini-project can import shared code with a plain import:

from triage.jev_client import client_from_env          # no sys.path.append(...) anywhere
from smartplant.decision_service import SmartPlantDecisionService

💡 Mental Model: one lab, many experiments Think of the workspace as a single lab bench. The two capstones are the shared equipment. Each mini-project is an experiment that borrows the equipment, so you never copy code between folders and never fiddle with sys.path.

Step 2: install and sync

# 1. Install uv (once)
curl -LsSf https://astral.sh/uv/install.sh | sh          # macOS / Linux
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows

# 2. From the repo root: one venv, triage + smartplant installed editable
uv python install 3.12                                   # SDK needs Python 3.10+
uv sync                                                  # creates .venv + uv.lock (dev group included)
uv sync --group adapter --group ch7                      # add groups per chapter as you need them

• uv python install 3.12 makes sure a suitable Python exists (the SDK needs 3.10+).
• uv sync builds .venv and uv.lock in one go. Extra dependency groups (adapter, ch7, …) are opt-in per chapter.

Step 3: tell the code which decision backend to use

# 3. Configure the decision backend (Part I: hosted Jev)
export TYPESAFE_API_KEY=your_key                         # never commit this
export JEV_MODEL=jev-1.13.0                              # pin the version you calibrate against

⚠️ Watch Out Never commit TYPESAFE_API_KEY. Pinning JEV_MODEL matters for the same reason as pinning a library version: the thresholds you calibrate in Chapter 6 are only valid for the model you calibrated them against.

Step 4: run things

You can run these from the repo root or from inside any mini-project folder:

# 4. Run things (from the root or from inside any mini-project folder)
uv run pytest -q                                         # 48 passed, 1 skipped (Part I live eval)
uv run pytest -q capstone-project                        # Part I only: 17 passed, 1 skipped
uv run pytest -q smartplant-capstone                     # Part II only: 26 passed

RUN_LIVE_EVALS=1 uv run pytest capstone-project/tests/test_labeled_evals.py -s   # replay labeled set against Jev
uv run python -m triage.probes                           # Appendix A: probe your backend's behaviour
uv run python mini-projects/07-multi-engine-benchmark/multi_engine_eval.py --engines offline   # Ch7; add jev,kev,openai-decisions

The two test counts are the book’s health check: Part I contributes 17 tests (+1 skipped live eval), Part II contributes 26.

Step 5 (Part II only): run Kev locally

Kev needs Python 3.12/3.13 and torch, so clone it outside this workspace and give it its own venv:

git clone https://github.com/jaredpalmer/kev.git ~/src/kev && cd ~/src/kev
uv sync --extra serve
uv run --extra serve python -m kev.serve --run jaredpalmer/kev-0.8b --port 8009   # kev-4b for accuracy work

Then point this repo at your local Kev server and try the Part II mini-projects:

# back in this repo
export DECISION_BACKEND=kev KEV_BASE_URL=http://127.0.0.1:8009   # + KEV_API_KEY if the server sets one
uv run python mini-projects/08-iot-sensor-simulator/run_simulator.py --fault gradual_degradation
uv run python mini-projects/08-iot-sensor-simulator/kev_console.py snapshots.jsonl            # Kev's decision per snapshot

uv run python mini-projects/09-smartplant-decision-service/run_decision_service.py S06 S07
uv run python mini-projects/10-closed-loop-controller/run_controller.py --kev-down-at 120
uv run python mini-projects/11-smartplant-eval-suite/run_eval.py --kev      # add --llm for the 3-way benchmark
DECISION_BACKEND=kev uv run python -m triage.probes                         # Appendix A probes against Kev
# no Kev box yet? add --offline (mini-projects 09/10) or drop --kev (11) to use the scripted stand-in

No Kev box yet? Add --offline (mini-projects 09/10) or drop --kev (11) to use the scripted stand-in.

Environment variables at a glance

Edits to capstone-project/src/triage/*.py or smartplant-capstone/src/smartplant/*.py show up everywhere immediately, with no reinstall. Commit uv.lock so everyone resolves the same SDK version.

Repository layout

Read this tree once, then use it as a map. Every file in src/ is introduced in exactly one chapter.

mastering-jev-guide/
├── pyproject.toml                # uv workspace root: depends on triage-engine + smartplant (editable)
├── uv.lock                       # commit this
├── .venv/                        # one shared environment (git-ignored)
├── capstone-project/             # workspace member -> installable package "triage-engine"
│   ├── pyproject.toml            # hatchling build, packages = ["src/triage"]
│   ├── src/triage/
│   │   ├── jev_client.py         # Ch2 (+ KevDecisionClient, Ch10)
│   │   ├── contract.py           # Ch3
│   │   ├── state_builder.py      # Ch4
│   │   ├── policy_engine.py      # Ch5
│   │   ├── trace.py              # Ch5
│   │   ├── resilience.py         # Ch6
│   │   ├── executors.py          # Ch7
│   │   ├── verifier.py           # Ch7
│   │   ├── tool_guard.py         # Ch7
│   │   ├── cascade.py            # Ch8
│   │   ├── engine.py, wiring.py, fakes.py, service.py   # Ch9
│   │   └── probes.py             # Appendix A (python -m triage.probes)
│   ├── tests/                    # labeled_cases.jsonl + 6 test modules (17 tests + 1 live)
│   └── tools/sweep_threshold.py  # Ch5
├── smartplant-capstone/          # workspace member -> installable package "smartplant"
│   ├── pyproject.toml            # depends on triage-engine; console scripts smartplant-sim/-eval/-export
│   ├── src/smartplant/
│   │   ├── sensor_simulator.py  fault_injector.py  edge_state_builder.py       # Ch10
│   │   ├── contract.py  context_enricher.py  models.py  decision_service.py    # Ch11
│   │   ├── fallback_rules.py  cmms_mock_service.py  audit_log.py               # Ch12
│   │   ├── action_orchestrator.py                                              # Ch12
│   │   ├── scenario_runner.py  benchmark_metrics.py  eval_dashboard.py         # Ch13
│   │   ├── training_export.py                                                  # Ch14
│   │   └── data/test_scenarios.json  # packaged, so mini-projects 09 and 11 share it with no paths
│   └── tests/                    # 26 tests; Kev integration tested against a mock server
└── mini-projects/
    ├── 01-starter-client/ … 07-multi-engine-benchmark/   # Part I: code is in Ch2–8; create as you follow along
    ├── 08-iot-sensor-simulator/run_simulator.py  kev_console.py   # kev_console: replay snapshots through Kev
    ├── 09-smartplant-decision-service/run_decision_service.py
    ├── 10-closed-loop-controller/run_controller.py
    └── 11-smartplant-eval-suite/run_eval.py
    └── 12-learning-loop/record_outcomes.py                    # Ch14: technician outcomes -> training data

Part I’s mini-projects (01–07) are listed in full inside their chapters, which tell you which file each listing belongs in. Part II’s mini-projects ship as runnable entry points. Their “key files” (sensor_simulator.py, fallback_rules.py, scenario_runner.py, …) live in the smartplant package, because later mini-projects import earlier ones.

Two rules keep imports clean:

• Shared code lives in a package (triage, smartplant) and is imported as from triage... import ....
• Mini-project-local modules (e.g. triage_schema.py, queue_manager.py) are imported by plain name. Python puts the running script’s folder on sys.path, so uv run python mini-projects/02-support-triage/evaluator.py finds triage_schema without any configuration. Give them names that don’t collide with triage, smartplant or the standard library.

The workspace files

You do not need to memorise these. They are here so you can see how the pieces connect.

Root pyproject.toml: declares the workspace.

📄 Full source: pyproject.toml

[project]
name = "mastering-jev-guide"
version = "1.0.0"
description = "Mastering Jev: book workspace (chapters, mini-projects, two capstones)"
requires-python = ">=3.10"
dependencies = [
    "triage-engine",                      # Part I:  `import triage` everywhere
    "smartplant",                         # Part II: `import smartplant` everywhere
]

The root depends on both capstone packages. Next, the optional dependency groups. Each chapter that needs extra libraries has its own group:

[dependency-groups]
dev = ["pytest>=8"]
adapter = ["system-one-adapter[openai]"]          # Ch1: build before you have a Jev key
ch3 = []                                          # uses typesafe-sdk async client only
ch6 = []                                          # pure-Python BM25
ch7 = ["openai>=3.26", "matplotlib", "scikit-learn"]  # Decisions API client, plot, classical baseline
service = ["fastapi", "uvicorn"]                  # Ch8 HTTP entry point
iot = ["paho-mqtt>=2"]                            # Part II: optional MQTT publish/subscribe

Finally, tell uv this is a workspace and where its members live:

[tool.uv]
package = false                                   # the root is a workspace, not a library
default-groups = ["dev"]

[tool.uv.workspace]
members = ["capstone-project", "smartplant-capstone"]

[tool.uv.sources]
triage-engine = { workspace = true }              # editable install of capstone-project/src/triage
smartplant = { workspace = true }                 # editable install of smartplant-capstone/src/smartplant

capstone-project/pyproject.toml: the Part I package.

📄 Full source: capstone-project/pyproject.toml

[project]
name = "triage-engine"
version = "1.0.0"
description = "Autonomous Incident & FinTech Triage Engine (Mastering Jev capstone)"
requires-python = ">=3.10"
dependencies = ["typesafe-sdk"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/triage"]

[tool.pytest.ini_options]
testpaths = ["tests"]

smartplant-capstone/pyproject.toml: the Part II package. It depends on triage-engine, so smartplant can reuse the Part I client and circuit breaker.

📄 Full source: smartplant-capstone/pyproject.toml

[project]
name = "smartplant"
version = "1.0.0"
description = "SmartPlant Industrial IoT decision intelligence on open-source Kev (Mastering Jev, Part II capstone)"
requires-python = ">=3.10"
dependencies = ["triage-engine"]       # reuses triage.jev_client + triage.resilience

[project.scripts]
smartplant-sim = "smartplant.sensor_simulator:main"
smartplant-eval = "smartplant.scenario_runner:main"
smartplant-export = "smartplant.training_export:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/smartplant"]

[tool.uv.sources]
triage-engine = { workspace = true }

[tool.pytest.ini_options]
testpaths = ["tests"]

💡 Mental Model: why a workspace? The packages are installed once, in editable mode, from a single lock file. IDEs (VS Code, PyCharm) resolve triage and smartplant through the selected .venv interpreter, so autocomplete and type checking work in every mini-project too.

Sources and a note on numbers

TypeSafe Jev engineering, theory, concepts, prices, latencies and benchmark figures come from:

• TypeSafe’s published material and docs
• Flavio Copes, A Deep Dive into Jev (Sep 2026)
• @0xCodila, Jev Engineering playbook (Sep 2026)
• the jaredpalmer/kev README (Oct 2026, Part II)
• OpenAI Decisions API beta docs and independent write-ups (Oct 2026, Chapter 8)
• Archer Hume, Jev’s Architecture Unmasked (17 Sep 2026, Appendix A), a black-box study whose architectural claims are inferences, labelled as such
• the deepanwadhwa/OpenDecision README and the Decision Systems Architecture: OpenDecision, Jev, Kev brief (Appendix A)

⚠️ Watch Out Vendors report their best cases, and Kev is a young, fast-moving project, so check its README before relying on model names or flags. The OpenAI Decisions API is in public beta, so re-check its schema and prices at GA. Every chapter includes a harness so you can measure on your own traffic, and your own measurements are the only numbers to put in a design doc.

Terms used in the examples

Contact Me

SHEIK UDUMAN ALI

• For questions and queries, please use this book source code repository GitHub Discussions https://github.com/udooz/mastering-jev-and-kev-book/discussions/
• LinkedIn https://www.linkedin.com/in/sheik-uduman-ali/

Publication Version 1.0 (Oct 11, 2026)

Copyright © 2026 [Sheik Uduman Ali]. All rights reserved.

The book. The text, diagrams, illustrations and cover of Mastering TypeSafe Jev are protected by copyright. You may not reproduce, distribute, translate or adapt any part of the book in any form, including print, PDF, e-book, audio, video, slides or AI training datasets, without written permission from the author. Short quotations for reviews, articles or teaching are welcome with attribution.

The source code. All source code in this book and its companion repository (capstone-project/, smartplant-capstone/, mini-projects/ and code listings in the chapters) is released under the MIT License. You’re free to use, copy, modify and distribute it, including in commercial projects. Attribution is appreciated but not required beyond keeping the licence notice in copies of the code.

Trademarks. TypeSafe, Jev, Kev, OpenAI and other product names, articles belong to their respective owners and are used here only to identify those products. This book isn’t affiliated with or endorsed by any of them.

No warranty. The code and techniques are provided “as is”, without warranty of any kind. Test them thoroughly before using them in production, and never let a decision model override safety systems.