livepilot 1.9.23 → 1.10.0

package/mcp_server/sample_engine/models.py

@@ -0,0 +1,193 @@
+"""Sample Engine data models — all dataclasses with to_dict().
+
+Pure data structures for sample profiles, intents, critic results,
+fit reports, candidates, and techniques. Zero I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+VALID_MATERIAL_TYPES = frozenset({
+    "vocal", "drum_loop", "instrument_loop", "one_shot",
+    "texture", "foley", "fx", "full_mix", "unknown",
+})
+
+VALID_INTENTS = frozenset({
+    "rhythm", "texture", "layer", "melody", "vocal",
+    "atmosphere", "transform", "challenge",
+})
+
+VALID_SIMPLER_MODES = frozenset({"classic", "one_shot", "slice"})
+
+VALID_SLICE_METHODS = frozenset({"transient", "beat", "region", "manual"})
+
+VALID_WARP_MODES = frozenset({
+    "beats", "tones", "texture", "complex", "complex_pro",
+})
+
+
+@dataclass
+class SampleProfile:
+    """Complete fingerprint of a sample."""
+
+    source: str
+    file_path: str
+    name: str
+    uri: Optional[str] = None
+    freesound_id: Optional[int] = None
+    license: Optional[str] = None
+
+    key: Optional[str] = None
+    key_confidence: float = 0.0
+    bpm: Optional[float] = None
+    bpm_confidence: float = 0.0
+    time_signature: str = "4/4"
+
+    material_type: str = "unknown"
+    material_confidence: float = 0.0
+
+    frequency_center: float = 0.0
+    frequency_spread: float = 0.0
+    brightness: float = 0.0
+    transient_density: float = 0.0
+
+    duration_seconds: float = 0.0
+    duration_beats: Optional[float] = None
+    bar_count: Optional[float] = None
+    has_clear_downbeat: bool = False
+
+    suggested_mode: str = "classic"
+    suggested_slice_by: str = "transient"
+    suggested_warp_mode: str = "complex"
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class SampleIntent:
+    """What the user wants to do with a sample."""
+
+    intent_type: str
+    description: str
+    philosophy: str = "auto"
+    target_track: Optional[int] = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class CriticResult:
+    """Result from a single sample critic."""
+
+    critic_name: str
+    score: float
+    recommendation: str
+    adjustments: list = field(default_factory=list)
+
+    @property
+    def rating(self) -> str:
+        if self.score >= 0.8:
+            return "excellent"
+        if self.score >= 0.6:
+            return "good"
+        if self.score >= 0.4:
+            return "fair"
+        return "poor"
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["rating"] = self.rating
+        return d
+
+
+@dataclass
+class SampleFitReport:
+    """Output of the 6-critic battery."""
+
+    sample: SampleProfile
+    critics: dict  # str -> CriticResult
+    recommended_intent: str = ""
+    recommended_technique: str = ""
+    processing_chain: list = field(default_factory=list)
+    warnings: list = field(default_factory=list)
+    surgeon_plan: list = field(default_factory=list)
+    alchemist_plan: list = field(default_factory=list)
+
+    @property
+    def overall_score(self) -> float:
+        if not self.critics:
+            return 0.0
+        scores = [c.score if isinstance(c, CriticResult) else c.get("score", 0)
+                  for c in self.critics.values()]
+        return sum(scores) / len(scores) if scores else 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "sample": self.sample.to_dict(),
+            "overall_score": round(self.overall_score, 3),
+            "critics": {k: (v.to_dict() if isinstance(v, CriticResult) else v)
+                        for k, v in self.critics.items()},
+            "recommended_intent": self.recommended_intent,
+            "recommended_technique": self.recommended_technique,
+            "processing_chain": self.processing_chain,
+            "warnings": self.warnings,
+            "surgeon_plan": self.surgeon_plan,
+            "alchemist_plan": self.alchemist_plan,
+        }
+
+
+@dataclass
+class SampleCandidate:
+    """A sample discovered by a source, pre-load."""
+
+    source: str
+    name: str
+    metadata: dict = field(default_factory=dict)
+    file_path: Optional[str] = None
+    uri: Optional[str] = None
+    freesound_id: Optional[int] = None
+    relevance_score: float = 0.0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class TechniqueStep:
+    """A single step in a sample technique recipe."""
+
+    tool: str
+    params: dict = field(default_factory=dict)
+    description: str = ""
+    condition: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class SampleTechnique:
+    """A sample manipulation recipe from the technique library."""
+
+    technique_id: str
+    name: str
+    philosophy: str
+    material_types: list = field(default_factory=list)
+    intents: list = field(default_factory=list)
+    difficulty: str = "basic"
+    description: str = ""
+    inspiration: str = ""
+    steps: list = field(default_factory=list)  # list[TechniqueStep]
+    success_signals: list = field(default_factory=list)
+    failure_signals: list = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["steps"] = [s.to_dict() if isinstance(s, TechniqueStep) else s
+                      for s in self.steps]
+        return d

package/mcp_server/sample_engine/moves.py

@@ -0,0 +1,127 @@
+"""Sample-domain semantic moves — musical intents for sample manipulation.
+
+These moves express creative sample-based intentions that compile to
+deterministic tool sequences via the sample compilers.
+"""
+
+from ..semantic_moves.models import SemanticMove
+from ..semantic_moves.registry import register
+
+SAMPLE_CHOP_RHYTHM = SemanticMove(
+    move_id="sample_chop_rhythm",
+    family="sample",
+    intent="Chop a sample into rhythmic slices — create a new groove from existing material",
+    targets={"groove": 0.5, "novelty": 0.3, "punch": 0.2},
+    protect={"clarity": 0.6, "coherence": 0.5},
+    risk_level="medium",
+    compile_plan=[
+        {"tool": "load_sample_to_simpler", "params": {"description": "Load sample into Simpler for slicing"}, "description": "Load into Simpler", "backend": "bridge_command"},
+        {"tool": "set_simpler_playback_mode", "params": {"mode": "slice", "description": "Switch to slice mode for rhythmic chopping"}, "description": "Enable slice mode", "backend": "remote_command"},
+        {"tool": "crop_simpler", "params": {"description": "Crop to rhythmically relevant region"}, "description": "Crop to useful region", "backend": "bridge_command"},
+    ],
+    verification_plan=[
+        {"tool": "get_simpler_slices", "check": "slices present and evenly distributed", "backend": "bridge_command"},
+        {"tool": "get_track_meters", "check": "track producing audio after slicing", "backend": "remote_command"},
+    ],
+)
+
+SAMPLE_TEXTURE_LAYER = SemanticMove(
+    move_id="sample_texture_layer",
+    family="sample",
+    intent="Layer a sample as background texture — stretching and filtering for atmosphere",
+    targets={"depth": 0.4, "motion": 0.3, "warmth": 0.3},
+    protect={"clarity": 0.7, "punch": 0.5},
+    risk_level="low",
+    compile_plan=[
+        {"tool": "load_sample_to_simpler", "params": {"description": "Load textural sample into Simpler"}, "description": "Load texture sample", "backend": "bridge_command"},
+        {"tool": "set_simpler_playback_mode", "params": {"mode": "classic", "description": "Classic mode for sustained texture playback"}, "description": "Classic playback", "backend": "remote_command"},
+        {"tool": "set_device_parameter", "params": {"description": "Lower filter cutoff to sit beneath main elements"}, "description": "Filter for background placement", "backend": "remote_command"},
+        {"tool": "set_track_send", "params": {"description": "Add reverb send for spatial depth"}, "description": "Reverb for depth", "backend": "remote_command"},
+    ],
+    verification_plan=[
+        {"tool": "get_track_meters", "check": "track producing audio at low level", "backend": "remote_command"},
+    ],
+)
+
+SAMPLE_VOCAL_GHOST = SemanticMove(
+    move_id="sample_vocal_ghost",
+    family="sample",
+    intent="Create ghostly vocal texture — pitch-shift, reverse, and wash a vocal sample",
+    targets={"novelty": 0.4, "depth": 0.3, "motion": 0.3},
+    protect={"clarity": 0.5},
+    risk_level="medium",
+    compile_plan=[
+        {"tool": "load_sample_to_simpler", "params": {"description": "Load vocal sample into Simpler"}, "description": "Load vocal", "backend": "bridge_command"},
+        {"tool": "reverse_simpler", "params": {"description": "Reverse for ghostly character"}, "description": "Reverse vocal", "backend": "bridge_command"},
+        {"tool": "set_device_parameter", "params": {"description": "Detune -5 to -12 semitones for haunting pitch"}, "description": "Pitch down for ghost effect", "backend": "remote_command"},
+        {"tool": "set_track_send", "params": {"description": "Heavy reverb send 40-60% for wash"}, "description": "Reverb wash", "backend": "remote_command"},
+    ],
+    verification_plan=[
+        {"tool": "get_track_meters", "check": "track producing audio with reverb tail", "backend": "remote_command"},
+    ],
+)
+
+SAMPLE_BREAK_LAYER = SemanticMove(
+    move_id="sample_break_layer",
+    family="sample",
+    intent="Layer a breakbeat over existing drums — slice and rearrange for energy",
+    targets={"groove": 0.4, "punch": 0.3, "novelty": 0.3},
+    protect={"coherence": 0.6, "clarity": 0.5},
+    risk_level="medium",
+    compile_plan=[
+        {"tool": "create_midi_track", "params": {"description": "New track for break layer"}, "description": "Create break track", "backend": "remote_command"},
+        {"tool": "load_sample_to_simpler", "params": {"description": "Load breakbeat into Simpler"}, "description": "Load break", "backend": "bridge_command"},
+        {"tool": "set_simpler_playback_mode", "params": {"mode": "slice", "slice_by": "transient", "description": "Slice by transients for individual hits"}, "description": "Slice break by transients", "backend": "remote_command"},
+        {"tool": "set_track_volume", "params": {"description": "Set break layer volume below main drums"}, "description": "Balance break level", "backend": "remote_command"},
+    ],
+    verification_plan=[
+        {"tool": "get_simpler_slices", "check": "break sliced into individual hits", "backend": "bridge_command"},
+        {"tool": "get_track_meters", "check": "break track producing audio, not overpowering drums", "backend": "remote_command"},
+    ],
+)
+
+SAMPLE_RESAMPLE_DESTROY = SemanticMove(
+    move_id="sample_resample_destroy",
+    family="sample",
+    intent="Destructively resample — warp, bitcrush, and mangle for creative destruction",
+    targets={"novelty": 0.5, "motion": 0.3, "groove": 0.2},
+    protect={"coherence": 0.4},
+    risk_level="high",
+    compile_plan=[
+        {"tool": "load_sample_to_simpler", "params": {"description": "Load sample for destruction"}, "description": "Load source material", "backend": "bridge_command"},
+        {"tool": "warp_simpler", "params": {"description": "Extreme warp settings for time-stretch artifacts"}, "description": "Warp for artifacts", "backend": "bridge_command"},
+        {"tool": "set_device_parameter", "params": {"description": "Add Redux or bitcrusher for lo-fi destruction"}, "description": "Bitcrush/reduce", "backend": "remote_command"},
+        {"tool": "set_device_parameter", "params": {"description": "Saturator drive to maximum for harmonic distortion"}, "description": "Saturate heavily", "backend": "remote_command"},
+    ],
+    verification_plan=[
+        {"tool": "get_track_meters", "check": "track producing audio, signal significantly transformed", "backend": "remote_command"},
+    ],
+)
+
+SAMPLE_ONE_SHOT_ACCENT = SemanticMove(
+    move_id="sample_one_shot_accent",
+    family="sample",
+    intent="Place a one-shot sample as rhythmic accent — trigger on key beats for punctuation",
+    targets={"punch": 0.4, "groove": 0.3, "novelty": 0.3},
+    protect={"clarity": 0.6, "coherence": 0.5},
+    risk_level="low",
+    compile_plan=[
+        {"tool": "load_sample_to_simpler", "params": {"description": "Load one-shot into Simpler"}, "description": "Load one-shot", "backend": "bridge_command"},
+        {"tool": "set_simpler_playback_mode", "params": {"mode": "one_shot", "description": "One-shot mode for trigger playback"}, "description": "One-shot mode", "backend": "remote_command"},
+        {"tool": "crop_simpler", "params": {"description": "Tight crop around the transient"}, "description": "Crop to transient", "backend": "bridge_command"},
+    ],
+    verification_plan=[
+        {"tool": "get_track_meters", "check": "one-shot triggers cleanly on beat", "backend": "remote_command"},
+    ],
+)
+
+# Register all sample moves
+for _move in [
+    SAMPLE_CHOP_RHYTHM,
+    SAMPLE_TEXTURE_LAYER,
+    SAMPLE_VOCAL_GHOST,
+    SAMPLE_BREAK_LAYER,
+    SAMPLE_RESAMPLE_DESTROY,
+    SAMPLE_ONE_SHOT_ACCENT,
+]:
+    register(_move)

package/mcp_server/sample_engine/planner.py

@@ -0,0 +1,186 @@
+"""SamplePlanner — technique selection and plan compilation.
+
+Pure computation. Selects the best technique for a given sample + intent,
+then compiles it into a concrete sequence of MCP tool calls.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .models import SampleProfile, SampleIntent, SampleTechnique
+from .techniques import find_techniques, get_technique
+
+
+def select_technique(
+    profile: SampleProfile,
+    intent: SampleIntent,
+    taste_graph: object = None,
+    recent_techniques: Optional[list[str]] = None,
+) -> Optional[SampleTechnique]:
+    """Select the best technique for this sample + intent.
+
+    Scoring: material_match(0.3) + intent_match(0.3) + philosophy_match(0.2) +
+             novelty_bonus(0.1) + taste_fit(0.1)
+    """
+    candidates = find_techniques(
+        material_type=profile.material_type,
+        intent=intent.intent_type,
+        philosophy=intent.philosophy if intent.philosophy != "auto" else None,
+    )
+
+    if not candidates:
+        # Broaden search — try without material filter
+        candidates = find_techniques(intent=intent.intent_type)
+
+    if not candidates:
+        return None
+
+    recent = set(recent_techniques or [])
+
+    scored: list[tuple[SampleTechnique, float]] = []
+    for t in candidates:
+        score = 0.0
+
+        # Material match
+        if profile.material_type in t.material_types:
+            score += 0.3
+        elif "any" in t.material_types or not t.material_types:
+            score += 0.15
+
+        # Intent match
+        if intent.intent_type in t.intents:
+            score += 0.3
+        elif any(i in t.intents for i in _related_intents(intent.intent_type)):
+            score += 0.15
+
+        # Philosophy match
+        if intent.philosophy == "auto" or intent.philosophy == t.philosophy or t.philosophy == "both":
+            score += 0.2
+        elif intent.philosophy != t.philosophy:
+            score += 0.05
+
+        # Novelty bonus
+        if t.technique_id not in recent:
+            score += 0.1
+
+        scored.append((t, score))
+
+    scored.sort(key=lambda x: -x[1])
+    return scored[0][0] if scored else None
+
+
+def _related_intents(intent_type: str) -> list[str]:
+    """Get related intents for broader matching."""
+    relations = {
+        "rhythm": ["layer", "transform"],
+        "texture": ["atmosphere", "transform"],
+        "layer": ["melody", "rhythm"],
+        "melody": ["layer", "vocal"],
+        "vocal": ["melody", "texture"],
+        "atmosphere": ["texture"],
+        "transform": ["texture", "rhythm", "atmosphere"],
+        "challenge": ["transform"],
+    }
+    return relations.get(intent_type, [])
+
+
+def compile_sample_plan(
+    profile: SampleProfile,
+    intent: SampleIntent,
+    target_track: Optional[int] = None,
+    technique: Optional[SampleTechnique] = None,
+) -> list[dict]:
+    """Compile a concrete tool-call plan for sample manipulation.
+
+    Returns list of {tool, params, description} dicts ready for execution.
+    """
+    if technique is None:
+        technique = select_technique(profile, intent)
+    if technique is None:
+        return _fallback_plan(profile, intent, target_track)
+
+    plan: list[dict] = []
+
+    for step in technique.steps:
+        compiled_step = {
+            "tool": step.tool,
+            "params": _resolve_params(step.params, profile, intent, target_track),
+            "description": step.description,
+        }
+        if step.condition:
+            if not _evaluate_condition(step.condition, profile, intent):
+                continue
+        plan.append(compiled_step)
+
+    return plan
+
+
+def _resolve_params(
+    params: dict,
+    profile: SampleProfile,
+    intent: SampleIntent,
+    target_track: Optional[int],
+) -> dict:
+    """Resolve template variables in technique step params."""
+    replacements = {
+        "{file_path}": profile.file_path,
+        "{track_index}": target_track if target_track is not None else 0,
+        "{material_type}": profile.material_type,
+        "{key}": profile.key or "",
+        "{bpm}": profile.bpm or 120.0,
+        "{name}": profile.name,
+    }
+
+    def _resolve_single(v, repl):
+        """Resolve a single value against replacements."""
+        if isinstance(v, str):
+            # Exact template match — return the raw typed value
+            if v in repl:
+                return repl[v]
+            # Partial template substitution within a longer string
+            for template, value in repl.items():
+                v = v.replace(template, str(value))
+            return v
+        return v
+
+    resolved = {}
+    for k, v in params.items():
+        if isinstance(v, list):
+            resolved[k] = [_resolve_single(item, replacements) for item in v]
+        else:
+            resolved[k] = _resolve_single(v, replacements)
+    return resolved
+
+
+def _evaluate_condition(condition: str, profile: SampleProfile,
+                        intent: SampleIntent) -> bool:
+    """Evaluate a simple condition string."""
+    if "material_type" in condition:
+        for mt in ("vocal", "drum_loop", "instrument_loop", "one_shot",
+                   "texture", "foley", "fx", "full_mix"):
+            if f'material_type == "{mt}"' in condition:
+                return profile.material_type == mt
+    if "philosophy" in condition:
+        for p in ("surgeon", "alchemist"):
+            if f'philosophy == "{p}"' in condition:
+                return intent.philosophy == p
+    return True
+
+
+def _fallback_plan(
+    profile: SampleProfile,
+    intent: SampleIntent,
+    target_track: Optional[int],
+) -> list[dict]:
+    """Generic fallback when no technique matches."""
+    track = target_track if target_track is not None else 0
+    return [
+        {"tool": "load_sample_to_simpler",
+         "params": {"track_index": track, "file_path": profile.file_path},
+         "description": f"Load {profile.name} into Simpler"},
+        {"tool": "set_simpler_playback_mode",
+         "params": {"track_index": track, "device_index": 0,
+                     "playback_mode": 2 if profile.suggested_mode == "slice" else 0},
+         "description": f"Set Simpler to {profile.suggested_mode} mode"},
+    ]