livepilot 1.9.13 → 1.9.15

package/mcp_server/performance_engine/planner.py

@@ -0,0 +1,267 @@
+"""Performance Engine planner — scene transitions and energy steering.
+
+Pure computation — builds HandoffPlans and suggests energy-aware moves.
+
+Zero I/O.
+"""
+
+from __future__ import annotations
+
+from .models import (
+    EnergyWindow,
+    HandoffPlan,
+    LiveSafeMove,
+    PerformanceState,
+    SceneRole,
+)
+from .safety import get_blocked_moves, get_safe_moves
+
+
+# ── Scene transition planning ─────────────────────────────────────────
+
+
+def plan_scene_transition(
+    from_scene: SceneRole,
+    to_scene: SceneRole,
+) -> HandoffPlan:
+    """Plan a transition from one scene to another.
+
+    Generates an energy path (linear interpolation) and
+    appropriate transition gestures based on the energy delta
+    and role pairing.
+    """
+    energy_delta = to_scene.energy_level - from_scene.energy_level
+    abs_delta = abs(energy_delta)
+
+    # Determine number of steps based on energy distance
+    if abs_delta < 0.2:
+        steps = 2
+    elif abs_delta < 0.5:
+        steps = 4
+    else:
+        steps = 6
+
+    # Build linear energy path
+    energy_path: list[float] = []
+    for i in range(steps + 1):
+        t = i / steps
+        energy = from_scene.energy_level + t * energy_delta
+        energy_path.append(round(energy, 3))
+
+    # Build gesture sequence
+    gestures: list[dict] = []
+
+    # Pre-transition: prepare
+    gestures.append({
+        "type": "prepare",
+        "step": 0,
+        "description": f"Prepare transition from '{from_scene.name}' to '{to_scene.name}'",
+    })
+
+    # Energy-based transition gestures
+    if energy_delta > 0.3:
+        # Building energy — use additive layering
+        gestures.append({
+            "type": "filter_sweep",
+            "step": 1,
+            "description": "Open filter to build energy",
+            "parameters": {"direction": "up"},
+        })
+        gestures.append({
+            "type": "send_nudge",
+            "step": 2,
+            "description": "Increase send levels for spatial build",
+            "parameters": {"delta": 0.1},
+        })
+    elif energy_delta < -0.3:
+        # Dropping energy — use subtractive approach
+        gestures.append({
+            "type": "filter_sweep",
+            "step": 1,
+            "description": "Close filter to reduce energy",
+            "parameters": {"direction": "down"},
+        })
+        gestures.append({
+            "type": "mute_toggle",
+            "step": 2,
+            "description": "Strip layers to reduce density",
+            "parameters": {},
+        })
+    else:
+        # Similar energy — smooth crossfade
+        gestures.append({
+            "type": "volume_nudge",
+            "step": 1,
+            "description": "Smooth crossfade between scenes",
+            "parameters": {"delta_db": 0.0},
+        })
+
+    # Scene launch at the midpoint
+    gestures.append({
+        "type": "scene_launch",
+        "step": steps // 2,
+        "description": f"Launch scene {to_scene.scene_index} ('{to_scene.name}')",
+        "parameters": {"scene_index": to_scene.scene_index},
+    })
+
+    # Post-transition: settle
+    gestures.append({
+        "type": "settle",
+        "step": steps,
+        "description": f"Settle into '{to_scene.name}' ({to_scene.role})",
+    })
+
+    return HandoffPlan(
+        from_scene=from_scene.scene_index,
+        to_scene=to_scene.scene_index,
+        gestures=gestures,
+        energy_path=energy_path,
+    )
+
+
+# ── Energy-aware move suggestions ─────────────────────────────────────
+
+
+def suggest_energy_moves(
+    energy_window: EnergyWindow,
+    scene: SceneRole,
+) -> list[LiveSafeMove]:
+    """Suggest moves to steer energy toward the target.
+
+    Considers the current scene's role to tailor suggestions.
+    """
+    moves: list[LiveSafeMove] = []
+    gap = energy_window.target_energy - energy_window.current_energy
+
+    if abs(gap) < 0.05:
+        # Close enough — hold steady
+        moves.append(LiveSafeMove(
+            move_type="macro_nudge",
+            target="performance_macro",
+            description="Maintain current energy — micro-adjust macro for variation",
+            risk_level="safe",
+            parameters={"delta": 0.01},
+            reversible=True,
+        ))
+        return moves
+
+    if gap > 0:
+        # Need more energy
+        moves.append(LiveSafeMove(
+            move_type="volume_nudge",
+            target="master",
+            description=f"Lift volume toward target energy ({energy_window.target_energy:.1f})",
+            risk_level="safe",
+            parameters={"delta_db": min(2.0, gap * 6.0)},
+            reversible=True,
+        ))
+        if scene.role in ("build", "chorus", "drop"):
+            moves.append(LiveSafeMove(
+                move_type="send_nudge",
+                target="delay_send",
+                description="Add delay send for rhythmic energy boost",
+                risk_level="safe",
+                parameters={"delta": min(0.15, gap * 0.3)},
+                reversible=True,
+            ))
+        moves.append(LiveSafeMove(
+            move_type="filter_sweep",
+            target="master_filter",
+            description="Open high-pass for brightness lift",
+            risk_level="safe",
+            parameters={"direction": "up", "range": [2000, 16000]},
+            reversible=True,
+        ))
+    else:
+        # Need less energy
+        moves.append(LiveSafeMove(
+            move_type="filter_sweep",
+            target="master_filter",
+            description=f"Low-pass sweep toward target energy ({energy_window.target_energy:.1f})",
+            risk_level="safe",
+            parameters={"direction": "down", "range": [200, 8000]},
+            reversible=True,
+        ))
+        if scene.role in ("breakdown", "outro", "intro"):
+            moves.append(LiveSafeMove(
+                move_type="mute_toggle",
+                target="percussion_layer",
+                description="Mute percussion to soften breakdown",
+                risk_level="safe",
+                parameters={},
+                reversible=True,
+            ))
+        moves.append(LiveSafeMove(
+            move_type="volume_nudge",
+            target="master",
+            description="Reduce volume toward target energy",
+            risk_level="safe",
+            parameters={"delta_db": max(-2.0, gap * 6.0)},
+            reversible=True,
+        ))
+
+    return moves
+
+
+# ── Build full performance state ──────────────────────────────────────
+
+
+def build_performance_state(
+    scenes: list[SceneRole],
+    current_scene_index: int,
+) -> PerformanceState:
+    """Build a complete PerformanceState from scene roles.
+
+    Computes energy window from current scene context and
+    populates safe/blocked move lists.
+    """
+    # Find current scene
+    current = None
+    for s in scenes:
+        if s.scene_index == current_scene_index:
+            current = s
+            break
+
+    if current is None:
+        # Fallback: use defaults
+        current_energy = 0.5
+        target_energy = 0.5
+        direction = "hold"
+    else:
+        current_energy = current.energy_level
+
+        # Infer target from adjacent scenes
+        next_scenes = [s for s in scenes if s.scene_index > current_scene_index]
+        if next_scenes:
+            next_scene = min(next_scenes, key=lambda s: s.scene_index)
+            target_energy = next_scene.energy_level
+        else:
+            target_energy = current_energy
+
+        delta = target_energy - current_energy
+        if delta > 0.05:
+            direction = "up"
+        elif delta < -0.05:
+            direction = "down"
+        else:
+            direction = "hold"
+
+    urgency = min(1.0, abs(target_energy - current_energy) * 2.0)
+
+    energy_window = EnergyWindow(
+        current_energy=current_energy,
+        target_energy=target_energy,
+        direction=direction,
+        urgency=round(urgency, 3),
+    )
+
+    safe_moves = get_safe_moves(scenes, current_scene_index, energy_window)
+    blocked = get_blocked_moves()
+
+    return PerformanceState(
+        scenes=scenes,
+        current_scene=current_scene_index,
+        energy_window=energy_window,
+        safe_moves=safe_moves,
+        blocked_moves=blocked,
+    )

