feat: Added Partners, Backgrounds, and related variation selections to commander building.

code/deck_builder/suggestions.py

@@ -0,0 +1,662 @@
+"""Partner suggestion scoring helpers.
+
+This module provides a scoring helper that ranks potential partner/background
+pairings for a selected primary commander. It consumes the normalized metadata
+emitted by ``build_partner_suggestions.py`` (themes, role tags, partner flags,
+and pairing telemetry) and blends several weighted components:
+
+* Shared theme overlap (normalized Jaccard/role-aware) – baseline synergy.
+* Theme adjacency (deck export co-occurrence + curated overrides).
+* Color compatibility (prefers compact color changes).
+* Mechanic affinity (Partner With, Doctor/Companion, Background matches).
+* Penalties (illegal configurations, missing tags, restricted conflicts).
+
+Weights are mode-specific so future tuning can adjust emphasis without
+rewriting the algorithm. The public ``score_partner_candidate`` helper returns
+both the aggregate score and a component breakdown for diagnostics.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Dict, Iterable, Mapping, MutableMapping, Sequence
+
+from .combined_commander import PartnerMode
+
+__all__ = [
+    "PartnerSuggestionContext",
+    "ScoreWeights",
+    "ScoreResult",
+    "MODE_WEIGHTS",
+    "score_partner_candidate",
+    "is_noise_theme",
+]
+
+
+def _clean_str(value: object) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _normalize_token(value: str | None) -> str:
+    return _clean_str(value).casefold()
+
+
+def _commander_name(payload: Mapping[str, object]) -> str:
+    name = _clean_str(payload.get("display_name")) or _clean_str(payload.get("name"))
+    return name or "Unknown Commander"
+
+
+def _commander_key(payload: Mapping[str, object]) -> str:
+    return _normalize_token(_commander_name(payload))
+
+
+def _sequence(payload: Mapping[str, object], key: str) -> tuple[str, ...]:
+    raw = payload.get(key)
+    if raw is None:
+        return tuple()
+    if isinstance(raw, (list, tuple)):
+        return tuple(_clean_str(item) for item in raw if _clean_str(item))
+    return tuple(filter(None, (_clean_str(raw),)))
+
+
+_EXCLUDED_THEME_TOKENS = {
+    "legends matter",
+    "historics matter",
+    "partner",
+    "partner - survivors",
+}
+
+
+def _theme_should_be_excluded(theme: str) -> bool:
+    token = _normalize_token(theme)
+    if not token:
+        return False
+    if token in _EXCLUDED_THEME_TOKENS:
+        return True
+    return "kindred" in token
+
+
+def is_noise_theme(theme: str | None) -> bool:
+    """Return True when the provided theme is considered too generic/noisy.
+
+    The partner suggestion UI should suppress these themes from overlap summaries to
+    keep recommendations focused on distinctive archetypes.
+    """
+
+    if theme is None:
+        return False
+    return _theme_should_be_excluded(theme)
+
+
+def _theme_sequence(payload: Mapping[str, object], key: str = "themes") -> tuple[str, ...]:
+    return tuple(
+        theme
+        for theme in _sequence(payload, key)
+        if not _theme_should_be_excluded(theme)
+    )
+
+
+def _normalize_string_set(values: Iterable[str]) -> tuple[str, ...]:
+    seen: set[str] = set()
+    collected: list[str] = []
+    for value in values:
+        token = _clean_str(value)
+        if not token:
+            continue
+        key = token.casefold()
+        if key in seen:
+            continue
+        seen.add(key)
+        collected.append(token)
+    return tuple(collected)
+
+
+@dataclass(frozen=True)
+class ScoreWeights:
+    """Weight multipliers for each scoring component."""
+
+    overlap: float
+    synergy: float
+    color: float
+    affinity: float
+    penalty: float
+
+
+@dataclass(frozen=True)
+class ScoreResult:
+    """Result returned by :func:`score_partner_candidate`."""
+
+    score: float
+    mode: PartnerMode
+    components: Mapping[str, float]
+    notes: tuple[str, ...]
+    weights: ScoreWeights
+
+
+class PartnerSuggestionContext:
+    """Container for suggestion dataset fragments used during scoring."""
+
+    def __init__(
+        self,
+        *,
+        theme_cooccurrence: Mapping[str, Mapping[str, int]] | None = None,
+        pairing_counts: Mapping[tuple[str, str, str], int] | None = None,
+        curated_synergy: Mapping[tuple[str, str], float] | None = None,
+    ) -> None:
+        self._theme_cooccurrence: Dict[str, Dict[str, float]] = {}
+        self._pairing_counts: Dict[tuple[str, str, str], float] = {}
+        self._curated_synergy: Dict[tuple[str, str], float] = {}
+
+        max_co = 0
+        if theme_cooccurrence:
+            for theme, neighbors in theme_cooccurrence.items():
+                theme_key = _normalize_token(theme)
+                if not theme_key:
+                    continue
+                store: Dict[str, float] = {}
+                for other, count in neighbors.items():
+                    other_key = _normalize_token(other)
+                    if not other_key:
+                        continue
+                    value = float(count or 0)
+                    if value <= 0:
+                        continue
+                    store[other_key] = value
+                    max_co = max(max_co, value)
+                if store:
+                    self._theme_cooccurrence[theme_key] = store
+        self._theme_co_max = max(max_co, 1.0)
+
+        max_pair = 0
+        if pairing_counts:
+            for key, count in pairing_counts.items():
+                if not isinstance(key, tuple) or len(key) != 3:
+                    continue
+                mode, primary, secondary = key
+                norm_key = (
+                    _normalize_token(mode),
+                    _normalize_token(primary),
+                    _normalize_token(secondary),
+                )
+                value = float(count or 0)
+                if value <= 0:
+                    continue
+                self._pairing_counts[norm_key] = value
+                # Store symmetric entry to simplify lookups.
+                symmetric = (
+                    _normalize_token(mode),
+                    _normalize_token(secondary),
+                    _normalize_token(primary),
+                )
+                self._pairing_counts[symmetric] = value
+                max_pair = max(max_pair, value)
+        self._pairing_max = max(max_pair, 1.0)
+
+        if curated_synergy:
+            for key, value in curated_synergy.items():
+                if not isinstance(key, tuple) or len(key) != 2:
+                    continue
+                primary, secondary = key
+                normalized = (
+                    _normalize_token(primary),
+                    _normalize_token(secondary),
+                )
+                if value is None:
+                    continue
+                magnitude = max(0.0, float(value))
+                if magnitude <= 0:
+                    continue
+                self._curated_synergy[normalized] = min(1.0, magnitude)
+                self._curated_synergy[(normalized[1], normalized[0])] = min(1.0, magnitude)
+
+    @classmethod
+    def from_dataset(cls, payload: Mapping[str, object] | None) -> "PartnerSuggestionContext":
+        if not payload:
+            return cls()
+
+        themes_raw = payload.get("themes")
+        theme_cooccurrence: Dict[str, Dict[str, int]] = {}
+        if isinstance(themes_raw, Mapping):
+            for theme_key, entry in themes_raw.items():
+                co = entry.get("co_occurrence") if isinstance(entry, Mapping) else None
+                if not isinstance(co, Mapping):
+                    continue
+                inner: Dict[str, int] = {}
+                for other, info in co.items():
+                    if isinstance(info, Mapping):
+                        count = info.get("count")
+                    else:
+                        count = info
+                    try:
+                        inner[str(other)] = int(count)
+                    except Exception:
+                        continue
+                theme_cooccurrence[str(theme_key)] = inner
+
+        pairings = payload.get("pairings")
+        pairing_counts: Dict[tuple[str, str, str], int] = {}
+        if isinstance(pairings, Mapping):
+            records = pairings.get("records")
+            if isinstance(records, Sequence):
+                for entry in records:
+                    if not isinstance(entry, Mapping):
+                        continue
+                    mode = str(entry.get("mode", "unknown"))
+                    primary = str(entry.get("primary_canonical") or entry.get("primary") or "")
+                    secondary = str(entry.get("secondary_canonical") or entry.get("secondary") or "")
+                    if not primary or not secondary:
+                        continue
+                    try:
+                        count = int(entry.get("count", 0))
+                    except Exception:
+                        continue
+                    pairing_counts[(mode, primary, secondary)] = count
+
+        curated = payload.get("curated_overrides")
+        curated_synergy: Dict[tuple[str, str], float] = {}
+        if isinstance(curated, Mapping):
+            entries = curated.get("entries")
+            if isinstance(entries, Mapping):
+                for raw_key, raw_value in entries.items():
+                    if not isinstance(raw_key, str):
+                        continue
+                    parts = [part.strip() for part in raw_key.split("::") if part.strip()]
+                    if len(parts) != 2:
+                        continue
+                    try:
+                        magnitude = float(raw_value)
+                    except Exception:
+                        continue
+                    curated_synergy[(parts[0], parts[1])] = magnitude
+
+        return cls(
+            theme_cooccurrence=theme_cooccurrence,
+            pairing_counts=pairing_counts,
+            curated_synergy=curated_synergy,
+        )
+
+    @lru_cache(maxsize=256)
+    def theme_synergy(self, theme_a: str, theme_b: str) -> float:
+        key_a = _normalize_token(theme_a)
+        key_b = _normalize_token(theme_b)
+        if not key_a or not key_b or key_a == key_b:
+            return 0.0
+        co = self._theme_cooccurrence.get(key_a, {})
+        value = co.get(key_b, 0.0)
+        normalized = value / self._theme_co_max
+        curated = self._curated_synergy.get((key_a, key_b), 0.0)
+        return max(0.0, min(1.0, max(normalized, curated)))
+
+    @lru_cache(maxsize=128)
+    def pairing_strength(self, mode: PartnerMode, primary: str, secondary: str) -> float:
+        key = (
+            mode.value,
+            _normalize_token(primary),
+            _normalize_token(secondary),
+        )
+        value = self._pairing_counts.get(key, 0.0)
+        return max(0.0, min(1.0, value / self._pairing_max))
+
+
+DEFAULT_WEIGHTS = ScoreWeights(
+    overlap=0.45,
+    synergy=0.25,
+    color=0.15,
+    affinity=0.10,
+    penalty=0.20,
+)
+
+
+MODE_WEIGHTS: Mapping[PartnerMode, ScoreWeights] = {
+    PartnerMode.PARTNER: DEFAULT_WEIGHTS,
+    PartnerMode.PARTNER_WITH: ScoreWeights(overlap=0.40, synergy=0.20, color=0.10, affinity=0.20, penalty=0.25),
+    PartnerMode.BACKGROUND: ScoreWeights(overlap=0.50, synergy=0.30, color=0.10, affinity=0.10, penalty=0.25),
+    PartnerMode.DOCTOR_COMPANION: ScoreWeights(overlap=0.30, synergy=0.20, color=0.10, affinity=0.30, penalty=0.25),
+    PartnerMode.NONE: DEFAULT_WEIGHTS,
+}
+
+
+def _clamp(value: float, minimum: float = 0.0, maximum: float = 1.0) -> float:
+    if value < minimum:
+        return minimum
+    if value > maximum:
+        return maximum
+    return value
+
+
+def score_partner_candidate(
+    primary: Mapping[str, object],
+    candidate: Mapping[str, object],
+    *,
+    mode: PartnerMode | str | None = None,
+    context: PartnerSuggestionContext | None = None,
+) -> ScoreResult:
+    """Score a partner/background candidate for the provided primary.
+
+    Args:
+        primary: Commander metadata dictionary (as produced by the dataset).
+        candidate: Potential partner/background metadata dictionary.
+        mode: Desired partner mode (auto-detected when omitted).
+        context: Optional suggestion context providing theme/pairing statistics.
+
+    Returns:
+        ScoreResult with aggregate score ``0.0`` – ``1.0`` and component details.
+    """
+
+    mode = _resolve_mode(primary, candidate, mode)
+    weights = MODE_WEIGHTS.get(mode, DEFAULT_WEIGHTS)
+    ctx = context or PartnerSuggestionContext()
+
+    overlap = _theme_overlap(primary, candidate)
+    synergy = _theme_synergy(primary, candidate, ctx)
+    color_value = _color_compatibility(primary, candidate)
+    affinity, affinity_notes, affinity_penalties = _mechanic_affinity(primary, candidate, mode, ctx)
+    penalty_value, penalty_notes = _collect_penalties(primary, candidate, mode, affinity_penalties)
+
+    positive_total = weights.overlap + weights.synergy + weights.color + weights.affinity
+    positive_total = positive_total or 1.0
+    blended = (
+        weights.overlap * overlap
+        + weights.synergy * synergy
+        + weights.color * color_value
+        + weights.affinity * affinity
+    ) / positive_total
+
+    adjusted = blended - weights.penalty * penalty_value
+    final_score = _clamp(adjusted)
+
+    notes = tuple(note for note in (*affinity_notes, *penalty_notes) if note)
+    components = {
+        "overlap": overlap,
+        "synergy": synergy,
+        "color": color_value,
+        "affinity": affinity,
+        "penalty": penalty_value,
+    }
+
+    return ScoreResult(
+        score=final_score,
+        mode=mode,
+        components=components,
+        notes=notes,
+        weights=weights,
+    )
+
+
+def _resolve_mode(
+    primary: Mapping[str, object],
+    candidate: Mapping[str, object],
+    provided: PartnerMode | str | None,
+) -> PartnerMode:
+    if isinstance(provided, PartnerMode):
+        return provided
+    if isinstance(provided, str) and provided:
+        normalized = provided.replace("-", "_").strip().casefold()
+        for mode in PartnerMode:
+            if mode.value == normalized:
+                return mode
+
+    partner_meta_primary = _partner_meta(primary)
+    partner_meta_candidate = _partner_meta(candidate)
+    candidate_name = _commander_name(candidate)
+
+    if partner_meta_candidate.get("is_background"):
+        return PartnerMode.BACKGROUND
+    partner_with = {
+        _normalize_token(name)
+        for name in partner_meta_primary.get("partner_with", [])
+    }
+    if partner_with and _normalize_token(candidate_name) in partner_with:
+        return PartnerMode.PARTNER_WITH
+    if partner_meta_primary.get("is_doctor") and partner_meta_candidate.get("is_doctors_companion"):
+        return PartnerMode.DOCTOR_COMPANION
+    if partner_meta_primary.get("is_doctors_companion") and partner_meta_candidate.get("is_doctor"):
+        return PartnerMode.DOCTOR_COMPANION
+    if partner_meta_primary.get("has_partner") and partner_meta_candidate.get("has_partner"):
+        return PartnerMode.PARTNER
+    if partner_meta_candidate.get("supports_backgrounds") and partner_meta_primary.get("is_background"):
+        return PartnerMode.BACKGROUND
+    if partner_meta_candidate.get("has_partner"):
+        return PartnerMode.PARTNER
+    return PartnerMode.PARTNER
+
+
+def _partner_meta(payload: Mapping[str, object]) -> MutableMapping[str, object]:
+    meta = payload.get("partner")
+    if isinstance(meta, Mapping):
+        return dict(meta)
+    return {}
+
+
+def _theme_overlap(primary: Mapping[str, object], candidate: Mapping[str, object]) -> float:
+    theme_primary = {
+        _normalize_token(theme)
+        for theme in _theme_sequence(primary)
+    }
+    theme_candidate = {
+        _normalize_token(theme)
+        for theme in _theme_sequence(candidate)
+    }
+    theme_primary.discard("")
+    theme_candidate.discard("")
+
+    role_primary = {
+        _normalize_token(tag)
+        for tag in _sequence(primary, "role_tags")
+    }
+    role_candidate = {
+        _normalize_token(tag)
+        for tag in _sequence(candidate, "role_tags")
+    }
+    role_primary.discard("")
+    role_candidate.discard("")
+
+    # Base Jaccard over theme tags.
+    union = theme_primary | theme_candidate
+    if not union:
+        base = 0.0
+    else:
+        base = len(theme_primary & theme_candidate) / len(union)
+
+    # Role-aware bonus (weighted at 30% of overlap component).
+    role_union = role_primary | role_candidate
+    if not role_union:
+        role_score = 0.0
+    else:
+        role_score = len(role_primary & role_candidate) / len(role_union)
+
+    combined = 0.7 * base + 0.3 * role_score
+    return _clamp(combined)
+
+
+def _theme_synergy(
+    primary: Mapping[str, object],
+    candidate: Mapping[str, object],
+    context: PartnerSuggestionContext,
+) -> float:
+    themes_primary = _theme_sequence(primary)
+    themes_candidate = _theme_sequence(candidate)
+    if not themes_primary or not themes_candidate:
+        return 0.0
+
+    total = 0.0
+    weight = 0
+    for theme_a in themes_primary:
+        for theme_b in themes_candidate:
+            value = context.theme_synergy(theme_a, theme_b)
+            if value <= 0:
+                continue
+            total += value
+            weight += 1
+
+    if weight == 0:
+        return 0.0
+
+    average = total / weight
+
+    # Observed pairing signal augments synergy.
+    primary_name = _commander_name(primary)
+    candidate_name = _commander_name(candidate)
+    observed_partner = context.pairing_strength(PartnerMode.PARTNER, primary_name, candidate_name)
+    observed_background = context.pairing_strength(PartnerMode.BACKGROUND, primary_name, candidate_name)
+    observed_doctor = context.pairing_strength(PartnerMode.DOCTOR_COMPANION, primary_name, candidate_name)
+    observed_any = max(observed_partner, observed_background, observed_doctor)
+
+    return _clamp(max(average, observed_any))
+
+
+def _color_compatibility(primary: Mapping[str, object], candidate: Mapping[str, object]) -> float:
+    primary_colors = {
+        _clean_str(color).upper()
+        for color in _sequence(primary, "color_identity")
+    }
+    candidate_colors = {
+        _clean_str(color).upper()
+        for color in _sequence(candidate, "color_identity")
+    }
+
+    if not candidate_colors:
+        # Colorless partners still provide value when primary is colored.
+        return 0.6 if primary_colors else 0.0
+
+    overlap = primary_colors & candidate_colors
+    union = primary_colors | candidate_colors
+    overlap_ratio = len(overlap) / max(len(candidate_colors), 1)
+
+    added_colors = len(union) - len(primary_colors)
+    if added_colors <= 0:
+        delta = 1.0
+    elif added_colors == 1:
+        delta = 0.75
+    elif added_colors == 2:
+        delta = 0.45
+    else:
+        delta = 0.20
+
+    colorless_bonus = 0.1 if candidate_colors == {"C"} else 0.0
+
+    blended = 0.6 * overlap_ratio + 0.4 * delta + colorless_bonus
+    return _clamp(blended)
+
+
+def _mechanic_affinity(
+    primary: Mapping[str, object],
+    candidate: Mapping[str, object],
+    mode: PartnerMode,
+    context: PartnerSuggestionContext,
+) -> tuple[float, list[str], list[tuple[str, float]]]:
+    primary_meta = _partner_meta(primary)
+    candidate_meta = _partner_meta(candidate)
+    primary_name = _commander_name(primary)
+    candidate_name = _commander_name(candidate)
+
+    notes: list[str] = []
+    penalties: list[tuple[str, float]] = []
+    score = 0.0
+
+    if mode is PartnerMode.PARTNER_WITH:
+        partner_with = {
+            _normalize_token(name)
+            for name in primary_meta.get("partner_with", [])
+        }
+        if partner_with and _normalize_token(candidate_name) in partner_with:
+            score = 1.0
+            notes.append("partner_with_match")
+        else:
+            penalties.append(("missing_partner_with_link", 0.9))
+
+    elif mode is PartnerMode.BACKGROUND:
+        if candidate_meta.get("is_background") and primary_meta.get("supports_backgrounds"):
+            score = 0.9
+            notes.append("background_compatible")
+        else:
+            if not candidate_meta.get("is_background"):
+                penalties.append(("candidate_not_background", 1.0))
+            if not primary_meta.get("supports_backgrounds"):
+                penalties.append(("primary_cannot_use_background", 1.0))
+
+    elif mode is PartnerMode.DOCTOR_COMPANION:
+        primary_is_doctor = bool(primary_meta.get("is_doctor"))
+        primary_is_companion = bool(primary_meta.get("is_doctors_companion"))
+        candidate_is_doctor = bool(candidate_meta.get("is_doctor"))
+        candidate_is_companion = bool(candidate_meta.get("is_doctors_companion"))
+
+        if primary_is_doctor and candidate_is_companion:
+            score = 1.0
+            notes.append("doctor_companion_match")
+        elif primary_is_companion and candidate_is_doctor:
+            score = 1.0
+            notes.append("doctor_companion_match")
+        else:
+            penalties.append(("doctor_pairing_illegal", 1.0))
+
+    else:  # Partner-style default
+        if primary_meta.get("has_partner") and candidate_meta.get("has_partner"):
+            score = 0.6
+            notes.append("shared_partner_keyword")
+        else:
+            penalties.append(("missing_partner_keyword", 1.0))
+
+        primary_labels = {
+            _normalize_token(label)
+            for label in _sequence(primary_meta, "restricted_partner_labels")
+        }
+        candidate_labels = {
+            _normalize_token(label)
+            for label in _sequence(candidate_meta, "restricted_partner_labels")
+        }
+        shared_labels = primary_labels & candidate_labels
+        if primary_labels or candidate_labels:
+            if shared_labels:
+                score = max(score, 0.85)
+                notes.append("restricted_label_match")
+            else:
+                penalties.append(("restricted_label_mismatch", 0.7))
+
+    observed = context.pairing_strength(mode, primary_name, candidate_name)
+    if observed > 0:
+        score = max(score, observed)
+        notes.append("observed_pairing")
+
+    return _clamp(score), notes, penalties
+
+
+def _collect_penalties(
+    primary: Mapping[str, object],
+    candidate: Mapping[str, object],
+    mode: PartnerMode,
+    extra: Iterable[tuple[str, float]],
+) -> tuple[float, list[str]]:
+    penalties: list[tuple[str, float]] = list(extra)
+
+    themes_primary_raw = _sequence(primary, "themes")
+    themes_candidate_raw = _sequence(candidate, "themes")
+    themes_primary = _theme_sequence(primary)
+    themes_candidate = _theme_sequence(candidate)
+    if (not themes_primary or not themes_candidate) and (not themes_primary_raw or not themes_candidate_raw):
+        penalties.append(("missing_theme_metadata", 0.5))
+
+    if mode is PartnerMode.PARTNER_WITH:
+        partner_with = {
+            _normalize_token(name)
+            for name in _sequence(primary.get("partner", {}), "partner_with")
+        }
+        if not partner_with:
+            penalties.append(("primary_missing_partner_with", 0.7))
+
+    colors_candidate = set(_sequence(candidate, "color_identity"))
+    if len(colors_candidate) >= 4:
+        penalties.append(("candidate_color_spread", 0.25))
+
+    total = 0.0
+    reasons: list[str] = []
+    for reason, magnitude in penalties:
+        if magnitude <= 0:
+            continue
+        total += magnitude
+        reasons.append(reason)
+
+    return _clamp(total), reasons