livepilot 1.23.6 → 1.24.0

package/mcp_server/composer/fast/tier_classification.py

@@ -0,0 +1,159 @@
+"""Tier classification for instruments — used by fast-mode brief hunt-order.
+
+The framework provides VOCABULARY (descriptive). The LLM provides FORM (creative).
+For instrument candidates: Tier-A and Tier-B are safe to return in briefs.
+Tier-C bare URIs MUST NEVER be returned — the brief substitutes a curated preset
+or omits that synth entirely.
+
+Tier table (BINDING):
+  A_curated_preset — .adg / .adv from sounds/ folder. Loaded with character.
+  A_drum_sample    — raw sample (.aif/.wav) from drums/ folder. load_browser_item
+                     auto-wraps in Simpler with drum-role defaults.
+  B_drum_synth     — drum-specific synth (DS Kick etc). Default patch IS the drum.
+  B_audible_default — generic melodic synth (Operator, Wavetable etc).
+                      Default patch is "generic AI synth" — only return as fallback
+                      when sounds/ returns nothing for a melodic role.
+  C_needs_preset   — empty container (Drum Sampler, Emit etc). NEVER return.
+
+Legacy tier value "A_sample_ready" is accepted in VALID_BRIEF_TIERS so old
+tests still pass; new candidates use the specific A_* values.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+# ── Tier VALUE constants (used as the `tier` field in brief candidates) ──
+
+TIER_A_CURATED_PRESET = "A_curated_preset"
+TIER_A_DRUM_SAMPLE = "A_drum_sample"
+TIER_B_DRUM_SYNTH = "B_drum_synth"
+TIER_B_AUDIBLE_DEFAULT_VALUE = "B_audible_default"
+TIER_C_NEEDS_PRESET_VALUE = "C_needs_preset"
+
+# Tiers that are valid in brief output (Tier-C is NEVER valid)
+VALID_BRIEF_TIERS = frozenset({
+    TIER_A_CURATED_PRESET,
+    TIER_A_DRUM_SAMPLE,
+    TIER_B_DRUM_SYNTH,
+    TIER_B_AUDIBLE_DEFAULT_VALUE,
+    # Legacy alias — kept so old briefs and tests still work
+    "A_sample_ready",
+    # Legacy alias — "B_audible_default" is also the old tier value and is valid
+    "B_audible_default",
+})
+
+# Role sets
+DRUM_ROLES = frozenset({"kick", "snare", "hat", "perc", "clap", "tom", "drum"})
+MELODIC_ROLES = frozenset({"bass", "lead", "pad", "atmos", "vox", "fx", "texture"})
+
+
+# ── Frozensets of instrument names (used for name-based classification) ──
+
+# Drum-specific synths — purpose-built drum sound generators.
+# Their default patches ARE the intended drum sound (unlike generic melodic
+# synths whose defaults are "generic AI synth").
+# Allowed in drum-role briefs as Tier-B without curated presets.
+DRUM_SPECIFIC_SYNTHS: frozenset[str] = frozenset({
+    "DS Kick",
+    "DS Snare",
+    "DS Hi-Hat",
+    "DS Clap",
+    "DS Cymbal",
+    "DS Tom",
+    "DS Sampler",
+    "DS Drum Bus",
+})
+
+# Melodic synths with audible defaults — "generic AI synth" risk.
+# Renamed from TIER_B_AUDIBLE_DEFAULT to MELODIC_AUDIBLE_DEFAULTS to
+# disambiguate from the tier VALUE string TIER_B_AUDIBLE_DEFAULT_VALUE.
+# The old name TIER_B_AUDIBLE_DEFAULT is kept as an alias for backward compat.
+MELODIC_AUDIBLE_DEFAULTS: frozenset[str] = frozenset({
+    "Operator",
+    "Wavetable",
+    "Drift",
+    "Analog",
+    "Bass",
+    "Electric",
+    "Tension",
+    "Collision",
+    "Meld",
+})
+
+# Backward-compat alias (old tests and callers use this name)
+TIER_B_AUDIBLE_DEFAULT = MELODIC_AUDIBLE_DEFAULTS
+
+# Containers + programming-required synths — NEVER return bare URIs.
+# Renamed from TIER_C_NEEDS_PRESET to CONTAINERS_NEEDING_PRESETS to
+# disambiguate from the tier VALUE string TIER_C_NEEDS_PRESET_VALUE.
+# The old name TIER_C_NEEDS_PRESET is kept as an alias for backward compat.
+CONTAINERS_NEEDING_PRESETS: frozenset[str] = frozenset({
+    "Drum Sampler",
+    "Drum Rack",
+    "DrumGroup",      # internal alias for Drum Rack
+    "Simpler",
+    "Sampler",
+    "Impulse",
+    "Emit",
+    "Vector FM",
+    "Vector Grain",
+    "Granulator III",
+    "Granulator II",  # legacy
+    "Instrument Rack",
+    "Looper",
+    "External Instrument",
+})
+
+# Backward-compat alias
+TIER_C_NEEDS_PRESET = CONTAINERS_NEEDING_PRESETS
+
+# Combined lookup: name → tier string
+# Drum-specific synths → "B_drum_synth"; melodic audible defaults → "B_audible_default";
+# containers → "C_needs_preset". Unknown instruments return None.
+TIER_CLASSIFICATION: dict[str, str] = {
+    name: "B_drum_synth" for name in DRUM_SPECIFIC_SYNTHS
+} | {
+    name: "B_audible_default" for name in MELODIC_AUDIBLE_DEFAULTS
+} | {
+    name: "C_needs_preset" for name in CONTAINERS_NEEDING_PRESETS
+}
+
+
+def classify_instrument(name: str) -> Optional[str]:
+    """Classify an instrument by name.
+
+    Returns one of:
+      "B_drum_synth"      — drum-specific synth, safe for drum roles bare
+      "B_audible_default" — generic melodic synth, only as fallback
+      "C_needs_preset"    — container, NEVER return bare
+      None                — unknown instrument
+    """
+    return TIER_CLASSIFICATION.get(name)
+
+
+def is_drum_specific_synth(name: str) -> bool:
+    """True if `name` is a drum-specific synth — safe to return bare for drum roles."""
+    return name in DRUM_SPECIFIC_SYNTHS
+
+
+# Search terms for hunting curated chains in sounds/ and drums/ per role.
+# Used by build_creative_brief to populate instruments_by_role.
+ROLE_SEARCH_TERMS: dict[str, dict[str, Optional[str]]] = {
+    # drum roles — search drums/ first, sounds/ second
+    "kick":    {"sounds_term": "kick",       "drums_term": "kick"},
+    "snare":   {"sounds_term": "snare",      "drums_term": "snare"},
+    "hat":     {"sounds_term": "hihat",      "drums_term": "hihat"},
+    "perc":    {"sounds_term": "percussion", "drums_term": "perc"},
+    "clap":    {"sounds_term": "clap",       "drums_term": "clap"},
+    "tom":     {"sounds_term": "tom",        "drums_term": "tom"},
+    # melodic roles — search sounds/ for curated presets
+    "bass":    {"sounds_term": "bass",    "drums_term": None},
+    "lead":    {"sounds_term": "lead",    "drums_term": None},
+    "pad":     {"sounds_term": "pad",     "drums_term": None},
+    "atmos":   {"sounds_term": "ambient", "drums_term": None},
+    "vox":     {"sounds_term": "vocal",   "drums_term": None},
+    "fx":      {"sounds_term": "fx",      "drums_term": None},
+    "texture": {"sounds_term": "texture", "drums_term": None},
+}

package/mcp_server/composer/framework/applier.py

@@ -0,0 +1,179 @@
+"""Applier — shared Phase-3 executor for fast / full / develop compose modes.
+
+Concentrates pre-flight (analyzer load + bridge connect + handshake retry)
+and post-flight (monitoring state + back_to_arranger) so fixes for
+BUG-FULL-MODE-14 (bridge race) and BUG-FULL-MODE-17 (manual arm required)
+land once across all three modes instead of three times.
+
+Functions are dependency-injected (not imported directly) so unit tests can
+mock them without monkey-patching.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Awaitable, Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Type aliases
+AsyncCtxFn = Callable[[Any], Awaitable[Any]]
+AsyncTrackFn = Callable[..., Awaitable[Any]]
+
+
+class Applier:
+    """Shared pre-flight + apply + post-flight skeleton for compose modes.
+
+    v1.24 Phase 1: pre-flight + post-flight only. The `run()` method (full
+    plan execution) stays a stub; each mode's apply.py wires its own
+    plan-execution loop using `Applier.preflight()` and `Applier.postflight()`
+    around it.
+
+    Future phases may extend this with a unified plan-walker.
+    """
+
+    def __init__(
+        self,
+        *,
+        ensure_analyzer_fn: AsyncCtxFn,
+        reconnect_bridge_fn: AsyncCtxFn,
+        bridge_ping_fn: AsyncCtxFn,
+        set_track_input_monitoring_fn: Optional[AsyncTrackFn] = None,
+        back_to_arranger_fn: Optional[AsyncCtxFn] = None,
+        handshake_max_attempts: int = 3,
+        handshake_gap_seconds: float = 0.2,
+    ):
+        self._ensure_analyzer_fn = ensure_analyzer_fn
+        self._reconnect_bridge_fn = reconnect_bridge_fn
+        self._bridge_ping_fn = bridge_ping_fn
+        self._set_track_input_monitoring_fn = set_track_input_monitoring_fn
+        self._back_to_arranger_fn = back_to_arranger_fn
+        self._handshake_max_attempts = handshake_max_attempts
+        self._handshake_gap_seconds = handshake_gap_seconds
+
+    # ── pre-flight ──────────────────────────────────────────────────
+
+    async def preflight(self, ctx: Any) -> dict:
+        """Load analyzer, connect bridge, handshake until ping succeeds.
+
+        Fixes BUG-FULL-MODE-14: the previous code returned success on
+        bridge.connect() but the M4L JS listener takes 100-500ms to bind
+        the UDP socket. Without the handshake retry loop, the next
+        bridge-using call (load_sample_to_simpler etc.) fails with
+        "UDP bridge is not connected".
+
+        Returns dict with keys: analyzer_status, bridge_connected,
+        handshake_attempts, and optionally handshake_error if all
+        retries failed.
+        """
+        analyzer_result = await self._ensure_analyzer_fn(ctx)
+        analyzer_status = (
+            analyzer_result.get("status", "unknown")
+            if isinstance(analyzer_result, dict)
+            else "unknown"
+        )
+
+        bridge_result = await self._reconnect_bridge_fn(ctx)
+        bridge_connected_initial = (
+            bridge_result.get("connected", False)
+            if isinstance(bridge_result, dict)
+            else False
+        )
+
+        handshake_attempts = 0
+        handshake_error: Optional[str] = None
+        bridge_ready = False
+
+        if bridge_connected_initial:
+            for attempt in range(1, self._handshake_max_attempts + 1):
+                handshake_attempts = attempt
+                try:
+                    await self._bridge_ping_fn(ctx)
+                    bridge_ready = True
+                    break
+                except Exception as exc:
+                    handshake_error = str(exc)
+                    logger.debug(
+                        "Applier preflight handshake attempt %d failed: %s",
+                        attempt,
+                        exc,
+                    )
+                    if attempt < self._handshake_max_attempts:
+                        await asyncio.sleep(self._handshake_gap_seconds)
+
+        result = {
+            "analyzer_status": analyzer_status,
+            "bridge_connected": bridge_ready,
+            "handshake_attempts": handshake_attempts,
+        }
+        if not bridge_ready and handshake_error is not None:
+            result["handshake_error"] = handshake_error
+        return result
+
+    # ── post-flight ─────────────────────────────────────────────────
+
+    async def postflight(
+        self,
+        ctx: Any,
+        applied_track_indices: list[int],
+    ) -> dict:
+        """Set monitoring=Auto on each newly-created track, then back_to_arranger.
+
+        BUG-FIX (post-Phase-4-Task-4 live test): the original BUG-FULL-MODE-17
+        fix set monitoring to state=0 ("In"), which is WRONG. State codes:
+            0 = In   (always pass input through — leaves track "hot")
+            1 = Auto (monitor when armed + recording — DEFAULT for new tracks)
+            2 = Off  (never monitor)
+
+        New tracks default to Auto (1) and arrangement clips already play
+        correctly with Auto. The actual fix for "manual arm required" is
+        back_to_arranger alone — clearing the session-vs-arrangement
+        override flag. We set state=Auto here defensively in case any
+        other code path moved monitoring away from default.
+
+        applied_track_indices: list of track indices that were created
+        during this apply pass. Empty list (e.g. develop mode writing
+        only session clips, no new tracks) skips the per-track step but
+        still calls back_to_arranger.
+        """
+        tracks_set = 0
+        if self._set_track_input_monitoring_fn is not None:
+            for track_index in applied_track_indices:
+                try:
+                    # state=1 (Auto) — the default for new tracks. NOT 0 (In).
+                    await self._set_track_input_monitoring_fn(
+                        ctx, track_index=track_index, state=1
+                    )
+                    tracks_set += 1
+                except Exception as exc:
+                    logger.warning(
+                        "Applier postflight set_monitoring failed for track %d: %s",
+                        track_index,
+                        exc,
+                    )
+
+        back_to_arranger_ok = False
+        if self._back_to_arranger_fn is not None:
+            try:
+                await self._back_to_arranger_fn(ctx)
+                back_to_arranger_ok = True
+            except Exception as exc:
+                logger.warning("Applier postflight back_to_arranger failed: %s", exc)
+
+        return {
+            "tracks_set": tracks_set,
+            "back_to_arranger": back_to_arranger_ok,
+        }
+
+    # ── stub run() — not used in v1.24 ──────────────────────────────
+
+    async def run(self, ctx: Any, plan: list) -> dict:
+        """Stub kept from Task 1 — full plan-walk implementation deferred.
+
+        Phase 1 only extracts pre/post-flight. Each mode's apply.py
+        continues to execute its own plan loop, just sandwiched by
+        ``preflight()`` and ``postflight()``.
+        """
+        return {"status": "stub"}

