livepilot 1.9.21 → 1.9.23

package/mcp_server/song_brain/tools.py

@@ -0,0 +1,294 @@
+"""SongBrain MCP tools — 3 tools for song identity modeling.
+
+  build_song_brain — construct the musical identity of the current piece
+  explain_song_identity — human-readable summary of what the song is about
+  detect_identity_drift — compare before/after to detect identity damage
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import builder
+from .models import SongBrain
+
+
+# Module-level fallback for consumers without ctx.
+# Prefer ctx.lifespan_context["current_brain"] when ctx is available.
+_current_brain: SongBrain | None = None
+
+# Snapshot store: brain_id -> SongBrain, max 10 snapshots
+_brain_snapshots: dict[str, SongBrain] = {}
+_MAX_SNAPSHOTS = 10
+
+
+def _set_brain(ctx: Context, brain: SongBrain) -> None:
+    """Store brain in lifespan_context, module fallback, and snapshot store."""
+    global _current_brain
+    _current_brain = brain
+    ctx.lifespan_context["current_brain"] = brain
+    # Save snapshot for later drift comparison
+    _brain_snapshots[brain.brain_id] = brain
+    # Evict oldest if over limit
+    while len(_brain_snapshots) > _MAX_SNAPSHOTS:
+        oldest_key = next(iter(_brain_snapshots))
+        del _brain_snapshots[oldest_key]
+
+
+def _get_snapshot(brain_id: str) -> SongBrain | None:
+    """Retrieve a past brain snapshot by ID."""
+    return _brain_snapshots.get(brain_id)
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+def _fetch_session_data(ctx: Context) -> dict:
+    """Fetch all available session data for brain building.
+
+    Populates real data from Ableton and pure-computation modules:
+    - motif_data: from get_motif_graph (motif engine)
+    - composition_analysis: from musical intelligence section inference
+    - role_graph: from semantic move resolvers (track role inference)
+    - recent_moves: from session-scoped action ledger
+    """
+    ableton = _get_ableton(ctx)
+    data: dict = {
+        "session_info": {},
+        "scenes": [],
+        "tracks": [],
+        "motif_data": {},
+        "composition_analysis": {},
+        "role_graph": {},
+        "recent_moves": [],
+    }
+
+    try:
+        data["session_info"] = ableton.send_command("get_session_info", {})
+    except Exception:
+        data["session_info"] = {"tempo": 120.0, "track_count": 0}
+
+    try:
+        matrix = ableton.send_command("get_scene_matrix")
+        data["scenes"] = [
+            {"name": s.get("name", f"Scene {i}"), "clips": row}
+            for i, (s, row) in enumerate(
+                zip(matrix.get("scenes", []), matrix.get("matrix", []))
+            )
+        ]
+    except Exception:
+        pass
+
+    try:
+        info = data["session_info"]
+        tracks_list = info.get("tracks", [])
+        data["tracks"] = tracks_list if isinstance(tracks_list, list) else []
+    except Exception:
+        pass
+
+    # Motif data — from the motif engine if notes exist
+    try:
+        data["motif_data"] = ableton.send_command("get_motif_graph")
+    except Exception:
+        pass  # Motif graph requires notes in clips; empty is valid
+
+    # Composition analysis — from musical intelligence detectors (pure computation)
+    try:
+        from ..musical_intelligence import detectors
+        total_tracks = data["session_info"].get("track_count", 6)
+        purposes = detectors.infer_section_purposes(data["scenes"], total_tracks)
+        arc = detectors.score_emotional_arc(purposes)
+        data["composition_analysis"] = {
+            "sections": [p.to_dict() for p in purposes],
+            "emotional_arc": arc.to_dict(),
+        }
+    except Exception:
+        pass
+
+    # Role graph — from semantic move resolvers (pure computation, no I/O)
+    try:
+        from ..semantic_moves.resolvers import infer_role
+        roles = {}
+        for track in data["tracks"]:
+            name = track.get("name", "")
+            role = infer_role(name)
+            roles[name] = {"index": track.get("index", 0), "role": role}
+        data["role_graph"] = roles
+    except Exception:
+        pass
+
+    # Recent moves — from session-scoped action ledger
+    try:
+        from ..runtime.action_ledger import SessionLedger
+        ledger = ctx.lifespan_context.get("action_ledger")
+        if isinstance(ledger, SessionLedger):
+            recent = ledger.get_recent_moves(limit=10)
+            data["recent_moves"] = [e.to_dict() for e in recent]
+    except Exception:
+        pass
+
+    return data
+
+
+@mcp.tool()
+def build_song_brain(ctx: Context) -> dict:
+    """Build the musical identity model for the current song.
+
+    Analyzes the session to identify:
+    - identity_core: the strongest defining idea
+    - sacred_elements: motifs/textures/grooves that must be preserved
+    - section_purposes: what each section is trying to do emotionally
+    - energy_arc: rise/fall shape across sections
+    - open_questions: what the song has not resolved yet
+
+    Call this at the start of complex creative workflows.
+    Returns the full SongBrain as a dict.
+    """
+    data = _fetch_session_data(ctx)
+    brain = builder.build_song_brain(
+        session_info=data["session_info"],
+        scenes=data["scenes"],
+        tracks=data["tracks"],
+        motif_data=data["motif_data"],
+        composition_analysis=data["composition_analysis"],
+        role_graph=data["role_graph"],
+        recent_moves=data["recent_moves"],
+    )
+    _set_brain(ctx, brain)
+
+    return {
+        **brain.to_dict(),
+        "summary": brain.summary,
+    }
+
+
+@mcp.tool()
+def explain_song_identity(ctx: Context) -> dict:
+    """Explain the current song's identity in human musical language.
+
+    If no SongBrain exists yet, builds one first. Returns a structured
+    explanation suitable for the agent to talk about the song naturally.
+    """
+    if _current_brain is None:
+        data = _fetch_session_data(ctx)
+        brain = builder.build_song_brain(
+            session_info=data["session_info"],
+            scenes=data["scenes"],
+            tracks=data["tracks"],
+            motif_data=data["motif_data"],
+            composition_analysis=data["composition_analysis"],
+            role_graph=data["role_graph"],
+            recent_moves=data["recent_moves"],
+        )
+        _set_brain(ctx, brain)
+
+    brain = _current_brain
+    explanation: dict = {
+        "identity": brain.identity_core,
+        "confidence": brain.identity_confidence,
+    }
+
+    # Sacred elements in natural language
+    if brain.sacred_elements:
+        explanation["protect"] = [
+            f"{e.element_type}: {e.description}" for e in brain.sacred_elements
+        ]
+    else:
+        explanation["protect"] = ["No clearly sacred elements detected yet"]
+
+    # What each section does
+    if brain.section_purposes:
+        explanation["sections"] = [
+            f"{s.label} — {s.emotional_intent} (energy {s.energy_level:.0%})"
+            for s in brain.section_purposes
+        ]
+
+    # Energy shape
+    if brain.energy_arc:
+        arc = brain.energy_arc
+        if len(arc) >= 3:
+            peak_idx = arc.index(max(arc))
+            peak_pct = peak_idx / max(len(arc) - 1, 1)
+            if peak_pct < 0.3:
+                explanation["energy_shape"] = "front-loaded — peaks early"
+            elif peak_pct > 0.7:
+                explanation["energy_shape"] = "slow burn — builds to late peak"
+            else:
+                explanation["energy_shape"] = "centered arc — peaks in the middle"
+        else:
+            explanation["energy_shape"] = "short form — limited arc data"
+
+    # Open questions
+    if brain.open_questions:
+        explanation["open_questions"] = [q.question for q in brain.open_questions]
+
+    # Drift warning
+    if brain.identity_drift_risk > 0.3:
+        explanation["warning"] = (
+            f"Identity drift risk is {brain.identity_drift_risk:.0%} — "
+            "recent edits may be moving the song away from itself"
+        )
+
+    explanation["summary"] = brain.summary
+    return explanation
+
+
+@mcp.tool()
+def detect_identity_drift(
+    ctx: Context,
+    before_brain_id: str = "",
+) -> dict:
+    """Detect whether recent changes have damaged the song's identity.
+
+    Compares the current state against a previous SongBrain snapshot.
+    If before_brain_id is provided, looks up that specific snapshot.
+    If empty, uses the last cached brain.
+    If no previous brain exists, builds baseline and reports no drift.
+
+    before_brain_id: optional brain_id from a previous build_song_brain call.
+
+    Returns drift score, changed elements, sacred damage, and recommendation.
+    """
+    # Look up the "before" brain — by ID if provided, else use last cached
+    if before_brain_id:
+        before = _get_snapshot(before_brain_id)
+        if before is None:
+            available = list(_brain_snapshots.keys())
+            return {
+                "error": f"No snapshot found for brain_id '{before_brain_id}'",
+                "available_snapshots": available,
+            }
+    else:
+        before = _current_brain
+
+    # Build fresh brain from current state
+    data = _fetch_session_data(ctx)
+    after = builder.build_song_brain(
+        session_info=data["session_info"],
+        scenes=data["scenes"],
+        tracks=data["tracks"],
+        motif_data=data["motif_data"],
+        composition_analysis=data["composition_analysis"],
+        role_graph=data["role_graph"],
+        recent_moves=data["recent_moves"],
+    )
+
+    if before is None:
+        _set_brain(ctx, after)
+        return {
+            "drift_score": 0.0,
+            "note": "No previous brain to compare — this is the baseline",
+            "brain_id": after.brain_id,
+            "recommendation": "safe",
+        }
+
+    drift = builder.detect_identity_drift(before, after)
+    _set_brain(ctx, after)
+
+    return {
+        **drift.to_dict(),
+        "before_brain_id": before.brain_id,
+        "after_brain_id": after.brain_id,
+    }

package/mcp_server/stuckness_detector/__init__.py

@@ -0,0 +1,5 @@
+"""Stuckness Detector — momentum rescue for Stage 2.
+
+Identifies when the session is losing momentum and shifts the agent
+from micro-fixing into directional help.
+"""

package/mcp_server/stuckness_detector/detector.py

@@ -0,0 +1,400 @@
+"""Stuckness detection engine — pure computation, zero I/O.
+
+Analyzes action history, session state, and patterns to detect
+when the user is stuck and suggest rescue strategies.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Optional
+
+from .models import RescueSuggestion, StucknessReport, StucknessSignal
+
+
+# ── Main detection ────────────────────────────────────────────────
+
+
+def detect_stuckness(
+    action_history: list[dict],
+    session_info: Optional[dict] = None,
+    song_brain: Optional[dict] = None,
+    section_count: int = 0,
+) -> StucknessReport:
+    """Detect whether the session is stuck.
+
+    Analyzes action history for repeated undos, local tweaking,
+    long loops without structural edits, and other stuckness signals.
+    """
+    session_info = session_info or {}
+    song_brain = song_brain or {}
+    signals: list[StucknessSignal] = []
+
+    # 1. Repeated undos
+    undo_signal = _check_repeated_undos(action_history)
+    if undo_signal:
+        signals.append(undo_signal)
+
+    # 2. Local tweaking (many small changes in one area)
+    tweak_signal = _check_local_tweaking(action_history)
+    if tweak_signal:
+        signals.append(tweak_signal)
+
+    # 3. Long loop time without structural edits
+    loop_signal = _check_loop_without_structure(action_history, section_count)
+    if loop_signal:
+        signals.append(loop_signal)
+
+    # 4. Repeated asks without acceptance
+    repeat_signal = _check_repeated_requests(action_history)
+    if repeat_signal:
+        signals.append(repeat_signal)
+
+    # 5. Too many decorative layers
+    density_signal = _check_decoration_overload(session_info)
+    if density_signal:
+        signals.append(density_signal)
+
+    # 6. Identity unclear
+    identity_signal = _check_identity_unclear(song_brain)
+    if identity_signal:
+        signals.append(identity_signal)
+
+    # Compute overall confidence
+    if not signals:
+        return StucknessReport(confidence=0.0, level="flowing")
+
+    # Compound: strongest signal + 0.15 per additional signal (don't average)
+    strengths = sorted((s.strength for s in signals), reverse=True)
+    confidence = strengths[0]
+    for extra in strengths[1:]:
+        confidence += extra * 0.15
+    confidence = min(1.0, round(confidence, 3))
+
+    # Determine level
+    if confidence > 0.7:
+        level = "deeply_stuck"
+    elif confidence > 0.45:
+        level = "stuck"
+    elif confidence > 0.2:
+        level = "slowing"
+    else:
+        level = "flowing"
+
+    # Determine rescue types
+    primary, secondary = _classify_rescue_type(signals, song_brain, session_info)
+    diagnosis = _build_diagnosis(signals, level)
+
+    return StucknessReport(
+        confidence=confidence,
+        level=level,
+        signals=signals,
+        diagnosis=diagnosis,
+        primary_rescue_type=primary,
+        secondary_rescue_types=secondary,
+    )
+
+
+# ── Signal checkers ───────────────────────────────────────────────
+
+
+def _check_repeated_undos(history: list[dict]) -> Optional[StucknessSignal]:
+    """Check for repeated undone moves (kept=False in ledger entries)."""
+    recent = history[-20:] if len(history) > 20 else history
+    undo_count = sum(1 for a in recent if a.get("kept") is False)
+
+    if undo_count >= 4:
+        return StucknessSignal(
+            signal_type="repeated_undo",
+            strength=min(0.8, undo_count * 0.15),
+            evidence=f"{undo_count} undone moves in last {len(recent)} entries",
+        )
+    return None
+
+
+def _check_local_tweaking(history: list[dict]) -> Optional[StucknessSignal]:
+    """Check for many small parameter changes in one local area."""
+    recent = history[-15:] if len(history) > 15 else history
+    param_tools = {"set_device_parameter", "set_track_volume", "set_track_pan",
+                   "set_send_level", "set_clip_loop", "batch_set_parameters"}
+    param_entries = []
+    for entry in recent:
+        tools_used = [a.get("tool", "") for a in entry.get("actions", [])]
+        if any(t in param_tools for t in tools_used):
+            param_entries.append(entry)
+
+    if len(param_entries) >= 6:
+        scopes = Counter(
+            entry.get("scope", {}).get("track", entry.get("intent", ""))
+            for entry in param_entries
+        )
+        most_common = scopes.most_common(1)
+        if most_common and most_common[0][1] >= 4:
+            return StucknessSignal(
+                signal_type="local_tweaking",
+                strength=min(0.7, len(param_entries) * 0.1),
+                evidence=f"{len(param_entries)} parameter tweaks, mostly on {most_common[0][0]}",
+            )
+    return None
+
+
+def _check_loop_without_structure(
+    history: list[dict], section_count: int
+) -> Optional[StucknessSignal]:
+    """Check for long work without structural changes."""
+    recent = history[-30:] if len(history) > 30 else history
+    structural_tools = {"create_clip", "delete_clip", "create_midi_track",
+                        "create_audio_track", "delete_track", "duplicate_clip"}
+    structural = 0
+    for entry in recent:
+        tools_used = {a.get("tool", "") for a in entry.get("actions", [])}
+        if tools_used & structural_tools:
+            structural += 1
+
+    if len(recent) >= 15 and structural == 0:
+        return StucknessSignal(
+            signal_type="long_loop_no_structure",
+            strength=0.5,
+            evidence=f"{len(recent)} moves without any structural changes",
+        )
+
+    if section_count <= 1 and len(recent) > 20:
+        return StucknessSignal(
+            signal_type="single_loop",
+            strength=0.4,
+            evidence="Working in a single loop/scene for extended period",
+        )
+
+    return None
+
+
+def _check_repeated_requests(history: list[dict]) -> Optional[StucknessSignal]:
+    """Check for repeated similar intents without acceptance."""
+    recent = history[-10:] if len(history) > 10 else history
+    intents = [a.get("intent", "").lower() for a in recent if a.get("intent")]
+
+    if len(intents) >= 3:
+        words = Counter()
+        for intent in intents:
+            for word in intent.split():
+                if len(word) > 3:
+                    words[word] += 1
+
+        repeated = {w: c for w, c in words.items() if c >= 3}
+        if repeated:
+            return StucknessSignal(
+                signal_type="repeated_requests",
+                strength=0.5,
+                evidence=f"Repeated intent keywords: {', '.join(repeated.keys())}",
+            )
+    return None
+
+
+def _check_decoration_overload(session_info: dict) -> Optional[StucknessSignal]:
+    """Check for too many decorative layers without role clarity."""
+    track_count = session_info.get("track_count", 0)
+    if track_count > 16:
+        return StucknessSignal(
+            signal_type="high_density",
+            strength=min(0.6, (track_count - 16) * 0.05),
+            evidence=f"{track_count} tracks — may be too dense to progress",
+        )
+    return None
+
+
+def _check_identity_unclear(song_brain: dict) -> Optional[StucknessSignal]:
+    """Check if song identity is unclear."""
+    confidence = song_brain.get("identity_confidence", 0.5)
+    if confidence < 0.3:
+        return StucknessSignal(
+            signal_type="identity_unclear",
+            strength=0.5,
+            evidence="Song identity is not clearly established",
+        )
+    return None
+
+
+# ── Rescue classification ─────────────────────────────────────────
+
+
+def _classify_rescue_type(
+    signals: list[StucknessSignal],
+    song_brain: dict,
+    session_info: dict,
+) -> tuple[str, list[str]]:
+    """Determine the best rescue type from signals."""
+    signal_types = {s.signal_type for s in signals}
+
+    primary = "contrast_needed"  # default
+    secondary: list[str] = []
+
+    if "identity_unclear" in signal_types:
+        primary = "identity_unclear"
+        secondary = ["hook_underdeveloped", "too_safe_to_progress"]
+    elif "single_loop" in signal_types:
+        primary = "overpolished_loop"
+        secondary = ["section_missing", "contrast_needed"]
+    elif "high_density" in signal_types:
+        primary = "too_dense_to_progress"
+        secondary = ["contrast_needed", "identity_unclear"]
+    elif "local_tweaking" in signal_types:
+        primary = "overpolished_loop"
+        secondary = ["contrast_needed", "section_missing"]
+    elif "repeated_undo" in signal_types:
+        primary = "contrast_needed"
+        secondary = ["hook_underdeveloped", "too_safe_to_progress"]
+    elif "long_loop_no_structure" in signal_types:
+        primary = "section_missing"
+        secondary = ["contrast_needed", "transition_not_earned"]
+
+    return primary, secondary
+
+
+# ── Rescue suggestions ────────────────────────────────────────────
+
+
+def suggest_rescue(
+    report: StucknessReport,
+    mode: str = "gentle",
+) -> list[RescueSuggestion]:
+    """Generate rescue suggestions based on stuckness analysis."""
+    suggestions: list[RescueSuggestion] = []
+
+    rescue_strategies = {
+        "contrast_needed": RescueSuggestion(
+            rescue_type="contrast_needed",
+            title="Add contrast to break the plateau",
+            description="The session needs a moment that feels different from what's been happening.",
+            strategies=[
+                "Strip everything except the hook for 4-8 bars, then re-enter",
+                "Introduce a new timbral element that wasn't there before",
+                "Change the harmonic context (try a relative minor/major shift)",
+                "Create a rhythmic break — half-time or double-time feel",
+            ],
+        ),
+        "section_missing": RescueSuggestion(
+            rescue_type="section_missing",
+            title="Add a new section for structural progress",
+            description="The track needs more form — a new section would create momentum.",
+            strategies=[
+                "Create a B section that contrasts the current loop",
+                "Add an intro that sets up the main idea",
+                "Build a breakdown section that strips to essentials",
+                "Design a transition that earns the next section",
+            ],
+        ),
+        "hook_underdeveloped": RescueSuggestion(
+            rescue_type="hook_underdeveloped",
+            title="Develop the hook before adding more layers",
+            description="The most memorable idea needs more attention before the arrangement grows.",
+            strategies=[
+                "Write a variation of the hook for a different section",
+                "Add a countermelody that complements the hook",
+                "Create a stripped version of the hook for contrast sections",
+                "Make the hook hit harder — better sound design or arrangement support",
+            ],
+        ),
+        "transition_not_earned": RescueSuggestion(
+            rescue_type="transition_not_earned",
+            title="Build better transitions between sections",
+            description="Sections jump abruptly — earn the transitions.",
+            strategies=[
+                "Add a 2-4 bar transition between sections",
+                "Use filter sweeps or risers to build anticipation",
+                "Create drum fills or melodic ornaments at section boundaries",
+                "Use silence or space before the next section arrives",
+            ],
+        ),
+        "overpolished_loop": RescueSuggestion(
+            rescue_type="overpolished_loop",
+            title="Stop polishing — move forward structurally",
+            description="This loop is getting over-refined. Time to build form.",
+            strategies=[
+                "Duplicate the scene and subtract elements for a contrasting section",
+                "Record a live take over the loop to find new directions",
+                "Commit to the current state and start the arrangement",
+                "Create a completely different section from scratch",
+            ],
+        ),
+        "identity_unclear": RescueSuggestion(
+            rescue_type="identity_unclear",
+            title="Define the track's identity before adding more",
+            description="It's hard to progress when the track doesn't know what it is.",
+            strategies=[
+                "Identify or create one defining melodic/rhythmic idea",
+                "Choose a reference track and distill its key principles",
+                "Remove tracks that don't serve a clear purpose",
+                "Write a one-sentence description of what this track should feel like",
+            ],
+        ),
+        "too_dense_to_progress": RescueSuggestion(
+            rescue_type="too_dense_to_progress",
+            title="Subtract before adding more",
+            description="Too many elements fighting for attention. Simplify first.",
+            strategies=[
+                "Mute all tracks, then bring back only the essential ones",
+                "Delete or freeze tracks with no clear role",
+                "Create a stripped version as a new starting point",
+                "Focus on making 3-4 elements work perfectly instead of 12 elements existing",
+            ],
+        ),
+        "too_safe_to_progress": RescueSuggestion(
+            rescue_type="too_safe_to_progress",
+            title="Take a risk — the safe path isn't working",
+            description="Everything is technically correct but uninspired. Time for a bold move.",
+            strategies=[
+                "Try a dramatic sound design change on a key element",
+                "Add an unexpected harmonic or rhythmic element",
+                "Radically change the arrangement structure",
+                "Experiment with an extreme processing chain (distortion, granular, etc.)",
+            ],
+        ),
+    }
+
+    # Primary suggestion
+    primary_strat = rescue_strategies.get(report.primary_rescue_type)
+    if primary_strat:
+        primary_strat.urgency = "high" if report.confidence > 0.6 else "medium"
+        suggestions.append(primary_strat)
+
+    # Secondary suggestions (in gentle mode, only show primary)
+    if mode == "direct":
+        for rt in report.secondary_rescue_types[:2]:
+            sec = rescue_strategies.get(rt)
+            if sec:
+                sec.urgency = "medium"
+                suggestions.append(sec)
+
+    return suggestions
+
+
+# ── Diagnosis builder ─────────────────────────────────────────────
+
+
+def _build_diagnosis(signals: list[StucknessSignal], level: str) -> str:
+    """Build a human-readable diagnosis from signals."""
+    if level == "flowing":
+        return "Session is flowing well — no intervention needed"
+
+    signal_descriptions = {
+        "repeated_undo": "frequent undos suggest dissatisfaction with results",
+        "local_tweaking": "lots of small parameter changes in one area",
+        "long_loop_no_structure": "no structural changes for a while",
+        "single_loop": "working in a single loop without expanding",
+        "repeated_requests": "similar requests being repeated",
+        "high_density": "track count is very high",
+        "identity_unclear": "the song's identity isn't clear yet",
+    }
+
+    parts = []
+    for s in signals:
+        desc = signal_descriptions.get(s.signal_type, s.signal_type)
+        parts.append(desc)
+
+    prefix = {
+        "slowing": "The session is slowing down",
+        "stuck": "The session appears stuck",
+        "deeply_stuck": "The session is deeply stuck",
+    }.get(level, "Momentum issue detected")
+
+    return f"{prefix}: {'; '.join(parts)}"