jevfilter 0.1.0__tar.gz

jevfilter-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+.env
+.coverage
+htmlcov/

jevfilter-0.1.0/CLAUDE.md

@@ -0,0 +1,47 @@
+# jevfilter
+
+Open-source (MIT) Python library for checking a message against
+plain-English **topics** with TypeSafe's **Jev**: membership, category,
+field selection from candidates, item matching, tracking rules,
+thresholds, budget and failure policy. Stateless — no storage, cache,
+hooks, sources or UI; callers persist the plain results. Published to
+PyPI as `jevfilter`. First consumer: `jev-gmail-filter`, a Gmail app.
+
+## Context
+
+- **Model:** Jev via `typesafe-sdk` (`client.system_one`). Typed answers
+  with calibrated probabilities; input tokens billed ($0.042/Mtok), output
+  free.
+- **Docs:** <https://docs.typesafe.ai> — append `.md` to any page path for
+  its Markdown source.
+- Pattern origin: <https://github.com/damiensmith1/semantic-pubsub-jev> (Go).
+- Project docs: everything under `docs/` — background, requirements,
+  design, `topic-format.md` (language-neutral definition schema),
+  `api.md` (usage by example; see design.md "Status" for what's built).
+- Goals: **easy** (three-line start), **extensible** (every part a small
+  protocol), **powerful** (fan-out, hierarchies, scores, items, eval).
+
+## Conventions
+
+- Python ≥ 3.10 (matches `typesafe-sdk`), src layout, typed public API.
+- Tooling: `uv sync`, `uv run pytest`, `uv run ruff check . && uv run ruff format .`.
+  Check the floor with `uv run --python 3.10 --isolated --with pytest --with pyyaml pytest`.
+- Keep it stateless and source-agnostic. Nothing Gmail-specific here.
+- `TYPESAFE_API_KEY` lives in `.env` (gitignored). Never log or commit it.
+- Tests stub Jev. Live tests are opt-in and never run in CI.
+- Commits are atomic and explain *why*. No co-author trailers.
+
+## Keeping docs in sync
+
+Everything under docs/ is this project's source of truth, not a one-time
+snapshot — including any file added there after initial setup, not just
+background.md/requirements.md/design.md. In the SAME turn as a code
+change (not a followup), update the relevant doc when you:
+- resolve or add an open question in design.md
+- make or change an architecture/approach decision
+- add, change, or drop a requirement or non-goal
+- learn something that changes the "why" in background.md
+- create a new doc under docs/ for a topic that doesn't fit the above
+
+Don't fabricate a decision that wasn't actually made. If it's unclear
+whether something is doc-worthy, ask instead of guessing.

jevfilter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damien Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jevfilter-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: jevfilter
+Version: 0.1.0
+Summary: Judge content against plain-English topic definitions with TypeSafe's Jev.
+Project-URL: Repository, https://github.com/damiensmith1/jevfilter
+Author: Damien Smith
+License-Expression: MIT
+License-File: LICENSE
+Keywords: classification,filter,jev,llm,typesafe
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typesafe-sdk<0.8,>=0.7.1
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# jevfilter
+
+[![CI](https://github.com/damiensmith1/jevfilter/actions/workflows/ci.yml/badge.svg)](https://github.com/damiensmith1/jevfilter/actions/workflows/ci.yml)
+
+Judge content against plain-English definitions with TypeSafe's
+[Jev](https://docs.typesafe.ai). 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
+
+```sh
+pip install "jevfilter[yaml]"
+export TYPESAFE_API_KEY=...
+```
+
+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
+
+```python
+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.
+
+```yaml
+# 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.
+```
+
+```python
+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.
+
+See [docs/topic-format.md](docs/topic-format.md) for every topic option
+(scores, composites, `when`, thresholds, `meta`) and [docs/api.md](docs/api.md)
+for the rest of the API.
+
+## Testing without an API key
+
+```python
+from jevfilter.judges import FakeJudge
+
+fake = FakeJudge({"Jobs/membership": 0.95, "Jobs/categories": "applied"})
+r = jf.Filter(topics, judge=fake).judge("...")
+```
+
+## Development
+
+```sh
+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

jevfilter-0.1.0/README.md

@@ -0,0 +1,105 @@
+# jevfilter
+
+[![CI](https://github.com/damiensmith1/jevfilter/actions/workflows/ci.yml/badge.svg)](https://github.com/damiensmith1/jevfilter/actions/workflows/ci.yml)
+
+Judge content against plain-English definitions with TypeSafe's
+[Jev](https://docs.typesafe.ai). 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
+
+```sh
+pip install "jevfilter[yaml]"
+export TYPESAFE_API_KEY=...
+```
+
+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
+
+```python
+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.
+
+```yaml
+# 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.
+```
+
+```python
+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.
+
+See [docs/topic-format.md](docs/topic-format.md) for every topic option
+(scores, composites, `when`, thresholds, `meta`) and [docs/api.md](docs/api.md)
+for the rest of the API.
+
+## Testing without an API key
+
+```python
+from jevfilter.judges import FakeJudge
+
+fake = FakeJudge({"Jobs/membership": 0.95, "Jobs/categories": "applied"})
+r = jf.Filter(topics, judge=fake).judge("...")
+```
+
+## Development
+
+```sh
+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

jevfilter-0.1.0/docs/api.md

@@ -0,0 +1,209 @@
+---
+title: API
+tags: [jevfilter, api]
+status: draft — partly implemented (see design → Status)
+---
+
+# API by example
+
+Proposed public API, from simplest to most advanced. See [design](design.md) for
+the internals and [topic-format](topic-format.md) for definitions.
+
+## Install
+
+```sh
+pip install jevfilter            # core
+pip install "jevfilter[yaml,cli,eval]"
+export TYPESAFE_API_KEY=...
+```
+
+## API key and model
+
+jevfilter uses `TYPESAFE_API_KEY` from the environment by default. It
+never reads `.env` files; load one yourself (e.g. `python-dotenv`) if you
+keep the key there. To set it in code:
+
+```python
+import jevfilter as jf
+from jevfilter.judges import JevJudge
+
+jf.configure(api_key=key, model="jev-1.13.0")   # default for helpers and filters
+f = Filter(topics, judge=JevJudge(api_key=key))  # or per filter
+jf.choose("...", ["a", "b"], judge=my_judge)     # or per call
+```
+
+## Level 1 — helpers
+
+```python
+import jevfilter as jf
+
+jf.choose("I was charged twice", ["billing", "bug", "feature request"])
+# Choice(value='billing', confidence=0.97, probabilities={...})
+
+jf.check("Can you send the signed form by Friday?", {
+    "needs_reply": "The sender is asking me to reply or send something",
+    "has_deadline": "A specific deadline is mentioned",
+})
+# {'needs_reply': 0.98, 'has_deadline': 0.95}
+
+jf.rate("The site is down for all customers", "severity",
+        ["cosmetic", "degraded", "blocking"])
+# Score(value=1.96, level='blocking', confidence=0.93, ...)
+```
+
+Descriptions can be dicts (`{"billing": "Charges, refunds…"}`) for
+clarity.
+
+## Level 2 — topics
+
+```python
+from jevfilter import Filter, Topic
+
+topics = Topic.load("topics/")     # dir, file, or list of dicts
+f = Filter(topics)
+
+r = f.judge({"from": "...", "subject": "...", "body": "..."})
+
+for t in r.matches:                # outcome == "match"
+    print(t.topic, t.p, t.category, t.flags, t.scores)
+for t in r.review:                 # needs a person
+    print(t.topic, t.reasons)
+
+r.cost_usd, r.input_tokens, r.model
+```
+
+Topics in code:
+
+```python
+Topic(
+    name="Receipts",
+    description="Receipts and order confirmations for things I bought",
+    fields={"merchant": {"kind": "org"}},
+)
+```
+
+### Fields and candidates
+
+```python
+from jevfilter import Content
+
+r = f.judge(Content(email, candidates={"Jobs": {"company": ["Acme", "Initech"]}}))
+r["Jobs"].fields["company"]        # Field(value='Acme', confidence=0.99)
+```
+
+Omit `candidates` to use the extractor registered for each field's
+`kind`.
+
+### Items and tracking
+
+```python
+from jevfilter import track
+
+jobs = topics["Jobs"]
+m = f.match_item(email, jobs, items=[
+    {"id": 3, "fields": {"company": "Acme", "role": "Backend Engineer"}, "status": "applied"},
+    {"id": 7, "fields": {"company": "Acme", "role": "Data Engineer"}, "status": "contacted"},
+])
+m.item_id          # 3, or None for a new item
+m.outcome          # "match" | "review"
+
+track.next_status(jobs, current="applied", category="interview")   # "interviewing"
+track.is_stale(jobs, last_activity=dt, now=now)                   # bool
+```
+
+### Many items
+
+```python
+results = await AsyncFilter(topics).judge_many(emails, concurrency=8)
+```
+
+### Inspect before sending
+
+```python
+plan = f.explain(email)
+plan.requests      # exact payloads
+plan.cost_usd      # estimate
+```
+
+## Level 3 — engine
+
+```python
+from jevfilter import Filter, Budget, ThresholdPolicy
+from jevfilter.judges import JevJudge, KeywordJudge
+
+budget = Budget(usd=1.00, per_minute=60)       # share across filters
+
+f = Filter(
+    topics,
+    judge=JevJudge(model="jev-1.13.0"),         # pin the version
+    policy=ThresholdPolicy(accept=0.8, reject=0.2, min_confidence=0.6),
+    budget=budget,
+    on_error=KeywordJudge(),                    # or "raise" / "review"
+)
+```
+
+### Saving results (your code)
+
+```python
+r = f.judge(email)
+db.insert(r.to_dict())      # plain, JSON-able; restore with Result.from_dict
+```
+
+### Editing topics (e.g. from a UI)
+
+```python
+t = Topic.from_dict(form_data)      # validates, raises with clear messages
+t.to_yaml("topics/jobs.yaml")       # round-trips unchanged
+t.version                           # changes → offer a rescan
+```
+
+### Custom facet
+
+```python
+import jevfilter as jf
+from jevfilter.facets import NoulFacet
+
+@jf.facet("pii")
+class ContainsPII(NoulFacet):
+    instructions = "Does `content` contain personal data such as addresses or ID numbers?"
+```
+
+```yaml
+# usable from topic files
+name: Support
+description: Customer support requests.
+pii: {}
+```
+
+### Custom extractor
+
+```python
+@jf.extractor("order_number")
+def order_numbers(content, field):
+    return re.findall(r"#\d{5,}", content.text)
+```
+
+### Testing without the API
+
+```python
+from jevfilter.judges import FakeJudge
+
+fake = FakeJudge({"Jobs/membership": 0.95, "Jobs/categories": "applied"})
+r = Filter(topics, judge=fake).judge("...")
+```
+
+Record once, replay forever:
+
+```python
+judge = RecordingJudge(JevJudge(), path="tests/cassettes/jobs.jsonl")
+judge = ReplayJudge("tests/cassettes/jobs.jsonl")
+```
+
+## CLI
+
+```sh
+jevfilter try topics/ "Your application was sent to Acme"
+jevfilter explain topics/ email.txt
+jevfilter lint topics/
+jevfilter eval topics/ labelled.jsonl --sweep
+```

jevfilter-0.1.0/docs/background.md

@@ -0,0 +1,85 @@
+---
+title: Background
+tags: [jevfilter, jev, typesafe, library]
+status: draft
+---
+
+# Background
+
+## The recurring problem
+
+A piece of content arrives — an email, an event, a ticket, a document —
+and code needs to decide things about it that only a person could
+previously judge:
+
+- Does it belong to any of these user-defined topics? (several may apply)
+- Which category is it?
+- Which company / person / order is it about?
+- Which thing we're already tracking does it concern?
+- How urgent / relevant / severe is it?
+
+Keyword rules can't express meaning. Generative LLM prompts can, but
+return prose to parse, drift between runs, and give no usable confidence.
+
+## Why Jev
+
+TypeSafe's **Jev** is a System One model: it takes a *state* and a set of
+*questions* and returns typed answers with calibrated probabilities —
+**Noul** (probability of yes), **Choice** (one of a set, with a
+distribution), **Score** (a position on ordered levels). All questions in
+a request see the same state and are evaluated independently and in
+parallel, so asking many questions at once costs little extra latency.
+Input tokens are billed ($0.042 per million at the time of writing),
+output is free — an estimated few cents per thousand typical emails.
+
+That's the right primitive, but it's low level. Every project ends up
+writing the same layer on top of it.
+
+## Where the pattern came from
+
+- [semantic-pubsub-jev](https://github.com/damiensmith1/semantic-pubsub-jev) (Go) — subscribers state interests in plain
+  English; Jev decides who gets each message. Measured and settled:
+  - batch all conditions into one request (1 → 100 questions: 193ms →
+    224ms)
+  - one Noul per condition, because several can match
+  - keep raw probabilities, not just the thresholded boolean
+  - pin the model version when measuring; record which version answered
+  - two spend ceilings (rate and total) that refuse rather than block
+  - an explicit failure policy (fail open vs closed)
+- `jev-gmail-filter` (a Gmail app built on this library) (Python prototype) — user-defined topics filter
+  Gmail, with categories, tracked items and status pipelines. Added:
+  topics as files, selecting field values from code-extracted candidates
+  rather than generating them, a review band for uncertain answers, and
+  matching an email to an existing tracked item. A live run on four
+  synthetic job emails classified all of them correctly, including
+  rejecting a job-alert digest.
+
+## What jevfilter is
+
+An open-source Python library that turns "judge this content against
+these plain-English definitions" into a few lines of code, and scales up
+to categories, fields, scores, tracked items and hierarchies without
+changing tools. It owns the layer both projects rebuilt: turning
+definitions into questions, packing them into requests, applying
+decision policy, controlling spend, handling failure, and making results
+inspectable and testable.
+
+It is not an app, and it doesn't know about email.
+
+## Goals
+
+- **Easy** — a first result in three lines; definitions in plain English.
+- **Extensible** — every moving part (backend, extractors, facets,
+  policy) is a small protocol you can replace.
+- **Powerful** — speculative fan-out, many topics per request,
+  hierarchical categories, composite scores, entity/item matching,
+  tracking rules, batch processing, evaluation against labelled data.
+
+## Prior art
+
+- `typesafe-sdk` — the official client. jevfilter builds on it.
+- Gmail filters / rule engines — keyword and header matching, no meaning.
+- LLM classification prompts — generated text, uncalibrated.
+- TypeSafe cookbooks (fan-out, composite scoring, hierarchical
+  classification, value extraction) — patterns jevfilter packages as
+  reusable building blocks.