livepilot 1.9.13 → 1.9.15

package/mcp_server/tools/motif.py

@@ -0,0 +1,104 @@
+"""Motif MCP tools — pattern detection and transformation.
+
+2 tools: get_motif_graph (detect patterns) and transform_motif (apply transformations).
+"""
+
+from __future__ import annotations
+
+import json
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import _motif_engine as motif_engine
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+@mcp.tool()
+def get_motif_graph(ctx: Context) -> dict:
+    """Detect recurring melodic and rhythmic patterns across all tracks.
+
+    Scans note data from all session clips to find repeated interval
+    patterns. Returns motifs sorted by salience (most memorable first),
+    with occurrence locations, fatigue risk, and suggested transformations.
+
+    Use this to understand what musical ideas are present and which
+    ones need development or variation.
+    """
+    ableton = _get_ableton(ctx)
+    session = ableton.send_command("get_session_info")
+    tracks = session.get("tracks", [])
+
+    # Collect notes from all tracks and clips
+    notes_by_track: dict[int, list[dict]] = {}
+    for track in tracks:
+        t_idx = track["index"]
+        if not track.get("has_midi_input", False):
+            continue
+        track_notes = []
+        for clip_idx in range(session.get("scene_count", 8)):
+            try:
+                result = ableton.send_command("get_notes", {
+                    "track_index": t_idx,
+                    "clip_index": clip_idx,
+                })
+                track_notes.extend(result.get("notes", []))
+            except Exception:
+                pass
+        if track_notes:
+            notes_by_track[t_idx] = track_notes
+
+    motifs = motif_engine.detect_motifs(notes_by_track)
+
+    return {
+        "motifs": [m.to_dict() for m in motifs],
+        "motif_count": len(motifs),
+        "tracks_analyzed": len(notes_by_track),
+    }
+
+
+@mcp.tool()
+def transform_motif(
+    ctx: Context,
+    motif_intervals: list | str,
+    transformation: str,
+    reference_pitch: int = 60,
+) -> dict:
+    """Transform a musical motif using classical composition techniques.
+
+    motif_intervals: interval pattern (list of semitone distances, e.g., [2, -1, 3])
+                     Get this from get_motif_graph → motif.intervals
+    transformation: inversion | retrograde | augmentation | diminution |
+                    fragmentation | register_shift_up | register_shift_down
+    reference_pitch: starting MIDI pitch for output (default: C4=60)
+
+    Returns: list of notes ready for add_notes.
+
+    Example: transform_motif([2, 2, -1, 2], "inversion", 60)
+    → notes descending instead of ascending
+    """
+    if isinstance(motif_intervals, str):
+        try:
+            motif_intervals = json.loads(motif_intervals)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in motif_intervals: {exc}") from exc
+
+    # Build a temporary MotifUnit for the transformation
+    motif = motif_engine.MotifUnit(
+        motif_id="transform_input",
+        kind="melodic",
+        intervals=motif_intervals,
+        rhythm=[],
+        representative_pitches=[reference_pitch],
+    )
+
+    notes = motif_engine.transform_motif(motif, transformation, reference_pitch)
+    return {
+        "notes": notes,
+        "note_count": len(notes),
+        "transformation": transformation,
+        "original_intervals": motif_intervals,
+    }

package/mcp_server/tools/planner.py

