livepilot 1.10.9 → 1.13.0

package/mcp_server/memory/taste_graph.py

@@ -75,13 +75,37 @@ class TasteGraph:
     # Device preferences
     device_affinities: dict[str, DeviceAffinity] = field(default_factory=dict)
 
-    # Novelty tolerance: 0 = very conservative, 1 = very experimental
-    novelty_band: float = 0.5
+    # PR8 — per-goal-mode novelty bands. Canonical source of truth.
+    # Keys are goal modes ("improve", "explore", or any string a caller
+    # supplies). novelty_band (below, as a property) reads/writes
+    # novelty_bands["improve"] — one storage, two access paths.
+    novelty_bands: dict = field(
+        default_factory=lambda: {"improve": 0.5, "explore": 0.5}
+    )
+
+    # PR8 — when True, rank_moves returns uniform taste scores (0.5) to
+    # bypass taste filtering during branch generation. Callers flip this
+    # for fresh / surprise-me mode so novelty survives to post-hoc ranking.
+    bypass_taste_in_generation: bool = False
 
     # Total evidence count (how many decisions informed this graph)
     evidence_count: int = 0
     last_updated_ms: int = 0
 
+    @property
+    def novelty_band(self) -> float:
+        """Legacy flat novelty band — mirrors novelty_bands["improve"].
+
+        Kept for back-compat with callers that set/read novelty_band
+        directly. Setting this property writes through to the bands dict
+        so there's no dual source of truth.
+        """
+        return self.novelty_bands.get("improve", 0.5)
+
+    @novelty_band.setter
+    def novelty_band(self, value: float) -> None:
+        self.novelty_bands["improve"] = float(value)
+
     def to_dict(self) -> dict:
         return {
             "dimension_weights": self.dimension_weights,
@@ -96,7 +120,11 @@ class TasteGraph:
                     key=lambda x: -x[1].affinity,
                 )[:10]  # Top 10 only
             },
+            # novelty_band kept for legacy consumers that read it directly;
+            # novelty_bands is the canonical per-goal-mode shape going forward.
             "novelty_band": round(self.novelty_band, 3),
+            "novelty_bands": {k: round(v, 3) for k, v in self.novelty_bands.items()},
+            "bypass_taste_in_generation": self.bypass_taste_in_generation,
             "evidence_count": self.evidence_count,
         }
 
@@ -154,21 +182,53 @@ class TasteGraph:
         self.evidence_count += 1
         self.last_updated_ms = now
 
-    def update_novelty_from_experiment(self, chose_bold: bool) -> None:
-        """Shift novelty band based on experiment choices."""
+    def update_novelty_from_experiment(
+        self, chose_bold: bool, goal_mode: str = "improve",
+    ) -> None:
+        """Shift novelty band for a given goal mode based on experiment choices.
+
+        PR8: goal_mode defaults to "improve" so legacy callers land on the
+        same band they updated before. Pass "explore" to shift the
+        exploration-mode band without touching improve-mode preference.
+        (novelty_band is a property view over novelty_bands["improve"], so
+        improve-mode updates automatically surface there too.)
+        """
+        current = self.novelty_bands.get(goal_mode, 0.5)
         if chose_bold:
-            self.novelty_band = min(1.0, self.novelty_band + 0.05)
+            new_val = min(1.0, current + 0.05)
         else:
-            self.novelty_band = max(0.0, self.novelty_band - 0.05)
+            new_val = max(0.0, current - 0.05)
+        self.novelty_bands[goal_mode] = new_val
 
     # ── Ranking ──────────────────────────────────────────────────────
 
-    def rank_moves(self, move_specs: list[dict]) -> list[dict]:
+    def rank_moves(
+        self,
+        move_specs: list[dict],
+        goal_mode: str = "improve",
+    ) -> list[dict]:
         """Rank a list of semantic move dicts by taste fit.
 
         Each move dict should have: move_id, family, targets, risk_level.
         Returns the same dicts with added 'taste_score' field, sorted desc.
+
+        PR8 additions:
+          goal_mode (str, default "improve"): which novelty band to use for
+            risk alignment. "improve" respects the user's conservative history;
+            "explore" uses the explore-mode band so past timid choices don't
+            punish surprise-me branch generation.
+          bypass_taste_in_generation (instance flag): when True, every move
+            scores a uniform 0.5. Used during branch generation so taste
+            doesn't prune novelty before the user has a chance to audition.
+            Ranking order is preserved from input when this flag is on.
         """
