roomkit 0.75.2__tar.gz → 0.76.0__tar.gz

{roomkit-0.75.2 → roomkit-0.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roomkit
-Version: 0.75.2
+Version: 0.76.0
 Summary: Pure async Python library for multi-channel conversations
 Project-URL: Homepage, https://roomkit.live
 Project-URL: Documentation, https://www.roomkit.live/docs/
@@ -40,6 +40,7 @@ Requires-Dist: deepgram-sdk>=6.0.0; extra == 'all'
 Requires-Dist: discord-py>=2.4; extra == 'all'
 Requires-Dist: elevenlabs>=2.40; extra == 'all'
 Requires-Dist: google-genai>=2.0.0; extra == 'all'
+Requires-Dist: google-genai>=2.18.0; extra == 'all'
 Requires-Dist: gradium>=0.5.7; extra == 'all'
 Requires-Dist: httpx-sse>=0.4; extra == 'all'
 Requires-Dist: httpx>=0.27; extra == 'all'
@@ -95,7 +96,7 @@ Requires-Dist: asyncpg>=0.29; extra == 'dev'
 Requires-Dist: bandit>=1.7; extra == 'dev'
 Requires-Dist: botbuilder-core>=4.17; extra == 'dev'
 Requires-Dist: discord-py>=2.4; extra == 'dev'
-Requires-Dist: google-genai>=2.0.0; extra == 'dev'
+Requires-Dist: google-genai>=2.18.0; extra == 'dev'
 Requires-Dist: gradium>=0.5.7; extra == 'dev'
 Requires-Dist: httpx-sse>=0.4; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
@@ -138,7 +139,7 @@ Requires-Dist: librosa>=0.10; extra == 'fastrtc'
 Requires-Dist: numpy<2.5,>=1.26; extra == 'fastrtc'
 Requires-Dist: pydub>=0.25; extra == 'fastrtc'
 Provides-Extra: gemini
-Requires-Dist: google-genai>=2.0.0; extra == 'gemini'
+Requires-Dist: google-genai>=2.18.0; extra == 'gemini'
 Provides-Extra: gradium
 Requires-Dist: gradium>=0.5.7; extra == 'gradium'
 Provides-Extra: httpx
@@ -180,7 +181,7 @@ Provides-Extra: providers
 Requires-Dist: anthropic>=0.30; extra == 'providers'
 Requires-Dist: botbuilder-core>=4.17; extra == 'providers'
 Requires-Dist: discord-py>=2.4; extra == 'providers'
-Requires-Dist: google-genai>=2.0.0; extra == 'providers'
+Requires-Dist: google-genai>=2.18.0; extra == 'providers'
 Requires-Dist: gradium>=0.5.7; extra == 'providers'
 Requires-Dist: httpx>=0.27; extra == 'providers'
 Requires-Dist: mistralai<3,>=2.0; extra == 'providers'

{roomkit-0.75.2 → roomkit-0.76.0}/pyproject.toml

@@ -49,7 +49,7 @@ cerebras = ["openai>=2.28,<3"]
 # read like the family's umbrella install rather than the chat provider.
 qwen-ai = ["openai>=2.28,<3"]
 ollama = ["ollama>=0.4"]
-gemini = ["google-genai>=2.0.0"]
+gemini = ["google-genai>=2.18.0"]
 mistral = ["mistralai>=2.0,<3"]
 polargrid = ["polargrid-sdk>=0.10.0"]
 deepgram = ["deepgram-sdk>=6.0.0"]

{roomkit-0.75.2 → roomkit-0.76.0}/src/roomkit/__init__.py

@@ -171,7 +171,17 @@ from roomkit.orchestration import (
 )
 from roomkit.providers.ai import ModelPricing
 from roomkit.providers.cerebras import CerebrasAIProvider, CerebrasConfig
-from roomkit.providers.image import ImageProvider, ImageResult, MockImageProvider
+from roomkit.providers.image import (
+    ImageAttempt,
+    ImageCapabilities,
+    ImageGenerationError,
+    ImageModelInfo,
+    ImageOptions,
+    ImageProgressCallback,
+    ImageProvider,
+    ImageResult,
+    MockImageProvider,
+)
 from roomkit.sandbox import SandboxExecutor, SandboxResult
 from roomkit.skills import ScriptExecutor, Skill, SkillMetadata, SkillRegistry
 from roomkit.store import ConversationStore, InMemoryStore, SQLiteSchemaError, SQLiteStore
@@ -427,6 +437,12 @@ __all__ = [
     "FrameworkEvent",
     "HookResult",
     "ImageProvider",
+    "ImageAttempt",
+    "ImageCapabilities",
+    "ImageGenerationError",
+    "ImageModelInfo",
+    "ImageOptions",
+    "ImageProgressCallback",
     "ImageResult",
     "InjectedEvent",
     "InboundMessage",

roomkit-0.76.0/src/roomkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.76.0"

{roomkit-0.75.2 → roomkit-0.76.0}/src/roomkit/providers/gemini/image.py

@@ -21,11 +21,17 @@ from roomkit.providers.gemini.errors import wrap_gemini_error
 from roomkit.providers.gemini.image_models import MODELS
 from roomkit.providers.gemini.sdk import build_genai_client, close_genai_client
 from roomkit.providers.image.base import (
+    ImageAttempt,
+    ImageGenerationError,
+    ImageProgressCallback,
     ImageProvider,
     ImageResult,
+    notify_image_progress,
     parse_data_uri,
     parse_size,
 )
+from roomkit.providers.image.options import ImageModelInfo, ImageOptions, plain_metadata
+from roomkit.providers.image.usage import gemini_image_usage
 
 # Aspect ratios the Interactions image format accepts. A requested size is
 # reduced to its ratio and looked up here; an unlisted one is refused rather
@@ -64,7 +70,10 @@ class GeminiImageProvider(ImageProvider):
         # The client carries the connect/read split; see ``build_genai_client``
         # for why it cannot go on the request.
         built = build_genai_client(
-            config, provider="GeminiImageProvider", api_key=config.api_key.get_secret_value()
+            config,
+            provider="GeminiImageProvider",
+            api_key=config.api_key.get_secret_value(),
+            disable_retries=True,
         )
         self._client, self._http = built.client, built.http
 
@@ -88,24 +97,141 @@ class GeminiImageProvider(ImageProvider):
         size: str | None = None,
         n: int = 1,
         reference_images: list[AIImagePart] | None = None,
+    ) -> list[ImageResult]:
+        return await self.generate_with_options(
+            prompt, size=size, n=n, reference_images=reference_images
+        )
+
+    async def generate_with_options(
+        self,
+        prompt: str,
+        *,
+        size: str | None = None,
+        n: int = 1,
+        reference_images: list[AIImagePart] | None = None,
+        options: ImageOptions | None = None,
+        mask: AIImagePart | None = None,
+        on_progress: ImageProgressCallback | None = None,
     ) -> list[ImageResult]:
         if n < 1:
-            raise ValueError(f"n must be at least 1, got {n}")
-        request = self._build_request(prompt, size, reference_images or [])
-        # A task group rather than ``gather``: when one interaction fails the
-        # siblings are cancelled instead of running to completion for a result
-        # nobody will read. Each one is a billed image.
+            raise ValueError("n must be at least 1")
+        if mask:
+            raise ValueError("Gemini does not support explicit masks")
+        options = options or ImageOptions()
+        references = reference_images or []
+        if size and (options.aspect_ratio or options.image_size):
+            raise ValueError("Use size or aspect_ratio/image_size, not both")
+        defaults: dict[str, Any] = {}
+        if self._config.image_size:
+            defaults["image_size"] = self._config.image_size
+        if self._config.output_mime_type:
+            defaults["output_format"] = self._config.output_mime_type.removeprefix("image/")
+        if size:
+            defaults["aspect_ratio"], defaults["image_size"] = self.resolve_size(size)
+        options = ImageOptions.model_validate(
+            {**defaults, **options.model_dump(exclude_none=True)}
+        )
+        entry = self.catalog_entry()
+        if isinstance(entry, ImageModelInfo):
+            entry.image.validate_request(
+                options, size=None, n=n, references=len(references), mask=False
+            )
+        elif set(options.model_dump(exclude_none=True)) - set(defaults) - {"store"}:
+            raise ValueError("Advanced controls require a model with known image capabilities")
+        request = self._build_request(prompt, None, references)
+        for field in ("aspect_ratio", "image_size"):
+            if (value := getattr(options, field)) is not None:
+                request["response_format"][field] = value
+        if options.output_format:
+            request["response_format"]["mime_type"] = "image/" + options.output_format
+        if options.store is not None:
+            request["store"] = options.store
+        if options.previous_interaction_id:
+            request["previous_interaction_id"] = options.previous_interaction_id
+        if options.search_types:
+            request["tools"] = [{"type": "google_search", "search_types": options.search_types}]
+        if options.thinking_level:
+            request["generation_config"] = {"thinking_level": options.thinking_level}
+        # Each call settles independently. A rejected sibling does not erase a
+        # successful billed image or cancel a call whose outcome is still unknown.
+        outcomes = await asyncio.gather(
+            *[self._attempt(request, index, on_progress) for index in range(n)],
+            return_exceptions=True,
+        )
+        attempts: list[ImageAttempt] = []
+        failures: list[BaseException] = []
+        for outcome in outcomes:
+            if isinstance(outcome, ImageAttempt):
+                attempts.append(outcome)
+            elif isinstance(outcome, ImageGenerationError):
+                attempts.extend(outcome.attempts)
+                failures.append(outcome)
+            elif isinstance(outcome, BaseException):
+                failures.append(outcome)
+        if failures:
+            first = failures[0]
+            raise ImageGenerationError(str(first), provider="gemini", attempts=attempts) from (
+                first.__cause__ or first
+            )
+        return [result for attempt in attempts for result in attempt.results]
+
+    async def _attempt(
+        self, request: dict[str, Any], index: int, on_progress: ImageProgressCallback | None
+    ) -> ImageAttempt:
+        attempt = ImageAttempt(
+            index=index,
+            effective_options={key: value for key, value in request.items() if key != "input"},
+        )
+        if on_progress:
+            await notify_image_progress(on_progress, attempt, provider="gemini")
+        interaction = None
+        failure: Exception | None = None
         try:
-            async with asyncio.TaskGroup() as group:
-                tasks = [group.create_task(self._create(request)) for _ in range(n)]
-        except BaseExceptionGroup as failures:
-            # The caller asked for images and gets the failure that stopped
-            # them, not a group wrapper it would have to unpack to find the
-            # ProviderError its retry policy reads. Re-chained to its own cause
-            # so the SDK exception underneath survives the unwrapping.
-            first = failures.exceptions[0]
-            raise first from first.__cause__
-        return [self._result(task.result()) for task in tasks]
+            interaction = await self._create(request)
+            attempt.provider_request_id = getattr(interaction, "id", None)
+            attempt.usage = self._usage(interaction)
+            attempt.raw_usage = plain_metadata(getattr(interaction, "usage", None)) or {}
+            attempt.metadata = {
+                "steps": plain_metadata(getattr(interaction, "steps", [])),
+                "output_text": getattr(interaction, "output_text", None),
+            }
+            result = self._result(interaction)
+            attempt.results = [
+                result.model_copy(
+                    update={
+                        "attempt_id": attempt.id,
+                        "provider_request_id": attempt.provider_request_id,
+                        "raw_usage": attempt.raw_usage,
+                        "effective_options": attempt.effective_options,
+                        "metadata": attempt.metadata,
+                    }
+                )
+            ]
+            attempt.status = "succeeded"
+        except asyncio.CancelledError as cancelled:
+            attempt.status = "unknown"
+            attempt.error = "Cancelled locally; the provider may still bill this request"
+            try:
+                await notify_image_progress(on_progress, attempt, provider="gemini")
+            except Exception as exc:
+                cancelled.add_note(f"Failed to report unknown image outcome: {exc}")
+            raise
+        except Exception as exc:
+            failure = exc
+            attempt.status = (
+                "failed"
+                if interaction is not None or getattr(exc, "status_code", None)
+                else "unknown"
+            )
+            attempt.error = str(exc)
+            attempt.status_code = getattr(exc, "status_code", None)
+        if on_progress:
+            await notify_image_progress(on_progress, attempt, provider="gemini")
+        if failure:
+            raise ImageGenerationError(
+                str(failure), provider="gemini", attempts=[attempt]
+            ) from failure
+        return attempt
 
     def _build_request(
         self,
@@ -130,7 +256,7 @@ class GeminiImageProvider(ImageProvider):
         if size is not None:
             # The requested pixels win over the deployment default: a caller
             # naming a geometry is more specific than a configured tier.
-            aspect_ratio, tier = self._geometry(size)
+            aspect_ratio, tier = self.resolve_size(size)
             response_format["aspect_ratio"] = aspect_ratio
             response_format["image_size"] = tier
         elif self._config.image_size is not None:
@@ -153,7 +279,7 @@ class GeminiImageProvider(ImageProvider):
             raise wrap_gemini_error(exc) from exc
 
     @staticmethod
-    def _geometry(size: str) -> tuple[str, str]:
+    def resolve_size(size: str) -> tuple[str, str]:
         """Translate ``"WIDTHxHEIGHT"`` into Gemini's aspect ratio and size tier.
 
         Gemini expresses geometry as a named ratio and a resolution tier, not
@@ -174,6 +300,8 @@ class GeminiImageProvider(ImageProvider):
                 return aspect_ratio, tier
         raise ValueError(f"size {size!r} exceeds Gemini's largest tier (4K)")
 
+    _geometry = resolve_size
+
     @staticmethod
     def _image_content(part: AIImagePart, index: int) -> dict[str, Any]:
         """Turn a reference image into an Interactions image content block.
@@ -241,34 +369,10 @@ class GeminiImageProvider(ImageProvider):
         again, which would bill the pixels twice. Thought tokens are billed at
         the text output rate, so they join the text output counter.
         """
-        usage = getattr(interaction, "usage", None)
-        if usage is None:
-            return {}
-        input_total = int(getattr(usage, "total_input_tokens", 0) or 0)
-        output_total = int(getattr(usage, "total_output_tokens", 0) or 0)
-        thoughts = int(getattr(usage, "total_thought_tokens", 0) or 0)
-        input_image = _modality_tokens(getattr(usage, "input_tokens_by_modality", None), "image")
-        output_image = _modality_tokens(getattr(usage, "output_tokens_by_modality", None), "image")
-        return {
-            "input_tokens": max(input_total - input_image, 0),
-            "input_image_tokens": input_image,
-            "output_tokens": max(output_total - output_image, 0) + thoughts,
-            "output_image_tokens": output_image,
-        }
+        return gemini_image_usage(getattr(interaction, "usage", None))
 
     async def close(self) -> None:
         """Close the SDK and the httpx client it was given."""
         client, self._client = self._client, None
         http, self._http = self._http, None
         await close_genai_client(client, http)
-
-
-def _modality_tokens(breakdown: Any, modality: str) -> int:
-    """Sum the token counts one modality contributes to a usage breakdown."""
-    if not breakdown:
-        return 0
-    total = 0
-    for entry in breakdown:
-        if str(getattr(entry, "modality", "")).lower() == modality:
-            total += int(getattr(entry, "tokens", 0) or 0)
-    return total

{roomkit-0.75.2 → roomkit-0.76.0}/src/roomkit/providers/gemini/image_models.py

@@ -32,13 +32,61 @@ from datetime import date
 
 from roomkit.providers.ai.base import ModelInfo, ModelPricing
 from roomkit.providers.image.base import IMAGE_GEN_CAPABILITY
+from roomkit.providers.image.options import ImageCapabilities, ImageModelInfo
 
 _VERIFIED = date(2026, 8, 7)
 _CAPS = [IMAGE_GEN_CAPABILITY, "edit"]
 
+_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
+_PRO = ImageCapabilities(
+    options=[
+        "aspect_ratio",
+        "image_size",
+        "output_format",
+        "previous_interaction_id",
+        "store",
+        "search_types",
+    ],
+    aspect_ratios=_RATIOS,
+    image_sizes=["1K", "2K", "4K"],
+    formats=["png", "jpeg"],
+    max_references=14,
+    max_images=None,
+    continuity=True,
+    search_types=["web_search"],
+    verified=date(2026, 9, 15),
+)
+_FLASH = _PRO.model_copy(
+    update={
+        "options": [*_PRO.options, "thinking_level"],
+        "thinking_levels": ["minimal", "high"],
+        "aspect_ratios": [*_RATIOS, "1:4", "4:1", "1:8", "8:1"],
+        "image_sizes": ["512", "1K", "2K", "4K"],
+        "search_types": ["web_search", "image_search"],
+    }
+)
+_LITE = _PRO.model_copy(
+    update={
+        "image_sizes": ["1K"],
+        "search_types": [],
+        "options": [option for option in _PRO.options if option != "search_types"]
+        + ["thinking_level"],
+        "thinking_levels": ["minimal", "high"],
+    }
+)
+_V25 = _LITE.model_copy(
+    update={
+        "max_references": 3,
+        "retirement_date": date(2026, 10, 2),
+        "thinking_levels": [],
+        "options": [option for option in _LITE.options if option != "thinking_level"],
+    }
+)
+
 MODELS: list[ModelInfo] = [
-    ModelInfo(
+    ImageModelInfo(
         id="gemini-3-pro-image",
+        image=_PRO,
         display_name="Gemini 3 Pro Image (Nano Banana Pro)",
         supports_vision=True,
         capabilities=_CAPS,
@@ -51,8 +99,9 @@ MODELS: list[ModelInfo] = [
             verified=_VERIFIED,
         ),
     ),
-    ModelInfo(
+    ImageModelInfo(
         id="gemini-3.1-flash-image",
+        image=_FLASH,
         display_name="Gemini 3.1 Flash Image (Nano Banana 2)",
         supports_vision=True,
         capabilities=_CAPS,
@@ -64,8 +113,9 @@ MODELS: list[ModelInfo] = [
             verified=_VERIFIED,
         ),
     ),
-    ModelInfo(
+    ImageModelInfo(
         id="gemini-3.1-flash-lite-image",
+        image=_LITE,
         display_name="Gemini 3.1 Flash Lite Image (Nano Banana 2 Lite)",
         supports_vision=True,
         capabilities=_CAPS,
@@ -77,8 +127,10 @@ MODELS: list[ModelInfo] = [
             verified=_VERIFIED,
         ),
     ),
-    ModelInfo(
+    ImageModelInfo(
         id="gemini-2.5-flash-image",
+        image=_V25,
+        deprecated=True,
         display_name="Gemini 2.5 Flash Image (Nano Banana)",
         supports_vision=True,
         capabilities=_CAPS,

{roomkit-0.75.2 → roomkit-0.76.0}/src/roomkit/providers/gemini/sdk.py

@@ -84,14 +84,16 @@ def _restore_client_timeout(timeout: httpx.Timeout) -> Callable[[httpx.Request],
     return restore
 
 
-def build_genai_client(timeouts: HTTPTimeouts, *, provider: str, api_key: str) -> GenaiClient:
+def build_genai_client(
+    timeouts: HTTPTimeouts, *, provider: str, api_key: str, disable_retries: bool = False
+) -> GenaiClient:
     """A client for the Gemini Developer API, authenticated by *api_key*.
 
     ``timeouts.timeout`` is the read/write/pool budget, ``connect_timeout``
     bounds the TCP connect. *provider* names the caller in the ImportError
     raised when google-genai is not installed.
     """
-    return _build_client(timeouts, provider, api_key=api_key)
+    return _build_client(timeouts, provider, api_key=api_key, disable_retries=disable_retries)
 
 
 def build_vertex_genai_client(
@@ -118,7 +120,13 @@ def build_vertex_genai_client(
     )
 
 
-def _build_client(timeouts: HTTPTimeouts, provider: str, **client_kwargs: Any) -> GenaiClient:
+def _build_client(
+    timeouts: HTTPTimeouts,
+    provider: str,
+    *,
+    disable_retries: bool = False,
+    **client_kwargs: Any,
+) -> GenaiClient:
     """Build the pair behind both entry points; *client_kwargs* go to ``genai.Client``."""
     # Both optional: google-genai brings httpx along, and the package root
     # reaches this module (through the video vision providers), so neither
@@ -148,6 +156,14 @@ def _build_client(timeouts: HTTPTimeouts, provider: str, **client_kwargs: Any) -
             # The sync client is built by the SDK regardless; same budget.
             client_args={"timeout": timeout},
             httpx_async_client=http,
+            # Interactions interprets attempts as retries, while the parent
+            # client changes zero to one. Use an impossible HTTP status to
+            # disable status retries, including successful paid POSTs.
+            **(
+                {"retry_options": {"attempts": 1, "http_status_codes": [0]}}
+                if disable_retries
+                else {}
+            ),
         ),
     )
     return GenaiClient(client, http, genai.types)

{roomkit-0.75.2 → roomkit-0.76.0}/src/roomkit/providers/image/__init__.py

@@ -2,6 +2,9 @@
 
 from roomkit.providers.image.base import (
     IMAGE_GEN_CAPABILITY,
+    ImageAttempt,
+    ImageGenerationError,
+    ImageProgressCallback,
     ImageProvider,
     ImageResult,
     parse_data_uri,
@@ -10,9 +13,16 @@ from roomkit.providers.image.base import (
     to_data_uri,
 )
 from roomkit.providers.image.mock import MockImageProvider
+from roomkit.providers.image.options import ImageCapabilities, ImageModelInfo, ImageOptions
 
 __all__ = [
     "IMAGE_GEN_CAPABILITY",
+    "ImageAttempt",
+    "ImageCapabilities",
+    "ImageGenerationError",
+    "ImageModelInfo",
+    "ImageOptions",
+    "ImageProgressCallback",
     "ImageProvider",
     "ImageResult",
     "MockImageProvider",

{roomkit-0.75.2 → roomkit-0.76.0}/src/roomkit/providers/image/base.py

@@ -16,11 +16,14 @@ from __future__ import annotations
 
 import re
 from abc import ABC, abstractmethod
-from typing import Any
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+from uuid import uuid4
 
 from pydantic import BaseModel, Field, field_validator
 
-from roomkit.providers.ai.base import AIImagePart, ModelInfo
+from roomkit.providers.ai.base import AIImagePart, ModelInfo, ProviderError
+from roomkit.providers.image.options import ImageOptions, image_model_entry
 from roomkit.providers.utils import parse_data_uri as parse_data_uri
 from roomkit.providers.utils import to_data_uri as to_data_uri
 
@@ -108,6 +111,13 @@ class ImageResult(BaseModel):
     mime_type: str
     revised_prompt: str | None = None
     usage: dict[str, Any] = Field(default_factory=dict)
+    attempt_id: str | None = None
+    provider_request_id: str | None = None
+    raw_usage: dict[str, Any] = Field(default_factory=dict)
+    effective_options: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    width: int | None = None
+    height: int | None = None
 
     @field_validator("data")
     @classmethod
@@ -136,6 +146,59 @@ class ImageResult(BaseModel):
         return AIImagePart(url=self.data, mime_type=self.mime_type)
 
 
+class ImageAttempt(BaseModel):
+    """One vendor call, including outcomes that produced no usable image.
+
+    ``usage`` applies to the whole call. Result-level usage is the compatibility
+    projection of this same measurement; a consumer must not sum both.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    index: int = 0
+    status: Literal["started", "preview", "succeeded", "failed", "unknown"] = "started"
+    provider_request_id: str | None = None
+    usage: dict[str, Any] = Field(default_factory=dict)
+    raw_usage: dict[str, Any] = Field(default_factory=dict)
+    effective_options: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    results: list[ImageResult] = Field(default_factory=list)
+    error: str | None = None
+    status_code: int | None = None
+
+
+ImageProgressCallback = Callable[[ImageAttempt], Awaitable[None]]
+
+
+class ImageGenerationError(ProviderError):
+    """A failed generation with every available outcome; never auto-retry it."""
+
+    def __init__(self, message: str, *, provider: str, attempts: list[ImageAttempt]) -> None:
+        super().__init__(
+            message,
+            provider=provider,
+            retryable=False,
+            status_code=next(
+                (attempt.status_code for attempt in attempts if attempt.status_code), None
+            ),
+        )
+        self.attempts = attempts
+        self.results = [result for attempt in attempts for result in attempt.results]
+
+
+async def notify_image_progress(
+    callback: ImageProgressCallback | None, attempt: ImageAttempt, *, provider: str
+) -> None:
+    """Callback failure preserves the billed outcome and never repeats a request."""
+    if callback is None:
+        return
+    try:
+        await callback(attempt.model_copy(deep=True))
+    except Exception as exc:
+        raise ImageGenerationError(
+            f"Image progress callback failed: {exc}", provider=provider, attempts=[attempt]
+        ) from exc
+
+
 class ImageProvider(ABC):
     """Generates images from a prompt, decoupled from the conversation (RFC §25)."""
 
@@ -174,11 +237,30 @@ class ImageProvider(ABC):
 
     def catalog_entry(self) -> ModelInfo | None:
         """The offline :class:`ModelInfo` for the active model, if the catalog has it."""
-        name = self.model_name
-        for model in type(self).available_models():
-            if model.id == name:
-                return model
-        return None
+        return image_model_entry(type(self).available_models(), self.model_name)
+
+    async def generate_with_options(
+        self,
+        prompt: str,
+        *,
+        size: str | None = None,
+        n: int = 1,
+        reference_images: list[AIImagePart] | None = None,
+        options: ImageOptions | None = None,
+        mask: AIImagePart | None = None,
+        on_progress: ImageProgressCallback | None = None,
+    ) -> list[ImageResult]:
+        """Generate with endpoint-specific controls and observable outcomes.
+
+        Providers override this additive entry point to support advanced controls.
+        The default preserves third-party implementations of ``generate`` and
+        rejects unsupported controls rather than silently discarding them.
+        """
+        if mask or (options and options.model_dump(exclude_none=True)):
+            raise ValueError(f"{self.name} does not support advanced image options")
+        if on_progress:
+            raise ValueError(f"{self.name} does not support image progress callbacks")
+        return await self.generate(prompt, size=size, n=n, reference_images=reference_images)
 
     @abstractmethod
     async def generate(