jevkit-runtime 0.1.0__py3-none-any.whl

jevkit_core/__init__.py

@@ -0,0 +1,48 @@
+"""Shared implementation for the independent JevKit tools."""
+
+from .backends import (
+    PRICE_PER_MTOK,
+    PROVIDERS,
+    Backend,
+    backend_catalog,
+    config_dir,
+    credential,
+    resolve_backend,
+)
+from .cache import AnswerCache, answer_key, cache_path, digest
+from .client import DecisionClient, validate_answer
+from .errors import JevBudgetExceeded, JevError, JevFatal
+from .provenance import answer_provenance
+from .transport import FATAL, RETRYABLE, RetryPolicy, error_detail, json_object, request_json
+from .usage import Meter, Usage, parse_usage, record_usage
+
+__version__ = "0.1.0"
+__all__ = [
+    "AnswerCache",
+    "Backend",
+    "DecisionClient",
+    "FATAL",
+    "JevBudgetExceeded",
+    "JevError",
+    "JevFatal",
+    "Meter",
+    "PRICE_PER_MTOK",
+    "PROVIDERS",
+    "RETRYABLE",
+    "RetryPolicy",
+    "Usage",
+    "answer_key",
+    "answer_provenance",
+    "backend_catalog",
+    "cache_path",
+    "config_dir",
+    "credential",
+    "digest",
+    "error_detail",
+    "json_object",
+    "parse_usage",
+    "record_usage",
+    "request_json",
+    "resolve_backend",
+    "validate_answer",
+]

jevkit_core/backends.py

