frutebox-node 0.1.0__py3-none-any.whl

frutebox/adminheader.py

@@ -0,0 +1,59 @@
+"""The admin header's name, in ONE place, during the cutover from `x-stevai-*` to `x-frutebox-*`.
+
+WHY A MODULE FOR A STRING
+Because the string is live. Thomas sends this header by hand from his terminal, the gateways send
+it to the directory, the directory sends it to the web app, and nine web routes check it. Renaming
+it anywhere before everywhere means a request that used to authenticate stops authenticating, and
+the failure looks like a permissions bug rather than a rename.
+
+THE ORDER, WHICH IS THE WHOLE POINT (NC-1):
+  1. every READER accepts BOTH spellings — deployed first, so nothing can break;
+  2. every SENDER moves to the new spelling — code, scripts, docs;
+  3. `ACCEPT_LEGACY` goes False and the fallback below is deleted — deployed last.
+At no point does a window exist where neither spelling works.
+
+THE SECOND TOKEN MOVES IN THE SAME WINDOW. `x-stevai-admin-token-2` is the quorum kill-switch's
+second signature. Giving it its own cutover later would mean opening this same window twice, so it
+travels with the first.
+"""
+from __future__ import annotations
+
+#: The names we are moving to.
+NEW = "x-frutebox-admin-token"
+NEW_2 = "x-frutebox-admin-token-2"
+
+#: The names we are moving from. Deleted at phase 3.
+OLD = "x-stevai-admin-token"
+OLD_2 = "x-stevai-admin-token-2"
+
+#: PHASE 2 → 3 SWITCH. While True, a reader accepts either spelling. Phase 3 sets it False AND
+#: deletes the legacy branch below; it is a constant rather than an env var on purpose — the
+#: cutover should end in code that has no memory of the old name, not in a flag someone has to
+#: remember is still set.
+ACCEPT_LEGACY = True
+
+
+def read(headers, *, second: bool = False) -> str:
+    """The admin token from a request's headers, under either spelling.
+
+    `headers` is anything with a `.get(name, default)` — Starlette/FastAPI request headers are
+    case-insensitive, which is why no lower()ing happens here.
+
+    Returns "" when absent, never None, so a caller can hand the result straight to
+    `secrets.compare_digest` without a type check.
+    """
+    new, old = (NEW_2, OLD_2) if second else (NEW, OLD)
+    value = headers.get(new, "") or ""
+    if value:
+        return value
+    if ACCEPT_LEGACY:
+        return headers.get(old, "") or ""
+    return ""
+
+
+def send(token: str, *, second: bool = False) -> dict:
+    """The header dict a caller should send. Always the NEW spelling — senders never emit the old
+    one, because phase 1 already taught every reader to accept it."""
+    if not token:
+        return {}
+    return {NEW_2 if second else NEW: token}

frutebox/attest.py

@@ -0,0 +1,43 @@
+"""Software integrity attestation — is the node running the code we shipped?
+
+On (re)connect a node reports a digest of its own agent code + declared version.
+The operator compares it to the set of digests it has published for that version.
+A mismatch means the node is running modified or unknown code (a patched agent
+that logs prompts, say) and it is refused/quarantined before it can take traffic.
+
+This is SOFTWARE attestation — a hash check plus the accountable-operator trust
+model — explicitly NOT a hardware TEE. It raises the bar for a tampered node
+without any special silicon; it is one tripwire among several, not a proof.
+"""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Iterable
+
+# The agent files whose bytes define "the code we shipped". Kept small and
+# stable; in production this would be the signed release manifest.
+# engine_guard.py is in the set deliberately: it holds the model allowlist, the
+# engine endpoint allowlist and the resource ceilings, so it is precisely the file a
+# node operator would edit to make their machine accept work it should refuse.
+_AGENT_FILES = ("provider.py", "supervisor.py", "inference.py", "engine_guard.py")
+
+
+def agent_digest(root: Path | None = None, files: Iterable[str] = _AGENT_FILES) -> str:
+    """A stable SHA-256 over the agent's own source. Same code → same digest."""
+    root = root or Path(__file__).resolve().parent
+    h = hashlib.sha256()
+    for name in sorted(files):
+        p = root / name
+        h.update(name.encode())
+        h.update(b"\0")
+        if p.exists():
+            h.update(p.read_bytes())
+        h.update(b"\0")
+    return h.hexdigest()
+
+
+def verify(reported_digest: str, allowed_digests: Iterable[str]) -> bool:
+    """True iff the node's reported digest is one the operator has published."""
+    allowed = set(allowed_digests or ())
+    return bool(reported_digest) and reported_digest in allowed

