# Exports

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

Source: https://maincode.com/docs/python-client-sdk-exports
Section: Client SDK · Matilda documentation

---

## 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. |