livepilot 1.12.2 → 1.13.0

package/mcp_server/synthesis_brain/adapters/meld.py

@@ -0,0 +1,151 @@
+"""Meld adapter — Ableton 12's newest FM/granular hybrid.
+
+Meld pairs two "Engines" with per-engine algorithms and a shared
+modulation / amp / filter section. PR10 ships one canned proposer:
+engine_algo_swap — changes Engine 1's algorithm to produce a
+materially different core timbre without disturbing the envelope
+or filter. Later PRs add engine-blend, unison, and modulation-matrix
+variants.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Optional
+
+from ...branches import BranchSeed, freeform_seed
+from ..models import (
+    SynthProfile,
+    TimbralFingerprint,
+    ModulationGraph,
+    ArticulationProfile,
+    NATIVE,
+)
+from .base import register_adapter
+
+
+_KNOWN_PARAMS = {
+    "Engine 1 Algorithm",
+    "Engine 2 Algorithm",
+    "Engine 1 Level",
+    "Engine 2 Level",
+    "Engine 1 Morph",
+    "Engine 2 Morph",
+    "Filter Freq",
+    "Filter Res",
+    "Amp A",
+    "Amp D",
+    "Amp S",
+    "Amp R",
+}
+
+
+@register_adapter
+class MeldAdapter:
+    device_name: str = "Meld"
+
+    def extract_profile(
+        self,
+        track_index: int,
+        device_index: int,
+        parameter_state: dict,
+        display_values: Optional[dict] = None,
+        role_hint: str = "",
+    ) -> SynthProfile:
+        notes: list[str] = []
+
+        e1_algo = parameter_state.get("Engine 1 Algorithm")
+        e2_algo = parameter_state.get("Engine 2 Algorithm")
+        if e1_algo is not None and e2_algo is not None and e1_algo == e2_algo:
+            notes.append(
+                "Both Engines on same algorithm — consider differentiating for depth"
+            )
+
+        articulation = ArticulationProfile(
+            attack_ms=float(parameter_state.get("Amp A", 0.0) or 0.0),
+            release_ms=float(parameter_state.get("Amp R", 0.0) or 0.0),
+        )
+
+        mod = ModulationGraph()
+        # Meld has many internal mod routes; PR10 just records engine levels
+        # as rough "sources" so downstream can see the mix balance.
+        e1_level = parameter_state.get("Engine 1 Level", 0.0)
+        e2_level = parameter_state.get("Engine 2 Level", 0.0)
+        if e1_level and e1_level > 0:
+            mod.routes.append({"source": "Engine 1", "target": "output", "amount": e1_level})
+        if e2_level and e2_level > 0:
+            mod.routes.append({"source": "Engine 2", "target": "output", "amount": e2_level})
+
+        focused_state = {k: v for k, v in parameter_state.items() if k in _KNOWN_PARAMS}
+        focused_display = (
+            {k: v for k, v in (display_values or {}).items() if k in _KNOWN_PARAMS}
+            if display_values else {}
+        )
+
+        return SynthProfile(
+            device_name=self.device_name,
+            opacity=NATIVE,
+            track_index=track_index,
+            device_index=device_index,
+            parameter_state=focused_state,
+            display_values=focused_display,
+            role_hint=role_hint,
+            modulation=mod,
+            articulation=articulation,
+            notes=notes,
+        )
+
+    def propose_branches(
+        self,
+        profile: SynthProfile,
+        target: TimbralFingerprint,
+        kernel: Optional[dict] = None,
+    ) -> list[tuple[BranchSeed, dict]]:
+        kernel = kernel or {}
+        freshness = float(kernel.get("freshness", 0.5) or 0.5)
+        track = profile.track_index
+        device = profile.device_index
+
+        # Algorithm indices are device-internal; we propose a relative shift
+        # by +1 (modulo a safe ceiling of 10 — Meld has 12 algos but we're
+        # conservative). Freshness amplifies the shift to +3.
+        current_algo = int(profile.parameter_state.get("Engine 1 Algorithm", 0) or 0)
+        shift = 1 if freshness < 0.5 else 3
+        new_algo = (current_algo + shift) % 10
+
+        seed = freeform_seed(
+            seed_id=_short_id("ml_algo", f"{track}:{device}:{new_algo}"),
+            hypothesis=(
+                f"Meld Engine 1 algorithm swap: {current_algo} → {new_algo} "
+                f"for a materially different core timbre"
+            ),
+            source="synthesis",
+            novelty_label="unexpected" if shift == 3 else "strong",
+            risk_label="medium",
+            affected_scope={
+                "track_indices": [track],
+                "device_paths": [f"track/{track}/device/{device}"],
+            },
+            distinctness_reason="only Meld seed that changes Engine 1 algorithm",
+        )
+        plan = {
+            "steps": [
+                {
+                    "tool": "set_device_parameter",
+                    "params": {
+                        "track_index": track,
+                        "device_index": device,
+                        "parameter_name": "Engine 1 Algorithm",
+                        "value": new_algo,
+                    },
+                },
+            ],
+            "step_count": 1,
+            "summary": f"Engine 1 Algorithm {current_algo} → {new_algo}",
+        }
+        return [(seed, plan)]
+
+
+def _short_id(prefix: str, key: str) -> str:
+    h = hashlib.sha256(f"{prefix}:{key}".encode()).hexdigest()[:10]
+    return f"{prefix}_{h}"

package/mcp_server/synthesis_brain/adapters/operator.py

@@ -0,0 +1,169 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Optional
+
+from ...branches import BranchSeed, freeform_seed
+from ..models import (
+    SynthProfile,
+    TimbralFingerprint,
+    ModulationGraph,
+    ArticulationProfile,
+    NATIVE,
+)
+from .base import register_adapter
+
+
+_KNOWN_PARAMS = {
+    "Algorithm",
+    "Oscillator A Coarse",
+    "Oscillator B Coarse",
+    "Oscillator C Coarse",
+    "Oscillator D Coarse",
+    "Oscillator A Fine",
+    "Oscillator B Fine",
+    "Oscillator A Level",
+    "Oscillator B Level",
+    "Oscillator C Level",
+    "Oscillator D Level",
+    "Oscillator A Attack",
+    "Oscillator A Release",
+    "Filter Frequency",
+    "Filter Resonance",
+    "Time",  # global envelope time
+}
+
+
+@register_adapter
+class OperatorAdapter:
+    """Adapter for Ableton's native Operator."""
+
+    device_name: str = "Operator"
+
+    def extract_profile(
+        self,
+        track_index: int,
+        device_index: int,
+        parameter_state: dict,
+        display_values: Optional[dict] = None,
+        role_hint: str = "",
+    ) -> SynthProfile:
+        notes: list[str] = []
+
+        algo = parameter_state.get("Algorithm", 0)
+        if algo is not None:
+            notes.append(f"Algorithm={algo} — topology governs which ops are carriers vs modulators")
+
+        # Crude modulator-detection: any oscillator with Coarse > 1 and Level > 0
+        # is acting as a modulator. Precise detection needs algorithm decoding,
+        # which lands in PR10.
+        mod_routes = []
+        for op in ("A", "B", "C", "D"):
+            coarse = parameter_state.get(f"Oscillator {op} Coarse", 1)
+            level = parameter_state.get(f"Oscillator {op} Level", 0)
+            if coarse and coarse > 1 and level and level > 0:
+                mod_routes.append({
+                    "source": f"Oscillator {op}",
+                    "target": "(per algorithm)",
+                    "amount": level,
+                    "range": None,
+                    "coarse": coarse,
+                })
+        mod = ModulationGraph(routes=mod_routes)
+
+        articulation = ArticulationProfile(
+            attack_ms=float(parameter_state.get("Oscillator A Attack", 0.0) or 0.0),
+            release_ms=float(parameter_state.get("Oscillator A Release", 0.0) or 0.0),
+        )
+
+        focused_state = {k: v for k, v in parameter_state.items() if k in _KNOWN_PARAMS}
+        focused_display = (
+            {k: v for k, v in (display_values or {}).items() if k in _KNOWN_PARAMS}
+            if display_values
+            else {}
+        )
+
+        return SynthProfile(
+            device_name=self.device_name,
+            opacity=NATIVE,
+            track_index=track_index,
+            device_index=device_index,
+            parameter_state=focused_state,
+            display_values=focused_display,
+            role_hint=role_hint,
+            modulation=mod,
+            articulation=articulation,
+            notes=notes,
+        )
+
+    def propose_branches(
+        self,
+        profile: SynthProfile,
+        target: TimbralFingerprint,
+        kernel: Optional[dict] = None,
+    ) -> list[tuple[BranchSeed, dict]]:
+        kernel = kernel or {}
+        freshness = float(kernel.get("freshness", 0.5) or 0.5)
+        track = profile.track_index
+        device = profile.device_index
+
+        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)
+        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)
+        seed_a = freeform_seed(
+            seed_id=_short_id("op_ratio", f"{track}:{device}:{new_coarse}"),
+            hypothesis=(
+                f"Shift Operator Osc B Coarse from {current_coarse} to {new_coarse} "
+                f"for a {'subtle' if step == 1 else 'significant'} FM tone change"
+            ),
+            source="synthesis",
+            novelty_label="strong" if step == 1 else "unexpected",
+            risk_label="medium",
+            affected_scope={
+                "track_indices": [track],
+                "device_paths": [f"track/{track}/device/{device}"],
+            },
+            distinctness_reason=(
+                "only seed that changes the modulator/carrier ratio on Osc B"
+            ),
+        )
+        plan_a = {
+            "steps": [
+                {
+                    "tool": "set_device_parameter",
+                    "params": {
+                        "track_index": track,
+                        "device_index": device,
+                        "parameter_name": "Oscillator B Coarse",
+                        "value": new_coarse,
+                    },
+                },
+            ],
+            "step_count": 1,
+            "summary": f"Osc B Coarse {current_coarse} → {new_coarse}",
+        }
+        results.append((seed_a, plan_a))
+
+        return results
+
+
+def _short_id(prefix: str, key: str) -> str:
+    h = hashlib.sha256(f"{prefix}:{key}".encode()).hexdigest()[:10]
+    return f"{prefix}_{h}"

