livepilot 1.10.4 → 1.10.6

package/mcp_server/tools/_composition_engine/gestures.py

@@ -0,0 +1,230 @@
+"""Part of the _composition_engine package — extracted from the single-file engine.
+
+Pure-computation core, no external deps. Callers should import from the package
+facade (e.g. `from mcp_server.tools._composition_engine import X`), which
+re-exports everything from these sub-modules.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+from .models import GestureIntent, GesturePlan
+
+_GESTURE_MAPPINGS: dict[GestureIntent, dict] = {
+    GestureIntent.REVEAL: {
+        "description": "Open filter, introduce width, grow send level, unmask harmonics",
+        "parameter_hints": ["filter_cutoff", "send_level", "utility_width"],
+        "curve_family": "exponential",
+        "default_direction": "up",
+        "typical_duration_bars": 4,
+    },
+    GestureIntent.CONCEAL: {
+        "description": "Close filter, narrow image, reduce send, darken support",
+        "parameter_hints": ["filter_cutoff", "volume", "utility_width"],
+        "curve_family": "logarithmic",
+        "default_direction": "down",
+        "typical_duration_bars": 4,
+    },
+    GestureIntent.HANDOFF: {
+        "description": "One voice dims while another emerges",
+        "parameter_hints": ["volume", "send_level"],
+        "curve_family": "s_curve",
+        "default_direction": "crossfade",
+        "typical_duration_bars": 2,
+    },
+    GestureIntent.INHALE: {
+        "description": "Pull energy back before impact — pre-drop vacuum",
+        "parameter_hints": ["volume", "filter_cutoff", "send_level"],
+        "curve_family": "exponential",
+        "default_direction": "down",
+        "typical_duration_bars": 2,
+    },
+    GestureIntent.RELEASE: {
+        "description": "Restore weight, width, or harmonic color after tension",
+        "parameter_hints": ["filter_cutoff", "utility_width", "volume"],
+        "curve_family": "spring",
+        "default_direction": "up",
+        "typical_duration_bars": 1,
+    },
+    GestureIntent.LIFT: {
+        "description": "HP filter rise, reverb send increase — upward energy",
+        "parameter_hints": ["hp_filter", "send_level", "reverb_mix"],
+        "curve_family": "exponential",
+        "default_direction": "up",
+        "typical_duration_bars": 8,
+    },
+    GestureIntent.SINK: {
+        "description": "LP filter close, remove highs, settle into sub",
+        "parameter_hints": ["filter_cutoff", "eq_high"],
+        "curve_family": "logarithmic",
+        "default_direction": "down",
+        "typical_duration_bars": 4,
+    },
+    GestureIntent.PUNCTUATE: {
+        "description": "Dub throw spike, beat repeat burst — accent a moment",
+        "parameter_hints": ["send_level", "beat_repeat"],
+        "curve_family": "spike",
+        "default_direction": "burst",
+        "typical_duration_bars": 1,
+    },
+    GestureIntent.DRIFT: {
+        "description": "Subtle organic movement — perlin noise on parameters",
+        "parameter_hints": ["filter_cutoff", "pan", "send_level"],
+        "curve_family": "perlin",
+        "default_direction": "oscillate",
+        "typical_duration_bars": 8,
+    },
+}
+
+def plan_gesture(
+    intent: GestureIntent,
+    target_tracks: list[int],
+    start_bar: int,
+    duration_bars: Optional[int] = None,
+    foreground: bool = False,
+) -> GesturePlan:
+    """Create a gesture plan from a musical intent.
+
+    Maps the abstract intent to concrete automation parameters and curve type.
+    The agent uses this plan with apply_automation_shape to execute.
+    """
+    mapping = _GESTURE_MAPPINGS.get(intent)
+    if mapping is None:
+        raise ValueError(f"Unknown gesture intent: {intent}")
+
+    actual_duration = duration_bars or mapping["typical_duration_bars"]
+
+    return GesturePlan(
+        gesture_id=f"gest_{intent.value}_{start_bar}",
+        intent=intent,
+        description=mapping["description"],
+        target_tracks=target_tracks,
+        parameter_hints=mapping["parameter_hints"],
+        curve_family=mapping["curve_family"],
+        direction=mapping["default_direction"],
+        start_bar=start_bar,
+        end_bar=start_bar + actual_duration,
+        foreground=foreground,
+    )
+
+GESTURE_TEMPLATES: dict[str, dict] = {
+    "pre_arrival_vacuum": {
+        "description": "Pull energy back before impact — classic build technique",
+        "steps": [
+            {"intent": "inhale", "offset_bars": -4, "duration_bars": 3},
+            {"intent": "release", "offset_bars": 0, "duration_bars": 1},
+        ],
+        "best_for": ["pre_drop", "pre_chorus", "turnaround"],
+    },
+    "sectional_width_bloom": {
+        "description": "Narrow then widen — creates sense of opening up",
+        "steps": [
+            {"intent": "conceal", "offset_bars": -2, "duration_bars": 2},
+            {"intent": "reveal", "offset_bars": 0, "duration_bars": 4},
+            {"intent": "drift", "offset_bars": 4, "duration_bars": 8},
+        ],
+        "best_for": ["chorus_entry", "verse_to_chorus", "section_expansion"],
+    },
+    "phrase_end_throw": {
+        "description": "Accent the end of a phrase with a dub throw",
+        "steps": [
+            {"intent": "punctuate", "offset_bars": -1, "duration_bars": 1},
+        ],
+        "best_for": ["phrase_cadence", "hook_accent", "transition"],
+    },
+    "turnaround_accent": {
+        "description": "Mark turnaround with lift then settle",
+        "steps": [
+            {"intent": "lift", "offset_bars": -2, "duration_bars": 2},
+            {"intent": "sink", "offset_bars": 0, "duration_bars": 2},
+        ],
+        "best_for": ["loop_turnaround", "phrase_repeat", "section_end"],
+    },
+    "outro_decay_dissolve": {
+        "description": "Gradual dissolution for endings",
+        "steps": [
+            {"intent": "conceal", "offset_bars": 0, "duration_bars": 8},
+            {"intent": "sink", "offset_bars": 4, "duration_bars": 8},
+        ],
+        "best_for": ["outro", "fade_out", "ending"],
+    },
+    "bass_tuck_before_kick": {
+        "description": "Duck bass before kick re-entry",
+        "steps": [
+            {"intent": "inhale", "offset_bars": -1, "duration_bars": 1},
+            {"intent": "release", "offset_bars": 0, "duration_bars": 1},
+        ],
+        "best_for": ["kick_reentry", "drop", "bass_return"],
+    },
+    "harmonic_tint_rise": {
+        "description": "Gradually introduce harmonic color via filter opening",
+        "steps": [
+            {"intent": "reveal", "offset_bars": 0, "duration_bars": 8},
+        ],
+        "best_for": ["verse_development", "pad_introduction", "harmonic_shift"],
+    },
+    "response_echo": {
+        "description": "Echo gesture — punctuate then drift the tail",
+        "steps": [
+            {"intent": "punctuate", "offset_bars": 0, "duration_bars": 1},
+            {"intent": "drift", "offset_bars": 1, "duration_bars": 4},
+        ],
+        "best_for": ["call_and_response", "hook_echo", "delay_throw"],
+    },
+    "texture_drift_bed": {
+        "description": "Subtle ongoing motion for background textures",
+        "steps": [
+            {"intent": "drift", "offset_bars": 0, "duration_bars": 16},
+        ],
+        "best_for": ["pad_movement", "background_texture", "atmosphere"],
+    },
+    "tension_ratchet": {
+        "description": "Stepped tension increase — reveal in stages",
+        "steps": [
+            {"intent": "reveal", "offset_bars": 0, "duration_bars": 4},
+            {"intent": "reveal", "offset_bars": 4, "duration_bars": 4},
+            {"intent": "lift", "offset_bars": 8, "duration_bars": 4},
+        ],
+        "best_for": ["long_build", "riser", "gradual_intensification"],
+    },
+    "re_entry_spotlight": {
+        "description": "Spotlight a returning element",
+        "steps": [
+            {"intent": "conceal", "offset_bars": -2, "duration_bars": 2},
+            {"intent": "release", "offset_bars": 0, "duration_bars": 1},
+        ],
+        "best_for": ["hook_return", "melody_reentry", "element_spotlight"],
+    },
+}
+
+def resolve_gesture_template(
+    template_name: str,
+    target_tracks: list[int],
+    anchor_bar: int,
+    foreground: bool = False,
+) -> list[GesturePlan]:
+    """Resolve a gesture template into a sequence of concrete GesturePlans.
+
+    anchor_bar: the reference point (e.g., section boundary bar number).
+    Steps with negative offsets happen before the anchor.
+    """
+    template = GESTURE_TEMPLATES.get(template_name)
+    if template is None:
+        valid = list(GESTURE_TEMPLATES.keys())
+        raise ValueError(f"Unknown template '{template_name}'. Valid: {valid}")
+
+    plans = []
+    for i, step in enumerate(template["steps"]):
+        intent = GestureIntent(step["intent"])
+        start = anchor_bar + step.get("offset_bars", 0)
+        duration = step.get("duration_bars", None)
+        gesture = plan_gesture(intent, target_tracks, start, duration, foreground)
+        gesture.gesture_id = f"{template_name}_{i:02d}_{start}"
+        plans.append(gesture)
+
+    return plans
+

package/mcp_server/tools/_composition_engine/harmony.py

@@ -0,0 +1,70 @@
+"""Part of the _composition_engine package — extracted from the single-file engine.
+
+Pure-computation core, no external deps. Callers should import from the package
+facade (e.g. `from mcp_server.tools._composition_engine import X`), which
+re-exports everything from these sub-modules.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+from .models import HarmonyField
+
+def build_harmony_field(
+    section_id: str,
+    harmony_analysis: Optional[dict] = None,
+    scale_info: Optional[dict] = None,
+    progression_info: Optional[dict] = None,
+    voice_leading_info: Optional[dict] = None,
+) -> HarmonyField:
+    """Build a HarmonyField from theory/harmony tool outputs.
+
+    All parameters are optional — degrades gracefully.
+    """
+    hf = HarmonyField(section_id=section_id)
+
+    # Scale / key info
+    if scale_info:
+        top = scale_info.get("top_match", {})
+        hf.key = top.get("tonic", "")
+        hf.mode = top.get("mode", "")
+        hf.confidence = top.get("confidence", 0.0)
+
+    # Chord progression
+    if harmony_analysis:
+        chords = harmony_analysis.get("chords", [])
+        hf.chord_progression = [c.get("chord_name", "?") for c in chords]
+
+        # Instability: ratio of non-tonic chords
+        roman_numerals = [c.get("roman_numeral", "?") for c in chords]
+        if roman_numerals:
+            non_tonic = sum(1 for r in roman_numerals if r not in ("i", "I", "?"))
+            hf.instability = non_tonic / len(roman_numerals)
+
+        # Resolution potential: does it end on tonic?
+        if roman_numerals:
+            hf.resolution_potential = 1.0 if roman_numerals[-1] in ("i", "I") else 0.3
+
+    # Progression classification
+    if progression_info:
+        classification = progression_info.get("classification", "")
+        # "diatonic" = more stable, "free neo-Riemannian" = more unstable
+        if "diatonic" in classification.lower():
+            hf.instability = max(0.0, hf.instability - 0.1)
+        elif "free" in classification.lower():
+            hf.instability = min(1.0, hf.instability + 0.1)
+
+    # Voice leading quality
+    if voice_leading_info:
+        steps = voice_leading_info.get("steps", 0)
+        found = voice_leading_info.get("found", False)
+        if found and steps > 0:
+            # Fewer steps = smoother voice leading
+            hf.voice_leading_quality = max(0.0, 1.0 - (steps - 1) * 0.15)
+
+    return hf
+

