jevfilter

Judge content against plain-English definitions with TypeSafe's Jev. Describe what you care about in a few words; get back typed answers with calibrated probabilities: which topics match, which category, which company, how urgent.

jevfilter is stateless: no storage, no cache and no network except Jev. You get plain results back and store them however you like.

Pre-alpha. The API may change before 1.0.

Install

pip install "jevfilter[yaml]"
export TYPESAFE_API_KEY=...

On PyPI: https://pypi.org/project/jevfilter/

Python 3.10+. You can also set the key in code with jf.configure(api_key=..., model="jev-1.13.0"). jevfilter never reads .env files, so load one yourself if you use it.

Quick start

import jevfilter as jf

jf.choose("I was charged twice", ["billing", "bug", "feature request"])
# Choice(value='billing', confidence=0.96, ...)

jf.check("Can you send the form by Friday?", {"needs_reply": "The sender wants a reply"})
# {'needs_reply': 0.98}

jf.rate("The site is down for everyone", "severity", ["cosmetic", "degraded", "blocking"])
# Score(value=2.0, level='blocking', ...)

Topics

A topic only needs a name and a description. Categories, fields, scores and flags are optional.

# topics/jobs.yaml
name: Jobs
description: Applications I submitted, and recruiters contacting me about a role.
exclude: Job alerts, digests, newsletters.
categories:
  applied: Confirms I submitted an application.
  interview: Invites me to an interview.
  rejection: Tells me I'm not moving forward.
fields:
  company: {about: The hiring company, required: true}
flags:
  needs_reply: The sender is asking me to reply.

f = jf.Filter(jf.Topic.load("topics/"))

email = {"from": "...", "subject": "...", "body": "..."}
r = f.judge(jf.Content(email, candidates={"Jobs": {"company": ["Acme", "Initech"]}}))

for t in r.matches:
    print(t.topic, t.p, t.category.value, t.fields["company"].value, t.flags)
for t in r.review:            # uncertain: let a person decide
    print(t.topic, t.reasons)

r.cost_usd                    # every result reports its cost
db.save(r.to_dict())          # plain JSON; restore with jf.Result.from_dict

Each topic comes back as match, review or no. All questions for one piece of content go to Jev in a single request. Field values are picked from the candidates you pass in, never generated. f.explain(email) shows the exact request and its estimated cost without sending it.

If most of your content matches no topic, jf.Filter(topics, speculative=False) asks membership first and the rest only for topics that might match: a second round trip, but about 30% fewer tokens in our tests.

Tracked items and batches

# Which of your tracked items is this email about? (you store the items)
m = f.match_item(email, "Jobs", my_jobs, result=r["Jobs"])
m.item_id                     # an id from my_jobs, or None for a new one

jf.track.next_status(topics["Jobs"], "applied", "interview")   # "interviewing"

# Many emails at once, with a spend cap that refuses instead of overspending
af = jf.AsyncFilter(topics, budget=jf.Budget(usd=0.50, per_minute=120))
results = await af.judge_many(emails, concurrency=8)

See docs/topic-format.md for every topic option (scores, composites, when, thresholds, meta) and docs/api.md for the rest of the API.

Command line

jevfilter try topics/ "Your application to Acme was received"
jevfilter explain topics/ --file email.json    # requests + cost, sends nothing
jevfilter lint topics/
jevfilter eval topics/ labelled.jsonl --sweep --record runs/cassette.jsonl

eval scores your topics against labelled examples (precision, recall, review rate, calibration) and shows which thresholds trade off best.

Testing without an API key

from jevfilter.judges import FakeJudge

fake = FakeJudge({"Jobs/membership": 0.95, "Jobs/categories": "applied"})
r = jf.Filter(topics, judge=fake).judge("...")

Or record real answers once and replay them: RecordingJudge / ReplayJudge in jevfilter.judges.

Development

uv sync
uv run pytest                                   # unit tests, no network
JEVFILTER_LIVE=1 uv run pytest tests/live -s    # real Jev, prints spend
uv run ruff check . && uv run ruff format .

License

MIT