livepilot 1.13.0 → 1.14.0

package/mcp_server/synthesis_brain/adapters/operator.py

@@ -1,9 +1,20 @@
 """Operator adapter — native-synth-aware branch production for Ableton's Operator.
 
 FM synthesis is defined by operator ratios + algorithm topology + per-op
-envelopes. PR9 ships one canned proposer that shifts a carrier/modulator
-ratio, which is the highest-leverage single parameter change for FM tone.
-Later PRs add algorithm swaps, envelope reshaping, and feedback variants.
+envelopes. PR9 always targeted Oscillator B because modulator role was
+unknown; PR2/v2 decodes Algorithm → which oscillators are actually
+carriers vs modulators, and targets the modulator with the highest Level
+so the ratio shift produces a real timbral change rather than changing
+an inaudible operator.
+
+Strategy: ratio_shift_<operator>. Each seed's producer_payload captures:
+  {schema_version, device_name, track_index, device_index,
+   strategy: "ratio_shift_<op>",
+   topology_hint: {algorithm, carriers, modulators, targeted_op,
+                   current_coarse, new_coarse}}
+
+so later render-verification can confirm the shift actually altered the
+modulated carrier's spectrum.
 """
 
 from __future__ import annotations
@@ -42,6 +53,81 @@ _KNOWN_PARAMS = {
 }
 
 
+# Static topology table for Ableton Operator's 11 algorithms. Each entry
+# names the ops that act as carriers (audible) and modulators (FM sources).
+# Source: Ableton Operator manual, DX7-compatible topologies. The exact
+# modulation routing within an algorithm (who modulates whom) matters less
+# for adapter targeting than the carrier/modulator role — what we need to
+# know is "which op's Coarse, when shifted, produces an audible timbral
+# change?" Answer: any op acting as a modulator.
+#
+# Algorithm numbering follows Ableton's 0-based display order.
+_ALGO_TOPOLOGY: dict[int, dict] = {
+    0:  {"carriers": ["D"],              "modulators": ["A", "B", "C"]},
+    1:  {"carriers": ["B", "D"],         "modulators": ["A", "C"]},
+    2:  {"carriers": ["B", "C", "D"],    "modulators": ["A"]},
+    3:  {"carriers": ["D"],              "modulators": ["A", "B", "C"]},
+    4:  {"carriers": ["C", "D"],         "modulators": ["A", "B"]},
+    5:  {"carriers": ["A", "B", "C", "D"], "modulators": []},
+    6:  {"carriers": ["B", "D"],         "modulators": ["A", "C"]},
+    7:  {"carriers": ["D"],              "modulators": ["A", "B", "C"]},
+    8:  {"carriers": ["B", "C", "D"],    "modulators": ["A"]},
+    9:  {"carriers": ["A", "B", "C", "D"], "modulators": []},
+    10: {"carriers": ["B", "C", "D"],    "modulators": ["A"]},
+}
+
+
+def _topology_for_algorithm(algorithm: int) -> dict:
+    """Look up carrier/modulator roles for an Operator algorithm index."""
+    # Default to algorithm 0 (classic serial chain) if unknown.
+    return _ALGO_TOPOLOGY.get(int(algorithm or 0), _ALGO_TOPOLOGY[0])
+
+
+def _pick_target_modulator(
+    topology: dict,
+    parameter_state: dict,
+) -> Optional[str]:
+    """Pick the modulator with the highest Level — the best shift target.
+
+    Returns the operator letter ("A".."D") or None when the algorithm has
+    no modulators (purely additive algos 5 and 9). Level-based selection
+    ensures the Coarse shift produces an audible change; shifting an
+    op whose Level is 0 is a no-op.
+    """
+    candidates = []
+    for op in topology.get("modulators", []):
+        level_key = f"Oscillator {op} Level"
+        level = float(parameter_state.get(level_key, 0.0) or 0.0)
+        candidates.append((level, op))
+    if not candidates:
+        return None
+    candidates.sort(reverse=True)  # highest level first
+    top_level, top_op = candidates[0]
+    # If every modulator is silent, still return the first one — the shift
+    # primes the patch for a future Level bump. Better than no branch.
+    return top_op
+
+
+def _fallback_carrier_target(
+    topology: dict,
+    parameter_state: dict,
+) -> Optional[str]:
+    """Fallback when algorithm has no modulators (additive algos).
+
+    Picks the carrier with the highest Level; shifting its Coarse changes
+    the fundamental spectrum rather than FM depth.
+    """
+    candidates = []
+    for op in topology.get("carriers", []):
+        level_key = f"Oscillator {op} Level"
+        level = float(parameter_state.get(level_key, 0.0) or 0.0)
+        candidates.append((level, op))
+    if not candidates:
+        return None
+    candidates.sort(reverse=True)
+    return candidates[0][1]
+
+
 @register_adapter
 class OperatorAdapter:
     """Adapter for Ableton's native Operator."""
