matilda-client 0.3.0__py3-none-any.whl

matilda_client/__init__.py

@@ -0,0 +1,196 @@
+"""Public Python client SDK for the Matilda API.
+
+Async-first (httpx) client mirroring the TypeScript
+``@maincode-ai/matilda-client-sdk``: streaming chat with typed events,
+grammar-constrained structured output, robust chunked parallel file uploads,
+conversations, feedback (including SDK bug reports), and API-key management.
+
+Minimal dependencies: httpx + stdlib only, per ADR-025's SDK-boundary rule.
+
+    async with MatildaClient(token="eyJ...") as client:
+        response = await client.chat.create(input="G'day")
+        print(response.output_text)
+"""
+
+from ._client import MatildaClient, PublicRuntimeConfig
+from ._config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CHUNK_SIZE,
+    DEFAULT_CHUNKED_THRESHOLD,
+    DEFAULT_MAX_PART_RETRIES,
+    DEFAULT_PART_CONCURRENCY,
+    MAX_FILE_COUNT,
+    MatildaConfig,
+    TokenProvider,
+)
+from ._errors import (
+    CHAT_ERROR_CODES,
+    ChatErrorCode,
+    MatildaAPIError,
+    MatildaContentTypeError,
+    MatildaError,
+    MatildaObjectParseError,
+    MatildaStreamError,
+    QuotaExceededError,
+    SafetyReplaceError,
+    UploadError,
+)
+from ._events import (
+    ChatEvent,
+    Completed,
+    CursorEvent,
+    EventCallback,
+    GenerationStatus,
+    MatildaChatResponse,
+    MatildaObjectEvent,
+    MatildaObjectResponse,
+    ObjectEvent,
+    OutputTextDelta,
+    OutputTextReplace,
+    QueuedEvent,
+    ResponseCreated,
+    ResponseError,
+    StatusEvent,
+    StreamErrorInfo,
+    ToolCallCompleted,
+    ToolCallProgress,
+    ToolCallStarted,
+    Truncated,
+    Usage,
+    UsageEvent,
+)
+from ._sse import DEFAULT_STALL_TIMEOUT_MS
+from ._version import (
+    MATILDA_API_VERSION_HEADER,
+    MATILDA_CURRENT_API_VERSION,
+    sdk_version,
+)
+from .auth import (
+    AuthError,
+    AuthServerMetadata,
+    BeginLoginResult,
+    DeviceAuthorization,
+    MemoryStorage,
+    StorageAdapter,
+    TokenManager,
+    TokenSet,
+    assert_state,
+    base64_url_encode,
+    begin_login,
+    build_authorize_url,
+    complete_login,
+    create_pkce_pair,
+    create_token_manager,
+    exchange_code_for_tokens,
+    fetch_auth_server_metadata,
+    memory_storage,
+    poll_device_token,
+    random_state,
+    refresh_token_grant,
+    request_device_code,
+)
+from .auth_local import (
+    DEFAULT_SUCCESS_REDIRECT,
+    AuthorizeUrlEvent,
+    AuthResource,
+    FileTokenStore,
+    LoginFlowEvent,
+    LoopbackReceiver,
+    StateEvent,
+    UserCodeEvent,
+    create_file_token_store,
+    create_loopback_receiver,
+    default_device_on_event,
+    run_device_login_flow,
+    run_loopback_login_flow,
+)
+from .feedback import FeedbackPlatform, ReportReason
+from .files import S3_MIN_CHUNK_SIZE, FileComplete
+
+__all__ = [
+    "CHAT_ERROR_CODES",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_CHUNK_SIZE",
+    "DEFAULT_CHUNKED_THRESHOLD",
+    "DEFAULT_MAX_PART_RETRIES",
+    "DEFAULT_PART_CONCURRENCY",
+    "DEFAULT_STALL_TIMEOUT_MS",
+    "DEFAULT_SUCCESS_REDIRECT",
+    "MATILDA_API_VERSION_HEADER",
+    "MATILDA_CURRENT_API_VERSION",
+    "MAX_FILE_COUNT",
+    "S3_MIN_CHUNK_SIZE",
+    "AuthError",
+    "AuthResource",
+    "AuthServerMetadata",
+    "AuthorizeUrlEvent",
+    "BeginLoginResult",
+    "ChatErrorCode",
+    "ChatEvent",
+    "Completed",
+    "CursorEvent",
+    "DeviceAuthorization",
+    "EventCallback",
+    "FeedbackPlatform",
+    "FileComplete",
+    "FileTokenStore",
+    "GenerationStatus",
+    "LoginFlowEvent",
+    "LoopbackReceiver",
+    "MatildaAPIError",
+    "MatildaChatResponse",
+    "MatildaClient",
+    "MatildaConfig",
+    "MatildaContentTypeError",
+    "MatildaError",
+    "MatildaObjectEvent",
+    "MatildaObjectParseError",
+    "MatildaObjectResponse",
+    "MatildaStreamError",
+    "MemoryStorage",
+    "ObjectEvent",
+    "OutputTextDelta",
+    "OutputTextReplace",
+    "PublicRuntimeConfig",
+    "QueuedEvent",
+    "QuotaExceededError",
+    "ReportReason",
+    "ResponseCreated",
+    "ResponseError",
+    "SafetyReplaceError",
+    "StateEvent",
+    "StatusEvent",
+    "StorageAdapter",
+    "StreamErrorInfo",
+    "TokenManager",
+    "TokenProvider",
+    "TokenSet",
+    "ToolCallCompleted",
+    "ToolCallProgress",
+    "ToolCallStarted",
+    "Truncated",
+    "UploadError",
+    "Usage",
+    "UsageEvent",
+    "UserCodeEvent",
+    "assert_state",
+    "base64_url_encode",
+    "begin_login",
+    "build_authorize_url",
+    "complete_login",
+    "create_file_token_store",
+    "create_loopback_receiver",
+    "create_pkce_pair",
+    "create_token_manager",
+    "default_device_on_event",
+    "exchange_code_for_tokens",
+    "fetch_auth_server_metadata",
+    "memory_storage",
+    "poll_device_token",
+    "random_state",
+    "refresh_token_grant",
+    "request_device_code",
+    "run_device_login_flow",
+    "run_loopback_login_flow",
+    "sdk_version",
+]

