claude-subprocess 0.1.1__py3-none-any.whl

claude_cli/__init__.py

@@ -0,0 +1,89 @@
+"""claude-cli — one hardened wrapper around the local ``claude -p`` CLI.
+
+Subscription/OAuth auth (no ``ANTHROPIC_API_KEY``), a locked-down surface, both
+output formats, JSON extraction from prose replies, and a sha256 response cache.
+See :mod:`claude_cli.runner` for the invariants this library exists to protect.
+"""
+
+from .batch import pack_batches, run_chunks
+from .cache import (
+    CacheStore,
+    DictCacheStore,
+    FileCacheStore,
+    cache_key,
+    cached_run,
+    normalize_prompt,
+)
+from .errors import ClaudeCliError, NotLoggedInError, UsageLimitError
+from .parsing import (
+    extract_json,
+    extract_json_or_none,
+    parse_envelope,
+    parse_stream,
+    strip_fences,
+)
+from .preflight import (
+    BENCHMARKS,
+    CONSTRAINTS,
+    GUIDES,
+    MATRIX,
+    QUOTA_FREE_SUBCOMMANDS,
+    TIERS,
+    doctor,
+    dry_run_plan,
+    health,
+    quota_status,
+    simulate,
+)
+from .runner import (
+    MODELS,
+    ClaudeCliProvider,
+    ClaudeResult,
+    LLMProvider,
+    arun_claude,
+    build_args,
+    claude_available,
+    ping,
+    run_claude,
+    stream_claude,
+)
+
+__all__ = [
+    "BENCHMARKS",
+    "CONSTRAINTS",
+    "GUIDES",
+    "MATRIX",
+    "MODELS",
+    "QUOTA_FREE_SUBCOMMANDS",
+    "TIERS",
+    "CacheStore",
+    "ClaudeCliError",
+    "ClaudeCliProvider",
+    "ClaudeResult",
+    "DictCacheStore",
+    "FileCacheStore",
+    "LLMProvider",
+    "NotLoggedInError",
+    "UsageLimitError",
+    "arun_claude",
+    "build_args",
+    "cache_key",
+    "cached_run",
+    "claude_available",
+    "doctor",
+    "dry_run_plan",
+    "extract_json",
+    "extract_json_or_none",
+    "health",
+    "normalize_prompt",
+    "pack_batches",
+    "parse_envelope",
+    "parse_stream",
+    "ping",
+    "quota_status",
+    "run_chunks",
+    "run_claude",
+    "simulate",
+    "stream_claude",
+    "strip_fences",
+]

claude_cli/batch.py

