"""Node-specific workflow chat injection contracts.""" from __future__ import annotations from copy import deepcopy from typing import Any from backend.dto.workflow_dto import WorkflowNode from engines.character_flow import canonical_gradual_node_key NODE_INJECTION_TEMPLATE_VERSION = "2026-07-09.node-injection-schema.v1" NODE_KEY_TEMPLATE_KINDS: dict[str, str] = { "profile_brief": "persona_split", "prompt_plan": "prompt_plan", "material_bind": "material_bind", "headshot": "portrait_generation", "upper_body": "halfbody_generation", "lower_body": "fullbody_generation", "full_body": "fullbody_generation", "turnaround": "sheet_generation", "design_sheet": "pose_generation", "style_lock": "hires_fix", "profile_card": "archive", "fast_profile": "persona_split", "fast_candidates": "portrait_generation", "fast_final": "archive", "quick_avatar": "portrait_generation", "quick_bust": "halfbody_generation", "quick_stand": "fullbody_generation", "quick_sheet": "sheet_generation", "questionnaire": "profile_import", "preview": "prompt_plan", "virtual_single_image": "single_image_generation", } TEMPLATE_INTENTS: dict[str, str] = { "profile_import": "upsert_profile_fields", "persona_split": "update_structured_persona", "prompt_plan": "update_prompt_matrix", "material_bind": "update_material_bindings", "portrait_generation": "update_portrait_node", "halfbody_generation": "update_halfbody_node", "fullbody_generation": "update_fullbody_node", "sheet_generation": "update_design_sheet_node", "pose_generation": "update_pose_sheet_node", "stage_review": "review_stage_candidate", "candidate_review": "review_candidates", "hires_fix": "update_final_refinement", "archive": "archive_character_workflow", "single_image_generation": "single_image_generation", "generic_workflow_node": "update_current_node", } EXPECTED_RESPONSE_SCHEMAS: dict[str, dict[str, Any]] = { "profile_import": { "intent": "upsert_profile_fields", "target_language": "zh-CN", "profile_patch": { "name": "string?", "identity": "string?", "personality": "string?", "appearance": "string?", "outfit": "string?", "style": "string?", "negative": "string?", }, "missing_fields": ["string"], "conflicts": ["string"], "next_action": "refresh_profile_import | ask_user | enter_persona_split", }, "persona_split": { "intent": "update_structured_persona", "split_fields_patch": { "identity": "string?", "appearance": "string?", "outfit": "string?", "materials": "string?", "guardrails": "string?", }, "locked_fields": ["string"], "conflicts": ["string"], "next_action": "refresh_persona_split | enter_prompt_plan", }, "prompt_plan": { "intent": "update_prompt_matrix", "schema_version": "2026-07-09.prompt-plan-schema.v1", "target_language": "en", "matrix": [ { "target_id": "portrait | bust | fullbody | sheet | all", "target_node_keys": ["headshot | upper_body | lower_body | full_body | turnaround | design_sheet"], "positive_patch": "string", "negative_patch": "string?", "weight_suggestions": [{"label": "string", "value": "number?", "reason": "string"}], "weight_basis": "string", "inheritance_fields": ["string"], "inheritance_changes": ["string"], "conflicts": ["string"], "status": "ready | review | pending", } ], "guardrails": { "negative_prompt": "string", "checks": [{"key": "string", "label": "string", "value": "string", "status": "ready | review | pending"}], }, "conflicts": [{"target_id": "string", "message": "string", "severity": "info | warn | error"}], "next_action": "refresh_prompt_plan | enter_material_bind", }, "material_bind": { "intent": "update_material_bindings", "schema_version": "2026-07-09.material-binding-schema.v1", "reference_policy": { "mode": "explicit_only", "default_use_reference": False, "empty_material_means": "do_not_use_reference", }, "bindings": [ { "material_category": "style | composition | clothing | socks | shoes | accessory | other", "bind_to_stages": [{"stage_id": "string", "stage_title": "string"}], "target_node_keys": ["headshot | upper_body | lower_body | full_body | turnaround | design_sheet | style_lock"], "inheritance_rule": "string", "reference_strength": "string?", "use_reference": "boolean", "expand_to_nodes_later": True, } ], "conflicts": ["string"], "next_action": "refresh_material_bind | enter_draft_generation", }, "portrait_generation": { "intent": "update_portrait_node", "target_language": "en", "prompt_patch": "string", "negative_patch": "string?", "face_locks": ["face shape | hairstyle | hair color | eye color | expression"], "generation_params": {"count": "number?", "aspect_ratio": "1:1", "reference_strength": "string?"}, "next_action": "generate_portrait | rerun_portrait | confirm_use | ask_user", }, "halfbody_generation": { "intent": "update_halfbody_node", "target_language": "en", "prompt_patch": "string", "negative_patch": "string?", "inherited_locks": ["portrait baseline | face | hair | eye direction"], "outfit_patch": "string?", "pose_patch": "string?", "generation_params": {"count": "number?", "aspect_ratio": "3:4", "reference_strength": "string?"}, "next_action": "generate_halfbody | rerun_halfbody | confirm_use | ask_user", }, "fullbody_generation": { "intent": "update_fullbody_node", "target_language": "en", "prompt_patch": "string", "negative_patch": "string?", "proportion_locks": ["head ratio | body proportion | outfit silhouette | shoes and socks"], "accessory_requirements": ["string"], "generation_params": {"count": "number?", "aspect_ratio": "2:3", "reference_strength": "string?"}, "next_action": "generate_fullbody | rerun_fullbody | confirm_use | ask_user", }, "sheet_generation": { "intent": "update_design_sheet_node", "target_language": "en", "prompt_patch": "string", "negative_patch": "string?", "sheet_layout": "front view | detail callouts | expression set | material labels", "inherited_locks": ["portrait | halfbody | fullbody | detail nodes"], "next_action": "generate_sheet | rerun_sheet | confirm_use | ask_user", }, "pose_generation": { "intent": "update_pose_sheet_node", "target_language": "en", "prompt_patch": "string", "negative_patch": "string?", "pose_targets": ["standing | action | hand pose | prop interaction"], "inherited_locks": ["identity | outfit | style"], "next_action": "generate_pose_sheet | rerun_pose_sheet | ask_user", }, "stage_review": { "intent": "review_stage_candidate", "target_language": "en", "review_stage": "portrait | halfbody | body_sheet", "same_prompt_regeneration": True, "primary_image_id": "string?", "selected_image_ids": ["string"], "model_route_notes": ["string"], "defects_to_regenerate": ["string"], "locked_items": ["string"], "selection_reason": "string", "next_action": "regenerate_selected_image | confirm_next_flow | ask_user", }, "candidate_review": { "intent": "review_candidates", "review_dimensions": [ "identity consistency", "outfit inheritance", "style consistency", "image defects", "policy/negative constraints", ], "primary_image_id": "string?", "selected_image_ids": ["string"], "reject_image_ids": ["string"], "selection_reason": "string", "next_round_direction": "string", "next_action": "select_candidate | regenerate_node | enter_hires_fix", }, "hires_fix": { "intent": "update_final_refinement", "target_language": "en", "prompt_patch": "string", "defects_to_fix": ["string"], "keep_locked_items": ["string"], "next_action": "regenerate_hires | enter_archive", }, "archive": { "intent": "archive_character_workflow", "archive_summary": "string", "reusable_tags": ["string"], "version_note": "string", "next_action": "save_archive | ask_user", }, "single_image_generation": { "intent": "single_image_generation", "target_language": "en", "prompt_patch": "string", "negative_patch": "string?", "generation_params": {"count": "number?", "aspect_ratio": "string?"}, "next_action": "generate_image | ask_user", }, "generic_workflow_node": { "intent": "update_current_node", "target_language": "en", "prompt_patch": "string", "metadata_patch": "object", "next_action": "refresh_current_node | ask_user", }, } CONTEXT_REQUIREMENTS: dict[str, list[str]] = { "profile_import": ["user_instruction", "current_profile", "source_language"], "persona_split": ["user_instruction", "current_profile", "structured_persona_fields"], "prompt_plan": ["user_instruction", "structured_persona_fields", "material_bindings"], "material_bind": ["user_instruction", "available_materials", "target_stage_ids"], "portrait_generation": ["user_instruction", "current_profile", "material_bindings"], "halfbody_generation": ["user_instruction", "upstream_selected_images", "material_bindings"], "fullbody_generation": ["user_instruction", "upstream_selected_images", "material_bindings"], "sheet_generation": ["user_instruction", "upstream_selected_images", "material_bindings"], "pose_generation": ["user_instruction", "upstream_selected_images", "material_bindings"], "stage_review": ["user_instruction", "selected_draft_image_ids", "upstream_selected_images"], "candidate_review": ["user_instruction", "selected_draft_image_ids", "review_policy"], "hires_fix": ["user_instruction", "stage_inputs", "upstream_selected_images"], "archive": ["user_instruction", "accepted_images", "workflow_history"], "single_image_generation": ["user_instruction", "current_profile"], "generic_workflow_node": ["user_instruction", "node_context"], } def template_kind_for_node(node: WorkflowNode, requested_kind: str | None = None) -> str: normalized = str(requested_kind or "").strip() if normalized in EXPECTED_RESPONSE_SCHEMAS: return normalized return NODE_KEY_TEMPLATE_KINDS.get( canonical_gradual_node_key(node.node_key), "generic_workflow_node", ) def build_node_injection_contract( node: WorkflowNode, *, requested_kind: str | None = None, user_instruction: str | None = None, dependency_context: dict[str, Any] | None = None, material_bindings: Any | None = None, prompt_plan: Any | None = None, stage_inputs: Any | None = None, selected_draft_image_ids: list[str] | None = None, ui_context: dict[str, Any] | None = None, ) -> dict[str, Any]: kind = template_kind_for_node(node, requested_kind) dependency_context = dependency_context if isinstance(dependency_context, dict) else {} return { "version": NODE_INJECTION_TEMPLATE_VERSION, "template_kind": kind, "node_key": node.node_key, "node_id": node.node_id, "intent": TEMPLATE_INTENTS.get(kind, TEMPLATE_INTENTS["generic_workflow_node"]), "language_policy": { "source_language": "auto", "target_prompt_language": "en", "translation_mode": "backend_llm", "preserve_character_names": True, }, "user_instruction": { "raw_text": str(user_instruction or "").strip(), "source_language": "auto", }, "node_context": { "title": node.title, "step_name": node.step_name, "node_type": node.node_type, "status": node.status, "prompt": node.prompt, "negative_prompt": node.negative_prompt, "selected_image_id": node.selected_image_id, "metadata": node.metadata, }, "dependency_context": { "dependency_count": dependency_context.get("dependency_count", 0), "prompt_context": dependency_context.get("prompt_context", ""), "selected_image_ids": dependency_context.get("selected_image_ids", []), "dependencies": dependency_context.get("dependencies", []), }, "material_bindings": material_bindings if material_bindings is not None else [], "prompt_plan": prompt_plan if prompt_plan is not None else {}, "stage_inputs": stage_inputs if stage_inputs is not None else {}, "selected_draft_image_ids": selected_draft_image_ids or [], "ui_context": ui_context or {}, "context_requirements": CONTEXT_REQUIREMENTS.get(kind, CONTEXT_REQUIREMENTS["generic_workflow_node"]), "expected_response_schema": deepcopy( EXPECTED_RESPONSE_SCHEMAS.get(kind, EXPECTED_RESPONSE_SCHEMAS["generic_workflow_node"]) ), "prompt_contract": [ "Understand the user's source-language instruction.", "Translate user-facing edits into concise English image-generation prompt language.", "Preserve locked identity traits, selected upstream images, material bindings, and negative constraints.", "Return a JSON-compatible object matching expected_response_schema.", "If the target node is locked, return a branch-required next_action instead of mutating the original chain.", ], } def injection_payload_from_generation_request(payload: dict[str, Any]) -> dict[str, Any]: metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {} user_instruction = ( metadata.get("user_instruction") or payload.get("user_instruction") or payload.get("prompt_patch") or payload.get("extra_prompt") or "" ) return { "requested_kind": metadata.get("node_injection_kind") or payload.get("node_injection_kind"), "user_instruction": str(user_instruction or ""), "material_bindings": metadata.get("material_binding_rules") or payload.get("material_bindings") or [], "stage_inputs": metadata.get("stage_inputs") or payload.get("stage_inputs") or {}, "selected_draft_image_ids": _string_list( metadata.get("selected_draft_image_ids") or payload.get("selected_draft_image_ids") ), "ui_context": { "ui_node_id": metadata.get("ui_node_id"), "ui_node_title": metadata.get("ui_node_title"), "ui_node_phase": metadata.get("ui_node_phase"), "review_source_ui_node_id": metadata.get("review_source_ui_node_id"), "review_next_ui_node_id": metadata.get("review_next_ui_node_id"), }, } def _string_list(value: Any) -> list[str]: if not isinstance(value, list): return [] return [str(item) for item in value if str(item or "").strip()]