livepilot 1.14.1 → 1.16.0

package/mcp_server/splice_client/http_bridge.py

@@ -0,0 +1,361 @@
+"""HTTPS bridge for Splice plugin-exclusive features.
+
+The Splice Sounds Plugin (beta) ships two capabilities that are NOT on the
+local gRPC service:
+  - **Describe a Sound** — natural-language search ("dark ambient pad
+    with shimmer")
+  - **Variations** — generate unique re-keyed / re-tempo'd versions of
+    any sample
+
+Both call `api.splice.com` over HTTPS, authenticated with the session
+token we can read from the local gRPC `GetSession` RPC.
+
+This module is *scaffolding* — it builds the auth flow, endpoint URLs,
+response parsing, and retry/timeout plumbing so that capturing the real
+endpoint shapes (via mitmproxy against the running plugin) is a matter
+of updating the URL templates rather than rebuilding infrastructure.
+
+## How to go from scaffolding to working tool
+
+1. Run mitmproxy in transparent mode against the Splice Sounds Plugin
+   while it makes a Describe a Sound or Variations request.
+2. Capture the real endpoint URL, request body shape, and response body.
+3. Drop the values into `SpliceHTTPConfig` defaults or via env vars:
+     - `SPLICE_API_BASE_URL` (default: https://api.splice.com)
+     - `SPLICE_DESCRIBE_ENDPOINT` (default: /v1/describe)
+     - `SPLICE_VARIATION_ENDPOINT` (default: /v1/variations/{file_hash})
+4. Run `splice_describe_sound("dark pad")` — done.
+
+Until step 4 is complete, the MCP tools return a clear, actionable error
+rather than pretending to work. Zero cheats.
+
+## Why token-based instead of embedding the plugin
+
+The plugin's authentication flow uses Splice's OAuth session tokens.
+These rotate periodically — hardcoding them wouldn't work. Reading from
+`GetSession` RPC means we always use the current session, tied to the
+user's currently-logged-in Splice desktop app.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import ssl
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ── Configuration ─────────────────────────────────────────────────────
+
+
+@dataclass
+class SpliceHTTPConfig:
+    """Endpoint configuration for the HTTPS bridge.
+
+    All fields have env-var overrides so a dev can swap them for testing
+    without code changes. Defaults are best-guesses based on Splice's
+    public URL conventions — they WILL need updating when we capture real
+    traffic. That's expected.
+    """
+
+    base_url: str = "https://api.splice.com"
+    describe_endpoint: str = "/v1/describe"
+    variation_endpoint: str = "/v1/variations/{file_hash}"
+    search_with_sound_endpoint: str = "/v1/search-with-sound"
+    timeout_sec: float = 30.0
+    max_retries: int = 2
+
+    @classmethod
+    def from_env(cls) -> "SpliceHTTPConfig":
+        """Load config from env vars, falling back to defaults."""
+        return cls(
+            base_url=os.environ.get("SPLICE_API_BASE_URL", cls.base_url),
+            describe_endpoint=os.environ.get(
+                "SPLICE_DESCRIBE_ENDPOINT", cls.describe_endpoint,
+            ),
+            variation_endpoint=os.environ.get(
+                "SPLICE_VARIATION_ENDPOINT", cls.variation_endpoint,
+            ),
+            search_with_sound_endpoint=os.environ.get(
+                "SPLICE_SEARCH_WITH_SOUND_ENDPOINT",
+                cls.search_with_sound_endpoint,
+            ),
+            timeout_sec=float(os.environ.get("SPLICE_HTTP_TIMEOUT", cls.timeout_sec)),
+            max_retries=int(os.environ.get("SPLICE_HTTP_RETRIES", cls.max_retries)),
+        )
+
+    @property
+    def is_user_configured(self) -> bool:
+        """True when at least one endpoint URL has been overridden by env var.
+
+        Defaults are unverified guesses; callers check this before making
+        requests so we don't silently hit non-existent endpoints.
+        """
+        return (
+            "SPLICE_API_BASE_URL" in os.environ
+            or "SPLICE_DESCRIBE_ENDPOINT" in os.environ
+            or "SPLICE_VARIATION_ENDPOINT" in os.environ
+            or "SPLICE_SEARCH_WITH_SOUND_ENDPOINT" in os.environ
+            or os.environ.get("SPLICE_ALLOW_UNVERIFIED_ENDPOINTS") == "1"
+        )
+
+
+# ── Auth token fetch ─────────────────────────────────────────────────
+
+
+async def fetch_session_token(grpc_client) -> Optional[str]:
+    """Fetch the current Splice session token from the local gRPC.
+
+    The `GetSession` RPC returns an `Auth` object with a `Token` field —
+    this is the bearer we attach to `api.splice.com` requests. The token
+    rotates periodically so we always fetch fresh rather than caching.
+    """
+    if not grpc_client or not getattr(grpc_client, "connected", False):
+        return None
+    pb2 = getattr(grpc_client, "_pb2", None)
+    if pb2 is None:
+        return None
+    try:
+        response = await grpc_client.stub.GetSession(
+            pb2.GetSessionRequest(), timeout=5.0,
+        )
+        return str(response.Auth.Token) if response.Auth else None
+    except Exception as exc:
+        logger.warning("GetSession RPC failed: %s", exc)
+        return None
+
+
+# ── HTTP client ───────────────────────────────────────────────────────
+
+
+@dataclass
+class SpliceHTTPError(Exception):
+    """Structured error for HTTPS-bridge calls."""
+
+    code: str
+    message: str
+    endpoint: str = ""
+    status_code: int = 0
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.message} ({self.endpoint})"
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": False,
+            "error": self.message,
+            "code": self.code,
+            "endpoint": self.endpoint,
+            "status_code": self.status_code,
+        }
+
+
+class SpliceHTTPBridge:
+    """Low-level HTTPS client for Splice cloud APIs.
+
+    Attaches the bearer token, retries on 5xx, applies a total timeout.
+    Thread-safe — each request builds its own opener. Synchronous network
+    calls run in an executor from the async wrappers.
+    """
+
+    def __init__(
+        self,
+        config: Optional[SpliceHTTPConfig] = None,
+        grpc_client=None,
+    ):
+        self.config = config or SpliceHTTPConfig.from_env()
+        self.grpc_client = grpc_client
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[dict] = None,
+        query: Optional[dict] = None,
+    ) -> Any:
+        token = await fetch_session_token(self.grpc_client)
+        if token is None:
+            raise SpliceHTTPError(
+                code="NO_AUTH",
+                message=(
+                    "Could not fetch Splice session token via GetSession RPC. "
+                    "Is the Splice desktop app running and logged in?"
+                ),
+                endpoint=path,
+            )
+
+        url = self.config.base_url.rstrip("/") + path
+        if query:
+            import urllib.parse
+            qs = urllib.parse.urlencode(query)
+            url = f"{url}?{qs}"
+
+        data_bytes = None
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "User-Agent": "LivePilot/1.15 (+splice-http-bridge)",
+        }
+        if body is not None:
+            data_bytes = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        loop = asyncio.get_running_loop()
+        last_err = None
+        for attempt in range(1 + max(0, self.config.max_retries)):
+            try:
+                return await loop.run_in_executor(
+                    None,
+                    self._perform_sync_request,
+                    url, method, data_bytes, headers,
+                )
+            except SpliceHTTPError as exc:
+                last_err = exc
+                # Retry only on 5xx / network. 4xx is terminal.
+                if exc.status_code and exc.status_code < 500:
+                    raise
+            await asyncio.sleep(min(2 ** attempt, 5))
+        assert last_err is not None
+        raise last_err
+
+    def _perform_sync_request(self, url, method, data_bytes, headers):
+        try:
+            req = urllib.request.Request(
+                url, data=data_bytes, headers=headers, method=method,
+            )
+            context = ssl.create_default_context()
+            with urllib.request.urlopen(
+                req, timeout=self.config.timeout_sec, context=context,
+            ) as resp:
+                raw = resp.read()
+                content_type = resp.headers.get("Content-Type", "")
+                if "application/json" in content_type:
+                    return json.loads(raw.decode("utf-8"))
+                return {"raw": raw.decode("utf-8", errors="replace")}
+        except urllib.error.HTTPError as exc:
+            raise SpliceHTTPError(
+                code="HTTP_ERROR",
+                message=f"HTTP {exc.code}: {exc.reason}",
+                endpoint=url,
+                status_code=exc.code,
+            )
+        except urllib.error.URLError as exc:
+            raise SpliceHTTPError(
+                code="NETWORK_ERROR",
+                message=f"Network error: {exc.reason}",
+                endpoint=url,
+                status_code=0,
+            )
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise SpliceHTTPError(
+                code="DECODE_ERROR",
+                message=f"Response decode failed: {exc}",
+                endpoint=url,
+            )
+
+    # ── Tool-facing helpers ──────────────────────────────────────────
+
+    async def describe_sound(
+        self,
+        description: str,
+        bpm: Optional[int] = None,
+        key: Optional[str] = None,
+        limit: int = 20,
+    ) -> dict:
+        """Natural-language sample search.
+
+        Returns a dict with keys: `samples` (list of sample metadata),
+        `total_hits`, plus whatever Splice echoes back. Shape is best-effort
+        until we capture real traffic — see module docstring.
+        """
+        if not self.config.is_user_configured:
+            raise SpliceHTTPError(
+                code="ENDPOINT_NOT_CONFIGURED",
+                message=(
+                    "Describe a Sound endpoint is unverified. Set "
+                    "SPLICE_DESCRIBE_ENDPOINT (or SPLICE_ALLOW_UNVERIFIED_"
+                    "ENDPOINTS=1) once you've captured the real URL via "
+                    "mitmproxy against the Sounds Plugin."
+                ),
+                endpoint=self.config.describe_endpoint,
+            )
+        body = {
+            "description": description,
+            "limit": int(limit),
+        }
+        if bpm is not None:
+            body["bpm"] = int(bpm)
+        if key:
+            body["key"] = key
+        return await self._request("POST", self.config.describe_endpoint, body=body)
+
+    async def generate_variation(
+        self,
+        file_hash: str,
+        target_key: Optional[str] = None,
+        target_bpm: Optional[int] = None,
+        count: int = 1,
+    ) -> dict:
+        """Generate AI variations of a sample.
+
+        Returns a dict with keys: `variations` (list), `credits_spent`.
+        Shape is best-effort until captured — see module docstring.
+        """
+        if not self.config.is_user_configured:
+            raise SpliceHTTPError(
+                code="ENDPOINT_NOT_CONFIGURED",
+                message=(
+                    "Variations endpoint is unverified. Set "
+                    "SPLICE_VARIATION_ENDPOINT (or SPLICE_ALLOW_UNVERIFIED_"
+                    "ENDPOINTS=1) once you've captured the real URL via "
+                    "mitmproxy against the Sounds Plugin."
+                ),
+                endpoint=self.config.variation_endpoint,
+            )
+        path = self.config.variation_endpoint.format(file_hash=file_hash)
+        body: dict = {"count": max(1, int(count))}
+        if target_key:
+            body["target_key"] = target_key
+        if target_bpm is not None:
+            body["target_bpm"] = int(target_bpm)
+        return await self._request("POST", path, body=body)
+
+    async def search_with_sound(
+        self,
+        audio_path: str,
+        limit: int = 20,
+    ) -> dict:
+        """Sample-reference search — find catalog samples similar to a file.
+
+        Encodes the file as a multipart POST. Wiring waits on a real
+        endpoint capture; the upload shape is the most uncertain part
+        of the bridge.
+        """
+        if not self.config.is_user_configured:
+            raise SpliceHTTPError(
+                code="ENDPOINT_NOT_CONFIGURED",
+                message=(
+                    "Search with Sound endpoint is unverified. Set "
+                    "SPLICE_SEARCH_WITH_SOUND_ENDPOINT (or SPLICE_ALLOW_"
+                    "UNVERIFIED_ENDPOINTS=1) once you've captured the real "
+                    "URL via mitmproxy against the Sounds Plugin."
+                ),
+                endpoint=self.config.search_with_sound_endpoint,
+            )
+        # Multipart upload — reserved for the real-capture wiring.
+        raise SpliceHTTPError(
+            code="NOT_YET_IMPLEMENTED",
+            message=(
+                "search_with_sound multipart upload wiring is pending real-"
+                "endpoint capture. File a follow-up when the Describe a "
+                "Sound endpoint has been mapped — similar shape is likely."
+            ),
+            endpoint=self.config.search_with_sound_endpoint,
+        )

package/mcp_server/splice_client/models.py

@@ -1,11 +1,137 @@
-"""Splice client data models — Python representations of Splice gRPC messages."""
+"""Splice client data models — Python representations of Splice gRPC messages.
+
+Models here mirror the proto messages under `protos/app_pb2.py`.
+See `project_splice_subscription_model.md` for the two-pocket model
+(daily samples vs Splice.com credits) that PlanKind classifies.
+"""
 
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import Optional
 
 
+# ── Plan classification ──────────────────────────────────────────────────
+
+
+class PlanKind(str, Enum):
+    """Classification of Splice subscription plans.
+
+    Splice returns `User.SoundsStatus` as a generic string (often just
+    "subscribed"), so we classify tier via the `Features` map and numeric
+    `SoundsPlan` id. See `project_splice_subscription_model.md`.
+
+    - ABLETON_LIVE: $12.99/mo, 100 samples/day unmetered via Ableton drag-drop
+      + 100 intro credits for Splice.com content. Sample downloads DO NOT
+      cost credits on this plan — they deplete a daily counter.
+    - SOUNDS_PLUS: legacy per-credit tiers (100/300/600/1000) + Creator+.
+      Samples DO cost credits.
+    - CREATOR: $12.99/mo legacy creator plan, 100 credits/mo.
+    - FREE: anonymous or unconverted trial.
+    - UNKNOWN: plan metadata absent — treat like SOUNDS_PLUS (safest).
+    """
+
+    ABLETON_LIVE = "ableton_live"
+    SOUNDS_PLUS = "sounds_plus"
+    CREATOR = "creator"
+    CREATOR_PLUS = "creator_plus"
+    FREE = "free"
+    UNKNOWN = "unknown"
+
+    @property
+    def is_subscribed(self) -> bool:
+        return self != PlanKind.FREE and self != PlanKind.UNKNOWN
+
+    @property
+    def has_daily_sample_quota(self) -> bool:
+        """True iff sample downloads deplete a daily counter, not credits."""
+        return self == PlanKind.ABLETON_LIVE
+
+
+# Feature-flag keys we look for in `User.Features`. Splice sets these in
+# the ValidateLogin response. Names are best-effort — Splice may rename
+# them; the classifier tolerates missing keys.
+_FEATURE_ABLETON_UNMETERED = "ableton_unmetered"
+_FEATURE_ABLETON_LIVE_PLAN = "ableton_live_plan"
+_FEATURE_UNMETERED = "unmetered_downloads"
+_FEATURE_CREATOR_PLUS = "creator_plus"
+
+# Numeric plan IDs we've observed. Splice uses `User.SoundsPlan` as a
+# proprietary enum. These are inferred from the API responses and the
+# public plan catalog.
+_PLAN_ID_ABLETON_LIVE = {12, 13}      # possible IDs for the Ableton plan
+_PLAN_ID_CREATOR_PLUS = {11}
+_PLAN_ID_CREATOR = {1, 2, 3}
+_PLAN_ID_FREE = {0}
+
+
+def classify_plan(
+    sounds_status: str,
+    sounds_plan: int,
+    features: Optional[dict[str, bool]] = None,
+) -> PlanKind:
+    """Classify the user's Splice plan from the ValidateLogin response.
+
+    Priority order (most authoritative first):
+      1. Feature flags — if `ableton_unmetered` etc. is set, trust it.
+      2. Non-zero numeric plan IDs we recognize.
+      3. Free-form status string heuristics — catches "subscribed",
+         "ableton live plan", "creator plus", etc.
+      4. Numeric 0 → FREE only when the status string doesn't
+         contradict. (plan_id=0 alone with status="subscribed" is NOT
+         free — it's just a plan we don't have a numeric ID for yet.)
+      5. Fallback: UNKNOWN so callers keep the safe credit-floor default.
+    """
+    features = features or {}
+
+    # Step 1: feature flags are authoritative
+    if features.get(_FEATURE_ABLETON_UNMETERED) or features.get(_FEATURE_ABLETON_LIVE_PLAN):
+        return PlanKind.ABLETON_LIVE
+    if features.get(_FEATURE_UNMETERED):
+        return PlanKind.ABLETON_LIVE
+    if features.get(_FEATURE_CREATOR_PLUS):
+        return PlanKind.CREATOR_PLUS
+
+    # Step 2: recognized non-zero plan IDs
+    if sounds_plan in _PLAN_ID_ABLETON_LIVE:
+        return PlanKind.ABLETON_LIVE
+    if sounds_plan in _PLAN_ID_CREATOR_PLUS:
+        return PlanKind.CREATOR_PLUS
+    if sounds_plan in _PLAN_ID_CREATOR:
+        return PlanKind.CREATOR
+
+    # Step 3: string heuristics — BEFORE the plan_id=0 FREE check, because
+    # "subscribed" + plan_id=0 means "subscribed plan we don't recognize
+    # numerically", NOT free.
+    status_lower = (sounds_status or "").lower().strip()
+    if "ableton" in status_lower:
+        return PlanKind.ABLETON_LIVE
+    if "creator" in status_lower and "plus" in status_lower:
+        return PlanKind.CREATOR_PLUS
+    if "creator" in status_lower:
+        return PlanKind.CREATOR
+    if status_lower in ("subscribed", "paid", "active", "sounds_plus", "sounds+"):
+        # Generic "subscribed" is ambiguous — SOUNDS_PLUS is the safe
+        # default because it keeps the credit floor on. The MCP tool
+        # documents this.
+        return PlanKind.SOUNDS_PLUS
+    if status_lower in ("free", "trial", "unconverted"):
+        return PlanKind.FREE
+
+    # Step 4: numeric FREE path — only reached when status was silent
+    if sounds_plan in _PLAN_ID_FREE:
+        return PlanKind.FREE
+
+    # Step 5: fallback
+    if not status_lower:
+        return PlanKind.FREE
+    return PlanKind.UNKNOWN
+
+
+# ── Sample & search ──────────────────────────────────────────────────────
+
+
 @dataclass
 class SpliceSample:
     """A sample from the Splice catalog or local library."""
@@ -24,6 +150,7 @@ class SpliceSample:
     pack_uuid: str = ""
     popularity: int = 0
     is_premium: bool = False
+    price: int = 0                # 0 ⇒ free regardless of plan
     preview_url: str = ""
     waveform_url: str = ""
     is_downloaded: bool = False
@@ -42,6 +169,15 @@ class SpliceSample:
     def duration_seconds(self) -> float:
         return self.duration_ms / 1000.0 if self.duration_ms else 0.0
 
+    @property
+    def is_free(self) -> bool:
+        """True iff this sample costs no credits under any plan.
+
+        Splice marks samples as free via `IsPremium == False` or `Price == 0`.
+        This is orthogonal to plan: even a free-tier user can license these.
+        """
+        return (not self.is_premium) or self.price == 0
+
     def to_dict(self) -> dict:
         return {
             "file_hash": self.file_hash,
@@ -60,6 +196,9 @@ class SpliceSample:
             "popularity": self.popularity,
             "is_downloaded": self.is_downloaded,
             "is_premium": self.is_premium,
+            "price": self.price,
+            "is_free": self.is_free,
+            "preview_url": self.preview_url,
         }
 
 
@@ -80,17 +219,142 @@ class SpliceSearchResult:
         }
 
 
+# ── Credits & plan ───────────────────────────────────────────────────────
+
+
 @dataclass
 class SpliceCredits:
-    """User credit status."""
+    """User credit status plus plan classification.
+
+    `plan` is the raw Splice `SoundsStatus` string (e.g. "subscribed").
+    `plan_kind` is our classification — use this for gating decisions.
+    `features` carries the full `Features` map so callers can check
+    granular flags not yet modelled by PlanKind.
+    """
 
     credits: int = 0
     username: str = ""
     plan: str = ""
+    sounds_plan_id: int = 0
+    features: dict[str, bool] = field(default_factory=dict)
+    plan_kind: PlanKind = PlanKind.UNKNOWN
+    user_uuid: str = ""
 
     def to_dict(self) -> dict:
         return {
             "credits": self.credits,
             "username": self.username,
             "plan": self.plan,
+            "sounds_plan_id": self.sounds_plan_id,
+            "plan_kind": self.plan_kind.value,
+            "features": dict(self.features),
+            "user_uuid": self.user_uuid,
+        }
+
+
+# ── Collections (Splice-side personal organization) ──────────────────────
+
+
+@dataclass
+class SpliceCollection:
+    """A user-curated Collection (Likes, custom folders, Daily Picks bookmark)."""
+
+    uuid: str = ""
+    name: str = ""
+    description: str = ""
+    access: str = ""              # "public", "private"
+    permalink: str = ""
+    cover_url: str = ""
+    sample_count: int = 0
+    preset_count: int = 0
+    pack_count: int = 0
+    subscription_count: int = 0
+    created_by_current_user: bool = False
+    creator_username: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "uuid": self.uuid,
+            "name": self.name,
+            "description": self.description,
+            "access": self.access,
+            "permalink": self.permalink,
+            "sample_count": self.sample_count,
+            "preset_count": self.preset_count,
+            "pack_count": self.pack_count,
+            "cover_url": self.cover_url,
+            "owned_by_me": self.created_by_current_user,
+            "creator": self.creator_username,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+
+# ── Packs ────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SplicePack:
+    """A sample pack (Splice `SamplePack` message)."""
+
+    uuid: str = ""
+    name: str = ""
+    cover_url: str = ""
+    genre: str = ""
+    permalink: str = ""
+    provider_name: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "uuid": self.uuid,
+            "name": self.name,
+            "genre": self.genre,
+            "permalink": self.permalink,
+            "provider": self.provider_name,
+            "cover_url": self.cover_url,
+        }
+
+
+# ── Presets ──────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SplicePreset:
+    """A Splice Instrument or VST/AU preset from the catalog."""
+
+    uuid: str = ""
+    file_hash: str = ""
+    filename: str = ""
+    local_path: str = ""
+    tags: list[str] = field(default_factory=list)
+    price: int = 0
+    is_default: bool = False
+    plugin_name: str = ""
+    plugin_version: str = ""
+    provider_name: str = ""
+    pack_uuid: str = ""
+    preview_url: str = ""
+    purchased_at: int = 0
+
+    @property
+    def is_downloaded(self) -> bool:
+        return bool(self.local_path)
+
+    def to_dict(self) -> dict:
+        return {
+            "uuid": self.uuid,
+            "file_hash": self.file_hash,
+            "filename": self.filename,
+            "local_path": self.local_path,
+            "tags": self.tags,
+            "price": self.price,
+            "plugin_name": self.plugin_name,
+            "plugin_version": self.plugin_version,
+            "provider": self.provider_name,
+            "pack_uuid": self.pack_uuid,
+            "is_default": self.is_default,
+            "is_downloaded": self.is_downloaded,
+            "preview_url": self.preview_url,
         }