matrx-api 0.1.0__py3-none-any.whl

matrx_api/__init__.py

@@ -0,0 +1,31 @@
+"""matrx-api: the Python client of every AI Matrx server, generated from the server contract."""
+
+from .client import (
+    ApiStream,
+    CallOptions,
+    JsonOrStream,
+    MatrxApi,
+    Multipart,
+    OperationDescriptor,
+    RequestInfo,
+)
+from .credentials import (
+    ApiKeyCredential,
+    GuestCredential,
+    MATRX_HEADERS,
+    ScopedCredential,
+    ServiceCredential,
+    UserCredential,
+    credential_to_headers,
+)
+from .deployments import CONTRACT_SHA256, DEPLOYMENTS, DOMAINS
+from .errors import MatrxApiError, OrganizationContextError
+from .streams import NdjsonFramer, SseFrame, SseFramer
+
+__all__ = [
+    "ApiKeyCredential", "ApiStream", "CONTRACT_SHA256", "CallOptions", "DEPLOYMENTS", "DOMAINS",
+    "GuestCredential", "JsonOrStream", "MATRX_HEADERS", "MatrxApi", "MatrxApiError", "Multipart",
+    "NdjsonFramer", "OperationDescriptor", "OrganizationContextError", "RequestInfo",
+    "ScopedCredential", "ServiceCredential", "SseFrame", "SseFramer", "UserCredential",
+    "credential_to_headers",
+]

matrx_api/client.py

