kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/catalog.py

@@ -0,0 +1,445 @@
+"""Live model catalogs fetched from provider APIs.
+
+Model ids drift fast: providers ship new ones every few weeks and retire old
+ones without warning. The curated tuples in :mod:`kiwimatecoder.providers` are
+only a shipped-at-build-time starting point, so this module asks each provider
+what it actually serves today via ``GET {base_url}/models`` and turns the answer
+into the list ``/model`` offers.
+
+Two rules shape the result:
+
+* **New models are added.** Anything the provider lists is offered, ordered
+  newest-first so freshly released ids surface at the top.
+* **Deprecated models are removed.** Only ids present in the live listing
+  survive, so a retired model disappears from ``/model`` on the next refresh
+  even if it is still hard-coded in the curated catalog.
+
+Listings are filtered to models this CLI can actually drive: text chat models
+that support tool calling. Embedding, audio, image, and moderation endpoints are
+dropped by name, and provider metadata (OpenRouter's ``supported_parameters`` /
+``architecture``, Mistral's ``capabilities``) is honored when present.
+
+Nothing here touches disk; :mod:`kiwimatecoder.config` owns the cache that keeps
+``/model`` from hitting the network on every invocation.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from kiwimatecoder import network
+from kiwimatecoder.providers import ProviderConfig
+
+# A catalog older than this is refetched the next time the models are shown.
+CATALOG_TTL_SECONDS = 24 * 60 * 60
+# After a failed fetch, don't retry automatically for this long (an explicit
+# `/model refresh` always retries). Keeps `/model` snappy when offline.
+FAILURE_BACKOFF_SECONDS = 30 * 60
+# Model listings are small; a short timeout keeps a hung provider from blocking
+# the selector.
+FETCH_TIMEOUT = 8.0
+# Server-detection probes (setup wizard) should feel instant.
+PROBE_TIMEOUT = 0.75
+# Gateways such as OpenRouter serve hundreds of models. Offer the newest slice
+# in the selector — any id can still be set by name with `/model <id>`.
+MAX_CATALOG_MODELS = 60
+ANTHROPIC_VERSION = "2023-06-01"
+
+# Substrings that mark an id as something other than a text chat model. Matched
+# case-insensitively against the model id.
+NON_CHAT_MARKERS = (
+    "embed",
+    "rerank",
+    "moderation",
+    "guard",
+    "whisper",
+    "audio",
+    "speech",
+    "transcribe",
+    "voice",
+    "tts",
+    "dall-e",
+    "image",
+    "imagen",
+    "video",
+    "veo",
+    "sora",
+    "diffusion",
+    "flux",
+    "clip",
+    "ocr",
+)
+
+
+class CatalogFetchError(RuntimeError):
+    """Raised when a provider's model listing cannot be retrieved or parsed."""
+
+
+@dataclass(frozen=True)
+class RemoteModel:
+    """One model as reported by a provider's listing endpoint."""
+
+    id: str
+    created: float = 0.0  # epoch seconds; 0 when the provider reports no date
+
+
+@dataclass(frozen=True)
+class ModelCatalog:
+    """The model list offered for a provider, plus how it was obtained.
+
+    ``source`` is ``"live"`` (just fetched), ``"cache"`` (a previous fetch), or
+    ``"curated"`` (the tuple shipped in the registry). ``added`` and ``removed``
+    are only populated for a live fetch and describe the change against the
+    previously known catalog — ``removed`` is the list of deprecated ids that
+    just dropped out of ``/model``.
+    """
+
+    provider_id: str
+    models: list[str]
+    source: str
+    fetched_at: float | None = None
+    added: list[str] = field(default_factory=list)
+    removed: list[str] = field(default_factory=list)
+    error: str | None = None
+
+
+def models_url(provider: ProviderConfig) -> str:
+    """Return the listing endpoint for ``provider`` (with any api-version)."""
+    return provider.versioned_url(f"{provider.base_url.rstrip('/')}/models")
+
+
+def request_headers(provider: ProviderConfig, api_key: str | None) -> dict[str, str]:
+    """Build auth headers for a listing request.
+
+    Anthropic's native API wants ``x-api-key`` plus a version header; every
+    OpenAI-compatible provider uses its configured ``key_header``/``key_prefix``
+    (``Authorization: Bearer`` by default, ``api-key`` for Azure). Provider
+    ``extra_headers`` are applied last so a custom provider can override
+    anything.
+    """
+    headers = {"Accept": "application/json"}
+    if provider.compat == "anthropic":
+        headers["anthropic-version"] = ANTHROPIC_VERSION
+        if api_key:
+            headers["x-api-key"] = api_key
+    elif api_key:
+        headers[provider.key_header] = f"{provider.key_prefix}{api_key}"
+    headers.update(provider.extra_headers)
+    return headers
+
+
+def request_params(provider: ProviderConfig) -> dict[str, str | int]:
+    """Return query params for the listing request."""
+    if provider.compat == "anthropic":
+        # Anthropic paginates at 20 by default; 1000 is the documented maximum
+        # and comfortably covers the whole catalog in one request.
+        return {"limit": 1000}
+    return {}
+
+
+def _parse_timestamp(value: object) -> float:
+    """Coerce a provider timestamp (epoch seconds or ISO 8601) to a float."""
+    if isinstance(value, bool):
+        return 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            return datetime.fromisoformat(value.strip().replace("Z", "+00:00")).timestamp()
+        except ValueError:
+            return 0.0
+    return 0.0
+
+
+def normalize_model_id(raw: object) -> str:
+    """Normalize a listed id to the form the chat endpoint expects.
+
+    Google's OpenAI-compatible listing returns ``models/gemini-...`` while its
+    chat endpoint expects the bare id, so the prefix is stripped.
+    """
+    model_id = str(raw or "").strip()
+    if model_id.startswith("models/"):
+        model_id = model_id[len("models/") :]
+    return model_id
+
+
+# Name fragments that mark an id as a model of the given media kind; used only
+# when the provider's listing has no modality metadata.
+MEDIA_NAME_MARKERS: dict[str, tuple[str, ...]] = {
+    "image": ("image", "imagen", "dall-e", "flux", "diffusion"),
+    "video": ("video", "veo", "sora"),
+}
+
+
+def is_chat_model(
+    entry: dict[str, Any], model_id: str, *, require_tools: bool = True
+) -> bool:
+    """Return whether a listed model is a text chat model this CLI can drive.
+
+    Provider metadata wins when present; otherwise the id is matched against
+    :data:`NON_CHAT_MARKERS`. Tool calling is required — the agent loop is built
+    on it — so a provider that reports ``supported_parameters`` without
+    ``tools`` (OpenRouter does this for every entry) is filtered out, unless
+    ``require_tools`` is off for a chat-only provider.
+    """
+    lowered = model_id.lower()
+    if not lowered or any(marker in lowered for marker in NON_CHAT_MARKERS):
+        return False
+
+    capabilities = entry.get("capabilities")
+    if isinstance(capabilities, dict):
+        chat = capabilities.get("completion_chat")
+        if chat is False:
+            return False
+        if require_tools and capabilities.get("function_calling") is False:
+            return False
+
+    architecture = entry.get("architecture")
+    if isinstance(architecture, dict):
+        outputs = architecture.get("output_modalities")
+        if isinstance(outputs, list) and outputs and "text" not in outputs:
+            return False
+        inputs = architecture.get("input_modalities")
+        if isinstance(inputs, list) and inputs and "text" not in inputs:
+            return False
+
+    supported = entry.get("supported_parameters")
+    if (
+        require_tools
+        and isinstance(supported, list)
+        and supported
+        and "tools" not in supported
+    ):
+        return False
+
+    return True
+
+
+def is_media_model(entry: dict[str, Any], model_id: str, kind: str) -> bool:
+    """Return whether a listed model produces ``kind`` ("image" or "video").
+
+    ``architecture.output_modalities`` wins when the provider reports it
+    (OpenRouter does); otherwise the id is matched against
+    :data:`MEDIA_NAME_MARKERS`.
+    """
+    lowered = model_id.lower()
+    if not lowered:
+        return False
+    architecture = entry.get("architecture")
+    if isinstance(architecture, dict):
+        outputs = architecture.get("output_modalities")
+        if isinstance(outputs, list) and outputs:
+            return kind in outputs
+    return any(marker in lowered for marker in MEDIA_NAME_MARKERS[kind])
+
+
+def parse_models_response(
+    payload: object, *, require_tools: bool = True, kind: str = "chat"
+) -> list[RemoteModel]:
+    """Extract usable models of ``kind`` (chat by default) from a provider's listing payload.
+
+    Accepts the OpenAI shape (``{"data": [...]}``), a bare list, or a
+    ``{"models": [...]}`` variant, and tolerates entries that are plain strings.
+    Unusable entries are skipped rather than raising, so one odd record cannot
+    break the whole catalog. ``require_tools`` is passed to
+    :func:`is_chat_model`.
+    """
+    if isinstance(payload, dict):
+        entries = payload.get("data")
+        if not isinstance(entries, list):
+            entries = payload.get("models")
+    else:
+        entries = payload
+    if not isinstance(entries, list):
+        return []
+
+    models: dict[str, RemoteModel] = {}
+    for raw_entry in entries:
+        if isinstance(raw_entry, str):
+            entry: dict[str, Any] = {"id": raw_entry}
+        elif isinstance(raw_entry, dict):
+            entry = raw_entry
+        else:
+            continue
+
+        model_id = normalize_model_id(entry.get("id") or entry.get("name"))
+        if not model_id or model_id in models:
+            continue
+        if kind == "chat":
+            usable = is_chat_model(entry, model_id, require_tools=require_tools)
+        else:
+            usable = is_media_model(entry, model_id, kind)
+        if not usable:
+            continue
+
+        created = _parse_timestamp(
+            entry.get("created")
+            if entry.get("created") is not None
+            else entry.get("created_at")
+        )
+        models[model_id] = RemoteModel(id=model_id, created=created)
+
+    return list(models.values())
+
+
+def fetch_models(
+    provider: ProviderConfig,
+    api_key: str | None = None,
+    *,
+    timeout: float = FETCH_TIMEOUT,
+    transport: httpx.BaseTransport | None = None,
+    kind: str = "chat",
+) -> list[RemoteModel]:
+    """Fetch and parse ``provider``'s live model listing.
+
+    Raises :class:`CatalogFetchError` for any transport, status, payload, or
+    "nothing usable came back" failure so callers have a single thing to catch.
+    ``transport`` is an injection point for tests.
+    """
+    if not provider.is_local and network.offline_enabled():
+        raise CatalogFetchError(
+            f"{provider.name}: {network.offline_message('model catalog fetch')}"
+        )
+    url = models_url(provider)
+    try:
+        with httpx.Client(
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=True,
+            **network.current_options(),
+        ) as client:
+            response = client.get(
+                url,
+                headers=request_headers(provider, api_key),
+                # ``params={}`` would drop an api-version already in the URL.
+                params=request_params(provider) or None,
+            )
+    except httpx.HTTPError as exc:
+        raise CatalogFetchError(f"{provider.name}: {exc}") from exc
+
+    if response.status_code != 200:
+        body = response.text[:200].replace("\n", " ").strip()
+        raise CatalogFetchError(
+            f"{provider.name} returned HTTP {response.status_code} for {url}"
+            + (f": {body}" if body else "")
+        )
+
+    try:
+        payload = response.json()
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise CatalogFetchError(
+            f"{provider.name} returned a non-JSON model list from {url}"
+        ) from exc
+
+    models = parse_models_response(
+        payload, require_tools=provider.supports_tools, kind=kind
+    )
+    if not models:
+        raise CatalogFetchError(f"{provider.name} listed no usable {kind} models")
+    return models
+
+
+def probe(
+    provider: ProviderConfig,
+    *,
+    api_key: str | None = None,
+    timeout: float = PROBE_TIMEOUT,
+    transport: httpx.BaseTransport | None = None,
+) -> bool:
+    """Return whether ``provider``'s server answers a listing request right now.
+
+    Used to annotate local providers in the setup wizard; never raises. Any
+    200 counts as "running", even when no models are loaded yet — that is a
+    server the user can still pull models into. A 401 also counts as running
+    for providers that enforce auth (Unsloth): the server is up, only the key
+    is missing — and it may not exist yet when the wizard first probes.
+
+    With offline mode on, cloud providers are reported as not running without a
+    request; local servers are still probed so the setup wizard keeps working.
+    """
+    if not provider.is_local and network.offline_enabled():
+        return False
+    try:
+        with httpx.Client(
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=True,
+            **network.current_options(),
+        ) as client:
+            response = client.get(
+                models_url(provider),
+                headers=request_headers(provider, api_key),
+                params=request_params(provider) or None,
+            )
+    except httpx.HTTPError:
+        return False
+    if response.status_code == 200:
+        return True
+    return response.status_code == 401 and provider.requires_key
+
+
+def search_models(models: Sequence[str], query: str) -> list[str]:
+    """Filter ``models`` to ids whose name matches every token of ``query``.
+
+    Matching is a case-insensitive substring test per whitespace-separated
+    token, combined with AND — ``search claude sonnet`` matches
+    ``anthropic/claude-sonnet-5``. An empty or blank query returns everything,
+    so callers can treat it as "no filter".
+    """
+    tokens = [token for token in query.lower().split() if token]
+    if not tokens:
+        return list(models)
+    return [
+        model_id
+        for model_id in models
+        if all(token in model_id.lower() for token in tokens)
+    ]
+
+
+def summarize_ids(model_ids: Sequence[str], limit: int = 8) -> str:
+    """Join model ids for display, trimming long lists to ``limit`` entries.
+
+    A first refresh can add dozens of models at once; printing all of them
+    buries the part the user cares about.
+    """
+    shown = ", ".join(model_ids[:limit])
+    extra = len(model_ids) - limit
+    return f"{shown}, +{extra} more" if extra > 0 else shown
+
+
+def merge_catalog(
+    provider: ProviderConfig,
+    remote: Iterable[RemoteModel],
+    *,
+    keep: Sequence[str] = (),
+    limit: int | None = MAX_CATALOG_MODELS,
+) -> list[str]:
+    """Turn a live listing into the catalog ``/model`` should offer.
+
+    Caller-supplied ``keep`` ids such as the session's current model come
+    first, then the rest newest-first. There is no default model to pin: the
+    user chooses. Only ids the provider still lists survive — that is how
+    deprecated models leave the catalog — so ``keep`` can pin a model but never
+    resurrect a retired one.
+    """
+    ordered = [model.id for model in sorted(remote, key=lambda m: -m.created)]
+    live = set(ordered)
+
+    pinned = list(
+        dict.fromkeys(
+            model
+            for model in keep
+            if model and model in live
+        )
+    )
+    rest = [model for model in ordered if model not in set(pinned)]
+    catalog = pinned + rest
+    if limit is not None and limit > 0:
+        catalog = catalog[:limit]
+    return catalog

