jevq 0.1.0__tar.gz

jevq-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+
+# Beads / Dolt files (added by bd init)
+.dolt/
+*.db
+.beads-credential-key
+.beads/proxieddb/
+*.gate.lock*
+
+# BEGIN ortus block=gitignore schema=1 generated-by=ortus@0.4.1.dev103+ga5d6da2
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Credentials and secrets
+credentials.json
+*_secret*
+*.pem
+*.key
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Beads viewer local config
+.bv/
+
+# bd runtime lock at the repo root (bd >= 1.2) — tool state, never source
+.beads.gate.lock
+
+# Human-decision report (regenerated by `ortus human`)
+HUMAN-TODO.md
+
+# Build artifacts and logs
+*.log
+logs/
+
+# Cache directories
+.cache/
+
+# CodeGraph index — local, machine-specific, and large. Every fresh clone
+# rebuilds it with `codegraph init`; `ortus check` reports it when missing.
+.codegraph/
+
+# Python / Node / Go / Rust common build outputs
+__pycache__/
+*.py[cod]
+.venv/
+node_modules/
+dist/
+build/
+target/
+# END ortus block=gitignore

jevq-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to jevq are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and jevq uses
+[semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- The jq sidecar filter: read JSONL on stdin and keep each value whose System
+  One noul is at or above the threshold, emitting the original bytes.
+- `--score`, which wraps every value as `{"score":<noul>,"value":<original>}`.
+- `--pass`, a byte passthrough with no API call and no key.
+- `-t/--threshold` and `$JEV_THRESHOLD`.
+- `-f/--fields`, which sends only the named keys as state.
+- `--model`, with the default pinned to `jev-1.13.0`, and `$JEV_MODEL`.
+- `-v/--verbose` for end-of-run counts and the answering model; stderr stays
+  quiet on success otherwise.
+- Retries with backoff on HTTP 429 and 5xx responses.
+- `samples/` fixtures and offline sample pipe tests against a fake System One.
+- GitHub Actions CI.
+- `scripts/reinstall-cli.sh`.
+- PyPI packaging with a tag-triggered release workflow.
+
+[Unreleased]: https://github.com/who/jevq/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/who/jevq/releases/tag/v0.1.0

jevq-0.1.0/LICENSE

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

jevq-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: jevq
+Version: 0.1.0
+Summary: jq-compatible System One noul filter
+Project-URL: Homepage, https://github.com/who/jevq
+Project-URL: Repository, https://github.com/who/jevq
+Project-URL: Issues, https://github.com/who/jevq/issues
+Author-email: who <githubwho@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,filter,jq,json,jsonl,llm,typesafe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Filters
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# jevq
+
+[![CI](https://github.com/who/jevq/actions/workflows/ci.yml/badge.svg)](https://github.com/who/jevq/actions/workflows/ci.yml)
+
+`jq | jevq | jq`. jq handles structure; jevq reads one JSON value per line from stdin, asks
+Jev (a TypeSafe System One model) a yes/no question about each, and passes through the yeses.
+QUESTION is a yes/no claim about the current value, not a search query.
+
+![jevq demo: filtering support tickets to open refund requests](https://raw.githubusercontent.com/who/jevq/main/docs/assets/jevq-demo.gif)
+
+Video: [docs/assets/jevq-demo.mp4](https://github.com/who/jevq/blob/main/docs/assets/jevq-demo.mp4)
+
+## Install
+
+```bash
+uv tool install jevq            # from PyPI (or: pipx install jevq)
+uv tool install --editable .    # from a source checkout
+export TYPESAFE_API_KEY=...
+```
+
+`scripts/reinstall-cli.sh` forces a rebuild (`--dry-run`, `--no-editable`, `--skip-smoke`).
+
+## Options
+
+`jevq [options] QUESTION` reads JSONL on stdin. QUESTION is required unless `--pass`.
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `QUESTION` | none | Yes/no claim about each value |
+| `-t N`, `--threshold N` | `0.5` (`$JEV_THRESHOLD`) | Keep values scoring at least N |
+| `-f a,b`, `--fields a,b` | whole value | Send only these keys; output stays the full value |
+| `--score` | off | Emit every value as `{"score":<noul>,"value":<original>}` |
+| `--pass` | off | Emit every value unchanged; no API call, no key |
+| `--model NAME` | `jev-1.13.0` (`$JEV_MODEL`) | Model to ask |
+| `-v`, `--verbose` | off | Print counts and the answering model to stderr |
+| `-h`, `--help` | | Show help and exit |
+
+`--score` and `--pass` are mutually exclusive. A flag beats its env var.
+
+## Environment
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `TYPESAFE_API_KEY` | none | API key; required except with `--pass` |
+| `JEV_MODEL` | `jev-1.13.0` | Default model |
+| `JEV_BASE_URL` | `https://api.typesafe.ai/v1/systemone` | API base URL |
+| `JEV_THRESHOLD` | `0.5` | Default threshold |
+
+## Use cases
+
+```bash
+jq -c '.[] | select(.status == "open")' samples/tickets.json |
+  jevq "the customer is asking for a refund" |
+  jq -c '{id, subject}'
+```
+
+Open tickets asking for money back, printed as `{id, subject}`.
+
+```bash
+jq -c 'select(.level == "error")' samples/app.ndjson |
+  jevq "this error is caused by a network timeout, not a bug in our code"
+```
+
+Error log lines that look like a timeout rather than a code bug.
+
+```bash
+gh api 'repos/itchyny/gojq/issues?state=open&per_page=100' |
+  jq -c '.[] | select(.pull_request | not) | {number, title, body}' |
+  jevq --score "reports a crash or wrong output, not a feature request" |
+  jq -rs 'sort_by(-.score) | .[:5][] | .value | "\(.number)\t\(.title)"'
+```
+
+The five most bug-like open issues, as `number<TAB>title`.
+
+More examples: [docs/examples.md](https://github.com/who/jevq/blob/main/docs/examples.md)
+
+Full contract (output rules, exit codes, HTTP, retries): [docs/jevq.md](https://github.com/who/jevq/blob/main/docs/jevq.md)
+
+## Testing
+
+```bash
+uv run pytest -q
+bash tests/samples/run.sh
+```
+
+`JEVQ_LIVE=1 TYPESAFE_API_KEY=... bash tests/samples/run.sh` runs the sample pipes live.
+
+Not supported in v1: `--path`, a `jev()` builtin, concurrency, caching.

jevq-0.1.0/README.md

@@ -0,0 +1,88 @@
+# jevq
+
+[![CI](https://github.com/who/jevq/actions/workflows/ci.yml/badge.svg)](https://github.com/who/jevq/actions/workflows/ci.yml)
+
+`jq | jevq | jq`. jq handles structure; jevq reads one JSON value per line from stdin, asks
+Jev (a TypeSafe System One model) a yes/no question about each, and passes through the yeses.
+QUESTION is a yes/no claim about the current value, not a search query.
+
+![jevq demo: filtering support tickets to open refund requests](https://raw.githubusercontent.com/who/jevq/main/docs/assets/jevq-demo.gif)
+
+Video: [docs/assets/jevq-demo.mp4](https://github.com/who/jevq/blob/main/docs/assets/jevq-demo.mp4)
+
+## Install
+
+```bash
+uv tool install jevq            # from PyPI (or: pipx install jevq)
+uv tool install --editable .    # from a source checkout
+export TYPESAFE_API_KEY=...
+```
+
+`scripts/reinstall-cli.sh` forces a rebuild (`--dry-run`, `--no-editable`, `--skip-smoke`).
+
+## Options
+
+`jevq [options] QUESTION` reads JSONL on stdin. QUESTION is required unless `--pass`.
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `QUESTION` | none | Yes/no claim about each value |
+| `-t N`, `--threshold N` | `0.5` (`$JEV_THRESHOLD`) | Keep values scoring at least N |
+| `-f a,b`, `--fields a,b` | whole value | Send only these keys; output stays the full value |
+| `--score` | off | Emit every value as `{"score":<noul>,"value":<original>}` |
+| `--pass` | off | Emit every value unchanged; no API call, no key |
+| `--model NAME` | `jev-1.13.0` (`$JEV_MODEL`) | Model to ask |
+| `-v`, `--verbose` | off | Print counts and the answering model to stderr |
+| `-h`, `--help` | | Show help and exit |
+
+`--score` and `--pass` are mutually exclusive. A flag beats its env var.
+
+## Environment
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `TYPESAFE_API_KEY` | none | API key; required except with `--pass` |
+| `JEV_MODEL` | `jev-1.13.0` | Default model |
+| `JEV_BASE_URL` | `https://api.typesafe.ai/v1/systemone` | API base URL |
+| `JEV_THRESHOLD` | `0.5` | Default threshold |
+
+## Use cases
+
+```bash
+jq -c '.[] | select(.status == "open")' samples/tickets.json |
+  jevq "the customer is asking for a refund" |
+  jq -c '{id, subject}'
+```
+
+Open tickets asking for money back, printed as `{id, subject}`.
+
+```bash
+jq -c 'select(.level == "error")' samples/app.ndjson |
+  jevq "this error is caused by a network timeout, not a bug in our code"
+```
+
+Error log lines that look like a timeout rather than a code bug.
+
+```bash
+gh api 'repos/itchyny/gojq/issues?state=open&per_page=100' |
+  jq -c '.[] | select(.pull_request | not) | {number, title, body}' |
+  jevq --score "reports a crash or wrong output, not a feature request" |
+  jq -rs 'sort_by(-.score) | .[:5][] | .value | "\(.number)\t\(.title)"'
+```
+
+The five most bug-like open issues, as `number<TAB>title`.
+
+More examples: [docs/examples.md](https://github.com/who/jevq/blob/main/docs/examples.md)
+
+Full contract (output rules, exit codes, HTTP, retries): [docs/jevq.md](https://github.com/who/jevq/blob/main/docs/jevq.md)
+
+## Testing
+
+```bash
+uv run pytest -q
+bash tests/samples/run.sh
+```
+
+`JEVQ_LIVE=1 TYPESAFE_API_KEY=... bash tests/samples/run.sh` runs the sample pipes live.
+
+Not supported in v1: `--path`, a `jev()` builtin, concurrency, caching.

jevq-0.1.0/docs/examples.md

@@ -0,0 +1,105 @@
+# jevq examples
+
+More pipes beyond the three in the [README](../README.md). They use the files
+in `samples/`, so run them from the repo root. Output rules and exit codes
+are in [jevq.md](jevq.md).
+
+## Dev tools in runtime dependencies
+
+```bash
+jq -c '.dependencies | to_entries[]' samples/package.json |
+  jevq "this npm package is a test, lint or build tool, not a runtime library" |
+  jq -r .key
+```
+
+Prints the dependencies that belong in `devDependencies`, one name per line.
+
+## Failed logins, cut at 0.7
+
+```bash
+printf '%s\n' \
+    '{"level":"warn","msg":"failed login for alice from 10.0.0.5"}' \
+    '{"level":"info","msg":"user bob logged in"}' \
+    '{"level":"warn","msg":"invalid password for root from 203.0.113.9"}' \
+    '{"level":"info","msg":"cache warmed in 120ms"}' |
+  jevq --score "this log line records a failed login" |
+  jq -c 'select(.score >= 0.7) | .value'
+```
+
+`--score` wraps each line with its score and jq applies the cutoff.
+
+## Send only some fields with `-f`
+
+```bash
+jq -c '.[] | select(.status == "open")' samples/tickets.json |
+  jevq -f subject,body "the customer is asking for a refund"
+```
+
+Only `subject` and `body` go to Jev; stdout still gets the full ticket.
+
+## Tune the threshold with `-t`
+
+```bash
+jq -c '.[]' samples/tickets.json |
+  jevq -t 0.8 "the customer is asking for a refund"
+```
+
+`-t 0.8` keeps confident matches only. To pick a value, look at the scores
+first:
+
+```bash
+jq -c '.[]' samples/tickets.json |
+  jevq --score "the customer is asking for a refund" |
+  jq -r .score |
+  sort -n
+```
+
+## Dry run with `--pass`
+
+```bash
+jq -c '.[] | select(.status == "open")' samples/tickets.json |
+  jevq --pass |
+  wc -l
+```
+
+Counts the rows a real run would ask about, with no API call and no key.
+`--pass` is also an identity:
+
+```bash
+f=$(mktemp) && jq -c '.[]' samples/tickets.json > "$f" &&
+  jevq --pass < "$f" |
+  cmp - "$f" &&
+  echo identical
+```
+
+## Rank GitHub issues offline
+
+```bash
+jq -c '.[] | select(.pull_request | not) | {number, title, body}' samples/gh-issues.json |
+  jevq --score "reports a crash or wrong output, not a feature request" |
+  jq -rs 'sort_by(-.score) | .[:5][] | .value | "\(.number)\t\(.title)"'
+```
+
+The README's GitHub pipe with `gh api` swapped for a saved copy.
+
+## Counts and model with `-v`
+
+```bash
+jq -c '.[] | select(.status == "open")' samples/tickets.json |
+  jevq -v "the customer is asking for a refund" > refunds.jsonl
+```
+
+At the end of the run stderr gets:
+
+```
+jevq: read 14, emitted 5
+jevq: model: jev-1.13.0
+```
+
+## Tips
+
+- Phrase QUESTION so a high score means yes to what you want to keep.
+- To invert, filter on the score: `jevq --score "..." | jq -c 'select(.score < 0.5) | .value'`.
+- Prefilter with jq and slim with `-f` so each row stays small (about 32k tokens max).
+- Scores are not calibrated probabilities; tune `-t` on real data.
+- One API call per row, sequential; the account limit is about 1,200 requests per minute.

jevq-0.1.0/docs/jevq.md

@@ -0,0 +1,175 @@
+# jevq
+
+jevq filters JSON values with a TypeSafe System One `noul` score. It reads
+JSONL on stdin (the output of `jq -c`), makes one System One call per value,
+and writes JSONL on stdout.
+
+## Usage
+
+```
+jevq [options] QUESTION
+```
+
+QUESTION is a yes/no claim about the current value, for example
+`"the customer is asking for a refund"`. It is not a search query. It is
+required unless `--pass` is given.
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `QUESTION` | Yes/no claim about the current value. |
+| `--score` | Emit every value as `{"score":<noul>,"value":<original>}`. No threshold is applied. |
+| `--pass` | Emit every input value unchanged. No API call and no key required. Cannot be combined with `--score`. |
+| `-t N`, `--threshold N` | Cutoff in [0, 1]. A value is kept when its score is at least N. Default 0.5 or `$JEV_THRESHOLD`. |
+| `-f a,b`, `--fields a,b` | Send only these top-level keys to the model. Output is still the full original value. |
+| `--model NAME` | Model to ask. Default `jev-1.13.0` (pinned) or `$JEV_MODEL`. |
+| `-v`, `--verbose` | Print the end-of-run counts and the answering model to stderr. Combines with every mode. |
+| `-h`, `--help` | Print help and exit. |
+
+## Environment
+
+| Variable | Meaning |
+| --- | --- |
+| `TYPESAFE_API_KEY` | API key, sent as `Authorization: Bearer <key>`. Required except with `--pass`. |
+| `JEV_MODEL` | Default model when `--model` is not given. Default `jev-1.13.0`. |
+| `JEV_BASE_URL` | Endpoint URL. Default `https://api.typesafe.ai/v1/systemone`. |
+| `JEV_THRESHOLD` | Default threshold when `-t` is not given. Default `0.5`. |
+
+## State sent to the model
+
+- An object is sent as it is.
+- With `--fields`, an object is cut down to the listed keys that it has. A
+  missing key is skipped, not an error.
+- Anything that is not an object (a string, number, array, `true`, `false` or
+  `null`) is sent wrapped as `{"value": <value>}`. `--fields` does not apply
+  to it.
+
+`--fields` only changes what the model sees. stdout always carries the input
+line, so `jq -c '.dependencies | to_entries[]' package.json | jevq -f key ...`
+asks about the package name alone and still emits `{"key":...,"value":...}`.
+
+## HTTP request
+
+One `POST` to `$JEV_BASE_URL` (default
+`https://api.typesafe.ai/v1/systemone`) per input value, with a 30 second
+timeout and a `User-Agent: jevq/<version>` header. The body is:
+
+```json
+{
+  "model": "jev-1.13.0",
+  "state": {"id": 7, "subject": "Refund please"},
+  "questions": {"q": {"type": "noul", "instructions": "the customer is asking for a refund"}}
+}
+```
+
+The score is read from `answers.q.noul` in the response and must be a finite
+number. A response that is not JSON, lacks `answers.q.noul`, or holds a
+non-number there is an API error. The top-level `model` field of the response,
+when present, is recorded for the `-v` report.
+
+Calls run one at a time, in input order. There is no caching.
+
+## Retries
+
+Transport errors, HTTP 429 and HTTP 5xx are retried, up to 4 attempts in all.
+The wait before each retry is the `Retry-After` header in seconds, capped at
+10 s, or when that header is missing or unusable, 0.5 s, 1 s, then 2 s. Any
+other non-2xx status fails at once. An API failure is never treated as a "no".
+
+## Output
+
+- Default mode: each value whose score is at least the threshold is written
+  exactly as it was read (whitespace around the line trimmed), one per line.
+- `--score`: every value is written as the compact line
+  `{"score":<noul>,"value":<original>}`. This is the only way jevq wraps a
+  value.
+- `--pass`: every value is written unchanged.
+
+Blank input lines are skipped. Output is flushed after every line, so jevq
+works in a streaming pipe, and a downstream reader that closes early (such as
+`| head -1`) ends jevq quietly with status 0.
+
+On success jevq writes nothing to stderr. With `-v`/`--verbose` it writes, at
+the end of the run (also after an error):
+
+```
+jevq: read N, emitted M
+```
+
+After at least one successful API response it also writes the model or models
+that answered, taken from the responses:
+
+```
+jevq: model: jev-1.13.0
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success. |
+| 1 | Runtime failure: an API error (after retries) or an input line that is not valid JSON. jevq stops at that line; values already emitted stay emitted. |
+| 2 | Usage error: bad flags, missing QUESTION, an invalid threshold or `--fields` value, or `TYPESAFE_API_KEY` not set. Reported before stdin is read. |
+
+Errors go to stderr prefixed `jevq:`, with or without `-v`, for example
+`jevq: line 3: invalid JSON: ...` or `jevq: line 3: API error: HTTP 401: ...`.
+
+## Reinstalling the local tool
+
+`uv tool install --editable .` can reuse a cached build or an existing tool
+environment, so the global `jevq` may not match this checkout. After pulling
+or changing code, run:
+
+```bash
+scripts/reinstall-cli.sh
+```
+
+It works from any directory. It force-reinstalls only the `jevq` uv tool from
+the repo root (`uv tool install --editable --force --reinstall`), then prints
+the version before and after, the source path and install mode, the HEAD short
+sha (with ` (dirty)` when the tree has uncommitted or untracked files), and
+where `jevq` resolves on PATH. It finishes with a smoke test that needs no API
+key: `printf '{"a":1}\n' | jevq --pass` must reproduce its input byte for byte.
+
+Flags:
+
+- `--dry-run` prints the exact uv command and changes nothing.
+- `--no-editable` installs a snapshot instead of an editable install.
+- `--skip-smoke` skips the `--pass` smoke test.
+- `-h`, `--help` prints usage.
+
+The script honours `UV_TOOL_DIR` and `UV_TOOL_BIN_DIR`, so you can install
+into a scratch location without touching your real global tools.
+
+## Sample pipes
+
+`samples/` holds invented data for four realistic `jq | jevq | jq` pipes: stock
+jq picks or reshapes values, jevq judges each one, and jq post-processes the
+survivors. Run them from the repo root:
+
+```bash
+jq -c '.[] | select(.status == "open")' samples/tickets.json | jevq "the customer is asking for a refund" | jq -c '{id, subject}'
+jq -c 'select(.level == "error")' samples/app.ndjson | jevq "this error is caused by a network timeout, not a bug in our code"
+jq -c '.dependencies | to_entries[]' samples/package.json | jevq "this npm package is a test, lint or build tool, not a runtime library" | jq -r '.key'
+jq -c '.[] | select(.pull_request | not) | {number, title, body}' samples/gh-issues.json | jevq --score "reports a crash or wrong output, not a feature request" | jq -rs 'sort_by(-.score) | .[:5][] | .value | "\(.number)\t\(.title)"'
+```
+
+`tests/samples/run.sh` runs these pipes end to end, plus checks for `--fields`,
+`--threshold`, `--pass`, one request per value, and a missing key. It starts a
+deterministic fake System One (`tests/samples/fake_systemone.py`, scored by
+`tests/samples/rules.json`) on 127.0.0.1, so it needs no API key and makes no
+network calls. It works from any directory:
+
+```bash
+bash tests/samples/run.sh
+```
+
+It prints `PASS`, `FAIL` or `SKIP` per case and a final
+`samples: N passed, M failed, K skipped` line, and exits nonzero if any case
+fails. To also run the four pipes against the real endpoint, with looser shape
+checks, set:
+
+```bash
+JEVQ_LIVE=1 TYPESAFE_API_KEY=... bash tests/samples/run.sh
+```

jevq-0.1.0/docs/releasing.md

@@ -0,0 +1,29 @@
+# Releasing jevq
+
+The version comes from the git tag (hatch-vcs), so there is nothing to bump in
+`pyproject.toml`.
+
+## Cut a release
+
+1. In `CHANGELOG.md`, move the `[Unreleased]` notes under
+   `## [X.Y.Z] - YYYY-MM-DD` and update the compare links at the bottom.
+2. Commit and push to `main`.
+3. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+4. `.github/workflows/release.yml` builds the wheel and sdist, publishes them
+   to PyPI, and creates a GitHub release whose notes are that version's
+   CHANGELOG section.
+
+A tag containing `-test` (for example `v0.2.0-test1`) builds and creates the
+GitHub release but skips PyPI. A manual `workflow_dispatch` run only builds.
+
+## One-time setup
+
+Publishing uses PyPI trusted publishing; there are no tokens or secrets.
+
+1. On pypi.org, add a pending publisher with these values:
+   - PyPI project name: `jevq`
+   - Owner: `who`
+   - Repository: `jevq`
+   - Workflow: `release.yml`
+   - Environment: `pypi`
+2. In the GitHub repository settings, create an environment named `pypi`.

jevq-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "jevq"
+dynamic = ["version"]
+description = "jq-compatible System One noul filter"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = { text = "MIT" }
+authors = [{ name = "who", email = "githubwho@gmail.com" }]
+keywords = ["jq", "json", "jsonl", "cli", "filter", "llm", "typesafe"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+    "Topic :: Text Processing :: Filters",
+]
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/who/jevq"
+Repository = "https://github.com/who/jevq"
+Issues = "https://github.com/who/jevq/issues"
+
+[project.scripts]
+jevq = "jevq.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+fallback_version = "0.0.0"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/jevq", "README.md", "LICENSE", "CHANGELOG.md", "docs", "pyproject.toml"]
+exclude = [
+    ".beads",
+    "prd",
+    ".claude",
+    ".grok",
+    ".codex",
+    ".cursor",
+    ".ortusrc",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "docs/assets",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jevq"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

jevq-0.1.0/src/jevq/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("jevq")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

jevq-0.1.0/src/jevq/cli.py

@@ -0,0 +1,297 @@
+"""Command-line entry point for jevq."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import sys
+from collections.abc import Callable, Iterator, Mapping
+from typing import Any, BinaryIO, Protocol, TextIO
+
+from jevq.client import DEFAULT_MODEL, DEFAULT_URL, JevqAPIError, SystemOneClient
+
+DESCRIPTION = """\
+Filter JSON values from stdin (JSONL from `jq -c`) with a System One noul.
+One System One call per value. QUESTION is a yes/no claim about the current
+object, not a search query."""
+
+EPILOG = """\
+environment:
+  TYPESAFE_API_KEY  API key (required except --pass)
+  JEV_MODEL         default model (default jev-1.13.0)
+  JEV_BASE_URL      API base URL (default https://api.typesafe.ai/v1/systemone)
+  JEV_THRESHOLD     default threshold (default 0.5)
+
+examples:
+  jq -c '.[] | select(.status == "open")' tickets.json | jevq "the customer is asking for a refund" | jq -c '{id, subject}'
+  jq -c '.[]' tickets.json | jevq --score "the customer is angry" | jq -c 'select(.score >= 0.8) | .value.id'
+  jq -c '.[]' tickets.json | jevq --pass"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="jevq",
+        usage="jevq [options] QUESTION",
+        description=DESCRIPTION,
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "question",
+        nargs="?",
+        metavar="QUESTION",
+        help="yes/no claim about the current object",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--score",
+        action="store_true",
+        help='emit every row as {"score": <noul>, "value": <original>}',
+    )
+    mode.add_argument(
+        "--pass",
+        dest="pass_",
+        action="store_true",
+        help="emit every input value unchanged. No API call. No key required",
+    )
+    parser.add_argument(
+        "-t",
+        "--threshold",
+        metavar="N",
+        default=None,
+        help="cutoff in [0,1]. Default 0.5 or $JEV_THRESHOLD",
+    )
+    parser.add_argument(
+        "-f",
+        "--fields",
+        metavar="a,b",
+        default=None,
+        help="slim state only. Output is still the full original value",
+    )
+    parser.add_argument(
+        "--model",
+        metavar="NAME",
+        default=None,
+        help="default jev-1.13.0 (pinned) or $JEV_MODEL",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="print end-of-run counts (read/emitted) and the answering model to stderr",
+    )
+    return parser
+
+
+class InputError(Exception):
+    """A non-blank input line that is not exactly one JSON value."""
+
+    def __init__(self, line_no: int, message: str) -> None:
+        super().__init__(f"line {line_no}: invalid JSON: {message}")
+        self.line_no = line_no
+        self.message = message
+
+
+def iter_values(stream: BinaryIO) -> Iterator[tuple[int, bytes, Any]]:
+    """Yield (line_no, raw_bytes, value) per non-blank JSONL line, lazily."""
+    for line_no, line in enumerate(stream, start=1):
+        raw = line.strip()
+        if not raw:
+            continue
+        try:
+            value = json.loads(raw)
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise InputError(line_no, str(exc)) from None
+        yield line_no, raw, value
+
+
+def emit(stdout: BinaryIO, raw: bytes) -> None:
+    stdout.write(raw + b"\n")
+    stdout.flush()
+
+
+def format_score_line(score: float, raw: bytes) -> bytes:
+    """The only wrap: compact ``{"score":<noul>,"value":<raw>}`` plus newline."""
+    return b'{"score":' + json.dumps(float(score)).encode() + b',"value":' + raw + b"}\n"
+
+
+def report(stderr: TextIO, read: int, emitted: int) -> None:
+    stderr.write(f"jevq: read {read}, emitted {emitted}\n")
+
+
+def report_model(stderr: TextIO, client: object) -> None:
+    """Name the model(s) that answered, once any System One response succeeded."""
+    models = getattr(client, "answered_models", None)
+    if models is None or not getattr(client, "responses", 0):
+        return
+    stderr.write(f"jevq: model: {', '.join(models) if models else 'not reported'}\n")
+
+
+class UsageError(Exception):
+    """Bad flags, environment or missing key; exit 2 before reading stdin."""
+
+
+class NoulClient(Protocol):
+    def noul(self, state: Any, question: str) -> float: ...
+
+
+ClientFactory = Callable[[str, str, str], NoulClient]
+
+
+def resolve_threshold(arg: str | None, env: Mapping[str, str]) -> float:
+    raw = arg if arg is not None else (env.get("JEV_THRESHOLD") or None)
+    if raw is None:
+        return 0.5
+    try:
+        value = float(raw)
+    except ValueError:
+        value = math.nan
+    if not math.isfinite(value) or not 0.0 <= value <= 1.0:
+        raise UsageError("threshold must be a number in [0, 1]")
+    return value
+
+
+def parse_fields(arg: str | None) -> list[str] | None:
+    if arg is None:
+        return None
+    names = [name.strip() for name in arg.split(",")]
+    names = [name for name in names if name]
+    if not names:
+        raise UsageError("--fields needs at least one key name")
+    return names
+
+
+def build_state(value: Any, fields: list[str] | None) -> Any:
+    """The state sent to System One; emitted output is always the raw line."""
+    if not isinstance(value, dict):
+        return {"value": value}
+    if fields is None:
+        return value
+    return {k: value[k] for k in fields if k in value}
+
+
+def _default_client_factory(api_key: str, model: str, url: str) -> NoulClient:
+    return SystemOneClient(api_key, model, url)
+
+
+def run(
+    argv: list[str] | None,
+    stdin: BinaryIO,
+    stdout: BinaryIO,
+    stderr: TextIO,
+    env: Mapping[str, str],
+    *,
+    client_factory: ClientFactory | None = None,
+) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        code = exc.code
+        return code if isinstance(code, int) else (0 if code is None else 2)
+    if args.pass_:
+        return _run_pass(stdin, stdout, stderr, verbose=args.verbose)
+    if not (args.question or "").strip():
+        stderr.write("jevq: QUESTION is required unless --pass\n")
+        return 2
+    try:
+        threshold = resolve_threshold(args.threshold, env)
+        fields = parse_fields(args.fields)
+        api_key = (env.get("TYPESAFE_API_KEY") or "").strip()
+        if not api_key:
+            raise UsageError("TYPESAFE_API_KEY is not set")
+    except UsageError as exc:
+        stderr.write(f"jevq: {exc}\n")
+        return 2
+    model = args.model or env.get("JEV_MODEL") or DEFAULT_MODEL
+    url = env.get("JEV_BASE_URL") or DEFAULT_URL
+    client = (client_factory or _default_client_factory)(api_key, model, url)
+    try:
+        return _run_filter(
+            client,
+            args.question,
+            threshold,
+            fields,
+            stdin,
+            stdout,
+            stderr,
+            score_mode=args.score,
+            verbose=args.verbose,
+        )
+    finally:
+        close = getattr(client, "close", None)
+        if close is not None:
+            close()
+
+
+def _run_filter(
+    client: NoulClient,
+    question: str,
+    threshold: float,
+    fields: list[str] | None,
+    stdin: BinaryIO,
+    stdout: BinaryIO,
+    stderr: TextIO,
+    *,
+    score_mode: bool = False,
+    verbose: bool = False,
+) -> int:
+    read = emitted = 0
+    try:
+        for line_no, raw, value in iter_values(stdin):
+            read += 1
+            try:
+                score = client.noul(build_state(value, fields), question)
+            except JevqAPIError as exc:
+                stderr.write(f"jevq: line {line_no}: API error: {exc}\n")
+                if verbose:
+                    report(stderr, read, emitted)
+                    report_model(stderr, client)
+                return 1
+            if score_mode:
+                stdout.write(format_score_line(score, raw))
+                stdout.flush()
+                emitted += 1
+            elif score >= threshold:
+                emit(stdout, raw)
+                emitted += 1
+    except InputError as exc:
+        stderr.write(f"jevq: {exc}\n")
+        if verbose:
+            report(stderr, read, emitted)
+            report_model(stderr, client)
+        return 1
+    if verbose:
+        report(stderr, read, emitted)
+        report_model(stderr, client)
+    return 0
+
+
+def _run_pass(stdin: BinaryIO, stdout: BinaryIO, stderr: TextIO, *, verbose: bool = False) -> int:
+    read = emitted = 0
+    try:
+        for _line_no, raw, _value in iter_values(stdin):
+            read += 1
+            emit(stdout, raw)
+            emitted += 1
+    except InputError as exc:
+        stderr.write(f"jevq: {exc}\n")
+        if verbose:
+            report(stderr, read, emitted)
+        return 1
+    if verbose:
+        report(stderr, read, emitted)
+    return 0
+
+
+def main() -> None:
+    try:
+        code = run(sys.argv[1:], sys.stdin.buffer, sys.stdout.buffer, sys.stderr, os.environ)
+    except BrokenPipeError:
+        # Downstream closed early (e.g. `| head -1`): silence the flush at exit.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        sys.exit(0)
+    sys.exit(code)

jevq-0.1.0/src/jevq/client.py

@@ -0,0 +1,137 @@
+"""httpx client for the TypeSafe System One ``noul`` endpoint."""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from jevq import __version__
+
+DEFAULT_URL = "https://api.typesafe.ai/v1/systemone"
+DEFAULT_MODEL = "jev-1.13.0"
+
+_MAX_RETRY_AFTER = 10.0
+_BASE_BACKOFF = 0.5
+
+
+class JevqAPIError(Exception):
+    """System One call failed; never a "no" answer."""
+
+
+def _retry_after(resp: httpx.Response | None) -> float | None:
+    if resp is None:
+        return None
+    raw = resp.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    if not math.isfinite(value) or value < 0:
+        return None
+    return min(value, _MAX_RETRY_AFTER)
+
+
+def _is_retryable(status: int) -> bool:
+    return status == 429 or 500 <= status <= 599
+
+
+class SystemOneClient:
+    """Ask System One one ``noul`` question about one state per call."""
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = DEFAULT_MODEL,
+        url: str = DEFAULT_URL,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.model = model
+        self.url = url
+        self.max_retries = max_retries
+        self._sleep = sleep
+        self.responses = 0
+        self.answered_models: list[str] = []
+        self._http = httpx.Client(
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": f"jevq/{__version__}",
+            },
+        )
+
+    def build_body(self, state: Any, question: str) -> dict:
+        return {
+            "model": self.model,
+            "state": state,
+            "questions": {"q": {"type": "noul", "instructions": question}},
+        }
+
+    def noul(self, state: Any, question: str) -> float:
+        body = self.build_body(state, question)
+        attempts = self.max_retries + 1
+        last_error = ""
+        for attempt in range(attempts):
+            resp: httpx.Response | None = None
+            try:
+                resp = self._http.post(self.url, json=body)
+            except httpx.TransportError as exc:
+                last_error = f"transport error: {type(exc).__name__}"
+            else:
+                if resp.is_success:
+                    score = _parse_noul(resp)
+                    self._record_model(resp)
+                    return score
+                if not _is_retryable(resp.status_code):
+                    raise JevqAPIError(f"HTTP {resp.status_code}: {resp.text[:200]}")
+                last_error = f"HTTP {resp.status_code}"
+            if attempt < self.max_retries:
+                delay = _retry_after(resp)
+                if delay is None:
+                    delay = _BASE_BACKOFF * 2**attempt
+                self._sleep(delay)
+        raise JevqAPIError(f"{last_error} after {attempts} attempts")
+
+    def _record_model(self, resp: httpx.Response) -> None:
+        """Note the answering model from the response's top-level ``model``."""
+        self.responses += 1
+        model = resp.json().get("model")
+        if isinstance(model, str) and model and model not in self.answered_models:
+            self.answered_models.append(model)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> SystemOneClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+def _parse_noul(resp: httpx.Response) -> float:
+    try:
+        value = resp.json()["answers"]["q"]["noul"]
+    except ValueError as exc:
+        raise JevqAPIError(f"invalid response: not JSON ({exc})") from None
+    except (KeyError, TypeError, IndexError):
+        raise JevqAPIError("invalid response: missing answers.q.noul") from None
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise JevqAPIError(f"invalid response: noul is {type(value).__name__}, not a number")
+    try:
+        score = float(value)
+    except OverflowError:
+        score = math.inf
+    if not math.isfinite(score):
+        raise JevqAPIError("invalid response: noul is not finite")
+    return score