livepilot 1.16.0 → 1.16.1

package/mcp_server/atlas/enrichments/utility/vector_map.yaml

@@ -0,0 +1,36 @@
+id: vector_map
+name: Vector Map
+sonic_description: >
+  Particle-physics modulation router (Inspired by Nature, Dillon Bastan).
+  One particle drives multiple parameter destinations simultaneously. Unlike
+  an LFO (one source → one destination), Vector Map lets a single particle's
+  position control filter cutoff AND send level AND reverb decay at once —
+  coupled modulation that LFOs cannot produce. Essential for organic,
+  physically-coherent sound design.
+category: modulation_source
+character_tags: [particle_physics, coupled_modulation, multi_destination, generative]
+use_cases: [coupled_modulation, non_trivial_modulation, physical_motion]
+genre_affinity:
+  primary: [experimental, ambient, deep_minimal]
+  secondary: [idm, sound_design]
+complexity: advanced
+introduced_in: "11.0"
+pack: Inspired by Nature
+creator: Dillon Bastan
+class_name: PluginDevice
+
+key_parameters:
+  - name: "Particle Behavior"
+    description: "Gravity, friction, forces — defines how the particle moves."
+  - name: "Destination Mappings"
+    description: "Route the particle's X/Y/velocity to multiple Live parameters."
+  - name: "Depth per destination"
+    description: "How much the particle influences each destination."
+
+signature_techniques:
+  - name: "Coupled filter + reverb motion"
+    description: "Particle X → filter cutoff, particle Y → reverb wet, particle velocity → dry/wet balance. Single physical motion drives a 3-parameter sonic change."
+    aesthetic: [ambient, experimental]
+
+learn_more:
+  pack: "Inspired by Nature"

package/mcp_server/sample_engine/tools.py