package/mcp_server/performance_engine/safety.py

@@ -0,0 +1,162 @@
+"""Performance Engine safety — move classification and policy.
+
+Defines which move types are safe during live performance,
+which require caution, and which are blocked entirely.
+
+Zero I/O.
+"""
+
+from __future__ import annotations
+
+from .models import EnergyWindow, LiveSafeMove, SceneRole
+
+
+# ── Move classification sets ──────────────────────────────────────────
+
+SAFE_MOVE_TYPES: frozenset = frozenset({
+    "scene_launch",
+    "send_nudge",
+    "macro_nudge",
+    "filter_sweep",
+    "mute_toggle",
+    "volume_nudge",
+})
+
+CAUTION_MOVE_TYPES: frozenset = frozenset({
+    "tempo_nudge",
+    "device_toggle",
+    "pan_nudge",
+})
+
+BLOCKED_MOVE_TYPES: frozenset = frozenset({
+    "device_chain_surgery",
+    "arrangement_edit",
+    "track_create_delete",
+    "note_edit",
+    "clip_create_delete",
+})
+
+
+# ── Classification ────────────────────────────────────────────────────
+
+
+def classify_move_safety(move_type: str) -> str:
+    """Classify a move type as 'safe', 'caution', or 'blocked'.
+
+    Returns:
+        'safe' if the move is in SAFE_MOVE_TYPES,
+        'blocked' if in BLOCKED_MOVE_TYPES,
+        'caution' otherwise (unknown or caution-class moves).
+    """
+    if move_type in SAFE_MOVE_TYPES:
+        return "safe"
+    if move_type in BLOCKED_MOVE_TYPES:
+        return "blocked"
+    return "caution"
+
+
+# ── Safe move suggestions ─────────────────────────────────────────────
+
+
+def get_safe_moves(
+    scene_roles: list[SceneRole],
+    current_scene: int,
+    energy_window: EnergyWindow,
+) -> list[LiveSafeMove]:
+    """Suggest safe moves based on current scene and energy state.
+
+    Returns a list of LiveSafeMove instances — only safe-class moves.
+    """
+    moves: list[LiveSafeMove] = []
+
+    # Scene launch suggestions: suggest adjacent scenes
+    for scene in scene_roles:
+        if scene.scene_index == current_scene:
+            continue
+        energy_delta = scene.energy_level - energy_window.current_energy
+        # Suggest scenes that move toward the target energy
+        if energy_window.direction == "up" and energy_delta > 0:
+            moves.append(LiveSafeMove(
+                move_type="scene_launch",
+                target=f"scene_{scene.scene_index}",
+                description=f"Launch '{scene.name}' (energy {scene.energy_level:.1f}, role: {scene.role})",
+                risk_level="safe",
+                parameters={"scene_index": scene.scene_index},
+                reversible=True,
+            ))
+        elif energy_window.direction == "down" and energy_delta < 0:
+            moves.append(LiveSafeMove(
+                move_type="scene_launch",
+                target=f"scene_{scene.scene_index}",
+                description=f"Launch '{scene.name}' (energy {scene.energy_level:.1f}, role: {scene.role})",
+                risk_level="safe",
+                parameters={"scene_index": scene.scene_index},
+                reversible=True,
+            ))
+        elif energy_window.direction == "hold":
+            # Suggest scenes with similar energy
+            if abs(energy_delta) < 0.2:
+                moves.append(LiveSafeMove(
+                    move_type="scene_launch",
+                    target=f"scene_{scene.scene_index}",
+                    description=f"Launch '{scene.name}' (similar energy {scene.energy_level:.1f})",
+                    risk_level="safe",
+                    parameters={"scene_index": scene.scene_index},
+                    reversible=True,
+                ))
+
+    # Energy-based nudge suggestions
+    if energy_window.direction == "up":
+        moves.append(LiveSafeMove(
+            move_type="volume_nudge",
+            target="master",
+            description="Nudge master volume up for energy lift",
+            risk_level="safe",
+            parameters={"delta_db": 1.0},
+            reversible=True,
+        ))
+        moves.append(LiveSafeMove(
+            move_type="send_nudge",
+            target="reverb_send",
+            description="Increase reverb send for spatial expansion",
+            risk_level="safe",
+            parameters={"delta": 0.05},
+            reversible=True,
+        ))
+    elif energy_window.direction == "down":
+        moves.append(LiveSafeMove(
+            move_type="filter_sweep",
+            target="master",
+            description="Low-pass filter sweep to reduce energy",
+            risk_level="safe",
+            parameters={"direction": "down", "range": [200, 8000]},
+            reversible=True,
+        ))
+        moves.append(LiveSafeMove(
+            move_type="mute_toggle",
+            target="high_energy_track",
+            description="Mute a high-energy layer to reduce intensity",
+            risk_level="safe",
+            parameters={},
+            reversible=True,
+        ))
+
+    # Always offer macro nudge as a safe option
+    moves.append(LiveSafeMove(
+        move_type="macro_nudge",
+        target="performance_macro",
+        description="Adjust performance macro for subtle variation",
+        risk_level="safe",
+        parameters={"delta": 0.02},
+        reversible=True,
+    ))
+
+    return moves
+
+
+# ── Blocked move list ─────────────────────────────────────────────────
+
+
+def get_blocked_moves() -> list[str]:
+    """Return all blocked move types as a sorted list."""
+    return sorted(BLOCKED_MOVE_TYPES)

