livepilot 1.9.21 → 1.9.23

package/mcp_server/semantic_moves/sound_design_compilers.py

@@ -0,0 +1,266 @@
+"""Compilers for sound-design-domain semantic moves.
+
+These prefer native Ableton devices. Volume/send adjustments are used
+as safe fallbacks when device chain details aren't in the kernel.
+"""
+
+from __future__ import annotations
+
+from .compiler import CompiledPlan, CompiledStep, register_compiler
+from .models import SemanticMove
+from . import resolvers
+
+
+def _compile_add_warmth(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    """Compile 'add_warmth': volume boost + reverb send for perceived warmth.
+
+    SAFETY: Never blindly set device parameters — device_index=0, parameter_index=0
+    can kill audio if the first device isn't a Saturator. Only adjust device params
+    when find_device_on_track confirms a Saturator is present.
+    """
+    steps = []
+    descriptions = []
+    warnings = []
+
+    # Target melodic or bass tracks for warmth
+    targets = resolvers.find_tracks_by_role(kernel, ["bass", "chords", "pad"])
+    if not targets:
+        targets = resolvers.find_tracks_by_role(kernel, ["lead"])
+
+    for t in targets[:2]:
+        idx = t["index"]
+        name = t["name"]
+
+        # Try to find a Saturator on the track (safe device adjustment)
+        saturator = resolvers.find_device_on_track(kernel, idx, "Saturator")
+        if saturator:
+            steps.append(CompiledStep(
+                tool="set_device_parameter",
+                params={
+                    "track_index": idx,
+                    "device_index": saturator["device_index"],
+                    "parameter_index": 0,
+                    "value": 0.3,
+                },
+                description=f"Gentle Saturator drive on {name}",
+            ))
+            descriptions.append(f"Saturate {name}")
+        else:
+            # No Saturator found — use volume + send instead of risky device params
+            warnings.append(f"No Saturator on {name} — using volume+reverb for warmth")
+
+        # Boost volume slightly for perceived warmth
+        steps.append(CompiledStep(
+            tool="set_track_volume",
+            params={"track_index": idx, "volume": 0.65},
+            description=f"Boost {name} slightly for warmth",
+        ))
+
+        # Add reverb send for depth/warmth perception
+        steps.append(CompiledStep(
+            tool="set_track_send",
+            params={"track_index": idx, "send_index": 0, "value": 0.25},
+            description=f"Add reverb warmth to {name}",
+        ))
+        descriptions.append(f"Warm {name}")
+
+    steps.append(CompiledStep(
+        tool="get_track_meters",
+        params={"include_stereo": True},
+        description="Verify warmth — tracks producing audio, no distortion",
+    ))
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=steps,
+        before_reads=[{"tool": "get_master_spectrum", "params": {}}],
+        after_reads=[{"tool": "get_master_spectrum", "params": {}}],
+        risk_level="low",
+        summary="; ".join(descriptions) if descriptions else "No tracks for warmth",
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=warnings,
+    )
+
+
+def _compile_add_texture(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    """Compile 'add_texture': perlin filter motion + delay send."""
+    steps = []
+    descriptions = []
+
+    targets = resolvers.find_tracks_by_role(kernel, ["pad", "chords", "lead"])
+
+    for t in targets[:1]:
+        idx = t["index"]
+        name = t["name"]
+        steps.append(CompiledStep(
+            tool="apply_automation_shape",
+            params={
+                "track_index": idx,
+                "clip_index": 0,
+                "parameter_type": "device",
+                "device_index": 0,
+                "parameter_index": 0,
+                "curve_type": "perlin",
+                "center": 0.4,
+                "amplitude": 0.2,
+                "duration": 8,
+                "density": 16,
+            },
+            description=f"Perlin filter motion on {name} for organic texture",
+        ))
+        descriptions.append(f"Perlin filter on {name}")
+
+        # Add delay send
+        steps.append(CompiledStep(
+            tool="set_track_send",
+            params={"track_index": idx, "send_index": 1, "value": 0.20},
+            description=f"Add delay send on {name} for spatial texture",
+        ))
+        descriptions.append(f"Delay texture on {name}")
+
+    steps.append(CompiledStep(
+        tool="get_track_meters",
+        params={"include_stereo": True},
+        description="Verify texture — track active with variation",
+    ))
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=steps,
+        risk_level="medium",
+        summary="; ".join(descriptions) if descriptions else "No tracks for texture",
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+    )
+
+
+def _compile_shape_transients(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    """Compile 'shape_transients': push drum volume for punch, adjust sends.
+
+    SAFETY: Never blindly set device parameters. Only adjust Compressor params
+    when find_device_on_track confirms one exists. Otherwise use volume for punch.
+    """
+    steps = []
+    descriptions = []
+    warnings = []
+
+    drums = resolvers.find_tracks_by_role(kernel, ["drums", "percussion"])
+    if not drums:
+        return CompiledPlan(
+            move_id=move.move_id,
+            intent=move.intent,
+            summary="No drum/percussion tracks found",
+            warnings=["No rhythm tracks for transient shaping"],
+        )
+
+    for dt in drums[:1]:
+        idx = dt["index"]
+        name = dt["name"]
+
+        # Try to find a Compressor on the track
+        compressor = resolvers.find_device_on_track(kernel, idx, "Compressor")
+        if compressor:
+            steps.append(CompiledStep(
+                tool="set_device_parameter",
+                params={
+                    "track_index": idx,
+                    "device_index": compressor["device_index"],
+                    "parameter_index": 0,
+                    "value": 0.2,
+                },
+                description=f"Faster Compressor attack on {name} for snap",
+            ))
+            descriptions.append(f"Shape {name} compressor")
+        else:
+            warnings.append(f"No Compressor on {name} — using volume push for punch")
+
+        # Push volume for transient punch regardless
+        steps.append(CompiledStep(
+            tool="set_track_volume",
+            params={"track_index": idx, "volume": 0.75},
+            description=f"Push {name} to 0.75 for transient punch",
+        ))
+        descriptions.append(f"Push {name} for punch")
+
+        # Reduce reverb send to tighten transients
+        steps.append(CompiledStep(
+            tool="set_track_send",
+            params={"track_index": idx, "send_index": 0, "value": 0.10},
+            description=f"Tighten reverb on {name} for cleaner transients",
+        ))
+
+    steps.append(CompiledStep(
+        tool="get_track_meters",
+        params={"include_stereo": True},
+        description="Verify transient character after shaping",
+    ))
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=steps,
+        risk_level="low",
+        summary="; ".join(descriptions),
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=warnings,
+    )
+
+
+def _compile_add_space(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    """Compile 'add_space': reverb + delay + pan widening."""
+    steps = []
+    descriptions = []
+
+    targets = resolvers.find_tracks_by_role(kernel, ["chords", "lead", "pad"])
+
+    for t in targets[:2]:
+        idx = t["index"]
+        name = t["name"]
+        steps.append(CompiledStep(
+            tool="set_track_send",
+            params={"track_index": idx, "send_index": 0, "value": 0.30},
+            description=f"Add reverb depth to {name}",
+        ))
+        descriptions.append(f"Reverb on {name}")
+
+    # Widen one element
+    for t in targets[:1]:
+        steps.append(CompiledStep(
+            tool="set_track_pan",
+            params={"track_index": t["index"], "pan": -0.20},
+            description=f"Pan {t['name']} slightly left for spatial width",
+        ))
+    for t in targets[1:2]:
+        steps.append(CompiledStep(
+            tool="set_track_pan",
+            params={"track_index": t["index"], "pan": 0.20},
+            description=f"Pan {t['name']} slightly right for spatial width",
+        ))
+
+    descriptions.append("Widen spatial field")
+
+    steps.append(CompiledStep(
+        tool="get_track_meters",
+        params={"include_stereo": True},
+        description="Verify spatial depth — stereo present, no phase issues",
+    ))
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=steps,
+        before_reads=[{"tool": "analyze_mix", "params": {}}],
+        after_reads=[{"tool": "analyze_mix", "params": {}}],
+        risk_level="low",
+        summary="; ".join(descriptions) if descriptions else "No tracks for space",
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+    )
+
+
+# ── Register ────────────────────────────────────────────────────────────────
+
+register_compiler("add_warmth", _compile_add_warmth)
+register_compiler("add_texture", _compile_add_texture)
+register_compiler("shape_transients", _compile_shape_transients)
+register_compiler("add_space", _compile_add_space)

