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

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

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-07-19
+
+### Added
+- Added `ImageInput` and optional `input_images` support to Gemini `generate_image_bytes()` for image reference/edit workflows.
+- Added OpenAI structured output generation through `generate_json()` with native Pydantic parsing.
+- Added typed OpenAI Responses API text streaming through `stream_text()`.
+
+### Changed
+- Replaced the OpenAI Chat Completions implementation with the Responses API.
+- Updated the OpenAI SDK requirement to `openai>=2.0,<3.0`.
+- Changed the OpenAI default model to `gpt-5.6-luna` with `reasoning={"effort": "none"}` and `store=False` defaults.
+
+## [0.2.4] - 2026-05-21
+
+### Changed
+- Widened the supported `codex-core` range to include the `0.4.x` series.
+- Clarified the Gemini-first provider focus in the package documentation.
+
 ## [0.2.3] - 2026-05-17
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-ai
-Version: 0.2.3
+Version: 0.2.5
 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,17 +16,17 @@ 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==2.3.0; extra == 'all'
-Requires-Dist: openai<2.0,>=1.0; extra == 'all'
+Requires-Dist: openai<3.0,>=2.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==2.3.0; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: openai<2.0,>=1.0; extra == 'dev'
+Requires-Dist: openai<3.0,>=2.0; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: pre-commit>=3.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -42,17 +42,17 @@ Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Provides-Extra: gemini
 Requires-Dist: google-genai==2.3.0; extra == 'gemini'
 Provides-Extra: openai
-Requires-Dist: openai<2.0,>=1.0; extra == 'openai'
+Requires-Dist: openai<3.0,>=2.0; extra == 'openai'
 Description-Content-Type: text/markdown
 
 # codex-ai <!-- Type: LANDING -->
 
 [![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 provides modern Responses API text, structured JSON, and streaming helpers. The router/dispatcher layer is kept for legacy text workflows.
 
 ## Install
 
@@ -68,9 +68,11 @@ Requires Python 3.12 or newer.
 ## Gemini Direct API
 
 ```python
+from pathlib import Path
+
 from pydantic import BaseModel
 
-from codex_ai import GeminiProvider
+from codex_ai import GeminiProvider, ImageInput
 
 
 class LootItem(BaseModel):
@@ -89,6 +91,13 @@ image_bytes, content_type = await gemini.generate_image_bytes(
     image_config={"aspect_ratio": "1:1", "image_size": "4K"},
 )
 
+source_image_bytes = Path("source.png").read_bytes()
+edited_bytes, edited_content_type = await gemini.generate_image_bytes(
+    "Keep the composition, but redraw it as a watercolor map.",
+    response_mime_type="image/png",
+    input_images=[ImageInput(data=source_image_bytes, mime_type="image/png")],
+)
+
 imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
     "A fantasy clan banner, game icon style.",
     response_mime_type="image/jpeg",
@@ -101,11 +110,40 @@ imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
 `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. 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
+the Gemini provider retries once with `2K`. Pass `input_images` with `ImageInput`
+items to provide reference/edit-source images for Gemini image models. Use `generate_imagen_bytes()` for
 Imagen models; that path uses `generate_images` and passes the requested MIME as
 `output_mime_type`.
 
-## Router Pipeline
+## OpenAI Responses API
+
+```python
+from pydantic import BaseModel
+
+from codex_ai import OpenAIProvider
+
+
+class LootItem(BaseModel):
+    name: str
+    power: int
+
+
+openai = OpenAIProvider(api_key="sk-...")
+
+text = await openai.generate_text("Write one short tavern rumor.")
+loot = await openai.generate_json("Create one loot item.", schema=LootItem)
+
+async for chunk in openai.stream_text("Tell a short story."):
+    print(chunk, end="")
+```
+
+The OpenAI provider uses the Responses API and the `openai` 2.x SDK. Responses
+are not stored by default. Its default `gpt-5.6-luna` model uses
+`reasoning={"effort": "none"}` to retain a cost- and latency-sensitive role;
+override the model and reasoning options per request when a workload needs more
+capability.
+
+## Legacy Text Router
 
 ```python
 from codex_ai import GeminiProvider, LLMDispatcher, LLMMessage, LLMRouter, PromptResult
@@ -127,13 +165,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]` | OpenAI Responses API text, structured JSON, and streaming adapter |
+| `codex_ai.core` | - | Legacy text router/dispatcher contracts and shared provider exceptions |
 
 ## Development
 

{codex_ai-0.2.3 → codex_ai-0.2.5}/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 provides modern Responses API text, structured JSON, and streaming helpers. The router/dispatcher layer is kept for legacy text workflows.
 
 ## Install
 
@@ -21,9 +21,11 @@ Requires Python 3.12 or newer.
 ## Gemini Direct API
 
 ```python
+from pathlib import Path
+
 from pydantic import BaseModel
 
-from codex_ai import GeminiProvider
+from codex_ai import GeminiProvider, ImageInput
 
 
 class LootItem(BaseModel):
@@ -42,6 +44,13 @@ image_bytes, content_type = await gemini.generate_image_bytes(
     image_config={"aspect_ratio": "1:1", "image_size": "4K"},
 )
 
+source_image_bytes = Path("source.png").read_bytes()
+edited_bytes, edited_content_type = await gemini.generate_image_bytes(
+    "Keep the composition, but redraw it as a watercolor map.",
+    response_mime_type="image/png",
+    input_images=[ImageInput(data=source_image_bytes, mime_type="image/png")],
+)
+
 imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
     "A fantasy clan banner, game icon style.",
     response_mime_type="image/jpeg",
@@ -54,11 +63,40 @@ imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
 `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. 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
+the Gemini provider retries once with `2K`. Pass `input_images` with `ImageInput`
+items to provide reference/edit-source images for Gemini image models. Use `generate_imagen_bytes()` for
 Imagen models; that path uses `generate_images` and passes the requested MIME as
 `output_mime_type`.
 
-## Router Pipeline
+## OpenAI Responses API
+
+```python
+from pydantic import BaseModel
+
+from codex_ai import OpenAIProvider
+
+
+class LootItem(BaseModel):
+    name: str
+    power: int
+
+
+openai = OpenAIProvider(api_key="sk-...")
+
+text = await openai.generate_text("Write one short tavern rumor.")
+loot = await openai.generate_json("Create one loot item.", schema=LootItem)
+
+async for chunk in openai.stream_text("Tell a short story."):
+    print(chunk, end="")
+```
+
+The OpenAI provider uses the Responses API and the `openai` 2.x SDK. Responses
+are not stored by default. Its default `gpt-5.6-luna` model uses
+`reasoning={"effort": "none"}` to retain a cost- and latency-sensitive role;
+override the model and reasoning options per request when a workload needs more
+capability.
+
+## Legacy Text Router
 
 ```python
 from codex_ai import GeminiProvider, LLMDispatcher, LLMMessage, LLMRouter, PromptResult
@@ -80,13 +118,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]` | OpenAI Responses API text, structured JSON, and streaming adapter |
+| `codex_ai.core` | - | Legacy text router/dispatcher contracts and shared provider exceptions |
 
 ## Development
 

{codex_ai-0.2.3 → codex_ai-0.2.5}/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.3 → codex_ai-0.2.5}/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.3 → codex_ai-0.2.5}/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 a separate modern Responses API adapter.
 
 Gemini is the primary target and exposes direct methods for text, JSON, and image generation:
 
