autobyteus 1.1.5__py3-none-any.whl → 1.1.6__py3-none-any.whl

autobyteus/multimedia/audio/audio_client_factory.py

@@ -0,0 +1,120 @@
+import logging
+from typing import Dict, Optional
+
+from autobyteus.multimedia.audio.base_audio_client import BaseAudioClient
+from autobyteus.multimedia.audio.audio_model import AudioModel
+from autobyteus.multimedia.providers import MultimediaProvider
+from autobyteus.multimedia.audio.api.gemini_audio_client import GeminiAudioClient
+from autobyteus.multimedia.audio.autobyteus_audio_provider import AutobyteusAudioModelProvider
+from autobyteus.multimedia.utils.multimedia_config import MultimediaConfig
+from autobyteus.utils.singleton import SingletonMeta
+
+logger = logging.getLogger(__name__)
+
+GEMINI_TTS_VOICES = [
+    "Zephyr", "Puck", "Charon", "Kore", "Fenrir", "Leda", "Orus", "Aoede", 
+    "Callirrhoe", "Autonoe", "Enceladus", "Iapetus", "Umbriel", "Algieba", 
+    "Despina", "Erinome", "Algenib", "Rasalgethi", "Laomedeia", "Achernar", 
+    "Alnilam", "Schedar", "Gacrux", "Pulcherrima", "Achird", "Zubenelgenubi", 
+    "Vindemiatrix", "Sadachbia", "Sadaltager", "Sulafat"
+]
+
+class AudioClientFactory(metaclass=SingletonMeta):
+    """
+    A factory for creating instances of audio clients based on registered AudioModels.
+    """
+    _models_by_identifier: Dict[str, AudioModel] = {}
+    _initialized = False
+
+    @staticmethod
+    def ensure_initialized():
+        """Ensures the factory is initialized before use."""
+        if not AudioClientFactory._initialized:
+            AudioClientFactory._initialize_registry()
+            AudioClientFactory._initialized = True
+
+    @staticmethod
+    def reinitialize():
+        """Reinitializes the model registry, clearing all models and re-discovering them."""
+        logger.info("Reinitializing Audio model registry...")
+        AudioClientFactory._initialized = False
+        AudioClientFactory._models_by_identifier.clear()
+        AudioClientFactory.ensure_initialized()
+        logger.info("Audio model registry reinitialized successfully.")
+
+    @staticmethod
+    def _initialize_registry():
+        """Initializes the registry with built-in audio models."""
+        
+        # Google Gemini Audio Models
+        gemini_tts_model = AudioModel(
+            name="gemini-2.5-flash-tts",
+            value="gemini-2.5-flash-preview-tts",
+            provider=MultimediaProvider.GOOGLE,
+            client_class=GeminiAudioClient,
+            parameter_schema={
+                "mode": { 
+                    "type": "string", 
+                    "default": "single-speaker", 
+                    "allowed_values": ["single-speaker", "multi-speaker"],
+                    "description": "The speech generation mode. 'single-speaker' for a consistent voice, or 'multi-speaker' to assign different voices to speakers identified in the prompt."
+                },
+                "voice_name": { 
+                    "type": "string", 
+                    "default": "Kore",
+                    "allowed_values": GEMINI_TTS_VOICES,
+                    "description": "The voice to use for single-speaker generation."
+                },
+                "style_instructions": {
+                    "type": "string",
+                    "description": "Optional instructions on the style of speech, e.g., 'Say this in a dramatic whisper'."
+                },
+                "speaker_mapping": {
+                    "type": "object",
+                    "description": "Required for multi-speaker mode. An object mapping speaker names from the prompt (e.g., 'Joe') to a voice name (e.g., 'Puck')."
+                }
+            }
+        )
+
+        models_to_register = [
+            gemini_tts_model,
+        ]
+        
+        for model in models_to_register:
+            AudioClientFactory.register_model(model)
+        
+        logger.info("Default API-based audio models registered.")
+        
+        # Discover models from remote Autobyteus servers
+        AutobyteusAudioModelProvider.discover_and_register()
+
+    @staticmethod
+    def register_model(model: AudioModel):
+        """Registers a new audio model."""
+        identifier = model.model_identifier
+        if identifier in AudioClientFactory._models_by_identifier:
+            logger.warning(f"Audio model '{identifier}' is already registered. Overwriting.")
+        
+        if not isinstance(model.provider, MultimediaProvider):
+            try:
+                model.provider = MultimediaProvider(model.provider)
+            except ValueError:
+                logger.error(f"Cannot register model '{identifier}' with unknown provider '{model.provider}'.")
+                return
+
+        AudioClientFactory._models_by_identifier[identifier] = model
+
+    @staticmethod
+    def create_audio_client(model_identifier: str, config_override: Optional[MultimediaConfig] = None) -> BaseAudioClient:
+        """Creates an instance of a registered audio client for a specific model."""
+        AudioClientFactory.ensure_initialized()
+        
+        model = AudioClientFactory._models_by_identifier.get(model_identifier)
+        if not model:
+            raise ValueError(f"No audio model registered with the name '{model_identifier}'. "
+                             f"Available models: {list(AudioClientFactory._models_by_identifier.keys())}")
+        
+        logger.info(f"Creating instance of audio client for model '{model_identifier}'.")
+        return model.create_client(config_override)
+
+audio_client_factory = AudioClientFactory()

