livepilot 1.26.0 → 1.26.1

package/livepilot/skills/livepilot-evaluation/references/capability-modes.md

@@ -0,0 +1,176 @@
+# Capability Modes Reference
+
+The evaluation engine adapts its behavior based on what measurement capabilities are available. Call `get_capability_state` to determine the current mode.
+
+## Mode: normal
+
+Full measurement capabilities available.
+
+**Requirements:**
+- Ableton Live connected via TCP port 9878
+- M4L analyzer bridge running on master track
+- UDP 9880 (M4L -> Server) and OSC 9881 (Server -> M4L) active
+- SpectralCache receiving fresh data (age < 5 seconds)
+
+**Available measurements:**
+- `get_master_spectrum` — 9-band spectral analysis (sub_low → air), real-time
+- `get_master_rms` — RMS and peak levels
+- `get_detected_key` — key detection from audio
+- `get_mel_spectrum` — mel-scaled spectral representation
+- `get_chroma` — chromagram for harmonic analysis
+- `get_onsets` — transient detection
+- `get_momentary_loudness` — short-term loudness
+- `get_spectral_shape` — centroid, spread, skewness, kurtosis
+- All device parameter reads and session state tools
+
+**Evaluation quality:** Highest. Critics use measured spectral evidence. Before/after comparisons are numerically precise.
+
+## Mode: measured_degraded
+
+Analyzer data is present but stale or intermittent.
+
+**Indicators:**
+- SpectralCache age > 5 seconds
+- Intermittent UDP packet loss from M4L device
+- M4L bridge loaded but analyzer section not receiving audio
+
+**Available measurements:**
+- All session state tools (tracks, clips, devices, parameters)
+- Cached spectral data (may not reflect current audio)
+- Device parameter reads (always fresh)
+
+**Evaluation quality:** Moderate. Spectral comparisons may be inaccurate if data is stale. Always check cache age before trusting spectrum values.
+
+**User notification:** "Analyzer data may be stale. For accurate spectral evaluation, play audio through the master bus and wait 2-3 seconds for the cache to refresh."
+
+## Mode: judgment_only
+
+No M4L analyzer connected. The evaluation engine operates on structural and parametric data only.
+
+**Indicators:**
+- M4L bridge not loaded on master track
+- UDP 9880 not receiving data
+- `get_master_spectrum` returns error or empty data
+
+**Available measurements:**
+- All session state tools
+- Device parameter reads
+- Track structure (names, types, device chains)
+- Note and clip data
+- Role-based heuristics (bass tracks should have low content, etc.)
+
+**Evaluation quality:** Limited. No spectral evidence for masking, balance, or loudness judgments. Critics infer from:
+- Track names and roles (a track named "Bass" should have low-frequency content)
+- Device chains (a track with EQ Eight + Compressor is likely processed)
+- Parameter values (filter cutoff position, compressor threshold)
+- Volume/pan/send positions
+
+**User notification:** "M4L analyzer is not connected. Evaluation is based on track structure and parameter analysis only. For spectral verification, load the LivePilot Bridge device on the master track."
+
+## Mode: read_only
+
+Session disconnected or in an error state.
+
+**Indicators:**
+- TCP connection to port 9878 failed or timed out
+- Remote Script not responding
+- Ableton Live not running or crashed
+
+**Available measurements:**
+- Cached session data from last successful connection
+- Memory system (technique recall, preferences)
+- No live reads from the session
+
+**Evaluation quality:** None for current state. Can only reference cached data and memory.
+
+**User notification:** "Session disconnected. Cannot evaluate current state. Reconnect to Ableton Live to resume."
+
+## Capability Fallback Chain
+
+When a measurement fails, fall back gracefully:
+
+1. Try the primary measurement tool
+2. If it fails, check if degraded data is available in cache
+3. If no cache, use parametric/structural heuristics
+4. If no session connection, report inability and suggest reconnection
+
+Never silently skip evaluation. Always inform the user which capability mode is active and how it affects the quality of judgment.
+
+## Checking Capability State
+
+Call `get_capability_state` at the start of any evaluation session. The response is a nested `domains` dict keyed by capability name — NOT the flat shape older docs described.
+
+```json
+{
+  "capability_state": {
+    "generated_at_ms": 1776929160866,
+    "overall_mode": "normal",
+    "domains": {
+      "session_access": {"name": "session_access", "available": true,  "confidence": 1.0, "mode": "healthy",     "reasons": []},
+      "analyzer":       {"name": "analyzer",       "available": true,  "confidence": 0.9, "mode": "available",   "reasons": []},
+      "memory":         {"name": "memory",         "available": true,  "confidence": 1.0, "mode": "available",   "reasons": []},
+      "web":            {"name": "web",            "available": true,  "confidence": 0.7, "mode": "available",   "reasons": []},
+      "research":       {"name": "research",       "available": true,  "confidence": 0.9, "mode": "available",   "reasons": []},
+      "flucoma":        {"name": "flucoma",        "available": false, "confidence": 0.0, "mode": "unavailable", "reasons": ["flucoma_not_installed"]}
+    }
+  }
+}
+```
+
+### Top-level fields
+
+- `capability_state.generated_at_ms`: Unix-ms timestamp of the probe.
+- `capability_state.overall_mode`: one of `"normal"`, `"measured_degraded"`, `"judgment_only"`, `"read_only"` — the global evaluation-quality tier computed from the per-domain signals.
+- `capability_state.domains`: dict keyed by domain name; each value is a capability-domain record.
+
+### Per-domain fields
+
+Every entry in `domains` has the same shape:
+
+- `name`: the domain key (`"session_access"`, `"analyzer"`, `"memory"`, `"web"`, `"research"`, `"flucoma"`).
+- `available`: boolean — is this capability ready to use right now?
+- `confidence`: 0.0–1.0 — how much to trust the `available` flag (e.g. stale analyzer data lowers confidence).
+- `mode`: short human label specific to the domain (`"healthy"`, `"available"`, `"measured"`, `"stale"`, `"targeted_only"`, `"full"`, `"unavailable"`).
+- `reasons`: list of short machine-readable tokens explaining why the domain is in its current state (`"analyzer_offline"`, `"web_unavailable"`, `"flucoma_not_installed"`, …). Empty when healthy.
+- `freshness_ms`: optional — milliseconds since the domain last received fresh data (currently only the analyzer domain populates this).
+
+### Domain definitions
+
+- **session_access** — live TCP connectivity to the Ableton Remote Script on port 9878. `available=true` means a `get_session_info` round-trip succeeded.
+- **analyzer** — the M4L bridge + spectral cache. `available=true` requires the bridge to be connected AND the spectral cache to have recently received data.
+- **memory** — the local technique-store / taste memory. `available=true` means the persistent stores can be read and written.
+- **web** — server-side outbound HTTP capability. True when the MCP host can reach an arbitrary public URL (probed by a 500 ms HEAD request to `https://api.github.com`). Does NOT imply curated research corpora are installed — see the `research` domain for that.
+- **research** — composite over `session_access`, `memory`, and `web`. `mode="full"` when all three are available; `"targeted_only"` when at least one source is up; `"unavailable"` when nothing is reachable.
+- **flucoma** — whether the optional `flucoma` Python package is importable (probed via `importlib.util.find_spec`). FluCoMa-backed tools (`check_flucoma`, `extract_timbre_fingerprint`, etc.) degrade gracefully when this domain is unavailable.
+
+## Collaborative Mode (Live 12.4+)
+
+Live 12.4 introduces a new capability tier that unlocks native LOM access for sample replacement. This tier is separate from the evaluation modes above — it affects routing behavior in the MCP server, not spectral measurement.
+
+**Version gate:** Live 12.4.0+
+
+**Detection flag:** `LiveVersionCapabilities.has_replace_sample_native == True`
+(exposed on `LiveVersionCapabilities.capability_tier == "collaborative"`)
+
+**What changes at this tier:**
+- `SimplerDevice.replace_sample(path)` is available as a native LOM call.
+  The MCP tools `replace_simpler_sample` and `load_sample_to_simpler`
+  route to this native path automatically.
+- The native path handles empty Simplers — the long-standing limitation
+  (documented in `feedback_load_browser_item_is_source_of_truth.md`)
+  that required `load_browser_item` as a workaround no longer applies
+  on Live 12.4+.
+
+**Backward compatibility:**
+- Live 12.0–12.3.x: `has_replace_sample_native == False`. All sample
+  replacement still routes through the M4L bridge. Zero behavior change.
+- Live 12.4+: native path preferred; M4L bridge used only on fallback.
+
+**Tool signatures:** unchanged. Callers do not need to detect the tier —
+routing is transparent.
+
+**Follow-up plans (not yet shipped):**
+- Link Audio (tempo-sync sharing between Live sets) — tracked as a
+  future Collaborative-tier feature.
+- Stem Separation v2 — tracked as a future Collaborative-tier feature.
+Neither is available in the 1.26.1 release — still pending.

