induscode 0.1.0__py3-none-any.whl

induscode/launch/catalog.py

@@ -0,0 +1,310 @@
+"""Model catalog printer — :func:`print_model_catalog`.
+
+Renders the available models as a padded text table. The data comes from the
+conductor's :class:`~induscode.conductor.ModelCatalog` (itself a normalized
+view over the framework :func:`indusagi.ai.get_providers` /
+:func:`indusagi.ai.get_models`); this module re-derives the rows it needs,
+applies a plain case-insensitive :class:`~.contract.CatalogFilter`, sorts by
+provider then model id, and lays the result out as aligned columns with a
+Title-Case header and a rule row beneath it.
+
+Filtering is a literal substring test — no fuzzy matcher, no external
+ranking. The column set (provider, model, context window, max output,
+thinking, images) is the established model-table shape; only the headers and
+ordering are this module's own.
+
+Port note: the TS module sat on the framework ``ModelRegistry``; the port
+plan routes the printer through the conductor catalog so there is exactly one
+catalog path in the app (plan §3 "Model catalog"). The injectable
+:class:`CatalogModelSource` seam keeps the TS test shape: a test hands in a
+plain provider→models map and the layout is exercised deterministically.
+
+(Port of TS ``src/launch/catalog.ts``.)
+"""
+
+from __future__ import annotations
+
+import math
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Final, Protocol
+
+from ..conductor import ModelCatalog
+from .contract import CatalogFilter
+
+__all__ = [
+    "CatalogIo",
+    "CatalogModelSource",
+    "catalog_source",
+    "default_catalog_io",
+    "print_model_catalog",
+]
+
+
+# ---------------------------------------------------------------------------
+# Output seam
+# ---------------------------------------------------------------------------
+
+
+class CatalogIo(Protocol):
+    """The minimal sink the catalog prints onto. A test captures the lines
+    into a list; production passes a writer over stdout."""
+
+    def print(self, line: str) -> None:
+        """Emit one line of table text."""
+        ...
+
+
+class _DefaultCatalogIo:
+    """The default :class:`CatalogIo` backed by stdout."""
+
+    def print(self, line: str) -> None:
+        sys.stdout.write(line if line.endswith("\n") else line + "\n")
+
+
+def default_catalog_io() -> CatalogIo:
+    """Build the live stdout-backed :class:`CatalogIo`."""
+    return _DefaultCatalogIo()
+
+
+# ---------------------------------------------------------------------------
+# Row projection
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class _CatalogRow:
+    """One normalized table row, derived from a framework model record."""
+
+    provider: str
+    model_id: str
+    context_window: int
+    max_output: int
+    thinking: bool
+    images: bool
+
+
+#: The table column headers, in render order.
+_HEADERS: Final[tuple[str, ...]] = (
+    "Provider",
+    "Model",
+    "Context",
+    "Max Output",
+    "Thinking",
+    "Images",
+)
+
+#: Sentinel marking "field not present at all" on a raw record.
+_ABSENT: Final[Any] = object()
+
+
+def _field_of(raw: Any, name: str) -> Any:
+    """Read ``name`` off a raw model record — mapping key or dataclass
+    attribute — returning the absent sentinel when the field does not exist.
+    Mirrors the conductor catalog's tolerant accessor so test fakes can be
+    plain mappings."""
+    if isinstance(raw, Mapping):
+        return raw.get(name, _ABSENT)
+    return getattr(raw, name, _ABSENT)
+
+
+def _as_int(value: Any) -> int:
+    """A number field as an int, 0 for anything non-numeric."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return 0
+    return int(value)
+
+
+def _to_row(model: Any) -> _CatalogRow:
+    """Project a framework model record down to a :class:`_CatalogRow`."""
+    raw_inputs = _field_of(model, "input")
+    inputs = (
+        list(raw_inputs)
+        if isinstance(raw_inputs, Sequence) and not isinstance(raw_inputs, (str, bytes))
+        else []
+    )
+    return _CatalogRow(
+        provider=str(_field_of(model, "provider")),
+        model_id=str(_field_of(model, "id")),
+        context_window=_as_int(_field_of(model, "contextWindow")),
+        max_output=_as_int(_field_of(model, "maxTokens")),
+        thinking=_field_of(model, "reasoning") is True,
+        images="image" in inputs,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Filtering & sorting
+# ---------------------------------------------------------------------------
+
+
+def _filter_rows(
+    rows: Sequence[_CatalogRow], filter: CatalogFilter
+) -> list[_CatalogRow]:
+    """Keep the rows that satisfy every set field of ``filter``. An absent
+    field matches everything; ``search`` is a case-insensitive substring test
+    over ``"provider/modelId"``."""
+    provider_needle = (
+        str(filter.provider).lower() if filter.provider is not None else None
+    )
+    search_needle = filter.search.strip().lower() if filter.search is not None else None
+    selected: list[_CatalogRow] = []
+    for row in rows:
+        if provider_needle is not None and row.provider.lower() != provider_needle:
+            continue
+        if filter.thinking_only is True and not row.thinking:
+            continue
+        if filter.images_only is True and not row.images:
+            continue
+        if search_needle:
+            haystack = f"{row.provider}/{row.model_id}".lower()
+            if search_needle not in haystack:
+                continue
+        selected.append(row)
+    return selected
+
+
+def _sort_rows(rows: Sequence[_CatalogRow]) -> list[_CatalogRow]:
+    """Order rows by provider, then by model id, both ascending."""
+    return sorted(rows, key=lambda row: (row.provider, row.model_id))
+
+
+# ---------------------------------------------------------------------------
+# Formatting
+# ---------------------------------------------------------------------------
+
+
+def _format_token_count(tokens: int) -> str:
+    """Format a token count compactly: ``128K`` / ``1.0M`` for large windows,
+    the bare number otherwise. A dash stands in for an unknown (zero)
+    count."""
+    if tokens <= 0:
+        return "-"
+    if tokens >= 1_000_000:
+        millions = tokens / 1_000_000
+        rendered = f"{millions:.0f}" if millions % 1 == 0 else f"{millions:.1f}"
+        return f"{rendered}M"
+    if tokens >= 1_000:
+        # Math.round semantics (half away from zero for positives).
+        return f"{math.floor(tokens / 1_000 + 0.5)}K"
+    return str(tokens)
+
+
+def _cells(row: _CatalogRow) -> tuple[str, ...]:
+    """Render one row to its six string cells, in header order."""
+    return (
+        row.provider,
+        row.model_id,
+        _format_token_count(row.context_window),
+        _format_token_count(row.max_output),
+        "yes" if row.thinking else "no",
+        "yes" if row.images else "no",
+    )
+
+
+def _pad(value: str, width: int) -> str:
+    """Pad a cell to a fixed width on the right."""
+    return value if len(value) >= width else value + " " * (width - len(value))
+
+
+def _layout(rows: Sequence[_CatalogRow]) -> list[str]:
+    """Lay out a header plus body as an aligned table: compute each column
+    width from the widest cell, emit the Title-Case header, a rule row of
+    dashes, then every body row. Pure; returns the lines for the caller to
+    print."""
+    body = [_cells(row) for row in rows]
+    widths = [
+        max(len(header), *(len(row[col]) for row in body)) if body else len(header)
+        for col, header in enumerate(_HEADERS)
+    ]
+
+    def render(cells: Sequence[str]) -> str:
+        return "  ".join(_pad(cell, widths[col]) for col, cell in enumerate(cells)).rstrip()
+
+    rule = "  ".join("-" * width for width in widths)
+    return [render(_HEADERS), rule, *(render(row) for row in body)]
+
+
+# ---------------------------------------------------------------------------
+# Data source
+# ---------------------------------------------------------------------------
+
+
+class CatalogModelSource(Protocol):
+    """The seam the catalog sources its raw models from. Defaults to the
+    conductor :class:`~induscode.conductor.ModelCatalog`; tests inject a
+    stand-in to drive the layout deterministically."""
+
+    def providers(self) -> Sequence[str]:
+        """Enumerate the providers to scan."""
+        ...
+
+    def models(self, provider: str) -> Sequence[Any]:
+        """Pull every model for one provider."""
+        ...
+
+
+class _ModelCatalogSource:
+    """A :class:`CatalogModelSource` over a conductor
+    :class:`~induscode.conductor.ModelCatalog`: providers come from the
+    catalog's grouping and each card contributes its retained framework model
+    record."""
+
+    def __init__(self, catalog: ModelCatalog) -> None:
+        self._catalog = catalog
+
+    def providers(self) -> Sequence[str]:
+        return self._catalog.providers()
+
+    def models(self, provider: str) -> Sequence[Any]:
+        return [card.model for card in self._catalog.by_provider(provider)]
+
+
+def catalog_source(catalog: ModelCatalog | None = None) -> CatalogModelSource:
+    """Build a :class:`CatalogModelSource` over a conductor model catalog
+    (a fresh one over the live framework registry when none is given)."""
+    return _ModelCatalogSource(catalog if catalog is not None else ModelCatalog())
+
+
+# ---------------------------------------------------------------------------
+# Public entry
+# ---------------------------------------------------------------------------
+
+
+def print_model_catalog(
+    io: CatalogIo | None = None,
+    filter: CatalogFilter | None = None,
+    source: CatalogModelSource | None = None,
+) -> None:
+    """Print the model catalog table.
+
+    Pulls every model from the source, applies ``filter``, sorts, and writes
+    the aligned table through ``io``. When the filter matches nothing, a
+    single explanatory line is printed instead of an empty table.
+
+    :param io: the line sink (defaults to stdout)
+    :param filter: optional provider / capability / substring narrowing
+    :param source: optional model source (defaults to the conductor catalog
+        over the live framework registry)
+    """
+    live_io = io if io is not None else default_catalog_io()
+    live_filter = filter if filter is not None else CatalogFilter()
+    live_source = source if source is not None else catalog_source()
+
+    all_rows: list[_CatalogRow] = []
+    for provider in live_source.providers():
+        try:
+            models = live_source.models(str(provider))
+        except Exception:
+            continue
+        for model in models:
+            all_rows.append(_to_row(model))
+
+    selected = _sort_rows(_filter_rows(all_rows, live_filter))
+    if not selected:
+        live_io.print("No models match the given filter.")
+        return
+
+    for line in _layout(selected):
+        live_io.print(line)