livepilot 1.12.2 → 1.14.0

package/mcp_server/experiment/engine.py

@@ -22,6 +22,7 @@ import time
 from typing import Optional
 
 from .models import ExperimentSet, ExperimentBranch, BranchSnapshot
+from ..branches import BranchSeed, seed_from_move_id
 import logging
 
 logger = logging.getLogger(__name__)
@@ -39,27 +40,43 @@ def _gen_id(prefix: str, seed: str) -> str:
 # ── Create experiments ───────────────────────────────────────────────────────
 
 
-def create_experiment(
+def create_experiment_from_seeds(
     request_text: str,
-    move_ids: list[str],
+    seeds: list[BranchSeed],
     kernel_id: str = "",
+    compiled_plans: Optional[list] = None,
 ) -> ExperimentSet:
-    """Create an experiment set with branches for each semantic move.
+    """Create an experiment set from BranchSeeds (PR3 canonical path).
 
-    Does NOT execute anything — just creates the branch structures.
-    Call run_experiment() to actually trial each branch.
+    seeds: one BranchSeed per desired branch. Can be any source — semantic_move,
+      freeform, synthesis, composer, technique.
+    compiled_plans: optional parallel list; when entry ``i`` is a dict, that
+      plan is attached to branch ``i`` (used by freeform / synthesis / composer
+      producers that do their own compilation). When None or entry is None,
+      run_experiment compiles from the seed at run time — which only succeeds
+      for source="semantic_move" seeds.
+
+    Does NOT execute anything — call run_experiment() to trial each branch.
     """
+    if compiled_plans is not None and len(compiled_plans) != len(seeds):
+        raise ValueError(
+            f"compiled_plans length ({len(compiled_plans)}) must match "
+            f"seeds length ({len(seeds)})"
+        )
+
     exp_id = _gen_id("exp", request_text)
     now = int(time.time() * 1000)
 
     branches = []
-    for i, move_id in enumerate(move_ids):
-        branch = ExperimentBranch(
-            branch_id=_gen_id("br", f"{move_id}_{i}"),
-            name=f"Branch {i+1}: {move_id}",
-            move_id=move_id,
+    for i, seed in enumerate(seeds):
+        plan = compiled_plans[i] if compiled_plans else None
+        display = seed.move_id or (seed.hypothesis[:32] if seed.hypothesis else seed.seed_id)
+        branch = ExperimentBranch.from_seed(
+            seed=seed,
+            branch_id=_gen_id("br", f"{seed.seed_id}_{i}"),
+            name=f"Branch {i+1}: {display}",
             source_kernel_id=kernel_id,
-            status="pending",
+            compiled_plan=plan,
             created_at_ms=now,
         )
         branches.append(branch)
@@ -76,6 +93,25 @@ def create_experiment(
     return experiment
 
 
+def create_experiment(
+    request_text: str,
+    move_ids: list[str],
+    kernel_id: str = "",
+) -> ExperimentSet:
+    """Create an experiment set with one semantic_move branch per move_id.
+
+    Legacy API — kept for back-compat. Internally builds one BranchSeed per
+    move_id via seed_from_move_id and delegates to create_experiment_from_seeds.
+    Branch naming, ids, and lifecycle are unchanged for existing callers.
+    """
+    seeds = [seed_from_move_id(mid) for mid in move_ids]
+    return create_experiment_from_seeds(
+        request_text=request_text,
+        seeds=seeds,
+        kernel_id=kernel_id,
+    )
+
+
 def get_experiment(experiment_id: str) -> Optional[ExperimentSet]:
     """Get an experiment by ID."""
     return _EXPERIMENTS.get(experiment_id)

package/mcp_server/experiment/models.py

@@ -1,8 +1,15 @@
 """Experiment branch data models.
 
-An ExperimentBranch represents one trial of a semantic move against the
-current session state. Multiple branches form an experiment set that can
-be compared and ranked.
+An ExperimentBranch represents one trial against the current session state.
+
+Pre-PR3 every branch was tied to a semantic_move (positional required
+``move_id``). PR3 widens this: a branch may now be built from any
+:class:`mcp_server.branches.BranchSeed` — semantic_move, freeform,
+synthesis, composer, or technique. The ``move_id`` field is retained as
+an optional convenience that mirrors ``seed.move_id`` for back-compat with
+callers that read ``branch.move_id`` directly.
+
+Multiple branches form an experiment set that can be compared and ranked.
 """
 
 from __future__ import annotations
@@ -11,15 +18,42 @@ import time
 from dataclasses import dataclass, field
 from typing import Any, Optional
 
+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 = {}
@@ -31,20 +65,40 @@ 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
 
 
 @dataclass
 class ExperimentBranch:
-    """One trial branch in an experiment set."""
+    """One trial branch in an experiment set.
+
+    move_id is retained as an optional convenience (empty for freeform /
+    synthesis / composer seeds) so pre-PR3 callers that read
+    ``branch.move_id`` directly keep working. The authoritative source of
+    branch intent is ``seed`` when present.
+    """
     branch_id: str
     name: str
-    move_id: str
+    # PR3 — was a required positional; now defaults to "" for seeds whose
+    # source is not "semantic_move". When seed is present, move_id mirrors
+    # seed.move_id (populated by ExperimentBranch.from_seed).
+    move_id: str = ""
     source_kernel_id: str = ""
-    status: str = "pending"  # pending | running | evaluated | committed | discarded
+    status: str = "pending"  # pending | running | evaluated | committed | discarded | interesting_but_failed
 
-    # Compiled plan for this branch
+    # Compiled plan for this branch. Pre-PR3 this was always filled in at
+    # run_experiment time. Post-PR3, freeform / synthesis / composer producers
+    # MAY pre-populate it on the seed path; run_experiment respects a
+    # pre-existing plan and only compiles when it's None.
     compiled_plan: Optional[dict] = None
 
     # Captured snapshots
@@ -65,6 +119,44 @@ class ExperimentBranch:
     created_at_ms: int = 0
     executed_at_ms: int = 0
 
+    # PR3 — branch-native seed. None for legacy move-only branches built via
+    # the bare constructor; populated when built through from_seed() or via
+    # create_experiment_from_seeds.
+    seed: Optional[BranchSeed] = None
+
+    @classmethod
+    def from_seed(
+        cls,
+        seed: BranchSeed,
+        branch_id: str,
+        name: str = "",
+        source_kernel_id: str = "",
+        compiled_plan: Optional[dict] = None,
+        created_at_ms: int = 0,
+    ) -> "ExperimentBranch":
+        """Construct an ExperimentBranch from a BranchSeed.
+
+        ``move_id`` is mirrored from ``seed.move_id`` (empty for freeform /
+        synthesis / composer / technique seeds). When ``compiled_plan`` is
+        provided, the producer has already compiled — run_experiment will
+        skip compilation for this branch. When None, compilation defers to
+        the semantic_moves.compiler at run time and only succeeds for
+        source="semantic_move" seeds.
+        """
+        default_name = (
+            f"Branch ({seed.source}:{seed.move_id or seed.seed_id[:8]})"
+        )
+        return cls(
+            branch_id=branch_id,
+            name=name or default_name,
+            move_id=seed.move_id,
+            source_kernel_id=source_kernel_id,
+            status="pending",
+            compiled_plan=compiled_plan,
+            created_at_ms=created_at_ms,
+            seed=seed,
+        )
+
     def to_dict(self) -> dict:
         d = {
             "branch_id": self.branch_id,
@@ -87,6 +179,18 @@ class ExperimentBranch:
             d["execution_log"] = self.execution_log
             d["steps_ok"] = sum(1 for e in self.execution_log if e.get("ok"))
             d["steps_failed"] = sum(1 for e in self.execution_log if not e.get("ok"))
+        if self.seed is not None:
+            d["seed"] = self.seed.to_dict()
+            d["branch_source"] = self.seed.source
+            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