Configuration
EstuaryConfig
The EstuaryConfig dataclass controls all client behavior. Pass it to the EstuaryClient constructor.
from estuary_sdk import EstuaryConfig
config = EstuaryConfig(
server_url="https://api.estuary-ai.com",
api_key="est_your_api_key",
character_id="your-character-uuid",
player_id="user-123",
)
Required Fields
| Field | Type | Description |
|---|---|---|
server_url | str | Estuary server URL |
api_key | str | API key (starts with est_) |
character_id | str | UUID of the AI character to connect to |
player_id | str | Unique identifier for the current user |
Optional Fields
| Field | Type | Default | Description |
|---|---|---|---|
voice_transport | VoiceTransport | "websocket" | Voice transport: "websocket", "livekit", or "auto" |
audio_sample_rate | int | 16000 | Audio sample rate in Hz |
auto_reconnect | bool | True | Automatically reconnect on disconnect |
max_reconnect_attempts | int | 5 | Maximum number of reconnection attempts |
reconnect_delay | float | 1.0 | Base delay between reconnection attempts (seconds) |
debug | bool | False | Enable verbose debug logging |
realtime_memory | bool | False | Enable memory_updated events during conversations |
VoiceTransport
A string literal type controlling which voice transport to use:
| Value | Description |
|---|---|
"websocket" | WebSocket-based voice streaming (default) |
"livekit" | LiveKit WebRTC with AEC and audio processing |
"auto" | Prefer LiveKit if the livekit package is installed, fall back to WebSocket |
from estuary_sdk import EstuaryConfig
# Explicit WebSocket
config = EstuaryConfig(..., voice_transport="websocket")
# Explicit LiveKit (requires livekit package)
config = EstuaryConfig(..., voice_transport="livekit")
# Auto-detect
config = EstuaryConfig(..., voice_transport="auto")
RetryConfig
Optional retry configuration for RestClient HTTP requests. Uses exponential backoff.
| Field | Type | Default | Description |
|---|---|---|---|
max_retries | int | 3 | Maximum number of retry attempts |
backoff_factor | float | 1.0 | Multiplier for exponential backoff (delay = factor * 2^attempt) |
retry_on_status | tuple[int, ...] | (500, 502, 503, 504) | HTTP status codes that trigger a retry |
from estuary_sdk import RetryConfig
from estuary_sdk.rest.rest_client import RestClient
retry = RetryConfig(max_retries=5, backoff_factor=0.5)
rest = RestClient(base_url="https://api.estuary-ai.com", api_key="est_...", retry_config=retry)
note
This is for advanced users building custom REST clients. The built-in sub-clients (client.memory, client.players, etc.) use the default RestClient created by EstuaryClient.