livepilot 1.19.1 → 1.20.1

package/mcp_server/semantic_moves/device_mutation_compilers.py

@@ -0,0 +1,157 @@
+"""Compilers for device-mutation semantic moves (v1.20).
+
+Pure functions. Read ``kernel["seed_args"]`` for the user's target, emit
+CompiledPlan steps matching the expected tool signatures
+(``batch_set_parameters``, ``delete_device``, ``add_session_memory``).
+"""
+
+from __future__ import annotations
+
+from .compiler import CompiledPlan, CompiledStep, register_compiler
+from .models import SemanticMove
+
+
+def _empty_plan(move: SemanticMove, warnings: list[str]) -> CompiledPlan:
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=[],
+        risk_level=move.risk_level,
+        summary="; ".join(warnings) if warnings else "No plan compiled",
+        requires_approval=True,
+        warnings=warnings,
+    )
+
+
+# ── configure_device ──────────────────────────────────────────────────────────
+
+
+def _compile_configure_device(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    args = kernel.get("seed_args") or {}
+    track_index = args.get("track_index")
+    device_index = args.get("device_index")
+    overrides = args.get("param_overrides")
+
+    if track_index is None or device_index is None or overrides is None:
+        return _empty_plan(move, [
+            "configure_device requires seed_args.track_index + device_index + param_overrides"
+        ])
+    if not isinstance(track_index, int) or not isinstance(device_index, int):
+        return _empty_plan(move, [
+            f"track_index and device_index must be ints, got "
+            f"{type(track_index).__name__}/{type(device_index).__name__}"
+        ])
+    if device_index < 0:
+        return _empty_plan(move, [f"device_index must be non-negative, got {device_index}"])
+    if not isinstance(overrides, dict):
+        return _empty_plan(move, [
+            f"param_overrides must be a dict[str, Any], got {type(overrides).__name__}"
+        ])
+    if not overrides:
+        return _empty_plan(move, [
+            "param_overrides is empty — nothing to configure (delete_device "
+            "is a different move)"
+        ])
+
+    # WIRE-FORMAT NOTE: compiled steps use the remote_command backend,
+    # which calls ableton.send_command() directly — bypassing the MCP
+    # tool's ergonomic rename at mcp_server/tools/devices.py:292
+    # (_normalize_batch_entry). Ableton's Remote Script handler
+    # (remote_script/LivePilot/devices.py:149) reads `name_or_index`
+    # exclusively. Emit that key directly.
+    parameters = [
+        {"name_or_index": str(name), "value": value}
+        for name, value in overrides.items()
+    ]
+
+    step = CompiledStep(
+        tool="batch_set_parameters",
+        params={
+            "track_index": track_index,
+            "device_index": device_index,
+            "parameters": parameters,
+        },
+        description=(
+            f"Configure device at track {track_index}, device_index {device_index} — "
+            f"set {len(parameters)} parameter(s): "
+            f"{', '.join(p['name_or_index'] for p in parameters)}"
+        ),
+        verify_after=True,
+        backend="remote_command",
+    )
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=[step],
+        risk_level=move.risk_level,
+        summary=step.description,
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=[],
+    )
+
+
+# ── remove_device ──────────────────────────────────────────────────────────────
+
+
+def _compile_remove_device(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    args = kernel.get("seed_args") or {}
+    track_index = args.get("track_index")
+    device_index = args.get("device_index")
+    reason = args.get("reason")
+
+    if track_index is None or device_index is None:
+        return _empty_plan(move, [
+            "remove_device requires seed_args.track_index + device_index"
+        ])
+    if not isinstance(track_index, int) or not isinstance(device_index, int):
+        return _empty_plan(move, [
+            "track_index and device_index must be ints"
+        ])
+    if device_index < 0:
+        return _empty_plan(move, [f"device_index must be non-negative, got {device_index}"])
+    if not isinstance(reason, str) or not reason.strip():
+        return _empty_plan(move, [
+            "remove_device requires a non-empty seed_args.reason — "
+            "destructive moves must be justified for the audit trail"
+        ])
+
+    delete_step = CompiledStep(
+        tool="delete_device",
+        params={"track_index": track_index, "device_index": device_index},
+        description=(
+            f"Delete device at track {track_index}, device_index {device_index}"
+        ),
+        verify_after=True,
+        backend="remote_command",
+    )
+
+    memory_step = CompiledStep(
+        tool="add_session_memory",
+        params={
+            "category": "device_removal",
+            "content": (
+                f"Removed track={track_index} device_index={device_index}: "
+                f"{reason.strip()}"
+            ),
+        },
+        description="Log removal reason to session memory for audit",
+        verify_after=False,
+        backend="mcp_tool",
+    )
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=[delete_step, memory_step],
+        risk_level=move.risk_level,
+        summary=f"{delete_step.description} — reason: {reason.strip()}",
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=[],
+    )
+
+
+# ── Register compilers ────────────────────────────────────────────────────────
+
+register_compiler("configure_device", _compile_configure_device)
+register_compiler("remove_device", _compile_remove_device)