@@ -205,6 +205,7 @@ async def search_samples(
     max_results: int = 10,
     free_only: bool = False,
     q: Optional[str] = None,
+    collection_uuid: str = "",
 ) -> dict:
     """Search for samples across Splice library, Ableton browser, and local filesystem.
 
@@ -224,6 +225,9 @@ async def search_samples(
     key: prefer samples in this key (e.g., "Cm", "F#")
     bpm_range: "min-max" BPM range (e.g., "120-130")
     source: "splice", "browser", "filesystem", or None for all
+    collection_uuid: scope Splice results to a user collection (Likes,
+      bass, keys, etc.). Obtain via splice_list_collections. When set,
+      browser/filesystem sources are skipped — this is taste-scoped search.
     max_results: maximum results to return (default 10)
     free_only: if True, only return samples that cost nothing to license
       (IsPremium=False or Price=0). Under the Ableton Live plan these
@@ -247,6 +251,11 @@ async def search_samples(
             except ValueError:
                 pass
 
+    # When scoped to a Splice collection, force source=splice and skip
+    # browser/filesystem since those don't carry collection metadata.
+    if collection_uuid and source is None:
+        source = "splice"
+
     # Splice search — prefer gRPC online catalog when available, fall back
     # to local SQLite index. See docs/2026-04-14-bugs-discovered.md — P0-2.
     if source in (None, "splice"):
@@ -267,6 +276,7 @@ async def search_samples(
                     per_page=max_results,
                     page=1,
                     purchased_only=False,
+                    collection_uuid=collection_uuid,
                 )
                 for s in grpc_result.samples[:max_results]:
                     if free_only and not s.is_free:
@@ -782,11 +792,15 @@ async def get_splice_credits(ctx: Context) -> dict:
         gating = "credit_floor"
         can_download = remaining > CREDIT_HARD_FLOOR
 
+    from ..splice_client.client import _read_plan_kind_override
+    plan_override_active = _read_plan_kind_override()
+
     return {
         "connected": True,
         "username": info.username,
         "plan_raw": info.plan,
         "plan_kind": plan.value,
+        "plan_kind_override": plan_override_active,
         "sounds_plan_id": info.sounds_plan_id,
         "features": info.features,
         "user_uuid": info.user_uuid,
@@ -1091,16 +1105,34 @@ async def splice_preview_sample(
     if client is None or not getattr(client, "connected", False):
         return {"ok": False, "error": "Splice gRPC not connected"}
 
+    # Two-stage lookup: SampleInfo is the fast path but only returns
+    # full metadata (including the signed PreviewURL) for downloaded or
+    # purchased samples. For un-downloaded catalog items, fall back to
+    # SearchSamples(FileHash=...) which hits the catalog index and always
+    # returns PreviewURL. Observed live 2026-04-22.
     sample = None
     try:
         sample = await client.get_sample_info(file_hash)
     except Exception as exc:
-        return {"ok": False, "error": f"SampleInfo failed: {exc}"}
+        logger.debug("SampleInfo lookup failed, falling back to search: %s", exc)
+
+    if sample is None or not sample.preview_url:
+        try:
+            search = await client.search_samples(file_hash=file_hash, per_page=1)
+            if search.samples:
+                sample = search.samples[0]
+        except Exception as exc:
+            return {"ok": False, "error": f"PreviewURL lookup failed: {exc}"}
 
     if sample is None or not sample.preview_url:
         return {
             "ok": False,
-            "error": "No preview URL available for this sample",
+            "error": (
+                "No preview URL available for this sample. Splice may "
+                "require the sample to be in a public catalog index. "
+                "Try splice_catalog_hunt first to obtain a fresh "
+                "preview_url from the search result directly."
+            ),
             "file_hash": file_hash,
         }
 
@@ -1410,9 +1442,23 @@ async def splice_pack_info(ctx: Context, pack_uuid: str) -> dict:
         return err
     if not pack_uuid:
         return {"ok": False, "error": "pack_uuid is required"}
-    pack = await client.get_pack_info(pack_uuid)
+    # Pass the UUID through unchanged — Splice uses two valid UUID formats
+    # (canonical 36-char and extended 43-char with longer last group). The
+    # client tries BOTH forms during ListSamplePacks matching. An earlier
+    # revision pre-truncated to 36 chars here, which incorrectly discarded
+    # part of a legitimate extended UUID (observed 2026-04-22 live: pack
+    # "1170db75-0ce1-5280-bb61-887a0dd7f26bf5a3951" is an owned pack but
+    # pre-truncation made the client look for a UUID that didn't exist in
+    # ListSamplePacks' response).
+    submitted = pack_uuid.strip()
+    pack, err_msg = await client.get_pack_info(submitted)
     if pack is None:
-        return {"ok": False, "error": "Pack not found or gRPC call failed"}
+        return {
+            "ok": False,
+            "error": err_msg or "Pack not found",
+            "pack_uuid_submitted": submitted,
+            "pack_uuid_original": pack_uuid,
+        }
     return {"ok": True, "pack": pack.to_dict()}
 
 

package/mcp_server/server.py

@@ -378,11 +378,21 @@ def _get_all_tools():
             "_local_provider._tools",
             lambda: list(mcp._local_provider._tools.values()),
         ),
-        # Public-API future path (what we're asking for in the upstream FR);
-        # harmless to probe now so that once it ships we can lift the ceiling
-        # without touching this function again.
-        ("list_tools", lambda: list(mcp.list_tools())),
+        # NB: mcp.list_tools() IS the public API, but it's a coroutine —
+        # can't be iterated in a sync context. We skip it here and rely on
+        # the internal probes. When FastMCP exposes a sync view we'll add
+        # it back. (Earlier form tried `list(mcp.list_tools())` which
+        # raised `RuntimeWarning: coroutine was never awaited` at every
+        # module import — removed 2026-04-22.)
     ]
+    # Observation 2026-04-22: some FastMCP 3.x builds keep BOTH the legacy
+    # `_tool_manager._tools` dict AND the newer `_local_provider._components`
+    # registry populated at the same time — but the legacy one lags the
+    # newer one (385 vs 422 during a recent startup). Returning the FIRST
+    # non-empty probe accidentally picked the stale view. Instead, collect
+    # every working probe and return the LARGEST view (the registry with
+    # the most tools is the authoritative one).
+    best: list = []
     for label, fn in probes:
         try:
             tools = fn()
@@ -390,8 +400,10 @@ def _get_all_tools():
             continue
         except Exception:  # noqa: BLE001 — any error from an internal probe means "skip"
             continue
-        if tools:
-            return tools
+        if tools and len(tools) > len(best):
+            best = tools
+    if best:
+        return best
 
     # All probes empty. Surface fastmcp version + attempted paths so the
     # breakage is diagnosable without re-reading the code.

package/mcp_server/splice_client/client.py

@@ -119,6 +119,30 @@ def _try_import_protos():
         return None, None
 
 
+def _read_plan_kind_override() -> Optional[str]:
+    """Read `plan_kind_override` from ~/.livepilot/splice.json, if present.
+
+    Lets the user pin their Splice plan_kind when gRPC data is ambiguous.
+    Example config:
+        {"plan_kind_override": "ableton_live"}
+    Returns None silently on any I/O or JSON error.
+    """
+    import json
+    path = os.path.expanduser("~/.livepilot/splice.json")
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            value = data.get("plan_kind_override")
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    except (OSError, json.JSONDecodeError):
+        pass
+    return None
+
+
 class SpliceGRPCClient:
     """Async gRPC client for Splice desktop's App service."""
 
