404 行
18 KiB
Python
404 行
18 KiB
Python
"""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()
|