package/mcp_server/semantic_moves/device_mutation_moves.py

@@ -0,0 +1,94 @@
+"""Device-mutation semantic moves (v1.20) — configure an existing device
+in bulk, or remove one with an audit reason.
+
+Both moves take user targets via ``kernel["seed_args"]``. configure_device
+uses explicit ``param_overrides: dict`` rather than a preset library —
+the preset-YAML infrastructure the original plan called for is deferred
+to v1.21 so this commit can ship at-budget without widening blast radius.
+Once a preset library lands, it can layer on top: the preset is just a
+resolved param_overrides dict.
+"""
+
+from .models import SemanticMove
+from .registry import register
+
+
+CONFIGURE_DEVICE = SemanticMove(
+    move_id="configure_device",
+    family="sound_design",
+    intent=(
+        "Reconfigure an existing device in bulk — set multiple parameters "
+        "in a single undoable move. Takes track_index, device_index, and "
+        "a param_overrides dict ({param_name: value}) via seed_args."
+    ),
+    # Reconfiguring a device touches timbre + depth + clarity in a general
+    # way; caller scopes intent through the specific param_overrides dict
+    # they pass, and taste alignment happens per-dimension at rank time.
+    targets={"timbre": 0.4, "depth": 0.3, "clarity": 0.3},
+    protect={},
+    risk_level="low",
+    plan_template=[
+        {
+            "tool": "batch_set_parameters",
+            "params": {
+                "description": (
+                    "Apply param_overrides dict as a single batch_set_parameters call"
+                ),
+            },
+            "description": "Configure device parameters in one move",
+            "backend": "remote_command",
+        },
+    ],
+    verification_plan=[
+        {
+            "tool": "get_device_parameters",
+            "check": "requested parameter values match the overrides",
+            "backend": "remote_command",
+        },
+    ],
+)
+
+REMOVE_DEVICE = SemanticMove(
+    move_id="remove_device",
+    family="sound_design",
+    intent=(
+        "Remove a device from a track — destructive but undoable via Live's "
+        "undo stack. Takes track_index, device_index, and a human-readable "
+        "reason via seed_args. Reason is logged to session memory for audit."
+    ),
+    targets={},
+    # Removing a device on an active signal path can silence audio entirely.
+    # Caller is responsible for ensuring the device isn't load-bearing.
+    protect={"signal_integrity": 0.9},
+    risk_level="medium",
+    plan_template=[
+        {
+            "tool": "delete_device",
+            "params": {"description": "Delete the target device"},
+            "description": "Remove the device",
+            "backend": "remote_command",
+        },
+        {
+            "tool": "add_session_memory",
+            "params": {
+                "description": (
+                    "Log the reason under category=device_removal so the audit "
+                    "trail survives anti-repetition scrubbing"
+                ),
+            },
+            "description": "Log removal reason",
+            "backend": "mcp_tool",
+        },
+    ],
+    verification_plan=[
+        {
+            "tool": "get_track_info",
+            "check": "device count on track decreased by 1",
+            "backend": "remote_command",
+        },
+    ],
+)
+
+
+for _move in (CONFIGURE_DEVICE, REMOVE_DEVICE):
+    register(_move)