@@ -13,7 +13,14 @@ await gemini.generate_image_bytes(...)
 await gemini.generate_imagen_bytes(...)
 ```
 
-OpenAI is kept as a text provider with the same `generate_text(...)` convenience.
+OpenAI exposes direct text, structured JSON, and typed streaming helpers:
+
+```python
+await openai.generate_text(...)
+await openai.generate_json(..., schema=MyModel)
+async for chunk in openai.stream_text(...):
+    ...
+```
 
 ## Architecture
 
@@ -24,7 +31,9 @@ PromptResult/String
       ├── GeminiProvider.generate_json(...)        -> dict | BaseModel
       ├── GeminiProvider.generate_image_bytes(...) -> tuple[bytes, str]
       ├── GeminiProvider.generate_imagen_bytes(...) -> tuple[bytes, str]
-      └── OpenAIProvider.generate_text(...)        -> str
+      ├── OpenAIProvider.generate_text(...)        -> str
+      ├── OpenAIProvider.generate_json(...)        -> dict | BaseModel
+      └── OpenAIProvider.stream_text(...)          -> AsyncIterator[str]
 ```
 
 The legacy router pipeline remains available:
@@ -40,14 +49,19 @@ LLMRouter builder -> PromptResult -> LLMDispatcher.process() -> provider.answer(
 | Component | Class | SDK | Default Model |
 |-----------|-------|-----|---------------|
 | `gemini.py` | `GeminiProvider` | `google-genai` | `gemini-2.5-flash-lite` |
-| `openai.py` | `OpenAIProvider` | `openai` | `gpt-4o-mini` |
+| `openai.py` | `OpenAIProvider` | `openai` 2.x | `gpt-5.6-luna` |
 
 ## Key Design Decisions
 
 - 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.
+- OpenAI uses the Responses API exclusively; the old Chat Completions path is not retained.
+- OpenAI requests default to `store=False` and `reasoning={"effort": "none"}`.
+- OpenAI Pydantic schemas use the SDK's native `responses.parse()` structured-output path.
+- The OpenAI SDK client is injectable behind a small Responses API port for deterministic tests and custom transports.
 - 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, and Gemini image controls are passed through `image_config`.
+- `generate_image_bytes()` can also accept `input_images=[ImageInput(...)]` for image reference/edit workflows; without `input_images`, the prompt-only path is unchanged.
 - `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.3 → codex_ai-0.2.5}/docs/en/architecture/providers/data_flow.md

@@ -33,6 +33,16 @@ prompt: str
     -> (bytes, actual_mime_type)
 ```
 
+With `input_images`, the provider sends multimodal content:
+
+```
+prompt: str + input_images: list[ImageInput]
+    -> text part + inline_data image parts
+    -> GeminiProvider.generate_image_bytes()
+    -> first returned 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`.
 
@@ -51,7 +61,30 @@ prompt: str
 ```
 PromptResult | str
     -> OpenAIProvider.generate_text()
-    -> chat.completions.create()
-    -> choices[0].message.content
+    -> _OpenAIRequestMapper
+    -> responses.create(store=False)
+    -> response.output_text
     -> str
 ```
+
+## OpenAI Structured JSON
+
+```
+PromptResult | str + Pydantic schema
+    -> OpenAIProvider.generate_json()
+    -> responses.parse(text_format=schema)
+    -> response.output_parsed
+    -> BaseModel
+```
+
+Without a schema, the provider requests JSON mode and decodes `response.output_text`.
+
+## OpenAI Streaming
+
+```
+PromptResult | str
+    -> OpenAIProvider.stream_text()
+    -> responses.create(stream=True)
+    -> response.output_text.delta events
+    -> AsyncIterator[str]
+```

{codex_ai-0.2.3 → codex_ai-0.2.5}/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.3 → codex_ai-0.2.5}/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.3 → codex_ai-0.2.5}/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 является отдельным современным адаптером Responses API.
 
 Gemini является основным направлением и дает прямые методы для текста, JSON и картинок:
 
