livepilot 1.23.6 → 1.24.0

package/mcp_server/composer/develop/brief_builder.py

@@ -0,0 +1,269 @@
+"""Develop-mode brief builder — Phase 1 of the LLM-creative two-phase flow.
+
+Takes a SeedState (from seed_introspector) and an optional prompt directive,
+returns a brief carrying VOCABULARY for the agent to design variants from.
+
+CRITICAL: The brief MUST NOT contain predetermined section sequences, bar
+counts, or fixed variant taxonomies. The agent decides those per call.
+The framework only provides:
+- The existing seed (read-only context)
+- Genre/artist character vocabulary (descriptive)
+- The 42-event structural lexicon (named primitives, not a sequence)
+- Atlas instrument alternates (for sample-trigger swaps)
+- Research hooks (WebSearch directives for niche styles)
+- An open-ended design_targets text describing the variation surface
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+
+# ── artist vocabulary loader ────────────────────────────────────────
+
+# Cached after first load; ARTIST_NAMES is a tuple of producer names parsed from
+# artist-vocabularies.md (matches the file's ### heading lines).
+_ARTIST_NAMES_CACHE: Optional[tuple[str, ...]] = None
+
+
+def _load_artist_names() -> tuple[str, ...]:
+    """Parse artist-vocabularies.md for known producer names (cached).
+
+    Artist entries use ### headings (h3). Section groupings use ## (h2).
+    We parse ### lines only.
+    """
+    global _ARTIST_NAMES_CACHE
+    if _ARTIST_NAMES_CACHE is not None:
+        return _ARTIST_NAMES_CACHE
+
+    # Locate the markdown file relative to repo root
+    here = Path(__file__).resolve()
+    # Walk up to find livepilot/skills/livepilot-core/references/artist-vocabularies.md
+    for parent in here.parents:
+        candidate = (
+            parent
+            / "livepilot"
+            / "skills"
+            / "livepilot-core"
+            / "references"
+            / "artist-vocabularies.md"
+        )
+        if candidate.exists():
+            text = candidate.read_text(encoding="utf-8")
+            names = []
+            for line in text.splitlines():
+                # Artist entries are ### headings, e.g. "### Burial"
+                # or "### Aphex Twin (Richard D. James)"
+                m = re.match(r"^###\s+(.+?)\s*$", line)
+                if m:
+                    raw = m.group(1).strip()
+                    # Strip parenthetical aliases: "Aphex Twin (Richard D. James)" → "Aphex Twin"
+                    # Keep the primary name only
+                    primary = re.sub(r"\s*\(.*?\)\s*$", "", raw).strip()
+                    if primary:
+                        names.append(primary)
+                        # Also add alias if present (the part inside parens)
+                        alias_m = re.search(r"\(([^)]+)\)", raw)
+                        if alias_m:
+                            alias = alias_m.group(1).strip()
+                            # Only add meaningful aliases (not descriptive phrases)
+                            if alias and len(alias.split()) <= 4:
+                                names.append(alias)
+            _ARTIST_NAMES_CACHE = tuple(names)
+            return _ARTIST_NAMES_CACHE
+
+    # Fallback if the markdown isn't found: empty tuple
+    _ARTIST_NAMES_CACHE = ()
+    return _ARTIST_NAMES_CACHE
+
+
+def extract_artist_refs(prompt: str) -> list[str]:
+    """Find producer names in the prompt (case-insensitive substring match).
+
+    Returns a list of canonical artist names (preserving the artist-
+    vocabularies.md spelling — the primary name, not the alias).
+    """
+    if not prompt:
+        return []
+    names = _load_artist_names()
+    if not names:
+        return []
+    prompt_lower = prompt.lower()
+    found = []
+    seen_lower: set[str] = set()
+    for name in names:
+        name_lower = name.lower()
+        if name_lower in seen_lower:
+            continue
+        if name_lower in prompt_lower:
+            found.append(name)
+            seen_lower.add(name_lower)
+    return found
+
+
+# ── research hooks ──────────────────────────────────────────────────
+
+# Common-genre terms that DON'T need research (LLM training data covers them)
+_COMMON_GENRE_TERMS = {
+    "techno",
+    "house",
+    "ambient",
+    "hiphop",
+    "hip-hop",
+    "trap",
+    "pop",
+    "rock",
+    "jazz",
+    "edm",
+    "electronic",
+    "dance",
+    "downtempo",
+    "minimal",
+    "deep house",
+    "minor",
+    "major",
+    "key",
+    "tempo",
+    "bpm",
+    "lo-fi",
+    "lofi",
+    "dark",
+}
+
+# Niche terms that warrant research (not exhaustive — heuristic)
+_NICHE_GENRE_HINTS = (
+    "wonky",
+    "uk funky",
+    "footwork",
+    "juke",
+    "kuduro",
+    "gqom",
+    "speed garage",
+    "hyperpop",
+    "vapor",
+    "chillwave",
+    "future garage",
+    "dubstep wobble",
+    "psy-trance",
+    "psytrance",
+    "balearic",
+    "italo",
+    "freestyle",
+    "screwed",
+    "chopped and screwed",
+    "phonk",
+    "drift phonk",
+)
+
+
+def detect_research_hooks(prompt: str) -> list[str]:
+    """Identify niche style terms the agent should research before designing.
+
+    Returns a list of terms found in the prompt that are NOT in the common
+    set. Heuristic — agent uses these as WebSearch directives.
+    """
+    if not prompt:
+        return []
+    prompt_lower = prompt.lower()
+    hooks = []
+    for hint in _NICHE_GENRE_HINTS:
+        if hint in prompt_lower:
+            hooks.append(hint)
+    return hooks
+
+
+# ── atlas alternates (stub for Phase 4 enrichment) ─────────────────
+
+def _atlas_alternates_per_role(seed_state: dict) -> dict:
+    """For sample-trigger roles, return alternate sample suggestions.
+
+    Phase 1 stub — returns empty dict per role. Phase 4 KnowledgePack
+    integration will populate with real atlas_search results.
+    """
+    alternates: dict = {}
+    for track in seed_state.get("tracks", []):
+        if track.get("classification") == "sample_trigger":
+            alternates[track["role"]] = []  # populated in Phase 4
+    return alternates
+
+
+# ── genre context ──────────────────────────────────────────────────
+
+def _genre_context_for(prompt_directive: Optional[str]) -> dict:
+    """Phase 1 stub — full genre-vocabularies.md loading happens in Phase 4.
+
+    Returns empty dict shape; Phase 4 will populate with the descriptive
+    character data (kick, bass register, harmonic palette, devices).
+    """
+    return {}
+
+
+# ── identity preservation ──────────────────────────────────────────
+
+_IDENTITY_DIRECTIVE = (
+    "Preserve the existing seed identity. Existing samples MUST NOT be replaced "
+    "(except where you intentionally schedule a sample swap as part of a variant). "
+    "Existing notes in scene 0 MUST NOT be overwritten — write variants to NEW scenes "
+    "(scene_index >= 1). Existing automation curves MUST be preserved as the 'main' "
+    "state. The original loop must still play identically when fired. New material "
+    "extends the loop; it does not replace it."
+)
+
+
+# ── design targets ─────────────────────────────────────────────────
+
+_DESIGN_TARGETS = (
+    "Design a set of variant clips for the seed loop that allow it to develop into a "
+    "fuller arrangement. You decide: how many variants per layer, what sections those "
+    "variants serve, the section sequence and length, where the hook lands, when to "
+    "withhold and restate. Use the seed's identity (key, tempo, role classification) "
+    "as the unbreakable foundation. For midi_riff layers, design fresh per-variant "
+    "MIDI rooted in the same scale and tonal center. For sample_trigger layers, "
+    "consider sample swaps in fills and breakdowns — but only when the variation "
+    "genuinely benefits, not as default. Drum dropouts, sustained pad swells, and "
+    "filter sweeps are valid structural moves drawn from the event lexicon. The form "
+    "is yours to design — vocabularies tell you what a genre or artist sounds like, "
+    "they do not tell you the bar count of an intro."
+)
+
+
+# ── main entry point ───────────────────────────────────────────────
+
+def build_develop_brief(
+    ctx: Any,
+    seed_state: dict,
+    prompt_directive: Optional[str] = None,
+) -> dict:
+    """Build a Phase-1 develop brief.
+
+    Args:
+      ctx: Lifespan context (lifespan_context.ableton, etc.) — not heavily
+           used in Phase 1; Phase 4 KnowledgePack consumes it.
+      seed_state: SeedState dict from introspect_seed() — read-only
+      prompt_directive: optional free-text directive ("extend in microhouse style",
+                        "make it sound like Burial", etc.)
+
+    Returns dict with vocabulary fields. NEVER returns form-prescriptive fields.
+    """
+    artist_refs = extract_artist_refs(prompt_directive or "")
+    research_hooks = detect_research_hooks(prompt_directive or "")
+    genre_context = _genre_context_for(prompt_directive)
+    artist_context = {name: {} for name in artist_refs}  # Phase 4 fills in
+    atlas_alternates = _atlas_alternates_per_role(seed_state)
+
+    brief = {
+        "mode": "develop",
+        "tempo": seed_state.get("tempo", 120.0),
+        "key": seed_state.get("key"),
+        "seed_state": seed_state,
+        "identity_preservation_directive": _IDENTITY_DIRECTIVE,
+        "design_targets": _DESIGN_TARGETS,
+        "genre_context": genre_context,
+        "artist_context": artist_context,
+        "atlas_alternates_per_role": atlas_alternates,
+        "research_hooks": research_hooks,
+        "prompt_directive": prompt_directive,
+    }
+    return brief

package/mcp_server/composer/develop/seed_introspector.py

@@ -0,0 +1,195 @@
+"""SeedIntrospector — read-only classifier for the existing loop in a live session.
+
+Takes the project's current state (focused on a single scene, scene 0 by
+default) and produces a SeedState dict describing what's there. Callers
+(DevelopBrief builder, develop_apply) consume this to know what to extend.
+
+Role classification:
+- Name-match first: track.name lower-cased matches against role keyword sets
+- Fallback to register heuristic when name is unrecognized
+
+Sample-trigger vs MIDI-riff:
+- A track is sample_trigger if ALL of: exactly 1 note, pitch == 60, duration >= clip_length
+- Otherwise: midi_riff (multiple notes OR pitch != 60 OR duration < clip_length)
+- Empty clip returns 'empty'
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Role-keyword maps. Order matters within each list — check more specific names first
+_ROLE_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "drums": ("drum", "kick", "snare", "hat", "hi-hat", "hihat", "cymbal", "perc", "percussion", "clap", "ride", "tom"),
+    "bass": ("bass", "sub", "808"),
+    "lead": ("lead", "melody", "synth lead", "arp"),
+    "pad": ("pad", "string", "chord", "harm"),
+    "texture": ("texture", "atmos", "ambient", "noise", "drone"),
+    "fx": ("fx", "riser", "impact", "swell", "sweep"),
+    "vocal": ("vocal", "voice", "vox", "chop", "ad-lib", "adlib"),
+}
+
+
+def infer_role_from_name(name: str) -> str:
+    """Match track name (case-insensitive) against role keywords.
+
+    Returns one of: drums, bass, lead, pad, texture, fx, vocal, unknown.
+    Caller may fall back to register heuristic when this returns 'unknown'.
+    """
+    if not name:
+        return "unknown"
+    lower = name.lower()
+    for role, keywords in _ROLE_KEYWORDS.items():
+        for kw in keywords:
+            # Use prefix word-boundary to avoid false positives (e.g. "tom" in "MyCustomTrack")
+            # but still match "drum" in "drums", "string" in "strings", "chop" in "chops"
+            if re.search(r'\b' + re.escape(kw), lower):
+                return role
+    return "unknown"
+
+
+def classify_track(notes: list[dict], clip_length: float) -> str:
+    """Classify a track as sample_trigger / midi_riff / empty.
+
+    Heuristic per v1.24 spec:
+    - empty: no notes
+    - sample_trigger: exactly 1 note, pitch == 60, duration >= clip_length
+    - midi_riff: anything else
+    """
+    if not notes:
+        return "empty"
+    if len(notes) == 1:
+        n = notes[0]
+        if int(n.get("pitch", -1)) == 60 and float(n.get("duration", 0.0)) >= clip_length:
+            return "sample_trigger"
+    return "midi_riff"
+
+
+def introspect_seed(ctx: Any, scene_index: int = 0) -> dict:
+    """Build a SeedState dict from the live session.
+
+    Reads tempo, time signature, song scale, and per-track clip content
+    for the given scene. Returns dict shape:
+
+    {
+      "scene_index": int,
+      "tempo": float,
+      "clip_length": float,        # bars-in-beats; 4.0 = 1 bar at 4/4
+      "time_signature": str,        # e.g. "4/4"
+      "key": str | None,
+      "scale_mode": str | None,
+      "tracks": [
+        {
+          "index": int,
+          "name": str,
+          "role": str,              # from name-match
+          "classification": str,    # sample_trigger | midi_riff | empty
+          "notes": list[dict],
+          "muted": bool,
+        },
+        ...
+      ],
+      "status": str | None,         # "no_seed_found" if scene has no clips
+      "error": str | None,
+    }
+
+    On missing ableton context: returns {"error": "..."}.
+    """
+    ableton = ctx.lifespan_context.get("ableton") if hasattr(ctx, "lifespan_context") else None
+    if ableton is None:
+        return {"error": "ableton client not available in ctx"}
+
+    try:
+        session = ableton.send_command("get_session_info", {})
+    except Exception as exc:
+        return {"error": f"get_session_info failed: {exc}"}
+
+    seed: dict = {
+        "scene_index": scene_index,
+        "tempo": float(session.get("tempo", 120.0)),
+        "tracks": [],
+    }
+    sig_num = session.get("signature_numerator")
+    sig_den = session.get("signature_denominator")
+    if sig_num and sig_den:
+        seed["time_signature"] = f"{sig_num}/{sig_den}"
+
+    # Try to read song scale (Live 12.4)
+    try:
+        scale_result = ableton.send_command("get_song_scale", {})
+        if scale_result and not scale_result.get("error"):
+            seed["key"] = scale_result.get("root_note") or scale_result.get("key")
+            seed["scale_mode"] = scale_result.get("scale_name") or scale_result.get("mode")
+    except Exception as exc:
+        logger.debug("introspect_seed: get_song_scale unavailable: %s", exc)
+
+    track_descriptors = session.get("tracks", []) or []
+    clip_length_seen: Optional[float] = None
+    populated_track_count = 0
+
+    for td in track_descriptors:
+        ti = int(td.get("index", -1))
+        name = td.get("name", "")
+        muted = bool(td.get("mute", False))
+
+        # Read the clip in this scene
+        try:
+            clip_info = ableton.send_command(
+                "get_clip_info",
+                {"track_index": ti, "clip_index": scene_index},
+            )
+        except Exception as exc:
+            logger.debug("introspect_seed: get_clip_info(%d, %d) failed: %s", ti, scene_index, exc)
+            continue
+
+        if clip_info.get("error"):
+            # No clip in this slot — skip but include the track stub for completeness
+            seed["tracks"].append({
+                "index": ti,
+                "name": name,
+                "role": infer_role_from_name(name),
+                "classification": "empty",
+                "notes": [],
+                "muted": muted,
+            })
+            continue
+
+        clip_length = float(clip_info.get("length", 0.0))
+        if clip_length_seen is None and clip_length > 0:
+            clip_length_seen = clip_length
+
+        try:
+            notes_result = ableton.send_command(
+                "get_notes",
+                {"track_index": ti, "clip_index": scene_index},
+            )
+            notes = notes_result.get("notes", []) if isinstance(notes_result, dict) else []
+        except Exception as exc:
+            logger.debug("introspect_seed: get_notes(%d, %d) failed: %s", ti, scene_index, exc)
+            notes = []
+
+        classification = classify_track(notes, clip_length) if clip_length > 0 else "empty"
+        if classification != "empty":
+            populated_track_count += 1
+
+        seed["tracks"].append({
+            "index": ti,
+            "name": name,
+            "role": infer_role_from_name(name),
+            "classification": classification,
+            "notes": notes,
+            "muted": muted,
+        })
+
+    seed["clip_length"] = clip_length_seen if clip_length_seen is not None else 0.0
+
+    if populated_track_count == 0:
+        seed["status"] = "no_seed_found"
+        seed["tracks"] = []  # Per spec: empty result tracks list
+
+    return seed