livepilot 1.9.13 → 1.9.15

package/mcp_server/tools/_conductor.py

@@ -0,0 +1,199 @@
+"""Conductor — intelligent request routing to specialized engines.
+
+Analyzes a natural-language production request and determines which engines
+should handle it, in what order, with what priority. This is the "brain"
+that connects all the specialist engines into a coherent workflow.
+
+Zero external dependencies beyond stdlib.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+# ── Engine Registry ──────────────────────────────────────────────────
+
+@dataclass
+class EngineRoute:
+    """A routing decision for a single engine."""
+    engine: str
+    priority: int  # 1=primary, 2=secondary, 3=supporting
+    reason: str
+    entry_tool: str  # which MCP tool to call first
+    follow_up_tools: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ConductorPlan:
+    """Full routing plan for a production request."""
+    request: str
+    request_type: str  # "mix", "composition", "sound_design", "transition", etc.
+    routes: list[EngineRoute] = field(default_factory=list)
+    capability_requirements: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+    budget: Optional[dict] = None
+
+    def to_dict(self) -> dict:
+        result = {
+            "request": self.request,
+            "request_type": self.request_type,
+            "routes": [r.to_dict() for r in self.routes],
+            "engine_count": len(self.routes),
+            "primary_engine": self.routes[0].engine if self.routes else None,
+            "capability_requirements": self.capability_requirements,
+            "notes": self.notes,
+        }
+        if self.budget is not None:
+            result["budget"] = self.budget
+        return result
+
+
+# ── Request Classification ───────────────────────────────────────────
+
+# Keyword → (engine, request_type, entry_tool, follow_up_tools)
+_ROUTING_PATTERNS: list[tuple[str, str, str, str, list[str]]] = [
+    # Mix requests
+    (r"clean|mud|muddy|low.?mid|eq|equaliz", "mix_engine", "mix", "analyze_mix", ["plan_mix_move", "evaluate_mix_move"]),
+    (r"punch|punchy|transient|dynamics|compress", "mix_engine", "mix", "analyze_mix", ["plan_mix_move"]),
+    (r"wide|wider|width|stereo|narrow|mono.?compat", "mix_engine", "mix", "analyze_mix", ["plan_mix_move"]),
+    (r"glue|cohes|bus.?comp|mix.?bus", "mix_engine", "mix", "analyze_mix", ["plan_mix_move"]),
+    (r"balance|level|volume.?balanc|gain.?stag", "mix_engine", "mix", "analyze_mix", ["plan_mix_move"]),
+    (r"headroom|clip|peak|limit", "mix_engine", "mix", "analyze_mix", ["plan_mix_move"]),
+    (r"depth|dry|wet|reverb.?mix|send", "mix_engine", "mix", "analyze_mix", ["plan_mix_move"]),
+    (r"mask|frequency.?collis|overlap", "mix_engine", "mix", "get_masking_report", ["plan_mix_move"]),
+
+    # Composition requests
+    (r"arrange|arrangement|song.?structure|loop.?to.?song", "composition", "composition", "plan_arrangement", ["analyze_composition"]),
+    (r"section|verse|chorus|drop|intro|outro|bridge|breakdown", "composition", "composition", "analyze_composition", ["get_section_graph"]),
+    (r"phrase|motif|pattern|repetit|variation", "composition", "composition", "analyze_composition", ["get_motif_graph"]),
+    (r"tension|energy.?arc|emotional|build.?up", "composition", "composition", "get_emotional_arc", ["analyze_composition"]),
+    (r"form|structure|reorder|expand|compress|split|insert", "composition", "composition", "transform_section", ["analyze_composition"]),
+
+    # Sound design requests
+    (r"synth|patch|oscillat|timbre|timbral|wavetable|operator", "sound_design", "sound_design", "analyze_sound_design", ["plan_sound_design_move"]),
+    (r"haunted|lush|aggressive|warm.?pad|fat.?bass|bright.?lead", "sound_design", "sound_design", "analyze_sound_design", ["plan_sound_design_move"]),
+    (r"modulation|lfo|movement|evolv|texture", "sound_design", "sound_design", "get_patch_model", ["analyze_sound_design"]),
+    (r"layer|sub.?layer|transient.?layer|body", "sound_design", "sound_design", "analyze_sound_design", ["plan_sound_design_move"]),
+
+    # Transition requests
+    (r"transition|handoff|arrival|drop.?feel|feel.?earned", "transition_engine", "transition", "analyze_transition", ["plan_transition"]),
+    (r"smooth|seamless|boundary|crossfade", "transition_engine", "transition", "analyze_transition", ["plan_transition"]),
+
+    # Reference requests
+    (r"reference|sound.?like|style.?of|burial|daft.?punk|inspired.?by", "reference_engine", "reference", "build_reference_profile", ["analyze_reference_gaps", "plan_reference_moves"]),
+    (r"compare|match|closer.?to", "reference_engine", "reference", "build_reference_profile", ["analyze_reference_gaps"]),
+
+    # Translation requests
+    (r"translat|mono|phone.?speaker|small.?speaker|earbud|headphone", "translation_engine", "translation", "check_translation", ["get_translation_issues"]),
+    (r"harsh|bright.?hurt|sibilant|ear.?fatigue", "translation_engine", "translation", "check_translation", []),
+
+    # Performance requests
+    (r"live|perform|set|scene.?steer|safe.?mode|improv", "performance_engine", "performance", "get_performance_state", ["get_performance_safe_moves"]),
+    (r"scene.?transition|handoff.?scene|energy.?steer", "performance_engine", "performance", "plan_scene_handoff", ["get_performance_safe_moves"]),
+
+    # Research requests
+    (r"research|how.?to|technique|tutorial|learn", "research", "research", "research_technique", []),
+    (r"style.?tactic|production.?style|genre.?approach", "research", "research", "get_style_tactics", []),
+]
+
+
+def classify_request(request: str) -> ConductorPlan:
+    """Analyze a production request and route to the right engines.
+
+    Returns a ConductorPlan with ranked engine routes and capability requirements.
+    """
+    lower = request.lower().strip()
+    if not lower:
+        return ConductorPlan(request=request, request_type="unknown",
+                             notes=["Empty request — ask the user what they want to do"])
+
+    # Score each engine by how many patterns match
+    engine_scores: dict[str, dict] = {}
+
+    for pattern, engine, req_type, entry_tool, follow_ups in _ROUTING_PATTERNS:
+        if re.search(pattern, lower):
+            if engine not in engine_scores:
+                engine_scores[engine] = {
+                    "score": 0, "request_type": req_type,
+                    "entry_tool": entry_tool, "follow_ups": follow_ups,
+                }
+            engine_scores[engine]["score"] += 1
+
+    if not engine_scores:
+        # Default: try Agent OS core loop (general "make it better")
+        return ConductorPlan(
+            request=request,
+            request_type="general",
+            routes=[EngineRoute(
+                engine="agent_os",
+                priority=1,
+                reason="No specific engine matched — using core Agent OS loop",
+                entry_tool="build_world_model",
+                follow_up_tools=["evaluate_move"],
+            )],
+            capability_requirements=["session_access"],
+            notes=["General request — Agent OS core loop with goal vector"],
+        )
+
+    # Sort engines by score (most matches = primary)
+    sorted_engines = sorted(engine_scores.items(), key=lambda x: -x[1]["score"])
+
+    routes: list[EngineRoute] = []
+    for i, (engine, info) in enumerate(sorted_engines):
+        routes.append(EngineRoute(
+            engine=engine,
+            priority=i + 1,
+            reason=f"Matched {info['score']} keyword pattern(s)",
+            entry_tool=info["entry_tool"],
+            follow_up_tools=info["follow_ups"],
+        ))
+
+    primary_type = sorted_engines[0][1]["request_type"]
+
+    # Determine capability requirements
+    caps = ["session_access"]
+    if any(r.engine == "mix_engine" for r in routes):
+        caps.append("analyzer")
+    if any(r.engine in ("reference_engine",) for r in routes):
+        caps.append("offline_perception")
+    if any(r.engine == "performance_engine" for r in routes):
+        caps.append("live_performance_safe")
+
+    # Always suggest starting with Project Brain for complex multi-engine tasks
+    notes = []
+    if len(routes) > 1:
+        notes.append("Multi-engine task — call build_project_brain first for shared state")
+    if any(r.engine == "mix_engine" for r in routes):
+        notes.append("Mix engine works best with analyzer data — check get_capability_state")
+
+    return ConductorPlan(
+        request=request,
+        request_type=primary_type,
+        routes=routes,
+        capability_requirements=caps,
+        notes=notes,
+    )
+
+
+def create_conductor_plan(
+    request: str,
+    mode: str = "improve",
+    aggression: float = 0.5,
+) -> ConductorPlan:
+    """Create a full ConductorPlan with routing + budget.
+
+    Combines classify_request (routing) with create_budget (resource limits)
+    into a single plan the agent can consume.
+    """
+    from . import _conductor_budgets as budgets
+
+    plan = classify_request(request)
+    budget = budgets.create_budget(mode=mode, aggression=aggression)
+    plan.budget = budget.to_dict()
+    return plan

package/mcp_server/tools/_conductor_budgets.py

@@ -0,0 +1,222 @@
+"""Conductor Budget System — prevents the agent from overcommitting.
+
+Every turn maintains six resource pools: latency, risk, novelty, change,
+undo, and research. Mode shapes the initial budget; spend functions enforce
+limits and return (updated_budget, allowed) tuples.
+
+Zero external dependencies beyond stdlib.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Tuple
+
+
+# ── TurnBudget ──────────────────────────────────────────────────────
+
+@dataclass
+class TurnBudget:
+    """Resource pools for a single agent turn."""
+
+    # Limits
+    latency_ms: int = 30000       # max 30s per turn
+    risk_points: float = 1.0      # 0-1, how much risk left
+    novelty_points: float = 0.5   # 0-1, how much novelty allowed
+    change_count: int = 3         # max moves per turn
+    undo_count: int = 3           # max consecutive undos before stop
+    research_calls: int = 2       # max research calls per turn
+
+    # Tracking
+    elapsed_ms: int = 0
+    risk_spent: float = 0.0
+    novelty_spent: float = 0.0
+    changes_made: int = 0
+    undos_consecutive: int = 0
+    research_used: int = 0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Mode Presets ────────────────────────────────────────────────────
+
+# Each mode overrides specific budget fields.
+# Keys map to TurnBudget field names.
+_MODE_PRESETS: dict[str, dict] = {
+    "observe": {
+        "risk_points": 0.1,
+        "novelty_points": 0.1,
+        "change_count": 0,
+        "research_calls": 0,
+        "latency_ms": 15000,
+    },
+    "improve": {
+        # Default values — no overrides needed
+    },
+    "explore": {
+        "risk_points": 1.0,
+        "novelty_points": 1.0,
+        "change_count": 5,
+        "research_calls": 3,
+        "latency_ms": 45000,
+    },
+    "finish": {
+        "risk_points": 0.3,
+        "novelty_points": 0.1,
+        "change_count": 2,
+        "research_calls": 1,
+        "latency_ms": 20000,
+    },
+    "diagnose": {
+        "risk_points": 0.0,
+        "novelty_points": 0.0,
+        "change_count": 0,
+        "research_calls": 3,
+        "latency_ms": 20000,
+    },
+    "performance": {
+        "risk_points": 0.2,
+        "novelty_points": 0.1,
+        "change_count": 2,
+        "undo_count": 1,
+        "research_calls": 0,
+        "latency_ms": 10000,
+    },
+}
+
+
+# ── Budget Factory ──────────────────────────────────────────────────
+
+def create_budget(mode: str = "improve", aggression: float = 0.5) -> TurnBudget:
+    """Create a TurnBudget shaped by mode and aggression.
+
+    mode: observe | improve | explore | finish | diagnose | performance
+    aggression: 0.0 (subtle) to 1.0 (bold) — scales risk and change limits.
+    """
+    aggression = max(0.0, min(1.0, float(aggression)))
+
+    budget = TurnBudget()
+
+    # Apply mode preset
+    preset = _MODE_PRESETS.get(mode, {})
+    for key, value in preset.items():
+        setattr(budget, key, value)
+
+    # Aggression scales risk_points and change_count (never below preset floor)
+    if mode not in ("observe", "diagnose"):
+        base_risk = budget.risk_points
+        budget.risk_points = round(base_risk * (0.5 + aggression * 0.5), 3)
+        base_changes = budget.change_count
+        budget.change_count = max(1, int(base_changes * (0.5 + aggression * 0.5)))
+
+    return budget
+
+
+# ── Spend Functions ─────────────────────────────────────────────────
+
+def spend_risk(budget: TurnBudget, amount: float) -> Tuple[TurnBudget, bool]:
+    """Spend risk points. Returns (updated_budget, allowed)."""
+    amount = max(0.0, float(amount))
+    remaining = budget.risk_points - budget.risk_spent
+    if amount > remaining + 1e-9:
+        return budget, False
+    budget.risk_spent = round(budget.risk_spent + amount, 6)
+    return budget, True
+
+
+def spend_change(budget: TurnBudget) -> Tuple[TurnBudget, bool]:
+    """Record one change. Returns (updated_budget, allowed)."""
+    if budget.changes_made >= budget.change_count:
+        return budget, False
+    budget.changes_made += 1
+    # A successful change resets consecutive undo count
+    budget.undos_consecutive = 0
+    return budget, True
+
+
+def record_undo(budget: TurnBudget) -> Tuple[TurnBudget, bool]:
+    """Record a consecutive undo. Returns False if limit exceeded (should stop)."""
+    budget.undos_consecutive += 1
+    if budget.undos_consecutive > budget.undo_count:
+        return budget, False
+    return budget, True
+
+
+def spend_research(budget: TurnBudget) -> Tuple[TurnBudget, bool]:
+    """Spend one research call. Returns (updated_budget, allowed)."""
+    if budget.research_used >= budget.research_calls:
+        return budget, False
+    budget.research_used += 1
+    return budget, True
+
+
+def spend_novelty(budget: TurnBudget, amount: float) -> Tuple[TurnBudget, bool]:
+    """Spend novelty points. Returns (updated_budget, allowed)."""
+    amount = max(0.0, float(amount))
+    remaining = budget.novelty_points - budget.novelty_spent
+    if amount > remaining + 1e-9:
+        return budget, False
+    budget.novelty_spent = round(budget.novelty_spent + amount, 6)
+    return budget, True
+
+
+# ── Budget Queries ──────────────────────────────────────────────────
+
+def is_budget_exhausted(budget: TurnBudget) -> bool:
+    """Check if any budget dimension is fully spent."""
+    if budget.elapsed_ms >= budget.latency_ms:
+        return True
+    if budget.risk_spent >= budget.risk_points:
+        return True
+    if budget.changes_made >= budget.change_count:
+        return True
+    if budget.undos_consecutive > budget.undo_count:
+        return True
+    if budget.novelty_spent >= budget.novelty_points:
+        return True
+    # research_used exhaustion alone doesn't exhaust the budget —
+    # running out of research calls just blocks further research.
+    return False
+
+
+def get_budget_summary(budget: TurnBudget) -> dict:
+    """Return a human-readable summary of the current budget state."""
+    return {
+        "latency": {
+            "used_ms": budget.elapsed_ms,
+            "limit_ms": budget.latency_ms,
+            "remaining_ms": max(0, budget.latency_ms - budget.elapsed_ms),
+            "exhausted": budget.elapsed_ms >= budget.latency_ms,
+        },
+        "risk": {
+            "spent": round(budget.risk_spent, 3),
+            "limit": round(budget.risk_points, 3),
+            "remaining": round(max(0.0, budget.risk_points - budget.risk_spent), 3),
+            "exhausted": budget.risk_spent >= budget.risk_points,
+        },
+        "novelty": {
+            "spent": round(budget.novelty_spent, 3),
+            "limit": round(budget.novelty_points, 3),
+            "remaining": round(max(0.0, budget.novelty_points - budget.novelty_spent), 3),
+            "exhausted": budget.novelty_spent >= budget.novelty_points,
+        },
+        "changes": {
+            "made": budget.changes_made,
+            "limit": budget.change_count,
+            "remaining": max(0, budget.change_count - budget.changes_made),
+            "exhausted": budget.changes_made >= budget.change_count,
+        },
+        "undos": {
+            "consecutive": budget.undos_consecutive,
+            "limit": budget.undo_count,
+            "should_stop": budget.undos_consecutive > budget.undo_count,
+        },
+        "research": {
+            "used": budget.research_used,
+            "limit": budget.research_calls,
+            "remaining": max(0, budget.research_calls - budget.research_used),
+            "exhausted": budget.research_used >= budget.research_calls,
+        },
+        "overall_exhausted": is_budget_exhausted(budget),
+    }

