jgrep

grep, but the pattern is a description.

$ 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, 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

uv tool install jev-grep        # the command it installs is jgrep
uv tool upgrade jev-grep        # upgrade an existing installation

jgrep needs a key for one of two APIs, or for a gateway of your own (below). With keys for several, it uses TypeSafe's.

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.

Behind an LLM gateway that serves System One (LiteLLM, Ramp Router, a corporate proxy), point jgrep at it with --api gateway. The URL is the full endpoint and the key is the gateway's own:

export JEV_GATEWAY_URL=https://gateway.example.com/v1/systemone
export JEV_GATEWAY_API_KEY=...       # or ~/.config/jev/gateway.key and gateway.url
jgrep "a stack trace" build.log      # picked automatically when it is the only key set

Requests are sent as they would be to TypeSafe, so the gateway sees the same {model, state, questions} body. Ask for a model the gateway knows with --model; the default is jev-latest. --stats prices gateway calls at TypeSafe's list price, which may not be what the gateway bills.

Use

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 -C 2 "a line in the middle of a stack trace" app.log   # judged with its neighbours
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"
jgrep --jsonl --field message "a payment failed" events.jsonl
jgrep --csv --field abstract "uses a natural experiment" papers.csv
jgrep -rl --glob '*.txt' "mentions a rent increase" notes/
jgrep --chunks 8000 --json "describes an identification strategy" paper.txt

Exit status follows grep: 0 if anything matched, 1 if nothing did, 2 on error.

Structured records

--jsonl expects one JSON object per line. --csv expects a header with unique column names and supports quoted commas and multiline cells. Both require --field NAME. Only that field is sent for judgment; -C also supplies that field from neighboring records. Matching output retains the complete JSON line or CSV row, including fields that were not judged. CSV output includes the original header once for each input file with matches. Record terminators are written as newlines, while quoting and embedded newlines are preserved.

JSON field names can be dotted paths, such as event.message or events.0.message. An exact key takes precedence over a dotted path. Strings are judged directly, null is treated as empty text, and other values are represented as JSON. Missing fields, invalid JSON, and malformed CSV rows are reported as errors; valid later records are still processed when parsing can continue. Blank JSONL lines are skipped.

Structured output omits automatic filename prefixes so it can be read as JSONL or CSV. Use -H or -n only when you want those prefixes. --json instead emits a match object containing file, the starting physical line, p, text (the original record), field, and record (the parsed object, with CSV column values kept as strings). For several CSV files with different headers, this JSON output is easier to combine. -c counts matching records, and -l lists matching files without headers or rows.

Directory and document search

-r visits files in sorted order, respecting .gitignore and .ignore in each directory and parent ignore files inside a Git repository. It skips symlinks, .git directories, and files with a NUL byte in the initial binary check. --glob '*.txt' selects names anywhere below the search root; patterns can also match relative paths. --exclude uses gitignore patterns. --no-ignore disables ignore files but still honors explicit exclusions. Explicit file arguments bypass ignore files; include/exclude filters still apply. Use -l when only the matching paths are needed.

Ordinary lines, paragraphs, selected fields, and --whole judgments are limited to the first 8000 characters by default. jgrep reports when this truncates a record or its context. Raise --max-chars to change that limit, or use --chunks N to search the entire text file a passage at a time. Chunk size replaces the ordinary character limit. Overlap defaults to the smaller of 200 characters and one quarter of the chunk size; --overlap 0 disables it.

Chunk output includes the starting line number. With --json, each matching passage also has chunk (one-based), start and end (zero-based character offsets, end exclusive), and end_line (the last source line containing characters from the passage). Offsets count decoded Unicode characters, not bytes. Passages can overlap and are judged independently; their scores are not combined into a document-wide probability. -c counts matching passages, while --chunks 8000 -l lists files with at least one matching passage.

Chunk mode applies to plain text files and cannot be combined with structured input, --para, --whole, or -C; use overlap to retain text across passage boundaries. These modes read text, not PDF or Word formats.

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. -C N sends 2N+1 lines in place of one, so -C 2 costs roughly three times as much per line once the fixed overhead is counted.

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.

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:

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 weak spots: counting, comparing numbers or dates, double negatives, and long inputs full of irrelevant detail.
• A line is judged alone unless you pass -C N, which shows Jev the N lines either side of it. The decision is still per line, and the neighbours are not printed. Context does not reach across files, and on tail -f a line cannot be judged until the N after it arrive.
• 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

uv sync && uv run pytest        # offline tests using a fake API and local HTTP server; no key
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/inputs.py handles file discovery, structured records, and document passages. src/jgrep/core.py is the client: API backends, retries inside a time budget, the cache, in-flight deduplication and the cost meter. It shares its design with jlink, which links records across datasets with the same model.

MIT license.