package/mcp_server/composer/framework/artist_loader.py

@@ -0,0 +1,63 @@
+"""Markdown parser for livepilot/skills/livepilot-core/references/artist-vocabularies.md."""
+
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Optional
+
+
+_ARTIST_CACHE: Optional[dict[str, dict]] = None
+
+
+def _artist_md_path() -> Optional[Path]:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "livepilot" / "skills" / "livepilot-core" / "references" / "artist-vocabularies.md"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _load_artist_md() -> dict[str, dict]:
+    """Parse artist entries. Existing pattern in develop/brief_builder.py:
+    `### Name` headers with body content."""
+    global _ARTIST_CACHE
+    if _ARTIST_CACHE is not None:
+        return _ARTIST_CACHE
+    path = _artist_md_path()
+    if path is None:
+        _ARTIST_CACHE = {}
+        return _ARTIST_CACHE
+    text = path.read_text(encoding="utf-8")
+
+    artists: dict[str, dict] = {}
+    sections = re.split(r"^###\s+(.+?)\s*$", text, flags=re.MULTILINE)
+    for i in range(1, len(sections), 2):
+        name = sections[i].strip()
+        if not name or "Vocabulary" in name or "How to" in name:
+            continue
+        body = sections[i + 1] if i + 1 < len(sections) else ""
+        # Strip parenthetical aliases for canonical key: "Aphex Twin (Richard D. James)" → "Aphex Twin"
+        primary = re.sub(r"\s*\(.*?\)\s*$", "", name).strip()
+        if primary:
+            artists[primary] = {"name": primary, "raw_md": body.strip()[:2000]}
+    _ARTIST_CACHE = artists
+    return _ARTIST_CACHE
+
+
+def load_artist_context(artist_names: list[str]) -> dict[str, dict]:
+    """Load context for the given artist names.
+
+    artist_names: list of names (case-insensitive matched against parser keys)
+    Returns: {artist_name: {raw_md: ..., ...}, ...}
+    """
+    if not artist_names:
+        return {}
+    parsed = _load_artist_md()
+    result = {}
+    parsed_lower = {k.lower(): k for k in parsed.keys()}
+    for name in artist_names:
+        canonical = parsed_lower.get(name.lower())
+        if canonical:
+            result[canonical] = parsed[canonical]
+    return result