package/mcp_server/semantic_moves/sound_design_moves.py

@@ -0,0 +1,78 @@
+"""Sound-design-domain semantic moves — musical intents for timbre and texture.
+
+These moves prefer native Ableton devices over third-party plugins.
+"""
+
+from .models import SemanticMove
+from .registry import register
+
+ADD_WARMTH = SemanticMove(
+    move_id="add_warmth",
+    family="sound_design",
+    intent="Add warmth to a track or the mix — gentle saturation and low-mid boost",
+    targets={"warmth": 0.5, "depth": 0.3, "cohesion": 0.2},
+    protect={"clarity": 0.6, "punch": 0.5},
+    risk_level="low",
+    compile_plan=[
+        {"tool": "set_device_parameter", "params": {"description": "Add Saturator drive +2-4dB for harmonic warmth"}, "description": "Add saturation"},
+        {"tool": "set_device_parameter", "params": {"description": "Boost EQ low-mid shelf +1-2dB"}, "description": "Low-mid warmth"},
+    ],
+    verification_plan=[
+        {"tool": "get_master_spectrum", "check": "low-mid energy increased, high-mid stable"},
+        {"tool": "get_track_meters", "check": "target track producing audio"},
+    ],
+)
+
+ADD_TEXTURE = SemanticMove(
+    move_id="add_texture",
+    family="sound_design",
+    intent="Add texture and movement to a static sound — modulation and grain",
+    targets={"motion": 0.4, "novelty": 0.3, "depth": 0.3},
+    protect={"clarity": 0.6},
+    risk_level="medium",
+    compile_plan=[
+        {"tool": "apply_automation_shape", "params": {"curve_type": "perlin", "description": "Perlin noise on filter cutoff for organic texture"}, "description": "Organic filter motion"},
+        {"tool": "set_track_send", "params": {"description": "Increase delay send for spatial texture"}, "description": "Spatial texture via delay"},
+    ],
+    verification_plan=[
+        {"tool": "get_track_meters", "check": "track producing audio with variation"},
+    ],
+)
+
+SHAPE_TRANSIENTS = SemanticMove(
+    move_id="shape_transients",
+    family="sound_design",
+    intent="Shape transient character — sharpen or soften attack for rhythmic clarity",
+    targets={"punch": 0.5, "clarity": 0.3, "groove": 0.2},
+    protect={"warmth": 0.5},
+    risk_level="low",
+    compile_plan=[
+        {"tool": "set_device_parameter", "params": {"description": "Adjust Compressor attack time (faster = sharper transients, slower = rounder)"}, "description": "Shape attack"},
+        {"tool": "set_device_parameter", "params": {"description": "Adjust Compressor release for rhythmic pumping"}, "description": "Shape release"},
+    ],
+    verification_plan=[
+        {"tool": "get_track_meters", "check": "track producing audio with expected transient character"},
+    ],
+)
+
+ADD_SPACE = SemanticMove(
+    move_id="add_space",
+    family="sound_design",
+    intent="Add spatial depth — reverb, delay, and stereo enhancement without muddying",
+    targets={"depth": 0.5, "width": 0.3, "clarity": 0.2},
+    protect={"punch": 0.6, "clarity": 0.5},
+    risk_level="low",
+    compile_plan=[
+        {"tool": "set_track_send", "params": {"description": "Increase reverb send to 25-35%"}, "description": "Add reverb depth"},
+        {"tool": "set_track_send", "params": {"description": "Add subtle delay send 10-15%"}, "description": "Add delay texture"},
+        {"tool": "set_track_pan", "params": {"description": "Widen pan slightly for spatial presence"}, "description": "Widen spatial field"},
+    ],
+    verification_plan=[
+        {"tool": "get_track_meters", "check": "stereo output present, no phase cancellation"},
+        {"tool": "analyze_mix", "check": "stereo.mono_risk is false"},
+    ],
+)
+
+# Register all sound design moves
+for _move in [ADD_WARMTH, ADD_TEXTURE, SHAPE_TRANSIENTS, ADD_SPACE]:
+    register(_move)

