livepilot 1.10.9 → 1.13.0

package/mcp_server/composer/branch_producer.py

@@ -0,0 +1,229 @@
+"""Composer branch producer — emit section-hypothesis BranchSeeds.
+
+PR11 adds a branch-native entry point alongside the existing compose()
+pipeline. Instead of a single deterministic layer plan, callers can
+request N distinct compositional hypotheses and audition them via
+create_experiment(seeds=..., compiled_plans=...).
+
+Design:
+  A composer branch is a CompositionIntent + variant_strategy. Three
+  canned strategies are shipped in PR11:
+
+    "canonical"     — intent unchanged, layer plan uses genre defaults
+    "energy_shift"  — intent.energy inverted around 0.5 (dense ⇄ sparse)
+    "layer_contrast" — one role swapped in the layer plan (e.g. bass
+                       role replaced with pad-anchor, or percussion
+                       stripped to emphasize melodic content)
+
+Seeds carry source="composer". Each branch produces a pre-compiled
+plan through the existing ComposerEngine.compose() pipeline so
+run_experiment respects the plans without re-compiling. Later PRs
+can add more strategies (key-shift, section-reorder, tempo-halftime).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Optional
+
+from ..branches import BranchSeed, freeform_seed
+from .prompt_parser import parse_prompt, CompositionIntent
+from .layer_planner import plan_layers, plan_sections
+
+
+# Strategy registry — each function takes an intent and returns (modified
+# intent, distinctness_reason, novelty_label, risk_label).
+def _strategy_canonical(intent: CompositionIntent):
+    return (
+        intent,
+        "baseline composition with genre defaults",
+        "safe",
+        "low",
+    )
+
+
+def _strategy_energy_shift(intent: CompositionIntent):
+    new = CompositionIntent(
+        genre=intent.genre,
+        sub_genre=intent.sub_genre,
+        mood=intent.mood,
+        tempo=intent.tempo,
+        key=intent.key,
+        descriptors=list(intent.descriptors),
+        explicit_elements=list(intent.explicit_elements),
+        energy=round(1.0 - intent.energy, 2),
+        layer_count=intent.layer_count,
+        duration_bars=intent.duration_bars,
+    )
+    direction = "denser" if new.energy > intent.energy else "sparser"
+    return (
+        new,
+        f"energy shifted from {intent.energy:.1f} → {new.energy:.1f} ({direction})",
+        "strong",
+        "low",
+    )
+
+
+def _strategy_layer_contrast(intent: CompositionIntent):
+    new = CompositionIntent(
+        genre=intent.genre,
+        sub_genre=intent.sub_genre,
+        mood=intent.mood,
+        tempo=intent.tempo,
+        key=intent.key,
+        descriptors=list(intent.descriptors),
+        # Force the layer planner to drop "bass" as an anchor role by adding
+        # "pad" explicitly to explicit_elements and not asking for a bass.
+        explicit_elements=list(intent.explicit_elements) + ["pad_anchor", "no_bass"],
+        energy=intent.energy,
+        layer_count=intent.layer_count,
+        duration_bars=intent.duration_bars,
+    )
+    return (
+        new,
+        "layer contrast — pad anchor instead of bass line",
+        "unexpected",
+        "medium",
+    )
+
+
+_STRATEGIES = [
+    ("canonical", _strategy_canonical),
+    ("energy_shift", _strategy_energy_shift),
+    ("layer_contrast", _strategy_layer_contrast),
+]
+
+
+def _short_id(prefix: str, key: str) -> str:
+    h = hashlib.sha256(f"{prefix}:{key}".encode()).hexdigest()[:10]
+    return f"{prefix}_{h}"
+
+
+def propose_composer_branches(
+    request_text: str,
+    kernel: Optional[dict] = None,
+    count: int = 2,
+    search_roots: Optional[list] = None,
+) -> list[tuple[BranchSeed, dict]]:
+    """Emit composer-source branch seeds with pre-compiled plans.
+
+    request_text: the natural-language composition prompt.
+    kernel: optional SessionKernel dict — reads ``freshness`` to gate
+      whether high-novelty strategies (layer_contrast) are included.
+    count: desired number of branches (clamped to 1..len(_STRATEGIES)).
+    search_roots: optional list of directory paths for sample resolution,
+      threaded to ComposerEngine.compose().
+
+    Returns a list of (BranchSeed, compiled_plan_dict) tuples. Each plan
+    is a dict with {"steps": [...], "step_count": N, "summary": "..."}
+    compatible with run_experiment.
+    """
+    kernel = kernel or {}
+    freshness = float(kernel.get("freshness", 0.5) or 0.5)
+
+    intent = parse_prompt(request_text)
+
+    # Gate high-novelty strategies on freshness.
+    if freshness < 0.4:
+        strategies = [_STRATEGIES[0]]  # canonical only
+    elif freshness < 0.7:
+        strategies = _STRATEGIES[:2]   # canonical + energy_shift
+    else:
+        strategies = _STRATEGIES       # all three
+
+    count = max(1, min(count, len(strategies)))
+    results: list[tuple[BranchSeed, dict]] = []
+
+    for name, strategy_fn in strategies[:count]:
+        try:
+            variant_intent, reason, novelty, risk = strategy_fn(intent)
+            plan = _build_section_hypothesis_plan(variant_intent, name)
+
+            seed = freeform_seed(
+                seed_id=_short_id(f"cmp_{name}", request_text),
+                hypothesis=f"Composer branch ({name}): {reason}",
+                source="composer",
+                novelty_label=novelty,
+                risk_label=risk,
+                distinctness_reason=reason,
+            )
+            results.append((seed, plan))
+        except Exception as exc:
+            # Don't let one strategy's failure kill the rest.
+            import logging
+            logging.getLogger(__name__).warning(
+                "composer strategy %s failed: %s", name, exc
+            )
+            continue
+
+    return results
+
+
+def _build_section_hypothesis_plan(intent: CompositionIntent, strategy_name: str) -> dict:
+    """Build a lightweight, executable plan from an intent.
+
+    Uses the synchronous planning primitives (plan_layers, plan_sections)
+    to generate a scaffolding plan: set_tempo + create_midi_track per layer
+    with sensible names and colors. Sample resolution is deferred —
+    callers that want samples loaded should either hand the branch to
+    commit_experiment after auditioning, or re-run ComposerEngine.compose()
+    on the winning intent.
+
+    Returns a dict with {"steps", "step_count", "summary"}.
+    """
+    layers = plan_layers(intent)
+    sections = plan_sections(intent)
+
+    steps: list[dict] = []
+
+    # Step 1: tempo — only when intent.tempo is set. Remote transport
+    # handler takes "tempo" (not "bpm") — see transport.py:set_tempo.
+    if intent.tempo and intent.tempo > 0:
+        steps.append({
+            "tool": "set_tempo",
+            "params": {"tempo": float(intent.tempo)},
+        })
+
+    # Step 2: one create_midi_track per layer role — the skeleton every
+    # subsequent composition step builds on.
+    for idx, layer in enumerate(layers):
+        name = getattr(layer, "role", f"layer_{idx}")
+        steps.append({
+            "tool": "create_midi_track",
+            "params": {"name": str(name)},
+        })
+
+    # Step 3: one create_scene + set_scene_name per section. Remote
+    # create_scene handler only accepts "index" — see scenes.py:create_scene.
+    # Section labels land via set_scene_name after creation. step_id +
+    # $from_step binding resolves the new scene index so parallel branches
+    # with different section counts don't step on each other.
+    for s_idx, section in enumerate(sections):
+        if isinstance(section, dict):
+            sec_name = section.get("name", f"Section {s_idx + 1}")
+        else:
+            sec_name = f"Section {s_idx + 1}"
+        create_step_id = f"create_scene_{s_idx}"
+        steps.append({
+            "tool": "create_scene",
+            "step_id": create_step_id,
+            "params": {"index": -1},  # -1 ⇒ append at end
+        })
+        steps.append({
+            "tool": "set_scene_name",
+            "params": {
+                "scene_index": {"$from_step": create_step_id, "path": "index"},
+                "name": str(sec_name),
+            },
+        })
+
+    summary = (
+        f"{strategy_name}: {intent.genre or 'auto-genre'} @ "
+        f"{intent.tempo or 'auto-tempo'} bpm, energy {intent.energy:.1f} — "
+        f"{len(layers)} layers, {len(sections)} sections"
+    )
+    return {
+        "steps": steps,
+        "step_count": len(steps),
+        "summary": summary,
+    }

package/mcp_server/evaluation/policy.py

@@ -4,10 +4,24 @@ Consistent keep/undo semantics shared across sonic, composition,
 and all future evaluators.
 
 Design: EVALUATION_FABRIC_V1.md, section 8
+
+PR7 adds ``classify_branch_outcome`` — a branch-lifecycle classifier that
+maps a score (and optional hard-rule inputs) to one of three statuses:
+"keep", "undo", "interesting_but_failed". The third status exists for
+exploration mode: a branch that failed technical gates but surfaced a
+novel idea is kept for audit and never re-applied. Protection violations
+still force undo regardless of exploration mode — that's a safety
+invariant, not a taste judgment.
 """
 
 from __future__ import annotations
 