@@ -13,7 +13,14 @@ await gemini.generate_image_bytes(...)
 await gemini.generate_imagen_bytes(...)
 ```
 
-OpenAI оставлен как текстовый провайдер с `generate_text(...)`.
+OpenAI предоставляет прямые методы для текста, структурированного JSON и typed streaming:
+
+```python
+await openai.generate_text(...)
+await openai.generate_json(..., schema=MyModel)
+async for chunk in openai.stream_text(...):
+    ...
+```
 
 ## Архитектура
 
@@ -24,7 +31,9 @@ PromptResult/String
       ├── GeminiProvider.generate_json(...)        -> dict | BaseModel
       ├── GeminiProvider.generate_image_bytes(...) -> tuple[bytes, str]
       ├── GeminiProvider.generate_imagen_bytes(...) -> tuple[bytes, str]
-      └── OpenAIProvider.generate_text(...)        -> str
+      ├── OpenAIProvider.generate_text(...)        -> str
+      ├── OpenAIProvider.generate_json(...)        -> dict | BaseModel
+      └── OpenAIProvider.stream_text(...)          -> AsyncIterator[str]
 ```
 
 Старый router pipeline остается доступным:
@@ -40,14 +49,19 @@ LLMRouter builder -> PromptResult -> LLMDispatcher.process() -> provider.answer(
 | Компонент | Класс | SDK | Модель по умолчанию |
 |-----------|-------|-----|---------------------|
 | `gemini.py` | `GeminiProvider` | `google-genai` | `gemini-2.5-flash-lite` |
-| `openai.py` | `OpenAIProvider` | `openai` | `gpt-4o-mini` |
+| `openai.py` | `OpenAIProvider` | `openai` 2.x | `gpt-5.6-luna` |
 
 ## Ключевые решения
 
 - Возможности Gemini представлены напрямую, без широкой универсальной абстракции.
 - JSON generation использует native JSON config провайдера и локальную проверку через `json.loads` и optional Pydantic schema.
+- OpenAI использует только Responses API; старый путь Chat Completions не сохраняется.
+- OpenAI-запросы по умолчанию используют `store=False` и `reasoning={"effort": "none"}`.
+- Pydantic-схемы OpenAI обрабатываются через native structured-output путь `responses.parse()`.
+- OpenAI SDK client можно внедрить через небольшой Responses API port для детерминированных тестов и custom transport.
 - Gemini image generation и Imagen generation разведены в отдельные явные методы, потому что они используют разные SDK calls.
 - `generate_image_bytes()` использует Gemini `generate_content` с image modality. Его `response_mime_type` является только preferred/fallback MIME type, а Gemini image controls передаются через `image_config`.
+- `generate_image_bytes()` также принимает `input_images=[ImageInput(...)]` для сценариев reference/edit; без `input_images` старый prompt-only путь не меняется.
 - `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 в этой линейке.