livepilot 1.24.0 → 1.25.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## v1.25.0 — 2026-05-02
+
+Hybrid Knowledge Surface — closes the gap between "compose runs successfully" and "compose makes thoughtful production decisions" by giving the agent three layers of atlas-corpus access during plan design instead of one-shot pre-resolution.
+
+### Added — three new MCP tools
+
+- **`atlas_explore(role, mood, genre, artists?, n=5, avoid_uris?, cohort_constraint?)`** — refined per-role candidate query callable mid-design. Wraps `AtlasResolver.resolve_for_role` with corpus-deep ranking signals: tag/genre match base, signature_techniques mood overlap (+0.20), curated `.adg` boost (+0.10), recent positive preference (+0.10), §1 banned-default penalty for melodic roles (−0.50), opaque-M4L pad penalty (−0.30), §7 #2 anti-repeat (−0.15), caller avoid-list (−0.30). Returns 3-5 ranked candidates with reasoning trails and a cohort_hint inferred from result frequency.
+- **`atlas_audition(uri)`** — full sidecar dump for a single URI: character_tags, signature_techniques (joined from `device_techniques_index.json`), producer-curated macro names (joined via `preset_resolver`), curated `.adg` paths, related demos placeholder. Use BEFORE committing to a candidate when its tags alone aren't enough.
+- **`atlas_substitute(current_uri, anti_tag, n=3)`** — anti-tag-driven swap for after analyze_sound_design or analyze_mix flags an issue. Substring-matches anti_tag against the 11-key map (bright/harsh/aggressive/sparse/thin/muddy/clean/dark/warm/static/generic) to derive (excluded_tags, preferred_tags), filters role-mate candidates that don't carry excluded character_tags, ranks the survivors with preferred_tags as mood boost.
+
+### Added — framework
+
+- **`mcp_server/composer/framework/atlas_resolver.py`** — `AtlasResolver` class with `resolve_anchors()` (Layer A: cohort + role-anchored URIs at brief-build time, wraps `atlas_pack_aware_compose` with coarse→fine role mapping) and `resolve_for_role()` (Layer B: per-role ranked candidates with cohort_constraint + excluded_uris). `AtlasCandidate` and `AtlasAnchors` dataclasses define the shared shape. Memory-rule constants `BANNED_DEFAULT_MELODIC` and `OPAQUE_M4L_FOR_PAD` are exported.
+- **`mcp_server/atlas/explore_tools.py`** — pure-Python implementations for the three new MCP tools, including `_ANTI_TAG_MAP` (11-key inversion table) and `_load_device_techniques_index()` lazy loader.
+
+### Changed — KnowledgePack + brief
+
+- `KnowledgePack.build()` accepts `atlas`, `ableton`, `ctx`, `brief_text` kwargs. When `mode="full"` AND `atlas` AND `brief_text` are provided, populates `atlas_anchors` (best-effort — silently `None` on any failure path).
+- `build_full_brief` now threads the atlas object through. The brief carries `atlas_anchors` alongside the existing fields.
+- `_DESIGN_TARGETS` text in `full/brief_builder.py` updated to teach the LLM about the three new tools and when to call each.
+
+### Tests
+
+- `tests/composer/framework/test_atlas_resolver.py` — 17 cases covering ranking math (8), `resolve_for_role` (6), candidate shape (1), `resolve_anchors` integration with mocked `pack_aware_compose` (2).
+- `tests/atlas/test_explore_tools.py` — 20 cases covering `atlas_explore` (6), `atlas_audition` (5), `_resolve_anti_tags` (3), `atlas_substitute` (6).
+- `tests/test_tools_contract.py` — count assertion updated 459 → 462; atlas tool registry expects the three new names.
+
+### Tool count
+
+- Net delta: **459 → 462** (+3: atlas_explore, atlas_audition, atlas_substitute).
+
+### Changed — `resolve_for_role` four-source union
+
+- **`AtlasResolver.resolve_for_role()`** previously queried only the bundled atlas tag index (`self._atlas._by_tag`). User-curated rack instruments and pack overlays were structurally invisible to the agent's design-time queries.
+- Two-pass overlay union added via new helper `_gather_from_overlays()`:
+  - **Pass A** — explicit `entity_type="demo_project"` query against the `packs` namespace. Demo-project entries (analyzed `.als` parses with `track_names` + `parent_pack` + `device_class_counts`) are the highest-confidence per-role anchors. Each survivor receives a **+0.15 score boost** with reasoning trail entry `"demo_project ground-truth (+0.15)"`.
+  - **Pass B** — full overlay search with no namespace filter. Captures `packs/pack`, `packs/cross_pack_workflow`, `m4l-devices/*`, `user.*`, `elektron/*` entries that share role tags.
+- New helper `_overlay_entry_to_device()` synthesizes `overlay://<namespace>/<entity_id>` URIs so overlay candidates render in the same shape as factory atlas candidates. Agents resolve to a loadable URI via `extension_atlas_get(namespace, entity_id)` afterward.
+- Best-effort: import or runtime failure of the overlay backend silently returns an empty list rather than raising — matches the existing `resolve_anchors` failure semantics.
+
+### Changed — `_DESIGN_TARGETS` four-source search mandate
+
+- Brief text in `mcp_server/composer/full/brief_builder.py::_DESIGN_TARGETS` rewritten to explicitly require the agent to UNION four sources before committing any role pick:
+  1. **Source 1 — Factory atlas** (already in `atlas_anchors`): `atlas_explore` / `atlas_audition` / `atlas_substitute`.
+  2. **Source 2 — User corpus** (mandatory): `extension_atlas_search(query=role)` and `extension_atlas_search(query=role, entity_type="demo_project")` for ground-truth role→URI mappings, plus `extension_atlas_get(namespace, entity_id)` for full-body inspection.
+  3. **Source 3 — Anthropic Ableton Knowledge MCP**: `mcp__Ableton_Knowledge__search_transcripts` / `search_live_manual` / `search_knowledge_base` / `search_videos` for tutorial-grade context.
+  4. **Five-step protocol** documented per role: read anchor → atlas_explore → extension_atlas_search (corpus + demo_project) → Ableton_Knowledge search → union, score, commit.
+- Production motivation: factory-atlas-only selection consistently missed canonical user-curated rack instruments (e.g., the `808 Trap Selector Rack.adg` from the Trap Drums by Sound Oracle pack lives in the packs overlay, not the factory tag index).
+
+### Fixed — `load_browser_item(role="drum")` post-load defaults
+
+Two compounding bugs in `mcp_server/tools/browser.py` made `role="drum"` a no-op since v1.20:
+
+- **Wrong parameter name** — `_SIMPLER_ROLE_DEFAULTS["drum"]` set `"Sample Pitch Coarse"` to 36, but that parameter does NOT exist on `OriginalSimpler`. The `set_device_parameter` call raised `Parameter 'Sample Pitch Coarse' not found`, was swallowed by the per-param try/except, and silently lost. Replaced with `("Transpose", 24)` (range −48..+48 semitones); +24 compensates for Simpler's default sample root C3 vs the drum-pad MIDI convention C1. Melodic and texture roles updated to `("Transpose", 0)` (no shift — C3 default matches their input range).
+- **Device-detection logic never triggered** — wrapper checked `result.get("device_index")` and `result.get("class_name")` from the load response, but the underlying TCP `load_browser_item` command returns only `{loaded, name, device_count}`. Both fields were always `None`/`""`, the `Simpler in device_class` check failed, and the entire role-defaults branch was skipped on every call. Fixed: post-load probe via `get_device_info(track_index, device_index=0)` to read class + name, treating chain-head as the canonical instrument slot Live places fresh instruments at.
+- Same broken parameter name was also patched in `mcp_server/tools/_analyzer_engine/sample.py::_simpler_post_load_hygiene`. Auto-detect-drum-root-note now translates `drum_root → Transpose = 60 − drum_root`, clamped to ±48 semitones.
+- Response now carries `role`, `role_defaults_applied: [{parameter, value|skipped}…]`, and `device_class` so callers can verify the four defaults landed.
+
+### Added — M4L instrument post-load hygiene
+
+- New `_M4L_INSTRUMENT_HYGIENE` dict in `mcp_server/tools/browser.py` maps a device-name substring to a list of `(parameter_name, value)` tames. Runs **unconditionally** (not gated on `role`) post-load, after Simpler role defaults.
+- Initial entry: `Harmonic Drone Generator` (Drone Lab pack) — sets `Latch=0` (off), `Volume=-40` (≈ −20 dB display, vs default ≈ −6 dB), `Density=40` (40 %, vs default 80 %). Without these tames every fresh HDG load slammed an 8-voice drone at full volume the moment any MIDI note hit it. The `Latch` issue compounded by keeping that note ringing forever even after the MIDI source released.
+- Response now carries `m4l_hygiene: {device_name, applied: [{parameter, value|skipped}…]}` when a hygiene entry matches. One match per load (`break` after first hit).
+
+### Tests
+
+- `tests/test_next_steps_2026_04_22.py::test_role_defaults_reasonable_for_drum_role` — assertion updated to `Transpose == 24`; regression guard `"Sample Pitch Coarse" not in drum` prevents the broken param name from ever reappearing.
+- `tests/test_next_steps_2026_04_22.py::test_role_defaults_reasonable_for_melodic_role` — assertion updated to `Transpose == 0` plus the same regression guard.
+- All four role-defaults tests pass against the new `_SIMPLER_ROLE_DEFAULTS` shape.
+
 ## v1.24.0 — 2026-05-02
 
 Compose framework rebuild — fast / full / develop modes share an Applier substrate; full mode is a clean-room rewrite around an LLM-creative two-phase brief flow (LLM provides FORM, framework provides VOCABULARY).

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  459 tools. 54 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
+  462 tools. 55 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
 </p>
 
 <br>
