hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/model_catalog.py

@@ -0,0 +1,551 @@
+"""Model catalog and model switching (docs/MODEL-SWITCHING.md).
+
+- The Hyper model list comes from the gateway (``GET {gateway}/v1/catalog``
+  with the install key), cached with a TTL; offline it falls back to the last
+  good cache, then to the packaged HyperSpeed V2 entry. New Hyper models
+  appear without an app update.
+- Third-party providers are merged here, client-side, from models.yaml —
+  never from the gateway — and labelled "your own provider (<name>)", or
+  "<model>, via Hyper" on a Hyper-issued key (hyperclaw.model_policy). A
+  Hyper-deployed install lists only the models on its allowed list
+  (hyperclaw.managed_config; default HyperSpeed V2 only), and choosing a
+  third-party model needs the owner's consent (docs/MODEL-POLICY.md).
+- tools vs chat-only comes ONLY from signed qualification records
+  (``Provider.effective_capabilities``). The catalog never grants tools.
+- A selection is per surface ("terminal", "telegram") and lasts for the
+  running process. ``selected_route`` is the hook the route selection uses.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+log = logging.getLogger("hyperclaw.model_catalog")
+
+TERMINAL = "terminal"
+TELEGRAM = "telegram"
+
+DEFAULT_TTL_S = 6 * 3600
+FETCH_TIMEOUT_S = 5.0
+CATALOG_URL_ENV = "HYPERCLAW_CATALOG_URL"
+TTL_ENV = "HYPERCLAW_CATALOG_TTL_S"
+
+SOURCE_GATEWAY = "Hyper gateway"
+SOURCE_CACHE = "cached"
+SOURCE_OFFLINE = "offline, last good copy"
+SOURCE_PACKAGED = "built-in default"
+
+# Ctrl-T cycles models in the terminal (docs/MODEL-SWITCHING.md).
+# - libedit (macOS's Python): ^T calls readline's completion hook, which runs
+#   the switch in place and redraws the line; what was typed is kept. (A
+#   libedit string macro only replays its first key under Python's
+#   callback-driven input(), so a "/model next" macro cannot work there.)
+# - GNU readline: a macro that clears the line and submits "/model next"
+#   (so a half-typed message is never sent).
+SHORTCUT_LABEL = "Ctrl-T"
+SHORTCUT_COMMAND = "/model next"
+SHORTCUT_RAW = "\x14"   # what input() returns for Ctrl-T without readline
+_GNU_BINDING = r'"\C-t": "\C-a\C-k/model next\n"'
+_LIBEDIT_BINDINGS = ("bind ^T rl_complete", "bind ^I ed-insert")
+
+_ID = re.compile(r"^[A-Za-z0-9._:/-]{1,128}$")
+_CTRL = re.compile(r"[\x00-\x1f\x7f]")
+
+STATUS_TOOLS = "tools (qualified)"
+STATUS_NOT_QUALIFIED = "chat-only (not qualified for tools)"
+STATUS_CHAT = "chat-only"
+
+
+# ───────────────────────── catalog ─────────────────────────
+
+@dataclass
+class CatalogResult:
+    models: list            # sanitized entries (dicts)
+    source: str             # SOURCE_*
+    fetched_at: Optional[float] = None
+
+
+def ttl_s() -> float:
+    try:
+        return max(0.0, float(os.environ.get(TTL_ENV, "") or DEFAULT_TTL_S))
+    except ValueError:
+        return float(DEFAULT_TTL_S)
+
+
+def cache_path() -> Path:
+    from hyperclaw.userconfig import root
+    return root() / "cache" / "model_catalog.json"
+
+
+def packaged_default() -> list:
+    """The one entry every install has: HyperSpeed V2 as configured."""
+    from hyperclaw import hyperspeed
+    return [{"id": hyperspeed.model(), "display_name": hyperspeed.LABEL, "family": "hyper",
+             "modalities": ["text"], "context_window": None, "default": True,
+             "deprecated": False}]
+
+
+def catalog_url() -> str:
+    """HYPERCLAW_CATALOG_URL, else the HyperSpeed base + /catalog. A raw RunPod
+    base has no catalog route, so it is never asked ("" = don't fetch)."""
+    explicit = os.environ.get(CATALOG_URL_ENV, "").strip()
+    if explicit:
+        return explicit
+    from hyperclaw import hyperspeed
+    base = hyperspeed.base_url().rstrip("/")
+    if not base or "runpod" in base.lower():
+        return ""
+    return base + "/catalog" if base.endswith("/v1") else base + "/v1/catalog"
+
+
+def _key_fp(key: str) -> str:
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()[:12] if key else ""
+
+
+def sanitize(payload) -> Optional[list]:
+    """Valid entries from a catalog response, or None if it isn't one.
+    Unknown fields (anything about tools/capabilities included) are dropped."""
+    if not isinstance(payload, dict) or not isinstance(payload.get("models"), list):
+        return None
+    out, seen = [], set()
+    for m in payload["models"]:
+        if not isinstance(m, dict):
+            continue
+        mid = m.get("id")
+        if not isinstance(mid, str) or not _ID.match(mid) or mid in seen:
+            continue
+        seen.add(mid)
+        name = m.get("display_name")
+        name = _CTRL.sub("", name)[:80].strip() if isinstance(name, str) else ""
+        fam = m.get("family")
+        mods = m.get("modalities")
+        cw = m.get("context_window")
+        out.append({
+            "id": mid,
+            "display_name": name or mid,
+            "family": _CTRL.sub("", fam)[:40] if isinstance(fam, str) and fam else "hyper",
+            "modalities": [x for x in mods if isinstance(x, str)][:8]
+            if isinstance(mods, list) else ["text"],
+            "context_window": cw if isinstance(cw, int) and not isinstance(cw, bool)
+            and cw > 0 else None,
+            "default": m.get("default") is True,
+            "deprecated": m.get("deprecated") is True,
+        })
+    return out
+
+
+def _http_fetch(url: str, key: str, timeout: float):
+    import httpx
+    with httpx.Client(timeout=timeout) as client:
+        r = client.get(url, headers={"Authorization": f"Bearer {key}",
+                                     "Accept": "application/json"})
+        return r.status_code, (r.json() if r.status_code == 200 else None)
+
+
+def _read_cache(url: str, key: str) -> Optional[dict]:
+    try:
+        data = json.loads(cache_path().read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    if not isinstance(data, dict) or data.get("url") != url or data.get("key_fp") != _key_fp(key):
+        return None
+    models = sanitize({"models": data.get("models")})
+    if models is None or not isinstance(data.get("fetched_at"), (int, float)):
+        return None
+    return {"models": models, "fetched_at": float(data["fetched_at"])}
+
+
+def _write_cache(url: str, key: str, models: list, now: float) -> None:
+    p = cache_path()
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".tmp")
+        tmp.write_text(json.dumps({"url": url, "key_fp": _key_fp(key), "fetched_at": now,
+                                   "models": models}, indent=1), encoding="utf-8")
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, p)
+    except OSError as e:
+        log.warning(f"model catalog cache not written: {e}")
+
+
+def get_catalog(fetch: Optional[Callable] = None, now: Optional[float] = None,
+                force: bool = False) -> CatalogResult:
+    """Fresh cache → gateway → last good cache → packaged default."""
+    from hyperclaw import hyperspeed
+    now = time.time() if now is None else now
+    url = catalog_url()
+    key = os.environ.get(hyperspeed.API_KEY_ENV, "").strip()
+    if not url or not key:
+        return CatalogResult(packaged_default(), SOURCE_PACKAGED)
+    cached = _read_cache(url, key)
+    if cached and not force and now - cached["fetched_at"] < ttl_s():
+        return CatalogResult(cached["models"], SOURCE_CACHE, cached["fetched_at"])
+    try:
+        status, payload = (fetch or _http_fetch)(url, key, FETCH_TIMEOUT_S)
+        models = sanitize(payload) if status == 200 else None
+        if models is None:
+            raise ValueError(f"catalog answered HTTP {status}" if status != 200
+                             else "catalog response is malformed")
+        _write_cache(url, key, models, now)
+        return CatalogResult(models, SOURCE_GATEWAY, now)
+    except Exception as e:   # never fatal: the list falls back, chat is unaffected
+        log.warning(f"model catalog unavailable ({type(e).__name__}: {str(e)[:120]})")
+    if cached:
+        return CatalogResult(cached["models"], SOURCE_OFFLINE, cached["fetched_at"])
+    return CatalogResult(packaged_default(), SOURCE_PACKAGED)
+
+
+# ───────────────────────── listing ─────────────────────────
+
+@dataclass(frozen=True)
+class ModelOption:
+    provider: str
+    model: str
+    display_name: str
+    source: str          # "HyperSpeed V2" | "your own provider (Anthropic)"
+    origin: str          # hyper | customer
+    family: str
+    tools: bool          # from the signed record only
+    status: str
+    default: bool = False
+    deprecated: bool = False
+    context_window: Optional[int] = None
+
+    @property
+    def key(self) -> str:
+        return f"{self.provider}/{self.model}"
+
+
+def tool_status(prov, model: str) -> tuple:
+    """(tools?, label) from the signed record via effective_capabilities."""
+    if "tool_use" in prov.effective_capabilities(model):
+        return True, STATUS_TOOLS
+    if "tool_use" in prov.capabilities:
+        return False, STATUS_NOT_QUALIFIED
+    return False, STATUS_CHAT
+
+
+def _customer_models(prov) -> list:
+    seen, out = set(), []
+    for m in [prov.model_for()] + list((prov.models or {}).values()):
+        if m and isinstance(m, str) and m not in seen:
+            seen.add(m)
+            out.append(m)
+    return out
+
+
+def available_models(registry=None, catalog: Optional[CatalogResult] = None) -> list:
+    """Every model this install can use now: Hyper models first (catalog
+    order, plus the configured V2 model), then third-party providers
+    (Claude, OpenAI, Grok, ...). Hyper-deployed: only the models on the
+    install's allowed list (hyperclaw.managed_config; default V2 only)."""
+    from hyperclaw import hyperspeed
+    from hyperclaw.deployment import is_hyper
+    from hyperclaw.managed_config import allowed_for, is_allowed
+    from hyperclaw.model_policy import model_label
+    if registry is None:
+        from hyperclaw.providers import registry as _reg
+        registry = _reg()
+    hyper_only = is_hyper()
+    out: list = []
+
+    hp = registry.providers.get(hyperspeed.PROVIDER_NAME)
+    if hp is not None and hp.live and hp.origin == "hyper":
+        catalog = catalog or get_catalog()
+        entries = [e for e in catalog.models
+                   if not hyper_only or e.get("family", "hyper") == "hyper"]
+        configured = hp.model_for()
+        if configured and all(e["id"] != configured for e in entries):
+            entries = entries + [{"id": configured, "display_name": hp.display_label,
+                                  "family": "hyper", "context_window": None,
+                                  "default": not any(e.get("default") for e in entries),
+                                  "deprecated": False}]
+        for e in entries:
+            if not is_allowed(hp.name, e["id"]):
+                continue
+            tools, status = tool_status(hp, e["id"])
+            out.append(ModelOption(hp.name, e["id"], e.get("display_name") or e["id"],
+                                   hp.display_label, "hyper", e.get("family") or "hyper",
+                                   tools, status, bool(e.get("default")),
+                                   bool(e.get("deprecated")), e.get("context_window")))
+
+    for name, prov in registry.providers.items():
+        if prov.origin == "hyper" or not prov.live or "chat" not in prov.capabilities:
+            continue
+        models = _customer_models(prov)
+        if hyper_only:
+            explicit = [m for m in allowed_for(name) if m != "*"]
+            models = list(dict.fromkeys(
+                [m for m in models if is_allowed(name, m)] + explicit))
+        for m in models:
+            tools, status = tool_status(prov, m)
+            out.append(ModelOption(name, m, m, model_label(prov, m), "customer",
+                                   prov.name, tools, status))
+    return out
+
+
+def answering_line(options: list, active_key: str) -> str:
+    """'Answering now: <label> · model <id>' for the active model, '' if none."""
+    for o in options:
+        if o.key == active_key:
+            return f"Answering now: {o.source} · model {o.model}"
+    return ""
+
+
+def format_listing(options: list, active_key: str, catalog: Optional[CatalogResult] = None,
+                   surface: str = TERMINAL) -> str:
+    if not options:
+        return "No models are available on this install. Run `hyperclaw doctor`."
+    head = "Models on this install"
+    if catalog is not None:
+        when = (time.strftime(" %Y-%m-%d %H:%M", time.localtime(catalog.fetched_at))
+                if catalog.fetched_at else "")
+        head += f" (Hyper catalog: {catalog.source}{when})"
+    lines = [head + ":"]
+    for i, o in enumerate(options, 1):
+        name = o.display_name if o.display_name == o.model else f"{o.display_name} ({o.model})"
+        mark = "*" if o.key == active_key else " "
+        extra = " · deprecated" if o.deprecated else ""
+        tail = "  ← active" if o.key == active_key else ""
+        lines.append(f"{mark} {i}. {name} · {o.source} · {o.status}{extra}{tail}")
+    answering = answering_line(options, active_key)
+    if answering:
+        lines.append(answering)
+    from hyperclaw.deployment import is_hyper
+    if is_hyper():
+        lines.append("Only the models on this install's allowed list can be selected.")
+    if surface == TELEGRAM:
+        lines.append("Switch: /model <number or id> · /model next · /model default. "
+                     "Telegram replies are text only, whatever the model.")
+    else:
+        lines.append(f"Switch: /model <number or id> · {SHORTCUT_LABEL} or /model next · "
+                     "/model default")
+    return "\n".join(lines)
+
+
+def find_option(options: list, arg: str) -> Optional[ModelOption]:
+    arg = (arg or "").strip()
+    if not arg:
+        return None
+    if arg.isdigit():
+        i = int(arg)
+        return options[i - 1] if 1 <= i <= len(options) else None
+    for o in options:
+        if o.key == arg:
+            return o
+    hits = [o for o in options if o.model == arg] or \
+        [o for o in options if o.display_name.lower() == arg.lower()]
+    return hits[0] if len(hits) == 1 else None
+
+
+def next_option(options: list, active_key: str) -> Optional[ModelOption]:
+    """The model after the active one, skipping deprecated ones, wrapping."""
+    usable = [o for o in options if not o.deprecated] or list(options)
+    if not usable:
+        return None
+    keys = [o.key for o in usable]
+    if active_key in keys:
+        return usable[(keys.index(active_key) + 1) % len(usable)]
+    return usable[0]
+
+
+# ───────────────────────── selection (route hook) ─────────────────────────
+
+_SELECTION: dict = {}   # surface -> (provider name, model id)
+
+
+def select(surface: str, provider: str, model: str) -> None:
+    _SELECTION[surface] = (provider, model)
+
+
+def clear(surface: Optional[str] = None) -> None:
+    if surface is None:
+        _SELECTION.clear()
+    else:
+        _SELECTION.pop(surface, None)
+
+
+def selection(surface: str) -> Optional[tuple]:
+    return _SELECTION.get(surface)
+
+
+def is_selected(surface: str, provider: str, model: str) -> bool:
+    return _SELECTION.get(surface) == (provider, model)
+
+
+def selected_route(registry, surface: str) -> Optional[tuple]:
+    """(Provider, model) for this surface's selection, or None (no selection,
+    or it is no longer usable: provider gone or not live, not on a
+    Hyper-deployed install's allowed list, or a third-party provider without
+    the owner's consent)."""
+    sel = _SELECTION.get(surface)
+    if not sel:
+        return None
+    from hyperclaw.managed_config import is_allowed
+    from hyperclaw.model_policy import needs_consent
+    prov = getattr(registry, "providers", {}).get(sel[0])
+    if prov is None or not prov.live or "chat" not in prov.capabilities:
+        return None
+    if not is_allowed(prov.name, sel[1]) or needs_consent(prov):
+        return None
+    return prov, sel[1]
+
+
+def prefer_selected(registry, surface: str, candidates: list, need=()) -> list:
+    """Put the surface's selected model first in a slot ladder when it can
+    serve the turn (declared + qualified capabilities); else the ladder."""
+    sel = selected_route(registry, surface)
+    if not sel:
+        return list(candidates)
+    prov, model = sel
+    if not frozenset(need or ()) <= prov.effective_capabilities(model):
+        return list(candidates)
+    return [(prov, model)] + [(p, m) for p, m in candidates
+                              if (p.name, m) != (prov.name, model)]
+
+
+def route_key(route) -> str:
+    """'provider/model' for a (mode, provider, model) route, '' if none."""
+    if not route or route[1] is None:
+        return ""
+    return f"{getattr(route[1], 'name', '?')}/{route[2] or ''}"
+
+
+# ───────────────────────── /model command ─────────────────────────
+
+@dataclass
+class CommandResult:
+    text: str
+    switched: Optional[ModelOption] = None
+    cleared: bool = False
+    needs_consent: bool = False
+
+
+CONSENT_WORDS = ("yes", "agree")
+
+
+def run_command(args: list, surface: str, active_key: str, registry=None,
+                catalog: Optional[CatalogResult] = None,
+                confirm: Optional[Callable] = None) -> CommandResult:
+    """/model, /model next, /model default, /model <number|id|provider/id>.
+    Selection only; the caller re-applies the route, prompt and log.
+
+    A third-party model shows the one consent line (model_policy). Without
+    recorded consent the owner must agree: ``confirm(line) -> bool`` (the
+    terminal asks), or a trailing "yes" (``/model 3 yes`` on Telegram). No
+    consent, no switch."""
+    from hyperclaw import model_policy as mp
+    catalog = catalog or get_catalog()
+    options = available_models(registry, catalog)
+    if not args:
+        return CommandResult(format_listing(options, active_key, catalog, surface))
+    agreed = len(args) > 1 and args[-1].strip().lower() in CONSENT_WORDS
+    if agreed:
+        args = args[:-1]
+    arg = " ".join(args).strip()
+    if arg.lower() in ("default", "reset"):
+        clear(surface)
+        return CommandResult("Back to this install's default model.", cleared=True)
+    choice = next_option(options, active_key) if arg.lower() == "next" \
+        else find_option(options, arg)
+    if choice is None:
+        return CommandResult(f"No model {arg!r} on this install.\n"
+                             + format_listing(options, active_key, catalog, surface))
+    if choice.key == active_key:
+        return CommandResult(f"Already using {choice.display_name}.")
+    consent = ""
+    if choice.origin != "hyper":
+        consent = mp.consent_line(choice.provider)
+        if not mp.has_consent(choice.provider):
+            ok = agreed or (confirm is not None and bool(confirm(consent)))
+            if not ok:
+                how = (f"To go ahead, send /model {choice.key} yes" if confirm is None
+                       else "Nothing changed.")
+                return CommandResult(f"{consent}\n{how}", needs_consent=True)
+            mp.record_consent(choice.provider, choice.model)
+            consent = ""   # already shown by confirm, or just agreed to
+    select(surface, choice.provider, choice.model)
+    return CommandResult((consent + "\n" if consent else "")
+                         + f"Switched to {choice.display_name} · {choice.source} · "
+                         f"{choice.status}.", switched=choice)
+
+
+def record_switch(surface: str, old_key: str, new_key: str, mode: str,
+                  kept: int) -> None:
+    """Activity log entry (spec rule 6) for a model switch."""
+    try:
+        from hyperclaw.tools.ledger import get_ledger
+        get_ledger().record(conversation=surface, turn="", surface=surface,
+                            tool="model_switch", effect="config",
+                            target=f"{old_key or '(none)'} -> {new_key} ({mode})",
+                            status="ok",
+                            message=f"history kept ({kept} messages); mode {mode}")
+    except Exception as e:
+        log.warning(f"model switch not written to the activity log: {e}")
+
+
+# ───────────────────────── history for a chat-only model ─────────────────────────
+
+def chat_only_messages(history: list) -> list:
+    """History for a chat-only model on the Messages API: tool calls and
+    results flattened to labelled text (truth_guard.history_to_openai
+    chat-only path), same-role neighbours merged, no tool block types."""
+    from hyperclaw.truth_guard import history_to_openai
+    out: list = []
+    for m in history_to_openai(history, native_tools=False):
+        role = "assistant" if m.get("role") == "assistant" else "user"
+        text = m.get("content") or ""
+        if not isinstance(text, str) or not text.strip():
+            continue
+        if out and out[-1]["role"] == role:
+            out[-1]["content"] += "\n\n" + text
+        else:
+            out.append({"role": role, "content": text})
+    while out and out[0]["role"] != "user":
+        out.pop(0)
+    return out
+
+
+# ───────────────────────── terminal shortcut ─────────────────────────
+
+def shortcut_bindings(libedit: bool) -> tuple:
+    return _LIBEDIT_BINDINGS if libedit else (_GNU_BINDING,)
+
+
+def install_shortcut(on_shortcut: Optional[Callable] = None, readline_mod=None) -> bool:
+    """Bind Ctrl-T for input(). libedit needs ``on_shortcut`` (run in place);
+    GNU readline submits '/model next'. False if not installed."""
+    try:
+        rl = readline_mod
+        if rl is None:
+            import readline as rl  # noqa: F811
+        libedit = "libedit" in (getattr(rl, "__doc__", "") or "") or \
+            getattr(rl, "backend", "") == "editline"
+        if libedit:
+            if on_shortcut is None:
+                return False
+
+            def _hook(text, state):
+                if state == 0:
+                    try:
+                        on_shortcut()
+                    except Exception as e:   # never break the input line
+                        print(f"\n[model switch failed: {e}]")
+                    try:
+                        rl.redisplay()
+                    except Exception:
+                        pass
+                return None
+            rl.set_completer(_hook)
+        for b in shortcut_bindings(libedit):
+            rl.parse_and_bind(b)
+        return True
+    except Exception:
+        return False