package/mcp_server/composer/framework/brief.py

@@ -0,0 +1,79 @@
+"""Brief dataclasses — uniform shape across the 3 compose modes (fast/full/develop).
+
+The framework provides VOCABULARY (descriptive). The LLM provides FORM (creative).
+Briefs MUST NOT carry predetermined section sequences, bar counts, or variant taxonomies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict, fields
+from typing import Optional, Type, TypeVar
+
+
+T = TypeVar("T", bound="Brief")
+
+
+@dataclass(frozen=True)
+class Brief:
+    """Base — every compose mode returns a Brief subclass.
+
+    Common fields shared across all modes. Subclasses extend with mode-
+    specific fields (instruments_by_role, design_targets, seed_state, etc.).
+    """
+    mode: str
+    tempo: float
+    key: Optional[str]
+    intent: dict
+    knowledge: dict
+
+    def to_dict(self) -> dict:
+        """Serialize to a JSON-friendly dict including subclass fields."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls: Type[T], data: dict) -> T:
+        """Deserialize from a dict.
+
+        Filters out unknown keys (forward-compatibility) and uses dataclass
+        defaults for missing optional fields.
+        """
+        known = {f.name for f in fields(cls)}
+        filtered = {k: v for k, v in data.items() if k in known}
+        return cls(**filtered)
+
+
+@dataclass(frozen=True)
+class FastBrief(Brief):
+    """Loop-sketch brief — agent designs MIDI inline.
+
+    instruments_by_role: dict mapping role name → list of atlas device candidates
+    scale_pitches: list of MIDI pitches in the inferred key/scale
+    """
+    instruments_by_role: dict = field(default_factory=dict)
+    scale_pitches: list = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class FullBrief(Brief):
+    """Full-track brief — agent designs FORM and notes per call.
+
+    NB: must NOT include section_sequence, bar_counts, or form_template
+    fields per the vocabulary-not-form principle.
+
+    research_hooks: list of niche-style terms the agent should research
+                    before designing (WebSearch directives)
+    design_targets: open-ended description of what the agent should produce
+    """
+    research_hooks: list = field(default_factory=list)
+    design_targets: str = ""
+
+
+@dataclass(frozen=True)
+class DevelopBrief(Brief):
+    """Loop-extension brief — agent designs variants per call.
+
+    seed_state: introspected SeedState dict (key, tempo, role classification, motif)
+    identity_preservation_directive: explicit guidance that seed must survive
+    """
+    seed_state: dict = field(default_factory=dict)
+    identity_preservation_directive: str = ""