@@ -117,20 +203,50 @@ class OperatorAdapter:
 
         results: list[tuple[BranchSeed, dict]] = []
 
-        # ── Branch A: ratio_shift on modulator B ─────────────────────
-        # Pick a new Coarse ratio for Oscillator B (a common modulator slot)
-        # that contrasts with current. 2 → 3 is inharmonic, 1 → 2 is octave+,
-        # 3 → 5 is bell-like. Default to +1 coarse step when freshness < 0.5,
-        # +2 steps when higher.
-        current_coarse = int(profile.parameter_state.get("Oscillator B Coarse", 1) or 1)
+        # ── Branch A: algorithm-aware ratio_shift ────────────────────
+        # Decode the current Algorithm, pick the real modulator (highest
+        # Level among the algorithm's modulator ops), and shift its
+        # Coarse. When the algorithm is purely additive (no modulators),
+        # fall back to shifting the dominant carrier — changes the
+        # fundamental spectrum instead of FM depth.
+        algorithm = int(profile.parameter_state.get("Algorithm", 0) or 0)
+        topology = _topology_for_algorithm(algorithm)
+        targeted_op = _pick_target_modulator(topology, profile.parameter_state)
+        target_role = "modulator"
+
+        if targeted_op is None:
+            targeted_op = _fallback_carrier_target(topology, profile.parameter_state)
+            target_role = "carrier"
+            if targeted_op is None:
+                # No usable operators — skip the branch rather than emit
+                # something that can't produce a timbral change.
+                return results
+
+        coarse_key = f"Oscillator {targeted_op} Coarse"
+        current_coarse = int(profile.parameter_state.get(coarse_key, 1) or 1)
         step = 1 if freshness < 0.5 else 2
         new_coarse = min(24, current_coarse + step)
         if new_coarse == current_coarse:
             new_coarse = max(1, current_coarse - step)
+
+        strategy = f"ratio_shift_{targeted_op}"
+        topology_hint = {
+            "algorithm": algorithm,
+            "carriers": list(topology.get("carriers", [])),
+            "modulators": list(topology.get("modulators", [])),
+            "targeted_op": targeted_op,
+            "target_role": target_role,
+            "current_coarse": current_coarse,
+            "new_coarse": new_coarse,
+        }
+
         seed_a = freeform_seed(
-            seed_id=_short_id("op_ratio", f"{track}:{device}:{new_coarse}"),
+            seed_id=_short_id(
+                "op_ratio", f"{track}:{device}:{algorithm}:{targeted_op}:{new_coarse}"
+            ),
             hypothesis=(
-                f"Shift Operator Osc B Coarse from {current_coarse} to {new_coarse} "
+                f"Shift Operator Osc {targeted_op} ({target_role}) Coarse "
+                f"{current_coarse} → {new_coarse} under algorithm {algorithm} "
                 f"for a {'subtle' if step == 1 else 'significant'} FM tone change"
             ),
             source="synthesis",
@@ -141,8 +257,15 @@ class OperatorAdapter:
                 "device_paths": [f"track/{track}/device/{device}"],
             },
             distinctness_reason=(
-                "only seed that changes the modulator/carrier ratio on Osc B"
+                f"algorithm-{algorithm} aware shift on {target_role} Osc {targeted_op}"
             ),
+            producer_payload={
+                "device_name": self.device_name,
+                "track_index": track,
+                "device_index": device,
+                "strategy": strategy,
+                "topology_hint": topology_hint,
+            },
         )
         plan_a = {
             "steps": [
@@ -151,13 +274,13 @@ class OperatorAdapter:
                     "params": {
                         "track_index": track,
                         "device_index": device,
-                        "parameter_name": "Oscillator B Coarse",
+                        "parameter_name": coarse_key,
                         "value": new_coarse,
                     },
                 },
             ],
             "step_count": 1,