+from dataclasses import asdict, dataclass, field
+from typing import Literal, Optional
+
+
+BranchOutcomeStatus = Literal["keep", "undo", "interesting_but_failed"]
+
 
 def apply_hard_rules(
     goal_progress: float,
@@ -16,11 +30,17 @@ def apply_hard_rules(
     measurable_count: int,
     score: float,
     target_count: int,
+    defer_on_unmeasurable: bool = True,
 ) -> tuple[bool, list[str]]:
     """Enforce hard rules and return (keep_change, failure_reasons).
 
     Rules (evaluated in order):
-    1. All targets unmeasurable + no protection violation -> defer to agent
+    1. (optional) All targets unmeasurable + no protection violation
+       -> defer to agent. Fires only when defer_on_unmeasurable=True
+       (the default). The evaluation fabric relies on this to mark
+       decision_mode="deferred". Score-producing evaluators (branch
+       lifecycle, PR7) pass defer_on_unmeasurable=False because the
+       score IS the judgment — no deferral needed.
     2. Protection violated -> force undo
     3. Measurable delta <= 0 when measurable targets exist -> force undo
     4. Score < 0.40 -> force undo
@@ -32,6 +52,10 @@ def apply_hard_rules(
         measurable_count: how many target dimensions were measurable
         score: composite quality score (0-1)
         target_count: total number of target dimensions
+        defer_on_unmeasurable: when True (default), rule 1 returns
+            (True, [defer message]) as soon as no measurable targets
+            exist. When False, rule 1 is skipped and rules 2-4 run
+            unconditionally.
 
     Returns:
         (keep_change, list_of_rule_failure_reasons)
@@ -39,7 +63,11 @@ def apply_hard_rules(
     failures: list[str] = []
 
     # Rule 1: all unmeasurable + no protection violation -> defer
-    if measurable_count == 0 and not protection_violated:
+    if (
+        defer_on_unmeasurable
+        and measurable_count == 0
+        and not protection_violated
+    ):
         return True, [
             "No measurable target dimensions — deferring keep/undo "
             "to agent musical judgment"
@@ -65,3 +93,102 @@ def apply_hard_rules(
 
     keep_change = len(failures) == 0
     return keep_change, failures
+
+
+# ── PR7 — branch-lifecycle classifier ────────────────────────────────────
+
+
+@dataclass
+class BranchOutcome:
+    """Unified branch evaluation result.
+
+    Fields:
+      status: terminal classification — "keep" | "undo" | "interesting_but_failed"
+      keep_change: True ⇒ status == "keep"; never True for the other statuses.
+      score: the composite score that informed the decision.
+      failure_reasons: human-readable list of failed hard rules (empty on keep).
+      note: optional explanation aimed at the user.
+    """
+
+    status: BranchOutcomeStatus
+    keep_change: bool
+    score: float
+    failure_reasons: list[str] = field(default_factory=list)
+    note: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def classify_branch_outcome(
+    score: float,
+    *,
+    protection_violated: bool = False,
+    measurable_count: int = 0,
+    target_count: int = 0,
+    goal_progress: float = 0.0,
+    exploration_rules: bool = False,
+) -> BranchOutcome:
+    """Classify a branch's terminal status from a score + optional hard-rule inputs.
+
+    Delegates to apply_hard_rules with ``defer_on_unmeasurable=False`` — a
+    score-producing evaluator DID make a judgment, so rule 1's deferral
+    path is not appropriate here. The score alone is enough to push a
+    branch toward undo / interesting_but_failed.
+
+    Post-processing:
+      - ``exploration_rules=False`` (technical safety, default):
+        any hard-rule failure ⇒ status="undo".
+      - ``exploration_rules=True`` (creative exploration):
+        protection violations still force undo (safety invariant);
+        all other failures downgrade to "interesting_but_failed".
+
+    Returns a BranchOutcome that callers can plug into branch.score /
+    .status / .evaluation without further interpretation.
+    """
+    keep_change, failures = apply_hard_rules(
+        goal_progress=goal_progress,
+        collateral_damage=0.0,  # not threaded here — branch lifecycle doesn't compute it yet
+        protection_violated=protection_violated,
+        measurable_count=measurable_count,
+        score=score,
+        target_count=target_count,
+        defer_on_unmeasurable=False,
+    )
+
+    if keep_change:
+        return BranchOutcome(
+            status="keep",
+            keep_change=True,
+            score=score,
+            failure_reasons=[],
+            note="",
+        )
+
+    # Failed — decide between undo and interesting_but_failed.
+    protection_failure = any("protected dimension" in f for f in failures)
+
+    if exploration_rules and not protection_failure:
+        return BranchOutcome(
+            status="interesting_but_failed",
+            keep_change=False,
+            score=score,
+            failure_reasons=failures,
+            note=(
+                "Exploration rule: branch failed technical gates but is "
+                "retained for audit. Not re-applied."
+            ),
+        )
+
+    return BranchOutcome(
+        status="undo",
+        keep_change=False,
+        score=score,
+        failure_reasons=failures,
+        note=(
+            "Protection violation — branch rolled back regardless of "
+            "exploration mode."
+            if protection_failure
+            else "Branch rolled back per hard rules."
+        ),
+    )

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,6 +18,8 @@ import time
 from dataclasses import dataclass, field
 from typing import Any, Optional
 
+from ..branches import BranchSeed
+
 
 @dataclass
 class BranchSnapshot:
@@ -37,14 +46,26 @@ class BranchSnapshot:
 
 @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 +86,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 +146,12 @@ 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
+            )
         return d