Client SDK quickstart.

A small, self-contained Python SDK for building Matilda clients. Async-first (built on httpx), fully typed, with typed stream events and zero runtime dependencies beyond httpx and the standard library. Requires Python 3.12 or later. This guide covers SDK version 0.3.0.

The SDK follows the OpenAI client shape where it helps: constructor config, resource groups, request options, typed API errors, and async-iterable streaming. It does not expose model or provider selection — Matilda core owns routing, safety, resumable SSE, server-side tool execution, and policy.

What's included

• Chat — non-streaming, full-event streaming, text-only streaming, schema-constrained structured output, and durable stream resume
• Conversations — list, retrieve, rename, and set message feedback
• Files — upload (single and parallel), retrieve metadata
• Feedback — report harmful content and submit response feedback
• Auth — managed PKCE browser login, RFC 8628 device flow, token refresh, and persistent token storage
• API keys — create, list, and revoke mc_live_ API keys via SDK methods or the matilda-key CLI

What's not included

• Local tool-execution loop — for client-side tool execution (client_tools, local approval/sandbox loops, tool-result continuation), use the agent SDK
• Session class — multi-turn conversations are managed via conversation_id; see Multi-turn conversations
• Devices — push-notification device management is not yet exposed on the Python client surface

Installation

pip install matilda-client

pydantic is an optional dependency — install it alongside the SDK if you want schema-validated structured output (Structured output). The SDK detects pydantic models by duck-typing, so any version works:

pip install pydantic

Import

from matilda_client import MatildaClient

Auth modules

The standalone auth helpers live in two submodules — the transport-agnostic OAuth protocol core, and the local-machine adapters (loopback receiver, file token store, managed login flows):

from matilda_client.auth import (
    create_token_manager,
    fetch_auth_server_metadata,
    memory_storage,
)
from matilda_client.auth_local import (
    create_file_token_store,
    create_loopback_receiver,
    run_device_login_flow,
    run_loopback_login_flow,
)

Quick start

Send a message

import asyncio
import os

from matilda_client import MatildaClient


async def main():
    async with MatildaClient(token=os.environ["MATILDA_ACCESS_TOKEN"]) as client:
        response = await client.chat.create(input="Summarize this thread.")
        print(response.output_text)


asyncio.run(main())

Stream a response

import os

from matilda_client import MatildaClient


async def main():
    async with MatildaClient(token=os.environ["MATILDA_ACCESS_TOKEN"]) as client:
        async for event in client.chat.stream(input="Write a short plan."):
            if event.type == "response.output_text.delta":
                print(event.delta, end="", flush=True)

Authenticated: device flow and chat

import asyncio

from matilda_client import MatildaClient


async def main():
    async with MatildaClient() as client:
        # Authenticate via RFC 8628 device flow — prints a code to stderr
        await client.auth.login_with_device_flow(client_id="matilda-code")

        # Token is now managed automatically — no manual header wiring
        response = await client.chat.create(input="Hello, Matilda!")
        print(response.output_text)


asyncio.run(main())