livepilot 1.9.24 → 1.10.1

package/livepilot/skills/livepilot-sample-engine/references/sample-techniques.md

@@ -0,0 +1,131 @@
+# Sample Technique Catalog — 29 Recipes
+
+## Category 1: Rhythmic Sampling
+
+### slice_and_sequence (Surgeon)
+Classic MPC workflow: load loop, slice on transients, sequence with MIDI.
+**Material:** drum_loop, full_mix | **Steps:** load -> slice -> get slices -> create clip -> add notes
+
+### vocal_chop_rhythm (Alchemist)
+Chop vocal into syllable-length slices, trigger as staccato rhythm. Burial-inspired.
+**Material:** vocal | **Steps:** load -> slice by region -> MIDI staccato -> Auto Filter
+
+### micro_chop (Alchemist)
+1/32 slices, varied velocity, slight timing offsets. J Dilla micro-timing.
+**Material:** any loop | **Steps:** load -> manual slice -> dense 1/32 MIDI
+
+### stab_isolation (Surgeon)
+Isolate single chord stab, crop, retrigger rhythmically. DJ Premier style.
+**Material:** full_mix, instrument_loop | **Steps:** load -> classic mode -> crop -> MIDI
+
+### euclidean_slice_trigger (Alchemist)
+Map Simpler slices to Euclidean rhythm for polyrhythmic texture.
+**Material:** drum_loop, vocal, instrument_loop | **Steps:** load -> slice -> Euclidean pattern
+
+## Category 2: Textural Transformation
+
+### extreme_stretch (Alchemist)
+Paulstretch-style: Texture warp at 10-50x, reverb wash. Stars of the Lid territory.
+**Material:** any | **Steps:** load -> warp 64 beats -> Reverb 60-80% wet
+
+### drum_to_pad (Alchemist)
+Reverse + extreme stretch + reverb = drum hit becomes ambient pad.
+**Material:** drum_loop, one_shot | **Steps:** load -> reverse -> stretch -> Reverb
+
+### reverse_layer (Alchemist)
+Reversed sample as pre-echo swell or ghostly texture.
+**Material:** vocal, instrument_loop, one_shot | **Steps:** load -> reverse -> Delay
+
+### granular_scatter (Alchemist)
+Grain Delay as granular engine — scatter grains for cloud textures. Amon Tobin.
+**Material:** vocal, instrument_loop, texture | **Steps:** load -> Grain Delay -> Reverb
+
+### spectral_freeze (Alchemist)
+Crop to tiny region (50-200ms), extreme stretch = spectral freeze drone.
+**Material:** vocal, instrument_loop, full_mix | **Steps:** load -> crop -> stretch 64 beats
+
+### tail_harvest (Alchemist)
+Resample only the reverb/delay tail as independent texture.
+**Material:** any | **Steps:** load -> Reverb 100% wet -> level for subtle layer
+
+## Category 3: Melodic/Harmonic
+
+### key_matched_layer (Surgeon)
+Transpose to song key, EQ carve, blend behind existing elements.
+**Material:** instrument_loop | **Steps:** load -> transpose -> EQ -> volume -6 to -10dB
+
+### vocal_harmony_stack (Surgeon)
+Pitch-shifted vocal layers — Bon Iver Prismizer approach.
+**Material:** vocal | **Steps:** load -> duplicate -> transpose +3/+5/+7 -> blend
+
+### counterpoint_from_chops (Alchemist)
+Create countermelody from rearranged melodic fragments. Four Tet.
+**Material:** instrument_loop, vocal, full_mix | **Steps:** load -> slice by beat -> program melody
+
+### chord_stab_extraction (Surgeon)
+Isolate chord from full mix, crop, retrigger. Classic house/disco.
+**Material:** full_mix, instrument_loop | **Steps:** load -> slice -> crop -> rhythmic pattern
+
+## Category 4: Drum Enhancement
+
+### break_layering (Surgeon)
+Layer drum break under programmed drums. High-pass to avoid kick clash.
+**Material:** drum_loop | **Steps:** load -> warp 16 beats -> EQ HP 200-400Hz -> volume -10 to -15dB
+
+### ghost_note_texture (Alchemist)
+Heavy filter + low volume = barely audible ghost-note layer.
+**Material:** drum_loop | **Steps:** load -> Auto Filter BP 1-4kHz -> volume -18 to -24dB
+
+### transient_replacement (Surgeon)
+Layer one-shot transient over existing drums for punch.
+**Material:** one_shot | **Steps:** load -> classic mode -> MIDI on kick/snare hits
+
+### shuffle_extract (Alchemist)
+Extract groove timing from loop via slice positions, apply to MIDI.
+**Material:** drum_loop | **Steps:** load -> slice by transient -> read positions
+
+## Category 5: Vocal Processing
+
+### syllable_instrument (Alchemist)
+Each syllable = playable note. Vocal becomes a melodic instrument.
+**Material:** vocal | **Steps:** load -> slice by region -> program melody across slices
+
+### formant_shift_character (Alchemist)
+Shift formants for alien/robotic character. Transpose +/-12st.
+**Material:** vocal | **Steps:** load -> transpose -> Corpus for resonant body
+
+### vocal_freeze_drone (Alchemist)
+Sustain one vowel as ambient pad. Crop tiny region, extreme stretch.
+**Material:** vocal | **Steps:** load -> crop 100-300ms -> stretch 64 beats -> Chorus -> Reverb
+
+### phone_recording_texture (Alchemist)
+Burial signature: pitch down, lo-pass, ghost-level volume.
+**Material:** vocal, foley | **Steps:** load -> pitch -5 to -12 -> LP 800Hz -> volume -20 to -30dB
+
+## Category 6: Resampling Chains
+
+### serial_resample (Alchemist)
+Multi-pass destruction: Saturator + Grain Delay + Reverb, freeze, flatten, repeat.
+**Material:** any | **Steps:** load -> Saturator -> Grain Delay -> Reverb -> freeze -> flatten
+
+### parallel_resample (Alchemist)
+Duplicate, process one copy destructively, blend wet/dry.
+**Material:** any | **Steps:** load -> duplicate -> process duplicate -> blend -6 to -12dB
+
+### freeze_flatten_rechop (Alchemist)
+Freeze processed material, flatten to audio, re-slice the result. Recursive.
+**Material:** any | **Steps:** freeze -> flatten -> re-load into Simpler -> slice again
+
+## Category 7: Creative Constraints
+
+### one_sample_challenge (Alchemist)
+Build entire beat from one sample: kick, snare, hat, bass, pad all from slices.
+**Material:** any | **Steps:** load -> slice -> program full beat across slice pitches
+
+### found_sound_only (Alchemist)
+Non-musical field recordings as sole source material. Musique concrete.
+**Material:** foley | **Steps:** load -> slice -> EQ to isolate musical frequencies
+
+### reverse_engineering (Both)
+Recreate a reference track's texture by sampling and transforming similar elements.
+**Material:** full_mix | **Steps:** load -> slice by beat -> analyze structure