autobyteus/multimedia/audio/audio_model.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+import logging
+from typing import TYPE_CHECKING, Type, Optional, Iterator, Dict, Any
+from urllib.parse import urlparse
+
+from autobyteus.multimedia.providers import MultimediaProvider
+from autobyteus.multimedia.runtimes import MultimediaRuntime
+from autobyteus.multimedia.utils.multimedia_config import MultimediaConfig
+
+if TYPE_CHECKING:
+    from autobyteus.multimedia.audio.base_audio_client import BaseAudioClient
+
+logger = logging.getLogger(__name__)
+
+class AudioModelMeta(type):
+    """
+    Metaclass for AudioModel to allow discovery and access like an Enum.
+    """
+    def __iter__(cls) -> Iterator[AudioModel]:
+        from autobyteus.multimedia.audio.audio_client_factory import AudioClientFactory
+        AudioClientFactory.ensure_initialized()
+        for model in AudioClientFactory._models_by_identifier.values():
+            yield model
+
+    def __getitem__(cls, name_or_identifier: str) -> AudioModel:
+        from autobyteus.multimedia.audio.audio_client_factory import AudioClientFactory
+        AudioClientFactory.ensure_initialized()
+        model = AudioClientFactory._models_by_identifier.get(name_or_identifier)
+        if model:
+            return model
+        raise KeyError(f"Audio model '{name_or_identifier}' not found.")
+
+    def __len__(cls) -> int:
+        from autobyteus.multimedia.audio.audio_client_factory import AudioClientFactory
+        AudioClientFactory.ensure_initialized()
+        return len(AudioClientFactory._models_by_identifier)
+
+
+class AudioModel(metaclass=AudioModelMeta):
+    """
+    Represents a single audio model's metadata.
+    """
+    def __init__(
+        self,
+        name: str,
+        value: str,
+        provider: MultimediaProvider,
+        client_class: Type["BaseAudioClient"],
+        parameter_schema: Optional[Dict[str, Any]] = None,
+        runtime: MultimediaRuntime = MultimediaRuntime.API,
+        host_url: Optional[str] = None
+    ):
+        self.name = name
+        self.value = value
+        self.provider = provider
+        self.client_class = client_class
+        self.runtime = runtime
+        self.host_url = host_url
+        self.parameter_schema = parameter_schema if parameter_schema else {}
+
+        # Automatically build default_config from the schema's default values
+        default_params = {
+            key: meta.get("default")
+            for key, meta in self.parameter_schema.items()
+            if "default" in meta
+        }
+        self.default_config = MultimediaConfig(params=default_params)
+
+    @property
+    def model_identifier(self) -> str:
+        """Returns the unique identifier for the model."""
+        if self.runtime == MultimediaRuntime.AUTOBYTEUS and self.host_url:
+            try:
+                host = urlparse(self.host_url).hostname
+                return f"{self.name}@{host}"
+            except Exception:
+                return f"{self.name}@{self.host_url}" # Fallback
+        return self.name
+
+    def create_client(self, config_override: Optional[MultimediaConfig] = None) -> "BaseAudioClient":
+        """
+        Instantiates the client class for this model.
+        """
+        config_to_use = self.default_config
+        if config_override:
+            from copy import deepcopy
+            config_to_use = deepcopy(self.default_config)
+            config_to_use.merge_with(config_override)
+        
+        return self.client_class(model=self, config=config_to_use)
+
+    def __repr__(self):
+        return (
+            f"AudioModel(identifier='{self.model_identifier}', "
+            f"provider='{self.provider.name}', runtime='{self.runtime.value}')"
+        )