kiwimatecoder/checkpoints.py

@@ -0,0 +1,103 @@
+"""Per-tool file snapshots backing ``/undo`` and ``/rewind``.
+
+Before a mutating tool runs, the target files are copied into a per-session
+temporary directory. A checkpoint records where each pre-change snapshot lives
+(``None`` means the file did not exist yet, so undo removes it). Restoring is
+best-effort and never raises on a single unreadable file.
+"""
+
+from __future__ import annotations
+
+import datetime
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _resolve(relative: str, workspace_root: Path) -> Path | None:
+    """Resolve inside the workspace without a circular import at module load."""
+    from kiwimatecoder.tools.paths import PathError, resolve_in_workspace
+
+    try:
+        return resolve_in_workspace(relative, workspace_root)
+    except PathError:
+        return None
+
+
+@dataclass
+class Checkpoint:
+    """A snapshot of files captured before one mutating tool call."""
+
+    id: int
+    label: str
+    created_at: str
+    # Workspace-relative path -> snapshot file path, or None when absent.
+    files: dict[str, str | None] = field(default_factory=dict)
+
+    @property
+    def paths(self) -> list[str]:
+        return list(self.files)
+
+
+class CheckpointStore:
+    """Captures and restores file snapshots for one session."""
+
+    def __init__(self, snapshot_root: Path | None = None) -> None:
+        self._root = snapshot_root or Path(
+            tempfile.mkdtemp(prefix="kiwimatecoder-checkpoints-")
+        )
+        self._counter = 0
+
+    def capture(
+        self, workspace_root: Path, paths: list[str], label: str
+    ) -> Checkpoint:
+        """Snapshot ``paths`` as they are right now and return the checkpoint."""
+        self._counter += 1
+        files: dict[str, str | None] = {}
+        for raw in paths:
+            relative = str(raw).strip()
+            if not relative or relative in files:
+                continue
+            target = _resolve(relative, workspace_root)
+            if target is None:
+                continue
+            if target.is_file():
+                dest = self._root / str(self._counter) / f"{len(files)}.snap"
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                try:
+                    shutil.copyfile(target, dest)
+                except OSError:
+                    continue
+                files[relative] = str(dest)
+            else:
+                files[relative] = None
+        return Checkpoint(
+            id=self._counter,
+            label=label,
+            created_at=datetime.datetime.now().isoformat(),
+            files=files,
+        )
+
+    def restore(self, workspace_root: Path, checkpoint: Checkpoint) -> list[str]:
+        """Restore the checkpoint's files; returns the paths actually changed."""
+        restored: list[str] = []
+        for relative, snapshot in checkpoint.files.items():
+            target = _resolve(relative, workspace_root)
+            if target is None:
+                continue
+            if snapshot is None:
+                try:
+                    if target.exists():
+                        target.unlink()
+                        restored.append(relative)
+                except OSError:
+                    continue
+            else:
+                try:
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copyfile(snapshot, target)
+                    restored.append(relative)
+                except OSError:
+                    continue
+        return restored