feat(speech-generation): add Gradium TTS provider with WebSocket API (withceleste#89)

* feat(speech-generation): add Gradium TTS provider (#XX)

  Add comprehensive Gradium text-to-speech integration with WebSocket streaming
  support.

  Features:
  - WebSocket-based TTS streaming with low-latency audio generation
  - 14 flagship voices across 5 languages (en, fr, de, es, pt)
  - Custom voice cloning with create/list/update/delete operations
  - Speed control via padding_bonus parameter (-4.0 to 4.0)
  - Multiple audio formats (wav, pcm, opus, ulaw_8000, alaw_8000, pcm_16000,
  pcm_24000)
  - EU/US regional endpoints for optimized latency
  - Credits monitoring and usage tracking

  Implementation details:
  - WebSocket protocol handling with proper message sequencing
  - Parameter mappers for voice, speed, and response_format
  - Pydantic models for API responses (VoiceInfo, CreditsSummary, TTSResult)
  - Full voice management REST API integration
  - Comprehensive test suite with 6 test functions

  Dependencies:
  - Added websockets>=13.0 to support WebSocket connections

  Documentation:
  - Complete README with usage examples and API reference
  - Test scripts for validation (test_gradium_tts.py, test_gradium_minimal.py)

* feat(speech-generation): add Gradium TTS provider with WebSocket API

Add Gradium as a new speech generation provider using their WebSocket-based
Text-to-Speech API. This provider enables high-quality multilingual speech
synthesis with 14 flagship voices across 5 languages.

Key changes:
- Add celeste-gradium provider package with WebSocket TTS client
- Add Gradium capability provider with parameter mappers
- Add WebSocket client module to celeste core
- Add 14 flagship voices (EN, FR, DE, ES, PT)
- Add Gradium integration test and CI secrets
- Bump celeste-ai and celeste-speech-generation to 0.3.1

Provider features:
- WebSocket streaming for low-latency audio generation
- Support for wav, pcm, opus output formats
- Voice selection by name (Emma, Kent, Sydney, etc.)
- Speed control via padding_bonus translation

* fix(gradium): fix provider inconsistencies

- Export GRADIUM_VOICES in speech-generation __init__.py
- Add DEFAULT_VOICE_ID to config.py (consistent with ElevenLabs)
- Add _make_request stub to satisfy abstract interface
- Remove unused httpx import from capability client

* test: improve test coverage for constraints and parameters

* test: fix Int constraint test to accept booleans

---------

Co-authored-by: maxence <maxencedemonteynard@yahoo.fr>

Author: Kamilbenkirane

.env.example

@@ -39,3 +39,6 @@ TOPAZLABS_API_KEY=your-topazlabs-api-key-here
 
 # Perplexity
 PERPLEXITY_API_KEY=your-perplexity-api-key-here
+
+# Gradium
+GRADIUM_API_KEY=your-gradium-api-key-here

.github/workflows/publish.yml

@@ -136,6 +136,7 @@ jobs:
           BYTEPLUS_API_KEY: ${{ secrets.BYTEPLUS_API_KEY }}
           XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
           ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY }}
+          GRADIUM_API_KEY: ${{ secrets.GRADIUM_API_KEY }}
         run: uv run pytest packages/capabilities/${{ matrix.package }}/tests/integration_tests/ -m integration -v
 
   build:

.gitignore

@@ -157,3 +157,4 @@ uv.lock
 
 # Security reports
 bandit-report.json
+mureka.md

packages/capabilities/speech-generation/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "celeste-speech-generation"
-version = "0.3.0"
+version = "0.3.1"
 description = "Speech generation package for Celeste AI. Unified interface for all providers"
 authors = [{name = "Kamilbenkirane", email = "kamil@withceleste.ai"}]
 readme = "README.md"
@@ -17,7 +17,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Typing :: Typed",
 ]
-keywords = ["ai", "speech-generation", "tts", "text-to-speech", "openai", "google", "elevenlabs", "audio-ai"]
+keywords = ["ai", "speech-generation", "tts", "text-to-speech", "openai", "google", "elevenlabs", "gradium", "audio-ai"]
 
 [project.urls]
 Homepage = "https://withceleste.ai"
@@ -28,6 +28,8 @@ Issues = "https://github.com/withceleste/celeste-python/issues"
 [tool.uv.sources]
 celeste-ai = { workspace = true }
 celeste-elevenlabs = { workspace = true }
+celeste-google = { workspace = true }
+celeste-gradium = { workspace = true }
 celeste-openai = { workspace = true }
 
 [project.entry-points."celeste.packages"]

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

@@ -30,16 +30,20 @@ def register_package() -> None:
 from celeste_speech_generation.providers.google.voices import (  # noqa: E402
     GOOGLE_VOICES,
 )
+from celeste_speech_generation.providers.gradium.voices import (  # noqa: E402
+    GRADIUM_VOICES,
+)
 from celeste_speech_generation.providers.openai.voices import (  # noqa: E402
     OPENAI_VOICES,
 )
 from celeste_speech_generation.streaming import SpeechGenerationStream  # noqa: E402
 from celeste_speech_generation.voices import Voice  # noqa: E402
 
 VOICES: list[Voice] = [
+    *ELEVENLABS_VOICES,
     *GOOGLE_VOICES,
+    *GRADIUM_VOICES,
     *OPENAI_VOICES,
-    *ELEVENLABS_VOICES,
 ]
 
 __all__ = [

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

@@ -5,10 +5,12 @@
     MODELS as ELEVENLABS_MODELS,
 )
 from celeste_speech_generation.providers.google.models import MODELS as GOOGLE_MODELS
