livepilot 1.9.13 → 1.9.15

package/mcp_server/transition_engine/tools.py

@@ -0,0 +1,291 @@
+"""Transition Engine MCP tools — 3 tools for boundary analysis and planning.
+
+Each tool fetches section data from Ableton via the shared connection,
+builds TransitionBoundary objects, then delegates to pure-computation modules.
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+from ..tools import _composition_engine as comp_engine
+
+from .archetypes import TRANSITION_ARCHETYPES, select_archetype
+from .critics import run_all_transition_critics
+from .models import TransitionBoundary, TransitionPlan, TransitionScore
+
+
+# ── Helpers ───────────────────────────────────────────────────────────
+
+
+def _build_sections_from_ableton(ctx: Context) -> list[comp_engine.SectionNode]:
+    """Fetch session data and build section graph."""
+    ableton = ctx.lifespan_context["ableton"]
+    session = ableton.send_command("get_session_info")
+    scenes = session.get("scenes", [])
+    track_count = session.get("track_count", 0)
+
+    try:
+        matrix_data = ableton.send_command("get_scene_matrix")
+        clip_matrix = matrix_data.get("matrix", [])
+    except Exception:
+        clip_matrix = [[] for _ in range(len(scenes))]
+
+    return comp_engine.build_section_graph_from_scenes(
+        scenes, clip_matrix, track_count,
+    )
+
+
+def _find_section_pair(
+    sections: list[comp_engine.SectionNode],
+    from_section: str,
+    to_section: str,
+) -> tuple[comp_engine.SectionNode | None, comp_engine.SectionNode | None]:
+    """Find two sections by ID or name."""
+    from_node = None
+    to_node = None
+    for s in sections:
+        sid = s.section_id.lower()
+        sname = (s.name or "").lower()
+        if sid == from_section.lower() or sname == from_section.lower():
+            from_node = s
+        if sid == to_section.lower() or sname == to_section.lower():
+            to_node = s
+    return from_node, to_node
+
+
+def _build_boundary(
+    from_node: comp_engine.SectionNode,
+    to_node: comp_engine.SectionNode,
+) -> TransitionBoundary:
+    """Build a TransitionBoundary from two adjacent SectionNodes."""
+    return TransitionBoundary(
+        from_section_id=from_node.section_id,
+        to_section_id=to_node.section_id,
+        boundary_bar=to_node.start_bar,
+        from_type=from_node.section_type.value,
+        to_type=to_node.section_type.value,
+        energy_delta=to_node.energy - from_node.energy,
+        density_delta=to_node.density - from_node.density,
+    )
+
+
+def _score_boundary(boundary: TransitionBoundary) -> TransitionScore:
+    """Compute a TransitionScore from boundary data.
+
+    Pure heuristic scoring — no I/O.
+    """
+    abs_energy = abs(boundary.energy_delta)
+    abs_density = abs(boundary.density_delta)
+
+    # Boundary clarity: how obvious is the section change?
+    boundary_clarity = min(1.0, abs_energy * 2.0 + abs_density * 1.5)
+
+    # Payoff strength: does a high-energy arrival feel earned?
+    if boundary.energy_delta > 0.2:
+        # Rising energy — payoff depends on contrast magnitude
+        payoff_strength = min(1.0, boundary.energy_delta * 1.5)
+    elif boundary.energy_delta < -0.2:
+        # Falling energy — payoff is the breath/relief
+        payoff_strength = min(1.0, abs(boundary.energy_delta) * 1.2)
+    else:
+        # Flat — low payoff unless density compensates
+        payoff_strength = min(1.0, abs_density * 1.5)
+
+    # Energy redirection: how much does energy actually shift?
+    energy_redirection = min(1.0, abs_energy * 2.5)
+
+    # Identity preservation (heuristic: same density = same character)
+    identity_preservation = max(0.0, 1.0 - abs_density * 2.0)
+
+    # Cliche risk: common pairs with standard archetypes are higher risk
+    _common_pairs = {
+        ("build", "drop"), ("verse", "chorus"), ("pre_chorus", "chorus"),
+    }
+    pair = (boundary.from_type, boundary.to_type)
+    cliche_risk = 0.5 if pair in _common_pairs else 0.2
+
+    # Overall: weighted average (cliche_risk is inverted — lower is better)
+    overall = (
+        boundary_clarity * 0.25
+        + payoff_strength * 0.30
+        + energy_redirection * 0.20
+        + identity_preservation * 0.10
+        + (1.0 - cliche_risk) * 0.15
+    )
+
+    return TransitionScore(
+        boundary_clarity=round(boundary_clarity, 3),
+        payoff_strength=round(payoff_strength, 3),
+        energy_redirection=round(energy_redirection, 3),
+        identity_preservation=round(identity_preservation, 3),
+        cliche_risk=round(cliche_risk, 3),
+        overall=round(overall, 3),
+    )
+
+
+def _build_plan(
+    boundary: TransitionBoundary,
+    archetype=None,
+) -> TransitionPlan:
+    """Build a TransitionPlan for a boundary using the selected archetype."""
+    if archetype is None:
+        archetype = select_archetype(boundary)
+
+    # Map archetype gestures to lead-in and arrival
+    lead_in_gestures = []
+    arrival_gestures = []
+
+    for gesture_name in archetype.gestures:
+        gesture = {"intent": gesture_name, "archetype": archetype.name}
+        if gesture_name in ("inhale", "conceal", "lift", "punctuate"):
+            lead_in_gestures.append({
+                **gesture,
+                "offset_bars": -2,
+                "duration_bars": 2,
+            })
+        else:
+            arrival_gestures.append({
+                **gesture,
+                "offset_bars": 0,
+                "duration_bars": 2,
+            })
+
+    # Payoff estimate from energy delta and archetype risk
+    risk_penalty = {"low": 0.0, "medium": 0.1, "high": 0.2}.get(
+        archetype.risk_profile, 0.0,
+    )
+    payoff_estimate = min(1.0, max(0.0,
+        abs(boundary.energy_delta) * 1.5 + 0.3 - risk_penalty
+    ))
+
+    return TransitionPlan(
+        boundary=boundary,
+        archetype=archetype,
+        lead_in_gestures=lead_in_gestures,
+        arrival_gestures=arrival_gestures,
+        payoff_estimate=round(payoff_estimate, 3),
+    )
+
+
+# ── MCP Tools ─────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def analyze_transition(
+    ctx: Context,
+    from_section: str,
+    to_section: str,
+) -> dict:
+    """Analyze the transition boundary between two sections.
+
+    Builds a TransitionBoundary, selects an archetype, scores the
+    boundary, and runs all 5 transition critics.
+
+    Args:
+        from_section: Name or ID of the outgoing section.
+        to_section: Name or ID of the arriving section.
+
+    Returns: boundary, archetype, score, issues, and recommended moves.
+    """
+    sections = _build_sections_from_ableton(ctx)
+    from_node, to_node = _find_section_pair(sections, from_section, to_section)
+
+    if not from_node:
+        return {"error": f"Section '{from_section}' not found",
+                "available": [s.name or s.section_id for s in sections]}
+    if not to_node:
+        return {"error": f"Section '{to_section}' not found",
+                "available": [s.name or s.section_id for s in sections]}
+
+    boundary = _build_boundary(from_node, to_node)
+    archetype = select_archetype(boundary)
+    score = _score_boundary(boundary)
+    plan = _build_plan(boundary, archetype)
+    issues = run_all_transition_critics(boundary, plan, score)
+
+    return {
+        "boundary": boundary.to_dict(),
+        "archetype": archetype.to_dict(),
+        "score": score.to_dict(),
+        "issues": [i.to_dict() for i in issues],
+        "issue_count": len(issues),
+    }
+
+
+@mcp.tool()
+def plan_transition(
+    ctx: Context,
+    from_section: str,
+    to_section: str,
+) -> dict:
+    """Plan a transition between two sections with concrete gestures.
+
+    Selects the best archetype for the boundary and generates
+    lead-in and arrival gesture sequences.
+
+    Args:
+        from_section: Name or ID of the outgoing section.
+        to_section: Name or ID of the arriving section.
+
+    Returns: plan with archetype, gestures, payoff estimate, and issues.
+    """
+    sections = _build_sections_from_ableton(ctx)
+    from_node, to_node = _find_section_pair(sections, from_section, to_section)
+
+    if not from_node:
+        return {"error": f"Section '{from_section}' not found",
+                "available": [s.name or s.section_id for s in sections]}
+    if not to_node:
+        return {"error": f"Section '{to_section}' not found",
+                "available": [s.name or s.section_id for s in sections]}
+
+    boundary = _build_boundary(from_node, to_node)
+    plan = _build_plan(boundary)
+    score = _score_boundary(boundary)
+    issues = run_all_transition_critics(boundary, plan, score)
+
+    return {
+        "plan": plan.to_dict(),
+        "score": score.to_dict(),
+        "issues": [i.to_dict() for i in issues],
+        "issue_count": len(issues),
+        "available_archetypes": list(TRANSITION_ARCHETYPES.keys()),
+    }
+
+
+@mcp.tool()
+def score_transition(
+    ctx: Context,
+    from_section: str,
+    to_section: str,
+) -> dict:
+    """Score the transition quality between two sections.
+
+    Returns a multi-dimensional score: boundary clarity, payoff strength,
+    energy redirection, identity preservation, and cliche risk.
+
+    Args:
+        from_section: Name or ID of the outgoing section.
+        to_section: Name or ID of the arriving section.
+
+    Returns: score breakdown and overall rating.
+    """
+    sections = _build_sections_from_ableton(ctx)
+    from_node, to_node = _find_section_pair(sections, from_section, to_section)
+
+    if not from_node:
+        return {"error": f"Section '{from_section}' not found",
+                "available": [s.name or s.section_id for s in sections]}
+    if not to_node:
+        return {"error": f"Section '{to_section}' not found",
+                "available": [s.name or s.section_id for s in sections]}
+
+    boundary = _build_boundary(from_node, to_node)
+    score = _score_boundary(boundary)
+
+    return {
+        "boundary": boundary.to_dict(),
+        "score": score.to_dict(),
+    }

package/mcp_server/translation_engine/__init__.py

@@ -0,0 +1,5 @@
+"""Translation Engine V1 — playback robustness intelligence.
+
+Mono compatibility, small speaker survival, harshness risk,
+low-end stability, front-element presence. Pure computation, zero I/O.
+"""

package/mcp_server/translation_engine/critics.py

@@ -0,0 +1,297 @@
+"""Translation Engine critics — detect playback robustness issues.
+
+Five critics: mono_collapse, small_speaker, harshness,
+low_end_instability, front_element.
+All pure computation, zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import List
+
+from .models import TranslationReport
+
+
+# ── TranslationIssue ──────────────────────────────────────────────
+
+
+@dataclass
+class TranslationIssue:
+    """A single detected translation/playback issue."""
+
+    issue_type: str = ""
+    critic: str = ""
+    severity: float = 0.0  # 0-1
+    confidence: float = 0.0  # 0-1
+    evidence: str = ""
+    recommended_moves: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Mono Collapse Critic ──────────────────────────────────────────
+
+
+def run_mono_collapse_critic(
+    stereo_width: float,
+    center_strength: float,
+) -> List[TranslationIssue]:
+    """Warn if stereo width > 0.7 and center strength < 0.4.
+
+    A wide mix with weak center will lose significant content
+    when summed to mono.
+    """
+    issues: List[TranslationIssue] = []
+
+    if stereo_width > 0.7 and center_strength < 0.4:
+        severity = min(1.0, (stereo_width - 0.5) * (0.5 - center_strength) * 4.0)
+        issues.append(TranslationIssue(
+            issue_type="mono_collapse",
+            critic="mono_collapse",
+            severity=max(0.0, severity),
+            confidence=0.7,
+            evidence=(
+                f"Stereo width {stereo_width:.2f} with center strength "
+                f"{center_strength:.2f} — mono playback will lose "
+                f"significant stereo content"
+            ),
+            recommended_moves=["narrow_stereo_width", "strengthen_center"],
+        ))
+
+    return issues
+
+
+# ── Small Speaker Critic ──────────────────────────────────────────
+
+
+def run_small_speaker_critic(
+    sub_energy: float,
+    low_energy: float,
+) -> List[TranslationIssue]:
+    """Warn if sub-bass dominates the low-end balance.
+
+    If sub_energy > 0.5 of total low-end (sub + low), small speakers
+    will lose the foundation because they cannot reproduce sub frequencies.
+    """
+    issues: List[TranslationIssue] = []
+    total_low = sub_energy + low_energy
+
+    if total_low > 0 and sub_energy / total_low > 0.5:
+        sub_ratio = sub_energy / total_low
+        severity = min(1.0, (sub_ratio - 0.5) * 4.0)
+        issues.append(TranslationIssue(
+            issue_type="small_speaker_loss",
+            critic="small_speaker",
+            severity=max(0.0, severity),
+            confidence=0.65,
+            evidence=(
+                f"Sub energy {sub_energy:.2f} is {sub_ratio:.0%} of total "
+                f"low-end ({total_low:.2f}) — small speakers will lose "
+                f"the low-end foundation"
+            ),
+            recommended_moves=["add_harmonics_to_bass", "reduce_sub_energy"],
+        ))
+
+    return issues
+
+
+# ── Harshness Critic ──────────────────────────────────────────────
+
+
+def run_harshness_critic(
+    high_energy: float,
+    presence_energy: float,
+) -> List[TranslationIssue]:
+    """Warn if combined high + presence energy exceeds 0.75.
+
+    Excessive brightness causes listening fatigue, especially on
+    earbuds and small speakers with boosted treble response.
+    """
+    issues: List[TranslationIssue] = []
+    combined = high_energy + presence_energy
+
+    if combined > 0.75:
+        severity = min(1.0, (combined - 0.75) * 4.0)
+        issues.append(TranslationIssue(
+            issue_type="harshness_risk",
+            critic="harshness",
+            severity=max(0.0, severity),
+            confidence=0.6,
+            evidence=(
+                f"High energy {high_energy:.2f} + presence energy "
+                f"{presence_energy:.2f} = {combined:.2f} — "
+                f"likely harsh on earbuds and small speakers"
+            ),
+            recommended_moves=["reduce_high_shelf", "tame_presence_peak"],
+        ))
+
+    return issues
+
+
+# ── Low End Instability Critic ────────────────────────────────────
+
+
+def run_low_end_instability_critic(
+    sub_energy: float,
+    low_mid_energy: float,
+) -> List[TranslationIssue]:
+    """Warn if sub and low-mid energies are competing.
+
+    When both are high, they create muddiness and masking in
+    the low-frequency range.
+    """
+    issues: List[TranslationIssue] = []
+
+    if sub_energy > 0.4 and low_mid_energy > 0.4:
+        severity = min(1.0, (sub_energy + low_mid_energy - 0.8) * 2.5)
+        issues.append(TranslationIssue(
+            issue_type="low_end_instability",
+            critic="low_end_instability",
+            severity=max(0.0, severity),
+            confidence=0.6,
+            evidence=(
+                f"Sub energy {sub_energy:.2f} and low-mid energy "
+                f"{low_mid_energy:.2f} are both high — "
+                f"competing low frequencies cause muddiness"
+            ),
+            recommended_moves=["high_pass_non_bass", "eq_low_mid_cut"],
+        ))
+
+    return issues
+
+
+# ── Front Element Critic ──────────────────────────────────────────
+
+
+def run_front_element_critic(
+    has_foreground: bool,
+    foreground_masked: bool,
+) -> List[TranslationIssue]:
+    """Warn if lead/vocal is absent or buried.
+
+    The front element (vocal, lead synth, melody) must remain
+    present and unmasked for the mix to translate.
+    """
+    issues: List[TranslationIssue] = []
+
+    if not has_foreground:
+        issues.append(TranslationIssue(
+            issue_type="no_front_element",
+            critic="front_element",
+            severity=0.7,
+            confidence=0.5,
+            evidence="No foreground element detected — mix lacks a focal point",
+            recommended_moves=["add_lead_element", "boost_vocal"],
+        ))
+
+    if has_foreground and foreground_masked:
+        issues.append(TranslationIssue(
+            issue_type="front_element_masked",
+            critic="front_element",
+            severity=0.6,
+            confidence=0.6,
+            evidence=(
+                "Foreground element is present but masked — "
+                "lead/vocal is buried in the mix"
+            ),
+            recommended_moves=["eq_pocket_for_vocal", "reduce_competing_mids"],
+        ))
+
+    return issues
+
+
+# ── Run all translation critics ───────────────────────────────────
+
+
+def run_all_translation_critics(mix_snapshot: dict) -> List[TranslationIssue]:
+    """Run all 5 translation critics against a mix snapshot.
+
+    Expected mix_snapshot keys:
+        stereo_width: float (0-1)
+        center_strength: float (0-1)
+        sub_energy: float (0-1)
+        low_energy: float (0-1)
+        low_mid_energy: float (0-1)
+        high_energy: float (0-1)
+        presence_energy: float (0-1)
+        has_foreground: bool
+        foreground_masked: bool
+    """
+    issues: List[TranslationIssue] = []
+
+    issues.extend(run_mono_collapse_critic(
+        stereo_width=mix_snapshot.get("stereo_width", 0.0),
+        center_strength=mix_snapshot.get("center_strength", 0.5),
+    ))
+
+    issues.extend(run_small_speaker_critic(
+        sub_energy=mix_snapshot.get("sub_energy", 0.0),
+        low_energy=mix_snapshot.get("low_energy", 0.0),
+    ))
+
+    issues.extend(run_harshness_critic(
+        high_energy=mix_snapshot.get("high_energy", 0.0),
+        presence_energy=mix_snapshot.get("presence_energy", 0.0),
+    ))
+
+    issues.extend(run_low_end_instability_critic(
+        sub_energy=mix_snapshot.get("sub_energy", 0.0),
+        low_mid_energy=mix_snapshot.get("low_mid_energy", 0.0),
+    ))
+
+    issues.extend(run_front_element_critic(
+        has_foreground=mix_snapshot.get("has_foreground", True),
+        foreground_masked=mix_snapshot.get("foreground_masked", False),
+    ))
+
+    return issues
+
+
+# ── Build TranslationReport ───────────────────────────────────────
+
+
+def build_translation_report(mix_snapshot: dict) -> TranslationReport:
+    """Run all critics and compile a TranslationReport."""
+    issues = run_all_translation_critics(mix_snapshot)
+
+    # Classify booleans from issues
+    mono_safe = not any(i.issue_type == "mono_collapse" for i in issues)
+    small_speaker_safe = not any(i.issue_type == "small_speaker_loss" for i in issues)
+    harshness = max(
+        (i.severity for i in issues if i.issue_type == "harshness_risk"),
+        default=0.0,
+    )
+    low_end_stable = not any(i.issue_type == "low_end_instability" for i in issues)
+    front_element_present = not any(
+        i.issue_type in ("no_front_element", "front_element_masked")
+        for i in issues
+    )
+
+    # Collect all suggested moves
+    all_moves: list[str] = []
+    for issue in issues:
+        for move in issue.recommended_moves:
+            if move not in all_moves:
+                all_moves.append(move)
+
+    # Overall robustness classification
+    max_severity = max((i.severity for i in issues), default=0.0)
+    if max_severity >= 0.7 or len(issues) >= 3:
+        overall = "critical"
+    elif max_severity >= 0.4 or len(issues) >= 2:
+        overall = "fragile"
+    else:
+        overall = "robust"
+
+    return TranslationReport(
+        mono_safe=mono_safe,
+        small_speaker_safe=small_speaker_safe,
+        harshness_risk=harshness,
+        low_end_stable=low_end_stable,
+        front_element_present=front_element_present,
+        overall_robustness=overall,
+        issues=[i.to_dict() for i in issues],
+        suggested_moves=all_moves,
+    )

