livepilot 1.9.13 → 1.9.15

package/mcp_server/reference_engine/profile_builder.py

@@ -0,0 +1,149 @@
+"""Reference profile builders — construct ReferenceProfile from various sources.
+
+Pure functions, zero I/O.
+"""
+
+from __future__ import annotations
+
+from .models import ReferenceProfile
+
+
+# ── Audio Reference ────────────────────────────────────────────────
+
+
+def build_audio_reference_profile(comparison_data: dict) -> ReferenceProfile:
+    """Build a ReferenceProfile from compare_to_reference output.
+
+    Args:
+        comparison_data: dict returned by perception engine's
+            compare_to_reference (keys: reference_lufs, centroid_delta_hz,
+            stereo_width_ref, band_deltas, suggestions, etc.)
+
+    Returns:
+        ReferenceProfile with source_type="audio".
+    """
+    band_deltas = comparison_data.get("band_deltas", {})
+
+    # Reconstruct approximate reference spectral contour from band deltas.
+    # The deltas are (mix - ref), so ref bands are conceptually the baseline.
+    spectral_contour: dict = {
+        "band_balance": band_deltas,
+        "centroid_delta_hz": comparison_data.get("centroid_delta_hz", 0.0),
+    }
+
+    width_depth: dict = {
+        "stereo_width": comparison_data.get("stereo_width_ref", 0.0),
+    }
+
+    # Extract loudness posture
+    loudness = comparison_data.get("reference_lufs", comparison_data.get("ref_lufs", 0.0))
+
+    return ReferenceProfile(
+        source_type="audio",
+        loudness_posture=float(loudness),
+        spectral_contour=spectral_contour,
+        width_depth=width_depth,
+        density_arc=[],  # audio comparison doesn't provide density
+        section_pacing=[],  # not available from offline comparison
+        harmonic_character="",  # would need chroma analysis
+        transition_tendencies=[],
+    )
+
+
+# ── Style Reference ───────────────────────────────────────────────
+
+
+def build_style_reference_profile(style_tactics: list[dict]) -> ReferenceProfile:
+    """Build a ReferenceProfile from style tactic data.
+
+    Args:
+        style_tactics: list of StyleTactic.to_dict() entries from the
+            research engine's get_style_tactics.
+
+    Returns:
+        ReferenceProfile with source_type="style".
+    """
+    if not style_tactics:
+        return ReferenceProfile(source_type="style")
+
+    # Aggregate arrangement patterns into section_pacing
+    section_pacing: list[dict] = []
+    transition_tendencies: list[str] = []
+    device_names: list[str] = []
+
+    for tactic in style_tactics:
+        # Arrangement patterns -> section pacing
+        for pattern in tactic.get("arrangement_patterns", []):
+            section_pacing.append({
+                "label": pattern,
+                "source": tactic.get("artist_or_genre", "unknown"),
+            })
+
+        # Automation gestures -> transition tendencies
+        for gesture in tactic.get("automation_gestures", []):
+            if gesture not in transition_tendencies:
+                transition_tendencies.append(gesture)
+
+        # Collect device names for harmonic character hints
+        for dev in tactic.get("device_chain", []):
+            name = dev.get("name", "")
+            if name and name not in device_names:
+                device_names.append(name)
+
+    # Infer harmonic character from device chain
+    harmonic_character = _infer_harmonic_character(device_names)
+
+    # Estimate density from arrangement pattern count
+    density_arc = _estimate_density_from_patterns(style_tactics)
+
+    return ReferenceProfile(
+        source_type="style",
+        loudness_posture=0.0,  # style doesn't specify loudness
+        spectral_contour={},  # style doesn't specify spectrum
+        width_depth={},
+        density_arc=density_arc,
+        section_pacing=section_pacing,
+        harmonic_character=harmonic_character,
+        transition_tendencies=transition_tendencies,
+    )
+
+
+# ── Internal helpers ──────────────────────────────────────────────
+
+
+def _infer_harmonic_character(device_names: list[str]) -> str:
+    """Heuristic: infer harmonic character from common device names."""
+    lower_names = [d.lower() for d in device_names]
+
+    if any("reverb" in n for n in lower_names):
+        if any("filter" in n for n in lower_names):
+            return "atmospheric_filtered"
+        return "spacious"
+    if any("saturator" in n or "overdrive" in n or "amp" in n for n in lower_names):
+        return "warm_harmonic"
+    if any("operator" in n or "wavetable" in n for n in lower_names):
+        return "synthetic"
+    return "neutral"
+
+
+def _estimate_density_from_patterns(style_tactics: list[dict]) -> list[float]:
+    """Heuristic: estimate a density arc from arrangement patterns.
+
+    More patterns / longer structures suggest higher density.
+    """
+    if not style_tactics:
+        return []
+
+    densities: list[float] = []
+    for tactic in style_tactics:
+        patterns = tactic.get("arrangement_patterns", [])
+        # Simple heuristic: 1-2 patterns = sparse, 3+ = dense
+        n = len(patterns)
+        if n == 0:
+            densities.append(0.2)
+        elif n <= 2:
+            densities.append(0.4)
+        else:
+            densities.append(min(0.9, 0.3 + n * 0.15))
+
+    return densities

