"""Versioned material recognition normalization and generation capsules. The first rollout intentionally stores these structures inside ``material.metadata``. That keeps existing database rows and API consumers compatible while giving newer composition code a stable, explainable representation. """ from __future__ import annotations from copy import deepcopy from datetime import datetime, timezone from typing import Any, Mapping MATERIAL_SCHEMA_VERSION = "1.0" MATERIAL_PROMPT_VERSION = "1.0" ASSET_CATEGORIES = { "identity", "hair", "headwear", "face_accessory", "jewelry", "top", "bottom", "dress", "suit", "outerwear", "underwear", "hosiery", "footwear", "prop", "pose", "background", "style", "other", } ASSET_ROLES = {"identity", "garment", "accessory", "prop", "pose", "background", "style", "other"} BODY_SLOTS = { "identity", "hair", "head", "face", "ears", "neck", "upper_body", "arms", "hands", "waist", "hips", "upper_legs", "lower_legs", "feet", "pose", "background", "global_style", } WEAR_LAYERS = {"skin", "inner", "base", "middle", "outer", "overlay", "accessory", "prop"} SOURCE_STATES = {"observed", "inferred", "unknown", "occluded", "low_visibility"} CAPSULE_TIERS = ("compact", "standard", "detailed") CATEGORY_ALIASES = { "shirt": "top", "blouse": "top", "t-shirt": "top", "top": "top", "上衣": "top", "衬衫": "top", "skirt": "bottom", "pants": "bottom", "trousers": "bottom", "shorts": "bottom", "裙子": "bottom", "裤子": "bottom", "dress": "dress", "gown": "dress", "连衣裙": "dress", "coat": "outerwear", "jacket": "outerwear", "cloak": "outerwear", "外套": "outerwear", "shoe": "footwear", "shoes": "footwear", "boot": "footwear", "boots": "footwear", "鞋": "footwear", "靴": "footwear", "necklace": "jewelry", "earring": "jewelry", "bracelet": "jewelry", "ring": "jewelry", "首饰": "jewelry", "hat": "headwear", "cap": "headwear", "头饰": "headwear", "hair": "hair", "发型": "hair", "pose": "pose", "姿势": "pose", "background": "background", "scene": "background", "背景": "background", "style": "style", "画风": "style", "character": "identity", "identity": "identity", "角色": "identity", } CATEGORY_SEMANTICS: dict[str, tuple[str, list[str], str | None]] = { "identity": ("identity", ["identity", "face"], None), "hair": ("identity", ["hair"], None), "headwear": ("accessory", ["head"], "accessory"), "face_accessory": ("accessory", ["face"], "accessory"), "jewelry": ("accessory", ["ears", "neck", "hands"], "accessory"), "top": ("garment", ["upper_body", "arms"], "base"), "bottom": ("garment", ["waist", "hips", "upper_legs", "lower_legs"], "base"), "dress": ("garment", ["upper_body", "waist", "hips", "upper_legs", "lower_legs"], "base"), "suit": ("garment", ["upper_body", "waist", "hips", "upper_legs", "lower_legs"], "middle"), "outerwear": ("garment", ["upper_body", "arms"], "outer"), "underwear": ("garment", ["upper_body", "waist", "hips"], "inner"), "hosiery": ("garment", ["upper_legs", "lower_legs"], "inner"), "footwear": ("garment", ["feet"], "base"), "prop": ("prop", ["hands"], "prop"), "pose": ("pose", ["pose"], None), "background": ("background", ["background"], None), "style": ("style", ["global_style"], None), "other": ("other", [], None), } RAW_ANALYSIS_SCHEMA: dict[str, Any] = { "type": "object", "required": ["schema_version", "created_at", "model_source", "attributes"], "properties": { "schema_version": {"type": "string"}, "created_at": {"type": "string"}, "model_source": {"type": "object"}, "attributes": {"type": "object"}, "source_payload": {"type": "object"}, }, } NORMALIZED_ASSET_PROFILE_SCHEMA: dict[str, Any] = { "type": "object", "required": ["schema_version", "category", "role", "body_slots", "attributes"], "properties": { "category": {"enum": sorted(ASSET_CATEGORIES)}, "role": {"enum": sorted(ASSET_ROLES)}, "body_slots": {"type": "array", "items": {"enum": sorted(BODY_SLOTS)}}, "wear_layer": {"type": ["string", "null"]}, }, } GENERATION_CAPSULE_SCHEMA: dict[str, Any] = { "type": "object", "required": ["schema_version", "prompt_version", "tier", "prompt_parts", "negative_parts"], "properties": {"tier": {"enum": list(CAPSULE_TIERS)}}, } class MaterialNormalizationError(ValueError): """Raised when provider data cannot be normalized safely.""" class MaterialNormalizationService: def normalize_recognition( self, structured_data: Mapping[str, Any], *, prompt: str, negative_prompt: str | None, tags: list[str], confidence: float | None, provider_id: str, model: str, route_name: str, category_hint: str | None = None, previous_metadata: Mapping[str, Any] | None = None, ) -> dict[str, Any]: now = _utc_now() payload = deepcopy(dict(structured_data)) raw_section = payload.get("raw_analysis") if isinstance(payload.get("raw_analysis"), dict) else payload raw_attributes = self._normalize_attributes(raw_section.get("attributes"), confidence) if not raw_attributes: raw_attributes = self._attributes_from_legacy(prompt, tags, confidence) raw_analysis = { "schema_version": MATERIAL_SCHEMA_VERSION, "prompt_version": MATERIAL_PROMPT_VERSION, "created_at": now, "model_source": {"provider_id": provider_id, "model": model, "route_name": route_name}, "attributes": raw_attributes, "description": _text(raw_section.get("description") or payload.get("description")), "source_payload": payload, } profile_input = payload.get("normalized_asset_profile") if not isinstance(profile_input, dict): profile_input = payload.get("asset_profile") if isinstance(payload.get("asset_profile"), dict) else {} normalized = self._build_profile( profile_input, raw_attributes=raw_attributes, prompt=prompt, negative_prompt=negative_prompt, tags=tags, confidence=confidence, category_hint=category_hint, created_at=now, ) capsules = self._build_capsules(payload.get("generation_capsules"), normalized, prompt, negative_prompt, now) result = {"raw_analysis": raw_analysis, "normalized_asset_profile": normalized, "generation_capsules": capsules} validate_material_structures(result) return self._preserve_history(result, previous_metadata) def ensure_legacy_structures( self, *, prompt: str | None, negative_prompt: str | None, tags: list[str], metadata: Mapping[str, Any] | None, category_hint: str | None = None, ) -> dict[str, Any]: existing = deepcopy(dict(metadata or {})) if all(isinstance(existing.get(key), dict) for key in ("raw_analysis", "normalized_asset_profile", "generation_capsules")): return existing normalized = self.normalize_recognition( {"legacy": True}, prompt=_text(prompt) or ", ".join(tags) or "material reference", negative_prompt=negative_prompt, tags=tags, confidence=None, provider_id="legacy", model="legacy-prompt", route_name="legacy", category_hint=category_hint, previous_metadata=existing, ) return {**existing, **normalized, "material_schema_migrated": True} def _build_profile( self, value: Mapping[str, Any], *, raw_attributes: dict[str, Any], prompt: str, negative_prompt: str | None, tags: list[str], confidence: float | None, category_hint: str | None, created_at: str, ) -> dict[str, Any]: category = normalize_category(value.get("category") or category_hint or _category_from_text([*tags, prompt])) role, default_slots, default_layer = CATEGORY_SEMANTICS[category] body_slots = _enum_list(value.get("body_slots") or value.get("slots"), BODY_SLOTS) or default_slots wear_layer = _enum(value.get("wear_layer") or value.get("layer"), WEAR_LAYERS) or default_layer attributes = { key: item for key, item in raw_attributes.items() if item.get("source_state") == "observed" and float(item.get("confidence") or 0.0) >= 0.60 } requires_confirmation = category == "other" or any( item.get("source_state") != "observed" or float(item.get("confidence") or 0.0) < 0.80 for item in raw_attributes.values() ) return { "schema_version": MATERIAL_SCHEMA_VERSION, "prompt_version": MATERIAL_PROMPT_VERSION, "created_at": created_at, "category": category, "role": _enum(value.get("role"), ASSET_ROLES) or role, "body_slots": body_slots, "wear_layer": wear_layer, "attributes": attributes, "must_preserve": _string_list(value.get("must_preserve")), "forbidden_changes": _string_list(value.get("forbidden_changes")) or _split_prompt(negative_prompt), "tags": sorted(set(tags)), "confidence": _confidence(value.get("confidence"), confidence), "requires_confirmation": requires_confirmation, "confirmed": bool(value.get("confirmed", False)), "user_locked": bool(value.get("user_locked", False)), "stackable": bool(value.get("stackable", category in {"jewelry", "headwear"})), } def _build_capsules( self, provided: Any, profile: Mapping[str, Any], prompt: str, negative_prompt: str | None, created_at: str, ) -> dict[str, Any]: supplied = provided if isinstance(provided, dict) else {} observed_parts = _attribute_prompt_parts(profile.get("attributes")) must_preserve = _string_list(profile.get("must_preserve")) base_parts = _unique([prompt, *observed_parts, *must_preserve]) negative_parts = _unique(_split_prompt(negative_prompt) + _string_list(profile.get("forbidden_changes"))) limits = {"compact": 4, "standard": 10, "detailed": 24} capsules: dict[str, Any] = {} for tier in CAPSULE_TIERS: item = supplied.get(tier) if isinstance(supplied.get(tier), dict) else {} capsules[tier] = { "schema_version": MATERIAL_SCHEMA_VERSION, "prompt_version": MATERIAL_PROMPT_VERSION, "created_at": created_at, "tier": tier, "prompt_parts": _string_list(item.get("prompt_parts")) or base_parts[: limits[tier]], "negative_parts": _string_list(item.get("negative_parts")) or negative_parts, "must_preserve": _string_list(item.get("must_preserve")) or must_preserve, "forbidden_changes": _string_list(item.get("forbidden_changes")) or _string_list(profile.get("forbidden_changes")), "legacy": not bool(supplied), } return capsules def _normalize_attributes(self, value: Any, fallback_confidence: float | None) -> dict[str, Any]: if not isinstance(value, dict): return {} result: dict[str, Any] = {} for key, raw in value.items(): name = _text(key).lower().replace(" ", "_") if not name: continue item = raw if isinstance(raw, dict) else {"value": raw} source_state = _enum(item.get("source_state") or item.get("state"), SOURCE_STATES) or "observed" confidence = _confidence(item.get("confidence"), fallback_confidence) result[name] = { "value": deepcopy(item.get("value")), "confidence": confidence, "source_state": source_state, "source": _text(item.get("source")) or "vision_model", "locked": bool(item.get("locked", False)), "eligible_for_generation": source_state == "observed" and confidence >= 0.60, "requires_confirmation": source_state != "observed" or confidence < 0.80, } return result def _attributes_from_legacy(self, prompt: str, tags: list[str], confidence: float | None) -> dict[str, Any]: value = _unique([*tags, *_split_prompt(prompt)]) score = _confidence(confidence, 0.60) return { "legacy_description": { "value": value, "confidence": score, "source_state": "observed" if confidence is not None else "inferred", "source": "legacy_prompt", "locked": False, "eligible_for_generation": confidence is not None and score >= 0.60, "requires_confirmation": confidence is None or score < 0.80, } } def _preserve_history(self, current: dict[str, Any], previous_metadata: Mapping[str, Any] | None) -> dict[str, Any]: previous = dict(previous_metadata or {}) old_profile = previous.get("normalized_asset_profile") old_raw = previous.get("raw_analysis") history = list(previous.get("material_schema_history") or []) if isinstance(old_profile, dict) or isinstance(old_raw, dict): history.append({"archived_at": _utc_now(), "raw_analysis": old_raw, "normalized_asset_profile": old_profile, "generation_capsules": previous.get("generation_capsules")}) if history: current["material_schema_history"] = history[-10:] if isinstance(old_profile, dict): profile = current["normalized_asset_profile"] if old_profile.get("confirmed") or old_profile.get("user_locked"): for key in ("category", "role", "body_slots", "wear_layer", "must_preserve", "forbidden_changes", "stackable", "confirmed", "user_locked"): if key in old_profile: profile[key] = deepcopy(old_profile[key]) old_attributes = old_profile.get("attributes") if isinstance(old_attributes, dict): for key, item in old_attributes.items(): if isinstance(item, dict) and item.get("locked"): profile.setdefault("attributes", {})[key] = deepcopy(item) return current def normalize_category(value: Any) -> str: text = _text(value).lower().replace("_", " ").strip() if text in ASSET_CATEGORIES: return text for alias, category in CATEGORY_ALIASES.items(): if alias in text: return category return "other" def validate_material_structures(value: Mapping[str, Any]) -> None: raw = value.get("raw_analysis") profile = value.get("normalized_asset_profile") capsules = value.get("generation_capsules") if not isinstance(raw, dict) or not isinstance(raw.get("attributes"), dict): raise MaterialNormalizationError("raw_analysis.attributes must be an object") if not isinstance(profile, dict) or profile.get("category") not in ASSET_CATEGORIES: raise MaterialNormalizationError("normalized_asset_profile.category is invalid") if profile.get("role") not in ASSET_ROLES: raise MaterialNormalizationError("normalized_asset_profile.role is invalid") if any(slot not in BODY_SLOTS for slot in profile.get("body_slots", [])): raise MaterialNormalizationError("normalized_asset_profile.body_slots contains an invalid value") if profile.get("wear_layer") is not None and profile.get("wear_layer") not in WEAR_LAYERS: raise MaterialNormalizationError("normalized_asset_profile.wear_layer is invalid") if not isinstance(capsules, dict) or any(not isinstance(capsules.get(tier), dict) for tier in CAPSULE_TIERS): raise MaterialNormalizationError("generation_capsules must contain compact, standard and detailed") def _category_from_text(values: list[str]) -> str: return " ".join(_text(item) for item in values) def _attribute_prompt_parts(value: Any) -> list[str]: if not isinstance(value, dict): return [] parts: list[str] = [] for name, item in value.items(): if not isinstance(item, dict) or not item.get("eligible_for_generation", True): continue raw = item.get("value") if isinstance(raw, list): text = ", ".join(_text(part) for part in raw if _text(part)) else: text = _text(raw) if text: parts.append(f"{name.replace('_', ' ')}: {text}") return parts def _split_prompt(value: Any) -> list[str]: text = _text(value) return [part.strip() for part in text.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 value in values: text = _text(value) key = text.casefold() if text and key not in seen: seen.add(key) result.append(text) return result def _enum(value: Any, allowed: set[str]) -> str | None: text = _text(value).lower() return text if text in allowed else None def _enum_list(value: Any, allowed: set[str]) -> list[str]: values = value if isinstance(value, (list, tuple, set)) else [value] return _unique([item for item in (_enum(part, allowed) for part in values) if item]) def _confidence(value: Any, fallback: float | None) -> float: try: number = float(value if value is not None else fallback if fallback is not None else 0.0) except (TypeError, ValueError): number = 0.0 return min(max(number, 0.0), 1.0) def _text(value: Any) -> str: return str(value or "").strip() def _utc_now() -> str: return datetime.now(timezone.utc).isoformat()