modulex-python 0.1.0__py3-none-any.whl

modulex/_exceptions.py

@@ -0,0 +1,131 @@
+"""Exception classes for the ModuleX SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class ModulexError(Exception):
+    """Base exception for all ModuleX SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response: httpx.Response | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        self.body = body
+
+
+class AuthenticationError(ModulexError):
+    """Raised when authentication fails (401)."""
+
+
+class PermissionError(ModulexError):
+    """Raised when the user lacks permissions (403)."""
+
+
+class NotFoundError(ModulexError):
+    """Raised when a resource is not found (404)."""
+
+
+class BadRequestError(ModulexError):
+    """Raised for malformed requests (400)."""
+
+
+class ValidationError(ModulexError):
+    """Raised for validation errors (422)."""
+
+
+class ConflictError(ModulexError):
+    """Raised for resource conflicts (409)."""
+
+
+class RateLimitError(ModulexError):
+    """Raised when rate limited (429)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = 429,
+        response: httpx.Response | None = None,
+        body: Any = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response=response, body=body)
+        self.retry_after = retry_after
+
+
+class InternalError(ModulexError):
+    """Raised for internal server errors (500)."""
+
+
+class ExternalServiceError(ModulexError):
+    """Raised for external service errors (502)."""
+
+
+class ServiceUnavailableError(ModulexError):
+    """Raised when the service is unavailable (503)."""
+
+
+class StreamError(ModulexError):
+    """Raised for SSE stream errors."""
+
+
+class TimeoutError(ModulexError):
+    """Raised when a request times out."""
+
+
+_STATUS_CODE_MAP: dict[int, type[ModulexError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+    500: InternalError,
+    502: ExternalServiceError,
+    503: ServiceUnavailableError,
+}
+
+RETRYABLE_STATUS_CODES = {429, 500, 502, 503}
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Raise an appropriate exception for error HTTP status codes."""
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {"detail": response.text}
+
+    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)
+
+    exc_class = _STATUS_CODE_MAP.get(response.status_code, ModulexError)
+
+    kwargs: dict[str, Any] = {
+        "status_code": response.status_code,
+        "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
+
+    raise exc_class(str(detail), **kwargs)

modulex/_streaming.py

@@ -0,0 +1,118 @@
+"""SSE streaming support for the ModuleX SDK."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from httpx_sse import aconnect_sse
+
+from modulex._exceptions import StreamError
+
+
+@dataclass
+class SSEEvent:
+    """A Server-Sent Event."""
+
+    event: str
+    data: dict[str, Any]
+    id: str | None = None
+    retry: int | None = None
+
+
+class SSEStream:
+    """Async iterator for Server-Sent Events streams."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self._response = response
+        self._closed = False
+
+    def __aiter__(self) -> AsyncIterator[SSEEvent]:
+        return self._iterate()
+
+    async def _iterate(self) -> AsyncIterator[SSEEvent]:
+        """Iterate over SSE events from the response."""
+        try:
+            async for line in self._response.aiter_lines():
+                if self._closed:
+                    break
+
+                line = line.strip()
+                if not line or line.startswith(":"):
+                    continue
+
+                event = self._parse_event(line)
+                if event and event.event != "keepalive":
+                    yield event
+        except httpx.StreamClosed:
+            return
+        except Exception as e:
+            if not self._closed:
+                raise StreamError(f"SSE stream error: {e}") from e
+
+    @staticmethod
+    def _parse_event(line: str) -> SSEEvent | None:
+        """Parse a single SSE line into an event."""
+        if line.startswith("data:"):
+            data_str = line[5:].strip()
+            try:
+                data = json.loads(data_str)
+            except json.JSONDecodeError:
+                data = {"raw": data_str}
+            return SSEEvent(event="message", data=data)
+        return None
+
+    async def close(self) -> None:
+        """Close the SSE stream."""
+        self._closed = True
+        await self._response.aclose()
+
+
+class EventSourceStream:
+    """Full SSE parser that handles multi-line event blocks."""
+
+    def __init__(self, client: httpx.AsyncClient, method: str, url: str, **kwargs: Any) -> None:
+        self._client = client
+        self._method = method
+        self._url = url
+        self._kwargs = kwargs
+        self._closed = False
+
+    def __aiter__(self) -> AsyncIterator[SSEEvent]:
+        return self._iterate()
+
+    async def _iterate(self) -> AsyncIterator[SSEEvent]:
+        """Connect and iterate over SSE events."""
+        try:
+            async with aconnect_sse(self._client, self._method, self._url, **self._kwargs) as event_source:
+                async for sse in event_source.aiter_sse():
+                    if self._closed:
+                        break
+
+                    event_type = sse.event or "message"
+                    if event_type == "keepalive":
+                        continue
+
+                    try:
+                        data = json.loads(sse.data) if sse.data else {}
+                    except json.JSONDecodeError:
+                        data = {"raw": sse.data}
+
+                    yield SSEEvent(
+                        event=event_type,
+                        data=data,
+                        id=sse.id,
+                        retry=sse.retry,
+                    )
+        except httpx.StreamClosed:
+            return
+        except Exception as e:
+            if not self._closed:
+                raise StreamError(f"SSE stream error: {e}") from e
+
+    async def close(self) -> None:
+        """Close the SSE stream."""
+        self._closed = True

modulex/resources/__init__.py

@@ -0,0 +1 @@
+# Resources package for the ModuleX Python SDK.

modulex/resources/api_keys.py

@@ -0,0 +1,39 @@
+"""ApiKeys resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class ApiKeys(_BaseResource):
+    """Resource for managing API keys."""
+
+    async def create(
+        self,
+        name: str,
+        *,
+        organization_id: str | None = None,
+        expires_at: str | None = None,
+        rate_limit_per_minute: int = 60,
+    ) -> Any:
+        """Create a new API key with the given name and options."""
+        body: dict[str, Any] = {"name": name, "rate_limit_per_minute": rate_limit_per_minute}
+        if organization_id is not None:
+            body["organization_id"] = organization_id
+        if expires_at is not None:
+            body["expires_at"] = expires_at
+        return await self._post("/api-keys", json=body)
+
+    async def list(self, *, include_revoked: bool = False) -> Any:
+        """Return all API keys, optionally including revoked ones."""
+        return await self._get("/api-keys", params={"include_revoked": include_revoked})
+
+    async def get(self, key_id: str) -> Any:
+        """Return a single API key by its ID."""
+        return await self._get(f"/api-keys/{key_id}")
+
+    async def revoke(self, key_id: str) -> Any:
+        """Revoke an API key by its ID."""
+        return await self._delete(f"/api-keys/{key_id}")

modulex/resources/auth.py

@@ -0,0 +1,38 @@
+"""Auth resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class Auth(_BaseResource):
+    """Resource for authentication and identity endpoints."""
+
+    async def me(self) -> Any:
+        """Return the currently authenticated user's profile."""
+        return await self._get("/auth/me")
+
+    async def organizations(self, *, role: str | None = None) -> Any:
+        """Return organizations the current user belongs to, optionally filtered by role."""
+        params: dict[str, Any] = {}
+        if role is not None:
+            params["role"] = role
+        return await self._get("/auth/me/organizations", params=params or None)
+
+    async def invitations(self) -> Any:
+        """Return all pending invitations for the current user."""
+        return await self._get("/auth/invitations/my")
+
+    async def accept_invitation(self, invitation_id: str) -> Any:
+        """Accept a pending organization invitation by its ID."""
+        return await self._post(f"/auth/invitations/{invitation_id}/accept")
+
+    async def reject_invitation(self, invitation_id: str) -> Any:
+        """Reject a pending organization invitation by its ID."""
+        return await self._post(f"/auth/invitations/{invitation_id}/reject")
+
+    async def leave_organization(self, *, organization_id: str | None = None) -> Any:
+        """Leave the organization identified by the organization_id header."""
+        return await self._post("/auth/organizations/leave", organization_id=organization_id)

modulex/resources/chats.py

@@ -0,0 +1,62 @@
+"""Chats resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+from modulex._streaming import EventSourceStream
+
+
+class Chats(_BaseResource):
+    """Resource for managing chat sessions and their messages."""
+
+    async def list(self, *, organization_id: str | None = None) -> Any:
+        """Return all chat sessions for the current user or organization."""
+        return await self._get("/chats", organization_id=organization_id)
+
+    async def get(self, chat_id: str, *, organization_id: str | None = None) -> Any:
+        """Return a single chat session by its ID."""
+        return await self._get(f"/chats/{chat_id}", organization_id=organization_id)
+
+    async def messages(
+        self,
+        chat_id: str,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return a paginated list of messages for a chat session."""
+        return await self._get(
+            f"/chats/{chat_id}/messages",
+            params={"limit": limit, "offset": offset},
+            organization_id=organization_id,
+        )
+
+    async def update(
+        self,
+        chat_id: str,
+        *,
+        title: str | None = None,
+        is_private: bool | None = None,
+        folder: str | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Update metadata for a chat session such as title, privacy, or folder."""
+        body: dict[str, Any] = {}
+        if title is not None:
+            body["title"] = title
+        if is_private is not None:
+            body["is_private"] = is_private
+        if folder is not None:
+            body["folder"] = folder
+        return await self._patch(f"/chats/{chat_id}", json=body or None, organization_id=organization_id)
+
+    async def delete(self, chat_id: str, *, organization_id: str | None = None) -> Any:
+        """Delete a chat session by its ID."""
+        return await self._delete(f"/chats/{chat_id}", organization_id=organization_id)
+
+    def stream(self, *, organization_id: str | None = None) -> EventSourceStream:
+        """Open an SSE stream to receive real-time chat events."""
+        return self._stream_sse("/chats/stream", organization_id=organization_id)

modulex/resources/composer.py

@@ -0,0 +1,134 @@
+"""Composer resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+from modulex._streaming import EventSourceStream
+
+
+class Composer(_BaseResource):
+    """Resource for the AI-assisted workflow composer and its chat sessions."""
+
+    async def chat(
+        self,
+        message: str,
+        *,
+        workflow_id: str | None = None,
+        composer_chat_id: str | None = None,
+        llm: str | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Send a message to the composer and receive an AI-generated workflow response."""
+        body: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "message": message,
+                "workflow_id": workflow_id,
+                "composer_chat_id": composer_chat_id,
+                "llm": llm,
+            }.items()
+            if v is not None
+        }
+        return await self._post("/composer/chat", json=body, organization_id=organization_id)
+
+    async def get(
+        self,
+        composer_chat_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return a composer chat session by its ID."""
+        return await self._get(f"/composer/chat/{composer_chat_id}", organization_id=organization_id)
+
+    def listen(
+        self,
+        composer_chat_id: str,
+        run_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> EventSourceStream:
+        """Open an SSE stream to receive live events for a composer chat run."""
+        return self._stream_sse(
+            f"/composer/chat/{composer_chat_id}/listen/{run_id}",
+            organization_id=organization_id,
+        )
+
+    async def save(
+        self,
+        composer_chat_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Save the current workflow state generated by a composer chat session."""
+        return await self._post(
+            f"/composer/chat/{composer_chat_id}/save",
+            organization_id=organization_id,
+        )
+
+    async def revert(
+        self,
+        composer_chat_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Revert the composer chat session to its last saved workflow state."""
+        return await self._post(
+            f"/composer/chat/{composer_chat_id}/revert",
+            organization_id=organization_id,
+        )
+
+    async def history(
+        self,
+        workflow_id: str,
+        *,
+        limit: int = 10,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return the composer chat history associated with a workflow."""
+        params: dict[str, Any] = {"limit": limit}
+        return await self._get(
+            f"/composer/chat/workflow/{workflow_id}/history",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def delete(
+        self,
+        composer_chat_id: str,
+        *,
+        permanent: bool = False,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Delete a composer chat session, optionally removing it permanently."""
+        params: dict[str, Any] = {"permanent": permanent}
+        return await self._delete(
+            f"/composer/chat/{composer_chat_id}",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def status(
+        self,
+        composer_chat_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return the current processing status of a composer chat session."""
+        return await self._get(
+            f"/composer/chat/{composer_chat_id}/status",
+            organization_id=organization_id,
+        )
+
+    async def cancel(
+        self,
+        composer_chat_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Cancel an in-progress composer chat run."""
+        return await self._post(
+            f"/composer/chat/{composer_chat_id}/cancel",
+            organization_id=organization_id,
+        )