package/mcp_server/reference_engine/tactic_router.py

@@ -0,0 +1,117 @@
+"""Tactic router — map gaps to target engines and rank tactics.
+
+Pure functions, zero I/O.
+"""
+
+from __future__ import annotations
+
+from .models import GapEntry, GapReport, ReferencePlan
+
+
+# ── Domain -> Engine mapping ───────────────────────────────────────
+
+_DOMAIN_ENGINE_MAP: dict[str, str] = {
+    "spectral": "mix_engine",
+    "loudness": "mix_engine",
+    "width": "mix_engine",
+    "density": "composition",
+    "pacing": "composition",
+    "harmonic": "composition",
+}
+
+
+# ── Routing ────────────────────────────────────────────────────────
+
+
+def route_to_engines(gap_report: GapReport) -> list[dict]:
+    """Map each relevant gap to a target engine with priority.
+
+    Returns:
+        list of {domain, engine, delta, tactic, priority} dicts,
+        sorted by priority (highest first).
+    """
+    routes: list[dict] = []
+
+    for gap in gap_report.relevant_gaps:
+        engine = _DOMAIN_ENGINE_MAP.get(gap.domain, "mix_engine")
+        priority = _compute_priority(gap)
+
+        routes.append({
+            "domain": gap.domain,
+            "engine": engine,
+            "delta": gap.delta,
+            "tactic": gap.suggested_tactic,
+            "priority": priority,
+            "identity_warning": gap.identity_warning,
+        })
+
+    # Sort by priority descending
+    routes.sort(key=lambda r: -r["priority"])
+    return routes
+
+
+def build_reference_plan(gap_report: GapReport) -> ReferencePlan:
+    """Build a full ReferencePlan from a gap report.
+
+    Combines routing with ranked tactics and target engine list.
+    """
+    routes = route_to_engines(gap_report)
+
+    # Ranked tactics: each route is a tactic entry
+    ranked_tactics = [
+        {
+            "rank": i + 1,
+            "domain": r["domain"],
+            "tactic": r["tactic"],
+            "engine": r["engine"],
+            "priority": r["priority"],
+            "identity_warning": r["identity_warning"],
+        }
+        for i, r in enumerate(routes)
+    ]
+
+    # Unique target engines in priority order
+    seen: set[str] = set()
+    target_engines: list[str] = []
+    for r in routes:
+        if r["engine"] not in seen:
+            target_engines.append(r["engine"])
+            seen.add(r["engine"])
+
+    return ReferencePlan(
+        gap_report=gap_report,
+        ranked_tactics=ranked_tactics,
+        target_engines=target_engines,
+    )
+
+
+# ── Priority scoring ──────────────────────────────────────────────
+
+
+def _compute_priority(gap: GapEntry) -> float:
+    """Compute routing priority for a gap.
+
+    Higher = more urgent. Identity-warned gaps get deprioritized
+    to avoid flattening the project.
+    """
+    base = abs(gap.delta)
+
+    # Normalize different domains to comparable scales
+    scale = _DOMAIN_SCALE.get(gap.domain, 1.0)
+    normalized = min(base * scale, 1.0)
+
+    # Penalize identity-risky gaps
+    if gap.identity_warning:
+        normalized *= 0.5
+
+    return round(normalized, 3)
+
+
+_DOMAIN_SCALE: dict[str, float] = {
+    "spectral": 10.0,   # band deltas are small (0.001-0.1)
+    "loudness": 0.1,    # LUFS deltas are large (1-10)
+    "width": 5.0,       # width deltas moderate (0.01-0.3)
+    "density": 2.0,     # 0-1 range
+    "pacing": 0.2,      # section count deltas
+    "harmonic": 1.0,    # binary (0 or 1)
+}

