astrbot_plugin_imagestudio/engines/review_flow.py

431 行
16 KiB
Python

"""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",
}
@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.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,
}
)
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