# Providers (/reference/providers)

Each provider is a Python class behind a slot interface. `config.cuelo` names
it, and the registry (`x-cuelo-providers` in the schema) maps the name to the
class, the pip extra it needs and the environment variable holding its key.

Install the extras you use: `pip install "cuelo[smallest,anthropic,maai]"`.
The CLI install includes the common ones.

## Speech-to-text [#speech-to-text]

All STT providers are streaming. They support `language` (BCP-47) and
`vocab` (keyword boosting) and accept `model`, `base_url` and `api_key_env`.

| Field                 | Type                                                                                            | Default | Description                                                |
| --------------------- | ----------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `provider` (required) | `smallest` \| `elevenlabs` \| `deepgram` \| `cartesia` \| `inworld` \| `assemblyai` \| `soniox` | —       | —                                                          |
| `model`               | string                                                                                          | —       | Provider model ID. Omit for the provider default.          |
| `language`            | string                                                                                          | —       | BCP-47 tag, e.g. en or en-US. Omit to auto-detect.         |
| `vocab`               | string[]                                                                                        | —       | Terms to recognize more reliably: names, products, jargon. |
| `api_key_env`         | envName                                                                                         | —       | —                                                          |
| `base_url`            | string                                                                                          | —       | —                                                          |

## LLM [#llm]

| Name                | Class                                      | Extra              | Credential           |
| ------------------- | ------------------------------------------ | ------------------ | -------------------- |
| `anthropic`         | `cuelo.llms.anthropic.AnthropicLLM`        | `cuelo[anthropic]` | `ANTHROPIC_API_KEY`  |
| `openai`            | `cuelo.llms.openai_native.OpenAINativeLLM` | `cuelo[openai]`    | `OPENAI_API_KEY`     |
| `openrouter`        | `cuelo.llms.openrouter.OpenRouterLLM`      | `cuelo[openai]`    | `OPENROUTER_API_KEY` |
| `cerebras`          | `cuelo.llms.cerebras.CerebrasLLM`          | `cuelo[openai]`    | `CEREBRAS_API_KEY`   |
| `openai-compatible` | `cuelo.llms.openai_spec.OpenAISpecLLM`     | `cuelo[openai]`    | `OPENAI_API_KEY`     |

`openrouter` and `cerebras` are thin subclasses of the OpenAI-compatible
client with their own base URL and key. `openai` uses OpenAI's native API.
Use `openai-compatible` with `base_url` for anything else that speaks Chat
Completions.

## Text-to-speech [#text-to-speech]

Names ending in `-streaming` take text as the LLM writes it and stream audio
back over one connection, which is the lowest latency. The others synthesize
one sentence at a time over HTTP, which is simpler and often just as fast for
short replies. `elevenlabs-dialogue` uses ElevenLabs' multi-speaker dialogue
model.

| Field                 | Type                                                                                                                                                                                          | Default | Description                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `provider` (required) | `smallest` \| `elevenlabs` \| `elevenlabs-streaming` \| `elevenlabs-dialogue` \| `cartesia` \| `cartesia-streaming` \| `deepgram` \| `deepgram-streaming` \| `inworld` \| `inworld-streaming` | —       | —                                                                   |
| `voice` (required)    | string                                                                                                                                                                                        | —       | A provider voice ID, or a path to a voice profile (voices/\*.yaml). |
| `model`               | string                                                                                                                                                                                        | —       | —                                                                   |
| `speed`               | number                                                                                                                                                                                        | —       | —                                                                   |
| `language`            | string                                                                                                                                                                                        | —       | —                                                                   |
| `api_key_env`         | envName                                                                                                                                                                                       | —       | —                                                                   |
| `base_url`            | string                                                                                                                                                                                        | —       | —                                                                   |

| Provider         | `voice` |     `speed`      | `language` | pronunciations |
| ---------------- | :-----: | :--------------: | :--------: | :------------: |
| smallest         |    ✓    |        ✓         |     ✓      |       ✓        |
| elevenlabs (all) |    ✓    | ✓ (not dialogue) |     ✓      |       ✓        |
| cartesia (all)   |    ✓    |        ✓         |     ✓      |       ✓        |
| deepgram (all)   |    ✓    |        ✓         |     —      |       ✓        |
| inworld (all)    |    ✓    |        ✓         |     ✓      |       ✓        |

Setting a field a provider doesn't support raises at startup, so mistakes
don't fail silently.

## Turn-taking controllers [#turn-taking-controllers]

These have no credentials. They run locally on model weights from the
[models catalog](/reference/models).

| Name                   | Class                                                                  | Extra           | Credential |
| ---------------------- | ---------------------------------------------------------------------- | --------------- | ---------- |
| `vad`                  | `cuelo.controllers.vad_turn.VADController`                             | `cuelo[silero]` | —          |
| `backchannel`          | `cuelo.controllers.backchannel.VADBackchannelController`               | `cuelo[silero]` | —          |
| `smart-turn`           | `cuelo.controllers.smart_turn.SmartTurnController`                     | `cuelo[silero]` | —          |
| `turn-1-mini`          | `cuelo.controllers.turn1_mini.Turn1MiniController`                     | `cuelo[silero]` | —          |
| `backchannel-detector` | `cuelo.controllers.backchannel_detector.BackchannelDetectorController` | `cuelo[silero]` | —          |
| `maai`                 | `cuelo.controllers.maai.MaaiTurnController`                            | `cuelo[maai]`   | —          |
| `maai-backchannel`     | `cuelo.controllers.maai.MaaiBackchannelController`                     | `cuelo[maai]`   | —          |
| `maai-interrupt`       | `cuelo.controllers.maai.MaaiInterruptController`                       | `cuelo[maai]`   | —          |
| `backchannel-first`    | `cuelo.controllers.compose.BackchannelFirst`                           | `cuelo[silero]` | —          |

## Verified status [#verified-status]

Every provider has tests against a local fake server that follows its
documented protocol. These are also verified against the live APIs: **Smallest**
(STT and TTS), **Cerebras** and **Anthropic**. The rest are implemented to their
docs but not yet live-tested. Reports and fixes are welcome.

Missing a provider? [Add one](/contributing/providers).