package/mcp_server/synthesis_brain/adapters/wavetable.py

@@ -0,0 +1,228 @@
+"""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
+
+Later PRs add: modulation-matrix inversion, filter-envelope reshaping,
+tuning-table variants, sub/body-layer variants.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Optional
+
+from ...branches import BranchSeed, freeform_seed
+from ..models import (
+    SynthProfile,
+    TimbralFingerprint,
+    ModulationGraph,
+    ArticulationProfile,
+    NATIVE,
+)
+from .base import register_adapter
+
+
+# Parameter names we know and care about. Extracted from the Wavetable
+# corpus (see skills/livepilot-core/references/device-knowledge/
+# instruments-synths.md). PR9 uses a small subset; later PRs extend.
+_KNOWN_PARAMS = {
+    "Osc 1 Position",
+    "Osc 2 Position",
+    "Osc 1 Transpose",
+    "Osc 2 Transpose",
+    "Voices",
+    "Voices Detune",
+    "Filter Freq",
+    "Filter Res",
+    "Filter Drive",
+    "Amp Attack",
+    "Amp Release",
+    "LFO 1 Rate",
+    "LFO 1 Amount",
+}
+
+
+@register_adapter
+class WavetableAdapter:
+    """Adapter for Ableton's native Wavetable."""
+
+    device_name: str = "Wavetable"
+
+    def extract_profile(
+        self,
+        track_index: int,
+        device_index: int,
+        parameter_state: dict,
+        display_values: Optional[dict] = None,
+        role_hint: str = "",
+    ) -> SynthProfile:
+        notes: list[str] = []
+
+        voices = parameter_state.get("Voices", 0)
+        detune = parameter_state.get("Voices Detune", 0.0)
+        if voices and voices >= 4 and detune and detune > 0.1:
+            notes.append(
+                f"voices={voices}, detune={detune:.2f} — already rich, avoid over-thickening"
+            )
+        if voices and voices <= 1:
+            notes.append("mono voice mode — width variants must add voices")
+
+        # Articulation from amp envelope when present
+        articulation = ArticulationProfile(
+            attack_ms=float(parameter_state.get("Amp Attack", 0.0) or 0.0),
+            release_ms=float(parameter_state.get("Amp Release", 0.0) or 0.0),
+        )
+
+        # Modulation graph — minimal in PR9, just LFO 1 if it has amount > 0
+        mod = ModulationGraph()
+        lfo_amount = parameter_state.get("LFO 1 Amount", 0.0)
+        if lfo_amount and abs(lfo_amount) > 0.01:
+            mod.routes.append({
+                "source": "LFO 1",
+                "target": "(destination inferred from patch)",
+                "amount": lfo_amount,
+                "range": None,
+            })
+
+        # Filter only the known parameters into parameter_state for a compact
+        # profile — full state is available to callers via the raw dict they
+        # already have. This keeps the profile focused on what adapters use.
+        focused_state = {
+            k: v for k, v in parameter_state.items() if k in _KNOWN_PARAMS
+        }
+        focused_display = (
+            {k: v for k, v in (display_values or {}).items() if k in _KNOWN_PARAMS}
+            if display_values
+            else {}
+        )
+
+        return SynthProfile(
+            device_name=self.device_name,
+            opacity=NATIVE,
+            track_index=track_index,
+            device_index=device_index,
+            parameter_state=focused_state,
+            display_values=focused_display,
+            role_hint=role_hint,
+            modulation=mod,
+            articulation=articulation,
+            notes=notes,
+        )
+
+    def propose_branches(
+        self,
+        profile: SynthProfile,
+        target: TimbralFingerprint,
+        kernel: Optional[dict] = None,
+    ) -> list[tuple[BranchSeed, dict]]:
+        kernel = kernel or {}
+        freshness = float(kernel.get("freshness", 0.5) or 0.5)
+        track = profile.track_index
+        device = profile.device_index
+
+        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.
+        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)
+        else:
+            new_pos = min(1.0, current_pos + shift)
+        seed_a = freeform_seed(
+            seed_id=_short_id("wt_pos", f"{track}:{device}:{new_pos:.2f}"),
+            hypothesis=(
+                f"Shift Wavetable Osc 1 Position from {current_pos:.2f} to {new_pos:.2f} "
+                f"for a contrasting harmonic spectrum"
+            ),
+            source="synthesis",
+            novelty_label="strong" if freshness < 0.7 else "unexpected",
+            risk_label="low",
+            affected_scope={
+                "track_indices": [track],
+                "device_paths": [f"track/{track}/device/{device}"],
+            },
+            distinctness_reason="only seed that changes Osc 1 Position",
+        )
+        plan_a = {
+            "steps": [
+                {
+                    "tool": "set_device_parameter",
+                    "params": {
+                        "track_index": track,
+                        "device_index": device,
+                        "parameter_name": "Osc 1 Position",
+                        "value": round(new_pos, 3),
+                    },
+                },
+            ],
+            "step_count": 1,
+            "summary": f"Osc 1 Position {current_pos:.2f} → {new_pos:.2f}",
+        }
+        results.append((seed_a, plan_a))
+
+        # ── Branch B: voice_width_variant ─────────────────────────────
+        # Push Voices + Detune for a richer stereo image — unless profile
+        # notes flag that voices are already high (avoid over-thickening).
+        skip_width = any("over-thickening" in n for n in profile.notes)
+        if not skip_width:
+            current_voices = float(profile.parameter_state.get("Voices", 1) or 1)
+            current_detune = float(profile.parameter_state.get("Voices Detune", 0.0) or 0.0)
+            new_voices = min(8.0, max(current_voices, 4.0))
+            new_detune = min(0.5, max(current_detune + 0.1, 0.15))
+            seed_b = freeform_seed(
+                seed_id=_short_id("wt_width", f"{track}:{device}:{new_voices}:{new_detune:.2f}"),
+                hypothesis=(
+                    f"Increase Wavetable voices to {int(new_voices)} with detune "
+                    f"{new_detune:.2f} for a wider, richer image"
+                ),
+                source="synthesis",
+                novelty_label="safe",
+                risk_label="low",
+                affected_scope={
+                    "track_indices": [track],
+                    "device_paths": [f"track/{track}/device/{device}"],
+                },
+                distinctness_reason=(
+                    "only seed that changes voice count + detune; focuses on "
+                    "width rather than spectrum"
+                ),
+            )
+            plan_b = {
+                "steps": [
+                    {
+                        "tool": "set_device_parameter",
+                        "params": {
+                            "track_index": track,
+                            "device_index": device,
+                            "parameter_name": "Voices",
+                            "value": new_voices,
+                        },
+                    },
+                    {
+                        "tool": "set_device_parameter",
+                        "params": {
+                            "track_index": track,
+                            "device_index": device,
+                            "parameter_name": "Voices Detune",
+                            "value": round(new_detune, 3),
+                        },
+                    },
+                ],
+                "step_count": 2,
+                "summary": f"Voices → {int(new_voices)}, Detune → {new_detune:.2f}",
+            }
+            results.append((seed_b, plan_b))
+
+        return results
+
+
+def _short_id(prefix: str, key: str) -> str:
+    h = hashlib.sha256(f"{prefix}:{key}".encode()).hexdigest()[:10]
+    return f"{prefix}_{h}"

