diff --git a/engines/__init__.py b/engines/__init__.py index 88eecfc..039a023 100644 --- a/engines/__init__.py +++ b/engines/__init__.py @@ -1 +1,21 @@ """ImageStudio workflow engines.""" + +from engines.image_provider import ( + GeneratedImagePayload, + ImageGenerationRequest, + ImageGenerationResult, + ImageProviderConfig, + ImageProviderError, + MockImageProvider, + OpenAIImageProvider, +) + +__all__ = [ + "GeneratedImagePayload", + "ImageGenerationRequest", + "ImageGenerationResult", + "ImageProviderConfig", + "ImageProviderError", + "MockImageProvider", + "OpenAIImageProvider", +] diff --git a/engines/image_provider.py b/engines/image_provider.py new file mode 100644 index 0000000..e8c98ac --- /dev/null +++ b/engines/image_provider.py @@ -0,0 +1,222 @@ +"""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 diff --git a/tests/test_image_provider.py b/tests/test_image_provider.py new file mode 100644 index 0000000..65520fe --- /dev/null +++ b/tests/test_image_provider.py @@ -0,0 +1,77 @@ +from __future__ import annotations + +import unittest + +from engines.image_provider import ( + ImageGenerationRequest, + ImageProviderConfig, + ImageProviderError, + MockImageProvider, + OpenAIImageProvider, +) + + +class ImageProviderTests(unittest.TestCase): + def test_openai_image_provider_normalizes_generation_response(self): + calls = [] + + def transport(url, payload, headers, timeout): + calls.append((url, payload, headers, timeout)) + return { + "created": 1783268032, + "data": [ + { + "b64_json": "aW1hZ2U=", + "url": "https://example.test/image.png", + "revised_prompt": "red dot", + } + ], + "usage": {"total_tokens": 12}, + } + + provider = OpenAIImageProvider( + ImageProviderConfig( + provider_id="site_b", + base_url="https://botcf.com", + api_key="secret", + image_model="image2", + timeout_seconds=180, + ), + transport=transport, + ) + + result = provider.generate_image( + ImageGenerationRequest( + prompt="red dot", + input_images=("https://example.test/input.jpg",), + ) + ) + + self.assertTrue(result.has_images) + self.assertEqual(result.provider_id, "site_b") + self.assertEqual(result.model, "image2") + self.assertEqual(result.usage["total_tokens"], 12) + self.assertEqual(result.images[0].b64_json, "aW1hZ2U=") + self.assertEqual(result.images[0].url, "https://example.test/image.png") + self.assertEqual(calls[0][0], "https://botcf.com/v1/images/generations") + self.assertEqual(calls[0][1]["model"], "image2") + self.assertEqual(calls[0][1]["image"], ["https://example.test/input.jpg"]) + self.assertEqual(calls[0][3], 180) + + def test_provider_requires_model(self): + provider = OpenAIImageProvider(ImageProviderConfig(provider_id="missing", base_url="https://example.test")) + + with self.assertRaises(ImageProviderError) as raised: + provider.generate_image(ImageGenerationRequest(prompt="red dot")) + + self.assertEqual(raised.exception.error_type, "configuration_error") + + def test_mock_provider_returns_image_payload(self): + result = MockImageProvider().generate_image(ImageGenerationRequest(prompt="red dot", model="mock")) + + self.assertTrue(result.has_images) + self.assertEqual(result.images[0].revised_prompt, "red dot") + + +if __name__ == "__main__": + unittest.main()