livepilot 1.9.13 → 1.9.15

package/mcp_server/project_brain/role_graph.py

@@ -0,0 +1,103 @@
+"""Role graph builder — infers musical function per track per section.
+
+Reuses _composition_engine.build_role_graph and infer_role_for_track
+for the heavy inference, then converts composition RoleNodes to brain
+RoleNodes and computes an overall confidence summary.
+
+Pure computation, zero I/O.
+"""
+
+from __future__ import annotations
+
+from ..tools._composition_engine import (
+    SectionNode as CESectionNode,
+    SectionType as CESectionType,
+    build_role_graph as _ce_build_role_graph,
+)
+from .models import ConfidenceInfo, RoleGraph, RoleNode
+
+
+def build_role_graph(
+    sections: list[dict],
+    track_data: list[dict],
+    notes_map: dict[str, dict[int, list[dict]]],
+) -> RoleGraph:
+    """Build a RoleGraph from brain sections, track data, and note data.
+
+    Args:
+        sections: list of brain SectionNode.to_dict() or raw dicts with
+            section_id, start_bar, end_bar, section_type, energy, density.
+        track_data: [{index, name, devices: [{class_name, ...}]}].
+        notes_map: {section_id: {track_index: [notes]}}.
+
+    Returns:
+        RoleGraph with role assignments and overall confidence.
+    """
+    graph = RoleGraph()
+
+    if not sections or not track_data:
+        return graph
+
+    # Convert brain section dicts to composition-engine SectionNodes
+    ce_sections = []
+    for sec in sections:
+        # Determine which tracks are active in this section
+        # If notes_map has data for this section, those tracks are active
+        section_id = sec.get("section_id", sec.get("id", ""))
+        active_tracks = []
+        section_notes = notes_map.get(section_id, {})
+        for t_idx, notes in section_notes.items():
+            if notes:
+                active_tracks.append(t_idx)
+
+        # Also include all tracks if no notes data (assume all active)
+        if not active_tracks and not notes_map:
+            active_tracks = [t.get("index", 0) for t in track_data]
+
+        try:
+            stype = CESectionType(sec.get("section_type", "unknown"))
+        except ValueError:
+            stype = CESectionType.UNKNOWN
+
+        ce_sections.append(CESectionNode(
+            section_id=section_id,
+            start_bar=sec.get("start_bar", 0),
+            end_bar=sec.get("end_bar", 0),
+            section_type=stype,
+            confidence=sec.get("confidence", 0.5),
+            energy=sec.get("energy", 0.0),
+            density=sec.get("density", 0.0),
+            tracks_active=active_tracks,
+        ))
+
+    # Delegate to composition engine
+    ce_roles = _ce_build_role_graph(ce_sections, track_data, notes_map)
+
+    # Convert composition RoleNodes -> brain RoleNodes
+    low_confidence_nodes = []
+    confidence_sum = 0.0
+
+    for ce_role in ce_roles:
+        brain_role = RoleNode(
+            track_index=ce_role.track_index,
+            section_id=ce_role.section_id,
+            role=ce_role.role.value if hasattr(ce_role.role, "value") else str(ce_role.role),
+            confidence=ce_role.confidence,
+            foreground=ce_role.foreground,
+        )
+        graph.add_role(brain_role)
+        confidence_sum += ce_role.confidence
+
+        if ce_role.confidence < 0.5:
+            low_confidence_nodes.append(
+                f"t{ce_role.track_index}@{ce_role.section_id}"
+            )
+
+    # Compute overall confidence
+    overall = confidence_sum / max(len(ce_roles), 1)
+    graph.confidence = ConfidenceInfo(
+        overall=round(overall, 3),
+        low_confidence_nodes=low_confidence_nodes,
+    )
+
+    return graph

package/mcp_server/project_brain/session_graph.py

