modulex-python 0.1.0__py3-none-any.whl

modulex/resources/knowledge.py

@@ -0,0 +1,343 @@
+"""Knowledge resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+import builtins
+import json as json_module
+import os
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class Knowledge(_BaseResource):
+    """Resource for managing knowledge bases, documents, and semantic search."""
+
+    async def list(
+        self,
+        *,
+        status: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return all knowledge bases accessible to the caller."""
+        params: dict[str, Any] = {
+            k: v for k, v in {"status": status, "limit": limit, "offset": offset}.items() if v is not None
+        }
+        return await self._get("/knowledge-bases", params=params, organization_id=organization_id)
+
+    async def create(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        embedding_config: dict[str, Any] | None = None,
+        chunking_config: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Create a new knowledge base with the given name and optional configuration."""
+        body: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "name": name,
+                "description": description,
+                "embedding_config": embedding_config,
+                "chunking_config": chunking_config,
+            }.items()
+            if v is not None
+        }
+        return await self._post("/knowledge-bases", json=body, organization_id=organization_id)
+
+    async def get(
+        self,
+        knowledge_base_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return a single knowledge base by its ID."""
+        return await self._get(f"/knowledge-bases/{knowledge_base_id}", organization_id=organization_id)
+
+    async def update(
+        self,
+        knowledge_base_id: str,
+        *,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Update an existing knowledge base with the provided field values."""
+        body: dict[str, Any] = {k: v for k, v in kwargs.items() if v is not None}
+        return await self._put(
+            f"/knowledge-bases/{knowledge_base_id}",
+            json=body,
+            organization_id=organization_id,
+        )
+
+    async def delete(
+        self,
+        knowledge_base_id: str,
+        *,
+        delete_files: bool = True,
+        organization_id: str | None = None,
+    ) -> None:
+        """Delete a knowledge base and optionally its associated files."""
+        params: dict[str, Any] = {"delete_files": delete_files}
+        await self._delete(
+            f"/knowledge-bases/{knowledge_base_id}",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def archive(
+        self,
+        knowledge_base_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Archive a knowledge base, making it read-only."""
+        return await self._post(
+            f"/knowledge-bases/{knowledge_base_id}/archive",
+            organization_id=organization_id,
+        )
+
+    async def stats(self, *, organization_id: str | None = None) -> Any:
+        """Return aggregate statistics for all knowledge bases in the organization."""
+        return await self._get("/knowledge-bases/stats", organization_id=organization_id)
+
+    async def list_documents(
+        self,
+        knowledge_base_id: str,
+        *,
+        status: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return all documents within a knowledge base."""
+        params: dict[str, Any] = {
+            k: v for k, v in {"status": status, "limit": limit, "offset": offset}.items() if v is not None
+        }
+        return await self._get(
+            f"/knowledge-bases/{knowledge_base_id}/documents",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def upload_document(
+        self,
+        knowledge_base_id: str,
+        *,
+        file_path: str | None = None,
+        file: Any | None = None,
+        filename: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Upload a document to a knowledge base via multipart form data."""
+        if file_path is not None:
+            f = open(file_path, "rb")
+            fn = filename or os.path.basename(file_path)
+        elif file is not None:
+            f = file
+            fn = filename or "document"
+        else:
+            raise ValueError("Either file_path or file must be provided")
+
+        data: dict[str, str] = {}
+        if metadata is not None:
+            data["metadata"] = json_module.dumps(metadata)
+
+        try:
+            return await self._upload(
+                f"/knowledge-bases/{knowledge_base_id}/documents",
+                file=f,
+                filename=fn,
+                data=data if data else None,
+                organization_id=organization_id,
+            )
+        finally:
+            if file_path is not None:
+                f.close()
+
+    async def get_document(
+        self,
+        knowledge_base_id: str,
+        document_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return a single document within a knowledge base by its ID."""
+        return await self._get(
+            f"/knowledge-bases/{knowledge_base_id}/documents/{document_id}",
+            organization_id=organization_id,
+        )
+
+    async def document_status(
+        self,
+        knowledge_base_id: str,
+        document_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return the processing status of a document."""
+        return await self._get(
+            f"/knowledge-bases/{knowledge_base_id}/documents/{document_id}/status",
+            organization_id=organization_id,
+        )
+
+    async def delete_document(
+        self,
+        knowledge_base_id: str,
+        document_id: str,
+        *,
+        delete_file: bool = True,
+        organization_id: str | None = None,
+    ) -> None:
+        """Delete a document from a knowledge base and optionally its underlying file."""
+        params: dict[str, Any] = {"delete_file": delete_file}
+        await self._delete(
+            f"/knowledge-bases/{knowledge_base_id}/documents/{document_id}",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def retry_document(
+        self,
+        knowledge_base_id: str,
+        document_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Retry processing for a failed document."""
+        return await self._post(
+            f"/knowledge-bases/{knowledge_base_id}/documents/{document_id}/retry",
+            organization_id=organization_id,
+        )
+
+    async def document_chunks(
+        self,
+        knowledge_base_id: str,
+        document_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return the text chunks produced from a document after processing."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        return await self._get(
+            f"/knowledge-bases/{knowledge_base_id}/documents/{document_id}/chunks",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def search(
+        self,
+        knowledge_base_id: str,
+        query: str,
+        *,
+        top_k: int = 5,
+        min_score: float = 0.0,
+        filters: dict[str, Any] | None = None,
+        include_content: bool = True,
+        include_metadata: bool = True,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Perform a semantic vector search against a knowledge base."""
+        body: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "query": query,
+                "top_k": top_k,
+                "min_score": min_score,
+                "filters": filters,
+                "include_content": include_content,
+                "include_metadata": include_metadata,
+            }.items()
+            if v is not None
+        }
+        return await self._post(
+            f"/knowledge-bases/{knowledge_base_id}/search",
+            json=body,
+            organization_id=organization_id,
+        )
+
+    async def multi_search(
+        self,
+        knowledge_base_ids: builtins.list[str],
+        query: str,
+        *,
+        top_k: int = 5,
+        min_score: float = 0.0,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Search across multiple knowledge bases in a single request."""
+        body: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "knowledge_base_ids": knowledge_base_ids,
+                "query": query,
+                "top_k": top_k,
+                "min_score": min_score,
+            }.items()
+            if v is not None
+        }
+        return await self._post("/knowledge-bases/search", json=body, organization_id=organization_id)
+
+    async def hybrid_search(
+        self,
+        knowledge_base_id: str,
+        query: str,
+        *,
+        top_k: int = 5,
+        keyword_weight: float = 0.3,
+        semantic_weight: float = 0.7,
+        min_score: float = 0.0,
+        filters: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Perform a hybrid keyword-plus-semantic search against a knowledge base."""
+        body: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "query": query,
+                "top_k": top_k,
+                "keyword_weight": keyword_weight,
+                "semantic_weight": semantic_weight,
+                "min_score": min_score,
+                "filters": filters,
+            }.items()
+            if v is not None
+        }
+        return await self._post(
+            f"/knowledge-bases/{knowledge_base_id}/hybrid-search",
+            json=body,
+            organization_id=organization_id,
+        )
+
+    async def retrieve_context(
+        self,
+        knowledge_base_id: str,
+        query: str,
+        *,
+        max_tokens: int = 2000,
+        top_k: int = 10,
+        min_score: float = 0.3,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Retrieve a token-bounded context string suitable for LLM prompts."""
+        body: dict[str, Any] = {
+            "query": query,
+            "max_tokens": max_tokens,
+            "top_k": top_k,
+            "min_score": min_score,
+        }
+        return await self._post(
+            f"/knowledge-bases/{knowledge_base_id}/retrieve-context",
+            json=body,
+            organization_id=organization_id,
+        )
+
+    async def supported_file_types(self) -> Any:
+        """Return the list of file types supported for document upload."""
+        return await self._get("/knowledge-bases/info/supported-file-types")

modulex/resources/notifications.py

@@ -0,0 +1,39 @@
+"""Notifications resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class Notifications(_BaseResource):
+    """Resource for listing and creating organization notifications."""
+
+    async def list(self, *, organization_id: str | None = None) -> Any:
+        """Return all notifications for the organization."""
+        return await self._get("/notifications", organization_id=organization_id)
+
+    async def create(
+        self,
+        notification_topic: str,
+        message: str,
+        *,
+        notified_to: str | None = None,
+        notification_url: str | None = None,
+        expires_at: str | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Create and dispatch a new notification to the organization."""
+        body: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "notification_topic": notification_topic,
+                "message": message,
+                "notified_to": notified_to,
+                "notification_url": notification_url,
+                "expires_at": expires_at,
+            }.items()
+            if v is not None
+        }
+        return await self._post("/notifications/organization", json=body, organization_id=organization_id)

modulex/resources/organizations.py

@@ -0,0 +1,72 @@
+"""Organizations resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class Organizations(_BaseResource):
+    """Resource for managing organizations and their memberships."""
+
+    async def create(self, name: str, *, slug: str | None = None) -> Any:
+        """Create a new organization with the given name and optional slug."""
+        body: dict[str, Any] = {"name": name}
+        if slug is not None:
+            body["slug"] = slug
+        return await self._post("/organizations", json=body)
+
+    async def llms(self, *, organization_id: str | None = None) -> Any:
+        """Return the LLM configurations available to the organization."""
+        return await self._get("/organizations/llms", organization_id=organization_id)
+
+    async def invite(
+        self,
+        invited_email: str,
+        *,
+        role: str = "member",
+        invitation_message: str | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Send an invitation email to a user to join the organization."""
+        body: dict[str, Any] = {"invited_email": invited_email, "role": role}
+        if invitation_message is not None:
+            body["invitation_message"] = invitation_message
+        return await self._post("/organizations/invite", json=body, organization_id=organization_id)
+
+    async def cancel_invitation(self, invitation_id: str, *, organization_id: str | None = None) -> Any:
+        """Cancel a pending organization invitation by its ID."""
+        return await self._post(
+            f"/organizations/invitations/{invitation_id}/cancel",
+            organization_id=organization_id,
+        )
+
+    async def reinvite(self, invitation_id: str, *, organization_id: str | None = None) -> Any:
+        """Resend an organization invitation by its ID."""
+        return await self._post(
+            f"/organizations/invitations/{invitation_id}/reinvite",
+            organization_id=organization_id,
+        )
+
+    async def update_user_role(
+        self,
+        org_id: str,
+        user_id: str,
+        role: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Update the role of a user within an organization."""
+        return await self._put(
+            f"/organizations/{org_id}/users/{user_id}/role",
+            json={"role": role},
+            organization_id=organization_id,
+        )
+
+    async def remove_user(self, org_id: str, user_id: str, *, organization_id: str | None = None) -> Any:
+        """Remove a user from an organization."""
+        return await self._delete(
+            f"/organizations/{org_id}/users/{user_id}",
+            organization_id=organization_id,
+        )

modulex/resources/schedules.py

@@ -0,0 +1,172 @@
+"""Schedules resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class Schedules(_BaseResource):
+    """Resource for managing workflow schedules and their execution runs."""
+
+    async def create(
+        self,
+        workflow_id: str,
+        name: str,
+        schedule_type: str,
+        *,
+        interval_seconds: int | None = None,
+        cron_expression: str | None = None,
+        timezone: str = "UTC",
+        description: str | None = None,
+        input: dict[str, Any] | None = None,
+        config: dict[str, Any] | None = None,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Create a new schedule that triggers a workflow on a defined cadence."""
+        body: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "workflow_id": workflow_id,
+                "name": name,
+                "schedule_type": schedule_type,
+                "interval_seconds": interval_seconds,
+                "cron_expression": cron_expression,
+                "timezone": timezone,
+                "description": description,
+                "input": input,
+                "config": config,
+            }.items()
+            if v is not None
+        }
+        return await self._post("/schedules", json=body, organization_id=organization_id)
+
+    async def list(
+        self,
+        *,
+        workflow_id: str | None = None,
+        is_active: bool | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return all schedules, optionally filtered by workflow or active status."""
+        params: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "workflow_id": workflow_id,
+                "is_active": is_active,
+                "limit": limit,
+                "offset": offset,
+            }.items()
+            if v is not None
+        }
+        return await self._get("/schedules", params=params, organization_id=organization_id)
+
+    async def get(
+        self,
+        schedule_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return a single schedule by its ID."""
+        return await self._get(f"/schedules/{schedule_id}", organization_id=organization_id)
+
+    async def update(
+        self,
+        schedule_id: str,
+        *,
+        organization_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Update an existing schedule with the provided field values."""
+        body: dict[str, Any] = {k: v for k, v in kwargs.items() if v is not None}
+        return await self._put(f"/schedules/{schedule_id}", json=body, organization_id=organization_id)
+
+    async def delete(
+        self,
+        schedule_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Delete a schedule permanently by its ID."""
+        return await self._delete(f"/schedules/{schedule_id}", organization_id=organization_id)
+
+    async def pause(
+        self,
+        schedule_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Pause an active schedule so it no longer triggers new runs."""
+        return await self._post(f"/schedules/{schedule_id}/pause", organization_id=organization_id)
+
+    async def resume(
+        self,
+        schedule_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Resume a paused schedule so it resumes triggering runs."""
+        return await self._post(f"/schedules/{schedule_id}/resume", organization_id=organization_id)
+
+    async def list_runs(
+        self,
+        schedule_id: str,
+        *,
+        status: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return execution runs for a schedule, optionally filtered by status."""
+        params: dict[str, Any] = {
+            k: v for k, v in {"status": status, "limit": limit, "offset": offset}.items() if v is not None
+        }
+        return await self._get(
+            f"/schedules/{schedule_id}/runs",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def run_stats(
+        self,
+        schedule_id: str,
+        *,
+        days: int = 7,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return aggregated run statistics for a schedule over the given number of days."""
+        params: dict[str, Any] = {"days": days}
+        return await self._get(
+            f"/schedules/{schedule_id}/runs/stats",
+            params=params,
+            organization_id=organization_id,
+        )
+
+    async def get_run(
+        self,
+        schedule_id: str,
+        run_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Return a single run record for a schedule by run ID."""
+        return await self._get(
+            f"/schedules/{schedule_id}/runs/{run_id}",
+            organization_id=organization_id,
+        )
+
+    async def retry_run(
+        self,
+        schedule_id: str,
+        run_id: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Retry a failed schedule run by its ID."""
+        return await self._post(
+            f"/schedules/{schedule_id}/runs/{run_id}/retry",
+            organization_id=organization_id,
+        )

modulex/resources/subscriptions.py

@@ -0,0 +1,38 @@
+"""Subscriptions resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class Subscriptions(_BaseResource):
+    """Resource for managing organization subscription plans and billing."""
+
+    async def organization_plans(self, *, organization_id: str | None = None) -> Any:
+        """Return available subscription plans for the organization."""
+        return await self._get("/subscriptions/organization-plans", organization_id=organization_id)
+
+    async def organization_billing(self, *, organization_id: str | None = None) -> Any:
+        """Return the current billing details for the organization."""
+        return await self._get("/subscriptions/organization-billing", organization_id=organization_id)
+
+    async def checkout_link(
+        self,
+        plan_id: str,
+        interval: str,
+        *,
+        organization_id: str | None = None,
+    ) -> Any:
+        """Generate a Stripe checkout link for upgrading to a given plan and billing interval."""
+        params: dict[str, Any] = {"plan_id": plan_id, "interval": interval}
+        return await self._post(
+            "/subscriptions/checkout-link",
+            json=params,
+            organization_id=organization_id,
+        )
+
+    async def customer_portal(self, *, organization_id: str | None = None) -> Any:
+        """Generate a Stripe customer portal link for managing the organization's subscription."""
+        return await self._post("/subscriptions/customer-portal", organization_id=organization_id)

modulex/resources/system.py

@@ -0,0 +1,28 @@
+"""System resource for the ModuleX Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modulex._base import _BaseResource
+
+
+class System(_BaseResource):
+    """Resource for system-level health, metrics, and reference data."""
+
+    async def health(self) -> Any:
+        """Return the current health status of the API service."""
+        return await self._get("/system/health")
+
+    async def metrics(self) -> Any:
+        """Return system-level performance and usage metrics."""
+        return await self._get("/system/metrics")
+
+    async def timezones(self) -> Any:
+        """Return the full list of supported IANA timezone identifiers."""
+        return await self._get("/system/timezones")
+
+    async def search_timezones(self, query: str) -> Any:
+        """Search supported timezones by a keyword query string."""
+        params: dict[str, Any] = {"q": query}
+        return await self._get("/system/timezones/search", params=params)