modulex-python 0.1.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

modulex/__init__.py

@@ -4,19 +4,25 @@ from modulex._client import Modulex
 from modulex._exceptions import (
     AuthenticationError,
     BadRequestError,
+    BillingError,
     ConflictError,
+    CreditExhaustedError,
     ExternalServiceError,
     InternalError,
     ModulexError,
     NotFoundError,
+    PaymentRequiredError,
     PermissionError,
+    QuotaExceededError,
     RateLimitError,
     ServiceUnavailableError,
     StreamError,
     TimeoutError,
     ValidationError,
+    WalletError,
 )
 from modulex._streaming import SSEEvent
+from modulex._version import __version__
 
 __all__ = [
     "Modulex",
@@ -33,7 +39,11 @@ __all__ = [
     "ServiceUnavailableError",
     "StreamError",
     "TimeoutError",
+    "BillingError",
+    "PaymentRequiredError",
+    "QuotaExceededError",
+    "CreditExhaustedError",
+    "WalletError",
     "SSEEvent",
+    "__version__",
 ]
-
-__version__ = "0.1.0"

modulex/_base.py

@@ -14,6 +14,7 @@ from modulex._exceptions import (
     raise_for_status,
 )
 from modulex._streaming import EventSourceStream
+from modulex._version import __version__
 
 if TYPE_CHECKING:
     from modulex._client import Modulex
@@ -31,15 +32,29 @@ class _BaseResource:
             return organization_id
         return self._client._config.organization_id
 
-    def _build_headers(self, organization_id: str | None = None) -> dict[str, str]:
-        """Build request headers with auth and optional org context."""
+    def _build_headers(
+        self,
+        organization_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, str]:
+        """Build request headers with auth and optional org context.
+
+        User-supplied ``default_headers`` may override the User-Agent but never
+        the auth or content-type headers. ``idempotency_key`` (for mutating
+        requests) is sent as the ``Idempotency-Key`` header so the backend can
+        de-duplicate retried side-effectful operations.
+        """
         headers: dict[str, str] = {
+            "User-Agent": f"modulex-python/{__version__}",
+            **self._client._config.default_headers,
             "Authorization": f"Bearer {self._client._config.api_key}",
             "Content-Type": "application/json",
         }
         org_id = self._resolve_org_id(organization_id)
         if org_id:
             headers["X-Organization-ID"] = org_id
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
         return headers
 
     def _should_retry(self, method: str, status_code: int, attempt: int) -> bool:
@@ -69,11 +84,12 @@ class _BaseResource:
         params: dict[str, Any] | None = None,
         json: dict[str, Any] | None = None,
         organization_id: str | None = None,
+        idempotency_key: str | None = None,
         **kwargs: Any,
     ) -> Any:
         """Execute an HTTP request with retry logic."""
         url = f"{self._client._config.base_url}{path}"
-        headers = self._build_headers(organization_id)
+        headers = self._build_headers(organization_id, idempotency_key)
 
         # Filter None values from params
         if params:
@@ -191,17 +207,27 @@ class _BaseResource:
         *,
         method: str = "GET",
         organization_id: str | None = None,
+        json: dict[str, Any] | None = None,
+        include_heartbeats: bool = False,
         **kwargs: Any,
     ) -> EventSourceStream:
-        """Create an SSE stream connection."""
+        """Create an SSE stream connection.
+
+        For POST streams (e.g. credentials bulk), pass ``json=`` — the JSON
+        Content-Type is kept; for GET streams it is dropped.
+        """
         url = f"{self._client._config.base_url}{path}"
         headers = self._build_headers(organization_id)
-        headers.pop("Content-Type", None)
+        if json is not None:
+            kwargs["json"] = json
+        else:
+            headers.pop("Content-Type", None)
         return EventSourceStream(
             self._client._http,
             method,
             url,
             headers=headers,
+            include_heartbeats=include_heartbeats,
             timeout=httpx.Timeout(self._client._config.timeout, read=None),
             **kwargs,
         )
