livepilot 1.9.21 → 1.9.23

package/mcp_server/creative_constraints/models.py

@@ -0,0 +1,75 @@
+"""Creative Constraints data models — pure dataclasses, zero I/O."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+CONSTRAINT_MODES = [
+    "use_loaded_devices_only",
+    "no_new_tracks",
+    "subtraction_only",
+    "arrangement_only",
+    "mood_shift_without_new_fx",
+    "make_it_stranger_but_keep_the_hook",
+    "club_translation_safe",
+    "performance_safe_creative",
+]
+
+
+@dataclass
+class ConstraintSet:
+    """A set of creative constraints for planning."""
+
+    constraints: list[str] = field(default_factory=list)
+    description: str = ""
+    reason: str = ""  # why these constraints help
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ReferencePrinciple:
+    """A distilled principle from a reference track."""
+
+    domain: str = ""  # "arrangement", "texture", "density", "width", "payoff", "emotional"
+    principle: str = ""  # human-readable principle
+    value: float = 0.0  # quantified where possible
+    applicability: float = 0.5  # 0-1 how applicable to current song
+    note: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ReferenceDistillation:
+    """Distilled principles from a reference, ready to apply."""
+
+    reference_id: str = ""
+    reference_description: str = ""
+    principles: list[ReferencePrinciple] = field(default_factory=list)
+    emotional_posture: str = ""
+    density_motion: str = ""
+    arrangement_patience: str = ""
+    texture_treatment: str = ""
+    foreground_background: str = ""
+    width_strategy: str = ""
+    payoff_architecture: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "reference_id": self.reference_id,
+            "reference_description": self.reference_description,
+            "principles": [p.to_dict() for p in self.principles],
+            "emotional_posture": self.emotional_posture,
+            "density_motion": self.density_motion,
+            "arrangement_patience": self.arrangement_patience,
+            "texture_treatment": self.texture_treatment,
+            "foreground_background": self.foreground_background,
+            "width_strategy": self.width_strategy,
+            "payoff_architecture": self.payoff_architecture,
+            "principle_count": len(self.principles),
+        }

package/mcp_server/creative_constraints/tools.py

@@ -0,0 +1,341 @@
+"""Creative Constraints MCP tools — 5 tools for constrained creativity
+and reference distillation.
+
+  apply_creative_constraint_set — activate creative constraints
+  distill_reference_principles — learn principles from a reference
+  map_reference_principles_to_song — translate reference into current song
+  generate_constrained_variants — generate triptych variants under constraints
+  generate_reference_inspired_variants — variants from reference principles
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import engine
+from .models import CONSTRAINT_MODES
+
+
+# Module-level cache for active constraints and distillations
+_active_constraints: Optional[engine.ConstraintSet] = None
+_cached_distillation: Optional[engine.ReferenceDistillation] = None
+
+
+@mcp.tool()
+def apply_creative_constraint_set(
+    ctx: Context,
+    constraints: list[str] | None = None,
+) -> dict:
+    """Apply creative constraints to focus suggestions.
+
+    Constraints modify planning and ranking, not just validation.
+    When stuck, try adding constraints instead of more unconstrained advice.
+
+    Available constraints:
+    - use_loaded_devices_only — only use what's already loaded
+    - no_new_tracks — work within existing tracks
+    - subtraction_only — only remove/reduce, no additions
+    - arrangement_only — only structural changes
+    - mood_shift_without_new_fx — shift mood with existing tools
+    - make_it_stranger_but_keep_the_hook — push novelty safely
+    - club_translation_safe — keep changes club/DJ-friendly
+    - performance_safe_creative — only live-safe changes
+
+    constraints: list of constraint names to activate
+    """
+    global _active_constraints
+
+    if not constraints:
+        return {
+            "error": "No constraints provided",
+            "available": CONSTRAINT_MODES,
+        }
+
+    cs = engine.build_constraint_set(constraints)
+    _active_constraints = cs
+
+    invalid = [c for c in constraints if c not in CONSTRAINT_MODES]
+    result = {
+        "active_constraints": cs.constraints,
+        "description": cs.description,
+        "reason": cs.reason,
+    }
+    if invalid:
+        result["invalid_constraints"] = invalid
+        result["available"] = CONSTRAINT_MODES
+
+    return result
+
+
+@mcp.tool()
+def distill_reference_principles(
+    ctx: Context,
+    reference_description: str = "",
+    style_name: str = "",
+) -> dict:
+    """Learn musical principles from a reference — not surface traits.
+
+    Extracts: emotional posture, density motion, arrangement patience,
+    texture treatment, width strategy, and payoff architecture.
+
+    Never outputs a plan that copies surface traits directly.
+    Always translates through the current song's identity.
+
+    reference_description: text description of the reference
+    style_name: optional style/genre name for style-based references
+    """
+    global _cached_distillation
+
+    if not reference_description.strip() and not style_name.strip():
+        return {"error": "Provide reference_description or style_name"}
+
+    # Build a reference profile from available data
+    reference_profile: dict = {}
+
+    # Try to get style tactics if style_name is provided
+    if style_name:
+        try:
+            from ..tools._research_engine import get_style_tactics
+            tactics = get_style_tactics(style_name)
+            if tactics:
+                reference_profile = {
+                    "emotional_stance": tactics.get("emotional_stance", ""),
+                    "density_arc": tactics.get("density_arc", []),
+                    "section_pacing": tactics.get("section_pacing", []),
+                    "width_depth": tactics.get("width_depth", {}),
+                    "spectral_contour": tactics.get("spectral_contour", {}),
+                    "groove_posture": tactics.get("groove_posture", {}),
+                    "harmonic_character": tactics.get("harmonic_character", ""),
+                }
+        except Exception:
+            pass
+
+    # Try to get a reference profile from the reference engine
+    if not reference_profile:
+        try:
+            from ..reference_engine.profile_builder import build_style_reference_profile
+            profile = build_style_reference_profile(
+                style_name or reference_description
+            )
+            reference_profile = profile.to_dict()
+        except Exception:
+            # Fallback: build from description keywords
+            reference_profile = _profile_from_description(reference_description)
+
+    distillation = engine.distill_reference_principles(
+        reference_profile=reference_profile,
+        reference_description=reference_description or style_name,
+    )
+    _cached_distillation = distillation
+
+    return distillation.to_dict()
+
+
+@mcp.tool()
+def map_reference_principles_to_song(
+    ctx: Context,
+) -> dict:
+    """Map distilled reference principles to the current song.
+
+    Must call distill_reference_principles first. Translates each
+    principle through the song's identity, loaded tools, and hook.
+
+    Returns actionable mappings — how to apply each principle
+    while preserving the song's own character.
+    """
+    if _cached_distillation is None:
+        return {"error": "No reference distilled yet — call distill_reference_principles first"}
+
+    song_brain = _get_song_brain_dict()
+
+    mappings = engine.map_principles_to_song(song_brain, _cached_distillation)
+
+    return {
+        "reference": _cached_distillation.reference_description,
+        "mappings": mappings,
+        "mapping_count": len(mappings),
+        "note": "Principles are adapted to your song — not copied from the reference",
+    }
+
+
+@mcp.tool()
+def generate_constrained_variants(
+    ctx: Context,
+    request_text: str,
+    constraints: list[str] | None = None,
+    kernel_id: str = "",
+) -> dict:
+    """Generate creative variants under active constraints.
+
+    Combines constraint filtering with the Preview Studio's triptych.
+    Each variant respects the constraint set — e.g., "subtraction_only"
+    means no variant adds new elements.
+
+    request_text: what the user wants
+    constraints: list of constraint names to apply (or uses currently active)
+    kernel_id: optional session kernel reference
+    """
+    if not request_text.strip():
+        return {"error": "request_text cannot be empty"}
+
+    # Apply constraints
+    active = _active_constraints
+    if constraints:
+        active = engine.build_constraint_set(constraints)
+
+    if not active or not active.constraints:
+        return {
+            "error": "No constraints active — call apply_creative_constraint_set first or provide constraints",
+            "available": CONSTRAINT_MODES,
+        }
+
+    # Generate variants via preview studio
+    try:
+        from ..preview_studio import engine as ps_engine
+        song_brain = _get_song_brain_dict()
+        taste_graph = {}
+        try:
+            from ..memory.taste_graph import build_taste_graph
+            from ..memory.taste_memory import TasteMemoryStore
+            from ..memory.anti_memory import AntiMemoryStore
+            taste_store = ctx.lifespan_context.setdefault("taste_memory", TasteMemoryStore())
+            anti_store = ctx.lifespan_context.setdefault("anti_memory", AntiMemoryStore())
+            taste_graph = build_taste_graph(taste_store=taste_store, anti_store=anti_store).to_dict()
+        except Exception:
+            pass
+
+        ps = ps_engine.create_preview_set(
+            request_text=f"[Constrained: {', '.join(active.constraints)}] {request_text}",
+            kernel_id=kernel_id,
+            strategy="creative_triptych",
+            song_brain=song_brain,
+            taste_graph=taste_graph,
+        )
+
+        # Validate each variant's compiled_plan against constraints
+        for v in ps.variants:
+            v.what_preserved = f"{v.what_preserved} | Constraints: {', '.join(active.constraints)}"
+            if v.compiled_plan:
+                plan = {"steps": [
+                    {"action": step.get("tool", ""), **step}
+                    for step in v.compiled_plan
+                ]}
+                validation = engine.validate_plan_against_constraints(plan, active)
+                if not validation["valid"]:
+                    v.compiled_plan = None
+                    v.what_changed = f"[FILTERED] {v.what_changed} — violates {', '.join(active.constraints)}"
+
+        return {
+            "preview_set": ps.to_dict(),
+            "constraints_applied": active.constraints,
+            "note": "Variants with violating plans have been filtered",
+        }
+    except Exception as e:
+        return {"error": f"Failed to generate constrained variants: {e}"}
+
+
+@mcp.tool()
+def generate_reference_inspired_variants(
+    ctx: Context,
+    request_text: str = "",
+    kernel_id: str = "",
+) -> dict:
+    """Generate creative variants inspired by a distilled reference.
+
+    Requires a prior call to distill_reference_principles.
+    Uses the distilled principles (not surface traits) to shape
+    each variant through the current song's identity.
+
+    request_text: optional extra context for what the user wants
+    kernel_id: optional session kernel reference
+    """
+    if _cached_distillation is None:
+        return {"error": "No reference distilled yet — call distill_reference_principles first"}
+
+    # Build request text from reference principles
+    principles_text = ", ".join(
+        p.principle for p in _cached_distillation.principles[:3]
+    )
+    full_request = (
+        f"Inspired by: {_cached_distillation.reference_description}. "
+        f"Key principles: {principles_text}. "
+        f"{request_text}"
+    ).strip()
+
+    # Generate variants via preview studio
+    try:
+        from ..preview_studio import engine as ps_engine
+        song_brain = _get_song_brain_dict()
+
+        ps = ps_engine.create_preview_set(
+            request_text=full_request,
+            kernel_id=kernel_id,
+            strategy="creative_triptych",
+            song_brain=song_brain,
+        )
+
+        # Annotate variants with reference info
+        for v in ps.variants:
+            v.why_it_matters = (
+                f"Reference-inspired: {_cached_distillation.reference_description}. "
+                f"{v.why_it_matters}"
+            )
+
+        return {
+            "preview_set": ps.to_dict(),
+            "reference": _cached_distillation.reference_description,
+            "principles_applied": [p.to_dict() for p in _cached_distillation.principles[:5]],
+            "note": "Variants are shaped by reference principles, not surface imitation",
+        }
+    except Exception as e:
+        return {"error": f"Failed to generate reference-inspired variants: {e}"}
+
+
+# ── Helpers ───────────────────────────────────────────────────────
+
+
+def _get_song_brain_dict() -> dict:
+    try:
+        from ..song_brain.tools import _current_brain
+        if _current_brain is not None:
+            return _current_brain.to_dict()
+    except Exception as _e:
+        if __debug__:
+            import sys
+            print(f"LivePilot: SongBrain unavailable in creative_constraints: {_e}", file=sys.stderr)
+    return {}
+
+
+def _profile_from_description(description: str) -> dict:
+    """Build a rough reference profile from text description."""
+    desc_lower = description.lower()
+
+    emotional_map = {
+        "dark": "tense",
+        "bright": "euphoric",
+        "sad": "melancholic",
+        "aggressive": "aggressive",
+        "dreamy": "dreamy",
+        "chill": "relaxed",
+        "intense": "aggressive",
+        "minimal": "restrained",
+    }
+
+    emotional = ""
+    for keyword, stance in emotional_map.items():
+        if keyword in desc_lower:
+            emotional = stance
+            break
+
+    return {
+        "emotional_stance": emotional,
+        "density_arc": [],
+        "section_pacing": [],
+        "width_depth": {},
+        "spectral_contour": {},
+        "groove_posture": {},
+        "harmonic_character": "",
+    }

