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

modulex/_streaming.py

@@ -1,4 +1,16 @@
-"""SSE streaming support for the ModuleX SDK."""
+"""SSE streaming support for the ModuleX SDK.
+
+The ModuleX backend uses **two** SSE wire conventions:
+
+  A) ``/chats/stream`` emits a real ``event:`` line (event name in the SSE field).
+  B) workflow / composer / assistant / credential streams emit raw ``data: {...}``
+     with NO ``event:`` line — the real event type lives in ``data["type"]``.
+
+``EventSourceStream`` normalizes both: ``SSEEvent.event`` always carries the
+logical event name, whether it came from the SSE ``event:`` field or from
+``data["type"]``. This is what makes ``executions.listen()`` / ``composer.listen()``
+dispatch correctly instead of seeing every event as ``"message"``.
+"""
 
 from __future__ import annotations
 
@@ -10,103 +22,121 @@ from typing import Any
 import httpx
 from httpx_sse import aconnect_sse
 
-from modulex._exceptions import StreamError
+from modulex._exceptions import ModulexError, StreamError, raise_for_status
+
+#: Event types that terminate a run stream — iteration stops after one is seen.
+TERMINAL_EVENT_TYPES = frozenset({"done", "error", "cancelled", "interrupted"})
+
+#: Event types treated as keepalive noise and filtered out by default.
+HEARTBEAT_EVENT_TYPES = frozenset({"heartbeat", "keepalive"})
 
 
 @dataclass
 class SSEEvent:
-    """A Server-Sent Event."""
+    """A Server-Sent Event with a normalized logical event name.
+
+    ``event`` is the logical name (from the SSE ``event:`` field for A-group
+    streams, or from ``data["type"]`` for B-group streams). ``raw_event`` keeps
+    the original SSE ``event:`` field for debugging.
+    """
 
     event: str
     data: dict[str, Any]
     id: str | None = None
     retry: int | None = None
+    raw_event: str | 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()
+    @property
+    def is_terminal(self) -> bool:
+        """Whether this event terminates the stream (done/error/cancelled/interrupted)."""
+        return self.event in TERMINAL_EVENT_TYPES
 
 
 class EventSourceStream:
-    """Full SSE parser that handles multi-line event blocks."""
-
-    def __init__(self, client: httpx.AsyncClient, method: str, url: str, **kwargs: Any) -> None:
+    """Async iterator over a Server-Sent Events stream.
+
+    Normalizes the two backend wire conventions, surfaces HTTP errors on connect
+    as typed exceptions, filters heartbeats, and stops after a terminal event.
+    Usable as an async iterator or async context manager::
+
+        async with client.executions.listen(run_id) as stream:
+            async for event in stream:
+                ...
+    """
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        method: str,
+        url: str,
+        *,
+        include_heartbeats: bool = False,
+        **kwargs: Any,
+    ) -> None:
         self._client = client
         self._method = method
         self._url = url
+        self._include_heartbeats = include_heartbeats
         self._kwargs = kwargs
         self._closed = False
+        self.last_event_id: str | None = None
 
     def __aiter__(self) -> AsyncIterator[SSEEvent]:
         return self._iterate()
 
+    async def __aenter__(self) -> EventSourceStream:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
     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:
+                response = event_source.response
+                if response.status_code >= 400:
+                    # Surface auth/billing/rate denials as typed exceptions instead
+                    # of an opaque "content type is not text/event-stream" SSEError.
+                    await response.aread()
+                    raise_for_status(response)
+
                 async for sse in event_source.aiter_sse():
                     if self._closed:
                         break
 
-                    event_type = sse.event or "message"
-                    if event_type == "keepalive":
-                        continue
-
+                    raw_event = sse.event or None
                     try:
                         data = json.loads(sse.data) if sse.data else {}
                     except json.JSONDecodeError:
                         data = {"raw": sse.data}
 
+                    # Normalize: prefer data["type"] (B-group), fall back to the
+                    # SSE event: field (A-group). "message" is httpx_sse's default
+                    # when no event: line is present, so treat it as "unknown".
+                    type_in_data = data.get("type") if isinstance(data, dict) else None
+                    event_name = type_in_data or (raw_event if raw_event and raw_event != "message" else "message")
+
+                    if event_name in HEARTBEAT_EVENT_TYPES and not self._include_heartbeats:
+                        continue
+
+                    if sse.id:
+                        self.last_event_id = sse.id
+
                     yield SSEEvent(
-                        event=event_type,
-                        data=data,
+                        event=event_name,
+                        data=data if isinstance(data, dict) else {"raw": data},
                         id=sse.id,
                         retry=sse.retry,
+                        raw_event=raw_event,
                     )
