livepilot 1.9.13 → 1.9.15

package/mcp_server/runtime/safety_tools.py

@@ -0,0 +1,42 @@
+"""MCP tool wrapper for the Safety Kernel.
+
+Tools:
+  check_safety — validate a proposed action before executing
+"""
+
+from __future__ import annotations
+
+import json
+
+from fastmcp import Context
+
+from ..server import mcp
+from .safety_kernel import check_action_safety
+
+
+@mcp.tool()
+def check_safety(ctx: Context, action: str, scope: str = "{}") -> dict:
+    """Validate a proposed action against safety policies before executing.
+
+    Parameters
+    ----------
+    action : str
+        The tool / command name to check (e.g. "delete_track").
+    scope : str
+        JSON string describing what the action will affect.
+        Recognised keys: ``track_count`` (int).
+        Defaults to ``"{}"``.
+
+    Returns
+    -------
+    dict
+        SafetyCheck with keys: action, allowed, risk_level, reason,
+        requires_confirmation.
+    """
+    try:
+        scope_dict = json.loads(scope) if isinstance(scope, str) else scope
+    except (json.JSONDecodeError, TypeError):
+        scope_dict = {}
+
+    result = check_action_safety(action, scope=scope_dict)
+    return result.to_dict()

package/mcp_server/runtime/tools.py

