"""Lightweight workflow review checks.""" from __future__ import annotations from dataclasses import dataclass from typing import Any from backend.dto.image_dto import GenerationImage from backend.dto.workflow_dto import ProfileWorkflow, WorkflowNode STAGE_REVIEW_RESULT_VERSION = "2026-07-09.stage-review-result.v1" _KNOWN_NODE_STATUSES = { "draft", "pending", "queued", "running", "completed", "selected", "failed", "cancelled", "skipped", "discarded", } _GENERATION_NODE_TYPES = {"generation", "single_image", "virtual_single_image"} @dataclass(frozen=True) class ReviewPolicy: version: str = "default-v1" warn_without_images: bool = True require_selected_image_for_statuses: tuple[str, ...] = ("completed", "selected") fail_on_selected_image_not_found: bool = True fail_on_archived_selected_image: bool = True workflow_terminal_statuses: tuple[str, ...] = ("completed", "selected", "skipped") def to_dict(self) -> dict[str, Any]: return { "version": self.version, "warn_without_images": self.warn_without_images, "require_selected_image_for_statuses": list(self.require_selected_image_for_statuses), "fail_on_selected_image_not_found": self.fail_on_selected_image_not_found, "fail_on_archived_selected_image": self.fail_on_archived_selected_image, "workflow_terminal_statuses": list(self.workflow_terminal_statuses), } @classmethod def from_mapping(cls, payload: dict[str, Any]) -> tuple["ReviewPolicy", list[dict[str, Any]]]: errors: list[dict[str, Any]] = [] defaults = cls() values: dict[str, Any] = {} for field_name in ( "warn_without_images", "fail_on_selected_image_not_found", "fail_on_archived_selected_image", ): value = payload.get(field_name, getattr(defaults, field_name)) if not isinstance(value, bool): errors.append( { "field": field_name, "code": "INVALID_BOOLEAN", "message": f"{field_name} must be a boolean", } ) value = getattr(defaults, field_name) values[field_name] = value for field_name in ("require_selected_image_for_statuses", "workflow_terminal_statuses"): value = payload.get(field_name, getattr(defaults, field_name)) normalized = _normalize_status_list(value) if not normalized: errors.append( { "field": field_name, "code": "INVALID_STATUS_LIST", "message": f"{field_name} must contain at least one known node status", } ) normalized = getattr(defaults, field_name) unknown = [status for status in normalized if status not in _KNOWN_NODE_STATUSES] if unknown: errors.append( { "field": field_name, "code": "UNKNOWN_STATUS", "message": f"{field_name} contains unknown statuses", "statuses": unknown, } ) normalized = tuple(status for status in normalized if status in _KNOWN_NODE_STATUSES) if not normalized: normalized = getattr(defaults, field_name) values[field_name] = normalized version = str(payload.get("version") or defaults.version).strip() or defaults.version return cls(version=version, **values), errors class ReviewFlowEngine: def __init__(self, policy: ReviewPolicy | None = None): self.policy = policy or ReviewPolicy() def policy_snapshot(self) -> dict[str, Any]: return self.policy.to_dict() def validate_policy(self, payload: dict[str, Any]) -> dict[str, Any]: policy, errors = ReviewPolicy.from_mapping(payload) return {"valid": not errors, "policy": policy.to_dict(), "errors": errors} def review_node( self, node: WorkflowNode, images: list[GenerationImage], workflow_metadata: dict[str, Any] | None = None, ) -> dict[str, Any]: warnings: list[dict[str, Any]] = [] errors: list[dict[str, Any]] = [] selected_image = next((image for image in images if image.image_id == node.selected_image_id), None) if self.policy.warn_without_images and not images: warnings.append({"code": "NO_IMAGES", "message": "node has no generated images"}) if ( node.node_type in _GENERATION_NODE_TYPES and node.status in self.policy.require_selected_image_for_statuses and not node.selected_image_id ): errors.append({"code": "MISSING_SELECTED_IMAGE", "message": "completed node has no selected image"}) if ( self.policy.fail_on_selected_image_not_found and node.selected_image_id and node.selected_image_id not in {image.image_id for image in images} ): errors.append({"code": "SELECTED_IMAGE_NOT_FOUND", "message": "selected image is not in node images"}) if self.policy.fail_on_archived_selected_image and any( image.image_id == node.selected_image_id and image.is_archived for image in images ): errors.append({"code": "SELECTED_IMAGE_ARCHIVED", "message": "selected image is archived"}) if selected_image and node.model_route and selected_image.model_route and node.model_route != selected_image.model_route: warnings.append( { "code": "MODEL_ROUTE_MISMATCH", "message": "selected image model_route differs from node model_route", "node_model_route": node.model_route, "image_model_route": selected_image.model_route, } ) if selected_image and node.prompt and selected_image.positive_prompt: node_prompt = _normalize_prompt(node.prompt) image_prompt = _normalize_prompt(selected_image.positive_prompt) if node_prompt and image_prompt and node_prompt not in image_prompt and image_prompt not in node_prompt: warnings.append( { "code": "PROMPT_MISMATCH", "message": "selected image prompt differs from node prompt", } ) return { "target_type": "node", "target_id": node.node_id, "passed": not errors, "warnings": warnings, "errors": errors, "summary": { "image_count": len(images), "selected_image_id": node.selected_image_id, "selected_image_model_route": selected_image.model_route if selected_image else None, "node_status": node.status, "node_model_route": node.model_route, "policy_version": self.policy.version, }, "stage_review": build_stage_review_result(node, images, workflow_metadata or {}), } def review_workflow( self, workflow: ProfileWorkflow, nodes: list[WorkflowNode], node_results: list[dict[str, Any]], ) -> dict[str, Any]: errors = [error for result in node_results for error in result["errors"]] warnings = [warning for result in node_results for warning in result["warnings"]] incomplete = [node.node_id for node in nodes if node.status not in self.policy.workflow_terminal_statuses] if incomplete: warnings.append( { "code": "INCOMPLETE_NODES", "message": "workflow has nodes that are not finished", "node_ids": incomplete, } ) incomplete_generation = [ node.node_id for node in nodes if node.node_type in _GENERATION_NODE_TYPES and node.status not in self.policy.workflow_terminal_statuses ] if incomplete_generation: errors.append( { "code": "INCOMPLETE_GENERATION_NODES", "message": "workflow has unfinished generation nodes", "node_ids": incomplete_generation, } ) selected_model_routes = sorted( { str(result["summary"].get("selected_image_model_route")) for result in node_results if result["summary"].get("selected_image_model_route") } ) if len(selected_model_routes) > 1: warnings.append( { "code": "INCONSISTENT_SELECTED_MODEL_ROUTES", "message": "workflow selected images use multiple model routes", "model_routes": selected_model_routes, } ) return { "target_type": "workflow", "target_id": workflow.workflow_id, "passed": not errors, "warnings": warnings, "errors": errors, "summary": { "workflow_type": workflow.workflow_type, "node_count": len(nodes), "incomplete_count": len(incomplete), "selected_model_routes": selected_model_routes, "policy_version": self.policy.version, }, "nodes": node_results, } def _normalize_status_list(value: Any) -> tuple[str, ...]: if isinstance(value, str): candidates = [value] elif isinstance(value, (list, tuple)): candidates = value else: return () statuses: list[str] = [] for item in candidates: status = str(item or "").strip() if status and status not in statuses: statuses.append(status) return tuple(statuses) def _normalize_prompt(value: str) -> str: return " ".join(str(value or "").lower().replace(",", " ").split()) def build_stage_review_result( node: WorkflowNode, images: list[GenerationImage], workflow_metadata: dict[str, Any] | None = None, ) -> dict[str, Any]: candidates = [_review_candidate(node, image, index + 1) for index, image in enumerate(images)] selected_candidate = next( ( { "candidate_id": candidate["candidate_id"], "image_id": candidate["image_id"], "model_route": candidate["model_route"], "score": candidate["score"], "status": candidate["status"], } for candidate in candidates if candidate["image_id"] == node.selected_image_id or candidate["is_selected"] ), None, ) return { "schema_version": STAGE_REVIEW_RESULT_VERSION, "node_id": node.node_id, "node_key": node.node_key, "review_mode": "same_prompt_multi_model", "prompt_contract": { "positive_prompt": node.prompt, "negative_prompt": node.negative_prompt, "model_route": node.model_route, "locked_after_confirm": True, }, "scoring_dimensions": [ "identity_consistency", "prompt_consistency", "model_route_consistency", "visual_defects", "archive_state", ], "candidates": candidates, "selected_candidate": selected_candidate, "regeneration_records": [ candidate["regeneration"] for candidate in candidates if candidate.get("regeneration", {}).get("is_regeneration") ], "manual_confirmation": { "action": "adopt_image", "endpoint": f"nodes/{node.node_id}/adopt-image", "requires_image_id": True, "changes_node_status_to": "selected", "locks_source_node": True, "branch_required_after_confirm": True, }, "handoff": { "current_node_input": _stage_input_for_node(workflow_metadata or {}, node.node_id), "metadata_key": "stage_inputs", "expected_next_input_shape": { "image_id": "string", "from_node_id": node.node_id, "history_id": "string", "role": "next_stage_input | hires_fix_input", }, }, } def _review_candidate(node: WorkflowNode, image: GenerationImage, rank: int) -> dict[str, Any]: metadata = image.metadata if isinstance(image.metadata, dict) else {} warnings = _candidate_warnings(node, image) defects = _string_list(metadata.get("review_defects") or metadata.get("defects")) score_value, score_basis = _candidate_score(metadata, warnings, defects, image.is_archived) status = "selected" if image.is_selected or image.image_id == node.selected_image_id else "candidate" if image.is_archived: status = "archived" return { "candidate_id": f"{node.node_id}:{image.image_id}", "rank": rank, "image_id": image.image_id, "image_uri": image.image_uri, "thumbnail_uri": image.thumbnail_uri, "model_route": image.model_route, "model_used": image.model_used, "seed": image.seed, "width": image.width, "height": image.height, "positive_prompt": image.positive_prompt, "negative_prompt": image.negative_prompt, "is_selected": image.is_selected or image.image_id == node.selected_image_id, "is_archived": image.is_archived, "status": status, "warnings": warnings, "defects": defects, "score": { "value": score_value, "basis": score_basis, "warnings_count": len(warnings), "defects_count": len(defects), }, "regeneration": _regeneration_record(node, image, metadata), } def _candidate_warnings(node: WorkflowNode, image: GenerationImage) -> list[dict[str, Any]]: warnings: list[dict[str, Any]] = [] if image.is_archived: warnings.append({"code": "ARCHIVED", "message": "candidate image is archived"}) if node.model_route and image.model_route and node.model_route != image.model_route: warnings.append( { "code": "MODEL_ROUTE_MISMATCH", "message": "candidate model_route differs from node model_route", "node_model_route": node.model_route, "image_model_route": image.model_route, } ) if node.prompt and image.positive_prompt: node_prompt = _normalize_prompt(node.prompt) image_prompt = _normalize_prompt(image.positive_prompt) if node_prompt and image_prompt and node_prompt not in image_prompt and image_prompt not in node_prompt: warnings.append({"code": "PROMPT_MISMATCH", "message": "candidate prompt differs from node prompt"}) return warnings def _candidate_score( metadata: dict[str, Any], warnings: list[dict[str, Any]], defects: list[str], is_archived: bool, ) -> tuple[int, str]: explicit = metadata.get("review_score") if isinstance(explicit, (int, float)): return max(0, min(100, int(explicit))), "metadata.review_score" score = 100 - len(warnings) * 10 - len(defects) * 8 if is_archived: score -= 40 return max(0, min(100, score)), "heuristic" def _regeneration_record(node: WorkflowNode, image: GenerationImage, metadata: dict[str, Any]) -> dict[str, Any]: source_image_id = _optional_text( metadata.get("regenerated_from_image_id") or metadata.get("source_image_id") or metadata.get("review_source_image_id") ) is_regeneration = bool( source_image_id or metadata.get("same_prompt_regeneration") or metadata.get("review_regeneration") or metadata.get("regeneration_attempt") ) return { "is_regeneration": is_regeneration, "image_id": image.image_id, "source_image_id": source_image_id, "node_id": node.node_id, "same_prompt": bool(metadata.get("same_prompt_regeneration") or metadata.get("review_regeneration")), "attempt": _optional_int(metadata.get("regeneration_attempt") or metadata.get("review_attempt")), "model_route": image.model_route, "created_at": image.created_at, } def _stage_input_for_node(workflow_metadata: dict[str, Any], node_id: str) -> dict[str, Any]: stage_inputs = workflow_metadata.get("stage_inputs") if not isinstance(stage_inputs, dict): return {} value = stage_inputs.get(node_id) return value if isinstance(value, dict) else {} def _string_list(value: Any) -> list[str]: if isinstance(value, str): return [value] if value.strip() else [] if not isinstance(value, list): return [] return [str(item).strip() for item in value if str(item or "").strip()] def _optional_text(value: Any) -> str | None: if value is None: return None text = str(value).strip() return text or None def _optional_int(value: Any) -> int | None: if value is None: return None try: return int(value) except (TypeError, ValueError): return None