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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-ai
-Version: 0.2.3
+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,7 +16,7 @@ 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'
@@ -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
 
@@ -105,7 +105,7 @@ 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
@@ -127,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.3 → 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
 
@@ -58,7 +58,7 @@ 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
@@ -80,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.3 → 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.3 → 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.3 → 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
 
@@ -50,4 +50,4 @@ LLMRouter builder -> PromptResult -> LLMDispatcher.process() -> provider.answer(
 - `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.3 → 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.3 → 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.3 → 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(...)`.
 
 ## Архитектура
 
@@ -50,4 +50,4 @@ LLMRouter builder -> PromptResult -> LLMDispatcher.process() -> provider.answer(
 - `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.3 → 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]

{codex_ai-0.2.3 → 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.3 → 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

{codex_ai-0.2.3 → 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.
         """
         ...
 

{codex_ai-0.2.3 → 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.3 → 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.

{codex_ai-0.2.3 → 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.