livepilot 1.12.2 → 1.14.0

package/mcp_server/synthesis_brain/adapters/wavetable.py

@@ -0,0 +1,364 @@
+"""Wavetable adapter — native-synth-aware branch production for Ableton's Wavetable.
+
+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.
+
+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
+
+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",
+}
+
+
+# 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."""
+
+    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: 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)
+        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:
+            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}:{current_region}:{target_region}:{new_pos:.2f}"
+            ),
+            hypothesis=(
+                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",
+            risk_label="low",
+            affected_scope={
+                "track_indices": [track],
+                "device_paths": [f"track/{track}/device/{device}"],
+            },
+            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": [
+                {
+                    "tool": "set_device_parameter",
+                    "params": {
+                        "track_index": track,
+                        "device_index": device,
+                        "parameter_name": "Osc 1 Position",
+                        "value": new_pos,
+                    },
+                },
+            ],
+            "step_count": 1,
+            "summary": f"Osc 1 Position {current_pos:.2f} ({current_region}) → {new_pos:.2f} ({target_region})",
+        }
+        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"
+                ),
+                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": [
+                    {
+                        "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 {},
+    )

package/mcp_server/synthesis_brain/models.py

@@ -0,0 +1,121 @@
+"""Synthesis-brain data models.
+
+Pure dataclasses — zero I/O. Shape is intentionally minimal in PR9;
+later PRs firm up fields as adapters discover what's actually useful.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Literal, Optional
+
+
+# Device opacity markers — natives are inspectable via device parameters,
+# opaque plugins (AU / VST) are not. Adapters are registered for natives only.
+NATIVE = "native"
+OPAQUE = "opaque"
+
+DeviceOpacity = Literal["native", "opaque"]
+
+
+@dataclass
+class TimbralFingerprint:
+    """A compact per-device timbre target.
+
+    All dimensions are floats in [-1.0, 1.0]; 0.0 means "no change from
+    whatever the source patch is". This intentionally mirrors the existing
+    TimbralGoalVector in sound_design.models so the two subsystems can
+    share goal inputs.
+    """
+
+    brightness: float = 0.0
+    warmth: float = 0.0
+    bite: float = 0.0
+    softness: float = 0.0
+    instability: float = 0.0
+    width: float = 0.0
+    texture_density: float = 0.0
+    movement: float = 0.0
+    polish: float = 0.0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ModulationGraph:
+    """Flat list of modulation routes on a single device.
+
+    Each route: {source, target, amount, range}. Shape is deliberately
+    loose because natives differ (Wavetable has LFO routing, Operator
+    has a per-osc modulation matrix, Analog has FM + Envelope routing).
+    Adapters populate it in a device-consistent way.
+    """
+
+    routes: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"routes": list(self.routes)}
+
+
+@dataclass
+class ArticulationProfile:
+    """How a patch responds to note-on / note-off / velocity.
+
+    attack_ms / release_ms are envelope rough times; velocity_mapping is
+    a tag ("linear", "exponential", "flat"); mono indicates mono-only
+    mode (portamento hints live here in later PRs).
+    """
+
+    attack_ms: float = 0.0
+    release_ms: float = 0.0
+    velocity_mapping: str = "linear"
+    mono: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class SynthProfile:
+    """Extracted per-device patch state.
+
+    Fields:
+      device_name: the Ableton device name ("Wavetable", "Operator", ...)
+      opacity: NATIVE ⇒ adapter knows this device; OPAQUE ⇒ fallback path
+      track_index / device_index: where the device lives in the session
+      parameter_state: raw ``{name: value}`` dict from get_device_parameters;
+        adapters translate this into structured knowledge
+      display_values: parallel ``{name: value_string}`` when available
+        (lets adapters reason about actual Hz / dB / % rather than 0-1 floats)
+      role_hint: caller-supplied role ("pad", "lead", "bass", "perc", ...) or ""
+      modulation: the device's current modulation graph
+      articulation: envelope + velocity response
+      notes: free-form observations the adapter wants to record for downstream
+        reasoning (e.g. "voices=4, detune=0.12 — subtly rich already")
+    """
+
+    device_name: str = ""
+    opacity: DeviceOpacity = OPAQUE
+    track_index: int = -1
+    device_index: int = -1
+    parameter_state: dict = field(default_factory=dict)
+    display_values: dict = field(default_factory=dict)
+    role_hint: str = ""
+    modulation: ModulationGraph = field(default_factory=ModulationGraph)
+    articulation: ArticulationProfile = field(default_factory=ArticulationProfile)
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "device_name": self.device_name,
+            "opacity": self.opacity,
+            "track_index": self.track_index,
+            "device_index": self.device_index,
+            "parameter_state": dict(self.parameter_state),
+            "display_values": dict(self.display_values),
+            "role_hint": self.role_hint,
+            "modulation": self.modulation.to_dict(),
+            "articulation": self.articulation.to_dict(),
+            "notes": list(self.notes),
+        }