livepilot 1.9.14 → 1.9.16

package/mcp_server/tools/_research_provider.py

@@ -0,0 +1,185 @@
+"""Research Provider Router — explicit provider ladder with mode-based routing.
+
+Pure Python, zero I/O.  Determines which research providers to query based on
+the research mode (targeted, deep, background_mining) and provider availability.
+
+Design: spec at docs/specs/2026-04-08-phase2-4-roadmap.md, Round 3.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+# ── Provider Definitions ────────────────────────────────────────────
+
+@dataclass
+class ResearchProvider:
+    """A single research data source with cost and priority metadata."""
+
+    name: str  # "session_evidence", "local_docs", "memory", etc.
+    available: bool
+    priority: int  # 1=highest
+    cost: str  # "free", "low", "medium", "high"
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+PROVIDER_LADDER: list[ResearchProvider] = [
+    ResearchProvider("session_evidence", True, 1, "free"),
+    ResearchProvider("local_docs", True, 2, "free"),
+    ResearchProvider("memory", True, 3, "free"),
+    ResearchProvider("user_references", False, 4, "low"),
+    ResearchProvider("structured_connectors", False, 5, "medium"),
+    ResearchProvider("web", False, 6, "high"),
+]
+
+# Which providers each mode is allowed to use
+_MODE_ALLOWED: dict[str, set[str]] = {
+    "targeted": {"session_evidence", "local_docs", "memory"},
+    "deep": {
+        "session_evidence", "local_docs", "memory",
+        "user_references", "structured_connectors", "web",
+    },
+    "background_mining": {"session_evidence", "memory"},
+}
+
+_VALID_MODES = set(_MODE_ALLOWED.keys())
+
+
+# ── Provider Selection ──────────────────────────────────────────────
+
+def get_available_providers(
+    capability_state: Optional[dict] = None,
+) -> list[ResearchProvider]:
+    """Return providers that are currently available.
+
+    capability_state: optional dict of provider_name -> bool overrides.
+    """
+    result: list[ResearchProvider] = []
+    overrides = capability_state or {}
+
+    for p in PROVIDER_LADDER:
+        available = overrides.get(p.name, p.available)
+        result.append(ResearchProvider(
+            name=p.name,
+            available=available,
+            priority=p.priority,
+            cost=p.cost,
+        ))
+
+    return result
+
+
+def route_research(
+    query: str,
+    mode: str,
+    providers: Optional[list[ResearchProvider]] = None,
+) -> dict:
+    """Determine which providers to query based on mode.
+
+    Returns: {
+        mode, query, providers_to_query: [provider dicts],
+        skipped: [provider dicts with reason],
+    }
+    """
+    if mode not in _VALID_MODES:
+        return {
+            "error": f"invalid mode {mode!r}, must be one of {sorted(_VALID_MODES)}",
+        }
+
+    if providers is None:
+        providers = get_available_providers()
+
+    allowed_names = _MODE_ALLOWED[mode]
+
+    to_query: list[dict] = []
+    skipped: list[dict] = []
+
+    for p in sorted(providers, key=lambda x: x.priority):
+        if p.name not in allowed_names:
+            skipped.append({**p.to_dict(), "reason": f"not allowed in {mode} mode"})
+        elif not p.available:
+            skipped.append({**p.to_dict(), "reason": "provider not available"})
+        else:
+            to_query.append(p.to_dict())
+
+    return {
+        "mode": mode,
+        "query": query,
+        "providers_to_query": to_query,
+        "skipped": skipped,
+    }
+
+
+# ── Research Outcome Feedback ───────────────────────────────────────
+
+@dataclass
+class ResearchOutcomeFeedback:
+    """Track whether research results were actually useful."""
+
+    research_id: str
+    technique_card_id: str
+    applied: bool
+    move_kept: bool
+    score: float  # 0-1
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class ResearchFeedbackStore:
+    """In-memory store for research effectiveness tracking."""
+
+    def __init__(self) -> None:
+        self._entries: list[ResearchOutcomeFeedback] = []
+
+    def record(self, feedback: ResearchOutcomeFeedback) -> dict:
+        """Record research feedback.  Returns summary."""
+        self._entries.append(feedback)
+        return {
+            "recorded": feedback.to_dict(),
+            "total_feedback": len(self._entries),
+            "effectiveness": self._effectiveness(),
+        }
+
+    def _effectiveness(self) -> dict:
+        """Compute aggregate effectiveness stats."""
+        if not self._entries:
+            return {"applied_rate": 0.0, "kept_rate": 0.0, "avg_score": 0.0, "count": 0}
+
+        applied = sum(1 for e in self._entries if e.applied)
+        kept = sum(1 for e in self._entries if e.move_kept)
+        avg_score = sum(e.score for e in self._entries) / len(self._entries)
+
+        return {
+            "applied_rate": round(applied / len(self._entries), 3),
+            "kept_rate": round(kept / len(self._entries), 3),
+            "avg_score": round(avg_score, 3),
+            "count": len(self._entries),
+        }
+
+    def get_effectiveness(self) -> dict:
+        """Public access to effectiveness stats."""
+        return self._effectiveness()
+
+    def get_all(self) -> list[dict]:
+        """Return all feedback entries."""
+        return [e.to_dict() for e in self._entries]
+
+    def to_dict(self) -> dict:
+        return {
+            "feedback": self.get_all(),
+            "effectiveness": self._effectiveness(),
+        }
+
+
+def record_research_feedback(feedback: ResearchOutcomeFeedback) -> dict:
+    """Standalone function to create a feedback record dict."""
+    return {
+        "feedback": feedback.to_dict(),
+        "timestamp_ms": int(time.time() * 1000),
+    }

package/mcp_server/tools/_snapshot_normalizer.py

@@ -0,0 +1,49 @@
+"""Snapshot Normalizer — canonical input normalization for all evaluators.
+
+Ensures analyzer outputs are in a consistent schema regardless of
+which tool produced them. All evaluators should consume normalized
+snapshots, never raw tool outputs.
+
+Design: AGENT_OS_PHASE0_HARDENING_PLAN.md, section 3.2
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+
+def normalize_sonic_snapshot(
+    raw: Optional[dict],
+    source: str = "unknown",
+) -> Optional[dict]:
+    """Normalize a raw analyzer/perception output into canonical snapshot form.
+
+    Accepts both {"bands": {...}} and {"spectrum": {...}} shapes.
+    Returns None if input is empty or None.
+
+    Canonical form:
+    {
+        "spectrum": {band: value, ...},
+        "rms": float or None,
+        "peak": float or None,
+        "detected_key": str or None,
+        "source": str,
+        "normalized_at_ms": int,
+    }
+    """
+    if not raw or not isinstance(raw, dict):
+        return None
+
+    bands = raw.get("spectrum") or raw.get("bands")
+    if not bands:
+        return None
+
+    return {
+        "spectrum": bands,
+        "rms": raw.get("rms"),
+        "peak": raw.get("peak"),
+        "detected_key": raw.get("key") or raw.get("detected_key"),
+        "source": source,
+        "normalized_at_ms": int(time.time() * 1000),
+    }