autobyteus/multimedia/audio/autobyteus_audio_provider.py

@@ -0,0 +1,108 @@
+import logging
+from typing import List
+import os
+from urllib.parse import urlparse
+
+from autobyteus_llm_client import AutobyteusClient
+from autobyteus.multimedia.audio.api.autobyteus_audio_client import AutobyteusAudioClient
+from autobyteus.multimedia.audio.audio_model import AudioModel
+from autobyteus.multimedia.providers import MultimediaProvider
+from autobyteus.multimedia.runtimes import MultimediaRuntime
+
+logger = logging.getLogger(__name__)
+
+class AutobyteusAudioModelProvider:
+    """
+    Discovers and registers audio models from remote Autobyteus server instances.
+    """
+    DEFAULT_SERVER_URL = 'http://localhost:8000'
+
+    @staticmethod
+    def _get_hosts() -> List[str]:
+        """Gets Autobyteus server hosts from env vars."""
+        hosts_str = os.getenv('AUTOBYTEUS_LLM_SERVER_HOSTS')
+        if hosts_str:
+            return [host.strip() for host in hosts_str.split(',')]
+        
+        legacy_host = os.getenv('AUTOBYTEUS_LLM_SERVER_URL')
+        if legacy_host:
+            return [legacy_host]
+            
+        return [AutobyteusAudioModelProvider.DEFAULT_SERVER_URL]
+
+    @staticmethod
+    def discover_and_register():
+        """Discover and register audio models from all configured hosts."""
+        try:
+            from autobyteus.multimedia.audio.audio_client_factory import AudioClientFactory
+
+            hosts = AutobyteusAudioModelProvider._get_hosts()
+            total_registered_count = 0
+
+            for host_url in hosts:
+                if not AutobyteusAudioModelProvider.is_valid_url(host_url):
+                    logger.error(f"Invalid Autobyteus host URL for audio model discovery: {host_url}, skipping.")
+                    continue
+                
+                logger.info(f"Discovering audio models from host: {host_url}")
+                client = None
+                try:
+                    client = AutobyteusClient(server_url=host_url)
+                    response = client.get_available_audio_models_sync()
+                except Exception as e:
+                    logger.warning(f"Could not fetch audio models from Autobyteus server at {host_url}: {e}")
+                    continue
+                finally:
+                    if client:
+                        client.sync_client.close()
+
+                if not response.get('models'):
+                    logger.info(f"No audio models found on host {host_url}.")
+                    continue
+
+                models = response.get('models', [])
+                host_registered_count = 0
+                for model_info in models:
+                    try:
+                        if not all(k in model_info for k in ["name", "value", "provider"]):
+                            logger.warning(f"Skipping malformed audio model from {host_url}: {model_info}")
+                            continue
+
+                        if "parameter_schema" not in model_info:
+                             logger.debug(f"Skipping model from {host_url} as it lacks a parameter schema, likely not an audio model: {model_info.get('name')}")
+                             continue
+
+                        audio_model = AudioModel(
+                            name=model_info["name"],
+                            value=model_info["value"],
+                            provider=MultimediaProvider(model_info["provider"]),
+                            client_class=AutobyteusAudioClient,
+                            runtime=MultimediaRuntime.AUTOBYTEUS,
+                            host_url=host_url,
+                            parameter_schema=model_info.get("parameter_schema")
+                        )
+                        
+                        AudioClientFactory.register_model(audio_model)
+                        host_registered_count += 1
+                        
+                    except Exception as e:
+                        logger.error(f"Failed to register audio model '{model_info.get('name')}' from {host_url}: {e}")
+                
+                if host_registered_count > 0:
+                    logger.info(f"Registered {host_registered_count} audio models from Autobyteus host {host_url}")
+                total_registered_count += host_registered_count
+            
+            if total_registered_count > 0:
+                 logger.info(f"Finished Autobyteus audio model discovery. Total models registered: {total_registered_count}")
+
+        except Exception as e:
+            logger.error(f"An unexpected error occurred during Autobyteus audio model discovery: {e}", exc_info=True)
+
+    @staticmethod
+    def is_valid_url(url: str) -> bool:
+        """Validate URL format"""
+        try:
+            result = urlparse(url)
+            return all([result.scheme, result.netloc])
+        except Exception:
+            return False

