Client SDK · Reference

Exports.

Every class, dataclass, and type the matilda-client package exports.

Client

Export	Kind	Description
`MatildaClient`	class	Main client class — owns the `chat`, `files`, `conversations`, `feedback`, `api_keys`, and `auth` resources.
`MatildaConfig`	dataclass	Client configuration (frozen).
`TokenProvider`	type alias	`Callable[[bool], Awaitable[str \| None]]` — async token provider.

Chat responses and events

Export	Kind	Description
`MatildaChatResponse`	dataclass	Collected response from `chat.create()`.
`MatildaObjectResponse[T]`	dataclass	`chat.create_object()` response (extends `MatildaChatResponse`, adds `object`).
`ChatEvent`	type alias	Union of the 14 stream event dataclasses.
`MatildaObjectEvent[T]`	type alias	`chat.stream_object()` events — all chat events, plus a final `ObjectEvent`.
`ObjectEvent[T]`	dataclass	Terminal structured-output event (`type="object"`).
`ResponseCreated`	dataclass	`response.created` — stream ID.
`OutputTextDelta`	dataclass	`response.output_text.delta` — text chunk.
`OutputTextReplace`	dataclass	`response.output_text.replace` — safety replacement.
`StatusEvent`	dataclass	`response.status` — lifecycle status.
`QueuedEvent`	dataclass	`response.queued` — queue position.
`ToolCallStarted`	dataclass	`response.tool_call.started`.
`ToolCallProgress`	dataclass	`response.tool_call.progress`.
`ToolCallCompleted`	dataclass	`response.tool_call.completed`.
`GenerationStatus`	dataclass	`response.generation_status`.
`UsageEvent`	dataclass	`response.usage` — wraps `Usage`.
`Usage`	dataclass	Token usage payload.
`CursorEvent`	dataclass	`response.cursor` — durable cursor.
`Truncated`	dataclass	`response.truncated`.
`Completed`	dataclass	`response.completed`.
`ResponseError`	dataclass	`response.error` — code + message.
`StreamErrorInfo`	dataclass	Error entry in `MatildaChatResponse.errors`.
`EventCallback`	type alias	`Callable[[ChatEvent], None]`.
`ChatErrorCode`	type alias	`Literal` union of the chat error codes.

Errors

Export	Kind	Description
`MatildaError`	class	Base class for every SDK error.
`MatildaAPIError`	class	HTTP error (`status`, `response_text`).
`QuotaExceededError`	class	429 quota error with structured quota attributes.
`MatildaStreamError`	class	Terminal stream `error` event (`code`).
`SafetyReplaceError`	class	Safety filter replacement (`categories`).
`MatildaObjectParseError`	class	Structured output parse/validation failure (`raw`, `cause`).
`UploadError`	class	File upload failure.
`AuthError`	class	OAuth error (`code`, `retryable`).

Auth

Export	Kind	Description
`AuthResource`	class	Managed auth on `client.auth` — `login_with_browser`, `login_with_device_flow`, `refresh_token`, `get_tokens`, `logout`.
`TokenManager`	class	Per-session token manager with single-flight refresh.
`create_token_manager`	function	`TokenManager` factory.
`TokenSet`	dataclass	OAuth token set (`access_token`, `refresh_token`, `id_token`, `expires_at`).
`StorageAdapter`	protocol	Pluggable token storage (sync or async).
`MemoryStorage` / `memory_storage`	class / function	In-memory `StorageAdapter`.
`FileTokenStore` / `create_file_token_store`	class / function	`0600` JSON file store with `.store` and cross-process `.lock`.
`LoopbackReceiver` / `create_loopback_receiver`	class / function	RFC 8252 loopback redirect receiver.
`run_loopback_login_flow`	function	Headless PKCE loopback login.
`run_device_login_flow`	function	Headless RFC 8628 device login.
`default_device_on_event`	function	Prints the device user code to stderr.
`LoginFlowEvent`	type alias	`StateEvent \| AuthorizeUrlEvent \| UserCodeEvent`.
`StateEvent` / `AuthorizeUrlEvent` / `UserCodeEvent`	dataclasses	Login flow state events.
`AuthServerMetadata`	dataclass	RFC 8414 server metadata.
`fetch_auth_server_metadata`	function	Metadata discovery.
`DeviceAuthorization`	dataclass	Device-flow code + URIs.
`request_device_code` / `poll_device_token`	functions	Device-flow grant halves.
`BeginLoginResult` / `begin_login` / `complete_login`	dataclass / functions	Stateless redirect-login halves.
`exchange_code_for_tokens`	function	Authorization-code exchange.
`refresh_token_grant`	function	Raw refresh-token grant.
`create_pkce_pair`	function	PKCE verifier + S256 challenge.
`build_authorize_url`	function	Construct the authorize URL.
`assert_state`	function	Validate the OAuth `state` round-trip.
`random_state`	function	High-entropy state value.
`base64_url_encode`	function	Padding-free base64url.

Files and feedback types

Export	Kind	Description
`FileComplete`	dataclass	Upload completion result (`file_id`, `status`).
`FeedbackPlatform`	type alias	`'web' \| 'ios' \| 'android' \| 'unknown'`.
`ReportReason`	type alias	`'harmful' \| 'inaccurate' \| 'off_topic' \| 'privacy' \| 'other'`.

Constants and version helpers

Export	Value	Description
`DEFAULT_BASE_URL`	`https://matilda.maincode.com/api`	Production API base URL.
`DEFAULT_CHUNK_SIZE`	8 MiB	Chunked-upload part size.
`DEFAULT_CHUNKED_THRESHOLD`	16 MiB	Chunked-upload file-size threshold.
`DEFAULT_PART_CONCURRENCY`	4	Parallel upload parts.
`DEFAULT_MAX_PART_RETRIES`	3	Retries per upload part.
`MAX_FILE_COUNT`	5	Maximum files per request.
`S3_MIN_CHUNK_SIZE`	5 MiB	S3 multipart minimum.
`DEFAULT_STALL_TIMEOUT_MS`	45 000	SSE stall watchdog default.
`DEFAULT_SUCCESS_REDIRECT`	`https://matilda.maincode.com/cli/signed-in`	Browser-login success redirect.
`MATILDA_API_VERSION_HEADER`	`X-Matilda-API-Version`	API version header name.
`MATILDA_CURRENT_API_VERSION`	—	Current API version string.
`CHAT_ERROR_CODES`	frozenset	The chat error codes.
`sdk_version()`	—	Installed package version.