@@ -0,0 +1,144 @@
+"""Planner MCP tools — loop-to-song arrangement planning.
+
+2 tools that connect the planner engine (_planner_engine.py) to the
+live Ableton session.
+
+  plan_arrangement — transform a loop into a full arrangement blueprint
+  get_emotional_arc — (in research.py, shares composition data)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import _composition_engine as comp_engine
+from . import _planner_engine as planner_engine
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+@mcp.tool()
+def plan_arrangement(
+    ctx: Context,
+    target_bars: int = 128,
+    style: str = "electronic",
+) -> dict:
+    """Transform the current loop/session into a full arrangement blueprint.
+
+    Analyzes the existing tracks and their roles, then proposes:
+    - Section sequence (intro → verse → build → drop → etc.)
+    - Element reveal order (what enters/exits when)
+    - Gesture automation suggestions for transitions
+    - Orchestration plan (which tracks play in which sections)
+
+    target_bars: desired total arrangement length (default: 128 bars)
+    style: electronic | hiphop | pop | ambient | techno
+
+    Returns: full ArrangementPlan with actionable section-by-section instructions.
+    """
+    if style not in planner_engine.VALID_STYLES:
+        return {"error": f"Unknown style '{style}'. Valid: {sorted(planner_engine.VALID_STYLES)}"}
+
+    ableton = _get_ableton(ctx)
+
+    # 1. Get session info
+    session = ableton.send_command("get_session_info")
+    scenes = session.get("scenes", [])
+    tracks = session.get("tracks", [])
+    track_count = session.get("track_count", 0)
+
+    # 2. Build section graph (to analyze current state)
+    from .composition import _build_clip_matrix
+    clip_matrix = _build_clip_matrix(ableton, len(scenes), track_count)
+    sections = comp_engine.build_section_graph_from_scenes(scenes, clip_matrix, track_count)
+
+    # 3. Get track info for role inference
+    track_data = []
+    notes_map: dict[str, dict[int, list]] = {}
+
+    for track in tracks:
+        t_idx = track["index"]
+        try:
+            ti = ableton.send_command("get_track_info", {"track_index": t_idx})
+            track_data.append(ti)
+        except Exception:
+            track_data.append({"index": t_idx, "name": track.get("name", ""), "devices": []})
+
+    for section in sections:
+        notes_map[section.section_id] = {}
+        for t_idx in section.tracks_active:
+            notes_map[section.section_id][t_idx] = []
+
+    # 4. Build role graph
+    roles = comp_engine.build_role_graph(sections, track_data, notes_map)
+
+    # 5. Analyze loop identity
+    loop_identity = planner_engine.analyze_loop_identity(roles, sections)
+
+    # 6. Plan arrangement
+    plan = planner_engine.plan_arrangement_from_loop(
+        loop_identity,
+        target_duration_bars=target_bars,
+        style=style,
+    )
+
+    result = plan.to_dict()
+    result["loop_identity"] = loop_identity.to_dict()
+    result["available_styles"] = sorted(planner_engine.VALID_STYLES)
+    return result
+
+
+# ── transform_section (Round 4) ─────────────────────────────────────
+
+
+@mcp.tool()
+def transform_section(
+    ctx: Context,
+    transformation: str,
+    section_index: int = -1,
+    bars: int = 8,
+) -> dict:
+    """Apply a structural transformation to the arrangement.
+
+    Proposes radical structural moves — reorder sections, expand loops,
+    compress verbose arrangements, insert bridges. Returns the proposed
+    new section graph without modifying the actual session.
+
+    transformation: insert_bridge_before_final_chorus | swap_verse_positions |
+                    extend_section | compress_section | insert_breakdown |
+                    duplicate_section | remove_section | reverse_section_order |
+                    split_section
+    section_index: which section to transform (required for targeted operations, -1 = auto)
+    bars: how many bars for extend/compress/insert operations
+
+    Returns: before/after section graphs with description and bar delta.
+    """
+    from . import _form_engine as form_engine
+
+    ableton = _get_ableton(ctx)
+    session = ableton.send_command("get_session_info")
+    scenes = session.get("scenes", [])
+    track_count = session.get("track_count", 0)
+
+    from .composition import _build_clip_matrix
+    clip_matrix = _build_clip_matrix(ableton, len(scenes), track_count)
+    sections = comp_engine.build_section_graph_from_scenes(scenes, clip_matrix, track_count)
+
+    if not sections:
+        return {"error": "No sections detected in the arrangement"}
+
+    target = section_index if section_index >= 0 else None
+
+    try:
+        result = form_engine.transform_section_order(
+            sections, transformation, target_index=target, bars=bars,
+        )
+        return result.to_dict()
+    except ValueError as e:
+        return {"error": str(e)}

package/mcp_server/tools/research.py

@@ -0,0 +1,223 @@
+"""Research MCP tools — targeted and deep technique research.
+
+2 tools that connect the research engine (_research_engine.py) to the
+live session context via device atlas and memory.
+
+  research_technique — search corpus + memory for production answers
+  deep_research — multi-source synthesis (adds web if available)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import _research_engine as research_engine
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+@mcp.tool()
+def research_technique(
+    ctx: Context,
+    query: str,
+    scope: str = "targeted",
+) -> dict:
+    """Research a production technique — search device atlas + memory for answers.
+
+    Synthesizes findings from the device atlas (built-in device knowledge),
+    technique memory (past session learnings), and reference corpus into
+    a structured TechniqueCard with devices, method, and verification steps.
+
+    query: what you want to learn (e.g., "how to sidechain bass to kick")
+    scope: "targeted" (device atlas + memory) or "deep" (adds web search)
+
+    Returns: findings ranked by relevance, synthesized technique card, confidence.
+    """
+    if not query or not query.strip():
+        return {"error": "query cannot be empty"}
+
+    if scope not in ("targeted", "deep"):
+        return {"error": f"scope must be 'targeted' or 'deep', got '{scope}'"}
+
+    ableton = _get_ableton(ctx)
+
+    # 1. Analyze query to predict relevant devices
+    query_info = research_engine.analyze_query(query)
+
+    # 2. Search device atlas for relevant devices
+    device_atlas_results = []
+    for device_name in query_info.get("likely_devices", [])[:5]:
+        try:
+            ref = ableton.send_command("search_browser", {"query": device_name, "category": "instruments"})
+            if ref and not ref.get("error"):
+                device_atlas_results.append(ref)
+        except Exception:
+            pass
+
+    # 3. Search memory for related techniques
+    memory_results = []
+    try:
+        # Search technique cards
+        mem = ableton.send_command("memory_list", {
+            "type": "technique_card",
+            "limit": 10,
+            "sort_by": "updated_at",
+        })
+        memory_results.extend(mem.get("techniques", []))
+    except Exception:
+        pass
+
+    try:
+        # Also search research memories
+        mem = ableton.send_command("memory_list", {
+            "type": "research",
+            "limit": 5,
+            "sort_by": "updated_at",
+        })
+        memory_results.extend(mem.get("techniques", []))
+    except Exception:
+        pass
+
+    if scope == "targeted":
+        result = research_engine.targeted_research(
+            query, device_atlas_results, memory_results,
+        )
+    else:
+        # Deep research — try to get web results
+        # Note: web search requires external integration (graceful degradation)
+        result = research_engine.deep_research(
+            query,
+            web_results=[],  # Web search injected by agent if available
+            device_atlas_results=device_atlas_results,
+            memory_results=memory_results,
+        )
+
+    return result.to_dict()
+
+
+@mcp.tool()
+def get_emotional_arc(ctx: Context) -> dict:
+    """Analyze the emotional arc of the arrangement — tension, climax, resolution.
+
+    Checks for: monotone energy, all-climax (no rest), build without payoff,
+    no resolution at the end, peak too early.
+
+    Returns: tension curve and issues with recommended composition moves.
+    """
+    from . import _composition_engine as engine
+
+    ableton = _get_ableton(ctx)
+    session = ableton.send_command("get_session_info")
+    scenes = session.get("scenes", [])
+    tracks = session.get("tracks", [])
+    track_count = session.get("track_count", 0)
+
+    # Build section graph
+    from .composition import _build_clip_matrix
+    clip_matrix = _build_clip_matrix(ableton, len(scenes), track_count)
+    sections = engine.build_section_graph_from_scenes(scenes, clip_matrix, track_count)
+
+    if len(sections) < 3:
+        return {
+            "issues": [],
+            "tension_curve": [],
+            "note": "Need at least 3 sections for emotional arc analysis",
+        }
+
+    # Try to build harmony fields for richer analysis
+    harmony_fields = []
+    for i, section in enumerate(sections):
+        hf = engine.HarmonyField(section_id=section.section_id)
+        # Try to get harmony data
+        for t_idx in section.tracks_active[:3]:
+            try:
+                si = ableton.send_command("identify_scale", {
+                    "track_index": t_idx, "clip_index": i,
+                })
+                if si.get("top_match"):
+                    hf.key = si["top_match"].get("tonic", "")
+                    hf.mode = si["top_match"].get("mode", "")
+                    hf.confidence = si["top_match"].get("confidence", 0.0)
+                    break
+            except Exception:
+                continue
+        harmony_fields.append(hf)
+
+    issues = engine.run_emotional_arc_critic(sections, harmony_fields)
+
+    # Build tension curve for visualization
+    tension_curve = []
+    for section in sections:
+        hf_match = next((hf for hf in harmony_fields if hf.section_id == section.section_id), None)
+        instability = hf_match.instability if hf_match else 0.3
+        tension = round(section.energy * 0.5 + section.density * 0.3 + instability * 0.2, 3)
+        tension_curve.append({
+            "section": section.name or section.section_id,
+            "section_type": section.section_type.value,
+            "tension": tension,
+            "energy": section.energy,
+            "density": section.density,
+        })
+
+    return {
+        "tension_curve": tension_curve,
+        "issues": [i.to_dict() for i in issues],
+        "issue_count": len(issues),
+        "section_count": len(sections),
+    }
+
+
+# ── get_style_tactics (Round 4) ─────────────────────────────────────
+
+
+@mcp.tool()
+def get_style_tactics(
+    ctx: Context,
+    artist_or_genre: str,
+) -> dict:
+    """Get production tactics for a specific artist style or genre.
+
+    Returns structured recipe cards with device chains, arrangement patterns,
+    automation gestures, and verification steps.
+
+    artist_or_genre: e.g., "burial", "techno", "daft punk", "ambient", "trap"
+
+    Returns: list of StyleTactic cards with actionable production instructions.
+    """
+    if not artist_or_genre or not artist_or_genre.strip():
+        return {"error": "artist_or_genre cannot be empty"}
+
+    ableton = _get_ableton(ctx)
+
+    # Search user memory for saved tactics
+    memory_tactics = []
+    try:
+        mem = ableton.send_command("memory_list", {
+            "type": "style_tactic",
+            "limit": 10,
+        })
+        memory_tactics = mem.get("techniques", [])
+    except Exception:
+        pass
+
+    tactics = research_engine.get_style_tactics(artist_or_genre, memory_tactics)
+
+    if not tactics:
+        return {
+            "query": artist_or_genre,
+            "tactics": [],
+            "note": f"No tactics found for '{artist_or_genre}'. "
+                    f"Available built-in styles: burial, daft punk, techno, ambient, trap, lo-fi",
+        }
+
+    return {
+        "query": artist_or_genre,
+        "tactics": [t.to_dict() for t in tactics],
+        "tactic_count": len(tactics),
+    }

