livepilot 1.6.5 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.7.0 — Creative Engine (March 2026)
+
+**13 new tools (142 → 155), 3 new domains, MIDI file I/O, neo-Riemannian harmony, generative algorithms.**
+
+### MIDI I/O Domain (4 tools)
+- `export_clip_midi` — export session clip to .mid file
+- `import_midi_to_clip` — load .mid file into session clip
+- `analyze_midi_file` — offline analysis of any .mid file
+- `extract_piano_roll` — 2D velocity matrix from .mid file
+
+### Generative Domain (5 tools)
+- `generate_euclidean_rhythm` — Bjorklund algorithm, identifies known rhythms
+- `layer_euclidean_rhythms` — stack patterns for polyrhythmic textures
+- `generate_tintinnabuli` — Arvo Pärt technique: triad voice from melody
+- `generate_phase_shift` — Steve Reich technique: drifting canon
+- `generate_additive_process` — Philip Glass technique: expanding melody
+
+### Harmony Domain (4 tools)
+- `navigate_tonnetz` — PRL neighbors in harmonic space
+- `find_voice_leading_path` — shortest path between two chords through Tonnetz
+- `classify_progression` — identify neo-Riemannian transform pattern
+- `suggest_chromatic_mediants` — all chromatic mediant relations with film score picks
+
+### Architecture
+- Two new pure Python engines (`_generative_engine.py`, `_harmony_engine.py`)
+- New dependencies: midiutil, pretty-midi, opycleid (~5 MB total, lazy-loaded)
+- Opycleid fallback: harmony tools work without the package via pure Python PRL
+- All generative tools return note arrays — LLM orchestrates placement
+
 ## 1.6.5 — Drop music21 (March 2026)
 
 **Theory tools rewritten with zero-dependency pure Python engine.**

package/README.md

