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), or jevbrief[web]
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

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.

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: 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.

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. Details: web · json · otel. 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.