frutebox/audiogen.py

@@ -0,0 +1,364 @@
+"""Audio generation — runs on a GPU node. Speech (TTS), voice cloning and music/sound,
+mirroring `imagegen`. Heavy libs are imported lazily and only present on an audio-capable
+node, so `available()` is False elsewhere and the gateway never routes audio jobs here.
+Output is WAV bytes.
+
+WHAT CHANGED AND WHY IT MATTERED. This module used to pick its own models by env default:
+
+    _SPEECH_MODEL = envvar("SPEECH_MODEL", "suno/bark-small")
+    _MUSIC_MODEL  = envvar("MUSIC_MODEL",  "facebook/musicgen-small")
+    _CLONE_MODEL  = envvar("VOICE_CLONE_MODEL", "resemble-ai/chatterbox")
+
+All three were wrong, in three different ways:
+
+  * **MusicGen is CC-BY-NC 4.0.** Plan 23 §A excludes it by name, `libraries.md` lists it under
+    "⛔ AVOID — NON-commercial, CI-blocked", and `web/src/lib/audio/music-models.ts` already
+    recorded it as excluded "kept here so nobody re-adds it". It was nevertheless the live
+    default on every audio-capable node, because the file-09 licence CI matches registry IDS
+    and this surface spoke WEIGHTS REFS — `landmines_referenced(["facebook/musicgen-small"])`
+    returned `[]`. A commercial product was shipping a non-commercial model with green tests.
+  * **Bark is not declared in `registry/models.yaml`**, so it passed no licence, territory or
+    tier gate on its way to a GPU. Its own licence is fine; that is not the point. Plan 23 §A's
+    TTS primary is Kokoro-82M.
+  * **`resemble-ai/chatterbox` does not exist** (HTTP 401). The org is `ResembleAI`. The
+    voice-cloning path could never have fetched its model at all.
+
+Model choice now comes from `mediaserving.resolve_media_model(kind, ...)` — registry-declared,
+licence-gated, geo-fenced and sized to this card. The env overrides still exist and are
+VALIDATED: `MUSIC_MODEL=facebook/musicgen-small` is refused with the licence as the reason
+rather than honoured.
+
+RUNTIMES. Each model needs its own loader (`libraries.md` §7 is authoritative): Kokoro is the
+`kokoro` pip package, Chatterbox is `chatterbox.tts`, YuE is transformers, ACE-Step is its own
+pip package or ComfyUI. Where the runtime for the resolved model is not installed on this node,
+this raises and names the install — it never falls back to a different model, because the
+resolver already chose the only one the plan sanctions for that kind.
+"""
+from __future__ import annotations
+
+import io
+import os
+import struct
+
+from . import mediaserving
+
+_speech = None
+_music = None
+_clone = None
+_speech_ref = ""
+_music_ref = ""
+_clone_ref = ""
+
+# Keywords that mean "make music/a sound" rather than "speak this".
+_MUSIC_HINT = ("music", "melody", "song", "instrumental", "soundtrack", "beat", "tune", "compose")
+
+#: The pip install each model's runtime needs, from `libraries.md` §7. Quoted in the error so a
+#: node operator is told what to do rather than that something is missing.
+_RUNTIME_INSTALL = {
+    "kokoro-82m": "pip install kokoro",
+    "chatterbox": "pip install chatterbox-tts",
+    # NOT `pip install acestep` — that package is ACE-Step v1 and its pipeline takes a local
+    # checkpoint dir, so pointing it at the 1.5 repo id downloads v1 instead (see _make_music).
+    "ace-step-1.5": "ACE-Step 1.5 needs transformers with trust_remote_code, or ComfyUI",
+    "yue-7b": "pip install transformers",
+}
+
+
+def speech_runtime_available() -> bool:
+    """Is a TTS runtime this node could actually speak with importable here?
+
+    `imagegen.available()` checks for `diffusers` and `videogen.available()` for ffmpeg. The
+    audio equivalent has to be checked too, and for a while it was not: `available()` asked
+    only for CUDA and a resolvable model, so ANY GPU node advertised `audio` and then failed
+    every job in `_runtime_missing`. That is exactly the "capacity that does not exist" this
+    module's own §B2 advertisement floor was added to prevent — the node must not claim what
+    it cannot serve.
+    """
+    for mod in ("kokoro", "chatterbox"):
+        try:
+            __import__(mod)
+            return True
+        except Exception:
+            continue
+    return False
+
+
+def available() -> bool:
+    """True iff this node can generate audio: CUDA, a model it is ALLOWED to run, and a
+    runtime that can actually run it. All three, because any one of them missing means a job
+    routed here is a job that fails."""
+    try:
+        import torch  # type: ignore
+        if not torch.cuda.is_available():
+            return False
+    except Exception:
+        return False
+    if not speech_runtime_available():
+        return False
+    try:
+        resolved_model("speech")
+        return True
+    except mediaserving.MediaUnavailable:
+        return False
+
+
+def resolved_model(kind: str, *, node_region: str = "", user_region: str = ""):
+    """The registry-declared, licence-gated model for one audio kind, sized to this card.
+
+    `kind` is the resolver's vocabulary: "speech", "clone", "music", "song" or "sfx".
+    """
+    from .imagegen import device_vram_gb
+    area = {"speech": "SPEECH_MODEL", "clone": "VOICE_CLONE_MODEL"}.get(kind, "MUSIC_MODEL")
+    return mediaserving.resolve_media_model(
+        kind,
+        node_region=node_region, user_region=user_region,
+        override=mediaserving.model_override(area),
+        max_vram_gb=device_vram_gb(),
+    )
+
+
+def _wav(samples, rate: int) -> bytes:
+    """Encode float/int mono PCM samples to a 16-bit WAV (no external deps)."""
+    # Same treatment as deterministic.py's sympy/pandas guards: the caller gets this module's own
+    # "not available on this node" RuntimeError, the way `generate_audio` already reports a missing
+    # capability, rather than a bare ModuleNotFoundError from inside the encoder.
+    try:
+        import numpy as np  # type: ignore
+    except Exception as e:
+        raise RuntimeError("audio encoding is not available on this node: numpy is not installed") from e
+    arr = np.asarray(samples, dtype=np.float32).flatten()
+    if arr.size and arr.dtype.kind == "f":
+        arr = np.clip(arr, -1.0, 1.0)
+        pcm = (arr * 32767).astype("<i2").tobytes()
+    else:
+        pcm = np.asarray(samples, dtype="<i2").tobytes()
+    buf = io.BytesIO()
+    buf.write(b"RIFF"); buf.write(struct.pack("<I", 36 + len(pcm))); buf.write(b"WAVE")
+    buf.write(b"fmt "); buf.write(struct.pack("<IHHIIHH", 16, 1, 1, rate, rate * 2, 2, 16))
+    buf.write(b"data"); buf.write(struct.pack("<I", len(pcm))); buf.write(pcm)
+    return buf.getvalue()
+
+
+def _kind_for(prompt: str) -> str:
+    low = prompt.lower()
+    return "music" if any(k in low for k in _MUSIC_HINT) else "speech"
+
+
+def _runtime_missing(spec, exc: Exception) -> RuntimeError:
+    how = _RUNTIME_INSTALL.get(spec.model_id, "")
+    tail = f" — install it with: {how}" if how else ""
+    return RuntimeError(
+        f"{spec.model_id} is the model this node must use for {spec.kind!r}, but its runtime is "
+        f"not installed here{tail}. ({exc})")
+
+
+def clone_available() -> bool:
+    """True iff this node can speak in a supplied voice (the cloning model is present).
+
+    Separate from `available()` on purpose: a node may generate speech and music
+    without carrying the cloning model, and the gateway must be able to tell —
+    a request to speak in someone's voice is never quietly answered in a
+    stranger's voice instead.
+    """
+    if not available():
+        return False
+    try:
+        resolved_model("clone")
+    except mediaserving.MediaUnavailable:
+        return False
+    try:
+        import chatterbox  # type: ignore  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def generate_audio(prompt: str, *, kind: str = "", voice_sample: "bytes | None" = None,
+                   language: str = "", node_region: str = "", user_region: str = "") -> bytes:
+    """Generate WAV audio from a text prompt. `kind` is "speech" | "music" | "song" | "sfx"
+    (auto-detected between speech and music if empty). With `voice_sample` (a few seconds of
+    WAV/MP3 of a real person, supplied with their consent) the speech is produced IN THAT VOICE.
+
+    Raises RuntimeError where the models aren't available — never a substitute
+    voice, because the point of the request was whose voice it is."""
+    if not prompt or not prompt.strip():
+        raise ValueError("empty audio prompt")
+    # Capability is asked ONCE, here, through `available()` / `clone_available()` — not
+    # re-derived inline from torch. Those two functions are what the gateway reads to decide
+    # whether to route here at all, so a check that bypasses them can diverge from the
+    # advertisement, and the request that lands is the one that must not be answered wrong.
+    if not available():
+        raise RuntimeError("audio generation is not available on this node")
+    kind = kind or _kind_for(prompt)
+
+    if voice_sample:
+        if kind != "speech":
+            raise ValueError(f"a voice sample makes no sense for {kind} generation")
+        # THE RULE: a request to speak in somebody's voice is answered in THAT voice or
+        # refused. Never a stranger's voice — whose voice it is was the entire point.
+        if not clone_available():
+            raise RuntimeError("voice cloning is not available on this node")
+        spec = resolved_model("clone", node_region=node_region, user_region=user_region)
+        return _clone_speech(spec, prompt, voice_sample, language)
+
+    spec = resolved_model(kind, node_region=node_region, user_region=user_region)
+    if spec.tier == "tts":
+        return _speak(spec, prompt, language)
+    return _make_music(spec, prompt)
+
+
+def _speak(spec, text: str, language: str = "") -> bytes:
+    """Text-to-speech through the resolved TTS model's own runtime."""
+    global _speech, _speech_ref
+    if spec.model_id == "kokoro-82m":
+        try:
+            from kokoro import KPipeline  # type: ignore
+        except Exception as e:
+            raise _runtime_missing(spec, e) from e
+        # Kokoro selects its voice pack by language code; the dialect tag narrows to the
+        # language the model knows, exactly as the cloning path does.
+        lang = (language.split("-")[0].lower() if language else "a") or "a"
+        # The language is part of the cache key, not just the ref: KPipeline binds a voice pack
+        # at construction, so a cached English pipeline would answer a Dutch request in English.
+        key = f"{spec.ref}|{lang}"
+        if _speech is None or _speech_ref != key:
+            # UNPINNED TODAY — NOT WIRED, not impossible. `KPipeline` itself takes no
+            # `revision`, but it accepts a prebuilt `model=KModel(...)`, and `KModel` takes
+            # `config` and `model` as LOCAL PATHS. So the pin is reachable in a few lines:
+            #     cfg = hf_hub_download(spec.repo, "config.json", revision=spec.revision)
+            #     wts = hf_hub_download(spec.repo, <weights>, revision=spec.revision)
+            #     KPipeline(lang_code=lang, model=KModel(repo_id=spec.repo, config=cfg, model=wts))
+            # It is left unwired because it cannot be exercised here (no GPU, no kokoro
+            # package), and shipping an untested loader is how the ACE-Step defect happened.
+            # Written down rather than called impossible, because a wrong "cannot" is the kind
+            # of comment nobody ever revisits. Tracked in LANE_MEDIA.md.
+            _speech = KPipeline(lang_code=lang, repo_id=spec.repo)
+            _speech_ref = key
+        chunks = [audio for _gs, _ps, audio in _speech(text)]
+        if not chunks:
+            raise RuntimeError(f"{spec.model_id} produced no audio for this text")
+        try:
+            import numpy as np  # type: ignore
+        except Exception as e:
+            raise RuntimeError("audio encoding is not available on this node: numpy is not installed") from e
+        joined = np.concatenate([
+            c.detach().cpu().numpy() if hasattr(c, "detach") else np.asarray(c) for c in chunks])
+        return _wav(joined, 24000)
+    if spec.model_id == "chatterbox":
+        # Chatterbox without a reference sample speaks in its own default voice.
+        return _clone_speech(spec, text, b"", language)
+    raise _runtime_missing(spec, NotImplementedError(
+        f"no TTS runtime is wired for {spec.model_id} in this node build"))
+
+
+def _make_music(spec, prompt: str) -> bytes:  # noqa: ARG001 — see below
+    """Music / song / SFX through the resolved model's own runtime.
+
+    There is deliberately no generic `transformers.pipeline("text-to-audio")` path here. That is
+    how `facebook/musicgen-small` became a one-line default in the first place: a generic loader
+    will happily load ANY repo string, so the licence decision quietly moves from the registry to
+    whoever last edited an env var.
+
+    `prompt` is unused TODAY because neither music runtime is wired (see each branch). It stays
+    in the signature because the caller has it and wiring either branch needs it — dropping it
+    would make the wiring a two-file change for no gain.
+    """
+    if spec.model_id == "ace-step-1.5":
+        # NOT WIRED, deliberately, and this is the safer of the two options.
+        #
+        # The obvious call — `ACEStepPipeline(checkpoint_dir=spec.repo)` from the `acestep`
+        # package — is WRONG in a way that defeats this whole module. `checkpoint_dir` is a
+        # LOCAL DIRECTORY, not a repo id: that call makes a directory literally named
+        # "ACE-Step/Ace-Step1.5" under the node's cwd and then downloads the package's own
+        # hardcoded `ACE-Step/ACE-Step-v1-3.5B` into it. A DIFFERENT model from the one the
+        # registry gated, at no pinned revision, having passed none of the checks above —
+        # which is precisely the class of defect `mediaserving` exists to make impossible.
+        #
+        # ACE-Step 1.5 is also not a v1-layout checkpoint: its card declares
+        # `library_name: transformers` with `custom_code`, so it loads through transformers
+        # with `trust_remote_code`, i.e. by EXECUTING code from the repo on the node. That is
+        # a decision to take deliberately with a tested loader, not to slip in untested.
+        #
+        # So this refuses, names the pinned ref, and music stays honestly unavailable rather
+        # than quietly running something else.
+        raise _runtime_missing(spec, NotImplementedError(
+            f"ACE-Step 1.5 loads through transformers with trust_remote_code, not the v1 "
+            f"`acestep` pipeline; that loader is not wired into this node build. "
+            f"Pinned ref: {spec.ref}"))
+    if spec.model_id == "yue-7b":
+        # YuE is a TWO-STAGE model: stage 1 writes the vocal/accompaniment tokens, stage 2
+        # upsamples them into audio. A single-stage call returns tokens, not a song, so the
+        # resolver carries both repos and a node missing stage 2 is told so rather than
+        # returning something that is not a song.
+        if not spec.stage2_repo:
+            raise RuntimeError(f"{spec.model_id} needs its stage-2 repo and none is pinned")
+        raise _runtime_missing(spec, NotImplementedError(
+            "YuE's two-stage pipeline is not wired into this node build yet; "
+            f"stage 1 {spec.repo}, stage 2 {spec.stage2_repo}"))
+    raise _runtime_missing(spec, NotImplementedError(
+        f"no music runtime is wired for {spec.model_id} in this node build"))
+
+
+def _clone_speech(spec, text: str, voice_sample: bytes, language: str = "") -> bytes:
+    """Speak `text` in the voice of the person in `voice_sample`.
+
+    The sample is written to a temporary file and deleted immediately after: a
+    node never keeps a copy of someone's voice. It arrived for one utterance and
+    it leaves with it.
+
+    That file goes in the NODE'S OWN scratch directory (0700, and inside
+    $STEVAI_WORKSPACE when the supervisor provided one, so "stop sharing" really
+    wipes it) — not the shared system temp dir, where every other process on the
+    machine could read a stranger's voice while the utterance was being produced.
+    """
+    import tempfile
+
+    from .engine_guard import scratch_dir
+
+    global _clone, _clone_ref
+    # Reload when there is nothing cached, or when a cache WE populated is for a different
+    # resolved model. An empty `_clone_ref` means the model was supplied directly rather than
+    # loaded here, and a supplied model is used as given — replacing it would override the
+    # caller's explicit choice with a download.
+    if _clone is None or (_clone_ref and _clone_ref != spec.ref):
+        # Imported here, not at module load: a node without the cloning model
+        # still generates ordinary speech and music.
+        try:
+            from chatterbox.tts import ChatterboxTTS  # type: ignore
+        except Exception as e:
+            raise _runtime_missing(spec, e) from e
+        # UNPINNED TODAY — NOT WIRED, not impossible, same as the Kokoro path.
+        # `from_pretrained(device)` hardcodes its repo, but it is a thin wrapper over the
+        # PUBLIC `from_local(ckpt_dir, device)`, so the pin is reachable:
+        #     d = <dir of> hf_hub_download(spec.repo, <each file>, revision=spec.revision)
+        #     ChatterboxTTS.from_local(d, "cuda")
+        # Left unwired for the same reason: it cannot be exercised here, and an untested
+        # loader on this path is exactly what went wrong with ACE-Step. The resolver still
+        # decides WHETHER chatterbox may run at all (licence, territory, tier). Keyed on
+        # `spec.ref` so a resolver change reloads rather than reusing the previous model.
+        _clone = ChatterboxTTS.from_pretrained(device="cuda")
+        _clone_ref = spec.ref
+
+    path = None
+    try:
+        kwargs = {}
+        if voice_sample:
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False,
+                                             dir=str(scratch_dir())) as f:
+                f.write(voice_sample)
+                path = f.name
+            os.chmod(path, 0o600)
+            kwargs["audio_prompt_path"] = path
+        if language:
+            # A dialect tag ("nl-BE-westvl") narrows to the language the model
+            # knows; the dialect itself survives in the words, not the model id.
+            kwargs["language_id"] = language.split("-")[0].lower()
+        wav = _clone.generate(text, **kwargs)
+        rate = int(getattr(_clone, "sr", 24000))
+        return _wav(wav.squeeze().cpu().numpy() if hasattr(wav, "cpu") else wav, rate)
+    finally:
+        if path:
+            try:
+                os.remove(path)
+            except OSError:
+                pass