@@ -0,0 +1,420 @@
+"""``MatrxApi`` - the ONE client of every AI Matrx server (Python sister of ``createApi``).
+
+Every generated operation hands this client a small :class:`OperationDescriptor` straight from the
+server contract (method, path template, deployment, auth tier, org rule, stream kind). The client owns the rest:
+
+- base URL per deployment (defaults from api-deployments.json, overridable per deployment);
+- the injected credentials (five kinds, ``credentials.py``), re-read on every call;
+- the organization binding, honouring each operation's ``x-matrx-org``: ``required`` is refused BEFORE
+  the wire when absent, ``optional`` sends one when bound, ``exempt`` never sends one;
+- ``X-Request-Id`` (unique per call);
+- reads (GET/HEAD) retry with backoff on transport failure; writes NEVER retry;
+- one error model (:class:`MatrxApiError`);
+- NDJSON / SSE / bytes streams as async iterators.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from collections.abc import AsyncIterator, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Generic, Literal, TypeVar
+
+import httpx
+
+from .credentials import MATRX_HEADERS, CredentialsSetting, credential_to_headers, resolve_credential
+from .deployments import DEPLOYMENTS
+from .errors import MatrxApiError, OrganizationContextError
+from .streams import NdjsonFramer, SseFramer, SseFrame
+
+Environment = Literal["production", "localhost"]
+StreamKind = Literal["none", "ndjson", "sse", "bytes", "ndjson_or_json", "sse_or_json", "bytes_or_json"]
+
+DEFAULT_CONNECT_TIMEOUT = 15.0
+E = TypeVar("E")
+J = TypeVar("J")
+
+
+@dataclass(frozen=True, slots=True)
+class OperationDescriptor:
+    method: str
+    path: str
+    deployment: str
+    auth: str
+    org: str
+    stream: str  # "none" or a StreamKind
+    name: str  # "<domain>.<op>"
+
+
+@dataclass(frozen=True, slots=True)
+class CallOptions:
+    organization_id: str | None = None
+    headers: Mapping[str, str] | None = None
+    connect_timeout: float | None = None
+    total_timeout: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Multipart:
+    """A multipart/form-data body (``data`` fields + ``files`` as httpx accepts them)."""
+
+    data: Mapping[str, Any] | None = None
+    files: Any = None
+
+
+@dataclass(frozen=True, slots=True)
+class RequestInfo:
+    operation: str
+    method: str
+    url: str
+    request_id: str
+    deployment: str
+
+
+def _interpolate(template: str, params: Mapping[str, Any] | None) -> str:
+    import re
+    from urllib.parse import quote
+
+    def sub(m: "re.Match[str]") -> str:
+        name = m.group(1)
+        value = (params or {}).get(name)
+        if value is None or str(value) == "":
+            raise TypeError(f'Missing path parameter "{name}" for {template}')
+        return quote(str(value), safe="")
+
+    return re.sub(r"\{([^}]+)\}", sub, template)
+
+
+def _query_pairs(query: Mapping[str, Any] | None) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    for key, raw in (query or {}).items():
+        if raw is None:
+            continue
+        for v in raw if isinstance(raw, (list, tuple)) else [raw]:
+            if v is None:
+                continue
+            if isinstance(v, bool):
+                out.append((key, "true" if v else "false"))
+            elif isinstance(v, (dict, list)):
+                out.append((key, json.dumps(v)))
+            else:
+                out.append((key, str(v)))
+    return out
+
+
+def _accept(stream: str) -> str:
+    return {
+        "ndjson": "application/x-ndjson",
+        "sse": "text/event-stream",
+        "ndjson_or_json": "application/x-ndjson, application/json",
+        "sse_or_json": "text/event-stream, application/json",
+        "bytes": "*/*",
+        "bytes_or_json": "*/*, application/json",
+    }.get(stream, "application/json")
+
+
+class ApiStream(Generic[E]):
+    """An open streaming response. Iterate with ``async for``; ``aclose()`` (or the context manager) releases it."""
+
+    def __init__(self, response: httpx.Response, request_id: str, kind: str) -> None:
+        self.response = response
+        self.request_id = request_id
+        self._kind = kind
+        self._started = False
+
+    async def _iterate(self) -> AsyncIterator[Any]:
+        try:
+            if self._kind.startswith("ndjson"):
+                nd = NdjsonFramer()
+                async for chunk in self.response.aiter_bytes():
+                    for frame in nd.push_bytes(chunk):
+                        yield frame
+                for frame in nd.finish():
+                    yield frame
+            elif self._kind.startswith("sse"):
+                sse = SseFramer()
+                async for chunk in self.response.aiter_bytes():
+                    for frame in sse.push_bytes(chunk):
+                        yield frame
+                for frame in sse.finish():
+                    yield frame
+            else:
+                async for chunk in self.response.aiter_bytes():
+                    yield chunk
+        except httpx.TransportError as exc:
+            raise MatrxApiError(status=0, path=str(self.response.url), message=f"stream interrupted: {exc}", code="network_error") from exc
+        finally:
+            await self.response.aclose()
+
+    def __aiter__(self) -> AsyncIterator[E]:
+        if self._started:
+            raise RuntimeError("an ApiStream can only be iterated once")
+        self._started = True
+        return self._iterate()
+
+    async def aclose(self) -> None:
+        await self.response.aclose()
+
+    async def __aenter__(self) -> "ApiStream[E]":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+@dataclass(frozen=True, slots=True)
+class JsonOrStream(Generic[J, E]):
+    """Conditional streams: ``kind`` is ``"json"`` (``data``) or ``"stream"`` (``stream``)."""
+
+    kind: Literal["json", "stream"]
+    data: J | None = None
+    stream: ApiStream[E] | None = None
+
+
+class MatrxApi:
+    def __init__(
+        self,
+        *,
+        credentials: CredentialsSetting = None,
+        organization_id: str | None | Callable[[], str | None] = None,
+        environment: Environment = "production",
+        base_urls: Mapping[str, str] | None = None,
+        resolve_base_url: Callable[[str, OperationDescriptor], str | None] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        total_timeout: float | None = None,
+        retry_attempts: int = 3,
+        retry_backoff: float = 0.25,
+        request_id: Callable[[], str] | None = None,
+        headers: Mapping[str, str] | None = None,
+        on_request: Callable[[RequestInfo], None] | None = None,
+        sleep: Callable[[float], Any] = asyncio.sleep,
+    ) -> None:
+        self._credentials = credentials
+        self._organization_id = organization_id
+        self._environment = environment
+        self._base_urls = dict(base_urls or {})
+        self._resolve_base_url = resolve_base_url
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(transport=transport, follow_redirects=False)
+        self._connect_timeout = connect_timeout
+        self._total_timeout = total_timeout
+        self._retry_attempts = max(1, retry_attempts)
+        self._retry_backoff = retry_backoff
+        self._mint_request_id = request_id or (lambda: str(uuid.uuid4()))
+        self._headers = dict(headers or {})
+        self._on_request = on_request
+        self._sleep = sleep
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "MatrxApi":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    # -- routing -----------------------------------------------------------------------------
+    def base_url(self, op: OperationDescriptor) -> str:
+        if self._resolve_base_url:
+            dynamic = self._resolve_base_url(op.deployment, op)
+            if dynamic:
+                return dynamic.rstrip("/")
+        override = self._base_urls.get(op.deployment)
+        if override:
+            return override.rstrip("/")
+        dep = DEPLOYMENTS[op.deployment]
+        fallback = dep["base_url"].get(self._environment)
+        if not fallback:
+            server_env = dep.get("env", {}).get("server")
+            raise ValueError(
+                f'matrx_api: no base URL for deployment "{op.deployment}" in {self._environment} '
+                f'(operation {op.name}). Pass MatrxApi(base_urls={{"{op.deployment}": "https://..."}})'
+                + (f" - servers read it from {server_env}." if server_env else ".")
+            )
+        return fallback
+
+    def url(self, op: OperationDescriptor, *, path: Mapping[str, Any] | None = None) -> str:
+        return f"{self.base_url(op)}{_interpolate(op.path, path)}"
+
+    def _organization_for(self, op: OperationDescriptor, options: CallOptions | None) -> str | None:
+        if op.org == "exempt":
+            return None
+        bound = self._organization_id() if callable(self._organization_id) else self._organization_id
+        selected = (options.organization_id if options and options.organization_id else None) or bound
+        if op.org == "required":
+            if not isinstance(selected, str) or not selected.strip():
+                raise OrganizationContextError(
+                    "organization_context_required", f"Select an organization before calling {op.name}."
+                )
+            normalized = selected.strip()
+            try:
+                uuid.UUID(normalized)
+            except ValueError:
+                raise OrganizationContextError(
+                    "organization_context_invalid", "The selected organization ID is invalid."
+                ) from None
+            return normalized.lower()
+        return selected.strip() if isinstance(selected, str) and selected.strip() else None
+
+    # -- send --------------------------------------------------------------------------------
+    async def _build(
+        self,
+        op: OperationDescriptor,
+        path: Mapping[str, Any] | None,
+        query: Mapping[str, Any] | None,
+        body: Any,
+        options: CallOptions | None,
+    ) -> tuple[httpx.Request, str]:
+        url = self.url(op, path=path)
+        org = self._organization_for(op, options)
+        request_id = self._mint_request_id()
+        headers: dict[str, str] = {
+            **self._headers,
+            **(options.headers if options and options.headers else {}),
+            "Accept": _accept(op.stream),
+        }
+        headers[MATRX_HEADERS["request_id"]] = request_id
+        content: Any = None
+        data: Any = None
+        files: Any = None
+        json_body: Any = None
+        if body is not None and op.method not in ("GET", "HEAD"):
+            if isinstance(body, Multipart):
+                data, files = body.data, body.files
+            elif isinstance(body, (bytes, bytearray)):
+                content = bytes(body)
+            elif isinstance(body, str):
+                content = body.encode()
+            else:
+                json_body = body
+        headers.update(credential_to_headers(await resolve_credential(self._credentials)))
+        if org is not None:
+            headers[MATRX_HEADERS["organization"]] = org
+        if self._on_request:
+            self._on_request(RequestInfo(op.name, op.method, url, request_id, op.deployment))
+        connect = options.connect_timeout if options and options.connect_timeout is not None else self._connect_timeout
+        total = options.total_timeout if options and options.total_timeout is not None else self._total_timeout
+        # streams are long-lived: only the connect phase is bounded unless a total is requested
+        timeout = httpx.Timeout(total, connect=connect)
+        request = self._client.build_request(
+            op.method,
+            url,
+            params=_query_pairs(query) or None,
+            headers=headers,
+            content=content,
+            data=data,
+            files=files,
+            json=json_body,
+            timeout=timeout,
+        )
+        return request, request_id
+
+    async def _error(self, response: httpx.Response, op: OperationDescriptor, path: Mapping[str, Any] | None) -> MatrxApiError:
+        try:
+            await response.aread()
+        except httpx.HTTPError:
+            pass
+        try:
+            text = response.text
+        except httpx.ResponseNotRead:
+            text = ""
+        try:
+            detail: Any = json.loads(text) if text else None
+        except ValueError:
+            detail = text or None
+        await response.aclose()
+        return MatrxApiError(status=response.status_code, path=_interpolate(op.path, path), server_detail=detail)
+
+    async def send(
+        self,
+        op: OperationDescriptor,
+        *,
+        path: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        options: CallOptions | None = None,
+        stream: bool = False,
+    ) -> tuple[httpx.Response, str]:
+        """Send one operation; raises :class:`MatrxApiError` on non-2xx or transport failure."""
+        idempotent = op.method in ("GET", "HEAD") and not stream
+        attempts = self._retry_attempts if idempotent else 1
+        last: httpx.TransportError | None = None
+        for attempt in range(attempts):
+            request, request_id = await self._build(op, path, query, body, options)
+            try:
+                response = await self._client.send(request, stream=stream)
+            except httpx.TransportError as exc:
+                last = exc
+                if attempt + 1 < attempts:
+                    await self._sleep(self._retry_backoff * (2**attempt))
+                    continue
+                raise MatrxApiError(
+                    status=0,
+                    path=_interpolate(op.path, path),
+                    message=f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__,
+                    code="network_error",
+                ) from exc
+            if response.status_code >= 400:
+                raise await self._error(response, op, path)
+            return response, request_id
+        raise AssertionError(last)  # pragma: no cover
+
+    async def call(
+        self,
+        op: OperationDescriptor,
+        *,
+        path: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        options: CallOptions | None = None,
+    ) -> Any:
+        """A plain JSON operation: the parsed body (None for 204/HEAD, text when not JSON)."""
+        response, _ = await self.send(op, path=path, query=query, body=body, options=options)
+        if response.status_code == 204 or op.method == "HEAD" or not response.content:
+            return None
+        if "json" in response.headers.get("content-type", ""):
+            return response.json()
+        try:
+            return json.loads(response.text)
+        except ValueError:
+            return response.text
+
+    async def raw(self, op: OperationDescriptor, **kwargs: Any) -> httpx.Response:
+        """The complete raw response (non-streamed bytes operations)."""
+        response, _ = await self.send(op, **kwargs)
+        return response
+
+    async def open_stream(
+        self,
+        op: OperationDescriptor,
+        *,
+        path: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        options: CallOptions | None = None,
+    ) -> ApiStream[Any]:
+        response, request_id = await self.send(op, path=path, query=query, body=body, options=options, stream=True)
+        return ApiStream(response, request_id, op.stream)
+
+    async def open_json_or_stream(
+        self,
+        op: OperationDescriptor,
+        *,
+        path: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        options: CallOptions | None = None,
+    ) -> JsonOrStream[Any, Any]:
+        response, request_id = await self.send(op, path=path, query=query, body=body, options=options, stream=True)
+        if "application/json" in response.headers.get("content-type", ""):
+            await response.aread()
+            data = response.json()
+            await response.aclose()
+            return JsonOrStream(kind="json", data=data)
+        return JsonOrStream(kind="stream", stream=ApiStream(response, request_id, op.stream))

matrx_api/credentials.py

@@ -0,0 +1,105 @@
+"""The credentials port: five kinds, one credential -> header mapping (mirrors @ai-matrx/auth credentials)."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Union
+
+MATRX_HEADERS = {
+    "authorization": "Authorization",
+    "fingerprint": "X-Fingerprint-ID",
+    "organization": "X-Organization-Id",
+    "acting_user": "X-Matrx-User-Id",
+    "request_id": "X-Request-Id",
+}
+
+API_KEY_PREFIX = "mx_"
+
+
+@dataclass(frozen=True)
+class UserCredential:
+    """A signed-in person: ``Authorization: Bearer <Supabase JWT>``."""
+
+    access_token: str
+
+
+@dataclass(frozen=True)
+class GuestCredential:
+    """A fingerprint: ``X-Fingerprint-ID``."""
+
+    fingerprint_id: str
+
+
+@dataclass(frozen=True)
+class ApiKeyCredential:
+    """An AI Matrx API key (``mx_...``) as a Bearer token."""
+
+    api_key: str
+
+
+@dataclass(frozen=True)
+class ServiceCredential:
+    """One of our servers calling another: the server secret (+ the acting person)."""
+
+    secret: str
+    acting_user_id: str | None = None
+    secret_header: str = "Authorization"
+
+
+@dataclass(frozen=True)
+class ScopedCredential:
+    """A short-lived capability token; hand a provider so it is re-read per call."""
+
+    token: str
+
+
+Credential = Union[UserCredential, GuestCredential, ApiKeyCredential, ServiceCredential, ScopedCredential]
+CredentialsSetting = Union[
+    Credential,
+    None,
+    Callable[[], Union[Credential, None, Awaitable[Union[Credential, None]]]],
+]
+
+
+def credential_to_headers(credential: Credential | None) -> dict[str, str]:
+    """The single place that knows which header each credential kind rides in."""
+    h = MATRX_HEADERS
+    match credential:
+        case None:
+            return {}
+        case UserCredential(access_token=t):
+            return {h["authorization"]: f"Bearer {t}"}
+        case GuestCredential(fingerprint_id=f):
+            return {h["fingerprint"]: f}
+        case ScopedCredential(token=t):
+            return {h["authorization"]: f"Bearer {t}"}
+        case ServiceCredential() as c:
+            if c.secret_header.lower() == "authorization":
+                out = {h["authorization"]: f"Bearer {c.secret}"}
+            else:
+                out = {c.secret_header: c.secret}
+            if c.acting_user_id:
+                out[h["acting_user"]] = c.acting_user_id
+            return out
+        case ApiKeyCredential(api_key=k):
+            if not k.startswith(API_KEY_PREFIX):
+                raise ValueError(
+                    f'credential_to_headers: an api_key credential must start with "{API_KEY_PREFIX}" '
+                    "(AI Matrx API keys look like mx_live_...)"
+                )
+            return {h["authorization"]: f"Bearer {k}"}
+    raise TypeError(f"unknown credential: {credential!r}")
+
+
+async def resolve_credential(setting: CredentialsSetting) -> Credential | None:
+    """A fixed credential, None, or a (sync/async) provider called on every request."""
+    if setting is None:
+        return None
+    if callable(setting):
+        value = setting()
+        if inspect.isawaitable(value):
+            value = await value
+        return value
+    return setting

