Client SDK · Chat

Chat.

Send messages and get complete responses from the chat API.

`chat.create(...)`

Sends a chat message and returns the complete response. Internally this runs the stream and collects all events.

Python

async def main():
    async with MatildaClient(token="...") as client:
        response = await client.chat.create(
            input="What is the capital of Australia?",
            conversation_id="conv-123",
            response_mode="instant",
        )

        print(response.output_text)
        print(response.usage)

Parameters

Field	type	description
input	str \| None	The user's message. Required if messages is not provided.
messages	list[dict] \| None	Explicit message array. Overrides input. Each message: { role: 'user' \| 'assistant', content: str }.
conversation_id	str \| None	Associates this message with a conversation thread for multi-turn chat.
file_ids	list[str] \| None	File IDs to attach (from files.upload()).
response_mode	str \| None	Response depth: 'auto', 'instant', or 'deep'. Defaults to 'auto'.
response_schema	str \| None	Raw JSON Schema (as a string) to grammar-constrain the response to. Prefer chat.stream_object / chat.create_object, which convert a pydantic model for you (see Structured output).
access_token	str \| None	Override the client-level access token for this request.
fingerprint	str \| None	Device fingerprint for rate limiting.
stall_timeout_ms	int \| None	SSE stall watchdog timeout in ms. Defaults to 45_000. Pass 0 to disable.
on_event	Callable[[ChatEvent], None] \| None	Catch-all stream event hook — fires for every event. Only honoured by convenience methods that consume the stream for you (chat.create(), chat.create_object()); use chat.stream() when you want to process events yourself.

`MatildaChatResponse`

Field	type	description
output_text	str	The full assistant response text.
events	list[ChatEvent]	Every event emitted during the stream.
stream_id	str \| None	Durable stream ID (from the response.created event).
last_event_id	str \| None	Last Redis stream entry ID (for resume).
usage	Usage \| None	Token usage data.
errors	list[StreamErrorInfo]	Any errors emitted during the stream.
truncated_reason	str \| None	Why the response was truncated (e.g. 'max_tokens').

Response modes

'auto' — Server decides the optimal response depth.
'instant' — Optimised for low latency.
'deep' — Optimised for thoroughness.