@@ -237,6 +263,20 @@ class _BaseResource:
 
         return response.json()
 
+    @staticmethod
+    def _unwrap_page(result: Any, items_key: str) -> tuple[list[Any], dict[str, Any]]:
+        """Return (items, container) handling a nested ``data.<items_key>`` envelope.
+
+        e.g. dashboard/logs returns ``{success, data: {logs, total_count, has_next}}``.
+        """
+        if not isinstance(result, dict):
+            return [], {}
+        container = result
+        if items_key not in result and isinstance(result.get("data"), dict):
+            container = result["data"]
+        items = container.get(items_key, [])
+        return (items if isinstance(items, list) else []), container
+
     async def _paginate(
         self,
         path: str,
@@ -245,37 +285,92 @@ class _BaseResource:
         params: dict[str, Any] | None = None,
         organization_id: str | None = None,
         page_size: int = 20,
+        style: str | None = None,
+        total_key: str | None = None,
         **kwargs: Any,
     ) -> AsyncIterator[dict[str, Any]]:
-        """Auto-paginate through a list endpoint."""
+        """Auto-paginate a list endpoint across the backend's three styles.
+
+        Styles (auto-detected from ``params`` unless ``style`` is given):
+          - ``"page"``   — page / page_size, terminates on total_pages | has_more | short page
+          - ``"offset"`` — limit / offset, terminates on has_next | has_more | total/total_count | short page
+          - ``"cursor"`` — cursor / next_cursor (e.g. assistant & composer chat lists)
+        """
         params = dict(params or {})
 
-        # Detect pagination style
-        if "page" in params or "page_size" in params:
-            # Page-based pagination
+        if style is None:
+            if "cursor" in params:
+                style = "cursor"
+            elif "page" in params or "page_size" in params:
+                style = "page"
+            else:
+                style = "offset"
+
+        if style == "cursor":
+            cursor = params.pop("cursor", None)
+            while True:
+                if cursor is not None:
+                    params["cursor"] = cursor
+                result = await self._get(path, params=params, organization_id=organization_id, **kwargs)
+                items, container = self._unwrap_page(result, items_key)
+                for item in items:
+                    yield item
+                cursor = container.get("next_cursor")
+                if not cursor or not items:
+                    break
+
+        elif style == "page":
             page = params.pop("page", 1)
             params["page_size"] = params.pop("page_size", page_size)
             while True:
                 params["page"] = page
                 result = await self._get(path, params=params, organization_id=organization_id, **kwargs)
-                items = result.get(items_key, [])
+                items, container = self._unwrap_page(result, items_key)
                 for item in items:
                     yield item
-                total_pages = result.get("total_pages", 1)
-                if page >= total_pages:
+                total_pages = container.get("total_pages")
+                has_more = container.get("has_more")
+                if total_pages is not None:
+                    if page >= total_pages:
+                        break
+                elif has_more is not None:
+                    if not has_more:
+                        break
+                elif len(items) < params["page_size"] or not items:
                     break
                 page += 1
-        else:
-            # Limit/offset pagination
+
+        else:  # offset
             offset = params.pop("offset", 0)
             limit = params.pop("limit", page_size)
             params["limit"] = limit
             while True:
                 params["offset"] = offset
                 result = await self._get(path, params=params, organization_id=organization_id, **kwargs)
-                items = result.get(items_key, [])
+                items, container = self._unwrap_page(result, items_key)
                 for item in items:
                     yield item
-                if not result.get("has_next", False) or len(items) < limit:
+                if not items:
                     break