+
+                    if event_name in TERMINAL_EVENT_TYPES:
+                        break
+        except ModulexError:
+            # Typed SDK errors (auth/billing/rate from raise_for_status, StreamError)
+            # propagate as-is instead of being re-wrapped below.
+            raise
         except httpx.StreamClosed:
             return
         except Exception as e:
@@ -114,5 +144,5 @@ class EventSourceStream:
                 raise StreamError(f"SSE stream error: {e}") from e
 
     async def close(self) -> None:
-        """Close the SSE stream."""
+        """Stop iterating; the underlying connection closes on context exit."""
         self._closed = True

modulex/_version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the SDK version."""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"

modulex/resources/api_keys.py

@@ -5,6 +5,12 @@ from __future__ import annotations
 from typing import Any
 
 from modulex._base import _BaseResource
+from modulex.types.api_keys import (
+    ApiKeyListResponse,
+    ApiKeyResponse,
+    CreateApiKeyResponse,
+    RevokeApiKeyResponse,
+)
 
 
 class ApiKeys(_BaseResource):
@@ -17,23 +23,25 @@ class ApiKeys(_BaseResource):
         organization_id: str | None = None,
         expires_at: str | None = None,
         rate_limit_per_minute: int = 60,
-    ) -> Any:
+    ) -> CreateApiKeyResponse:
         """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)
+        return CreateApiKeyResponse.model_validate(await self._post("/api-keys", json=body))
 
-    async def list(self, *, include_revoked: bool = False) -> Any:
+    async def list(self, *, include_revoked: bool = False) -> ApiKeyListResponse:
         """Return all API keys, optionally including revoked ones."""
-        return await self._get("/api-keys", params={"include_revoked": include_revoked})
+        return ApiKeyListResponse.model_validate(
+            await self._get("/api-keys", params={"include_revoked": include_revoked})
+        )
 
-    async def get(self, key_id: str) -> Any:
+    async def get(self, key_id: str) -> ApiKeyResponse:
         """Return a single API key by its ID."""
-        return await self._get(f"/api-keys/{key_id}")
+        return ApiKeyResponse.model_validate(await self._get(f"/api-keys/{key_id}"))
 
-    async def revoke(self, key_id: str) -> Any:
+    async def revoke(self, key_id: str) -> RevokeApiKeyResponse:
         """Revoke an API key by its ID."""
-        return await self._delete(f"/api-keys/{key_id}")
+        return RevokeApiKeyResponse.model_validate(await self._delete(f"/api-keys/{key_id}"))

modulex/resources/assistant.py