package/livepilot/skills/livepilot-evaluation/references/evaluation-contracts.md

@@ -0,0 +1,121 @@
+# Evaluation Contracts Reference
+
+Every evaluator returns the same base contract. Engine-specific evaluators extend it with additional fields.
+
+## Base Evaluation Contract
+
+Returned by `evaluate_move`:
+
+```json
+{
+  "keep_change": true,
+  "score": 0.72,
+  "goal_progress": 0.6,
+  "collateral_damage": [],
+  "explanation": "Filter cut at 250 Hz reduced masking by 4 dB without affecting bass body.",
+  "before_metrics": {
+    "master_rms_db": -12.4,
+    "master_peak_db": -3.2,
+    "spectrum": [...]
+  },
+  "after_metrics": {
+    "master_rms_db": -12.8,
+    "master_peak_db": -3.5,
+    "spectrum": [...]
+  }
+}
+```
+
+### Field Definitions
+
+- **keep_change** (bool): `true` if the change improved the target without unacceptable regression. `false` if the change should be undone.
+- **score** (float 0.0-1.0): 0.0 = catastrophic regression, 0.5 = neutral (no change), 1.0 = perfect improvement. Scores below 0.4 trigger automatic undo recommendation.
+- **goal_progress** (float 0.0-1.0): how much of the stated goal has been achieved. 1.0 means the goal is fully met. Use this to decide whether to continue iterating.
+- **collateral_damage** (list of strings): side effects that got worse. Empty list means no regressions detected. Examples: "bass lost 2 dB of body", "stereo width narrowed by 15%".
+- **explanation** (string): one-sentence human-readable summary of the judgment. Always report this to the user.
+
+## Mix Evaluation Contract
+
+Returned by `evaluate_mix_move`, extends base with:
+
+```json
+{
+  "targets": {
+    "reduce_masking": { "before": 0.72, "after": 0.35, "improved": true },
+    "maintain_headroom": { "before": -3.2, "after": -3.5, "ok": true }
+  },
+  "protect": {
+    "bass_body": { "before": -14.2, "after": -14.8, "ok": true },
+    "vocal_presence": { "before": -8.1, "after": -8.0, "ok": true }
+  },
+  "spectral_delta_db": {
+    "sub": 0.1, "low": -0.3, "low_mid": -2.1,
+    "mid": 0.2, "high_mid": 0.1, "high": 0.0
+  }
+}
+```
+
+- **targets**: what the move aimed to improve, with before/after measurements
+- **protect**: what must not get worse, with tolerance checking
+- **spectral_delta_db**: per-band change in spectral energy
+
+## Composition Evaluation Contract
+
+Returned by `evaluate_composition_move`, extends base with:
+
+```json
+{
+  "structural_coherence": 0.85,
+  "thematic_continuity": 0.78,
+  "energy_delta": 0.15,
+  "transition_smoothness": 0.82,
+  "note_count_delta": 12
+}
+```
+
+- **structural_coherence**: how well the change fits the overall form
+- **thematic_continuity**: whether existing motifs are maintained or developed (not broken)
+- **energy_delta**: change in section energy level
+- **transition_smoothness**: quality of section boundaries after the change
+
+## Fabric Evaluation Contract
+
+Returned by `evaluate_with_fabric`, extends base with:
+
+```json
+{
+  "taste_alignment": 0.88,
+  "anti_preference_violations": [],
+  "similar_past_moves": [
+    { "memory_id": "mix_001", "similarity": 0.91, "past_score": 0.85 }
+  ],
+  "novelty_score": 0.3
+}
+```
+
+- **taste_alignment**: how well the move matches the user's saved taste profile
+- **anti_preference_violations**: list of anti-preferences this move conflicts with (should be empty)
+- **similar_past_moves**: techniques from memory that resemble this move, with their past scores
+- **novelty_score**: how different this move is from past approaches (high = novel, low = familiar)
+
+## Scoring Thresholds
+
+| Score Range | Interpretation | Action |
+|------------|---------------|--------|
+| 0.0 - 0.3 | Significant regression | Auto-undo, explain damage |
+| 0.3 - 0.45 | Mild regression | Undo recommended, ask user |
+| 0.45 - 0.55 | Neutral / no effect | Keep but note it had no impact |
+| 0.55 - 0.7 | Mild improvement | Keep, continue iterating |
+| 0.7 - 0.85 | Clear improvement | Keep, suggest memory promotion |
+| 0.85 - 1.0 | Excellent improvement | Keep, strongly suggest promotion |
+
+## Collateral Damage Categories
+
+Common side effects to check for:
+
+- **bass_body_loss**: EQ cuts in the low-mid range reduced bass warmth
+- **stereo_narrowing**: mono compatibility fix reduced perceived width
+- **headroom_reduction**: boost increased master peak level
+- **transient_loss**: compression removed punch from drums
+- **vocal_masking**: frequency boost created new masking with vocal track
+- **phase_issue**: stereo manipulation introduced phase cancellation

