livepilot 1.12.2 → 1.14.0

package/mcp_server/synthesis_brain/adapters/analog.py

@@ -0,0 +1,273 @@
+"""Analog adapter — Ableton's classic two-oscillator subtractive synth.
+
+PR10 ships one canned proposer: filter_envelope_variant — pushes Filter
+Envelope Amount while shortening the Filter Decay, producing the
+characteristic "plucked" attack that Analog excels at. Later PRs add
+detune/unison variants and dual-filter 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 = {
+    "Osc1 Shape",
+    "Osc2 Shape",
+    "Osc1 Tune",
+    "Osc2 Tune",
+    "F1 Freq",
+    "F1 Reso",
+    "F1 Env Amount",
+    "F1 Env A",
+    "F1 Env D",
+    "F1 Env S",
+    "F1 Env R",
+    "A1 Attack",
+    "A1 Decay",
+    "A1 Sustain",
+    "A1 Release",
+    "Glide Mode",
+    "Glide Time",
+}
+
+
+@register_adapter
+class AnalogAdapter:
+    device_name: str = "Analog"
+
+    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] = []
+
+        # Filter-env coupling summary
+        env_amount = parameter_state.get("F1 Env Amount", 0.0)
+        env_decay = parameter_state.get("F1 Env D", 0.0)
+        if env_amount and abs(env_amount) > 0.3 and env_decay and env_decay < 0.3:
+            notes.append(
+                f"Already plucky: F1 Env Amount={env_amount:.2f}, Decay={env_decay:.2f}"
+            )
+
+        articulation = ArticulationProfile(
+            attack_ms=float(parameter_state.get("A1 Attack", 0.0) or 0.0),
+            release_ms=float(parameter_state.get("A1 Release", 0.0) or 0.0),
+        )
+
+        mod = ModulationGraph()
+        if env_amount and abs(env_amount) > 0.01:
+            mod.routes.append({
+                "source": "Filter Env",
+                "target": "F1 Freq",
+                "amount": env_amount,
+                "range": None,
+            })
+
+        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]]:
+        # Strategy registry — each candidate strategy's ``applicable()``
+        # gates on profile+role+target, and ``build()`` emits (seed, plan).
+        # Adapter returns ALL applicable strategies' proposals so Wonder /
+        # create_experiment can offer them as branches. Callers cap total
+        # via max_seeds.
+        kernel = kernel or {}
+        results: list[tuple[BranchSeed, dict]] = []
+        for strategy_fn in (_strategy_filter_pluck, _strategy_detune_warmth):
+            try:
+                maybe = strategy_fn(profile, target, kernel, adapter=self)
+            except Exception:
+                # Never let one strategy's crash kill the rest.
+                continue
+            if maybe is not None:
+                results.append(maybe)
+        return results
+
+
+# ── Strategy registry ────────────────────────────────────────────────
+#
+# Each strategy is a pure function (profile, target, kernel, adapter) →
+# Optional[(BranchSeed, plan_dict)]. A strategy returns None when not
+# applicable to the current profile+target+role combination. This lets
+# the adapter stay thin while the intelligence lives in the strategies.
+
+
+def _strategy_filter_pluck(
+    profile: SynthProfile,
+    target: TimbralFingerprint,
+    kernel: dict,
+    adapter,
+) -> Optional[tuple[BranchSeed, dict]]:
+    """Couple Filter Env Amount up + Filter Decay down → attack pluck.
+
+    Gates: skip when profile already flags 'Already plucky'. Most useful
+    when role_hint is "bass", "pluck", "lead", or when target.bite > 0.
+    """
+    if any("Already plucky" in n for n in profile.notes):
+        return None
+
+    role = (profile.role_hint or "").lower()
+    want_bite = target.bite > 0.1 or role in {"bass", "pluck", "lead", "stab"}
+    if not want_bite and role in {"pad", "drone"}:
+        # Sustained roles actively fight this strategy.
+        return None
+
+    freshness = float(kernel.get("freshness", 0.5) or 0.5)
+    track = profile.track_index
+    device = profile.device_index
+    current_env = float(profile.parameter_state.get("F1 Env Amount", 0.0) or 0.0)
+    new_env = min(1.0, max(current_env, 0.45 if freshness < 0.5 else 0.65))
+    current_decay = float(profile.parameter_state.get("F1 Env D", 0.5) or 0.5)
+    new_decay = min(current_decay, 0.25 if freshness < 0.5 else 0.15)
+
+    seed = freeform_seed(
+        seed_id=_short_id("an_plk", f"{track}:{device}:{new_env:.2f}:{new_decay:.2f}"),
+        hypothesis=(
+            f"Analog filter-pluck: Env Amount → {new_env:.2f}, "
+            f"Decay → {new_decay:.2f} for attack character"
+        ),
+        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="couples Filter Env Amount + Decay for attack character",
+        producer_payload={
+            "device_name": adapter.device_name,
+            "track_index": track,
+            "device_index": device,
+            "strategy": "filter_pluck",
+            "topology_hint": {
+                "role_hint": profile.role_hint,
+                "current_env": current_env,
+                "new_env": new_env,
+                "current_decay": current_decay,
+                "new_decay": new_decay,
+            },
+        },
+    )
+    plan = {
+        "steps": [
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "F1 Env Amount",
+                        "value": round(new_env, 3)}},
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "F1 Env D",
+                        "value": round(new_decay, 3)}},
+        ],
+        "step_count": 2,
+        "summary": f"F1 Env Amount → {new_env:.2f}, F1 Env D → {new_decay:.2f}",
+    }
+    return (seed, plan)
+
+
+def _strategy_detune_warmth(
+    profile: SynthProfile,
+    target: TimbralFingerprint,
+    kernel: dict,
+    adapter,
+) -> Optional[tuple[BranchSeed, dict]]:
+    """Detune Osc2 slightly + lean warmer tone.
+
+    Gates: applicable when role_hint is "pad" / "lead" / "stab" / "drone"
+    or target.warmth > 0. Skip on "pluck"/"bass" to avoid woofiness.
+    """
+    role = (profile.role_hint or "").lower()
+    if role in {"bass", "pluck", "kick"}:
+        return None
+    want_warm = target.warmth > 0.1 or role in {"pad", "lead", "stab", "drone"}
+    if not want_warm:
+        return None
+
+    freshness = float(kernel.get("freshness", 0.5) or 0.5)
+    track = profile.track_index
+    device = profile.device_index
+    current_detune = float(profile.parameter_state.get("Osc2 Tune", 0.0) or 0.0)
+    # Detune is in semitones by convention on Analog; keep shifts musical.
+    step = 0.04 if freshness < 0.5 else 0.09
+    new_detune = round(current_detune + step, 3)
+
+    seed = freeform_seed(
+        seed_id=_short_id("an_det", f"{track}:{device}:{new_detune:.3f}"),
+        hypothesis=(
+            f"Analog detune warmth: Osc2 Tune {current_detune:.3f} → "
+            f"{new_detune:.3f} semitones for a wider, lusher body"
+        ),
+        source="synthesis",
+        novelty_label="safe",
+        risk_label="low",
+        affected_scope={
+            "track_indices": [track],
+            "device_paths": [f"track/{track}/device/{device}"],
+        },
+        distinctness_reason="slight Osc2 detune for body, no filter changes",
+        producer_payload={
+            "device_name": adapter.device_name,
+            "track_index": track,
+            "device_index": device,
+            "strategy": "detune_warmth",
+            "topology_hint": {
+                "role_hint": profile.role_hint,
+                "current_detune": current_detune,
+                "new_detune": new_detune,
+            },
+        },
+    )
+    plan = {
+        "steps": [
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "Osc2 Tune",
+                        "value": new_detune}},
+        ],
+        "step_count": 1,
+        "summary": f"Osc2 Tune → {new_detune:.3f}",
+    }
+    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/base.py

@@ -0,0 +1,86 @@
+"""SynthAdapter base protocol + registry infrastructure.
+
+Adapters are plain classes that expose:
+  - device_name (class attribute)
+  - extract_profile(track_index, device_index, parameter_state, display_values,
+                    role_hint) -> SynthProfile
+  - propose_branches(profile, target, kernel) -> list[tuple[BranchSeed, dict]]
+    (each tuple: (seed, compiled_plan_dict))
+
+Adapters register themselves via ``register_adapter(cls)`` as a class
+decorator at module-import time, so the registry is populated when
+the adapters package is imported.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable, Optional
+
+from ...branches import BranchSeed
+from ..models import SynthProfile, TimbralFingerprint
+
+
+# Adapter registry — populated by register_adapter at import time.
+_REGISTRY: dict[str, "SynthAdapter"] = {}
+
+
+@runtime_checkable
+class SynthAdapter(Protocol):
+    """Contract every native-synth adapter must satisfy."""
+
+    device_name: str
+
+    def extract_profile(
+        self,
+        track_index: int,
+        device_index: int,
+        parameter_state: dict,
+        display_values: Optional[dict] = None,
+        role_hint: str = "",
+    ) -> SynthProfile:
+        """Build a SynthProfile from raw device parameter state.
+
+        Must be pure — no I/O. The caller has already fetched parameters
+        via get_device_parameters / get_display_values and hands them here.
+        """
+        ...
+
+    def propose_branches(
+        self,
+        profile: SynthProfile,
+        target: TimbralFingerprint,
+        kernel: Optional[dict] = None,
+    ) -> list[tuple[BranchSeed, dict]]:
+        """Emit seed + pre-compiled plan pairs.
+
+        Each pair: (BranchSeed with source="synthesis", compiled_plan dict
+        ready for execution_router.execute_plan_steps_async).
+
+        The kernel dict may carry freshness / creativity_profile / synth_hints
+        (see SessionKernel PR2 additions); adapters read these to bias
+        proposals. Pre-PR10, adapters ship canned proposers; later PRs
+        extend with render-based verification.
+        """
+        ...
+
+
+def register_adapter(cls):
+    """Class decorator — register an adapter under its device_name.
+
+    Raises ValueError if the class lacks device_name or duplicates an
+    existing registration.
+    """
+    device_name = getattr(cls, "device_name", None)
+    if not device_name:
+        raise ValueError(
+            f"Adapter {cls.__name__} must define a class attribute "
+            f"'device_name' to register"
+        )
+    if device_name in _REGISTRY:
+        raise ValueError(
+            f"Duplicate synth adapter registration for device '{device_name}' "
+            f"(existing: {type(_REGISTRY[device_name]).__name__}, "
+            f"new: {cls.__name__})"
+        )
+    _REGISTRY[device_name] = cls()
+    return cls