matilda_client/_client.py

@@ -0,0 +1,379 @@
+"""Core client: configuration, header/auth plumbing, and request helpers.
+
+``MatildaClient`` owns the HTTP seam (``_http``, overridable in tests) and
+hosts the resource attributes — files, chat, conversations, feedback,
+api_keys — mirroring how the TS SDK's ``Matilda`` composes ``MatildaCore``.
+
+Every request helper mirrors the TS fetchWithRetry pattern: on HTTP 401 with
+a token provider configured, the provider is called with
+``force_refresh=True`` and the request is retried exactly once.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+import httpx
+
+from ._config import DEFAULT_BASE_URL, MatildaConfig, TokenProvider
+from ._errors import MatildaAPIError, QuotaExceededError, UploadError
+from ._version import (
+    MATILDA_API_VERSION_HEADER,
+    SDK_LANGUAGE,
+    SDK_NAME,
+    sdk_version,
+)
+
+
+def _positive_int_or_none(value: Any) -> int | None:
+    """Only positive ints propagate: non-positive server-advertised upload
+    sizing counts as absent (a zero chunk size would never advance the
+    slicing loop; negative values are nonsense)."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        return None
+    return value if value > 0 else None
+
+
+@dataclass(frozen=True)
+class PublicRuntimeConfig:
+    """Server-advertised upload settings (unauthenticated GET /config/public).
+
+    Defaults are the safe direction: chunking on, direct part upload OFF — so
+    an unreachable config endpoint never silently switches transport.
+    """
+
+    upload_chunk_size_bytes: int | None = None
+    upload_chunked_threshold_bytes: int | None = None
+    upload_chunked_enabled: bool = True
+    upload_direct_enabled: bool = False
+    uploads_host: str | None = None
+
+
+class MatildaClient:
+    """Top-level Matilda API client (async-first).
+
+    Example:
+        async with MatildaClient(token="eyJ...") as client:
+            result = await client.chat.create(input="G'day")
+            print(result.output_text)
+
+    Also accepts a pre-built ``config=MatildaConfig(...)``; per-request Bearer
+    tokens can come from ``config.token`` or the async ``config.get_token``
+    provider (the latter enables the 401-refresh-retry path).
+    """
+
+    def __init__(
+        self,
+        token: str = "",
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        get_token: TokenProvider | None = None,
+        config: MatildaConfig | None = None,
+    ) -> None:
+        if config is not None:
+            self.config = config
+        else:
+            self.config = MatildaConfig(
+                base_url=base_url.rstrip("/"), token=token, get_token=get_token
+            )
+
+        from .api_keys import ApiKeysResource
+        from .auth_local import AuthResource
+        from .chat import ChatResource
+        from .conversations import ConversationsResource
+        from .feedback import FeedbackResource
+        from .files import FilesResource
+
+        self.files = FilesResource(self)
+        self.chat = ChatResource(self)
+        self.conversations = ConversationsResource(self)
+        self.feedback = FeedbackResource(self)
+        self.api_keys = ApiKeysResource(self)
+        self.auth = AuthResource(self)
+
+        self._runtime_config: PublicRuntimeConfig | None = None
+
+    def _set_token_provider(self, provider: TokenProvider | None) -> None:
+        """Swap the async token provider (AuthResource wires this after
+        login/logout so every request carries a managed, auto-refreshing
+        token)."""
+        self.config = replace(self.config, get_token=provider)
+
+    # --- HTTP seam ---------------------------------------------------------
+
+    def _http(self) -> httpx.AsyncClient:
+        """Fresh AsyncClient per call.
+
+        Kept as a factory (rather than a shared client) so tests can inject a
+        MockTransport and so long-lived SSE streams never hold a shared
+        connection pool hostage. A persistent-client optimisation can revisit
+        this without touching call sites.
+        """
+        # trust_env=False: don't route requests through HTTP(S)_PROXY or pick
+        # up ~/.netrc credentials (httpx defaults to True; TS fetch has
+        # neither behaviour).
+        return httpx.AsyncClient(
+            timeout=httpx.Timeout(self.config.timeout, connect=10.0),
+            trust_env=False,
+        )
+
+    def _url(self, path: str, *, base: str | None = None) -> str:
+        """Absolute URL for ``path`` — built manually so a ``base_url`` with a
+        path prefix (e.g. the canonical ``.../api``) is never truncated by
+        RFC-3986 relative-URL joining."""
+        root = (base if base is not None else self.config.base_url).rstrip("/")
+        return f"{root}/{path.lstrip('/')}"
+
+    # --- Auth + headers ----------------------------------------------------
+
+    async def _resolve_token(
+        self,
+        *,
+        access_token: str | None = None,
+        force_refresh: bool = False,
+    ) -> str | None:
+        if access_token:
+            return access_token
+        if self.config.get_token is not None:
+            try:
+                return await self.config.get_token(force_refresh)
+            except Exception:
+                return None
+        return self.config.token or None
+
+    async def _build_headers(
+        self,
+        *,
+        json_content: bool = True,
+        fingerprint: str | None = None,
+        access_token: str | None = None,
+        force_refresh: bool = False,
+        sdk_provenance: dict[str, str] | None = None,
+    ) -> dict[str, str]:
+        """Mirrors MatildaCore.buildHeaders: API version, Bearer, fingerprint,
+        and SDK provenance (provenance only rides along when authenticated).
+
+        ``sdk_provenance`` swaps the provenance triplet for ONE request — used
+        by the agent SDK to label its own traffic without mutating the shared
+        client (the TS SDK's per-core ``clientProvenance`` equivalent)."""
+        headers: dict[str, str] = {}
+        if json_content:
+            headers["Content-Type"] = "application/json"
+        if self.config.api_version:
+            headers[MATILDA_API_VERSION_HEADER] = self.config.api_version
+        token = await self._resolve_token(access_token=access_token, force_refresh=force_refresh)
+        if fingerprint:
+            headers["x-fingerprint"] = fingerprint
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+            if sdk_provenance is not None:
+                headers.update(sdk_provenance)
+            else:
+                headers["x-matilda-sdk-name"] = SDK_NAME
+                headers["x-matilda-sdk-language"] = SDK_LANGUAGE
+                headers["x-matilda-sdk-version"] = sdk_version()
+        return headers
+
+    # --- Requests ----------------------------------------------------------
+
+    async def _stream_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        base: str | None = None,
+        json_body: Any = None,
+        content: bytes | None = None,
+        files: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        access_token: str | None = None,
+        fingerprint: str | None = None,
+        sdk_provenance: dict[str, str] | None = None,
+    ) -> tuple[httpx.AsyncClient, httpx.Response]:
+        """One streamed request with the 401 → force-refresh → retry-once dance.
+
+        Shared by the client's JSON helpers, the files resource's control-plane
+        calls, the chat SSE loop, and the agent SDK's SSE loops (which consume
+        it via ``MatildaClientProtocol``). Error mapping is deliberately left
+        to the caller: the client SDK maps through ``_raise_api`` (or
+        ``_raise_for_status`` for uploads) while the agent SDK raises
+        ``MatildaAgentRunError``.
+
+        Non-JSON bodies: pass ``content`` (raw bytes) or ``files`` (multipart)
+        instead of ``json_body`` — the JSON ``Content-Type`` is then dropped so
+        httpx can set the correct one; caller ``headers`` merge over the built
+        headers (e.g. ``Content-Type: application/octet-stream`` for a raw
+        part).
+
+        Returns the ``(http, response)`` pair with ``stream=True`` still open.
+        The caller owns both lifecycles: when the stream is exhausted (or the
+        caller bails out early), it must ``await resp.aclose()`` on a present
+        response and always ``await http.aclose()``.
+        """
+        http = self._http()
+        resp: httpx.Response | None = None
+        token_override = access_token
+        try:
+            for attempt in (0, 1):
+                req_headers = await self._build_headers(
+                    json_content=content is None and files is None,
+                    access_token=token_override,
+                    fingerprint=fingerprint,
+                    sdk_provenance=sdk_provenance,
+                )
+                if headers:
+                    req_headers.update(headers)
+                req = http.build_request(
+                    method,
+                    self._url(path, base=base),
+                    json=json_body,
+                    content=content,
+                    files=files,
+                    params=params,
+                    headers=req_headers,
+                )
+                resp = await http.send(req, stream=True)
+                if (
+                    resp.status_code == 401
+                    and attempt == 0
+                    and self.config.get_token is not None
+                ):
+                    fresh = await self._resolve_token(force_refresh=True)
+                    if fresh:
+                        await resp.aclose()
+                        token_override = fresh
+                        continue
+                break
+        except BaseException:
+            await http.aclose()
+            raise
+        if resp is None:  # pragma: no cover - loop always assigns before break
+            await http.aclose()
+            raise RuntimeError("unreachable")
+        return http, resp
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        base: str | None = None,
+        json_body: Any = None,
+        content: bytes | None = None,
+        files: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        access_token: str | None = None,
+        fingerprint: str | None = None,
+    ) -> httpx.Response:
+        """One buffered request with the 401 → force-refresh → retry-once dance."""
+        http, resp = await self._stream_request(
+            method,
+            path,
+            base=base,
+            json_body=json_body,
+            content=content,
+            files=files,
+            headers=headers,
+            params=params,
+            access_token=access_token,
+            fingerprint=fingerprint,
+        )
+        try:
+            await resp.aread()
+            return resp
+        finally:
+            await resp.aclose()
+            await http.aclose()
+
+    async def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        resp = await self._request(method, path, **kwargs)
+        self._raise_api(resp)
+        return resp.json()
+
+    async def _request_void(self, method: str, path: str, **kwargs: Any) -> None:
+        resp = await self._request(method, path, **kwargs)
+        self._raise_api(resp)
+
+    def _raise_api(self, resp: httpx.Response) -> None:
+        if resp.status_code < 400:
+            return
+        if resp.status_code == 429:
+            quota = _parse_quota(resp)
+            if quota is not None:
+                raise QuotaExceededError(quota, resp.text)
+        raise MatildaAPIError(resp.status_code, resp.text)
+
+    # --- Legacy upload error mapping (files resource) ----------------------
+
+    def _raise_for_status(self, resp: httpx.Response) -> None:
+        if resp.status_code >= 400:
+            body = resp.text
+            if resp.status_code == 413:
+                raise UploadError(f"File too large or quota exceeded (413): {body}")
+            if resp.status_code == 401:
+                raise UploadError(f"Authentication failed (401): {body}")
+            raise UploadError(f"Matilda API error ({resp.status_code}): {body}")
+
+    # --- Public runtime config ----------------------------------------------
+
+    async def fetch_public_runtime_config(self) -> PublicRuntimeConfig:
+        """Unauthenticated GET /config/public — server-advertised upload
+        settings (chunked/direct mode, chunk sizes, trusted uploads host).
+        Raises MatildaAPIError on non-2xx; fail-open callers should use
+        ``_ensure_runtime_config``."""
+        headers = (
+            {MATILDA_API_VERSION_HEADER: self.config.api_version}
+            if self.config.api_version
+            else {}
+        )
+        async with self._http() as http:
+            resp = await http.get(self._url("/config/public"), headers=headers)
+        self._raise_api(resp)
+        data = resp.json()
+        return PublicRuntimeConfig(
+            upload_chunk_size_bytes=_positive_int_or_none(data.get("uploadChunkSizeBytes")),
+            upload_chunked_threshold_bytes=_positive_int_or_none(
+                data.get("uploadChunkedThresholdBytes")
+            ),
+            upload_chunked_enabled=data.get("uploadChunkedEnabled") is not False,
+            upload_direct_enabled=data.get("uploadDirectEnabled") is True,
+            uploads_host=data.get("uploadsHost") or None,
+        )
+
+    async def _ensure_runtime_config(self) -> PublicRuntimeConfig:
+        """Fetch-once, client-lifetime cached runtime config. Fail-open: any
+        error yields the defaults (chunked on, direct OFF) so a config outage
+        never switches transport — mirrors the TS SDK's runtime-config
+        resolution (defaults take the safe direction)."""
+        if self._runtime_config is None:
+            try:
+                self._runtime_config = await self.fetch_public_runtime_config()
+            except Exception:
+                self._runtime_config = PublicRuntimeConfig()
+        return self._runtime_config
+
+    # --- Lifecycle ---------------------------------------------------------
+
+    async def aclose(self) -> None:
+        """No shared connections to close today; kept so ``async with`` has a
+        stable contract if a persistent client is introduced."""
+
+    async def __aenter__(self) -> MatildaClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+
+def _parse_quota(resp: httpx.Response) -> dict | None:
+    """Structured ``quota_exceeded`` body, or None (mirrors parseQuotaExceeded)."""
+    try:
+        body = resp.json()
+    except Exception:
+        return None
+    if isinstance(body, dict) and body.get("error") == "quota_exceeded":
+        return body
+    return None