autobyteus/multimedia/audio/base_audio_client.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any, List, TYPE_CHECKING
+from autobyteus.multimedia.utils.response_types import SpeechGenerationResponse
+
+if TYPE_CHECKING:
+    from autobyteus.multimedia.audio.audio_model import AudioModel
+    from autobyteus.multimedia.utils.multimedia_config import MultimediaConfig
+
+
+class BaseAudioClient(ABC):
+    """
+    Abstract base class for audio clients that connect to models for audio generation.
+    """
+    def __init__(self, model: "AudioModel", config: "MultimediaConfig"):
+        self.model = model
+        self.config = config
+
+    @abstractmethod
+    async def generate_speech(
+        self,
+        prompt: str,
+        generation_config: Optional[Dict[str, Any]] = None
+    ) -> SpeechGenerationResponse:
+        """
+        Generates spoken audio from text (Text-to-Speech).
+
+        Args:
+            prompt (str): The text to be converted to speech.
+            generation_config (Optional[Dict[str, Any]]): Provider-specific parameters
+                                                        (e.g., voice_name, speaker_mapping).
+
+        Returns:
+            SpeechGenerationResponse: An object containing URLs or paths to the generated audio files.
+        """
+        pass
+
+    async def cleanup(self):
+        """Optional cleanup method for resources like network clients."""
+        pass

autobyteus/multimedia/image/__init__.py

@@ -0,0 +1,11 @@
+from .image_client_factory import image_client_factory, ImageClientFactory
+from .image_model import ImageModel
+from .base_image_client import BaseImageClient
+from .api import *
+
+__all__ = [
+    "image_client_factory",
+    "ImageClientFactory",
+    "ImageModel",
+    "BaseImageClient",
+]

autobyteus/multimedia/image/api/__init__.py

@@ -0,0 +1,9 @@
+from .autobyteus_image_client import AutobyteusImageClient
+from .gemini_image_client import GeminiImageClient
+from .openai_image_client import OpenAIImageClient
+
+__all__ = [
+    "AutobyteusImageClient",
+    "GeminiImageClient",
+    "OpenAIImageClient",
+]

autobyteus/multimedia/image/api/autobyteus_image_client.py

@@ -0,0 +1,97 @@
+import logging
+from typing import Optional, List, Dict, Any, TYPE_CHECKING
+from autobyteus_llm_client import AutobyteusClient
+from autobyteus.multimedia.image.base_image_client import BaseImageClient
+from autobyteus.multimedia.utils.response_types import ImageGenerationResponse
+
+if TYPE_CHECKING:
+    from autobyteus.multimedia.image.image_model import ImageModel
+    from autobyteus.multimedia.utils.multimedia_config import MultimediaConfig
+
+logger = logging.getLogger(__name__)
+
+class AutobyteusImageClient(BaseImageClient):
+    """
+    An image client that connects to an Autobyteus LLM server instance for image tasks.
+    """
+
+    def __init__(self, model: "ImageModel", config: "MultimediaConfig"):
+        super().__init__(model, config)
+        if not model.host_url:
+            raise ValueError("AutobyteusImageClient requires a host_url in its ImageModel.")
+        
+        self.autobyteus_client = AutobyteusClient(server_url=model.host_url)
+        logger.info(f"AutobyteusImageClient initialized for model '{self.model.name}' on host '{model.host_url}'.")
+
+    async def generate_image(
+        self,
+        prompt: str,
+        input_image_urls: Optional[List[str]] = None,
+        generation_config: Optional[Dict[str, Any]] = None
+    ) -> ImageGenerationResponse:
+        """
+        Generates an image by calling the generate_image endpoint on the remote Autobyteus server.
+        """
+        # The remote server handles both generation and editing through one endpoint.
+        # This method is a unified entry point.
+        return await self._call_remote_generate(
+            prompt=prompt,
+            input_image_urls=input_image_urls,
+            mask_url=None, # Not used in pure generation
+            generation_config=generation_config
+        )
+
+    async def edit_image(
+        self,
+        prompt: str,
+        input_image_urls: List[str],
+        mask_url: Optional[str] = None,
+        generation_config: Optional[Dict[str, Any]] = None
+    ) -> ImageGenerationResponse:
+        """
+        Edits an image by calling the generate_image endpoint on the remote Autobyteus server.
+        """
+        return await self._call_remote_generate(
+            prompt=prompt,
+            input_image_urls=input_image_urls,
+            mask_url=mask_url,
+            generation_config=generation_config
+        )
+    
+    async def _call_remote_generate(
+        self,
+        prompt: str,
+        input_image_urls: Optional[List[str]],
+        mask_url: Optional[str],
+        generation_config: Optional[Dict[str, Any]]
+    ) -> ImageGenerationResponse:
+        """Internal helper to call the remote server."""
+        try:
+            logger.info(f"Sending image generation request for model '{self.model.name}' to {self.model.host_url}")
+            
+            # The model name for the remote server is the `value`, not the unique `model_identifier`
+            model_name_for_server = self.model.name
+
+            response_data = await self.autobyteus_client.generate_image(
+                model_name=model_name_for_server,
+                prompt=prompt,
+                input_image_urls=input_image_urls,
+                mask_url=mask_url,
+                generation_config=generation_config
+            )
+            
+            image_urls = response_data.get("image_urls", [])
+            if not image_urls:
+                raise ValueError("Remote Autobyteus server did not return any image URLs.")
+                
+            return ImageGenerationResponse(image_urls=image_urls)
+            
+        except Exception as e:
+            logger.error(f"Error calling Autobyteus server for image generation: {e}")
+            raise
+
+    async def cleanup(self):
+        """Closes the underlying AutobyteusClient."""
+        if self.autobyteus_client:
+            await self.autobyteus_client.close()
+        logger.debug("AutobyteusImageClient cleaned up.")

