feat(providers): add OpenAI API package and migrate capabilities to mixins (withceleste#82)

* feat(providers): add OpenAI API package

Add standalone provider package for OpenAI APIs with mixin pattern
for capability-agnostic reuse across multiple endpoints.

## Images API (OpenAIImagesClient)
- HTTP POST/streaming to /v1/images/generations endpoint
- Supports DALL-E 2/3 (b64_json format) and gpt-image-1 (streaming)
- Usage parsing: input_tokens, output_tokens, total_tokens
- Content extraction from data array
- Revised prompt handling in metadata

## Responses API (OpenAIResponsesClient)
- HTTP POST/streaming to /v1/responses endpoint
- Unified API for text generation capabilities
- Usage parsing with cached and reasoning tokens support
- Content extraction from output array
- Finish reason mapping (completed status)

## Videos API (OpenAIVideosClient)
- Async polling workflow for video generation
- Phase 1: POST to /v1/videos to create job
- Phase 2: Poll GET /v1/videos/{id} until completed/failed
- Phase 3: GET /v1/videos/{id}/content to retrieve video
- Usage parsing: billing units (seconds)
- Multipart request support for input_reference images

## Audio API (OpenAIAudioClient)
- HTTP POST to /v1/audio/speech endpoint
- Binary audio response handling
- Response format mapping (mp3, opus, aac, flac, wav, pcm)
- MIME type conversion to AudioMimeType

All clients follow the mixin pattern for reuse across capabilities.

* fix(providers): add _parse_usage to GoogleVeoClient

Add _parse_usage method to GoogleVeoClient to resolve mypy type checking error.
GoogleVeoClient was missing this implementation, causing unsafe super() call
in GoogleVideoGenerationClient.

Google Veo API doesn't return usage data in the response, so this method
returns an empty dict that capability clients can wrap in their Usage type.

* refactor(speech-generation): rename RESPONSE_FORMAT to OUTPUT_FORMAT

Standardize parameter naming across speech generation capability.
Changes unified parameter name from RESPONSE_FORMAT to OUTPUT_FORMAT
to match enum definition and be more consistent with other capabilities.

Breaking change: Updates parameter name in:
- SpeechGenerationParameter enum
- SpeechGenerationParameters class
- All ElevenLabs models (9 occurrences)
- All OpenAI models (3 occurrences)
- Provider parameter mappers

* refactor(image-generation): migrate OpenAI and Google to provider mixins

Migrate image generation capability clients to use provider package mixins,
eliminating code duplication and centralizing API-specific logic.

## Changes
- OpenAI client now inherits from OpenAIImagesClient mixin
- Parameter mappers inherit from provider package mappers
- Google client uses super()._parse_usage() pattern
- Remove unused config.py file (config now in provider package)
- Remove revised_prompt handling from provider mixin (handled in capability)

## Code Reduction
- ~188 lines removed across client and parameter files
- Significant deduplication of HTTP request logic

* refactor(speech-generation): migrate OpenAI and ElevenLabs to provider mixins

Migrate speech generation capability clients to use provider package mixins,
eliminating code duplication and centralizing API-specific logic.

## Changes
- OpenAI client now inherits from OpenAIAudioClient mixin
- Parameter mappers inherit from provider package mappers
- Add SpeechGenerationFinishReason type for consistency
- Remove unused config.py file (config now in provider package)
- Update _create_inputs to use parameters.get() pattern
- Simplify VoiceConstraint docstring
- Update tests to reflect new structure

## Code Reduction
- ~187 lines removed across client and parameter files
- Significant deduplication of HTTP request and parameter mapping logic

* refactor(video-generation): migrate OpenAI and Google to provider mixins

Migrate video generation capability clients to use provider package mixins,
eliminating code duplication and centralizing API-specific logic.

## Changes
- OpenAI client now inherits from OpenAIVideosClient mixin
- Parameter mappers inherit from provider package mappers
- Google client uses super()._parse_usage() pattern (after Commit 1 fix)
- Remove unused config.py file (config now in provider package)
- Remove async polling logic (now in provider mixin)
- Simplify _parse_usage to use mixin's implementation

## Code Reduction
- ~178 lines removed across client and parameter files
- Significant deduplication of HTTP request and polling logic

* refactor(text-generation): migrate OpenAI to provider mixins and remove config files

Migrate text generation capability client to use provider package mixins,
eliminating code duplication and centralizing API-specific logic.

## Changes
- OpenAI client now inherits from OpenAIResponsesClient mixin
- Parameter mappers inherit from provider package mappers
- Streaming class inherits from OpenAIResponsesStream mixin
- Remove unused config.py file (config now in provider package)
- Simplify _parse_content to use mixin's output array parsing
- Simplify _parse_finish_reason to use mixin's implementation

## Code Reduction
- ~429 lines removed across client, parameters, and streaming files
- Significant deduplication of HTTP request, streaming, and schema logic

* fix(capabilities): add celeste-openai dependency to all capabilities

Add celeste-openai to [tool.uv.sources] in all capability packages that
now import from the OpenAI provider package after the mixin migration.

## Changes
- image-generation: Add celeste-openai (imports celeste_openai.images)
- speech-generation: Add celeste-openai (imports celeste_openai.audio)
- text-generation: Add celeste-openai (imports celeste_openai.responses)
- video-generation: Add celeste-openai (imports celeste_openai.videos)

This ensures workspace dependencies are properly declared for the
refactored capability clients that use OpenAI provider mixins.

Author: Kamilbenkirane

packages/capabilities/image-generation/pyproject.toml

@@ -29,6 +29,7 @@ Issues = "https://github.com/withceleste/celeste-python/issues"
 celeste-ai = { workspace = true }
 celeste-bfl = { workspace = true }
 celeste-google = { workspace = true }
+celeste-openai = { workspace = true }
 
 [project.entry-points."celeste.packages"]
 image-generation = "celeste_image_generation:register_package"

packages/capabilities/image-generation/src/celeste_image_generation/providers/google/imagen.py

@@ -39,8 +39,8 @@ def _init_request(self, inputs: ImageGenerationInput) -> dict[str, Any]:
 
     def _parse_usage(self, response_data: dict[str, Any]) -> ImageGenerationUsage:
         """Parse usage from response."""
-        predictions = response_data.get("predictions", [])
-        return ImageGenerationUsage(num_images=len(predictions))
+        usage = super()._parse_usage(response_data)
+        return ImageGenerationUsage(**usage)
 
     def _parse_content(
         self,

packages/capabilities/image-generation/src/celeste_image_generation/providers/openai/client.py

@@ -1,13 +1,11 @@
 """OpenAI client implementation for image generation."""
 
 import base64
-from collections.abc import AsyncIterator
 from typing import Any, Unpack
 
-import httpx
+from celeste_openai.images.client import OpenAIImagesClient
 
 from celeste.artifacts import ImageArtifact
-from celeste.mime_types import ApplicationMimeType
 from celeste.parameters import ParameterMapper
 from celeste_image_generation.client import ImageGenerationClient
 from celeste_image_generation.io import (
@@ -17,12 +15,11 @@
 )
 from celeste_image_generation.parameters import ImageGenerationParameters
 
-from . import config
 from .parameters import OPENAI_PARAMETER_MAPPERS
 from .streaming import OpenAIImageGenerationStream
 
 
-class OpenAIImageGenerationClient(ImageGenerationClient):
+class OpenAIImageGenerationClient(OpenAIImagesClient, ImageGenerationClient):
     """OpenAI client for image generation."""
 
     @classmethod
@@ -44,19 +41,17 @@ def _init_request(self, inputs: ImageGenerationInput) -> dict[str, Any]:
 
     def _parse_usage(self, response_data: dict[str, Any]) -> ImageGenerationUsage:
         """Parse usage from response."""
-        return ImageGenerationUsage()
+        usage = super()._parse_usage(response_data)
+        return ImageGenerationUsage(**usage)
 
     def _parse_content(
         self,
         response_data: dict[str, Any],
         **parameters: Unpack[ImageGenerationParameters],
     ) -> ImageArtifact:
         """Parse content from response."""
-        data = response_data.get("data", [])
-        if not data:
-            msg = "No image data in response"
-            raise ValueError(msg)
-
+        # Use mixin's _parse_content to get data array
+        data = super()._parse_content(response_data)
         image_data = data[0]
 
         b64_json = image_data.get("b64_json")
@@ -73,62 +68,13 @@ def _parse_content(
 
     def _parse_finish_reason(
         self, response_data: dict[str, Any]
-    ) -> ImageGenerationFinishReason | None:
-        """Parse finish reason from response."""
-        return None
-
-    def _build_metadata(self, response_data: dict[str, Any]) -> dict[str, Any]:
-        """Build metadata dictionary from response data."""
-        metadata = super()._build_metadata(response_data)
-        # Add provider-specific parsed fields
-        if response_data.get("data") and response_data["data"]:
-            revised_prompt = response_data["data"][0].get("revised_prompt")
-            if revised_prompt:
-                metadata["revised_prompt"] = revised_prompt
-        return metadata
-
-    async def _make_request(
-        self,
-        request_body: dict[str, Any],
-        **parameters: Unpack[ImageGenerationParameters],
-    ) -> httpx.Response:
-        """Make HTTP request(s) and return response object."""
-        headers = {
-            **self.auth.get_headers(),
-            "Content-Type": ApplicationMimeType.JSON,
-        }
-
-        return await self.http_client.post(
-            f"{config.BASE_URL}{config.ENDPOINT}",
-            headers=headers,
-            json_body=request_body,
-        )
+    ) -> ImageGenerationFinishReason:
+        """OpenAI Images API doesn't provide finish reasons."""
+        return ImageGenerationFinishReason(reason=None)
 
     def _stream_class(self) -> type[OpenAIImageGenerationStream]:
         """Return the Stream class for this client."""
         return OpenAIImageGenerationStream
 
-    def _make_stream_request(
-        self,
-        request_body: dict[str, Any],
-        **parameters: Unpack[ImageGenerationParameters],
-    ) -> AsyncIterator[dict[str, Any]]:
-        """Make HTTP streaming request and return async iterator of events."""
-        request_body["stream"] = True
-
-        if "partial_images" not in request_body:
-            request_body["partial_images"] = 1
-
-        headers = {
-            **self.auth.get_headers(),
-            "Content-Type": ApplicationMimeType.JSON,
-        }
-
-        return self.http_client.stream_post(
-            f"{config.BASE_URL}{config.STREAM_ENDPOINT}",
-            headers=headers,
-            json_body=request_body,
-        )
-
 
 __all__ = ["OpenAIImageGenerationClient"]

packages/capabilities/image-generation/src/celeste_image_generation/providers/openai/config.py

@@ -1,113 +1,30 @@
-"""OpenAI parameter mappers for image generation."""
+"""OpenAI Images parameter mappers for image generation."""
+
+from celeste_openai.images.parameters import (
+    PartialImagesMapper as _PartialImagesMapper,
+)
+from celeste_openai.images.parameters import (
+    QualityMapper as _QualityMapper,
+)
+from celeste_openai.images.parameters import (
+    SizeMapper as _SizeMapper,
+)
 
-from typing import Any
-
-from celeste import Model
 from celeste.parameters import ParameterMapper
 from celeste_image_generation.parameters import ImageGenerationParameter
 
 
-class AspectRatioMapper(ParameterMapper):
-    """Map aspect_ratio parameter to OpenAI's size parameter."""
-
+class AspectRatioMapper(_SizeMapper):
     name = ImageGenerationParameter.ASPECT_RATIO
 
-    def map(
-        self,
-        request: dict[str, Any],
-        value: object,
-        model: Model,
-    ) -> dict[str, Any]:
-        """Transform aspect_ratio into provider request.
-
-        Maps unified aspect_ratio parameter to OpenAI's size format.
-        Values are OpenAI's native size strings (e.g., "1024x1024", "1792x1024").
-        Coercion from ratio format ("16:9") to size format can be added later.
-
-        Args:
-            request: Provider request dictionary to modify.
-            value: The aspect_ratio value (OpenAI size string).
-            model: Model instance with parameter constraints.
-
-        Returns:
-            Modified request dictionary with size parameter.
-        """
-        validated_value = self._validate_value(value, model)
-        if validated_value is None:
-            return request
-
-        # Transform to provider-specific request format (size parameter)
-        request["size"] = validated_value
-        return request
-
-
-class PartialImagesMapper(ParameterMapper):
-    """Map partial_images parameter for streaming."""
 
+class PartialImagesMapper(_PartialImagesMapper):
     name = ImageGenerationParameter.PARTIAL_IMAGES
 
-    def map(
-        self,
-        request: dict[str, Any],
-        value: object,
-        model: Model,
-    ) -> dict[str, Any]:
-        """Transform partial_images into provider request.
-
-        Controls number of partial images during streaming (0-3).
-
-        Args:
-            request: Provider request dictionary to modify.
-            value: The partial_images value (0-3).
-            model: Model instance with parameter constraints.
-
-        Returns:
-            Modified request dictionary with partial_images parameter.
-        """
-        validated_value = self._validate_value(value, model)
-        if validated_value is None:
-            return request
-
-        # Transform to provider-specific request format (top-level field)
-        request["partial_images"] = validated_value
-        return request
-
-
-class QualityMapper(ParameterMapper):
-    """Map quality parameter"""
 
+class QualityMapper(_QualityMapper):
     name = ImageGenerationParameter.QUALITY
 
-    def map(
-        self,
-        request: dict[str, Any],
-        value: object,
-        model: Model,
-    ) -> dict[str, Any]:
-        """Transform quality into provider request.
-
-        Controls image quality/detail level.
-        - DALL-E 3: "standard" or "hd"
-        - gpt-image-1: "low", "medium", "high", or "auto"
-        - gpt-image-1-mini: "low", "medium", "high", or "auto"
-        - DALL-E 2: Not supported (no constraint in model)
-
-        Args:
-            request: Provider request dictionary to modify.
-            value: The quality value.
-            model: Model instance with parameter constraints.
-
-        Returns:
-            Modified request dictionary with quality parameter.
-        """
-        validated_value = self._validate_value(value, model)
-        if validated_value is None:
-            return request
-
-        # Transform to provider-specific request format (top-level field)
-        request["quality"] = validated_value
-        return request
-
 
 OPENAI_PARAMETER_MAPPERS: list[ParameterMapper] = [
     AspectRatioMapper(),

packages/capabilities/image-generation/src/celeste_image_generation/providers/openai/parameters.py

@@ -1 +1 @@
-"""Integration tests for image generation capability."""
+"""Image generation integration test module."""

packages/capabilities/image-generation/tests/integration_tests/test_image_generation/__init__.py

@@ -27,6 +27,7 @@ Issues = "https://github.com/withceleste/celeste-python/issues"
 
 [tool.uv.sources]
 celeste-ai = { workspace = true }
+celeste-openai = { workspace = true }
 
 [project.entry-points."celeste.packages"]
 speech-generation = "celeste_speech_generation:register_package"

packages/capabilities/speech-generation/pyproject.toml

@@ -38,14 +38,12 @@ def _parse_content(
         """Parse content from provider response."""
 
     def _create_inputs(
-        self,
-        *args: str,
-        text: str | None = None,
-        **parameters: Unpack[SpeechGenerationParameters],
+        self, *args: str, **parameters: Unpack[SpeechGenerationParameters]
     ) -> SpeechGenerationInput:
         """Map positional arguments to Input type."""
         if args:
             return SpeechGenerationInput(text=args[0])
+        text: str | None = parameters.get("text")
         if text is None:
             msg = "text is required (either as positional argument or keyword argument)"
             raise ValidationError(msg)

packages/capabilities/speech-generation/src/celeste_speech_generation/client.py

@@ -8,10 +8,7 @@
 
 
 class VoiceConstraint(Constraint):
-    """Voice constraint - value must be a valid voice ID or name from the provided voices.
-
-    Accepts both voice IDs and names. If a name is provided, returns the corresponding ID.
-    """
+    """Voice constraint - value must be a valid voice ID from the provided voices."""
 
     voices: list[Voice] = Field(min_length=1)
 

packages/capabilities/speech-generation/src/celeste_speech_generation/constraints.py

@@ -1,7 +1,7 @@
 """Input and output types for speech generation."""
 
 from celeste.artifacts import AudioArtifact
-from celeste.io import Chunk, Input, Output, Usage
+from celeste.io import Chunk, FinishReason, Input, Output, Usage
 
 
 class SpeechGenerationInput(Input):
@@ -17,23 +17,26 @@ class SpeechGenerationUsage(Usage):
     """
 
 
+class SpeechGenerationFinishReason(FinishReason):
+    """Finish reason for speech generation."""
+
+
 class SpeechGenerationOutput(Output[AudioArtifact]):
     """Output with audio artifact content."""
 
 
 class SpeechGenerationChunk(Chunk[bytes]):
     """Typed chunk for speech generation streaming.
 
-    Note: Unlike TextGenerationChunk, this class intentionally omits a finish_reason
-    field. TTS providers stream raw audio bytes without completion signals - the
-    stream simply ends when audio generation is complete.
+    Speech streaming sends raw bytes without finish_reason.
     """
 
     usage: SpeechGenerationUsage | None = None
 
 
 __all__ = [
     "SpeechGenerationChunk",
+    "SpeechGenerationFinishReason",
     "SpeechGenerationInput",
     "SpeechGenerationOutput",
     "SpeechGenerationUsage",