@@ -59,7 +59,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## Two Ways to Talk to LivePilot
 
-Pick whichever is faster for the idea in your head — both reach the same 459-tool surface.
+Pick whichever is faster for the idea in your head — both reach the same 462-tool surface.
 
 ### Route A — Artist / aesthetic shorthand
 
@@ -112,8 +112,8 @@ Most sessions do both. Lead with shorthand to anchor the aesthetic, then refine
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   459 MCP Tools  │                                  │
-│                  │   54 domains     │                                  │
+│                  │   462 MCP Tools  │                                  │
+│                  │   55 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
 │           Remote Script ──┤── TCP 9878                                │
@@ -153,7 +153,7 @@ Most sessions do both. Lead with shorthand to anchor the aesthetic, then refine
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 459 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 462 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -205,7 +205,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-459 tools across 54 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+462 tools across 55 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -430,7 +430,7 @@ LivePilot reads Splice's local SQLite database to search your downloaded samples
 
 <br>
 
-### Composer — three modes (v1.24.0)
+### Composer — three modes (v1.25.0)
 
 Prompt-to-plan auto-composition engine. Three modes share a common Applier substrate (preflight: bridge handshake retry + analyzer load; postflight: monitoring=Auto on new tracks + back_to_arranger). All modes return executable plans — the agent executes each step, it does not run autonomously.
 
