codex-ai 0.2.2__tar.gz → 0.2.4__tar.gz

{codex_ai-0.2.2 → codex_ai-0.2.4}/CHANGELOG.md

@@ -4,6 +4,15 @@ 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

{codex_ai-0.2.2 → codex_ai-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-ai
-Version: 0.2.2
+Version: 0.2.4
 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/
@@ -16,15 +16,15 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.12
-Requires-Dist: codex-core<0.4.0,>=0.2.2
+Requires-Dist: codex-core<0.5.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
@@ -49,10 +49,10 @@ Description-Content-Type: text/markdown
 
 [![PyPI version](https://img.shields.io/pypi/v/codex-ai.svg)](https://pypi.org/project/codex-ai/)
 [![Python](https://img.shields.io/pypi/pyversions/codex-ai.svg)](https://pypi.org/project/codex-ai/)
-[![CI](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml)
+[![CI](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/codexdlc/codex-ai/blob/main/LICENSE)
 
-Gemini-first and OpenAI provider helpers for the Codex ecosystem. The library keeps the legacy prompt router for text generation, and exposes direct provider methods for practical Gemini workflows.
+Gemini-first API helpers for the Codex ecosystem. The active surface is direct Gemini text, JSON, Gemini image, and Imagen generation. OpenAI remains as a small text-only adapter, and the router/dispatcher layer is kept for legacy text workflows.
 
 ## Install
 
@@ -83,9 +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.",
-    model="gemini-2.5-flash-image",
-    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(
@@ -98,11 +99,13 @@ 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`.
 
-## Router Pipeline
+## Legacy Text Router
 
 ```python
 from codex_ai import GeminiProvider, LLMDispatcher, LLMMessage, LLMRouter, PromptResult
@@ -124,13 +127,17 @@ dispatcher.include_router(router)
 response = await dispatcher.process("chat", text="Hello!")
 ```
 
+Use this path only when you already have prompt builders registered through `LLMRouter`.
+New Gemini integrations should call `generate_text()`, `generate_json()`,
+`generate_image_bytes()`, or `generate_imagen_bytes()` directly.
+
 ## Modules
 
 | Module | Extra | Description |
 | :--- | :--- | :--- |
-| `codex_ai.core` | - | Dispatcher, router, protocol types, sync wrapper, and shared exception contract |
-| `codex_ai.providers.gemini` | `[gemini]` | Google Gemini text, JSON, Gemini image, and Imagen generation via pinned `google-genai` |
-| `codex_ai.providers.openai` | `[openai]` | OpenAI Chat Completions text provider |
+| `codex_ai.providers.gemini` | `[gemini]` | Primary API: Gemini text, JSON, Gemini image, and Imagen generation via pinned `google-genai` |
+| `codex_ai.providers.openai` | `[openai]` | Text-only OpenAI Chat Completions adapter |
+| `codex_ai.core` | - | Legacy text router/dispatcher contracts and shared provider exceptions |
 
 ## Development
 

{codex_ai-0.2.2 → codex_ai-0.2.4}/README.md

@@ -2,10 +2,10 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/codex-ai.svg)](https://pypi.org/project/codex-ai/)
 [![Python](https://img.shields.io/pypi/pyversions/codex-ai.svg)](https://pypi.org/project/codex-ai/)
-[![CI](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml)
+[![CI](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/codexdlc/codex-ai/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/codexdlc/codex-ai/blob/main/LICENSE)
 
-Gemini-first and OpenAI provider helpers for the Codex ecosystem. The library keeps the legacy prompt router for text generation, and exposes direct provider methods for practical Gemini workflows.
+Gemini-first API helpers for the Codex ecosystem. The active surface is direct Gemini text, JSON, Gemini image, and Imagen generation. OpenAI remains as a small text-only adapter, and the router/dispatcher layer is kept for legacy text workflows.
 
 ## Install
 
@@ -36,9 +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.",
-    model="gemini-2.5-flash-image",
-    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(
@@ -51,11 +52,13 @@ 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`.
 
-## Router Pipeline
+## Legacy Text Router
 
 ```python
 from codex_ai import GeminiProvider, LLMDispatcher, LLMMessage, LLMRouter, PromptResult
@@ -77,13 +80,17 @@ dispatcher.include_router(router)
 response = await dispatcher.process("chat", text="Hello!")
 ```
 
+Use this path only when you already have prompt builders registered through `LLMRouter`.
+New Gemini integrations should call `generate_text()`, `generate_json()`,
+`generate_image_bytes()`, or `generate_imagen_bytes()` directly.
+
 ## Modules
 
 | Module | Extra | Description |
 | :--- | :--- | :--- |
-| `codex_ai.core` | - | Dispatcher, router, protocol types, sync wrapper, and shared exception contract |
-| `codex_ai.providers.gemini` | `[gemini]` | Google Gemini text, JSON, Gemini image, and Imagen generation via pinned `google-genai` |
-| `codex_ai.providers.openai` | `[openai]` | OpenAI Chat Completions text provider |
+| `codex_ai.providers.gemini` | `[gemini]` | Primary API: Gemini text, JSON, Gemini image, and Imagen generation via pinned `google-genai` |
+| `codex_ai.providers.openai` | `[openai]` | Text-only OpenAI Chat Completions adapter |
+| `codex_ai.core` | - | Legacy text router/dispatcher contracts and shared provider exceptions |
 
 ## Development
 

{codex_ai-0.2.2 → codex_ai-0.2.4}/docs/en/architecture/core/README.md

@@ -2,19 +2,22 @@
 
 ## Purpose
 
-`codex_ai.core` is the orchestration layer for LLM interactions. It decouples prompt construction from provider selection — prompt logic is defined once and can be routed to any backend without changes.
+`codex_ai.core` is the legacy text orchestration layer. It keeps existing `LLMRouter`/`LLMDispatcher` prompt-builder workflows working while the active API surface moves to direct provider methods.
 
 ## Why It's a Module
 
-Working directly with LLM SDKs across a codebase creates three recurring problems:
+Older Codex integrations use mode-based prompt builders. This module keeps that shape stable without making it the primary abstraction for new work:
 
-| Problem | What breaks |
-|---------|-------------|
-| Prompt logic scattered across call sites | Hard to test, review, or reuse |
-| Provider SDK calls coupled to business code | Switching providers requires touching every call |
-| No unified contract for async/sync contexts | Different wiring for Django views, ARQ workers, bots |
+| Need | Current role |
+|------|--------------|
+| Keep registered prompt builders working | `LLMRouter` maps modes to builders |
+| Run existing text flows without rewriting callers | `LLMDispatcher.process()` still calls `provider.answer()` |
+| Bridge sync-only contexts | `SyncLLMDispatcher` remains available for CLI/WSGI code |
 
-`core` solves these by introducing a clean pipeline:
+For new Gemini work, prefer `GeminiProvider.generate_text()`, `generate_json()`,
+`generate_image_bytes()`, and `generate_imagen_bytes()` directly.
+
+The retained text pipeline is:
 
 ```
 @router.prompt("mode") → PromptResult (frozen DTO) → LLMProviderProtocol.answer()
@@ -32,7 +35,7 @@ Working directly with LLM SDKs across a codebase creates three recurring problem
                      │ include_router(router)
                      ▼
           ┌──────────────────────┐
-          │    LLMDispatcher     │  orchestrates builder → provider
+          │    LLMDispatcher     │  legacy text builder → provider
           │                      │
           │  .process(mode, **kw)│
           └──────┬───────────────┘
@@ -52,19 +55,20 @@ Working directly with LLM SDKs across a codebase creates three recurring problem
 
 | Component | Class | Role |
 |-----------|-------|------|
-| `protocol.py` | `PromptResult` | Frozen DTO — immutable prompt passed to providers |
-| `protocol.py` | `LLMProviderProtocol` | Structural protocol — any class with `async answer()` qualifies |
+| `protocol.py` | `PromptResult` | Frozen DTO used by legacy text prompt builders |
+| `protocol.py` | `LLMProviderProtocol` | Structural text compatibility protocol for `answer()` |
 | `protocol.py` | `PromptBuilder` | Type alias for `async def (...) -> PromptResult` |
 | `router.py` | `LLMRouter` | Registry: maps `mode` strings to builder functions via decorator |
-| `dispatcher.py` | `LLMDispatcher` | Wires router + provider; single entry point for prompt execution |
+| `dispatcher.py` | `LLMDispatcher` | Runs legacy text prompts and delegates direct provider convenience methods |
 | `sync.py` | `SyncLLMDispatcher` | Wraps `LLMDispatcher` with `asyncio.run()` for WSGI/CLI contexts |
 | `exceptions.py` | `LLMProviderError` | Base exception raised by all provider implementations |
 
 ## Key Design Decisions
 
-- **Frozen DTO (`PromptResult`)** — built once by the builder, cannot be mutated downstream. Prevents accidental state sharing between requests.
-- **`@runtime_checkable` Protocol** — `isinstance(obj, LLMProviderProtocol)` works at runtime. No inheritance required from any base class.
-- **Mode-based dispatch** — `dispatcher.process("chat", ...)` maps to a registered builder. Adding a new prompt type never touches existing code.
+- **Direct provider APIs first** — Gemini capabilities are exposed as explicit methods instead of being forced through a universal provider interface.
+- **Frozen DTO (`PromptResult`)** — kept for legacy builders and cannot be mutated downstream.
+- **`@runtime_checkable` Protocol** — retained for runtime checks at compatibility boundaries.
+- **Mode-based dispatch is legacy text infrastructure** — `dispatcher.process("chat", ...)` maps to a registered builder for existing flows.
 - **All logs at `DEBUG`** — dispatcher emits only debug-level messages. Production log level controls visibility without code changes.
 - **`SyncLLMDispatcher` for Django only** — uses `asyncio.run()` which creates a new event loop. Never call from inside an async context (ARQ, async views, bots) — use `LLMDispatcher` directly.
 

{codex_ai-0.2.2 → codex_ai-0.2.4}/docs/en/architecture/core/data_flow.md

@@ -1,6 +1,8 @@
 # Core — Data Flow
 
-## Request Lifecycle
+## Legacy Text Request Lifecycle
+
+This flow is retained for existing `LLMRouter` integrations. New Gemini work should use direct provider methods.
 
 ```
 1. Application calls:
@@ -13,14 +15,14 @@
    prompt = await builder(text="Hello!")
    # → PromptResult(messages=[LLMMessage(role="user", content="Hello!")])
 
-4. Dispatcher calls provider:
+4. Dispatcher calls the text compatibility method:
    response = await self._provider.answer(prompt, **kw)
 
 5. Provider returns text:
    "Hi there! How can I help?"
 ```
 
-## Component Interactions
+## Legacy Component Interactions
 
 ```
 Application

{codex_ai-0.2.2 → codex_ai-0.2.4}/docs/en/architecture/providers/README.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-`codex_ai.providers` contains concrete provider adapters for the APIs currently supported by the library: Gemini and OpenAI.
+`codex_ai.providers` contains concrete SDK adapters, not a broad interchangeable provider framework. Gemini is the product focus; OpenAI is retained only for text generation.
 
 Gemini is the primary target and exposes direct methods for text, JSON, and image generation:
 
@@ -13,7 +13,7 @@ await gemini.generate_image_bytes(...)
 await gemini.generate_imagen_bytes(...)
 ```
 
-OpenAI is kept as a text provider with the same `generate_text(...)` convenience.
+OpenAI is kept as a text-only adapter with the same `generate_text(...)` convenience.
 
 ## Architecture
 
@@ -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.
+- Anthropic, OpenRouter, and multi-provider failover are not active APIs in this line.

{codex_ai-0.2.2 → codex_ai-0.2.4}/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.2 → codex_ai-0.2.4}/docs/ru/architecture/core/README.md

@@ -2,19 +2,21 @@
 
 ## Назначение
 
-`codex_ai.core` — оркестрационный слой для работы с LLM. Разделяет построение промпта и выбор провайдера: логика промптов описывается один раз и может быть направлена к любому бэкенду без изменений.
+`codex_ai.core` — legacy-слой текстовой оркестрации. Он сохраняет существующие workflow на `LLMRouter`/`LLMDispatcher`, пока активная API-поверхность переехала в прямые методы провайдеров.
 
 ## Зачем это модуль
 
-Прямая работа с LLM SDK по всей кодовой базе создаёт три повторяющихся проблемы:
+Старые Codex-интеграции используют mode-based prompt builders. Этот модуль сохраняет такую форму, но больше не является основной абстракцией для новой работы:
 
-| Проблема | Что ломается |
-|----------|-------------|
-| Логика промптов разбросана по call site-ам | Трудно тестировать, ревьювить и переиспользовать |
-| Вызовы SDK провайдера связаны с бизнес-кодом | Смена провайдера требует правок в каждом вызове |
-| Нет единого контракта для async/sync контекстов | Разная обвязка для Django views, ARQ workers, ботов |
+| Потребность | Текущая роль |
+|-------------|--------------|
+| Сохранить зарегистрированные prompt builders | `LLMRouter` связывает modes с билдерами |
+| Не переписывать существующие текстовые вызовы | `LLMDispatcher.process()` продолжает вызывать `provider.answer()` |
+| Поддержать sync-only контексты | `SyncLLMDispatcher` остается для CLI/WSGI кода |
 
-`core` решает это через единый pipeline:
+Для новой Gemini-интеграции лучше использовать прямые методы `GeminiProvider.generate_text()`, `generate_json()`, `generate_image_bytes()` и `generate_imagen_bytes()`.
+
+Сохраненный текстовый pipeline:
 
 ```
 @router.prompt("mode") → PromptResult (frozen DTO) → LLMProviderProtocol.answer()
@@ -32,7 +34,7 @@
                      │ include_router(router)
                      ▼
           ┌──────────────────────┐
-          │    LLMDispatcher     │  оркестрирует builder → provider
+          │    LLMDispatcher     │  legacy text builder → provider
           │                      │
           │  .process(mode, **kw)│
           └──────┬───────────────┘
@@ -52,19 +54,20 @@
 
 | Компонент | Класс | Роль |
 |-----------|-------|------|
-| `protocol.py` | `PromptResult` | Frozen DTO — иммутабельный промпт, передаваемый провайдерам |
-| `protocol.py` | `LLMProviderProtocol` | Структурный протокол — любой класс с `async answer()` подходит |
+| `protocol.py` | `PromptResult` | Frozen DTO для legacy text prompt builders |
+| `protocol.py` | `LLMProviderProtocol` | Структурный текстовый compatibility-протокол для `answer()` |
 | `protocol.py` | `PromptBuilder` | Type alias для `async def (...) -> PromptResult` |
 | `router.py` | `LLMRouter` | Реестр: связывает строки `mode` с функциями-билдерами через декоратор |
-| `dispatcher.py` | `LLMDispatcher` | Связывает router + provider; единая точка входа для выполнения промптов |
+| `dispatcher.py` | `LLMDispatcher` | Выполняет legacy text prompts и делегирует прямые provider convenience methods |
 | `sync.py` | `SyncLLMDispatcher` | Оборачивает `LLMDispatcher` через `asyncio.run()` для WSGI/CLI |
 | `exceptions.py` | `LLMProviderError` | Базовое исключение, поднимаемое всеми реализациями провайдеров |
 
 ## Ключевые решения
 
-- **Frozen DTO (`PromptResult`)** — строится один раз в билдере, не может быть изменён downstream. Исключает случайный shared state между запросами.
-- **`@runtime_checkable` Protocol** — `isinstance(obj, LLMProviderProtocol)` работает в runtime. Наследование от базового класса не требуется.
-- **Mode-based dispatch** — `dispatcher.process("chat", ...)` находит зарегистрированный билдер. Добавление нового типа промпта не затрагивает существующий код.
+- **Direct provider APIs first** — возможности Gemini раскрываются явными методами, а не проталкиваются через универсальный provider interface.
+- **Frozen DTO (`PromptResult`)** — сохранен для legacy builders и не может быть изменён downstream.
+- **`@runtime_checkable` Protocol** — оставлен для runtime-проверок на compatibility boundaries.
+- **Mode-based dispatch — legacy text infrastructure** — `dispatcher.process("chat", ...)` находит зарегистрированный билдер для существующих flows.
 - **Все логи на `DEBUG`** — диспетчер пишет только debug-сообщения. Уровень логирования в продакшне управляет видимостью без изменений кода.
 - **`SyncLLMDispatcher` только для Django** — использует `asyncio.run()`, создающий новый event loop. Никогда не вызывать из async-контекста (ARQ, async views, боты) — используйте `LLMDispatcher` напрямую.
 

{codex_ai-0.2.2 → codex_ai-0.2.4}/docs/ru/architecture/core/data_flow.md

@@ -1,6 +1,8 @@
 # Core — Поток данных
 
-## Жизненный цикл запроса
+## Жизненный цикл legacy text запроса
+
+Этот flow сохранен для существующих интеграций на `LLMRouter`. Новую Gemini-интеграцию лучше писать через прямые методы провайдера.
 
 ```
 1. Приложение вызывает:
@@ -13,14 +15,14 @@
    prompt = await builder(text="Привет!")
    # → PromptResult(messages=[LLMMessage(role="user", content="Привет!")])
 
-4. Диспетчер вызывает провайдер:
+4. Диспетчер вызывает текстовый compatibility method:
    response = await self._provider.answer(prompt, **kw)
 
 5. Провайдер возвращает текст:
    "Привет! Чем могу помочь?"
 ```
 
-## Взаимодействие компонентов
+## Взаимодействие legacy-компонентов
 
 ```
 Приложение

{codex_ai-0.2.2 → codex_ai-0.2.4}/docs/ru/architecture/providers/README.md

@@ -2,7 +2,7 @@
 
 ## Назначение
 
-`codex_ai.providers` содержит адаптеры для API, которые сейчас реально поддерживаются библиотекой: Gemini и OpenAI.
+`codex_ai.providers` содержит конкретные SDK-адаптеры, а не широкий interchangeable provider framework. Фокус продукта — Gemini; OpenAI сохранен только для текстовой генерации.
 
 Gemini является основным направлением и дает прямые методы для текста, JSON и картинок:
 
@@ -13,7 +13,7 @@ await gemini.generate_image_bytes(...)
 await gemini.generate_imagen_bytes(...)
 ```
 
-OpenAI оставлен как текстовый провайдер с `generate_text(...)`.
+OpenAI оставлен как text-only адаптер с `generate_text(...)`.
 
 ## Архитектура
 
@@ -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-линейке.
+- Anthropic, OpenRouter и multi-provider failover не являются активными API в этой линейке.

{codex_ai-0.2.2 → codex_ai-0.2.4}/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.2 → codex_ai-0.2.4}/pyproject.toml

@@ -20,7 +20,7 @@ classifiers = [
 ]
 dependencies = [
     "pydantic>=2.0,<3.0",
-    "codex-core>=0.2.2,<0.4.0",
+    "codex-core>=0.2.2,<0.5.0",
 ]
 
 [project.urls]
@@ -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.2 → codex_ai-0.2.4}/src/codex_ai/core/__init__.py

@@ -1,7 +1,7 @@
 """
 codex_ai.core
 =============
-Core types, contracts, and dispatching logic for the LLM abstraction layer.
+Core legacy text router, dispatcher, and provider compatibility contracts.
 """
 
 from .dispatcher import LLMDispatcher

{codex_ai-0.2.2 → codex_ai-0.2.4}/src/codex_ai/core/dispatcher.py

@@ -1,10 +1,10 @@
 """
 codex_ai.core.dispatcher
 =========================
-LLMDispatcher — orchestrates prompt building and LLM provider calls.
+LLMDispatcher — legacy text prompt dispatcher plus direct provider delegation.
 
 Registers routers, selects the correct builder by mode,
-and delegates response generation to the provider.
+and delegates text response generation to the provider's ``answer()`` method.
 """
 
 from __future__ import annotations
@@ -27,13 +27,14 @@ log = logging.getLogger(__name__)
 
 class LLMDispatcher:
     """
-    Orchestrates prompt building and LLM response generation.
+    Orchestrates legacy text prompt building and provider calls.
 
     Connects one or more LLMRouters, selects the builder by mode,
-    calls it with provided kwargs, then passes the result to the provider.
+    calls it with provided kwargs, then passes the result to the provider's
+    text compatibility ``answer()`` method.
 
     Args:
-        provider: LLM backend implementing LLMProviderProtocol.
+        provider: Text-compatible provider implementing LLMProviderProtocol.
 
     Example:
         ```python
@@ -96,6 +97,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 +116,7 @@ class LLMDispatcher:
             prompt,
             model=model,
             response_mime_type=response_mime_type,
+            image_config=image_config,
             **kwargs,
         )
 

{codex_ai-0.2.2 → codex_ai-0.2.4}/src/codex_ai/core/protocol.py

@@ -1,10 +1,10 @@
 """
 codex_ai.core.protocol
 =======================
-Core types and contracts for the LLM abstraction layer.
+Core types and contracts for legacy text routing and direct provider helpers.
 
 PromptResult — frozen DTO returned by every prompt builder.
-LLMProviderProtocol — adapter contract for LLM backends (OpenAI, Gemini, etc.).
+LLMProviderProtocol — legacy text compatibility contract for ``answer()``.
 TextGenerationProvider — optional adapter contract for direct text generation.
 JsonGenerationProvider — optional adapter contract for direct JSON generation.
 ImageGenerationProvider — optional adapter contract for binary image generation.
@@ -39,11 +39,10 @@ class PromptResult(BaseDTO):
     """
     Frozen DTO produced by a prompt builder.
 
-    Passed directly to the LLM provider's ``answer()`` method.
+    Passed directly to the provider's legacy text ``answer()`` method.
 
     Attributes:
-        messages: Provider-specific message list (OpenAI ChatCompletionMessageParam format
-                  or Gemini contents). Each provider interprets this field as needed.
+        messages: Ordered text message list consumed by compatibility adapters.
         system: Optional system/developer instruction (top-level string, used by Gemini
                 and OpenAI o-series models that accept a dedicated system field).
 
@@ -68,9 +67,11 @@ class PromptResult(BaseDTO):
 @runtime_checkable
 class LLMProviderProtocol(Protocol):
     """
-    Adapter contract for LLM backends.
+    Legacy text adapter contract.
 
-    Implement this protocol to add a new provider (OpenAI, Gemini, Anthropic, etc.).
+    New Gemini integrations should prefer direct provider methods such as
+    ``generate_text()``, ``generate_json()``, and ``generate_image_bytes()``.
+    This protocol remains for router/dispatcher text compatibility.
 
     Example:
         ```python
@@ -82,14 +83,14 @@ class LLMProviderProtocol(Protocol):
 
     async def answer(self, prompt: PromptResult, **kw: Any) -> str:
         """
-        Send prompt to the LLM and return the response text.
+        Send a legacy text prompt and return the response text.
 
         Args:
             prompt: Frozen DTO with messages and system instruction.
             **kw: Extra provider-specific kwargs (temperature, max_tokens, etc.).
 
         Returns:
-            Response text from the LLM.
+            Response text from the provider.
         """
         ...
 
@@ -148,6 +149,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 +159,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.2 → codex_ai-0.2.4}/src/codex_ai/providers/__init__.py

@@ -1,7 +1,7 @@
 """
 codex_ai.providers
 ==================
-Provider implementations (Gemini and OpenAI).
+Provider adapters. Gemini is the primary API; OpenAI is text-only.
 
 Providers are lazy-loaded to avoid mandatory dependency on all SDK packages.
 """

{codex_ai-0.2.2 → codex_ai-0.2.4}/src/codex_ai/providers/gemini.py

@@ -1,7 +1,7 @@
 """
 codex_ai.providers.gemini
 ==========================
-GeminiProvider — LLM provider backed by Google Gemini (google-genai).
+GeminiProvider — Gemini-first direct API backed by google-genai.
 
 Requires: ``pip install codex-ai[gemini]``
 """
@@ -34,9 +34,10 @@ _DEFAULT_IMAGEN_MODEL = "imagen-3.0-generate-002"
 
 class GeminiProvider:
     """
-    LLM provider using Google Gemini via the google-genai SDK.
+    Direct Gemini adapter using the google-genai SDK.
 
-    Implements LLMProviderProtocol.
+    Implements legacy text compatibility through ``answer()`` and exposes
+    direct Gemini methods for text, JSON, Gemini image, and Imagen generation.
 
     Args:
         api_key: Google AI API key.
@@ -186,6 +187,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 +208,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.2 → codex_ai-0.2.4}/src/codex_ai/providers/openai.py

@@ -1,7 +1,7 @@
 """
 codex_ai.providers.openai
 ==========================
-OpenAIProvider — LLM provider backed by OpenAI's Chat Completions API.
+OpenAIProvider — text-only adapter backed by OpenAI's Chat Completions API.
 
 Requires: ``pip install codex-ai[openai]``
 """
@@ -28,9 +28,10 @@ _DEFAULT_MODEL = "gpt-4o-mini"
 
 class OpenAIProvider:
     """
-    LLM provider using OpenAI Chat Completions.
+    Text-only adapter using OpenAI Chat Completions.
 
-    Implements LLMProviderProtocol.
+    Implements legacy text compatibility through ``answer()`` and direct
+    ``generate_text()`` convenience.
 
     Args:
         api_key: OpenAI API key.

{codex_ai-0.2.2 → codex_ai-0.2.4}/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.2 → codex_ai-0.2.4}/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.2 → codex_ai-0.2.4}/tests/unit/providers/test_gemini_provider.py

@@ -418,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.2 → codex_ai-0.2.4}/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]]