package/mcp_server/semantic_moves/metadata_compilers.py

@@ -0,0 +1,230 @@
+"""Compilers for metadata-family semantic moves (v1.20).
+
+Pure functions. Each compiler emits one step per *provided* optional
+field — the move lets the director collapse multiple one-line raw tool
+calls into a single named intent without forcing the caller to fill in
+fields they don't care about.
+"""
+
+from __future__ import annotations
+
+from .compiler import CompiledPlan, CompiledStep, register_compiler
+from .models import SemanticMove
+
+
+def _empty_plan(move: SemanticMove, warnings: list[str]) -> CompiledPlan:
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=[],
+        risk_level=move.risk_level,
+        summary="; ".join(warnings) if warnings else "No plan compiled",
+        requires_approval=True,
+        warnings=warnings,
+    )
+
+
+# ── configure_groove ──────────────────────────────────────────────────────────
+
+
+def _compile_configure_groove(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    args = kernel.get("seed_args") or {}
+    track_index = args.get("track_index")
+    clip_indices = args.get("clip_indices")
+    groove_id = args.get("groove_id")
+    timing_amount = args.get("timing_amount")  # optional
+
+    if track_index is None or clip_indices is None or groove_id is None:
+        return _empty_plan(move, [
+            "configure_groove requires seed_args.track_index + clip_indices + groove_id"
+        ])
+    if not isinstance(track_index, int) or not isinstance(groove_id, int):
+        return _empty_plan(move, ["track_index and groove_id must be ints"])
+    if not isinstance(clip_indices, (list, tuple)) or not clip_indices:
+        return _empty_plan(move, ["clip_indices must be a non-empty list of ints"])
+    if not all(isinstance(ci, int) and ci >= 0 for ci in clip_indices):
+        return _empty_plan(move, [
+            "clip_indices entries must be non-negative ints"
+        ])
+
+    warnings: list[str] = []
+    clamped_timing: float | None = None
+    if timing_amount is not None:
+        try:
+            t = float(timing_amount)
+        except (TypeError, ValueError):
+            return _empty_plan(move, [f"timing_amount must be numeric, got {timing_amount!r}"])
+        clamped_timing = max(0.0, min(1.0, t))
+        if clamped_timing != t:
+            warnings.append(
+                f"Clamped timing_amount {t} → {clamped_timing} (must be 0.0-1.0)"
+            )
+
+    steps: list[CompiledStep] = []
+    for ci in clip_indices:
+        steps.append(CompiledStep(
+            tool="assign_clip_groove",
+            params={
+                "track_index": track_index,
+                "clip_index": ci,
+                "groove_id": groove_id,
+            },
+            description=f"Assign groove_id={groove_id} to track {track_index} clip {ci}",
+            verify_after=True,
+            backend="remote_command",
+        ))
+    if clamped_timing is not None:
+        steps.append(CompiledStep(
+            tool="set_groove_params",
+            params={
+                "groove_id": groove_id,
+                "timing_amount": clamped_timing,
+            },
+            description=f"Set groove {groove_id} timing_amount to {clamped_timing}",
+            verify_after=True,
+            backend="remote_command",
+        ))
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=steps,
+        risk_level=move.risk_level,
+        summary=(
+            f"Assign groove {groove_id} to {len(clip_indices)} clip(s) on track {track_index}"
+            + (f"; timing={clamped_timing}" if clamped_timing is not None else "")
+        ),
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=warnings,
+    )
+
+
+# ── set_scene_metadata ────────────────────────────────────────────────────────
+
+
+def _compile_set_scene_metadata(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    args = kernel.get("seed_args") or {}
+    scene_index = args.get("scene_index")
+    name = args.get("name")
+    color_index = args.get("color_index")
+    tempo = args.get("tempo")
+
+    if scene_index is None:
+        return _empty_plan(move, ["set_scene_metadata requires seed_args.scene_index"])
+    if not isinstance(scene_index, int) or scene_index < 0:
+        return _empty_plan(move, [
+            f"scene_index must be a non-negative int, got {scene_index!r}"
+        ])
+    if name is None and color_index is None and tempo is None:
+        return _empty_plan(move, [
+            "set_scene_metadata requires at least one of: name, color_index, tempo"
+        ])
+
+    steps: list[CompiledStep] = []
+    summary_parts: list[str] = []
+    if name is not None:
+        if not isinstance(name, str):
+            return _empty_plan(move, ["name must be a string"])
+        steps.append(CompiledStep(
+            tool="set_scene_name",
+            params={"scene_index": scene_index, "name": name},
+            description=f"Rename scene {scene_index} → '{name}'",
+            verify_after=True,
+            backend="remote_command",
+        ))
+        summary_parts.append(f"name='{name}'")
+    if color_index is not None:
+        if not isinstance(color_index, int):
+            return _empty_plan(move, ["color_index must be int"])
+        steps.append(CompiledStep(
+            tool="set_scene_color",
+            params={"scene_index": scene_index, "color_index": color_index},
+            description=f"Color scene {scene_index} → index {color_index}",
+            verify_after=True,
+            backend="remote_command",
+        ))
+        summary_parts.append(f"color={color_index}")
+    if tempo is not None:
+        try:
+            tempo_f = float(tempo)
+        except (TypeError, ValueError):
+            return _empty_plan(move, [f"tempo must be numeric, got {tempo!r}"])
+        steps.append(CompiledStep(
+            tool="set_scene_tempo",
+            params={"scene_index": scene_index, "tempo": tempo_f},
+            description=f"Set scene {scene_index} tempo → {tempo_f}",
+            verify_after=True,
+            backend="remote_command",
+        ))
+        summary_parts.append(f"tempo={tempo_f}")
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=steps,
+        risk_level=move.risk_level,
+        summary=f"Scene {scene_index} metadata: {', '.join(summary_parts)}",
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=[],
+    )
+
+
+# ── set_track_metadata ────────────────────────────────────────────────────────
+
+
+def _compile_set_track_metadata(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    args = kernel.get("seed_args") or {}
+    track_index = args.get("track_index")
+    name = args.get("name")
+    color_index = args.get("color_index")
+
+    if track_index is None:
+        return _empty_plan(move, ["set_track_metadata requires seed_args.track_index"])
+    if not isinstance(track_index, int):
+        return _empty_plan(move, [f"track_index must be int, got {track_index!r}"])
+    if name is None and color_index is None:
+        return _empty_plan(move, [
+            "set_track_metadata requires at least one of: name, color_index"
+        ])
+
+    steps: list[CompiledStep] = []
+    summary_parts: list[str] = []
+    if name is not None:
+        if not isinstance(name, str):
+            return _empty_plan(move, ["name must be a string"])
+        steps.append(CompiledStep(
+            tool="set_track_name",
+            params={"track_index": track_index, "name": name},
+            description=f"Rename track {track_index} → '{name}'",
+            verify_after=True,
+            backend="remote_command",
+        ))
+        summary_parts.append(f"name='{name}'")
+    if color_index is not None:
+        if not isinstance(color_index, int):
+            return _empty_plan(move, ["color_index must be int"])
+        steps.append(CompiledStep(
+            tool="set_track_color",
+            params={"track_index": track_index, "color_index": color_index},
+            description=f"Color track {track_index} → index {color_index}",
+            verify_after=True,
+            backend="remote_command",
+        ))
+        summary_parts.append(f"color={color_index}")
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=steps,
+        risk_level=move.risk_level,
+        summary=f"Track {track_index} metadata: {', '.join(summary_parts)}",
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=[],
+    )
+
+
+# ── Register compilers ────────────────────────────────────────────────────────
+
+register_compiler("configure_groove", _compile_configure_groove)
+register_compiler("set_scene_metadata", _compile_set_scene_metadata)
+register_compiler("set_track_metadata", _compile_set_track_metadata)

