All data models are frozen dataclasses with a from_dict() class method for deserialization. Import them from the top-level estuary_sdk package.
Session & Connection
SessionInfo
Returned by client.connect().
| Field | Type | Description |
|---|
session_id | str | Unique session identifier |
conversation_id | str | Conversation identifier |
character_id | str | Character (agent) ID |
player_id | str | Player ID |
livekit_token | str | None | LiveKit token (if server supports LiveKit) |
livekit_url | str | None | LiveKit server URL |
livekit_room | str | None | LiveKit room name |
Response Models
BotResponse
A chunk of the character's text response.
| Field | Type | Description |
|---|
text | str | Full accumulated response text |
partial | str | Text content of just this chunk |
is_final | bool | True when the response is complete |
message_id | str | Unique message identifier |
chunk_index | int | Sequential chunk index (starts at 0) |
is_interjection | bool | True if unprompted message |
BotVoice
A chunk of the character's voice audio.
| Field | Type | Description |
|---|
audio | str | Base64-encoded PCM audio data |
message_id | str | Unique message identifier |
chunk_index | int | Sequential chunk index |
is_final | bool | True when last audio chunk |
is_livekit | bool | True if audio routed via LiveKit |
SttResponse
Speech-to-text transcription result.
| Field | Type | Description |
|---|
text | str | Transcribed text |
is_final | bool | True when transcription is finalized |
InterruptData
Information about an interrupted response.
| Field | Type | Description |
|---|
message_id | str | None | ID of interrupted message |
reason | str | None | Reason for interruption |
interrupted_at | str | None | ISO timestamp |
QuotaExceededData
Quota limit information.
| Field | Type | Description |
|---|
message | str | Human-readable message |
current | int | Current usage count |
limit | int | Usage limit |
remaining | int | Remaining quota |
tier | str | Account tier |
CameraCaptureRequest
Server request for a camera image.
| Field | Type | Description |
|---|
request_id | str | Request identifier |
text | str | None | Optional text prompt |
Memory Models
MemoryData
A single memory entry.
| Field | Type | Description |
|---|
id | str | Memory ID |
user_id | str | Owning user ID |
agent_id | str | Character (agent) ID |
player_id | str | Player ID |
content | str | Memory content text |
memory_type | str | Type of memory |
confidence | float | Confidence score (0-1) |
status | str | Status ("active", "superseded", "decayed") |
source_conversation_id | str | ID of the conversation that produced this memory |
source_quote | str | Original text that produced this memory |
source | str | Source ("text_chat", "voice", etc.) |
topic | str | Primary topic |
secondary_topics | list[str] | Additional topics |
last_accessed_at | str | None | ISO timestamp of last retrieval |
access_count | int | Number of times this memory was retrieved |
extracted_at | str | None | ISO timestamp of extraction |
created_at | str | None | ISO timestamp of creation |
updated_at | str | None | ISO timestamp of last update |
MemoryListResponse
Paginated list of memories.
| Field | Type | Description |
|---|
memories | list[MemoryData] | Memory entries |
total | int | Total count |
limit | int | Page size |
offset | int | Page offset |
CoreFact
A stable, high-confidence fact.
| Field | Type | Description |
|---|
id | str | Fact ID |
fact_key | str | Fact key (e.g., "name", "favorite_food") |
fact_value | str | Fact value |
source_memory_id | str | None | ID of the memory this fact was derived from |
CoreFactsResponse
| Field | Type | Description |
|---|
core_facts | list[CoreFact] | List of core facts |
MemorySearchResult
A single search hit. It carries the matched memory's ID, score, and text, not the full MemoryData record. Look the record up with client.memory.get_memories() if you need its other fields.
| Field | Type | Description |
|---|
memory_id | str | ID of the matched memory |
similarity | float | Similarity score (higher is more relevant) |
content | str | The matched memory's content text |
MemorySearchResponse
| Field | Type | Description |
|---|
results | list[MemorySearchResult] | Search results |
query | str | Original search query |
total | int | Total matches |
MemoryTimeline
Memories grouped by time period.
| Field | Type | Description |
|---|
timeline | list[TimelineEntry] | Date-grouped entries |
total_memories | int | Total memory count |
group_by | str | Grouping period |
TimelineEntry
| Field | Type | Description |
|---|
date | str | Date label |
memories | list[MemoryData] | Memories in this period |
MemoryStats
| Field | Type | Description |
|---|
total_active | int | Active memories |
total_superseded | int | Superseded memories |
total_decayed | int | Decayed memories |
by_type | dict[str, int] | Count by memory type |
core_facts | int | Number of core facts |
MemoryDeleteResponse
| Field | Type | Description |
|---|
message | str | Legacy confirmation message (Deleted N records) synthesized by the SDK from the count. |
deleted_count | int | Number of memories deleted |
Knowledge Graph Models
MemoryGraph
The full knowledge graph.
| Field | Type | Description |
|---|
nodes | list[GraphNode] | Graph nodes |
edges | list[GraphEdge] | Graph edges |
stats | GraphStats | Graph statistics |
stale | bool | Whether the graph needs rebuilding |
GraphNode
A node in the knowledge graph. Fields vary by node type.
| Field | Type | Description |
|---|
id | str | Node ID |
type | str | Node type: "user", "cluster", "memory", "entity" |
label | str | None | Display label |
content | str | None | Memory content (memory nodes) |
memory_type | str | None | Memory type (memory nodes) |
confidence | float | None | Confidence score (memory nodes) |
name | str | None | Entity name (entity nodes) |
entity_type | str | None | Entity type (entity nodes) |
mention_count | int | None | Number of mentions (entity nodes) |
memory_count | int | None | Memories in cluster (cluster nodes) |
level | int | None | Hierarchy level (cluster nodes) |
GraphEdge
An edge connecting two nodes.
| Field | Type | Description |
|---|
source | str | Source node ID |
target | str | Target node ID |
type | str | Edge type |
relationship_type | str | None | Relationship category |
label | str | None | Display label |
confidence | float | None | Confidence score |
GraphStats
| Field | Type | Description |
|---|
total_memories | int | Total memories in graph |
total_entities | int | Total entities |
cluster_count | int | Number of clusters |
clusters | dict[str, int] | Cluster sizes by label |
Character Models
Character
A full character definition.
| Field | Type | Description |
|---|
id | str | Character ID |
name | str | Character name |
tagline | str | None | Short tagline |
personality | str | None | Personality description |
background | str | None | Background story |
avatar | str | None | Avatar URL |
system_prompt | str | None | Custom system prompt |
llm_provider | str | LLM provider (default: "openai") |
llm_model | str | LLM model (default: "gpt-5-mini") |
tts_provider | str | TTS provider (default: "inworld") |
tts_model | str | TTS model (default: "inworld-tts-2-flash") |
tts_delivery_mode | str | None | Inworld TTS-2 quality setting: "STABLE", "BALANCED", or "CREATIVE"; None uses the provider default |
tts_voice | str | None | TTS voice ID |
actions | list[AgentAction] | Available actions |
is_public | bool | Whether publicly visible |
is_active | bool | Whether currently active |
launch_status | str | "running", "stopped", etc. |
CharacterListResponse
| Field | Type | Description |
|---|
characters | list[Character] | Character list |
total | int | Total count |
limit | int | Page size |
offset | int | Page offset |
GeneratedCharacter
Result of image-to-character generation.
| Field | Type | Description |
|---|
id | str | Character ID |
name | str | Generated name |
personality | str | Generated personality |
model_url | str | None | 3D model URL (when ready) |
model_status | str | None | Model generation status |
source_image_url | str | None | Original image URL |
ModelStatus
3D model generation progress.
| Field | Type | Description |
|---|
model_status | str | None | Current status |
model_preview_url | str | None | Preview URL |
model_url | str | None | Final model URL |
thumbnail_url | str | None | Thumbnail URL |
progress | int | Progress percentage (0-100) |
Player Models
PlayerConversation
A player's conversation record.
| Field | Type | Description |
|---|
id | str | Conversation ID |
character_id | str | Character ID |
player_id | str | Player ID |
message_count | int | Number of messages |
last_activity | str | None | Last activity timestamp |
created_at | str | None | Creation timestamp |
PlayerConversationList
| Field | Type | Description |
|---|
conversations | list[PlayerConversation] | Conversation list |
total | int | Total count |
PlayerMessage
A single message in a conversation.
| Field | Type | Description |
|---|
id | int | Message ID |
conversation_id | str | Conversation ID |
role | str | "user" or "assistant" |
content | str | Message text |
timestamp | str | None | ISO timestamp |
image_url | str | None | Attached image URL |
PlayerMessageList
| Field | Type | Description |
|---|
messages | list[PlayerMessage] | Message list |
pagination | Pagination | Pagination metadata |
PlayerStats
| Field | Type | Description |
|---|
total_conversations | int | Total conversations |
total_messages | int | Total messages |
first_activity | str | None | First activity timestamp |
last_activity | str | None | Last activity timestamp |
| Field | Type | Description |
|---|
page | int | Current page |
limit | int | Page size |
total | int | Total items |
has_more | bool | Whether more pages exist |
RetryConfig
Configuration for HTTP request retries in RestClient.
| Field | Type | Default | Description |
|---|
max_retries | int | 3 | Maximum number of retry attempts |
backoff_factor | float | 1.0 | Multiplier for exponential backoff delay |
retry_on_status | tuple[int, ...] | (500, 502, 503, 504) | HTTP status codes that trigger a retry |
Action Models
AgentAction
An action the character can perform.
| Field | Type | Description |
|---|
name | str | Action name |
description | str | None | Action description |
parameters | list[ActionParameter] | Action parameters |
ActionParameter
| Field | Type | Description |
|---|
name | str | Parameter name |
type | str | Parameter type (default: "string") |
required | bool | Whether required |
description | str | None | Parameter description |
MemoryUpdatedEvent
Real-time memory extraction notification.
| Field | Type | Description |
|---|
agent_id | str | Character ID |
player_id | str | Player ID |
memories_extracted | int | Memories extracted this turn |
facts_extracted | int | Core facts extracted |
conversation_id | str | Conversation ID |
new_memories | list[MemoryData] | Newly extracted memories |
timestamp | str | ISO timestamp |