Why jevbrief

Jev turns state into typed decisions. It does its best work on small, relevant state, and it is weak at raw numbers, dates, and long lists of irrelevant detail. Real sources are the opposite: a web page has hundreds of elements, a ticket queue is full of closed and spam tickets, and an incident produces thousands of log lines.

jevbrief sits between your source and Jev. It keeps what matters, drops the rest with a reason for every drop, asks Jev one clear question, and records the whole decision so you can replay it.

Adapters

Quick start

pip install "jevbrief[all]"       # everything; or jevbrief (json and otel), jevbrief[web], or jevbrief[nes]
playwright install chromium       # only for web pages

inspect shows what would be kept and dropped, with no API key and no cost. ask calls Jev and writes a trace. --view opens the animated replay.

jevbrief ask logs.json --adapter otel --goal "Checkout requests started failing with 500 errors" --view

1447 log records -> 23 groups -> 5 sent to Jev
likely cause: auth: failed to load token signing key: certificate expired   (confidence 1.00)

jevbrief ask tickets.json --adapter json --config tickets.toml --goal "a customer was billed twice" --view

python examples/nes_live.py --rom nova.nes --headed

jevbrief ask https://news.ycombinator.com --goal "log in" --view

Get an API key at console.typesafe.ai. Set TYPESAFE_API_KEY in your environment, or put TYPESAFE_API_KEY=... in a .env file where you run the CLI. Run jevbrief adapters to list what is installed.

Watch Jev play a game

Every frame is a real Jev decision. jevbrief reads the game's memory, turns it into a few facts in words (Wall ahead, low (one block), touching), and asks Jev for one move, plus whether walking right is dangerous, in the same call. The game is paused while Jev answers.

On level 1-1, the facts got Nova to block 56 in 100 moves at 713 input tokens per call. Raw memory got her to block 8.6 at 2,829 tokens (results).

Try it yourself

You need Python 3.10 or newer, a TypeSafe API key, and about five minutes.

1. Get jevbrief with the example

git clone https://github.com/parthkomalwad/jevbrief && cd jevbrief
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[nes]"

2. Get the game. Download nova.nes (free) from the author's v1.0.6a release. Nova the Squirrel is an open-source NES platformer by NovaSquirrel: GPL-3.0 code, CC BY-NC-SA 4.0 graphics and levels. jevbrief never ships or downloads ROMs, and commercial games such as Super Mario Bros are not supported.

3. Add your key. Put TYPESAFE_API_KEY=... in a .env file in the jevbrief folder. Get one at console.typesafe.ai.

4. Play

python examples/nes_live.py --rom path/to/nova.nes --headed

Your browser opens the live viewer at http://127.0.0.1:8765/:

• Bottom right: the game, as it plays.
• Left: one row per decision, colored by Jev's confidence.
• Middle: what Jev was told, what was dropped and why, the frame with boxes, and how sure Jev was of each move.

The terminal prints one line per decision, such as jump_right 0.89 -> jump_right x=7.3 health=4. Replay a run later with jevbrief view traces/nes.jsonl.

Add another NES game: skills/jevbrief-nes-game/SKILL.md is a step-by-step guide, for you or a coding agent such as Claude Code, from a legal ROM to a tested adapter. It includes ram_search.py, which finds a game's memory addresses by watching which bytes change.

Use it in Python

Every adapter works the same way: create a Briefing, extract, decide.

from jevbrief import Briefing
from jevbrief.adapters.otel import OtelAdapter

brief = Briefing(OtelAdapter(), goal="Checkout requests started failing with 500 errors", trace="traces/incident.jsonl")
brief.extract("logs.json")
decision = brief.decide()
if decision.fact:
    print("likely cause:", decision.fact.label, decision.fact.attrs)

from jevbrief import Brief

brief = Brief(goal="add this item to the cart", trace="traces/agent.jsonl")
await brief.from_page(page)                 # or brief.from_page_sync(page)
decision = brief.next_click()
if decision.fact:
    await page.locator(decision.fact.selector).click()

Every decision comes back in the same shape:

Examples: nes_live.py · otel_incident.py · json_triage.py · click_agent.py

See every decision

jevbrief ask ... --view opens the viewer after a run, and jevbrief view opens the newest trace. Each decision starts with an animated replay: every fact read, the dropped ones struck out with their reason, the ones sent to Jev, Jev's answer, and a plain-English summary of what it means.

Each adapter chooses the view that fits its source.

Live, for games: jevbrief view --live traces/nes.jsonl serves the same viewer on 127.0.0.1, adds each decision as it is written, and shows the running game in a corner panel. See the game demo.

The viewer is a single HTML file with the trace and images embedded. It needs no server and no network, so it can be attached to a bug report.

How it works

Benchmarks

Same Jev (jev-1.13.0), same question, three runs per task, median input tokens. The raw arm sends what a naive integration would send: every element, every record, or the most recent log lines. The data is synthetic and built to resemble real sources, and some rules were designed while building these sets, so treat the numbers as illustrations rather than general results. For nes, accuracy is how far Nova got in 100 moves (median of 3 runs, level map 256 blocks); neither arm finished the level. Details: web · json · otel · nes. Reproduce them with jevbrief bench.

Build your own adapter

An adapter is one class with extract, rules, packs, and optionally state. Adding one never changes the core, and removing one never breaks anything.

1. Copy contrib/adapter_template and its test.
2. Follow ADAPTERS.md for facts, rules, the question pack, and the benchmark.
3. Pass the shared contract test: check_adapter(MyAdapter(), "sample.json", goal="...").
4. Ship it here in a pull request, or as your own package with a jevbrief.adapters entry point, which jevbrief discovers automatically.

Working with a coding agent? Copy skills/jevbrief/SKILL.md into its skills folder (for Claude Code, .claude/skills/jevbrief/SKILL.md).

Contributing

git clone https://github.com/parthkomalwad/jevbrief && cd jevbrief
python -m venv .venv && . .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]" && playwright install chromium
pytest -q

Privacy

• The API key is read from the environment or .env and is never printed, logged, or written to a trace.
• Adapters send only what they list. The web adapter never sends form values, the json adapter sends only the configured fields and buckets, and the otel adapter sends message templates with IDs, emails, and addresses replaced.
• Traces contain labels, source names, and, for web pages, a screenshot. Treat them like logs, and use --no-screenshot for private pages.

License

MIT. Community project, not affiliated with TypeSafe AI.