package/mcp_server/tools/_composition_engine/models.py

@@ -0,0 +1,193 @@
+"""Part of the _composition_engine package — extracted from the single-file engine.
+
+Pure-computation core, no external deps. Callers should import from the package
+facade (e.g. `from mcp_server.tools._composition_engine import X`), which
+re-exports everything from these sub-modules.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+# ── Enums ─────────────────────────────────────────────────────────────
+class SectionType(str, Enum):
+    LOOP = "loop"
+    INTRO = "intro"
+    VERSE = "verse"
+    PRE_CHORUS = "pre_chorus"
+    CHORUS = "chorus"
+    BUILD = "build"
+    DROP = "drop"
+    BRIDGE = "bridge"
+    BREAKDOWN = "breakdown"
+    OUTRO = "outro"
+    UNKNOWN = "unknown"
+
+class RoleType(str, Enum):
+    KICK_ANCHOR = "kick_anchor"
+    BASS_ANCHOR = "bass_anchor"
+    HOOK = "hook"
+    LEAD = "lead"
+    HARMONY_BED = "harmony_bed"
+    RHYTHMIC_TEXTURE = "rhythmic_texture"
+    TEXTURE_WASH = "texture_wash"
+    TRANSITION_FX = "transition_fx"
+    UTILITY = "utility"
+    UNKNOWN = "unknown"
+
+class GestureIntent(str, Enum):
+    REVEAL = "reveal"
+    CONCEAL = "conceal"
+    HANDOFF = "handoff"
+    INHALE = "inhale"
+    RELEASE = "release"
+    LIFT = "lift"
+    SINK = "sink"
+    PUNCTUATE = "punctuate"
+    DRIFT = "drift"
+
+@dataclass
+class SectionNode:
+    """A section of the arrangement with inferred type and energy."""
+    section_id: str
+    start_bar: int
+    end_bar: int
+    section_type: SectionType
+    confidence: float  # 0.0-1.0
+    energy: float  # 0.0-1.0 (relative within the track)
+    density: float  # 0.0-1.0 (how many tracks are active)
+    tracks_active: list[int] = field(default_factory=list)
+    name: str = ""
+
+    def length_bars(self) -> int:
+        return self.end_bar - self.start_bar
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["section_type"] = self.section_type.value
+        d["length_bars"] = self.length_bars()
+        return d
+
+
+# ── Phrase Grid ───────────────────────────────────────────────────────
+@dataclass
+class PhraseUnit:
+    """A musical phrase within a section."""
+    phrase_id: str
+    section_id: str
+    start_bar: int
+    end_bar: int
+    cadence_strength: float  # 0.0-1.0 (how strongly it resolves)
+    note_density: float  # notes per bar
+    has_variation: bool  # differs from adjacent phrases
+
+    def length_bars(self) -> int:
+        return self.end_bar - self.start_bar
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["length_bars"] = self.length_bars()
+        return d
+
+
+# ── Role Inference ────────────────────────────────────────────────────
+@dataclass
+class RoleNode:
+    """A track's musical role within a specific section."""
+    track_index: int
+    track_name: str
+    section_id: str
+    role: RoleType
+    confidence: float  # 0.0-1.0
+    foreground: bool  # is this a focal element?
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["role"] = self.role.value
+        return d
+
+
+# ── Composition Critics ───────────────────────────────────────────────
+@dataclass
+class CompositionIssue:
+    """A structural or musical problem detected by a critic."""
+    issue_type: str
+    critic: str  # "form", "section_identity", "phrase"
+    severity: float  # 0.0-1.0
+    confidence: float  # 0.0-1.0
+    scope: dict = field(default_factory=dict)  # e.g., {"section_id": "sec_01"}
+    recommended_moves: list[str] = field(default_factory=list)
+    evidence: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+@dataclass
+class GesturePlan:
+    """A concrete automation plan derived from a musical gesture intent."""
+    gesture_id: str
+    intent: GestureIntent
+    description: str
+    target_tracks: list[int]
+    parameter_hints: list[str]
+    curve_family: str
+    direction: str
+    start_bar: int
+    end_bar: int
+    foreground: bool  # is this a musical focus or background motion?
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["intent"] = self.intent.value
+        d["duration_bars"] = self.end_bar - self.start_bar
+        return d
+
+
+# ── Full Analysis Pipeline ────────────────────────────────────────────
+@dataclass
+class CompositionAnalysis:
+    """Complete composition analysis result."""
+    sections: list[SectionNode]
+    phrases: list[PhraseUnit]
+    roles: list[RoleNode]
+    issues: list[CompositionIssue]
+
+    def to_dict(self) -> dict:
+        return {
+            "sections": [s.to_dict() for s in self.sections],
+            "section_count": len(self.sections),
+            "phrases": [p.to_dict() for p in self.phrases],
+            "phrase_count": len(self.phrases),
+            "roles": [r.to_dict() for r in self.roles],
+            "role_count": len(self.roles),
+            "issues": [i.to_dict() for i in self.issues],
+            "issue_count": len(self.issues),
+            "issue_summary": {
+                "form": len([i for i in self.issues if i.critic == "form"]),
+                "section_identity": len([i for i in self.issues if i.critic == "section_identity"]),
+                "phrase": len([i for i in self.issues if i.critic == "phrase"]),
+                "transition": len([i for i in self.issues if i.critic == "transition"]),
+            },
+        }
+
+
+# ── Harmony Field (Round 1) ──────────────────────────────────────────
+@dataclass
+class HarmonyField:
+    """Harmonic analysis of a section — key, chords, voice-leading, tension."""
+    section_id: str
+    key: str = ""
+    mode: str = ""
+    confidence: float = 0.0
+    chord_progression: list[str] = field(default_factory=list)
+    voice_leading_quality: float = 0.5  # 0=rough, 1=smooth
+    instability: float = 0.0  # 0=stable/tonic, 1=highly unstable
+    resolution_potential: float = 0.5  # tendency toward resolution
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+