livepilot 1.12.2 → 1.14.0

package/mcp_server/composer/branch_producer.py

@@ -0,0 +1,349 @@
+"""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
+from .engine import ComposerEngine, CompositionResult
+
+
+# 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,
+                # PR3 — carry the variant intent + strategy so commit_experiment
+                # can rehydrate and run the full ComposerEngine.compose()
+                # pipeline on the winner instead of committing the scaffold.
+                producer_payload={
+                    "strategy": name,
+                    "intent": variant_intent.to_dict(),
+                    "request_text": request_text,
+                    "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
+
+
+async def escalate_composer_branch(
+    producer_payload: dict,
+    search_roots: Optional[list] = None,
+    splice_client: object = None,
+    browser_client: object = None,
+    max_credits: int = 10,
+) -> dict:
+    """Run the full ComposerEngine.compose() pipeline on a committed
+    composer branch, using the CompositionIntent captured in the seed's
+    producer_payload at emit time.
+
+    Returns a dict with:
+      ok: bool
+      plan: list of executable steps (the full resolved plan, not the
+            scaffolding the branch was auditioned with)
+      step_count: int
+      layer_count: int
+      resolved_samples: dict (role → local_path)
+      warnings: list (unresolved layers, missing samples, etc.)
+      error: str (when ok=False)
+
+    When ok=False, callers should fall back to committing the scaffold
+    plan instead of dropping the branch — the scaffolding is still
+    useful as a track/scene skeleton the user can populate manually.
+
+    This function is async because ComposerEngine.compose() is async
+    (it awaits Splice / filesystem sample resolution).
+    """
+    import logging
+    logger = logging.getLogger(__name__)
+
+    schema_version = producer_payload.get("schema_version") if producer_payload else None
+    intent_dict = (producer_payload or {}).get("intent")
+
+    if not intent_dict:
+        return {
+            "ok": False,
+            "error": (
+                "Composer branch producer_payload missing 'intent'. "
+                "This branch was likely emitted before PR3/v2 and cannot "
+                "be escalated — commit the scaffold plan instead."
+            ),
+        }
+
+    # Rehydrate CompositionIntent from the payload dict. Tolerate unknown
+    # keys by only pulling the fields CompositionIntent understands — older
+    # schemas may have fewer fields, newer may have more.
+    try:
+        intent_fields = {
+            k: v for k, v in intent_dict.items()
+            if k in (
+                "genre", "sub_genre", "mood", "tempo", "key",
+                "descriptors", "explicit_elements", "energy",
+                "layer_count", "duration_bars",
+            )
+        }
+        intent = CompositionIntent(**intent_fields)
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": (
+                f"Failed to rehydrate CompositionIntent from producer_payload "
+                f"(schema_version={schema_version}): {exc}"
+            ),
+        }
+
+    engine = ComposerEngine()
+    try:
+        result: CompositionResult = await engine.compose(
+            intent=intent,
+            dry_run=False,
+            max_credits=max_credits,
+            search_roots=search_roots or [],
+            splice_client=splice_client,
+            browser_client=browser_client,
+        )
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": f"ComposerEngine.compose() raised: {exc}",
+        }
+
+    # Fallback when no layers resolved — explicit signal so callers can
+    # fall back to the scaffold instead of silently shipping an empty
+    # plan.
+    if not result.plan or len(result.layers) == 0:
+        return {
+            "ok": False,
+            "error": (
+                "ComposerEngine.compose() produced zero executable layers. "
+                "Sample resolution likely failed — check Splice credits, "
+                "filesystem roots, or browser connectivity. Falling back "
+                "to scaffold commit is the correct action."
+            ),
+            "warnings": list(result.warnings),
+            "resolved_samples": dict(result.resolved_samples),
+        }
+
+    return {
+        "ok": True,
+        "plan": list(result.plan),
+        "step_count": len(result.plan),
+        "layer_count": len(result.layers),
+        "resolved_samples": dict(result.resolved_samples),
+        "credits_estimated": result.credits_estimated,
+        "warnings": list(result.warnings),
+        "intent_used": intent.to_dict(),
+    }
+
+
+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/composer/tools.py

@@ -1,8 +1,10 @@
-"""Composer Engine MCP tools — 3 tools for auto-composition.
+"""Composer Engine MCP tools — 4 tools for auto-composition.
 
 compose: full multi-layer composition from text prompt
 augment_with_samples: add layers to existing session
 get_composition_plan: dry run preview
+propose_composer_branches (PR5/v2): multi-strategy branch hypotheses for
+    exploratory workflows (feeds create_experiment(seeds=...))
 """
 
 from __future__ import annotations
@@ -213,3 +215,58 @@ async def get_composition_plan(
         "then step through each tool call in sequence."
     )
     return plan
+
+
+@mcp.tool()
+def propose_composer_branches(
+    ctx: Context,
+    request_text: str,
+    count: int = 2,
+    freshness: float = 0.65,
+) -> dict:
+    """Emit N distinct compositional hypotheses for a single prompt (PR5/v2).
+
+    Branch-native companion to compose(): instead of one deterministic
+    layer plan, produces up to ``count`` BranchSeeds with different
+    strategic angles the user can audition via create_experiment +
+    run_experiment. Each seed carries a pre-compiled scaffolding plan
+    (set_tempo + create_midi_track per layer + create_scene per section)
+    that gets escalated to a fully resolved plan by commit_experiment
+    when the winning branch is chosen.
+
+    Strategies (gated on freshness):
+      canonical      — intent unchanged, genre defaults
+                       (shipped at every freshness level)
+      energy_shift   — intent.energy inverted around 0.5
+                       (freshness >= 0.4)
+      layer_contrast — one role swapped (pad-anchor instead of bass)
+                       (freshness >= 0.7)
+
+    Returns:
+      {
+        "request_text": str,
+        "branch_count": int,
+        "seeds": [BranchSeed.to_dict(), ...],
+        "compiled_plans": [plan_dict, ...]   (parallel to seeds; scaffold),
+      }
+
+    Each seed's producer_payload carries {strategy, intent,
+    request_text, reason} so commit_experiment can rehydrate the
+    CompositionIntent and run the full ComposerEngine.compose() for
+    the winner.
+    """
+    from .branch_producer import propose_composer_branches as _propose
+
+    pairs = _propose(
+        request_text=request_text,
+        kernel={"freshness": float(freshness)},
+        count=int(count),
+    )
+    seeds = [s.to_dict() for s, _ in pairs]
+    plans = [p for _, p in pairs]
+    return {
+        "request_text": request_text,
+        "branch_count": len(seeds),
+        "seeds": seeds,
+        "compiled_plans": plans,
+    }

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,200 @@ 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 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,
+    *,
+    protection_violated: bool = False,
+    measurable_count: int = 0,
+    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.
+
+    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".
+
+    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
+        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."
+        ),
+    )