package/mcp_server/tools/agent_os.py

@@ -0,0 +1,448 @@
+"""Agent OS V1 MCP tools — goal compilation, world model, and evaluation.
+
+3 tools that connect the pure-computation engine (_agent_os_engine.py) to the
+live Ableton session via the existing MCP infrastructure.
+
+These tools power the Agent OS cyclical loop:
+  compile_goal_vector → build_world_model → [agent acts] → evaluate_move
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from ..memory.technique_store import TechniqueStore
+from . import _agent_os_engine as engine
+
+_memory_store = TechniqueStore()
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+def _get_spectral(ctx: Context):
+    return ctx.lifespan_context.get("spectral")
+
+
+def _parse_json_param(value, name: str) -> dict:
+    """Parse a dict, JSON string, or None parameter."""
+    if value is None:
+        return {}
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in {name}: {exc}") from exc
+    if isinstance(value, dict):
+        return value
+    raise ValueError(f"{name} must be a dict or JSON string")
+
+
+# ── compile_goal_vector ───────────────────────────────────────────────
+
+
+@mcp.tool()
+def compile_goal_vector(
+    ctx: Context,
+    request_text: str,
+    targets: dict | str,
+    protect: dict | str = "{}",
+    mode: str = "improve",
+    aggression: float = 0.5,
+    research_mode: str = "none",
+) -> dict:
+    """Compile a user request into a validated GoalVector.
+
+    The agent interprets the user's natural language into quality dimensions,
+    then this tool validates the schema and normalizes weights.
+
+    targets: dict of dimension → weight (e.g., {"punch": 0.4, "weight": 0.3, "energy": 0.3}).
+             Weights are normalized to sum to 1.0.
+    protect: dict of dimension → minimum threshold (e.g., {"clarity": 0.8}).
+             If a dimension drops below this value after a move, the move is undone.
+    mode: observe | improve | explore | finish | diagnose
+    aggression: 0.0 (subtle) to 1.0 (bold)
+    research_mode: none | targeted | deep
+
+    Valid dimensions: energy, punch, weight, density, brightness, warmth,
+    width, depth, motion, contrast, clarity, cohesion, groove, tension,
+    novelty, polish, emotion.
+    """
+    targets_dict = _parse_json_param(targets, "targets")
+    protect_dict = _parse_json_param(protect, "protect")
+
+    gv = engine.validate_goal_vector(
+        request_text=request_text,
+        targets=targets_dict,
+        protect=protect_dict,
+        mode=mode,
+        aggression=float(aggression),
+        research_mode=research_mode,
+    )
+
+    return {
+        "goal_vector": gv.to_dict(),
+        "measurable_dimensions": [
+            d for d in gv.targets if d in engine.MEASURABLE_PROXIES
+        ],
+        "unmeasurable_dimensions": [
+            d for d in gv.targets if d not in engine.MEASURABLE_PROXIES
+        ],
+    }
+
+
+# ── build_world_model ─────────────────────────────────────────────────
+
+
+@mcp.tool()
+def build_world_model(ctx: Context) -> dict:
+    """Build a WorldModel snapshot of the current Ableton session.
+
+    Reads session info, spectral data (if analyzer available), per-track
+    device health, and infers track roles from names. Degrades gracefully
+    if M4L Analyzer is not loaded.
+
+    Returns topology (tracks, devices, scenes), sonic state (spectrum, RMS, key),
+    technical state (analyzer/FluCoMa availability, plugin health), and
+    inferred track roles.
+    """
+    ableton = _get_ableton(ctx)
+    spectral = _get_spectral(ctx)
+
+    # Fetch session info (always available)
+    session_info = ableton.send_command("get_session_info")
+
+    # Fetch per-track device info for plugin health checks (I2 fix)
+    track_infos = []
+    for track in session_info.get("tracks", []):
+        try:
+            ti = ableton.send_command("get_track_info", {
+                "track_index": track["index"]
+            })
+            track_infos.append(ti)
+        except Exception:
+            pass  # Skip tracks that fail — don't block world model build
+
+    # Fetch spectral data (may be unavailable)
+    spectrum = None
+    rms = None
+    detected_key = None
+    flucoma_status = None
+
+    if spectral and spectral.is_connected:
+        spec_data = spectral.get("spectrum")
+        if spec_data:
+            spectrum = {"bands": spec_data["value"]}
+
+        rms_data = spectral.get("rms")
+        if rms_data:
+            rms = rms_data["value"] if isinstance(rms_data["value"], dict) else {"rms": rms_data["value"]}
+
+        key_data = spectral.get("key")
+        if key_data:
+            detected_key = key_data["value"] if isinstance(key_data["value"], dict) else {"key": key_data["value"]}
+
+        flucoma_data = spectral.get("flucoma_status")
+        if flucoma_data:
+            flucoma_status = flucoma_data["value"] if isinstance(flucoma_data["value"], dict) else {}
+    else:
+        flucoma_status = {"flucoma_available": False}
+
+    # Build model
+    wm = engine.build_world_model_from_data(
+        session_info=session_info,
+        spectrum=spectrum,
+        rms=rms,
+        detected_key=detected_key,
+        flucoma_status=flucoma_status,
+        track_infos=track_infos,
+    )
+
+    # Run critics with all-dimensions stub goal to surface all issues.
+    # The agent should filter these against its actual GoalVector.
+    goal_stub = engine.GoalVector(
+        request_text="world_model_build",
+        targets={d: 1.0 / len(engine.QUALITY_DIMENSIONS) for d in engine.QUALITY_DIMENSIONS},
+        mode="observe",
+    )
+    sonic_issues = engine.run_sonic_critic(wm.sonic, goal_stub, wm.track_roles)
+    technical_issues = engine.run_technical_critic(wm.technical)
+
+    # Round 1: Wire structural critic (composition engine) into world model
+    structural_issues = []
+    try:
+        from . import _composition_engine as comp_engine
+        # Build lightweight section graph for structural analysis
+        scenes = session_info.get("scenes", [])
+        track_count = session_info.get("track_count", 0)
+        clip_matrix = []
+        try:
+            matrix_data = ableton.send_command("get_scene_matrix")
+            clip_matrix = matrix_data.get("matrix", [])
+        except Exception:
+            pass
+
+        sections = comp_engine.build_section_graph_from_scenes(scenes, clip_matrix, track_count)
+        structural_issues = comp_engine.run_form_critic(sections)
+    except Exception:
+        pass  # Composition engine unavailable — degrade gracefully
+
+    result = wm.to_dict()
+    result["issues"] = {
+        "sonic": [i.to_dict() for i in sonic_issues],
+        "technical": [i.to_dict() for i in technical_issues],
+        "structural": [i.to_dict() for i in structural_issues],
+        "total_count": len(sonic_issues) + len(technical_issues) + len(structural_issues),
+        "note": "Issues are unfiltered — filter against your GoalVector targets before acting.",
+    }
+    return result
+
+
+# ── evaluate_move ─────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def evaluate_move(
+    ctx: Context,
+    goal_vector: dict | str,
+    before_snapshot: dict | str,
+    after_snapshot: dict | str,
+) -> dict:
+    """Evaluate whether a production move improved the mix toward the goal.
+
+    Takes before/after sonic snapshots and the active GoalVector.
+    Returns a score and keep/undo recommendation.
+
+    Snapshots should contain: spectrum (8-band dict), rms, peak.
+    Get these from get_master_spectrum + get_master_rms before and after
+    making changes.
+
+    Hard rules enforce undo when:
+    - No measurable improvement (delta <= 0)
+    - Protected dimension dropped below its threshold or by > 0.15
+    - Total score < 0.40
+
+    When all target dimensions are unmeasurable (e.g., groove, tension),
+    the tool defers keep/undo to the agent's musical judgment.
+
+    Returns consecutive_undo_hint=true when keep_change=false — the agent
+    should track consecutive undos and switch to observe mode after 3.
+    """
+    gv_dict = _parse_json_param(goal_vector, "goal_vector")
+    before = _parse_json_param(before_snapshot, "before_snapshot")
+    after = _parse_json_param(after_snapshot, "after_snapshot")
+
+    # I6 fix: validate the GoalVector to catch malformed input
+    gv = engine.validate_goal_vector(
+        request_text=gv_dict.get("request_text", "evaluate"),
+        targets=gv_dict.get("targets", {}),
+        protect=gv_dict.get("protect", {}),
+        mode=gv_dict.get("mode", "improve"),
+        aggression=float(gv_dict.get("aggression", 0.5)),
+        research_mode=gv_dict.get("research_mode", "none"),
+    )
+
+    return engine.compute_evaluation_score(gv, before, after)
+
+
+# ── analyze_outcomes (Round 1) ────────────────────────────────────────
+
+
+@mcp.tool()
+def analyze_outcomes(
+    ctx: Context,
+    limit: int = 50,
+) -> dict:
+    """Analyze accumulated outcome memories to identify user taste patterns.
+
+    Reads outcome-type memories from the technique library and returns:
+    - keep_rate: what percentage of moves does this user keep?
+    - dimension_success: which quality dimensions improve most often?
+    - common_kept_moves: which action types work best?
+    - common_undone_moves: which action types fail most?
+    - taste_vector: inferred dimension preferences from history
+
+    Use this before choosing moves to align with user taste.
+    The more outcomes stored (via memory_learn type="outcome"),
+    the better the taste analysis becomes.
+    """
+    # Fetch outcome memories directly from TechniqueStore
+    try:
+        techniques = _memory_store.list_techniques(
+            type_filter="outcome", sort_by="updated_at", limit=limit,
+        )
+    except Exception:
+        techniques = []
+
+    # Extract payloads from full technique records
+    outcomes = []
+    for t in techniques:
+        # list_techniques returns compact summaries; get full record for payload
+        try:
+            full = _memory_store.get(t["id"])
+            payload = full.get("payload", {})
+            if isinstance(payload, dict):
+                outcomes.append(payload)
+        except Exception:
+            pass
+
+    return engine.analyze_outcome_history(outcomes)
+
+
+# ── get_technique_card (Round 2) ──────────────────────────────────────
+
+
+@mcp.tool()
+def get_technique_card(
+    ctx: Context,
+    query: str,
+    limit: int = 5,
+) -> dict:
+    """Search for technique cards — structured production recipes.
+
+    Technique cards are reusable recipes saved from successful production
+    outcomes. Each card has: problem, context, devices, method, verification.
+
+    query: search term (e.g., "wider pad", "punchy kick", "sidechain bass")
+    limit: max results
+    """
+    # Search technique cards directly from TechniqueStore
+    try:
+        techniques = _memory_store.search(
+            query=query, type_filter="technique_card", limit=limit,
+        )
+    except Exception:
+        techniques = []
+
+    cards = []
+    for t in techniques:
+        # search() returns summaries without payload; get full record
+        try:
+            full = _memory_store.get(t["id"])
+            payload = full.get("payload", {})
+            if isinstance(payload, dict):
+                cards.append({
+                    "id": t.get("id"),
+                    "name": t.get("name"),
+                    "card": payload,
+                    "rating": t.get("rating", 0),
+                    "replay_count": t.get("replay_count", 0),
+                })
+        except Exception:
+            pass
+
+    return {
+        "query": query,
+        "cards": cards,
+        "count": len(cards),
+    }
+
+
+# ── get_taste_profile (Round 4) ────────────────────────────────────
+
+
+@mcp.tool()
+def get_taste_profile(
+    ctx: Context,
+    limit: int = 50,
+) -> dict:
+    """Get the user's production taste profile from outcome history.
+
+    Analyzes kept vs undone moves to identify: preferred dimensions,
+    avoided dimensions, taste vector weights, and overall keep rate.
+    Use this to understand what this user values in production.
+
+    limit: how many outcomes to analyze (default: 50)
+
+    Returns: {taste_vector, preferred_dimensions, avoided_dimensions,
+              keep_rate, sample_size}
+    """
+    # Fetch outcome memories directly from TechniqueStore
+    try:
+        techniques = _memory_store.list_techniques(
+            type_filter="outcome", sort_by="updated_at", limit=limit,
+        )
+    except Exception:
+        techniques = []
+
+    outcomes = []
+    for t in techniques:
+        try:
+            full = _memory_store.get(t["id"])
+            payload = full.get("payload", {})
+            if isinstance(payload, dict):
+                outcomes.append(payload)
+        except Exception:
+            pass
+
+    return engine.get_taste_profile(outcomes)
+
+
+# ── get_turn_budget (Conductor Budget) ────────────────────────────
+
+
+@mcp.tool()
+def get_turn_budget(
+    ctx: Context,
+    mode: str = "improve",
+    aggression: float = 0.5,
+) -> dict:
+    """Get a resource budget for the current agent turn.
+
+    Returns six resource pools that prevent overcommitting:
+    - latency_ms: time budget for this turn
+    - risk_points: how much risk is allowed (0-1)
+    - novelty_points: how much novelty is allowed (0-1)
+    - change_count: max production moves this turn
+    - undo_count: max consecutive undos before switching to observe
+    - research_calls: max research lookups this turn
+
+    mode: observe | improve | explore | finish | diagnose | performance
+      - observe: very low risk, zero changes, read-only
+      - improve: balanced defaults
+      - explore: high novelty, high risk, more moves
+      - finish: conservative, low novelty, few changes
+      - diagnose: zero changes, research-focused
+      - performance: very low latency, minimal risk
+    aggression: 0.0 (subtle) to 1.0 (bold) — scales risk and change limits
+
+    Use spend functions via the conductor to track consumption during the turn.
+    """
+    from . import _conductor_budgets as budgets
+
+    budget = budgets.create_budget(mode=mode, aggression=float(aggression))
+    summary = budgets.get_budget_summary(budget)
+    summary["budget"] = budget.to_dict()
+    summary["mode"] = mode
+    summary["aggression"] = float(aggression)
+    return summary
+
+
+# ── route_request (Conductor) ──────────────────────────────────────
+
+
+@mcp.tool()
+def route_request(
+    ctx: Context,
+    request: str,
+) -> dict:
+    """Route a production request to the right engine(s).
+
+    Analyzes natural language to determine which engines should handle
+    the request, in what priority order, with what entry tools.
+
+    request: what the user wants (e.g., "make this punchier", "turn the
+             loop into a song", "make it sound like Burial")
+
+    Returns: routing plan with engine priorities, entry tools, and
+    capability requirements.
+    """
+    from . import _conductor as conductor
+
+    plan = conductor.classify_request(request)
+    return plan.to_dict()