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 failed build prints thousands of log lines, and an incident produces thousands more.

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.

Quick start

pip install jevbrief                  # json, otel, and ci; add [web] or [nes], or [all] for everything

Get an API key at console.typesafe.ai, and set TYPESAFE_API_KEY in your environment or in a .env file where you run the CLI.

Every adapter uses the same two commands. inspect shows what would be kept and dropped, with no API key and no cost. ask calls Jev, writes a trace, and --view opens the replay.

gh run view <run id> --log-failed > run.log
jevbrief inspect run.log --adapter ci --goal "CI is red on main"
jevbrief ask     run.log --adapter ci --goal "CI is red on main" --view

27 log lines -> 7 failures -> 3 sent to Jev
likely cause: Run pytest -q: E KeyError: 'currency_code'   (confidence 0.84)
looks flaky: no (0.07)

Run jevbrief adapters to list what is installed. Each adapter's page below has its own quick start.

Adapters

Watch Jev play a game

Every frame is a real Jev decision. The nes adapter 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. Play it yourself with python examples/nes_live.py --rom nova.nes --headed. The nes page covers getting the free game, the options, and adding another game.

Use it in Python

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

from jevbrief import Briefing
from jevbrief.adapters.ci import CiAdapter

brief = Briefing(CiAdapter(), goal="CI is red on main", trace="traces/ci.jsonl")
brief.extract(["logs.zip", "reports/junit.xml"])
decision = brief.decide()
if decision.fact:
    print("likely cause:", decision.fact.label, decision.fact.attrs)

Every decision comes back in the same shape:

Extra questions in the same call, such as ci's flaky, are in decision.answers.

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()

More in examples/: one script per adapter.

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 picks the view that fits its source:

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 setup for both arms: the same Jev (jev-1.13.0) and the same question, with three runs per task and median input tokens. The raw arm sends what a naive integration would send: every element, every record, or the most recent log lines.
• ci's flaky question: here jevbrief scored lower, 67% against 93%. The raw arm answered "flaky" every time, and 13 of the 16 labels are flaky.
• Synthetic sets: some rules were designed while building them, so treat those numbers as illustrations.

Each adapter name links to its full results and caveats. Reproduce them with jevbrief bench.

Contributing

An adapter is one class with extract, rules, packs, and optionally state. Adding one never changes the core, and removing one never breaks anything. Working with a coding agent? Copy skills/jevbrief/SKILL.md into its skills folder (for Claude Code, .claude/skills/jevbrief/SKILL.md).

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

• API key: read from the environment or .env, and never printed, logged, or written to a trace.
• What adapters send:
  • The web adapter never sends form values.
  • The json adapter sends only the configured fields and buckets.
  • The otel and ci adapters send message templates, with IDs, emails, and addresses replaced.
• Traces: they 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.