livepilot 1.10.5 → 1.10.7

package/mcp_server/tools/_agent_os_engine/critics.py

@@ -0,0 +1,158 @@
+"""Part of the _agent_os_engine package — extracted from the single-file engine.
+
+Pure-computation core. Callers should import from the package facade
+(`from mcp_server.tools._agent_os_engine import X`), which re-exports from
+these sub-modules.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Optional
+
+from .models import Issue, GoalVector, WorldModel, MEASURABLE_PROXIES
+
+def run_sonic_critic(
+    sonic: Optional[dict],
+    goal: GoalVector,
+    track_roles: dict,
+) -> list[Issue]:
+    """Run sonic heuristics against spectrum data. Returns issues that overlap
+    with the goal's target dimensions."""
+    if sonic is None:
+        return [Issue(
+            type="analyzer_unavailable",
+            critic="sonic",
+            severity=0.3,
+            confidence=1.0,
+            affected_dimensions=list(MEASURABLE_PROXIES.keys()),
+            evidence=["M4L Analyzer not connected or no audio playing"],
+            recommended_actions=["Load LivePilot_Analyzer on master", "Start playback"],
+        )]
+
+    issues = []
+    bands = sonic.get("spectrum", {})
+    rms = sonic.get("rms")
+    peak = sonic.get("peak")
+    target_dims = set(goal.targets.keys())
+
+    # BUG-B42: if every spectrum band is zero AND rms is zero, playback
+    # is stopped (or nothing is routing to master). Spectrum-based
+    # critics (weak_foundation, harsh_highs, low_mid_congestion, etc.)
+    # would fire on zero data, reporting "no bass!" when the real cause
+    # is "no audio". Short-circuit to a playback_required advisory so
+    # callers don't chase phantom mix issues during static inspection.
+    _all_bands = all(float(bands.get(b, 0) or 0) == 0 for b in
+                     ("sub", "low", "low_mid", "mid", "high_mid", "high",
+                      "presence", "air"))
+    _silent = _all_bands and (rms is None or float(rms or 0) == 0)
+    if _silent:
+        return [Issue(
+            type="playback_required",
+            critic="sonic",
+            severity=0.1,
+            confidence=1.0,
+            affected_dimensions=list(MEASURABLE_PROXIES.keys()),
+            evidence=["spectrum and RMS both zero — playback stopped or no signal"],
+            recommended_actions=[
+                "Start playback before calling build_world_model / "
+                "analyze_mix so spectrum-based critics can evaluate.",
+            ],
+        )]
+
+    # 1. Mud detection: low_mid congestion
+    low_mid = bands.get("low_mid", 0)
+    if low_mid > 0.7 and {"clarity", "weight", "warmth"} & target_dims:
+        issues.append(Issue(
+            type="low_mid_congestion",
+            critic="sonic",
+            severity=min(1.0, (low_mid - 0.7) * 3.3),
+            confidence=0.85,
+            affected_dimensions=["clarity", "weight"],
+            evidence=[f"low_mid band energy: {low_mid:.2f} (threshold: 0.7)"],
+            recommended_actions=["EQ cut 200-500Hz on muddiest track", "HPF on non-bass elements"],
+        ))
+
+    # 2. Weak sub
+    sub = bands.get("sub", 0)
+    has_bass = any(r in ("kick", "bass", "sub_bass") for r in track_roles.values())
+    if sub < 0.15 and has_bass and {"weight", "energy", "punch"} & target_dims:
+        issues.append(Issue(
+            type="weak_foundation",
+            critic="sonic",
+            severity=0.6,
+            confidence=0.75,
+            affected_dimensions=["weight", "energy"],
+            evidence=[f"sub band energy: {sub:.2f} with bass tracks present"],
+            recommended_actions=["Boost sub on kick/bass", "Check HPF not too aggressive"],
+        ))
+
+    # 3. Harsh top
+    high = bands.get("high", 0)
+    presence = bands.get("presence", 0)
+    if (high + presence) > 0.8 and {"brightness", "clarity", "warmth"} & target_dims:
+        issues.append(Issue(
+            type="harsh_highs",
+            critic="sonic",
+            severity=min(1.0, ((high + presence) - 0.8) * 2.5),
+            confidence=0.80,
+            affected_dimensions=["brightness", "clarity"],
+            evidence=[f"high+presence: {high + presence:.2f} (threshold: 0.8)"],
+            recommended_actions=["Reduce high shelf on brightest element", "Add subtle LP filter"],
+        ))
+
+    # 4. Low headroom
+    if rms is not None and rms > 0.9 and {"energy", "punch", "clarity"} & target_dims:
+        issues.append(Issue(
+            type="headroom_risk",
+            critic="sonic",
+            severity=min(1.0, (rms - 0.9) * 10),
+            confidence=0.90,
+            affected_dimensions=["energy", "clarity", "punch"],
+            evidence=[f"RMS: {rms:.3f} (threshold: 0.9)"],
+            recommended_actions=["Reduce master volume", "Lower loudest track", "Add limiter"],
+        ))
+
+    # 5. Flat dynamics (C1 fix: correct dB formula)
+    if rms is not None and peak is not None and rms > 0 and peak > 0:
+        crest_db = 20.0 * math.log10(peak / max(rms, 0.001))
+        if crest_db < 3.0 and {"punch", "energy", "contrast"} & target_dims:
+            issues.append(Issue(
+                type="dynamics_flat",
+                critic="sonic",
+                severity=0.5,
+                confidence=0.70,
+                affected_dimensions=["punch", "contrast"],
+                evidence=[f"crest factor: {crest_db:.1f} dB (threshold: 3 dB)"],
+                recommended_actions=["Reduce compression", "Add transient shaper", "Reduce limiter"],
+            ))
+
+    return issues
+
+def run_technical_critic(technical: dict) -> list[Issue]:
+    """Check technical health of the session."""
+    issues = []
+
+    if not technical.get("analyzer_available", False):
+        issues.append(Issue(
+            type="analyzer_offline",
+            critic="technical",
+            severity=0.4,
+            confidence=1.0,
+            evidence=["LivePilot Analyzer not receiving data"],
+            recommended_actions=["Load LivePilot_Analyzer.amxd on master track"],
+        ))
+
+    for dev in technical.get("unhealthy_devices", []):
+        issues.append(Issue(
+            type="unhealthy_plugin",
+            critic="technical",
+            severity=0.7,
+            confidence=0.95,
+            evidence=[f"Track {dev['track']}: {dev['device']} — {dev['flag']}"],
+            recommended_actions=["Delete and replace with native Ableton device"],
+        ))
+
+    return issues
+