package/mcp_server/synthesis_brain/engine.py

@@ -0,0 +1,91 @@
+"""Synthesis-brain engine — dispatches to the right adapter based on device name.
+
+Two primary entry points:
+  analyze_synth_patch(device_name, ...) -> SynthProfile
+  propose_synth_branches(device_name, ...) -> list[(BranchSeed, compiled_plan)]
+
+Both are pure Python — no @mcp.tool() decorators in PR9. PR12 wires
+dedicated MCP tools and does the tool-count metadata sweep.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..branches import BranchSeed
+from .adapters import get_adapter, registered_devices
+from .models import SynthProfile, TimbralFingerprint, OPAQUE
+
+
+def supported_devices() -> list[str]:
+    """List devices that synthesis_brain has an adapter for."""
+    return registered_devices()
+
+
+def analyze_synth_patch(
+    device_name: str,
+    track_index: int,
+    device_index: int,
+    parameter_state: dict,
+    display_values: Optional[dict] = None,
+    role_hint: str = "",
+) -> SynthProfile:
+    """Extract a SynthProfile from live parameter state.
+
+    When no adapter exists for the device, returns an opaque SynthProfile —
+    the profile still carries parameter_state + display_values so callers
+    can inspect the raw patch, but without device-specific structure.
+    Opacity lets the composer / Wonder / user-facing layer decide how to
+    handle unsupported devices.
+    """
+    adapter = get_adapter(device_name)
+    if adapter is None:
+        return SynthProfile(
+            device_name=device_name,
+            opacity=OPAQUE,
+            track_index=track_index,
+            device_index=device_index,
+            parameter_state=dict(parameter_state or {}),
+            display_values=dict(display_values or {}),
+            role_hint=role_hint,
+            notes=[
+                f"No synthesis_brain adapter for '{device_name}'; "
+                f"falling back to opaque profile"
+            ],
+        )
+    return adapter.extract_profile(
+        track_index=track_index,
+        device_index=device_index,
+        parameter_state=parameter_state or {},
+        display_values=display_values or {},
+        role_hint=role_hint,
+    )
+
+
+def propose_synth_branches(
+    profile: SynthProfile,
+    target: Optional[TimbralFingerprint] = None,
+    kernel: Optional[dict] = None,
+) -> list[tuple[BranchSeed, dict]]:
+    """Emit synthesis-source branch seeds for the given profile.
+
+    Returns a list of (seed, compiled_plan) tuples. Seeds carry
+    source="synthesis" and a distinctness reason; compiled_plan is the
+    execution_router-ready dict with pre-filled steps. Both can be
+    handed to create_experiment(seeds=[seed_dicts], compiled_plans=[plans])
+    with no further compilation needed.
+
+    When the profile is opaque (no adapter), returns an empty list.
+    Callers can fall back to analytical-only seeds in that case.
+    """
+    if profile.opacity != "native":
+        return []
+    adapter = get_adapter(profile.device_name)
+    if adapter is None:
+        return []
+    target = target or TimbralFingerprint()
+    return adapter.propose_branches(
+        profile=profile,
+        target=target,
+        kernel=kernel or {},
+    )