package/mcp_server/tools/tracks.py

@@ -17,10 +17,21 @@ def _get_ableton(ctx: Context):
     return ctx.lifespan_context["ableton"]
 
 
-def _validate_track_index(track_index: int):
-    """Validate track index. Must be >= 0 for regular tracks."""
+def _validate_track_index(track_index: int, allow_return: bool = True):
+    """Validate track index.
+
+    Regular tracks: >= 0. Return tracks: -1 (A), -2 (B), etc.
+    Set allow_return=False for operations that only work on regular tracks
+    (e.g., create_scene, set_group_fold).
+    """
     if track_index < 0:
-        raise ValueError("track_index must be >= 0")
+        if not allow_return:
+            raise ValueError("track_index must be >= 0 (return tracks not supported for this operation)")
+        if track_index < -99:
+            raise ValueError(
+                "track_index must be >= 0 for regular tracks, "
+                "or -1..-99 for return tracks (-1=A, -2=B)"
+            )
 
 
 def _validate_color_index(color_index: int):
@@ -185,6 +196,10 @@ def freeze_track(ctx: Context, track_index: int) -> dict:
     Freeze is async in Ableton: this initiates the render and returns
     immediately. Poll get_freeze_status to check when it's done.
     Freezing a track that's already frozen is a no-op.