-            "summary": f"Osc B Coarse {current_coarse} → {new_coarse}",
+            "summary": f"Osc {targeted_op} Coarse {current_coarse} → {new_coarse} (algo {algorithm})",
         }
         results.append((seed_a, plan_a))
 

package/mcp_server/synthesis_brain/adapters/wavetable.py

@@ -1,12 +1,31 @@
 """Wavetable adapter — native-synth-aware branch production for Ableton's Wavetable.
 
-Knows the relevant parameter names and proposes two canned variant
-branches per call:
-  - osc_position_shift: moves Osc 1 position to create a timbral contrast
-  - voice_width_variant: increases unison voices and detune for width
+Knows the relevant parameter names. PR9 shipped two canned proposers;
+PR2/v2 adds position-region classification so the shift direction and
+magnitude depend on *where* in the wavetable the patch currently sits,
+not just freshness.
 
-Later PRs add: modulation-matrix inversion, filter-envelope reshaping,
-tuning-table variants, sub/body-layer variants.
+Strategies (selected based on profile + region):
+  - osc_position_to_bright: shift toward the bright/complex end when
+    the current position is sub_region or mid_region and the target
+    timbre asks for brightness.
+  - osc_position_to_dark: shift toward sub/mid when starting bright and
+    the profile or target prefers warmth.
+  - voice_width_variant: increase unison voices + detune for width,
+    unless the patch is already over-thickened.
+
+Each seed's producer_payload captures:
+  {schema_version, device_name, track_index, device_index,
+   strategy, topology_hint: {current_region, target_region,
+   current_pos, new_pos}}
+so PR4 render-verification and future position-to-spectrum mappings can
+refine the heuristic without losing provenance.
+
+Known limitation: region classification is a coarse heuristic on the
+raw Osc 1 Pos float. Specific factory wavetables don't always follow
+the "low value = simple, high value = complex" rule. PR4's render-based
+mapping will refine per-wavetable — producer_payload's topology_hint
+is the contract for that upgrade.
 """
 
 from __future__ import annotations
@@ -45,6 +64,76 @@ _KNOWN_PARAMS = {
 }
 
 
+# Coarse position → region mapping. Most Ableton factory wavetables fade
+# from low-harmonic (position 0) toward high-harmonic (position 1), but
+# this is approximate. PR4 will refine with render-based spectral mapping.
+_WAVETABLE_REGIONS: list[tuple[float, float, str]] = [
+    (0.0, 0.25, "sub_region"),
+    (0.25, 0.5, "mid_region"),
+    (0.5, 0.75, "bright_region"),
+    (0.75, 1.01, "complex_region"),
+]
+
+
+def _classify_position(pos: float) -> str:
+    """Map an Osc 1 Pos float to a coarse spectral region name."""
+    for lo, hi, region in _WAVETABLE_REGIONS:
+        if lo <= pos < hi:
+            return region
+    return "complex_region"
+
+
+def _choose_target_region(
+    current_region: str,
+    target: "TimbralFingerprint",
+) -> str:
+    """Pick a contrasting region based on the target fingerprint.
+
+    When the target asks for more brightness, move toward
+    bright_region/complex_region. When it asks for more warmth or less
+    brightness (negative target.brightness), move toward
+    sub_region/mid_region. When the target is neutral, shift one region
+    away from current for contrast.
+    """
+    want_bright = target.brightness
+    if abs(want_bright) < 0.1:
+        # Neutral target — shift one region away for variety.
+        fallback_map = {
+            "sub_region": "mid_region",
+            "mid_region": "bright_region",
+            "bright_region": "mid_region",
+            "complex_region": "bright_region",
+        }
+        return fallback_map.get(current_region, "mid_region")
+
+    if want_bright > 0:
+        # Bias brighter.
+        upshift = {
+            "sub_region": "mid_region",
+            "mid_region": "bright_region",
+            "bright_region": "complex_region",
+            "complex_region": "complex_region",
+        }
+        return upshift.get(current_region, "bright_region")
+
+    # want_bright < 0 — bias darker.
+    downshift = {
+        "complex_region": "bright_region",
+        "bright_region": "mid_region",
+        "mid_region": "sub_region",
+        "sub_region": "sub_region",
+    }
+    return downshift.get(current_region, "sub_region")
+
+
+def _region_center(region: str) -> float:
+    """Middle of the region's position range — the target for a shift."""
+    for lo, hi, name in _WAVETABLE_REGIONS:
+        if name == region:
+            return round((lo + min(hi, 1.0)) / 2.0, 3)
+    return 0.5
+
+
 @register_adapter
 class WavetableAdapter:
     """Adapter for Ableton's native Wavetable."""
