smartpipe-cli 1.3.0__py3-none-any.whl

smartpipe/models/anthropic_adapter.py

@@ -0,0 +1,149 @@
+"""Anthropic (Claude) adapter via the official SDK — an optional extra.
+
+Project policy (plan/decisions.md D04): Claude calls go through the ``anthropic``
+SDK, not raw HTTP. The SDK is lazy-imported so the core install stays SDK-free; a
+``claude-*`` model without the extra produces the actionable missing-extra screen.
+The SDK owns its own retries and credential resolution (``ANTHROPIC_API_KEY``,
+``ANTHROPIC_AUTH_TOKEN``, ``ant`` profiles) — we never pre-check the env var, and a
+rejected key surfaces as the key screen at request time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from smartpipe.cli import screens
+from smartpipe.core.errors import ItemError, SetupFault
+from smartpipe.core.jsontools import as_str, record_at
+from smartpipe.io import metering
+from smartpipe.models.base import AudioData, ImageData
+
+if TYPE_CHECKING:
+    from smartpipe.models.base import CompletionRequest, ModelRef
+
+__all__ = [
+    "AnthropicChatModel",
+    "build_anthropic_chat_model",
+    "build_kwargs",
+    "load_anthropic_client",
+]
+
+_TIMEOUT_SECONDS = 120.0
+# The SDK's built-in retries already honor Retry-After on 429 (unlike our raw-httpx
+# adapters, which route the header through retry.with_retries' delay_hint).
+_MAX_RETRIES = 3
+
+
+def load_anthropic_client(model: str) -> Any:
+    try:
+        import anthropic
+    except ImportError as exc:
+        raise SetupFault(screens.missing_anthropic_extra(model)) from exc
+    try:
+        return anthropic.AsyncAnthropic(timeout=_TIMEOUT_SECONDS, max_retries=_MAX_RETRIES)
+    except anthropic.AnthropicError as exc:  # e.g. no credentials resolvable at all
+        raise SetupFault(_key_screen(model)) from exc
+
+
+def _key_screen(model: str) -> str:
+    return screens.missing_api_key(model, "Anthropic", "ANTHROPIC_API_KEY", "sk-ant-...")
+
+
+def build_anthropic_chat_model(ref: ModelRef) -> AnthropicChatModel:
+    return AnthropicChatModel(ref=ref, client=load_anthropic_client(ref.name))
+
+
+@dataclass(frozen=True, slots=True)
+class AnthropicChatModel:
+    ref: ModelRef
+    client: Any  # anthropic.AsyncAnthropic — untyped here to keep the SDK a soft dependency
+
+    async def complete(self, request: CompletionRequest) -> str:
+        import anthropic
+
+        kwargs = build_kwargs(self.ref.name, request)
+        try:
+            metering.add_request_media(request.media)
+            message = await self.client.messages.create(**kwargs)
+        except (anthropic.AuthenticationError, anthropic.PermissionDeniedError) as exc:
+            raise SetupFault(_key_screen(self.ref.name)) from exc
+        except anthropic.APIConnectionError as exc:
+            raise SetupFault(
+                f"error: can't reach the Anthropic API ({exc})\n"
+                f"  The model '{self.ref}' needs api.anthropic.com.\n"
+                "  Check your network connection and try again."
+            ) from exc
+        except anthropic.APIStatusError as exc:
+            raise ItemError(f"anthropic error {exc.status_code}: {_status_detail(exc)}") from exc
+        return _reply_text(self.ref.name, message)
+
+
+def build_kwargs(name: str, request: CompletionRequest) -> dict[str, object]:
+    kwargs: dict[str, object] = {
+        "model": name,
+        "max_tokens": request.max_tokens,
+        "temperature": request.temperature,  # reproducible by default (D36)
+        "messages": [{"role": "user", "content": _user_content(request)}],
+    }
+    if request.system is not None:
+        kwargs["system"] = request.system
+    if request.json_schema is not None:
+        kwargs["output_config"] = {
+            "format": {"type": "json_schema", "schema": dict(request.json_schema)}
+        }
+    return kwargs
+
+
+def _user_content(request: CompletionRequest) -> str | list[dict[str, object]]:
+    """Plain string normally; image blocks (image first) when media rides along."""
+    if not request.media:
+        return request.user
+    if any(isinstance(part, AudioData) for part in request.media):
+        # the messages API has no audio input — fail before any bytes leave (D20 §2)
+        raise ItemError(
+            "this model can't hear audio — try an audio model "
+            "(voxtral, gemini) — smartpipe transcribes locally otherwise"
+        )
+    import base64
+
+    blocks: list[dict[str, object]] = [
+        {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": part.mime,
+                "data": base64.b64encode(part.data).decode(),
+            },
+        }
+        for part in request.media
+        if isinstance(part, ImageData)
+    ]
+    blocks.append({"type": "text", "text": request.user})
+    return blocks
+
+
+def _reply_text(name: str, message: Any) -> str:
+    if getattr(message, "stop_reason", None) == "refusal":
+        raise ItemError(f"the model '{name}' declined this item")
+    blocks = getattr(message, "content", []) or []
+    text = "".join(block.text for block in blocks if getattr(block, "type", None) == "text")
+    if not text:
+        raise ItemError(f"the model '{name}' returned an empty reply")
+    usage = getattr(message, "usage", None)
+    tokens_in = getattr(usage, "input_tokens", None)
+    tokens_out = getattr(usage, "output_tokens", None)
+    metering.add_tokens(
+        tokens_in=tokens_in if isinstance(tokens_in, int) else 0,
+        tokens_out=tokens_out if isinstance(tokens_out, int) else 0,
+    )
+    return text
+
+
+def _status_detail(exc: Any) -> str:
+    error = record_at(getattr(exc, "body", None), "error")
+    message = as_str(error.get("message")) if error is not None else None
+    if message is not None:
+        return message
+    fallback = getattr(exc, "message", None)
+    return fallback if isinstance(fallback, str) else str(exc)

smartpipe/models/base.py

@@ -0,0 +1,170 @@
+"""Provider-neutral model contracts (plan/architecture.md "Provider abstraction").
+
+Routing rule (plan/decisions.md D04, refined): ``provider/name`` is explicit for
+the four known providers; bare names route by shape — ``claude-*`` → anthropic,
+``gpt-*``/o-series/``text-embedding-*`` → openai, the Mistral family prefixes
+(``mistral-``, ``codestral-``, ``pixtral-`` …) → mistral, everything else → ollama.
+Unknown ``x/y`` prefixes are NOT errors: Ollama supports namespaced model names
+(``someuser/model:tag``, ``hf.co/org/model``), so they route to ollama whole —
+which is also why ``hf.co/mistralai/...`` must never be hijacked by the bare-name
+prefixes (the slash form wins first).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, Protocol, TypeGuard, runtime_checkable
+
+from smartpipe.core.errors import UsageFault
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+__all__ = [
+    "AudioData",
+    "ChatModel",
+    "CompletionRequest",
+    "EmbeddingModel",
+    "ImageData",
+    "MediaData",
+    "MediaEmbeddingModel",
+    "ModelRef",
+    "Provider",
+    "VideoData",
+    "parse_model_ref",
+    "supports_media_embedding",
+]
+
+Provider = Literal[
+    "local", "ollama", "openai", "anthropic", "mistral", "gemini", "openrouter", "jina"
+]
+
+_OPENAI_PREFIXES = ("gpt-", "chatgpt-", "text-embedding-")
+_OPENAI_O_SERIES = re.compile(r"o\d")
+_MISTRAL_PREFIXES = (
+    "mistral-",  # also covers mistral-embed
+    "ministral-",
+    "codestral-",
+    "magistral-",
+    "devstral-",
+    "pixtral-",
+    "voxtral-",  # the audio family — found missing by the live smoke
+    "open-mistral-",
+    "open-mixtral-",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ImageData:
+    data: bytes
+    mime: str
+
+
+@dataclass(frozen=True, slots=True)
+class VideoData:
+    """Raw video bytes + mime — converted to frames + track before any wire (D27)."""
+
+    data: bytes
+    mime: str
+
+
+@dataclass(frozen=True, slots=True)
+class AudioData:
+    data: bytes
+    mime: str  # audio/mpeg · audio/wav · audio/mp4 · audio/ogg · audio/flac
+
+
+# The D20 union: ONE optional media field on Item/CompletionRequest, dispatched
+# with match + assert_never. VideoData is reserved, not added — no wired provider
+# carries video on our wires (capability follows wire).
+MediaData = ImageData | AudioData | VideoData
+
+
+@dataclass(frozen=True, slots=True)
+class ModelRef:
+    provider: Provider
+    name: str  # passed through to the backend verbatim — smartpipe keeps no registry
+
+    def __str__(self) -> str:
+        return f"{self.provider}/{self.name}"
+
+
+@dataclass(frozen=True, slots=True)
+class CompletionRequest:
+    system: str | None
+    user: str
+    json_schema: Mapping[str, object] | None = None  # provider-native structured output
+    max_tokens: int = 8192
+    temperature: float = 0.0  # a pipe is a data tool — reproducible by default (D36)
+    presence_penalty: float | None = None  # anti-rambling; prose-only (D35)
+    frequency_penalty: float | None = None  # never on schema calls — penalties corrupt JSON
+    media: tuple[MediaData, ...] = ()  # vision/audio (bytes + mime; D20 union)
+
+
+class ChatModel(Protocol):
+    # A read-only property (not a bare attribute) so frozen-dataclass adapters,
+    # whose fields pyright treats as read-only, structurally satisfy the Protocol.
+    @property
+    def ref(self) -> ModelRef: ...
+
+    async def complete(self, request: CompletionRequest) -> str: ...
+
+
+@runtime_checkable
+class MediaEmbeddingModel(Protocol):
+    """An embedder that takes text AND images in one space (D39/04) — the
+    mention of such a model is the switch away from the caption pivot."""
+
+    @property
+    def ref(self) -> ModelRef: ...
+
+    async def embed_parts(
+        self, parts: Sequence[str | ImageData]
+    ) -> tuple[tuple[float, ...], ...]: ...
+
+
+def supports_media_embedding(model: object) -> TypeGuard[MediaEmbeddingModel]:
+    return isinstance(model, MediaEmbeddingModel)
+
+
+class EmbeddingModel(Protocol):
+    @property
+    def ref(self) -> ModelRef: ...
+
+    async def embed(self, texts: Sequence[str]) -> tuple[tuple[float, ...], ...]: ...
+
+
+def parse_model_ref(text: str) -> ModelRef:
+    cleaned = text.strip()
+    if not cleaned:
+        raise UsageFault("no model given — try: --model ollama/qwen3:8b")
+    prefix, slash, rest = cleaned.partition("/")
+    if slash:
+        match prefix:
+            case (
+                "local"
+                | "ollama"
+                | "openai"
+                | "anthropic"
+                | "mistral"
+                | "gemini"
+                | "openrouter"
+                | "jina"
+            ):
+                if not rest:
+                    raise UsageFault(f"model '{cleaned}' is missing a name after '{prefix}/'")
+                return ModelRef(provider=prefix, name=rest)
+            case _:
+                pass  # a namespaced ollama model name — fall through to shape routing
+    if cleaned.startswith("claude"):
+        return ModelRef(provider="anthropic", name=cleaned)
+    if cleaned.startswith(_OPENAI_PREFIXES) or _OPENAI_O_SERIES.match(cleaned):
+        return ModelRef(provider="openai", name=cleaned)
+    if not slash and cleaned.startswith(_MISTRAL_PREFIXES):
+        return ModelRef(provider="mistral", name=cleaned)
+    if not slash and cleaned.startswith("gemini-"):
+        return ModelRef(provider="gemini", name=cleaned)
+    # openrouter is explicit-only: its names ARE other vendors' names — a bare
+    # prefix would hijack every routing rule above (D24 commit)
+    return ModelRef(provider="ollama", name=cleaned)

smartpipe/models/budget.py

@@ -0,0 +1,94 @@
+"""``--max-calls`` (D18): a hard ceiling on model calls.
+
+The budget wraps models at the composition root, so verbs stay ignorant. One
+charge = one model call (a repair re-ask charges again; wire retries of the same
+call, inside ``with_retries``, do not — the wrapper sits outside them).
+
+Two exhaustion behaviors, pinned in ux.md: with a ``stop`` event (the per-item
+verbs' drain machinery) the limit call still runs, intake stops, and any racing
+in-flight worker skips its item; without one (whole-set verbs — a partial
+collection is nothing usable) exhaustion is fatal with the fix screen.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from smartpipe.core.errors import ItemError, SetupFault
+
+if TYPE_CHECKING:
+    import asyncio
+    from collections.abc import Sequence
+
+    from smartpipe.models.base import ChatModel, CompletionRequest, EmbeddingModel, ModelRef
+
+__all__ = ["CallBudget", "budgeted_chat", "budgeted_embed"]
+
+
+@dataclass(slots=True)
+class CallBudget:
+    """Mutable by design (documented Spinner-style exception): the counter is
+    per-run state shared by every model the container hands out."""
+
+    limit: int
+    stop: asyncio.Event | None  # per-item verbs trip intake; None = whole-set (fatal)
+    calls: int = 0
+    exhausted: bool = False
+
+    def __post_init__(self) -> None:
+        if self.limit < 1:
+            raise ValueError(f"--max-calls must be >= 1, got {self.limit}")
+
+    def charge(self) -> None:
+        if self.calls >= self.limit:
+            self.exhausted = True
+            if self.stop is None:
+                raise SetupFault(
+                    f"error: call budget reached mid-collection (--max-calls {self.limit})\n"
+                    "  This verb needs every item before it can produce a result — a cap\n"
+                    "  that stops early leaves nothing usable.\n"
+                    "  Raise --max-calls, shrink the input, or drop the cap."
+                )
+            raise ItemError(f"call budget reached (--max-calls {self.limit})")
+        self.calls += 1
+        if self.calls >= self.limit:
+            self.exhausted = True
+            if self.stop is not None:
+                self.stop.set()  # the limit call runs; nothing new starts
+
+
+@dataclass(frozen=True, slots=True)
+class _BudgetedChat:
+    inner: ChatModel
+    budget: CallBudget
+
+    @property
+    def ref(self) -> ModelRef:
+        return self.inner.ref
+
+    async def complete(self, request: CompletionRequest) -> str:
+        self.budget.charge()
+        return await self.inner.complete(request)
+
+
+@dataclass(frozen=True, slots=True)
+class _BudgetedEmbed:
+    inner: EmbeddingModel
+    budget: CallBudget
+
+    @property
+    def ref(self) -> ModelRef:
+        return self.inner.ref
+
+    async def embed(self, texts: Sequence[str]) -> tuple[tuple[float, ...], ...]:
+        self.budget.charge()
+        return await self.inner.embed(texts)
+
+
+def budgeted_chat(inner: ChatModel, budget: CallBudget) -> ChatModel:
+    return _BudgetedChat(inner, budget)
+
+
+def budgeted_embed(inner: EmbeddingModel, budget: CallBudget) -> EmbeddingModel:
+    return _BudgetedEmbed(inner, budget)

smartpipe/models/cache.py

@@ -0,0 +1,132 @@
+"""Result caching for chat completions (D38/15, KQL ``materialize``).
+
+Iteration stops re-paying unchanged work. Sound because of D36: temperature
+is 0.0 everywhere, so identical request → identical reply is the contract.
+The cache wraps OUTSIDE the call budget — a hit costs nothing and must not
+count against ``--max-calls`` (the belt caps spend, not answers).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from smartpipe.models.base import ChatModel, CompletionRequest, ModelRef
+
+__all__ = ["CachingChatModel", "cache_key", "sweep"]
+
+
+def cache_key(ref: ModelRef, request: CompletionRequest) -> str:
+    """Anything that changes the reply changes the key."""
+    payload: dict[str, object] = {
+        "provider": ref.provider,
+        "model": ref.name,
+        "system": request.system,
+        "user": request.user,
+        "schema": request.json_schema,
+        "temperature": request.temperature,
+        "presence": request.presence_penalty,
+        "frequency": request.frequency_penalty,
+        "max_tokens": request.max_tokens,
+        "media": [(part.mime, hashlib.sha256(part.data).hexdigest()) for part in request.media],
+    }
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+class CachingChatModel:
+    """ChatModel-shaped wrapper: hit → stored reply, miss → inner + store."""
+
+    def __init__(self, inner: ChatModel, directory: Path) -> None:
+        self.inner = inner
+        self.directory = directory
+        self.hits = 0
+        self.misses = 0
+
+    @property
+    def ref(self) -> ModelRef:
+        return self.inner.ref
+
+    async def complete(self, request: CompletionRequest) -> str:
+        key = cache_key(self.inner.ref, request)
+        path = self.directory / key[:2] / f"{key}.json"
+        stored = _read(path)
+        if stored is not None:
+            self.hits += 1
+            return stored
+        reply = await self.inner.complete(request)
+        self.misses += 1
+        _write(path, reply)
+        return reply
+
+
+def _read(path: Path) -> str | None:
+    try:
+        parsed: object = json.loads(path.read_text(encoding="utf-8"))
+        os.utime(path)  # a hit refreshes recency — the LRU truth (D39/02)
+    except (OSError, json.JSONDecodeError):
+        return None  # missing or corrupt — a miss, never a crash
+    from smartpipe.core.jsontools import as_record
+
+    record = as_record(parsed)
+    if record is not None:
+        reply = record.get("reply")
+        if isinstance(reply, str):
+            return reply
+    return None
+
+
+def _write(path: Path, reply: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    scratch = path.with_suffix(".tmp")
+    scratch.write_text(json.dumps({"reply": reply}, ensure_ascii=False), encoding="utf-8")
+    os.replace(scratch, path)  # atomic on POSIX — never a half-written entry
+
+
+_DAY_SECONDS = 86_400
+
+
+def sweep(directory: Path, *, ttl_days: int, max_mb: int, now: float) -> tuple[int, int]:
+    """Expire entries past the TTL, then LRU-evict (oldest mtime first) until
+    under the size cap. Returns (entries removed, bytes removed). Pure walk —
+    the caller owns the once-a-day gating and error tolerance."""
+    entries: list[tuple[float, int, Path]] = []
+    for path in directory.rglob("*.json"):
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+        entries.append((stat.st_mtime, stat.st_size, path))
+    removed = 0
+    freed = 0
+    survivors: list[tuple[float, int, Path]] = []
+    horizon = now - ttl_days * _DAY_SECONDS
+    for mtime, size, path in entries:
+        if mtime < horizon:
+            try:
+                path.unlink()
+                removed += 1
+                freed += size
+            except OSError:
+                survivors.append((mtime, size, path))
+        else:
+            survivors.append((mtime, size, path))
+    survivors.sort()  # oldest first
+    total = sum(size for _mtime, size, _path in survivors)
+    cap = max_mb * 1_048_576
+    for _mtime, size, path in survivors:
+        if total <= cap:
+            break
+        try:
+            path.unlink()
+            removed += 1
+            freed += size
+            total -= size
+        except OSError:
+            continue
+    return removed, freed