package/livepilot/skills/livepilot-sound-design-engine/SKILL.md

@@ -121,3 +121,48 @@ When adding processing blocks, prefer native Ableton devices for controllability
 - **Saturator** — waveshaping with multiple curve types
 
 Always `search_browser` before loading — never guess device names.
+
+## Deep Sound Design Reference
+
+Consult `references/sound-design-deep.md` for advanced techniques when working on creative requests. Key principles:
+
+### Making Sounds Breathe
+Every static sound can become alive with modulation below conscious perception:
+- **Filter breathing:** LFO at 0.1-0.5 Hz on filter cutoff, 5-15% depth
+- **Oscillator drift:** ±1-3 cent detune with very slow LFO (0.05-0.2 Hz)
+- **Amplitude micro-variation:** Perlin/brownian noise on volume, ±1-3 dB
+- **Rule:** If the listener can hear the modulation, it's too much. The best modulation is felt, not heard.
+
+### Space as Composition
+Reverb and delay are not decorations — in dub/minimal they ARE the composition:
+- **Dub chord:** Short stab → long delay (70-80% feedback) + filter on the delay return
+- **Delay throws:** Momentary send spikes (0→70% for half a beat) — the echo IS the event
+- **Sidechain reverb:** Dry drums trigger sidechain compression on reverb returns — the room pulses
+- **Feedback modulation:** Delay feedback at 75-85% + modulate delay time ±5-10% for warped echoes
+
+### Creative Sidechain (Beyond Pump)
+Sidechain compression is a modulation source, not just a mix tool:
+- **Sidechain filter:** Envelope follower from kick modulates pad filter cutoff — pad brightens between kicks
+- **Ghost sidechain:** Muted kick as sidechain source for textures — phantom groove on non-rhythmic elements
+- **Multiband sidechain:** Only duck sub frequencies from pad — shimmer stays, sub clears for kick
+
+### Effects as Instruments
+- **Self-oscillating filter:** Push resonance until it rings, play notes by changing cutoff
+- **Feedback loops:** Route output back to input through effects + compressor to control
+- **Convolution as synthesis:** Load non-IR files (speech, drum break) into convolution reverb — imprints spectral character
+- **Granular reverb:** Very short reverb (0.1-0.3s) high diffusion on percussion — smears transient into tonal cloud
+
+### The Frequency Dance
+At any moment, each frequency band should have one primary element. When one opens up, another pulls back:
+- Chord filter opens into highs → pull hi-hat back
+- Bass drops → kick shortens
+- Reverb tail fills → dry elements duck
+This is mix engineering as composition.
+
+### When to Apply These
+- User says "make it breathe" or "it sounds static" → micro-modulation
+- User says "more space" or "deeper" → dub techniques (delay throws, reverb composition)
+- User says "more groove" or "make it pump" → creative sidechain
+- User says "more texture" or "more complex" → textural layering
+- User says "surprise me" or "WTF moment" → brief textural disruption (2-8 beats max)
+- User says "warmer" or "more analog" → oscillator drift + subtle saturation + filter breathing