package/mcp_server/composer/framework/event_lexicon.py

@@ -0,0 +1,71 @@
+"""42-event structural lexicon — vocabulary of named primitives the agent
+can schedule at phrase boundaries. Used by full + develop mode briefs.
+
+Categories: filter, drums, layer, riser, dynamics, harmonic, space.
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+
+EVENT_LEXICON: list[dict] = [
+    # Filter gestures (5)
+    {"name": "hpf_sweep_up", "category": "filter", "description": "HPF rises 80 Hz → 1-2 kHz over 16-32 bars before drop"},
+    {"name": "lpf_close_slow", "category": "filter", "description": "LPF closes gradually over 64-128 bars (ambient texture removal)"},
+    {"name": "filter_open_snap", "category": "filter", "description": "Sudden filter opening on bar 1 of new section (drop arrival)"},
+    {"name": "band_pass_sweep", "category": "filter", "description": "Band-pass center sweeps up over 8 bars (microhouse)"},
+    {"name": "filter_wobble_increase", "category": "filter", "description": "LFO-driven filter mod depth increases over 8 bars"},
+    # Drum / Rhythm events (11)
+    {"name": "kick_dropout", "category": "drums", "description": "Kick muted for 8-16 bars before reintroduction"},
+    {"name": "kick_first_entry", "category": "drums", "description": "Kick appears for the first time after percussion-only intro"},
+    {"name": "snare_roll_final_bars", "category": "drums", "description": "Snare roll accelerating over bars 15-16 of 16-bar phrase"},
+    {"name": "hat_layer_entry", "category": "drums", "description": "Additional hat layer enters (closed → open, or second hat sample)"},
+    {"name": "perc_dropout", "category": "drums", "description": "All percussion except kick removed for 4-8 bars (tension)"},
+    {"name": "full_drum_dropout", "category": "drums", "description": "All drums including kick removed (breakdown)"},
+    {"name": "drum_reintroduction", "category": "drums", "description": "Drums return after full dropout at full energy"},
+    {"name": "clap_add", "category": "drums", "description": "Clap or snare enters where only kick existed before"},
+    {"name": "ghost_density_increase", "category": "drums", "description": "Ghost note velocity raised across all hats"},
+    {"name": "and_of_4_snare", "category": "drums", "description": "Extra snare hit on 'and of 4' on bar 16 (common fill marker)"},
+    {"name": "ride_cymbal_add", "category": "drums", "description": "Ride cymbal enters (jazz/DnB open feel)"},
+    # Layer entry / exit (9)
+    {"name": "layer_fade_in", "category": "layer", "description": "Track volume automation 0 → nominal over 4-8 bars"},
+    {"name": "layer_fade_out", "category": "layer", "description": "Track volume nominal → 0 over 8-16 bars"},
+    {"name": "layer_hard_cut_in", "category": "layer", "description": "Track unmutes on bar 1 of new section"},
+    {"name": "layer_hard_cut_out", "category": "layer", "description": "Track mutes on bar 1 of section change"},
+    {"name": "melody_first_entry", "category": "layer", "description": "Lead/melody track introduces for the first time"},
+    {"name": "texture_swell", "category": "layer", "description": "Atmosphere/pad rises from inaudible to audible over 32 bars"},
+    {"name": "sub_bass_entry", "category": "layer", "description": "Sub-bass track appears for first time"},
+    {"name": "pad_strip_to_silence", "category": "layer", "description": "Pad/harmonic layer removed for breakdown isolation"},
+    {"name": "vocal_chop_entry", "category": "layer", "description": "Vocal chop track enters"},
+    # Riser / Fall events (5)
+    {"name": "riser_swell", "category": "riser", "description": "Riser sample triggered at bar 13 of 16-bar phrase (arrives at bar 17)"},
+    {"name": "reverse_cymbal", "category": "riser", "description": "Reverse cymbal swell timed to arrive on bar 1 of next section"},
+    {"name": "noise_swell", "category": "riser", "description": "White noise volume −inf → 0 dB over 8 bars then cut on drop"},
+    {"name": "pitch_riser", "category": "riser", "description": "Sample or synth pitch automating upward over 4-8 bars"},
+    {"name": "downlifter", "category": "riser", "description": "Reverse riser / falling pitch for energy drop or breakdown arrival"},
+    # Sidechain / Dynamics (4)
+    {"name": "sidechain_activate", "category": "dynamics", "description": "Sidechain compressor (pad vs. kick) switches on at section start"},
+    {"name": "sidechain_deactivate", "category": "dynamics", "description": "Sidechain removed in breakdown, restoring pad sustain"},
+    {"name": "compressor_release_lengthen", "category": "dynamics", "description": "Compressor release extended for swelling effect"},
+    {"name": "drum_bus_saturation_increase", "category": "dynamics", "description": "Saturation drive increases during a build"},
+    # Harmonic / Melodic (5)
+    {"name": "chord_change", "category": "harmonic", "description": "Harmonic progression advances to next chord"},
+    {"name": "motif_restatement", "category": "harmonic", "description": "Primary hook returns after absence (ABAB form)"},
+    {"name": "motif_inversion", "category": "harmonic", "description": "Inverted motif (IDM/classical variation)"},
+    {"name": "motif_fragmentation", "category": "harmonic", "description": "Motif shortened to 1-2 notes, repeated (pre-climax)"},
+    {"name": "half_time_shift", "category": "harmonic", "description": "Note durations doubled (groove drops to half-time feel)"},
+    # Space / Reverb (3)
+    {"name": "reverb_send_increase", "category": "space", "description": "Send to reverb return increases over 4-8 bars"},
+    {"name": "dub_throw", "category": "space", "description": "Single 1-beat send spike to delay/reverb"},
+    {"name": "full_silence_bar", "category": "space", "description": "1-2 bars of total silence (highest-impact transition tool)"},
+]
+
+
+def get_event_lexicon(category: Optional[str] = None) -> list[dict]:
+    """Return the lexicon, optionally filtered by category.
+
+    category: 'filter', 'drums', 'layer', 'riser', 'dynamics', 'harmonic', 'space', or None for all.
+    """
+    if category is None:
+        return list(EVENT_LEXICON)
+    return [ev for ev in EVENT_LEXICON if ev["category"] == category]

package/mcp_server/composer/framework/genre_loader.py

@@ -0,0 +1,77 @@
+"""Markdown parser for livepilot/skills/livepilot-core/references/genre-vocabularies.md.
+
+Genre entries are demarcated by `## genre_name` headers. Each entry contains
+descriptive content (kick character, bass register, harmonic palette, etc.).
+We parse opportunistically — capture the raw markdown block per genre name,
+let the agent reason on the content rather than over-structuring it.
+"""
+
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Optional
+
+
+_GENRE_CACHE: Optional[dict[str, dict]] = None
+
+
+def _genre_md_path() -> Optional[Path]:
+    """Locate genre-vocabularies.md by walking up from this file."""
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "livepilot" / "skills" / "livepilot-core" / "references" / "genre-vocabularies.md"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _load_genre_md() -> dict[str, dict]:
+    """Parse the markdown into {genre_name_lowered: {raw: text, ...}}.
+
+    Cached after first call.
+    """
+    global _GENRE_CACHE
+    if _GENRE_CACHE is not None:
+        return _GENRE_CACHE
+    path = _genre_md_path()
+    if path is None:
+        _GENRE_CACHE = {}
+        return _GENRE_CACHE
+
+    text = path.read_text(encoding="utf-8")
+    # Genres are demarcated by `## name` (or `### name`) — the structure
+    # may vary, so handle both. Use a regex split.
+    genres: dict[str, dict] = {}
+    sections = re.split(r"^##+\s+(.+?)\s*$", text, flags=re.MULTILINE)
+    # Re.split returns [pre, name1, body1, name2, body2, ...]
+    for i in range(1, len(sections), 2):
+        name = sections[i].strip()
+        if not name or name.lower() in ("vocabulary", "how to read this", "table of contents"):
+            continue
+        body = sections[i + 1] if i + 1 < len(sections) else ""
+        # Lowercase + underscore normalize the key
+        key = name.lower().replace(" ", "_").replace("-", "_")
+        genres[key] = {"name": name, "raw_md": body.strip()[:2000]}  # cap to keep brief size sane
+
+    _GENRE_CACHE = genres
+    return _GENRE_CACHE
+
+
+def load_genre_context(genre: str) -> dict:
+    """Load descriptive context for a parsed genre.
+
+    genre: parsed genre slug (techno, microhouse, ambient, etc.)
+
+    Returns a dict with content if found, or {"status": "no_match", ...} if not.
+    """
+    if not genre:
+        return {"status": "no_genre_provided"}
+    genres = _load_genre_md()
+    key = genre.lower().replace(" ", "_").replace("-", "_")
+    if key in genres:
+        return genres[key]
+    # Try fuzzy: genre might be sub-genre matching a key contained in entry names
+    for k, v in genres.items():
+        if key in k or k in key:
+            return v
+    return {"status": "no_match", "parsed_genre": genre}