jev-select 0.1.0__py3-none-any.whl

jev_select-0.1.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: jev-select
+Version: 0.1.0
+Summary: Select useful, source-linked evidence for an AI task within a token budget
+Project-URL: Repository, https://github.com/keltokhy/jselect
+Project-URL: Documentation, https://github.com/keltokhy/jselect#readme
+Project-URL: Issues, https://github.com/keltokhy/jselect/issues
+Author: Khaled Eltokhy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,context,jev,retrieval,semantic search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pathspec>=0.12
+Requires-Dist: tiktoken>=0.8
+Description-Content-Type: text/markdown
+
+# jselect
+
+**Useful evidence for your AI, within a token budget.**
+
+Give jselect a task and your data. It finds relevant passages, favors different information over
+repetition, and assembles a source-linked context your agent can read directly.
+
+```bash
+jselect "Why are people giving up during signup?" conversations.jsonl --tokens 8000
+```
+
+```python
+from jselect import select
+
+evidence = select(records, task="Why are people giving up during signup?", tokens=8000)
+print(evidence.context)       # source excerpts and citations, within the token budget
+```
+
+No labels, predefined categories, vector database, or generative model required. Runs on files,
+directories, piped exports, or Python records. This is a **separate tool and package** from jgrep.
+
+## Install
+
+Python 3.10+:
+
+```bash
+uv tool install jev-select   # installs the jselect command on PATH
+pip install jev-select       # use jselect from your Python application
+```
+
+The distribution is named `jev-select`; the command and Python import are both `jselect`.
+
+```bash
+jselect doctor --json
+echo 'The signup verification email never arrived.' | jselect "signup problems" --tokens 600
+```
+
+For development, clone [the repository](https://github.com/keltokhy/jselect), run `uv sync`,
+then `uv run jselect ...`. For an editable command: `uv tool install --editable .`.
+
+If a TypeSafe or OpenRouter key is configured, the default uses **semantic relevance scoring** with Jev.
+Set `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`, or use existing credentials in
+`~/.config/jev/typesafe.key` or `~/.config/jev/openrouter.key`. Credentials never appear in output.
+`JEV_API`, `JEV_MODEL`, and `JEV_URL` overrides are supported. Gateways use `JEV_GATEWAY_URL` and
+`JEV_GATEWAY_API_KEY`, or `~/.config/jev/gateway.url` and `gateway.key`.
+
+Without credentials, jselect uses local lexical retrieval and says so. Force that with `--local`.
+Use `--mode semantic` to require semantic scoring and fail if credentials are missing.
+
+## Use it across your data
+
+```bash
+# Customer conversations, with common text fields detected automatically
+jselect "What prevents users from finishing signup?" conversations.jsonl --tokens 2000
+
+# Related turns stored as separate, possibly interleaved rows
+jselect "Where does the assistant contradict itself?" turns.jsonl --group-by conversation_id
+
+# Source code and documentation, respecting .gitignore and .ignore
+jselect "How are database connections released?" src/ docs/ --tokens 4000
+
+# Papers or interview responses in a CSV
+jselect "Evidence that challenges the proposed explanation" papers.csv --field abstract --tokens 3000
+
+# Export from another tool, preserving original IDs and field locations
+cat events.jsonl | jselect "Why are requests waiting?" --format jsonl --field message --json
+
+# Fully offline, including token accounting: byte count conservatively bounds byte-BPE token use
+jselect "retry timeout configuration" src/ --local --encoding bytes --tokens 4000
+```
+
+Supported inputs: UTF-8 text and code, logs, JSONL/NDJSON, JSON objects or arrays, CSV/TSV, directories,
+and stdin. Formats are inferred from extensions. Stdin defaults to lines; use `--format jsonl` for
+structured input. `.log` files default to one record per line; `--format text` preserves neighboring
+log lines in overlapping passages. PDF, Word, images, and audio need text extraction first.
+
+Common text fields are tried in this order: `text`, `content`, `message`, `messages`, `conversation`,
+`body`, `abstract`. If none exists, the entire object is serialized as JSON. `--field event.message`
+selects an exact or dotted field. Only selected text is sent to the scorer, not the entire original row.
+IDs come from `id`, `_id`, or input position. A group uses complete serialized rows unless you explicitly
+select a field, preserving roles and other turn context. Grouping preserves input order, not timestamp order.
+
+## Fast repeated investigations
+
+Build a local index once and ask many questions:
+
+```bash
+jselect index conversations.jsonl --output conversations.jselect
+jselect "Confusion about cancellation" conversations.jselect --json --output first.json
+jselect "Confusion about cancellation" conversations.jselect --against first.json --json --output next.json
+jselect inspect conversations.jselect --json
+jselect show conversations.jselect PASSAGE_ID --json
+```
+
+`--against` excludes exact excerpts already returned and penalizes similar text. It is useful when an
+agent asks for more evidence or brings an existing reference set. It does not promise every follow-up
+will introduce a new semantic idea. Saved indexes are snapshots: rebuild with `index ... --force` when
+the source changes. Replacement is atomic, so a failed rebuild leaves the previous index intact.
+
+For maximum retrieval breadth, use `--scan all`. This scores every unique passage that fits the output
+budget and is not already supplied in `--against`, then keeps a bounded pool for final selection.
+The full scan is preflighted against the estimated dollar budget before any calls are made.
+
+```bash
+jselect "Signs the customer has lost trust" conversations.jselect --scan all --budget 0.25
+```
+
+## Python and agents
+
+```python
+from jselect import Index, Record, aselect, select
+
+records = [
+    {"id": "ticket-1", "text": "The verification link never arrives."},
+    {"id": "ticket-2", "text": "The free trial requires a credit card."},
+]
+result = select(records, task="What blocks registration?", tokens=500)
+payload = result.to_dict()   # same schema as --json
+
+# Reuse an index in a process; no source scanning on each query.
+with Index.build(records) as index:
+    first = index.select(task="What blocks registration?", tokens=500)
+    more = index.select(task="What blocks registration?", tokens=500, against=first)
+
+# In an existing event loop or notebook:
+# result = await aselect(records, task="What blocks registration?", tokens=500)
+
+# Bring your existing reranker. Return one finite score in [0, 1] per passage.
+def judge(task, passages):
+    return existing_reranker(task, [p.text for p in passages])
+
+result = select(records, task="What blocks registration?", tokens=500, scorer=judge)
+```
+
+Custom scorers may be async functions or objects exposing `score(task, passages)`. Full scans invoke
+them in blocks of at most 256 passages. Use `Record(text, id=..., source=...)` for explicit provenance.
+A string or `Path` passed directly to `select` is an input path; strings inside an iterable are records.
+To use passages already retrieved by another system, pass them as records; set `scan="all"` with a
+custom or semantic scorer if the list exceeds the candidate limit and every passage must be evaluated.
+
+Pass **`result.context`** to your agent. The full JSON includes additional metadata and is not subject
+to the context token budget. Treat excerpts as source data rather than agent instructions.
+
+## How it works and what it costs
+
+1. Build or open a SQLite FTS5 index. Long records become overlapping, source-preserving passages.
+   Exact repeated passages share one indexed text while retaining occurrence counts and up to five sources.
+2. Shortlist up to 256 passages by default. Most come from BM25 with a text-diversity adjustment;
+   20% of slots are reserved for deterministic exploration in semantic mode. This is not exhaustive retrieval.
+3. Score relevance using small batches of Jev decisions. The question explicitly includes contradicting
+   evidence. Scores are cached per endpoint, model, prompt version, task, and exact passage.
+4. Greedily balance relevance, text novelty, and passage token cost. Citation headers and separators count
+   toward the budget. Oversized passages are split **before** scoring; returned text is never generated.
+
+The defaults are eight passages per request, eight requests in flight, a 20-second total request deadline,
+and a **$0.05 estimated spend budget**. Jev models are versioned (`jev-1.13.0` on TypeSafe and
+`typesafe/jev-1.13` on OpenRouter); responses report the served model when available. Requests retry
+transient errors within the deadline. Errors retain completed cache entries for the next run.
+
+The dollar guard uses a conservative UTF-8 byte estimate and the listed Jev input price. Actual provider
+or gateway pricing and unreported usage can differ; this is not a provider-enforced billing cap. JSON
+reports measured cost when available and marks list-price estimates. Failed requests without usage
+reports may have incurred additional costs. Use `--candidates`, `--batch-size`, and `--budget` to bound work.
+`--no-cache` disables the disk score cache at `~/.cache/jselect/scores.sqlite`.
+
+Token counting uses `o200k_base` by default. Set `--encoding` to another tiktoken encoding/model, or `bytes`
+for a conservative count with no tokenizer download. The first use of a tiktoken encoding may download its
+public vocabulary. Choose the encoding your downstream model uses and leave room for its other messages.
+
+## Measured results
+
+Measured locally on 2026-09-19; details and frozen reports are in [the benchmark report](https://github.com/keltokhy/jselect/blob/main/docs/BENCHMARKS.md).
+
+| Check | Observed result |
+|---|---|
+| One million distinct generated log records | 13.64 s to index; 0.40 s median repeated **local** query; 143 MB peak process memory |
+| 30 SciFact research queries, 2,000 tokens, 256 candidates, cache disabled | 86.7% mean labeled-source recall vs 78.3% for BM25 ranking; 1.86 s median; $0.149 total |
+| Handwritten support, code, and contract fixtures | All 4 intended evidence types in 4 passages in each fixture; relevance-only variant covered 3, 3, and 1 |
+
+These are scoped measurements, not guarantees for arbitrary data, agent answer quality, or future API
+latency. A selected set cannot establish prevalence or causation. Diversity is a lexical heuristic;
+it does not certify balanced viewpoints or find every contradiction. Semantic scores are model judgments,
+not calibrated confidence in a final answer. The JSON reports how much of the collection was considered.
+
+## Output and errors
+
+Default stdout is the exact context string. `--json` returns one object with `schema_version: 1`,
+`task`, `context`, `items`, `tokens`, `token_budget`, `encoding`, `stats`, and `warnings`.
+Each item contains original `text`, a stable content-hash `id`, `sources`, `occurrences`, `relevance`,
+`novelty`, and the selection rule used. See [the output contract](https://github.com/keltokhy/jselect/blob/main/docs/OUTPUT.md).
+
+Exit 0 means success, including empty evidence. Exit 2 means invalid input, bad setup, budget refusal,
+or a provider error. Exit 130 means interruption. JSON errors have an `error` object and any available
+usage `stats`; diagnostics never contaminate JSON stdout. `--stats` writes timings and cost to stderr.
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run ruff check src tests bench
+uv run ruff format --check src tests bench
+uv build
+```
+
+See [the validation plan](https://github.com/keltokhy/jselect/blob/main/docs/PLAN.md),
+[benchmarks](https://github.com/keltokhy/jselect/blob/main/docs/BENCHMARKS.md), and the
+[companion agent skill](https://github.com/keltokhy/jselect/blob/main/skills/jselect/SKILL.md). MIT licensed.

jev_select-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+jselect/__init__.py,sha256=5g2DNxjJVGDwQySR0upXJwhkUjViVYrdU0KEmn8Qqeo,320
+jselect/__main__.py,sha256=Huz0dExiaH0XTMLhfe3skkFD9-VH7ZUiWMbDR_J8TIY,28
+jselect/cli.py,sha256=mEGCOmDDfqOB-ErGJ6cmmFmneUhOMUsBHBKJqq7CeZY,10875
+jselect/index.py,sha256=kGEO36ZSVSVd3fLe6uq8HT2TpaPNdi-EKKpvzP35Qvg,10926
+jselect/inputs.py,sha256=4Fw8CGiGy9bulUkDK8Y4AzRpe5wf43gZyCJ5hm4xf7g,12182
+jselect/judge.py,sha256=_zSHexjtOQKYuxLAYY1-eaJ2muG49gEdWvN9RavTrjQ,15013
+jselect/select.py,sha256=gPBteVvnWdvZNfOZ9h2x833EfU1fW14pMfb0XTVWW-o,15354
+jselect/text.py,sha256=p954cyTLyC6wcnnA-uWIVUq2POE45jnRE9-rzoJu1Hk,4108
+jselect/types.py,sha256=_Q2XdoFlmGTdkA9BQ_9IY8qcN9jfGBxcIgSCcAVcXJ0,1938
+jev_select-0.1.0.dist-info/METADATA,sha256=gQkLrG-UZQMAtGoBmT-yqODryBBl-KCqEm9b0i0xpcM,12063
+jev_select-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+jev_select-0.1.0.dist-info/entry_points.txt,sha256=_R5BGb8cm9en7hGwcVgHrMPyxo-9IEtfKhEKjaQj5RA,44
+jev_select-0.1.0.dist-info/licenses/LICENSE,sha256=unAu2Ii_6qZZfNfkD44Vj0MNv9C7H6CBRje23cMNx4g,1071
+jev_select-0.1.0.dist-info/RECORD,,

jev_select-0.1.0.dist-info/WHEEL

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

jev_select-0.1.0.dist-info/entry_points.txt

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

jev_select-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khaled Eltokhy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jselect/__init__.py

@@ -0,0 +1,9 @@
+"""Useful evidence within a token budget."""
+
+from .index import Index
+from .select import aselect, select
+from .text import count_tokens
+from .types import Evidence, Passage, Record, Selection
+
+__all__ = ["Evidence", "Index", "Passage", "Record", "Selection", "aselect", "count_tokens", "select"]
+__version__ = "0.1.0"

jselect/__main__.py

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

jselect/cli.py

@@ -0,0 +1,272 @@
+"""The shell interface. stdout is evidence (or JSON); diagnostics go to stderr."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from . import __version__
+from .index import Index
+from .inputs import read_paths
+from .judge import SemanticError, resolve_backend
+from .select import select
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise ValueError(message)
+
+
+def inputs(parser):
+    parser.add_argument(
+        "paths", nargs="*", help="files/directories; '-' reads stdin; a .jselect file reuses an index"
+    )
+    parser.add_argument("--field", help="text field or dotted path; auto-detected for common JSON/CSV fields")
+    parser.add_argument(
+        "--group-by", help="combine rows by this field, e.g. conversation_id (in input order)"
+    )
+    parser.add_argument(
+        "--format",
+        choices=["auto", "text", "lines", "jsonl", "json", "csv", "tsv"],
+        default="auto",
+        help="input format (default: infer from extension)",
+    )
+    parser.add_argument("--glob", help="only read matching files in directories, e.g. '*.py'")
+    parser.add_argument(
+        "--exclude", action="append", default=[], help="gitignore-style exclusion; repeatable"
+    )
+    parser.add_argument(
+        "--chunk-size", type=int, default=1800, help="passage size in characters (default: 1800)"
+    )
+    parser.add_argument("--overlap", type=int, default=240, help="overlap in characters (default: 240)")
+
+
+def source(args):
+    return read_paths(
+        args.paths or ["-"],
+        field=args.field,
+        format=args.format,
+        glob=args.glob,
+        exclude=args.exclude,
+        group_by=args.group_by,
+    )
+
+
+def parser_for(command):
+    p = Parser(
+        prog="jselect" + (f" {command}" if command else ""),
+        description="Select useful, source-linked evidence within a token budget.",
+        epilog="Other commands: index (save a searchable collection), inspect (index stats), "
+        "show (read a passage by ID), doctor (check setup).",
+    )
+    p.add_argument("--version", action="version", version=f"jselect {__version__}")
+    p.add_argument("--json", action="store_true", help="emit a versioned JSON object, including JSON errors")
+    if command == "doctor":
+        p.add_argument("--api", choices=["typesafe", "openrouter", "gateway"])
+        return p
+    if command in {"inspect", "show"}:
+        p.add_argument("path", help="saved .jselect index")
+        if command == "show":
+            p.add_argument("id", help="full passage ID from JSON selection output")
+        return p
+    if command == "index":
+        inputs(p)
+        p.add_argument("--output", "-o", required=True, help="path for the saved .jselect index")
+        p.add_argument("--force", action="store_true", help="replace an existing index atomically")
+        return p
+    p.add_argument("task", help="the task, question, or information you need")
+    inputs(p)
+    p.add_argument(
+        "--tokens", type=int, default=8000, help="maximum tokens in the evidence context (default: 8000)"
+    )
+    p.add_argument(
+        "--encoding", default="o200k_base", help="tiktoken encoding/model, or 'bytes' (default: o200k_base)"
+    )
+    p.add_argument(
+        "--mode",
+        choices=["auto", "local", "semantic"],
+        default="auto",
+        help="auto uses semantic scoring when a key is configured, else local retrieval",
+    )
+    p.add_argument(
+        "--local", action="store_const", dest="mode", const="local", help="use local retrieval; no API calls"
+    )
+    p.add_argument("--candidates", type=int, default=256, help="maximum passages shortlisted (default: 256)")
+    p.add_argument(
+        "--scan", choices=["shortlist", "all"], default="shortlist", help="all scores every unique passage"
+    )
+    p.add_argument("--against", help="previous --json result or records: seek additional evidence")
+    p.add_argument(
+        "--diversity", type=float, default=0.7, help="penalty for repetitive text, 0..1 (default: 0.7)"
+    )
+    p.add_argument("--threshold", type=float, help="minimum relevance score (semantic default: 0.25)")
+    p.add_argument("-n", "--max-items", type=int, help="also cap the number of selected passages")
+    p.add_argument("--api", choices=["typesafe", "openrouter", "gateway"])
+    p.add_argument("--model", help="override the pinned Jev model")
+    p.add_argument(
+        "--budget",
+        type=float,
+        default=0.05,
+        help="semantic dollar budget; preflight estimate (default: 0.05)",
+    )
+    p.add_argument(
+        "-j", "--concurrency", type=int, default=8, help="maximum simultaneous requests (default: 8)"
+    )
+    p.add_argument("--batch-size", type=int, default=8, help="passages per API request, 1..16 (default: 8)")
+    p.add_argument("--timeout", type=float, default=20, help="total seconds per request, including retries")
+    p.add_argument("--no-cache", action="store_true", help="disable persistent semantic score caching")
+    p.add_argument("--stats", action="store_true", help="print timing and cost to stderr")
+    p.add_argument("--output", "-o", help="write evidence or JSON to this file instead of stdout")
+    return p
+
+
+def main(argv=None, *, out=None, err=None, transport=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    out, err = out or sys.stdout, err or sys.stderr
+    json_mode = "--json" in argv
+    command = next((arg for arg in argv if arg != "--json"), "")
+    command = command if command in {"index", "inspect", "show", "doctor"} else ""
+    if command:
+        argv.remove(command)
+    try:
+        args = parser_for(command).parse_intermixed_args(argv)
+        if command == "doctor":
+            issue = None
+            try:
+                backend = resolve_backend(args.api)
+            except (OSError, ValueError) as e:
+                backend, issue = None, str(e)
+            db = sqlite3.connect(":memory:")
+            try:
+                db.execute("CREATE VIRTUAL TABLE health USING fts5(text)")
+            finally:
+                db.close()
+            payload = {
+                "schema_version": 1,
+                "version": __version__,
+                "local_ready": True,
+                "semantic_configured": backend is not None,
+                "auth_verified": False,
+                "api": backend.name if backend else None,
+                "model": backend.model if backend else None,
+                "auth_source": backend.auth_source if backend else "missing",
+                "hint": issue
+                or (None if backend else "Set TYPESAFE_API_KEY or OPENROUTER_API_KEY for semantic scoring."),
+            }
+            print(
+                json.dumps(payload)
+                if args.json
+                else f"jselect {__version__}: local mode ready; "
+                f"semantic {'configured' if backend else 'not configured'}"
+                + (f"\n{payload['hint']}" if payload["hint"] else ""),
+                file=out,
+            )
+            return 0
+        if command == "index":
+            with Index.build(
+                source(args),
+                path=args.output,
+                chunk_size=args.chunk_size,
+                overlap=args.overlap,
+                force=args.force,
+            ) as index:
+                payload = {"schema_version": 1, "path": str(index.path), "stats": index.stats}
+            print(
+                json.dumps(payload)
+                if args.json
+                else f"Indexed {payload['stats']['records']:,} records → {payload['path']}",
+                file=out,
+            )
+            return 0
+        if command in {"inspect", "show"}:
+            with Index(args.path) as index:
+                payload = (
+                    {"schema_version": 1, "path": str(index.path), "stats": index.stats}
+                    if command == "inspect"
+                    else {"schema_version": 1, "passage": asdict(index.get(args.id))}
+                )
+            print(
+                json.dumps(payload, ensure_ascii=False)
+                if args.json or command == "inspect"
+                else payload["passage"]["text"],
+                file=out,
+            )
+            return 0
+        index = None
+        if len(args.paths) == 1 and Path(args.paths[0]).suffix == ".jselect":
+            index = Index(args.paths[0])
+        try:
+            result = select(
+                index or source(args),
+                task=args.task,
+                tokens=args.tokens,
+                encoding=args.encoding,
+                mode=args.mode,
+                candidates=args.candidates,
+                scan=args.scan,
+                diversity=args.diversity,
+                threshold=args.threshold,
+                max_items=args.max_items,
+                against=args.against,
+                api=args.api,
+                model=args.model,
+                budget=args.budget,
+                concurrency=args.concurrency,
+                batch_size=args.batch_size,
+                timeout=args.timeout,
+                cache=not args.no_cache,
+                chunk_size=args.chunk_size,
+                overlap=args.overlap,
+                _transport=transport,
+            )
+        finally:
+            if index:
+                index.close()
+        output = json.dumps(result.to_dict(), ensure_ascii=False) + "\n" if args.json else result.context
+        if args.output:
+            Path(args.output).write_text(output, encoding="utf-8")
+        else:
+            out.write(output)
+        if args.stats:
+            stats = result.stats
+            print(
+                f"jselect: {len(result.items)} passages, {result.tokens}/{result.token_budget} tokens; "
+                f"{stats.get('mode')}; {stats.get('calls', 0)} calls; ${stats.get('cost', 0):.6f}; "
+                f"{stats.get('seconds', 0):.3f}s",
+                file=err,
+            )
+        if not args.json:
+            for warning in result.warnings:
+                print(f"jselect: {warning}", file=err)
+        return 0
+    except BrokenPipeError:
+        return 0
+    except (ValueError, OSError, sqlite3.Error, SemanticError) as e:
+        if json_mode:
+            print(
+                json.dumps(
+                    {
+                        "schema_version": 1,
+                        "error": {"type": type(e).__name__, "message": str(e)},
+                        "stats": getattr(e, "stats", None),
+                    }
+                ),
+                file=out,
+            )
+        else:
+            print(f"jselect: {e}", file=err)
+        return 2
+    except KeyboardInterrupt:
+        print("jselect: interrupted", file=err)
+        return 130
+
+
+def cli():
+    try:
+        raise SystemExit(main())
+    except BrokenPipeError:
+        raise SystemExit(0) from None