@@ -0,0 +1,64 @@
+"""MCP tool wrappers for runtime capability state.
+
+Tools:
+  get_capability_state — probe session + analyzer + memory, return snapshot
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+from .capability_state import build_capability_state
+
+
+@mcp.tool()
+def get_capability_state(ctx: Context) -> dict:
+    """Probe the runtime and return a capability state snapshot.
+
+    Checks session connectivity, analyzer freshness, memory availability,
+    and reports what modes the system can operate in right now.
+    """
+    ableton = ctx.lifespan_context["ableton"]
+    spectral = ctx.lifespan_context.get("spectral")
+
+    # ── Probe session ───────────────────────────────────────────────
+    session_ok = False
+    try:
+        result = ableton.send_command("get_session_info")
+        session_ok = isinstance(result, dict) and "error" not in result
+    except Exception:
+        session_ok = False
+
+    # ── Probe analyzer (M4L bridge) ─────────────────────────────────
+    analyzer_ok = False
+    analyzer_fresh = False
+    if spectral is not None:
+        analyzer_ok = spectral.is_connected
+        if analyzer_ok:
+            # Check if we have recent spectrum data
+            snap = spectral.get("spectrum")
+            analyzer_fresh = snap is not None
+
+    # ── Probe memory ────────────────────────────────────────────────
+    memory_ok = False
+    try:
+        mem_result = ableton.send_command("memory_list", {"type": "technique"})
+        memory_ok = isinstance(mem_result, dict) and "error" not in mem_result
+    except Exception:
+        memory_ok = False
+
+    # ── Web / FluCoMa — not probed live, default to False ───────────
+    web_ok = False
+    flucoma_ok = False
+
+    state = build_capability_state(
+        session_ok=session_ok,
+        analyzer_ok=analyzer_ok,
+        analyzer_fresh=analyzer_fresh,
+        memory_ok=memory_ok,
+        web_ok=web_ok,
+        flucoma_ok=flucoma_ok,
+    )
+
+    return state.to_dict()

package/mcp_server/server.py

@@ -103,6 +103,23 @@ from .tools import generative   # noqa: F401, E402
 from .tools import harmony      # noqa: F401, E402
 from .tools import midi_io      # noqa: F401, E402
 from .tools import perception   # noqa: F401, E402
+from .tools import agent_os     # noqa: F401, E402
+from .tools import composition  # noqa: F401, E402
+from .tools import motif         # noqa: F401, E402
+from .tools import research      # noqa: F401, E402
+from .tools import planner       # noqa: F401, E402
+from .project_brain import tools as project_brain_tools  # noqa: F401, E402
+from .runtime import tools as runtime_tools              # noqa: F401, E402
+from .runtime import action_tools as action_ledger_tools  # noqa: F401, E402
+from .evaluation import tools as evaluation_tools  # noqa: F401, E402
+from .memory import tools as memory_fabric_tools   # noqa: F401, E402
+from .mix_engine import tools as mix_engine_tools  # noqa: F401, E402
+from .sound_design import tools as sound_design_tools      # noqa: F401, E402
+from .transition_engine import tools as transition_tools   # noqa: F401, E402
+from .reference_engine import tools as reference_tools     # noqa: F401, E402
+from .translation_engine import tools as translation_tools  # noqa: F401, E402
+from .performance_engine import tools as performance_tools  # noqa: F401, E402
+from .runtime import safety_tools  # noqa: F401, E402
 
 
 # ---------------------------------------------------------------------------
@@ -136,7 +153,12 @@ def _coerce_schema_property(prop: dict) -> None:
 
 
 def _get_all_tools():
-    """Get all registered tools, compatible with FastMCP 0.x and 3.x."""
+    """Get all registered tools, compatible with FastMCP 0.x and 3.x.
+
+    WARNING: Accesses FastMCP private internals (_tool_manager, _local_provider).
+    Pinned to fastmcp>=3.0.0,<3.3.0 in requirements.txt. If upgrading FastMCP,
+    verify these attributes still exist or update this function.
+    """
     # FastMCP 0.x: mcp._tool_manager._tools (dict of name -> Tool)
     if hasattr(mcp, "_tool_manager"):
         return list(mcp._tool_manager._tools.values())

package/mcp_server/sound_design/__init__.py

@@ -0,0 +1 @@
+"""Sound Design Engine V1 — timbral intelligence for LivePilot."""

package/mcp_server/sound_design/critics.py

@@ -0,0 +1,297 @@
+"""Sound Design Engine critics — detect timbral issues from state data.
+
+Five critics: static_timbre, weak_identity, masking_role,
+modulation_flatness, layer_overlap.
+All pure computation, zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+from .models import (
+    LayerStrategy,
+    PatchModel,
+    SoundDesignState,
+    TimbralGoalVector,
+)
+
+
+# ── SoundDesignIssue ─────────────────────────────────────────────────
+
+
+@dataclass
+class SoundDesignIssue:
+    """A single detected sound-design issue."""
+
+    issue_type: str = ""
+    critic: str = ""
+    severity: float = 0.0
+    confidence: float = 0.0
+    affected_blocks: list[str] = field(default_factory=list)
+    evidence: str = ""
+    recommended_moves: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Static Timbre Critic ─────────────────────────────────────────────
+
+
+def run_static_timbre_critic(
+    patch: PatchModel,
+    goal: TimbralGoalVector,
+) -> list[SoundDesignIssue]:
+    """Detect static timbre: no modulation sources, flat/lifeless sound.
+
+    Fires when the goal asks for movement or instability but the patch
+    has no LFOs and no non-default envelopes (only oscillators/filters/effects).
+    """
+    issues: list[SoundDesignIssue] = []
+
+    has_lfo = any(b.block_type == "lfo" for b in patch.blocks)
+    has_envelope = any(b.block_type == "envelope" for b in patch.blocks)
+    has_modulation = has_lfo or has_envelope
+
+    # If goal wants movement or instability but patch is static
+    wants_movement = goal.movement > 0.1 or goal.instability > 0.1
+    if wants_movement and not has_modulation and len(patch.blocks) > 0:
+        severity = min(1.0, (abs(goal.movement) + abs(goal.instability)) / 2.0)
+        issues.append(SoundDesignIssue(
+            issue_type="static_timbre",
+            critic="static_timbre",
+            severity=round(severity, 3),
+            confidence=0.8,
+            affected_blocks=[b.device_name for b in patch.blocks],
+            evidence=(
+                f"Goal wants movement={goal.movement:.2f}, "
+                f"instability={goal.instability:.2f} but patch has "
+                f"no LFOs or modulation envelopes"
+            ),
+            recommended_moves=["modulation_injection"],
+        ))
+
+    # Even without explicit goal, a patch with zero modulation is flat
+    if not has_modulation and not wants_movement and len(patch.blocks) > 0:
+        issues.append(SoundDesignIssue(
+            issue_type="no_modulation_sources",
+            critic="static_timbre",
+            severity=0.3,
+            confidence=0.5,
+            affected_blocks=[b.device_name for b in patch.blocks],
+            evidence=(
+                f"Patch has {len(patch.blocks)} blocks but no LFOs "
+                f"or modulation envelopes — timbre will be static"
+            ),
+            recommended_moves=["modulation_injection"],
+        ))
+
+    return issues
+
+
+# ── Weak Identity Critic ─────────────────────────────────────────────
+
+
+def run_weak_identity_critic(
+    patch: PatchModel,
+) -> list[SoundDesignIssue]:
+    """Detect weak patch identity: too few distinct blocks, generic chain.
+
+    A patch with only one or two blocks (e.g. just an oscillator + effect)
+    lacks timbral character.  Also flags chains with no filter or saturation,
+    which tend to sound generic.
+    """
+    issues: list[SoundDesignIssue] = []
+
+    controllable_blocks = [b for b in patch.blocks if b.controllable]
+    block_types = {b.block_type for b in controllable_blocks}
+
+    # Too few blocks for timbral identity
+    if len(controllable_blocks) < 2 and len(patch.device_chain) > 0:
+        issues.append(SoundDesignIssue(
+            issue_type="too_few_blocks",
+            critic="weak_identity",
+            severity=0.5,
+            confidence=0.6,
+            affected_blocks=[b.device_name for b in controllable_blocks],
+            evidence=(
+                f"Only {len(controllable_blocks)} controllable block(s) — "
+                f"patch lacks timbral sculpting potential"
+            ),
+            recommended_moves=["filter_contour", "source_balance"],
+        ))
+
+    # Generic chain: no filter or saturation for character
+    if len(controllable_blocks) >= 2:
+        has_character = "filter" in block_types or "saturation" in block_types
+        if not has_character:
+            issues.append(SoundDesignIssue(
+                issue_type="generic_chain",
+                critic="weak_identity",
+                severity=0.4,
+                confidence=0.5,
+                affected_blocks=[b.device_name for b in controllable_blocks],
+                evidence=(
+                    f"Block types {sorted(block_types)} lack filter or "
+                    f"saturation — chain will sound generic"
+                ),
+                recommended_moves=["filter_contour"],
+            ))
+
+    return issues
+
+
+# ── Masking Role Critic ──────────────────────────────────────────────
+
+
+def run_masking_role_critic(
+    patch: PatchModel,
+    layers: LayerStrategy,
+) -> list[SoundDesignIssue]:
+    """Detect layers overlapping in frequency role.
+
+    Flags when the same track is assigned as both sub_anchor and
+    body_layer (or other frequency-adjacent roles), or when a track's
+    roles suggest it covers too wide a frequency range.
+    """
+    issues: list[SoundDesignIssue] = []
+
+    # Frequency-adjacent role pairs that risk masking
+    adjacent_pairs = [
+        ("sub_anchor", "body_layer"),
+        ("body_layer", "transient_layer"),
+        ("texture_layer", "width_layer"),
+    ]
+
+    ti = patch.track_index
+    assigned_roles = []
+    if layers.sub_anchor == ti:
+        assigned_roles.append("sub_anchor")
+    if layers.body_layer == ti:
+        assigned_roles.append("body_layer")
+    if layers.transient_layer == ti:
+        assigned_roles.append("transient_layer")
+    if layers.texture_layer == ti:
+        assigned_roles.append("texture_layer")
+    if layers.width_layer == ti:
+        assigned_roles.append("width_layer")
+
+    for role_a, role_b in adjacent_pairs:
+        if role_a in assigned_roles and role_b in assigned_roles:
+            issues.append(SoundDesignIssue(
+                issue_type="frequency_role_overlap",
+                critic="masking_role",
+                severity=0.6,
+                confidence=0.7,
+                affected_blocks=[],
+                evidence=(
+                    f"Track {ti} assigned both '{role_a}' and '{role_b}' — "
+                    f"these frequency-adjacent roles risk masking each other"
+                ),
+                recommended_moves=["layer_split", "source_balance"],
+            ))
+
+    return issues
+
+
+# ── Modulation Flatness Critic ───────────────────────────────────────
+
+
+def run_modulation_flatness_critic(
+    patch: PatchModel,
+) -> list[SoundDesignIssue]:
+    """Detect modulation flatness: no LFOs, no envelopes beyond default.
+
+    Fires when a patch with 3+ blocks has zero dedicated modulation
+    sources — the patch will sound lifeless over time.
+    """
+    issues: list[SoundDesignIssue] = []
+
+    lfo_count = sum(1 for b in patch.blocks if b.block_type == "lfo")
+    envelope_count = sum(1 for b in patch.blocks if b.block_type == "envelope")
+    total_blocks = len(patch.blocks)
+
+    if total_blocks >= 3 and lfo_count == 0 and envelope_count == 0:
+        issues.append(SoundDesignIssue(
+            issue_type="no_modulation",
+            critic="modulation_flatness",
+            severity=0.5,
+            confidence=0.7,
+            affected_blocks=[b.device_name for b in patch.blocks],
+            evidence=(
+                f"Patch has {total_blocks} blocks but zero LFOs and "
+                f"zero modulation envelopes — sound will be static"
+            ),
+            recommended_moves=["modulation_injection", "envelope_shape"],
+        ))
+
+    if total_blocks >= 3 and lfo_count == 0 and envelope_count > 0:
+        issues.append(SoundDesignIssue(
+            issue_type="no_lfo_movement",
+            critic="modulation_flatness",
+            severity=0.3,
+            confidence=0.6,
+            affected_blocks=[b.device_name for b in patch.blocks if b.block_type != "envelope"],
+            evidence=(
+                f"Patch has envelopes but no LFOs — "
+                f"sustained notes will lack timbral movement"
+            ),
+            recommended_moves=["modulation_injection"],
+        ))
+
+    return issues
+
+
+# ── Layer Overlap Critic ─────────────────────────────────────────────
+
+
+def run_layer_overlap_critic(
+    layers: LayerStrategy,
+) -> list[SoundDesignIssue]:
+    """Detect when the same track serves multiple layer roles.
+
+    A single track trying to be both sub anchor and texture layer,
+    for example, will have conflicting EQ/processing needs.
+    """
+    issues: list[SoundDesignIssue] = []
+
+    role_map: dict[int, list[str]] = {}
+    for role_name in ("sub_anchor", "body_layer", "transient_layer",
+                      "texture_layer", "width_layer"):
+        track_idx = getattr(layers, role_name)
+        if track_idx is not None:
+            role_map.setdefault(track_idx, []).append(role_name)
+
+    for track_idx, roles in role_map.items():
+        if len(roles) > 1:
+            issues.append(SoundDesignIssue(
+                issue_type="multi_role_track",
+                critic="layer_overlap",
+                severity=min(1.0, 0.3 * len(roles)),
+                confidence=0.7,
+                affected_blocks=[],
+                evidence=(
+                    f"Track {track_idx} serves {len(roles)} layer roles: "
+                    f"{roles} — conflicting processing needs"
+                ),
+                recommended_moves=["layer_split"],
+            ))
+
+    return issues
+
+
+# ── Run all critics ──────────────────────────────────────────────────
+
+
+def run_all_sound_design_critics(
+    state: SoundDesignState,
+) -> list[SoundDesignIssue]:
+    """Run all five critics and aggregate issues."""
+    issues: list[SoundDesignIssue] = []
+    issues.extend(run_static_timbre_critic(state.patch, state.goal))
+    issues.extend(run_weak_identity_critic(state.patch))
+    issues.extend(run_masking_role_critic(state.patch, state.layers))
+    issues.extend(run_modulation_flatness_critic(state.patch))
+    issues.extend(run_layer_overlap_critic(state.layers))
+    return issues