+                if container.get("has_next") is not None:
+                    if not container["has_next"]:
+                        break
+                elif container.get("has_more") is not None:
+                    if not container["has_more"]:
+                        break
+                else:
+                    total = (
+                        container.get(total_key)
+                        if total_key
+                        else (
+                            container.get("total")
+                            if container.get("total") is not None
+                            else container.get("total_count")
+                        )
+                    )
+                    if total is not None:
+                        if offset + len(items) >= total:
+                            break
+                    elif len(items) < limit:
+                        break
                 offset += limit

modulex/_client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from typing import TYPE_CHECKING
 
 import httpx
@@ -10,6 +11,7 @@ from modulex._config import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEO
 
 if TYPE_CHECKING:
     from modulex.resources.api_keys import ApiKeys
+    from modulex.resources.assistant import Assistant
     from modulex.resources.auth import Auth
     from modulex.resources.chats import Chats
     from modulex.resources.composer import Composer
@@ -24,13 +26,15 @@ if TYPE_CHECKING:
     from modulex.resources.schedules import Schedules
     from modulex.resources.subscriptions import Subscriptions
     from modulex.resources.system import System
-    from modulex.resources.templates import Templates
     from modulex.resources.workflows import Workflows
 
 
 class Modulex:
     """Async client for the ModuleX API.
 
+    Configuration falls back to environment variables when arguments are omitted:
+    ``MODULEX_API_KEY``, ``MODULEX_BASE_URL``, ``MODULEX_ORGANIZATION_ID``.
+
     Usage:
         async with Modulex(api_key="mx_live_...") as client:
             me = await client.auth.me()
@@ -38,19 +42,27 @@ class Modulex:
 
     def __init__(
         self,
-        api_key: str,
+        api_key: str | None = None,
         *,
         organization_id: str | None = None,
-        base_url: str = DEFAULT_BASE_URL,
+        base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: dict[str, str] | None = None,
     ) -> None:
+        api_key = api_key or os.environ.get("MODULEX_API_KEY")
+        if not api_key:
+            raise ValueError("api_key is required: pass api_key=... or set the MODULEX_API_KEY environment variable")
+        base_url = base_url or os.environ.get("MODULEX_BASE_URL") or DEFAULT_BASE_URL
+        organization_id = organization_id or os.environ.get("MODULEX_ORGANIZATION_ID")
+
         self._config = ClientConfig(
             api_key=api_key,
             organization_id=organization_id,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
+            default_headers=default_headers or {},
         )
         self._http = httpx.AsyncClient()
 
@@ -64,8 +76,8 @@ class Modulex:
         self._integrations: object | None = None
         self._knowledge: object | None = None
         self._schedules: object | None = None
-        self._templates: object | None = None
         self._composer: object | None = None
+        self._assistant: object | None = None
         self._dashboard: object | None = None
         self._subscriptions: object | None = None
         self._notifications: object | None = None
@@ -164,15 +176,6 @@ class Modulex:
             self._schedules = Schedules(self)
         return self._schedules  # type: ignore[return-value]
 
-    @property
-    def templates(self) -> Templates:
-        """Access template endpoints."""
-        if self._templates is None:
-            from modulex.resources.templates import Templates
-
-            self._templates = Templates(self)
-        return self._templates  # type: ignore[return-value]
-
     @property
     def composer(self) -> Composer:
         """Access composer endpoints."""
@@ -182,6 +185,15 @@ class Modulex:
             self._composer = Composer(self)
         return self._composer  # type: ignore[return-value]
 
+    @property
+    def assistant(self) -> Assistant:
+        """Access assistant (agentic chat) endpoints."""
+        if self._assistant is None:
+            from modulex.resources.assistant import Assistant
+
+            self._assistant = Assistant(self)
+        return self._assistant  # type: ignore[return-value]
+
     @property
     def dashboard(self) -> Dashboard:
         """Access dashboard endpoints."""

modulex/_exceptions.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from email.utils import parsedate_to_datetime
 from typing import Any
 
 import httpx
@@ -50,7 +51,11 @@ class ConflictError(ModulexError):
 
 
 class RateLimitError(ModulexError):
-    """Raised when rate limited (429)."""
+    """Raised when rate limited (429).
+
+    Carries the rate-limit headers the backend sends (``X-RateLimit-*`` and
+    ``Retry-After``) so callers can back off intelligently.
+    """
 
     def __init__(
         self,
@@ -60,9 +65,15 @@ class RateLimitError(ModulexError):
         response: httpx.Response | None = None,
         body: Any = None,
         retry_after: float | None = None,
+        limit: int | None = None,
+        remaining: int | None = None,
+        reset: float | None = None,
     ) -> None:
         super().__init__(message, status_code=status_code, response=response, body=body)
         self.retry_after = retry_after
+        self.limit = limit
+        self.remaining = remaining
+        self.reset = reset
 
 
 class InternalError(ModulexError):
@@ -85,9 +96,61 @@ class TimeoutError(ModulexError):
     """Raised when a request times out."""
 
 
+class BillingError(ModulexError):
+    """Base class for billing / quota / credit / wallet denials.
+
+    The ModuleX backend returns a *structured denial envelope* (top-level, NOT
+    under ``detail``) for usage gating: ``{code, layer, key, current, limit, reason}``.
+    The ``layer`` determines the HTTP status (quota -> 403, rate -> 429,
+    credit/wallet -> 402). This class surfaces those fields structurally instead
+    of collapsing them into an opaque message.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response: httpx.Response | None = None,
+        body: Any = None,
+        code: str | None = None,
+        layer: str | None = None,
+        key: str | None = None,
+        current: float | int | None = None,
+        limit: float | int | None = None,
+        reason: str | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response=response, body=body)
+        self.code = code
+        self.layer = layer
+        self.key = key
+        self.current = current
+        self.limit = limit
+        self.reason = reason
+        self.retry_after = retry_after
+
+
+class PaymentRequiredError(BillingError):
+    """Raised for payment-required denials (402) without a structured envelope."""
+
+
+class QuotaExceededError(BillingError):
+    """Raised when a usage quota is exceeded (layer="quota", HTTP 403)."""
+
+
+class CreditExhaustedError(BillingError):
+    """Raised when the credit plan is exhausted (layer="credit", HTTP 402)."""
+
+
+class WalletError(BillingError):
+    """Raised for wallet overage denials (layer="wallet", HTTP 402)."""
+
+
 _STATUS_CODE_MAP: dict[int, type[ModulexError]] = {
     400: BadRequestError,
     401: AuthenticationError,
+    402: PaymentRequiredError,
     403: PermissionError,
     404: NotFoundError,
     409: ConflictError,
@@ -98,8 +161,78 @@ _STATUS_CODE_MAP: dict[int, type[ModulexError]] = {
     503: ServiceUnavailableError,
 }
 
+# Map the backend denial ``layer`` to a specific BillingError subclass.
+_BILLING_LAYER_MAP: dict[str, type[BillingError]] = {
+    "quota": QuotaExceededError,
+    "credit": CreditExhaustedError,
+    "wallet": WalletError,
+}
+
 RETRYABLE_STATUS_CODES = {429, 500, 502, 503}
 
+# Statuses that may carry a structured billing/usage denial envelope.
+_DENIAL_STATUSES = {402, 403, 429}
+_DENIAL_KEYS = ("code", "layer", "reason")
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Parse a ``Retry-After`` header (delay-seconds OR an HTTP-date)."""
+    if not value:
+        return None
+    value = value.strip()
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    try:
+        from datetime import datetime, timezone
+
+        dt = parsedate_to_datetime(value)
+        if dt is None:
+            return None
+        delta = (dt - datetime.now(timezone.utc)).total_seconds()
+        return max(delta, 0.0)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_rate_headers(response: httpx.Response) -> tuple[int | None, int | None, float | None]:
+    """Read ``X-RateLimit-Limit/Remaining/Reset`` headers (best-effort)."""
+
+    def _as_int(name: str) -> int | None:
+        raw = response.headers.get(name)
+        try:
+            return int(raw) if raw is not None else None
+        except ValueError:
+            return None
+
+    reset_raw = response.headers.get("X-RateLimit-Reset")
+    try:
+        reset = float(reset_raw) if reset_raw is not None else None
+    except ValueError:
+        reset = None
+    return _as_int("X-RateLimit-Limit"), _as_int("X-RateLimit-Remaining"), reset
+
+
+def _extract_denial_envelope(body: Any) -> dict[str, Any] | None:
+    """Return the structured denial envelope if present.
+
+    Tolerates three shapes (mirrors the UI's ``billing-error.ts:extractEnvelope``):
+      - top-level ``{code, layer, ...}``
+      - ``{"detail": {code, layer, ...}}`` (FastAPI-wrapped dict detail)
+      - a bare ``{"reason": ...}`` top-level dict
+    """
+    candidates = []
+    if isinstance(body, dict):
+        candidates.append(body)
+        detail = body.get("detail")
+        if isinstance(detail, dict):
+            candidates.append(detail)
+    for candidate in candidates:
+        if any(k in candidate for k in _DENIAL_KEYS):
+            return candidate
+    return None
+
 
 def raise_for_status(response: httpx.Response) -> None:
     """Raise an appropriate exception for error HTTP status codes."""
@@ -111,21 +244,52 @@ def raise_for_status(response: httpx.Response) -> None:
     except Exception:
         body = {"detail": response.text}
 
+    status = response.status_code
+
+    # 1) Structured billing/usage denial envelope (402/403/429) — surface fields.
+    if status in _DENIAL_STATUSES:
+        envelope = _extract_denial_envelope(body)
+        if envelope is not None:
+            layer = envelope.get("layer")
+            reason = envelope.get("reason")
+            code = envelope.get("code")
+            message = reason or code or "Request denied by usage gate"
+            retry_after = parse_retry_after(response.headers.get("Retry-After"))
+            exc_cls = _BILLING_LAYER_MAP.get(layer or "", BillingError)
+            raise exc_cls(
+                str(message),
+                status_code=status,
+                response=response,
+                body=body,
+                code=code,
+                layer=layer,
+                key=envelope.get("key"),
+                current=envelope.get("current"),
+                limit=envelope.get("limit"),
+                reason=reason,
+                retry_after=retry_after,
+            )
+
+    # 2) Standard error mapping.
     detail = body.get("detail", response.text) if isinstance(body, dict) else str(body)
-    if isinstance(detail, list):
-        detail = "; ".join(item.get("msg", str(item)) for item in detail)
+    if isinstance(detail, list):  # FastAPI 422 validation errors
+        detail = "; ".join(item.get("msg", str(item)) if isinstance(item, dict) else str(item) for item in detail)
+    elif isinstance(detail, dict):  # org-member 429 dict-detail (non-envelope)
+        detail = detail.get("reason") or detail.get("message") or detail.get("code") or str(detail)
 
-    exc_class = _STATUS_CODE_MAP.get(response.status_code, ModulexError)
+    exc_class = _STATUS_CODE_MAP.get(status, ModulexError)
 
     kwargs: dict[str, Any] = {
-        "status_code": response.status_code,
+        "status_code": status,
         "response": response,
         "body": body,
     }
 
     if exc_class is RateLimitError:
-        retry_after_header = response.headers.get("Retry-After")
-        retry_after = float(retry_after_header) if retry_after_header else None
-        kwargs["retry_after"] = retry_after
+        kwargs["retry_after"] = parse_retry_after(response.headers.get("Retry-After"))
+        limit, remaining, reset = _parse_rate_headers(response)
+        kwargs["limit"] = limit
+        kwargs["remaining"] = remaining
+        kwargs["reset"] = reset
 
     raise exc_class(str(detail), **kwargs)