package/mcp_server/semantic_moves/tools.py

@@ -0,0 +1,204 @@
+"""Semantic move MCP tools — propose, preview, and apply musical intents.
+
+3 tools:
+  list_semantic_moves — discover available moves by domain
+  preview_semantic_move — see what a move will do before applying
+  propose_next_best_move — AI-ranked suggestions based on current session state
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import registry
+
+
+@mcp.tool()
+def list_semantic_moves(
+    ctx: Context,
+    domain: str = "",
+    style: str = "",
+) -> dict:
+    """List available semantic moves — high-level musical intents.
+
+    Semantic moves express WHAT to achieve musically, not HOW parametrically.
+    Each move compiles into a sequence of existing deterministic tools.
+
+    domain: filter by family (mix, arrangement, transition, sound_design, performance)
+    style: filter by genre/style (reserved for future use)
+
+    Returns: list of moves with move_id, family, intent, targets, risk_level.
+    """
+    moves = registry.list_moves(domain=domain, style=style)
+    return {"moves": moves, "count": len(moves), "available_domains": ["mix", "arrangement"]}
+
+
+@mcp.tool()
+def preview_semantic_move(
+    ctx: Context,
+    move_id: str,
+) -> dict:
+    """Preview what a semantic move will do before applying it.
+
+    Returns the full compile plan (tool sequence), verification plan,
+    targets, protection constraints, and risk level. Use this to understand
+    the impact before committing.
+    """
+    move = registry.get_move(move_id)
+    if not move:
+        available = [m["move_id"] for m in registry.list_moves()]
+        return {
+            "error": f"Unknown move_id: {move_id}",
+            "available_moves": available,
+        }
+
+    return move.to_full_dict()
+
+
+@mcp.tool()
+def propose_next_best_move(
+    ctx: Context,
+    request_text: str,
+    limit: int = 3,
+) -> dict:
+    """Propose the best semantic moves for a natural language request.
+
+    Analyzes the request text and ranks available semantic moves by
+    relevance. Returns up to `limit` suggestions with confidence scores.
+
+    request_text: what the user wants (e.g., "make this punchier",
+                  "tighten the low end", "reduce repetition")
+    limit: max suggestions to return (default 3)
+    """
+    if not request_text.strip():
+        return {"error": "request_text cannot be empty"}
+
+    # Simple keyword matching for now — will be replaced by conductor
+    # routing + taste ranking in V2 Step 7
+    request_lower = request_text.lower()
+    all_moves = list(registry._REGISTRY.values())
+
+    scored = []
+    for move in all_moves:
+        score = 0.0
+        # Match keywords from intent and move_id
+        intent_lower = move.intent.lower()
+        move_words = set(move.move_id.replace("_", " ").split())
+        intent_words = set(intent_lower.split())
+        request_words = set(request_lower.split())
+
+        # Word overlap scoring
+        overlap = request_words & (move_words | intent_words)
+        score += len(overlap) * 0.3
+
+        # Dimension matching
+        for dim in move.targets:
+            if dim in request_lower:
+                score += 0.2
+
+        # Boost exact intent matches
+        if move.move_id.replace("_", " ") in request_lower:
+            score += 1.0
+
+        if score > 0:
+            scored.append((move, min(score, 1.0)))
+
+    # Sort by score descending
+    scored.sort(key=lambda x: -x[1])
+    top = scored[:limit]
+
+    suggestions = []
+    for move, score in top:
+        d = move.to_dict()
+        d["match_score"] = round(score, 3)
+        suggestions.append(d)
+
+    return {
+        "request": request_text,
+        "suggestions": suggestions,
+        "count": len(suggestions),
+    }
+
+
+@mcp.tool()
+def apply_semantic_move(
+    ctx: Context,
+    move_id: str,
+    mode: str = "improve",
+) -> dict:
+    """Compile and optionally execute a semantic move against the current session.
+
+    Resolves the move's intent into concrete, parameterized tool calls based
+    on the current session topology (track names, roles, devices).
+
+    mode controls behavior:
+    - "improve" / "finish": compile and RETURN the plan for user approval.
+      The agent should present the steps and ask "Shall I do it?"
+    - "explore": compile and EXECUTE immediately, capturing before/after.
+    - "observe" / "diagnose": compile only, never execute. Return the plan.
+
+    Returns: CompiledPlan with concrete steps, summary, and execution status.
+    """
+    from . import compiler
+
+    move = registry.get_move(move_id)
+    if not move:
+        return {"error": f"Unknown move_id: {move_id}"}
+
+    # Build a lightweight kernel from session info
+    ableton = ctx.lifespan_context["ableton"]
+    session_info = ableton.send_command("get_session_info")
+    kernel = {
+        "session_info": session_info,
+        "mode": mode,
+        "capability_state": {},
+    }
+
+    # Compile the move
+    plan = compiler.compile(move, kernel)
+
+    if not plan.executable:
+        result = plan.to_dict()
+        result["executed"] = False
+        return result
+
+    if mode in ("observe", "diagnose"):
+        result = plan.to_dict()
+        result["executed"] = False
+        result["note"] = f"Mode '{mode}' — plan compiled but not executed"
+        return result
+
+    if mode in ("improve", "finish"):
+        result = plan.to_dict()
+        result["executed"] = False
+        result["note"] = "Awaiting approval — present the plan to the user, then execute steps individually"
+        return result
+
+    # explore mode — execute immediately
+    executed_steps = []
+    for step in plan.steps:
+        try:
+            tool_result = ableton.send_command(step.tool, step.params)
+            executed_steps.append({
+                "tool": step.tool,
+                "description": step.description,
+                "result": tool_result,
+                "ok": True,
+            })
+        except Exception as exc:
+            executed_steps.append({
+                "tool": step.tool,
+                "description": step.description,
+                "error": str(exc),
+                "ok": False,
+            })
+
+    result = plan.to_dict()
+    result["executed"] = True
+    result["execution_results"] = executed_steps
+    result["success_count"] = sum(1 for s in executed_steps if s["ok"])
+    result["failure_count"] = sum(1 for s in executed_steps if not s["ok"])
+    return result