package/mcp_server/tools/_evaluation_contracts.py

@@ -0,0 +1,91 @@
+"""Evaluation Contracts — shared types for all engine evaluators.
+
+Defines the canonical evaluation request/result types and the
+authoritative registry of which quality dimensions are measurable.
+
+All engines should produce EvaluationResult objects. The Evaluation
+Fabric (Phase 1D) will consume these through a unified interface.
+
+Design: EVALUATION_FABRIC_V1.md, section 6
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+# ── Dimension Registry ───────────────────────────────────────────────
+
+# Authoritative registry: dimensions with working spectral proxies.
+# If it's not here, it's unmeasurable in current phase and the evaluator
+# must report confidence=0.0 for that dimension.
+MEASURABLE_DIMENSIONS: frozenset[str] = frozenset({
+    "brightness", "warmth", "weight", "clarity",
+    "density", "energy", "punch",
+})
+
+# All valid quality dimensions (measurable + unmeasurable).
+ALL_DIMENSIONS: frozenset[str] = frozenset({
+    "energy", "punch", "weight", "density", "brightness", "warmth",
+    "width", "depth", "motion", "contrast", "clarity", "cohesion",
+    "groove", "tension", "novelty", "polish", "emotion",
+})
+
+
+def is_dimension_measurable(dim: str) -> bool:
+    """Check if a dimension has a working spectral proxy."""
+    return dim in MEASURABLE_DIMENSIONS
+
+
+# ── Evaluation Request ───────────────────────────────────────────────
+
+@dataclass
+class EvaluationRequest:
+    """Canonical evaluation request — engine-agnostic.
+
+    All engines submit evaluation through this shape. The Evaluation
+    Fabric routes to the appropriate engine-specific evaluator.
+    """
+    engine: str
+    goal: dict = field(default_factory=dict)
+    before: dict = field(default_factory=dict)
+    after: dict = field(default_factory=dict)
+    protect: dict = field(default_factory=dict)
+    context: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Evaluation Result ────────────────────────────────────────────────
+
+@dataclass
+class EvaluationResult:
+    """Canonical evaluation result — all engines produce this shape.
+
+    Fields:
+        engine: which engine produced this result
+        score: 0-1 composite quality score
+        keep_change: should the move be kept?
+        goal_progress: -1 to 1, how much the goal improved
+        collateral_damage: 0-1, harm to protected dimensions
+        hard_rule_failures: list of rule names that triggered
+        dimension_changes: {dim: {before, after, delta}}
+        notes: human-readable explanation
+        decision_mode: "measured", "judgment", or "deferred"
+        memory_candidate: should this outcome be saved to memory?
+    """
+    engine: str
+    score: float = 0.0
+    keep_change: bool = True
+    goal_progress: float = 0.0
+    collateral_damage: float = 0.0
+    hard_rule_failures: list[str] = field(default_factory=list)
+    dimension_changes: dict = field(default_factory=dict)
+    notes: list[str] = field(default_factory=list)
+    decision_mode: str = "measured"
+    memory_candidate: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)