package/mcp_server/performance_engine/tools.py

@@ -0,0 +1,183 @@
+"""Performance Engine MCP tools — 3 tools for live performance mode.
+
+Each tool fetches scene data from Ableton via the shared connection,
+then delegates to pure-computation modules.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import Context
+
+from ..server import mcp
+from .models import EnergyWindow, SceneRole
+from .planner import build_performance_state, plan_scene_transition, suggest_energy_moves
+from .safety import classify_move_safety, get_blocked_moves, get_safe_moves
+
+
+# ── Helpers ─────────────────────────────────────────────────────────
+
+
+def _infer_role(name: str, index: int, scene_count: int) -> str:
+    """Infer a scene's role from its name or position."""
+    lower = name.lower()
+    for role in ("intro", "verse", "chorus", "build", "drop", "breakdown", "outro", "transition"):
+        if role in lower:
+            return role
+    # Positional fallback
+    if index == 0:
+        return "intro"
+    if index == scene_count - 1:
+        return "outro"
+    if scene_count > 4:
+        quarter = scene_count / 4
+        if index < quarter:
+            return "intro"
+        elif index < quarter * 2:
+            return "verse"
+        elif index < quarter * 3:
+            return "chorus"
+        else:
+            return "outro"
+    return "verse"
+
+
+def _infer_energy(role: str) -> float:
+    """Infer energy level from scene role."""
+    energy_map = {
+        "intro": 0.2,
+        "verse": 0.4,
+        "build": 0.6,
+        "chorus": 0.7,
+        "drop": 0.9,
+        "breakdown": 0.3,
+        "transition": 0.5,
+        "outro": 0.2,
+    }
+    return energy_map.get(role, 0.5)
+
+
+def _fetch_scene_data(ctx: Context) -> tuple[list[SceneRole], int]:
+    """Fetch scene info from Ableton and build SceneRole list."""
+    ableton = ctx.lifespan_context["ableton"]
+
+    scenes_info = ableton.send_command("get_scenes_info", {})
+    scenes_list = scenes_info.get("scenes", [])
+    scene_count = len(scenes_list)
+
+    scene_roles: list[SceneRole] = []
+    for i, scene_data in enumerate(scenes_list):
+        name = scene_data.get("name", f"Scene {i}")
+        role = _infer_role(name, i, scene_count)
+        energy = _infer_energy(role)
+        scene_roles.append(SceneRole(
+            scene_index=i,
+            name=name,
+            energy_level=energy,
+            role=role,
+        ))
+
+    # Determine current scene — default to 0 since session_info
+    # doesn't expose a selected_scene field
+    current_scene = 0
+    try:
+        session_info = ableton.send_command("get_session_info", {})
+        # Check if any scene is marked as triggered/playing
+        session_scenes = session_info.get("scenes", [])
+        for i, s in enumerate(session_scenes):
+            if s.get("is_triggered", False):
+                current_scene = i
+                break
+    except Exception:
+        pass
+
+    return scene_roles, current_scene
+
+
+# ── MCP Tools ───────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_performance_state(ctx: Context) -> dict:
+    """Get current live performance overview — scenes, energy, safe moves.
+
+    Returns scene roles with energy levels, current energy window
+    with steering direction, available safe moves, and blocked move types.
+    Use this to understand the performance context before making changes.
+    """
+    scene_roles, current_scene = _fetch_scene_data(ctx)
+    state = build_performance_state(scene_roles, current_scene)
+    return state.to_dict()
+
+
+@mcp.tool()
+def get_performance_safe_moves(ctx: Context) -> dict:
+    """Get available safe moves for live performance.
+
+    Returns only performance-safe moves based on current scene
+    and energy direction. All moves are reversible and low-risk.
+    Also returns the full blocked move list for transparency.
+    """
+    scene_roles, current_scene = _fetch_scene_data(ctx)
+    state = build_performance_state(scene_roles, current_scene)
+
+    # Also get energy-specific suggestions
+    current = None
+    for s in scene_roles:
+        if s.scene_index == current_scene:
+            current = s
+            break
+
+    energy_moves: list[dict] = []
+    if current is not None:
+        em = suggest_energy_moves(state.energy_window, current)
+        energy_moves = [m.to_dict() for m in em]
+
+    return {
+        "safe_moves": [m.to_dict() for m in state.safe_moves],
+        "energy_moves": energy_moves,
+        "blocked_moves": state.blocked_moves,
+        "safe_move_count": len(state.safe_moves),
+        "energy_move_count": len(energy_moves),
+    }
+
+
+@mcp.tool()
+def plan_scene_handoff(
+    ctx: Context,
+    from_scene: int,
+    to_scene: int,
+) -> dict:
+    """Plan a safe transition between two scenes.
+
+    Generates an energy path and gesture sequence for smooth
+    scene-to-scene handoffs during live performance.
+
+    Args:
+        from_scene: Source scene index.
+        to_scene: Destination scene index.
+    """
+    scene_roles, _ = _fetch_scene_data(ctx)
+
+    # Find the two scenes
+    from_role = None
+    to_role = None
+    for s in scene_roles:
+        if s.scene_index == from_scene:
+            from_role = s
+        if s.scene_index == to_scene:
+            to_role = s
+
+    if from_role is None:
+        return {"error": f"Scene {from_scene} not found", "code": "NOT_FOUND"}
+    if to_role is None:
+        return {"error": f"Scene {to_scene} not found", "code": "NOT_FOUND"}
+
+    plan = plan_scene_transition(from_role, to_role)
+    return {
+        "handoff_plan": plan.to_dict(),
+        "from_scene": from_role.to_dict(),
+        "to_scene": to_role.to_dict(),
+        "energy_delta": round(to_role.energy_level - from_role.energy_level, 3),
+        "gesture_count": len(plan.gestures),
+        "step_count": len(plan.energy_path),
+    }