package/mcp_server/experiment/__init__.py

@@ -0,0 +1,6 @@
+"""Experiment engine — branch-based creative search.
+
+Experiments let the system try multiple approaches to a musical problem,
+evaluate each one, and present ranked winners. Branches are virtual —
+they use Ableton's undo system to revert between trials.
+"""

package/mcp_server/experiment/engine.py

@@ -0,0 +1,213 @@
+"""Experiment engine — runs branches sequentially using Ableton's undo system.
+
+The engine manages the lifecycle: create branches from semantic moves,
+run each one (apply → capture → undo), evaluate, rank, and commit the winner.
+
+Critical constraint: Ableton has linear undo. Experiments MUST run sequentially:
+  1. Capture before state
+  2. Apply semantic move (compiled plan)
+  3. Capture after state
+  4. Undo all changes back to the checkpoint
+  5. Repeat for next branch
+  6. When winner is chosen, re-apply that branch's moves permanently
+
+All I/O happens through the AbletonConnection passed to run methods.
+The engine itself is pure orchestration logic.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from typing import Optional
+
+from .models import ExperimentSet, ExperimentBranch, BranchSnapshot
+
+
+# ── In-memory experiment store ───────────────────────────────────────────────
+
+_EXPERIMENTS: dict[str, ExperimentSet] = {}
+
+
+def _gen_id(prefix: str, seed: str) -> str:
+    """Generate a short deterministic ID."""
+    h = hashlib.sha256(f"{prefix}:{seed}:{time.time()}".encode()).hexdigest()[:8]
+    return f"{prefix}_{h}"
+
+
+# ── Create experiments ───────────────────────────────────────────────────────
+
+def create_experiment(
+    request_text: str,
+    move_ids: list[str],
+    kernel_id: str = "",
+) -> ExperimentSet:
+    """Create an experiment set with branches for each semantic move.
+
+    Does NOT execute anything — just creates the branch structures.
+    Call run_experiment() to actually trial each branch.
+    """
+    exp_id = _gen_id("exp", request_text)
+    now = int(time.time() * 1000)
+
+    branches = []
+    for i, move_id in enumerate(move_ids):
+        branch = ExperimentBranch(
+            branch_id=_gen_id("br", f"{move_id}_{i}"),
+            name=f"Branch {i+1}: {move_id}",
+            move_id=move_id,
+            source_kernel_id=kernel_id,
+            status="pending",
+            created_at_ms=now,
+        )
+        branches.append(branch)
+
+    experiment = ExperimentSet(
+        experiment_id=exp_id,
+        request_text=request_text,
+        branches=branches,
+        status="open",
+        created_at_ms=now,
+    )
+
+    _EXPERIMENTS[exp_id] = experiment
+    return experiment
+
+
+def get_experiment(experiment_id: str) -> Optional[ExperimentSet]:
+    """Get an experiment by ID."""
+    return _EXPERIMENTS.get(experiment_id)
+
+
+def list_experiments() -> list[dict]:
+    """List all experiment sets."""
+    return [exp.to_dict() for exp in _EXPERIMENTS.values()]
+
+
+# ── Run experiments (requires Ableton connection) ────────────────────────────
+
+def run_branch(
+    branch: ExperimentBranch,
+    ableton,  # AbletonConnection
+    compiled_plan: dict,
+    capture_fn,  # function() -> BranchSnapshot
+) -> ExperimentBranch:
+    """Run a single branch experiment.
+
+    1. Capture before state
+    2. Execute compiled plan steps
+    3. Capture after state
+    4. Undo all changes
+
+    The branch is updated in-place with snapshots and status.
+    """
+    branch.status = "running"
+    branch.compiled_plan = compiled_plan
+
+    # 1. Capture before
+    branch.before_snapshot = capture_fn()
+
+    # 2. Execute plan steps
+    steps_executed = 0
+    for step in compiled_plan.get("steps", []):
+        tool = step.get("tool", "")
+        params = step.get("params", {})
+        if not tool:
+            continue
+        # Skip read-only verification steps
+        if tool in ("get_track_meters", "get_master_spectrum", "analyze_mix"):
+            continue
+        try:
+            ableton.send_command(tool, params)
+            steps_executed += 1
+        except Exception:
+            pass  # Best effort — continue with remaining steps
+
+    branch.executed_at_ms = int(time.time() * 1000)
+
+    # 3. Capture after
+    branch.after_snapshot = capture_fn()
+
+    # 4. Undo all changes back to checkpoint
+    for _ in range(steps_executed):
+        try:
+            ableton.send_command("undo", {})
+        except Exception:
+            break
+
+    branch.status = "evaluated"
+    return branch
+
+
+def evaluate_branch(
+    branch: ExperimentBranch,
+    evaluate_fn,  # function(before, after) -> dict with "score", "keep_change"
+) -> ExperimentBranch:
+    """Score a branch using the evaluation fabric."""
+    if not branch.before_snapshot or not branch.after_snapshot:
+        branch.evaluation = {"error": "Missing snapshots"}
+        branch.score = 0.0
+        return branch
+
+    result = evaluate_fn(
+        branch.before_snapshot.to_dict(),
+        branch.after_snapshot.to_dict(),
+    )
+    branch.evaluation = result
+    branch.score = result.get("score", 0.0)
+    return branch
+
+
+# ── Commit / discard ─────────────────────────────────────────────────────────
+
+def commit_branch(
+    experiment: ExperimentSet,
+    branch_id: str,
+    ableton,
+) -> dict:
+    """Re-apply the winning branch's moves permanently."""
+    branch = experiment.get_branch(branch_id)
+    if not branch:
+        return {"error": f"Branch {branch_id} not found"}
+
+    if not branch.compiled_plan:
+        return {"error": "Branch has no compiled plan"}
+
+    # Re-execute the plan (this time without undoing)
+    executed = []
+    for step in branch.compiled_plan.get("steps", []):
+        tool = step.get("tool", "")
+        params = step.get("params", {})
+        if not tool or tool in ("get_track_meters", "get_master_spectrum", "analyze_mix"):
+            continue
+        try:
+            result = ableton.send_command(tool, params)
+            executed.append({"tool": tool, "ok": True})
+        except Exception as exc:
+            executed.append({"tool": tool, "ok": False, "error": str(exc)})
+
+    branch.status = "committed"
+    experiment.winner_branch_id = branch_id
+    experiment.status = "committed"
+
+    return {
+        "committed": True,
+        "branch_id": branch_id,
+        "branch_name": branch.name,
+        "steps_executed": len(executed),
+        "score": branch.score,
+    }
+
+
+def discard_experiment(experiment_id: str) -> dict:
+    """Discard an entire experiment set."""
+    exp = _EXPERIMENTS.get(experiment_id)
+    if not exp:
+        return {"error": f"Experiment {experiment_id} not found"}
+
+    for branch in exp.branches:
+        if branch.status not in ("committed", "discarded"):
+            branch.status = "discarded"
+    exp.status = "discarded"
+
+    return {"discarded": True, "experiment_id": experiment_id}