astrbot_plugin_imagestudio/backend/services/composition_builder.py

307 行
15 KiB
Python

2026-07-12 02:54:45 +08:00
"""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_catalog_resolver import is_trusted_advanced_metadata
2026-07-12 02:54:45 +08:00
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"),
)
ADVANCED_VERIFIED_PRIORITY_BONUS = 20.0
2026-07-12 02:54:45 +08:00
@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
advanced_verified_bonus = (
ADVANCED_VERIFIED_PRIORITY_BONUS
if is_trusted_advanced_metadata(metadata)
else 0.0
)
2026-07-12 02:54:45 +08:00
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 + advanced_verified_bonus + visibility_bonus + restoration_feedback_bonus - low_confidence_penalty - season_penalty
2026-07-12 02:54:45 +08:00
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,
"advanced_verified_bonus": advanced_verified_bonus,
2026-07-12 02:54:45 +08:00
"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()