package/livepilot/skills/livepilot-wonder/SKILL.md

@@ -60,3 +60,20 @@ For the recommendation, explain:
 - Why this one over the others
 - What risk it introduces
 - What sacred elements it preserves
+
+## Creative Intelligence (consult before generating variants)
+
+Wonder Mode should produce musically interesting results, not just technically correct ones. Before generating or applying any variant:
+
+1. Read `references/device-knowledge/automation-as-music.md` for automation shapes and macro gestures
+2. Read `references/device-knowledge/creative-thinking.md` for emotional-to-technical mapping
+3. Read `references/device-knowledge/chains-genre.md` if the session has a genre identity
+
+When reviewing Wonder variants, aim for musical depth:
+- **Filter arcs** — evolving filter across sections adds movement
+- **Space arcs** — reverb/delay sends breathing with density
+- **Micro-modulation** — subtle LFOs on sustained sounds
+- **Macro gestures** — coordinated multi-parameter moves at transitions
+
+Note: these are agent-level guidelines, not enforced by the Wonder engine.
+The engine generates variants from semantic moves; the agent adds musical polish.

package/m4l_device/livepilot_bridge.js

@@ -84,7 +84,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.9.22"});
+            send_response({"ok": true, "version": "1.10.1"});
             break;
         case "get_params":
             cmd_get_params(args);

package/manifest.json

@@ -2,14 +2,14 @@
   "manifest_version": "0.3",
   "name": "livepilot",
   "display_name": "LivePilot — AI for Ableton Live",
-  "version": "1.9.24",
-  "description": "Agentic production system for Ableton Live 12. Make beats, mix tracks, design sounds, and arrange songs with 293 AI-powered tools.",
-  "long_description": "LivePilot is an AI production assistant that connects directly to Ableton Live 12. It can create drum patterns, program basslines, write chord progressions, design sounds, mix your tracks, analyze your audio, and arrange full songs — all through natural language.\n\n**What it does:**\n- Creates MIDI clips with notes, chords, and rhythms\n- Loads instruments and effects from Ableton's browser\n- Shapes sounds by adjusting device parameters\n- Mixes with volume, panning, sends, and automation\n- Analyzes your mix with real-time spectral data\n- Remembers your production style across sessions\n\n**How it works:**\nLivePilot installs a Remote Script in Ableton that communicates with the AI over a local TCP connection. Everything runs on your machine — no audio leaves your computer.",
+  "version": "1.10.1",
+  "description": "Agentic production system for Ableton Live 12. Make beats, mix tracks, design sounds, and arrange songs with 317 AI-powered tools.",
+  "long_description": "LivePilot is an agentic production system for Ableton Live 12. 317 tools across 43 domains — device atlas (1305 devices), sample intelligence (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, and 12 creative engines.\n\n**What it does:**\n- Creates MIDI clips with notes, chords, and rhythms\n- Loads instruments and effects via Device Atlas (1305 devices indexed)\n- Searches samples across Splice, Ableton browser, and filesystem\n- Plans compositions from text prompts with genre-aware layering\n- Slices samples with intent-based MIDI generation\n- Mixes with volume, panning, sends, and automation\n- Analyzes your mix with real-time spectral data (M4L bridge)\n- Diagnoses stuck sessions and generates creative rescue variants\n- Remembers your production style across sessions\n\n**How it works:**\nLivePilot installs a Remote Script in Ableton that communicates with the AI over a local TCP connection. Everything runs on your machine — no audio leaves your computer.",
   "author": {
     "name": "Pilot Studio",
     "url": "https://github.com/dreamrec/LivePilot"
   },
