livepilot 1.12.2 → 1.14.0

package/mcp_server/synthesis_brain/adapters/meld.py

@@ -0,0 +1,261 @@
+"""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 {}
+        results: list[tuple[BranchSeed, dict]] = []
+        for strategy_fn in (_strategy_engine_algo_swap, _strategy_engine_mix_shift):
+            try:
+                maybe = strategy_fn(profile, target, kernel, adapter=self)
+            except Exception:
+                continue
+            if maybe is not None:
+                results.append(maybe)
+        return results
+
+
+# ── Strategy registry ────────────────────────────────────────────────
+
+
+def _strategy_engine_algo_swap(
+    profile: SynthProfile,
+    target: TimbralFingerprint,
+    kernel: dict,
+    adapter,
+) -> Optional[tuple[BranchSeed, dict]]:
+    """Shift Engine 1 Algorithm by +1 (low freshness) or +3 (high).
+
+    Always applicable — algorithm swaps are guaranteed to change tone
+    regardless of current state.
+    """
+    freshness = float(kernel.get("freshness", 0.5) or 0.5)
+    track = profile.track_index
+    device = profile.device_index
+    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="changes Engine 1 algorithm",
+        producer_payload={
+            "device_name": adapter.device_name,
+            "track_index": track,
+            "device_index": device,
+            "strategy": "engine_algo_swap",
+            "topology_hint": {
+                "role_hint": profile.role_hint,
+                "current_algo": current_algo,
+                "new_algo": new_algo,
+            },
+        },
+    )
+    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 _strategy_engine_mix_shift(
+    profile: SynthProfile,
+    target: TimbralFingerprint,
+    kernel: dict,
+    adapter,
+) -> Optional[tuple[BranchSeed, dict]]:
+    """Rebalance Engine 1 / Engine 2 Level for layered character.
+
+    Gates: applicable when BOTH engines have non-zero Level (mix makes
+    no sense if one engine is silent). Shifts the balance by 0.15-0.3
+    depending on freshness.
+    """
+    e1 = float(profile.parameter_state.get("Engine 1 Level", 0.0) or 0.0)
+    e2 = float(profile.parameter_state.get("Engine 2 Level", 0.0) or 0.0)
+    if e1 < 0.05 or e2 < 0.05:
+        return None  # one engine silent — mix shift is meaningless
+
+    freshness = float(kernel.get("freshness", 0.5) or 0.5)
+    track = profile.track_index
+    device = profile.device_index
+
+    # Push toward the engine with LESS level currently — highlights the
+    # underused engine's character. When roughly equal, pick Engine 2.
+    if e1 < e2:
+        direction = "to_e1"
+        delta = 0.15 if freshness < 0.5 else 0.3
+        new_e1 = min(1.0, e1 + delta)
+        new_e2 = max(0.0, e2 - delta / 2)
+    else:
+        direction = "to_e2"
+        delta = 0.15 if freshness < 0.5 else 0.3
+        new_e2 = min(1.0, e2 + delta)
+        new_e1 = max(0.0, e1 - delta / 2)
+
+    seed = freeform_seed(
+        seed_id=_short_id(
+            "ml_mix", f"{track}:{device}:{direction}:{new_e1:.2f}:{new_e2:.2f}"
+        ),
+        hypothesis=(
+            f"Meld engine mix shift {direction}: E1 {e1:.2f} → {new_e1:.2f}, "
+            f"E2 {e2:.2f} → {new_e2:.2f}"
+        ),
+        source="synthesis",
+        novelty_label="strong",
+        risk_label="low",
+        affected_scope={
+            "track_indices": [track],
+            "device_paths": [f"track/{track}/device/{device}"],
+        },
+        distinctness_reason=(
+            f"Meld mix rebalance {direction}; algorithm unchanged"
+        ),
+        producer_payload={
+            "device_name": adapter.device_name,
+            "track_index": track,
+            "device_index": device,
+            "strategy": f"engine_mix_shift_{direction}",
+            "topology_hint": {
+                "role_hint": profile.role_hint,
+                "current_e1": e1,
+                "current_e2": e2,
+                "new_e1": round(new_e1, 3),
+                "new_e2": round(new_e2, 3),
+            },
+        },
+    )
+    plan = {
+        "steps": [
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "Engine 1 Level",
+                        "value": round(new_e1, 3)}},
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "Engine 2 Level",
+                        "value": round(new_e2, 3)}},
+        ],
+        "step_count": 2,
+        "summary": f"E1 {e1:.2f}→{new_e1:.2f}, E2 {e2:.2f}→{new_e2:.2f}",
+    }
+    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,292 @@
+"""Operator adapter — native-synth-aware branch production for Ableton's Operator.
+
+FM synthesis is defined by operator ratios + algorithm topology + per-op
+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
+
+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
+}
+
+
+# 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."""
+
+    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: 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}:{algorithm}:{targeted_op}:{new_coarse}"
+            ),
+            hypothesis=(
+                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",
+            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=(
+                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": [
+                {
+                    "tool": "set_device_parameter",
+                    "params": {
+                        "track_index": track,
+                        "device_index": device,
+                        "parameter_name": coarse_key,
+                        "value": new_coarse,
+                    },
+                },
+            ],
+            "step_count": 1,
+            "summary": f"Osc {targeted_op} Coarse {current_coarse} → {new_coarse} (algo {algorithm})",
+        }
+        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}"