livepilot 1.9.13 → 1.9.15

package/mcp_server/memory/tools.py

@@ -0,0 +1,112 @@
+"""Memory Fabric V2 MCP tools — anti-memory, promotion, session, and taste endpoints.
+
+6 tools: get_anti_preferences, record_anti_preference, get_promotion_candidates,
+         get_session_memory, add_session_memory, get_taste_dimensions.
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+from .anti_memory import AntiMemoryStore
+from .promotion import batch_evaluate_promotions
+from .session_memory import SessionMemoryStore
+from .taste_memory import TasteMemoryStore
+
+
+def _get_anti_memory(ctx: Context) -> AntiMemoryStore:
+    """Get or create the session-scoped AntiMemoryStore."""
+    return ctx.lifespan_context.setdefault("anti_memory", AntiMemoryStore())
+
+
+def _get_session_memory(ctx: Context) -> SessionMemoryStore:
+    """Get or create the session-scoped SessionMemoryStore."""
+    return ctx.lifespan_context.setdefault("session_memory", SessionMemoryStore())
+
+
+def _get_taste_memory(ctx: Context) -> TasteMemoryStore:
+    """Get or create the session-scoped TasteMemoryStore."""
+    return ctx.lifespan_context.setdefault("taste_memory", TasteMemoryStore())
+
+
+@mcp.tool()
+def get_anti_preferences(ctx: Context) -> dict:
+    """Return all recorded anti-preferences — dimensions the user has repeatedly disliked."""
+    store = _get_anti_memory(ctx)
+    return store.to_dict()
+
+
+@mcp.tool()
+def record_anti_preference(
+    ctx: Context, dimension: str, direction: str
+) -> dict:
+    """Record a user dislike for a dimension+direction. direction must be 'increase' or 'decrease'."""
+    if direction not in ("increase", "decrease"):
+        return {"error": "direction must be 'increase' or 'decrease'"}
+    store = _get_anti_memory(ctx)
+    pref = store.record_dislike(dimension, direction)
+    return {
+        "recorded": pref.to_dict(),
+        "should_caution": store.should_caution(dimension, direction),
+    }
+
+
+@mcp.tool()
+def get_promotion_candidates(ctx: Context, limit: int = 10) -> dict:
+    """Check the session ledger for entries eligible for memory promotion."""
+    ledger = ctx.lifespan_context.get("action_ledger")
+    if ledger is None:
+        return {"candidates": [], "count": 0, "note": "no session ledger active"}
+
+    # Get memory candidates from ledger and evaluate
+    raw_candidates = ledger.get_memory_candidates()
+    entry_dicts = [e.to_dict() for e in raw_candidates]
+    eligible = batch_evaluate_promotions(entry_dicts)
+
+    # Apply limit
+    eligible = eligible[:limit]
+    return {
+        "candidates": [c.to_dict() for c in eligible],
+        "count": len(eligible),
+    }
+
+
+# ── Session Memory ──────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_session_memory(
+    ctx: Context, limit: int = 10, category: str = ""
+) -> dict:
+    """Return recent session memory entries — ephemeral observations, hypotheses, decisions."""
+    store = _get_session_memory(ctx)
+    cat = category.strip() or None
+    entries = store.get_recent(limit=limit, category=cat)
+    return {
+        "entries": [e.to_dict() for e in entries],
+        "count": len(entries),
+    }
+
+
+@mcp.tool()
+def add_session_memory(
+    ctx: Context, category: str, content: str, engine: str = "agent_os"
+) -> dict:
+    """Add an ephemeral session memory entry (observation, hypothesis, decision, issue)."""
+    store = _get_session_memory(ctx)
+    try:
+        entry_id = store.add(category=category, content=content, engine=engine)
+    except ValueError as exc:
+        return {"error": str(exc)}
+    return {"id": entry_id, "status": "added"}
+
+
+# ── Taste Memory ────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_taste_dimensions(ctx: Context) -> dict:
+    """Return all taste dimensions — user preferences inferred from kept/undone outcomes."""
+    store = _get_taste_memory(ctx)
+    return store.to_dict()

package/mcp_server/mix_engine/__init__.py

@@ -0,0 +1 @@
+"""Mix Engine V1 — dedicated mixing intelligence."""

package/mcp_server/mix_engine/critics.py

@@ -0,0 +1,299 @@
+"""Mix Engine critics — detect mix issues from state data.
+
+Six critics: balance, masking, dynamics, stereo, depth, translation.
+All pure computation, zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+from .models import (
+    BalanceState,
+    DepthState,
+    DynamicsState,
+    MaskingMap,
+    MixState,
+    StereoState,
+)
+
+
+# ── MixIssue ───────────────────────────────────────────────────────
+
+
+@dataclass
+class MixIssue:
+    """A single detected mix issue."""
+
+    issue_type: str = ""
+    critic: str = ""
+    severity: float = 0.0
+    confidence: float = 0.0
+    affected_tracks: list[int] = field(default_factory=list)
+    evidence: str = ""
+    recommended_moves: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Balance Critic ──────────────────────────────────────────────────
+
+
+def run_balance_critic(balance: BalanceState) -> list[MixIssue]:
+    """Detect balance problems: anchor too weak, support too loud."""
+    issues: list[MixIssue] = []
+    active = [t for t in balance.track_states if not t.mute]
+
+    if not active:
+        return issues
+
+    # Compute average volume of active tracks
+    avg_vol = sum(t.volume for t in active) / len(active)
+
+    # Check if anchor tracks are too quiet
+    for t in active:
+        if t.track_index in balance.anchor_tracks:
+            if t.volume < avg_vol * 0.6:
+                issues.append(MixIssue(
+                    issue_type="anchor_too_weak",
+                    critic="balance",
+                    severity=min(1.0, (avg_vol - t.volume) / max(avg_vol, 0.01)),
+                    confidence=0.7,
+                    affected_tracks=[t.track_index],
+                    evidence=(
+                        f"Anchor track '{t.name}' (role={t.role}) at volume "
+                        f"{t.volume:.2f}, average is {avg_vol:.2f}"
+                    ),
+                    recommended_moves=["gain_staging"],
+                ))
+
+    # Check if non-anchor tracks are too loud
+    for t in active:
+        if t.track_index not in balance.anchor_tracks:
+            if t.volume > avg_vol * 1.5 and t.role not in ("kick", "bass", "vocal", "lead"):
+                issues.append(MixIssue(
+                    issue_type="support_too_loud",
+                    critic="balance",
+                    severity=min(1.0, (t.volume - avg_vol) / max(avg_vol, 0.01)),
+                    confidence=0.6,
+                    affected_tracks=[t.track_index],
+                    evidence=(
+                        f"Support track '{t.name}' (role={t.role}) at volume "
+                        f"{t.volume:.2f}, average is {avg_vol:.2f}"
+                    ),
+                    recommended_moves=["gain_staging"],
+                ))
+
+    return issues
+
+
+# ── Masking Critic ──────────────────────────────────────────────────
+
+
+def run_masking_critic(masking: MaskingMap) -> list[MixIssue]:
+    """Detect frequency collision issues from masking map."""
+    issues: list[MixIssue] = []
+
+    for entry in masking.entries:
+        if entry.severity >= 0.4:
+            issues.append(MixIssue(
+                issue_type="frequency_collision",
+                critic="masking",
+                severity=entry.severity,
+                confidence=0.6,
+                affected_tracks=[entry.track_a, entry.track_b],
+                evidence=(
+                    f"Tracks {entry.track_a} and {entry.track_b} collide "
+                    f"in {entry.overlap_band} band (severity {entry.severity:.2f})"
+                ),
+                recommended_moves=["eq_correction"],
+            ))
+
+    return issues
+
+
+# ── Dynamics Critic ─────────────────────────────────────────────────
+
+
+def run_dynamics_critic(dynamics: DynamicsState) -> list[MixIssue]:
+    """Detect dynamics problems: over-compression, flat dynamics, low headroom."""
+    issues: list[MixIssue] = []
+
+    if dynamics.over_compressed:
+        issues.append(MixIssue(
+            issue_type="over_compressed",
+            critic="dynamics",
+            severity=min(1.0, max(0.0, (6.0 - dynamics.crest_factor_db) / 6.0)),
+            confidence=0.7,
+            affected_tracks=[],
+            evidence=(
+                f"Crest factor {dynamics.crest_factor_db:.1f} dB — "
+                f"dynamics are flat, likely over-compressed"
+            ),
+            recommended_moves=["bus_compression", "transient_shaping"],
+        ))
+
+    if dynamics.crest_factor_db < 3.0 and dynamics.crest_factor_db > 0:
+        issues.append(MixIssue(
+            issue_type="flat_dynamics",
+            critic="dynamics",
+            severity=0.8,
+            confidence=0.8,
+            affected_tracks=[],
+            evidence=(
+                f"Crest factor {dynamics.crest_factor_db:.1f} dB — "
+                f"extremely flat, transients are lost"
+            ),
+            recommended_moves=["transient_shaping", "gain_staging"],
+        ))
+
+    if dynamics.headroom < 1.0:
+        issues.append(MixIssue(
+            issue_type="low_headroom",
+            critic="dynamics",
+            severity=min(1.0, (1.0 - dynamics.headroom)),
+            confidence=0.9,
+            affected_tracks=[],
+            evidence=f"Only {dynamics.headroom:.1f} dB headroom — clipping risk",
+            recommended_moves=["gain_staging"],
+        ))
+
+    return issues
+
+
+# ── Stereo Critic ───────────────────────────────────────────────────
+
+
+def run_stereo_critic(stereo: StereoState) -> list[MixIssue]:
+    """Detect stereo problems: center collapse, overwide."""
+    issues: list[MixIssue] = []
+
+    if stereo.mono_risk:
+        issues.append(MixIssue(
+            issue_type="center_collapse",
+            critic="stereo",
+            severity=0.6,
+            confidence=0.7,
+            affected_tracks=[],
+            evidence=(
+                f"Center strength {stereo.center_strength:.2f}, "
+                f"side activity {stereo.side_activity:.2f} — "
+                f"mix is essentially mono"
+            ),
+            recommended_moves=["width_adjustment"],
+        ))
+
+    if stereo.side_activity > 0.7:
+        issues.append(MixIssue(
+            issue_type="overwide",
+            critic="stereo",
+            severity=min(1.0, stereo.side_activity - 0.5),
+            confidence=0.5,
+            affected_tracks=[],
+            evidence=(
+                f"Side activity {stereo.side_activity:.2f} — "
+                f"mix may be too wide, center elements could be weak"
+            ),
+            recommended_moves=["width_adjustment"],
+        ))
+
+    return issues
+
+
+# ── Depth Critic ────────────────────────────────────────────────────
+
+
+def run_depth_critic(depth: DepthState) -> list[MixIssue]:
+    """Detect depth problems: no separation, excessive wash."""
+    issues: list[MixIssue] = []
+
+    if depth.depth_separation < 0.05 and depth.wet_dry_ratio > 0.0:
+        issues.append(MixIssue(
+            issue_type="no_depth_separation",
+            critic="depth",
+            severity=0.5,
+            confidence=0.5,
+            affected_tracks=[],
+            evidence=(
+                f"Depth separation {depth.depth_separation:.3f} — "
+                f"all tracks at similar depth, no front/back contrast"
+            ),
+            recommended_moves=["send_rebalance"],
+        ))
+
+    if depth.wash_risk:
+        issues.append(MixIssue(
+            issue_type="excessive_wash",
+            critic="depth",
+            severity=min(1.0, depth.wet_dry_ratio),
+            confidence=0.6,
+            affected_tracks=[],
+            evidence=(
+                f"Wet/dry ratio {depth.wet_dry_ratio:.2f} — "
+                f"excessive reverb/delay washing out the mix"
+            ),
+            recommended_moves=["send_rebalance"],
+        ))
+
+    return issues
+
+
+# ── Translation Critic ──────────────────────────────────────────────
+
+
+def run_translation_critic(
+    dynamics: DynamicsState,
+    stereo: StereoState,
+) -> list[MixIssue]:
+    """Detect translation risks: mono weakness, harshness risk."""
+    issues: list[MixIssue] = []
+
+    # Mono weakness: wide mix with weak center
+    if stereo.side_activity > 0.5 and stereo.center_strength < 0.3:
+        issues.append(MixIssue(
+            issue_type="mono_weakness",
+            critic="translation",
+            severity=0.7,
+            confidence=0.6,
+            affected_tracks=[],
+            evidence=(
+                f"Side activity {stereo.side_activity:.2f} with center "
+                f"strength {stereo.center_strength:.2f} — mono playback "
+                f"will lose significant content"
+            ),
+            recommended_moves=["width_adjustment", "gain_staging"],
+        ))
+
+    # Harshness risk: over-compressed + low headroom
+    if dynamics.over_compressed and dynamics.headroom < 3.0:
+        issues.append(MixIssue(
+            issue_type="harshness_risk",
+            critic="translation",
+            severity=0.6,
+            confidence=0.5,
+            affected_tracks=[],
+            evidence=(
+                f"Over-compressed (crest {dynamics.crest_factor_db:.1f} dB) "
+                f"with only {dynamics.headroom:.1f} dB headroom — "
+                f"will sound harsh on smaller speakers"
+            ),
+            recommended_moves=["gain_staging", "bus_compression"],
+        ))
+
+    return issues
+
+
+# ── Run all critics ─────────────────────────────────────────────────
+
+
+def run_all_mix_critics(mix_state: MixState) -> list[MixIssue]:
+    """Run all six critics and aggregate issues."""
+    issues: list[MixIssue] = []
+    issues.extend(run_balance_critic(mix_state.balance))
+    issues.extend(run_masking_critic(mix_state.masking))
+    issues.extend(run_dynamics_critic(mix_state.dynamics))
+    issues.extend(run_stereo_critic(mix_state.stereo))
+    issues.extend(run_depth_critic(mix_state.depth))
+    issues.extend(run_translation_critic(mix_state.dynamics, mix_state.stereo))
+    return issues

