livepilot 1.6.5 → 1.7.1

package/mcp_server/tools/generative.py

@@ -0,0 +1,273 @@
+"""Generative music tools — Euclidean rhythms, tintinnabuli, phase shift, additive process.
+
+5 tools returning note arrays. Pure computation — no Ableton connection needed.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import _generative_engine as gen
+from . import _theory_engine as theory
+
+
+def _ensure_list(value: Any) -> list:
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+# -- Tool 1: generate_euclidean_rhythm --------------------------------------
+
+@mcp.tool()
+def generate_euclidean_rhythm(
+    ctx: Context,
+    pulses: int,
+    steps: int,
+    rotation: int = 0,
+    pitch: int = 36,
+    velocity: int = 100,
+    step_duration: float = 0.25,
+) -> dict:
+    """Generate a Euclidean rhythm using the Bjorklund algorithm.
+
+    Distributes pulses as evenly as possible across steps. Identifies
+    known rhythms (tresillo, cinquillo, bossa nova, etc.) when matched.
+    Returns note array — use add_notes to place in a clip.
+    """
+    if not 0 <= pulses <= 64:
+        return {"error": "pulses must be 0-64"}
+    if not 1 <= steps <= 64:
+        return {"error": "steps must be 1-64"}
+    if pulses > steps:
+        return {"error": "pulses must be <= steps"}
+
+    pattern = gen.bjorklund(pulses, steps)
+    if rotation:
+        pattern = gen.rotate_pattern(pattern, rotation)
+
+    notes = []
+    for i, hit in enumerate(pattern):
+        if hit:
+            notes.append({
+                "pitch": pitch,
+                "start_time": round(i * step_duration, 4),
+                "duration": step_duration,
+                "velocity": velocity,
+            })
+
+    return {
+        "notes": notes,
+        "pattern": pattern,
+        "name": gen.identify_rhythm(pulses, steps),
+        "total_duration": round(steps * step_duration, 4),
+    }
+
+
+# -- Tool 2: layer_euclidean_rhythms ----------------------------------------
+
+@mcp.tool()
+def layer_euclidean_rhythms(
+    ctx: Context,
+    layers: Any,
+) -> dict:
+    """Stack multiple Euclidean rhythms for polyrhythmic textures.
+
+    Each layer specifies pulses, steps, pitch, and optional velocity/rotation.
+    Returns combined note array ready for add_notes.
+    """
+    layers = _ensure_list(layers)
+    if not layers:
+        return {"error": "At least one layer required"}
+
+    all_notes: list[dict] = []
+    layer_info: list[dict] = []
+    max_duration = 0.0
+
+    for layer in layers:
+        p = int(layer["pulses"])
+        s = int(layer["steps"])
+        rot = int(layer.get("rotation", 0))
+        pitch = int(layer["pitch"])
+        vel = int(layer.get("velocity", 100))
+        dur = float(layer.get("step_duration", 0.25))
+
+        pattern = gen.bjorklund(p, s)
+        if rot:
+            pattern = gen.rotate_pattern(pattern, rot)
+
+        layer_notes = []
+        for i, hit in enumerate(pattern):
+            if hit:
+                layer_notes.append({
+                    "pitch": pitch,
+                    "start_time": round(i * dur, 4),
+                    "duration": dur,
+                    "velocity": vel,
+                })
+
+        all_notes.extend(layer_notes)
+        total_dur = round(s * dur, 4)
+        max_duration = max(max_duration, total_dur)
+        layer_info.append({
+            "pattern": pattern,
+            "note_count": len(layer_notes),
+            "name": gen.identify_rhythm(p, s),
+        })
+
+    return {
+        "notes": sorted(all_notes, key=lambda n: n["start_time"]),
+        "layers": layer_info,
+        "total_duration": max_duration,
+    }
+
+
+# -- Tool 3: generate_tintinnabuli ------------------------------------------
+
+@mcp.tool()
+def generate_tintinnabuli(
+    ctx: Context,
+    melody_notes: Any,
+    triad: str,
+    position: str = "nearest",
+    velocity: int = 80,
+) -> dict:
+    """Generate a tintinnabuli voice (Arvo Pärt technique).
+
+    For each melody note, finds the nearest note of the specified triad.
+    Returns the tintinnabuli voice as a separate note array — combine
+    with the original melody via add_notes for the full Pärt effect.
+    Only major and minor triads are supported.
+    """
+    melody_notes = _ensure_list(melody_notes)
+    if not melody_notes:
+        return {"error": "melody_notes cannot be empty"}
+    if position not in ("above", "below", "nearest"):
+        return {"error": "position must be 'above', 'below', or 'nearest'"}
+
+    try:
+        parsed = theory.parse_key(triad)
+    except ValueError:
+        return {"error": f"Cannot parse triad: {triad}"}
+    if parsed["mode"] not in ("major", "minor"):
+        return {"error": "Only major and minor triads are supported"}
+
+    root = parsed["tonic"]
+    if parsed["mode"] == "major":
+        triad_pcs = [root, (root + 4) % 12, (root + 7) % 12]
+    else:
+        triad_pcs = [root, (root + 3) % 12, (root + 7) % 12]
+
+    melody_pitches = [int(n["pitch"]) for n in melody_notes]
+    t_pitches = gen.tintinnabuli_voice(melody_pitches, triad_pcs, position)
+
+    notes = []
+    for i, n in enumerate(melody_notes):
+        notes.append({
+            "pitch": t_pitches[i],
+            "start_time": float(n["start_time"]),
+            "duration": float(n["duration"]),
+            "velocity": velocity,
+        })
+
+    triad_name = f"{theory.NOTE_NAMES[root]} {parsed['mode']}"
+    return {
+        "notes": notes,
+        "technique": "tintinnabuli",
+        "triad_used": triad_name,
+        "description": f"T-voice moves to {position} {triad_name} triad tone for each melody note",
+    }
+
+
+# -- Tool 4: generate_phase_shift -------------------------------------------
+
+@mcp.tool()
+def generate_phase_shift(
+    ctx: Context,
+    pattern_notes: Any,
+    voices: int = 2,
+    shift_amount: float = 0.125,
+    total_length: float = 16.0,
+) -> dict:
+    """Generate a phase-shifted canon (Steve Reich technique).
+
+    Voice 0 loops the pattern normally. Each subsequent voice drifts
+    by shift_amount beats per repetition, creating gradual phase displacement.
+    Returns combined note array with velocity-encoded voices.
+    """
+    pattern_notes = _ensure_list(pattern_notes)
+    if not pattern_notes:
+        return {"error": "pattern_notes cannot be empty"}
+    if not 1 <= voices <= 8:
+        return {"error": "voices must be 1-8"}
+    if shift_amount <= 0:
+        return {"error": "shift_amount must be > 0"}
+
+    result_notes = gen.phase_shift(pattern_notes, voices, shift_amount, total_length)
+
+    pattern_length = max(n["start_time"] + n["duration"] for n in pattern_notes)
+
+    alignment = None
+    if voices == 2 and shift_amount > 0 and pattern_length > 0:
+        alignment = round((pattern_length / shift_amount) * pattern_length, 4)
+        if alignment > total_length:
+            alignment = None
+
+    return {
+        "notes": result_notes,
+        "voices": voices,
+        "shift_per_repeat": shift_amount,
+        "pattern_length": round(pattern_length, 4),
+        "full_alignment_at": alignment,
+    }
+
+
+# -- Tool 5: generate_additive_process --------------------------------------
+
+@mcp.tool()
+def generate_additive_process(
+    ctx: Context,
+    melody_notes: Any,
+    direction: str = "forward",
+    repetitions_per_stage: int = 2,
+) -> dict:
+    """Generate an additive process (Philip Glass technique).
+
+    Forward: builds melody note by note (1, then 1-2, then 1-2-3...).
+    Backward: full melody, then removes from front.
+    Both: forward then backward.
+    Returns note array — use add_notes to place in a clip.
+    """
+    melody_notes = _ensure_list(melody_notes)
+    if not melody_notes:
+        return {"error": "melody_notes cannot be empty"}
+    if direction not in ("forward", "backward", "both"):
+        return {"error": "direction must be 'forward', 'backward', or 'both'"}
+    if repetitions_per_stage < 1:
+        return {"error": "repetitions_per_stage must be >= 1"}
+
+    result_notes = gen.additive_process(melody_notes, direction,
+                                         repetitions_per_stage)
+    n = len(melody_notes)
+    if direction == "forward":
+        stages = n
+    elif direction == "backward":
+        stages = n
+    else:
+        stages = (2 * n) - 1
+
+    total_duration = max(
+        (no["start_time"] + no["duration"] for no in result_notes),
+        default=0.0,
+    )
+
+    return {
+        "notes": result_notes,
+        "stages": stages,
+        "total_duration": round(total_duration, 4),
+        "direction": direction,
+    }

package/mcp_server/tools/harmony.py

@@ -0,0 +1,253 @@
+"""Neo-Riemannian harmony tools — Tonnetz navigation, voice-leading paths,
+progression classification, chromatic mediant suggestions.
+
+4 tools for advanced harmonic analysis and exploration.
+Pure computation — no Ableton connection needed.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import _harmony_engine as harmony
+from . import _theory_engine as theory
+
+
+def _ensure_list(value: Any) -> list:
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+# -- Tool 1: navigate_tonnetz ------------------------------------------------
+
+@mcp.tool()
+def navigate_tonnetz(
+    ctx: Context,
+    chord: str,
+    depth: int = 1,
+) -> dict:
+    """Show neo-Riemannian neighbors of a chord on the Tonnetz.
+
+    P (Parallel) flips the third: C major → C minor.
+    L (Leading-tone) shifts by semitone: C major → E minor.
+    R (Relative) shifts by whole tone: C major → A minor.
+
+    Use depth 2-3 to see compound transforms (PL, PR, PRL, etc.).
+    """
+    if not 1 <= depth <= 3:
+        return {"error": "depth must be 1-3"}
+    try:
+        root_pc, quality = harmony.parse_chord(chord)
+    except ValueError as e:
+        return {"error": str(e)}
+
+    all_neighbors = harmony.get_neighbors(root_pc, quality, depth)
+
+    descriptions = {
+        "P": "flip third (Parallel)",
+        "L": "shift by semitone (Leading-tone)",
+        "R": "shift by whole tone (Relative)",
+    }
+
+    depth_1 = {}
+    for label in ("P", "L", "R"):
+        if label in all_neighbors:
+            r, q = all_neighbors[label]
+            depth_1[label] = {
+                "chord": harmony.chord_to_str(r, q),
+                "transform": label,
+                "description": descriptions[label],
+            }
+
+    result: dict = {"chord": chord, "neighbors": depth_1}
+
+    if depth >= 2:
+        depth_2 = {}
+        for key, (r, q) in all_neighbors.items():
+            if len(key) == 2:
+                depth_2[key] = {
+                    "chord": harmony.chord_to_str(r, q),
+                    "transforms": key,
+                }
+        result["depth_2"] = depth_2
+
+    if depth >= 3:
+        depth_3 = {}
+        for key, (r, q) in all_neighbors.items():
+            if len(key) == 3:
+                depth_3[key] = {
+                    "chord": harmony.chord_to_str(r, q),
+                    "transforms": key,
+                }
+        result["depth_3"] = depth_3
+
+    return result
+
+
+# -- Tool 2: find_voice_leading_path -----------------------------------------
+
+@mcp.tool()
+def find_voice_leading_path(
+    ctx: Context,
+    from_chord: str,
+    to_chord: str,
+    max_steps: int = 4,
+) -> dict:
+    """Find the shortest neo-Riemannian path between two chords.
+
+    Returns each intermediate chord and the specific voice movements.
+    This is the 'film score progression finder' — chromatic mediants,
+    hexatonic poles, and other cinematic chord moves.
+    """
+    if not 1 <= max_steps <= 6:
+        return {"error": "max_steps must be 1-6"}
+    try:
+        from_parsed = harmony.parse_chord(from_chord)
+        to_parsed = harmony.parse_chord(to_chord)
+    except ValueError as e:
+        return {"error": str(e)}
+
+    result = harmony.find_shortest_path(from_parsed, to_parsed, max_steps)
+
+    if not result["found"]:
+        return {
+            "from": from_chord,
+            "to": to_chord,
+            "found": False,
+            "steps": -1,
+            "path": [],
+            "transforms": [],
+            "voice_leading": [],
+        }
+
+    path_strs = [harmony.chord_to_str(*c) for c in result["path"]]
+    voice_leading = []
+    for i in range(len(result["path"]) - 1):
+        from_midi = harmony.chord_to_midi(*result["path"][i])
+        to_midi = harmony.chord_to_midi(*result["path"][i + 1])
+        movements = []
+        for f, t in zip(from_midi, to_midi):
+            if f != t:
+                movements.append(f"{theory.pitch_name(f)}→{theory.pitch_name(t)}")
+        voice_leading.append({
+            "from": from_midi,
+            "to": to_midi,
+            "movement": ", ".join(movements) if movements else "no movement",
+        })
+
+    return {
+        "from": from_chord,
+        "to": to_chord,
+        "found": True,
+        "steps": result["steps"],
+        "path": path_strs,
+        "transforms": result["transforms"],
+        "voice_leading": voice_leading,
+    }
+
+
+# -- Tool 3: classify_progression --------------------------------------------
+
+@mcp.tool()
+def classify_progression(
+    ctx: Context,
+    chords: Any,
+) -> dict:
+    """Classify a chord progression by its neo-Riemannian transform pattern.
+
+    Identifies hexatonic cycles (PL), octatonic cycles (PR), diatonic
+    cycles (LR), and other known patterns. Pairs with analyze_harmony
+    to understand why a progression sounds 'cinematic' or 'otherworldly'.
+    """
+    chords = _ensure_list(chords)
+    if len(chords) < 2:
+        return {"error": "Need at least 2 chords to classify"}
+
+    try:
+        parsed = [harmony.parse_chord(c) for c in chords]
+    except ValueError as e:
+        return {"error": str(e)}
+
+    transforms = harmony.classify_transform_sequence(parsed)
+    pattern = "".join(transforms)
+
+    classification = "free neo-Riemannian progression"
+    notable_usage = None
+    clean = pattern.replace("?", "")
+
+    if len(clean) >= 2:
+        pair = clean[:2]
+        if pair in ("PL", "LP") and all(c in "PL" for c in clean):
+            classification = "hexatonic cycle fragment"
+            notable_usage = "Radiohead, film scores (Zimmer, Howard)"
+        elif pair in ("PR", "RP") and all(c in "PR" for c in clean):
+            classification = "octatonic cycle fragment"
+            notable_usage = "late Romantic (Wagner, Strauss), horror film scores"
+        elif pair in ("LR", "RL") and all(c in "LR" for c in clean):
+            classification = "diatonic cycle fragment"
+            notable_usage = "functional harmony, common in classical and pop"
+
+    if len(clean) == 1:
+        names = {"P": "parallel transform", "L": "leading-tone transform",
+                 "R": "relative transform"}
+        classification = names.get(clean, classification)
+
+    return {
+        "chords": chords,
+        "transforms": transforms,
+        "pattern": pattern,
+        "classification": classification,
+        "notable_usage": notable_usage,
+    }
+
+
+# -- Tool 4: suggest_chromatic_mediants --------------------------------------
+
+@mcp.tool()
+def suggest_chromatic_mediants(
+    ctx: Context,
+    chord: str,
+) -> dict:
+    """Suggest all chromatic mediant relations for a chord.
+
+    Chromatic mediants are chords a major/minor third away — they share
+    0-1 common tones, creating maximum color shift with minimal voice movement.
+    Includes 'cinematic picks' highlighting the most film-score-friendly options.
+    """
+    try:
+        root_pc, quality = harmony.parse_chord(chord)
+    except ValueError as e:
+        return {"error": str(e)}
+
+    mediants = harmony.get_chromatic_mediants(root_pc, quality)
+
+    chord_pcs = set(harmony.chord_to_midi(root_pc, quality))
+    formatted = {}
+    for key, (r, q) in mediants.items():
+        mediant_pcs = set(harmony.chord_to_midi(r, q))
+        common = len(chord_pcs & mediant_pcs)
+        formatted[key] = {
+            "chord": harmony.chord_to_str(r, q),
+            "common_tones": common,
+            "relation": key.replace("_", " "),
+        }
+
+    cinematic = [
+        harmony.chord_to_str(*mediants["lower_major_third"]),
+        harmony.chord_to_str(*mediants["upper_major_third"]),
+    ]
+
+    return {
+        "chord": chord,
+        "chromatic_mediants": formatted,
+        "cinematic_picks": cinematic,
+        "explanation": (
+            "Chromatic mediants share 0-1 common tones with the original chord. "
+            "Maximum color shift with minimal voice movement — the 'epic' sound."
+        ),
+    }