package/mcp_server/reference_engine/tools.py

@@ -0,0 +1,235 @@
+"""Reference Engine MCP tools — 3 tools for reference-aware production intelligence.
+
+Each tool fetches data from Ableton/perception 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._research_engine import get_style_tactics
+from .profile_builder import build_audio_reference_profile, build_style_reference_profile
+from .gap_analyzer import analyze_gaps, classify_gap_relevance, detect_identity_warnings
+from .tactic_router import build_reference_plan
+
+
+# ── Helpers ────────────────────────────────────────────────────────
+
+
+def _fetch_comparison_data(ctx: Context, mix_path: str, reference_path: str) -> dict:
+    """Run compare_to_reference via the perception engine."""
+    from ..tools._perception_engine import compare_to_reference
+
+    if not mix_path:
+        return {"error": "No mix_path provided — bounce your project first and pass the path", "code": "INVALID_PARAM"}
+
+    return compare_to_reference(mix_path, reference_path, normalize=True)
+
+
+def _fetch_project_snapshot(ctx: Context) -> dict:
+    """Build a lightweight project snapshot for gap analysis."""
+    ableton = ctx.lifespan_context["ableton"]
+
+    snapshot: dict = {
+        "loudness": 0.0,
+        "spectral": {},
+        "width": 0.0,
+        "density": 0.0,
+        "pacing": [],
+        "harmonic_character": "",
+    }
+
+    # Try to get master RMS / loudness
+    try:
+        rms_result = ableton.send_command("get_master_rms", {})
+        rms = rms_result.get("rms", 0.0) if isinstance(rms_result, dict) else 0.0
+        # Approximate LUFS from RMS (rough heuristic)
+        if rms > 0:
+            import math
+            snapshot["loudness"] = round(20 * math.log10(max(rms, 1e-10)), 2)
+    except Exception:
+        pass
+
+    # Try to get spectrum data
+    try:
+        spectrum = ableton.send_command("get_master_spectrum", {})
+        if isinstance(spectrum, dict):
+            snapshot["spectral"] = spectrum
+    except Exception:
+        pass
+
+    # Try to get session info for pacing / density
+    try:
+        session_info = ableton.send_command("get_session_info", {})
+        track_count = session_info.get("track_count", 0)
+        scene_count = session_info.get("scene_count", 0)
+        # Rough density estimate
+        snapshot["density"] = min(1.0, track_count / 20.0)
+        snapshot["pacing"] = [{"label": f"scene_{i}", "bars": 8} for i in range(scene_count)]
+    except Exception:
+        pass
+
+    return snapshot
+
+
+# ── MCP Tools ──────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def build_reference_profile(
+    ctx: Context,
+    reference_path: str = "",
+    mix_path: str = "",
+    style: str = "",
+) -> dict:
+    """Build a reference profile from an audio file or style/genre name.
+
+    Provide either reference_path (for audio comparison) or style
+    (for style tactic lookup). If both are provided, audio takes priority.
+
+    Args:
+        reference_path: Absolute path to a reference audio file (.wav, .flac, .aiff).
+        mix_path: Absolute path to your bounced mix file (required for audio comparison).
+        style: Artist or genre name (e.g. "burial", "techno", "lo-fi").
+
+    Returns:
+        ReferenceProfile as dict with source_type, loudness_posture,
+        spectral_contour, width_depth, density_arc, section_pacing,
+        harmonic_character, transition_tendencies.
+    """
+    if reference_path:
+        comparison = _fetch_comparison_data(ctx, mix_path, reference_path)
+        if "error" in comparison:
+            return comparison
+        profile = build_audio_reference_profile(comparison)
+        return profile.to_dict()
+
+    if style:
+        tactics = get_style_tactics(style)
+        if not tactics:
+            return {
+                "error": f"No style tactics found for '{style}'",
+                "code": "NOT_FOUND",
+            }
+        tactic_dicts = [t.to_dict() for t in tactics]
+        profile = build_style_reference_profile(tactic_dicts)
+        return profile.to_dict()
+
+    return {
+        "error": "Provide either reference_path or style",
+        "code": "INVALID_PARAM",
+    }
+
+
+@mcp.tool()
+def analyze_reference_gaps(
+    ctx: Context,
+    reference_path: str = "",
+    mix_path: str = "",
+    style: str = "",
+    goal_dimensions: str = "",
+) -> dict:
+    """Analyze gaps between your project and a reference.
+
+    Computes deltas across spectral, loudness, width, density, pacing,
+    and harmonic domains. Flags which gaps are relevant and which
+    would destroy your project's identity if closed.
+
+    Args:
+        reference_path: Absolute path to a reference audio file.
+        mix_path: Absolute path to your bounced mix file (required for audio comparison).
+        style: Artist or genre name for style-based comparison.
+        goal_dimensions: Comma-separated domains to focus on
+            (e.g. "spectral,width"). Empty = all domains.
+
+    Returns:
+        GapReport as dict with gaps, relevant_gaps, identity_warnings,
+        and overall_distance.
+    """
+    # Build reference profile
+    if reference_path:
+        comparison = _fetch_comparison_data(ctx, mix_path, reference_path)
+        if "error" in comparison:
+            return comparison
+        profile = build_audio_reference_profile(comparison)
+    elif style:
+        tactics = get_style_tactics(style)
+        if not tactics:
+            return {"error": f"No style tactics found for '{style}'", "code": "NOT_FOUND"}
+        tactic_dicts = [t.to_dict() for t in tactics]
+        profile = build_style_reference_profile(tactic_dicts)
+    else:
+        return {"error": "Provide either reference_path or style", "code": "INVALID_PARAM"}
+
+    # Build project snapshot
+    snapshot = _fetch_project_snapshot(ctx)
+
+    # Analyze gaps
+    gap_report = analyze_gaps(snapshot, profile)
+
+    # Reclassify relevance if user specified goal dimensions
+    if goal_dimensions:
+        dims = [d.strip() for d in goal_dimensions.split(",") if d.strip()]
+        for gap in gap_report.gaps:
+            gap.relevant = classify_gap_relevance(gap, dims)
+
+    return gap_report.to_dict()
+
+
+@mcp.tool()
+def plan_reference_moves(
+    ctx: Context,
+    reference_path: str = "",
+    mix_path: str = "",
+    style: str = "",
+    goal_dimensions: str = "",
+) -> dict:
+    """Plan concrete moves to close reference gaps.
+
+    Builds a reference profile, analyzes gaps, then routes each gap
+    to the appropriate engine (mix_engine or composition) with
+    ranked tactics and identity warnings.
+
+    Args:
+        reference_path: Absolute path to a reference audio file.
+        mix_path: Absolute path to your bounced mix file (required for audio comparison).
+        style: Artist or genre name for style-based comparison.
+        goal_dimensions: Comma-separated domains to focus on.
+
+    Returns:
+        ReferencePlan as dict with gap_report, ranked_tactics,
+        and target_engines.
+    """
+    # Build reference profile
+    if reference_path:
+        comparison = _fetch_comparison_data(ctx, mix_path, reference_path)
+        if "error" in comparison:
+            return comparison
+        profile = build_audio_reference_profile(comparison)
+    elif style:
+        tactics = get_style_tactics(style)
+        if not tactics:
+            return {"error": f"No style tactics found for '{style}'", "code": "NOT_FOUND"}
+        tactic_dicts = [t.to_dict() for t in tactics]
+        profile = build_style_reference_profile(tactic_dicts)
+    else:
+        return {"error": "Provide either reference_path or style", "code": "INVALID_PARAM"}
+
+    # Build project snapshot
+    snapshot = _fetch_project_snapshot(ctx)
+
+    # Analyze gaps
+    gap_report = analyze_gaps(snapshot, profile)
+
+    # Reclassify relevance if user specified goal dimensions
+    if goal_dimensions:
+        dims = [d.strip() for d in goal_dimensions.split(",") if d.strip()]
+        for gap in gap_report.gaps:
+            gap.relevant = classify_gap_relevance(gap, dims)
+
+    # Build plan
+    plan = build_reference_plan(gap_report)
+
+    return plan.to_dict()

package/mcp_server/runtime/__init__.py

@@ -0,0 +1 @@
+"""Runtime subsystem — capability state, action ledger."""

package/mcp_server/runtime/action_ledger.py

@@ -0,0 +1,117 @@
+"""SessionLedger — in-memory store for semantic moves.
+
+Pure Python, zero I/O.  The ledger tracks every agent-initiated mutation
+as a *semantic move* that can be debugged, undone, or promoted to memory.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Optional
+
+from .action_ledger_models import LedgerEntry, UndoGroup
+
+
+class SessionLedger:
+    """Per-session record of semantic moves."""
+
+    def __init__(self) -> None:
+        self._entries: OrderedDict[str, LedgerEntry] = OrderedDict()
+
+    # ── lifecycle ──────────────────────────────────────────────────────
+
+    def start_move(
+        self,
+        engine: str,
+        move_class: str,
+        intent: str,
+        undo_scope: str = "micro",
+    ) -> str:
+        """Create a new LedgerEntry and return its id."""
+        entry = LedgerEntry(
+            engine=engine,
+            move_class=move_class,
+            intent=intent,
+            undo_scope=undo_scope,
+        )
+        self._entries[entry.id] = entry
+        return entry.id
+
+    def append_action(
+        self, entry_id: str, tool_name: str, summary: str
+    ) -> None:
+        """Add a tool-call record to an existing entry."""
+        entry = self._entries.get(entry_id)
+        if entry is None:
+            raise KeyError(f"No ledger entry with id {entry_id!r}")
+        entry.actions.append({"tool": tool_name, "summary": summary})
+
+    def set_before_refs(self, entry_id: str, refs: dict) -> None:
+        entry = self._entries.get(entry_id)
+        if entry is None:
+            raise KeyError(f"No ledger entry with id {entry_id!r}")
+        entry.before_refs = refs
+
+    def set_after_refs(self, entry_id: str, refs: dict) -> None:
+        entry = self._entries.get(entry_id)
+        if entry is None:
+            raise KeyError(f"No ledger entry with id {entry_id!r}")
+        entry.after_refs = refs
+
+    def finalize_move(
+        self,
+        entry_id: str,
+        kept: bool = True,
+        score: float = 0.0,
+        memory_candidate: bool = False,
+    ) -> None:
+        """Seal a move with its evaluation outcome."""
+        entry = self._entries.get(entry_id)
+        if entry is None:
+            raise KeyError(f"No ledger entry with id {entry_id!r}")
+        entry.kept = kept
+        entry.score = score
+        entry.memory_candidate = memory_candidate
+
+    # ── queries ────────────────────────────────────────────────────────
+
+    def get_entry(self, entry_id: str) -> Optional[LedgerEntry]:
+        return self._entries.get(entry_id)
+
+    def get_last_move(self) -> Optional[LedgerEntry]:
+        if not self._entries:
+            return None
+        # OrderedDict preserves insertion order — last item is newest
+        return next(reversed(self._entries.values()))
+
+    def get_recent_moves(
+        self,
+        limit: int = 10,
+        engine: Optional[str] = None,
+        kept: Optional[bool] = None,
+    ) -> list[LedgerEntry]:
+        """Return recent moves, newest first, with optional filters."""
+        results: list[LedgerEntry] = []
+        for entry in reversed(self._entries.values()):
+            if engine is not None and entry.engine != engine:
+                continue
+            if kept is not None and entry.kept != kept:
+                continue
+            results.append(entry)
+            if len(results) >= limit:
+                break
+        return results
+
+    def get_memory_candidates(self) -> list[LedgerEntry]:
+        """Return all entries flagged as memory promotion candidates."""
+        return [e for e in self._entries.values() if e.memory_candidate]
+
+    def get_undo_groups(self) -> list[UndoGroup]:
+        """Group entries by undo_scope."""
+        groups: dict[str, list[str]] = {}
+        for entry in self._entries.values():
+            groups.setdefault(entry.undo_scope, []).append(entry.id)
+        return [
+            UndoGroup(scope=scope, entry_ids=ids)
+            for scope, ids in groups.items()
+        ]