-  "license": "MIT",
+  "license": "BSL-1.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/dreamrec/LivePilot"

package/mcp_server/__init__.py

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

package/mcp_server/atlas/__init__.py

@@ -0,0 +1,357 @@
+"""Device Atlas v2 — indexed in-memory device knowledge base.
+
+Loads a JSON atlas file and builds indexes for fast lookup, search,
+suggestion, chain building, and device comparison.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+
+class AtlasManager:
+    """In-memory device atlas with indexed lookups."""
+
+    def __init__(self, atlas_path: str):
+        with open(atlas_path, "r") as f:
+            data = json.load(f)
+
+        self._meta = data.get("meta", {})
+        self._devices: List[Dict[str, Any]] = data.get("devices", [])
+
+        # ── Build indexes ───────────────────────────────────────────
+        self._by_id: Dict[str, Dict[str, Any]] = {}
+        self._by_name: Dict[str, Dict[str, Any]] = {}  # lowercase key
+        self._by_uri: Dict[str, Dict[str, Any]] = {}
+        self._by_category: Dict[str, List[Dict[str, Any]]] = {}
+        self._by_tag: Dict[str, List[Dict[str, Any]]] = {}
+        self._by_genre: Dict[str, List[Dict[str, Any]]] = {}
+
+        for dev in self._devices:
+            dev_id = dev.get("id", "")
+            dev_name = dev.get("name", "")
+            dev_uri = dev.get("uri", "")
+            dev_category = dev.get("category", "")
+
+            if dev_id:
+                self._by_id[dev_id] = dev
+            if dev_name:
+                self._by_name[dev_name.lower()] = dev
+            if dev_uri:
+                self._by_uri[dev_uri] = dev
+
+            # Category index
+            if dev_category:
+                self._by_category.setdefault(dev_category, []).append(dev)
+
+            # Tag index
+            for tag in dev.get("tags", []):
+                self._by_tag.setdefault(tag.lower(), []).append(dev)
+
+            # Genre index (primary + secondary)
+            for genre in dev.get("genres", {}).get("primary", []):
+                self._by_genre.setdefault(genre.lower(), []).append(dev)
+            for genre in dev.get("genres", {}).get("secondary", []):
+                self._by_genre.setdefault(genre.lower(), []).append(dev)
+
+    # ── Properties ──────────────────────────────────────────────────
+
+    @property
+    def version(self) -> str:
+        return self._meta.get("version", "unknown")
+
+    @property
+    def device_count(self) -> int:
+        return len(self._devices)
+
+    @property
+    def stats(self) -> Dict[str, Any]:
+        categories: Dict[str, int] = {}
+        for dev in self._devices:
+            cat = dev.get("category", "unknown")
+            categories[cat] = categories.get(cat, 0) + 1
+        return {
+            "version": self.version,
+            "device_count": self.device_count,
+            "categories": categories,
+            "index_sizes": {
+                "by_id": len(self._by_id),
+                "by_name": len(self._by_name),
+                "by_uri": len(self._by_uri),
+                "by_category": len(self._by_category),
+                "by_tag": len(self._by_tag),
+                "by_genre": len(self._by_genre),
+            },
+        }
+
+    # ── Lookup ──────────────────────────────────────────────────────
+
+    def lookup(self, name_or_id: str) -> Optional[Dict[str, Any]]:
+        """Exact match by ID, name (case-insensitive), or URI. Returns None on miss."""
+        # Try ID first
+        if name_or_id in self._by_id:
+            return self._by_id[name_or_id]
+        # Try name (case-insensitive)
+        lower = name_or_id.lower()
+        if lower in self._by_name:
+            return self._by_name[lower]
+        # Try URI
+        if name_or_id in self._by_uri:
+            return self._by_uri[name_or_id]
+        return None
+
+    # ── Search ──────────────────────────────────────────────────────
+
+    def search(
+        self, query: str, category: str = "all", limit: int = 10
+    ) -> List[Dict[str, Any]]:
+        """Multi-signal search scoring across name, tags, use_cases, genre, description."""
+        if not query:
+            return []
+
+        query_lower = query.lower()
+        query_words = query_lower.split()
+        results: List[Dict[str, Any]] = []
+
+        for dev in self._devices:
+            # Category filter
+            if category != "all" and dev.get("category", "") != category:
+                continue
+
+            score = 0
+            dev_name = dev.get("name", "")
+            dev_name_lower = dev_name.lower()
+
+            # Name scoring: 100pts exact, 50pts substring
+            if dev_name_lower == query_lower:
+                score += 100
+            elif query_lower in dev_name_lower:
+                score += 50
+
+            # Tag scoring: 30pts per matching tag
+            dev_tags = [t.lower() for t in dev.get("tags", [])]
+            for word in query_words:
+                if word in dev_tags:
+                    score += 30
+
+            # Use case scoring: 25pts per match
+            for use_case in dev.get("use_cases", []):
+                use_lower = use_case.lower()
+                for word in query_words:
+                    if word in use_lower:
+                        score += 25
+                        break  # one match per use_case
+
+            # Genre scoring: 20pts primary, 10pts secondary
+            genres = dev.get("genres", {})
+            for genre in genres.get("primary", []):
+                if query_lower in genre.lower() or genre.lower() in query_lower:
+                    score += 20
+            for genre in genres.get("secondary", []):
+                if query_lower in genre.lower() or genre.lower() in query_lower:
+                    score += 10
+
+            # Description keyword scoring: 15pts
+            description = dev.get("description", "").lower()
+            for word in query_words:
+                if len(word) >= 3 and word in description:
+                    score += 15
+
+            if score > 0:
+                results.append({"device": dev, "score": score})
+
+        # Sort by score descending, then by name for stability
+        results.sort(key=lambda r: (-r["score"], r["device"].get("name", "")))
+        return results[:limit]
+
+    # ── Suggest ─────────────────────────────────────────────────────
+
+    def suggest(
+        self,
+        intent: str,
+        genre: str = "",
+        energy: str = "medium",
+        limit: int = 5,
+    ) -> List[Dict[str, Any]]:
+        """Suggest devices for an intent, returning ranked list with rationale and recipe."""
+        # Use search to find candidates
+        search_query = intent
+        if genre:
+            search_query = f"{intent} {genre}"
+        candidates = self.search(search_query, limit=limit * 2)
+
+        results = []
+        for candidate in candidates[:limit]:
+            dev = candidate["device"]
+            dev_name = dev.get("name", "")
+            dev_category = dev.get("category", "")
+            dev_tags = dev.get("tags", [])
+            dev_sweet_spot = dev.get("sweet_spot", "")
+
+            # Build rationale
+            rationale_parts = []
+            if dev_category:
+                rationale_parts.append(f"{dev_name} is a {dev_category}")
+            if dev_tags:
+                rationale_parts.append(f"suited for {', '.join(dev_tags[:3])}")
+            if genre:
+                primary_genres = dev.get("genres", {}).get("primary", [])
+                if any(genre.lower() in g.lower() for g in primary_genres):
+                    rationale_parts.append(f"commonly used in {genre}")
+            rationale = " — ".join(rationale_parts) if rationale_parts else f"{dev_name} matches your intent"
+
+            # Build recipe
+            recipe = {}
+            if dev_sweet_spot:
+                recipe["sweet_spot"] = dev_sweet_spot
+            recipe["energy"] = energy
+            key_params = dev.get("key_parameters", [])
+            if key_params:
+                recipe["start_with"] = key_params[:3]
+
+            results.append({
+                "device": dev,
+                "rationale": rationale,
+                "recipe": recipe,
+            })
+
+        return results
+
+    # ── Chain Suggest ───────────────────────────────────────────────
+
+    def chain_suggest(
+        self, role: str, genre: str = ""
+    ) -> Dict[str, Any]:
+        """Suggest a device chain for a given role (e.g., 'bass', 'lead', 'pad')."""
+        chain: List[Dict[str, Any]] = []
+        position = 0
+
+        # Determine chain structure based on role
+        role_lower = role.lower()
+
+        # Stage 1: Instrument (if the role implies one)
+        instrument_intents = {
+            "bass": "bass synthesizer",
+            "lead": "lead synthesizer",
+            "pad": "pad synthesizer",
+            "keys": "keyboard instrument",
+            "drums": "drum machine",
+            "vocal": "vocal",
+        }
+
+        intent = instrument_intents.get(role_lower, role_lower)
+        search_q = f"{intent} {genre}" if genre else intent
+
+        # Find instrument
+        instrument_candidates = self.search(search_q, category="instrument", limit=3)
+        if instrument_candidates:
+            best = instrument_candidates[0]["device"]
+            chain.append({
+                "position": position,
+                "device": best,
+                "reason": f"Primary {role} instrument",
+            })
+            position += 1
+
+        # Stage 2: Effects
+        effect_stages = [
+            ("eq", f"Shape the {role} tone"),
+            ("compression", f"Control {role} dynamics"),
+            ("reverb", f"Add space to {role}"),
+        ]
+
+        for effect_type, reason in effect_stages:
+            effect_q = f"{effect_type} {genre}" if genre else effect_type
+            effect_candidates = self.search(effect_q, category="effect", limit=2)
+            if effect_candidates:
+                best = effect_candidates[0]["device"]
+                chain.append({
+                    "position": position,
+                    "device": best,
+                    "reason": reason,
+                })
+                position += 1
+
+        return {
+            "role": role,
+            "genre": genre,
+            "chain": chain,
+        }
+
+    # ── Compare ─────────────────────────────────────────────────────
+
+    def compare(
+        self, device_a: str, device_b: str, role: str = ""
+    ) -> Dict[str, Any]:
+        """Compare two devices side-by-side with a recommendation."""
+        dev_a = self.lookup(device_a)
+        dev_b = self.lookup(device_b)
+
+        if not dev_a:
+            return {"error": f"Device not found: {device_a}"}
+        if not dev_b:
+            return {"error": f"Device not found: {device_b}"}
+
+        def _summarize(dev: Dict[str, Any]) -> Dict[str, Any]:
+            return {
+                "name": dev.get("name", ""),
+                "category": dev.get("category", ""),
+                "tags": dev.get("tags", []),
+                "genres": dev.get("genres", {}),
+                "use_cases": dev.get("use_cases", []),
+                "description": dev.get("description", ""),
+                "cpu_weight": dev.get("cpu_weight", "unknown"),
+                "sweet_spot": dev.get("sweet_spot", ""),
+            }
+
+        summary_a = _summarize(dev_a)
+        summary_b = _summarize(dev_b)
+
+        # Recommendation logic: score each for the role
+        score_a = 0
+        score_b = 0
+        if role:
+            role_lower = role.lower()
+            # Check use_cases
+            for uc in dev_a.get("use_cases", []):
+                if role_lower in uc.lower():
+                    score_a += 20
+            for uc in dev_b.get("use_cases", []):
+                if role_lower in uc.lower():
+                    score_b += 20
+            # Check tags
+            for tag in dev_a.get("tags", []):
+                if role_lower in tag.lower():
+                    score_a += 10
+            for tag in dev_b.get("tags", []):
+                if role_lower in tag.lower():
+                    score_b += 10
+
+        if score_a > score_b:
+            recommendation = f"{summary_a['name']} is better suited for {role}" if role else f"{summary_a['name']} scores higher"
+        elif score_b > score_a:
+            recommendation = f"{summary_b['name']} is better suited for {role}" if role else f"{summary_b['name']} scores higher"
+        else:
+            recommendation = "Both devices are equally suited" + (f" for {role}" if role else "")
+
+        return {
+            "device_a": summary_a,
+            "device_b": summary_b,
+            "recommendation": recommendation,
+        }
+
+
+# ── Module-level lazy loader ───────────────────────────────────────
+
+_atlas_instance: Optional[AtlasManager] = None
+
+
+def _load_atlas() -> AtlasManager:
+    """Lazy-load the atlas from device_atlas.json in the same directory."""
+    global _atlas_instance
+    if _atlas_instance is None:
+        atlas_path = os.path.join(os.path.dirname(__file__), "device_atlas.json")
+        _atlas_instance = AtlasManager(atlas_path)
+    return _atlas_instance