jevq 0.1.0__py3-none-any.whl

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

jevq-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+jevq/__init__.py,sha256=Wnlf-_59Qwn66xZUiA2oyHLtF7izD-gZyHiaCnvG6Uo,164
+jevq/cli.py,sha256=33Ugf3KDG4RGu14qN1zaLVE8Nze6xDSGi47A4Uo6rTY,9226
+jevq/client.py,sha256=qIzzG_MMjMdp7aBs4vCePkJehVoH2J7gDVpgkC9pNIw,4348
+jevq-0.1.0.dist-info/METADATA,sha256=b88CHQgeltL7hqrKbWasf6CoUmyNpSARjTy9zjl4KnM,4116
+jevq-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+jevq-0.1.0.dist-info/entry_points.txt,sha256=Ce5-FLbUDQsGnzPZm-JlOnIXCwz2xISYoR1R8_zEAyo,39
+jevq-0.1.0.dist-info/licenses/LICENSE,sha256=7g1B9RFIOYnUT-dx6FnYMn6HEA9bqDDEVLtji__nRLE,1060
+jevq-0.1.0.dist-info/RECORD,,

jevq-0.1.0.dist-info/WHEEL

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

jevq-0.1.0.dist-info/entry_points.txt

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

jevq-0.1.0.dist-info/licenses/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.