package/mcp_server/translation_engine/models.py

@@ -0,0 +1,27 @@
+"""Translation Engine models — all dataclasses with to_dict().
+
+Pure data structures for playback robustness analysis.
+Zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import List
+
+
+@dataclass
+class TranslationReport:
+    """Full playback robustness report."""
+
+    mono_safe: bool = True
+    small_speaker_safe: bool = True
+    harshness_risk: float = 0.0  # 0-1
+    low_end_stable: bool = True
+    front_element_present: bool = True
+    overall_robustness: str = "robust"  # "robust", "fragile", "critical"
+    issues: List[dict] = field(default_factory=list)
+    suggested_moves: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)

package/mcp_server/translation_engine/tools.py

@@ -0,0 +1,74 @@
+"""Translation Engine MCP tools — 2 tools for playback robustness.
+
+Each tool fetches data from Ableton via the shared connection,
+then delegates to pure-computation critics.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import Context
+
+from ..server import mcp
+from .critics import build_translation_report, run_all_translation_critics
+
+
+# ── Helpers ─────────────────────────────────────────────────────────
+
+
+def _fetch_translation_data(ctx: Context) -> dict:
+    """Fetch mix snapshot data needed for translation analysis."""
+    ableton = ctx.lifespan_context["ableton"]
+
+    # Get mix snapshot — contains spectral and stereo info
+    snapshot = {}
+    try:
+        snapshot = ableton.send_command("get_mix_snapshot", {})
+    except Exception:
+        pass
+
+    # Extract spectral bands from snapshot
+    spectrum = snapshot.get("spectrum", {})
+    stereo = snapshot.get("stereo", {})
+
+    return {
+        "stereo_width": stereo.get("side_activity", 0.0),
+        "center_strength": stereo.get("center_strength", 0.5),
+        "sub_energy": spectrum.get("sub", 0.0),
+        "low_energy": spectrum.get("low", 0.0),
+        "low_mid_energy": spectrum.get("low_mid", 0.0),
+        "high_energy": spectrum.get("high", 0.0),
+        "presence_energy": spectrum.get("presence", 0.0),
+        "has_foreground": snapshot.get("has_foreground", True),
+        "foreground_masked": snapshot.get("foreground_masked", False),
+    }
+
+
+# ── MCP Tools ───────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def check_translation(ctx: Context) -> dict:
+    """Check playback robustness — mono safety, small speakers, harshness.
+
+    Returns a full translation report with robustness classification
+    (robust/fragile/critical), boolean safety flags, and suggested
+    corrective moves.
+    """
+    mix_snapshot = _fetch_translation_data(ctx)
+    report = build_translation_report(mix_snapshot)
+    return report.to_dict()
+
+
+@mcp.tool()
+def get_translation_issues(ctx: Context) -> dict:
+    """Get just the translation issues without the full report.
+
+    Lighter than check_translation — returns only detected issues
+    from the 5 playback robustness critics.
+    """
+    mix_snapshot = _fetch_translation_data(ctx)
+    issues = run_all_translation_critics(mix_snapshot)
+    return {
+        "issues": [i.to_dict() for i in issues],
+        "issue_count": len(issues),
+    }