Metadata-Version: 2.4
Name: pipecat-rumik
Version: 0.1.1
Summary: Rumik text-to-speech services for Pipecat
Project-URL: Homepage, https://rumik.ai
Project-URL: Repository, https://github.com/ira-rumik/pipecat-rumik
Project-URL: Issues, https://github.com/ira-rumik/pipecat-rumik/issues
Project-URL: Support, https://github.com/ira-rumik/pipecat-rumik/issues
Author: Rumik AI
Maintainer: Rumik AI
License: MIT License
        
        Copyright (c) 2026 Rumik AI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: pipecat,rumik,speech,text-to-speech,tts,voice-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: certifi>=2024.2.2
Requires-Dist: pipecat-ai<2,>=1.0.0
Requires-Dist: websockets>=13
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# pipecat-rumik

Text-to-speech service implementations for
[Pipecat](https://github.com/pipecat-ai/pipecat) using Rumik's TTS APIs.

## Overview

`pipecat-rumik` provides two Pipecat TTS services:

- `RumikTTSService` for WebSocket-based synthesis in interactive voice
  pipelines.
- `RumikHttpTTSService` for HTTP request/response synthesis.

The package follows Pipecat's service conventions: constructor-level provider
configuration, runtime-configurable `Settings`, raw PCM audio frames, metrics,
and standard service connection events.

```python
from pipecat_rumik import RumikHttpTTSService, RumikTTSService, RumikTTSSettings
```

## Installation

```bash
pip install pipecat-rumik
```

For local development:

```bash
uv sync --extra dev
```

## Prerequisites

Before using either service, configure access to the Rumik gateway:

```bash
export RUMIK_API_KEY=...
export RUMIK_GATEWAY_URL=...
```

Optional environment variables used by the smoke-test examples:

```bash
export RUMIK_MODEL=muga
export RUMIK_SPEAKER_ID=0
export RUMIK_DESCRIPTION=neutral
export RUMIK_TEMPERATURE=0.6
export RUMIK_TOPK=40
export RUMIK_MAX_NEW_TOKENS=2048
```

## Service Selection

| Service | Transport | Recommended Use |
| --- | --- | --- |
| `RumikTTSService` | WebSocket | Interactive Pipecat voice agents that need interruption-aware TTS. |
| `RumikHttpTTSService` | HTTP | Simpler synthesis flows where a request/response API is preferred. |

Use the WebSocket service for conversational applications. Use the HTTP service
for batch-style synthesis or integration tests that do not need a persistent TTS
connection.

## Configuration

### RumikTTSService

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `str` | yes | Rumik API key. |
| `gateway_url` | `str` | yes | Rumik gateway base URL. |
| `settings` | `RumikTTSService.Settings \| None` | no | Runtime-configurable TTS settings. |
| `sample_rate` | `int \| None` | no | Output sample rate. Rumik currently emits 24 kHz PCM. |
| `full_response_aggregation` | `bool` | no | Buffer a complete LLM response before sending it to Rumik. Defaults to `True`. |

### RumikHttpTTSService

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `str` | yes | Rumik API key. |
| `gateway_url` | `str` | yes | Rumik gateway base URL. |
| `aiohttp_session` | `aiohttp.ClientSession` | yes | Caller-owned HTTP session. |
| `settings` | `RumikHttpTTSService.Settings \| None` | no | Runtime-configurable TTS settings. |
| `sample_rate` | `int \| None` | no | Output sample rate. Rumik currently emits 24 kHz PCM. |

## Settings

Both services use Pipecat's service settings pattern:

```python
settings=RumikTTSService.Settings(...)
settings=RumikHttpTTSService.Settings(...)
```

`RumikTTSService.Settings` and `RumikHttpTTSService.Settings` are aliases of
`RumikTTSSettings`.

| Setting | Type | Default | Used By | Description |
| --- | --- | --- | --- | --- |
| `model` | `str \| None` | `"muga"` | HTTP, WS | Rumik model identifier. |
| `voice` | `str \| None` | `None` | inherited | Reserved for Pipecat provider compatibility. |
| `language` | `Language \| str \| None` | `None` | inherited | Reserved for Pipecat provider compatibility. |
| `speaker_id` | `int` | `0` | WS | Rumik WebSocket speaker ID. |
| `description` | `str \| None` | `"neutral"` | HTTP | Voice/style description. |
| `temperature` | `float \| None` | `0.6` | HTTP | Sampling temperature. |
| `topk` | `int \| None` | `40` | HTTP | Top-k sampling. |
| `max_new_tokens` | `int \| None` | `2048` | HTTP | Maximum generated audio tokens. |

Runtime updates use Pipecat's `TTSUpdateSettingsFrame` with
`RumikTTSSettings`.

## Usage

### WebSocket Service

```python
import os

from pipecat_rumik import RumikTTSService

tts = RumikTTSService(
    api_key=os.environ["RUMIK_API_KEY"],
    gateway_url=os.environ["RUMIK_GATEWAY_URL"],
    settings=RumikTTSService.Settings(
        model="muga",
        speaker_id=0,
    ),
)
```

By default, `RumikTTSService` uses full-response aggregation. This sends one
complete assistant response to Rumik instead of creating a separate TTS request
for every sentence.

```python
tts = RumikTTSService(
    api_key=os.environ["RUMIK_API_KEY"],
    gateway_url=os.environ["RUMIK_GATEWAY_URL"],
    full_response_aggregation=False,
)
```

### HTTP Service

```python
import os

import aiohttp

from pipecat_rumik import RumikHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = RumikHttpTTSService(
        api_key=os.environ["RUMIK_API_KEY"],
        gateway_url=os.environ["RUMIK_GATEWAY_URL"],
        aiohttp_session=session,
        settings=RumikHttpTTSService.Settings(
            model="muga",
            description="neutral",
            temperature=0.6,
            topk=40,
            max_new_tokens=2048,
        ),
    )
```

The HTTP service uses the caller-owned `aiohttp.ClientSession`. Create and close
the session in your application code.

## Notes

- **WebSocket vs HTTP**: The WebSocket service is intended for interactive
  Pipecat conversations. The HTTP service is useful for simpler batch-style
  synthesis.
- **Request lifecycle**: The WebSocket service keeps one active synthesis
  request per connection so audio chunks are routed deterministically to the
  active Pipecat audio context.
- **Interruption handling**: On interruption, the WebSocket service closes the
  active socket and opens a fresh session before accepting the next synthesis
  request.
- **Audio format**: Rumik currently emits 24 kHz, mono, signed 16-bit PCM. The
  services validate provider responses against this audio contract before
  emitting Pipecat audio frames.
- **HTTP response handling**: The HTTP service validates the WAV response,
  removes the WAV container, and emits raw PCM frames.

## Event Handlers

`RumikTTSService` supports Pipecat's standard service connection events:

| Event | Description |
| --- | --- |
| `on_connected` | Connected to the Rumik WebSocket service. |
| `on_disconnected` | Disconnected from the Rumik WebSocket service. |
| `on_connection_error` | WebSocket connection error occurred. |

```python
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Rumik")
```

## Examples

The repository includes manual smoke tests:

```bash
env PYTHONPATH=src uv run python examples/smoke_rumik_http.py
env PYTHONPATH=src uv run python examples/smoke_rumik_ws.py
env PYTHONPATH=src uv run python examples/smoke_rumik_ws_suite.py
```

The smoke tests require real Rumik credentials. Unit tests do not.

## Testing

Offline checks:

```bash
uv run --locked pytest -q
uv run --locked ruff check src tests examples scripts
uv run --locked python -m compileall -q src tests examples scripts
uv build
uv run --with twine twine check dist/*
```

See [TESTING.md](TESTING.md) for the full test checklist and
[RELEASE.md](RELEASE.md) for TestPyPI/PyPI release steps.

## License

This package is released under the MIT License. See [LICENSE](LICENSE).
