Skip to main content

jevfilter

CI PyPI

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, per topic. Add --holdout 0.3 to check them on examples they weren't tuned on.

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

Metadata

Release files for jevfilter 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jevfilter 0.5.0
File Size Uploaded Provenance Actions
jevfilter-0.5.0.tar.gz 114.6 kB Without provenance Details for jevfilter-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jevfilter 0.5.0
File Interpreter ABI Platform Actions
jevfilter-0.5.0-py3-none-any.whl Python 3 none any Details for jevfilter-0.5.0-py3-none-any.whl

Total release size: 167.6 kB

Release files / jevfilter-0.5.0.tar.gz

Download URL jevfilter-0.5.0.tar.gz
Size 114.6 kB
Tags Source
SHA-256 checksum
How to use checksums
24cdf115a2b61850b84873ec056ba65e7e5878a17eda4f596bec13bd127f8b63
BLAKE2b-256 checksum
How to use checksums
344af747462610d97771e0da689edb0a22c3d4d6ff645dcd138b8e082252633b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / jevfilter-0.5.0-py3-none-any.whl

Download URL jevfilter-0.5.0-py3-none-any.whl
Size 53.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2373f97624de29881e2fc47d0e4a56dfbd247b1140c76bb2704f2eb6fe57b031
BLAKE2b-256 checksum
How to use checksums
1bfbbe1d3c9b19d520d32d172a7feeb5b326f35702c58209d975004eaa854ffc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for jevfilter 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page