package/livepilot/skills/livepilot-evaluation/references/memory-promotion.md

@@ -0,0 +1,110 @@
+# Memory Promotion Reference
+
+Memory promotion saves successful production moves to persistent storage for recall in future sessions.
+
+## Promotion Flow
+
+1. A move scores > 0.7 in evaluation
+2. Call `get_promotion_candidates` to list all eligible moves from this session
+3. Present the candidate to the user with score and description
+4. If the user confirms, call `memory_learn(name, type, qualities, payload)` to save
+5. The technique is now available via `memory_recall` in future sessions
+
+## Promotion Candidates
+
+`get_promotion_candidates` returns moves that meet all criteria:
+
+- Evaluation score > 0.7
+- `keep_change` was `true`
+- The move has not already been promoted
+- The move does not conflict with any anti-preference
+
+Response format:
+```json
+{
+  "candidates": [
+    {
+      "action_id": "act_001",
+      "move_type": "eq_cut",
+      "score": 0.85,
+      "goal": "reduce masking between bass and kick",
+      "parameters": {
+        "track": "Bass",
+        "device": "EQ Eight",
+        "band": 3,
+        "frequency": 250,
+        "gain_db": -4.5,
+        "q": 2.0
+      },
+      "explanation": "4.5 dB cut at 250 Hz on bass cleared kick presence without losing bass warmth"
+    }
+  ]
+}
+```
+
+## Memory Types
+
+When calling `memory_learn`, specify the type:
+
+- `mix_template` — mixing techniques (EQ curves, compression settings, gain staging recipes)
+- `sound_design` — patch design moves (modulation settings, filter configurations, oscillator tuning)
+- `composition` — structural techniques (transition patterns, arrangement gestures, motif transformations)
+- `automation` — automation curves and recipes
+- `performance` — live performance patterns (scene orderings, safe macro ranges)
+
+## Anti-Preferences
+
+Anti-preferences are the inverse of promotion — they record moves the user explicitly rejected.
+
+### Recording
+
+Call `record_anti_preference(dimension, direction)` when:
+- The user says "I hate that", "never do that again", "that's wrong"
+- A move is undone and the user expresses displeasure (not just neutral undo)
+- The user explicitly states a preference against a technique
+
+### Checking
+
+Call `get_anti_preferences` before suggesting any move. The response lists all recorded anti-preferences with descriptions and creation dates.
+
+### Format
+```json
+{
+  "anti_preferences": [
+    {
+      "id": "ap_001",
+      "description": "Never boost above 10 kHz on vocals — user finds it harsh",
+      "created": "2026-04-08T14:30:00Z"
+    },
+    {
+      "id": "ap_002",
+      "description": "No sidechain compression on pads — user prefers volume automation for ducking",
+      "created": "2026-04-09T09:15:00Z"
+    }
+  ]
+}
+```
+
+### Rules
+
+1. Always check anti-preferences before planning any move
+2. If a planned move matches an anti-preference, skip it and choose an alternative
+3. Anti-preferences are permanent until the user explicitly asks to remove one
+4. When skipping a move due to anti-preference, tell the user: "Skipping [move] because you previously indicated [anti-preference]."
+
+## Promotion Best Practices
+
+1. **Do not auto-promote.** Always ask: "That scored [score] — want me to save this technique?"
+2. **Include context in the saved data.** A raw parameter value without context (genre, source material, goal) is less useful on recall.
+3. **Group related moves.** If three EQ cuts together solved a masking problem, save them as one technique, not three.
+4. **Tag with genre and role.** A bass EQ technique for house music may not apply to jazz. Include tags for future filtering.
+5. **Review periodically.** Suggest `memory_list` to the user occasionally to prune outdated techniques.
+
+## Recall Integration
+
+When starting a new production task:
+
+1. Call `memory_recall(type, query)` to find relevant past techniques
+2. Present matches with their past scores: "I found a similar technique from a past session (scored 0.85). Want me to try it here?"
+3. If the user agrees, apply the recalled technique and evaluate as normal
+4. If the recalled technique scores lower in the new context, note this — context sensitivity means not all techniques transfer

