refactor: make _parse_content a pure parser, add Chunk type param (#203)

* refactor: make _parse_content a pure parser, add Chunk type param

- Remove **parameters from _parse_content across ~28 provider clients,
  base abstract method, docstrings, templates, and tests
- Add 5th type parameter (Chunk) to ModalityClient and all 5 modality
  base clients for correct mypy typing of _stream_class overrides
- Eliminate 4 duplicated _transform_output overrides in audio providers
  by implementing parse_output() on their OutputFormatMapper mappers
- Remove if-value-is-not-None guard in base _transform_output so
  parse_output() always runs (safe: default is no-op)

Closes #202

* fix: imagen _parse_content regression for empty images

When predictions exist but none contain valid image data, _parse_content
now returns [] instead of ImageArtifact() sentinel, preventing
_transform_output from wrapping it into [ImageArtifact()].

* fix: use dict.get pattern for audio MIME type mapping

- Google Cloud TTS: replace try/except + AudioMimeType(value) with
  _mime_map dict.get, consistent with all other audio providers
- OpenAI: remove "wav"/"pcm" from _mime_map since map() cannot send
  these formats to the API

Author: Kamilbenkirane

src/celeste/client.py

@@ -12,7 +12,8 @@
 from celeste.core import Modality, Provider
 from celeste.exceptions import StreamingNotSupportedError
 from celeste.http import HTTPClient, get_http_client
-from celeste.io import Chunk, FinishReason, Input, Output, Usage
+from celeste.io import Chunk as ChunkBase
+from celeste.io import FinishReason, Input, Output, Usage
 from celeste.mime_types import ApplicationMimeType
 from celeste.models import Model
 from celeste.parameters import ParameterMapper, Parameters
@@ -130,15 +131,19 @@ def _handle_error_response(self, response: httpx.Response) -> None:
         super()._handle_error_response(response)  # type: ignore[misc]
 
 
-class ModalityClient[In: Input, Out: Output, Params: Parameters, Content](
-    APIMixin, BaseModel
-):
+class ModalityClient[
+    In: Input,
+    Out: Output,
+    Params: Parameters,
+    Content,
+    Chunk: ChunkBase,
+](APIMixin, BaseModel):
     """Base class for unified modality clients.
 
     Operation methods in subclasses delegate to _predict().
 
     Example:
-        class ImagesClient(ModalityClient[ImagesInput, ImagesOutput, ImagesParameters, ImageContent]):
+        class ImagesClient(ModalityClient[ImagesInput, ImagesOutput, ImagesParameters, ImageContent, ImageChunk]):
             modality = Modality.IMAGES
 
             async def generate(self, prompt: str, **parameters) -> ImageGenerationOutput:
@@ -198,7 +203,7 @@ async def _predict(
         response_data = await self._make_request(
             request_body, endpoint=endpoint, extra_headers=extra_headers, **parameters
         )
-        content = self._parse_content(response_data, **parameters)
+        content = self._parse_content(response_data)
         content = self._transform_output(content, **parameters)
         return self._output_class()(
             content=content,
@@ -277,7 +282,6 @@ def _parse_usage(self, response_data: dict[str, Any]) -> RawUsage:
     def _parse_content(
         self,
         response_data: dict[str, Any],
-        **parameters: Unpack[Params],  # type: ignore[misc]
     ) -> Content:
         """Parse content from provider response."""
         ...
@@ -384,8 +388,7 @@ def _transform_output(
         """Transform content using parameter mapper output transformations."""
         for mapper in self.parameter_mappers():
             value = parameters.get(mapper.name)
-            if value is not None:
-                content = mapper.parse_output(content, value)
+            content = mapper.parse_output(content, value)
         return content
 
     @abstractmethod

src/celeste/modalities/audio/client.py

@@ -8,13 +8,13 @@
 from celeste.core import Modality
 from celeste.types import AudioContent
 
-from .io import AudioFinishReason, AudioInput, AudioOutput, AudioUsage
+from .io import AudioChunk, AudioFinishReason, AudioInput, AudioOutput, AudioUsage
 from .parameters import AudioParameters
 from .streaming import AudioStream
 
 
 class AudioClient(
-    ModalityClient[AudioInput, AudioOutput, AudioParameters, AudioContent]
+    ModalityClient[AudioInput, AudioOutput, AudioParameters, AudioContent, AudioChunk]
 ):
     """Base audio client. Providers implement speak() method."""
 

src/celeste/modalities/audio/providers/elevenlabs/client.py

@@ -64,18 +64,14 @@ def _init_request(self, inputs: AudioInput) -> dict[str, Any]:
     def _parse_content(
         self,
         response_data: dict[str, Any],
-        **parameters: Unpack[AudioParameters],
     ) -> AudioArtifact:
         """Extract audio bytes from response."""
         audio_bytes = response_data.get("audio_bytes")
         if not audio_bytes:
             msg = "No audio data in response"
             raise ValueError(msg)
 
-        output_format = parameters.get("output_format")
-        mime_type = self._map_output_format_to_mime_type(output_format)
-
-        return AudioArtifact(data=audio_bytes, mime_type=mime_type)
+        return AudioArtifact(data=audio_bytes)
 
     def _stream_class(self) -> type[AudioStream]:
         """Return the Stream class for this provider."""

src/celeste/modalities/audio/providers/google/client.py

@@ -3,7 +3,6 @@
 from typing import Any, Unpack
 
 from celeste.artifacts import AudioArtifact
-from celeste.mime_types import AudioMimeType
 from celeste.parameters import ParameterMapper
 from celeste.providers.google.cloud_tts import config
 from celeste.providers.google.cloud_tts.client import (
@@ -16,7 +15,7 @@
     AudioInput,
     AudioOutput,
 )
-from ...parameters import AudioParameter, AudioParameters
+from ...parameters import AudioParameters
 from .parameters import GOOGLE_PARAMETER_MAPPERS
 
 
@@ -51,15 +50,10 @@ def _init_request(self, inputs: AudioInput) -> dict[str, Any]:
     def _parse_content(
         self,
         response_data: dict[str, Any],
-        **parameters: Unpack[AudioParameters],
     ) -> AudioArtifact:
         """Extract audio bytes from response."""
         audio_b64 = super()._parse_content(response_data)
-
-        output_format = parameters.get(AudioParameter.OUTPUT_FORMAT)
-        mime_type = AudioMimeType(output_format) if output_format else AudioMimeType.MP3
-
-        return AudioArtifact(data=audio_b64, mime_type=mime_type)
+        return AudioArtifact(data=audio_b64)
 
 
 __all__ = ["GoogleAudioClient"]

src/celeste/modalities/audio/providers/gradium/client.py

@@ -64,18 +64,14 @@ def _init_request(self, inputs: AudioInput) -> dict[str, Any]:
     def _parse_content(
         self,
         response_data: dict[str, Any],
-        **parameters: Unpack[AudioParameters],
     ) -> AudioArtifact:
         """Extract audio bytes from response."""
         audio_bytes = response_data.get("audio_bytes")
         if not audio_bytes:
             msg = "No audio data in response"
             raise ValueError(msg)
 
-        output_format = parameters.get("output_format")
-        mime_type = self._map_output_format_to_mime_type(output_format)
-
-        return AudioArtifact(data=audio_bytes, mime_type=mime_type)
+        return AudioArtifact(data=audio_bytes)
 
     def _stream_class(self) -> type[AudioStream]:
         """Return the Stream class for this provider."""

src/celeste/modalities/audio/providers/openai/client.py

@@ -41,19 +41,14 @@ def _init_request(self, inputs: AudioInput) -> dict[str, Any]:
     def _parse_content(
         self,
         response_data: dict[str, Any],
-        **parameters: Unpack[AudioParameters],
     ) -> AudioArtifact:
         """Extract audio bytes from response."""
         audio_bytes = response_data.get("audio_bytes")
         if not audio_bytes:
             msg = "No audio data in response"
             raise ValueError(msg)
 
-        # Use mixin helper to determine MIME type from output_format
-        output_format = parameters.get("output_format")
-        mime_type = self._map_response_format_to_mime_type(output_format)
-
-        return AudioArtifact(data=audio_bytes, mime_type=mime_type)
+        return AudioArtifact(data=audio_bytes)
 
     def _parse_finish_reason(self, response_data: dict[str, Any]) -> AudioFinishReason:
         """OpenAI TTS doesn't provide finish reasons."""

src/celeste/modalities/embeddings/client.py

@@ -9,6 +9,7 @@
 from celeste.types import EmbeddingsContent
 
 from .io import (
+    EmbeddingsChunk,
     EmbeddingsFinishReason,
     EmbeddingsInput,
     EmbeddingsOutput,
@@ -19,7 +20,11 @@
 
 class EmbeddingsClient(
     ModalityClient[
-        EmbeddingsInput, EmbeddingsOutput, EmbeddingsParameters, EmbeddingsContent
+        EmbeddingsInput,
+        EmbeddingsOutput,
+        EmbeddingsParameters,
+        EmbeddingsContent,
+        EmbeddingsChunk,
     ]
 ):
     """Base embeddings client. Providers implement operation methods."""

src/celeste/modalities/embeddings/providers/google/client.py

@@ -1,6 +1,6 @@
 """Google embeddings client."""
 
-from typing import Any, Unpack
+from typing import Any
 
 from celeste.parameters import ParameterMapper
 from celeste.providers.google.embeddings.client import (
@@ -10,7 +10,6 @@
 
 from ...client import EmbeddingsClient
 from ...io import EmbeddingsInput
-from ...parameters import EmbeddingsParameters
 from .parameters import GOOGLE_PARAMETER_MAPPERS
 
 
@@ -42,7 +41,6 @@ def _init_request(self, inputs: EmbeddingsInput) -> dict[str, Any]:
     def _parse_content(
         self,
         response_data: dict[str, Any],
-        **parameters: Unpack[EmbeddingsParameters],
     ) -> EmbeddingsContent:
         """Parse embedding vectors from response."""
         return super()._parse_content(response_data)

src/celeste/modalities/images/client.py

@@ -9,13 +9,13 @@
 from celeste.core import Modality
 from celeste.types import ImageContent
 
-from .io import ImageFinishReason, ImageInput, ImageOutput, ImageUsage
+from .io import ImageChunk, ImageFinishReason, ImageInput, ImageOutput, ImageUsage
 from .parameters import ImageParameters
 from .streaming import ImagesStream
 
 
 class ImagesClient(
-    ModalityClient[ImageInput, ImageOutput, ImageParameters, ImageContent]
+    ModalityClient[ImageInput, ImageOutput, ImageParameters, ImageContent, ImageChunk]
 ):
     """Base images client. Providers implement generate/edit methods."""
 

src/celeste/modalities/images/providers/bfl/client.py

@@ -59,7 +59,6 @@ def _init_request(self, inputs: ImageInput) -> dict[str, Any]:
     def _parse_content(
         self,
         response_data: dict[str, Any],
-        **parameters: Unpack[ImageParameters],
     ) -> ImageArtifact:
         """Parse content from response."""
         result = super()._parse_content(response_data)