@@ -0,0 +1,142 @@
+"""Backend capabilities and credentials; product adapters select their supported backends."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .errors import JevFatal
+
+PRICE_PER_MTOK = float(os.environ.get("JEV_PRICE_PER_MTOK", 0.042))
+
+
+def config_dir() -> Path:
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "jev"
+
+
+def credential(name: str, variable: str) -> tuple[str, str]:
+    """Return a key and its source, without putting secrets in errors or logs."""
+    key = os.environ.get(variable, "").strip()
+    if key:
+        return key, "env"
+    path = config_dir() / f"{name}.key"
+    return (path.read_text().strip(), "config") if path.is_file() else ("", "config")
+
+
+@dataclass(frozen=True)
+class Backend:
+    name: str
+    url: str
+    model: str
+    key_env: str
+    url_env: str | None = None
+    requires_key: bool = True
+    auto_select: bool = True
+    price_per_mtok: float = PRICE_PER_MTOK
+    cache_by_request: bool = False
+
+    @property
+    def key_file(self) -> Path:
+        return config_dir() / f"{self.name}.key"
+
+    @property
+    def url_file(self) -> Path:
+        return config_dir() / f"{self.name}.url"
+
+    def key(self) -> str | None:
+        # Retain the historical precedence of an explicitly set environment value.
+        if os.environ.get(self.key_env):
+            return os.environ[self.key_env].strip()
+        return self.key_file.read_text().strip() if self.key_file.exists() else None
+
+    def configured_url(self) -> str | None:
+        if not self.url_env:
+            return self.url
+        if os.environ.get(self.url_env):
+            return os.environ[self.url_env].strip()
+        return (self.url_file.read_text().strip() if self.url_file.exists() else None) or self.url or None
+
+    def endpoint(self) -> str:
+        return os.environ.get("JEV_URL") or self.configured_url() or self.url
+
+
+PROVIDERS = {
+    "typesafe": Backend("typesafe", "https://api.typesafe.ai/v1/systemone", "jev-latest", "TYPESAFE_API_KEY"),
+    "openrouter": Backend(
+        "openrouter",
+        "https://openrouter.ai/api/alpha/decisions",
+        "~typesafe/jev-latest",
+        "OPENROUTER_API_KEY",
+    ),
+    "gateway": Backend("gateway", "", "jev-latest", "JEV_GATEWAY_API_KEY", url_env="JEV_GATEWAY_URL"),
+    # Local servers are explicit opt-ins and never replace a configured hosted provider.
+    "diffusiongemma": Backend(
+        "diffusiongemma",
+        "http://127.0.0.1:8080/v1/systemone",
+        "openjev-latest",
+        "JEV_DIFFUSIONGEMMA_API_KEY",
+        url_env="JEV_DIFFUSIONGEMMA_URL",
+        requires_key=False,
+        auto_select=False,
+        price_per_mtok=float(os.environ.get("JEV_PRICE_PER_MTOK", 0)),
+        cache_by_request=True,
+    ),
+    "laya": Backend(
+        "laya",
+        "http://127.0.0.1:8081/v1/systemone",
+        "laya-421m",
+        "JEV_LAYA_API_KEY",
+        url_env="JEV_LAYA_URL",
+        requires_key=False,
+        auto_select=False,
+        price_per_mtok=float(os.environ.get("JEV_PRICE_PER_MTOK", 0)),
+    ),
+}
+
+
+def backend_catalog(
+    *names: str, models: dict[str, str] | None = None, backend_type: type[Backend] = Backend
+) -> dict[str, Backend]:
+    """Select providers in priority order, retaining tool-owned model defaults and adapters.
+
+    Both the mapping and its definitions are fresh, so a consumer's overrides never
+    change another consumer's catalog. Unknown providers or unused overrides fail early.
+    """
+    models = {} if models is None else models
+    if unknown := models.keys() - set(names):
+        raise ValueError(f"model overrides for unselected providers: {', '.join(sorted(unknown))}")
+    return {
+        name: backend_type(**(asdict(PROVIDERS[name]) | {"model": models.get(name, PROVIDERS[name].model)}))
+        for name in names
+    }
+
+
+def resolve_backend(
+    backends: dict[str, Backend], name: str | None = None, *, require_key: bool = True, help_suffix: str = ""
+) -> tuple[Backend, str]:
+    name = name or os.environ.get("JEV_API")
+    if name:
+        if name not in backends:
+            raise JevFatal(f"unknown API {name!r}; choose from {', '.join(backends)}")
+        backend = backends[name]
+        key = backend.key() or ""
+        if require_key and backend.requires_key and not key:
+            raise JevFatal(f"no key for {name}. Set {backend.key_env} or put the key in {backend.key_file}")
+        if backend.url_env and not backend.configured_url() and not os.environ.get("JEV_URL"):
+            raise JevFatal(
+                f"no URL for {name}. Set {backend.url_env} to the full System One endpoint "
+                f"(for example https://gateway.example.com/v1/systemone) or put it in {backend.url_file}"
+            )
+        return backend, key
+    for backend in backends.values():
+        if (
+            backend.auto_select
+            and (key := backend.key())
+            and (not backend.url_env or backend.configured_url())
+        ):
+            return backend, key
+    if not require_key:
+        return next(iter(backends.values())), ""
+    options = " or ".join(b.key_env for b in backends.values() if b.auto_select)
+    raise JevFatal(f"no API key. Set {options}, or put a key in {config_dir()}/<api>.key{help_suffix}")

jevkit_core/cache.py

@@ -0,0 +1,92 @@
+"""Thread-safe SQLite answers, compatible with the existing three-column table.
+
+Storage is shared; key identity is explicit. Existing tools retain their exact legacy
+key functions in adapters. New consumers may opt into the versioned answer_key.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sqlite3
+import threading
+import time
+from pathlib import Path
+
+
+def cache_path() -> Path:
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "jev" / "answers.sqlite"
+
+
+def digest(parts) -> str:
+    return hashlib.sha256(json.dumps(parts, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+
+
+def answer_key(model: str, state, question: dict, *, provider: str, endpoint: str) -> str:
+    """Opt-in v1 identity; no unsafe fallback to ambiguous legacy keys."""
+    return digest(["jevkit-answer-v1", provider, endpoint, model, state, question])
+
+
+class AnswerCache:
+    metadata = True
+
+    def __init__(self, path: Path | None = None):
+        path = Path(path) if path is not None else cache_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.db = sqlite3.connect(path, timeout=30, isolation_level=None, check_same_thread=False)
+        self._lock = threading.RLock()
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute("PRAGMA synchronous=NORMAL")
+        self.db.execute(
+            "CREATE TABLE IF NOT EXISTS answers "
+            "(key TEXT PRIMARY KEY, answer TEXT NOT NULL, at REAL NOT NULL) WITHOUT ROWID"
+        )
+        if self.metadata:
+            self.db.execute(
+                "CREATE TABLE IF NOT EXISTS answer_metadata "
+                "(key TEXT PRIMARY KEY, at REAL NOT NULL, metadata TEXT NOT NULL) WITHOUT ROWID"
+            )
+
+    def get(self, key: str) -> dict | None:
+        with self._lock:
+            row = self.db.execute("SELECT answer FROM answers WHERE key = ?", (key,)).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def get_entry(self, key: str) -> tuple[dict, dict] | None:
+        if not self.metadata:
+            answer = self.get(key)
+            return (answer, {}) if answer is not None else None
+        with self._lock:
+            row = self.db.execute(
+                "SELECT a.answer, m.metadata FROM answers a LEFT JOIN answer_metadata m "
+                "ON a.key = m.key AND a.at = m.at WHERE a.key = ?",
+                (key,),
+            ).fetchone()
+        return (json.loads(row[0]), json.loads(row[1]) if row[1] else {}) if row else None
+
+    def put(self, key: str, answer: dict, *, metadata: dict | None = None) -> None:
+        encoded = json.dumps(answer)
+        encoded_metadata = json.dumps(metadata) if metadata is not None else None
+        with self._lock:
+            at = time.time()
+            if not self.metadata:
+                self.db.execute("INSERT OR REPLACE INTO answers VALUES (?, ?, ?)", (key, encoded, at))
+                return
+            self.db.execute("BEGIN IMMEDIATE")
+            try:
+                self.db.execute("INSERT OR REPLACE INTO answers VALUES (?, ?, ?)", (key, encoded, at))
+                if metadata is not None:
+                    self.db.execute(
+                        "INSERT OR REPLACE INTO answer_metadata VALUES (?, ?, ?)", (key, at, encoded_metadata)
+                    )
+                else:
+                    self.db.execute("DELETE FROM answer_metadata WHERE key = ?", (key,))
+                self.db.execute("COMMIT")
+            except BaseException:
+                self.db.execute("ROLLBACK")
+                raise
+
+    def close(self) -> None:
+        with self._lock:
+            self.db.close()

jevkit_core/client.py

@@ -0,0 +1,109 @@
+"""Shared client lifecycle and transport; adapters own answer/request reuse semantics."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import os
+from collections.abc import Callable, Coroutine, Iterable
+from typing import Any, TypeVar
+
+import httpx
+
+from . import transport
+from .backends import Backend
+from .errors import JevError
+from .usage import Meter
+
+T = TypeVar("T")
+
+
+def validate_answer(qid: str, question: dict, answer) -> None:
+    if not isinstance(answer, dict):
+        raise JevError(f"invalid answer returned for question {qid!r}: expected an object")
+    if question.get("type") == "noul":
+        p = answer.get("noul")
+        if isinstance(p, bool) or not isinstance(p, (int, float)) or not math.isfinite(p) or not 0 <= p <= 1:
+            raise JevError(
+                f"invalid answer returned for question {qid!r}: noul must be a probability from 0 to 1"
+            )
+
+
+class DecisionClient:
+    def __init__(
+        self,
+        key: str,
+        backend: Backend,
+        *,
+        model: str | None = None,
+        timeout: float = 15.0,
+        attempts: int = 4,
+        concurrency: int = 32,
+        cache=None,
+        transport=None,
+        meter: Meter | None = None,
+        http2: bool = False,
+    ):
+        self.backend = backend
+        self.model = model or os.environ.get("JEV_MODEL") or backend.model
+        self.url = backend.endpoint()
+        self.timeout, self.attempts, self.cache = timeout, attempts, cache
+        self.meter = meter if meter is not None else Meter()
+        self._flights: dict[str, asyncio.Task] = {}
+        headers = {"X-Title": "jev tools"}
+        if key:
+            headers["Authorization"] = f"Bearer {key}"
+        limits = (
+            httpx.Limits(max_connections=16, max_keepalive_connections=16, keepalive_expiry=120)
+            if http2
+            else httpx.Limits(max_connections=concurrency + 4, max_keepalive_connections=concurrency + 4)
+        )
+        self.http = httpx.AsyncClient(
+            headers=headers, limits=limits, transport=transport, http2=http2 and transport is None
+        )
+
+    async def close(self) -> None:
+        await self.http.aclose()
+
+    def share_request(
+        self, keys: Iterable[str], start: Callable[[], Coroutine[Any, Any, T]]
+    ) -> tuple[asyncio.Task[T], bool]:
+        """Get an in-flight request and whether this caller started it.
+
+        Called on the client's event loop without yielding. The lazy factory runs
+        only for new requests, so admission checks and charge callbacks belong to
+        the owner. Callers keep their existing awaiting/cancellation or hedging policy.
+        """
+        flight = "|".join(sorted(keys))
+        if (task := self._flights.get(flight)) is not None:
+            self.meter.cached += 1
+            return task, False
+        task = asyncio.ensure_future(start())
+        self._flights[flight] = task
+
+        def discard(completed):
+            if self._flights.get(flight) is completed:
+                del self._flights[flight]
+
+        task.add_done_callback(discard)
+        return task, True
+
+    async def _call(self, state, questions: dict[str, dict], **kwargs):
+        body = {"model": self.model, "state": state, "questions": questions}
+
+        def retry():
+            self.meter.retries += 1
+
+        data, seconds = await transport.request_json(
+            self.http,
+            self.url,
+            body,
+            provider=self.backend.name,
+            timeout=self.timeout,
+            attempts=self.attempts,
+            on_retry=retry,
+        )
+        return self._record(state, questions, data, seconds, **kwargs)
+
+    def _record(self, state, questions, data, seconds, **kwargs):
+        raise NotImplementedError("the product adapter must record and validate its answer contract")

jevkit_core/errors.py

@@ -0,0 +1,22 @@
+"""Errors shared by all JevKit client adapters."""
+
+
+class JevError(Exception):
+    """One request failed; the rest of the run may continue."""
+
+
+class JevFatal(Exception):
+    """Stop the run until configuration, credentials, or metering is corrected."""
+
+
+class JevBudgetExceeded(Exception):
+    """No cached or in-flight answer exists and a new paid request is forbidden."""
+
+
+class RequestExhausted(JevError):
+    """Structured exhaustion details let each CLI retain its error wording."""
+
+    def __init__(self, timeout: float, last: str, *, timed_out: bool = False):
+        self.timeout, self.last = timeout, last
+        self.timed_out = timed_out
+        super().__init__(f"gave up after {timeout:g}s ({last})")

jevkit_core/provenance.py

@@ -0,0 +1,18 @@
+"""Answer origins shared by caches and saved results, independent of current defaults."""
+
+from __future__ import annotations
+
+import time
+
+
+def answer_provenance(*, provider: str, requested_model: str, resolved_model: object) -> dict:
+    """Record the responder literally; an absent model must never become the requested alias."""
+    return {
+        "version": 1,
+        "provider": provider,
+        "requested_model": requested_model,
+        "resolved_model": resolved_model
+        if isinstance(resolved_model, str) and resolved_model.strip()
+        else None,
+        "answered_at": time.time(),
+    }

jevkit_core/transport.py

@@ -0,0 +1,119 @@
+"""One HTTP retry and deadline implementation for all JevKit tools."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import random
+import time
+from dataclasses import dataclass
+
+import httpx
+
+from .errors import JevError, JevFatal, RequestExhausted
+
+RETRYABLE = frozenset({408, 429, 500, 502, 503, 504, 529})
+FATAL = frozenset({401, 402, 403})
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    delay: float = 0.2
+    jitter: float = 0.1
+    retry_after: bool = False
+    strict_json: bool = False
+    require_answers: bool = True
+    error_details: bool = True
+
+
+DEFAULT_RETRY_POLICY = RetryPolicy()
+
+
+def json_object(response: httpx.Response) -> dict:
+    try:
+        data = response.json()
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def error_detail(data: dict) -> str:
+    found = data.get("error", data.get("detail"))
+    if isinstance(found, list):
+        found = "; ".join(error_detail({"detail": item}) for item in found)
+    elif isinstance(found, dict):
+        found = found.get("message") or found.get("msg") or json.dumps(found)
+    return " ".join(str(found or "").split())[:200]
+
+
+async def request_json(
+    client: httpx.AsyncClient,
+    url: str,
+    body: dict,
+    *,
+    provider: str,
+    timeout: float = 15.0,
+    attempts: int = 4,
+    on_retry=None,
+    policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+) -> tuple[dict, float]:
+    if isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError("timeout must be positive and finite")
+    if isinstance(attempts, bool) or not isinstance(attempts, int) or attempts < 1:
+        raise ValueError("attempts must be a positive integer")
+    deadline = time.monotonic() + timeout
+    last = "no attempt made"
+    timed_out = False
+    for attempt in range(attempts):
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        started = time.perf_counter()
+        pause = policy.delay * 2**attempt + random.random() * policy.jitter
+        try:
+            response = await asyncio.wait_for(client.post(url, json=body, timeout=remaining), remaining)
+        except asyncio.TimeoutError:
+            last = "deadline exceeded"
+            timed_out = True
+            break
+        except httpx.TransportError as exc:
+            last = type(exc).__name__
+        else:
+            if response.status_code == 200 and policy.strict_json:
+                try:
+                    data = response.json()
+                except ValueError as exc:
+                    raise JevError("provider returned invalid JSON") from exc
+                if not isinstance(data, dict):
+                    raise JevError("provider returned a non-object response")
+            else:
+                data = json_object(response)
+            if response.status_code == 200 and (not policy.require_answers or "answers" in data):
+                return data, time.perf_counter() - started
+            if response.status_code in FATAL or (
+                response.status_code != 200 and response.status_code not in RETRYABLE
+            ):
+                error = JevFatal if response.status_code in FATAL else JevError
+                if not policy.error_details:
+                    raise error(f"{provider} returned HTTP {response.status_code}")
+                detail = error_detail(data) or response.text[:200]
+                message = (
+                    f"{provider} said {response.status_code}: {detail}"
+                    if error is JevFatal
+                    else f"HTTP {response.status_code}: {detail}"
+                )
+                raise error(message)
+            last = f"HTTP {response.status_code}"
+            if policy.retry_after:
+                try:
+                    retry_after = float(response.headers.get("Retry-After", 0))
+                    if math.isfinite(retry_after):
+                        pause = max(pause, retry_after)
+                except ValueError:
+                    pass
+        if attempt + 1 < attempts:
+            if on_retry is not None:
+                on_retry()
+            await asyncio.sleep(max(0.0, min(pause, deadline - time.monotonic())))
+    raise RequestExhausted(timeout, last, timed_out=timed_out)

jevkit_core/usage.py

@@ -0,0 +1,88 @@
+"""Validated usage and the common meter; budget policy remains with the caller."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, MutableMapping
+from dataclasses import dataclass, field
+
+from .backends import PRICE_PER_MTOK
+from .errors import JevFatal
+
+
+@dataclass(frozen=True)
+class Usage:
+    tokens: int | float
+    cost: float
+    source: str
+
+
+def record_usage(totals: MutableMapping, usage: Usage) -> None:
+    """Accumulate one validated response in existing meter or report fields."""
+    totals["calls"] += 1
+    totals["input_tokens"] += usage.tokens
+    totals["cost"] += usage.cost
+
+
+def parse_usage(
+    usage, *, price_per_mtok: float = PRICE_PER_MTOK, missing_tokens: int = 0, fractional_tokens: bool = False
+) -> Usage:
+    usage = {} if usage is None else usage
+    if not isinstance(usage, dict):
+        raise JevFatal("invalid API usage metadata: expected an object; stopped to avoid unmetered calls")
+    tokens = usage.get("input_tokens")
+    tokens = missing_tokens if tokens is None else tokens
+    valid_types = (int, float) if fractional_tokens else (int,)
+    if isinstance(tokens, bool) or not isinstance(tokens, valid_types) or tokens < 0:
+        raise JevFatal("invalid API usage metadata: input_tokens must be a nonnegative integer")
+    cost = usage.get("cost")
+    if cost is not None and (isinstance(cost, bool) or not isinstance(cost, (int, float))):
+        raise JevFatal("invalid API usage metadata: cost must be a finite nonnegative number")
+    try:
+        metered_cost = tokens * price_per_mtok / 1e6 if cost is None else float(cost)
+        valid = math.isfinite(tokens) and math.isfinite(metered_cost) and metered_cost >= 0
+    except OverflowError as exc:
+        raise JevFatal("invalid API usage metadata: cost exceeds numeric range") from exc
+    if not valid:
+        raise JevFatal("invalid API usage metadata: cost must be a finite nonnegative number")
+    return Usage(tokens, metered_cost, "estimated_from_tokens" if cost is None else "reported_by_api")
+
+
+@dataclass
+class Meter:
+    calls: int = 0
+    cached: int = 0
+    retries: int = 0
+    input_tokens: int = 0
+    cost: float = 0.0
+    model: str = ""
+    latencies: list[float] = field(default_factory=list)
+
+    def record(
+        self,
+        usage: Usage,
+        seconds: float,
+        *,
+        model: str | None = None,
+        on_cost: Callable[[float], None] | None = None,
+    ) -> None:
+        """Count the response before answer validation, including charges for invalid answers.
+
+        The request owner supplies on_cost; consumers of a shared request never
+        call it. Model fallback and tool-specific statistics remain adapter policy.
+        """
+        record_usage(vars(self), usage)
+        if on_cost is not None:
+            on_cost(usage.cost)
+        self.latencies.append(seconds)
+        if model is not None:
+            self.model = model
+
+    def summary(self) -> str:
+        parts = [f"{self.calls:,} calls, {self.cached:,} cached"]
+        if self.retries:
+            parts.append(f"{self.retries:,} retries")
+        if self.calls:
+            parts.append(f"{self.input_tokens:,} tokens")
+            parts.append(f"${self.cost:.4f}")
+        return "; ".join(parts)

jevkit_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: jevkit-runtime
+Version: 0.1.0
+Summary: Shared transport, configuration, caching, and accounting for JevKit tools
+Project-URL: Homepage, https://github.com/keltokhy/jevkit-core
+Project-URL: Issues, https://github.com/keltokhy/jevkit-core/issues
+Author: Khaled Eltokhy
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: http2
+Requires-Dist: httpx[http2]>=0.27; extra == 'http2'
+Description-Content-Type: text/markdown
+
+# JevKit core
+
+Distribution: **`jevkit-runtime`**. Python import: **`jevkit_core`**.
+The PyPI name `jevkit-core` belongs to a different project.
+
+Shared provider definitions, backend configuration, HTTP transport, retries, deadlines,
+SQLite answer storage, in-flight requests, usage accounting, and answer provenance
+for jgrep, jsort, jlink, jselect, and jcol.
+
+Each product remains a separate repository and package. This core imports none of them.
+Product adapters retain prompts, cache identities, reuse policies, budget policies, and public APIs.
+
+Version 0.1.0 is a **local development release**, not a published PyPI release.
+Ordinary source edits in an editable core installation apply on the next run;
+already-running Python processes need to restart.
+
+## Development
+
+Keep the six checkouts as siblings. Each consumer declares a normal versioned
+dependency on `jevkit-runtime` and a uv development override:
+
+```toml
+[tool.uv.sources]
+jevkit-runtime = { path = "../jevkit-core", editable = true }
+```
+
+Clone `keltokhy/jevkit-core` beside `keltokhy/jgrep`, `keltokhy/jsort`,
+`keltokhy/jlink`, `keltokhy/jselect`, and `keltokhy/jcol`. All six repositories
+remain independently versioned. For isolated development checkouts named
+`jgrep-jevkit` and so on, use the `--suffix=-jevkit` option shown below.
+
+From this directory:
+
+```bash
+python3 scripts/dev.py --suffix=-jevkit setup
+python3 scripts/dev.py --suffix=-jevkit check
+python3 scripts/dev.py --suffix=-jevkit wheel-check
+python3 scripts/dev.py --suffix=-jevkit run jgrep -- --help
+```
+
+`run` uses the selected worktree's virtual environment and preserves the caller's
+working directory. To use it with data, replace `--help` with the normal tool arguments.
+For ordinary unsuffixed clones, omit `--suffix`. `--repos-root` selects their parent;
+`--tool jgrep` limits setup and checks to one consumer.
+
+`setup` installs dependencies and prepares the public tiktoken encoding files needed
+by jselect. It performs no model inference. `check` runs each suite in its own
+environment, strips model credentials, isolates configuration/cache directories,
+and blocks outbound sockets while permitting local fake HTTP servers. It also proves
+that every consumer calls the shared transport and imports this exact source tree,
+and compares its fixture behavior to the commits in `consumer-baselines.json`.
+Those commits must be present locally; use a full clone or fetch that history.
+
+`wheel-check` builds the core and consumer wheels, installs each consumer alongside
+the core wheel in a separate temporary environment, and exercises model fixtures and
+CLI entry points outside the source trees. It also checks packaged browser/review assets
+and jcol's installed process workflow. Dependency installation may use the package index;
+inference checks stay offline.
+
+## Shared boundary
+
+| Module | Responsibility |
+|---|---|
+| `backends.py` | Provider catalog, credential/configuration lookup, capabilities, selection |
+| `transport.py` | HTTP requests, total deadlines, retries, JSON/error handling |
+| `client.py` | Client lifecycle, shared in-flight requests, transport delegation, common answer validation |
+| `cache.py` | SQLite answer storage and atomic provenance writes, key serialization |
+| `usage.py` | Usage validation, reported/estimated costs, meter and report accumulation |
+| `provenance.py` | Versioned answer origins with literal or unknown responder identity |
+| `errors.py` | Shared failure types and structured request exhaustion |
+
+`DecisionClient` is an adapter base, not a complete standalone scoring SDK. Product
+adapters supply their own `ask` and `_record` contracts. jselect calls the shared
+transport directly while retaining its relevance batching, score cache, and statistics.
+Tool-specific meter fields remain in small subclasses.
+
+`backend_catalog` selects provider definitions in each tool's priority order and
+accepts model overrides. The four decision clients retain moving model aliases;
+jselect keeps its pinned defaults. The catalog also defines two opt-in local providers; tools choose whether to expose them. Adding a catalog entry does not automatically enable it in every tool.
+
+`DecisionClient.share_request` returns a task and an ownership flag. It invokes a
+lazy request factory only for the owner, allowing jlink's cache-only callers to
+join existing requests and jsort to charge only the initiating caller. It removes
+finished, failed, and cancelled tasks from the registry. Awaiting, cancellation,
+cache identity, and jcol's hedging policy remain with the adapters; sharing does
+not introduce cancellation shielding or change how a hedge is charged.
+
+`Meter.record` and `record_usage` accumulate the same call/token/cost fields for
+the four clients and jselect's dictionary reports. Meter callbacks run after
+totals change and before latency/model updates. Cost-source labels, jsort's
+maximum call cost, jlink's provenance summaries, and model fallback remain local.
+`answer_provenance` constructs the shared version-1 metadata for jsort and jlink;
+missing responder identity stays unknown rather than inheriting a requested alias.
+
+No product imports another product, and the core imports none of them. NumPy,
+pandas, SciPy, Polars, tokenizers, and browser dependencies stay in their owning
+tools. HTTP/2 is an optional core extra used by jcol.
+
+## Compatibility
+
+- Existing prompts, CLI flags, supported backend choices, cache-key bytes, and
+  saved project/scale/index formats are retained by the adapters.
+- Existing `~/.config/jev` and cache locations continue to work. No user cache or
+  credential files were opened or migrated during development.
+- Legacy answer keys remain explicitly tool-owned. The shared `answer_key` function
+  offers an opt-in, versioned provider/endpoint identity for future consumers; it
+  never falls back to an ambiguous legacy entry. In particular, jlink's existing
+  cross-backend cache behavior has not silently changed.
+- jcol checkpoints and jselect's score cache remain separate from shared answer storage.
+- Budget meanings remain local: zero is unlimited for jgrep/jsort, cache-only for
+  jlink, and rejected by jselect's semantic scorer. jcol retains its scheduler policy.
+- The separate experimental jgrep branch retains joint-read caching and keyless
+  local backends. The main-branch migration exposes its original three providers;
+  unrelated experiments and benchmark graphics are not part of that migration.
+- All clients now use a true total HTTP deadline. jlink and jcol previously passed
+  the remaining time only to httpx's individual network waits.
+- All five use validated usage parsing. Malformed, negative, nonfinite, or boolean
+  usage values fail rather than corrupting accounting; jselect retains its
+  fractional-token and missing-token estimate policy.
+
+These last two points are deliberate hardening accompanying the extraction.
+The adapter tests remain the source of truth for each tool's external behavior.
+
+## Cross-repository validation
+
+```bash
+python3 scripts/dev.py --suffix=-jevkit check
+```
+
+For a before/after request, result, and metering comparison, use a consumer's
+environment with `scripts/probe_consumer.py TOOL --baseline-repo PATH --baseline-ref COMMIT`.
+The probe covers cold/warm caches, repeated requests, in-flight sharing, typed
+jcol answers, and provider definitions/defaults. It verifies shared accounting
+for all five, request sharing for the four decision clients, and provenance
+construction for jsort/jlink. It is a focused compatibility fixture, not an
+exhaustive equivalence proof.
+
+The core CI tests Python 3.10 and 3.13. The downstream workflow tests the exact
+core revision against all five consumer main branches in separate jobs, including
+wheel installs. Pull-request and main-push runs are enabled with the repository
+variable `JEVKIT_CONSUMERS_READY=true` after bootstrap. Manual dispatch can select
+a common consumer branch/tag before then. All five consumer repositories are public.
+
+## Release sequence
+
+The five packages retain independent releases. Their wheels contain a dependency
+on `jevkit-runtime>=0.1.0,<0.2.0`, never a local source path; jcol requests the `http2` extra.
+
+Before publishing any migrated consumer to PyPI:
+
+1. Merge and tag the verified core as `v0.1.0`. Consumer CI checks out this tag
+   beside its own source, so tests do not depend on PyPI publication timing.
+2. Configure a PyPI Trusted Publisher for `jevkit-runtime`, repository
+   `keltokhy/jevkit-core`, workflow `publish.yml`, environment `pypi`. Dispatch the
+   publish workflow with the verified release tag. Publishing is explicit; creating
+   a Git tag alone does not upload a package.
+3. Release each consumer through its existing versioning/publishing process. Update
+   its supported core range, lockfile, and CI core reference together on upgrades.
+
+Until the runtime distribution is available on PyPI, source development uses the
+sibling checkout. The cross-repository wheel checks install a freshly built core
+wheel explicitly alongside each consumer. Existing published tool versions remain
+independent of this migration. Once the runtime is published, standalone source
+clones can use `uv sync --no-sources`; published wheels use ordinary dependencies.

jevkit_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+jevkit_core/__init__.py,sha256=3JmP7EnIt2rNdIEAHSWomld17d2sN9k6te0WeOgvP54,1121
+jevkit_core/backends.py,sha256=FaB_4Q9BcchJyYlq5nwKsN7RN0orOogXuY74Vu3BFUs,5295
+jevkit_core/cache.py,sha256=NtCQULEM9JN3pyGGoCJEgWsj1LjrRhDnWb9PMG0kCeU,3665
+jevkit_core/client.py,sha256=sEmoSP34FL8EVIMopWxh0RAuwLA2yGu6_D63iNhNuBI,3820
+jevkit_core/errors.py,sha256=BzER95nTOIZIWCxouLuow3_3zhtrE_vTSZEfh9mFlLI,721
+jevkit_core/provenance.py,sha256=CudRdmRUy49ti14lpvTSbf9T0a1POm_U4nzBOK5ic4A,614
+jevkit_core/transport.py,sha256=X_hpAjyiEPOwcZ_bmHQhFH9KNJcOuKr4PV77tw86JSI,4277
+jevkit_core/usage.py,sha256=osTO8nn6d3c5DHm0r2EW9Zlk1G-jfCoDpdq2QXqB6n8,3264
+jevkit_runtime-0.1.0.dist-info/METADATA,sha256=4ffDl434VIdLCwMOXT6uvyrfp8HmtywhrzXAHjthMuo,9758
+jevkit_runtime-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+jevkit_runtime-0.1.0.dist-info/licenses/LICENSE,sha256=unAu2Ii_6qZZfNfkD44Vj0MNv9C7H6CBRje23cMNx4g,1071
+jevkit_runtime-0.1.0.dist-info/RECORD,,

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

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