Metadata-Version: 2.4
Name: swarmauri_tts_cartesia
Version: 0.1.0a1
Summary: Alpha Swarmauri Cartesia text-to-speech provider with file synthesis, async execution, streaming and bounded batches; live API verification pending.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: swarmauri,cartesia,tts,text-to-speech,speech-synthesis,audio-streaming,async-audio,alpha-provider
Author: Jacob Stewart
Author-email: jacob@swarmauri.com
Requires-Python: >=3.10,<3.15
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Dist: httpx (>=0.27,<0.29)
Requires-Dist: pydantic (>=2.0)
Requires-Dist: swarmauri_base (>=0.11.0.dev12,<0.12)
Project-URL: Issues, https://github.com/swarmauri/swarmauri-sdk/issues
Project-URL: Repository, https://github.com/swarmauri/swarmauri-sdk
Description-Content-Type: text/markdown

![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)

# swarmauri_tts_cartesia

Alpha Swarmauri Cartesia speech provider. Versioned Sonic bytes API. WebSockets, SSE and voice management are excluded.

[![Downloads](https://img.shields.io/pypi/dm/swarmauri_tts_cartesia)](https://pepy.tech/projects/swarmauri_tts_cartesia)
[![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/standards/swarmauri_tts_cartesia.svg)](https://github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/standards/swarmauri_tts_cartesia)
[![Python](https://img.shields.io/pypi/pyversions/swarmauri_tts_cartesia)](https://pypi.org/project/swarmauri_tts_cartesia/)
[![License](https://img.shields.io/pypi/l/swarmauri_tts_cartesia)](https://pypi.org/project/swarmauri_tts_cartesia/)
[![Version](https://img.shields.io/pypi/v/swarmauri_tts_cartesia?label=swarmauri_tts_cartesia&color=green)](https://pypi.org/project/swarmauri_tts_cartesia/)

## Features

- Synchronous/asynchronous file generation and bounded batches.
- Incremental HTTP audio with cancellation cleanup.
- Provider-specific authentication, payloads, formats and model validation.
- Fixed provider endpoints; no automatic replay of billable requests.

`voice` must be an account-accessible voice ID. HTTP chunks retain the selected output codec. No realtime latency claim is made.

## Installation

```bash
uv add --prerelease allow swarmauri_tts_cartesia
```

```bash
pip install --pre swarmauri_tts_cartesia
```

This source candidate requires the companion `swarmauri_base>=0.11.0.dev12`
release before these alpha packages can be installed from the index.

## Usage

Set `CARTESIA_API_KEY` privately. Use a model and voice available to your own account.

```python
import os
from swarmauri_tts_cartesia import CartesiaTTS

provider = CartesiaTTS(
    api_key=os.environ["CARTESIA_API_KEY"],
    name="sonic-3.6",
    voice="db6b0ed5-d5d3-463d-ae85-518a07d3c2b4",
)
path = provider.predict("Welcome to Swarmauri.", "welcome.mp3")
# await provider.apredict(text, audio_path)
# provider.batch({"Hello": "hello.mp3"})
# await provider.abatch({"Hello": "hello.mp3"}, max_concurrent=2)
# Iterate provider.stream(text), or async-iterate provider.astream(text).
```

The filename does not convert the codec. Select matching output settings and
extensions. The component implements `TTSBase` for `TextToSpeechAgent` use.

## Models and output settings

The initial model list is `sonic-3.6`, `sonic-3.5` and `sonic-3`.
`api_version` is pinned to `2026-08-14`. Select `response_format="mp3"`
(default), `"wav"` or `"raw"`; WAV/raw use `pcm_s16le`. Set `sample_rate`
to 8000, 16000, 22050, 24000, 44100 (default) or 48000. `bit_rate` applies
only to MP3 (default 128000). Optional `speed` ranges from 0.6 to 1.5;
`language` passes the language code to Cartesia.

## Verification and alpha status

Live API behavior is **unverified**; tracked in [#6293](https://github.com/swarmauri/swarmauri-sdk/issues/6293). No paid synthesis was run. Offline tests
cover transport and documented schemas, not account/model availability,
playability, latency, pricing or quality. Keep `Development Status :: 3 - Alpha`
in `pyproject.toml` until maintainers review sufficient live evidence.

Live tests require both `CARTESIA_API_KEY` and `SWARMAURI_LIVE_TTS=1`.
An explicit `SWARMAURI_TTS_VOICE` is required.
By default only `predict` runs (one request). Set
`SWARMAURI_LIVE_TTS_OPERATIONS=predict,apredict,stream,astream,batch,abatch`
to select all operations (eight requests per model). Use
`SWARMAURI_TTS_MODEL` and `SWARMAURI_TTS_VOICE` for model-specific checks.
Never paste keys into logs or issues. See the
[verification tracker](https://github.com/swarmauri/swarmauri-sdk/blob/master/docs/verification/tts-providers.md).

## License

Apache-2.0. Part of the [Swarmauri SDK](https://github.com/swarmauri/swarmauri-sdk).

