"""Profile workflow and workflow node service.""" from __future__ import annotations from typing import Any from uuid import uuid4 from backend.dto.common import ApiError, ErrorCode from backend.dto.workflow_dto import ProfileWorkflow, WorkflowBranch, WorkflowDetail, WorkflowNode from backend.services.material_binding_schema_service import ( MATERIAL_BINDING_SCHEMA_VERSION, normalize_material_bindings, ) from backend.services.prompt_plan_schema_service import ( PROMPT_PLAN_SCHEMA_VERSION, normalize_prompt_plan, ) from backend.services.queue_service import QueueService from core.audit_service import AuditService from core.event_bus import EventBus from core.fsm import node_transition, workflow_transition from core.identity import RequestContext from database.repositories.profile_repository import ProfileRepository from database.repositories.workflow_repository import WorkflowRepository from engines.character_flow import gradual_node_templates from engines.fast_character_flow import fast_character_node_templates from engines.quick_profile_flow import quick_profile_node_templates WORKFLOW_TYPES = {"single_image", "character_gradual", "character_fast", "quick_profile"} WORKFLOW_STATUSES = {"draft", "active", "running", "completed", "failed", "archived", "cancelled"} BRANCH_STATUSES = {"active", "archived"} NODE_STATUSES = { "draft", "queued", "running", "completed", "selected", "failed", "cancelled", "skipped", "discarded", } LOCKED_NODE_STATUSES = {"completed", "selected"} class WorkflowService: def __init__( self, workflow_repository: WorkflowRepository, profile_repository: ProfileRepository, audit_service: AuditService, event_bus: EventBus | None = None, ): self.workflow_repository = workflow_repository self.profile_repository = profile_repository self.audit_service = audit_service self.event_bus = event_bus def create_workflow( self, profile_id: str, payload: dict[str, Any], ctx: RequestContext, ) -> WorkflowDetail: self._ensure_profile_exists(profile_id) workflow_type = str(payload.get("workflow_type") or "").strip() if workflow_type not in WORKFLOW_TYPES: raise ApiError( ErrorCode.VALIDATION_FAILED, "unsupported workflow type", {"field": "workflow_type", "allowed": sorted(WORKFLOW_TYPES)}, ) display_name = str(payload.get("display_name") or "").strip() if not display_name: raise ApiError( ErrorCode.VALIDATION_FAILED, "workflow display_name is required", {"field": "display_name"}, ) status = payload.get("status", "draft") self._validate_workflow_status(status) workflow_id = payload.get("workflow_id") or new_workflow_id() node_payloads = self._initial_node_payloads(workflow_id, workflow_type, payload) workflow, nodes = self.workflow_repository.create_workflow_with_nodes( { "workflow_id": workflow_id, "profile_id": profile_id, "workflow_type": workflow_type, "display_name": display_name, "mode": payload.get("mode"), "status": status, "current_node_id": node_payloads[0]["node_id"] if node_payloads else None, "current_branch": payload.get("current_branch", "main"), "session_key": payload.get("session_key") or ctx.session_key, "metadata": payload.get("metadata") or {}, }, node_payloads, ) self.audit_service.record( ctx=ctx, action="create_workflow", target_type="profile_workflow", target_id=workflow.workflow_id, after_snapshot=workflow.to_dict(), ) self._publish( "workflow.created", { "workflow_id": workflow.workflow_id, "profile_id": workflow.profile_id, "workflow_type": workflow.workflow_type, "node_ids": [node.node_id for node in nodes], }, ) return WorkflowDetail(workflow=workflow, nodes=nodes) def list_workflows(self, profile_id: str) -> list[ProfileWorkflow]: self._ensure_profile_exists(profile_id) return self.workflow_repository.list_workflows(profile_id) def get_workflow(self, workflow_id: str) -> WorkflowDetail: workflow = self.workflow_repository.get_workflow(workflow_id) if workflow is None: raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "workflow not found", {"workflow_id": workflow_id}, ) return WorkflowDetail( workflow=workflow, nodes=self.workflow_repository.list_nodes(workflow_id), ) def update_workflow( self, workflow_id: str, payload: dict[str, Any], ctx: RequestContext, ) -> ProfileWorkflow: before = self.get_workflow(workflow_id).workflow if "status" in payload: self._validate_workflow_status_transition(before.status, str(payload["status"])) if "display_name" in payload and not str(payload["display_name"]).strip(): raise ApiError( ErrorCode.VALIDATION_FAILED, "workflow display_name is required", {"field": "display_name"}, ) update_payload = dict(payload) if "display_name" in update_payload: update_payload["display_name"] = str(update_payload["display_name"]).strip() if "metadata" in update_payload and isinstance(update_payload["metadata"], dict): update_payload["metadata"] = self._normalize_workflow_metadata(before, update_payload["metadata"]) after = self.workflow_repository.update_workflow(workflow_id, update_payload) if after is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "workflow not found", {"workflow_id": workflow_id}) self.audit_service.record( ctx=ctx, action="update_workflow", target_type="profile_workflow", target_id=workflow_id, before_snapshot=before.to_dict(), after_snapshot=after.to_dict(), ) if before.status != after.status: self._publish( "workflow.status_changed", { "workflow_id": workflow_id, "profile_id": after.profile_id, "before_status": before.status, "after_status": after.status, }, ) self._publish("workflow.updated", {"workflow_id": workflow_id, "profile_id": after.profile_id}) return after def cancel_workflow( self, workflow_id: str, ctx: RequestContext, queue_service: QueueService, ) -> ProfileWorkflow: """Cancel a workflow and CAS-cancel its active tasks and nodes.""" while True: before = self.get_workflow(workflow_id).workflow if before.status == "cancelled": after = before break self._validate_workflow_status_transition(before.status, "cancelled") after = self.workflow_repository.update_workflow_if_status( workflow_id, {before.status}, {"status": "cancelled"}, ) if after is not None: self.audit_service.record( ctx=ctx, action="cancel_workflow", target_type="profile_workflow", target_id=workflow_id, before_snapshot=before.to_dict(), after_snapshot=after.to_dict(), ) self._publish( "workflow.status_changed", { "workflow_id": workflow_id, "profile_id": after.profile_id, "before_status": before.status, "after_status": after.status, }, ) self._publish("workflow.updated", {"workflow_id": workflow_id, "profile_id": after.profile_id}) break queue_service.cancel_workflow_jobs(workflow_id, ctx, reason="workflow cancelled") for node in self.workflow_repository.list_nodes(workflow_id): if node.status not in {"queued", "running"}: continue node_metadata = node.metadata if isinstance(node.metadata, dict) else {} last_task_id = str(node_metadata.get("last_task_id") or "").strip() if last_task_id: try: last_task = queue_service.get_job(last_task_id) except ApiError as exc: if exc.error_code != ErrorCode.RESOURCE_NOT_FOUND: raise else: # A task that committed before workflow cancellation owns # its terminal node update. Tasks still active were CAS- # cancelled above and their nodes are cancelled here. if last_task.status in {"completed", "succeeded"}: continue cancelled_node = self.workflow_repository.update_node_if_status( node.node_id, {node.status}, { "status": "cancelled", "metadata": { **node_metadata, "workflow_cancellation": { "workflow_id": workflow_id, "requested_by": ctx.actor_id or "system", }, }, }, ) if cancelled_node is None: continue self.audit_service.record( ctx=ctx, action="cancel_node", target_type="workflow_node", target_id=node.node_id, before_snapshot=node.to_dict(), after_snapshot=cancelled_node.to_dict(), metadata={"source": "workflow.cancel"}, ) self._publish( "workflow.node_status_changed", { "workflow_id": workflow_id, "node_id": node.node_id, "before_status": node.status, "after_status": cancelled_node.status, }, ) self._publish("workflow.node_updated", {"workflow_id": workflow_id, "node_id": node.node_id}) return after def create_branch( self, workflow_id: str, payload: dict[str, Any], ctx: RequestContext, ) -> WorkflowBranch: workflow = self._ensure_workflow_exists(workflow_id) branch_name = str(payload.get("branch_name") or "").strip() if not branch_name: raise ApiError(ErrorCode.VALIDATION_FAILED, "branch_name is required", {"field": "branch_name"}) if self.workflow_repository.get_branch(workflow_id, branch_name): raise ApiError( ErrorCode.VALIDATION_FAILED, "branch already exists", {"workflow_id": workflow_id, "branch_name": branch_name}, ) base_branch_name = str(payload.get("base_branch_name") or workflow.current_branch or "main").strip() base_node_id = payload.get("base_node_id") or workflow.current_node_id copy_nodes = payload.get("copy_nodes", True) if copy_nodes or base_node_id: self._resolve_branch_copy_base(workflow_id, base_branch_name, base_node_id) branch = self.workflow_repository.create_branch( { "branch_id": payload.get("branch_id") or new_branch_id(), "workflow_id": workflow_id, "branch_name": branch_name, "base_branch_name": base_branch_name, "base_node_id": base_node_id, "status": payload.get("status", "active"), "metadata": payload.get("metadata") or {}, } ) copied_nodes = [] if copy_nodes: copied_nodes = self._copy_branch_nodes(workflow_id, base_branch_name, branch_name, ctx, base_node_id) self.audit_service.record( ctx=ctx, action="create_branch", target_type="workflow_branch", target_id=branch.branch_id, after_snapshot={**branch.to_dict(), "copied_node_ids": [node.node_id for node in copied_nodes]}, ) self._publish( "workflow.branch_created", { "workflow_id": workflow_id, "branch_name": branch.branch_name, "copied_node_ids": [node.node_id for node in copied_nodes], }, ) return branch def list_branches(self, workflow_id: str) -> list[WorkflowBranch]: self._ensure_workflow_exists(workflow_id) branches = self.workflow_repository.list_branches(workflow_id) if branches: return branches return [ WorkflowBranch( branch_id="branch_virtual_main", workflow_id=workflow_id, branch_name="main", base_branch_name=None, base_node_id=None, status="active", metadata={"virtual": True}, created_at="", updated_at="", ) ] def switch_branch(self, workflow_id: str, branch_name: str, ctx: RequestContext) -> ProfileWorkflow: before = self._ensure_workflow_exists(workflow_id) if branch_name != "main" and self.workflow_repository.get_branch(workflow_id, branch_name) is None: raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "branch not found", {"workflow_id": workflow_id, "branch_name": branch_name}, ) branch_nodes = self.workflow_repository.list_nodes(workflow_id, branch_name=branch_name) after = self.update_workflow( workflow_id, { "current_branch": branch_name, "current_node_id": branch_nodes[0].node_id if branch_nodes else before.current_node_id, }, ctx, ) self.audit_service.record( ctx=ctx, action="switch_branch", target_type="profile_workflow", target_id=workflow_id, before_snapshot=before.to_dict(), after_snapshot=after.to_dict(), ) return after def create_node( self, workflow_id: str, payload: dict[str, Any], ctx: RequestContext, *, audit: bool = True, ) -> WorkflowNode: self._ensure_workflow_exists(workflow_id) node_key = str(payload.get("node_key") or "").strip() title = str(payload.get("title") or "").strip() if not node_key: raise ApiError(ErrorCode.VALIDATION_FAILED, "node_key is required", {"field": "node_key"}) if not title: raise ApiError(ErrorCode.VALIDATION_FAILED, "node title is required", {"field": "title"}) status = payload.get("status", "draft") if status not in NODE_STATUSES: raise ApiError( ErrorCode.VALIDATION_FAILED, "unsupported node status", {"field": "status", "allowed": sorted(NODE_STATUSES)}, ) node = self.workflow_repository.create_node( { "node_id": payload.get("node_id") or new_node_id(), "workflow_id": workflow_id, "node_key": node_key, "title": title, "description": payload.get("description"), "step_name": payload.get("step_name"), "node_type": payload.get("node_type", "generation"), "status": status, "branch_name": payload.get("branch_name", "main"), "prompt": payload.get("prompt"), "negative_prompt": payload.get("negative_prompt"), "model_route": payload.get("model_route"), "selected_image_id": payload.get("selected_image_id"), "sort_order": payload.get("sort_order", 0), "metadata": payload.get("metadata") or {}, } ) if audit: self.audit_service.record( ctx=ctx, action="create_node", target_type="workflow_node", target_id=node.node_id, after_snapshot=node.to_dict(), ) self._publish( "workflow.node_created", {"workflow_id": workflow_id, "node_id": node.node_id, "node_key": node.node_key}, ) return node def list_nodes(self, workflow_id: str) -> list[WorkflowNode]: self._ensure_workflow_exists(workflow_id) return self.workflow_repository.list_nodes(workflow_id) def get_node(self, node_id: str) -> WorkflowNode: node = self.workflow_repository.get_node(node_id) if node is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "node not found", {"node_id": node_id}) return node def update_node( self, node_id: str, payload: dict[str, Any], ctx: RequestContext, *, allow_locked_adoption: bool = False, ) -> WorkflowNode: before = self.get_node(node_id) if before.status in LOCKED_NODE_STATUSES and _node_payload_changes(before, payload): if not (allow_locked_adoption and _is_locked_image_adoption(before, payload)): raise locked_node_edit_error(before) if "status" in payload: self._validate_node_status_transition(before.status, str(payload["status"])) if "title" in payload and not str(payload["title"]).strip(): raise ApiError(ErrorCode.VALIDATION_FAILED, "node title is required", {"field": "title"}) update_payload = dict(payload) if "title" in update_payload: update_payload["title"] = str(update_payload["title"]).strip() after = self.workflow_repository.update_node(node_id, update_payload) if after is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "node not found", {"node_id": node_id}) self._sync_material_bindings_from_node(after) self._sync_prompt_plan_from_node(after) self.audit_service.record( ctx=ctx, action="update_node", target_type="workflow_node", target_id=node_id, before_snapshot=before.to_dict(), after_snapshot=after.to_dict(), ) if before.status != after.status: self._publish( "workflow.node_status_changed", { "workflow_id": after.workflow_id, "node_id": node_id, "before_status": before.status, "after_status": after.status, }, ) self._publish("workflow.node_updated", {"workflow_id": after.workflow_id, "node_id": node_id}) return after def _initial_node_payloads( self, workflow_id: str, workflow_type: str, payload: dict[str, Any], ) -> list[dict[str, Any]]: if payload.get("auto_create_nodes", True) is False: return [] nodes: list[dict[str, Any]] = [] for template in _initial_node_templates(workflow_type): node_key = str(template.get("node_key") or "").strip() title = str(template.get("title") or "").strip() status = str(template.get("status") or "draft") if not node_key or not title or status not in NODE_STATUSES: raise RuntimeError(f"invalid initial node template for {workflow_type}") nodes.append( { "node_id": template.get("node_id") or new_node_id(), "workflow_id": workflow_id, "node_key": node_key, "title": title, "description": template.get("description"), "step_name": template.get("step_name"), "node_type": template.get("node_type", "generation"), "status": status, "branch_name": template.get("branch_name", "main"), "prompt": template.get("prompt"), "negative_prompt": template.get("negative_prompt"), "model_route": template.get("model_route"), "selected_image_id": template.get("selected_image_id"), "sort_order": template.get("sort_order", 0), "metadata": template.get("metadata") or {}, } ) return nodes def _copy_branch_nodes( self, workflow_id: str, from_branch: str, to_branch: str, ctx: RequestContext, base_node_id: str | None = None, ) -> list[WorkflowNode]: source_nodes, base_sort_order = self._resolve_branch_copy_base(workflow_id, from_branch, base_node_id) return [ self.create_node( workflow_id, { "node_key": node.node_key, "title": node.title, "description": node.description, "step_name": node.step_name, "node_type": node.node_type, "status": _branch_copy_status(node, base_sort_order), "branch_name": to_branch, "prompt": node.prompt, "negative_prompt": node.negative_prompt, "model_route": node.model_route, "selected_image_id": _branch_copy_selected_image_id(node, base_sort_order), "sort_order": node.sort_order, "metadata": _branch_copy_metadata(node, base_sort_order), }, ctx, audit=False, ) for node in source_nodes ] def _resolve_branch_copy_base( self, workflow_id: str, from_branch: str, base_node_id: str | None = None, ) -> tuple[list[WorkflowNode], int | None]: source_nodes = self.workflow_repository.list_nodes(workflow_id, branch_name=from_branch) if not source_nodes and from_branch != "main": source_nodes = self.workflow_repository.list_nodes(workflow_id, branch_name="main") base_node = None if base_node_id: base_node = next((node for node in source_nodes if node.node_id == base_node_id), None) if base_node is None: raise ApiError( ErrorCode.VALIDATION_FAILED, "base_node_id does not belong to the source branch", {"workflow_id": workflow_id, "branch_name": from_branch, "base_node_id": base_node_id}, ) return source_nodes, base_node.sort_order if base_node else None def _ensure_profile_exists(self, profile_id: str) -> None: profile = self.profile_repository.get(profile_id) if profile is None or profile.status == "deleted": raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "profile not found", {"profile_id": profile_id}, ) def _ensure_workflow_exists(self, workflow_id: str) -> ProfileWorkflow: workflow = self.workflow_repository.get_workflow(workflow_id) if workflow is None: raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "workflow not found", {"workflow_id": workflow_id}, ) return workflow def _validate_workflow_status_transition(self, current: str, target: str) -> None: self._validate_workflow_status(target) transition = workflow_transition(current, target) if not transition.allowed: raise ApiError( ErrorCode.VALIDATION_FAILED, "workflow status transition is not allowed", {"current": current, "target": target, "reason": transition.reason}, ) def _validate_workflow_status(self, status: Any) -> None: if not isinstance(status, str) or status not in WORKFLOW_STATUSES: raise ApiError( ErrorCode.VALIDATION_FAILED, "unsupported workflow status", {"field": "status", "allowed": sorted(WORKFLOW_STATUSES)}, ) def _validate_node_status_transition(self, current: str, target: str) -> None: if target not in NODE_STATUSES: raise ApiError( ErrorCode.VALIDATION_FAILED, "unsupported node status", {"field": "status", "allowed": sorted(NODE_STATUSES)}, ) transition = node_transition(current, target) if not transition.allowed: raise ApiError( ErrorCode.VALIDATION_FAILED, "node status transition is not allowed", {"current": current, "target": target, "reason": transition.reason}, ) def _publish(self, event_type: str, payload: dict[str, Any]) -> None: if self.event_bus: self.event_bus.publish(event_type, payload) def _normalize_workflow_metadata( self, workflow: ProfileWorkflow, metadata: dict[str, Any], ) -> dict[str, Any]: material_bindings = metadata.get("material_bindings") prompt_plan = metadata.get("prompt_plan") or metadata.get("prompt_matrix") if material_bindings is None and prompt_plan is None: return metadata nodes = self.workflow_repository.list_nodes(workflow.workflow_id, branch_name=workflow.current_branch) normalized = dict(metadata) if material_bindings is not None: normalized["material_binding_schema_version"] = MATERIAL_BINDING_SCHEMA_VERSION normalized["material_bindings"] = normalize_material_bindings(material_bindings, nodes) if prompt_plan is not None: normalized["prompt_plan_schema_version"] = PROMPT_PLAN_SCHEMA_VERSION normalized["prompt_plan"] = normalize_prompt_plan(prompt_plan, nodes) normalized.pop("prompt_matrix", None) return normalized def _sync_material_bindings_from_node(self, node: WorkflowNode) -> None: if node.node_key != "material_bind" or not isinstance(node.metadata, dict): return raw_bindings = node.metadata.get("material_bindings") if raw_bindings is None: return workflow = self.workflow_repository.get_workflow(node.workflow_id) if workflow is None: return nodes = self.workflow_repository.list_nodes(node.workflow_id, branch_name=node.branch_name) normalized = normalize_material_bindings(raw_bindings, nodes) self.workflow_repository.update_workflow( workflow.workflow_id, { "metadata": { **(workflow.metadata or {}), "material_binding_schema_version": MATERIAL_BINDING_SCHEMA_VERSION, "material_binding_source_node_id": node.node_id, "material_binding_updated_at": node.updated_at, "material_bindings": normalized, } }, ) def _sync_prompt_plan_from_node(self, node: WorkflowNode) -> None: if node.node_key != "prompt_plan" or not isinstance(node.metadata, dict): return raw_plan = node.metadata.get("prompt_plan") or node.metadata.get("prompt_matrix") if raw_plan is None: return workflow = self.workflow_repository.get_workflow(node.workflow_id) if workflow is None: return nodes = self.workflow_repository.list_nodes(node.workflow_id, branch_name=node.branch_name) normalized = normalize_prompt_plan(raw_plan, nodes) self.workflow_repository.update_workflow( workflow.workflow_id, { "metadata": { **(workflow.metadata or {}), "prompt_plan_schema_version": PROMPT_PLAN_SCHEMA_VERSION, "prompt_plan_source_node_id": node.node_id, "prompt_plan_updated_at": node.updated_at, "prompt_plan": normalized, } }, ) def new_workflow_id() -> str: return f"workflow_{uuid4().hex}" def new_node_id() -> str: return f"node_{uuid4().hex}" def new_branch_id() -> str: return f"branch_{uuid4().hex}" def locked_node_edit_error(node: WorkflowNode) -> ApiError: return ApiError( ErrorCode.VALIDATION_FAILED, "completed node is locked; create a workflow branch before editing", { "node_id": node.node_id, "workflow_id": node.workflow_id, "branch_name": node.branch_name, "status": node.status, "suggested_action": "create_branch", "base_node_id": node.node_id, }, ) def is_repeatable_single_image_node(node: WorkflowNode) -> bool: return bool( node.node_key == "virtual_single_image" or node.node_type == "virtual_single_image" or (isinstance(node.metadata, dict) and node.metadata.get("virtual") is True) ) def _node_payload_changes(node: WorkflowNode, payload: dict[str, Any]) -> bool: comparable = { "title": node.title, "description": node.description, "step_name": node.step_name, "node_type": node.node_type, "status": node.status, "branch_name": node.branch_name, "prompt": node.prompt, "negative_prompt": node.negative_prompt, "model_route": node.model_route, "selected_image_id": node.selected_image_id, "sort_order": node.sort_order, "metadata": node.metadata, } for key, value in payload.items(): if key not in comparable: continue current = comparable[key] if key == "sort_order": try: value = int(value) except (TypeError, ValueError): return True if key == "title" and value is not None: value = str(value).strip() if value != current: return True return False def _is_locked_image_adoption(node: WorkflowNode, payload: dict[str, Any]) -> bool: allowed_keys = {"status", "selected_image_id"} if any(key not in allowed_keys for key in payload): return False selected_image_id = payload.get("selected_image_id") if not selected_image_id: return False target_status = payload.get("status", node.status) if target_status != "selected": return False if node.status == "completed": return True return node.status == "selected" and node.selected_image_id == selected_image_id def _branch_copy_status(node: WorkflowNode, base_sort_order: int | None) -> str: if base_sort_order is None: return "draft" if node.sort_order < base_sort_order: return node.status return "draft" def _branch_copy_selected_image_id(node: WorkflowNode, base_sort_order: int | None) -> str | None: if base_sort_order is not None and node.sort_order < base_sort_order: return node.selected_image_id return None def _branch_copy_metadata(node: WorkflowNode, base_sort_order: int | None) -> dict[str, Any]: metadata = { **node.metadata, "copied_from_node_id": node.node_id, } if base_sort_order is None: return metadata locked_ancestor = node.sort_order < base_sort_order and node.status in LOCKED_NODE_STATUSES metadata.update( { "branch_cut_base_sort_order": base_sort_order, "branch_reset_from_status": node.status, "branch_locked_ancestor": locked_ancestor, "branch_editable_from_cut": node.sort_order >= base_sort_order, } ) return metadata def _initial_node_templates(workflow_type: str) -> list[dict[str, Any]]: if workflow_type == "single_image": return [ { "node_key": "virtual_single_image", "title": "Single image", "description": "Backend virtual node for the single image flow.", "node_type": "virtual_single_image", "sort_order": 0, "metadata": {"virtual": True, "template": "single_image_v1"}, } ] if workflow_type == "character_gradual": return gradual_node_templates() if workflow_type == "character_fast": return fast_character_node_templates() if workflow_type == "quick_profile": return quick_profile_node_templates() return []