livepilot 1.9.13 → 1.9.15

package/mcp_server/mix_engine/state_builder.py

@@ -0,0 +1,316 @@
+"""State builder — construct MixState from session data.
+
+Pure computation, zero I/O.  MCP tool wrappers fetch data from Ableton
+and pass it here.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional
+
+from .models import (
+    BalanceState,
+    DepthState,
+    DynamicsState,
+    MaskingEntry,
+    MaskingMap,
+    MixState,
+    StereoState,
+    TrackMixState,
+)
+
+
+# Roles considered "anchor" — should be prominent in the mix.
+_ANCHOR_ROLES = frozenset({"kick", "bass", "vocal", "lead", "drums"})
+
+# Frequency bands where masking is most problematic.
+_MASKING_BANDS = ("sub", "low", "low_mid", "mid", "high_mid", "presence", "high")
+
+
+# ── Balance ─────────────────────────────────────────────────────────
+
+
+def build_balance_state(
+    track_infos: list[dict],
+    role_hints: Optional[dict[int, str]] = None,
+) -> BalanceState:
+    """Build BalanceState from track info dicts.
+
+    Args:
+        track_infos: list of dicts from get_track_info (Remote Script format).
+                     Volume/panning are nested under "mixer", sends under "sends".
+        role_hints: optional {track_index: role_name} overrides.
+    """
+    from ..tools._agent_os_engine import infer_track_role
+
+    role_hints = role_hints or {}
+    states: list[TrackMixState] = []
+    anchor_indices: list[int] = []
+    loudest_idx = -1
+    quietest_idx = -1
+    loudest_vol = -math.inf
+    quietest_vol = math.inf
+
+    for info in track_infos:
+        idx = info.get("index", 0)
+        name = info.get("name", "")
+        # Infer role from track name if no explicit hint
+        role = role_hints.get(idx, infer_track_role(name))
+        # Extract mixer values from nested Remote Script response
+        mixer = info.get("mixer", {})
+        vol = mixer.get("volume", 0.0) if mixer else info.get("volume", 0.0)
+        pan = mixer.get("panning", 0.0) if mixer else info.get("pan", 0.0)
+        # Extract send levels from sends array
+        sends_raw = info.get("sends", [])
+        send_levels = [s.get("value", 0.0) for s in sends_raw] if sends_raw else []
+
+        ts = TrackMixState(
+            track_index=idx,
+            name=name,
+            role=role,
+            volume=vol,
+            pan=pan,
+            mute=info.get("mute", False),
+            solo=info.get("solo", False),
+            send_levels=send_levels,
+        )
+        states.append(ts)
+
+        if role in _ANCHOR_ROLES:
+            anchor_indices.append(idx)
+
+        if not ts.mute:
+            if vol > loudest_vol:
+                loudest_vol = vol
+                loudest_idx = idx
+            if vol < quietest_vol:
+                quietest_vol = vol
+                quietest_idx = idx
+
+    return BalanceState(
+        track_states=states,
+        anchor_tracks=anchor_indices,
+        loudest_track=loudest_idx,
+        quietest_track=quietest_idx,
+    )
+
+
+# ── Masking ─────────────────────────────────────────────────────────
+
+
+def build_masking_map(
+    spectrum: Optional[dict],
+    track_roles: Optional[dict[int, str]] = None,
+) -> MaskingMap:
+    """Build MaskingMap from spectrum data.
+
+    Uses per-track spectrum bands if available, otherwise returns empty.
+    Spectrum shape: {"tracks": {track_idx_str: {band: value, ...}, ...}}
+    or flat {"bands": {band: value}} for master-only.
+
+    For Phase 1 we detect masking heuristically from role collisions
+    in known problem bands (kick/bass in sub/low, bass/chords in low_mid).
+    """
+    entries: list[MaskingEntry] = []
+    track_roles = track_roles or {}
+
+    if not spectrum or not track_roles:
+        return MaskingMap(entries=[], worst_pair=None)
+
+    # Build role->indices mapping
+    role_to_indices: dict[str, list[int]] = {}
+    for idx, role in track_roles.items():
+        role_to_indices.setdefault(role, []).append(idx)
+
+    # Known problematic role pairs and their collision bands
+    collision_rules: list[tuple[str, str, str, float]] = [
+        ("kick", "bass", "sub", 0.7),
+        ("kick", "bass", "low", 0.6),
+        ("bass", "chords", "low_mid", 0.5),
+        ("bass", "keys", "low_mid", 0.5),
+        ("vocal", "lead", "presence", 0.4),
+        ("vocal", "lead", "high_mid", 0.4),
+        ("lead", "synth", "mid", 0.3),
+        ("chords", "pad", "mid", 0.3),
+    ]
+
+    for role_a, role_b, band, base_severity in collision_rules:
+        indices_a = role_to_indices.get(role_a, [])
+        indices_b = role_to_indices.get(role_b, [])
+        for ia in indices_a:
+            for ib in indices_b:
+                if ia != ib:
+                    entries.append(MaskingEntry(
+                        track_a=ia,
+                        track_b=ib,
+                        overlap_band=band,
+                        severity=base_severity,
+                    ))
+
+    worst = None
+    if entries:
+        worst_entry = max(entries, key=lambda e: e.severity)
+        worst = (worst_entry.track_a, worst_entry.track_b)
+
+    return MaskingMap(entries=entries, worst_pair=worst)
+
+
+# ── Dynamics ────────────────────────────────────────────────────────
+
+
+def build_dynamics_state(
+    rms: Optional[float],
+    peak: Optional[float],
+) -> DynamicsState:
+    """Build DynamicsState from RMS and peak values.
+
+    Args:
+        rms: master RMS level in linear (0-1) or dB.
+        peak: master peak level in linear (0-1) or dB.
+    """
+    if rms is None or peak is None or rms <= 0:
+        return DynamicsState(crest_factor_db=0.0, over_compressed=False, headroom=0.0)
+
+    # If values look like they're in dB (negative), convert to linear
+    if rms < 0:
+        rms_linear = 10 ** (rms / 20.0)
+        peak_linear = 10 ** ((peak or 0) / 20.0)
+    else:
+        rms_linear = rms
+        peak_linear = peak if peak else rms
+
+    if rms_linear <= 0:
+        return DynamicsState(crest_factor_db=0.0, over_compressed=False, headroom=0.0)
+
+    crest = 20 * math.log10(max(peak_linear, 1e-10) / max(rms_linear, 1e-10))
+
+    # Over-compressed when crest factor < 6 dB (flat dynamics)
+    over_compressed = crest < 6.0
+
+    # Headroom = distance from peak to 0 dBFS
+    if peak_linear > 0:
+        headroom = -20 * math.log10(max(peak_linear, 1e-10))
+    else:
+        headroom = 100.0  # effectively infinite headroom
+
+    return DynamicsState(
+        crest_factor_db=round(crest, 2),
+        over_compressed=over_compressed,
+        headroom=round(headroom, 2),
+    )
+
+
+# ── Composite builder ──────────────────────────────────────────────
+
+
+def build_mix_state(
+    session_info: Optional[dict] = None,
+    track_infos: Optional[list[dict]] = None,
+    spectrum: Optional[dict] = None,
+    rms_data: Optional[float] = None,
+    role_hints: Optional[dict[int, str]] = None,
+) -> MixState:
+    """Build a full MixState from session data.
+
+    Args:
+        session_info: session-level info (tempo, etc.) — reserved for future.
+        track_infos: per-track info dicts.
+        spectrum: spectrum data (master or per-track).
+        rms_data: master RMS value.
+        role_hints: {track_index: role_str} overrides.
+    """
+    track_infos = track_infos or []
+    role_hints = role_hints or {}
+
+    balance = build_balance_state(track_infos, role_hints)
+    masking = build_masking_map(spectrum, role_hints)
+
+    # Extract peak from spectrum if available
+    peak = None
+    if spectrum:
+        peak = spectrum.get("peak")
+
+    dynamics = build_dynamics_state(rms_data, peak)
+
+    # Stereo and depth require per-track analysis not yet available.
+    # Build from track send levels as a proxy.
+    stereo = _build_stereo_from_tracks(balance.track_states)
+    depth = _build_depth_from_tracks(balance.track_states)
+
+    return MixState(
+        balance=balance,
+        masking=masking,
+        dynamics=dynamics,
+        stereo=stereo,
+        depth=depth,
+    )
+
+
+# ── Internal helpers ────────────────────────────────────────────────
+
+
+def _build_stereo_from_tracks(tracks: list[TrackMixState]) -> StereoState:
+    """Estimate stereo field from pan positions."""
+    if not tracks:
+        return StereoState(center_strength=1.0, side_activity=0.0, mono_risk=False)
+
+    center_count = 0
+    total_side = 0.0
+    active = [t for t in tracks if not t.mute]
+
+    if not active:
+        return StereoState(center_strength=1.0, side_activity=0.0, mono_risk=False)
+
+    for t in active:
+        if abs(t.pan) < 0.1:
+            center_count += 1
+        total_side += abs(t.pan)
+
+    center_strength = center_count / len(active)
+    side_activity = total_side / len(active)
+
+    # Mono risk: everything is centered
+    mono_risk = center_strength > 0.85 and side_activity < 0.05
+
+    return StereoState(
+        center_strength=round(center_strength, 3),
+        side_activity=round(side_activity, 3),
+        mono_risk=mono_risk,
+    )
+
+
+def _build_depth_from_tracks(tracks: list[TrackMixState]) -> DepthState:
+    """Estimate depth from send levels (reverb/delay sends)."""
+    if not tracks:
+        return DepthState(wet_dry_ratio=0.0, depth_separation=0.0, wash_risk=False)
+
+    active = [t for t in tracks if not t.mute]
+    if not active:
+        return DepthState(wet_dry_ratio=0.0, depth_separation=0.0, wash_risk=False)
+
+    total_send = 0.0
+    send_values: list[float] = []
+
+    for t in active:
+        avg_send = sum(t.send_levels) / max(len(t.send_levels), 1) if t.send_levels else 0.0
+        total_send += avg_send
+        send_values.append(avg_send)
+
+    avg_wet = total_send / len(active)
+
+    # Depth separation: variance in send levels
+    if len(send_values) > 1:
+        mean = sum(send_values) / len(send_values)
+        variance = sum((v - mean) ** 2 for v in send_values) / len(send_values)
+        depth_sep = math.sqrt(variance)
+    else:
+        depth_sep = 0.0
+
+    wash_risk = avg_wet > 0.6
+
+    return DepthState(
+        wet_dry_ratio=round(avg_wet, 3),
+        depth_separation=round(depth_sep, 3),
+        wash_risk=wash_risk,
+    )

package/mcp_server/mix_engine/tools.py

@@ -0,0 +1,214 @@
+"""Mix Engine MCP tools — 6 tools for mix analysis and move planning.
+
+Each tool fetches data from Ableton via the shared connection,
+then delegates to pure-computation modules.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import Context
+
+from ..server import mcp
+from ..tools._evaluation_contracts import EvaluationRequest
+from ..tools._snapshot_normalizer import normalize_sonic_snapshot
+from ..evaluation.fabric import evaluate_sonic_move
+from .state_builder import build_mix_state
+from .critics import run_all_mix_critics
+from .planner import plan_mix_moves
+
+
+# ── Helpers ─────────────────────────────────────────────────────────
+
+
+def _fetch_mix_data(ctx: Context) -> dict:
+    """Fetch all data needed to build a MixState from Ableton."""
+    ableton = ctx.lifespan_context["ableton"]
+
+    session_info = ableton.send_command("get_session_info", {})
+    track_count = session_info.get("track_count", 0)
+
+    track_infos: list[dict] = []
+    for i in range(track_count):
+        try:
+            info = ableton.send_command("get_track_info", {"track_index": i})
+            track_infos.append(info)
+        except Exception:
+            continue
+
+    # Try to get spectrum and RMS data
+    spectrum = None
+    rms_data = None
+    try:
+        spectrum = ableton.send_command("get_master_spectrum", {})
+    except Exception:
+        pass
+    try:
+        rms_result = ableton.send_command("get_master_rms", {})
+        rms_data = rms_result.get("rms") if isinstance(rms_result, dict) else None
+    except Exception:
+        pass
+
+    return {
+        "session_info": session_info,
+        "track_infos": track_infos,
+        "spectrum": spectrum,
+        "rms_data": rms_data,
+    }
+
+
+# ── MCP Tools ───────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def analyze_mix(ctx: Context) -> dict:
+    """Build full mix state and run all critics.
+
+    Returns the complete mix analysis including all sub-states
+    (balance, masking, dynamics, stereo, depth) and all detected issues.
+    """
+    data = _fetch_mix_data(ctx)
+    mix_state = build_mix_state(
+        session_info=data["session_info"],
+        track_infos=data["track_infos"],
+        spectrum=data["spectrum"],
+        rms_data=data["rms_data"],
+    )
+    issues = run_all_mix_critics(mix_state)
+    moves = plan_mix_moves(issues, mix_state)
+
+    return {
+        "mix_state": mix_state.to_dict(),
+        "issues": [i.to_dict() for i in issues],
+        "suggested_moves": [m.to_dict() for m in moves],
+        "issue_count": len(issues),
+        "move_count": len(moves),
+    }
+
+
+@mcp.tool()
+def get_mix_issues(ctx: Context) -> dict:
+    """Run all mix critics and return detected issues only.
+
+    Lighter than analyze_mix — skips move planning.
+    """
+    data = _fetch_mix_data(ctx)
+    mix_state = build_mix_state(
+        session_info=data["session_info"],
+        track_infos=data["track_infos"],
+        spectrum=data["spectrum"],
+        rms_data=data["rms_data"],
+    )
+    issues = run_all_mix_critics(mix_state)
+
+    return {
+        "issues": [i.to_dict() for i in issues],
+        "issue_count": len(issues),
+    }
+
+
+@mcp.tool()
+def plan_mix_move(ctx: Context) -> dict:
+    """Get ranked move suggestions based on current mix issues.
+
+    Runs critics and planner, returns sorted moves with
+    estimated impact and risk scores.
+    """
+    data = _fetch_mix_data(ctx)
+    mix_state = build_mix_state(
+        session_info=data["session_info"],
+        track_infos=data["track_infos"],
+        spectrum=data["spectrum"],
+        rms_data=data["rms_data"],
+    )
+    issues = run_all_mix_critics(mix_state)
+    moves = plan_mix_moves(issues, mix_state)
+
+    return {
+        "moves": [m.to_dict() for m in moves],
+        "move_count": len(moves),
+        "issue_count": len(issues),
+    }
+
+
+@mcp.tool()
+def evaluate_mix_move(
+    ctx: Context,
+    before_snapshot: dict,
+    after_snapshot: dict,
+    targets: dict | None = None,
+    protect: dict | None = None,
+) -> dict:
+    """Score a mix change using the evaluation fabric.
+
+    Compare before/after spectral snapshots and evaluate whether
+    the mix move improved the targeted dimensions without harming
+    protected ones.
+
+    Args:
+        before_snapshot: Spectral snapshot before the move.
+        after_snapshot: Spectral snapshot after the move.
+        targets: Goal targets {dimension: weight} (e.g. {"clarity": 0.5}).
+        protect: Protected dimensions {dimension: threshold}.
+    """
+    targets = targets or {}
+    protect = protect or {}
+
+    request = EvaluationRequest(
+        engine="mix_engine",
+        goal={"targets": targets},
+        before=before_snapshot,
+        after=after_snapshot,
+        protect=protect,
+    )
+    result = evaluate_sonic_move(request)
+    return result.to_dict()
+
+
+@mcp.tool()
+def get_masking_report(ctx: Context) -> dict:
+    """Get detailed frequency collision report.
+
+    Shows all detected masking pairs, severity, and the
+    worst collision pair.
+    """
+    data = _fetch_mix_data(ctx)
+    mix_state = build_mix_state(
+        session_info=data["session_info"],
+        track_infos=data["track_infos"],
+        spectrum=data["spectrum"],
+        rms_data=data["rms_data"],
+    )
+    masking = mix_state.masking
+
+    return {
+        "masking": masking.to_dict(),
+        "collision_count": len(masking.entries),
+        "worst_pair": list(masking.worst_pair) if masking.worst_pair else None,
+    }
+
+
+@mcp.tool()
+def get_mix_summary(ctx: Context) -> dict:
+    """Lightweight mix overview — track count, issue count, dynamics state.
+
+    Faster than full analysis for quick status checks.
+    """
+    data = _fetch_mix_data(ctx)
+    mix_state = build_mix_state(
+        session_info=data["session_info"],
+        track_infos=data["track_infos"],
+        spectrum=data["spectrum"],
+        rms_data=data["rms_data"],
+    )
+    issues = run_all_mix_critics(mix_state)
+
+    return {
+        "track_count": len(mix_state.balance.track_states),
+        "issue_count": len(issues),
+        "dynamics": mix_state.dynamics.to_dict(),
+        "stereo": mix_state.stereo.to_dict(),
+        "depth": mix_state.depth.to_dict(),
+        "anchor_tracks": mix_state.balance.anchor_tracks,
+        "loudest_track": mix_state.balance.loudest_track,
+        "quietest_track": mix_state.balance.quietest_track,
+    }