@@ -0,0 +1,51 @@
+"""Session graph builder — transforms raw get_session_info into SessionGraph.
+
+Pure computation, zero I/O.
+"""
+
+from __future__ import annotations
+
+from .models import FreshnessInfo, SessionGraph, TrackNode
+
+
+def build_session_graph(session_info: dict) -> SessionGraph:
+    """Build a SessionGraph from raw get_session_info output.
+
+    Args:
+        session_info: dict from Ableton's get_session_info command.
+
+    Returns:
+        Populated SessionGraph with freshness marked fresh (revision 0).
+    """
+    graph = SessionGraph()
+
+    # Tracks
+    for raw in session_info.get("tracks", []):
+        track = TrackNode(
+            index=raw.get("index", 0),
+            name=raw.get("name", ""),
+            has_midi=raw.get("has_midi_input", False) or raw.get("has_midi", False),
+            has_audio=raw.get("has_audio_input", False) or raw.get("has_audio", False),
+            mute=raw.get("mute", False),
+            solo=raw.get("solo", False),
+            arm=raw.get("arm", False),
+            group_index=raw.get("group_track_index", None),
+        )
+        graph.add_track(track)
+
+    # Return tracks
+    graph.return_tracks = session_info.get("return_tracks", [])
+
+    # Scenes
+    graph.scenes = session_info.get("scenes", [])
+
+    # Tempo & time signature
+    graph.tempo = session_info.get("tempo", 120.0)
+    ts_num = session_info.get("time_signature_numerator", 4)
+    ts_den = session_info.get("time_signature_denominator", 4)
+    graph.time_signature = f"{ts_num}/{ts_den}"
+
+    # Mark fresh
+    graph.freshness.mark_fresh(revision=0)
+
+    return graph

package/mcp_server/project_brain/tools.py