package/mcp_server/mix_engine/models.py

@@ -0,0 +1,152 @@
+"""Mix Engine state models — all dataclasses with to_dict().
+
+Pure data structures representing the five mix subgraphs
+(BalanceState, MaskingMap, DynamicsState, StereoState, DepthState)
+plus the composite MixState container.
+
+Zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+# ── Track-level state ───────────────────────────────────────────────
+
+
+@dataclass
+class TrackMixState:
+    """Mix-relevant state for a single track."""
+
+    track_index: int = 0
+    name: str = ""
+    role: str = "unknown"
+    volume: float = 0.0
+    pan: float = 0.0
+    mute: bool = False
+    solo: bool = False
+    send_levels: list[float] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Balance ─────────────────────────────────────────────────────────
+
+
+@dataclass
+class BalanceState:
+    """Track-level and role-weighted loudness balance."""
+
+    track_states: list[TrackMixState] = field(default_factory=list)
+    anchor_tracks: list[int] = field(default_factory=list)
+    loudest_track: int = -1
+    quietest_track: int = -1
+
+    def to_dict(self) -> dict:
+        return {
+            "track_states": [t.to_dict() for t in self.track_states],
+            "anchor_tracks": list(self.anchor_tracks),
+            "loudest_track": self.loudest_track,
+            "quietest_track": self.quietest_track,
+        }
+
+
+# ── Masking ─────────────────────────────────────────────────────────
+
+
+@dataclass
+class MaskingEntry:
+    """A single frequency masking collision between two tracks."""
+
+    track_a: int = 0
+    track_b: int = 0
+    overlap_band: str = ""
+    severity: float = 0.0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class MaskingMap:
+    """All detected frequency masking collisions."""
+
+    entries: list[MaskingEntry] = field(default_factory=list)
+    worst_pair: Optional[tuple[int, int]] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "entries": [e.to_dict() for e in self.entries],
+            "worst_pair": list(self.worst_pair) if self.worst_pair else None,
+        }
+
+
+# ── Dynamics ────────────────────────────────────────────────────────
+
+
+@dataclass
+class DynamicsState:
+    """Master dynamics condition."""
+
+    crest_factor_db: float = 0.0
+    over_compressed: bool = False
+    headroom: float = 0.0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Stereo ──────────────────────────────────────────────────────────
+
+
+@dataclass
+class StereoState:
+    """Stereo field condition."""
+
+    center_strength: float = 0.0
+    side_activity: float = 0.0
+    mono_risk: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Depth ───────────────────────────────────────────────────────────
+
+
+@dataclass
+class DepthState:
+    """Front-to-back depth separation."""
+
+    wet_dry_ratio: float = 0.0
+    depth_separation: float = 0.0
+    wash_risk: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Composite container ────────────────────────────────────────────
+
+
+@dataclass
+class MixState:
+    """Top-level container for all mix sub-states."""
+
+    balance: BalanceState = field(default_factory=BalanceState)
+    masking: MaskingMap = field(default_factory=MaskingMap)
+    dynamics: DynamicsState = field(default_factory=DynamicsState)
+    stereo: StereoState = field(default_factory=StereoState)
+    depth: DepthState = field(default_factory=DepthState)
+
+    def to_dict(self) -> dict:
+        return {
+            "balance": self.balance.to_dict(),
+            "masking": self.masking.to_dict(),
+            "dynamics": self.dynamics.to_dict(),
+            "stereo": self.stereo.to_dict(),
+            "depth": self.depth.to_dict(),
+        }

package/mcp_server/mix_engine/planner.py

@@ -0,0 +1,103 @@
+"""Mix Engine planner — rank and suggest mix moves.
+
+Pure computation, zero I/O.  Takes critic issues and mix state,
+returns a ranked list of reversible moves.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+from .critics import MixIssue
+from .models import MixState
+
+
+# ── MixMove ─────────────────────────────────────────────────────────
+
+
+@dataclass
+class MixMove:
+    """A single suggested mix move."""
+
+    move_type: str = ""
+    target_tracks: list[int] = field(default_factory=list)
+    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: "track" < "bus" < "master" — prefer smallest scope
+_MOVE_META: dict[str, tuple[str, float]] = {
+    "eq_correction": ("track", 0.1),
+    "transient_shaping": ("track", 0.15),
+    "saturation_adjustment": ("track", 0.2),
+    "width_adjustment": ("track", 0.15),
+    "send_rebalance": ("track", 0.1),
+    "gain_staging": ("track", 0.05),
+    "bus_compression": ("bus", 0.25),
+}
+
+_SCOPE_PENALTY: dict[str, float] = {
+    "track": 0.0,
+    "bus": 0.1,
+    "master": 0.2,
+}
+
+
+# ── Planner ─────────────────────────────────────────────────────────
+
+
+def plan_mix_moves(
+    issues: list[MixIssue],
+    mix_state: MixState,
+) -> list[MixMove]:
+    """Generate a ranked list of suggested moves from detected issues.
+
+    Ranking: estimated_impact * (1 - risk), highest first.
+    Prefers track-level moves over bus-level moves.
+
+    Returns an empty list if no issues are present.
+    """
+    if not issues:
+        return []
+
+    moves: list[MixMove] = []
+
+    for issue in issues:
+        for move_type in issue.recommended_moves:
+            scope, base_risk = _MOVE_META.get(move_type, ("track", 0.2))
+            risk = min(1.0, base_risk + _SCOPE_PENALTY.get(scope, 0.0))
+            impact = issue.severity * issue.confidence
+
+            move = MixMove(
+                move_type=move_type,
+                target_tracks=list(issue.affected_tracks),
+                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 preferring
+    # track-level (lower scope penalty).
+    def _rank_key(m: MixMove) -> tuple[float, float]:
+        score = m.estimated_impact * (1.0 - m.risk)
+        scope, _ = _MOVE_META.get(m.move_type, ("track", 0.2))
+        scope_order = _SCOPE_PENALTY.get(scope, 0.0)
+        return (-score, scope_order)
+
+    moves.sort(key=_rank_key)
+    return moves