livepilot 1.12.2 → 1.13.0

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),
+        }

package/mcp_server/synthesis_brain/timbre.py

@@ -0,0 +1,194 @@
+"""Render-based timbre extraction.
+
+Builds a TimbralFingerprint from captured spectrum / loudness / spectral-shape
+data. The inputs come from existing perception tools (capture_audio →
+analyze_spectrum_offline / analyze_loudness / get_spectral_shape when
+FluCoMa is available).
+
+This layer is intentionally pure Python — no I/O. Callers capture audio
+and feed the dicts here. PR10 ships a heuristic first pass; later PRs
+will add model-driven extraction on render-based features.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .models import TimbralFingerprint
+
+
+# ── Band-based brightness / warmth mapping ──────────────────────────────
+#
+# The M4L analyzer returns an 8-band spectrum by default. When a full
+# spectrum dict is passed, we look for these band keys in order. If the
+# raw {freq: magnitude} shape is passed instead, we fall back to a coarser
+# low/mid/high split.
+
+_BANDS = ("sub", "low", "low_mid", "mid", "high_mid", "high", "very_high", "ultra")
+
+
+def _band_energy(spectrum: Optional[dict], band: str) -> float:
+    """Read a single band's energy from a spectrum dict. Defaults to 0."""
+    if not spectrum:
+        return 0.0
+    val = spectrum.get(band)
+    if val is None and "bands" in spectrum:
+        val = spectrum["bands"].get(band)
+    try:
+        return float(val or 0.0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _normalize_to_range(value: float, low: float = -1.0, high: float = 1.0) -> float:
+    """Clamp to [-1, 1]."""
+    return max(low, min(high, value))
+
+
+def extract_timbre_fingerprint(
+    spectrum: Optional[dict] = None,
+    loudness: Optional[dict] = None,
+    spectral_shape: Optional[dict] = None,
+) -> TimbralFingerprint:
+    """Build a TimbralFingerprint from captured analysis data.
+
+    Inputs are all optional — the function degrades gracefully when only
+    some dimensions are measurable.
+
+      spectrum: either {sub, low, low_mid, mid, high_mid, high, very_high, ultra}
+        or {"bands": {...}} — the 8-band shape returned by get_master_spectrum /
+        analyze_spectrum_offline. Missing bands default to 0.
+      loudness: {"rms": float, "peak": float, "lufs": float, "lra": float} —
+        output shape from analyze_loudness.
+      spectral_shape: FluCoMa descriptors when available — {"centroid", "flatness",
+        "rolloff", "crest"} (see get_spectral_shape).
+
+    Heuristic dimension mapping (each dimension is clamped to [-1, 1]):
+      brightness ← (high_mid + high - low_mid) / total, scaled; or centroid / 10000
+      warmth     ← low_mid / total — classic low-mid richness
+      bite       ← high_mid / mid — the "bite" frequency balance
+      softness   ← 1.0 - crest (if present) or 1.0 - peak/rms
+      instability ← flatness (if present) — noisier = less stable pitch
+      width      ← not from single-channel data; left at 0 (stereo support in PR11+)
+      texture_density ← flatness proxy — more noise-like = denser texture
+      movement   ← not from single capture — left at 0
+      polish     ← rough dynamic-range proxy: rms / peak closer to 1 = less polished
+    """
+    bands = {b: _band_energy(spectrum, b) for b in _BANDS}
+    total = sum(bands.values())
+    # Silent/empty input → neutral fingerprint. Band-derived dimensions
+    # need real signal to be meaningful; falling back to 0 everywhere is
+    # more honest than forcing brightness/warmth into the extremes.
+    has_signal = total > 1e-6
+    total_safe = total if has_signal else 1.0
+
+    low_mid = bands["low_mid"]
+    mid = bands["mid"] or 0.001
+    high_mid = bands["high_mid"]
+    high = bands["high"]
+
+    # brightness ∈ [-1, 1] — bias on high-band presence relative to low-mid
+    brightness = (
+        _normalize_to_range((high_mid + high - low_mid) / total_safe * 2.0)
+        if has_signal else 0.0
+    )
+    # Prefer spectral centroid when available (model-driven).
+    shape = spectral_shape or {}
+    centroid = shape.get("centroid")
+    if centroid is not None:
+        # Centroid typically in Hz — map 200Hz → -0.8, 5000Hz → +0.8.
+        try:
+            c = float(centroid)
+            # Log-scale mapping is fairer; approximate with piecewise linear.
+            if c <= 200:
+                brightness = -0.8
+            elif c >= 5000:
+                brightness = 0.8
+            else:
+                # linear over log(200..5000) ≈ 2.30 .. 3.70
+                import math
+                t = (math.log10(c) - math.log10(200)) / (math.log10(5000) - math.log10(200))
+                brightness = _normalize_to_range(-0.8 + t * 1.6)
+        except (TypeError, ValueError):
+            pass
+
+    warmth = (
+        _normalize_to_range(low_mid / total_safe * 4.0 - 1.0)
+        if has_signal else 0.0
+    )
+    bite = (
+        _normalize_to_range((high_mid / mid) - 1.0)
+        if has_signal else 0.0
+    )
+
+    # softness via crest factor (lower crest = more sustained / softer)
+    crest = shape.get("crest") if spectral_shape else None
+    if crest is not None:
+        try:
+            softness = _normalize_to_range(1.0 - float(crest) / 10.0)
+        except (TypeError, ValueError):
+            softness = 0.0
+    elif loudness:
+        peak = float(loudness.get("peak", 0.0) or 0.0)
+        rms = float(loudness.get("rms", 0.0) or 0.0)
+        if peak > 0:
+            softness = _normalize_to_range(rms / peak * 2.0 - 1.0)
+        else:
+            softness = 0.0
+    else:
+        softness = 0.0
+
+    # instability + texture_density via spectral flatness
+    flatness = shape.get("flatness") if spectral_shape else None
+    if flatness is not None:
+        try:
+            f = float(flatness)
+            instability = _normalize_to_range(f * 2.0 - 1.0)
+            texture_density = _normalize_to_range(f * 2.0 - 1.0)
+        except (TypeError, ValueError):
+            instability = 0.0
+            texture_density = 0.0
+    else:
+        instability = 0.0
+        texture_density = 0.0
+
+    # polish = inverse of crest dominance (very crest-heavy = unpolished)
+    if crest is not None:
+        try:
+            polish = _normalize_to_range(1.0 - float(crest) / 8.0)
+        except (TypeError, ValueError):
+            polish = 0.0
+    else:
+        polish = 0.0
+
+    return TimbralFingerprint(
+        brightness=round(brightness, 3),
+        warmth=round(warmth, 3),
+        bite=round(bite, 3),
+        softness=round(softness, 3),
+        instability=round(instability, 3),
+        width=0.0,  # stereo detection in later PRs
+        texture_density=round(texture_density, 3),
+        movement=0.0,  # single-capture — no movement signal
+        polish=round(polish, 3),
+    )
+
+
+def diff_fingerprint(a: TimbralFingerprint, b: TimbralFingerprint) -> dict:
+    """Return per-dimension delta a → b.
+
+    Useful after a branch has been auditioned: capture audio before and
+    after, extract fingerprints for each, and diff to see which dimensions
+    actually moved.
+    """
+    return {
+        "brightness": round(b.brightness - a.brightness, 3),
+        "warmth": round(b.warmth - a.warmth, 3),
+        "bite": round(b.bite - a.bite, 3),
+        "softness": round(b.softness - a.softness, 3),
+        "instability": round(b.instability - a.instability, 3),
+        "width": round(b.width - a.width, 3),
+        "texture_density": round(b.texture_density - a.texture_density, 3),
+        "movement": round(b.movement - a.movement, 3),
+        "polish": round(b.polish - a.polish, 3),
+    }

package/mcp_server/tools/_conductor.py

@@ -311,3 +311,147 @@ def create_conductor_plan(
     budget = budgets.create_budget(mode=mode, aggression=aggression)
     plan.budget = budget.to_dict()
     return plan
+
+
+# ── PR4 — creative_search routing fork ──────────────────────────────────
+#
+# Runs only when the user intent is exploratory (workflow_mode =
+# "creative_search"). Adds producer selection on top of the base
+# engine routing so Wonder / synthesis_brain / composer / technique memory
+# can all be consulted for branch seeds. The base classify_request is
+# untouched so every existing caller and test continues to see identical
+# behavior — this path is a parallel, additive classifier.
+
+
+@dataclass
+class CreativeSearchPlan:
+    """Extended routing plan used for creative_search mode.
+
+    Wraps a ConductorPlan with producer-selection metadata that branch
+    assemblers (Wonder / synthesis_brain / composer) act on to generate
+    diverse branch seeds.
+
+    Fields:
+      base_plan: the engine routing from classify_request().
+      branch_sources: ordered list of producers to consult. Always contains
+        "semantic_move" and "freeform"; adds "synthesis", "composer", and
+        "technique" based on request content and kernel state.
+      seed_hints: per-source hints passed to the producer. Shape:
+        {"synthesis": {...kernel.synth_hints...}, "composer": {...}, ...}
+      target_branch_count: how many branches to aim for (3 by default;
+        matches the safe / strong / unexpected triptych in Preview Studio).
+      freshness: 0.0-1.0, threaded from kernel.freshness.
+      creativity_profile: from kernel.creativity_profile ("" when absent).
+    """
+
+    base_plan: ConductorPlan
+    branch_sources: list[str] = field(default_factory=list)
+    seed_hints: dict = field(default_factory=dict)
+    target_branch_count: int = 3
+    freshness: float = 0.5
+    creativity_profile: str = ""
+
+    def to_dict(self) -> dict:
+        d = self.base_plan.to_dict()
+        d["creative_search"] = {
+            "branch_sources": list(self.branch_sources),
+            "seed_hints": dict(self.seed_hints),
+            "target_branch_count": self.target_branch_count,
+            "freshness": self.freshness,
+            "creativity_profile": self.creativity_profile,
+        }
+        # Creative-search plans always recommend experiments
+        d["experiment_recommended"] = True
+        return d
+
+
+# Keyword families that imply a particular producer is worth consulting
+# even when the kernel carries no explicit hint for it.
+_SYNTH_REQUEST = re.compile(
+    r"synth|patch|timbre|timbral|oscillat|wavetable|operator|filter|"
+    r"modulation|lfo|envelope|drift|meld|analog|detune|spread|"
+    r"haunted|lush|aggressive|warm.?pad|fat.?bass|bright.?lead",
+    re.IGNORECASE,
+)
+_TECHNIQUE_HINT = re.compile(
+    r"like.?last.?time|same.?as|recall|remember|how.?i.?did",
+    re.IGNORECASE,
+)
+
+
+def classify_request_creative(
+    request: str,
+    kernel: Optional[dict] = None,
+) -> CreativeSearchPlan:
+    """Classify a request for creative_search mode.
+
+    Builds on classify_request() for engine routing and adds producer
+    selection so downstream branch assemblers know which sources to
+    consult. This is intentionally additive — callers that don't know
+    about creative_search mode can keep using classify_request() and see
+    no difference.
+
+    Producer selection:
+      - "semantic_move" is always included (baseline).
+      - "synthesis" added when kernel.synth_hints is non-empty OR the
+        request mentions synth / patch / timbre / oscillator / filter /
+        modulation / etc.
+      - "composer" added when base_plan primary engine is "composition".
+      - "technique" added when the kernel has enough taste evidence
+        (>= 3 recorded move outcomes) OR the request suggests recalling
+        a prior technique.
+      - "freeform" is always the last option — a catch-all for producers
+        that want to emit a seed without matching any structured category.
+
+    When kernel is None, the function still works — it just skips the
+    kernel-driven producer additions (synthesis / technique) unless the
+    request text triggers them directly.
+    """
+    base = classify_request(request)
+    kernel = kernel or {}
+    request_lower = request.lower()
+
+    sources: list[str] = ["semantic_move"]
+    hints: dict = {}
+
+    # ── Synthesis producer ──────────────────────────────────────────────
+    synth_hints = kernel.get("synth_hints") or {}
+    synth_matched_by_request = bool(_SYNTH_REQUEST.search(request_lower))
+    if synth_hints or synth_matched_by_request:
+        sources.append("synthesis")
+        hints["synthesis"] = dict(synth_hints) if synth_hints else {}
+        if synth_matched_by_request and not synth_hints:
+            hints["synthesis"]["inferred_from_request"] = True
+
+    # ── Composer producer (only for composition-primary routes) ────────
+    if base.routes and base.routes[0].engine == "composition":
+        sources.append("composer")
+        hints["composer"] = {"request": request}
+
+    # ── Technique memory producer ──────────────────────────────────────
+    taste = kernel.get("taste_graph") or {}
+    move_fam = taste.get("move_family_scores") or {}
+    evidence = int(taste.get("evidence_count", 0) or 0)
+    technique_hinted = bool(_TECHNIQUE_HINT.search(request_lower))
+    if technique_hinted or (move_fam and evidence >= 3):
+        sources.append("technique")
+        preferred = []
+        for fam, s in move_fam.items():
+            if isinstance(s, dict) and s.get("score", 0) > 0.2:
+                preferred.append(fam)
+        hints["technique"] = {
+            "preferred_families": preferred[:3],
+            "hinted_by_request": technique_hinted,
+        }
+
+    # ── Freeform always available ──────────────────────────────────────
+    sources.append("freeform")
+
+    return CreativeSearchPlan(
+        base_plan=base,
+        branch_sources=sources,
+        seed_hints=hints,
+        target_branch_count=3,
+        freshness=float(kernel.get("freshness", 0.5) or 0.5),
+        creativity_profile=kernel.get("creativity_profile", "") or "",
+    )