codex-ai 0.2.1__tar.gz → 0.2.3__tar.gz

{codex_ai-0.2.1 → codex_ai-0.2.3}/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-05-17
+
+### Added
+- Added explicit Gemini image `image_config` support for aspect ratio and image size controls.
+- Added a Gemini image retry from `image_size="4K"` to `image_size="2K"` when the initial 4K request is rejected.
+
+### Changed
+- Updated the Gemini extra to `google-genai==2.3.0` for the SDK image configuration contract.
+
+## [0.2.2] - 2026-05-15
+
+### Fixed
+- Changed the Gemini image default model to the official API model id `gemini-2.5-flash-image`.
+
 ## [0.2.1] - 2026-05-15
 
 ### Added

{codex_ai-0.2.1 → codex_ai-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-ai
-Version: 0.2.1
+Version: 0.2.3
 Summary: Gemini-first and OpenAI provider helpers for Codex
 Project-URL: Homepage, https://github.com/codexdlc/codex-ai
 Project-URL: Documentation, https://codexdlc.github.io/codex-ai/
@@ -19,12 +19,12 @@ Requires-Python: >=3.12
 Requires-Dist: codex-core<0.4.0,>=0.2.2
 Requires-Dist: pydantic<3.0,>=2.0
 Provides-Extra: all
-Requires-Dist: google-genai==1.68.0; extra == 'all'
+Requires-Dist: google-genai==2.3.0; extra == 'all'
 Requires-Dist: openai<2.0,>=1.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: bandit>=1.7; extra == 'dev'
 Requires-Dist: detect-secrets>=1.5; extra == 'dev'
-Requires-Dist: google-genai==1.68.0; extra == 'dev'
+Requires-Dist: google-genai==2.3.0; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: openai<2.0,>=1.0; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
@@ -40,7 +40,7 @@ Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Provides-Extra: gemini
-Requires-Dist: google-genai==1.68.0; extra == 'gemini'
+Requires-Dist: google-genai==2.3.0; extra == 'gemini'
 Provides-Extra: openai
 Requires-Dist: openai<2.0,>=1.0; extra == 'openai'
 Description-Content-Type: text/markdown
@@ -83,8 +83,10 @@ gemini = GeminiProvider(api_key="AIza...")
 text = await gemini.generate_text("Write one short tavern rumor.")
 loot = await gemini.generate_json("Create one loot item.", schema=LootItem)
 image_bytes, content_type = await gemini.generate_image_bytes(
-    "A fantasy clan banner, game icon style.",
-    response_mime_type="image/webp",
+    "Square tactical dark fantasy ruined capital city map, no labels.",
+    model="gemini-3-pro-image-preview",
+    response_mime_type="image/png",
+    image_config={"aspect_ratio": "1:1", "image_size": "4K"},
 )
 
 imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
@@ -97,7 +99,9 @@ imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
 
 `generate_image_bytes()` targets Gemini image models through `generate_content` and treats
 `response_mime_type` as a preferred/fallback MIME type. It does not pass image MIME values
-to Gemini's text `response_mime_type` config field. Use `generate_imagen_bytes()` for
+to Gemini's text `response_mime_type` config field. Pass Gemini image controls such as
+`aspect_ratio` and `image_size` with `image_config`; if a `4K` request is rejected,
+the Gemini provider retries once with `2K`. Use `generate_imagen_bytes()` for
 Imagen models; that path uses `generate_images` and passes the requested MIME as
 `output_mime_type`.
 

{codex_ai-0.2.1 → codex_ai-0.2.3}/README.md

@@ -36,8 +36,10 @@ gemini = GeminiProvider(api_key="AIza...")
 text = await gemini.generate_text("Write one short tavern rumor.")
 loot = await gemini.generate_json("Create one loot item.", schema=LootItem)
 image_bytes, content_type = await gemini.generate_image_bytes(
-    "A fantasy clan banner, game icon style.",
-    response_mime_type="image/webp",
+    "Square tactical dark fantasy ruined capital city map, no labels.",
+    model="gemini-3-pro-image-preview",
+    response_mime_type="image/png",
+    image_config={"aspect_ratio": "1:1", "image_size": "4K"},
 )
 
 imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
@@ -50,7 +52,9 @@ imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
 
 `generate_image_bytes()` targets Gemini image models through `generate_content` and treats
 `response_mime_type` as a preferred/fallback MIME type. It does not pass image MIME values
-to Gemini's text `response_mime_type` config field. Use `generate_imagen_bytes()` for
+to Gemini's text `response_mime_type` config field. Pass Gemini image controls such as
+`aspect_ratio` and `image_size` with `image_config`; if a `4K` request is rejected,
+the Gemini provider retries once with `2K`. Use `generate_imagen_bytes()` for
 Imagen models; that path uses `generate_images` and passes the requested MIME as
 `output_mime_type`.
 

{codex_ai-0.2.1 → codex_ai-0.2.3}/docs/en/architecture/providers/README.md

@@ -47,6 +47,7 @@ LLMRouter builder -> PromptResult -> LLMDispatcher.process() -> provider.answer(
 - Gemini-specific capabilities are represented directly instead of being hidden behind a broad universal abstraction.
 - JSON generation uses provider-native JSON configuration and still validates locally with `json.loads` and optional Pydantic models.
 - Gemini image generation and Imagen generation are separate explicit methods because they use different SDK calls.
-- `generate_image_bytes()` uses Gemini `generate_content` with image modality. Its `response_mime_type` is only a preferred/fallback MIME type.
+- `generate_image_bytes()` uses Gemini `generate_content` with image modality. Its `response_mime_type` is only a preferred/fallback MIME type, and Gemini image controls are passed through `image_config`.
+- `generate_image_bytes()` retries a rejected `image_config={"image_size": "4K"}` request once as `2K`.
 - `generate_imagen_bytes()` uses Imagen `generate_images` and passes the requested MIME as `output_mime_type`.
 - Anthropic, OpenRouter, and multi-provider failover are not active APIs in this alpha line.

{codex_ai-0.2.1 → codex_ai-0.2.3}/docs/en/architecture/providers/data_flow.md

@@ -28,12 +28,13 @@ PromptResult | str
 ```
 prompt: str
     -> GeminiProvider.generate_image_bytes()
-    -> GenerateContentConfig(response_modalities=[IMAGE])
+    -> GenerateContentConfig(response_modalities=[IMAGE], image_config=...)
     -> first inline_data image part
     -> (bytes, actual_mime_type)
 ```
 
 `response_mime_type` is not passed to `GenerateContentConfig.response_mime_type` on this path; it is only a fallback content type when Gemini omits `inline_data.mime_type`.
+When `image_config.image_size` is `4K` and Gemini rejects the request, the provider retries once with `image_size` changed to `2K`.
 
 ## Imagen Images
 

{codex_ai-0.2.1 → codex_ai-0.2.3}/docs/ru/architecture/providers/README.md

@@ -47,6 +47,7 @@ LLMRouter builder -> PromptResult -> LLMDispatcher.process() -> provider.answer(
 - Возможности Gemini представлены напрямую, без широкой универсальной абстракции.
 - JSON generation использует native JSON config провайдера и локальную проверку через `json.loads` и optional Pydantic schema.
 - Gemini image generation и Imagen generation разведены в отдельные явные методы, потому что они используют разные SDK calls.
-- `generate_image_bytes()` использует Gemini `generate_content` с image modality. Его `response_mime_type` является только preferred/fallback MIME type.
+- `generate_image_bytes()` использует Gemini `generate_content` с image modality. Его `response_mime_type` является только preferred/fallback MIME type, а Gemini image controls передаются через `image_config`.
+- `generate_image_bytes()` один раз повторяет отклоненный `image_config={"image_size": "4K"}` запрос как `2K`.
 - `generate_imagen_bytes()` использует Imagen `generate_images` и передает requested MIME как `output_mime_type`.
 - Anthropic, OpenRouter и multi-provider failover не являются активными API в этой alpha-линейке.

{codex_ai-0.2.1 → codex_ai-0.2.3}/docs/ru/architecture/providers/data_flow.md

@@ -28,12 +28,13 @@ PromptResult | str
 ```
 prompt: str
     -> GeminiProvider.generate_image_bytes()
-    -> GenerateContentConfig(response_modalities=[IMAGE])
+    -> GenerateContentConfig(response_modalities=[IMAGE], image_config=...)
     -> first inline_data image part
     -> (bytes, actual_mime_type)
 ```
 
 `response_mime_type` в этом пути не передается в `GenerateContentConfig.response_mime_type`; он используется только как fallback content type, если Gemini не вернул `inline_data.mime_type`.
+Если `image_config.image_size` равен `4K` и Gemini отклоняет запрос, провайдер один раз повторяет его с `image_size="2K"`.
 
 ## Imagen Images
 

{codex_ai-0.2.1 → codex_ai-0.2.3}/pyproject.toml

@@ -31,7 +31,7 @@ Issues = "https://github.com/codexdlc/codex-ai/issues"
 
 [project.optional-dependencies]
 openai = ["openai>=1.0,<2.0"]
-gemini = ["google-genai==1.68.0"]
+gemini = ["google-genai==2.3.0"]
 all = [
     "codex-ai[openai,gemini]",
 ]

{codex_ai-0.2.1 → codex_ai-0.2.3}/src/codex_ai/core/dispatcher.py

@@ -96,6 +96,7 @@ class LLMDispatcher:
         *,
         model: str | None = None,
         response_mime_type: str = "image/webp",
+        image_config: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> tuple[bytes, str]:
         """
@@ -114,6 +115,7 @@ class LLMDispatcher:
             prompt,
             model=model,
             response_mime_type=response_mime_type,
+            image_config=image_config,
             **kwargs,
         )
 

{codex_ai-0.2.1 → codex_ai-0.2.3}/src/codex_ai/core/protocol.py

@@ -148,6 +148,7 @@ class ImageGenerationProvider(Protocol):
         *,
         model: str | None = None,
         response_mime_type: str = "image/webp",
+        image_config: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> tuple[bytes, str]:
         """
@@ -157,6 +158,8 @@ class ImageGenerationProvider(Protocol):
             prompt: Plain image-generation prompt.
             model: Optional image model override.
             response_mime_type: Requested/preferred image MIME type.
+            image_config: Optional image generation controls such as
+                ``{"aspect_ratio": "1:1", "image_size": "4K"}``.
             **kwargs: Extra provider-specific kwargs.
 
         Returns:

{codex_ai-0.2.1 → codex_ai-0.2.3}/src/codex_ai/providers/gemini.py

@@ -28,7 +28,7 @@ from codex_ai.core.exceptions import LLMProviderError
 from codex_ai.core.protocol import PromptResult
 
 _DEFAULT_MODEL = "gemini-2.5-flash-lite"
-_DEFAULT_IMAGE_MODEL = "gemini-3.1-flash-image-preview"
+_DEFAULT_IMAGE_MODEL = "gemini-2.5-flash-image"
 _DEFAULT_IMAGEN_MODEL = "imagen-3.0-generate-002"
 
 
@@ -41,7 +41,7 @@ class GeminiProvider:
     Args:
         api_key: Google AI API key.
         model: Gemini text model name. Defaults to ``"gemini-2.5-flash-lite"``.
-        image_model: Gemini image model name. Defaults to ``"gemini-3.1-flash-image-preview"``.
+        image_model: Gemini image model name. Defaults to ``"gemini-2.5-flash-image"``.
 
     Example:
         ```python
@@ -186,6 +186,7 @@ class GeminiProvider:
         *,
         model: str | None = None,
         response_mime_type: str = "image/webp",
+        image_config: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> tuple[bytes, str]:
         """
@@ -206,29 +207,75 @@ class GeminiProvider:
         runtime_kw = kwargs.copy()
         runtime_kw.pop("model", None)
         runtime_kw.pop("response_mime_type", None)
+        runtime_kw.pop("image_config", None)
 
-        config = genai_types.GenerateContentConfig(
-            response_modalities=[genai_types.Modality.IMAGE],
+        config_kwargs: dict[str, Any] = {
+            "response_modalities": [genai_types.Modality.IMAGE],
             **runtime_kw,
-        )
+        }
+        if image_config is not None:
+            config_kwargs["image_config"] = image_config
 
         try:
-            response = await self._client.aio.models.generate_content(
+            return await self._generate_image_once(
                 model=selected_model,
-                contents=prompt,
-                config=config,
+                prompt=prompt,
+                config_kwargs=config_kwargs,
+                fallback_mime=requested_mime,
             )
-            image = self._extract_first_inline_image(response, fallback_mime=requested_mime)
-            if image is not None:
-                return image
-
-            detail = self._describe_non_image_response(response)
-            raise LLMProviderError(f"Gemini image generation did not return image data{detail}")
         except LLMProviderError:
             raise
         except Exception as exc:
+            fallback_config_kwargs = self._fallback_4k_image_config_to_2k(config_kwargs)
+            if fallback_config_kwargs is not None:
+                try:
+                    return await self._generate_image_once(
+                        model=selected_model,
+                        prompt=prompt,
+                        config_kwargs=fallback_config_kwargs,
+                        fallback_mime=requested_mime,
+                    )
+                except LLMProviderError:
+                    raise
+                except Exception as fallback_exc:
+                    raise LLMProviderError(f"Gemini image generation error: {fallback_exc}") from fallback_exc
+
             raise LLMProviderError(f"Gemini image generation error: {exc}") from exc
 
+    async def _generate_image_once(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        config_kwargs: dict[str, Any],
+        fallback_mime: str,
+    ) -> tuple[bytes, str]:
+        config = genai_types.GenerateContentConfig(**config_kwargs)
+        response = await self._client.aio.models.generate_content(
+            model=model,
+            contents=prompt,
+            config=config,
+        )
+        image = self._extract_first_inline_image(response, fallback_mime=fallback_mime)
+        if image is not None:
+            return image
+
+        detail = self._describe_non_image_response(response)
+        raise LLMProviderError(f"Gemini image generation did not return image data{detail}")
+
+    @staticmethod
+    def _fallback_4k_image_config_to_2k(config_kwargs: dict[str, Any]) -> dict[str, Any] | None:
+        image_config = config_kwargs.get("image_config")
+        if not isinstance(image_config, dict) or image_config.get("image_size") != "4K":
+            return None
+
+        fallback_image_config = image_config.copy()
+        fallback_image_config["image_size"] = "2K"
+
+        fallback_config_kwargs = config_kwargs.copy()
+        fallback_config_kwargs["image_config"] = fallback_image_config
+        return fallback_config_kwargs
+
     async def generate_imagen_bytes(
         self,
         prompt: str,

{codex_ai-0.2.1 → codex_ai-0.2.3}/tests/unit/core/test_dispatcher.py

@@ -126,9 +126,10 @@ class ImageProvider:
         *,
         model: str | None = None,
         response_mime_type: str = "image/webp",
+        image_config: dict | None = None,
         **kwargs,
     ) -> tuple[bytes, str]:
-        self.calls.append((prompt, model, response_mime_type, kwargs))
+        self.calls.append((prompt, model, response_mime_type, image_config, kwargs))
         return b"image-bytes", "image/png"
 
     async def generate_imagen_bytes(
@@ -159,11 +160,14 @@ async def test_dispatcher_generate_image_bytes_delegates_to_image_provider():
         "draw a castle",
         model="gemini-image",
         response_mime_type="image/webp",
+        image_config={"aspect_ratio": "1:1", "image_size": "4K"},
         seed=123,
     )
 
     assert result == (b"image-bytes", "image/png")
-    assert provider.calls == [("draw a castle", "gemini-image", "image/webp", {"seed": 123})]
+    assert provider.calls == [
+        ("draw a castle", "gemini-image", "image/webp", {"aspect_ratio": "1:1", "image_size": "4K"}, {"seed": 123})
+    ]
 
 
 async def test_dispatcher_generate_image_bytes_raises_for_unsupported_provider(mock_provider):

{codex_ai-0.2.1 → codex_ai-0.2.3}/tests/unit/core/test_protocol.py

@@ -106,6 +106,7 @@ def test_image_generation_provider_structural_check():
             *,
             model: str | None = None,
             response_mime_type: str = "image/webp",
+            image_config: dict | None = None,
             **kwargs,
         ) -> tuple[bytes, str]:
             return b"image", response_mime_type

{codex_ai-0.2.1 → codex_ai-0.2.3}/tests/unit/providers/test_gemini_provider.py

@@ -384,6 +384,19 @@ async def test_gemini_generate_image_bytes_uses_image_model_not_text_model():
     assert kwargs["contents"] == "draw a castle"
 
 
+async def test_gemini_generate_image_bytes_default_image_model_matches_api_id():
+    provider, mock_generate, _ = _make_provider()
+    mock_generate.return_value = _image_response()
+
+    with patch("codex_ai.providers.gemini.genai_types") as mock_types:
+        mock_types.Modality.IMAGE = "IMAGE"
+        mock_types.GenerateContentConfig.return_value = MagicMock()
+        await provider.generate_image_bytes("draw a castle")
+
+    _, kwargs = mock_generate.call_args
+    assert kwargs["model"] == "gemini-2.5-flash-image"
+
+
 async def test_gemini_generate_image_bytes_model_override_wins():
     provider, mock_generate, _ = _make_provider()
     provider._image_model = "image-model"
@@ -405,14 +418,43 @@ async def test_gemini_generate_image_bytes_config_requests_image_modality_not_te
     with patch("codex_ai.providers.gemini.genai_types") as mock_types:
         mock_types.Modality.IMAGE = "IMAGE"
         mock_types.GenerateContentConfig.return_value = MagicMock()
-        await provider.generate_image_bytes("draw a castle", response_mime_type="image/webp", seed=7)
+        await provider.generate_image_bytes(
+            "draw a castle",
+            response_mime_type="image/png",
+            image_config={"aspect_ratio": "1:1", "image_size": "4K"},
+            seed=7,
+        )
 
     config_kwargs = mock_types.GenerateContentConfig.call_args.kwargs
     assert config_kwargs["response_modalities"] == ["IMAGE"]
     assert "response_mime_type" not in config_kwargs
+    assert config_kwargs["image_config"] == {"aspect_ratio": "1:1", "image_size": "4K"}
     assert config_kwargs["seed"] == 7
 
 
+async def test_gemini_generate_image_bytes_falls_back_from_4k_to_2k_when_config_rejected():
+    provider, mock_generate, _ = _make_provider()
+    mock_generate.side_effect = [
+        ValueError("unsupported image_size"),
+        _image_response(data=b"png", mime_type="image/png"),
+    ]
+
+    with patch("codex_ai.providers.gemini.genai_types") as mock_types:
+        mock_types.Modality.IMAGE = "IMAGE"
+        mock_types.GenerateContentConfig.side_effect = lambda **kwargs: kwargs
+        result = await provider.generate_image_bytes(
+            "draw a castle",
+            response_mime_type="image/png",
+            image_config={"aspect_ratio": "1:1", "image_size": "4K"},
+        )
+
+    assert result == (b"png", "image/png")
+    first_config = mock_generate.call_args_list[0].kwargs["config"]
+    second_config = mock_generate.call_args_list[1].kwargs["config"]
+    assert first_config["image_config"] == {"aspect_ratio": "1:1", "image_size": "4K"}
+    assert second_config["image_config"] == {"aspect_ratio": "1:1", "image_size": "2K"}
+
+
 async def test_gemini_generate_image_bytes_returns_inline_image_bytes_and_actual_mime():
     provider, mock_generate, _ = _make_provider()
     mock_generate.return_value = _image_response(data=b"png-bytes", mime_type="image/png")

{codex_ai-0.2.1 → codex_ai-0.2.3}/uv.lock

@@ -344,9 +344,9 @@ requires-dist = [
     { name = "bandit", marker = "extra == 'dev'", specifier = ">=1.7" },
     { name = "codex-core", specifier = ">=0.2.2,<0.4.0" },
     { name = "detect-secrets", marker = "extra == 'dev'", specifier = ">=1.5" },
-    { name = "google-genai", marker = "extra == 'all'", specifier = "==1.68.0" },
-    { name = "google-genai", marker = "extra == 'dev'", specifier = "==1.68.0" },
-    { name = "google-genai", marker = "extra == 'gemini'", specifier = "==1.68.0" },
+    { name = "google-genai", marker = "extra == 'all'", specifier = "==2.3.0" },
+    { name = "google-genai", marker = "extra == 'dev'", specifier = "==2.3.0" },
+    { name = "google-genai", marker = "extra == 'gemini'", specifier = "==2.3.0" },
     { name = "mike", marker = "extra == 'docs'", specifier = ">=2.0" },
     { name = "mkdocs", marker = "extra == 'docs'", specifier = ">=1.5" },
     { name = "mkdocs-include-markdown-plugin", marker = "extra == 'docs'" },
@@ -622,7 +622,7 @@ requests = [
 
 [[package]]
 name = "google-genai"
-version = "1.68.0"
+version = "2.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -636,9 +636,9 @@ dependencies = [
     { name = "typing-extensions" },
     { name = "websockets" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/9c/2c/f059982dbcb658cc535c81bbcbe7e2c040d675f4b563b03cdb01018a4bc3/google_genai-1.68.0.tar.gz", hash = "sha256:ac30c0b8bc630f9372993a97e4a11dae0e36f2e10d7c55eacdca95a9fa14ca96", size = 511285, upload-time = "2026-03-18T01:03:18.243Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/02/8e/dfa4b34dd4c0baffccf6466fc68d6d35011662d43e7d79accb902320db74/google_genai-2.3.0.tar.gz", hash = "sha256:e877c750a4ccacdd9928fc3aa8ca8820ce85cade0ca51bd83feceacf5959b579", size = 546930, upload-time = "2026-05-15T06:22:36.264Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/84/de/7d3ee9c94b74c3578ea4f88d45e8de9405902f857932334d81e89bce3dfa/google_genai-1.68.0-py3-none-any.whl", hash = "sha256:a1bc9919c0e2ea2907d1e319b65471d3d6d58c54822039a249fe1323e4178d15", size = 750912, upload-time = "2026-03-18T01:03:15.983Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/6e/aa6b30b09f58b946750fc4089c5248fbd3576f746e0e818d88633559dc84/google_genai-2.3.0-py3-none-any.whl", hash = "sha256:89d3c71c9f5f5b931b405b88a5837aea2bd4d27ed90323b9599f5760bbb91d92", size = 805484, upload-time = "2026-05-15T06:22:34.247Z" },
 ]
 
 [[package]]