induscode 0.1.0__py3-none-any.whl

induscode/conductor/catalog.py

@@ -0,0 +1,309 @@
+"""Model catalog — :class:`ModelCatalog` (port of TS ``src/conductor/catalog/catalog.ts``).
+
+A transform pipeline over the framework model list. The framework publishes
+its catalog per provider via :func:`indusagi.ai.get_models`; each entry is a
+rich :class:`indusagi.ai.Model` record. This module **re-derives** that data
+into the conductor's own normalized shape — a :class:`CatalogCard` — through a
+validate → normalize → key pipeline, then exposes a small lookup surface
+(:meth:`ModelCatalog.all`, :meth:`ModelCatalog.by_provider`,
+:meth:`ModelCatalog.get`) keyed by a canonical ``"provider/modelId"`` id.
+
+The full framework :class:`~indusagi.ai.Model` is retained on each card so the
+conductor can hand a complete model object to the agent without a second
+registry round-trip.
+
+Port notes
+----------
+- The TS zod gate (``rawModelGate.safeParse``) becomes a **manual tolerant
+  probe** (:func:`_clears_gate`): a malformed provider record is silently
+  DROPPED, never raised on. pydantic is deliberately not pulled in for six
+  field checks. # parity: the gate drops invalid cards — it must never throw.
+- Raw records may be the framework's frozen :class:`~indusagi.ai.Model`
+  dataclasses (the live source) *or* plain mappings (test sources); every
+  field read goes through the tolerant :func:`_field_of` accessor, mirroring
+  how zod validated plain objects structurally.
+- TS ``z.<type>().optional()`` admits *undefined* but rejects *null*; the
+  Python probe mirrors that by distinguishing an absent field (passes) from a
+  present ``None`` (rejects).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from indusagi.ai import get_models, get_providers
+
+from induscode.conductor.contract import ModelCardRef
+
+__all__ = [
+    "CatalogCard",
+    "CatalogSource",
+    "ModelCatalog",
+    "canonical_id",
+    "to_card_ref",
+]
+
+
+# ---------------------------------------------------------------------------
+# Card shape
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogCard:
+    """One normalized entry in the catalog (TS ``CatalogCard``).
+
+    Extends the lightweight :class:`~induscode.conductor.contract.ModelCardRef`
+    identity projection with the extra capability facets the matcher filters
+    on, plus the original framework ``Model``. ``ref`` is the slice a UI
+    lists/labels with; ``model`` is the full record the conductor binds to the
+    agent. Field names keep the TS spelling.
+    """
+
+    # Canonical "provider/modelId" identifier — the catalog key.
+    id: str
+    # Owning provider slug.
+    provider: str
+    # Provider-scoped model id (e.g. "claude-sonnet-4").
+    modelId: str
+    # Human-readable display name.
+    name: str
+    # Whether the model exposes a reasoning/thinking budget.
+    reasoning: bool
+    # Whether the model accepts image input.
+    acceptsImages: bool
+    # Context window size in tokens (0 when the framework omits it).
+    contextTokens: int
+    # The framework model record, retained verbatim for binding.
+    model: Any
+
+
+def to_card_ref(card: CatalogCard) -> ModelCardRef:
+    """Project a :class:`CatalogCard` down to its public ``ModelCardRef`` slice."""
+    return ModelCardRef(
+        id=card.id,
+        provider=card.provider,
+        modelId=card.modelId,
+        name=card.name,
+        reasoning=card.reasoning,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Validation gate (the zod gate, hand-probed)
+# ---------------------------------------------------------------------------
+
+#: Sentinel marking "field not present at all" (TS ``undefined``).
+_ABSENT: Any = object()
+
+
+def _field_of(raw: Any, name: str) -> Any:
+    """Read ``name`` off a raw record — mapping key or dataclass attribute —
+    returning :data:`_ABSENT` when the field does not exist."""
+    if isinstance(raw, Mapping):
+        return raw.get(name, _ABSENT)
+    return getattr(raw, name, _ABSENT)
+
+
+def _is_nonempty_str(value: Any) -> bool:
+    return isinstance(value, str) and len(value) >= 1
+
+
+def _clears_gate(raw: Any) -> bool:
+    """The minimal slice of a framework ``Model`` the catalog depends on.
+
+    Run every raw record through this gate so a malformed provider entry is
+    dropped rather than poisoning lookups downstream. Unknown extra fields are
+    tolerated (only named keys are read). Mirrors the TS zod gate exactly:
+
+    - ``id`` / ``name`` / ``provider``: required non-empty strings
+      (``provider`` admits any non-empty string, matching ``z.string()`` over
+      the ``KnownProvider | string`` union);
+    - ``reasoning``: optional bool;
+    - ``input``: optional array of strings;
+    - ``contextWindow``: optional number.
+    """
+    if raw is None or isinstance(raw, (str, int, float, bool)):
+        return False
+    if not _is_nonempty_str(_field_of(raw, "id")):
+        return False
+    if not _is_nonempty_str(_field_of(raw, "name")):
+        return False
+    if not _is_nonempty_str(_field_of(raw, "provider")):
+        return False
+    reasoning = _field_of(raw, "reasoning")
+    if reasoning is not _ABSENT and not isinstance(reasoning, bool):
+        return False
+    inputs = _field_of(raw, "input")
+    if inputs is not _ABSENT:
+        if not isinstance(inputs, Sequence) or isinstance(inputs, (str, bytes)):
+            return False
+        if not all(isinstance(item, str) for item in inputs):
+            return False
+    context_window = _field_of(raw, "contextWindow")
+    if context_window is not _ABSENT and (
+        isinstance(context_window, bool) or not isinstance(context_window, (int, float))
+    ):
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Pipeline helpers
+# ---------------------------------------------------------------------------
+
+
+def canonical_id(provider: str, model_id: str) -> str:
+    """Compose the canonical catalog key from a provider + model id."""
+    return f"{provider}/{model_id}"
+
+
+def _normalize_card(raw: Any) -> CatalogCard:
+    """Normalize one validated raw record into a :class:`CatalogCard`.
+
+    Pure: the same input always yields the same card. Capability flags are
+    derived defensively from the (optional) framework fields.
+    """
+    provider = str(_field_of(raw, "provider"))
+    model_id = _field_of(raw, "id")
+    raw_inputs = _field_of(raw, "input")
+    inputs = (
+        list(raw_inputs)
+        if isinstance(raw_inputs, Sequence) and not isinstance(raw_inputs, (str, bytes))
+        else []
+    )
+    context_window = _field_of(raw, "contextWindow")
+    return CatalogCard(
+        id=canonical_id(provider, model_id),
+        provider=provider,
+        modelId=model_id,
+        name=_field_of(raw, "name"),
+        reasoning=_field_of(raw, "reasoning") is True,
+        acceptsImages="image" in inputs,
+        contextTokens=(
+            int(context_window)
+            if isinstance(context_window, (int, float)) and not isinstance(context_window, bool)
+            else 0
+        ),
+        model=raw,
+    )
+
+
+def _build_index(
+    providers: Sequence[str],
+    pull: Callable[[str], Sequence[Any]],
+) -> dict[str, CatalogCard]:
+    """The transform pipeline: pull every provider's raw model list, validate,
+    drop rejects, normalize, and de-duplicate by canonical id (first wins).
+    The result is a stable, insertion-ordered map."""
+    index: dict[str, CatalogCard] = {}
+    for provider in providers:
+        try:
+            raws = pull(str(provider))
+        except Exception:
+            continue  # a provider that can't be enumerated is simply absent
+        for raw in raws:
+            if not _clears_gate(raw):
+                continue
+            card = _normalize_card(raw)
+            if card.id not in index:
+                index[card.id] = card
+    return index
+
+
+# ---------------------------------------------------------------------------
+# ModelCatalog
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogSource:
+    """Injection seam for tests: how the catalog sources its raw data
+    (TS ``CatalogSource``)."""
+
+    # Enumerate the providers to scan.
+    providers: Callable[[], Sequence[str]]
+    # Pull the raw model list for one provider.
+    models: Callable[[str], Sequence[Any]]
+
+
+#: Providers excluded from the live catalog.
+#:
+#: ``mock`` is the framework's echo provider (its one model, ``mock-default``,
+#: replies "Mock response to: …"). It is invaluable in tests but must never
+#: surface to a real session — neither as the auto-selected default nor as a
+#: row in the model picker — so it is filtered out of the live source. Tests
+#: that want it inject their own :class:`CatalogSource`.
+_EXCLUDED_PROVIDERS: frozenset[str] = frozenset({"mock"})
+
+
+def _framework_source() -> CatalogSource:
+    """The live framework source — ``get_providers`` + ``get_models`` from
+    :mod:`indusagi.ai`. Built lazily per call site: no import-time registry I/O."""
+    return CatalogSource(
+        providers=lambda: [
+            p for p in get_providers() if str(p) not in _EXCLUDED_PROVIDERS
+        ],
+        models=lambda provider: get_models(provider),
+    )
+
+
+class ModelCatalog:
+    """A normalized, validated view of the framework model list.
+
+    Construct once (the build pipeline runs eagerly in the constructor) and
+    query many times. The instance is immutable after construction; call
+    :meth:`refreshed` to rebuild against the current framework state.
+    """
+
+    __slots__ = ("_index", "_by_provider")
+
+    def __init__(self, source: CatalogSource | None = None) -> None:
+        """``source`` is the raw-data seam; defaults to the live
+        :mod:`indusagi.ai` registry."""
+        src = source if source is not None else _framework_source()
+        self._index: dict[str, CatalogCard] = _build_index(src.providers(), src.models)
+        grouped: dict[str, list[CatalogCard]] = {}
+        for card in self._index.values():
+            grouped.setdefault(card.provider, []).append(card)
+        self._by_provider: dict[str, list[CatalogCard]] = grouped
+
+    @property
+    def size(self) -> int:
+        """Total number of cards in the catalog."""
+        return len(self._index)
+
+    def all(self) -> list[CatalogCard]:
+        """Every card, in insertion order (provider scan order)."""
+        return list(self._index.values())
+
+    def by_provider(self, provider: str) -> list[CatalogCard]:
+        """Cards owned by one provider (empty list if the provider has none)."""
+        return list(self._by_provider.get(str(provider), []))
+
+    def providers(self) -> list[str]:
+        """The providers that contributed at least one card, in scan order."""
+        return list(self._by_provider.keys())
+
+    def get(self, id: str) -> CatalogCard | None:
+        """Look up one card by its canonical ``"provider/modelId"`` id. Also
+        accepts a bare provider-scoped model id when it is unambiguous across
+        providers."""
+        direct = self._index.get(id)
+        if direct is not None:
+            return direct
+        if "/" not in id:
+            matches = [c for c in self._index.values() if c.modelId == id]
+            if len(matches) == 1:
+                return matches[0]
+        return None
+
+    def has(self, id: str) -> bool:
+        """True when the canonical id resolves to a card."""
+        return self.get(id) is not None
+
+    def refreshed(self, source: CatalogSource | None = None) -> "ModelCatalog":
+        """Rebuild against the current framework state, returning a fresh catalog."""
+        return ModelCatalog(source if source is not None else _framework_source())