livepilot 1.27.2 → 1.27.3

package/mcp_server/project_brain/models.py

@@ -128,6 +128,7 @@ class SectionNode:
     section_type: str = "unknown"
     energy: float = 0.0
     density: float = 0.0
+    tracks_active: list[int] = field(default_factory=list)
 
     def to_dict(self) -> dict:
         return {
@@ -137,6 +138,7 @@ class SectionNode:
             "section_type": self.section_type,
             "energy": self.energy,
             "density": self.density,
+            "tracks_active": list(self.tracks_active),
         }
 
 

package/mcp_server/project_brain/role_graph.py

@@ -41,18 +41,24 @@ def build_role_graph(
     # Convert brain section dicts to composition-engine SectionNodes
     ce_sections = []
     for sec in sections:
-        # Determine which tracks are active in this section
-        # If notes_map has data for this section, those tracks are active
+        # Determine which tracks are active in this section.
+        # Primary source is the clip-presence matrix (`tracks_active`),
+        # which includes AUDIO tracks that carry no MIDI notes. Union in
+        # any note-bearing tracks as a fallback so MIDI-only data (legacy
+        # callers that pass no tracks_active) still produces roles.
         section_id = sec.get("section_id", sec.get("id", ""))
-        active_tracks = []
+        active_set = {int(t) for t in (sec.get("tracks_active") or [])}
         section_notes = notes_map.get(section_id, {})
         for t_idx, notes in section_notes.items():
             if notes:
-                active_tracks.append(t_idx)
+                active_set.add(int(t_idx))
 
-        # Also include all tracks if no notes data (assume all active)
-        if not active_tracks and not notes_map:
-            active_tracks = [t.get("index", 0) for t in track_data]
+        # Also include all tracks if no clip-presence and no notes data
+        # (assume all active — e.g. a bare section with no matrix info).
+        if not active_set and not notes_map:
+            active_set = {int(t.get("index", 0)) for t in track_data}
+
+        active_tracks = sorted(active_set)
 
         try:
             stype = CESectionType(sec.get("section_type", "unknown"))

package/mcp_server/reference_engine/gap_analyzer.py

@@ -22,10 +22,49 @@ _RELEVANCE_THRESHOLDS: dict[str, float] = {
     "harmonic": 0.0,     # always relevant if different
 }
 
+# Per-domain normalization scales for _compute_overall_distance. Raw deltas
+# live in incompatible units (loudness in LU, width/spectral/density in 0-1
+# fractions, pacing in section COUNT), so summing their squares directly lets
+# the large-magnitude domains (loudness, pacing) dominate while sub-unity
+# spectral/width deltas contribute nothing (P2-37). Dividing each delta by a
+# characteristic "one notable step" for its domain converts every term into a
+# comparable, dimensionless number before the Euclidean sum.
+_NORMALIZATION_SCALES: dict[str, float] = {
+    "loudness": 6.0,     # ~6 LU is a clearly audible loudness gap
+    "spectral": 0.1,     # a 0.1 shift in a band's energy fraction is large
+    "width": 0.2,        # 0.2 of the 0-1 stereo-width range is substantial
+    "density": 0.3,      # 0.3 of the 0-1 density range is a big arrangement move
+    "pacing": 2.0,       # a 2-section structural difference is significant
+    "harmonic": 1.0,     # harmonic delta is already a 0/1 indicator
+}
+_DEFAULT_NORMALIZATION_SCALE = 1.0
+
 # When a gap exceeds this fraction of the project value, closing it
 # risks flattening identity.
 _IDENTITY_WARNING_THRESHOLD = 0.6
 
+# ReferenceProfile.loudness_posture is always integrated LUFS (see models.py).
+# The project snapshot may report loudness in a different scale, so we tag it
+# with "loudness_unit" and convert to LUFS here before differencing. The ITU
+# BS.1770 K-weighting has near-unity broadband gain plus a fixed -0.691 dB
+# absolute-calibration offset, so a full-program RMS dBFS ≈ LUFS - 0.691. This
+# is an approximation (it ignores K-weighting's frequency tilt and gating), but
+# it keeps both sides of the loudness delta on the SAME axis — far better than
+# subtracting a plain dBFS RMS from an integrated LUFS (P2-36).
+_RMS_DBFS_TO_LUFS_OFFSET = -0.691
+
+
+def _project_loudness_in_lufs(loudness: float, unit: str) -> float:
+    """Convert a project-snapshot loudness reading to the integrated-LUFS
+    scale used by ReferenceProfile.loudness_posture."""
+    if unit in ("lufs", "integrated_lufs"):
+        return loudness
+    if unit in ("rms_dbfs", "dbfs"):
+        return loudness + _RMS_DBFS_TO_LUFS_OFFSET
+    # Unknown unit: assume it is already on the LUFS axis rather than
+    # corrupting it with an offset we can't justify.
+    return loudness
+
 
 # ── Main analysis ──────────────────────────────────────────────────
 
@@ -50,7 +89,12 @@ def analyze_gaps(
     ref_id = f"{reference.source_type}"
 
     # 1. Loudness gap
-    proj_loudness = project_snapshot.get("loudness", 0.0)
+    # Both sides must be on the integrated-LUFS axis. The reference always is;
+    # the project snapshot declares its unit so we can convert (P2-36).
+    raw_loudness = project_snapshot.get("loudness", 0.0)
+    proj_loudness = _project_loudness_in_lufs(
+        raw_loudness, project_snapshot.get("loudness_unit", "lufs")
+    )
     if reference.loudness_posture != 0.0 or proj_loudness != 0.0:
         delta = proj_loudness - reference.loudness_posture
         gaps.append(GapEntry(
@@ -200,11 +244,22 @@ def _is_identity_risk(project_value: float, delta: float) -> bool:
 
 
 def _compute_overall_distance(gaps: list[GapEntry]) -> float:
-    """Euclidean-like distance across all relevant gap deltas."""
+    """Euclidean distance across relevant gap deltas, normalized per-domain.
+
+    Each delta is divided by a characteristic scale for its domain so that
+    deltas measured in incompatible units (LU, 0-1 fractions, section counts)
+    become dimensionless and comparable before the Euclidean sum (P2-37).
+    """
     relevant = [g for g in gaps if g.relevant]
     if not relevant:
         return 0.0
-    sum_sq = sum(g.delta ** 2 for g in relevant)
+    sum_sq = 0.0
+    for g in relevant:
+        scale = _NORMALIZATION_SCALES.get(g.domain, _DEFAULT_NORMALIZATION_SCALE)
+        if scale <= 0:
+            scale = _DEFAULT_NORMALIZATION_SCALE
+        normalized = g.delta / scale
+        sum_sq += normalized ** 2
     return math.sqrt(sum_sq)
 
 

package/mcp_server/reference_engine/profile_builder.py

@@ -24,10 +24,30 @@ def build_audio_reference_profile(comparison_data: dict) -> ReferenceProfile:
     """
     band_deltas = comparison_data.get("band_deltas", {})
 
-    # Reconstruct approximate reference spectral contour from band deltas.
-    # The deltas are (mix - ref), so ref bands are conceptually the baseline.
+    # The reference profile's band_balance MUST be the reference's OWN
+    # absolute per-band energy — NOT band_deltas (mix - ref), which is a
+    # different quantity entirely (a signed difference, not a level). Using
+    # the deltas here made analyze_gaps compute (proj_band - delta), so an
+    # identical mix produced a spurious gap equal to the project's own band
+    # energy instead of ~0.
+    #
+    # Prefer the absolute reference_band_balance emitted by
+    # compare_to_reference. If only mix bands + deltas are present,
+    # reconstruct ref = mix - delta. Fall back to {} (no spectral contour)
+    # rather than silently treating deltas as levels.
+    ref_band_balance = comparison_data.get("reference_band_balance")
+    if not ref_band_balance:
+        mix_band_balance = comparison_data.get("mix_band_balance")
+        if mix_band_balance and band_deltas:
+            ref_band_balance = {
+                band: round(mix_band_balance.get(band, 0.0) - delta, 6)
+                for band, delta in band_deltas.items()
+            }
+        else:
+            ref_band_balance = {}
+
     spectral_contour: dict = {
-        "band_balance": band_deltas,
+        "band_balance": ref_band_balance,
         "centroid_delta_hz": comparison_data.get("centroid_delta_hz", 0.0),
     }
 
@@ -103,7 +123,9 @@ def build_style_reference_profile(style_tactics: list[dict]) -> ReferenceProfile
     # shape — e.g., Auto Filter at 800Hz low-pass = darker spectrum,
     # Utility Width > 0.6 = wider stereo). Rough but non-empty values
     # are better than zeros for downstream reference-gap analysis.
-    loudness_posture = _derive_loudness_posture(style_tactics)
+    # loudness_posture is contracted to be integrated LUFS, so the [-1,+1]
+    # device-chain posture is mapped onto the LUFS axis (_style_posture_to_lufs).
+    loudness_posture = _style_posture_to_lufs(_derive_loudness_posture(style_tactics))
     spectral_contour = _derive_spectral_contour(style_tactics)
     width_depth = _derive_width_depth(style_tactics)
 
@@ -163,6 +185,27 @@ def _estimate_density_from_patterns(style_tactics: list[dict]) -> list[float]:
 # ── BUG-B50 derivations — style → loudness/spectral/width heuristics ──────
 
 
+# Style profiles infer a dimensionless loudness POSTURE in [-1, +1] from the
+# device chain (limiters/glue → louder, reverb-heavy → quieter). But
+# ReferenceProfile.loudness_posture is contracted to be integrated LUFS — the
+# gap analyzer differences it directly against the project's LUFS (gap_analyzer
+# lines 92-99). So the posture is mapped onto the LUFS axis: -14 LUFS is the
+# streaming-normalization neutral; ±6 LU spans a hot/limited master
+# (+1 → -8 LUFS) to a dynamic/quiet mix (-1 → -20 LUFS). A no-signal posture of
+# 0 lands on the -14 neutral, yielding ~no spurious loudness gap against a
+# typical project — whereas a raw 0.0 would read as a bogus ~14 LU gap.
+_STYLE_LOUDNESS_NEUTRAL_LUFS = -14.0
+_STYLE_LOUDNESS_RANGE_LU = 6.0
+
+
+def _style_posture_to_lufs(posture: float) -> float:
+    """Map a [-1, +1] device-chain loudness posture onto the integrated-LUFS
+    axis that ReferenceProfile.loudness_posture is contracted to carry."""
+    return round(
+        _STYLE_LOUDNESS_NEUTRAL_LUFS + posture * _STYLE_LOUDNESS_RANGE_LU, 2
+    )
+
+
 def _derive_loudness_posture(style_tactics: list[dict]) -> float:
     """Heuristic: compression / saturation / limiter devices imply a
     specific loudness posture. Glue / Ratio>3 → loud, saturator drive

package/mcp_server/reference_engine/tools.py

@@ -50,6 +50,12 @@ def _fetch_project_snapshot(ctx: Context) -> dict:
 
     snapshot: dict = {
         "loudness": 0.0,
+        # Unit of snapshot["loudness"]. The live SpectralCache only exposes a
+        # plain-RMS value, so the best we can derive here is RMS dBFS — NOT
+        # the K-weighted integrated LUFS that ReferenceProfile.loudness_posture
+        # carries. analyze_gaps reads this tag to convert to a common scale
+        # instead of blindly subtracting dBFS from LUFS (P2-36).
+        "loudness_unit": "rms_dbfs",
         "spectral": {},
         "width": 0.0,
         "density": 0.0,

package/mcp_server/runtime/execution_router.py

@@ -22,12 +22,16 @@ Step-result binding:
 
 from __future__ import annotations
 
+import asyncio
 import inspect
+import logging
 from dataclasses import dataclass
 from typing import Any, Awaitable, Callable, Optional
 
 from .remote_commands import BRIDGE_COMMANDS, REMOTE_COMMANDS
 
+logger = logging.getLogger(__name__)
+
 
 # MCP-only tools that exist as Python functions but NOT as TCP handlers.
 # These must be called through direct import, not ableton.send_command().
@@ -233,7 +237,17 @@ async def _execute_step_async(
                 error="Ableton connection unavailable",
             )
         try:
-            result = ableton.send_command(tool, params)
+            # Offload the blocking TCP round-trip to a worker thread so this
+            # shared executor never stalls the event loop (and therefore the
+            # concurrent UDP analyzer bridge) for the duration of the call.
+            # Prefer the real AbletonConnection's async wrapper when present;
+            # fall back to asyncio.to_thread directly for lightweight test
+            # doubles that only implement send_command.
+            send_command_async = getattr(ableton, "send_command_async", None)
+            if callable(send_command_async):
+                result = await send_command_async(tool, params)
+            else:
+                result = await asyncio.to_thread(ableton.send_command, tool, params)
             if isinstance(result, dict) and "error" in result:
                 return ExecutionResult(ok=False, backend=backend, tool=tool, error=result["error"])
             return ExecutionResult(ok=True, backend=backend, tool=tool, result=result)
@@ -391,3 +405,39 @@ async def execute_plan_steps_async(
             break
 
     return results
+
+
+# ── Undo helper ──────────────────────────────────────────────────────────
+
+async def undo_remote_steps(ableton: Any, exec_results: list[ExecutionResult]) -> int:
+    """Undo the remote_command steps from a list of ExecutionResults.
+
+    Only remote_command steps land on Ableton's linear undo stack — bridge
+    (M4L/OSC) and mcp_tool mutations do NOT, so issuing one `undo` per
+    successful step regardless of backend over-undoes and walks back
+    unrelated prior user edits. This counts successful remote_command
+    steps and issues exactly that many `undo` calls via
+    ``ableton.send_command_async``, stopping early if an undo call raises
+    (leaving the rest un-undone rather than risking a cascading error).
+
+    Extracted from the duplicated experiment/engine.py + preview_studio
+    /tools.py undo-count logic (both had drifted into copy-pasted
+    near-identical blocks) so the "count remote_command successes, then
+    undo that many times" rule lives in exactly one place.
+
+    Returns the number of undo calls actually issued (<= the number of
+    successful remote_command steps; less if an undo call raised partway
+    through).
+    """
+    undo_count = sum(
+        1 for r in exec_results if r.ok and r.backend == "remote_command"
+    )
+    issued = 0
+    for _ in range(undo_count):
+        try:
+            await ableton.send_command_async("undo", {})
+            issued += 1
+        except Exception as exc:
+            logger.debug("undo_remote_steps: undo call failed: %s", exc)
+            break
+    return issued

package/mcp_server/runtime/tools.py

@@ -89,7 +89,6 @@ def _probe_flucoma_package() -> bool:
             externals = package_dir / "externals"
             if externals.exists() and any(externals.glob("fluid.*")):
                 return True
-            return True
         return False
     except Exception as exc:  # noqa: BLE001
         logger.debug("_probe_flucoma_package failed: %s", exc)

package/mcp_server/sample_engine/sources.py

@@ -207,8 +207,6 @@ class SpliceSource:
             if key:
                 # Normalize: user might pass "Cm" or "C#", Splice stores "c" or "c#"
                 # Strip minor suffix for comparison — Splice uses chord_type column
-                key_normalized = key.lower().rstrip("m").rstrip("inor")
-                # But proper suffix removal:
                 k = key.lower()
                 for suffix in ("minor", "min"):
                     if k.endswith(suffix):

package/mcp_server/sample_engine/tools.py

@@ -222,15 +222,13 @@ async def search_samples(
 ) -> dict:
     """Search for samples across Splice library, Ableton browser, and local filesystem.
 
-    Searches all enabled sources in parallel and ranks results.
-    Splice results include rich metadata (key, BPM, genre, tags, pack info,
-    is_premium, price, is_free, preview_url).
+    Searches all enabled sources in parallel, ranked Splice-first, then
+    browser, then filesystem. Splice results carry key/BPM/genre/tags/
+    pack/is_premium/price/is_free/preview_url metadata.
 
-    When the Splice desktop app is running AND grpcio is installed, this
-    searches Splice's ONLINE catalog (19,690+ hits for a generic query)
-    and returns un-downloaded items alongside local files. When gRPC is
-    unavailable, it falls back to the local SQLite index and only returns
-    already-downloaded samples.
+    With the Splice desktop app running + grpcio installed: searches
+    Splice's ONLINE catalog, returning un-downloaded items too. Without
+    gRPC: falls back to the local SQLite index (downloaded samples only).
 
     query: search text like "dark vocal", "breakbeat", "foley metal"
     q: alias for `query` (accepts either name for ergonomics)
@@ -776,24 +774,12 @@ async def get_splice_credits(ctx: Context) -> dict:
     Returns both pockets of the Splice subscription model:
       - `credits_remaining`: Splice.com credits for presets/MIDI/Instrument
       - `daily_quota`: sample-download counter (Ableton Live plan only)
+      - `download_gating`: "daily_quota" (Ableton Live plan) or
+        "credit_floor" (Sounds+/Creator/Creator+ — protects the last
+        CREDIT_HARD_FLOOR credits)
 
-    Example (Ableton Live plan):
-      {
-        "connected": true,
-        "username": "user-1367453956",
-        "plan_raw": "subscribed",
-        "plan_kind": "ableton_live",
-        "sounds_plan_id": 12,
-        "features": {"ableton_unmetered": true, ...},
-        "credits_remaining": 80,
-        "credit_floor": 5,
-        "daily_quota": {
-            "used_today": 3, "remaining_today": 97, "daily_limit": 100,
-            "near_limit": false, "at_limit": false,
-        },
-        "can_download_sample": true,
-        "download_gating": "daily_quota",  # or "credit_floor"
-      }
+    Full example response: livepilot-sample-engine references/
+    splice-tools-notes.md#get_splice_credits--full-response-example-ableton-live-plan.
 
     Returns connected=False (with zero credits) when the Splice desktop app
     isn't running or grpcio isn't installed.
@@ -1538,12 +1524,9 @@ async def splice_describe_sound(
     """Natural-language sample search — the Sounds Plugin's "Describe a Sound".
 
     Splice's AI matches free-form descriptions like "dark ambient pad with
-    shimmer" or "tight 90s house hi-hat" to catalog samples. Hits the
-    GraphQL `SamplesSearch` operation on `surfaces-graphql.splice.com`
-    with `semantic=1` + `rephrase=true` enabled.
-
-    **Status: LIVE** as of 2026-04-22. Endpoint captured via mitmproxy
-    against Splice desktop 5.4.9 + Sounds Plugin.
+    shimmer" or "tight 90s house hi-hat" to catalog samples. Endpoint
+    history: livepilot-sample-engine references/splice-tools-notes.md
+    #splice_describe_sound--splice_generate_variation--endpoint-history.
 
     description: free-text prompt ("warm analog bass under 80bpm")
     bpm:         optional BPM filter
@@ -1590,13 +1573,11 @@ async def splice_generate_variation(
     """Find catalog samples similar to a given Splice sample — the "Variations" feature.
 
     Splice's right-click "Variations" menu item surfaces other catalog
-    samples with similar sonic character. The GraphQL operation name
-    is `AssetSimilarSoundsQuery`. Up to 10 results per call. No credit
-    cost (this is a recommender lookup, not AI audio synthesis — the
-    original naming in the handoff was aspirational).
-
-    **Status: LIVE** as of 2026-04-22. Endpoint captured via mitmproxy
-    against Splice desktop v5.4.9.
+    samples with similar sonic character. Up to 10 results per call. No
+    credit cost — a recommender lookup, not AI audio synthesis (the
+    "generate" naming was aspirational). Endpoint history: livepilot-
+    sample-engine references/splice-tools-notes.md
+    #splice_describe_sound--splice_generate_variation--endpoint-history.
 
     uuid:       source sample's catalog uuid (from `splice_describe_sound`
                 results or any other Splice metadata call)