livepilot 1.12.2 → 1.13.0

package/mcp_server/experiment/tools.py

@@ -16,6 +16,7 @@ from typing import Optional
 from fastmcp import Context
 
 from ..server import mcp
+from ..branches import BranchSeed
 from . import engine
 from .models import BranchSnapshot
 import logging
@@ -63,18 +64,71 @@ def create_experiment(
     request_text: str,
     move_ids: Optional[list] = None,
     limit: int = 3,
+    seeds: Optional[list] = None,
+    compiled_plans: Optional[list] = None,
 ) -> dict:
     """Create an experiment set to compare multiple approaches.
 
-    If move_ids is provided, creates one branch per move.
-    Otherwise, uses propose_next_best_move to find candidates.
+    Three input modes (in priority order):
 
-    request_text: what the user wants (e.g., "make this punchier")
-    move_ids: specific moves to try (e.g., ["make_punchier", "tighten_low_end"])
-    limit: max branches when auto-proposing (default 3)
+    1. seeds (PR3+): a list of BranchSeed dicts. Each seed becomes one branch.
+       compiled_plans (optional parallel list) attaches pre-compiled plans
+       for freeform / synthesis / composer producers. Seed dict shape:
+         {seed_id, source, move_id, hypothesis, protected_qualities,
+          affected_scope, distinctness_reason, risk_label, novelty_label,
+          analytical_only}
+       Missing fields default per BranchSeed. This is the canonical path
+       for producers that have already done their own selection work.
+
+    2. move_ids: legacy path — one semantic_move seed per move_id.
+       Unchanged behavior; internally delegates to the seeds path.
+
+    3. Auto-proposal: neither seeds nor move_ids provided. Scans the semantic
+       move registry by keyword overlap with request_text and takes the top
+       ``limit`` moves (default 3).
 
     Returns: experiment set with branch IDs ready for run_experiment.
     """
+    # ── Mode 1: seeds provided ──────────────────────────────────────────
+    if seeds:
+        rehydrated: list[BranchSeed] = []
+        for i, s in enumerate(seeds):
+            if isinstance(s, BranchSeed):
+                rehydrated.append(s)
+            elif isinstance(s, dict):
+                try:
+                    rehydrated.append(BranchSeed(**s))
+                except TypeError as exc:
+                    return {"error": f"seeds[{i}] invalid: {exc}"}
+            else:
+                return {
+                    "error": (
+                        f"seeds[{i}] must be dict or BranchSeed, "
+                        f"got {type(s).__name__}"
+                    )
+                }
+
+        if compiled_plans is not None and len(compiled_plans) != len(rehydrated):
+            return {
+                "error": (
+                    f"compiled_plans length ({len(compiled_plans)}) must match "
+                    f"seeds length ({len(rehydrated)})"
+                )
+            }
+
+        ableton = _get_ableton(ctx)
+        ableton.send_command("get_session_info")
+        kernel_id = f"kern_{int(time.time())}"
+
+        experiment = engine.create_experiment_from_seeds(
+            request_text=request_text,
+            seeds=rehydrated,
+            kernel_id=kernel_id,
+            compiled_plans=compiled_plans,
+        )
+        return experiment.to_dict()
+
+    # ── Mode 2/3: legacy move_ids path ──────────────────────────────────
     if not move_ids:
         # Auto-propose moves from the registry
         from ..semantic_moves import registry
