2026-07-06 01:47:45 +08:00
|
|
|
"""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
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
from core.remote_fetch import RemoteFetchError, read_http_response_limited, validate_http_url
|
|
|
|
|
|
2026-07-06 01:47:45 +08:00
|
|
|
|
|
|
|
|
JsonDict = dict[str, Any]
|
|
|
|
|
HttpTransport = Callable[[str, JsonDict, dict[str, str], int], JsonDict]
|
2026-07-11 21:50:34 +08:00
|
|
|
MAX_PROVIDER_IMAGE_BYTES = 25 * 1024 * 1024
|
|
|
|
|
MAX_PROVIDER_IMAGE_COUNT = 8
|
|
|
|
|
MAX_PROVIDER_JSON_BASE_OVERHEAD_BYTES = 1024 * 1024
|
|
|
|
|
MAX_PROVIDER_JSON_PER_IMAGE_OVERHEAD_BYTES = 128 * 1024
|
|
|
|
|
# Decoding JSON temporarily retains the response bytes, decoded text, and
|
|
|
|
|
# parsed base64 strings. Keep the aggregate response bounded even when eight
|
|
|
|
|
# images are requested; individual images still receive their full 25 MiB cap.
|
|
|
|
|
MAX_PROVIDER_JSON_HARD_BYTES = 128 * 1024 * 1024
|
|
|
|
|
MAX_PROVIDER_ERROR_BYTES = 64 * 1024
|
2026-07-06 01:47:45 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
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)
|
2026-07-11 21:50:34 +08:00
|
|
|
supports_negative_prompt: bool = True
|
2026-07-06 01:47:45 +08:00
|
|
|
|
|
|
|
|
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
|
2026-07-11 21:50:34 +08:00
|
|
|
negative_prompt: str | None = None
|
2026-07-06 01:47:45 +08:00
|
|
|
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),
|
2026-07-11 21:50:34 +08:00
|
|
|
"response_format": "b64_json",
|
2026-07-06 01:47:45 +08:00
|
|
|
}
|
|
|
|
|
if request.input_images:
|
|
|
|
|
payload["image"] = list(request.input_images)
|
2026-07-11 21:50:34 +08:00
|
|
|
if self.config.supports_negative_prompt and (negative_prompt := _optional_text(request.negative_prompt)):
|
|
|
|
|
payload["negative_prompt"] = negative_prompt
|
2026-07-06 01:47:45 +08:00
|
|
|
headers = {
|
|
|
|
|
"Content-Type": "application/json",
|
2026-07-11 21:50:34 +08:00
|
|
|
**({"Authorization": f"Bearer {self.config.api_key}"} if self.config.api_key else {}),
|
2026-07-06 01:47:45 +08:00
|
|
|
**self.config.extra_headers,
|
|
|
|
|
}
|
2026-07-06 02:14:13 +08:00
|
|
|
try:
|
|
|
|
|
response = self._transport(self.config.endpoint_url(), payload, headers, self.config.timeout_seconds)
|
|
|
|
|
except ImageProviderError as exc:
|
|
|
|
|
if exc.provider_id != "unknown":
|
|
|
|
|
raise
|
|
|
|
|
raise ImageProviderError(
|
|
|
|
|
str(exc),
|
|
|
|
|
provider_id=self.provider_id,
|
|
|
|
|
status_code=exc.status_code,
|
|
|
|
|
error_type=exc.error_type,
|
|
|
|
|
details=exc.details,
|
|
|
|
|
) from exc
|
2026-07-11 21:50:34 +08:00
|
|
|
return _parse_image_response(
|
|
|
|
|
self.provider_id,
|
|
|
|
|
model,
|
|
|
|
|
response,
|
|
|
|
|
provider_base_url=self.config.base_url,
|
|
|
|
|
)
|
2026-07-06 01:47:45 +08:00
|
|
|
|
|
|
|
|
|
2026-07-11 22:31:53 +08:00
|
|
|
class FallbackImageProvider:
|
|
|
|
|
"""Try configured image providers in priority order on provider failures."""
|
|
|
|
|
|
|
|
|
|
def __init__(self, providers: list[ImageProvider]):
|
|
|
|
|
if not providers:
|
|
|
|
|
raise ValueError("at least one image provider is required")
|
|
|
|
|
self.providers = providers
|
|
|
|
|
self.provider_id = providers[0].provider_id
|
|
|
|
|
|
|
|
|
|
def generate_image(self, request: ImageGenerationRequest) -> ImageGenerationResult:
|
|
|
|
|
failures: list[dict[str, Any]] = []
|
|
|
|
|
for provider in self.providers:
|
|
|
|
|
try:
|
|
|
|
|
result = provider.generate_image(request)
|
|
|
|
|
return ImageGenerationResult(
|
|
|
|
|
provider_id=result.provider_id,
|
|
|
|
|
model=result.model,
|
|
|
|
|
images=result.images,
|
|
|
|
|
usage=result.usage,
|
|
|
|
|
raw_metadata={**result.raw_metadata, "fallback_attempts": failures},
|
|
|
|
|
)
|
|
|
|
|
except ImageProviderError as exc:
|
|
|
|
|
failures.append({"provider_id": provider.provider_id, "error_type": exc.error_type, "status_code": exc.status_code})
|
|
|
|
|
raise ImageProviderError(
|
|
|
|
|
"all configured image providers failed",
|
|
|
|
|
provider_id=self.provider_id,
|
|
|
|
|
error_type="provider_pool_exhausted",
|
|
|
|
|
details={"attempts": failures},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
|
2026-07-06 01:47:45 +08:00
|
|
|
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:
|
2026-07-11 21:50:34 +08:00
|
|
|
try:
|
|
|
|
|
validate_http_url(url, allow_private=True)
|
|
|
|
|
except RemoteFetchError as exc:
|
|
|
|
|
raise ImageProviderError(
|
|
|
|
|
"image provider endpoint is invalid",
|
|
|
|
|
provider_id="unknown",
|
|
|
|
|
error_type="configuration_error",
|
|
|
|
|
details={"reason": str(exc)},
|
|
|
|
|
) from exc
|
2026-07-06 01:47:45 +08:00
|
|
|
data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
|
|
|
|
|
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
|
|
|
|
|
try:
|
2026-07-11 21:50:34 +08:00
|
|
|
body = read_http_response_limited(
|
|
|
|
|
request,
|
|
|
|
|
timeout_seconds=timeout_seconds,
|
|
|
|
|
max_bytes=_provider_json_limit(payload.get("n", 1)),
|
|
|
|
|
allow_private=True,
|
|
|
|
|
same_origin_redirects_only=True,
|
|
|
|
|
).decode("utf-8-sig")
|
2026-07-06 01:47:45 +08:00
|
|
|
except urllib.error.HTTPError as exc:
|
2026-07-11 21:50:34 +08:00
|
|
|
body = exc.read(MAX_PROVIDER_ERROR_BYTES + 1).decode("utf-8", errors="replace")
|
2026-07-06 01:47:45 +08:00
|
|
|
raise ImageProviderError(
|
|
|
|
|
"image provider returned an HTTP error",
|
|
|
|
|
provider_id="unknown",
|
|
|
|
|
status_code=exc.code,
|
|
|
|
|
error_type="http_error",
|
2026-07-11 21:50:34 +08:00
|
|
|
details={"body_preview": body[:500], "body_truncated": len(body) > MAX_PROVIDER_ERROR_BYTES},
|
2026-07-06 01:47:45 +08:00
|
|
|
) 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
|
2026-07-11 21:50:34 +08:00
|
|
|
except (RemoteFetchError, UnicodeDecodeError) as exc:
|
|
|
|
|
raise ImageProviderError(
|
|
|
|
|
"image provider response exceeded safety limits",
|
|
|
|
|
provider_id="unknown",
|
|
|
|
|
error_type="invalid_response",
|
|
|
|
|
details={"reason": str(exc)},
|
|
|
|
|
) from exc
|
2026-07-06 01:47:45 +08:00
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
def _parse_image_response(
|
|
|
|
|
provider_id: str,
|
|
|
|
|
model: str,
|
|
|
|
|
response: JsonDict,
|
|
|
|
|
*,
|
|
|
|
|
provider_base_url: str | None = None,
|
|
|
|
|
) -> ImageGenerationResult:
|
2026-07-06 01:47:45 +08:00
|
|
|
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()),
|
2026-07-11 21:50:34 +08:00
|
|
|
"provider_base_url": provider_base_url,
|
2026-07-06 01:47:45 +08:00
|
|
|
},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
|
2026-07-11 21:50:34 +08:00
|
|
|
return min(max(count, 1), MAX_PROVIDER_IMAGE_COUNT)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _provider_json_limit(requested_count: Any) -> int:
|
|
|
|
|
"""Bound a base64 JSON response according to the requested image count."""
|
|
|
|
|
|
|
|
|
|
count = _bounded_count(requested_count)
|
|
|
|
|
base64_bytes_per_image = ((MAX_PROVIDER_IMAGE_BYTES + 2) // 3) * 4
|
|
|
|
|
calculated = (
|
|
|
|
|
MAX_PROVIDER_JSON_BASE_OVERHEAD_BYTES
|
|
|
|
|
+ count * (base64_bytes_per_image + MAX_PROVIDER_JSON_PER_IMAGE_OVERHEAD_BYTES)
|
|
|
|
|
)
|
|
|
|
|
return min(calculated, MAX_PROVIDER_JSON_HARD_BYTES)
|
2026-07-06 01:47:45 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
def _optional_text(value: Any) -> str | None:
|
|
|
|
|
text = str(value or "").strip()
|
|
|
|
|
return text or None
|