+
+    Note: freeze() is not available via ControlSurface API in all Live
+    versions. If this fails, use Ableton's Freeze Track menu command
+    (Cmd+F on Mac) manually instead.
     """
     _validate_track_index(track_index)
     return _get_ableton(ctx).send_command("freeze_track", {

package/mcp_server/tools/transport.py

@@ -73,8 +73,16 @@ def continue_playback(ctx: Context) -> dict:
 
 
 @mcp.tool()
-def toggle_metronome(ctx: Context, enabled: bool) -> dict:
-    """Enable or disable the metronome click."""
+def toggle_metronome(ctx: Context, enabled: Optional[bool] = None) -> dict:
+    """Enable or disable the metronome click.
+
+    If enabled is omitted, toggles the current state (true toggle).
+    If enabled is provided, sets to that value explicitly.
+    """
+    if enabled is None:
+        # True toggle: read current state and flip it
+        info = _get_ableton(ctx).send_command("get_session_info")
+        enabled = not info.get("metronome", False)
     return _get_ableton(ctx).send_command("toggle_metronome", {"enabled": enabled})
 
 

package/mcp_server/transition_engine/__init__.py

@@ -0,0 +1,6 @@
+"""Transition Engine V1 — section-boundary intelligence.
+
+Arrivals, exits, handoffs, payoff scoring, archetype library.
+Builds on top of the composition engine's transition critic and
+gesture templates. Pure computation, zero I/O.
+"""