"""Image provider adapter interfaces. The provider layer keeps remote model details outside workflow orchestration. Concrete adapters return normalized image payloads that later stages can persist through VFS without exposing local paths. """ from __future__ import annotations import json import urllib.error import urllib.request from dataclasses import dataclass, field from typing import Any, Callable, Protocol JsonDict = dict[str, Any] HttpTransport = Callable[[str, JsonDict, dict[str, str], int], JsonDict] class ImageProvider(Protocol): provider_id: str def generate_image(self, request: "ImageGenerationRequest") -> "ImageGenerationResult": ... @dataclass(frozen=True) class ImageProviderConfig: provider_id: str base_url: str api_key: str = "" image_model: str = "" image_endpoint: str = "/v1/images/generations" provider_type: str = "openai_compatible" timeout_seconds: int = 180 extra_headers: dict[str, str] = field(default_factory=dict) def endpoint_url(self) -> str: base = self.base_url.rstrip("/") endpoint = self.image_endpoint if self.image_endpoint.startswith("/") else f"/{self.image_endpoint}" return f"{base}{endpoint}" @dataclass(frozen=True) class ImageGenerationRequest: prompt: str model: str | None = None size: str = "1024x1024" count: int = 1 input_images: tuple[str, ...] = () metadata: dict[str, Any] = field(default_factory=dict) @dataclass(frozen=True) class GeneratedImagePayload: b64_json: str | None = None url: str | None = None revised_prompt: str | None = None metadata: dict[str, Any] = field(default_factory=dict) @property def has_image_data(self) -> bool: return bool(self.b64_json or self.url) @dataclass(frozen=True) class ImageGenerationResult: provider_id: str model: str images: list[GeneratedImagePayload] usage: dict[str, Any] = field(default_factory=dict) raw_metadata: dict[str, Any] = field(default_factory=dict) @property def has_images(self) -> bool: return any(image.has_image_data for image in self.images) class ImageProviderError(RuntimeError): def __init__( self, message: str, *, provider_id: str, status_code: int | None = None, error_type: str = "provider_error", details: dict[str, Any] | None = None, ): super().__init__(message) self.provider_id = provider_id self.status_code = status_code self.error_type = error_type self.details = details or {} class OpenAIImageProvider: def __init__(self, config: ImageProviderConfig, transport: HttpTransport | None = None): self.config = config self.provider_id = config.provider_id self._transport = transport or _post_json def generate_image(self, request: ImageGenerationRequest) -> ImageGenerationResult: model = request.model or self.config.image_model if not model: raise ImageProviderError( "image model is required", provider_id=self.provider_id, error_type="configuration_error", ) payload: JsonDict = { "model": model, "prompt": request.prompt, "size": request.size, "n": _bounded_count(request.count), } if request.input_images: payload["image"] = list(request.input_images) headers = { "Authorization": f"Bearer {self.config.api_key}", "Content-Type": "application/json", **self.config.extra_headers, } response = self._transport(self.config.endpoint_url(), payload, headers, self.config.timeout_seconds) return _parse_image_response(self.provider_id, model, response) class MockImageProvider: provider_id = "mock" def generate_image(self, request: ImageGenerationRequest) -> ImageGenerationResult: return ImageGenerationResult( provider_id=self.provider_id, model=request.model or "mock-image", images=[ GeneratedImagePayload( b64_json="iVBORw0KGgo=", revised_prompt=request.prompt, metadata={"mock": True}, ) ], raw_metadata={"mock": True}, ) def _post_json(url: str, payload: JsonDict, headers: dict[str, str], timeout_seconds: int) -> JsonDict: data = json.dumps(payload, ensure_ascii=False).encode("utf-8") request = urllib.request.Request(url, data=data, headers=headers, method="POST") try: with urllib.request.urlopen(request, timeout=timeout_seconds) as response: body = response.read().decode("utf-8-sig") except urllib.error.HTTPError as exc: body = exc.read().decode("utf-8", errors="replace") raise ImageProviderError( "image provider returned an HTTP error", provider_id="unknown", status_code=exc.code, error_type="http_error", details={"body_preview": body[:500]}, ) from exc except urllib.error.URLError as exc: raise ImageProviderError( "image provider network error", provider_id="unknown", error_type="network_error", details={"reason": str(exc.reason)}, ) from exc try: parsed = json.loads(body) except json.JSONDecodeError as exc: raise ImageProviderError( "image provider returned invalid JSON", provider_id="unknown", error_type="invalid_response", details={"body_preview": body[:500]}, ) from exc if not isinstance(parsed, dict): raise ImageProviderError("image provider response must be an object", provider_id="unknown") return parsed def _parse_image_response(provider_id: str, model: str, response: JsonDict) -> ImageGenerationResult: data = response.get("data", []) if not isinstance(data, list): raise ImageProviderError( "image provider response data must be a list", provider_id=provider_id, error_type="invalid_response", ) images = [_parse_image_payload(item) for item in data if isinstance(item, dict)] return ImageGenerationResult( provider_id=provider_id, model=model, images=images, usage=dict(response.get("usage") or {}), raw_metadata={ "created": response.get("created"), "response_keys": sorted(str(key) for key in response.keys()), }, ) def _parse_image_payload(item: JsonDict) -> GeneratedImagePayload: return GeneratedImagePayload( b64_json=_optional_text(item.get("b64_json") or item.get("base64") or item.get("image_base64")), url=_optional_text(item.get("url") or item.get("image_url")), revised_prompt=_optional_text(item.get("revised_prompt")), metadata={key: value for key, value in item.items() if key not in {"b64_json", "base64", "image_base64"}}, ) def _bounded_count(value: int) -> int: try: count = int(value) except (TypeError, ValueError): count = 1 return min(max(count, 1), 8) def _optional_text(value: Any) -> str | None: text = str(value or "").strip() return text or None