EstuaryClient
The main entry point for the Estuary Python SDK. Inherits from AsyncEventEmitter.
from estuary_sdk import EstuaryClient, EstuaryConfig
config = EstuaryConfig(...)
client = EstuaryClient(config)
Context Manager
EstuaryClient supports async with for automatic cleanup:
async with EstuaryClient(config) as client:
await client.connect()
# ... use client ...
# disconnect() is called automatically on exit
Connection Methods
connect() -> SessionInfo
Connect to the Estuary server and authenticate. Returns a SessionInfo with session details.
session = await client.connect()
print(session.session_id, session.conversation_id)
Raises: EstuaryError with AUTH_FAILED, CONNECTION_FAILED, or CONNECTION_TIMEOUT.
disconnect() -> None
Disconnect from the server and clean up all resources (voice, REST client).
await client.disconnect()
Properties
| Property | Type | Description |
|---|---|---|
is_connected | bool | Whether the client is currently connected |
session | SessionInfo | None | Current session info, or None if not connected |
Text Methods
send_text(text, text_only=False) -> None
Send a text message to the character.
| Parameter | Type | Default | Description |
|---|---|---|---|
text | str | required | The message text |
text_only | bool | False | If True, suppress voice response |
Raises: EstuaryError with NOT_CONNECTED.
say_line(text, text_only=False) -> None
Script the character to say a specific prewritten line. Interrupts any in-progress response, skips the LLM entirely, and feeds the text directly to TTS (or text-only if text_only=True). The line is saved to chat history as a normal assistant turn.
| Parameter | Type | Default | Description |
|---|---|---|---|
text | str | required | The exact line the character should speak. Blank/whitespace strings are silently ignored. |
text_only | bool | False | If True, only bot_response is emitted (no TTS audio). |
Raises: EstuaryError with NOT_CONNECTED (unless text is blank, which is a no-op).
send_text_and_wait(text, *, text_only=False, timeout=20.0) -> BotResponse
Send a text message and wait for the final bot response. Returns the complete BotResponse directly.
| Parameter | Type | Default | Description |
|---|---|---|---|
text | str | required | The message text |
text_only | bool | False | If True, suppress voice response |
timeout | float | 20.0 | Max seconds to wait for a final response |
Returns: BotResponse with is_final=True.
Raises: asyncio.TimeoutError if no final response within timeout. EstuaryError with NOT_CONNECTED.
interrupt(message_id=None) -> None
Interrupt the current bot response.
| Parameter | Type | Default | Description |
|---|---|---|---|
message_id | str | None | None | Specific message to interrupt, or None for current |
Voice Methods
start_voice(mode=VoiceMode.CONTINUOUS) -> None
Start a voice session.
| Parameter | Type | Default | Description |
|---|---|---|---|
mode | VoiceMode | CONTINUOUS | CONTINUOUS for VAD, PUSH_TO_TALK for manual control |
Raises: EstuaryError with VOICE_ALREADY_ACTIVE, VOICE_START_FAILED, or LIVEKIT_UNAVAILABLE.
stop_voice() -> None
Stop the voice session and clean up resources.
start_recording() -> None
Begin streaming audio (push-to-talk mode only).
Raises: EstuaryError with VOICE_NOT_ACTIVE.
stop_recording() -> None
Stop streaming audio and trigger end-of-turn (push-to-talk mode only).
Raises: EstuaryError with VOICE_NOT_ACTIVE.
send_audio(audio) -> None
Send raw PCM16 audio bytes to the server.
| Parameter | Type | Description |
|---|---|---|
audio | bytes | Raw PCM16 audio (16-bit signed integer, mono, at configured sample rate) |
Raises: EstuaryError with VOICE_NOT_ACTIVE.
toggle_mute() -> None
Toggle voice mute state.
Voice Properties
| Property | Type | Description |
|---|---|---|
is_voice_active | bool | Whether a voice session is currently active |
is_muted | bool | Whether voice is currently muted |
Vision Methods
send_camera_image(image_base64, mime_type, request_id=None, text=None) -> None
Send a camera image for vision processing.
| Parameter | Type | Default | Description |
|---|---|---|---|
image_base64 | str | required | Base64-encoded image data |
mime_type | str | required | Image MIME type (e.g., "image/jpeg") |
request_id | str | None | None | Request ID from camera_capture_request event |
text | str | None | None | Optional text to accompany the image |
Preferences
update_preferences(enable_vision_acknowledgment=None) -> None
Update session preferences.
notify_audio_playback_complete(message_id=None) -> None
Notify the server that audio playback has finished.
REST Sub-Clients
These are accessed as properties on the client:
client.memory -> MemoryClient
Memory REST API. Available after connect().
| Method | Returns | Description |
|---|---|---|
get_memories(...) | MemoryListResponse | List memories with filtering/pagination |
get_timeline(...) | MemoryTimeline | Memories grouped by time period |
get_stats() | MemoryStats | Aggregate memory statistics |
get_core_facts() | CoreFactsResponse | High-confidence stable facts |
get_graph(...) | MemoryGraph | Full knowledge graph |
search(query, limit) | MemorySearchResponse | Semantic similarity search |
delete_all(confirm) | MemoryDeleteResponse | Delete all memories |
client.players -> PlayersClient
Players REST API. Available after connect().
| Method | Returns | Description |
|---|---|---|
list(...) | PlayerConversationList | List player conversations |
get(player_id) | PlayerConversation | Get a single player conversation |
get_messages(player_id, ...) | PlayerMessageList | Get conversation messages |
get_stats() | PlayerStats | Aggregate player statistics |
delete(player_id) | dict | Delete a player and all data |
client.characters -> CharactersClient
Characters REST API. Available immediately (no connect() required).
| Method | Returns | Description |
|---|---|---|
create(name, ...) | Character | Create a new character |
list(limit, offset) | CharacterListResponse | List characters |
get(character_id) | Character | Get a character by ID |
update(character_id, ...) | Character | Update a character |
delete(character_id) | dict | Delete a character |
client.generate -> GenerateClient
Character generation REST API. Available immediately (no connect() required).
| Method | Returns | Description |
|---|---|---|
image_to_character(image_base64, mime_type) | GeneratedCharacter | Generate a character from an image |
get_model_status(agent_id) | ModelStatus | Poll 3D model generation status |
wait_for_model(agent_id, *, poll_interval, timeout, on_progress) | ModelStatus | Poll until model completes or fails |
client.shares -> SharesClient
Share characters via long-lived anchors (NFC tags, QR codes, print) or short-lived tokens. Available immediately (no connect() required).
See Sharing Characters for a full guide.
| Method | Returns | Description |
|---|---|---|
create_anchor(character_id, memory_sharing, max_interactions) | dict | Create a long-lived anchor ({id, anchorUrl}) |
open_anchor(anchor_id) | dict | Redeem an anchor for a session token |
exchange_share_token(token, recipient_id) | dict | Exchange a short-lived share token for a session token |
list_anchors(character_id) | dict | (Firebase auth) List owned anchors |
revoke_anchor(anchor_id) | dict | (Firebase auth) Revoke a single anchor |
bulk_revoke_anchors_by_api_key(api_key_id) | dict | (Firebase auth) Revoke all anchors minted by an API key |
create_share_token(character_id, ttl, memory_sharing, max_exchanges) | dict | (Firebase auth) Create a short-lived share token |
list_character_shares(character_id) | dict | (Firebase auth) List active share tokens for a character |
revoke_share_token(share_token_id) | dict | (Firebase auth) Revoke a share token |
Methods marked (Firebase auth) require a Firebase ID token on the backend and will raise EstuaryError (HTTP 401) with API-key-only auth. Only create_anchor, open_anchor, and exchange_share_token are reachable with a standard est_ API key.