@@ -119,19 +173,30 @@ def create_experiment(
 async def run_experiment(
     ctx: Context,
     experiment_id: str,
+    exploration_rules: bool = False,
 ) -> dict:
     """Run all pending branches in an experiment.
 
     For each branch:
     1. Compile the semantic move against current session
+       (skipped when branch.compiled_plan is already set — PR3+)
     2. Capture before state
-    3. Execute the compiled plan (through the async router — v1.10.3 truth)
+    3. Execute the compiled plan (through the async router)
     4. Capture after state
     5. Undo all successful steps (revert to checkpoint)
-    6. Evaluate the branch
+    6. Evaluate the branch and classify its outcome via evaluation.policy
     7. Record per-step results on branch.execution_log
 
     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.
     """
     experiment = engine.get_experiment(experiment_id)
     if not experiment:
@@ -149,19 +214,54 @@ async def run_experiment(
         if branch.status != "pending":
             continue
 
-        # Compile the move
-        move = registry.get_move(branch.move_id)
-        if not move:
-            branch.status = "failed"
-            branch.score = 0.0
-            branch.evaluation = {"error": f"Move {branch.move_id} not found"}
-            results.append(branch.to_dict())
-            continue
-
-        session_info = ableton.send_command("get_session_info")
-        kernel = {"session_info": session_info, "mode": "explore"}
-        plan = compiler.compile(move, kernel)
-        compiled_dict = plan.to_dict()
+        # PR3: respect a pre-existing compiled_plan on the branch (freeform /
+        # synthesis / composer producers bring their own). Only compile from
+        # move_id when the branch arrived without a plan — which requires a
+        # semantic_move seed (or a legacy move-only branch).
+        compiled_dict = branch.compiled_plan
+
+        if compiled_dict is None:
+            # Analytical-only branches short-circuit — no plan to run.
+            # Marked with status="analytical" so ranked_branches()
+            # (which only surfaces "evaluated") excludes them, and
+            # commit_experiment refuses to re-apply them.
+            if branch.seed is not None and branch.seed.analytical_only:
+                branch.status = "analytical"
+                branch.score = 0.0
+                branch.evaluation = {
+                    "score": 0.0,
+                    "keep_change": False,
+                    "status": "analytical",
+                    "note": "analytical_only branch — no execution path",
+                }
+                results.append(branch.to_dict())
+                continue
+
+            if not branch.move_id:
+                branch.status = "failed"
+                branch.score = 0.0
+                branch.evaluation = {
+                    "error": (
+                        "Branch has no compiled_plan and no move_id — "
+                        "freeform producers must pre-populate compiled_plan"
+                    )
+                }
+                results.append(branch.to_dict())
+                continue
+
+            # Compile from semantic move
+            move = registry.get_move(branch.move_id)
+            if not move:
+                branch.status = "failed"
+                branch.score = 0.0
+                branch.evaluation = {"error": f"Move {branch.move_id} not found"}
+                results.append(branch.to_dict())
+                continue
+
+            session_info = ableton.send_command("get_session_info")
+            kernel = {"session_info": session_info, "mode": "explore"}
+            plan = compiler.compile(move, kernel)
+            compiled_dict = plan.to_dict()
 
         # Run the branch through the async router
         await engine.run_branch_async(
@@ -174,26 +274,78 @@ async def run_experiment(
             ctx=ctx,
         )
 
-        # Evaluate
+        # Evaluate — score via the inline heuristic, then classify via
+        # evaluation.policy for a unified keep/undo/interesting_but_failed
+        # decision (PR7).
+        from ..evaluation.policy import classify_branch_outcome
+
         def eval_fn(before, after):
-            # Simple heuristic evaluation when spectral data isn't available
+            # Simple heuristic evaluation when spectral data isn't available.
+            # protection_violated is rough — derived from whether any track
+            # went silent (signal lost on a track = protection violation).
             score = 0.5  # Neutral
+            protection_violated = False
+            lost_tracks = 0
+
             if before.get("track_meters") and after.get("track_meters"):
-                # Check all tracks still alive
                 before_alive = sum(1 for t in before["track_meters"] if t.get("level", 0) > 0)
                 after_alive = sum(1 for t in after["track_meters"] if t.get("level", 0) > 0)
-                if after_alive >= before_alive:
+                lost_tracks = max(0, before_alive - after_alive)
+                if lost_tracks == 0:
                     score += 0.1
                 else:
-                    score -= 0.2  # Lost a track
+                    score -= 0.2
+                    # A track going silent is a protection violation — always
+                    # undo regardless of exploration mode.
+                    protection_violated = True
 
             if before.get("spectrum") and after.get("spectrum"):
-                # Spectral balance improvement heuristic
-                score += 0.1  # Bonus for having spectral data
-
-            return {"score": round(score, 3), "keep_change": score > 0.45}
+                score += 0.1  # presence-of-data bonus
+
+            score = round(score, 3)
+            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,
+            )
+
+            return {
+                "score": outcome.score,
+                "keep_change": outcome.keep_change,
+                "status": outcome.status,
+                "failure_reasons": outcome.failure_reasons,
+                "note": outcome.note,
+                "lost_tracks": lost_tracks,
+            }
 
         engine.evaluate_branch(branch, eval_fn)
+
+        # Promote the classified status onto the branch. ranked_branches()
+        # only surfaces status="evaluated", so branches the classifier
+        # rejected ("undo") or retained for audit ("interesting_but_failed")
+        # are both correctly excluded from winner recommendations.
+        # Without this mapping, a branch the hard-rule classifier explicitly
+        # rejected could still win a ranking and be re-applied by commit.
+        if branch.evaluation and branch.evaluation.get("status"):
+            status = branch.evaluation["status"]
+            if status == "keep":
+                branch.status = "evaluated"
+            elif status == "interesting_but_failed":
+                branch.status = "interesting_but_failed"
+            elif status == "undo":
+                # Undo-classified branches had their steps rolled back by
+                # run_branch_async's undo pass; they must NOT be eligible
+                # winners. "rejected" is a terminal branch status distinct
+                # from "failed" (execution failed) and distinct from
+                # "interesting_but_failed" (exploration-mode retention).
+                branch.status = "rejected"
+
         results.append(branch.to_dict())
 
     return {
@@ -221,6 +373,30 @@ def compare_experiments(
         return {"error": f"Experiment {experiment_id} not found"}
 
     ranked = experiment.ranked_branches()
+
+    # Surface non-winning branch categories separately. None of these are
+    # candidates for commit — ranked_branches() filters them out — but the
+    # user sees what was tried.
+    interesting_failed = [
+        b for b in experiment.branches if b.status == "interesting_but_failed"
+    ]
+    rejected = [
+        b for b in experiment.branches if b.status == "rejected"
+    ]
+    analytical = [
+        b for b in experiment.branches if b.status == "analytical"
+    ]
+
+    def _audit_row(b):
+        return {
+            "branch_id": b.branch_id,
+            "name": b.name,
+            "move_id": b.move_id,
+            "score": b.score,
+            "summary": b.compiled_plan.get("summary", "") if b.compiled_plan else "",
+            "evaluation": b.evaluation,
+        }
+
     return {
         "experiment_id": experiment_id,
         "request": experiment.request_text,
@@ -228,16 +404,14 @@ def compare_experiments(
         "ranking": [
             {
                 "rank": i + 1,
-                "branch_id": b.branch_id,
-                "name": b.name,
-                "move_id": b.move_id,
-                "score": b.score,
-                "summary": b.compiled_plan.get("summary", "") if b.compiled_plan else "",
-                "evaluation": b.evaluation,
+                **_audit_row(b),
             }
             for i, b in enumerate(ranked)
         ],
         "winner": ranked[0].to_dict() if ranked else None,
+        "interesting_but_failed": [_audit_row(b) for b in interesting_failed],
+        "rejected": [_audit_row(b) for b in rejected],
+        "analytical": [_audit_row(b) for b in analytical],
     }
 
 
@@ -258,6 +432,28 @@ async def commit_experiment(
     if not experiment:
         return {"error": f"Experiment {experiment_id} not found"}
 
+    # Refuse to commit branches the classifier rejected or that were
+    # analytical-only. Those statuses exist specifically so callers
+    # can't route them into re-application, and ranked_branches()
+    # already excludes them — so reaching commit with such a branch
+    # means the caller is bypassing the ranking layer.
+    target = experiment.get_branch(branch_id)
+    if target is None:
+        return {"error": f"Branch {branch_id} not found"}
+    if target.status in ("rejected", "analytical", "failed"):
+        return {
+            "error": (
+                f"Cannot commit branch with status '{target.status}'. "
+                f"'rejected' = hard-rule classifier rolled back; "
+                f"'analytical' = no executable plan; "
+                f"'failed' = zero steps applied successfully. "
+                f"Use compare_experiments to see eligible winners "
+                f"(only status='evaluated' branches are ranking candidates)."
+            ),
+            "branch_id": branch_id,
+            "branch_status": target.status,
+        }
+
     ableton = _get_ableton(ctx)
     bridge = ctx.lifespan_context.get("m4l")
     mcp_registry = ctx.lifespan_context.get("mcp_dispatch", {})

package/mcp_server/memory/taste_graph.py

@@ -75,13 +75,37 @@ class TasteGraph:
     # Device preferences
     device_affinities: dict[str, DeviceAffinity] = field(default_factory=dict)
 
-    # Novelty tolerance: 0 = very conservative, 1 = very experimental
-    novelty_band: float = 0.5
+    # PR8 — per-goal-mode novelty bands. Canonical source of truth.
+    # Keys are goal modes ("improve", "explore", or any string a caller
+    # supplies). novelty_band (below, as a property) reads/writes
+    # novelty_bands["improve"] — one storage, two access paths.
+    novelty_bands: dict = field(
+        default_factory=lambda: {"improve": 0.5, "explore": 0.5}
+    )
+
+    # PR8 — when True, rank_moves returns uniform taste scores (0.5) to
+    # bypass taste filtering during branch generation. Callers flip this
+    # for fresh / surprise-me mode so novelty survives to post-hoc ranking.
+    bypass_taste_in_generation: bool = False
 
     # Total evidence count (how many decisions informed this graph)
     evidence_count: int = 0
     last_updated_ms: int = 0
 
+    @property
+    def novelty_band(self) -> float:
+        """Legacy flat novelty band — mirrors novelty_bands["improve"].
+
+        Kept for back-compat with callers that set/read novelty_band
+        directly. Setting this property writes through to the bands dict
+        so there's no dual source of truth.
+        """
+        return self.novelty_bands.get("improve", 0.5)
+
+    @novelty_band.setter
+    def novelty_band(self, value: float) -> None:
+        self.novelty_bands["improve"] = float(value)
+
     def to_dict(self) -> dict:
         return {
             "dimension_weights": self.dimension_weights,
@@ -96,7 +120,11 @@ class TasteGraph:
                     key=lambda x: -x[1].affinity,
                 )[:10]  # Top 10 only
             },
+            # novelty_band kept for legacy consumers that read it directly;
+            # novelty_bands is the canonical per-goal-mode shape going forward.
             "novelty_band": round(self.novelty_band, 3),
+            "novelty_bands": {k: round(v, 3) for k, v in self.novelty_bands.items()},
+            "bypass_taste_in_generation": self.bypass_taste_in_generation,
             "evidence_count": self.evidence_count,
         }
 
@@ -154,21 +182,53 @@ class TasteGraph:
         self.evidence_count += 1
         self.last_updated_ms = now
 
-    def update_novelty_from_experiment(self, chose_bold: bool) -> None:
-        """Shift novelty band based on experiment choices."""
+    def update_novelty_from_experiment(
+        self, chose_bold: bool, goal_mode: str = "improve",
+    ) -> None:
+        """Shift novelty band for a given goal mode based on experiment choices.
+
+        PR8: goal_mode defaults to "improve" so legacy callers land on the
+        same band they updated before. Pass "explore" to shift the
+        exploration-mode band without touching improve-mode preference.
+        (novelty_band is a property view over novelty_bands["improve"], so
+        improve-mode updates automatically surface there too.)
+        """
+        current = self.novelty_bands.get(goal_mode, 0.5)
         if chose_bold:
-            self.novelty_band = min(1.0, self.novelty_band + 0.05)
+            new_val = min(1.0, current + 0.05)
         else:
-            self.novelty_band = max(0.0, self.novelty_band - 0.05)
+            new_val = max(0.0, current - 0.05)
+        self.novelty_bands[goal_mode] = new_val
 
     # ── Ranking ──────────────────────────────────────────────────────
 
-    def rank_moves(self, move_specs: list[dict]) -> list[dict]:
+    def rank_moves(
+        self,
+        move_specs: list[dict],
+        goal_mode: str = "improve",
+    ) -> list[dict]:
         """Rank a list of semantic move dicts by taste fit.
 
         Each move dict should have: move_id, family, targets, risk_level.
         Returns the same dicts with added 'taste_score' field, sorted desc.
+
+        PR8 additions:
+          goal_mode (str, default "improve"): which novelty band to use for
+            risk alignment. "improve" respects the user's conservative history;
+            "explore" uses the explore-mode band so past timid choices don't
+            punish surprise-me branch generation.
+          bypass_taste_in_generation (instance flag): when True, every move
+            scores a uniform 0.5. Used during branch generation so taste
+            doesn't prune novelty before the user has a chance to audition.
+            Ranking order is preserved from input when this flag is on.
         """
+        if self.bypass_taste_in_generation:
+            return [dict(move, taste_score=0.5) for move in move_specs]
+
+        # Read the band for the requested mode. Falls back to the improve
+        # band (via self.novelty_band property) when the mode is unknown.
+        novelty_band = self.novelty_bands.get(goal_mode, self.novelty_band)
+
         ranked = []
         for move in move_specs:
             taste_score = 0.5  # Neutral baseline
@@ -190,10 +250,10 @@ class TasteGraph:
                 if dim in self.dimension_avoidances:
                     taste_score -= 0.3
 
-            # Novelty/risk alignment
+            # Novelty/risk alignment (PR8: per-mode band)
             risk = move.get("risk_level", "low")
             risk_val = {"low": 0.2, "medium": 0.5, "high": 0.8}.get(risk, 0.5)
-            novelty_match = 1.0 - abs(risk_val - self.novelty_band)
+            novelty_match = 1.0 - abs(risk_val - novelty_band)
             taste_score += novelty_match * 0.1
 
             # Clamp
@@ -297,8 +357,21 @@ def build_taste_graph(
                 if total > 0:
                     fam.score = round((fam.kept_count - fam.undone_count) / total, 3)
 
-        # Novelty band
-        graph.novelty_band = persisted.get("novelty_band", 0.5)
+        # Novelty band — migrate from flat float if present, OR read
+        # per-mode dict if newer persistence format has it (PR8).
+        persisted_band = persisted.get("novelty_band", 0.5)
+        persisted_bands = persisted.get("novelty_bands")
+        if isinstance(persisted_bands, dict) and persisted_bands:
+            graph.novelty_bands = {
+                k: float(v) for k, v in persisted_bands.items() if isinstance(v, (int, float))
+            }
+            # Ensure both canonical keys are present with sensible defaults.
+            graph.novelty_bands.setdefault("improve", persisted_band)
+            graph.novelty_bands.setdefault("explore", persisted_band)
+            graph.novelty_band = graph.novelty_bands["improve"]
+        else:
+            graph.novelty_band = persisted_band
+            graph.novelty_bands = {"improve": persisted_band, "explore": persisted_band}
 
         # Device affinities
         for dev_name, dev_data in persisted.get("device_affinities", {}).items():

package/mcp_server/persistence/taste_store.py

@@ -48,15 +48,29 @@ class PersistentTasteStore:
             return data
         self._store.update(_update)
 
-    def update_novelty(self, chose_bold: bool) -> None:
-        """Update novelty band from experiment choice."""
+    def update_novelty(self, chose_bold: bool, goal_mode: str = "improve") -> None:
+        """Update novelty band from experiment choice for a given goal mode.
+
+        PR8: goal_mode defaults to "improve" so legacy callers land on the
+        same band they updated before. The per-mode dict ``novelty_bands``
+        is maintained alongside the flat ``novelty_band`` field; the flat
+        field mirrors the "improve" band.
+        """
         def _update(data: dict) -> dict:
             data = data if data.get("version") == 1 else self._default()
-            band = data.get("novelty_band", 0.5)
+            # Ensure the per-mode dict exists (migrating from legacy shape).
+            bands = data.get("novelty_bands")
+            if not isinstance(bands, dict) or not bands:
+                flat = data.get("novelty_band", 0.5)
+                bands = {"improve": flat, "explore": flat}
+            current = bands.get(goal_mode, 0.5)
             if chose_bold:
-                data["novelty_band"] = min(1.0, band + 0.05)
+                bands[goal_mode] = min(1.0, current + 0.05)
             else:
-                data["novelty_band"] = max(0.0, band - 0.05)
+                bands[goal_mode] = max(0.0, current - 0.05)
+            data["novelty_bands"] = bands
+            # Mirror the improve band onto the flat field for back-compat.
+            data["novelty_band"] = bands.get("improve", 0.5)
             data["evidence_count"] = data.get("evidence_count", 0) + 1
             return data
         self._store.update(_update)
@@ -114,6 +128,8 @@ class PersistentTasteStore:
             "version": 1,
             "move_outcomes": {},
             "novelty_band": 0.5,
+            # PR8 — per-goal-mode novelty bands; novelty_band mirrors "improve"
+            "novelty_bands": {"improve": 0.5, "explore": 0.5},
             "device_affinities": {},
             "anti_preferences": [],
             "dimension_weights": {},

package/mcp_server/runtime/session_kernel.py

@@ -45,6 +45,37 @@ class SessionKernel:
     recommended_engines: list = field(default_factory=list)
     recommended_workflow: str = ""
 
+    # ── Creative controls (PR2 — branch-native migration) ──────────────
+    # All optional. Producers (Wonder, synthesis_brain, composer) read these
+    # to bias branch generation. Pre-PR2 callers leave them at defaults and
+    # nothing changes. PR6 (Wonder refactor) and PR9 (synthesis_brain) start
+    # reading them in earnest.
+
+    # 0.0 = conservative / don't surprise me; 1.0 = surprise me.
+    # Distinct from aggression (which is about execution boldness).
+    freshness: float = 0.5
+
+    # Shorthand producer philosophy tag. The sample_engine already uses
+    # "surgeon" / "alchemist" (see livepilot-sample-engine); synth work
+    # may add "sculptor". Empty string = producer picks a default.
+    creativity_profile: str = ""
+
+    # Caller-asserted sacred elements. Normally sacred elements come from
+    # song_brain; this lets the user or a skill override. Shape matches
+    # song_brain.sacred_elements entries: {element_type, description, salience}.
+    sacred_elements: list = field(default_factory=list)
+
+    # Hints for synthesis_brain: which tracks/devices to focus on and what
+    # target timbre to aim for. Shape is open in PR2 and will be firmed up
+    # when PR9 adds the first adapters.
+    #   {
+    #     "track_indices": [int, ...],
+    #     "device_paths":  ["track/Wavetable", ...],
+    #     "target_timbre": {"brightness": +0.3, "width": +0.2, ...},
+    #     "preferred_devices": ["Wavetable", "Operator", ...],
+    #   }
+    synth_hints: dict = field(default_factory=dict)
+
     def to_dict(self) -> dict:
         return asdict(self)
 
@@ -60,12 +91,23 @@ def build_session_kernel(
     taste_graph: Optional[dict] = None,
     anti_preferences: Optional[list] = None,
     protected_dimensions: Optional[dict] = None,
+    # PR2 — creative controls. All optional; legacy callers unaffected.
+    freshness: float = 0.5,
+    creativity_profile: str = "",
+    sacred_elements: Optional[list] = None,
+    synth_hints: Optional[dict] = None,
 ) -> SessionKernel:
     """Build a SessionKernel from raw data.
 
     All optional fields degrade gracefully to empty defaults.
     The kernel_id is deterministic from the core inputs so it's stable
     within the same turn context.
+
+    The PR2 creative-control fields (freshness, creativity_profile,
+    sacred_elements, synth_hints) are intentionally excluded from the
+    kernel_id hash so existing callers see no identity changes. Producers
+    that need these fields to influence identity can compose their own
+    derived id downstream.
     """
     # Deterministic kernel_id from inputs
     id_seed = json.dumps(
@@ -93,4 +135,8 @@ def build_session_kernel(
         taste_graph=taste_graph or {},
         anti_preferences=anti_preferences or [],
         protected_dimensions=protected_dimensions or {},
+        freshness=freshness,
+        creativity_profile=creativity_profile,
+        sacred_elements=sacred_elements or [],
+        synth_hints=synth_hints or {},
     )