@@ -125,21 +214,47 @@ class WavetableAdapter:
 
         results: list[tuple[BranchSeed, dict]] = []
 
-        # ── Branch A: osc_position_shift ──────────────────────────────
-        # Moves Osc 1 position to a contrasting point. Safe / incremental
-        # when freshness < 0.5; more aggressive shift when higher.
+        # ── Branch A: region-aware Osc 1 Position shift ──────────────
+        # Classify current position into a spectral region, pick a
+        # contrasting target region based on the timbral target, then
+        # shift to that region's center. The actual shift magnitude
+        # (how close to the center) scales with freshness — low
+        # freshness stops partway, high freshness commits fully.
         current_pos = float(profile.parameter_state.get("Osc 1 Position", 0.0) or 0.0)
-        shift = 0.2 if freshness < 0.5 else 0.45
-        # Wrap within [0, 1]; if the current position is high, shift down.
-        if current_pos + shift > 1.0:
-            new_pos = max(0.0, current_pos - shift)
+        current_region = _classify_position(current_pos)
+        target_region = _choose_target_region(current_region, target)
+        region_target_pos = _region_center(target_region)
+
+        # Blend: low freshness only moves partway toward the target region,
+        # high freshness commits fully.
+        blend = 0.4 if freshness < 0.5 else 1.0
+        new_pos = round(
+            current_pos + (region_target_pos - current_pos) * blend, 3
+        )
+        new_pos = max(0.0, min(1.0, new_pos))
+
+        # Strategy name reflects direction (pick name from target region).
+        if target_region in ("bright_region", "complex_region"):
+            strategy = "osc_position_to_bright"
+        elif target_region in ("sub_region", "mid_region"):
+            strategy = "osc_position_to_dark"
         else:
-            new_pos = min(1.0, current_pos + shift)
+            strategy = "osc_position_shift"
+
+        topology_hint = {
+            "current_region": current_region,
+            "target_region": target_region,
+            "current_pos": current_pos,
+            "new_pos": new_pos,
+        }
+
         seed_a = freeform_seed(
-            seed_id=_short_id("wt_pos", f"{track}:{device}:{new_pos:.2f}"),
+            seed_id=_short_id(
+                "wt_pos", f"{track}:{device}:{current_region}:{target_region}:{new_pos:.2f}"
+            ),
             hypothesis=(
-                f"Shift Wavetable Osc 1 Position from {current_pos:.2f} to {new_pos:.2f} "
-                f"for a contrasting harmonic spectrum"
+                f"Shift Wavetable Osc 1 Position {current_pos:.2f} ({current_region}) → "
+                f"{new_pos:.2f} ({target_region}) for a {strategy.split('_to_')[-1]} spectrum"
             ),
             source="synthesis",
             novelty_label="strong" if freshness < 0.7 else "unexpected",
@@ -148,7 +263,16 @@ class WavetableAdapter:
                 "track_indices": [track],
                 "device_paths": [f"track/{track}/device/{device}"],
             },
-            distinctness_reason="only seed that changes Osc 1 Position",
+            distinctness_reason=(
+                f"moves Osc 1 Position from {current_region} to {target_region}"
+            ),
+            producer_payload={
+                "device_name": self.device_name,
+                "track_index": track,
+                "device_index": device,
+                "strategy": strategy,
+                "topology_hint": topology_hint,
+            },
         )
         plan_a = {
             "steps": [
@@ -158,12 +282,12 @@ class WavetableAdapter:
                         "track_index": track,
                         "device_index": device,
                         "parameter_name": "Osc 1 Position",
-                        "value": round(new_pos, 3),
+                        "value": new_pos,
                     },
                 },
             ],
             "step_count": 1,
-            "summary": f"Osc 1 Position {current_pos:.2f} → {new_pos:.2f}",
+            "summary": f"Osc 1 Position {current_pos:.2f} ({current_region}) → {new_pos:.2f} ({target_region})",
         }
         results.append((seed_a, plan_a))
 
@@ -193,6 +317,18 @@ class WavetableAdapter:
                     "only seed that changes voice count + detune; focuses on "
                     "width rather than spectrum"
                 ),