package/mcp_server/performance_engine/__init__.py

@@ -0,0 +1 @@
+"""Performance Engine V1 — live-safe mode, scene steering, safety policies."""

package/mcp_server/performance_engine/models.py

@@ -0,0 +1,148 @@
+"""Performance Engine state models — all dataclasses with to_dict().
+
+Pure data structures for live performance mode:
+SceneRole, EnergyWindow, LiveSafeMove, HandoffPlan, PerformanceState.
+
+Zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+
+# ── Valid values ──────────────────────────────────────────────────────
+
+VALID_ROLES = frozenset({
+    "intro", "verse", "chorus", "build", "drop",
+    "breakdown", "outro", "transition",
+})
+
+VALID_RISK_LEVELS = frozenset({"safe", "caution", "blocked"})
+
+VALID_DIRECTIONS = frozenset({"up", "down", "hold"})
+
+
+# ── SceneRole ─────────────────────────────────────────────────────────
+
+
+@dataclass
+class SceneRole:
+    """A scene's structural role and energy level."""
+
+    scene_index: int = 0
+    name: str = ""
+    energy_level: float = 0.5
+    role: str = "verse"
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.energy_level <= 1.0:
+            raise ValueError(
+                f"energy_level must be 0.0-1.0, got {self.energy_level}"
+            )
+        if self.role not in VALID_ROLES:
+            raise ValueError(
+                f"role must be one of {sorted(VALID_ROLES)}, got {self.role!r}"
+            )
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── EnergyWindow ──────────────────────────────────────────────────────
+
+
+@dataclass
+class EnergyWindow:
+    """Current energy state and steering intent."""
+
+    current_energy: float = 0.5
+    target_energy: float = 0.5
+    direction: str = "hold"
+    urgency: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.current_energy <= 1.0:
+            raise ValueError(
+                f"current_energy must be 0.0-1.0, got {self.current_energy}"
+            )
+        if not 0.0 <= self.target_energy <= 1.0:
+            raise ValueError(
+                f"target_energy must be 0.0-1.0, got {self.target_energy}"
+            )
+        if self.direction not in VALID_DIRECTIONS:
+            raise ValueError(
+                f"direction must be one of {sorted(VALID_DIRECTIONS)}, "
+                f"got {self.direction!r}"
+            )
+        if not 0.0 <= self.urgency <= 1.0:
+            raise ValueError(
+                f"urgency must be 0.0-1.0, got {self.urgency}"
+            )
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── LiveSafeMove ──────────────────────────────────────────────────────
+
+
+@dataclass
+class LiveSafeMove:
+    """A single performance-safe move suggestion."""
+
+    move_type: str = ""
+    target: str = ""
+    description: str = ""
+    risk_level: str = "safe"
+    parameters: dict = field(default_factory=dict)
+    reversible: bool = True
+
+    def __post_init__(self) -> None:
+        if self.risk_level not in VALID_RISK_LEVELS:
+            raise ValueError(
+                f"risk_level must be one of {sorted(VALID_RISK_LEVELS)}, "
+                f"got {self.risk_level!r}"
+            )
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── HandoffPlan ───────────────────────────────────────────────────────
+
+
+@dataclass
+class HandoffPlan:
+    """Transition plan from one scene to another."""
+
+    from_scene: int = 0
+    to_scene: int = 0
+    gestures: list[dict] = field(default_factory=list)
+    energy_path: list[float] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── PerformanceState ──────────────────────────────────────────────────
+
+
+@dataclass
+class PerformanceState:
+    """Top-level container for live performance state."""
+
+    scenes: list[SceneRole] = field(default_factory=list)
+    current_scene: int = 0
+    energy_window: EnergyWindow = field(default_factory=EnergyWindow)
+    safe_moves: list[LiveSafeMove] = field(default_factory=list)
+    blocked_moves: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "scenes": [s.to_dict() for s in self.scenes],
+            "current_scene": self.current_scene,
+            "energy_window": self.energy_window.to_dict(),
+            "safe_moves": [m.to_dict() for m in self.safe_moves],
+            "blocked_moves": list(self.blocked_moves),
+        }