@@ -485,14 +485,14 @@ Extends an existing 8-bar loop without disturbing the seed material.
 - Writes per-track variants and new supporting layers alongside the seed
 - Invoke with: *"Develop this loop"* or *"Extend what's here into a longer idea"*
 
-#### KnowledgePack scaffolding (v1.24.0)
+#### KnowledgePack scaffolding (v1.25.0)
 
 All three modes share a `KnowledgePack` that provides structured creative context at runtime:
 
 - `event_lexicon` — 42 structural events across 7 categories (drum density, harmonic, texture, vocal, rhythm feel, tension, fx gesture)
 - `genre_context` — parses the 15-genre `genre-vocabularies.md` at load time
 - `artist_context` — parses the ~25-producer `artist-vocabularies.md` at load time
-- `atlas_candidates_per_role` — **stubbed in v1.24.0**, will be populated in v1.25
+- `atlas_candidates_per_role` — **stubbed in v1.25.0**, will be populated in v1.25
 
 #### Core composer tools
 
@@ -540,7 +540,7 @@ The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and le
 | Creative Constraints | 5 | constraint activation, reference-inspired variants |
 | Preview Studio | 5 | variant creation, preview rendering, comparison, commit |
 
-> **[View all 459 tools →](docs/manual/tool-catalog.md)**
+> **[View all 462 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -767,7 +767,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 459 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 462 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 5264 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

package/m4l_device/livepilot_bridge.js

@@ -34,7 +34,7 @@ outlets = 2; // 0: to udpsend (responses), 1: to buffer~/status
 // Single source of truth for the bridge version — bumped alongside the
 // rest of the release manifest. Surfaced in the UI via messnamed("livepilot_version", ...)
 // so the frozen .amxd visibly reports which build it was last exported from.
-var VERSION = "1.23.6";
+var VERSION = "1.25.0";
 
 // ── State ──────────────────────────────────────────────────────────────────
 

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.24.0"
+__version__ = "1.25.0"

package/mcp_server/atlas/explore_tools.py

@@ -0,0 +1,332 @@
+"""Three v1.25 atlas knowledge-surface tools — agent-callable mid-design.
+
+  atlas_explore     — refined per-role candidate query (wraps AtlasResolver)
+  atlas_audition    — full sidecar dump for one URI (signature_techniques +
+                      producer-curated macro values + related demos + curated ADGs)
+  atlas_substitute  — anti-tag-driven swap (used after analyze_sound_design or
+                      analyze_mix flags an issue with a chosen layer)
+
+Imported and registered via @mcp.tool() decorators in atlas/tools.py.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ── Anti-tag → character-tag inversion map ──────────────────────────
+#
+# Maps a free-text "anti" descriptor to (excluded_tags, preferred_tags).
+# Used by atlas_substitute. Keys are lowercased; matched as substring of the
+# caller's anti_tag string so "too bright" and "bright" both resolve.
+
+_ANTI_TAG_MAP: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = {
+    "bright":     (("bright", "high", "shimmer", "airy"), ("warm", "dark", "muted", "vintage")),
+    "harsh":      (("harsh", "aggressive", "distorted"), ("smooth", "soft", "clean")),
+    "aggressive": (("harsh", "aggressive", "punchy"),  ("soft", "warm", "subtle")),
+    "sparse":     (("minimal", "sparse", "thin"),     ("dense", "lush", "thick", "wide")),
+    "thin":       (("thin", "minimal"),               ("thick", "fat", "dense", "wide")),
+    "muddy":      (("muddy", "low_mid"),              ("clear", "open", "defined")),
+    "clean":      (("clean", "pristine"),             ("dirty", "saturated", "vintage", "lo-fi")),
+    "dark":       (("dark", "muted"),                 ("bright", "shimmer", "airy")),
+    "warm":       (("warm", "vintage"),               ("clean", "modern", "digital")),
+    "static":     (("static", "single_layer"),        ("evolving", "modulated", "movement")),
+    "generic":    (("generic", "default"),            ("character", "unique", "signature")),
+}
+
+
+def _resolve_anti_tags(anti_tag: str) -> tuple[list[str], list[str]]:
+    """Return (excluded_tags, preferred_tags) for an anti-tag string.
+
+    Substring-matches the caller's anti_tag string against keys in the map;
+    aggregates all hits. "too bright and harsh" → matches "bright" + "harsh".
+    Empty input returns ([], []) — caller should treat that as no-op.
+    """
+    excluded: list[str] = []
+    preferred: list[str] = []
+    s = (anti_tag or "").lower()
+    for key, (excl, pref) in _ANTI_TAG_MAP.items():
+        if key in s:
+            for t in excl:
+                if t not in excluded:
+                    excluded.append(t)
+            for t in pref:
+                if t not in preferred:
+                    preferred.append(t)
+    return excluded, preferred
+
+
+# ── Tech-index lookup ───────────────────────────────────────────────
+
+
+@lru_cache(maxsize=1)
+def _load_device_techniques_index() -> dict[str, list[dict]]:
+    """Lazy-load the device_techniques_index.json sidecar.
+
+    Returns the inner `devices` dict keyed by device id/slug, or {} on miss.
+    """
+    path = Path(__file__).parent / "device_techniques_index.json"
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data.get("devices") or {}
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.debug("device_techniques_index load failed: %s", exc)
+        return {}
+
+
+def _lookup_techniques(device: dict) -> list[dict]:
+    """Find signature_techniques entries for a device.
+
+    Tries device id first (matches the index key), then name slug.
+    Returns the list of {technique, description, aesthetic, kind} dicts;
+    empty list on miss.
+    """
+    if not device:
+        return []
+    index = _load_device_techniques_index()
+    if not index:
+        return []
+    dev_id = (device.get("id") or "").lower()
+    if dev_id and dev_id in index:
+        return list(index[dev_id])
+    name_slug = (device.get("name") or "").lower().replace(" ", "_")
+    if name_slug and name_slug in index:
+        return list(index[name_slug])
+    return []
+
+
+# ── Tool implementations ────────────────────────────────────────────
+
+
+def explore(
+    *,
+    atlas: Any,
+    role: str,
+    mood: str = "",
+    genre: str = "",
+    artists: Optional[list[str]] = None,
+    n: int = 5,
+    avoid_uris: Optional[list[str]] = None,
+    cohort_constraint: Optional[list[str]] = None,
+) -> dict:
+    """atlas_explore implementation — wraps AtlasResolver.resolve_for_role.
+
+    Returns a structured dict (not raw dataclass) so MCP serialization is clean.
+    Falls through gracefully when atlas is missing — empty `candidates` plus a
+    `reasoning` line that says why.
+    """
+    if atlas is None:
+        return {
+            "candidates": [],
+            "cohort_hint": None,
+            "reasoning": "atlas not loaded — no candidates available",
+        }
+
+    from ..composer.framework.atlas_resolver import AtlasResolver
+
+    resolver = AtlasResolver(atlas=atlas)
+    candidates = resolver.resolve_for_role(
+        role=role,
+        genre=genre,
+        mood=mood,
+        artist_refs=list(artists or []),
+        avoid=[],
+        cohort_constraint=list(cohort_constraint or []) or None,
+        excluded_uris=set(avoid_uris or []) or None,
+        n=n,
+    )
+
+    cohort_hint: Optional[str] = None
+    if cohort_constraint:
+        cohort_hint = cohort_constraint[0]
+    elif candidates:
+        # Most-frequent pack across top candidates
+        packs = [c.in_pack for c in candidates if c.in_pack]
+        if packs:
+            cohort_hint = max(set(packs), key=packs.count)
+
+    reasoning_bits: list[str] = []
+    if cohort_constraint:
+        reasoning_bits.append(f"cohort-constrained to: {', '.join(cohort_constraint)}")
+    if mood:
+        reasoning_bits.append(f"mood: {mood}")
+    if genre:
+        reasoning_bits.append(f"genre: {genre}")
+    if not candidates:
+        reasoning_bits.append(f"no candidates matched role '{role}'")
+
+    return {
+        "candidates": [asdict(c) for c in candidates],
+        "cohort_hint": cohort_hint,
+        "reasoning": "; ".join(reasoning_bits) or f"role '{role}' resolved",
+    }
+
+
+def audition(*, atlas: Any, uri: str) -> dict:
+    """atlas_audition implementation — full sidecar dump for a single URI.
+
+    Joins atlas device record + device_techniques_index entries +
+    preset_resolver curated macros (when pack is known and device user_name
+    matches a sidecar). Best-effort on every join — missing data returns
+    empty fields rather than failing the whole call.
+    """
+    if atlas is None:
+        return {"error": "atlas not loaded", "uri": uri}
+    if not uri:
+        return {"error": "uri is required", "uri": uri}
+
+    device = atlas.lookup(uri) if hasattr(atlas, "lookup") else None
+    if not device:
+        return {
+            "error": "device not found in atlas",
+            "uri": uri,
+            "hint": "URI may be a runtime browser URI (FileId-keyed). Try atlas_explore to find the canonical atlas URI.",
+        }
+
+    techniques = _lookup_techniques(device)
+    pack = device.get("pack")
+    user_name = device.get("name") or ""
+
+    producer_macros: list[dict] = []
+    curated_adg_paths: list[str] = []
+    if pack and user_name:
+        try:
+            from .preset_resolver import resolve_preset_for_device
+            preset_match = resolve_preset_for_device(
+                pack_slug=pack,
+                device_class=device.get("class") or "",
+                device_user_name=user_name,
+            )
+            if preset_match.get("found"):
+                # macro_names is {idx: name}; surface as a list ordered by index
+                names = preset_match.get("macro_names") or {}
+                for idx in sorted(names.keys()):
+                    producer_macros.append({
+                        "index": idx,
+                        "name": names[idx],
+                        "source_preset": preset_match.get("preset_name"),
+                    })
+                if preset_match.get("preset_file"):
+                    curated_adg_paths.append(preset_match["preset_file"])
+        except Exception as exc:
+            logger.debug("audition: preset_resolver failed: %s", exc)
+
+    return {
+        "uri": uri,
+        "name": user_name,
+        "id": device.get("id", ""),
+        "pack": pack,
+        "category": device.get("category", ""),
+        "character_tags": list(device.get("character_tags") or device.get("tags") or []),
+        "signature_techniques": techniques,
+        "producer_macros": producer_macros,
+        "curated_adg_paths": curated_adg_paths,
+        "enriched": bool(device.get("enriched")),
+        # Related demos: defer until v1.25.x reverse-index lands; explicit empty
+        # so callers can rely on the field's presence.
+        "related_demos": [],
+    }
+
+
+def substitute(
+    *,
+    atlas: Any,
+    current_uri: str,
+    anti_tag: str,
+    n: int = 3,
+) -> dict:
+    """atlas_substitute implementation — anti-tag-driven candidate swap.
+
+    Looks up the current device's role/category/tags, derives an excluded-tag
+    set from the anti_tag string, and returns N alternatives that:
+      - share role/category with the current pick
+      - do NOT carry any excluded character_tag
+      - are scored by AtlasResolver with the excluded names on the avoid list
+    """
+    if atlas is None:
+        return {"error": "atlas not loaded"}
+    if not current_uri:
+        return {"error": "current_uri is required"}
+
+    current = atlas.lookup(current_uri) if hasattr(atlas, "lookup") else None
+    if not current:
+        return {
+            "error": "current device not found in atlas",
+            "current_uri": current_uri,
+        }
+
+    excluded_tags, preferred_tags = _resolve_anti_tags(anti_tag)
+    if not excluded_tags:
+        return {
+            "error": f"unrecognized anti_tag '{anti_tag}'",
+            "supported_anti_tags": sorted(_ANTI_TAG_MAP.keys()),
+        }
+
+    # Derive a role tag from the current device's character_tags. Prefer the
+    # most-specific role term (kick/snare/hat/bass/pad/lead/atmos) over generic.
+    current_tags_lower = [
+        str(t).lower() for t in (current.get("character_tags") or current.get("tags") or [])
+    ]
+    role_priority = ("kick", "snare", "hihat", "hi-hat", "hat", "perc",
+                     "bass", "pad", "lead", "atmos", "vocal", "fx", "spectral")
+    role_tag = next((t for t in role_priority if t in current_tags_lower), "")
+    role = role_tag or current.get("category") or "unknown"
+
+    # Collect candidates from the same role tag, filter out any carrying an
+    # excluded character_tag.
+    by_tag = getattr(atlas, "_by_tag", {}) or {}
+    role_candidates: list[dict] = []
+    seen: set[str] = set()
+    for dev in by_tag.get(role_tag.lower(), []) if role_tag else []:
+        uri = dev.get("uri") or ""
+        if not uri or uri in seen or uri == current_uri:
+            continue
+        dev_tags = [str(t).lower() for t in (dev.get("character_tags") or dev.get("tags") or [])]
+        if any(excl in dev_tags for excl in excluded_tags):
+            continue
+        seen.add(uri)
+        role_candidates.append(dev)
+
+    # Score the survivors via AtlasResolver and pick top N
+    from ..composer.framework.atlas_resolver import AtlasResolver
+
+    resolver = AtlasResolver(atlas=atlas)
+    scored: list[tuple[float, dict]] = []
+    for dev in role_candidates:
+        score, reasoning = resolver._score(
+            dev,
+            role=role if role in {
+                "kick", "snare", "hat", "perc", "clap",
+                "bass", "pad", "lead", "atmos", "vocal_chop", "fx", "spectral",
+            } else "",
+            genre="",
+            mood=" ".join(preferred_tags),
+            artist_refs=[],
+            avoid=[],
+        )
+        scored.append((score, AtlasResolver._to_candidate(dev, score, reasoning, source="atlas").__dict__))
+
+    scored.sort(key=lambda x: -x[0])
+    alternatives = [c for _, c in scored[:n]]
+
+    return {
+        "current_uri": current_uri,
+        "current_name": current.get("name", ""),
+        "anti_tag": anti_tag,
+        "excluded_tags": excluded_tags,
+        "preferred_tags": preferred_tags,
+        "alternatives": alternatives,
+        "reasoning": (
+            f"Excluded tags {excluded_tags} from candidates sharing role '{role}'. "
+            f"Boosted candidates whose character_tags overlap preferred tags {preferred_tags}."
+        ),
+    }