+                producer_payload={
+                    "device_name": self.device_name,
+                    "track_index": track,
+                    "device_index": device,
+                    "strategy": "voice_width_variant",
+                    "topology_hint": {
+                        "current_voices": int(current_voices),
+                        "current_detune": current_detune,
+                        "new_voices": int(new_voices),
+                        "new_detune": new_detune,
+                    },
+                },
             )
             plan_b = {
                 "steps": [

package/mcp_server/synthesis_brain/tools.py

@@ -0,0 +1,231 @@
+"""MCP tools for the synthesis_brain subsystem (PR5/v2).
+
+Four user-facing wrappers that expose the Python-callable internals
+through the MCP surface. Thin wrappers by design — all intelligence
+lives in adapters/engine.py; these tools handle ctx plumbing, param
+rehydration, and response shaping.
+
+Tools:
+  analyze_synth_patch(track_index, device_index, role_hint?)
+    → SynthProfile dict for any supported native synth on the given
+       track+device. Fetches parameter state via get_device_parameters
+       and display_values via get_display_values.
+
+  propose_synth_branches(track_index, device_index, target?, freshness?)
+    → List of (seed_dict, compiled_plan) pairs. Feed directly to
+       create_experiment(seeds=seed_dicts, compiled_plans=plans) OR
+       skip the plans list to have run_experiment compile from move_id
+       (not applicable here — synthesis seeds always ship with plans).
+
+  extract_timbre_fingerprint(spectrum?, loudness?, spectral_shape?)
+    → TimbralFingerprint dict. Pure transform; no I/O. Callers that
+       have already captured audio analysis dicts can convert them to
+       a fingerprint without going through the full render-verify path.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from .engine import analyze_synth_patch as _analyze_synth_patch
+from .engine import propose_synth_branches as _propose_synth_branches
+from .engine import supported_devices
+from .timbre import extract_timbre_fingerprint as _extract_fp
+from .models import TimbralFingerprint
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+@mcp.tool()
+def analyze_synth_patch(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    role_hint: str = "",
+) -> dict:
+    """Extract a SynthProfile for a native synth on the given track+device.
+
+    Fetches live parameter state + display_values from Ableton, then hands
+    them to the synthesis_brain adapter for that device. When the device
+    isn't a supported native (Wavetable / Operator / Analog / Drift / Meld),
+    returns an opaque SynthProfile — raw params survive for manual inspection
+    but no strategies are proposed.
+
+    role_hint: optional tag ("pad", "lead", "bass", "pluck", "stab",
+        "drone") that gates adapter strategy selection. Leave empty when
+        the role is ambiguous.
+
+    Returns: SynthProfile dict with device_name, opacity, track_index,
+    device_index, parameter_state, display_values, role_hint, modulation,
+    articulation, notes.
+    """
+    ableton = _get_ableton(ctx)
+    try:
+        info = ableton.send_command(
+            "get_device_info",
+            {"track_index": track_index, "device_index": device_index},
+        )
+    except Exception as exc:
+        return {"error": f"get_device_info failed: {exc}"}
+    if not isinstance(info, dict) or "error" in info:
+        return {"error": info.get("error") if isinstance(info, dict) else "device not found"}
+
+    device_name = info.get("name") or info.get("class_name") or ""
+
+    try:
+        params_result = ableton.send_command(
+            "get_device_parameters",
+            {"track_index": track_index, "device_index": device_index},
+        )
+    except Exception as exc:
+        return {"error": f"get_device_parameters failed: {exc}"}
+
+    parameter_state: dict = {}
+    display_values: dict = {}
+    if isinstance(params_result, dict):
+        for p in params_result.get("parameters", []) or []:
+            name = p.get("name")
+            if name is None:
+                continue
+            parameter_state[name] = p.get("value")
+            if "value_string" in p:
+                display_values[name] = p["value_string"]
+
+    profile = _analyze_synth_patch(
+        device_name=device_name,
+        track_index=int(track_index),
+        device_index=int(device_index),
+        parameter_state=parameter_state,
+        display_values=display_values,
+        role_hint=role_hint,
+    )
+    result = profile.to_dict()
+    result["supported_devices"] = supported_devices()
+    return result
+
+
+@mcp.tool()
+def propose_synth_branches(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    target: Optional[dict] = None,
+    freshness: float = 0.5,
+    role_hint: str = "",
+) -> dict:
+    """Propose branch seeds + pre-compiled plans for a native synth.
+
+    Fetches the device's current parameters (via analyze_synth_patch),
+    hands them to the appropriate adapter, and returns the emitted
+    (seed, plan) pairs as two parallel lists suitable for
+    create_experiment(seeds=..., compiled_plans=...).
+
+    target: optional TimbralFingerprint dict ({"brightness": 0.3, ...}).
+        Seeds that know about target direction (synthesis_brain adapters)
+        will score their diffs against it during run_experiment with
+        render_verify=True. When omitted, adapters shift based on freshness
+        alone and role_hint gating.
+
+    freshness: 0.0-1.0; threaded into kernel for adapter magnitude scaling.
+
+    Returns:
+      {
+        "device_name": str,
+        "branch_count": int,
+        "seeds": [BranchSeed.to_dict(), ...],
+        "compiled_plans": [plan_dict, ...]    (parallel to seeds),
+        "warnings": list,
+      }
+
+    Each seed's producer_payload captures strategy + topology_hint so
+    PR3/PR4 winner-commit and render-verify can refine behavior without
+    losing provenance.
+    """
+    profile_dict = analyze_synth_patch(
+        ctx, track_index=int(track_index), device_index=int(device_index),
+        role_hint=role_hint,
+    )
+    if "error" in profile_dict:
+        return profile_dict
+
+    device_name = profile_dict.get("device_name", "")
+    if profile_dict.get("opacity") != "native":
+        return {
+            "device_name": device_name,
+            "branch_count": 0,
+            "seeds": [],
+            "compiled_plans": [],
+            "warnings": [
+                f"'{device_name}' is not a supported native synth — "
+                f"synthesis_brain only knows about {supported_devices()}"
+            ],
+        }
+
+    # Rehydrate the SynthProfile from the dict (round-trip is lossy for
+    # some nested fields, so we re-analyze with the original parameter
+    # state captured by analyze_synth_patch).
+    from .engine import analyze_synth_patch as _refetch
+    profile = _refetch(
+        device_name=device_name,
+        track_index=int(track_index),
+        device_index=int(device_index),
+        parameter_state=profile_dict.get("parameter_state") or {},
+        display_values=profile_dict.get("display_values") or {},
+        role_hint=role_hint or profile_dict.get("role_hint", ""),
+    )
+
+    target_fp = TimbralFingerprint(**{
+        k: float(v) for k, v in (target or {}).items()
+        if k in TimbralFingerprint.__dataclass_fields__ and isinstance(v, (int, float))
+    })
+    kernel = {"freshness": float(freshness)}
+
+    pairs = _propose_synth_branches(profile, target=target_fp, kernel=kernel)
+
+    seeds = [s.to_dict() for s, _ in pairs]
+    plans = [p for _, p in pairs]
+    return {
+        "device_name": device_name,
+        "branch_count": len(seeds),
+        "seeds": seeds,
+        "compiled_plans": plans,
+        "warnings": [],
+    }
+
+
+@mcp.tool()
+def extract_timbre_fingerprint(
+    ctx: Context,
+    spectrum: Optional[dict] = None,
+    loudness: Optional[dict] = None,
+    spectral_shape: Optional[dict] = None,
+) -> dict:
+    """Build a TimbralFingerprint from analysis dicts.
+
+    Pure transform — no I/O. Useful when you already have spectrum +
+    loudness + spectral_shape dicts (e.g. from analyze_spectrum_offline
+    + analyze_loudness + get_spectral_shape) and want the 9-dimensional
+    fingerprint without going through the full render-verify pipeline.
+
+    Inputs are all optional; the fingerprint degrades gracefully to
+    neutral (all-zero) when no signal data is present.
+
+    Returns: TimbralFingerprint dict with brightness, warmth, bite,
+    softness, instability, width, texture_density, movement, polish
+    — each in [-1.0, 1.0].
+    """
+    fp = _extract_fp(
+        spectrum=spectrum,
+        loudness=loudness,
+        spectral_shape=spectral_shape,
+    )
+    return fp.to_dict()

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 398 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
+  "description": "Agentic production system for Ableton Live 12 — 402 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
   "author": "Pilot Studio",
   "license": "BSL-1.1",
   "type": "commonjs",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.13.0"
+__version__ = "1.14.0"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router