jev-grep 0.1.0__py3-none-any.whl

jev_grep-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: jev-grep
+Version: 0.1.0
+Summary: grep by meaning: filter lines with a plain-English description, judged by TypeSafe's Jev model
+Project-URL: Repository, https://github.com/keltokhy/jgrep
+Author: Khaled Eltokhy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,grep,jev,openrouter,semantic search,typesafe
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Text Processing :: Filters
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# jgrep
+
+grep, but the pattern is a description.
+
+```console
+$ tail -f app.log | jgrep "a user is getting frustrated"
+user 12: this is the third time checkout has failed, I am done with this app
+user 77: WHY does it log me out every five minutes??
+
+$ jgrep -o "announces or releases a new AI model" titles.txt | sort -rn | head -3
+0.980	PrismML Launches Bonsai 2 27B, Its Most Capable Model Yet
+0.970	Alibaba Releases Qwen3.8-Omni-Flash
+0.940	Google announces new experimental "CC" AI agent for families
+```
+
+Each line becomes one yes/no question to [Jev](https://docs.typesafe.ai), TypeSafe's decision
+model. Jev does not generate text. It returns a probability in about 200 ms for about a
+thousandth of a cent, which is fast and cheap enough to sit in a pipe. jgrep reads lines as
+they arrive, judges them concurrently and prints matches in input order, so it works on
+`tail -f` as well as on files.
+
+Measured on 994 Hacker News titles: 4.6 seconds and $0.012 for one description, and the same
+time for three descriptions at once.
+
+## Install
+
+```bash
+uv tool install git+https://github.com/keltokhy/jgrep
+```
+
+jgrep needs a key for one of two APIs. With keys for both, it uses TypeSafe's.
+
+| API | Key | Get one |
+|---|---|---|
+| TypeSafe | `TYPESAFE_API_KEY` | [console.typesafe.ai](https://console.typesafe.ai/settings/keys) |
+| OpenRouter | `OPENROUTER_API_KEY` | [openrouter.ai/keys](https://openrouter.ai/keys) |
+
+Set the environment variable, or put the key in `~/.config/jev/typesafe.key` or
+`~/.config/jev/openrouter.key`. Force a choice with `--api` or `JEV_API`.
+
+## Use
+
+```bash
+jgrep "a complaint about noise" complaints.txt          # lines that fit
+jgrep -v "spam" inbox.txt                               # lines that do not
+jgrep -c "asks a question" *.txt                        # counts per file
+jgrep -p 0.9 "mentions a specific dollar amount" f.txt  # only confident matches
+jgrep -o -p 0 "the writer is losing sleep" f.txt | sort -rn   # rank every line
+jgrep -e "about economics" -e "about New York" f.txt    # either; add --all for both
+jgrep --para "describes an identification strategy" paper.txt
+jgrep --whole "uses a bunching estimator" abstracts/*.txt     # prints matching file names
+jgrep -q "a stack trace" build.log && notify "build broke"
+```
+
+| Option | Meaning |
+|---|---|
+| `-p P` | Match when the probability is at least P. Default 0.5. |
+| `-o` | Put the probability in a first, tab-separated column. |
+| `-v`, `-c`, `-n`, `-H`, `-m NUM`, `-q` | As in grep. |
+| `-e DESC` | Another description. All of them go in one call per line. A line matches if any fits, or all with `--all`. |
+| `--para`, `--whole` | Judge paragraphs or whole files in place of lines. |
+| `--json` | One JSON object per match, with the probability. |
+| `--unordered` | Print matches as answers arrive. |
+| `-j N` | Calls in flight. Default 32. |
+| `--budget DOLLARS` | Stop once this much is spent. Default 1.00, or `$JGREP_BUDGET`; 0 for no limit. |
+| `--timeout SECONDS` | Give up on a line after this long, retries included. Default 15. |
+| `--no-cache`, `--api`, `--model`, `--stats` | See `jgrep --help`. |
+
+Exit status follows grep: 0 if anything matched, 1 if nothing did, 2 on error.
+
+## Cost
+
+A call bills roughly 270 tokens of fixed overhead plus the line and the description, so a
+typical line costs about 300 tokens, or $0.0000126 at $0.042 per million. A million lines is
+about $13. Blank lines, repeated lines and anything answered before are free: answers are
+cached in `~/.cache/jev/answers.sqlite`, keyed on the exact model, line and description.
+Extra `-e` descriptions add about 27 tokens each and no time.
+
+jgrep stops at `--budget`, one dollar by default, so a stray `jgrep pattern huge.log` cannot
+run up a bill. A dollar is about 80,000 lines. A stopped run loses nothing: rerun with a higher
+budget and everything already judged comes from the cache. For a long-lived `tail -f` monitor,
+set your own default once with `export JGREP_BUDGET=20`, or `0` for no limit. With `--stats`, or whenever stderr is a terminal, it prints what the run cost:
+
+```
+jgrep: 994 records, 33 matched; 994 calls, 0 cached; 292,839 tokens; $0.0123; 4.6s
+```
+
+## How well does it work
+
+Three benchmarks on public labeled text, run on 2026-09-18 with Jev 1.13 through OpenRouter.
+Each one runs the installed `jgrep` command itself, uncached, at its default threshold of 0.5.
+Reproduce them with `bench/accuracy.py`.
+
+**Against a keyword grep.** The UCI SMS Spam Collection: 5,574 text messages, 747 of them spam.
+
+| Filter | Precision | Recall | F1 | Time | Cost |
+|---|---:|---:|---:|---:|---:|
+| `jgrep "an unsolicited spam, scam or marketing text message"` | 0.87 | 0.95 | **0.91** | 27 s | $0.07 |
+| the same with `-p 0.9` | 0.98 | 0.84 | 0.90 | | |
+| `grep -iE "free\|win\|prize\|claim\|urgent\|cash\|txt\|call now\|..."` (17 terms) | 0.64 | 0.81 | 0.72 | 0.03 s | free |
+
+The regular expression was written before looking at any results and is in the script.
+
+**Against asking a chat model.** The do-it-yourself alternative is a loop that asks an LLM the
+same yes/no question about each line. On 300 of those messages, 32 requests in flight, all
+through OpenRouter:
+
+| Judge | F1 | Wall time | Cost | Median latency |
+|---|---:|---:|---:|---:|
+| **jgrep (Jev 1.13)** | 0.90 | **2.7 s** | $0.0039 | about 210 ms |
+| GPT Luna | 0.88 | 9.3 s | $0.0060 | 802 ms |
+| GPT Terra | 0.92 | 10.8 s | $0.0571 | 988 ms |
+| Qwen 3.7 Flash, thinking off | 0.78 | 8.4 s | $0.0007 | 789 ms |
+
+jgrep finished three to four times sooner than any of them. Its accuracy sits between the two
+GPT tiers; with 45 spam messages in the sample, those three F1 scores are within noise of each
+other. It is not the cheapest per line: a small open model costs a sixth as much and is
+clearly less accurate. Against the model that matched its accuracy, jgrep cost a fifteenth
+as much.
+
+**Several descriptions at once.** AG News test set, 7,600 articles, four descriptions
+(`-e "news about sports" -e "news about business, markets or the economy" ...`) judged in one
+call per article: 37 seconds and $0.13 for all four. Taking the most probable description as the
+label gives 86.6% accuracy with no training. One-vs-rest F1 at 0.5 was 0.97 for sports, 0.82 for
+science and technology, 0.82 for world affairs and 0.72 for business, which over-triggers
+(precision 0.58) because so much technology news is also business news.
+
+**Does the wording of a description matter?** `bench/phrasing.py` scores 30 hand-labeled lines
+against five descriptions of different grammatical shapes, including a negation and a question.
+Jev got all 150 right under each of four ways of wording the question; that set is easy on
+purpose. Asking five descriptions in one call changed no decision and moved probabilities by
+0.001 on average. Latency was flat at about 210 ms from 1 to 64 questions per call.
+
+On borderline lines the probabilities land in between, which is what `-p` is for:
+
+```
+0.65  [a complaint about noise]  The music from the church on Sunday mornings is lovely but it does start early.
+0.46  [does not mention a landlord]  The owner of the building never answers the phone.
+```
+
+Things to know:
+
+- These are a model's judgments. Check a sample before you rely on a filter.
+- Jev answers the description you wrote, not the one you meant. TypeSafe
+  [documents](https://docs.typesafe.ai/model-jaggedness/jev-1.13) weak spots: counting,
+  comparing numbers or dates, double negatives, and long inputs full of irrelevant detail.
+- Each line is judged alone. jgrep does not show Jev the lines around it.
+- Jev is close to deterministic, not exactly so. Asking 150 questions three times without the
+  cache gave identical probabilities for 128; the rest moved by up to 0.03 and no decision
+  flipped. The cache makes reruns exact.
+- The default model ID is an alias for the latest Jev. For results that must reproduce, pin
+  one with `--model` (for example `typesafe/jev-1.13` on OpenRouter).
+- Text in the input can try to steer the answer. Do not use jgrep as a security boundary.
+
+## Development
+
+```bash
+uv sync && uv run pytest        # 23 tests against a fake API; no key, no network
+uv run python bench/phrasing.py # live; costs about a cent
+uv run python bench/accuracy.py prepare && uv run python bench/accuracy.py spam   # also: news, llm
+```
+
+`src/jgrep/core.py` is the client: two backends, retries inside a time budget, the cache,
+in-flight deduplication and the cost meter. It is shared verbatim with
+[jlink](https://github.com/keltokhy/jlink), which links records across datasets with the same
+model.
+
+MIT license.

jev_grep-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+jgrep/__init__.py,sha256=VcrTKR06N1C0v00rOdHwACjIILKLCp46bPSxNwdGRto,87
+jgrep/__main__.py,sha256=Huz0dExiaH0XTMLhfe3skkFD9-VH7ZUiWMbDR_J8TIY,28
+jgrep/cli.py,sha256=-2PWnc4-HYckM0s3ySVGZQ6FcE9c0zPDuFQ6lCLVMuo,13539
+jgrep/core.py,sha256=ivXkuSpwww5LbdkAmTpwsd4g-3jVbeejxiXeyu7VZFM,10066
+jev_grep-0.1.0.dist-info/METADATA,sha256=ctTGHVDaFFnceuIwmxShgSmJlqNLhG8hVKA_QJr-Q1Q,9202
+jev_grep-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+jev_grep-0.1.0.dist-info/entry_points.txt,sha256=JRibfW3HBfTq5K8S7BMbOfPB4135MoBJOPigH1aIig0,40
+jev_grep-0.1.0.dist-info/licenses/LICENSE,sha256=unAu2Ii_6qZZfNfkD44Vj0MNv9C7H6CBRje23cMNx4g,1071
+jev_grep-0.1.0.dist-info/RECORD,,

jev_grep-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

jev_grep-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jgrep = jgrep.cli:cli

jev_grep-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khaled Eltokhy
+
+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.

jgrep/__init__.py

@@ -0,0 +1,3 @@
+"""jgrep: grep by meaning, on TypeSafe's Jev decision model."""
+
+__version__ = "0.1.0"

jgrep/__main__.py

@@ -0,0 +1,3 @@
+from .cli import cli
+
+cli()

jgrep/cli.py

@@ -0,0 +1,304 @@
+"""jgrep: print lines that fit a description.
+
+    tail -f app.log | jgrep "a user is getting frustrated"
+    jgrep -o "asks for police overtime records" requests.txt | sort -rn | head
+    jgrep -c -p 0.8 "uses a bunching estimator" abstracts.txt
+
+Each line is one yes/no question to Jev. Lines are read as they arrive, judged concurrently and
+printed in input order. Exit status follows grep: 0 if anything matched, 1 if not, 2 on error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+import threading
+import time
+from dataclasses import dataclass
+
+from . import __version__
+from .core import BACKENDS, Cache, Jev, JevError, JevFatal, config_dir, resolve_backend
+
+STDIN = "(standard input)"
+MAX_ERRORS_SHOWN = 10
+DEFAULT_BUDGET = 1.0  # dollars; a grep-shaped command that bills per line needs a seat belt
+
+
+@dataclass
+class Record:
+    seq: int
+    file: str
+    lineno: int
+    text: str
+
+
+def question(description: str) -> dict:
+    return {"type": "noul", "instructions": f'The text fits this description: "{description}"'}
+
+
+def parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="jgrep", formatter_class=argparse.RawDescriptionHelpFormatter,
+        usage="jgrep [options] DESCRIPTION [FILE ...]",
+        description="Print lines that fit a plain-English description, as judged by TypeSafe's Jev model.",
+        epilog='examples:\n'
+               '  tail -f app.log | jgrep "a user is getting frustrated"\n'
+               '  jgrep -o "about heat or hot water" complaints.txt | sort -rn | head\n'
+               '  jgrep -v -p 0.2 "spam" inbox.txt\n'
+               '  jgrep --whole "uses a bunching estimator" abstracts/*.txt\n\n'
+               "Jev is reached through TypeSafe's API (TYPESAFE_API_KEY) or OpenRouter (OPENROUTER_API_KEY).\n"
+               f"Keys can also live in {config_dir()}/typesafe.key or openrouter.key.")
+    ap.add_argument("args", nargs="*", help=argparse.SUPPRESS)
+    ap.add_argument("-e", dest="descriptions", action="append", metavar="DESCRIPTION",
+                    help="a description; repeat for several, which are judged in one call (a line matches if any fits)")
+    ap.add_argument("--all", action="store_true", help="with several -e, a line must fit all of them")
+    ap.add_argument("-p", "--threshold", type=float, default=0.5, metavar="P",
+                    help="match when the probability is at least P (default 0.5)")
+    ap.add_argument("-v", "--invert-match", action="store_true", help="print lines that do not match")
+    ap.add_argument("-o", "--prob", action="store_true", help="put the probability in a first, tab-separated column")
+    ap.add_argument("-n", "--line-number", action="store_true", help="prefix each line with its line number")
+    ap.add_argument("-H", "--with-filename", action="store_true", help="prefix each line with its file name")
+    ap.add_argument("--no-filename", action="store_true", help="never print file names")
+    ap.add_argument("-c", "--count", action="store_true", help="print only a count of matching lines")
+    ap.add_argument("-m", "--max-count", type=int, metavar="NUM", help="stop after NUM matches")
+    ap.add_argument("-q", "--quiet", action="store_true", help="print nothing; exit 0 at the first match")
+    ap.add_argument("--json", action="store_true", help="print one JSON object per match")
+    ap.add_argument("--para", action="store_true", help="judge paragraphs (separated by blank lines), not lines")
+    ap.add_argument("--whole", action="store_true", help="judge each file as a whole and print matching file names")
+    ap.add_argument("--unordered", action="store_true", help="print matches as answers arrive, not in input order")
+    ap.add_argument("-j", "--concurrency", type=int, default=32, metavar="N", help="calls in flight (default 32)")
+    ap.add_argument("--timeout", type=float, default=15.0, metavar="SECONDS",
+                    help="give up on a line after this long, retries included (default 15)")
+    ap.add_argument("--budget", type=float, default=None, metavar="DOLLARS",
+                    help="stop once this much has been spent (default 1.00, or $JGREP_BUDGET; 0 for no limit)")
+    ap.add_argument("--max-chars", type=int, default=8000, metavar="N",
+                    help="judge only the first N characters of a record (default 8000)")
+    ap.add_argument("--no-cache", action="store_true", help="do not read or write the answer cache")
+    ap.add_argument("--api", choices=list(BACKENDS), help="which API to call (default: whichever has a key)")
+    ap.add_argument("--model", metavar="ID", help="model ID to request (default: the API's latest Jev)")
+    ap.add_argument("--stats", action=argparse.BooleanOptionalAction, default=None,
+                    help="print calls, tokens and cost to stderr at the end (default: when stderr is a terminal)")
+    ap.add_argument("--version", action="version", version=f"jgrep {__version__}")
+    return ap
+
+
+def records(files: list[str], args, stop: threading.Event):
+    """Yield Records lazily, so `tail -f` works. Yields a str for a file that cannot be read."""
+    seq = 0
+    for name in files or ["-"]:
+        label = STDIN if name == "-" else name
+        try:
+            # A private reader on fd 0: sys.stdin's lock can wedge interpreter shutdown.
+            f = open(0, "rb", closefd=False) if name == "-" else open(name, "rb")
+        except OSError as e:
+            yield f"{name}: {e.strerror}"
+            continue
+        with f:
+            if args.whole:
+                yield Record(seq, label, 1, f.read(args.max_chars * 4).decode("utf-8", "replace"))
+                seq += 1
+                continue
+            para, start = [], 0
+            for lineno, raw in enumerate(iter(f.readline, b""), 1):
+                if stop.is_set():
+                    return
+                line = raw.decode("utf-8", "replace").rstrip("\r\n")
+                if not args.para:
+                    yield Record(seq, label, lineno, line)
+                    seq += 1
+                elif line.strip():
+                    start = start if para else lineno
+                    para.append(line)
+                elif para:
+                    yield Record(seq, label, start, "\n".join(para))
+                    seq, para = seq + 1, []
+            if para:
+                yield Record(seq, label, start, "\n".join(para))
+                seq += 1
+
+
+def render(rec: Record, p: float, ps: list[float], args, show_file: bool) -> str:
+    if args.json:
+        obj = {"file": rec.file, "line": rec.lineno, "p": round(p, 4)}
+        if len(ps) > 1:
+            obj["ps"] = [round(x, 4) for x in ps]
+        if not args.whole:
+            obj["text"] = rec.text
+        return json.dumps(obj, ensure_ascii=False)
+    if args.whole:
+        body = rec.file
+    else:
+        body = (f"{rec.file}:" if show_file else "") + (f"{rec.lineno}:" if args.line_number else "") + rec.text
+    if args.prob:
+        body = f"{p:.3f}\t{body}"
+    return body + ("\n" if args.para and not args.whole else "")
+
+
+async def run(args, descriptions: list[str], files: list[str], jev: Jev, out, err) -> int:
+    loop = asyncio.get_running_loop()
+    questions = {f"d{i}": question(d) for i, d in enumerate(descriptions)}
+    show_file = not args.no_filename and (args.with_filename or len(files) > 1)
+    queue: asyncio.Queue = asyncio.Queue(maxsize=args.concurrency)
+    sem = asyncio.Semaphore(args.concurrency)
+    stop, halt = threading.Event(), asyncio.Event()
+    finished: dict[int, tuple] = {}
+    tasks: set[asyncio.Task] = set()
+    counts: dict[str, int] = {}
+    s = {"next": 0, "seen": 0, "matched": 0, "errors": 0, "fatal": None, "over_budget": False}
+
+    def feed() -> None:
+        try:
+            for item in records(files, args, stop):
+                asyncio.run_coroutine_threadsafe(queue.put(item), loop).result()
+            asyncio.run_coroutine_threadsafe(queue.put(None), loop).result()
+        except BaseException:  # the loop is gone because the run halted early
+            pass
+
+    def complain(message: str) -> None:
+        s["errors"] += 1
+        if s["errors"] <= MAX_ERRORS_SHOWN:
+            print(f"jgrep: {message}", file=err)
+
+    def emit(rec: Record, p: float | None, ps: list[float] | None, error: str | None) -> None:
+        s["seen"] += 1
+        if error:
+            return complain(f"{rec.file}:{rec.lineno}: {error}")
+        if (p >= args.threshold) == args.invert_match:
+            return
+        s["matched"] += 1
+        counts[rec.file] = counts.get(rec.file, 0) + 1
+        if not (args.quiet or args.count):
+            try:
+                out.write(render(rec, p, ps, args, show_file) + "\n")
+                out.flush()
+            except BrokenPipeError:
+                halt.set()
+        if args.quiet or (args.max_count and s["matched"] >= args.max_count):
+            halt.set()
+
+    def deliver(rec: Record, result: tuple) -> None:
+        if args.unordered:
+            return None if halt.is_set() else emit(rec, *result)
+        finished[rec.seq] = (rec, *result)
+        while s["next"] in finished and not halt.is_set():
+            emit(*finished.pop(s["next"]))
+            s["next"] += 1
+
+    async def judge(rec: Record) -> None:
+        try:
+            if not rec.text.strip():
+                result = (0.0, [0.0] * len(questions), None)
+            else:
+                answers = await jev.ask(rec.text[:args.max_chars], questions)
+                ps = [float(answers[q]["noul"]) for q in questions]
+                result = (min(ps) if args.all else max(ps), ps, None)
+        except JevError as e:
+            result = (None, None, str(e))
+        except JevFatal as e:
+            s["fatal"] = s["fatal"] or str(e)
+            return halt.set()
+        finally:
+            sem.release()
+        deliver(rec, result)
+        if args.budget and jev.meter.cost >= args.budget and not s["over_budget"]:
+            s["over_budget"] = True
+            halt.set()
+
+    threading.Thread(target=feed, daemon=True).start()
+    halted = asyncio.ensure_future(halt.wait())
+    while not halt.is_set():
+        get = asyncio.ensure_future(queue.get())
+        await asyncio.wait({get, halted}, return_when=asyncio.FIRST_COMPLETED)
+        if not get.done():
+            get.cancel()
+            break
+        item = get.result()
+        if item is None:
+            break
+        if isinstance(item, str):
+            complain(item)
+            continue
+        await sem.acquire()
+        if halt.is_set():
+            break
+        task = asyncio.create_task(judge(item))
+        tasks.add(task)
+        task.add_done_callback(tasks.discard)
+
+    stop.set()
+    halted.cancel()
+    if halt.is_set():
+        for t in list(tasks):
+            t.cancel()
+    await asyncio.gather(*tasks, return_exceptions=True)
+    await jev.close()
+
+    if args.count and not args.quiet:
+        names = [STDIN if f == "-" else f for f in (files or ["-"])]
+        for name in names:
+            print(f"{name}:{counts.get(name, 0)}" if show_file else counts.get(name, 0), file=out)
+        out.flush()
+    if s["errors"] > MAX_ERRORS_SHOWN:
+        print(f"jgrep: and {s['errors'] - MAX_ERRORS_SHOWN:,} more errors", file=err)
+    if s["fatal"]:
+        print(f"jgrep: {s['fatal']}", file=err)
+    if s["over_budget"]:
+        print(f"jgrep: stopped at the ${args.budget:.2f} budget after {s['seen']:,} records; raise it with --budget",
+              file=err)
+    args.summary = f"{s['seen']:,} records, {s['matched']:,} matched; {jev.meter.summary()}"
+    if s["fatal"] or s["over_budget"] or s["errors"]:
+        return 0 if args.quiet and s["matched"] else 2
+    return 0 if s["matched"] else 1
+
+
+def main(argv: list[str] | None = None, *, transport=None, out=None, err=None) -> int:
+    out, err = out or sys.stdout, err or sys.stderr
+    ap = parser()
+    args = ap.parse_args(argv)
+    descriptions, files = (args.descriptions, args.args) if args.descriptions else (args.args[:1], args.args[1:])
+    if not descriptions:
+        ap.print_usage(err)
+        return 2
+    if args.budget is None:
+        try:
+            args.budget = float(os.environ.get("JGREP_BUDGET") or DEFAULT_BUDGET)
+        except ValueError:
+            print(f"jgrep: JGREP_BUDGET must be a number of dollars; got {os.environ['JGREP_BUDGET']!r}", file=err)
+            return 2
+    if args.whole and args.para:
+        print("jgrep: --whole and --para cannot be combined", file=err)
+        return 2
+    try:
+        backend, key = resolve_backend(args.api)
+    except JevFatal as e:
+        print(f"jgrep: {e}", file=err)
+        return 2
+
+    jev = Jev(key, backend, model=args.model, timeout=args.timeout, concurrency=args.concurrency,
+              cache=None if args.no_cache else Cache(), transport=transport)
+    t0 = time.perf_counter()
+    try:
+        code = asyncio.run(run(args, descriptions, files, jev, out, err))
+    except KeyboardInterrupt:
+        code, args.summary = 130, f"interrupted; {jev.meter.summary()}"
+    if args.stats or (args.stats is None and err.isatty()):
+        print(f"jgrep: {args.summary}; {time.perf_counter() - t0:.1f}s", file=err)
+    return code
+
+
+def cli() -> None:
+    code = main()
+    try:
+        sys.stdout.flush()
+    except BrokenPipeError:
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    sys.stderr.flush()
+    # A reader thread may still be blocked on stdin (tail -f); do not wait for it.
+    os._exit(code)
+
+
+if __name__ == "__main__":
+    cli()

jgrep/core.py

@@ -0,0 +1,244 @@
+"""Client for TypeSafe's Jev decision model: two backends, an answer cache and a cost meter.
+
+Jev can be reached through TypeSafe's own API or through OpenRouter. Both take one state and any
+number of questions per call and return one typed answer per question. Answers are cached per
+(model, state, question), so packing questions into a call and rerunning a command are both cheap.
+
+This file is shared verbatim between the jgrep and jlink repositories.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import random
+import sqlite3
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import httpx
+
+RETRYABLE = {408, 429, 500, 502, 503, 504, 529}
+FATAL = {401, 402, 403}
+# TypeSafe's API reports tokens but not cost; OpenRouter reports both.
+PRICE_PER_MTOK = float(os.environ.get("JEV_PRICE_PER_MTOK", 0.042))
+
+
+class JevError(Exception):
+    """One request failed; the rest of the run can continue."""
+
+
+class JevFatal(Exception):
+    """Nothing will work until the user fixes something, such as a bad key or no credits."""
+
+
+@dataclass(frozen=True)
+class Backend:
+    name: str
+    url: str
+    model: str
+    key_env: str
+
+    @property
+    def key_file(self) -> Path:
+        return config_dir() / f"{self.name}.key"
+
+    def key(self) -> str | None:
+        if os.environ.get(self.key_env):
+            return os.environ[self.key_env].strip()
+        return self.key_file.read_text().strip() if self.key_file.exists() else None
+
+
+# Order matters: with keys for both, TypeSafe's own API is used.
+BACKENDS = {
+    "typesafe": Backend("typesafe", "https://api.typesafe.ai/v1/systemone", "jev-latest", "TYPESAFE_API_KEY"),
+    "openrouter": Backend("openrouter", "https://openrouter.ai/api/alpha/decisions", "~typesafe/jev-latest",
+                          "OPENROUTER_API_KEY"),
+}
+
+
+def config_dir() -> Path:
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "jev"
+
+
+def cache_path() -> Path:
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "jev" / "answers.sqlite"
+
+
+def resolve_backend(name: str | None = None) -> tuple[Backend, str]:
+    """The API to use and its key. A name (or JEV_API) wins; otherwise the first backend with a key."""
+    name = name or os.environ.get("JEV_API")
+    if name:
+        if name not in BACKENDS:
+            raise JevFatal(f"unknown API {name!r}; choose from {', '.join(BACKENDS)}")
+        backend = BACKENDS[name]
+        if not (key := backend.key()):
+            raise JevFatal(f"no key for {name}. Set {backend.key_env} or put the key in {backend.key_file}")
+        return backend, key
+    for backend in BACKENDS.values():
+        if key := backend.key():
+            return backend, key
+    options = " or ".join(b.key_env for b in BACKENDS.values())
+    raise JevFatal(f"no API key. Set {options}, or put a key in {config_dir()}/<api>.key")
+
+
+class Cache:
+    """Answers on disk, keyed on the exact model, state and question."""
+
+    def __init__(self, path: Path | None = None):
+        path = path or cache_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.db = sqlite3.connect(path, timeout=30, isolation_level=None, check_same_thread=False)
+        # WAL lets two tools in one pipeline share the file.
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute("PRAGMA synchronous=NORMAL")
+        self.db.execute("CREATE TABLE IF NOT EXISTS answers "
+                        "(key TEXT PRIMARY KEY, answer TEXT NOT NULL, at REAL NOT NULL) WITHOUT ROWID")
+
+    @staticmethod
+    def key(model: str, state, question: dict) -> str:
+        blob = json.dumps([model, state, question], sort_keys=True, ensure_ascii=False)
+        return hashlib.sha256(blob.encode()).hexdigest()
+
+    def get(self, key: str) -> dict | None:
+        row = self.db.execute("SELECT answer FROM answers WHERE key = ?", (key,)).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def put(self, key: str, answer: dict) -> None:
+        self.db.execute("INSERT OR REPLACE INTO answers VALUES (?, ?, ?)", (key, json.dumps(answer), time.time()))
+
+
+@dataclass
+class Meter:
+    calls: int = 0
+    cached: int = 0
+    retries: int = 0
+    input_tokens: int = 0
+    cost: float = 0.0
+    model: str = ""  # the model the API says answered, which resolves aliases like jev-latest
+    latencies: list[float] = field(default_factory=list)
+
+    def summary(self) -> str:
+        parts = [f"{self.calls:,} calls, {self.cached:,} cached"]
+        if self.retries:
+            parts.append(f"{self.retries:,} retries")
+        if self.calls:
+            parts.append(f"{self.input_tokens:,} tokens")
+            parts.append(f"${self.cost:.4f}")
+        return "; ".join(parts)
+
+
+class Jev:
+    def __init__(self, key: str, backend: Backend | str = "openrouter", *, model: str | None = None,
+                 timeout: float = 15.0, attempts: int = 4, concurrency: int = 32, cache: Cache | None = None,
+                 transport=None):
+        self.backend = BACKENDS[backend] if isinstance(backend, str) else backend
+        self.model = model or os.environ.get("JEV_MODEL") or self.backend.model
+        self.url = os.environ.get("JEV_URL") or self.backend.url
+        self.timeout, self.attempts, self.cache = timeout, attempts, cache
+        self.meter = Meter()
+        self._flights: dict[str, asyncio.Task] = {}
+        self.http = httpx.AsyncClient(
+            headers={"Authorization": f"Bearer {key}", "X-Title": "jev tools"},
+            limits=httpx.Limits(max_connections=concurrency + 4, max_keepalive_connections=concurrency + 4),
+            transport=transport,
+        )
+
+    async def close(self) -> None:
+        await self.http.aclose()
+
+    async def ask(self, state, questions: dict[str, dict]) -> dict[str, dict]:
+        """Answer every question about one state. Only questions missing from the cache are sent."""
+        keys = {qid: Cache.key(self.model, state, q) for qid, q in questions.items()}
+        answers = {}
+        if self.cache:
+            for qid, k in keys.items():
+                if (hit := self.cache.get(k)) is not None:
+                    answers[qid] = hit
+        misses = {qid: q for qid, q in questions.items() if qid not in answers}
+        if not misses:
+            self.meter.cached += 1
+            return answers
+
+        # Identical requests already in the air share one call; logs repeat themselves a lot.
+        flight = "|".join(sorted(keys[qid] for qid in misses))
+        task = self._flights.get(flight)
+        if task is None:
+            task = asyncio.ensure_future(self._call(state, misses))
+            self._flights[flight] = task
+            task.add_done_callback(lambda _: self._flights.pop(flight, None))
+        else:
+            self.meter.cached += 1
+        by_key = await task
+        return answers | {qid: by_key[keys[qid]] for qid in misses}
+
+    async def _call(self, state, questions: dict[str, dict]) -> dict[str, dict]:
+        """One request, retried inside a total time budget. Returns answers by cache key."""
+        body = {"model": self.model, "state": state, "questions": questions}
+        deadline = time.monotonic() + self.timeout
+        last = "no attempt made"
+        for attempt in range(self.attempts):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            t0 = time.perf_counter()
+            try:
+                r = await self.http.post(self.url, json=body, timeout=remaining)
+            except httpx.TransportError as e:
+                last = type(e).__name__
+            else:
+                data = _json(r)
+                if r.status_code == 200 and "answers" in data:
+                    return self._record(state, questions, data, time.perf_counter() - t0)
+                detail = _detail(data) or r.text[:200]
+                if r.status_code in FATAL:
+                    raise JevFatal(f"{self.backend.name} said {r.status_code}: {detail}")
+                if r.status_code != 200 and r.status_code not in RETRYABLE:
+                    raise JevError(f"HTTP {r.status_code}: {detail}")
+                last = f"HTTP {r.status_code}"
+            if attempt + 1 < self.attempts:
+                self.meter.retries += 1
+                pause = 0.2 * 2 ** attempt + random.random() * 0.1
+                await asyncio.sleep(max(0.0, min(pause, deadline - time.monotonic())))
+        raise JevError(f"gave up after {self.timeout:g}s ({last})")
+
+    def _record(self, state, questions: dict, data: dict, seconds: float) -> dict[str, dict]:
+        usage = data.get("usage") or {}
+        tokens = usage.get("input_tokens") or 0
+        cost = usage.get("cost")
+        self.meter.calls += 1
+        self.meter.input_tokens += tokens
+        self.meter.cost += tokens * PRICE_PER_MTOK / 1e6 if cost is None else cost
+        self.meter.latencies.append(seconds)
+        self.meter.model = data.get("model") or self.model
+        out = {}
+        for qid, q in questions.items():
+            if qid not in data["answers"]:
+                raise JevError(f"no answer returned for question {qid!r}")
+            k = Cache.key(self.model, state, q)
+            out[k] = data["answers"][qid]
+            if self.cache:
+                self.cache.put(k, out[k])
+        return out
+
+
+def _json(r: httpx.Response) -> dict:
+    try:
+        data = r.json()
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _detail(data: dict) -> str:
+    """The human-readable part of an error body. OpenRouter nests it under `error`, TypeSafe under `detail`,
+    and `detail` may itself be a string, an object or a list of validation problems."""
+    found = data.get("error", data.get("detail"))
+    if isinstance(found, list):
+        found = "; ".join(_detail({"detail": item}) for item in found)
+    elif isinstance(found, dict):
+        found = found.get("message") or found.get("msg") or json.dumps(found)
+    return " ".join(str(found or "").split())[:200]