package/mcp_server/sound_design/models.py

@@ -0,0 +1,147 @@
+"""Sound Design Engine state models — all dataclasses with to_dict().
+
+Pure data structures representing timbral goals, patch topology,
+layer strategy, and the composite SoundDesignState container.
+
+Zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+# ── Timbral Goal Vector ──────────────────────────────────────────────
+
+
+@dataclass
+class TimbralGoalVector:
+    """Multi-dimensional timbral target compiled from natural language.
+
+    Each dimension is a float in [-1.0, 1.0] where 0.0 means "no change".
+    Positive values push toward more of that quality, negative toward less.
+    ``protect`` is a dict of dimensions that must not regress, with threshold weights.
+    """
+
+    brightness: float = 0.0
+    warmth: float = 0.0
+    bite: float = 0.0
+    softness: float = 0.0
+    instability: float = 0.0
+    width: float = 0.0
+    texture_density: float = 0.0
+    movement: float = 0.0
+    polish: float = 0.0
+    protect: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Patch Block ──────────────────────────────────────────────────────
+
+
+VALID_BLOCK_TYPES = frozenset({
+    "oscillator",
+    "filter",
+    "envelope",
+    "lfo",
+    "spatial",
+    "saturation",
+    "effect",
+})
+
+
+@dataclass
+class PatchBlock:
+    """A single functional block within a device chain.
+
+    ``block_type`` must be one of the VALID_BLOCK_TYPES.
+    ``controllable`` indicates whether the block's parameters are exposed
+    to automation (True for native devices, often False for opaque plugins).
+    """
+
+    block_type: str = "effect"
+    device_name: str = ""
+    controllable: bool = True
+
+    def __post_init__(self) -> None:
+        if self.block_type not in VALID_BLOCK_TYPES:
+            raise ValueError(
+                f"Invalid block_type '{self.block_type}'. "
+                f"Must be one of {sorted(VALID_BLOCK_TYPES)}"
+            )
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Patch Model ──────────────────────────────────────────────────────
+
+
+@dataclass
+class PatchModel:
+    """Structural model of an instrument/effect chain on a single track.
+
+    ``device_chain`` lists device names in signal-flow order.
+    ``roles`` describes the musical role(s) this patch fills
+    (e.g. ["lead"], ["sub_anchor", "body_layer"]).
+    ``blocks`` lists the controllable functional blocks.
+    ``opaque_blocks`` lists device names whose internals are not inspectable.
+    """
+
+    track_index: int = 0
+    device_chain: list[str] = field(default_factory=list)
+    roles: list[str] = field(default_factory=list)
+    blocks: list[PatchBlock] = field(default_factory=list)
+    opaque_blocks: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "track_index": self.track_index,
+            "device_chain": list(self.device_chain),
+            "roles": list(self.roles),
+            "blocks": [b.to_dict() for b in self.blocks],
+            "opaque_blocks": list(self.opaque_blocks),
+        }
+
+
+# ── Layer Strategy ───────────────────────────────────────────────────
+
+
+@dataclass
+class LayerStrategy:
+    """Describes how multiple tracks/layers divide timbral labor.
+
+    Each field is an optional track index indicating which track
+    owns that layer role.  None means no track is assigned.
+    """
+
+    sub_anchor: Optional[int] = None
+    body_layer: Optional[int] = None
+    transient_layer: Optional[int] = None
+    texture_layer: Optional[int] = None
+    width_layer: Optional[int] = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Composite State ──────────────────────────────────────────────────
+
+
+@dataclass
+class SoundDesignState:
+    """Top-level container for sound design analysis of a track."""
+
+    goal: TimbralGoalVector = field(default_factory=TimbralGoalVector)
+    patch: PatchModel = field(default_factory=PatchModel)
+    layers: LayerStrategy = field(default_factory=LayerStrategy)
+
+    def to_dict(self) -> dict:
+        return {
+            "goal": self.goal.to_dict(),
+            "patch": self.patch.to_dict(),
+            "layers": self.layers.to_dict(),
+        }

package/mcp_server/sound_design/planner.py

@@ -0,0 +1,104 @@
+"""Sound Design Engine planner — rank and suggest timbral moves.
+
+Pure computation, zero I/O.  Takes critic issues and sound design state,
+returns a ranked list of reversible moves.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+from .critics import SoundDesignIssue
+from .models import SoundDesignState
+
+
+# ── SoundDesignMove ──────────────────────────────────────────────────
+
+
+@dataclass
+class SoundDesignMove:
+    """A single suggested sound-design move."""
+
+    move_type: str = ""
+    target_block: str = ""
+    description: str = ""
+    estimated_impact: float = 0.0
+    risk: float = 0.0
+    parameters: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# Move type metadata: (scope, base_risk)
+# scope: "parameter" < "block" < "chain" — prefer smallest scope
+_MOVE_META: dict[str, tuple[str, float]] = {
+    "source_balance": ("block", 0.1),
+    "filter_contour": ("parameter", 0.1),
+    "envelope_shape": ("parameter", 0.1),
+    "modulation_injection": ("block", 0.2),
+    "spatial_separation": ("block", 0.15),
+    "layer_split": ("chain", 0.3),
+}
+
+_SCOPE_PENALTY: dict[str, float] = {
+    "parameter": 0.0,
+    "block": 0.05,
+    "chain": 0.15,
+}
+
+
+# ── Planner ──────────────────────────────────────────────────────────
+
+
+def plan_sound_design_moves(
+    issues: list[SoundDesignIssue],
+    state: SoundDesignState,
+) -> list[SoundDesignMove]:
+    """Generate a ranked list of suggested moves from detected issues.
+
+    Ranking: estimated_impact * (1 - risk), highest first.
+    Prefers parameter-level moves over chain-level moves.
+
+    Returns an empty list if no issues are present.
+    """
+    if not issues:
+        return []
+
+    moves: list[SoundDesignMove] = []
+
+    for issue in issues:
+        for move_type in issue.recommended_moves:
+            scope, base_risk = _MOVE_META.get(move_type, ("block", 0.2))
+            risk = min(1.0, base_risk + _SCOPE_PENALTY.get(scope, 0.0))
+            impact = issue.severity * issue.confidence
+
+            # Pick the first affected block as target, or empty
+            target = issue.affected_blocks[0] if issue.affected_blocks else ""
+
+            move = SoundDesignMove(
+                move_type=move_type,
+                target_block=target,
+                description=(
+                    f"{move_type} to address {issue.issue_type} "
+                    f"({issue.critic} critic)"
+                ),
+                estimated_impact=round(impact, 3),
+                risk=round(risk, 3),
+                parameters={
+                    "source_issue": issue.issue_type,
+                    "source_critic": issue.critic,
+                    "severity": issue.severity,
+                },
+            )
+            moves.append(move)
+
+    # Rank: impact * (1 - risk), highest first; tie-break by scope
+    def _rank_key(m: SoundDesignMove) -> tuple[float, float]:
+        score = m.estimated_impact * (1.0 - m.risk)
+        scope, _ = _MOVE_META.get(m.move_type, ("block", 0.2))
+        scope_order = _SCOPE_PENALTY.get(scope, 0.0)
+        return (-score, scope_order)
+
+    moves.sort(key=_rank_key)
+    return moves