matilda_client/_config.py

@@ -0,0 +1,78 @@
+"""Client configuration, mirroring the TS SDK's ClientConfig."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from ._errors import MatildaError, UploadError
+from ._version import MATILDA_CURRENT_API_VERSION
+
+DEFAULT_BASE_URL = "https://matilda.maincode.com/api"
+DEFAULT_CHUNK_SIZE = 8 * 1024 * 1024  # 8 MiB — mirrors core-api default
+DEFAULT_CHUNKED_THRESHOLD = 16 * 1024 * 1024  # 16 MiB
+DEFAULT_PART_CONCURRENCY = 4
+DEFAULT_MAX_PART_RETRIES = 3
+MAX_FILE_COUNT = 5
+
+# Async token provider: called with ``force_refresh`` and expected to return a
+# Bearer token or None. Wire this to a TokenManager-style refresher; on a 401 the
+# client calls it with ``force_refresh=True`` and retries the request once.
+TokenProvider = Callable[[bool], Awaitable[str | None]]
+
+
+@dataclass(frozen=True)
+class MatildaConfig:
+    """Client configuration.
+
+    ``token`` is a static Bearer JWT (e.g. from the matilda-code OAuth/PKCE
+    flow). For automatic refresh, pass ``get_token`` instead — an async
+    callable invoked on every request (and once more with
+    ``force_refresh=True`` after a 401, before the single retry).
+    """
+
+    base_url: str = DEFAULT_BASE_URL
+    token: str = ""
+    get_token: TokenProvider | None = None
+    timeout: float = 120.0
+    api_version: str = MATILDA_CURRENT_API_VERSION
+    chunk_size: int = DEFAULT_CHUNK_SIZE
+    chunked_threshold: int = DEFAULT_CHUNKED_THRESHOLD
+    part_concurrency: int = DEFAULT_PART_CONCURRENCY
+    max_part_retries: int = DEFAULT_MAX_PART_RETRIES
+
+    def __post_init__(self) -> None:
+        """Reject upload-control values that would hang or corrupt uploads:
+        a zero/negative chunk_size never advances the slicing loop, and
+        zero/negative concurrency deadlocks the part semaphore."""
+        if self.chunk_size <= 0:
+            raise ValueError(f"chunk_size must be positive (got {self.chunk_size})")
+        if self.chunked_threshold <= 0:
+            raise ValueError(f"chunked_threshold must be positive (got {self.chunked_threshold})")
+        if self.part_concurrency <= 0:
+            raise ValueError(f"part_concurrency must be positive (got {self.part_concurrency})")
+        if self.max_part_retries < 0:
+            raise ValueError(f"max_part_retries must be nonnegative (got {self.max_part_retries})")
+
+    @property
+    def auth_header(self) -> dict[str, str]:
+        """Static Bearer header built from ``token`` (raises when unset).
+
+        Prefer the awaited header builders on MatildaClient when a token
+        provider is configured — they can refresh.
+        """
+        if not self.token:
+            raise UploadError("No bearer token configured — call login() or pass token=.")
+        return {"Authorization": f"Bearer {self.token}"}
+
+    @property
+    def origin(self) -> str:
+        """Scheme+host of ``base_url`` — origin where core-auth endpoints live."""
+        parts = urlsplit(self.base_url)
+        if not parts.scheme or not parts.netloc:
+            raise MatildaError(
+                f'Auth flows require an absolute base URL (got "{self.base_url}"). '
+                'Pass an absolute URL like "https://matilda.example/api".'
+            )
+        return f"{parts.scheme}://{parts.netloc}"