hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/model_policy.py

@@ -0,0 +1,211 @@
+"""Model policy for HyperAgents (Vaughn, 2026-10-12; docs/MODEL-POLICY.md).
+
+- HyperSpeed V2 is the default and recommended model. HyperAgents may also run
+  Claude, OpenAI or Grok (xAI) models, on every install; a Hyper-deployed
+  install only the models on its allowed list (hyperclaw.managed_config).
+- Labels: Hyper's models by name ("HyperSpeed V2"); a model on a key Hyper
+  issued "<model name>, via Hyper"; a model on a key the user added
+  "your own provider (<provider>)".
+- Consent: choosing a third-party model shows exactly one line,
+  CONSENT_LINE, and needs the owner's yes, recorded (time, provider, model)
+  in an owner-only file. No consent, no switch, and no automatic fallback to
+  that provider.
+- Honesty: which model is answering is said at start-up, in /model, on every
+  switch and on every automatic fallback (one line naming the new model and
+  why).
+- Keys: a key that looks like a RunPod key (rpa_) is never accepted for any
+  provider.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+log = logging.getLogger("hyperclaw.model_policy")
+
+CONSENT_LINE = "Messages, emails and documents you share will be processed by {provider}."
+CONSENT_FILE = "model_consent.json"
+
+# The provider named in the consent line.
+PROVIDER_NAMES = {
+    "anthropic": "Anthropic",
+    "anthropic_compat": "the Anthropic-compatible endpoint you configured",
+    "openai": "OpenAI",
+    "openai_default": "the OpenAI-compatible endpoint you configured",
+    "openai_compat": "the OpenAI-compatible endpoint you configured",
+    "xai": "xAI",
+    "bedrock": "AWS Bedrock",
+}
+
+RUNPOD_PREFIX = "rpa_"
+RUNPOD_REFUSAL = ("That key can't be used here: it isn't a model provider key or a Hyper "
+                  "access key. Nothing was saved.")
+
+
+# ───────────────────────── who is third-party ─────────────────────────
+
+def is_third_party(prov) -> bool:
+    return getattr(prov, "origin", "customer") != "hyper"
+
+
+def provider_name(prov_or_name) -> str:
+    name = prov_or_name if isinstance(prov_or_name, str) else getattr(prov_or_name, "name", "")
+    if name in PROVIDER_NAMES:
+        return PROVIDER_NAMES[name]
+    label = "" if isinstance(prov_or_name, str) else getattr(prov_or_name, "label", "")
+    return label or name
+
+
+def consent_line(prov_or_name) -> str:
+    return CONSENT_LINE.format(provider=provider_name(prov_or_name))
+
+
+# ───────────────────────── labels ─────────────────────────
+
+_GPT = re.compile(r"^gpt-", re.I)
+
+
+def pretty_model_name(provider: str, model: str) -> str:
+    """A readable model name: managed name, known name, else from the id
+    ("claude-sonnet-5-5" -> "Claude Sonnet 5.5")."""
+    from hyperclaw import managed_config, xai
+    named = managed_config.model_name(provider, model)
+    if named:
+        return named
+    if model in xai.NAMES:
+        return xai.NAMES[model]
+    if not model:
+        return provider
+    if _GPT.match(model):
+        return "GPT-" + model[4:]
+    words, nums = [], []
+    for part in model.split("-"):
+        if part.isdigit() and len(part) <= 2:
+            nums.append(part)
+        elif nums:
+            break   # a date or snapshot suffix after the version: stop
+        else:
+            words.append(part[:1].upper() + part[1:])
+    return " ".join(words + ([".".join(nums)] if nums else [])) or model
+
+
+def model_label(prov, model: str) -> str:
+    """How this provider + model is named to the user."""
+    from hyperclaw import managed_config
+    if not is_third_party(prov):
+        return getattr(prov, "display_label", "") or getattr(prov, "label", "") or prov.name
+    if managed_config.hyper_issued(prov.name):
+        return f"{pretty_model_name(prov.name, model)}, via Hyper"
+    return f"your own provider ({getattr(prov, 'label', '') or prov.name})"
+
+
+def answering_text(label: str, model: str) -> str:
+    """'Answering: HyperSpeed V2 · model hospitality'."""
+    return f"Answering: {label}" + (f" · model {model}" if model else "")
+
+
+def fallback_notice(new_label: str, new_model: str, old_label: str) -> str:
+    """One line when an automatic fallback changes the answering model."""
+    model = f" · model {new_model}" if new_model else ""
+    return f"Now answering: {new_label}{model}, because {old_label} didn't respond."
+
+
+# ───────────────────────── consent (owner-only file) ─────────────────────────
+
+def consent_path() -> Path:
+    from hyperclaw.userconfig import root
+    return root() / "config" / CONSENT_FILE
+
+
+def _read() -> list:
+    try:
+        data = json.loads(consent_path().read_text(encoding="utf-8"))
+        rows = data.get("consents") if isinstance(data, dict) else None
+        return [r for r in rows if isinstance(r, dict)] if isinstance(rows, list) else []
+    except Exception:  # noqa: BLE001 -- missing or unreadable: no consent
+        return []
+
+
+def has_consent(provider: str) -> bool:
+    """True when the owner agreed to this provider processing their data."""
+    return any(r.get("provider") == provider for r in _read())
+
+
+def consents() -> list:
+    return _read()
+
+
+def record_consent(provider: str, model: str) -> dict:
+    """Append the owner's consent (UTC time, provider, model). The file is
+    owner read/write only (0600)."""
+    row = {"provider": provider, "model": model,
+           "provider_name": provider_name(provider),
+           "line": consent_line(provider),
+           "at": _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+    rows = _read() + [row]
+    p = consent_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump({"consents": rows}, f, indent=1)
+    try:
+        os.chmod(p, 0o600)
+    except OSError:
+        pass
+    return row
+
+
+def needs_consent(prov) -> bool:
+    return is_third_party(prov) and not has_consent(prov.name)
+
+
+def fallback_ladder(candidates: list) -> list:
+    """An automatic fallback never moves to a third-party provider the owner
+    hasn't agreed to; the first rung (the configured or chosen route) stays."""
+    if not candidates:
+        return []
+    return [candidates[0]] + [(p, m) for p, m in candidates[1:] if not needs_consent(p)]
+
+
+# ───────────────────────── keys ─────────────────────────
+
+def looks_like_runpod_key(key: str) -> bool:
+    return (key or "").strip().lower().startswith(RUNPOD_PREFIX)
+
+
+def check_key(key: str) -> str:
+    """'' when the key may be saved; else the plain reason it is refused."""
+    if looks_like_runpod_key(key):
+        return RUNPOD_REFUSAL
+    return ""
+
+
+# ───────────────────────── the allowed list, for people ─────────────────────────
+
+def allowed_display(entries: Optional[list] = None) -> list:
+    """The allowed list as names, HyperSpeed V2 first (onboarding, doctor,
+    provider list). [] when the install is not restricted."""
+    from hyperclaw import hyperspeed, managed_config
+    if entries is None:
+        entries = managed_config.allowed_models() or []
+    hyper, other = [], []
+    for e in entries:
+        prov, _, model = e.partition("/")
+        if prov == hyperspeed.PROVIDER_NAME:
+            if model in ("*", hyperspeed.model()):
+                hyper.insert(0, f"{hyperspeed.LABEL} (recommended)")
+            if model == "*":
+                hyper.append("other Hyper models")
+            elif model != hyperspeed.model():
+                hyper.append(f"{pretty_model_name(prov, model)} (Hyper)")
+            continue
+        base = (pretty_model_name(prov, model) if model != "*"
+                else f"{provider_name(prov)} models")
+        other.append(f"{base}, via Hyper" if managed_config.hyper_issued(prov)
+                     else f"{base} (your own provider)")
+    return list(dict.fromkeys(hyper + other))