induscode 0.1.0__py3-none-any.whl

induscode/conductor/matcher.py

@@ -0,0 +1,291 @@
+"""Model matcher — :class:`ModelMatcher` (port of TS ``src/conductor/catalog/matcher.ts``).
+
+A scored-candidate resolver over a :class:`~induscode.conductor.catalog.ModelCatalog`.
+Given a free-form query (a string, or a structured
+:class:`~induscode.conductor.contract.MatchQuery`), it produces the single
+best-matching :class:`~induscode.conductor.contract.ModelCardRef`, or ``None``
+when nothing clears the bar.
+
+Resolution is a *prioritized scoring pipeline*, not a chain of single-purpose
+match helpers: each candidate card is scored against the query by a set of
+independent strategy probes (exact-canonical, exact-id, provider-prefix,
+alias-substring, glob), the capability filters gate the field, and the highest
+scorer (with deterministic tie-breaks) wins.
+
+Port notes
+----------
+- The TS glob compiler is ported character-by-character (an index loop, the
+  same ``[^/]`` classes, the same escape set) and memoized via
+  :func:`functools.lru_cache` in place of the TS module-level ``Map`` cache.
+- Scoring weights and the tie bonus are VERBATIM:
+  pin 1000 / exact-canonical 900 / exact-id 800 / provider 600 / glob 400 /
+  substring 200, plus ``max(0, 40 - min(|len(id) - len(needle)|, 40))`` and a
+  ``+3`` reasoning nudge.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Union
+
+from induscode.conductor.contract import MatchQuery, ModelCardRef
+
+from induscode.conductor.catalog import CatalogCard, ModelCatalog, to_card_ref
+
+__all__ = [
+    "ModelMatcher",
+    "ResolveInput",
+]
+
+
+# ---------------------------------------------------------------------------
+# Query shape
+# ---------------------------------------------------------------------------
+
+#: Either a raw selector string or the structured ``MatchQuery``.
+ResolveInput = Union[str, MatchQuery]
+
+
+def _lift_query(input: ResolveInput) -> MatchQuery:
+    """Lift a bare selector string into a ``MatchQuery``."""
+    return MatchQuery(pattern=input) if isinstance(input, str) else input
+
+
+# ---------------------------------------------------------------------------
+# Scoring scale
+# ---------------------------------------------------------------------------
+
+# Strategy weights, highest-confidence first. A candidate's score is the single
+# best strategy that fires (strategies do not stack), so the order here defines
+# the resolution priority. The gap between tiers is wide enough that a weaker
+# probe never out-ranks a stronger one regardless of secondary bonuses.
+_SCALE_PINNED_PAIR = 1000  # explicit provider + modelId pin
+_SCALE_EXACT_CANONICAL = 900  # pattern == "provider/modelId"
+_SCALE_EXACT_MODEL_ID = 800  # pattern == modelId (provider-scoped id)
+_SCALE_PROVIDER_SCOPED = 600  # pattern == "provider/" or provider name
+_SCALE_GLOB_PATTERN = 400  # pattern is a glob that matches the id
+_SCALE_ALIAS_SUBSTRING = 200  # pattern is a case-folded substring of id/name
+
+
+@dataclass(frozen=True, slots=True)
+class _ScoredCard:
+    """A scored candidate awaiting tie-break (TS ``ScoredCard``)."""
+
+    card: CatalogCard
+    score: int
+    bonus: int
+
+
+# ---------------------------------------------------------------------------
+# Capability gate
+# ---------------------------------------------------------------------------
+
+
+def _clears_constraints(card: CatalogCard, q: MatchQuery) -> bool:
+    """Reject a card that fails a hard capability or provider constraint.
+
+    These are gates, not scores: a card that fails any constraint is removed
+    from the field entirely rather than merely down-ranked.
+    """
+    if q.provider is not None and card.provider != str(q.provider):
+        return False
+    if q.modelId is not None and card.modelId != q.modelId:
+        return False
+    if q.reasoning is True and not card.reasoning:
+        return False
+    if q.supportsImageInput is True and not card.acceptsImages:
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Glob compiler (standard technique — no fnmatch dependency, ported verbatim)
+# ---------------------------------------------------------------------------
+
+_GLOBBY = re.compile(r"[*?\[\]]")
+
+# The TS literal-character escape set: /[.+^${}()|\\]/
+_NEEDS_ESCAPE = frozenset(".+^${}()|\\")
+
+
+def _looks_globby(pattern: str) -> bool:
+    """True when a selector contains glob metacharacters worth compiling."""
+    return _GLOBBY.search(pattern) is not None
+
+
+@lru_cache(maxsize=None)
+def _compile_glob(pattern: str) -> re.Pattern[str] | None:
+    """Compile a shell-style glob (``*``, ``?``, ``[set]``) to an anchored,
+    case-folded regex. Compilation is memoized. A ``/`` in the pattern is
+    matched literally, so ``anthropic/*`` scopes to a provider. Returns
+    ``None`` for an uncompilable pattern.
+
+    Ported char-by-char from the TS compiler (index loop, same classes).
+    """
+    body = ""
+    i = 0
+    while i < len(pattern):
+        ch = pattern[i]
+        if ch == "*":
+            body += "[^/]*"
+        elif ch == "?":
+            body += "[^/]"
+        elif ch == "[":
+            close = pattern.find("]", i + 1)
+            if close == -1:
+                body += "\\["
+            else:
+                body += "[" + pattern[i + 1 : close].replace("\\", "\\\\") + "]"
+                i = close
+        else:
+            body += "\\" + ch if ch in _NEEDS_ESCAPE else ch
+        i += 1
+    try:
+        return re.compile(f"^{body}$", re.IGNORECASE)
+    except re.error:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Strategy probes (independent; one fires per card, the strongest wins)
+# ---------------------------------------------------------------------------
+
+
+def _probe_pattern(card: CatalogCard, pattern: str) -> int:
+    """Probe a single card against the selector pattern, returning the best
+    strategy score (or 0 if no probe fires). The probes are tried
+    strongest-first and the first hit short-circuits."""
+    needle = pattern.strip()
+    if needle == "":
+        return 0
+    folded = needle.lower()
+
+    if card.id == needle:
+        return _SCALE_EXACT_CANONICAL
+    if card.modelId == needle:
+        return _SCALE_EXACT_MODEL_ID
+
+    # provider-scoped: "anthropic/" or the bare provider slug
+    provider_prefix = f"{card.provider}/"
+    if needle == provider_prefix or folded == card.provider.lower():
+        return _SCALE_PROVIDER_SCOPED
+
+    if _looks_globby(needle):
+        compiled = _compile_glob(needle)
+        if compiled is not None and (
+            compiled.match(card.id) is not None or compiled.match(card.modelId) is not None
+        ):
+            return _SCALE_GLOB_PATTERN
+
+    if folded in card.id.lower() or folded in card.name.lower():
+        return _SCALE_ALIAS_SUBSTRING
+
+    return 0
+
+
+def _tie_bonus(card: CatalogCard, pattern: str) -> int:
+    """Secondary bonus for tie-breaking within a strategy tier. Rewards a card
+    whose id is *closer* to the pattern length (a tighter alias match), and
+    gently prefers reasoning-capable cards. Always small relative to a tier
+    gap."""
+    needle = pattern.strip().lower()
+    bonus = 0
+    if len(needle) > 0:
+        # tighter substring matches (less surrounding noise) rank higher
+        slack = abs(len(card.id) - len(needle))
+        bonus += max(0, 40 - min(slack, 40))
+    if card.reasoning:
+        bonus += 3
+    return bonus
+
+
+def _rank_key(scored: _ScoredCard) -> tuple[int, int, str]:
+    """Deterministic candidate ordering: higher strategy tier first, then
+    higher tie-bonus, then canonical id lexical order so equal scores never
+    depend on catalog iteration order (TS ``rankCandidates``)."""
+    return (-scored.score, -scored.bonus, scored.card.id)
+
+
+# ---------------------------------------------------------------------------
+# ModelMatcher
+# ---------------------------------------------------------------------------
+
+
+class ModelMatcher:
+    """Resolves model queries against a ``ModelCatalog`` by scored candidates.
+
+    Construct once with a catalog, then call :meth:`resolve` per query. The
+    matcher holds no mutable state; it is safe to share.
+    """
+
+    __slots__ = ("_catalog",)
+
+    def __init__(self, catalog: ModelCatalog) -> None:
+        self._catalog = catalog
+
+    def resolve(self, input: ResolveInput) -> ModelCardRef | None:
+        """Resolve a query to the single best ``ModelCardRef``, or ``None``.
+
+        Pipeline:
+          1. lift the input to a ``MatchQuery``;
+          2. honor an explicit ``provider``+``modelId`` *pin* (highest tier)
+             up front;
+          3. gate every card through the constraint filter;
+          4. with no pattern, return the leading surviving candidate (default
+             pick);
+          5. otherwise score each survivor (probe + tie bonus) and return the
+             top scorer (deterministic tie-break by tier, bonus, id).
+        """
+        q = _lift_query(input)
+        card = self.resolve_card(q)
+        return to_card_ref(card) if card is not None else None
+
+    def resolve_card(self, input: ResolveInput) -> CatalogCard | None:
+        """As :meth:`resolve`, but returns the full :class:`CatalogCard`."""
+        q = _lift_query(input)
+
+        # Tier 0: an explicit provider+modelId pin resolves directly.
+        if q.provider is not None and q.modelId is not None:
+            pinned = self._catalog.get(f"{q.provider}/{q.modelId}")
+            if pinned is not None and _clears_constraints(pinned, q):
+                return pinned
+
+        field = [c for c in self._catalog.all() if _clears_constraints(c, q)]
+        if len(field) == 0:
+            return None
+
+        pattern = q.pattern.strip() if q.pattern is not None else None
+        if not pattern:
+            # No selector: the default candidate is the leading survivor,
+            # nudged toward a reasoning model when the field offers one.
+            return next((c for c in field if c.reasoning), field[0])
+
+        scored = [
+            _ScoredCard(card=c, score=score, bonus=_tie_bonus(c, pattern))
+            for c in field
+            if (score := _probe_pattern(c, pattern)) > 0
+        ]
+        if len(scored) == 0:
+            return None
+
+        scored.sort(key=_rank_key)
+        return scored[0].card
+
+    def resolve_all(self, input: ResolveInput) -> list[ModelCardRef]:
+        """Resolve, returning *all* surviving candidates ranked best-first
+        (the field a "did you mean" picker would show). Useful for ambiguous
+        selectors."""
+        q = _lift_query(input)
+        field = [c for c in self._catalog.all() if _clears_constraints(c, q)]
+        pattern = q.pattern.strip() if q.pattern is not None else None
+        if not pattern:
+            return [to_card_ref(c) for c in field]
+        scored = [
+            _ScoredCard(card=c, score=score, bonus=_tie_bonus(c, pattern))
+            for c in field
+            if (score := _probe_pattern(c, pattern)) > 0
+        ]
+        scored.sort(key=_rank_key)
+        return [to_card_ref(s.card) for s in scored]