package/mcp_server/synthesis_brain/adapters/drift.py

@@ -0,0 +1,271 @@
+"""Drift adapter — Ableton 12's modern subtractive synth.
+
+Drift has a cleaner parameter set than Analog and pairs oscillator
+shapes with a character wave + sub + noise blend. PR10 ships one
+canned proposer: character_blend — shifts the oscillator wave + sub
+balance to change core tone without touching the filter. Later PRs
+add tuning-table variants and LFO-routing 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 = {
+    "Wave",
+    "Character",
+    "Tune",
+    "Sub Level",
+    "Sub Tone",
+    "Noise Level",
+    "Noise Color",
+    "Filter Freq",
+    "Filter Res",
+    "Filter Env",
+    "LFO Rate",
+    "LFO Amount",
+    "Amp Env A",
+    "Amp Env D",
+    "Amp Env S",
+    "Amp Env R",
+}
+
+
+@register_adapter
+class DriftAdapter:
+    device_name: str = "Drift"
+
+    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] = []
+
+        sub = float(parameter_state.get("Sub Level", 0.0) or 0.0)
+        noise = float(parameter_state.get("Noise Level", 0.0) or 0.0)
+        if sub > 0.5 and role_hint in ("lead", "stab"):
+            notes.append(f"Sub Level {sub:.2f} is high for a {role_hint} — check bass clash")
+        if noise > 0.5:
+            notes.append(f"Noise Level {noise:.2f} — significant noise content")
+
+        articulation = ArticulationProfile(
+            attack_ms=float(parameter_state.get("Amp Env A", 0.0) or 0.0),
+            release_ms=float(parameter_state.get("Amp Env R", 0.0) or 0.0),
+        )
+
+        mod = ModulationGraph()
+        lfo_amount = parameter_state.get("LFO Amount", 0.0)
+        if lfo_amount and abs(lfo_amount) > 0.01:
+            mod.routes.append({
+                "source": "LFO",
+                "target": "(inferred)",
+                "amount": lfo_amount,
+                "range": None,
+            })
+
+        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_character_blend, _strategy_filter_sweep):
+            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_character_blend(
+    profile: SynthProfile,
+    target: TimbralFingerprint,
+    kernel: dict,
+    adapter,
+) -> Optional[tuple[BranchSeed, dict]]:
+    """Shift Character + Sub balance. Always applicable."""
+    freshness = float(kernel.get("freshness", 0.5) or 0.5)
+    track = profile.track_index
+    device = profile.device_index
+    current_char = float(profile.parameter_state.get("Character", 0.0) or 0.0)
+    current_sub = float(profile.parameter_state.get("Sub Level", 0.0) or 0.0)
+
+    new_char = (
+        min(1.0, max(current_char + 0.3, 0.3))
+        if current_char <= 0.5
+        else max(0.0, current_char - 0.3)
+    )
+    target_sub = 0.3
+    new_sub = current_sub + (target_sub - current_sub) * (
+        0.5 if freshness < 0.5 else 0.8
+    )
+    new_sub = round(max(0.0, min(1.0, new_sub)), 3)
+
+    seed = freeform_seed(
+        seed_id=_short_id("dr_chr", f"{track}:{device}:{new_char:.2f}:{new_sub:.2f}"),
+        hypothesis=(
+            f"Drift character blend: Character → {new_char:.2f}, "
+            f"Sub Level → {new_sub:.2f} for a different core tone"
+        ),
+        source="synthesis",
+        novelty_label="strong",
+        risk_label="low",
+        affected_scope={
+            "track_indices": [track],
+            "device_paths": [f"track/{track}/device/{device}"],
+        },
+        distinctness_reason="shifts Character + Sub balance",
+        producer_payload={
+            "device_name": adapter.device_name,
+            "track_index": track,
+            "device_index": device,
+            "strategy": "character_blend",
+            "topology_hint": {
+                "role_hint": profile.role_hint,
+                "current_char": current_char,
+                "new_char": round(new_char, 3),
+                "current_sub": current_sub,
+                "new_sub": new_sub,
+            },
+        },
+    )
+    plan = {
+        "steps": [
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "Character",
+                        "value": round(new_char, 3)}},
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "Sub Level",
+                        "value": new_sub}},
+        ],
+        "step_count": 2,
+        "summary": f"Character → {new_char:.2f}, Sub Level → {new_sub:.2f}",
+    }
+    return (seed, plan)
+
+
+def _strategy_filter_sweep(
+    profile: SynthProfile,
+    target: TimbralFingerprint,
+    kernel: dict,
+    adapter,
+) -> Optional[tuple[BranchSeed, dict]]:
+    """Sweep Filter Freq toward target brightness.
+
+    Gates: applicable when target.brightness != 0 OR role_hint suggests
+    motion ("lead", "pad", "drone"). Skip when role is "bass" (sub roles
+    want a stable low-pass, not a sweep).
+    """
+    role = (profile.role_hint or "").lower()
+    if role in {"bass", "sub", "kick"}:
+        return None
+    want_motion = abs(target.brightness) > 0.1 or role in {"lead", "pad", "drone"}
+    if not want_motion:
+        return None
+
+    freshness = float(kernel.get("freshness", 0.5) or 0.5)
+    track = profile.track_index
+    device = profile.device_index
+    # Drift's filter freq is normalized 0-1 in the API; display is Hz.
+    current_freq = float(profile.parameter_state.get("Filter Freq", 0.5) or 0.5)
+    if target.brightness > 0:
+        # Open filter toward bright.
+        new_freq = min(1.0, current_freq + (0.15 if freshness < 0.5 else 0.3))
+        direction = "open"
+    else:
+        # Close toward warm.
+        new_freq = max(0.0, current_freq - (0.12 if freshness < 0.5 else 0.25))
+        direction = "close"
+
+    if abs(new_freq - current_freq) < 0.03:
+        return None  # barely any change — skip
+
+    seed = freeform_seed(
+        seed_id=_short_id(
+            "dr_flt", f"{track}:{device}:{direction}:{new_freq:.2f}"
+        ),
+        hypothesis=(
+            f"Drift filter sweep: Filter Freq {current_freq:.2f} → "
+            f"{new_freq:.2f} ({direction}) for a {direction}d voice"
+        ),
+        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=f"filter {direction} without touching core oscillator",
+        producer_payload={
+            "device_name": adapter.device_name,
+            "track_index": track,
+            "device_index": device,
+            "strategy": f"filter_sweep_{direction}",
+            "topology_hint": {
+                "role_hint": profile.role_hint,
+                "target_brightness": target.brightness,
+                "current_freq": current_freq,
+                "new_freq": round(new_freq, 3),
+            },
+        },
+    )
+    plan = {
+        "steps": [
+            {"tool": "set_device_parameter",
+             "params": {"track_index": track, "device_index": device,
+                        "parameter_name": "Filter Freq",
+                        "value": round(new_freq, 3)}},
+        ],
+        "step_count": 1,
+        "summary": f"Filter Freq {current_freq:.2f} → {new_freq:.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}"