@@ -0,0 +1,88 @@
+"""Batch helpers: pack items into prompt-sized chunks, and run a call per chunk."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+
+def pack_batches(
+    items: Iterable[Any],
+    budget: int,
+    *,
+    size_of: Callable[[Any], int],
+    max_items: int = 0,
+) -> list[list[Any]]:
+    """Greedily pack ``items`` into batches within a size budget, order preserved.
+
+    A batch is closed when adding the next item would push it over ``budget``
+    (chars, tokens — whatever ``size_of`` counts) or over ``max_items``. Both
+    caps are disabled when ``<= 0``. A batch always holds at least one item, so
+    an item larger than ``budget`` on its own rides alone.
+    """
+    batches: list[list[Any]] = []
+    cur: list[Any] = []
+    cur_size = 0
+    for item in items:
+        size = size_of(item)
+        over_count = max_items > 0 and len(cur) + 1 > max_items
+        over_budget = budget > 0 and cur_size + size > budget
+        if cur and (over_count or over_budget):
+            batches.append(cur)
+            cur, cur_size = [], 0
+        cur.append(item)
+        cur_size += size
+    if cur:
+        batches.append(cur)
+    return batches
+
+
+def run_chunks(
+    chunks: Iterable[Any],
+    fn: Callable[[Any], tuple[Any, float]],
+    *,
+    label: Callable[[Any], str],
+    workers: int = 1,
+    progress: Callable[..., Iterable] | None = None,
+) -> tuple[list, float, list[str]]:
+    """Apply ``fn(chunk) -> (data, cost)`` over ``chunks``, optionally in parallel.
+
+    Each call shells out to a ``claude`` subprocess, so threads give real
+    concurrency (the GIL is released during ``subprocess.run``).
+
+    Returns ``(results, total_cost, failed_labels)``. A chunk that raises is
+    recorded in ``failed_labels`` and skipped — one bad chunk never aborts the
+    batch.
+    """
+    chunks = list(chunks)
+    results, spent, failed = [], 0.0, []
+
+    def _record(produce: Callable[[], tuple[Any, float]], chunk) -> None:
+        nonlocal spent
+        try:
+            data, cost = produce()
+        except Exception as exc:  # noqa: BLE001 — keep the batch alive
+            failed.append(f"{label(chunk)}: {type(exc).__name__}: {str(exc)[:120]}")
+            return
+        spent += cost or 0.0
+        results.append(data)
+
+    if workers <= 1:
+        iterator = progress(chunks) if progress else chunks
+        for chunk in iterator:
+            _record(lambda c=chunk: fn(c), chunk)
+        return results, spent, failed
+
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        futs = {ex.submit(fn, c): c for c in chunks}
+        stream = as_completed(futs)
+        if progress:
+            stream = progress(stream, total=len(futs))
+        for fut in stream:
+            _record(fut.result, futs[fut])
+    return results, spent, failed

claude_cli/cache.py

@@ -0,0 +1,206 @@
+"""Response cache: a sha256 key plus a tiny pluggable store.
+
+Every consumer wants the same thing — never pay for the same prompt twice — so
+the key recipe and the sqlite table live here once. :class:`FileCacheStore` needs
+no server (a single sqlite file, ``CREATE TABLE IF NOT EXISTS``, safe to point at
+an existing db); :class:`DictCacheStore` is the in-memory one for tests.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import sqlite3
+from contextlib import closing
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Protocol
+
+log = logging.getLogger(__name__)
+
+
+def normalize_prompt(prompt: str) -> str:
+    """Collapse whitespace so trivially different prompts share a cache key."""
+    return " ".join(prompt.split())
+
+
+def cache_key(
+    model: str,
+    prompt: str,
+    *,
+    schema: str = "",
+    version: str = "",
+    purpose: str = "",
+    tools: str = "",
+) -> str:
+    """sha256 over model + normalized prompt + optional schema/version/purpose/tools.
+
+    Optional parts are folded in only when non-empty, so adding a dimension later
+    never invalidates rows that never used it. Each part is labeled so equal
+    values in different dimensions (schema="x" vs version="x") never collide.
+    ``tools`` matters because a tools-on (web-search-grounded) call must not
+    share a row with a tools-off one.
+    """
+    parts = [model, normalize_prompt(prompt)]
+    named = (("schema", schema), ("version", version), ("purpose", purpose), ("tools", tools))
+    parts += [f"{name}={value}" for name, value in named if value]
+    return hashlib.sha256("\x00".join(parts).encode("utf-8")).hexdigest()
+
+
+class CacheStore(Protocol):
+    """What :func:`cached_run` needs from a backend."""
+
+    def get(self, key: str) -> str | None: ...
+
+    def put(self, key: str, text: str, **meta) -> None: ...
+
+
+# Namespaced on purpose: consumers point FileCacheStore at existing db files, and
+# a generic name like `llm_cache` can collide with a project's own table of the
+# same name but a different schema (CREATE IF NOT EXISTS would no-op, INSERT
+# would then fail at runtime).
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS claude_cli_cache (
+    key TEXT PRIMARY KEY,
+    model TEXT,
+    purpose TEXT,
+    prompt TEXT,
+    response TEXT NOT NULL,
+    cost_usd REAL,
+    duration_ms INTEGER,
+    created_at TEXT NOT NULL
+)
+"""
+
+
+class FileCacheStore:
+    """A local sqlite3 file — no server, so caching never silently no-ops.
+
+    sqlite3 calls are synchronous but cost microseconds against a local file, so
+    there is no thread pool or aiosqlite here.
+    """
+
+    def __init__(self, path: str | Path, *, max_age_days: int | None = None) -> None:
+        """``max_age_days`` expires rows on read; None (default) keeps them forever.
+
+        A row is never deleted here — an expired hit is simply ignored, so the next
+        call re-asks and overwrites it. That keeps ``created_at`` history intact and
+        avoids a delete path that could lose a still-valid answer on a clock skew.
+        """
+        self.path = Path(path).expanduser()
+        self.max_age_days = max_age_days
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with closing(self._connect()) as conn:
+            conn.execute(_SCHEMA)
+            conn.commit()
+
+    def _connect(self) -> sqlite3.Connection:
+        # sqlite3's own context manager only manages the transaction — closing()
+        # is what actually releases the file handle after each call.
+        return sqlite3.connect(self.path)
+
+    def get(self, key: str) -> str | None:
+        with closing(self._connect()) as conn:
+            row = conn.execute(
+                "SELECT response, created_at FROM claude_cli_cache WHERE key = ?", (key,)
+            ).fetchone()
+        if row is None:
+            return None
+        return row[0] if self._fresh(row[1]) else None
+
+    def _fresh(self, created_at: str | None) -> bool:
+        if self.max_age_days is None:
+            return True
+        try:
+            written = datetime.fromisoformat(created_at or "")
+        except ValueError:  # unparseable timestamp: treat as expired, re-ask rather than trust
+            return False
+        if written.tzinfo is None:  # naive row (hand-written/legacy): assume UTC, never TypeError
+            written = written.replace(tzinfo=timezone.utc)
+        age = datetime.now(timezone.utc) - written
+        return age <= timedelta(days=self.max_age_days)
+
+    def put(self, key: str, text: str, **meta) -> None:
+        with closing(self._connect()) as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO claude_cli_cache "
+                "(key, model, purpose, prompt, response, cost_usd, duration_ms, created_at) "
+                "VALUES (?,?,?,?,?,?,?,?)",
+                (
+                    key,
+                    meta.get("model"),
+                    meta.get("purpose"),
+                    meta.get("prompt"),
+                    text,
+                    meta.get("cost_usd"),
+                    meta.get("duration_ms"),
+                    datetime.now(timezone.utc).isoformat(),
+                ),
+            )
+            conn.commit()
+
+
+class DictCacheStore:
+    """In-memory store for tests."""
+
+    def __init__(self) -> None:
+        self.rows: dict[str, str] = {}
+        self.meta: dict[str, dict] = {}
+
+    def get(self, key: str) -> str | None:
+        return self.rows.get(key)
+
+    def put(self, key: str, text: str, **meta) -> None:
+        self.rows[key] = text
+        self.meta[key] = meta
+
+
+#: run_claude kwargs that change which upstream answers (profile/config dir, provider, remote...).
+_ROUTING_KWARGS = ("tier", "provider", "profile", "remote", "base_url", "context")
+
+
+def cached_run(
+    runner,
+    store: CacheStore,
+    prompt: str,
+    *,
+    model: str = "sonnet",
+    schema: str = "",
+    version: str = "",
+    purpose: str = "",
+    refresh: bool = False,
+    store_prompt: bool = False,
+    **kwargs,
+) -> str:
+    """Call ``runner(prompt, model=..., **kwargs)`` behind ``store``; return the text.
+
+    ``runner`` is :func:`claude_cli.runner.run_claude` (or any callable returning
+    a :class:`~claude_cli.runner.ClaudeResult`). A cache-write failure is logged,
+    never raised — a broken cache must not fail an answer we already have.
+
+    ``store_prompt`` is opt-in: prompts often embed privacy-gated payloads, so by
+    default only the sha256 key touches disk and the ``prompt`` column stays NULL.
+    Callers needing hit/miss visibility use ``store.get``/``store.put`` directly.
+    """
+    # Routing kwargs pick a different upstream model, so they must split the key;
+    # folded into the model part only when set, so existing rows stay valid.
+    routing = ",".join(f"{k}={kwargs[k]}" for k in _ROUTING_KWARGS if kwargs.get(k))
+    key = cache_key(
+        f"{model}|{routing}" if routing else model, prompt, schema=schema,
+        version=version, purpose=purpose, tools=kwargs.get("tools", ""),
+    )
+    if not refresh:
+        hit = store.get(key)
+        if hit is not None:
+            log.debug("llm cache hit %s", purpose or key[:8])
+            return hit
+    result = runner(prompt, model=model, **kwargs)
+    try:
+        store.put(
+            key, result.text, model=model, purpose=purpose,
+            prompt=prompt if store_prompt else None,
+            cost_usd=result.cost_usd, duration_ms=result.duration_ms,
+        )
+    except (sqlite3.Error, OSError) as exc:
+        log.warning("llm cache write failed: %s", exc)
+    return result.text

claude_cli/errors.py

@@ -0,0 +1,44 @@
+"""Exceptions raised by the runner.
+
+All derive from :class:`ClaudeCliError`, itself a ``RuntimeError`` subclass — so
+existing callers that ``except RuntimeError`` to degrade gracefully (the
+finance-insights rules-only fallback, chat-watch's regex-only mode) keep working
+unchanged.
+"""
+
+from __future__ import annotations
+
+
+class ClaudeCliError(RuntimeError):
+    """The ``claude`` CLI exited non-zero, timed out, or reported an error.
+
+    ``stdout`` carries the raw CLI output of the failed run (empty when there
+    was none, e.g. a timeout) — consumers that archive failing runs for
+    inspection read it instead of losing the stream.
+    """
+
+    def __init__(self, message: str, *, stdout: str = "") -> None:
+        super().__init__(message)
+        self.stdout = stdout
+
+
+class NotLoggedInError(ClaudeCliError):
+    """The CLI reported "Not logged in" — run ``claude`` once and ``/login``."""
+
+
+class UsageLimitError(ClaudeCliError):
+    """A usage/rate/session limit was hit.
+
+    ``session_wide`` says whether the limit ends the whole run or just this call.
+    Behind an OmniRoute combo it is ``False``: the limit belongs to ONE upstream
+    (target #1 of the chain), the gateway still has other targets, and the next
+    call may well succeed — so a batch must skip this item, not abort. It is
+    ``True`` only for a direct ``claude`` call, where the limited subscription is
+    the only route there is and every further call would hit the same wall.
+
+    The caller owns the abort policy; this class only reports which case it is.
+    """
+
+    def __init__(self, message: str, *, stdout: str = "", session_wide: bool = True) -> None:
+        super().__init__(message, stdout=stdout)
+        self.session_wide = session_wide

claude_cli/http_api.py

@@ -0,0 +1,102 @@
+"""OmniRoute HTTP route: tool-less calls skip the `claude` subprocess.
+
+``POST /v1/chat/completions`` (OpenAI format) on the local gateway. No ``temperature``
+is ever sent: that would switch on OmniRoute's own semantic cache, whose key ignores
+system prompt and tools. No API key -> the route is silently off.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from .errors import ClaudeCliError
+from .runner import ClaudeResult
+
+log = logging.getLogger(__name__)
+
+# alias -> combo, the same mapping the gateway applies to `--model` for the CLI;
+# any other value (a bare combo name) passes through unchanged
+COMBOS = {"haiku": "free-stack", "sonnet": "free-stack", "opus": "hard"}
+COOLDOWN_SECS = 600
+ENV_FILE = Path.home() / ".omniroute" / ".env"
+
+_down_until = 0.0  # ponytail: per process, not per model; a dead gateway costs one timeout per window
+
+
+class HttpLlmError(ClaudeCliError):
+    """The HTTP route failed (transport, status, body); run_claude falls back to the CLI."""
+
+
+def api_key() -> str | None:
+    """OMNIROUTE_API_KEY from the env, else from ~/.omniroute/.env (never logged)."""
+    if key := os.environ.get("OMNIROUTE_API_KEY"):
+        return key
+    try:
+        for line in ENV_FILE.read_text().splitlines():
+            name, _, value = line.partition("=")
+            if name.strip() == "OMNIROUTE_API_KEY":
+                return value.strip().strip("\"'") or None
+    except OSError:
+        pass
+    return None
+
+
+def omniroute_chat(prompt: str, *, model: str = "sonnet", timeout: float = 300,
+                   system_prompt: str | None = None, **_ignored) -> ClaudeResult:
+    """One chat completion, ClaudeResult-shaped. CLI-only knobs (effort, cwd...) are ignored."""
+    key = api_key()
+    if not key:
+        raise HttpLlmError("no OMNIROUTE_API_KEY")
+    url = os.environ.get("OMNIROUTE_URL", "http://localhost:20128") + "/v1/chat/completions"
+    messages = [{"role": "user", "content": prompt}]
+    if system_prompt:
+        messages.insert(0, {"role": "system", "content": system_prompt})
+    body = json.dumps({"model": COMBOS.get(model, model), "messages": messages}).encode()
+    req = urllib.request.Request(url, body, {
+        "Authorization": f"Bearer {key}", "Content-Type": "application/json"})
+    t0 = time.monotonic()
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.load(resp)
+        text = data["choices"][0]["message"]["content"]
+    except urllib.error.HTTPError as exc:  # 401 key, 422 body, 429/503 busy
+        raise HttpLlmError(f"HTTP {exc.code} from {url}") from exc
+    except (OSError, ValueError, KeyError, IndexError, TypeError) as exc:
+        raise HttpLlmError(f"{type(exc).__name__}: {exc}") from exc
+    if not isinstance(text, str) or not text.strip():
+        raise HttpLlmError("empty completion")
+    # raw keeps the OpenAI body, but `usage` in the CLI envelope's keys so meters read it
+    usage = data.get("usage") or {}
+    raw = {**data, "usage": {"input_tokens": usage.get("prompt_tokens"),
+                             "output_tokens": usage.get("completion_tokens")}}
+    return ClaudeResult(text=text, cost_usd=0.0, raw=raw,
+                        duration_ms=int((time.monotonic() - t0) * 1000))
+
+
+def try_http(prompt: str, *, backend: str, cli_only: bool, **kw) -> ClaudeResult | None:
+    """The HTTP answer, or None when run_claude should use the CLI.
+
+    ``backend``: "cli" never, "api" always (errors propagate, no cooldown), "auto" when
+    a key exists, the gateway is not cooling down and the call needs nothing CLI-only.
+    """
+    global _down_until
+    backend = os.environ.get("CLAUDE_CLI_BACKEND") or backend
+    if backend == "cli" or cli_only:
+        return None
+    if backend == "api":
+        return omniroute_chat(prompt, **kw)
+    if time.monotonic() < _down_until or not api_key():
+        return None
+    try:
+        return omniroute_chat(prompt, **kw)
+    except HttpLlmError as exc:
+        _down_until = time.monotonic() + COOLDOWN_SECS
+        log.warning("omniroute http failed (%s); CLI fallback, http off for %ds",
+                    exc, COOLDOWN_SECS)
+        return None