Metadata-Version: 2.4
Name: kestrel-voice-xai
Version: 0.1.1
Summary: xAI realtime conversation, TTS, and STT providers for Kestrel Sovereign
License-Expression: Apache-2.0
Requires-Python: <3.15,>=3.11
Requires-Dist: httpx<1,>=0.27
Requires-Dist: kestrel-sovereign-sdk<1,>=0.30.0
Requires-Dist: websockets<17,>=14
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# kestrel-voice-xai

xAI voice providers for Kestrel Sovereign:

- Realtime speech-to-speech over the xAI Voice Agent WebSocket API
- Text to speech, including streaming MP3, WAV, PCM, μ-law, and A-law output
- Batch and streaming speech to text
- Runtime discovery of voice models, built-in voices, and custom voices
- Governed Kestrel function tools with atomic multi-tool continuation

Install the package beside `kestrel-feature-voice` and set `XAI_API_KEY`.
Providers are discovered through Python entry points; the feature package does
not import this distribution directly.

```bash
uv pip install git+https://github.com/KestrelSovereignAI/kestrel-voice-xai.git
export XAI_API_KEY=...
```

All three roles share the operator-facing `[voice.xai]` configuration. Model
and voice IDs are discovered at runtime; selecting no realtime voice lets xAI
use its current provider default.

```toml
[voice.xai]
language = "auto"
# model = "a-versioned-model-from-/v1/models"  # optional production pin
# keyterms = ["Kestrel", "your product name"]

# Provider-native tools are intentionally opt-in. Kestrel function tools do
# not go here; they remain governed by the Sovereign dispatcher.
native_tools = ["web_search", "x_search"]
```

Provider-native `web_search`, `x_search`, `file_search`, and remote `mcp` tools
are supported by xAI but disabled by default. Enable only the specific native
tool definitions intended for the agent in the provider configuration. Kestrel
function tools continue to execute through the Sovereign governed dispatcher.

The voice UI receives the provider's live built-in and team custom-voice
catalog, persists voice choices by provider, and uses an xAI ephemeral token
for direct browser WebSocket sessions. Long-lived API keys stay server-side.

Upstream contracts: [Voice Agent API](https://docs.x.ai/developers/model-capabilities/audio/voice-agent),
[ephemeral tokens](https://docs.x.ai/developers/model-capabilities/audio/ephemeral-tokens),
[text to speech](https://docs.x.ai/developers/model-capabilities/audio/text-to-speech),
[speech to text](https://docs.x.ai/developers/model-capabilities/audio/speech-to-text), and
[custom voices](https://docs.x.ai/developers/model-capabilities/audio/custom-voices).
