frutebox-node 0.1.0__py3-none-any.whl

frutebox/manifest.py

@@ -0,0 +1,218 @@
+"""Node capability-classing, lean manifest issuance, and big-GPU-claim challenge
+(§2) — in the REAL control plane (this Python service is what actually places
+models on nodes; the web copy is a reference).
+
+On join a node is benchmarked into a capability CLASS; the control plane issues a
+LEAN manifest (2-5 models) matched to the hardware — chosen to fit with headroom,
+span complementary task-types (so the box stays busy), and fill the region's demand
+gaps. Nodes are untrusted, so a machine that CLAIMS a big GPU is challenged with a
+real workload before it's trusted with big jobs; an inflated claim is downgraded to
+the measured reality. Pure + deterministic.
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+TIER_ORDER = ["C", "B", "A", "S"]
+
+
+def _rank(t: str) -> int:
+    return TIER_ORDER.index(t)
+
+
+# Committed, commercial-safe roster (Appendix A1). Non-commercial models
+# (MusicGen, FLUX.2 [dev]) are absent by construction.
+MODEL_CATALOG: list[dict] = [
+    {"id": "llama-3.2-1b", "tier": "C", "tasks": ["triage", "draft"], "vram_gb": 0.9, "pinned": False},
+    {"id": "llama-3.2-3b", "tier": "C", "tasks": ["chat"], "vram_gb": 2.1, "pinned": False},
+    {"id": "qwen3-4b", "tier": "C", "tasks": ["chat", "code"], "vram_gb": 4.0, "pinned": False},
+    {"id": "phi-4-mini-3.8b", "tier": "C", "tasks": ["code"], "vram_gb": 2.5, "pinned": False},
+    {"id": "nomic-embed-text-1.5", "tier": "C", "tasks": ["embed"], "vram_gb": 0.3, "pinned": False},
+    {"id": "qwen3-8b", "tier": "B", "tasks": ["chat", "brain"], "vram_gb": 5.0, "pinned": False},
+    {"id": "devstral-small-24b", "tier": "B", "tasks": ["code"], "vram_gb": 16.0, "pinned": True},
+    {"id": "qwen3-embedding-4b", "tier": "B", "tasks": ["embed"], "vram_gb": 2.5, "pinned": False},
+    {"id": "qwen3-reranker-0.6b", "tier": "B", "tasks": ["rerank"], "vram_gb": 1.0, "pinned": False},
+    {"id": "whisper-large-v3-turbo", "tier": "B", "tasks": ["stt"], "vram_gb": 6.0, "pinned": False},
+    {"id": "sdxl-1.0", "tier": "B", "tasks": ["image"], "vram_gb": 8.0, "pinned": True},
+    {"id": "ace-step-1.5", "tier": "B", "tasks": ["music"], "vram_gb": 8.0, "pinned": True},
+    {"id": "kokoro-82m", "tier": "B", "tasks": ["tts"], "vram_gb": 1.0, "pinned": False},
+    {"id": "stable-audio-open-1.5", "tier": "B", "tasks": ["sfx"], "vram_gb": 12.0, "pinned": True},
+    {"id": "qwen-3.6-27b", "tier": "A", "tasks": ["brain", "code"], "vram_gb": 22.0, "pinned": True},
+    {"id": "qwen-image-20b", "tier": "A", "tasks": ["image"], "vram_gb": 13.0, "pinned": True},
+    {"id": "wan-2.2", "tier": "A", "tasks": ["video"], "vram_gb": 24.0, "pinned": True},
+    {"id": "qwen3-embedding-8b", "tier": "A", "tasks": ["embed"], "vram_gb": 4.7, "pinned": False},
+    {"id": "qwen3-vl", "tier": "A", "tasks": ["vision"], "vram_gb": 20.0, "pinned": True},
+    {"id": "yue-7b", "tier": "A", "tasks": ["song"], "vram_gb": 16.0, "pinned": True},
+    # 09-B1: xtts-v2 (Coqui CPML, NON-COMMERCIAL — a named landmine) was here until
+    # the registry CI gate caught it. Chatterbox (MIT, US) is the licence-clean TTS.
+    {"id": "chatterbox", "tier": "A", "tasks": ["tts"], "vram_gb": 6.0, "pinned": False},
+    {"id": "kimi-k2.7-code", "tier": "S", "tasks": ["code", "brain"], "vram_gb": 200.0, "pinned": True},
+    {"id": "kimi-k2.6", "tier": "S", "tasks": ["brain", "code"], "vram_gb": 200.0, "pinned": True},
+    {"id": "qwen3-235b-a22b", "tier": "S", "tasks": ["brain"], "vram_gb": 140.0, "pinned": True},
+    {"id": "ltx-2.3", "tier": "S", "tasks": ["video"], "vram_gb": 48.0, "pinned": True},
+]
+_BY_ID = {m["id"]: m for m in MODEL_CATALOG}
+
+
+# Real Ollama tags for the CPU-runnable (Tier C) catalog ids, so a laptop node can
+# pull a concrete model by id/tier. Only these small models are Ollama-served here;
+# larger/pinned models run via other engines (llama.cpp) and are absent by design.
+OLLAMA_TAGS: dict[str, str] = {
+    "llama-3.2-1b": "llama3.2:1b",
+    "llama-3.2-3b": "llama3.2:3b",
+    "qwen3-4b": "qwen3:4b",
+    # The A40 smoke/backup lane's model (2026-08-30). Absent, the gateway's tag→id map could not
+    # resolve a node advertising "qwen3:8b" to the catalog's qwen3-8b, and dispatch answered
+    # "No machine available … available here: qwen3:8b" — the catalog-id/ollama-tag mismatch the
+    # runbook names as a usual culprit, firing again for want of one line.
+    "qwen3-8b": "qwen3:8b",
+    "phi-4-mini-3.8b": "phi4-mini:3.8b",
+    "nomic-embed-text-1.5": "nomic-embed-text",
+}
+
+
+def _tags_from_registry() -> dict[str, str]:
+    """28 §B — fill this map from the registry's PINNED `ollama_tag`s, without disturbing what is
+    already here.
+
+    THE DRIFT THIS CLOSES. The weights' location lived in four hand-maintained tables — the two in
+    `serving.py`, `MODEL_CATALOG` above, and this one — and in no registry. This table had 6 of the 12
+    enabled Ollama-runtime models, so the other 6 had no tag anywhere and `serving_spec` fell through
+    to an EMPTY command for them.
+
+    ADDITIVE ON PURPOSE, and this is a deliberate narrowing of the fix. The literal entries above WIN
+    over the registry where both exist, because this map is also read BACKWARDS — `gateway.py` builds
+    `{tag: id}` from it to resolve a node that advertises `qwen3:8b` to the catalog's `qwen3-8b`.
+    Changing an existing spelling would therefore change what an already-running node resolves to, and
+    a node that stops resolving reads to a user as "no machine available". Adding ids it did not have
+    cannot do that.
+
+    ONE KNOWN DISAGREEMENT, REPORTED AND NOT SILENTLY RESOLVED: this table says
+    `nomic-embed-text-1.5 -> "nomic-embed-text"` (unversioned, i.e. whatever `:latest` is) while the
+    registry pins `nomic-embed-text:v1.5`. Both pull the same weights today. `serving.py` uses the
+    pinned one; this map keeps the unversioned spelling so a node already advertising it still
+    resolves. Reconciling them means teaching the reverse lookup to accept both spellings, which is
+    gateway/routing work and a decision about node compatibility, not a registry edit.
+    """
+    try:
+        from .registry_gen import REGISTRY
+    except Exception:                              # pragma: no cover - generated module missing
+        return {}
+    out: dict[str, str] = {}
+    for m in REGISTRY:
+        tag = (m.get("source") or {}).get("ollama_tag")
+        if tag and m["id"] not in OLLAMA_TAGS:
+            out[m["id"]] = tag
+    return out
+
+
+OLLAMA_TAGS.update(_tags_from_registry())
+
+# The default CPU chat model a laptop pulls when nothing else is specified. Matches
+# inference.DEFAULT_MODEL (gemma3:4b) so the advertised model resolves correctly.
+DEFAULT_OLLAMA_TAG = "gemma3:4b"
+
+
+def ollama_tag_for_tier(tier: str) -> str:
+    """The Ollama tag a node of this tier should pull for CPU chat.
+
+    Tier C (Pi / laptop / CPU-only) → the small default chat model (gemma3:4b);
+    higher tiers get a slightly larger CPU-runnable chat model. Used by the
+    installer / run-node wrapper to provision a concrete, CPU-runnable model. This
+    reads the roster above; it does not touch the classify_capability thresholds."""
+    if tier == "C":
+        return DEFAULT_OLLAMA_TAG
+    # B/A/S can also run CPU chat as a fallback; give them a marginally larger tag.
+    return OLLAMA_TAGS.get("llama-3.2-3b", DEFAULT_OLLAMA_TAG)
+
+
+def classify_capability(vram_gb: float = 0.0) -> str:
+    """Classify measured hardware into a placement tier (§2 thresholds)."""
+    if vram_gb >= 80:
+        return "S"
+    if vram_gb >= 24:
+        return "A"
+    if vram_gb >= 8:
+        return "B"
+    return "C"  # Pi / laptop / old desktop / CPU-only
+
+
+def vision_models() -> list[str]:
+    """Catalog ids that can actually LOOK AT an image.
+
+    WHY THIS EXISTS (bug 2026-10-13, and the mobile image-recognition report is the same bug).
+    `selection.select_model` picks "the cheapest TEXT model that clears the prompt's quality bar" —
+    its docstring says so — and it takes a query string. It has never had any way to know that the
+    turn carries an image, so a message with an attachment was routed to a text model, which could
+    not see it. The catalog has known which model does vision all along (`tasks: ["vision"]`); what
+    was missing was anything that ASKED.
+
+    Read from the catalog rather than hard-coded, so adding a VLM to the roster is enough.
+    """
+    return [m["id"] for m in MODEL_CATALOG if "vision" in (m.get("tasks") or ())]
+
+
+def models_for_tier(tier: str) -> list[dict]:
+    # FILE 09-B1/B5 — the registry licence gate runs HERE, where every serving set is
+    # computed: non-commercial/unverified models never reach a manifest, and a
+    # paid-commercial model (Stability, Lightricks) appears only after its
+    # STEVAI_LICENSE_<VENDOR>_AGREED env is set. Import inside the function so a broken
+    # registry module cannot take node registration down with it — it fails OPEN to the
+    # catalog, and the CI tests (not runtime luck) guarantee the catalog itself is clean.
+    try:
+        from frutebox.registry import serving_allowed
+        allowed = [m for m in MODEL_CATALOG if serving_allowed(m["id"])]
+    except Exception:
+        allowed = list(MODEL_CATALOG)
+    return [m for m in allowed if _rank(m["tier"]) <= _rank(tier)]
+
+
+def build_manifest(
+    tier: str,
+    memory_budget_gb: float,
+    demand_gaps: Iterable[str] = (),
+    max_models: int = 5,
+    headroom: float = 0.8,
+) -> list[str]:
+    """A lean manifest: high-frequency small task-types + region demand gaps + a
+    brain if the budget allows, under a headroom fraction of the budget, capped in
+    size. Coverage comes from the mesh, not one node."""
+    budget = memory_budget_gb * headroom
+    candidates = sorted((m for m in models_for_tier(tier) if m["vram_gb"] <= budget), key=lambda m: m["vram_gb"])
+    chosen: list[dict] = []
+    used = 0.0
+    used_tasks: set[str] = set()
+
+    def try_add(m: dict | None) -> None:
+        nonlocal used
+        if not m or m in chosen or len(chosen) >= max_models or used + m["vram_gb"] > budget:
+            return
+        chosen.append(m)
+        used += m["vram_gb"]
+        used_tasks.update(m["tasks"])
+
+    def first_serving(task: str) -> dict | None:
+        return next((c for c in candidates if task in c["tasks"] and c not in chosen), None)
+
+    for task in ("triage", "embed", "chat"):
+        if task not in used_tasks:
+            try_add(first_serving(task))
+    for task in demand_gaps:
+        if task not in used_tasks:
+            try_add(first_serving(task))
+    if len(chosen) < max_models:
+        brain = next((c for c in reversed(candidates) if ("brain" in c["tasks"] or "code" in c["tasks"]) and c not in chosen and used + c["vram_gb"] <= budget), None)
+        try_add(brain)
+    return [m["id"] for m in chosen]
+
+
+def needs_capability_challenge(claimed_tier: str) -> bool:
+    """Big-GPU claims (Tier A/S) must be proven with a real workload before trust."""
+    return claimed_tier in ("A", "S")
+
+
+def verify_capability_claim(claimed_tier: str, measured_vram_gb: float) -> dict:
+    """Trust a node at its MEASURED tier, never above an inflated claim."""
+    measured = classify_capability(measured_vram_gb)
+    ok = _rank(measured) >= _rank(claimed_tier)
+    return {"ok": ok, "trusted_tier": claimed_tier if ok else measured, "measured_tier": measured}