package/mcp_server/project_brain/__init__.py

@@ -0,0 +1,6 @@
+"""Project Brain v1 — shared state substrate for LivePilot.
+
+Provides one coherent, inspectable, updateable representation of the
+current project state.  All engines read from this instead of each
+rebuilding partial state from scratch.
+"""

package/mcp_server/project_brain/arrangement_graph.py

@@ -0,0 +1,64 @@
+"""Arrangement graph builder — transforms scenes + clip matrix into ArrangementGraph.
+
+Reuses _composition_engine.build_section_graph_from_scenes for the heavy
+inference, then converts composition SectionNodes to brain SectionNodes.
+
+Pure computation, zero I/O.
+"""
+
+from __future__ import annotations
+
+from ..tools._composition_engine import (
+    build_section_graph_from_scenes as _ce_build_sections,
+)
+from .models import ArrangementGraph, SectionNode
+
+
+def build_arrangement_graph(
+    scenes: list[dict],
+    clip_matrix: list[list[dict]],
+    track_count: int,
+    beats_per_bar: int = 4,
+) -> ArrangementGraph:
+    """Build an ArrangementGraph from session-view scenes and clip matrix.
+
+    Args:
+        scenes: list of {index, name, tempo, color_index}.
+        clip_matrix: [scene_index][track_index] = {state, name, ...} or None.
+        track_count: total number of tracks in the session.
+        beats_per_bar: beats per bar (default 4).
+
+    Returns:
+        ArrangementGraph with sections, boundaries, and freshness (unfreshed).
+    """
+    graph = ArrangementGraph()
+
+    if not scenes:
+        return graph
+
+    # Delegate to composition engine for section inference
+    ce_sections = _ce_build_sections(scenes, clip_matrix, track_count, beats_per_bar)
+
+    # Convert composition SectionNodes -> brain SectionNodes
+    for ce_sec in ce_sections:
+        graph.sections.append(SectionNode(
+            section_id=ce_sec.section_id,
+            start_bar=ce_sec.start_bar,
+            end_bar=ce_sec.end_bar,
+            section_type=ce_sec.section_type.value,
+            energy=ce_sec.energy,
+            density=ce_sec.density,
+        ))
+
+    # Build boundary list (transitions between adjacent sections)
+    for i in range(len(graph.sections) - 1):
+        curr = graph.sections[i]
+        nxt = graph.sections[i + 1]
+        graph.boundaries.append({
+            "from_section": curr.section_id,
+            "to_section": nxt.section_id,
+            "bar": curr.end_bar,
+            "energy_delta": round(nxt.energy - curr.energy, 3),
+        })
+
+    return graph