"""Single-image workflow engine with an explicit development mock mode.""" from __future__ import annotations import base64 import binascii import re from dataclasses import dataclass from pathlib import Path from typing import Any, Callable from backend.dto.job_dto import GenerationTask from backend.dto.workflow_dto import WorkflowNode from core.generation_errors import provider_failure_attribution from core.image_formats import ImageFormat, detect_image_format from core.remote_fetch import RemoteFetchError, read_http_response_limited, url_hostname from core.storage import VfsStorage from engines.image_provider import ( MAX_PROVIDER_IMAGE_BYTES, ImageGenerationRequest, ImageProvider, ImageProviderError, ) ONE_PIXEL_PNG = base64.b64decode( "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=" ) @dataclass(frozen=True) class MockGeneratedAsset: image_uri: str thumbnail_uri: str positive_prompt: str negative_prompt: str | None model_route: str | None width: int height: int seed: int metadata: dict[str, Any] class SingleFlowEngine: def __init__( self, storage: VfsStorage | None = None, image_provider_factory: Callable[[dict[str, Any]], ImageProvider | None] | None = None, *, allow_mock_fallback: bool = False, ): self.storage = storage or VfsStorage() self.image_provider_factory = image_provider_factory self.allow_mock_fallback = allow_mock_fallback def generate(self, node: WorkflowNode, task: GenerationTask, request: dict[str, Any]) -> list[MockGeneratedAsset]: count = _bounded_count(request.get("count", 1)) prompt = _optional_text(request.get("expanded_prompt")) or _compose_prompt(node.prompt, request.get("prompt_patch")) negative_prompt = _optional_text(request.get("expanded_negative_prompt")) or _optional_text(node.negative_prompt) model_route = str(request.get("model_route") or node.model_route or "image_low") width, height = _dimensions(str(request.get("aspect_ratio") or "1:1")) provider = self._image_provider(request) if provider is not None: try: return self._generate_with_provider( provider, task, request, prompt, negative_prompt, model_route, width, height, count, ) except ImageProviderError as exc: if not self.allow_mock_fallback: raise route = request.get("resolved_model_route") if isinstance(request.get("resolved_model_route"), dict) else {} return self._generate_mock( task, request, prompt, negative_prompt, model_route, width, height, count, provider_error=provider_failure_attribution(exc, route_context=route, fallback_used=True), ) if self.allow_mock_fallback: return self._generate_mock(task, request, prompt, negative_prompt, model_route, width, height, count) route = request.get("resolved_model_route") if isinstance(request.get("resolved_model_route"), dict) else {} raise ImageProviderError( "no usable image provider is configured for this model route", provider_id=str(route.get("provider_id") or "unresolved"), error_type="configuration_error", details={"model_route": model_route}, ) def _generate_mock( self, task: GenerationTask, request: dict[str, Any], prompt: str, negative_prompt: str | None, model_route: str, width: int, height: int, count: int, *, provider_error: dict[str, Any] | None = None, ) -> list[MockGeneratedAsset]: assets: list[MockGeneratedAsset] = [] for index in range(count): seed = int(request.get("seed") or 1000 + index) image_uri, thumbnail_uri = _output_uris(task, request, index, ".png") self._write_png(image_uri) self._write_png(thumbnail_uri) assets.append( MockGeneratedAsset( image_uri=image_uri, thumbnail_uri=thumbnail_uri, positive_prompt=prompt, negative_prompt=negative_prompt, model_route=model_route, width=width, height=height, seed=seed, metadata={ "engine": "single_flow_mock", "quality": request.get("quality", "low"), "mock": True, **_output_scope_metadata(request), **({"provider_error": provider_error} if provider_error else {}), }, ) ) return assets def _generate_with_provider( self, provider: ImageProvider, task: GenerationTask, request: dict[str, Any], prompt: str, negative_prompt: str | None, model_route: str, width: int, height: int, count: int, ) -> list[MockGeneratedAsset]: route = dict(request.get("resolved_model_route") or {}) result = provider.generate_image( ImageGenerationRequest( prompt=prompt, negative_prompt=negative_prompt, model=str(route.get("model_id") or model_route), size=f"{width}x{height}", count=count, input_images=_normalize_input_images(request.get("input_images") or request.get("image")), metadata={"task_id": task.task_id, "model_route": model_route}, ) ) assets: list[MockGeneratedAsset] = [] for index, image in enumerate(result.images): if not image.has_image_data: continue image_bytes = _image_bytes( image.b64_json, image.url, provider_id=result.provider_id, provider_base_url=str(result.raw_metadata.get("provider_base_url") or ""), ) image_format = _require_image_format(image_bytes, provider_id=result.provider_id) image_uri, thumbnail_uri = _output_uris(task, request, index, image_format.extension) self._write_image(image_uri, image_bytes) self._write_image(thumbnail_uri, image_bytes) assets.append( MockGeneratedAsset( image_uri=image_uri, thumbnail_uri=thumbnail_uri, positive_prompt=image.revised_prompt or prompt, negative_prompt=negative_prompt, model_route=model_route, width=width, height=height, seed=int(request.get("seed") or 1000 + index), metadata={ "engine": "single_flow_provider", "mock": False, "provider_id": result.provider_id, "provider_model": result.model, "usage": result.usage, "source_url": image.url, "content_type": image_format.mime_type, "file_extension": image_format.extension, **_output_scope_metadata(request), }, ) ) if not assets: raise ImageProviderError( "image provider returned no usable image payloads", provider_id=result.provider_id, error_type="invalid_response", ) return assets def _write_png(self, uri: str, content: bytes = ONE_PIXEL_PNG) -> None: self._write_image(uri, content) def _write_image(self, uri: str, content: bytes) -> None: path = self.storage.resolve_uri(uri) Path(path).parent.mkdir(parents=True, exist_ok=True) Path(path).write_bytes(content) def _image_provider(self, request: dict[str, Any]) -> ImageProvider | None: if not self.image_provider_factory: return None route = request.get("resolved_model_route") if isinstance(request.get("resolved_model_route"), dict) else {} if route.get("status") != "resolved": return None return self.image_provider_factory(route) def _bounded_count(value: Any) -> int: try: count = int(value) except (TypeError, ValueError): count = 1 return min(max(count, 1), 8) def _compose_prompt(base_prompt: str | None, prompt_patch: Any) -> str: parts = [part.strip() for part in [base_prompt, str(prompt_patch or "")] if part and str(part).strip()] return ", ".join(parts) if parts else "single image mock generation" def _optional_text(value: Any) -> str | None: if value is None: return None text = str(value).strip() return text or None def _dimensions(aspect_ratio: str) -> tuple[int, int]: if aspect_ratio == "3:4": return 768, 1024 if aspect_ratio == "4:3": return 1024, 768 if aspect_ratio == "16:9": return 1280, 720 return 1024, 1024 def _safe_file_stem(value: str) -> str: stem = re.sub(r"[^A-Za-z0-9_-]+", "_", str(value or "").strip()).strip("_") return stem or "task" def _output_uris( task: GenerationTask, request: dict[str, Any], index: int, extension: str, ) -> tuple[str, str]: """Return legacy or workflow-scoped storage URIs for one provider asset.""" normalized_extension = extension if str(extension).startswith(".") else f".{extension}" scope = request.get("output_scope") if isinstance(request.get("output_scope"), dict) else None task_stem = _safe_file_stem(task.task_id) if not scope or not scope.get("round_id") or not scope.get("candidate_id"): filename = f"{task_stem}_{index + 1}{normalized_extension}" return ( f"storage://images/single/{filename}", f"storage://thumbnails/single/{filename}", ) workflow_id = _safe_file_stem(str(scope.get("workflow_id") or task.workflow_id or "workflow")) branch_name = _safe_file_stem(str(scope.get("branch_id") or scope.get("branch_name") or "main")) node_key = _safe_file_stem(str(scope.get("node_key") or task.node_id or "node")) round_id = _safe_file_stem(str(scope.get("round_id"))) round_display = _safe_file_stem(str(scope.get("round_display_code") or "round")) candidate_id = _safe_file_stem(str(scope.get("candidate_id"))) candidate_display = _safe_file_stem(str(scope.get("candidate_display_code") or "candidate")) round_folder = f"{round_display}__{round_id}" filename = f"{candidate_display}__{candidate_id}__{task_stem}_{index + 1:02d}{normalized_extension}" relative = f"workflows/{workflow_id}/{branch_name}/{node_key}/{round_folder}/{filename}" return ( f"storage://images/{relative}", f"storage://thumbnails/{relative}", ) def _output_scope_metadata(request: dict[str, Any]) -> dict[str, Any]: scope = request.get("output_scope") if isinstance(request.get("output_scope"), dict) else None if not scope or not scope.get("round_id") or not scope.get("candidate_id"): return {} allowed = ( "workflow_id", "branch_id", "branch_name", "node_key", "round_id", "round_display_code", "candidate_id", "candidate_display_code", ) return { "scoped_output": True, "output_scope": { key: str(scope[key]) for key in allowed if scope.get(key) is not None and str(scope.get(key)).strip() }, } def _normalize_input_images(value: Any) -> tuple[str, ...]: if value is None: return () if isinstance(value, str): text = value.strip() return (text,) if text else () if isinstance(value, (list, tuple, set)): return tuple(text for item in value if (text := str(item).strip())) text = str(value).strip() return (text,) if text else () def _image_bytes( b64_json: str | None, url: str | None, *, provider_id: str = "unknown", provider_base_url: str | None = None, ) -> bytes: if b64_json: encoded = re.sub(r"\s+", "", b64_json) if len(encoded) > ((MAX_PROVIDER_IMAGE_BYTES + 2) // 3) * 4: raise ImageProviderError( "image provider base64 payload exceeds the size limit", provider_id=provider_id, error_type="invalid_response", ) try: body = base64.b64decode(encoded, validate=True) except (binascii.Error, ValueError) as exc: raise ImageProviderError( "image provider returned invalid base64 image data", provider_id=provider_id, error_type="invalid_response", ) from exc return _validate_image_bytes(body, provider_id=provider_id) if url: provider_host = url_hostname(provider_base_url) try: body = read_http_response_limited( url, timeout_seconds=120, max_bytes=MAX_PROVIDER_IMAGE_BYTES, allowed_private_hosts=(provider_host,) if provider_host else (), ) return _validate_image_bytes(body, provider_id=provider_id) except (OSError, RemoteFetchError) as exc: raise ImageProviderError( "image provider image URL could not be downloaded", provider_id=provider_id, error_type="network_error", details={"reason": str(exc)}, ) from exc raise ImageProviderError("image payload is empty", provider_id=provider_id, error_type="invalid_response") def _validate_image_bytes(body: bytes, *, provider_id: str) -> bytes: if not body: raise ImageProviderError("image payload is empty", provider_id=provider_id, error_type="invalid_response") if len(body) > MAX_PROVIDER_IMAGE_BYTES: raise ImageProviderError( "image provider payload exceeds the size limit", provider_id=provider_id, error_type="invalid_response", ) _require_image_format(body, provider_id=provider_id) return body def _require_image_format(body: bytes, *, provider_id: str) -> ImageFormat: image_format = detect_image_format(body) if image_format is None: raise ImageProviderError( "image provider payload is not a supported image", provider_id=provider_id, error_type="invalid_response", ) return image_format