+from celeste_speech_generation.providers.gradium.models import MODELS as GRADIUM_MODELS
 from celeste_speech_generation.providers.openai.models import MODELS as OPENAI_MODELS
 
 MODELS: list[Model] = [
     *GOOGLE_MODELS,
     *OPENAI_MODELS,
     *ELEVENLABS_MODELS,
+    *GRADIUM_MODELS,
 ]

packages/capabilities/speech-generation/src/celeste_speech_generation/providers/__init__.py

@@ -14,6 +14,9 @@ def _get_providers() -> list[tuple[Provider, type[Client]]]:
     from celeste_speech_generation.providers.google.client import (
         GoogleSpeechGenerationClient,
     )
+    from celeste_speech_generation.providers.gradium.client import (
+        GradiumSpeechGenerationClient,
+    )
     from celeste_speech_generation.providers.openai.client import (
         OpenAISpeechGenerationClient,
     )
@@ -22,6 +25,7 @@ def _get_providers() -> list[tuple[Provider, type[Client]]]:
         (Provider.GOOGLE, GoogleSpeechGenerationClient),
         (Provider.OPENAI, OpenAISpeechGenerationClient),
         (Provider.ELEVENLABS, ElevenLabsSpeechGenerationClient),
+        (Provider.GRADIUM, GradiumSpeechGenerationClient),
     ]
 
 

packages/capabilities/speech-generation/src/celeste_speech_generation/providers/gradium/__init__.py

@@ -0,0 +1,9 @@
+"""Gradium provider for speech generation."""
+
+from .client import GradiumSpeechGenerationClient
+from .models import MODELS
+
+__all__ = [
+    "MODELS",
+    "GradiumSpeechGenerationClient",
+]

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

@@ -0,0 +1,79 @@
+"""Gradium client implementation for speech generation."""
+
+from typing import Any, Unpack
+
+from celeste_gradium.text_to_speech.client import GradiumTextToSpeechClient
+
+from celeste.artifacts import AudioArtifact
+from celeste.parameters import ParameterMapper
+from celeste_speech_generation.client import SpeechGenerationClient
+from celeste_speech_generation.io import (
+    SpeechGenerationInput,
+    SpeechGenerationOutput,
+    SpeechGenerationUsage,
+)
+from celeste_speech_generation.parameters import SpeechGenerationParameters
+
+from .parameters import GRADIUM_PARAMETER_MAPPERS
+
+
+class GradiumSpeechGenerationClient(GradiumTextToSpeechClient, SpeechGenerationClient):
+    """Gradium client for speech generation."""
+
+    @classmethod
+    def parameter_mappers(cls) -> list[ParameterMapper]:
+        return GRADIUM_PARAMETER_MAPPERS
+
+    def _init_request(self, inputs: SpeechGenerationInput) -> dict[str, Any]:
+        """Initialize request from Gradium API format."""
+        return {"text": inputs.text}
+
+    def _parse_usage(self, response_data: dict[str, Any]) -> SpeechGenerationUsage:
+        """Parse usage from response."""
+        usage = super()._parse_usage(response_data)
+        return SpeechGenerationUsage(**usage)
+
+    def _parse_content(
+        self,
+        response_data: dict[str, Any],
+        **parameters: Unpack[SpeechGenerationParameters],
+    ) -> AudioArtifact:
+        """Parse content from response.
+
+        Note: This method is not used for Gradium TTS since we override generate()
+        to handle WebSocket responses. Kept for interface compliance.
+        """
+        msg = "Gradium TTS uses WebSocket, use generate() override"
+        raise NotImplementedError(msg)
+
+    async def generate(
+        self,
+        *args: str,
+        **parameters: Unpack[SpeechGenerationParameters],
+    ) -> SpeechGenerationOutput:
+        """Generate speech from text.
+
+        Override base generate() to use WebSocket instead of HTTP.
+        """
+        inputs = self._create_inputs(*args, **parameters)
+        inputs, parameters = self._validate_artifacts(inputs, **parameters)
+        request_body = self._build_request(inputs, **parameters)
+
+        # Use WebSocket TTS flow
+        audio_bytes, output_format = await self._websocket_tts(request_body)
+
+        if not audio_bytes:
+            msg = "No audio data in response"
+            raise ValueError(msg)
+
+        # Determine MIME type from output_format
+        mime_type = self._map_output_format_to_mime_type(output_format)
+
+        return self._output_class()(
+            content=AudioArtifact(data=audio_bytes, mime_type=mime_type),
+            usage=SpeechGenerationUsage(),
+            metadata=self._build_metadata({}),
+        )
+
+
+__all__ = ["GradiumSpeechGenerationClient"]

packages/capabilities/speech-generation/src/celeste_speech_generation/providers/gradium/models.py

@@ -0,0 +1,34 @@
+"""Gradium model definitions for speech generation."""
+
+from celeste import Model, Provider
+from celeste.constraints import Choice, Range
+from celeste_speech_generation.constraints import VoiceConstraint
+from celeste_speech_generation.parameters import SpeechGenerationParameter
+
+from .voices import GRADIUM_VOICES
+
+MODELS: list[Model] = [
+    Model(
+        id="default",
+        provider=Provider.GRADIUM,
+        display_name="Gradium Default TTS",
+        streaming=False,
+        parameter_constraints={
+            SpeechGenerationParameter.VOICE: VoiceConstraint(voices=GRADIUM_VOICES),
+            SpeechGenerationParameter.OUTPUT_FORMAT: Choice(
+                options=[
+                    "wav",
+                    "pcm",
+                    "opus",
+                    "ulaw_8000",
+                    "alaw_8000",
+                    "pcm_16000",
+                    "pcm_24000",
+                ]
+            ),
+            SpeechGenerationParameter.SPEED: Range(min=0.25, max=4.0),
+        },
+    ),
+]
+
+__all__ = ["MODELS"]