@@ -12,7 +12,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/dreamrec/LivePilot)](https://github.com/dreamrec/LivePilot/stargazers)
 [![npm](https://img.shields.io/npm/v/livepilot)](https://www.npmjs.com/package/livepilot)
 
-**AI copilot for Ableton Live 12** — 142 MCP tools, a deep device knowledge corpus, real-time audio analysis, and persistent technique memory.
+**AI copilot for Ableton Live 12** — 155 MCP tools, a deep device knowledge corpus, real-time audio analysis, generative algorithms, neo-Riemannian harmony, MIDI file I/O, and persistent technique memory.
 
 Most Ableton MCP servers give the AI tools to push buttons. LivePilot gives it three things on top of that:
 
@@ -20,7 +20,7 @@ Most Ableton MCP servers give the AI tools to push buttons. LivePilot gives it t
 - **Perception** — An M4L analyzer that reads the master bus in real-time: 8-band spectrum, RMS/peak metering, pitch tracking, key detection. The AI makes decisions based on what it hears, not just what's configured.
 - **Memory** — A technique library that persists across sessions. The AI remembers how you built that bass sound, what swing you like on hi-hats, which reverb chain worked on vocals. It learns your taste over time.
 
-These three layers sit on top of 142 deterministic MCP tools that cover transport, tracks, clips, MIDI, devices, scenes, mixing, browser, arrangement, and sample manipulation. Every command goes through Ableton's official Live Object Model API — the same interface Ableton's own control surfaces use. Everything is reversible with undo.
+These three layers sit on top of 155 deterministic MCP tools that cover transport, tracks, clips, MIDI, devices, scenes, mixing, browser, arrangement, sample manipulation, generative algorithms, neo-Riemannian harmony, and MIDI file I/O. Every command goes through Ableton's official Live Object Model API — the same interface Ableton's own control surfaces use. Everything is reversible with undo.
 
 ---
 
@@ -296,7 +296,7 @@ npx -y github:dreamrec/LivePilot --status
 
 ---
 
-## 142 Tools Across 13 Domains
+## 155 Tools Across 16 Domains
 
 | Domain | Tools | What you can do |
 |--------|:-----:|-----------------|
@@ -313,6 +313,9 @@ npx -y github:dreamrec/LivePilot --status
 | **Memory** | 8 | Save, recall, replay, and manage production techniques |
 | **Analyzer** | 20 | Real-time spectral analysis, key detection, sample manipulation, warp markers, device introspection (requires M4L device) |
 | **Theory** | 7 | Harmony analysis, Roman numerals, scale identification, chord suggestions, countermelody, SATB harmonization, smart transposition |
+| **Generative** | 5 | Euclidean rhythms (Bjorklund), polyrhythmic layering, Pärt tintinnabuli, Reich phase shift, Glass additive process |
+| **Harmony** | 4 | Tonnetz navigation, voice leading paths, neo-Riemannian classification, chromatic mediants |
+| **MIDI I/O** | 4 | Export clips to .mid, import .mid files, offline MIDI analysis, piano roll extraction |
 
 <details>
 <summary><strong>Full tool list</strong></summary>
@@ -353,6 +356,18 @@ npx -y github:dreamrec/LivePilot --status
 ### Analyzer (20) — requires LivePilot Analyzer M4L device on master track
 `get_master_spectrum` · `get_master_rms` · `get_detected_key` · `get_hidden_parameters` · `get_automation_state` · `walk_device_tree` · `get_clip_file_path` · `replace_simpler_sample` · `load_sample_to_simpler` · `get_simpler_slices` · `crop_simpler` · `reverse_simpler` · `warp_simpler` · `get_warp_markers` · `add_warp_marker` · `move_warp_marker` · `remove_warp_marker` · `scrub_clip` · `stop_scrub` · `get_display_values`
 
+### Theory (7)
+`analyze_harmony` · `suggest_next_chord` · `detect_theory_issues` · `identify_scale` · `harmonize_melody` · `generate_countermelody` · `transpose_smart`
+
+### Generative (5)
+`generate_euclidean_rhythm` · `layer_euclidean_rhythms` · `generate_tintinnabuli` · `generate_phase_shift` · `generate_additive_process`
+
+### Harmony (4)
+`navigate_tonnetz` · `find_voice_leading_path` · `classify_progression` · `suggest_chromatic_mediants`
+
+### MIDI I/O (4)
+`export_clip_midi` · `import_midi_to_clip` · `analyze_midi_file` · `extract_piano_roll`
+
 </details>
 
 ---
@@ -403,7 +418,7 @@ There are **15+ MCP servers for Ableton Live** as of March 2026. Here's how the
 
 | | [LivePilot](https://github.com/dreamrec/LivePilot) | [AbletonMCP](https://github.com/ahujasid/ableton-mcp) | [MCP Extended](https://github.com/uisato/ableton-mcp-extended) | [Ableton Copilot](https://github.com/xiaolaa2/ableton-copilot-mcp) | [AbletonBridge](https://github.com/hidingwill/AbletonBridge) | [Producer Pal](https://github.com/adamjmurray/producer-pal) |
 |---|:-:|:-:|:-:|:-:|:-:|:-:|
-| **Tools** | 142 | ~20 | ~35 | ~45 | 322 | ~25 |
+| **Tools** | 155 | ~20 | ~35 | ~45 | 322 | ~25 |
 | **Device knowledge** | 280+ devices | -- | -- | -- | -- | -- |
 | **Audio analysis** | Spectrum/RMS/key | -- | -- | -- | Metering | -- |
 | **Technique memory** | Persistent | -- | -- | -- | -- | -- |
@@ -460,7 +475,7 @@ Every server on this list gives the AI tools to control Ableton. LivePilot is th
 
 The practical difference: other servers let the AI set a parameter. LivePilot lets the AI choose the right parameter based on what device is loaded (atlas), verify the result by reading the audio output (analyzer), and remember the technique for next time (memory).
 
-AbletonBridge has more raw tools (322 vs 142). Producer Pal has the easiest install (drag a .amxd). The original AbletonMCP has the community (2.3k stars). LivePilot has the deepest integration — tools that execute, knowledge that informs, perception that verifies, and memory that accumulates.
+AbletonBridge has more raw tools (322 vs 155). Producer Pal has the easiest install (drag a .amxd). The original AbletonMCP has the community (2.3k stars). LivePilot has the deepest integration — tools that execute, knowledge that informs, perception that verifies, and memory that accumulates.
 
 ---
 

package/bin/livepilot.js

@@ -70,12 +70,12 @@ function ensureVenv(systemPython, prefixArgs) {
   // Check if venv already exists and has our deps
   if (fs.existsSync(venvPy)) {
     try {
-      execFileSync(venvPy, ["-c", "import fastmcp"], {
+      execFileSync(venvPy, ["-c", "import fastmcp; import midiutil; import pretty_midi"], {
         encoding: "utf-8",
         timeout: 10000,
         stdio: "pipe",
       });
-      return venvPy; // venv exists and fastmcp is importable
+      return venvPy; // venv exists and all deps importable
     } catch {
       // venv exists but deps missing — reinstall
       console.error("LivePilot: reinstalling Python dependencies...");

package/m4l_device/livepilot_bridge.js

@@ -68,7 +68,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.6.5"});
+            send_response({"ok": true, "version": "1.7.0"});
             break;
         case "get_params":
             cmd_get_params(args);

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.6.5"
+__version__ = "1.7.0"

package/mcp_server/server.py

@@ -57,6 +57,9 @@ from .tools import memory       # noqa: F401, E402
 from .tools import analyzer     # noqa: F401, E402
 from .tools import automation   # noqa: F401, E402
 from .tools import theory       # noqa: F401, E402
+from .tools import generative   # noqa: F401, E402
+from .tools import harmony      # noqa: F401, E402
+from .tools import midi_io      # noqa: F401, E402
 
 
 # ---------------------------------------------------------------------------

package/mcp_server/tools/_generative_engine.py

@@ -0,0 +1,271 @@
+"""Pure Python generative music engine — zero dependencies.
+
+Implements: Bjorklund/Euclidean rhythms, tintinnabuli, phase shifting,
+additive process. All functions are pure — no state, no I/O.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+
+
+# ---------------------------------------------------------------------------
+# Known Euclidean rhythms
+# ---------------------------------------------------------------------------
+
+KNOWN_RHYTHMS: dict[tuple[int, int], str] = {
+    (2, 3): "shuffle",
+    (2, 5): "khafif-e-ramal",
+    (3, 4): "cumbia",
+    (3, 7): "ruchenitza",
+    (3, 8): "tresillo",
+    (4, 7): "yoruba bell",
+    (5, 8): "cinquillo",
+    (5, 16): "bossa nova",
+    (7, 12): "west african bell",
+    (7, 16): "brazilian necklace",
+}
+
+
+# ---------------------------------------------------------------------------
+# Bjorklund / Euclidean rhythm
+# ---------------------------------------------------------------------------
+
+def bjorklund(pulses: int, steps: int) -> list[int]:
+    """Bjorklund/Euclidean rhythm: distribute pulses evenly across steps.
+
+    Returns list of 0s and 1s with length == steps.
+    """
+    if steps <= 0:
+        return []
+    if pulses <= 0:
+        return [0] * steps
+    if pulses >= steps:
+        return [1] * steps
+
+    # Bresenham-style Euclidean distribution
+    pattern = []
+    counts = [0] * steps
+    remainders = [0] * steps
+    divisor = steps - pulses
+    remainders[0] = pulses
+    level = 0
+
+    while True:
+        counts[level] = divisor // remainders[level]
+        remainders[level + 1] = divisor % remainders[level]
+        divisor = remainders[level]
+        level += 1
+        if remainders[level] <= 1:
+            break
+
+    counts[level] = divisor
+
+    def _build(lv: int) -> list[int]:
+        if lv == -1:
+            return [0]
+        if lv == -2:
+            return [1]
+        seq: list[int] = []
+        for _ in range(counts[lv]):
+            seq.extend(_build(lv - 1))
+        if remainders[lv] != 0:
+            seq.extend(_build(lv - 2))
+        return seq
+
+    pattern = _build(level)
+    # Rotate to canonical form: first hit followed by a rest (1 then 0).
+    # If every position after a hit is also a hit (e.g. pulses == steps-1),
+    # fall back to rotating so the pattern simply starts with 1.
+    if not pattern or 1 not in pattern or 0 not in pattern:
+        return pattern
+    n = len(pattern)
+    for rot in range(n):
+        rotated = pattern[rot:] + pattern[:rot]
+        if rotated[0] == 1 and rotated[1] == 0:
+            return rotated
+    # Fallback: rotate to first 1
+    idx = pattern.index(1)
+    return pattern[idx:] + pattern[:idx]
+
+
+def rotate_pattern(pattern: list[int], rotation: int) -> list[int]:
+    """Rotate a pattern by N steps (positive = shift left)."""
+    if not pattern:
+        return pattern
+    n = len(pattern)
+    rotation = rotation % n
+    return pattern[rotation:] + pattern[:rotation]
+
+
+def identify_rhythm(pulses: int, steps: int) -> str | None:
+    """Return known rhythm name for (pulses, steps), or None."""
+    return KNOWN_RHYTHMS.get((pulses, steps))
+
+
+# ---------------------------------------------------------------------------
+# Tintinnabuli (Arvo Pärt)
+# ---------------------------------------------------------------------------
+
+def tintinnabuli_voice(
+    melody_pitches: list[int],
+    triad_pcs: list[int],
+    position: str = "nearest",
+) -> list[int]:
+    """Generate tintinnabuli voice: for each melody pitch, find nearest triad tone.
+
+    Args:
+        melody_pitches: MIDI pitch numbers of the melody.
+        triad_pcs: Pitch classes (0-11) of the triad (e.g. [0,4,7] for C major).
+        position: "above", "below", or "nearest".
+
+    Returns:
+        List of MIDI pitches for the tintinnabuli voice.
+    """
+    result = []
+    for mp in melody_pitches:
+        best = _find_triad_tone(mp, triad_pcs, position)
+        result.append(best)
+    return result
+
+
+def _find_triad_tone(pitch: int, triad_pcs: list[int], position: str) -> int:
+    """Find the nearest triad tone relative to a given pitch."""
+    candidates = []
+    for octave_offset in range(-2, 3):
+        for pc in triad_pcs:
+            candidate = (pitch // 12 + octave_offset) * 12 + pc
+            if 0 <= candidate <= 127:
+                candidates.append(candidate)
+
+    if position == "above":
+        above = [c for c in candidates if c > pitch]
+        return min(above) if above else max(candidates)
+    elif position == "below":
+        below = [c for c in candidates if c < pitch]
+        return max(below) if below else min(candidates)
+    else:  # nearest
+        others = [c for c in candidates if c != pitch]
+        if not others:
+            return pitch
+        return min(others, key=lambda c: abs(c - pitch))
+
+
+# ---------------------------------------------------------------------------
+# Phase shifting (Steve Reich)
+# ---------------------------------------------------------------------------
+
+def phase_shift(
+    pattern_notes: list[dict],
+    voices: int = 2,
+    shift_amount: float = 0.125,
+    total_length: float = 16.0,
+) -> list[dict]:
+    """Generate phase-shifted canon.
+
+    Voice 0 loops the pattern normally. Each subsequent voice accumulates
+    shift_amount offset per repetition, creating gradual phase drift.
+
+    Returns combined note array with velocity encoding per voice:
+    voice 0 = 100, voice 1 = 90, voice 2 = 80, etc.
+    """
+    if not pattern_notes:
+        return []
+
+    sorted_notes = sorted(pattern_notes, key=lambda n: n["start_time"])
+    pattern_length = max(n["start_time"] + n["duration"] for n in sorted_notes)
+    if pattern_length <= 0:
+        return []
+
+    result: list[dict] = []
+
+    for voice in range(voices):
+        velocity = max(100 - voice * 10, 30)
+        # Voice N starts shifted by voice * shift_amount and accumulates
+        # additional drift of voice * shift_amount per repetition.
+        # offset(rep) = rep * pattern_length + voice * shift_amount * (rep + 1)
+        repetition = 0
+        while True:
+            offset = repetition * pattern_length + voice * shift_amount * (repetition + 1)
+
+            if offset >= total_length:
+                break
+
+            for note in sorted_notes:
+                t = offset + note["start_time"]
+                if t >= total_length:
+                    continue
+                result.append({
+                    "pitch": note["pitch"],
+                    "start_time": round(t, 4),
+                    "duration": note["duration"],
+                    "velocity": velocity,
+                })
+            repetition += 1
+
+    return sorted(result, key=lambda n: n["start_time"])
+
+
+# ---------------------------------------------------------------------------
+# Additive process (Philip Glass)
+# ---------------------------------------------------------------------------
+
+def additive_process(
+    melody_notes: list[dict],
+    direction: str = "forward",
+    repetitions_per_stage: int = 2,
+) -> list[dict]:
+    """Glass-style additive process.
+
+    Forward: play note 0, then 0-1, then 0-1-2, ... each repeated N times.
+    Backward: play all, then remove from front.
+    Both: forward, then backward (skipping the full melody to avoid duplicate).
+    """
+    if not melody_notes:
+        return []
+
+    sorted_notes = sorted(melody_notes, key=lambda n: n["start_time"])
+    base = sorted_notes[0]["start_time"]
+    normalized = []
+    for n in sorted_notes:
+        normalized.append({
+            "pitch": n["pitch"],
+            "start_time": round(n["start_time"] - base, 4),
+            "duration": n["duration"],
+            "velocity": n.get("velocity", 100),
+        })
+
+    def _stage_duration(notes: list[dict]) -> float:
+        if not notes:
+            return 0.0
+        return max(n["start_time"] + n["duration"] for n in notes)
+
+    def _build_stages(note_slices: list[list[dict]]) -> list[dict]:
+        result: list[dict] = []
+        cursor = 0.0
+        for stage_notes in note_slices:
+            for _ in range(repetitions_per_stage):
+                for n in stage_notes:
+                    result.append({
+                        "pitch": n["pitch"],
+                        "start_time": round(cursor + n["start_time"], 4),
+                        "duration": n["duration"],
+                        "velocity": n["velocity"],
+                    })
+                cursor += _stage_duration(stage_notes)
+            cursor = round(cursor, 4)
+        return result
+
+    n_notes = len(normalized)
+
+    if direction == "forward":
+        slices = [normalized[:k + 1] for k in range(n_notes)]
+        return _build_stages(slices)
+    elif direction == "backward":
+        slices = [normalized[k:] for k in range(n_notes)]
+        return _build_stages(slices)
+    else:  # both
+        forward_slices = [normalized[:k + 1] for k in range(n_notes)]
+        backward_slices = [normalized[k:] for k in range(1, n_notes)]  # skip full
+        return _build_stages(forward_slices + backward_slices)

package/mcp_server/tools/_harmony_engine.py

@@ -0,0 +1,207 @@
+"""Neo-Riemannian harmony engine — pure Python with optional opycleid.
+
+Implements P/L/R transforms, Tonnetz navigation, BFS path finding,
+progression classification, and chromatic mediant computation.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Callable
+
+from . import _theory_engine as engine
+
+
+# ---------------------------------------------------------------------------
+# Note name display
+# ---------------------------------------------------------------------------
+
+_PC_NAMES_MAJOR = ['C', 'C#', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B']
+_PC_NAMES_MINOR = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'Bb', 'B']
+
+
+def chord_to_str(root_pc: int, quality: str) -> str:
+    """Convert (root_pc, quality) to display string like 'Ab major'."""
+    names = _PC_NAMES_MAJOR if quality == "major" else _PC_NAMES_MINOR
+    return f"{names[root_pc % 12]} {quality}"
+
+
+def parse_chord(chord_str: str) -> tuple[int, str]:
+    """Parse 'C major' → (0, 'major'), 'F# minor' → (6, 'minor').
+
+    Uses _theory_engine.parse_key() internally — check what it returns!
+    """
+    parsed = engine.parse_key(chord_str)
+    mode = parsed["mode"]
+    if mode not in ("major", "minor"):
+        raise ValueError(f"Only major/minor chords supported, got: {mode}")
+    return (parsed["tonic"], mode)
+
+
+# ---------------------------------------------------------------------------
+# PRL transforms
+# ---------------------------------------------------------------------------
+
+def parallel(root_pc: int, quality: str) -> tuple[int, str]:
+    """P: flip the third. Major ↔ minor, same root."""
+    new_q = "minor" if quality == "major" else "major"
+    return (root_pc, new_q)
+
+
+def leading_tone(root_pc: int, quality: str) -> tuple[int, str]:
+    """L: major → lower root by semitone → minor; minor → raise fifth by semitone → major."""
+    if quality == "major":
+        return ((root_pc + 4) % 12, "minor")
+    else:
+        return ((root_pc - 4) % 12, "major")
+
+
+def relative(root_pc: int, quality: str) -> tuple[int, str]:
+    """R: major → raise fifth by whole tone → minor; minor → lower root by whole tone → major."""
+    if quality == "major":
+        return ((root_pc + 9) % 12, "minor")
+    else:
+        return ((root_pc + 3) % 12, "major")
+
+
+TRANSFORMS: dict[str, Callable] = {
+    "P": parallel,
+    "L": leading_tone,
+    "R": relative,
+}
+
+
+def apply_transforms(root_pc: int, quality: str, transforms: str) -> tuple[int, str]:
+    """Apply a sequence of PRL transforms: 'PRL' → P, then R, then L."""
+    current = (root_pc, quality)
+    for char in transforms:
+        fn = TRANSFORMS.get(char)
+        if fn is None:
+            raise ValueError(f"Unknown transform: {char}. Use P, L, or R.")
+        current = fn(*current)
+    return current
+
+
+def chord_to_midi(root_pc: int, quality: str, octave: int = 4) -> list[int]:
+    """Convert chord to MIDI pitches in the given octave."""
+    base = (octave + 1) * 12 + root_pc
+    if quality == "major":
+        return [base, base + 4, base + 7]
+    else:
+        return [base, base + 3, base + 7]
+
+
+# ---------------------------------------------------------------------------
+# Tonnetz navigation
+# ---------------------------------------------------------------------------
+
+def get_neighbors(root_pc: int, quality: str, depth: int = 1) -> dict:
+    """Return all reachable chords up to depth PRL transforms."""
+    result = {}
+    _explore(root_pc, quality, "", depth, result)
+    return result
+
+
+def _explore(root_pc: int, quality: str, path: str, remaining: int,
+             result: dict) -> None:
+    """Recursive neighbor exploration."""
+    if remaining <= 0:
+        return
+    for label, fn in TRANSFORMS.items():
+        new_chord = fn(root_pc, quality)
+        key = path + label
+        if key not in result:
+            result[key] = new_chord
+            _explore(*new_chord, key, remaining - 1, result)
+
+
+# ---------------------------------------------------------------------------
+# BFS path finding
+# ---------------------------------------------------------------------------
+
+def find_shortest_path(
+    from_chord: tuple[int, str],
+    to_chord: tuple[int, str],
+    max_depth: int = 4,
+) -> dict:
+    """BFS through PRL space to find shortest path between two chords."""
+    if from_chord == to_chord:
+        return {
+            "found": True,
+            "steps": 0,
+            "path": [from_chord],
+            "transforms": [],
+        }
+
+    queue: deque = deque()
+    visited: set = {from_chord}
+
+    for label, fn in TRANSFORMS.items():
+        next_chord = fn(*from_chord)
+        if next_chord == to_chord:
+            return {
+                "found": True,
+                "steps": 1,
+                "path": [from_chord, to_chord],
+                "transforms": [label],
+            }
+        if next_chord not in visited:
+            visited.add(next_chord)
+            queue.append((next_chord, [from_chord, next_chord], [label]))
+
+    depth = 1
+    while queue and depth < max_depth:
+        depth += 1
+        level_size = len(queue)
+        for _ in range(level_size):
+            current, path, transforms = queue.popleft()
+            for label, fn in TRANSFORMS.items():
+                next_chord = fn(*current)
+                if next_chord == to_chord:
+                    return {
+                        "found": True,
+                        "steps": depth,
+                        "path": path + [to_chord],
+                        "transforms": transforms + [label],
+                    }
+                if next_chord not in visited:
+                    visited.add(next_chord)
+                    queue.append((next_chord, path + [next_chord],
+                                  transforms + [label]))
+
+    return {"found": False, "steps": -1, "path": [], "transforms": []}
+
+
+# ---------------------------------------------------------------------------
+# Progression classification
+# ---------------------------------------------------------------------------
+
+def classify_transform_sequence(chords: list[tuple[int, str]]) -> list[str]:
+    """Identify the PRL transform between each consecutive pair of chords."""
+    result = []
+    for i in range(len(chords) - 1):
+        found = "?"
+        for label, fn in TRANSFORMS.items():
+            if fn(*chords[i]) == chords[i + 1]:
+                found = label
+                break
+        result.append(found)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Chromatic mediants
+# ---------------------------------------------------------------------------
+
+def get_chromatic_mediants(root_pc: int, quality: str) -> dict:
+    """Return all 6 chromatic mediant relations."""
+    return {
+        "upper_major_third": ((root_pc + 4) % 12, quality),
+        "lower_major_third": ((root_pc - 4) % 12, quality),
+        "upper_minor_third": ((root_pc + 3) % 12, quality),
+        "lower_minor_third": ((root_pc - 3) % 12, quality),
+        "upper_major_third_flip": ((root_pc + 4) % 12,
+                                   "minor" if quality == "major" else "major"),
+        "lower_major_third_flip": ((root_pc - 4) % 12,
+                                   "minor" if quality == "major" else "major"),
+    }