museq 0.45.2__py3-none-any.whl

muse/__init__.py

@@ -0,0 +1,87 @@
+"""Muse: model-agnostic multi-modality generation server.
+
+The authoritative list of supported modalities lives in
+`muse.core.discovery.discover_modalities()`, which scans
+`src/muse/modalities/` plus any user-configured dirs. As of v0.32.0
+the bundled modalities are:
+
+  - audio/embedding: /v1/audio/embeddings (transformers AutoModel + librosa; MERT, CLAP, wav2vec; multipart upload, OpenAI-shape envelope)
+  - audio/generation: /v1/audio/music, /v1/audio/sfx (Stable Audio Open 1.0; capability-gated)
+  - audio/speech: /v1/audio/speech (TTS: Soprano, Kokoro, Bark)
+  - audio/transcription: /v1/audio/transcriptions, /v1/audio/translations (faster-whisper)
+  - chat/completion: /v1/chat/completions (llama-cpp-python over GGUF)
+  - embedding/text: /v1/embeddings (sentence-transformers)
+  - image/animation: /v1/images/animations (AnimateDiff; short looping clips, animated WebP/GIF/MP4)
+  - image/embedding: /v1/images/embeddings (transformers AutoModel; CLIP, SigLIP, DINOv2)
+  - image/generation: /v1/images/generations, /v1/images/edits (inpaint), /v1/images/variations (diffusers)
+  - image/segmentation: /v1/images/segment (SAM-2; multipart upload, mode-aware: auto/points/boxes/text; PNG or COCO RLE masks)
+  - image/upscale: /v1/images/upscale (StableDiffusionUpscalePipeline; SD x4; multipart upload)
+  - text/classification: /v1/moderations (HF text-classification)
+  - text/rerank: /v1/rerank (sentence-transformers CrossEncoder; Cohere-compat)
+  - text/summarization: /v1/summarize (transformers AutoModelForSeq2SeqLM; Cohere-compat)
+  - video/generation: /v1/video/generations (Wan, CogVideoX; narrative clips, mp4/webm/frames_b64; GPU-required)
+
+v0.32.0 adds CI smoke-tests of fresh per-model venvs (#124). The
+workflow `.github/workflows/fresh-venv-smoke.yml` matrix-tests five
+lightweight bundled models (kokoro-82m, dinov2-small, bart-large-cnn,
+bge-reranker-v2-m3, mert-v1-95m) on every push to main and every PR;
+each job creates a fresh venv, installs only what `muse pull` would
+install, and verifies the model loads via the in-venv probe worker
+(no inference; that's GPU-bound and out of scope). Catches the
+production failure mode where a bundled script's `pip_extras` misses
+a transitive dep that `from_pretrained` (or sentence-transformers, or
+diffusers) pulls in at load time, complementing the v0.30.0 static
+audit (#110) which can only flag direct-import gaps via AST scan.
+Heavy / GPU-only models deferred until paid runner budget allows.
+Local repro: `python scripts/smoke_fresh_venv.py --model_id <id>`.
+
+v0.31.0 consolidates cross-runtime utilities into
+`muse.core.runtime_helpers`: `select_device` (cuda/mps/cpu auto-detect),
+`dtype_for_name` (string-to-torch.dtype map with `fp16`/`bf16`/`fp32`
+aliases), `set_inference_mode` (no-grad switch with the literal
+method-name token kept out of caller bodies), and `LoadTimer` (opt-in
+load-time logging context). Removes ~30 per-runtime copies; an AST-based
+meta-test (`tests/core/test_runtime_helpers_meta.py`) walks every
+runtime and bundled script to flag re-implementations. Behavior-
+preserving; the existing 2150 fast-lane tests pass without modification.
+
+v0.30.0 bundles three operational improvements:
+  - the supervisor starts the gateway after the FIRST worker is healthy
+    (was: ALL workers), so clients can hit the fast workers while slow
+    ones still load. Remaining workers promote on a daemon thread.
+  - bundled scripts in `muse/models/` got a `pip_extras` audit; missing
+    transitive deps (torch, numpy) added to seven manifests; a static
+    regression-guard test parametrized over every bundled script
+    catches future gaps.
+  - new `muse models refresh <id> | --all | --enabled` re-installs
+    `muse[server,<extras>]` plus the model's `pip_extras` into per-model
+    venvs; use after `pip install -U muse` to propagate new server-side
+    deps.
+
+v0.29.0 adds `muse mcp`: an MCP (Model Context Protocol) server that
+exposes muse to LLM clients (Claude Desktop, Cursor, etc.) as 29
+structured tools. 11 admin tools wrap `/v1/admin/*` (gated by
+`MUSE_ADMIN_TOKEN`); 18 inference tools wrap the generation routes.
+Stdio mode is the default; HTTP+SSE mode is available for remote /
+web embedders. Filter mode lets ops pin to admin-only or
+inference-only. See CLAUDE.md "Using muse from Claude Desktop".
+
+v0.28.0 added an admin REST API under `/v1/admin/*` for runtime model
+control (enable/disable/probe/pull/remove without restarting `muse
+serve`). Closed-by-default behind `MUSE_ADMIN_TOKEN`. See README.md
+"Admin endpoints" and CLAUDE.md "Admin REST API" for the full surface.
+
+Heavy backends (transformers, diffusers, faster-whisper, llama-cpp,
+sentence-transformers) are imported lazily inside per-modality runtime
+modules to keep `muse --help` and `muse pull` instant. Each pulled
+model lives in its own venv at `~/.muse/venvs/<model-id>/`.
+
+`__version__` is read from pyproject.toml at install time; this
+fallback covers in-tree imports without an installed muse.
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("muse")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

muse/admin/__init__.py

@@ -0,0 +1,17 @@
+"""Admin REST API for runtime model control.
+
+Mounted on the gateway under /v1/admin/*; gated by MUSE_ADMIN_TOKEN.
+See docs/superpowers/specs/2026-04-28-admin-api-design.md for the full
+wire contract; this package provides:
+
+  - auth: bearer-token verification dependency for FastAPI
+  - jobs: in-memory async-job tracker with 10-minute retention
+  - operations: orchestrates enable / disable / probe / pull / remove
+                via the supervisor singleton
+  - routes/: per-resource APIRouter modules
+  - client: thin Python wrapper for programmatic admin access
+
+The admin surface is closed-by-default. Without MUSE_ADMIN_TOKEN set,
+all admin requests return 503 admin_disabled. With the env var set,
+the request must carry Authorization: Bearer <token>.
+"""

muse/admin/auth.py

@@ -0,0 +1,63 @@
+"""Bearer-token verification for admin endpoints.
+
+The token is read from the MUSE_ADMIN_TOKEN environment variable. With
+no token configured, every admin request is rejected with 503; this is
+the closed-by-default policy. With a token configured, the request must
+carry an Authorization: Bearer <token> header matching the env var.
+
+The token is never echoed in error messages or logs.
+"""
+from __future__ import annotations
+
+import os
+import secrets
+
+from fastapi import Header, HTTPException
+
+ADMIN_TOKEN_ENV = "MUSE_ADMIN_TOKEN"
+
+
+def _err(status: int, code: str, message: str) -> HTTPException:
+    """Build an OpenAI-shape envelope inside an HTTPException.
+
+    The message text never includes the secret token; only static
+    descriptive strings flow through here.
+    """
+    return HTTPException(
+        status_code=status,
+        detail={"error": {
+            "code": code,
+            "message": message,
+            "type": "invalid_request_error",
+        }},
+    )
+
+
+def verify_admin_token(authorization: str | None = Header(default=None)) -> None:
+    """FastAPI dependency: raise unless caller carries the admin bearer.
+
+    Five paths:
+      - env var unset                    -> 503 admin_disabled
+      - header missing                   -> 401 missing_token
+      - header malformed (no "Bearer ")  -> 401 missing_token
+      - header bearer wrong              -> 403 invalid_token
+      - header bearer matches            -> return None (route runs)
+    """
+    expected = os.environ.get(ADMIN_TOKEN_ENV)
+    if not expected:
+        raise _err(
+            503,
+            "admin_disabled",
+            f"Admin endpoints require the {ADMIN_TOKEN_ENV} env var to be set",
+        )
+    if not authorization or not authorization.startswith("Bearer "):
+        raise _err(
+            401,
+            "missing_token",
+            "Authorization: Bearer <token> required",
+        )
+    presented = authorization[len("Bearer "):]
+    # Constant-time compare prevents recovering the token byte-by-byte
+    # via response-time variance.
+    if not secrets.compare_digest(presented, expected):
+        raise _err(403, "invalid_token", "Bad admin token")

muse/admin/client.py

@@ -0,0 +1,195 @@
+"""AdminClient: thin Python wrapper over the /v1/admin/* HTTP surface.
+
+Use this for programmatic admin against a running `muse serve`. For
+in-process usage (no HTTP), import the operations module directly.
+
+Token resolution:
+  1. constructor `token=` arg
+  2. MUSE_ADMIN_TOKEN env var
+  3. None (every call will 503 since the server requires the env var)
+
+Server resolution:
+  1. constructor `base_url=` arg
+  2. MUSE_SERVER env var
+  3. http://localhost:8000
+
+The `wait` helper polls `/jobs/{id}` until the job lands in done/failed.
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+
+class AdminClientError(Exception):
+    """Raised when an admin call returns a non-2xx response.
+
+    `code` is the OpenAI error envelope's `code` field; `status` is
+    the HTTP status. `body` is the raw decoded JSON.
+    """
+
+    def __init__(self, status: int, code: str, message: str, body: Any):
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.body = body
+
+
+class AdminClient:
+    """HTTP client for /v1/admin/* admin endpoints."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 30.0,
+    ):
+        self.base_url = (
+            base_url
+            or os.environ.get("MUSE_SERVER")
+            or "http://localhost:8000"
+        ).rstrip("/")
+        self.token = token or os.environ.get("MUSE_ADMIN_TOKEN")
+        self._timeout = timeout
+
+    def _headers(self) -> dict:
+        if self.token is None:
+            return {}
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        url = f"{self.base_url}{path}"
+        # Per-call `timeout` overrides the constructor's default. None
+        # means "use the constructor's value." This is the escape hatch
+        # for slow operations like warmup, whose cold-load duration
+        # (10-60s) routinely exceeds the constructor default of 30s.
+        timeout = kwargs.pop("timeout", None)
+        if timeout is None:
+            timeout = self._timeout
+        with httpx.Client(timeout=timeout) as client:
+            r = client.request(
+                method,
+                url,
+                headers={**self._headers(), **kwargs.pop("headers", {})},
+                **kwargs,
+            )
+        if r.status_code >= 400:
+            try:
+                body = r.json()
+            except Exception:  # noqa: BLE001
+                body = {"raw": r.text}
+            err = body.get("error") or body.get("detail", {}).get("error") or {}
+            code = err.get("code", "http_error")
+            message = err.get("message", r.text)
+            raise AdminClientError(r.status_code, code, message, body)
+        try:
+            return r.json()
+        except Exception:  # noqa: BLE001
+            return {"raw": r.text}
+
+    # Per-model operations
+
+    def enable(self, model_id: str) -> dict:
+        return self._request("POST", f"/v1/admin/models/{model_id}/enable", json={})
+
+    def disable(self, model_id: str) -> dict:
+        return self._request("POST", f"/v1/admin/models/{model_id}/disable", json={})
+
+    def warmup(self, model_id: str, *, timeout: float | None = None) -> dict:
+        """Pre-load a model via the supervisor's LoadDirector.
+
+        Synchronous on the wire: returns once the director's warmup
+        completes (cold load duration: 10-60s for real models, longer
+        for video / large diffusion models). Returns {"model_id",
+        "worker_port"} on success; raises AdminClientError on 4xx/5xx.
+
+        `timeout` overrides the constructor's default for this call
+        only. The default constructor timeout (30s) is too short for
+        most cold loads; callers driving warmup should pass a more
+        generous value (e.g. 300s) or set timeout via the constructor.
+        None means "use the constructor's value."
+        """
+        return self._request(
+            "POST",
+            f"/v1/admin/models/{model_id}/warmup",
+            json={},
+            timeout=timeout,
+        )
+
+    def probe(
+        self,
+        model_id: str,
+        *,
+        no_inference: bool = False,
+        device: str | None = None,
+    ) -> dict:
+        body = {"no_inference": no_inference}
+        if device is not None:
+            body["device"] = device
+        return self._request("POST", f"/v1/admin/models/{model_id}/probe", json=body)
+
+    def pull(self, identifier: str) -> dict:
+        # Use the documented `_` placeholder path; identifier in body
+        # avoids URL-encoding hf://... slashes.
+        return self._request(
+            "POST",
+            "/v1/admin/models/_/pull",
+            json={"identifier": identifier},
+        )
+
+    def remove(self, model_id: str, *, purge: bool = False) -> dict:
+        return self._request(
+            "DELETE",
+            f"/v1/admin/models/{model_id}",
+            params={"purge": "true" if purge else "false"},
+        )
+
+    def status(self, model_id: str) -> dict:
+        return self._request("GET", f"/v1/admin/models/{model_id}/status")
+
+    # Cluster-wide views
+
+    def memory(self) -> dict:
+        return self._request("GET", "/v1/admin/memory")
+
+    def workers(self) -> dict:
+        return self._request("GET", "/v1/admin/workers")
+
+    def restart_worker(self, port: int) -> dict:
+        return self._request("POST", f"/v1/admin/workers/{port}/restart")
+
+    # Job tracking
+
+    def job(self, job_id: str) -> dict:
+        return self._request("GET", f"/v1/admin/jobs/{job_id}")
+
+    def jobs(self) -> dict:
+        return self._request("GET", "/v1/admin/jobs")
+
+    def wait(
+        self,
+        job_id: str,
+        *,
+        timeout: float = 300.0,
+        poll: float = 1.0,
+    ) -> dict:
+        """Block until job is done or failed; return the final job record.
+
+        Raises TimeoutError if the job never reaches a terminal state
+        within `timeout` seconds.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.job(job_id)
+            if job.get("state") in ("done", "failed"):
+                return job
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"job {job_id} did not finish within {timeout}s "
+                    f"(last state: {job.get('state')})"
+                )
+            time.sleep(poll)

muse/admin/jobs.py

@@ -0,0 +1,165 @@
+"""In-memory async-job tracker for admin operations.
+
+Each enable / pull / probe call returns a Job; the caller polls
+GET /v1/admin/jobs/{id} to observe progression. Jobs persist for ten
+minutes after `finished_at`; older jobs are reaped on every list call
+(lazy reap) to keep memory bounded without a dedicated reaper thread.
+
+The job_id is a uuid4 hex string. Jobs go through:
+  pending -> running -> (done | failed)
+"""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_RETENTION_SECONDS = 600.0  # ten minutes
+_MAX_JOBS = 100
+
+
+@dataclass
+class Job:
+    """One async admin operation.
+
+    `thread` is the daemon worker that runs the operation; tracked so
+    the gateway can join it on shutdown. Not serialized into to_dict.
+    `finished_at_monotonic` is for lazy expiry; not serialized either.
+    """
+    job_id: str
+    op: str
+    model_id: str
+    state: str = "pending"
+    started_at: str = ""
+    finished_at: str | None = None
+    result: dict | None = None
+    error: str | None = None
+    log_lines: list[str] = field(default_factory=list)
+    thread: Any = field(default=None, repr=False)
+    finished_at_monotonic: float | None = field(default=None, repr=False)
+
+    def to_dict(self) -> dict:
+        return {
+            "job_id": self.job_id,
+            "op": self.op,
+            "model_id": self.model_id,
+            "state": self.state,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "result": self.result,
+            "error": self.error,
+            "log_lines": list(self.log_lines),
+        }
+
+
+class JobStore:
+    """Thread-safe in-memory job map with lazy expiry.
+
+    `retention_seconds` controls how long a finished job stays
+    addressable via `get`/`list_recent`. The default is 10 minutes,
+    matching the spec.
+
+    `max_jobs` caps the live deque so we never grow unboundedly even
+    when nothing finishes (e.g. all pending). The deque drops the
+    oldest job_id when full; the dict entry stays addressable until
+    expiry, but `list_recent` only returns entries that are also in
+    the deque.
+    """
+
+    def __init__(self, retention_seconds: float = _RETENTION_SECONDS, max_jobs: int = _MAX_JOBS):
+        self._jobs: dict[str, Job] = {}
+        self._order: deque[str] = deque(maxlen=max_jobs)
+        self._lock = threading.Lock()
+        self._retention = retention_seconds
+
+    def create(self, op: str, model_id: str) -> Job:
+        job = Job(
+            job_id=uuid.uuid4().hex,
+            op=op,
+            model_id=model_id,
+            state="pending",
+            started_at=_now_iso(),
+        )
+        with self._lock:
+            self._reap_expired()
+            self._jobs[job.job_id] = job
+            self._order.append(job.job_id)
+        logger.info("job %s created (op=%s, model=%s)", job.job_id, op, model_id)
+        return job
+
+    def update(self, job_id: str, **fields: Any) -> Job | None:
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job is None:
+                return None
+            for k, v in fields.items():
+                setattr(job, k, v)
+            if job.state in ("done", "failed") and job.finished_at_monotonic is None:
+                job.finished_at = _now_iso()
+                job.finished_at_monotonic = time.monotonic()
+            return job
+
+    def get(self, job_id: str) -> Job | None:
+        with self._lock:
+            self._reap_expired()
+            return self._jobs.get(job_id)
+
+    def list_recent(self) -> list[Job]:
+        """Return jobs newest-first, capped at the deque's maxlen."""
+        with self._lock:
+            self._reap_expired()
+            return [self._jobs[jid] for jid in reversed(self._order) if jid in self._jobs]
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        """Join live worker threads; called on gateway shutdown."""
+        with self._lock:
+            threads = [j.thread for j in self._jobs.values() if j.thread is not None]
+        for t in threads:
+            try:
+                t.join(timeout=timeout)
+            except Exception as e:  # noqa: BLE001
+                logger.warning("error joining job thread: %s", e)
+
+    def _reap_expired(self) -> None:
+        """Drop jobs whose finished_at_monotonic is older than retention.
+
+        Caller must hold `self._lock`.
+        """
+        if self._retention <= 0:
+            return
+        cutoff = time.monotonic() - self._retention
+        expired = [
+            jid for jid, j in self._jobs.items()
+            if j.finished_at_monotonic is not None and j.finished_at_monotonic < cutoff
+        ]
+        for jid in expired:
+            self._jobs.pop(jid, None)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# Module-level default. Tests can build their own JobStore without
+# touching this; production code reaches it through get_default_store.
+_default_store: JobStore | None = None
+
+
+def get_default_store() -> JobStore:
+    global _default_store
+    if _default_store is None:
+        _default_store = JobStore()
+    return _default_store
+
+
+def reset_default_store() -> None:
+    """Test hook: drop the singleton so next get_default_store rebuilds it."""
+    global _default_store
+    _default_store = None