@@ -0,0 +1,154 @@
+"""Assistant resource for the ModuleX Python SDK.
+
+The assistant is the agentic "standard chat" surface. It shares the HITL
+(human-in-the-loop) contract with the composer: a paused run emits a
+``user_input_request`` SSE event answered via :meth:`resume`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+from modulex._streaming import EventSourceStream
+from modulex.types.assistant import (
+    AssistantCancelResponse,
+    AssistantChatDetails,
+    AssistantChatListResponse,
+    AssistantChatResponse,
+    AssistantDeleteResponse,
+    AssistantResumeResponse,
+    AssistantStatusResponse,
+)
+from modulex.types.realtime import ComposerLLMConfig, UserInputResponse, _to_payload
+
+
+class Assistant(_BaseResource):
+    """Resource for the agentic assistant chat (all endpoints: org member access)."""
+
+    async def chat(
+        self,
+        message: str,
+        *,
+        chat_id: str | None = None,
+        llm: ComposerLLMConfig | dict[str, Any] | None = None,
+        organization_id: str | None = None,
+    ) -> AssistantChatResponse:
+        """Start a new assistant chat or continue an existing one.
+
+        ``llm`` is a provider config ({integration_name, provider_id, model_id,
+        credential_id?}); omit it to use the organization's default. Returns a
+        ``run_id`` — open the event stream with :meth:`listen`.
+        """
+        body: dict[str, Any] = {"message": message}
+        if chat_id is not None:
+            body["chat_id"] = chat_id
+        if llm is not None:
+            body["llm"] = _to_payload(llm)
+        return AssistantChatResponse.model_validate(
+            await self._post("/assistant/chat", json=body, organization_id=organization_id)
+        )
+
+    async def get(self, chat_id: str, *, organization_id: str | None = None) -> AssistantChatDetails:
+        """Return an assistant chat with all its messages (and any pending HITL question)."""
+        return AssistantChatDetails.model_validate(
+            await self._get(f"/assistant/chat/{chat_id}", organization_id=organization_id)
+        )
+
+    async def list(
+        self,
+        *,
+        limit: int = 20,
+        cursor: str | None = None,
+        organization_id: str | None = None,
+    ) -> AssistantChatListResponse:
+        """List the caller's assistant chats (newest first, cursor-paginated)."""
+        params: dict[str, Any] = {"limit": limit, "cursor": cursor}
+        return AssistantChatListResponse.model_validate(
+            await self._get("/assistant/chats", params=params, organization_id=organization_id)
+        )
+
+    def listen(
+        self,
+        chat_id: str,
+        run_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> EventSourceStream:
+        """Open an SSE stream of live events for an assistant run.
+
+        Event types are carried in ``event.event`` (normalized from ``data['type']``).
+        A ``user_input_request`` event means the run paused for HITL input — answer
+        it with :meth:`resume`.
+
+        A 404 (``NotFoundError``) on connect means the chat/run was not found or is
+        not owned by your org — iterating the stream raises it rather than yielding
+        events (no reconnect loop, no existence leak).
+        """
+        return self._stream_sse(
+            f"/assistant/chat/{chat_id}/listen/{run_id}",
+            organization_id=organization_id,
+        )
+
+    async def resume(
+        self,
+        chat_id: str,
+        *,
+        request_id: str,
+        response: UserInputResponse | dict[str, Any],
+        llm: ComposerLLMConfig | dict[str, Any],
+        organization_id: str | None = None,
+    ) -> AssistantResumeResponse:
+        """Answer a paused HITL ``user_input_request`` and resume the run.
+
+        ``llm`` is required (the executor rebuilds the chat model on resume).
+        Returns a NEW ``run_id``; re-subscribe with :meth:`listen` on that run.
+
+        A 404 (``NotFoundError``) means the chat was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
+        """
+        body: dict[str, Any] = {
+            "request_id": request_id,
+            "response": _to_payload(response),
+            "llm": _to_payload(llm),
+        }
+        return AssistantResumeResponse.model_validate(
+            await self._post(
+                f"/assistant/chat/{chat_id}/resume",
+                json=body,
+                organization_id=organization_id,
+            )
+        )
+
+    async def status(self, chat_id: str, *, organization_id: str | None = None) -> AssistantStatusResponse:
+        """Return an assistant chat's status (running / awaiting_input / idle)."""
+        return AssistantStatusResponse.model_validate(
+            await self._get(f"/assistant/chat/{chat_id}/status", organization_id=organization_id)
+        )
+
+    async def cancel(self, chat_id: str, *, organization_id: str | None = None) -> AssistantCancelResponse:
+        """Cancel a running assistant run (also clears any pending HITL question).
+
+        A 404 (``NotFoundError``) means the chat was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
+        """
+        return AssistantCancelResponse.model_validate(
+            await self._post(f"/assistant/chat/{chat_id}/cancel", organization_id=organization_id)
+        )
+
+    async def delete(
+        self,
+        chat_id: str,
+        *,
+        permanent: bool = False,
+        organization_id: str | None = None,
+    ) -> AssistantDeleteResponse:
+        """Delete an assistant chat (soft by default; ``permanent=True`` for hard delete)."""
+        params: dict[str, Any] = {"permanent": permanent}
+        return AssistantDeleteResponse.model_validate(
+            await self._delete(
+                f"/assistant/chat/{chat_id}",
+                params=params,
+                organization_id=organization_id,
+            )
+        )

modulex/resources/auth.py

@@ -5,34 +5,46 @@ from __future__ import annotations
 from typing import Any
 
 from modulex._base import _BaseResource
+from modulex.types.auth import (
+    AcceptInvitationResponse,
+    InvitationsResponse,
+    LeaveOrganizationResponse,
+    RejectInvitationResponse,
+    UserOrganizationsResponse,
+    UserProfile,
+)
 
 
 class Auth(_BaseResource):
     """Resource for authentication and identity endpoints."""
 
-    async def me(self) -> Any:
+    async def me(self) -> UserProfile:
         """Return the currently authenticated user's profile."""
-        return await self._get("/auth/me")
+        return UserProfile.model_validate(await self._get("/auth/me"))
 
-    async def organizations(self, *, role: str | None = None) -> Any:
+    async def organizations(self, *, role: str | None = None) -> UserOrganizationsResponse:
         """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)
+        return UserOrganizationsResponse.model_validate(
+            await self._get("/auth/me/organizations", params=params or None)
+        )
 
-    async def invitations(self) -> Any:
+    async def invitations(self) -> InvitationsResponse:
         """Return all pending invitations for the current user."""
-        return await self._get("/auth/invitations/my")
+        return InvitationsResponse.model_validate(await self._get("/auth/invitations/my"))
 
-    async def accept_invitation(self, invitation_id: str) -> Any:
+    async def accept_invitation(self, invitation_id: str) -> AcceptInvitationResponse:
         """Accept a pending organization invitation by its ID."""
-        return await self._post(f"/auth/invitations/{invitation_id}/accept")
+        return AcceptInvitationResponse.model_validate(await self._post(f"/auth/invitations/{invitation_id}/accept"))
 
-    async def reject_invitation(self, invitation_id: str) -> Any:
+    async def reject_invitation(self, invitation_id: str) -> RejectInvitationResponse:
         """Reject a pending organization invitation by its ID."""
-        return await self._post(f"/auth/invitations/{invitation_id}/reject")
+        return RejectInvitationResponse.model_validate(await self._post(f"/auth/invitations/{invitation_id}/reject"))
 
-    async def leave_organization(self, *, organization_id: str | None = None) -> Any:
+    async def leave_organization(self, *, organization_id: str | None = None) -> LeaveOrganizationResponse:
         """Leave the organization identified by the organization_id header."""
-        return await self._post("/auth/organizations/leave", organization_id=organization_id)
+        return LeaveOrganizationResponse.model_validate(
+            await self._post("/auth/organizations/leave", organization_id=organization_id)
+        )

modulex/resources/chats.py

@@ -6,18 +6,29 @@ from typing import Any
 
 from modulex._base import _BaseResource
 from modulex._streaming import EventSourceStream
+from modulex.types.chats import (
+    ChatDeleteResponse,
+    ChatMessagesListResponse,
+    ChatResponse,
+)
 
 
 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 list(self, *, organization_id: str | None = None) -> dict[str, Any]:
+        """Return all chat sessions for the current user or organization.
 
-    async def get(self, chat_id: str, *, organization_id: str | None = None) -> Any:
+        The backend groups chats under dynamic folder keys (e.g. ``chats``,
+        ``pinned``, ``archived`` plus any user-defined folders), so this stays a
+        raw ``dict[str, list[...]]`` rather than a fixed model.
+        """
+        result: dict[str, Any] = await self._get("/chats", organization_id=organization_id)
+        return result
+
+    async def get(self, chat_id: str, *, organization_id: str | None = None) -> ChatResponse:
         """Return a single chat session by its ID."""
-        return await self._get(f"/chats/{chat_id}", organization_id=organization_id)
+        return ChatResponse.model_validate(await self._get(f"/chats/{chat_id}", organization_id=organization_id))
 
     async def messages(
         self,
@@ -26,12 +37,14 @@ class Chats(_BaseResource):
         limit: int = 20,
         offset: int = 0,
         organization_id: str | None = None,
-    ) -> Any:
+    ) -> ChatMessagesListResponse:
         """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,
+        return ChatMessagesListResponse.model_validate(
+            await self._get(
+                f"/chats/{chat_id}/messages",
+                params={"limit": limit, "offset": offset},
+                organization_id=organization_id,
+            )
         )
 
     async def update(
@@ -42,7 +55,7 @@ class Chats(_BaseResource):
         is_private: bool | None = None,
         folder: str | None = None,
         organization_id: str | None = None,
-    ) -> Any:
+    ) -> ChatResponse:
         """Update metadata for a chat session such as title, privacy, or folder."""
         body: dict[str, Any] = {}
         if title is not None:
@@ -51,11 +64,15 @@ class Chats(_BaseResource):
             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)
+        return ChatResponse.model_validate(
+            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:
+    async def delete(self, chat_id: str, *, organization_id: str | None = None) -> ChatDeleteResponse:
         """Delete a chat session by its ID."""
-        return await self._delete(f"/chats/{chat_id}", organization_id=organization_id)
+        return ChatDeleteResponse.model_validate(
+            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."""