"""Deterministic, explainable material composition for generation prompts.""" from __future__ import annotations from dataclasses import dataclass, field from typing import Any, Mapping from backend.services.material_normalization_service import CAPSULE_TIERS, WEAR_LAYERS BASE_WEIGHTS = { "identity": 100.0, "dress": 82.0, "suit": 80.0, "outerwear": 72.0, "top": 70.0, "bottom": 70.0, "hair": 68.0, "footwear": 55.0, "jewelry": 38.0, "headwear": 38.0, "face_accessory": 38.0, "prop": 34.0, "pose": 45.0, "style": 42.0, "background": 30.0, "other": 20.0, } LAYER_ORDER = {layer: index for index, layer in enumerate(("skin", "inner", "base", "middle", "outer", "overlay", "accessory", "prop"))} CONTRADICTIONS = ( ("fitted", "oversized"), ("matte", "glossy"), ("short sleeve", "long sleeve"), ("transparent", "opaque"), ("minimal", "ornate"), ) @dataclass(frozen=True) class ReferenceImageBinding: material_id: str image_uri: str role: str use_for: list[str] do_not_inherit: list[str] weight: float def to_dict(self) -> dict[str, Any]: return dict(self.__dict__) @dataclass(frozen=True) class CompositionPlan: materials: list[dict[str, Any]] identity_prompt: str = "" user_prompt: str = "" negative_prompt: str = "" prompt_budget: int = 4000 max_reference_images: int = 8 visible_slots: list[str] = field(default_factory=list) season: str = "" scene: str = "" @dataclass class CompositionResult: prompt: str negative_prompt: str selected_materials: list[dict[str, Any]] = field(default_factory=list) resolution_log: list[dict[str, Any]] = field(default_factory=list) conflicts: list[dict[str, Any]] = field(default_factory=list) ignored_materials: list[dict[str, Any]] = field(default_factory=list) downgraded_materials: list[dict[str, Any]] = field(default_factory=list) reference_bindings: list[ReferenceImageBinding] = field(default_factory=list) budget: dict[str, Any] = field(default_factory=dict) def to_dict(self) -> dict[str, Any]: return { "prompt": self.prompt, "negative_prompt": self.negative_prompt, "selected_materials": self.selected_materials, "resolution_log": self.resolution_log, "conflicts": self.conflicts, "ignored_materials": self.ignored_materials, "downgraded_materials": self.downgraded_materials, "reference_bindings": [item.to_dict() for item in self.reference_bindings], "budget": self.budget, } class CompositionBuilder: def build(self, plan: CompositionPlan | Mapping[str, Any]) -> CompositionResult: if not isinstance(plan, CompositionPlan): plan = CompositionPlan( materials=list(plan.get("materials") or []), identity_prompt=_text(plan.get("identity_prompt")), user_prompt=_text(plan.get("user_prompt")), negative_prompt=_text(plan.get("negative_prompt")), prompt_budget=max(int(plan.get("prompt_budget") or 4000), 256), max_reference_images=max(int(plan.get("max_reference_images") or 8), 0), visible_slots=_string_list(plan.get("visible_slots")), season=_text(plan.get("season")), scene=_text(plan.get("scene")), ) prepared = [self._prepare_material(item, plan) for item in plan.materials if isinstance(item, dict)] prepared.sort(key=lambda item: (-item["effective_weight"], item["material_id"])) kept, ignored, conflicts, resolution_log = self._resolve_conflicts(prepared) kept.sort(key=lambda item: (self._semantic_order(item), -item["effective_weight"], item["material_id"])) prompt_parts = _unique([plan.identity_prompt, *self._capsule_parts(kept), plan.user_prompt]) negative_parts = _unique([plan.negative_prompt, *self._negative_parts(kept)]) prompt, budget, downgraded = self._apply_budget(prompt_parts, kept, plan.prompt_budget) references = self._reference_bindings(kept, plan.max_reference_images, downgraded) return CompositionResult( prompt=prompt, negative_prompt=", ".join(negative_parts), selected_materials=kept, resolution_log=resolution_log, conflicts=conflicts, ignored_materials=ignored, downgraded_materials=downgraded, reference_bindings=references, budget=budget, ) def _prepare_material(self, item: dict[str, Any], plan: CompositionPlan) -> dict[str, Any]: metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {} profile = metadata.get("normalized_asset_profile") if isinstance(metadata.get("normalized_asset_profile"), dict) else {} capsules = metadata.get("generation_capsules") if isinstance(metadata.get("generation_capsules"), dict) else {} category = _text(profile.get("category") or item.get("category") or item.get("wardrobe_category") or "other") role = _text(profile.get("role") or item.get("role") or "other") confidence = _float(profile.get("confidence"), 0.5) locked = bool(item.get("locked") or item.get("user_locked") or profile.get("user_locked")) user_adjustment = _float(item.get("user_adjustment"), 0.0) role_bonus = 20.0 if role == "identity" else 8.0 if category in {"dress", "suit", "top", "bottom", "outerwear"} else 0.0 lock_bonus = 100.0 if locked else 0.0 slots = _string_list(profile.get("body_slots")) automatic_visibility = 10.0 if plan.visible_slots and set(slots) & set(plan.visible_slots) else 0.0 visibility_bonus = _float(item.get("visibility_bonus"), 0.0) + automatic_visibility restoration_feedback_bonus = (_float(item.get("restoration_score"), 0.5) - 0.5) * 20.0 season_penalty = 12.0 if plan.season and _text(item.get("season")) and plan.season.casefold() != _text(item.get("season")).casefold() else 0.0 low_confidence_penalty = max(0.0, 0.80 - confidence) * 40.0 base_weight = BASE_WEIGHTS.get(category, BASE_WEIGHTS["other"]) effective_weight = base_weight + user_adjustment + role_bonus + lock_bonus + visibility_bonus + restoration_feedback_bonus - low_confidence_penalty - season_penalty tier = _text(item.get("capsule_tier") or "detailed").lower() if tier not in CAPSULE_TIERS: tier = "standard" capsule = capsules.get(tier) if isinstance(capsules.get(tier), dict) else {} prompt_parts = _string_list(capsule.get("prompt_parts")) or _split_prompt(item.get("prompt")) negative_parts = _string_list(capsule.get("negative_parts")) or _split_prompt(item.get("negative_prompt")) return { **item, "material_id": _text(item.get("material_id")) or _text(item.get("wardrobe_item_id")) or f"material-{id(item)}", "category": category, "role": role, "body_slots": slots, "wear_layer": _text(profile.get("wear_layer")) or None, "stackable": bool(item.get("stackable", profile.get("stackable", False))), "locked": locked, "capsule_tier": tier, "prompt_parts": prompt_parts, "negative_parts": negative_parts, "must_preserve": _string_list(capsule.get("must_preserve") or profile.get("must_preserve")), "forbidden_changes": _string_list(capsule.get("forbidden_changes") or profile.get("forbidden_changes")), "effective_weight": round(effective_weight, 3), "weight_breakdown": { "base_weight": base_weight, "user_adjustment": user_adjustment, "lock_bonus": lock_bonus, "role_bonus": role_bonus, "visibility_bonus": visibility_bonus, "restoration_feedback_bonus": round(restoration_feedback_bonus, 3), "season_penalty": season_penalty, "low_confidence_penalty": round(low_confidence_penalty, 3), }, } def _resolve_conflicts(self, items: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]: kept: list[dict[str, Any]] = [] ignored: list[dict[str, Any]] = [] conflicts: list[dict[str, Any]] = [] log: list[dict[str, Any]] = [] for candidate in items: blocker = next((current for current in kept if self._conflict_reason(current, candidate)), None) if blocker is None: kept.append(candidate) log.append({"material_id": candidate["material_id"], "decision": "kept", "reason": "no_conflict", "effective_weight": candidate["effective_weight"]}) continue reason = self._conflict_reason(blocker, candidate) or "conflict" conflict = {"type": reason, "winner": blocker["material_id"], "loser": candidate["material_id"]} conflicts.append(conflict) ignored_item = {**candidate, "ignored_reason": reason, "conflicts_with": blocker["material_id"]} ignored.append(ignored_item) log.append({"material_id": candidate["material_id"], "decision": "ignored", "reason": reason, "winner": blocker["material_id"]}) return kept, ignored, conflicts, log def _conflict_reason(self, left: Mapping[str, Any], right: Mapping[str, Any]) -> str | None: categories = {left.get("category"), right.get("category")} if "dress" in categories and categories & {"top", "bottom", "suit"}: return "dress_separate_garment_conflict" slots = set(left.get("body_slots") or []) & set(right.get("body_slots") or []) if slots: if left.get("stackable") and right.get("stackable"): return None left_layer, right_layer = left.get("wear_layer"), right.get("wear_layer") if left_layer and right_layer and left_layer != right_layer: return None return "body_slot_conflict" left_text = " ".join(left.get("prompt_parts") or []).lower() right_text = " ".join(right.get("prompt_parts") or []).lower() if any((a in left_text and b in right_text) or (b in left_text and a in right_text) for a, b in CONTRADICTIONS): return "attribute_contradiction" return None def _semantic_order(self, item: Mapping[str, Any]) -> tuple[int, int]: role_order = {"identity": 0, "garment": 2, "accessory": 6, "prop": 7, "pose": 8, "background": 9, "style": 10, "other": 11} return role_order.get(_text(item.get("role")), 11), LAYER_ORDER.get(_text(item.get("wear_layer")), 99) def _capsule_parts(self, items: list[dict[str, Any]]) -> list[str]: result: list[str] = [] for item in items: result.extend(item["prompt_parts"]) result.extend(f"must preserve {value}" for value in item["must_preserve"]) return result def _negative_parts(self, items: list[dict[str, Any]]) -> list[str]: return [part for item in items for part in [*item["negative_parts"], *item["forbidden_changes"]]] def _apply_budget(self, parts: list[str], items: list[dict[str, Any]], budget: int) -> tuple[str, dict[str, Any], list[dict[str, Any]]]: original = ", ".join(parts) if len(original) <= budget: return original, {"limit": budget, "before": len(original), "after": len(original), "removed": []}, [] locked_terms = {term for item in items if item["locked"] or item["role"] == "identity" for term in [*item["prompt_parts"], *item["must_preserve"]]} kept = list(parts) removed: list[str] = [] for part in reversed(parts): if len(", ".join(kept)) <= budget: break if part in locked_terms or part.startswith("must preserve "): continue kept.remove(part) removed.append(part) text = ", ".join(kept) if len(text) > budget: # Locked and safety-relevant content is never silently truncated. text = text downgraded = [{"reason": "prompt_budget", "removed_prompt_parts": removed}] if removed else [] return text, {"limit": budget, "before": len(original), "after": len(text), "removed": removed}, downgraded def _reference_bindings(self, items: list[dict[str, Any]], limit: int, downgraded: list[dict[str, Any]]) -> list[ReferenceImageBinding]: candidates = [item for item in items if _text(item.get("image_uri"))] candidates.sort(key=lambda item: (-item["effective_weight"], item["material_id"])) bindings: list[ReferenceImageBinding] = [] for item in candidates[:limit]: role = item["role"] if role == "identity": use_for = ["identity", "face", "hair"] do_not_inherit = ["pose", "background", "style"] elif role in {"garment", "accessory"}: use_for = ["clothing", "design", "color", "material"] do_not_inherit = ["face", "identity", "body_shape", "pose", "background", "style"] else: use_for = [role] do_not_inherit = ["identity", "face"] bindings.append(ReferenceImageBinding(item["material_id"], item["image_uri"], role, use_for, do_not_inherit, min(max(item["effective_weight"] / 100.0, 0.1), 1.0))) for item in candidates[limit:]: downgraded.append({"material_id": item["material_id"], "reason": "reference_image_limit", "fallback": "text_capsule"}) return bindings def _split_prompt(value: Any) -> list[str]: return [part.strip() for part in _text(value).replace(";", ",").split(",") if part.strip()] def _string_list(value: Any) -> list[str]: if isinstance(value, str): return _split_prompt(value) if not isinstance(value, (list, tuple, set)): return [] return _unique([_text(item) for item in value]) def _unique(values: list[str]) -> list[str]: result: list[str] = [] seen: set[str] = set() for item in values: text = _text(item) if text and text.casefold() not in seen: seen.add(text.casefold()) result.append(text) return result def _float(value: Any, default: float) -> float: try: return float(value) except (TypeError, ValueError): return default def _text(value: Any) -> str: return str(value or "").strip()