@@ -486,10 +510,15 @@ class SpliceGRPCClient:
                 int(user.SoundsPlan) if hasattr(user, "SoundsPlan") else 0
             )
             uuid_str = str(user.UUID) if hasattr(user, "UUID") else ""
+            # Read optional plan_kind_override from ~/.livepilot/splice.json.
+            # Users who know their Splice plan can pin the classification
+            # here when the gRPC data is ambiguous. See models.classify_plan.
+            override = _read_plan_kind_override()
             plan_kind = classify_plan(
                 sounds_status=user.SoundsStatus,
                 sounds_plan=sounds_plan,
                 features=features,
+                override=override,
             )
             creds = SpliceCredits(
                 credits=user.Credits,
@@ -658,28 +687,71 @@ class SpliceGRPCClient:
 
     # ── Packs ───────────────────────────────────────────────────────
 
-    async def get_pack_info(self, pack_uuid: str) -> Optional[SplicePack]:
-        """Fetch metadata for a single sample pack."""
+    async def get_pack_info(
+        self, pack_uuid: str, max_pages: int = 5,
+    ) -> tuple[Optional[SplicePack], Optional[str]]:
+        """Fetch metadata for a single sample pack.
+
+        Splice's gRPC `App` service does NOT expose a per-UUID
+        `SamplePackInfo` RPC (only `ListSamplePacks` is published in the
+        service definition — the `SamplePackInfoRequest` / `...Response`
+        messages exist in the descriptor but no RPC binds them). So this
+        implementation paginates `ListSamplePacks` and matches client-side.
+
+        Only finds packs the user has engaged with (owned / downloaded /
+        in their library). Catalog-only packs return None with an
+        explanatory error.
+
+        Returns (pack, error) — `error` is a user-readable string when the
+        lookup didn't find a match.
+        """
         if not self.connected:
-            return None
+            return None, "Splice gRPC not connected"
         pb2 = self._pb2
+        target = pack_uuid.strip()
+        # Splice uses two UUID formats: canonical 36-char and an "extended"
+        # form with a longer last group (observed 43 chars, e.g.
+        # "1170db75-0ce1-5280-bb61-887a0dd7f26bf5a3951"). Both variants
+        # appear in sounds.db and search results. We match BOTH when the
+        # caller submits one form — the other form might be the one the
+        # server returns for the same pack. Observed 2026-04-22.
+        canonical = target[:36] if len(target) > 36 else target
+        targets = {target, canonical}
+        next_token = 0
         try:
-            response = await self.stub.SamplePackInfo(
-                pb2.SamplePackInfoRequest(UUID=pack_uuid),
-                timeout=INFO_TIMEOUT,
-            )
-            p = response.Pack
-            return SplicePack(
-                uuid=p.UUID,
-                name=p.Name,
-                cover_url=p.CoverURL,
-                genre=p.Genre,
-                permalink=p.Permalink,
-                provider_name=p.ProviderName,
-            )
+            for _page in range(max(1, int(max_pages))):
+                response = await self.stub.ListSamplePacks(
+                    pb2.ListSamplePacksRequest(NextToken=next_token),
+                    timeout=INFO_TIMEOUT,
+                )
+                for p in response.SamplePacks:
+                    p_uuid = p.UUID
+                    p_canonical = p_uuid[:36] if len(p_uuid) > 36 else p_uuid
+                    if p_uuid in targets or p_canonical in targets:
+                        return SplicePack(
+                            uuid=p_uuid,
+                            name=p.Name,
+                            cover_url=p.CoverURL,
+                            genre=p.Genre,
+                            permalink=p.Permalink,
+                            provider_name=p.ProviderName,
+                        ), None
+                # If no next-page token, we've exhausted the list.
+                new_token = int(response.NextToken)
+                if new_token == 0 or new_token == next_token:
+                    break
+                next_token = new_token
         except Exception as exc:
-            logger.warning(f"SamplePackInfo failed: {exc}")
-            return None
+            msg = f"ListSamplePacks gRPC call failed: {type(exc).__name__}: {exc}"
+            logger.warning(msg)
+            return None, msg
+        return None, (
+            f"Pack '{target}' not found in the user's library. "
+            "Splice's gRPC only lists packs the user has engaged with "
+            "(owned/downloaded/in library). Catalog-only packs can't be "
+            "looked up via this RPC. Use the Splice website or Desktop app "
+            "to browse un-engaged packs."
+        )
 
     # ── Presets ─────────────────────────────────────────────────────
 

package/mcp_server/splice_client/http_bridge.py

@@ -55,14 +55,31 @@ logger = logging.getLogger(__name__)
 # ── Configuration ─────────────────────────────────────────────────────
 
 
+_DEFAULT_CONFIG_PATH = os.path.expanduser("~/.livepilot/splice.json")
+
+
 @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.
+    Three sources, checked in order of precedence:
+      1. Env vars (highest — useful for one-off tests / CI)
+      2. JSON config file at `~/.livepilot/splice.json` (persistent user config)
+      3. Built-in defaults (unverified guesses — WILL need updating when
+         we capture real traffic)
+
+    JSON config shape:
+      {
+        "base_url": "https://api.splice.com",
+        "describe_endpoint": "/v1/...",
+        "variation_endpoint": "/v1/variations/{file_hash}",
+        "search_with_sound_endpoint": "/v1/...",
+        "timeout_sec": 30.0,
+        "max_retries": 2,
+        "allow_unverified_endpoints": false
+      }
+
+    Any subset of keys is allowed; omitted keys fall through to defaults.
     """
 
     base_url: str = "https://api.splice.com"
@@ -71,40 +88,96 @@ class SpliceHTTPConfig:
     search_with_sound_endpoint: str = "/v1/search-with-sound"
     timeout_sec: float = 30.0
     max_retries: int = 2
+    # Whether any of the above values came from user config (file or env)
+    # rather than the built-in defaults. Used by `is_user_configured`.
+    _user_configured: bool = False
 
     @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)),
+    def from_env(cls, config_path: Optional[str] = None) -> "SpliceHTTPConfig":
+        """Load config: defaults → JSON file → env vars.
+
+        `config_path` override is test-only. Production always uses
+        ~/.livepilot/splice.json (or skips the file silently if absent).
+        """
+        instance = cls()
+        loaded_from_file = False
+
+        # Layer 1: JSON file (persistent user config)
+        path = config_path or _DEFAULT_CONFIG_PATH
+        if os.path.isfile(path):
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                if isinstance(data, dict):
+                    for key in (
+                        "base_url", "describe_endpoint", "variation_endpoint",
+                        "search_with_sound_endpoint",
+                    ):
+                        if key in data and isinstance(data[key], str):
+                            setattr(instance, key, data[key])
+                            loaded_from_file = True
+                    for key in ("timeout_sec",):
+                        if key in data:
+                            try:
+                                setattr(instance, key, float(data[key]))
+                                loaded_from_file = True
+                            except (TypeError, ValueError):
+                                logger.warning(
+                                    "splice.json: %s must be a number", key,
+                                )
+                    for key in ("max_retries",):
+                        if key in data:
+                            try:
+                                setattr(instance, key, int(data[key]))
+                                loaded_from_file = True
+                            except (TypeError, ValueError):
+                                logger.warning(
+                                    "splice.json: %s must be an integer", key,
+                                )
+                    if data.get("allow_unverified_endpoints"):
+                        loaded_from_file = True
+            except (OSError, json.JSONDecodeError) as exc:
+                logger.warning(
+                    "Could not load %s: %s — falling back to defaults/env",
+                    path, exc,
+                )
+
+        # Layer 2: env vars (override file/defaults)
+        env_keys = (
+            ("SPLICE_API_BASE_URL", "base_url", str),
+            ("SPLICE_DESCRIBE_ENDPOINT", "describe_endpoint", str),
+            ("SPLICE_VARIATION_ENDPOINT", "variation_endpoint", str),
+            ("SPLICE_SEARCH_WITH_SOUND_ENDPOINT", "search_with_sound_endpoint", str),
+            ("SPLICE_HTTP_TIMEOUT", "timeout_sec", float),
+            ("SPLICE_HTTP_RETRIES", "max_retries", int),
         )
+        env_configured = False
+        for env_name, attr, cast in env_keys:
+            if env_name in os.environ:
+                try:
+                    setattr(instance, attr, cast(os.environ[env_name]))
+                    env_configured = True
+                except (TypeError, ValueError) as exc:
+                    logger.warning(
+                        "Env %s has invalid value: %s", env_name, exc,
+                    )
+
+        instance._user_configured = (
+            loaded_from_file
+            or env_configured
+            or os.environ.get("SPLICE_ALLOW_UNVERIFIED_ENDPOINTS") == "1"
+        )
+        return instance
 
     @property
     def is_user_configured(self) -> bool:
-        """True when at least one endpoint URL has been overridden by env var.
+        """True when at least one endpoint URL has been overridden by the
+        user (JSON config file or 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"
-        )
+        return self._user_configured
 
 
 # ── Auth token fetch ─────────────────────────────────────────────────

package/mcp_server/splice_client/models.py

@@ -70,10 +70,16 @@ def classify_plan(
     sounds_status: str,
     sounds_plan: int,
     features: Optional[dict[str, bool]] = None,
+    override: Optional[str] = None,
 ) -> PlanKind:
     """Classify the user's Splice plan from the ValidateLogin response.
 
     Priority order (most authoritative first):
+      0. Manual override from ~/.livepilot/splice.json → `plan_kind_override`.
+         Lets users who KNOW their plan bypass the safe-default classifier
+         when Splice's gRPC data is ambiguous (e.g. plan_id we don't
+         recognize + empty `features` + generic "subscribed" status —
+         observed 2026-04-22 with sounds_plan_id=6).
       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",
@@ -83,6 +89,12 @@ def classify_plan(
          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.
     """
+    if override:
+        override_norm = override.strip().lower()
+        for member in PlanKind:
+            if member.value == override_norm:
+                return member
+
     features = features or {}
 
     # Step 1: feature flags are authoritative