matrx_api/deployments.py

@@ -0,0 +1,122 @@
+"""GENERATED by matrx-api scripts/generate.py from aidream/api-contract - never edit by hand."""
+
+CONTRACT_SHA256 = '7a09c07daad8cd41c7ae301d9ce90aace006a8f2d3a21dde98885807e5881da5'
+
+# Which deployment answers (api-deployments.json): default base URLs and the env names that override them.
+DEPLOYMENTS: dict[str, dict] = {
+    "aidream": {
+        "app": "aidream-main",
+        "base_url": {
+            "localhost": "http://localhost:8000",
+            "production": "https://server.app.matrxserver.com"
+        },
+        "env": {
+            "browser": "NEXT_PUBLIC_BACKEND_URL_PROD",
+            "sandbox_service_token": "AIDREAM_SANDBOX_SERVICE_TOKEN",
+            "server": "MATRX_AIDREAM_URL",
+            "service_token": "MATRX_AIDREAM_SERVICE_TOKEN"
+        }
+    },
+    "cloud-browser-streaming": {
+        "app": "cloud-browser-streaming",
+        "base_url": {},
+        "env": {}
+    },
+    "cloud-browser-worker": {
+        "app": "cloud-browser-worker",
+        "base_url": {},
+        "env": {}
+    },
+    "files": {
+        "app": "files-standalone",
+        "base_url": {
+            "localhost": "http://127.0.0.1:8090",
+            "production": "https://files.matrxserver.com"
+        },
+        "env": {
+            "browser": "NEXT_PUBLIC_FILES_URL",
+            "browser_local": "NEXT_PUBLIC_FILES_URL_LOCAL",
+            "server": "MATRX_FILES_URL"
+        }
+    },
+    "hosted-box": {
+        "app": "hosted-box",
+        "base_url": {},
+        "env": {}
+    },
+    "matrx-local": {
+        "app": "matrx-local",
+        "base_url": {
+            "localhost": "http://127.0.0.1:22140"
+        },
+        "env": {
+            "port_base": "MATRX_PORT_BASE"
+        }
+    },
+    "sandbox-orchestrator": {
+        "app": "sandbox-orchestrator",
+        "base_url": {
+            "production": "https://orchestrator.dev.codematrx.com"
+        },
+        "env": {
+            "server": "SANDBOX_ORCHESTRATOR_URL",
+            "service_token": "SANDBOX_ORCHESTRATOR_API_KEY"
+        }
+    },
+    "scraper": {
+        "app": "scraper-server",
+        "base_url": {
+            "localhost": "http://localhost:8001",
+            "production": "https://scraper.app.matrxserver.com"
+        },
+        "env": {
+            "browser": "NEXT_PUBLIC_SCRAPER_URL",
+            "browser_local": "NEXT_PUBLIC_SCRAPER_URL_LOCAL",
+            "server": "MATRX_SCRAPER_URL",
+            "service_token": "MATRX_SCRAPER_TOKEN"
+        }
+    },
+    "seo": {
+        "app": "seo-standalone",
+        "base_url": {
+            "localhost": "http://127.0.0.1:8081",
+            "production": "https://seo.matrxserver.com"
+        },
+        "env": {
+            "browser": "NEXT_PUBLIC_SEO_URL",
+            "browser_local": "NEXT_PUBLIC_SEO_URL_LOCAL"
+        }
+    }
+}
+
+# One generated module per x-matrx-domain (module name -> domain).
+DOMAINS: dict[str, str] = {
+    "account": "account",
+    "agents": "agents",
+    "ai": "ai",
+    "apps": "apps",
+    "architecture": "architecture",
+    "audio": "audio",
+    "chat": "chat",
+    "code": "code",
+    "commerce": "commerce",
+    "communications": "communications",
+    "computer": "computer",
+    "content": "content",
+    "crm": "crm",
+    "data": "data",
+    "education": "education",
+    "files": "files",
+    "human_resources": "human-resources",
+    "integrations": "integrations",
+    "intelligence": "intelligence",
+    "knowledge": "knowledge",
+    "legal": "legal",
+    "marketing": "marketing",
+    "masterwork": "masterwork",
+    "media": "media",
+    "platform": "platform",
+    "publish": "publish",
+    "web": "web",
+    "workflows": "workflows"
+}