autobyteus/multimedia/image/api/gemini_image_client.py

@@ -0,0 +1,188 @@
+import asyncio
+import base64
+import logging
+import mimetypes
+import os
+from typing import Optional, List, Dict, Any, TYPE_CHECKING
+
+# ✅ Legacy Gemini SDK (as requested)
+import google.generativeai as genai
+import requests
+
+from autobyteus.multimedia.image.base_image_client import BaseImageClient
+from autobyteus.multimedia.utils.response_types import ImageGenerationResponse
+
+if TYPE_CHECKING:
+    from autobyteus.multimedia.image.image_model import ImageModel
+    from autobyteus.multimedia.utils.multimedia_config import MultimediaConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _data_uri(mime_type: str, raw: bytes) -> str:
+    """Convert raw bytes to a data URI."""
+    b64 = base64.b64encode(raw).decode("utf-8")
+    return f"data:{mime_type};base64,{b64}"
+
+
+def _guess_mime_from_url(url: str) -> str:
+    """Best-effort MIME guess from URL; fall back to image/jpeg."""
+    mime, _ = mimetypes.guess_type(url)
+    return mime or "image/jpeg"
+
+
+def _fetch_image_part(url: str) -> Dict[str, Any]:
+    """
+    Download an image and return an inline-data Part compatible with the legacy SDK:
+    { "mime_type": "...", "data": <bytes> }
+    """
+    resp = requests.get(url, timeout=30)
+    resp.raise_for_status()
+    mime = resp.headers.get("Content-Type") or _guess_mime_from_url(url)
+    return {"mime_type": mime.split(";")[0], "data": resp.content}
+
+
+def _extract_inline_images(response) -> List[Dict[str, bytes]]:
+    """
+    Collect inline image parts from the legacy SDK response.
+    Returns list of { "mime_type": str, "data": bytes }.
+    """
+    images = []
+    try:
+        candidates = getattr(response, "candidates", []) or []
+        if not candidates:
+            return images
+
+        parts = candidates[0].content.parts if candidates[0].content else []
+        for p in parts:
+            inline = getattr(p, "inline_data", None)
+            if not inline:
+                continue
+            mime = getattr(inline, "mime_type", "") or ""
+            if not mime.startswith("image/"):
+                continue
+
+            data = getattr(inline, "data", None)
+            if isinstance(data, bytes):
+                images.append({"mime_type": mime, "data": data})
+            elif isinstance(data, str):
+                # Some bindings expose base64 text
+                images.append({"mime_type": mime, "data": base64.b64decode(data)})
+    except Exception as e:
+        logger.error("Failed to parse inline image(s): %s", e)
+        raise
+    return images
+
+
+class GeminiImageClient(BaseImageClient):
+    """
+    Image generation client using Google's legacy SDK (`google.generativeai`).
+
+    Notes:
+      - We configure `response_mime_type='image/png'` to request image output.
+      - You can guide generation with input images by passing URLs; they’re added as inline image Parts.
+      - This runs the blocking SDK call in a worker thread to keep your async API.
+    """
+
+    def __init__(self, model: "ImageModel", config: "MultimediaConfig"):
+        super().__init__(model, config)
+
+        api_key = os.getenv("GEMINI_API_KEY")
+        if not api_key:
+            raise ValueError("Please set the GEMINI_API_KEY environment variable.")
+
+        try:
+            genai.configure(api_key=api_key)
+            # `self.model.value` should be an image-capable model.
+            # Examples (subject to availability): "imagen-3.0-generate", "imagen-3.0-fast",
+            # or Gemini image-preview models that support image output.
+            model_name = self.model.value or "imagen-3.0-generate"
+            self._model = genai.GenerativeModel(model_name)
+            logger.info("GeminiImageClient (legacy SDK) initialized for model '%s'.", model_name)
+        except Exception as e:
+            logger.error("Failed to initialize Gemini image client: %s", e)
+            raise RuntimeError(f"Failed to initialize Gemini image client: {e}")
+
+    async def generate_image(
+        self,
+        prompt: str,
+        input_image_urls: Optional[List[str]] = None,
+        generation_config: Optional[Dict[str, Any]] = None
+    ) -> ImageGenerationResponse:
+        """
+        Generate an image (text→image or image-guided).
+
+        `generation_config` supports common fields; we always ensure
+        `response_mime_type='image/png'` so the SDK returns inline image bytes.
+        """
+        try:
+            logger.info("Generating image with model '%s'...", self._model.model_name)
+
+            # Build contents array: [text, (optional) image parts...]
+            contents: List[Any] = [prompt]
+
+            if input_image_urls:
+                logger.info("Loading %d input image(s) for guidance...", len(input_image_urls))
+                for url in input_image_urls:
+                    try:
+                        contents.append(_fetch_image_part(url))
+                    except Exception as e:
+                        logger.error("Skipping image '%s' due to error: %s", url, e)
+
+            # Merge config and force image output
+            gen_cfg: Dict[str, Any] = (generation_config or {}).copy()
+            gen_cfg["response_mime_type"] = gen_cfg.get("response_mime_type", "image/png")
+
+            # Call the (sync) SDK in a worker thread
+            response = await asyncio.to_thread(
+                self._model.generate_content,
+                contents,
+                generation_config=gen_cfg,
+            )
+
+            # Handle safety blocks if present
+            feedback = getattr(response, "prompt_feedback", None)
+            block_reason = getattr(feedback, "block_reason", None)
+            if block_reason:
+                reason = getattr(block_reason, "name", str(block_reason))
+                logger.error("Image generation blocked by safety settings: %s", reason)
+                raise ValueError(f"Image generation failed due to safety settings: {reason}")
+
+            images = _extract_inline_images(response)
+            if not images:
+                logger.warning("No image parts returned for prompt: '%.100s...'", prompt)
+                raise ValueError("Gemini API did not return any images.")
+
+            image_urls = [_data_uri(img["mime_type"], img["data"]) for img in images]
+            logger.info("Successfully generated %d image(s).", len(image_urls))
+
+            return ImageGenerationResponse(
+                image_urls=image_urls,
+                revised_prompt=None  # legacy SDK does not provide a revised prompt here
+            )
+
+        except Exception as e:
+            logger.error("Error during Gemini image generation (legacy SDK): %s", e)
+            # Region support / feature gating errors sometimes include 'Unsupported' hints.
+            if "Unsupported" in str(e) and "location" in str(e):
+                raise ValueError(
+                    "Image generation may not be supported in your configured region or project. "
+                    "Check your API access and region settings."
+                )
+            raise ValueError(f"Google Gemini image generation failed: {str(e)}")
+
+    async def edit_image(
+        self,
+        prompt: str,
+        input_image_urls: List[str],
+        mask_url: Optional[str] = None,
+        generation_config: Optional[Dict[str, Any]] = None
+    ) -> ImageGenerationResponse:
+        """
+        Image editing/redraw with masks isn’t exposed via this legacy path here.
+        """
+        logger.error("Image editing is not supported by the GeminiImageClient (legacy SDK).")
+        raise NotImplementedError("The GeminiImageClient does not support the edit_image method.")
+
+    async def cleanup(self):
+        logger.debug("GeminiImageClient cleanup called (legacy SDK; nothing to release).")