Metadata-Version: 2.5
Name: jev-grep
Version: 0.2.1
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
Requires-Dist: pathspec>=0.12
Requires-Dist: unidiff<0.8,>=0.7.5
Provides-Extra: code
Requires-Dist: tree-sitter-go<0.26,>=0.25; extra == 'code'
Requires-Dist: tree-sitter<0.26,>=0.25; extra == 'code'
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 jev-grep        # the command it installs is jgrep
uv tool upgrade jev-grep        # upgrade an existing installation
```

For Go function parsing, install the optional syntax parser: `uv tool install 'jev-grep[code]'`.
Python function parsing and unified diffs work with the base package.

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.

| 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`.

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:

```bash
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

```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 -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
```

| 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`, `-q` | As in grep. |
| `-m NUM` | Stop each input file after NUM matches; `-m 0` reads no input and makes no API calls. |
| `-l` | Print a file name at its first matching record, then continue to the next file. |
| `-r` | Search directories recursively; defaults to the current directory if no paths are given. |
| `--glob PATTERN`, `--exclude PATTERN` | Include or exclude files; both can be repeated. |
| `--no-ignore` | During recursive search, disregard `.gitignore` and `.ignore`. |
| `-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. |
| `-C N` | Show Jev the N lines either side of each line. Still one decision per line, and still only the matching line is printed. |
| `--json` | One JSON object per match, with the probability. |
| `--jsonl --field NAME`, `--csv --field NAME` | Judge one field and return the complete original record. |
| `--chunks N`, `--overlap N` | Search full text files in overlapping passages, with source locations. |
| `--diff` | Judge each complete unified diff hunk, including removed lines and unchanged context. |
| `--functions`, `--lang python\|go` | Judge complete functions/methods with adjacent comments; infer language from the extension, or specify it for stdin. |
| `--estimate` | Read to EOF and preview calls and approximate cost without authentication or API calls. Add `--json` for a single report. |
| `--emit-records` | Export source-linked JSONL without judging; omit DESCRIPTION. Useful for inspection and other tools. |
| `--max-chars N` | Maximum characters judged per ordinary record; default 8000. Truncation produces a warning. |
| `--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.
Offline estimation and record export exit 0 on success, including empty input, and 2 on errors.

With ordered output, `-j N` bounds the total of active requests and completed results waiting
for earlier records. A slow first record therefore cannot let the rest of the input run ahead.
`--unordered` releases each slot as soon as its result arrives.

## Changes and complete functions

```bash
# Review both sides of each change, including deletion-only hunks
git diff --no-color | jgrep --diff "removes error handling for a persistent write"
jgrep --diff "weakens cancellation handling" review.patch --json

# Read the entire function; comments and decorators stay attached
jgrep --functions "ignores a failed rollback" plugin/installer.go --json
jgrep --functions "releases connections on every exit path" src/ -r --glob '*.py'

# Preview exactly the units the filter would judge; no key or paid call needed
git diff --no-color | jgrep --diff --estimate "removes error handling" --json

# Export functions for jselect without making any jgrep model calls
jgrep --functions --emit-records src/ -r > functions.jsonl
jselect "How does cancellation work?" functions.jsonl --tokens 2000
```

`--diff` accepts ordinary unified patches, including Git diffs, from files or stdin. One decision
covers a complete hunk: both removed and added lines, plus the context supplied in the patch.
Use `git diff -U10` when you need more surrounding lines. Each emitted hunk repeats its file headers.
It does not read the working tree or retrieve omitted context. Binary changes, metadata-only changes
(such as mode-only edits), combined merge diffs, and malformed hunks produce errors rather than
silently reporting no match. An empty diff contains no records.

For diff JSON, `file`, `line`, and `end_line` locate the hunk in the **input patch**, while `unit`
contains `old_file`, `new_file`, `old_start`, `old_count`, `new_start`, and `new_count`. Missing
file sides are null; zero-length ranges retain the unified diff's insertion/deletion anchor.
`-c` counts matching hunks per input patch and `-l` names matching input patches.

`--functions` supports Python through the standard-library AST and Go through the optional
Tree-sitter parser. It extracts named functions and methods, retaining decorators, docstrings,
adjacent comments, and nested function bodies. Nested functions are not emitted again separately.
Imports, class-level state and callers are not automatically attached. Recursive discovery skips
other extensions unless `--lang` is explicit. Syntax errors are reported rather than guessed around.
Function JSON includes `unit.language`, `unit.symbol`, and exact decoded-character `start`/`end`
offsets with one-based source lines. The Python API exposes the same deterministic readers in
`jgrep.code_inputs.function_records` and `diff_records`.

Diffs and functions **never truncate**: units over `--max-chars` fail with their size and location.
Raise that limit deliberately if needed. These modes cannot combine with `-C`, `--para`, `--whole`,
`--chunks`, or structured input. They read each input file into memory; keep live streams in line mode.

`--emit-records` writes one object containing `schema_version`, `id`, `text`, `source`, line/span
locations and `unit`. IDs include the source location and a text hash, so tools that select only
`text` and `id`, including jselect, retain a traceable reference. It exports full parsed records,
without ordinary line-mode truncation or a relevance judgment. Do not supply a description or match
filters. Errors are JSONL objects with an `error.message` and cause exit 2; a pipeline must check
the producer's exit status before treating its export as complete.

These modes retrieve evidence for review. Model scores do not prove a bug or certify that a change
is safe. Results and observed failures on 20 handwritten examples are in the
[code-review experiment](https://github.com/keltokhy/jgrep/blob/main/docs/CODE_REVIEW.md).

## Cost preview

`--estimate` uses the same input mode, selected field, context window, descriptions and model as
the filter. It reads existing cached answers in read-only mode and estimates reuse of exact repeated
requests. It does not normalize whitespace or identifiers, create a cache, or contact the provider.
Without a configured provider it uses TypeSafe's default model; use `--api` and `--model` to preview
a specific setup. No API key is required.

The JSON report includes record/cache/duplicate counts, `estimated_calls`, `call_upper_bound` before
new duplicate reuse, `estimated_input_tokens`, `estimated_cost_usd`, `byte_estimate_cost_usd`, errors
and assumptions. Costs use `JEV_PRICE_PER_MTOK` (default $0.042 per million input tokens). The nominal
estimate is UTF-8 request bytes divided by four plus 270 overhead tokens per request; the broader
byte estimate uses those bytes plus 1,024 overhead. Neither is a provider quote or guaranteed cap.
Retries, gateway pricing and concurrent cache misses can change actual cost.

Preview reads to EOF and ignores matching stop conditions (`-q`, `-l`, `-m`, threshold and budget),
because their effects depend on model answers. It reports ordinary-record truncation and oversized
code-unit errors. Use finite input, not an endless `tail -f` stream. With `--json`, the preview is one
object; `errors` makes a partially readable collection explicit and the exit status is 2.

## 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 provider, endpoint, exact model, judged text
and description. Changing gateways cannot reuse another endpoint's answers. Older cache entries
without provider/endpoint identity are not reused, so the first rerun may make fresh calls.
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.

| 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.
- 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

```bash
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](https://github.com/keltokhy/jlink), which links records across datasets with the same
model.

MIT license.
