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	24000	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
capabilities	SessionCapabilities | None	None	Declare what the device can physically do (see SessionCapabilities)
apm_echo_cancellation	bool	True	APM echo cancellation (LiveKit only)
apm_noise_suppression	bool	True	APM noise suppression (LiveKit only)
apm_auto_gain_control	bool	False	APM automatic gain control (LiveKit only)
apm_high_pass_filter	bool	True	APM high-pass filter (LiveKit only)

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")

SessionCapabilities

Declares what the host device can physically do. The server hides tools that require a missing capability — for example, the character won't request a camera image when camera=False, so a headless integration is never asked to see something it can't.

Field	Type	Default	Description
version	str	"1"	Schema version
camera	bool	True	A camera is available to answer camera_capture_request
microphone	bool	True	A microphone is available for voice capture
speaker	bool	True	A speaker is available for voice playback

from estuary_sdk import EstuaryConfig, SessionCapabilities

config = EstuaryConfig(
    server_url="https://api.estuary-ai.com",
    api_key="est_your_api_key",
    character_id="your-character-uuid",
    player_id="user-123",
    capabilities=SessionCapabilities(
        camera=False,      # Headless service with no camera
        microphone=True,
        speaker=True,
    ),
)

Declare device capability, not current usage mode — a voice-capable client sets microphone=True even while it is being used for text only.

note

Omitting capabilities is equivalent to declaring every field True, which is also what the server assumes for clients that send nothing. Existing code keeps working unchanged.

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.