livepilot 1.4.5 → 1.5.0

package/CHANGELOG.md

@@ -1,146 +1,153 @@
 # Changelog
 
-## [1.4.5] — 2026-03-18
-
-### Added
-- **Built-in Device Atlas** — 10 reference files covering all native Ableton instruments, effects, drums, EQ, dynamics, space, modulation, spectral, and MIDI tools. Agent uses these for informed device/parameter decisions without trial-and-error
-
-### Fixes
-- Excluded personal library data (M4L collections, AU/VST plugins, user samples) from npm package and git
-
-## [1.4.4] — 2026-03-18
-
-### Fixes
-- **`find_and_load_device` breadth-first search** — Pass 0 instant top-level check finds raw devices like "Operator", "Auto Filter", "Limiter" in O(50) instead of O(thousands). Falls back to breadth-first recursive search for nested items
-- **Better "no devices" error message** — `get_device_parameters` on an empty track now says "Track 'BASS' has no devices — load an instrument or effect first" instead of the confusing "Device index 0 out of range (0..-1)"
-
-## [1.4.3] — 2026-03-18
-
-### Fixes
-- **`find_and_load_device` now finds raw instruments** — two-pass search: exact name match first (finds "Operator" before "Hello Operator.adg"), then partial match for M4L devices (e.g., "Kickster" matches "trnr.Kickster")
-- **Browser now searches plugins and Max for Live categories** — added `browser.plugins` and `browser.max_for_live` to all browser operations. AU/VST/AUv3 plugins (Moog, Drambo, BYOD, etc.) are now discoverable and loadable via `find_and_load_device` and `search_browser("plugins")`
-- **`load_browser_item` handles Sounds FileId URIs** — URIs containing internal FileId references (e.g., `query:Sounds#Pad:FileId_6343`) now trigger a deep URI search instead of failing with "not found"
-- **`load_browser_item` URI category prioritization** — parses category hint from URI (e.g., `query:Drums#...` searches drums first), reducing search time from 10K+ iterations to under 1K for most loads
-- **Iteration limit increased** — `load_browser_item` and `load_device_by_uri` now search up to 50K iterations (was 10K), preventing timeouts on large browser categories
-- **Case-insensitive parameter matching** — `set_device_parameter` and `batch_set_parameters` now try exact match first, then case-insensitive fallback. Error messages list available parameter names for debugging
-- **Track index validation relaxed** — `_validate_track_index` in arrangement, browser, clips, notes, and tracks MCP tools now allows negative indices for return tracks (-1=A, -2=B) and -1000 for master, consistent with the remote script's `get_track()` behavior
-
-### Added
-- `search_browser("plugins")` — browse all installed AU/VST/AUv3 plugins
-- `search_browser("max_for_live")` — browse all M4L devices directly
-- `search_browser("clips")` and `search_browser("current_project")` — additional browser categories
-
-## [1.4.2] — 2026-03-18
-
-### Fixes
-- `memory_recall` multi-word search now works — queries are split into words and matched across name, tags, and qualities (was treating entire query as single substring)
-- `set_session_loop` returns correct loop state — echoes requested value instead of reading stale LOM property
-- `jump_to_time` returns correct position — echoes requested beat_time instead of reading stale `current_song_time`
-
-## [1.4.1] — 2026-03-18
-
-### Fixes
-- Browser search now enforces global 10,000 iteration budget across all categories (was resetting per-category)
-- `_search_recursive` returns early when `max_results` is reached instead of scanning remaining siblings
-- Narrowed 29 broad `except Exception` catches to specific types (`AttributeError`, `OSError`, `ValueError`) across browser, devices, mixing, and server modules
-- Kept `except Exception` only at the 3 outermost dispatch boundaries (router, command processor, logger)
-
-## [1.4.0] — 2026-03-18
-
-### Added
-- **Technique Memory System** — 8 new MCP tools (`memory_learn`, `memory_recall`, `memory_get`, `memory_replay`, `memory_list`, `memory_favorite`, `memory_update`, `memory_delete`) for persistent technique storage with agent-written stylistic qualities
-- Memory guide reference (`references/memory-guide.md`) with qualities template and examples
-- `/memory` command for browsing the technique library
-- Producer agent now consults memory by default before creative decisions (override with "fresh" / "ignore history")
-- Three memory modes: Informed (default), Fresh (override), Explicit Recall
-
-### Changed
-- Tool count: 96 → 104 (10 domains, was 9)
-- Commands: 4 → 5 (added /memory)
-
-## 1.3.0 — 2026-03-17
-
-### Enhancements
-- **Device tools now support return tracks and master track** — use negative `track_index` for return tracks (-1=A, -2=B) and -1000 for master track. Works with all 12 device tools: `get_device_info`, `get_device_parameters`, `set_device_parameter`, `batch_set_parameters`, `toggle_device`, `delete_device`, `load_device_by_uri`, `find_and_load_device`, `get_rack_chains`, `set_simpler_playback_mode`, `set_chain_volume`, `get_device_presets`
-- **Mixing tools now support return tracks** — `set_track_volume`, `set_track_pan`, `get_track_routing`, `set_track_routing` accept negative indices for return tracks
-- Fixed `quantize_clip` grid parameter documentation — was incorrectly documented as float beats, now correctly documented as integer enum (0-8)
-- Fixed tempo range typo in SKILL.md (was 20-969, corrected to 20-999)
-
-## 1.2.1 — 2026-03-17
-
-### Fixes
-- Remove 3 tools that don't work in Live 12's ControlSurface API: `create_group_track`, `freeze_track`, `flatten_track`
-- Fix `set_scene_name` — now allows empty string to clear scene name
-- Fix `set_scene_tempo` — removed invalid "0 to clear" (Live 12 range is 20-999 BPM)
-- All 96 tools live-tested against Ableton Live 12
-
-## 1.2.0 — 2026-03-17
-
-### New Tools (+5, total 96)
-- **`set_group_fold`** — fold/unfold a group track to show/hide children
-- **`set_track_input_monitoring`** — set input monitoring state (In/Auto/Off)
-- **`set_clip_warp_mode`** — set warp mode for audio clips (Beats/Tones/Texture/Re-Pitch/Complex/Complex Pro)
-- **`set_scene_color`** — set scene color (0-69)
-- **`set_scene_tempo`** — set per-scene tempo that triggers on launch (20-999 BPM)
-
-### Removed Tools (-3)
-- **`create_group_track`** — removed due to Live 12 API limitations
-- **`freeze_track`** — removed due to Live 12 API limitations
-- **`flatten_track`** — removed due to Live 12 API limitations
-
-### Enhancements
-- `get_clip_info` now returns `is_midi_clip`, `is_audio_clip`, and audio warp fields (`warping`, `warp_mode`)
-- `get_track_info` now returns `is_foldable`, `is_grouped`, `fold_state`, and `current_monitoring_state`
-
-### Fixes
-- `set_scene_name` now allows empty string to clear scene name
-
-## 1.1.2 — 2026-03-17
-
-### Fixes
-- Added missing `clip_index` validation to 4 arrangement MCP tools
-- Standardized `json` import (removed `_json` alias)
-- Added index range to arrangement clip error messages for consistency
-- Made installer version-agnostic (`/^Live \d+/` regex instead of hardcoded "Live 12")
-- Standardized project description across all config files
-
-## 1.1.1 — 2026-03-17
-
-### Fixes
-- Fixed `create_arrangement_clip` ignoring `loop_length` parameter (was always using source clip length for tiling)
-- Fixed double `end_undo_step()` calls in `create_arrangement_clip` and `set_arrangement_automation` (now uses `try/finally`)
-- Fixed `back_to_arranger` setting wrong value (`False` → `True`)
-- Added guard against `None` clip index after arrangement placement failure
-- Fixed `--doctor` summary not reflecting connection test result in exit code
-
-## 1.1.0 — 2026-03-17
-
-### New Tools (+7)
-- **`back_to_arranger`** — switch playback from session clips back to arrangement timeline
-- **`get_arrangement_notes`** — read MIDI notes from arrangement clips
-- **`remove_arrangement_notes`** — remove notes in a region of an arrangement clip
-- **`remove_arrangement_notes_by_id`** — remove specific notes by ID
-- **`modify_arrangement_notes`** — modify notes by ID (pitch, time, velocity, probability)
-- **`duplicate_arrangement_notes`** — copy notes by ID with optional time offset
-- **`get_device_presets`** — list presets for any device (audio effects, instruments, MIDI effects)
-
-### Fixes
-- Fixed arrangement tools test coverage (was missing 5 tools from expected set)
-- Synchronized tool count across all documentation (was 80/81/84, now consistently 91)
-
-## 1.0.0 — 2026-03-17
-
-Initial release.
-
-### Features
-- **84 MCP tools** across 9 domains: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement
-- **Remote Script** for Ableton Live 12 with thread-safe command queue via `schedule_message`
-- **MCP Server** (FastMCP) with input validation, auto-reconnect, and structured error messages
-- **CLI** (`npx livepilot`) with `--install`, `--uninstall`, `--status`, `--doctor`, `--version`
-- **Claude Code Plugin** with:
-  - `livepilot-core` skill — core discipline and workflow guides
-  - `livepilot-producer` agent — autonomous production from high-level descriptions
-  - 4 slash commands: `/session`, `/beat`, `/mix`, `/sounddesign`
-- **Installer** with auto-detection of Ableton paths on macOS and Windows
-- **Live 12 modern note API** support: note IDs, probability, velocity_deviation
-- **JSON over TCP** protocol on port 9878 with structured error codes
+## 1.5.0 — Agentic Production System (March 19, 2026)
+
+**Three-layer intelligence: Device Atlas + M4L Analyzer + Technique Memory.**
+
+LivePilot is no longer just a tool server. v1.5.0 reframes the architecture around three layers that give the AI context beyond raw API access:
+
+### Device Atlas
+- Structured knowledge corpus of 280+ Ableton devices, 139 drum kits, 350+ impulse responses
+- Indexed by category with sonic descriptions, parameter guides, and real browser URIs
+- The agent consults the atlas before loading any device — no more hallucinated preset names
+
+### M4L Analyzer (new in v1.1.0, now integrated into the agentic workflow)
+- 8-band spectral analysis, RMS/peak metering, pitch tracking, key detection on the master bus
+- The agent reads the spectrum after mixing moves to verify results
+- Key detection informs harmonic content decisions (bass lines, chord voicings)
+
+### Technique Memory
+- Persistent production decisions across sessions: beat patterns, device chains, mix templates, preferences
+- `memory_recall` matches on mood, genre, texture — not just names
+- The agent consults memory by default before creative decisions, building a profile of the user's taste over time
+
+### Producer Agent
+- Updated to use all three layers: atlas for instrument selection, analyzer for verification, memory for style context
+- Mandatory health checks between stages now include spectral verification when the analyzer is present
+
+### Documentation
+- README rewritten around the three-layer architecture
+- Manual updated with agentic approach section
+- Skill description reflects the full stack: tools + atlas + analyzer + memory
+- Comparison table updated to highlight knowledge, perception, and memory as differentiators
+
+---
+
+## 1.1.0 — M4L Bridge & Deep LOM Access (March 18-19, 2026)
+
+**23 new tools (104 -> 127), M4L Analyzer device, deep LiveAPI access via Max for Live bridge.**
+
+### M4L Bridge Architecture
+- New `LivePilot_Analyzer.amxd` Max for Live Audio Effect for the master track
+- UDP/OSC bridge: port 9880 (M4L -> Server), port 9881 (Server -> M4L)
+- `livepilot_bridge.js` with 22 bridge commands for deep LOM access
+- `SpectralCache` with thread-safe, time-expiring data storage (5s max age)
+- Graceful degradation: all 104 core tools work without the analyzer device
+- Base64-encoded JSON responses with chunked transfer for large payloads (>1400 bytes)
+- OSC addresses sent WITHOUT leading `/` to fix Max `udpreceive` messagename dispatch
+
+### New Tools: Analyzer Domain (20 tools)
+
+**Spectral Analysis (3):**
+- `get_master_spectrum` — 8-band frequency analysis (sub/low/low-mid/mid/high-mid/high/presence/air)
+- `get_master_rms` — real-time RMS, peak, and pitch from the master bus
+- `get_detected_key` — Krumhansl-Schmuckler key detection algorithm on accumulated pitch data
+
+**Deep LOM Access (4):**
+- `get_hidden_parameters` — all device parameters including hidden ones not in ControlSurface API
+- `get_automation_state` — automation state for all parameters (active/overridden)
+- `walk_device_tree` — recursive device chain tree walking (racks, drum pads, nested devices, 6 levels deep)
+- `get_display_values` — human-readable parameter values as shown in Live's UI (e.g., "440 Hz", "-6.0 dB")
+
+**Simpler Operations (7):**
+- `replace_simpler_sample` — load audio file into Simpler by absolute path (requires existing sample)
+- `load_sample_to_simpler` — full workflow: bootstrap Simpler via browser, then replace sample
+- `get_simpler_slices` — get slice point positions (frames and seconds) from Simpler
+- `crop_simpler` — crop sample to active region
+- `reverse_simpler` — reverse sample in Simpler
+- `warp_simpler` — time-stretch sample to fit N beats at current tempo
+- `get_clip_file_path` — get audio file path on disk for a clip
+
+**Warp Markers (4):**
+- `get_warp_markers` — get all warp markers (beat_time + sample_time) from audio clips
+- `add_warp_marker` — add warp marker at beat position
+- `move_warp_marker` — move warp marker to new beat position (tempo manipulation)
+- `remove_warp_marker` — remove warp marker at beat position
+
+**Clip Preview (2):**
+- `scrub_clip` — scrub/preview clip at specific beat position
+- `stop_scrub` — stop scrub preview
+
+### New Tools: Mixing Domain (3 tools)
+- `get_track_routing` — get input/output routing info for a track
+- `set_track_routing` — set input/output routing by display name
+- `get_mix_snapshot` — one-call full mix state (all meters, volumes, pans, sends, master)
+
+### Bugs Fixed
+
+**M4L Bridge Fixes:**
+- OSC addresses: removed leading `/` from outgoing commands — Max `udpreceive` passes the `/` as part of the messagename to JS, breaking the dispatch switch statement
+- `str_for_value` requires `call()` not `get()` — it's a function, not a property in Max JS LiveAPI
+- `warp_markers` is a dict property returning a JSON string, not LOM children — requires `JSON.parse()` on the raw `get()` result
+- `SimplerDevice.slices` lives on the `sample` child object (`device sample slices`), not on the device directly
+- `replace_sample` only works on Simplers that already have a sample loaded — silently fails on empty Simplers
+- `get()` in Max JS LiveAPI always returns arrays — must index or convert appropriately
+- `openinpresentation` attribute in .amxd doesn't persist from Max editor saves — requires binary patching
+
+**M4L Analyzer Display Fixes:**
+- Injected `settype Float` messages to fix spectrum bar display (was showing integer 0/1)
+- Fixed `vexpr` scaling factor from 10 to 200 for proper bar visualization range
+- Fixed freeze/JS caching: Max freezes JS from its search path cache (`~/Documents/Max 8/...`), not from the source file directory
+
+**Tool Fixes:**
+- Fixed key detection passthrough from streaming cache to bridge query fallback
+- Fixed parameter name case-sensitivity in hidden parameter reads
+- Fixed input validation on several analyzer tools (missing clip/track validation)
+- Fixed `load_sample_to_simpler` bootstrap: searches browser for any sample, loads it to create Simpler, then replaces
+
+### LiveAPI Insights Documented
+- `get()` returns arrays in Max JS LiveAPI (even for scalar properties)
+- `call()` vs `get()` distinction for functions vs properties
+- `.amxd` binary format: 24-byte `ampf` header + `ptch` chunk + `mx@c` header + JSON patcher + frozen dependencies
+- Binary patching technique: same-byte-count string replacements preserve file structure
+- Max freezes JS from cache path, not source directory — must copy to `~/Documents/Max 8/`
+
+### Technical
+- New `mcp_server/m4l_bridge.py` module: `SpectralCache`, `SpectralReceiver`, `M4LBridge` classes
+- New `mcp_server/tools/analyzer.py`: 20 MCP tools for the analyzer domain
+- New `m4l_device/livepilot_bridge.js`: 22 bridge commands
+- New `m4l_device/LivePilot_Analyzer.amxd`: compiled M4L device
+
+---
+
+## 1.0.0 — LivePilot
+
+**AI copilot for Ableton Live 12 — 104 MCP tools for real-time music production.**
+
+### Core
+- 104 MCP tools across 10 domains: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory
+- Remote Script using Ableton's official Live Object Model API (ControlSurface base class)
+- JSON over TCP, newline-delimited, port 9878
+- Structured errors with codes: INDEX_ERROR, NOT_FOUND, INVALID_PARAM, STATE_ERROR, TIMEOUT, INTERNAL
+
+### Browser & Device Loading
+- Breadth-first device search with exact-match priority
+- Plugin browser support (AU/VST/AUv3) via `search_browser("plugins")`
+- Max for Live browser via `search_browser("max_for_live")`
+- URI-based loading with category hint parsing for fast resolution
+- Case-insensitive parameter name matching
+
+### Arrangement
+- Full arrangement view support: create clips, add/remove/modify notes, automation envelopes
+- Automation on device parameters, volume, panning, and sends
+- Support for return tracks and master track across all tools
+
+### Plugin
+- 5 slash commands: /beat, /mix, /sounddesign, /session, /memory
+- Producer agent for autonomous multi-step tasks
+- Technique memory system (learn, recall, replay, favorite)
+- Built-in Device Atlas covering native Ableton instruments and effects
+
+### Installer
+- Auto-detects Ableton Remote Scripts path on macOS and Windows
+- Copies Remote Script files, verifies installation