Validate item template formatter hints

category_template_metadata.py

@@ -20,6 +20,12 @@ TEMPLATE_METADATA_KEYS = (
     "position_keys",
     "formatter_hint",
 )
+FORMATTER_HINT_ROUTES = ("all", "krea", "sdxl", "caption")
+FORMATTER_HINT_ROUTE_ALIASES = {
+    "krea2": "krea",
+    "naturalizer": "caption",
+    "training_caption": "caption",
+}
 
 
 def template_metadata(item: Any) -> dict[str, Any]:
@@ -49,6 +55,47 @@ def template_action_family(metadata: dict[str, Any]) -> str:
     return normalize_hardcore_action_family(metadata.get("action_family") or metadata.get("action_type"), "")
 
 
+def _list_from(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _clean_hint(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def normalize_formatter_route(value: Any) -> str:
+    route = re.sub(r"[^a-z0-9]+", "_", str(value or "").strip().lower()).strip("_")
+    route = FORMATTER_HINT_ROUTE_ALIASES.get(route, route)
+    return route if route in FORMATTER_HINT_ROUTES else ""
+
+
+def formatter_hints(metadata: dict[str, Any]) -> dict[str, list[str]]:
+    raw = metadata.get("formatter_hint")
+    if raw is None:
+        return {}
+    normalized: dict[str, list[str]] = {}
+
+    def add(route: str, values: Any) -> None:
+        route = normalize_formatter_route(route)
+        if not route:
+            return
+        for value in _list_from(values):
+            hint = _clean_hint(value)
+            if hint and hint not in normalized.setdefault(route, []):
+                normalized[route].append(hint)
+
+    if isinstance(raw, dict):
+        for route, values in raw.items():
+            add(str(route), values)
+    else:
+        add("all", raw)
+    return {route: hints for route, hints in normalized.items() if hints}
+
+
 def merge_position_keys(primary: list[str], fallback: list[str]) -> list[str]:
     merged: list[str] = []
     for key in [*primary, *fallback]:
@@ -85,4 +132,25 @@ def template_metadata_errors(metadata: dict[str, Any]) -> list[str]:
     ]
     if invalid_keys:
         errors.append("unknown position key(s): " + ", ".join(invalid_keys))
+    raw_hint = metadata.get("formatter_hint")
+    if raw_hint is not None:
+        if isinstance(raw_hint, dict):
+            for route, values in raw_hint.items():
+                if not normalize_formatter_route(route):
+                    errors.append(f"unknown formatter_hint route: {route}")
+                invalid_values = [
+                    repr(value)
+                    for value in _list_from(values)
+                    if not isinstance(value, str) or not value.strip()
+                ]
+                if invalid_values:
+                    errors.append(f"invalid formatter_hint value(s) for {route}: " + ", ".join(invalid_values))
+        else:
+            invalid_values = [
+                repr(value)
+                for value in _list_from(raw_hint)
+                if not isinstance(value, str) or not value.strip()
+            ]
+            if invalid_values:
+                errors.append("invalid formatter_hint value(s): " + ", ".join(invalid_values))
     return errors