+        if self.bypass_taste_in_generation:
+            return [dict(move, taste_score=0.5) for move in move_specs]
+
+        # Read the band for the requested mode. Falls back to the improve
+        # band (via self.novelty_band property) when the mode is unknown.
+        novelty_band = self.novelty_bands.get(goal_mode, self.novelty_band)
+
         ranked = []
         for move in move_specs:
             taste_score = 0.5  # Neutral baseline
@@ -190,10 +250,10 @@ class TasteGraph:
                 if dim in self.dimension_avoidances:
                     taste_score -= 0.3
 
-            # Novelty/risk alignment
+            # Novelty/risk alignment (PR8: per-mode band)
             risk = move.get("risk_level", "low")
             risk_val = {"low": 0.2, "medium": 0.5, "high": 0.8}.get(risk, 0.5)
-            novelty_match = 1.0 - abs(risk_val - self.novelty_band)
+            novelty_match = 1.0 - abs(risk_val - novelty_band)
             taste_score += novelty_match * 0.1
 
             # Clamp
@@ -297,8 +357,21 @@ def build_taste_graph(
                 if total > 0:
                     fam.score = round((fam.kept_count - fam.undone_count) / total, 3)
 
-        # Novelty band
-        graph.novelty_band = persisted.get("novelty_band", 0.5)
+        # Novelty band — migrate from flat float if present, OR read
+        # per-mode dict if newer persistence format has it (PR8).
+        persisted_band = persisted.get("novelty_band", 0.5)
+        persisted_bands = persisted.get("novelty_bands")
+        if isinstance(persisted_bands, dict) and persisted_bands:
+            graph.novelty_bands = {
+                k: float(v) for k, v in persisted_bands.items() if isinstance(v, (int, float))
+            }
+            # Ensure both canonical keys are present with sensible defaults.
+            graph.novelty_bands.setdefault("improve", persisted_band)
+            graph.novelty_bands.setdefault("explore", persisted_band)
+            graph.novelty_band = graph.novelty_bands["improve"]
+        else:
+            graph.novelty_band = persisted_band
+            graph.novelty_bands = {"improve": persisted_band, "explore": persisted_band}
 
         # Device affinities
         for dev_name, dev_data in persisted.get("device_affinities", {}).items():

package/mcp_server/persistence/taste_store.py

@@ -48,15 +48,29 @@ class PersistentTasteStore:
             return data
         self._store.update(_update)
 
-    def update_novelty(self, chose_bold: bool) -> None:
-        """Update novelty band from experiment choice."""
+    def update_novelty(self, chose_bold: bool, goal_mode: str = "improve") -> None:
+        """Update novelty band from experiment choice for a given goal mode.
+
+        PR8: goal_mode defaults to "improve" so legacy callers land on the
+        same band they updated before. The per-mode dict ``novelty_bands``
+        is maintained alongside the flat ``novelty_band`` field; the flat
+        field mirrors the "improve" band.
+        """
         def _update(data: dict) -> dict:
             data = data if data.get("version") == 1 else self._default()
-            band = data.get("novelty_band", 0.5)
+            # Ensure the per-mode dict exists (migrating from legacy shape).
+            bands = data.get("novelty_bands")
+            if not isinstance(bands, dict) or not bands:
+                flat = data.get("novelty_band", 0.5)
+                bands = {"improve": flat, "explore": flat}
+            current = bands.get(goal_mode, 0.5)
             if chose_bold:
-                data["novelty_band"] = min(1.0, band + 0.05)
+                bands[goal_mode] = min(1.0, current + 0.05)
             else:
-                data["novelty_band"] = max(0.0, band - 0.05)
+                bands[goal_mode] = max(0.0, current - 0.05)
+            data["novelty_bands"] = bands
+            # Mirror the improve band onto the flat field for back-compat.
+            data["novelty_band"] = bands.get("improve", 0.5)
             data["evidence_count"] = data.get("evidence_count", 0) + 1
             return data
         self._store.update(_update)
@@ -114,6 +128,8 @@ class PersistentTasteStore:
             "version": 1,
             "move_outcomes": {},
             "novelty_band": 0.5,
+            # PR8 — per-goal-mode novelty bands; novelty_band mirrors "improve"
+            "novelty_bands": {"improve": 0.5, "explore": 0.5},
             "device_affinities": {},
             "anti_preferences": [],
             "dimension_weights": {},

package/mcp_server/runtime/execution_router.py

@@ -47,6 +47,13 @@ MCP_TOOLS: frozenset[str] = frozenset({
     "generate_m4l_effect",
     "install_m4l_device",
     "list_genexpr_templates",
+    # MIDI Tool bridge (v1.12.0+) — these run entirely in the MCP server:
+    # config dispatch via OSC to m4l_bridge, cache state reads, filesystem
+    # copy. No TCP remote command, no bridge TCP round-trip.
+    "install_miditool_device",
+    "set_miditool_target",
+    "get_miditool_context",
+    "list_miditool_generators",
 })
 
 

package/mcp_server/runtime/mcp_dispatch.py

@@ -95,6 +95,33 @@ async def _list_genexpr_templates(params: dict, ctx: Any = None) -> dict:
     return await _call(list_genexpr_templates, ctx, params)
 
 
+# ── MIDI Tool bridge (v1.12.0+) ───────────────────────────────────────────
+#
+# These four run entirely in-process: install_miditool_device copies .amxd
+# files, set_miditool_target writes to MidiToolCache + OSC-sends config,
+# get_miditool_context reads the cache, list_miditool_generators reads the
+# GENERATOR_METADATA dict. None of them need TCP or bridge round-trips.
+
+async def _install_miditool_device(params: dict, ctx: Any = None) -> dict:
+    from ..tools.miditool import install_miditool_device
+    return await _call(install_miditool_device, ctx, params)
+
+
+async def _set_miditool_target(params: dict, ctx: Any = None) -> dict:
+    from ..tools.miditool import set_miditool_target
+    return await _call(set_miditool_target, ctx, params)
+
+
+async def _get_miditool_context(params: dict, ctx: Any = None) -> dict:
+    from ..tools.miditool import get_miditool_context
+    return await _call(get_miditool_context, ctx, params)
+
+
+async def _list_miditool_generators(params: dict, ctx: Any = None) -> dict:
+    from ..tools.miditool import list_miditool_generators
+    return await _call(list_miditool_generators, ctx, params)
+
+
 def build_mcp_dispatch_registry() -> dict[str, Callable]:
     """Return the canonical registry of MCP-only tools for plan execution.
 
@@ -115,4 +142,9 @@ def build_mcp_dispatch_registry() -> dict[str, Callable]:
         "generate_m4l_effect": _generate_m4l_effect,
         "install_m4l_device": _install_m4l_device,
         "list_genexpr_templates": _list_genexpr_templates,
+        # v1.12.0 MIDI Tool bridge
+        "install_miditool_device": _install_miditool_device,
+        "set_miditool_target": _set_miditool_target,
+        "get_miditool_context": _get_miditool_context,
+        "list_miditool_generators": _list_miditool_generators,
     }

package/mcp_server/runtime/remote_commands.py

@@ -48,6 +48,21 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "insert_device",           # 12.3+ native device insertion
     "insert_rack_chain",       # 12.3+ rack chain insertion
     "set_drum_chain_note",     # 12.3+ drum chain note assignment
+    # rack variations + macro CRUD (Live 11+)
+    "get_rack_variations", "store_rack_variation",
+    "recall_rack_variation", "delete_rack_variation",
+    "randomize_rack_macros", "add_rack_macro",
+    "remove_rack_macro", "set_rack_visible_macros",
+    # simpler slice CRUD (Live 11+)
+    "insert_simpler_slice", "move_simpler_slice",
+    "remove_simpler_slice", "clear_simpler_slices",
+    "reset_simpler_slices", "import_slices_from_onsets",
+    # wavetable modulation matrix (Live 11+)
+    "get_wavetable_mod_targets", "add_wavetable_mod_route",
+    "set_wavetable_mod_amount", "get_wavetable_mod_amount",
+    "get_wavetable_mod_matrix",
+    # device A/B compare (Live 12.3+)
+    "get_device_ab_state", "toggle_device_ab", "copy_device_state",
     # clip_automation (3)
     "get_clip_automation", "set_clip_automation", "clear_clip_automation",
     # browser (6)
@@ -65,8 +80,39 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "capture_midi", "start_recording", "stop_recording",
     "get_cue_points", "jump_to_cue", "toggle_cue_point",
     "back_to_arranger", "force_arrangement",
+    # scales — Song + per-clip scale awareness (Live 12.0+)
+    "get_song_scale", "set_song_scale", "set_song_scale_mode",
+    "list_available_scales",
+    "get_clip_scale", "set_clip_scale", "set_clip_scale_mode",
+    # tuning system (Live 12.1+)
+    "get_tuning_system", "set_tuning_reference_pitch",
+    "set_tuning_note", "reset_tuning_system",
+    # follow actions — clip (Live 12.0 revamp) + scene (Live 12.2+)
+    "get_clip_follow_action", "set_clip_follow_action",
+    "clear_clip_follow_action", "list_follow_action_types",
+    "apply_follow_action_preset",
+    "get_scene_follow_action", "set_scene_follow_action",
+    "clear_scene_follow_action",
+    # groove pool (Live 11+)
+    "list_grooves", "get_groove_info", "set_groove_params",
+    "assign_clip_groove", "get_clip_groove",
+    "get_song_groove_amount", "set_song_groove_amount",
+    # take lanes (Live 12.0 UI / 12.2 API)
+    "get_take_lanes", "create_take_lane", "set_take_lane_name",
+    "create_audio_clip_on_take_lane", "create_midi_clip_on_take_lane",
+    "get_take_lane_clips",
     # diagnostics (1)
     "get_session_diagnostics",
+    # control surfaces (diagnostic)
+    "list_control_surfaces", "get_control_surface_info",
+    # song primitives — transport/link
+    "tap_tempo", "nudge_tempo",
+    "set_exclusive_arm", "set_exclusive_solo",
+    "capture_and_insert_scene", "set_count_in_duration",
+    "get_link_state", "set_link_enabled", "force_link_beat_time",
+    # track primitives
+    "jump_in_session_clip", "get_track_performance_impact",
+    "get_appointed_device",
     # ping (built-in)
     "ping",
 })
@@ -92,6 +138,14 @@ BRIDGE_COMMANDS: frozenset[str] = frozenset({
     # async Python MCP tool in mcp_server/tools/analyzer.py, not a bridge
     # command. It has no case in livepilot_bridge.js and no @register handler
     # in remote_script. See mcp_server/runtime/execution_router.MCP_TOOLS.
+    # NOTE: MIDI Tool bridge commands (Live 12.0+ MIDI Generators /
+    # Transformations, requires LivePilot_MIDITool.amxd) do NOT belong in
+    # this set. They ride OSC prefixes /miditool/request, /miditool/ready
+    # (bridge→server) and miditool/config, miditool/response (server→bridge),
+    # dispatched through m4l_device/miditool_bridge.js (a separate JS, not
+    # livepilot_bridge.js) and pushed directly via M4LBridge.send_miditool_*
+    # helpers rather than through send_command. BRIDGE_COMMANDS is reserved
+    # for send_command targets that dispatch inside livepilot_bridge.js.
 })
 
 # Combined: all valid send_command targets

package/mcp_server/runtime/session_kernel.py

@@ -45,6 +45,37 @@ class SessionKernel:
     recommended_engines: list = field(default_factory=list)
     recommended_workflow: str = ""
 
+    # ── Creative controls (PR2 — branch-native migration) ──────────────
+    # All optional. Producers (Wonder, synthesis_brain, composer) read these
+    # to bias branch generation. Pre-PR2 callers leave them at defaults and
+    # nothing changes. PR6 (Wonder refactor) and PR9 (synthesis_brain) start
+    # reading them in earnest.
+
+    # 0.0 = conservative / don't surprise me; 1.0 = surprise me.
+    # Distinct from aggression (which is about execution boldness).
+    freshness: float = 0.5
+
+    # Shorthand producer philosophy tag. The sample_engine already uses
+    # "surgeon" / "alchemist" (see livepilot-sample-engine); synth work
+    # may add "sculptor". Empty string = producer picks a default.
+    creativity_profile: str = ""
+
+    # Caller-asserted sacred elements. Normally sacred elements come from
+    # song_brain; this lets the user or a skill override. Shape matches
+    # song_brain.sacred_elements entries: {element_type, description, salience}.
+    sacred_elements: list = field(default_factory=list)
+
+    # Hints for synthesis_brain: which tracks/devices to focus on and what
+    # target timbre to aim for. Shape is open in PR2 and will be firmed up
+    # when PR9 adds the first adapters.
+    #   {
+    #     "track_indices": [int, ...],
+    #     "device_paths":  ["track/Wavetable", ...],
+    #     "target_timbre": {"brightness": +0.3, "width": +0.2, ...},
+    #     "preferred_devices": ["Wavetable", "Operator", ...],
+    #   }
+    synth_hints: dict = field(default_factory=dict)
+
     def to_dict(self) -> dict:
         return asdict(self)
 
@@ -60,12 +91,23 @@ def build_session_kernel(
     taste_graph: Optional[dict] = None,
     anti_preferences: Optional[list] = None,
     protected_dimensions: Optional[dict] = None,
+    # PR2 — creative controls. All optional; legacy callers unaffected.
+    freshness: float = 0.5,
+    creativity_profile: str = "",
+    sacred_elements: Optional[list] = None,
+    synth_hints: Optional[dict] = None,
 ) -> SessionKernel:
     """Build a SessionKernel from raw data.
 
     All optional fields degrade gracefully to empty defaults.
     The kernel_id is deterministic from the core inputs so it's stable
     within the same turn context.
+
+    The PR2 creative-control fields (freshness, creativity_profile,
+    sacred_elements, synth_hints) are intentionally excluded from the
+    kernel_id hash so existing callers see no identity changes. Producers
+    that need these fields to influence identity can compose their own
+    derived id downstream.
     """
     # Deterministic kernel_id from inputs
     id_seed = json.dumps(
@@ -93,4 +135,8 @@ def build_session_kernel(
         taste_graph=taste_graph or {},
         anti_preferences=anti_preferences or [],
         protected_dimensions=protected_dimensions or {},
+        freshness=freshness,
+        creativity_profile=creativity_profile,
+        sacred_elements=sacred_elements or [],
+        synth_hints=synth_hints or {},
     )

package/mcp_server/runtime/tools.py

@@ -7,6 +7,8 @@ Tools:
 
 from __future__ import annotations
 
+from typing import Optional
+
 from fastmcp import Context
 
 from ..server import mcp
@@ -79,6 +81,10 @@ def get_session_kernel(
     request_text: str = "",
     mode: str = "improve",
     aggression: float = 0.5,
+    freshness: float = 0.5,
+    creativity_profile: str = "",
+    sacred_elements: Optional[list] = None,
+    synth_hints: Optional[dict] = None,
 ) -> dict:
     """Build the unified turn snapshot for V2 orchestration.
 
@@ -86,11 +92,27 @@ def get_session_kernel(
     Assembles: session info, capability state, action ledger, taste profile,
     anti-preferences, and session memory into one canonical snapshot.
 
-    mode: observe | improve | explore | finish | diagnose
-    aggression: 0.0 (subtle) to 1.0 (bold)
+    Core params:
+      mode: observe | improve | explore | finish | diagnose
+      aggression: 0.0 (subtle) to 1.0 (bold) — execution boldness.
+
+    Creative controls (PR2 — branch-native migration, optional):
+      freshness: 0.0 (don't surprise me) to 1.0 (surprise me). Read by
+        producers (Wonder, synthesis_brain, composer) to bias branch
+        generation. Distinct from aggression, which is about applying
+        a single move boldly; freshness is about how far to roam.
+      creativity_profile: shorthand producer philosophy tag. Known values
+        include "surgeon" (targeted), "alchemist" (transformative),
+        "sculptor" (synthesis-focused). Empty ⇒ producer picks a default.
+      sacred_elements: caller-asserted list of sacred elements that
+        override or augment what song_brain infers. Shape matches
+        song_brain entries: {element_type, description, salience}.
+      synth_hints: focus hints for synthesis_brain; shape is open in PR2
+        and firms up in PR9. Typical keys: track_indices, device_paths,
+        target_timbre, preferred_devices.
 
     Returns: SessionKernel dict with kernel_id, session topology, capabilities,
-    memory context, and routing hints.
+    memory context, routing hints, and (if provided) creative controls.
     """
     from .session_kernel import build_session_kernel
 
@@ -179,6 +201,10 @@ def get_session_kernel(
         session_memory=session_mem,
         taste_graph=taste_graph,
         anti_preferences=anti_prefs,
+        freshness=freshness,
+        creativity_profile=creativity_profile,
+        sacred_elements=sacred_elements,
+        synth_hints=synth_hints,
     )
 
     # Populate routing hints from conductor when request context is available

package/mcp_server/sample_engine/slice_classifier.py

@@ -0,0 +1,169 @@
+"""Spectral classification of Simpler-slice drum break segments.
+
+Lessons from the 2026-04-18 creative session that drove this module:
+
+- Never assume slice 0 is a kick. Slice content depends on transient
+  detection order in the source audio, not drum-rack convention.
+- Snares ALWAYS have 20-35% mid-frequency energy (drum body resonance).
+  Hi-hats / cymbals have <25% mid (they're thin metal discs with no
+  resonant body). This mid-content threshold is the critical separator
+  that tripped up the first classification pass.
+- Ghosts are defined by low peak amplitude (<0.35) regardless of spectrum.
+
+Thresholds validated against "Break Ghosts 90 bpm" (Ableton Core Library)
+in the session. See ``feedback_analyze_slices_before_programming`` memory
+entry for the full story and the specific slice map for that sample.
+
+This module is pure Python (numpy only). No LivePilot / Ableton /
+FastMCP dependencies — testable and runnable in isolation.
+"""
+from __future__ import annotations
+
+from typing import List, Literal, Sequence, TypedDict
+
+import numpy as np
+
+
+Label = Literal["KICK", "SNARE", "HAT", "ghost"]
+
+
+class SliceFeatures(TypedDict):
+    """Per-slice classification result plus the features that drove the decision."""
+
+    index: int
+    label: Label
+    peak: float
+    rms: float
+    sub_pct: float
+    low_pct: float
+    mid_pct: float
+    high_pct: float
+
+
+# ---------------------------------------------------------------------------
+# Band boundaries (Hz). Tuned against the 2026-04-18 session's working set.
+# ---------------------------------------------------------------------------
+
+_SUB_MAX = 100.0    # sub-bass (kick fundamentals live here)
+_LOW_MAX = 300.0    # body / low-mid (kick "thud" + bass fundamentals)
+_MID_MAX = 3000.0   # presence / drum body / vocals
+# Everything above _MID_MAX is "high" (sizzle / air / cymbal).
+
+
+# ---------------------------------------------------------------------------
+# Classification thresholds. DO NOT loosen these without re-validating on a
+# real break — the 2026-04-18 session proved that relaxing the HAT mid-cap
+# to 32% misclassifies loud snares as hats.
+# ---------------------------------------------------------------------------
+
+_GHOST_PEAK = 0.35        # Below this peak → ghost regardless of spectrum
+_KICK_SUB_LOW_MIN = 0.45  # sub + low must be this dominant
+_KICK_HIGH_MAX = 0.40     # kicks never have >40% high
+_SNARE_MID_MIN = 0.25     # snares HAVE a drum body (mid content)
+_SNARE_HIGH_MIN = 0.40    # + sizzle
+_SNARE_PEAK_MIN = 0.60    # + loud enough to not be a ghost
+_HAT_HIGH_MIN = 0.70      # hats are thin metal — overwhelmingly high
+_HAT_MID_MAX = 0.25       # hats have almost no drum body
+
+
+def _band_energy(segment: np.ndarray, sr: int) -> tuple[float, float, float, float]:
+    """Return (sub, low, mid, high) energy fractions that sum to ~1.0.
+
+    Uses an rFFT. If the segment is empty or silent, returns equal quarters
+    so downstream logic doesn't have to handle zero-sum edge cases (the
+    caller still sees silence via the peak/rms fields).
+    """
+    if len(segment) < 2:
+        return 0.25, 0.25, 0.25, 0.25
+    spec = np.abs(np.fft.rfft(segment))
+    total = float(spec.sum())
+    if total <= 0:
+        return 0.25, 0.25, 0.25, 0.25
+    freqs = np.fft.rfftfreq(len(segment), 1.0 / sr)
+    sub = float(spec[freqs < _SUB_MAX].sum() / total)
+    low = float(spec[(freqs >= _SUB_MAX) & (freqs < _LOW_MAX)].sum() / total)
+    mid = float(spec[(freqs >= _LOW_MAX) & (freqs < _MID_MAX)].sum() / total)
+    high = float(spec[freqs >= _MID_MAX].sum() / total)
+    return sub, low, mid, high
+
+
+def classify_segment(segment: np.ndarray, sr: int) -> Label:
+    """Classify a single audio segment as KICK / SNARE / HAT / ghost.
+
+    Returns the label string. See module docstring for the reasoning behind
+    each threshold.
+    """
+    if len(segment) < 2:
+        return "ghost"
+    peak = float(np.max(np.abs(segment)))
+    if peak < _GHOST_PEAK:
+        return "ghost"
+
+    sub, low, mid, high = _band_energy(segment, sr)
+
+    # KICK: sub+low dominance with limited high content.
+    if (sub + low) >= _KICK_SUB_LOW_MIN and high < _KICK_HIGH_MAX:
+        return "KICK"
+
+    # HAT: overwhelmingly high-freq, almost no drum-body mid content.
+    if high >= _HAT_HIGH_MIN and mid <= _HAT_MID_MAX:
+        return "HAT"
+
+    # SNARE: broadband (mid body + high sizzle) AND loud.
+    if (
+        mid >= _SNARE_MID_MIN
+        and high >= _SNARE_HIGH_MIN
+        and peak >= _SNARE_PEAK_MIN
+    ):
+        return "SNARE"
+
+    # Fallback for ambiguous mid/high dominant loud hits — usually
+    # snares with unusual spectrum (e.g., rim-shots, piccolo snare).
+    if peak >= _SNARE_PEAK_MIN and (mid + high) >= 0.70:
+        return "SNARE"
+
+    # If nothing else matched but there's real energy, call it a hat
+    # rather than a ghost (ghost is reserved for quiet hits).
+    return "HAT"
+
+
+def classify_slices(
+    audio: np.ndarray,
+    sr: int,
+    frame_boundaries: Sequence[int],
+) -> List[SliceFeatures]:
+    """Classify every slice defined by ``frame_boundaries``.
+
+    ``frame_boundaries`` is a list of N+1 frame positions defining N slices.
+    For a sample with slices starting at frames [0, 1000, 3000, 5000] and
+    total length 10000 frames, pass [0, 1000, 3000, 5000, 10000].
+
+    Stereo input is auto-downmixed (mean of the two channels).
+
+    Returns a list of ``SliceFeatures`` in slice-index order.
+    """
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+
+    results: List[SliceFeatures] = []
+    for i in range(len(frame_boundaries) - 1):
+        start = int(frame_boundaries[i])
+        end = int(frame_boundaries[i + 1])
+        segment = audio[start:end]
+        label = classify_segment(segment, sr)
+        peak = float(np.max(np.abs(segment))) if len(segment) else 0.0
+        rms = float(np.sqrt(np.mean(segment ** 2))) if len(segment) else 0.0
+        sub, low, mid, high = _band_energy(segment, sr)
+        results.append(
+            SliceFeatures(
+                index=i,
+                label=label,
+                peak=peak,
+                rms=rms,
+                sub_pct=sub,
+                low_pct=low,
+                mid_pct=mid,
+                high_pct=high,
+            )
+        )
+    return results