livepilot 1.12.2 → 1.13.0

package/mcp_server/runtime/tools.py

@@ -7,6 +7,8 @@ Tools:
 
 from __future__ import annotations
 
+from typing import Optional
+
 from fastmcp import Context
 
 from ..server import mcp
@@ -79,6 +81,10 @@ def get_session_kernel(
     request_text: str = "",
     mode: str = "improve",
     aggression: float = 0.5,
+    freshness: float = 0.5,
+    creativity_profile: str = "",
+    sacred_elements: Optional[list] = None,
+    synth_hints: Optional[dict] = None,
 ) -> dict:
     """Build the unified turn snapshot for V2 orchestration.
 
@@ -86,11 +92,27 @@ def get_session_kernel(
     Assembles: session info, capability state, action ledger, taste profile,
     anti-preferences, and session memory into one canonical snapshot.
 
-    mode: observe | improve | explore | finish | diagnose
-    aggression: 0.0 (subtle) to 1.0 (bold)
+    Core params:
+      mode: observe | improve | explore | finish | diagnose
+      aggression: 0.0 (subtle) to 1.0 (bold) — execution boldness.
+
+    Creative controls (PR2 — branch-native migration, optional):
+      freshness: 0.0 (don't surprise me) to 1.0 (surprise me). Read by
+        producers (Wonder, synthesis_brain, composer) to bias branch
+        generation. Distinct from aggression, which is about applying
+        a single move boldly; freshness is about how far to roam.
+      creativity_profile: shorthand producer philosophy tag. Known values
+        include "surgeon" (targeted), "alchemist" (transformative),
+        "sculptor" (synthesis-focused). Empty ⇒ producer picks a default.
+      sacred_elements: caller-asserted list of sacred elements that
+        override or augment what song_brain infers. Shape matches
+        song_brain entries: {element_type, description, salience}.
+      synth_hints: focus hints for synthesis_brain; shape is open in PR2
+        and firms up in PR9. Typical keys: track_indices, device_paths,
+        target_timbre, preferred_devices.
 
     Returns: SessionKernel dict with kernel_id, session topology, capabilities,
-    memory context, and routing hints.
+    memory context, routing hints, and (if provided) creative controls.
     """
     from .session_kernel import build_session_kernel
 
@@ -179,6 +201,10 @@ def get_session_kernel(
         session_memory=session_mem,
         taste_graph=taste_graph,
         anti_preferences=anti_prefs,
+        freshness=freshness,
+        creativity_profile=creativity_profile,
+        sacred_elements=sacred_elements,
+        synth_hints=synth_hints,
     )
 
     # Populate routing hints from conductor when request context is available

package/mcp_server/synthesis_brain/__init__.py

@@ -0,0 +1,53 @@
+"""Synthesis brain — native-synth-aware branch production.
+
+Parallel subsystem to mcp_server.sound_design. Where sound_design reasons
+at the block-type level (oscillator / filter / envelope / ...), the
+synthesis brain reasons at the native-device level with per-adapter
+knowledge of Wavetable / Operator / Analog / Drift / Meld parameter
+spaces, modulation graphs, and articulation profiles.
+
+Each adapter implements the SynthAdapter protocol:
+  - device_name: the Ableton device name it claims
+  - extract_profile(device_parameters): read a SynthProfile from live params
+  - propose_branches(profile, target, kernel): emit BranchSeed objects plus
+    pre-compiled plans (set_device_parameter / batch_set_parameters steps)
+
+PR9 ships Wavetable and Operator adapters. PR10 adds Analog, Drift, Meld
+and render-based timbre extraction on top of ``capture_audio``.
+
+No MCP @tool() decorators in this PR — the subsystem is callable from
+Python (Wonder's generate_branch_seeds, composer, etc.). PR12 wires
+dedicated MCP tools and does the tool-count metadata sweep in one pass.
+"""
+
+from .models import (
+    SynthProfile,
+    TimbralFingerprint,
+    ModulationGraph,
+    ArticulationProfile,
+    OPAQUE,
+    NATIVE,
+)
+from .adapters import get_adapter, SynthAdapter
+from .engine import (
+    analyze_synth_patch,
+    propose_synth_branches,
+    supported_devices,
+)
+from .timbre import extract_timbre_fingerprint, diff_fingerprint
+
+__all__ = [
+    "SynthProfile",
+    "TimbralFingerprint",
+    "ModulationGraph",
+    "ArticulationProfile",
+    "OPAQUE",
+    "NATIVE",
+    "SynthAdapter",
+    "get_adapter",
+    "analyze_synth_patch",
+    "propose_synth_branches",
+    "supported_devices",
+    "extract_timbre_fingerprint",
+    "diff_fingerprint",
+]

package/mcp_server/synthesis_brain/adapters/__init__.py

@@ -0,0 +1,34 @@
+"""Synth adapter registry.
+
+Each adapter is a Python class implementing the SynthAdapter protocol.
+Registration is explicit — adapters add themselves to ``_REGISTRY`` at
+module import time. ``get_adapter(device_name)`` returns the registered
+adapter or None.
+"""
+
+from __future__ import annotations
+
+from .base import SynthAdapter, _REGISTRY, register_adapter
+from . import wavetable as _wavetable  # noqa: F401 — import for registration
+from . import operator as _operator  # noqa: F401
+from . import analog as _analog  # noqa: F401
+from . import drift as _drift  # noqa: F401
+from . import meld as _meld  # noqa: F401
+
+
+def get_adapter(device_name: str) -> SynthAdapter | None:
+    """Return the adapter for a given Ableton device name, or None."""
+    return _REGISTRY.get(device_name)
+
+
+def registered_devices() -> list[str]:
+    """List device names this package has an adapter for."""
+    return sorted(_REGISTRY.keys())
+
+
+__all__ = [
+    "SynthAdapter",
+    "get_adapter",
+    "register_adapter",
+    "registered_devices",
+]

package/mcp_server/synthesis_brain/adapters/analog.py

@@ -0,0 +1,167 @@
+"""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]]:
+        kernel = kernel or {}
+        freshness = float(kernel.get("freshness", 0.5) or 0.5)
+        track = profile.track_index
+        device = profile.device_index
+
+        # Skip proposal if already plucky — avoids doubling-down on the
+        # same treatment.
+        if any("Already plucky" in n for n in profile.notes):
+            return []
+
+        current_env = float(profile.parameter_state.get("F1 Env Amount", 0.0) or 0.0)
+        # Target filter-env amount scales with freshness.
+        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="only Analog seed that couples Filter Env + 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 _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,166 @@
+"""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 {}
+        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)
+
+        # Toggle character in the opposite direction to create contrast.
+        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)
+        # Move sub slightly toward 0.3 if we're starting outside 0.2-0.4
+        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="only Drift seed that shifts Character + Sub balance",
+        )
+        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 _short_id(prefix: str, key: str) -> str:
+    h = hashlib.sha256(f"{prefix}:{key}".encode()).hexdigest()[:10]
+    return f"{prefix}_{h}"