package/mcp_server/tools/_agent_os_engine/evaluation.py

@@ -0,0 +1,206 @@
+"""Part of the _agent_os_engine package — extracted from the single-file engine.
+
+Pure-computation core. Callers should import from the package facade
+(`from mcp_server.tools._agent_os_engine import X`), which re-exports from
+these sub-modules.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Optional
+
+from .models import QUALITY_DIMENSIONS, GoalVector, WorldModel, _clamp
+from .taste import compute_taste_fit
+
+
+# ── Evaluation Engine ─────────────────────────────────────────────────
+# _clamp lives in .models — shared with taste.py to avoid circular imports.
+
+def _extract_dimension_value(
+    sonic: dict,
+    dimension: str,
+) -> Optional[float]:
+    """Map a quality dimension to a measurable value from sonic data.
+
+    Returns None for unmeasurable dimensions (confidence=0.0 in Phase 1).
+    All returned values are clamped to 0.0-1.0 for consistent scoring.
+    """
+    if not sonic:
+        return None
+    # Accept both "spectrum" and "bands" keys — get_master_spectrum returns
+    # {"bands": {...}} while the evaluator historically expected {"spectrum": {...}}.
+    # Finding 2 fix: tolerate either shape so raw analyzer output works.
+    bands = sonic.get("spectrum") or sonic.get("bands")
+    if not bands:
+        return None
+    rms = sonic.get("rms")
+    peak = sonic.get("peak")
+
+    if dimension == "brightness":
+        high = bands.get("high", 0)
+        presence = bands.get("presence", 0)
+        return _clamp((high + presence) / 2.0)
+    elif dimension == "warmth":
+        return _clamp(bands.get("low_mid", 0))
+    elif dimension == "weight":
+        sub = bands.get("sub", 0)
+        low = bands.get("low", 0)
+        return _clamp((sub + low) / 2.0)
+    elif dimension == "clarity":
+        low_mid = bands.get("low_mid", 0)
+        return _clamp(1.0 - low_mid)
+    elif dimension == "density":
+        # Spectral flatness: geometric mean / arithmetic mean of band values.
+        # Higher = more evenly distributed energy (noise-like).
+        # Lower = more tonal (energy concentrated in few bands).
+        vals = [max(v, 1e-10) for v in bands.values() if isinstance(v, (int, float))]
+        if not vals:
+            return None
+        geo_mean = math.exp(sum(math.log(v) for v in vals) / len(vals))
+        arith_mean = sum(vals) / len(vals)
+        return _clamp(geo_mean / max(arith_mean, 1e-10))
+    elif dimension == "energy":
+        return _clamp(rms) if rms is not None else None
+    elif dimension == "punch":
+        if rms and peak and rms > 0:
+            crest_db = 20.0 * math.log10(max(peak / rms, 1.0))
+            # Normalize: 0 dB = 0.0, 20 dB = 1.0
+            return _clamp(crest_db / 20.0)
+        return None
+    else:
+        # Unmeasurable in Phase 1 (width, depth, motion, contrast,
+        # groove, tension, novelty, polish, emotion, cohesion)
+        return None
+
+def compute_evaluation_score(
+    goal: GoalVector,
+    before_sonic: dict,
+    after_sonic: dict,
+    outcome_history: Optional[list[dict]] = None,
+) -> dict:
+    """Compute whether a move improved the mix toward the goal.
+
+    Returns:
+        {
+            "score": float (0-1),
+            "keep_change": bool,
+            "goal_progress": float (-1 to 1),
+            "collateral_damage": float (0-1),
+            "measurable_delta": float (-1 to 1),
+            "notes": list[str],
+            "dimension_changes": dict,
+            "consecutive_undo_hint": bool,
+        }
+    """
+    notes: list[str] = []
+    dimension_changes: dict[str, dict] = {}
+
+    # Compute per-dimension deltas
+    total_goal_progress = 0.0
+    measurable_count = 0
+
+    for dim, weight in goal.targets.items():
+        before_val = _extract_dimension_value(before_sonic, dim)
+        after_val = _extract_dimension_value(after_sonic, dim)
+
+        if before_val is not None and after_val is not None:
+            delta = after_val - before_val
+            dimension_changes[dim] = {
+                "before": round(before_val, 4),
+                "after": round(after_val, 4),
+                "delta": round(delta, 4),
+            }
+            total_goal_progress += delta * weight
+            measurable_count += 1
+        else:
+            notes.append(f"{dim}: not measurable in Phase 1 (confidence=0.0)")
+
+    # Check protected dimensions (C3 fix: use the actual threshold)
+    collateral_damage = 0.0
+    protection_violated = False
+
+    for dim, threshold in goal.protect.items():
+        before_val = _extract_dimension_value(before_sonic, dim)
+        after_val = _extract_dimension_value(after_sonic, dim)
+
+        if before_val is not None and after_val is not None:
+            drop = before_val - after_val
+            if drop > 0:
+                collateral_damage = max(collateral_damage, drop)
+            # Violation: value dropped below the user's threshold
+            if after_val < threshold:
+                protection_violated = True
+                notes.append(
+                    f"PROTECTED dimension '{dim}' at {after_val:.3f}, "
+                    f"below threshold {threshold:.3f}"
+                )
+            # Also flag large drops even if still above threshold
+            elif drop > 0.15:
+                protection_violated = True
+                notes.append(
+                    f"PROTECTED dimension '{dim}' dropped by {drop:.3f} "
+                    f"(absolute drop > 0.15)"
+                )
+
+    # Measurable delta (average improvement across measured dimensions)
+    measurable_delta = total_goal_progress / max(measurable_count, 1)
+
+    # Taste fit: how well does this move align with user preferences?
+    taste_fit = compute_taste_fit(goal, outcome_history) if outcome_history else 0.0
+
+    # Compute composite score (spec section 12.2)
+    goal_fit = _clamp(0.5 + total_goal_progress)
+    measurable_component = _clamp(0.5 + measurable_delta)
+    preservation = _clamp(1.0 - collateral_damage * 5)
+    confidence = measurable_count / max(len(goal.targets), 1)
+
+    score = (
+        0.30 * goal_fit
+        + 0.25 * measurable_component
+        + 0.15 * preservation
+        + 0.10 * taste_fit
+        + 0.10 * confidence
+        + 0.10 * 1.0   # reversibility: 1.0 for undo-able moves
+    )
+
+    # Hard rules
+    keep_change = True
+
+    if measurable_count > 0 and measurable_delta <= 0:
+        keep_change = False
+        notes.append("HARD RULE: measurable delta <= 0 — no measurable improvement")
+
+    if protection_violated:
+        keep_change = False
+        notes.append("HARD RULE: protected dimension violated")
+
+    if score < 0.40:
+        keep_change = False
+        notes.append(f"HARD RULE: total score {score:.3f} < 0.40 threshold")
+
+    if measurable_count == 0 and not protection_violated:
+        # All TARGET dimensions unmeasurable AND no protection violations —
+        # defer keep/undo to the agent's musical judgment.
+        # IMPORTANT: protection violations still force undo even when
+        # targets are unmeasurable (Finding 1 fix).
+        keep_change = True
+        notes.append(
+            "No measurable target dimensions — deferring keep/undo to agent musical judgment"
+        )
+
+    return {
+        "score": round(score, 4),
+        "keep_change": keep_change,
+        "goal_progress": round(total_goal_progress, 4),
+        "collateral_damage": round(collateral_damage, 4),
+        "measurable_delta": round(measurable_delta, 4),
+        "measurable_dimensions": measurable_count,
+        "total_dimensions": len(goal.targets),
+        "dimension_changes": dimension_changes,
+        "notes": notes,
+        # I5: hint for the agent to track consecutive undos
+        "consecutive_undo_hint": not keep_change,
+    }
+

package/mcp_server/tools/_agent_os_engine/models.py

@@ -0,0 +1,132 @@
+"""Part of the _agent_os_engine package — extracted from the single-file engine.
+
+Pure-computation core. Callers should import from the package facade
+(`from mcp_server.tools._agent_os_engine import X`), which re-exports from
+these sub-modules.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Optional
+
+
+# ── Shared utility ────────────────────────────────────────────────────
+def _clamp(value: float, lo: float = 0.0, hi: float = 1.0) -> float:
+    """Clamp value to [lo, hi] range. Shared across evaluation + taste."""
+    return max(lo, min(hi, value))
+
+
+# ── Quality Dimensions ────────────────────────────────────────────────
+QUALITY_DIMENSIONS = frozenset({
+    "energy", "punch", "weight", "density", "brightness", "warmth",
+    "width", "depth", "motion", "contrast", "clarity", "cohesion",
+    "groove", "tension", "novelty", "polish", "emotion",
+})
+
+MEASURABLE_PROXIES: dict[str, str] = {
+    "brightness": "high + presence bands (averaged)",
+    "warmth": "low_mid band energy",
+    "weight": "sub + low bands (averaged)",
+    "clarity": "inverse of low_mid congestion",
+    "density": "spectral flatness (geometric/arithmetic mean ratio)",
+    "energy": "RMS level",
+    "punch": "crest factor in dB (20*log10(peak/rms))",
+}
+
+VALID_MODES = frozenset({"observe", "improve", "explore", "finish", "diagnose"})
+
+VALID_RESEARCH_MODES = frozenset({"none", "targeted", "deep"})
+
+
+# ── GoalVector ────────────────────────────────────────────────────────
+@dataclass
+class GoalVector:
+    """Compiled user intent as a machine-usable goal.
+
+    targets: dimension → weight (0-1). Weights should approximately sum to 1.0.
+    protect: dimension → minimum acceptable value (0-1). If a dimension drops
+             below this value after a move, the move is undone.
+    """
+    request_text: str
+    targets: dict[str, float] = field(default_factory=dict)
+    protect: dict[str, float] = field(default_factory=dict)
+    mode: str = "improve"
+    aggression: float = 0.5
+    research_mode: str = "none"
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+_ROLE_PATTERNS: list[tuple[str, str]] = [
+    (r"kick|bd|bass\s*drum", "kick"),
+    (r"snare|sd|snr", "snare"),
+    (r"clap|cp|hand\s*clap", "clap"),
+    (r"h(?:i)?[\s\-]?hat|hh|hat", "hihat"),
+    (r"perc|percussion|conga|bongo|shaker|tamb", "percussion"),
+    (r"sub\s*bass|sub", "sub_bass"),
+    (r"bass|low", "bass"),
+    (r"pad|atmosphere|atmo|ambient|drone", "pad"),
+    (r"lead|melody|mel|synth\s*lead", "lead"),
+    (r"chord|keys|piano|organ|rhodes", "chords"),
+    (r"vocal|vox|voice", "vocal"),
+    (r"fx|sfx|riser|sweep|noise|texture|tape", "texture"),
+    (r"string", "strings"),
+    (r"brass", "brass"),
+    (r"resamp|bounce|bus|group|master", "utility"),
+]
+
+@dataclass
+class WorldModel:
+    """Session state snapshot for critic analysis."""
+    topology: dict = field(default_factory=dict)
+    sonic: Optional[dict] = None
+    technical: dict = field(default_factory=dict)
+    track_roles: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Critics ───────────────────────────────────────────────────────────
+@dataclass
+class Issue:
+    """A diagnosed problem or opportunity."""
+    type: str
+    critic: str  # "sonic" or "technical"
+    severity: float  # 0.0-1.0
+    confidence: float  # 0.0-1.0
+    affected_dimensions: list[str] = field(default_factory=list)
+    evidence: list[str] = field(default_factory=list)
+    recommended_actions: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Technique Cards (Round 2) ─────────────────────────────────────────
+@dataclass
+class TechniqueCard:
+    """A structured, reusable production recipe — not just text."""
+    problem: str
+    context: list[str] = field(default_factory=list)  # genre/style tags
+    devices: list[str] = field(default_factory=list)  # what to load
+    method: str = ""  # step-by-step instructions
+    verification: list[str] = field(default_factory=list)  # what to check after
+    evidence: dict = field(default_factory=dict)  # {sources, in_session_tested}
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def to_memory_payload(self) -> dict:
+        """Convert to a payload suitable for memory_learn(type='technique_card')."""
+        return {
+            "problem": self.problem,
+            "context": self.context,
+            "devices": self.devices,
+            "method": self.method,
+            "verification": self.verification,
+            "evidence": self.evidence,
+        }
+

