modulex-python 0.1.0__py3-none-any.whl

modulex/__init__.py

@@ -0,0 +1,39 @@
+"""ModuleX Python SDK — Official client for the ModuleX AI workflow orchestration platform."""
+
+from modulex._client import Modulex
+from modulex._exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    ExternalServiceError,
+    InternalError,
+    ModulexError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServiceUnavailableError,
+    StreamError,
+    TimeoutError,
+    ValidationError,
+)
+from modulex._streaming import SSEEvent
+
+__all__ = [
+    "Modulex",
+    "ModulexError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "BadRequestError",
+    "ValidationError",
+    "ConflictError",
+    "RateLimitError",
+    "InternalError",
+    "ExternalServiceError",
+    "ServiceUnavailableError",
+    "StreamError",
+    "TimeoutError",
+    "SSEEvent",
+]
+
+__version__ = "0.1.0"

modulex/_base.py

@@ -0,0 +1,281 @@
+"""Base resource class with HTTP methods, retry logic, and error handling."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from modulex._exceptions import (
+    RETRYABLE_STATUS_CODES,
+    TimeoutError,
+    raise_for_status,
+)
+from modulex._streaming import EventSourceStream
+
+if TYPE_CHECKING:
+    from modulex._client import Modulex
+
+
+class _BaseResource:
+    """Base class for all API resource classes."""
+
+    def __init__(self, client: Modulex) -> None:
+        self._client = client
+
+    def _resolve_org_id(self, organization_id: str | None) -> str | None:
+        """Resolve organization ID: per-request > client default > None."""
+        if organization_id is not None:
+            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."""
+        headers: dict[str, str] = {
+            "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
+        return headers
+
+    def _should_retry(self, method: str, status_code: int, attempt: int) -> bool:
+        """Determine if a request should be retried."""
+        if attempt >= self._client._config.max_retries:
+            return False
+        if status_code not in RETRYABLE_STATUS_CODES:
+            return False
+        if method.upper() not in ("GET", "HEAD"):
+            return False
+        return True
+
+    @staticmethod
+    def _backoff_delay(attempt: int, retry_after: float | None = None) -> float:
+        """Calculate backoff delay with jitter."""
+        if retry_after is not None:
+            return retry_after
+        base = 0.5
+        delay: float = min(base * (2**attempt) + random.random() * 0.5, 30.0)
+        return delay
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        organization_id: 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)
+
+        # Filter None values from params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        last_exc: Exception | None = None
+        for attempt in range(self._client._config.max_retries + 1):
+            try:
+                response = await self._client._http.request(
+                    method,
+                    url,
+                    headers=headers,
+                    params=params,
+                    json=json,
+                    timeout=self._client._config.timeout,
+                    **kwargs,
+                )
+            except httpx.TimeoutException as e:
+                if attempt < self._client._config.max_retries and method.upper() in ("GET", "HEAD"):
+                    last_exc = e
+                    import asyncio
+
+                    await asyncio.sleep(self._backoff_delay(attempt))
+                    continue
+                raise TimeoutError(f"Request timed out: {e}") from e
+
+            if response.status_code < 400:
+                if response.status_code == 204:
+                    return None
+                content_type = response.headers.get("content-type", "")
+                if "application/json" in content_type:
+                    return response.json()
+                try:
+                    return response.json()
+                except Exception:
+                    return response.text
+
+            if self._should_retry(method, response.status_code, attempt):
+                retry_after: float | None = None
+                if response.status_code == 429:
+                    retry_after_header = response.headers.get("Retry-After")
+                    if retry_after_header:
+                        retry_after = float(retry_after_header)
+
+                import asyncio
+
+                await asyncio.sleep(self._backoff_delay(attempt, retry_after))
+                continue
+
+            raise_for_status(response)
+
+        if last_exc:
+            raise TimeoutError(f"Request timed out after {self._client._config.max_retries} retries") from last_exc
+        raise_for_status(response)
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a GET request."""
+        return await self._request("GET", path, params=params, organization_id=organization_id, **kwargs)
+
+    async def _post(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a POST request."""
+        return await self._request("POST", path, json=json, organization_id=organization_id, **kwargs)
+
+    async def _put(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a PUT request."""
+        return await self._request("PUT", path, json=json, organization_id=organization_id, **kwargs)
+
+    async def _patch(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a PATCH request."""
+        return await self._request("PATCH", path, json=json, organization_id=organization_id, **kwargs)
+
+    async def _delete(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a DELETE request."""
+        return await self._request("DELETE", path, params=params, json=json, organization_id=organization_id, **kwargs)
+
+    def _stream_sse(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> EventSourceStream:
+        """Create an SSE stream connection."""
+        url = f"{self._client._config.base_url}{path}"
+        headers = self._build_headers(organization_id)
+        headers.pop("Content-Type", None)
+        return EventSourceStream(
+            self._client._http,
+            method,
+            url,
+            headers=headers,
+            timeout=httpx.Timeout(self._client._config.timeout, read=None),
+            **kwargs,
+        )
+
+    async def _upload(
+        self,
+        path: str,
+        *,
+        file: Any,
+        filename: str,
+        data: dict[str, str] | None = None,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a multipart file upload."""
+        url = f"{self._client._config.base_url}{path}"
+        headers = self._build_headers(organization_id)
+        headers.pop("Content-Type", None)
+
+        files = {"file": (filename, file)}
+
+        response = await self._client._http.post(
+            url,
+            headers=headers,
+            files=files,
+            data=data,
+            timeout=self._client._config.timeout,
+            **kwargs,
+        )
+
+        if response.status_code >= 400:
+            raise_for_status(response)
+
+        return response.json()
+
+    async def _paginate(
+        self,
+        path: str,
+        *,
+        items_key: str = "items",
+        params: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+        page_size: int = 20,
+        **kwargs: Any,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Auto-paginate through a list endpoint."""
+        params = dict(params or {})
+
+        # Detect pagination style
+        if "page" in params or "page_size" in params:
+            # Page-based pagination
+            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, [])
+                for item in items:
+                    yield item
+                total_pages = result.get("total_pages", 1)
+                if page >= total_pages:
+                    break
+                page += 1
+        else:
+            # Limit/offset pagination
+            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, [])
+                for item in items:
+                    yield item
+                if not result.get("has_next", False) or len(items) < limit:
+                    break
+                offset += limit

modulex/_client.py

@@ -0,0 +1,237 @@
+"""Main ModuleX client class."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+
+from modulex._config import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, ClientConfig
+
+if TYPE_CHECKING:
+    from modulex.resources.api_keys import ApiKeys
+    from modulex.resources.auth import Auth
+    from modulex.resources.chats import Chats
+    from modulex.resources.composer import Composer
+    from modulex.resources.credentials import Credentials
+    from modulex.resources.dashboard import Dashboard
+    from modulex.resources.deployments import Deployments
+    from modulex.resources.executions import Executions
+    from modulex.resources.integrations import Integrations
+    from modulex.resources.knowledge import Knowledge
+    from modulex.resources.notifications import Notifications
+    from modulex.resources.organizations import Organizations
+    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.
+
+    Usage:
+        async with Modulex(api_key="mx_live_...") as client:
+            me = await client.auth.me()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        organization_id: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._config = ClientConfig(
+            api_key=api_key,
+            organization_id=organization_id,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = httpx.AsyncClient()
+
+        # Lazy resource cache
+        self._auth: object | None = None
+        self._workflows: object | None = None
+        self._executions: object | None = None
+        self._deployments: object | None = None
+        self._chats: object | None = None
+        self._credentials: object | None = None
+        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._dashboard: object | None = None
+        self._subscriptions: object | None = None
+        self._notifications: object | None = None
+        self._api_keys: object | None = None
+        self._system: object | None = None
+        self._organizations: object | None = None
+
+    async def __aenter__(self) -> Modulex:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._http.aclose()
+
+    @property
+    def auth(self) -> Auth:
+        """Access auth endpoints."""
+        if self._auth is None:
+            from modulex.resources.auth import Auth
+
+            self._auth = Auth(self)
+        return self._auth  # type: ignore[return-value]
+
+    @property
+    def workflows(self) -> Workflows:
+        """Access workflow endpoints."""
+        if self._workflows is None:
+            from modulex.resources.workflows import Workflows
+
+            self._workflows = Workflows(self)
+        return self._workflows  # type: ignore[return-value]
+
+    @property
+    def executions(self) -> Executions:
+        """Access execution endpoints."""
+        if self._executions is None:
+            from modulex.resources.executions import Executions
+
+            self._executions = Executions(self)
+        return self._executions  # type: ignore[return-value]
+
+    @property
+    def deployments(self) -> Deployments:
+        """Access deployment endpoints."""
+        if self._deployments is None:
+            from modulex.resources.deployments import Deployments
+
+            self._deployments = Deployments(self)
+        return self._deployments  # type: ignore[return-value]
+
+    @property
+    def chats(self) -> Chats:
+        """Access chat endpoints."""
+        if self._chats is None:
+            from modulex.resources.chats import Chats
+
+            self._chats = Chats(self)
+        return self._chats  # type: ignore[return-value]
+
+    @property
+    def credentials(self) -> Credentials:
+        """Access credential endpoints."""
+        if self._credentials is None:
+            from modulex.resources.credentials import Credentials
+
+            self._credentials = Credentials(self)
+        return self._credentials  # type: ignore[return-value]
+
+    @property
+    def integrations(self) -> Integrations:
+        """Access integration endpoints."""
+        if self._integrations is None:
+            from modulex.resources.integrations import Integrations
+
+            self._integrations = Integrations(self)
+        return self._integrations  # type: ignore[return-value]
+
+    @property
+    def knowledge(self) -> Knowledge:
+        """Access knowledge base endpoints."""
+        if self._knowledge is None:
+            from modulex.resources.knowledge import Knowledge
+
+            self._knowledge = Knowledge(self)
+        return self._knowledge  # type: ignore[return-value]
+
+    @property
+    def schedules(self) -> Schedules:
+        """Access schedule endpoints."""
+        if self._schedules is None:
+            from modulex.resources.schedules import Schedules
+
+            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."""
+        if self._composer is None:
+            from modulex.resources.composer import Composer
+
+            self._composer = Composer(self)
+        return self._composer  # type: ignore[return-value]
+
+    @property
+    def dashboard(self) -> Dashboard:
+        """Access dashboard endpoints."""
+        if self._dashboard is None:
+            from modulex.resources.dashboard import Dashboard
+
+            self._dashboard = Dashboard(self)
+        return self._dashboard  # type: ignore[return-value]
+
+    @property
+    def subscriptions(self) -> Subscriptions:
+        """Access subscription endpoints."""
+        if self._subscriptions is None:
+            from modulex.resources.subscriptions import Subscriptions
+
+            self._subscriptions = Subscriptions(self)
+        return self._subscriptions  # type: ignore[return-value]
+
+    @property
+    def notifications(self) -> Notifications:
+        """Access notification endpoints."""
+        if self._notifications is None:
+            from modulex.resources.notifications import Notifications
+
+            self._notifications = Notifications(self)
+        return self._notifications  # type: ignore[return-value]
+
+    @property
+    def api_keys(self) -> ApiKeys:
+        """Access API key endpoints."""
+        if self._api_keys is None:
+            from modulex.resources.api_keys import ApiKeys
+
+            self._api_keys = ApiKeys(self)
+        return self._api_keys  # type: ignore[return-value]
+
+    @property
+    def system(self) -> System:
+        """Access system endpoints."""
+        if self._system is None:
+            from modulex.resources.system import System
+
+            self._system = System(self)
+        return self._system  # type: ignore[return-value]
+
+    @property
+    def organizations(self) -> Organizations:
+        """Access organization endpoints."""
+        if self._organizations is None:
+            from modulex.resources.organizations import Organizations
+
+            self._organizations = Organizations(self)
+        return self._organizations  # type: ignore[return-value]

modulex/_compat.py

@@ -0,0 +1,39 @@
+"""Synchronous compatibility wrapper for the ModuleX async client."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def _get_or_create_event_loop() -> asyncio.AbstractEventLoop:
+    """Get the current event loop or create a new one."""
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_closed():
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        return loop
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        return loop
+
+
+def run_sync(coro: Any) -> Any:
+    """Run an async coroutine synchronously."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(asyncio.run, coro)
+            return future.result()
+    else:
+        return asyncio.run(coro)

modulex/_config.py

@@ -0,0 +1,26 @@
+"""Client configuration for the ModuleX SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+DEFAULT_BASE_URL = "https://api.modulex.dev"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+
+@dataclass
+class ClientConfig:
+    """Configuration for the ModuleX client."""
+
+    api_key: str
+    organization_id: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    default_headers: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.base_url = self.base_url.rstrip("/")
+        if not self.api_key:
+            raise ValueError("api_key is required")