package/mcp_server/semantic_moves/metadata_moves.py

@@ -0,0 +1,126 @@
+"""Metadata-domain semantic moves (v1.20) — groove configuration, scene
+metadata, and bundled track rename/color.
+
+These moves collapse the most common "touch a few fields at once"
+patterns from Phase 6 into single named intents. set_track_metadata
+specifically bundles rename + color since they're always paired when a
+director is labelling a new track.
+"""
+
+from .models import SemanticMove
+from .registry import register
+
+
+CONFIGURE_GROOVE = SemanticMove(
+    move_id="configure_groove",
+    family="arrangement",
+    intent=(
+        "Assign a groove to one or more clips and optionally tune its "
+        "timing amount — the Dilla-swing primitive. Takes track_index, "
+        "clip_indices (list), groove_id, and optional timing_amount "
+        "(0.0-1.0) via seed_args. Agent pre-resolves groove_id via list_grooves()."
+    ),
+    targets={"groove": 0.6, "motion": 0.2, "contrast": 0.2},
+    protect={"clarity": 0.5},
+    risk_level="low",
+    plan_template=[
+        {
+            "tool": "assign_clip_groove",
+            "params": {"description": "Assign groove to each clip in clip_indices"},
+            "description": "Assign groove to clips",
+            "backend": "remote_command",
+        },
+        {
+            "tool": "set_groove_params",
+            "params": {"description": "Tune groove timing_amount if provided"},
+            "description": "Tune groove timing",
+            "backend": "remote_command",
+        },
+    ],
+    verification_plan=[
+        {
+            "tool": "get_clip_groove",
+            "check": "each clip now shows the expected groove_id",
+            "backend": "remote_command",
+        },
+    ],
+)
+
+SET_SCENE_METADATA = SemanticMove(
+    move_id="set_scene_metadata",
+    family="arrangement",
+    intent=(
+        "Set scene metadata (name/color/tempo) in a single move. Each "
+        "field is optional — the compiler emits one step per provided "
+        "field. set_scene_tempo does affect playback timing when the "
+        "scene is fired; caller should consider."
+    ),
+    targets={},
+    protect={},
+    risk_level="low",
+    plan_template=[
+        {
+            "tool": "set_scene_name",
+            "params": {"description": "When name is provided in seed_args"},
+            "description": "Rename scene",
+            "backend": "remote_command",
+        },
+        {
+            "tool": "set_scene_color",
+            "params": {"description": "When color_index is provided"},
+            "description": "Color scene",
+            "backend": "remote_command",
+        },
+        {
+            "tool": "set_scene_tempo",
+            "params": {"description": "When tempo is provided"},
+            "description": "Set scene tempo",
+            "backend": "remote_command",
+        },
+    ],
+    verification_plan=[
+        {
+            "tool": "get_scenes_info",
+            "check": "scene shows the new metadata fields",
+            "backend": "remote_command",
+        },
+    ],
+)
+
+SET_TRACK_METADATA = SemanticMove(
+    move_id="set_track_metadata",
+    family="mix",
+    intent=(
+        "Set track name and/or color in a single bundled move. Both "
+        "fields are optional; at least one required. The bundling is "
+        "intentional — Phase 6 usage always pairs rename with color."
+    ),
+    targets={},
+    protect={},
+    risk_level="low",
+    plan_template=[
+        {
+            "tool": "set_track_name",
+            "params": {"description": "When name is provided"},
+            "description": "Rename track",
+            "backend": "remote_command",
+        },
+        {
+            "tool": "set_track_color",
+            "params": {"description": "When color_index is provided"},
+            "description": "Color track",
+            "backend": "remote_command",
+        },
+    ],
+    verification_plan=[
+        {
+            "tool": "get_track_info",
+            "check": "track name / color match the requested values",
+            "backend": "remote_command",
+        },
+    ],
+)
+
+
+for _move in (CONFIGURE_GROOVE, SET_SCENE_METADATA, SET_TRACK_METADATA):
+    register(_move)