package/livepilot/skills/livepilot-mix-engine/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: livepilot-mix-engine
+description: This skill should be used when the user asks to "analyze my mix", "find mix issues", "fix masking", "check frequency clashes", "improve dynamics", "check stereo width", "check headroom", or wants critic-driven mix analysis and evaluation. Provides the mix critic loop for iterative mix improvement.
+---
+
+# Mix Engine — Critic-Driven Mix Improvement
+
+The mix engine runs an iterative critic loop: analyze, plan, execute, measure, evaluate, keep or undo. Every mix change is measured before and after. Nothing stays unless it scores better than the original.
+
+## The Mix Critic Loop
+
+Follow these steps in order. Do not skip the evaluation step.
+
+### Step 1 — Analyze
+
+Call `analyze_mix` or `get_mix_issues` to build a MixState and run all critics against the current session. The response contains an `issues` array, each with a `critic`, `severity`, `track_index`, and `evidence` dict.
+
+If the M4L analyzer bridge is absent, critics fall back to role-based heuristics only (track names, device chains, volume/pan positions). Inform the user that spectral analysis is unavailable and recommendations are less precise.
+
+For detailed frequency collision data, call `get_masking_report`. For a quick status overview without the full critic pass, call `get_mix_summary`.
+
+### Step 2 — Plan
+
+Pick the highest-severity issue from the `issues` array. Call `plan_mix_move` with the issue data. The planner returns the smallest intervention that addresses the problem — a single parameter change, not a chain of edits.
+
+Read the `move` object: it contains `move_type`, `target_track`, `target_device`, `target_parameter`, `target_value`, and `rationale`. Consult the move vocabulary in `references/mix-moves.md` for parameter ranges.
+
+### Step 3 — Capture Before
+
+Take a measurement snapshot before executing anything:
+
+1. Call `get_master_spectrum` — save the 9-band spectral data (sub_low → air)
+2. Call `get_master_rms` — save the RMS and peak values
+
+Optionally call `get_mix_snapshot` if you need per-track volume/pan/send state for the evaluation.
+
+### Step 4 — Execute
+
+Execute the planned move. Use the appropriate tool for the move type:
+
+- `set_device_parameter` for EQ cuts/boosts, compressor thresholds, saturation drives
+- `set_track_volume` for gain staging
+- `set_track_pan` for stereo placement
+- `set_track_send` for bus routing levels
+- `toggle_device` for bypassing/enabling processors
+- `batch_set_parameters` when the move requires multiple related parameter changes on the same device
+
+Execute exactly one move. Do not chain multiple interventions before measuring.
+
+### Step 5 — Capture After
+
+Repeat the same measurements from Step 3:
+
+1. Call `get_master_spectrum` — save the post-change spectral data
+2. Call `get_master_rms` — save the post-change RMS and peak values
+
+### Step 6 — Evaluate
+
+Call `evaluate_mix_move` with the before and after snapshots:
+
+```
+evaluate_mix_move(
+  before_snapshot: { spectrum: [...], rms: float, peak: float },
+  after_snapshot:  { spectrum: [...], rms: float, peak: float },
+  targets: { ... },     # what the move aimed to improve
+  protect: { ... }      # what must not get worse
+)
+```
+
+Read the response: `keep_change` (bool), `score` (0.0-1.0), `improvements` (list), `regressions` (list), `explanation` (string).
+
+### Step 7 — Keep or Undo
+
+If `keep_change` is `false`, call `undo()` immediately. Tell the user what was tried and why it was reverted, citing the `regressions` list.
+
+If `keep_change` is `true`, report the improvement to the user with the score and explanation.
+
+### Step 8 — Learn (Optional)
+
+If the move scored above 0.7 and the user confirms satisfaction, call `memory_learn(name="...", type="mix_template", qualities={"summary": "..."}, payload={...})` to save the technique for future recall.
+
+### Step 9 — Repeat
+
+Return to Step 1 and re-analyze. The critic list updates after each change. Continue until no high-severity issues remain or the user says to stop.
+
+## Quick Mix Checks
+
+Not every request needs the full loop:
+
+- **"How's my mix?"** — Call `get_mix_summary` for a one-shot status report with no changes
+- **"What's clashing?"** — Call `get_masking_report` for detailed per-pair frequency collision data
+- **"What are the issues?"** — Call `get_mix_issues` for the critic list without executing any fixes
+
+## Critic Types
+
+Six critics run during analysis. See `references/mix-critics.md` for thresholds and evidence format:
+
+- **masking** — frequency collisions between overlapping tracks
+- **over_compressed** — excessive compression reducing dynamic range
+- **flat_dynamics** — insufficient volume variation across sections
+- **low_headroom** — master peak too close to 0 dBFS
+- **stereo_width** — mono collapse or excessive width on specific elements
+- **spectral_balance** — overall tonal balance skew (too bright, too dark, mid-heavy)
+
+## Move Vocabulary
+
+The planner draws from six move types. See `references/mix-moves.md` for parameter ranges:
+
+- **gain_staging** — volume adjustments to establish proper level hierarchy
+- **bus_compression** — glue compression on groups or master
+- **transient_shaping** — attack/sustain manipulation for punch or smoothness
+- **eq_cut** — subtractive EQ to clear masking or remove resonances
+- **eq_boost** — additive EQ to bring out character (use sparingly)
+- **pan_spread** — stereo placement adjustments for width and separation
+
+## Analyzer Dependency
+
+The mix engine works in two modes:
+
+- **Full mode** (M4L analyzer connected): spectral data, RMS, key detection available. Critics use measured evidence.
+- **Heuristic mode** (no analyzer): critics infer from track names, device chains, and parameter positions. Always inform the user: "Spectral analysis unavailable — recommendations are based on track structure and device settings only."
+
+Call `get_capability_state` to check which mode is active before starting the loop.
+
+## Extended Perception Toolkit
+
+Beyond `get_master_spectrum` / `get_master_rms` / `get_detected_key`, the analyzer domain exposes six more measurements that give finer evidence than the 9-band spectrum alone. Use them when the standard snapshot is too coarse for the move you are evaluating:
+
+- **`get_spectral_shape`** — centroid, spread, skewness, kurtosis, rolloff, flatness, crest. Use for *tonal balance* judgments ("is this bright?", "is the energy concentrated or spread?") that 9 discrete bands cannot describe.
+- **`get_mel_spectrum`** — perceptual mel-band energies. Use when an EQ move needs to be evaluated against how the change is *heard*, not against linear-frequency bin energies.
+- **`get_chroma`** — 12-bin pitch-class energy. Use to detect harmonic clashes or to confirm a key without trusting `get_detected_key` alone.
+- **`get_onsets`** — transient detection. Use for groove / rhythm evaluations where you need to know *when* hits land, not just how loud the average is.
+- **`get_novelty`** — spectral change score with boundary flag. Use to confirm an arrangement boundary actually creates a perceived event, or to detect static sections that need disruption.
+- **`get_momentary_loudness`** — momentary LUFS + true-peak dBTP. Use during mastering moves where peak/RMS is insufficient and EBU R128 is the gauge.
+
+All six are bridge-dependent — they return helpful errors if the analyzer is not on master. They do not replace the before/after snapshot pattern; they enrich what "snapshot" means when the move warrants it.