livepilot 1.12.2 → 1.14.0

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/synthesis_brain/tools.py

@@ -0,0 +1,231 @@
+"""MCP tools for the synthesis_brain subsystem (PR5/v2).
+
+Four user-facing wrappers that expose the Python-callable internals
+through the MCP surface. Thin wrappers by design — all intelligence
+lives in adapters/engine.py; these tools handle ctx plumbing, param
+rehydration, and response shaping.
+
+Tools:
+  analyze_synth_patch(track_index, device_index, role_hint?)
+    → SynthProfile dict for any supported native synth on the given
+       track+device. Fetches parameter state via get_device_parameters
+       and display_values via get_display_values.
+
+  propose_synth_branches(track_index, device_index, target?, freshness?)
+    → List of (seed_dict, compiled_plan) pairs. Feed directly to
+       create_experiment(seeds=seed_dicts, compiled_plans=plans) OR
+       skip the plans list to have run_experiment compile from move_id
+       (not applicable here — synthesis seeds always ship with plans).
+
+  extract_timbre_fingerprint(spectrum?, loudness?, spectral_shape?)
+    → TimbralFingerprint dict. Pure transform; no I/O. Callers that
+       have already captured audio analysis dicts can convert them to
+       a fingerprint without going through the full render-verify path.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from .engine import analyze_synth_patch as _analyze_synth_patch
+from .engine import propose_synth_branches as _propose_synth_branches
+from .engine import supported_devices
+from .timbre import extract_timbre_fingerprint as _extract_fp
+from .models import TimbralFingerprint
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+@mcp.tool()
+def analyze_synth_patch(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    role_hint: str = "",
+) -> dict:
+    """Extract a SynthProfile for a native synth on the given track+device.
+
+    Fetches live parameter state + display_values from Ableton, then hands
+    them to the synthesis_brain adapter for that device. When the device
+    isn't a supported native (Wavetable / Operator / Analog / Drift / Meld),
+    returns an opaque SynthProfile — raw params survive for manual inspection
+    but no strategies are proposed.
+
+    role_hint: optional tag ("pad", "lead", "bass", "pluck", "stab",
+        "drone") that gates adapter strategy selection. Leave empty when
+        the role is ambiguous.
+
+    Returns: SynthProfile dict with device_name, opacity, track_index,
+    device_index, parameter_state, display_values, role_hint, modulation,
+    articulation, notes.
+    """
+    ableton = _get_ableton(ctx)
+    try:
+        info = ableton.send_command(
+            "get_device_info",
+            {"track_index": track_index, "device_index": device_index},
+        )
+    except Exception as exc:
+        return {"error": f"get_device_info failed: {exc}"}
+    if not isinstance(info, dict) or "error" in info:
+        return {"error": info.get("error") if isinstance(info, dict) else "device not found"}
+
+    device_name = info.get("name") or info.get("class_name") or ""
+
+    try:
+        params_result = ableton.send_command(
+            "get_device_parameters",
+            {"track_index": track_index, "device_index": device_index},
+        )
+    except Exception as exc:
+        return {"error": f"get_device_parameters failed: {exc}"}
+
+    parameter_state: dict = {}
+    display_values: dict = {}
+    if isinstance(params_result, dict):
+        for p in params_result.get("parameters", []) or []:
+            name = p.get("name")
+            if name is None:
+                continue
+            parameter_state[name] = p.get("value")
+            if "value_string" in p:
+                display_values[name] = p["value_string"]
+
+    profile = _analyze_synth_patch(
+        device_name=device_name,
+        track_index=int(track_index),
+        device_index=int(device_index),
+        parameter_state=parameter_state,
+        display_values=display_values,
+        role_hint=role_hint,
+    )
+    result = profile.to_dict()
+    result["supported_devices"] = supported_devices()
+    return result
+
+
+@mcp.tool()
+def propose_synth_branches(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    target: Optional[dict] = None,
+    freshness: float = 0.5,
+    role_hint: str = "",
+) -> dict:
+    """Propose branch seeds + pre-compiled plans for a native synth.
+
+    Fetches the device's current parameters (via analyze_synth_patch),
+    hands them to the appropriate adapter, and returns the emitted
+    (seed, plan) pairs as two parallel lists suitable for
+    create_experiment(seeds=..., compiled_plans=...).
+
+    target: optional TimbralFingerprint dict ({"brightness": 0.3, ...}).
+        Seeds that know about target direction (synthesis_brain adapters)
+        will score their diffs against it during run_experiment with
+        render_verify=True. When omitted, adapters shift based on freshness
+        alone and role_hint gating.
+
+    freshness: 0.0-1.0; threaded into kernel for adapter magnitude scaling.
+
+    Returns:
+      {
+        "device_name": str,
+        "branch_count": int,
+        "seeds": [BranchSeed.to_dict(), ...],
+        "compiled_plans": [plan_dict, ...]    (parallel to seeds),
+        "warnings": list,
+      }
+
+    Each seed's producer_payload captures strategy + topology_hint so
+    PR3/PR4 winner-commit and render-verify can refine behavior without
+    losing provenance.
+    """
+    profile_dict = analyze_synth_patch(
+        ctx, track_index=int(track_index), device_index=int(device_index),
+        role_hint=role_hint,
+    )
+    if "error" in profile_dict:
+        return profile_dict
+
+    device_name = profile_dict.get("device_name", "")
+    if profile_dict.get("opacity") != "native":
+        return {
+            "device_name": device_name,
+            "branch_count": 0,
+            "seeds": [],
+            "compiled_plans": [],
+            "warnings": [
+                f"'{device_name}' is not a supported native synth — "
+                f"synthesis_brain only knows about {supported_devices()}"
+            ],
+        }
+
+    # Rehydrate the SynthProfile from the dict (round-trip is lossy for
+    # some nested fields, so we re-analyze with the original parameter
+    # state captured by analyze_synth_patch).
+    from .engine import analyze_synth_patch as _refetch
+    profile = _refetch(
+        device_name=device_name,
+        track_index=int(track_index),
+        device_index=int(device_index),
+        parameter_state=profile_dict.get("parameter_state") or {},
+        display_values=profile_dict.get("display_values") or {},
+        role_hint=role_hint or profile_dict.get("role_hint", ""),
+    )
+
+    target_fp = TimbralFingerprint(**{
+        k: float(v) for k, v in (target or {}).items()
+        if k in TimbralFingerprint.__dataclass_fields__ and isinstance(v, (int, float))
+    })
+    kernel = {"freshness": float(freshness)}
+
+    pairs = _propose_synth_branches(profile, target=target_fp, kernel=kernel)
+
+    seeds = [s.to_dict() for s, _ in pairs]
+    plans = [p for _, p in pairs]
+    return {
+        "device_name": device_name,
+        "branch_count": len(seeds),
+        "seeds": seeds,
+        "compiled_plans": plans,
+        "warnings": [],
+    }
+
+
+@mcp.tool()
+def extract_timbre_fingerprint(
+    ctx: Context,
+    spectrum: Optional[dict] = None,
+    loudness: Optional[dict] = None,
+    spectral_shape: Optional[dict] = None,
+) -> dict:
+    """Build a TimbralFingerprint from analysis dicts.
+
+    Pure transform — no I/O. Useful when you already have spectrum +
+    loudness + spectral_shape dicts (e.g. from analyze_spectrum_offline
+    + analyze_loudness + get_spectral_shape) and want the 9-dimensional
+    fingerprint without going through the full render-verify pipeline.
+
+    Inputs are all optional; the fingerprint degrades gracefully to
+    neutral (all-zero) when no signal data is present.
+
+    Returns: TimbralFingerprint dict with brightness, warmth, bite,
+    softness, instability, width, texture_density, movement, polish
+    — each in [-1.0, 1.0].
+    """
+    fp = _extract_fp(
+        spectrum=spectrum,
+        loudness=loudness,
+        spectral_shape=spectral_shape,
+    )
+    return fp.to_dict()

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