@@ -0,0 +1,144 @@
+"""Project Brain MCP tools — build and query the shared state substrate.
+
+2 tools:
+  build_project_brain — full build from live Ableton session
+  get_project_brain_summary — lightweight summary without full rebuild
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+from .builder import build_project_state_from_data
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+@mcp.tool()
+def build_project_brain(ctx: Context) -> dict:
+    """Build a full Project Brain snapshot from the current Ableton session.
+
+    Gathers session info, scenes, clip matrix, track infos with device data,
+    builds all five subgraphs (session, arrangement, role, automation,
+    capability), and returns the canonical project state.
+
+    This is the primary entry point for engines that need a coherent view
+    of the project. Call once at session start, then use scoped refreshes.
+    """
+    ableton = _get_ableton(ctx)
+
+    # 1. Get session info
+    session_info = ableton.send_command("get_session_info")
+    tracks = session_info.get("tracks", [])
+
+    # 2. Get scenes info
+    scenes = []
+    try:
+        scenes_resp = ableton.send_command("get_scenes_info")
+        scenes = scenes_resp.get("scenes", [])
+    except Exception:
+        scenes = session_info.get("scenes", [])
+
+    # 3. Get clip matrix (scene_matrix)
+    clip_matrix = []
+    try:
+        matrix_resp = ableton.send_command("get_scene_matrix")
+        clip_matrix = matrix_resp.get("matrix", [])
+    except Exception:
+        pass
+
+    # 4. Gather per-track info with devices
+    track_infos = []
+    for track in tracks:
+        try:
+            info = ableton.send_command("get_track_info", {
+                "track_index": track["index"],
+            })
+            track_infos.append(info)
+        except Exception:
+            track_infos.append({
+                "index": track.get("index", 0),
+                "name": track.get("name", ""),
+                "devices": [],
+            })
+
+    # 5. Gather arrangement clips per track (legacy path)
+    arrangement_clips = {}
+    for track in tracks:
+        try:
+            arr = ableton.send_command("get_arrangement_clips", {
+                "track_index": track["index"],
+            })
+            clips = arr.get("clips", [])
+            if clips:
+                arrangement_clips[track["index"]] = clips
+        except Exception:
+            pass
+
+    # 6. Probe capabilities
+    analyzer_ok = False
+    analyzer_fresh = False
+    flucoma_ok = False
+    try:
+        # Check if M4L bridge is responding via spectral cache
+        bridge = ctx.lifespan_context.get("spectral_cache")
+        if bridge:
+            analyzer_ok = True
+            analyzer_fresh = not bridge.is_stale() if hasattr(bridge, "is_stale") else False
+    except Exception:
+        pass
+
+    try:
+        flucoma_resp = ableton.send_command("check_flucoma")
+        flucoma_ok = flucoma_resp.get("available", False)
+    except Exception:
+        pass
+
+    # 7. Build state
+    state = build_project_state_from_data(
+        session_info=session_info,
+        scenes=scenes if scenes and clip_matrix else None,
+        clip_matrix=clip_matrix if clip_matrix else None,
+        track_infos=track_infos if track_infos else None,
+        arrangement_clips=arrangement_clips if arrangement_clips else None,
+        analyzer_ok=analyzer_ok,
+        flucoma_ok=flucoma_ok,
+        session_ok=True,
+        analyzer_fresh=analyzer_fresh,
+        previous_revision=0,
+    )
+
+    return state.to_dict()
+
+
+@mcp.tool()
+def get_project_brain_summary(ctx: Context) -> dict:
+    """Get a lightweight Project Brain summary — track count, section count, stale status.
+
+    Faster than build_project_brain when you just need an overview.
+    Builds session graph only, skips deep inference.
+    """
+    ableton = _get_ableton(ctx)
+    session_info = ableton.send_command("get_session_info")
+
+    state = build_project_state_from_data(
+        session_info=session_info,
+        previous_revision=0,
+    )
+
+    return {
+        "project_id": state.project_id,
+        "revision": state.revision,
+        "track_count": len(state.session_graph.tracks),
+        "return_track_count": len(state.session_graph.return_tracks),
+        "scene_count": len(state.session_graph.scenes),
+        "section_count": len(state.arrangement_graph.sections),
+        "role_count": len(state.role_graph.roles),
+        "automated_param_count": len(state.automation_graph.automated_params),
+        "tempo": state.session_graph.tempo,
+        "time_signature": state.session_graph.time_signature,
+        "is_stale": state.is_stale(),
+    }

package/mcp_server/reference_engine/__init__.py

@@ -0,0 +1 @@
+"""Reference Engine V1 — reference-aware production intelligence."""

package/mcp_server/reference_engine/gap_analyzer.py

@@ -0,0 +1,239 @@
+"""Gap analyzer — compute and classify gaps between project and reference.
+
+Pure functions, zero I/O.
+"""
+
+from __future__ import annotations
+
+import math
+
+from .models import GapEntry, GapReport, ReferenceProfile
+
+
+# ── Domain thresholds ──────────────────────────────────────────────
+
+# Minimum delta magnitude to consider a gap meaningful
+_RELEVANCE_THRESHOLDS: dict[str, float] = {
+    "spectral": 0.01,
+    "loudness": 1.0,     # 1 LU
+    "density": 0.1,
+    "width": 0.05,
+    "pacing": 0.15,
+    "harmonic": 0.0,     # always relevant if different
+}
+
+# When a gap exceeds this fraction of the project value, closing it
+# risks flattening identity.
+_IDENTITY_WARNING_THRESHOLD = 0.6
+
+
+# ── Main analysis ──────────────────────────────────────────────────
+
+
+def analyze_gaps(
+    project_snapshot: dict,
+    reference: ReferenceProfile,
+) -> GapReport:
+    """Compare a project snapshot against a reference profile.
+
+    Args:
+        project_snapshot: dict with keys matching ReferenceProfile fields:
+            loudness (float), spectral (dict with band_balance),
+            width (float), density (float or list), pacing (list),
+            harmonic_character (str).
+        reference: The target ReferenceProfile.
+
+    Returns:
+        GapReport with all detected gaps.
+    """
+    gaps: list[GapEntry] = []
+    ref_id = f"{reference.source_type}"
+
+    # 1. Loudness gap
+    proj_loudness = project_snapshot.get("loudness", 0.0)
+    if reference.loudness_posture != 0.0 or proj_loudness != 0.0:
+        delta = proj_loudness - reference.loudness_posture
+        gaps.append(GapEntry(
+            domain="loudness",
+            delta=round(delta, 2),
+            relevant=abs(delta) >= _RELEVANCE_THRESHOLDS["loudness"],
+            identity_warning=False,
+            suggested_tactic=_suggest_loudness_tactic(delta),
+        ))
+
+    # 2. Spectral gaps (per-band)
+    proj_spectral = project_snapshot.get("spectral", {})
+    proj_bands = proj_spectral.get("band_balance", {})
+    ref_bands = reference.spectral_contour.get("band_balance", {})
+
+    all_bands = set(list(proj_bands.keys()) + list(ref_bands.keys()))
+    for band in sorted(all_bands):
+        proj_val = proj_bands.get(band, 0.0)
+        ref_val = ref_bands.get(band, 0.0)
+        delta = proj_val - ref_val
+        if abs(delta) >= _RELEVANCE_THRESHOLDS["spectral"]:
+            gaps.append(GapEntry(
+                domain="spectral",
+                delta=round(delta, 6),
+                relevant=True,
+                identity_warning=_is_identity_risk(proj_val, delta),
+                suggested_tactic=_suggest_spectral_tactic(band, delta),
+            ))
+
+    # 3. Width gap
+    proj_width = project_snapshot.get("width", 0.0)
+    ref_width = reference.width_depth.get("stereo_width", 0.0)
+    if proj_width != 0.0 or ref_width != 0.0:
+        delta = proj_width - ref_width
+        gaps.append(GapEntry(
+            domain="width",
+            delta=round(delta, 4),
+            relevant=abs(delta) >= _RELEVANCE_THRESHOLDS["width"],
+            identity_warning=_is_identity_risk(proj_width, delta),
+            suggested_tactic=_suggest_width_tactic(delta),
+        ))
+
+    # 4. Density gap
+    proj_density = project_snapshot.get("density", 0.0)
+    if isinstance(proj_density, list):
+        proj_density = sum(proj_density) / max(len(proj_density), 1)
+    ref_density = (
+        sum(reference.density_arc) / max(len(reference.density_arc), 1)
+        if reference.density_arc
+        else 0.0
+    )
+    if proj_density != 0.0 or ref_density != 0.0:
+        delta = proj_density - ref_density
+        gaps.append(GapEntry(
+            domain="density",
+            delta=round(delta, 3),
+            relevant=abs(delta) >= _RELEVANCE_THRESHOLDS["density"],
+            identity_warning=_is_identity_risk(proj_density, delta),
+            suggested_tactic=_suggest_density_tactic(delta),
+        ))
+
+    # 5. Pacing gap
+    proj_pacing = project_snapshot.get("pacing", [])
+    ref_pacing = reference.section_pacing
+    if proj_pacing or ref_pacing:
+        delta = len(proj_pacing) - len(ref_pacing)
+        gaps.append(GapEntry(
+            domain="pacing",
+            delta=float(delta),
+            relevant=abs(delta) >= _RELEVANCE_THRESHOLDS["pacing"],
+            identity_warning=False,
+            suggested_tactic=_suggest_pacing_tactic(delta),
+        ))
+
+    # 6. Harmonic gap
+    proj_harmonic = project_snapshot.get("harmonic_character", "")
+    ref_harmonic = reference.harmonic_character
+    if ref_harmonic and proj_harmonic != ref_harmonic:
+        gaps.append(GapEntry(
+            domain="harmonic",
+            delta=1.0 if proj_harmonic != ref_harmonic else 0.0,
+            relevant=True,
+            identity_warning=True,  # harmonic identity is core
+            suggested_tactic=f"Consider {ref_harmonic} voicings",
+        ))
+
+    # Compute overall distance
+    overall = _compute_overall_distance(gaps)
+
+    return GapReport(
+        reference_id=ref_id,
+        gaps=gaps,
+        overall_distance=round(overall, 3),
+    )
+
+
+# ── Relevance classification ──────────────────────────────────────
+
+
+def classify_gap_relevance(
+    gap: GapEntry,
+    goal_dimensions: list[str],
+) -> bool:
+    """Reclassify a gap's relevance against the user's stated goal dimensions.
+
+    Args:
+        gap: The GapEntry to classify.
+        goal_dimensions: list of domain names the user cares about
+            (e.g. ["spectral", "width"]).
+
+    Returns:
+        True if the gap is relevant to the goal.
+    """
+    if not goal_dimensions:
+        return gap.relevant  # keep original classification
+
+    return gap.domain in goal_dimensions
+
+
+# ── Identity warnings ──────────────────────────────────────────────
+
+
+def detect_identity_warnings(gaps: list[GapEntry]) -> list[str]:
+    """Detect gaps where closing them would destroy project identity.
+
+    Returns human-readable warning strings.
+    """
+    warnings: list[str] = []
+    for g in gaps:
+        if g.identity_warning:
+            warnings.append(
+                f"[{g.domain}] delta={g.delta:+.3f}: closing this gap "
+                f"risks flattening your project's unique {g.domain} character"
+            )
+    return warnings
+
+
+# ── Internal helpers ──────────────────────────────────────────────
+
+
+def _is_identity_risk(project_value: float, delta: float) -> bool:
+    """Check if the gap is large enough relative to project value
+    that closing it would significantly alter character."""
+    if abs(project_value) < 1e-9:
+        return False
+    return abs(delta / project_value) > _IDENTITY_WARNING_THRESHOLD
+
+
+def _compute_overall_distance(gaps: list[GapEntry]) -> float:
+    """Euclidean-like distance across all relevant gap deltas."""
+    relevant = [g for g in gaps if g.relevant]
+    if not relevant:
+        return 0.0
+    sum_sq = sum(g.delta ** 2 for g in relevant)
+    return math.sqrt(sum_sq)
+
+
+def _suggest_loudness_tactic(delta: float) -> str:
+    if delta > 2.0:
+        return "Reduce master gain or limiter ceiling"
+    elif delta < -2.0:
+        return "Increase gain staging or limiter drive"
+    return "Loudness is close — fine-tune with limiter"
+
+
+def _suggest_spectral_tactic(band: str, delta: float) -> str:
+    direction = "cut" if delta > 0 else "boost"
+    return f"EQ {direction} in {band} range"
+
+
+def _suggest_width_tactic(delta: float) -> str:
+    if delta > 0:
+        return "Narrow stereo image — check Utility width or mono bass"
+    return "Widen stereo image — try chorus, haas, or panning spread"
+
+
+def _suggest_density_tactic(delta: float) -> str:
+    if delta > 0:
+        return "Thin arrangement — mute or remove layers"
+    return "Add layers or textural elements for density"
+
+
+def _suggest_pacing_tactic(delta: float) -> str:
+    if delta > 0:
+        return "Consolidate sections — fewer, longer sections"
+    return "Add more section variety or transitions"

package/mcp_server/reference_engine/models.py

@@ -0,0 +1,105 @@
+"""Reference Engine state models — all dataclasses with to_dict().
+
+Pure data structures for reference profiles, gap reports, and tactic plans.
+Zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+# ── Reference Profile ──────────────────────────────────────────────
+
+
+@dataclass
+class ReferenceProfile:
+    """Multi-dimensional snapshot of a reference target.
+
+    Built from audio analysis, style tactic data, user descriptions,
+    or project-internal section comparisons.
+    """
+
+    source_type: str = "audio"  # "audio", "style", "user_described", "internal_section"
+    loudness_posture: float = 0.0  # integrated LUFS
+    spectral_contour: dict = field(default_factory=dict)  # band_balance + centroid
+    width_depth: dict = field(default_factory=dict)  # stereo width, depth hints
+    density_arc: list[float] = field(default_factory=list)  # per-section density 0-1
+    section_pacing: list[dict] = field(default_factory=list)  # [{label, bars, energy}]
+    harmonic_character: str = ""  # e.g. "minor_modal", "chromatic", "diatonic_major"
+    transition_tendencies: list[str] = field(default_factory=list)  # gesture names
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Gap Entry / Report ─────────────────────────────────────────────
+
+
+@dataclass
+class GapEntry:
+    """A single measured difference between project and reference."""
+
+    domain: str = ""  # "spectral", "loudness", "density", "width", "pacing", "harmonic"
+    delta: float = 0.0  # signed difference (project - reference)
+    relevant: bool = True  # whether the user's goal cares about this
+    identity_warning: bool = False  # closing this gap risks flattening identity
+    suggested_tactic: str = ""  # short tactic label
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class GapReport:
+    """All gaps between a project snapshot and a reference profile."""
+
+    reference_id: str = ""
+    gaps: list[GapEntry] = field(default_factory=list)
+    overall_distance: float = 0.0  # aggregate distance metric
+
+    @property
+    def relevant_gaps(self) -> list[GapEntry]:
+        """Return only gaps marked as relevant to the user's goal."""
+        return [g for g in self.gaps if g.relevant]
+
+    @property
+    def identity_warnings(self) -> list[str]:
+        """Return warning messages for gaps that threaten project identity."""
+        warnings: list[str] = []
+        for g in self.gaps:
+            if g.identity_warning:
+                warnings.append(
+                    f"Closing the {g.domain} gap (delta={g.delta:+.2f}) "
+                    f"may flatten your project's identity"
+                )
+        return warnings
+
+    def to_dict(self) -> dict:
+        return {
+            "reference_id": self.reference_id,
+            "gaps": [g.to_dict() for g in self.gaps],
+            "relevant_gaps": [g.to_dict() for g in self.relevant_gaps],
+            "identity_warnings": self.identity_warnings,
+            "overall_distance": self.overall_distance,
+        }
+
+
+# ── Reference Plan ─────────────────────────────────────────────────
+
+
+@dataclass
+class ReferencePlan:
+    """Actionable plan derived from a gap report."""
+
+    gap_report: GapReport = field(default_factory=GapReport)
+    ranked_tactics: list[dict] = field(default_factory=list)
+    target_engines: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "gap_report": self.gap_report.to_dict(),
+            "ranked_tactics": list(self.ranked_tactics),
+            "target_engines": list(self.target_engines),
+        }