livepilot 1.13.0 → 1.14.0

package/mcp_server/evaluation/policy.py

@@ -120,6 +120,74 @@ class BranchOutcome:
         return asdict(self)
 
 
+def derive_goal_progress_from_fingerprint(
+    fingerprint_diff: dict,
+    target: Optional[dict] = None,
+) -> tuple[float, int]:
+    """Derive (goal_progress, measurable_count) from a fingerprint diff.
+
+    PR4 wiring: TimbralFingerprint dimensions (brightness, warmth, bite,
+    softness, instability, width, texture_density, movement, polish) are
+    effectively a goal vector. When a branch has before/after fingerprints
+    extracted from actual captured audio, the per-dimension diff IS the
+    measurable evidence classify_branch_outcome needs to make a real
+    decision — no reason to fall back to the heuristic score alone.
+
+    fingerprint_diff: output of synthesis_brain.diff_fingerprint(before, after).
+      Shape: {"brightness": float, "warmth": float, ...}
+    target: optional TimbralFingerprint dict ({"brightness": 0.3, ...}).
+      When provided, goal_progress counts only dimensions the target
+      cared about (non-zero target value). When None, every dimension
+      with a non-trivial diff counts as a target.
+
+    Returns:
+      (goal_progress, measurable_count) tuple ready to feed into
+      classify_branch_outcome. goal_progress is signed (positive =
+      branch moved in the intended direction; negative = moved away).
+      measurable_count is how many dimensions had a readable diff.
+    """
+    if not fingerprint_diff:
+        return (0.0, 0)
+
+    # Epsilon — diffs this small are noise, not signal.
+    eps = 0.02
+    progress = 0.0
+    count = 0
+
+    # If target is provided, score each dimension by
+    #   sign(target) * diff
+    # so moving in the target's direction counts positive, regardless
+    # of target magnitude. When no target, count any non-trivial diff
+    # in either direction as progress (a branch that "moves" at all
+    # is evidence the producer did something).
+    if target:
+        for dim, delta in fingerprint_diff.items():
+            if not isinstance(delta, (int, float)):
+                continue
+            if abs(delta) < eps:
+                continue
+            target_val = target.get(dim, 0.0)
+            if abs(target_val) < eps:
+                continue  # target didn't care about this dimension
+            count += 1
+            # Normalize: sign(target) * delta, scaled so each dimension
+            # contributes at most 1.0 to progress.
+            direction = 1.0 if target_val > 0 else -1.0
+            progress += direction * max(-1.0, min(1.0, delta))
+    else:
+        for dim, delta in fingerprint_diff.items():
+            if not isinstance(delta, (int, float)):
+                continue
+            if abs(delta) < eps:
+                continue
+            count += 1
+            # Without a target, we can't tell "good" from "bad" movement.
+            # Count as weakly positive — branch did something measurable.
+            progress += abs(max(-1.0, min(1.0, delta))) * 0.5
+
+    return (round(progress, 3), count)
+
+
 def classify_branch_outcome(
     score: float,
     *,
@@ -128,6 +196,8 @@ def classify_branch_outcome(
     target_count: int = 0,
     goal_progress: float = 0.0,
     exploration_rules: bool = False,
+    fingerprint_diff: Optional[dict] = None,
+    timbral_target: Optional[dict] = None,
 ) -> BranchOutcome:
     """Classify a branch's terminal status from a score + optional hard-rule inputs.
 
@@ -143,9 +213,37 @@ def classify_branch_outcome(
         protection violations still force undo (safety invariant);
         all other failures downgrade to "interesting_but_failed".
 
+    PR4 additions (optional):
+      fingerprint_diff: output of synthesis_brain.diff_fingerprint
+        between before/after snapshots. When provided AND no caller-
+        supplied measurable_count/goal_progress were passed (both 0),
+        the classifier derives them from the diff — so the dimensions
+        of the TimbralFingerprint become the goal vector.
+      timbral_target: optional target fingerprint dict. Scores diff in
+        the target's direction (moving brighter counts positive when
+        target.brightness > 0). Omit when the branch had no specific
+        target; dimensions with non-trivial movement still contribute
+        measurable_count but progress is unsigned magnitude * 0.5.
+
     Returns a BranchOutcome that callers can plug into branch.score /
     .status / .evaluation without further interpretation.
     """
+    # PR4 — derive measurable evidence from fingerprint diff when the
+    # caller didn't supply their own. Keeps back-compat for existing
+    # callers that compute their own measurable inputs.
+    if (
+        fingerprint_diff
+        and measurable_count == 0
+        and abs(goal_progress) < 1e-6
+    ):
+        derived_progress, derived_count = derive_goal_progress_from_fingerprint(
+            fingerprint_diff, target=timbral_target,
+        )
+        goal_progress = derived_progress
+        measurable_count = derived_count
+        # target_count should also reflect the derived dimensions so the
+        # hard-rule path treats this as a genuinely measurable outcome.
+        target_count = max(target_count, derived_count)
     keep_change, failures = apply_hard_rules(
         goal_progress=goal_progress,
         collateral_damage=0.0,  # not threaded here — branch lifecycle doesn't compute it yet

package/mcp_server/experiment/models.py

@@ -23,12 +23,37 @@ from ..branches import BranchSeed
 
 @dataclass
 class BranchSnapshot:
-    """Captured state before or after a branch experiment."""
+    """Captured state before or after a branch experiment.
+
+    Pre-PR4 fields (spectrum / rms / peak / track_meters) stay the same —
+    they remain the fast-path evidence when render-verify isn't available
+    or wasn't opted in.
+
+    PR4 adds render-based fields that are populated only when the
+    experiment runs with render_verify=True:
+
+      capture_path: path to the captured audio file (useful for re-analysis
+                    or user audition of the branch output).
+      loudness: {lufs, lra, rms, peak, crest} from analyze_loudness.
+      spectral_shape: {centroid, flatness, rolloff, crest} from FluCoMa or
+                      the offline analyzer.
+      fingerprint: TimbralFingerprint.to_dict() extracted from the
+                   captured audio.
+
+    The fingerprint is what classify_branch_outcome reads to derive a
+    real goal_progress + measurable_count instead of relying on the
+    inline meter-based heuristic alone.
+    """
     spectrum: Optional[dict] = None
     rms: Optional[float] = None
     peak: Optional[float] = None
     track_meters: Optional[list] = None
     timestamp_ms: int = 0
+    # PR4 — render-based evidence (opt-in via render_verify flag)
+    capture_path: Optional[str] = None
+    loudness: Optional[dict] = None
+    spectral_shape: Optional[dict] = None
+    fingerprint: Optional[dict] = None  # TimbralFingerprint.to_dict()
 
     def to_dict(self) -> dict:
         d = {}
@@ -40,6 +65,14 @@ class BranchSnapshot:
             d["peak"] = self.peak
         if self.track_meters is not None:
             d["track_meters"] = self.track_meters
+        if self.capture_path is not None:
+            d["capture_path"] = self.capture_path
+        if self.loudness is not None:
+            d["loudness"] = self.loudness
+        if self.spectral_shape is not None:
+            d["spectral_shape"] = self.spectral_shape
+        if self.fingerprint is not None:
+            d["fingerprint"] = self.fingerprint
         d["timestamp_ms"] = self.timestamp_ms
         return d
 
@@ -152,6 +185,12 @@ class ExperimentBranch:
             d["analytical_only"] = (
                 self.seed.analytical_only or self.compiled_plan is None
             )
+            # Shortcut to the seed's producer_payload so downstream callers
+            # (composer winner-commit, synthesis re-target, provenance logs)
+            # don't have to reach into d["seed"]["producer_payload"] every
+            # time. The full seed dict is still available for producers
+            # that need other fields.
+            d["producer_payload"] = dict(self.seed.producer_payload or {})
         return d
 
 

package/mcp_server/experiment/tools.py

@@ -29,7 +29,11 @@ def _get_ableton(ctx: Context):
 
 
 def _capture_snapshot(ctx: Context) -> BranchSnapshot:
-    """Capture current session state as a BranchSnapshot."""
+    """Capture current session state as a BranchSnapshot (fast path).
+
+    Uses live meters + spectral cache. No audio rendering. Called when
+    render_verify is off (default) — adds no latency to branch trials.
+    """
     ableton = _get_ableton(ctx)
     spectral = ctx.lifespan_context.get("spectral")
 
@@ -58,6 +62,116 @@ def _capture_snapshot(ctx: Context) -> BranchSnapshot:
     return snapshot
 
 
+def _capture_snapshot_with_render_verify(
+    ctx: Context, duration_seconds: float = 2.0,
+) -> BranchSnapshot:
+    """Capture state AND render audio for fingerprint extraction (PR4).
+
+    Runs the fast-path snapshot first, then additionally:
+      1. capture_audio duration_seconds seconds from master
+      2. analyze_loudness on the captured file
+      3. analyze_spectrum_offline on the captured file
+      4. extract_timbre_fingerprint from spectrum + loudness
+
+    Attaches capture_path, loudness, spectral_shape, and fingerprint to
+    the snapshot. When any stage fails (bridge unavailable, analyzer
+    missing, etc.), that stage's field is left None and a debug log is
+    emitted — render-verify degrades gracefully to the fast-path snapshot.
+
+    Expected added latency: duration_seconds (capture) + ~1-2s (offline
+    analysis). For a 2-branch experiment with 2s captures, that's
+    ~8-10s of overhead vs the default path.
+    """
+    snapshot = _capture_snapshot(ctx)
+
+    ableton = _get_ableton(ctx)
+    bridge = ctx.lifespan_context.get("m4l")
+
+    # Step 1: capture_audio is a bridge command — route via bridge.send_command
+    # if available, else fall back to ableton TCP which doesn't support it.
+    capture_path = None
+    if bridge is not None:
+        try:
+            maybe = bridge.send_command("capture_audio", float(duration_seconds), "master", "")
+            # bridge.send_command may return awaitable or plain dict.
+            import inspect
+            if inspect.isawaitable(maybe):
+                # We're in a sync context here — best effort, skip await.
+                # Render-verify from within sync capture_fn is the compromise;
+                # the async variant wires through from run_branch_async which
+                # does have await. Use the fast-path capture only.
+                logger.debug("capture_audio returned awaitable in sync context; skipping render-verify for this snapshot")
+                return snapshot
+            if isinstance(maybe, dict):
+                capture_path = maybe.get("file_path") or maybe.get("path") or maybe.get("filename")
+        except Exception as exc:
+            logger.debug("render-verify capture_audio failed: %s", exc)
+    if not capture_path:
+        return snapshot  # graceful degrade — caller still gets fast-path data
+    snapshot.capture_path = capture_path
+
+    # Step 2-3: offline loudness + spectrum analysis (MCP tools, sync wrappers)
+    try:
+        from ..tools.analyzer import analyze_loudness as _analyze_loudness
+        loud = _analyze_loudness(capture_path)
+        if isinstance(loud, dict) and "error" not in loud:
+            snapshot.loudness = loud
+    except Exception as exc:
+        logger.debug("render-verify analyze_loudness failed: %s", exc)
+
+    try:
+        from ..tools.analyzer import analyze_spectrum_offline as _analyze_spectrum
+        spec = _analyze_spectrum(capture_path)
+        if isinstance(spec, dict) and "error" not in spec:
+            snapshot.spectral_shape = {
+                "centroid": spec.get("centroid_hz"),
+                "flatness": spec.get("spectral_flatness"),
+                "rolloff": spec.get("rolloff_hz"),
+                "bandwidth": spec.get("bandwidth_hz"),
+                # Back-map the 5-band balance into the 8-band keys our
+                # fingerprint extractor expects. Coarse mapping:
+                "bands": _map_5band_to_8band(spec.get("band_balance", {})),
+            }
+    except Exception as exc:
+        logger.debug("render-verify analyze_spectrum_offline failed: %s", exc)
+
+    # Step 4: build fingerprint from what we got
+    try:
+        from ..synthesis_brain import extract_timbre_fingerprint
+        fp = extract_timbre_fingerprint(
+            spectrum=(snapshot.spectral_shape or {}).get("bands"),
+            loudness=snapshot.loudness,
+            spectral_shape=snapshot.spectral_shape,
+        )
+        snapshot.fingerprint = fp.to_dict()
+    except Exception as exc:
+        logger.debug("render-verify extract_timbre_fingerprint failed: %s", exc)
+
+    return snapshot
+
+
+def _map_5band_to_8band(b5: dict) -> dict:
+    """Adapt analyze_spectrum_offline's 5-band balance to the 8-band shape
+    extract_timbre_fingerprint expects.
+
+    5-band: sub_60hz, low_250hz, mid_2khz, high_8khz, air_16khz
+    8-band: sub, low, low_mid, mid, high_mid, high, very_high, ultra
+    """
+    if not isinstance(b5, dict):
+        return {}
+    # Conservative mapping — split each 5-band bucket across the 8-band shape.
+    return {
+        "sub":       float(b5.get("sub_60hz", 0.0) or 0.0),
+        "low":       float(b5.get("low_250hz", 0.0) or 0.0) * 0.6,
+        "low_mid":   float(b5.get("low_250hz", 0.0) or 0.0) * 0.4,
+        "mid":       float(b5.get("mid_2khz", 0.0) or 0.0) * 0.6,
+        "high_mid":  float(b5.get("mid_2khz", 0.0) or 0.0) * 0.4,
+        "high":      float(b5.get("high_8khz", 0.0) or 0.0) * 0.6,
+        "very_high": float(b5.get("high_8khz", 0.0) or 0.0) * 0.4,
+        "ultra":     float(b5.get("air_16khz", 0.0) or 0.0),
+    }
+
+
 @mcp.tool()
 def create_experiment(
     ctx: Context,
@@ -174,6 +288,8 @@ async def run_experiment(
     ctx: Context,
     experiment_id: str,
     exploration_rules: bool = False,
+    render_verify: bool = False,
+    render_duration_seconds: float = 2.0,
 ) -> dict:
     """Run all pending branches in an experiment.
 
@@ -189,14 +305,28 @@ async def run_experiment(
 
     Branches run sequentially (Ableton has linear undo).
 
-    exploration_rules (PR7): when True, branches that fail technical gates
-    (score < 0.40, non-positive measurable delta) are classified as
-    "interesting_but_failed" instead of "failed" — they stay in the
-    experiment for audit but don't appear in the ranking. Protection
-    violations STILL force undo regardless of this flag — that's a safety
-    invariant, not a taste judgment.
-
-    Default False preserves pre-PR7 behavior exactly.
+    exploration_rules: when True, branches that fail technical gates
+      (score < 0.40, non-positive measurable delta) are classified as
+      "interesting_but_failed" instead of "failed" — they stay in the
+      experiment for audit but don't appear in the ranking. Protection
+      violations STILL force undo regardless of this flag — that's a
+      safety invariant, not a taste judgment.
+
+    render_verify (PR4/v2): when True, each branch also captures audio
+      before and after execution, analyzes spectrum + loudness offline,
+      extracts a TimbralFingerprint, and attaches the before/after
+      fingerprint + diff to the branch snapshots. The diff is fed into
+      classify_branch_outcome as real measurable evidence — the
+      classifier no longer relies on meter heuristics alone. Default
+      False preserves speed; opt in when you want the classifier to
+      respond to spectral movement, not just track-meter drops.
+
+    render_duration_seconds: capture length per snapshot when
+      render_verify is on. Default 2.0 seconds. Each branch adds
+      ~2 * duration_seconds of capture time plus ~1-2s of offline
+      analysis — a 3-branch experiment at 2s adds ~15-18s.
+
+    Default render_verify=False preserves pre-PR4 behavior exactly.
     """
     experiment = engine.get_experiment(experiment_id)
     if not experiment:
@@ -263,12 +393,22 @@ async def run_experiment(
             plan = compiler.compile(move, kernel)
             compiled_dict = plan.to_dict()
 
+        # Pick the capture function — render-verify mode captures audio
+        # and extracts a TimbralFingerprint, adding latency but giving
+        # classify_branch_outcome real measurable evidence.
+        if render_verify:
+            capture_fn = lambda: _capture_snapshot_with_render_verify(
+                ctx, duration_seconds=render_duration_seconds,
+            )
+        else:
+            capture_fn = lambda: _capture_snapshot(ctx)
+
         # Run the branch through the async router
         await engine.run_branch_async(
             branch=branch,
             ableton=ableton,
             compiled_plan=compiled_dict,
-            capture_fn=lambda: _capture_snapshot(ctx),
+            capture_fn=capture_fn,
             bridge=bridge,
             mcp_registry=mcp_registry,
             ctx=ctx,
@@ -303,19 +443,50 @@ async def run_experiment(
                 score += 0.1  # presence-of-data bonus
 
             score = round(score, 3)
+
+            # PR4 — fingerprint diff to feed the classifier when render-verify
+            # is on. When both before/after have fingerprints, compute the
+            # per-dimension diff via synthesis_brain.diff_fingerprint and let
+            # classify_branch_outcome derive real measurable_count + goal_progress
+            # from it. Much stronger evidence than the meter heuristic alone.
+            fingerprint_diff = None
+            timbral_target = None
+            before_fp = before.get("fingerprint")
+            after_fp = after.get("fingerprint")
+            if before_fp and after_fp:
+                try:
+                    from ..synthesis_brain import diff_fingerprint, TimbralFingerprint
+                    before_obj = TimbralFingerprint(**{
+                        k: v for k, v in before_fp.items()
+                        if k in TimbralFingerprint.__dataclass_fields__
+                    })
+                    after_obj = TimbralFingerprint(**{
+                        k: v for k, v in after_fp.items()
+                        if k in TimbralFingerprint.__dataclass_fields__
+                    })
+                    fingerprint_diff = diff_fingerprint(before_obj, after_obj)
+                except Exception as exc:
+                    logger.debug("fingerprint diff failed: %s", exc)
+
+            # If the branch's seed was a synthesis seed with a timbral target
+            # in its producer_payload, score diff in that target's direction.
+            if branch.seed is not None and branch.seed.source == "synthesis":
+                target_hint = (branch.seed.producer_payload or {}).get("timbral_target")
+                if isinstance(target_hint, dict):
+                    timbral_target = target_hint
+
             outcome = classify_branch_outcome(
                 score=score,
                 protection_violated=protection_violated,
-                # Minimal hard-rule inputs — the heuristic doesn't compute
-                # measurable_count / goal_progress deltas. target_count=0 and
-                # measurable_count=0 lets rule 1 defer to score-only judgment.
                 measurable_count=0,
                 target_count=0,
                 goal_progress=0.0,
                 exploration_rules=exploration_rules,
+                fingerprint_diff=fingerprint_diff,
+                timbral_target=timbral_target,
             )
 
-            return {
+            result_eval = {
                 "score": outcome.score,
                 "keep_change": outcome.keep_change,
                 "status": outcome.status,
@@ -323,6 +494,13 @@ async def run_experiment(
                 "note": outcome.note,
                 "lost_tracks": lost_tracks,
             }
+            # Surface fingerprint evidence on the evaluation dict so
+            # compare_experiments can show per-branch spectral deltas.
+            if fingerprint_diff is not None:
+                result_eval["fingerprint_diff"] = fingerprint_diff
+                result_eval["fingerprint_before"] = before_fp
+                result_eval["fingerprint_after"] = after_fp
+            return result_eval
 
         engine.evaluate_branch(branch, eval_fn)
 
@@ -458,7 +636,84 @@ async def commit_experiment(
     bridge = ctx.lifespan_context.get("m4l")
     mcp_registry = ctx.lifespan_context.get("mcp_dispatch", {})
 
-    return await engine.commit_branch_async(
+    # PR3 — composer winner escalation. When the winning branch came from
+    # the composer producer, the plan we auditioned was a lightweight
+    # scaffold (set_tempo + create_midi_track + create_scene/set_scene_name).
+    # Commit should deliver a populated session, not an empty skeleton.
+    # Re-run ComposerEngine.compose() on the intent captured in the seed's
+    # producer_payload, replace the branch's compiled_plan with the full
+    # resolved plan, then commit through the normal async router.
+    #
+    # When escalation fails (missing intent, zero resolved layers, etc.),
+    # fall back to committing the scaffold. Users get tracks + scenes
+    # they can populate manually, which is better than an error.
+    escalation_info = None
+    if (
+        target.seed is not None
+        and target.seed.source == "composer"
+        and target.seed.producer_payload
+    ):
+        try:
+            from ..composer import escalate_composer_branch
+            splice_client = ctx.lifespan_context.get("splice_client")
+            # browser_client only present on servers with live browser wiring;
+            # pass None defensively.
+            browser_client = ctx.lifespan_context.get("browser_client")
+            search_roots = ctx.lifespan_context.get("sample_search_roots") or []
+
+            escalation_info = await escalate_composer_branch(
+                producer_payload=target.seed.producer_payload,
+                search_roots=search_roots,
+                splice_client=splice_client,
+                browser_client=browser_client,
+            )
+
+            if escalation_info.get("ok"):
+                # Swap the compiled_plan for the fully resolved one before
+                # commit_branch_async runs it. Keep the old scaffold on the
+                # evaluation dict for audit.
+                old_plan = target.compiled_plan or {}
+                new_plan = {
+                    "steps": escalation_info["plan"],
+                    "step_count": escalation_info["step_count"],
+                    "summary": (
+                        f"Composer escalated: {escalation_info['layer_count']} "
+                        f"layers, {escalation_info['step_count']} steps "
+                        f"({len(escalation_info['resolved_samples'])} samples resolved)"
+                    ),
+                }
+                target.compiled_plan = new_plan
+                if target.evaluation is None:
+                    target.evaluation = {}
+                target.evaluation["composer_escalation"] = {
+                    "escalated": True,
+                    "scaffold_step_count": old_plan.get("step_count", 0),
+                    "resolved_step_count": escalation_info["step_count"],
+                    "layer_count": escalation_info["layer_count"],
+                    "resolved_samples": escalation_info["resolved_samples"],
+                    "warnings": escalation_info.get("warnings", []),
+                }
+            else:
+                # Record the fallback reason on evaluation so compare /
+                # commit responses carry explicit provenance.
+                if target.evaluation is None:
+                    target.evaluation = {}
+                target.evaluation["composer_escalation"] = {
+                    "escalated": False,
+                    "error": escalation_info.get("error", "unknown"),
+                    "warnings": escalation_info.get("warnings", []),
+                    "fallback": "scaffold_plan",
+                }
+        except Exception as exc:
+            if target.evaluation is None:
+                target.evaluation = {}
+            target.evaluation["composer_escalation"] = {
+                "escalated": False,
+                "error": f"escalation raised: {exc}",
+                "fallback": "scaffold_plan",
+            }
+
+    commit_result = await engine.commit_branch_async(
         experiment,
         branch_id,
         ableton,
@@ -467,6 +722,19 @@ async def commit_experiment(
         ctx=ctx,
     )
 
+    # Surface escalation details on the commit response so the caller
+    # sees whether a scaffold or resolved plan was applied.
+    if escalation_info is not None and isinstance(commit_result, dict):
+        commit_result["composer_escalation"] = {
+            "escalated": bool(escalation_info.get("ok")),
+            "step_count": escalation_info.get("step_count"),
+            "layer_count": escalation_info.get("layer_count"),
+            "error": escalation_info.get("error"),
+            "warnings": escalation_info.get("warnings", []),
+        }
+
+    return commit_result
+
 
 @mcp.tool()
 def discard_experiment(

package/mcp_server/server.py

@@ -305,6 +305,7 @@ from .device_forge import tools as device_forge_tools          # noqa: F401, E40
 from .sample_engine import tools as sample_engine_tools        # noqa: F401, E402
 from .atlas import tools as atlas_tools                        # noqa: F401, E402
 from .composer import tools as composer_tools                  # noqa: F401, E402
+from .synthesis_brain import tools as synthesis_brain_tools    # noqa: F401, E402
 from .tools import diagnostics   # noqa: F401, E402
 from .tools import miditool       # noqa: F401, E402