package/mcp_server/tools/_agent_os_engine/taste.py

@@ -0,0 +1,192 @@
+"""Part of the _agent_os_engine package — extracted from the single-file engine.
+
+Pure-computation core. Callers should import from the package facade
+(`from mcp_server.tools._agent_os_engine import X`), which re-exports from
+these sub-modules.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Optional
+
+from .models import QUALITY_DIMENSIONS, _clamp
+
+
+# ── Outcome Memory Analysis (Round 1) ────────────────────────────────
+def analyze_outcome_history(outcomes: list[dict]) -> dict:
+    """Analyze accumulated outcome memories to identify user taste patterns.
+
+    outcomes: list of outcome technique payloads from memory_list(type="outcome")
+    Returns taste analysis: keep rate, dimension success, inferred preferences.
+    """
+    if not outcomes:
+        return {
+            "total_outcomes": 0,
+            "keep_rate": 0.0,
+            "dimension_success": {},
+            "common_kept_moves": [],
+            "common_undone_moves": [],
+            "taste_vector": {},
+            "notes": ["No outcome history — use the evaluation loop to build taste data"],
+        }
+
+    total = len(outcomes)
+    kept = [o for o in outcomes if o.get("kept", False)]
+    undone = [o for o in outcomes if not o.get("kept", False)]
+    keep_rate = len(kept) / total
+
+    # Dimension success: average improvement per dimension when kept
+    dimension_success: dict[str, list[float]] = {}
+    for o in kept:
+        for dim, change in o.get("dimension_changes", {}).items():
+            delta = change.get("delta", 0) if isinstance(change, dict) else 0
+            dimension_success.setdefault(dim, []).append(delta)
+
+    avg_dimension_success = {
+        dim: round(sum(vals) / len(vals), 4)
+        for dim, vals in dimension_success.items()
+        if vals
+    }
+
+    # Common move types
+    kept_moves = {}
+    undone_moves = {}
+    for o in kept:
+        move_name = o.get("move", {}).get("name", "unknown") if isinstance(o.get("move"), dict) else "unknown"
+        kept_moves[move_name] = kept_moves.get(move_name, 0) + 1
+    for o in undone:
+        move_name = o.get("move", {}).get("name", "unknown") if isinstance(o.get("move"), dict) else "unknown"
+        undone_moves[move_name] = undone_moves.get(move_name, 0) + 1
+
+    common_kept = sorted(kept_moves.items(), key=lambda x: -x[1])[:5]
+    common_undone = sorted(undone_moves.items(), key=lambda x: -x[1])[:5]
+
+    # Taste vector: which dimensions does this user care about?
+    # Weight by how often each dimension appears in kept outcomes
+    taste_vector: dict[str, float] = {}
+    for o in kept:
+        gv = o.get("goal_vector", {})
+        targets = gv.get("targets", {}) if isinstance(gv, dict) else {}
+        for dim, weight in targets.items():
+            taste_vector[dim] = taste_vector.get(dim, 0) + weight
+
+    # Normalize
+    taste_total = sum(taste_vector.values())
+    if taste_total > 0:
+        taste_vector = {k: round(v / taste_total, 3) for k, v in taste_vector.items()}
+
+    notes = []
+    if keep_rate < 0.3:
+        notes.append(f"Low keep rate ({keep_rate:.0%}) — agent may be too aggressive")
+    if keep_rate > 0.8:
+        notes.append(f"High keep rate ({keep_rate:.0%}) — agent is well-calibrated or too conservative")
+
+    return {
+        "total_outcomes": total,
+        "kept": len(kept),
+        "undone": len(undone),
+        "keep_rate": round(keep_rate, 3),
+        "dimension_success": avg_dimension_success,
+        "common_kept_moves": [{"move": m, "count": c} for m, c in common_kept],
+        "common_undone_moves": [{"move": m, "count": c} for m, c in common_undone],
+        "taste_vector": taste_vector,
+        "notes": notes,
+    }
+
+
+# ── Taste Model (Round 4) ────────────────────────────────────────────
+def compute_taste_fit(
+    goal: GoalVector,
+    outcome_history: Optional[list[dict]] = None,
+) -> float:
+    """Compute how well a goal aligns with the user's accumulated taste preferences.
+
+    Analyzes outcome history to build a taste vector (which dimensions matter
+    most to this user), then scores the current goal's alignment.
+
+    Returns 0.0-1.0 where:
+    - 0.0 = no data or goal doesn't match taste
+    - 1.0 = goal perfectly aligns with user's demonstrated preferences
+    """
+    if not outcome_history:
+        return 0.0
+
+    # Build taste vector from kept outcomes
+    taste_vector: dict[str, float] = {}
+    total_kept = 0
+
+    for o in outcome_history:
+        if not o.get("kept", False):
+            continue
+        total_kept += 1
+        gv = o.get("goal_vector", {})
+        targets = gv.get("targets", {}) if isinstance(gv, dict) else {}
+        for dim, weight in targets.items():
+            taste_vector[dim] = taste_vector.get(dim, 0) + weight
+
+    if not taste_vector or total_kept == 0:
+        return 0.0
+
+    # Normalize taste vector
+    taste_total = sum(taste_vector.values())
+    if taste_total > 0:
+        taste_vector = {k: v / taste_total for k, v in taste_vector.items()}
+
+    # Score: how much does the current goal overlap with taste preferences?
+    # Dot product of normalized goal weights and taste weights
+    goal_targets = goal.targets
+    if not goal_targets:
+        return 0.0
+
+    goal_total = sum(goal_targets.values())
+    if goal_total <= 0:
+        return 0.0
+
+    overlap = 0.0
+    for dim, weight in goal_targets.items():
+        normalized_weight = weight / goal_total
+        taste_weight = taste_vector.get(dim, 0)
+        overlap += normalized_weight * taste_weight
+
+    # Scale: overlap is typically small (product of two normalized distributions)
+    # Amplify so that moderate overlap gives a meaningful score
+    return _clamp(overlap * 4.0)
+
+def get_taste_profile(outcome_history: list[dict]) -> dict:
+    """Build a full taste profile from outcome history.
+
+    Returns: {taste_vector, preferred_dimensions, avoided_dimensions,
+              keep_rate, sample_size}
+    """
+    analysis = analyze_outcome_history(outcome_history)
+    taste_vector = analysis.get("taste_vector", {})
+
+    # Identify preferred and avoided dimensions
+    preferred = sorted(taste_vector.items(), key=lambda x: -x[1])[:5]
+    avoided_dims: dict[str, float] = {}
+    for o in outcome_history:
+        if o.get("kept", False):
+            continue  # Only look at undone moves
+        gv = o.get("goal_vector", {})
+        targets = gv.get("targets", {}) if isinstance(gv, dict) else {}
+        for dim, weight in targets.items():
+            avoided_dims[dim] = avoided_dims.get(dim, 0) + weight
+
+    if avoided_dims:
+        avoid_total = sum(avoided_dims.values())
+        if avoid_total > 0:
+            avoided_dims = {k: v / avoid_total for k, v in avoided_dims.items()}
+
+    avoided = sorted(avoided_dims.items(), key=lambda x: -x[1])[:5]
+
+    return {
+        "taste_vector": taste_vector,
+        "preferred_dimensions": [{"dim": d, "weight": round(w, 3)} for d, w in preferred],
+        "avoided_dimensions": [{"dim": d, "weight": round(w, 3)} for d, w in avoided],
+        "keep_rate": analysis.get("keep_rate", 0),
+        "sample_size": analysis.get("total_outcomes", 0),
+        "notes": analysis.get("notes", []),
+    }
+