magickmind 0.1.1__py3-none-any.whl

magick_mind/resources/v1/corpus.py

@@ -0,0 +1,156 @@
+"""
+Corpus resource for Magick Mind SDK v1 API.
+
+Provides methods for managing corpus (knowledge base) resources.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from magick_mind.models.v1.corpus import (
+    Corpus,
+    CreateCorpusRequest,
+    ListCorpusResponse,
+    UpdateCorpusRequest,
+)
+from magick_mind.routes import Routes
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class CorpusResourceV1:
+    """Resource client for corpus operations."""
+
+    def __init__(self, http_client: httpx.Client):
+        """
+        Initialize the corpus resource.
+
+        Args:
+            http_client: Authenticated httpx client
+        """
+        self.http = http_client
+
+    def create(
+        self,
+        name: str,
+        description: str,
+        artifact_ids: Optional[list[str]] = None,
+    ) -> Corpus:
+        """
+        Create a new corpus.
+
+        Args:
+            name: Corpus name
+            description: Corpus description
+            artifact_ids: Optional list of artifact IDs to include
+
+        Returns:
+            Corpus object
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails
+        """
+        payload = CreateCorpusRequest(
+            name=name,
+            description=description,
+            artifact_ids=artifact_ids or [],
+        )
+
+        resp = self.http.post(Routes.CORPUS, json=payload.model_dump())
+        resp.raise_for_status()
+
+        return Corpus(**resp.json())
+
+    def get(self, corpus_id: str) -> Corpus:
+        """
+        Get a corpus by ID.
+
+        Args:
+            corpus_id: The corpus ID
+
+        Returns:
+            Corpus object
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails
+        """
+        resp = self.http.get(Routes.corpus(corpus_id))
+        resp.raise_for_status()
+
+        return Corpus(**resp.json())
+
+    def list(self, user_id: Optional[str] = None) -> ListCorpusResponse:
+        """
+        List all corpus, optionally filtered by user_id.
+
+        Args:
+            user_id: Optional user ID to filter by
+
+        Returns:
+            ListCorpusResponse with list of corpus
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails
+        """
+        params = {}
+        if user_id:
+            params["user_id"] = user_id
+
+        resp = self.http.get(Routes.CORPUS, params=params)
+        resp.raise_for_status()
+
+        return ListCorpusResponse(**resp.json())
+
+    def update(
+        self,
+        corpus_id: str,
+        name: str,
+        description: str,
+        artifact_ids: list[str],
+    ) -> Corpus:
+        """
+        Update an existing corpus.
+
+        Args:
+            corpus_id: The corpus ID to update
+            name: New corpus name
+            description: New corpus description
+            artifact_ids: New list of artifact IDs
+
+        Returns:
+            Corpus object
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails
+        """
+        payload = UpdateCorpusRequest(
+            name=name,
+            description=description,
+            artifact_ids=artifact_ids,
+        )
+
+        resp = self.http.put(Routes.corpus(corpus_id), json=payload.model_dump())
+        resp.raise_for_status()
+
+        return Corpus(**resp.json())
+
+    def delete(self, corpus_id: str) -> None:
+        """
+        Delete a corpus.
+
+        Args:
+            corpus_id: The corpus ID to delete
+
+        Returns:
+            None (Bifrost returns 204 No Content)
+
+        Example:
+            client.v1.corpus.delete(corpus_id="corpus-123")
+            print("Corpus deleted successfully")
+
+        Raises:
+            httpx.HTTPStatusError: If request fails
+        """
+        self.http.delete(Routes.corpus(corpus_id))

magick_mind/resources/v1/end_user.py

@@ -0,0 +1,181 @@
+"""
+End user resource for Magick Mind SDK v1 API.
+
+Provides methods for CRUD operations on end users in the agentic SaaS backend.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+from magick_mind.models.v1.end_user import (
+    CreateEndUserRequest,
+    EndUser,
+    QueryEndUserResponse,
+    UpdateEndUserRequest,
+)
+from magick_mind.resources.base import BaseResource
+from magick_mind.routes import Routes
+
+
+class EndUserResourceV1(BaseResource):
+    """
+    End user resource for managing end users in agentic SaaS applications.
+
+    End users represent the actual users of applications built on the bifrost
+    platform in a multi-tenant architecture.
+    """
+
+    def create(
+        self,
+        name: str,
+        tenant_id: str,
+        actor_id: str,
+        external_id: Optional[str] = None,
+    ) -> EndUser:
+        """
+        Create a new end user.
+
+        Args:
+            name: End user name (required)
+            tenant_id: Tenant ID this end user belongs to (required)
+            actor_id: Actor ID performing the action (required)
+            external_id: Optional external ID for mapping to external systems
+
+        Returns:
+            Created EndUser object
+
+        Example:
+            end_user = client.v1.end_user.create(
+                name="John Doe",
+                tenant_id="tenant-123",
+                actor_id="user-456",
+                external_id="ext-789"
+            )
+            print(f"Created end user: {end_user.id}")
+        """
+        request = CreateEndUserRequest(
+            name=name,
+            tenant_id=tenant_id,
+            actor_id=actor_id,
+            external_id=external_id,
+        )
+
+        response = self._http.post(Routes.END_USERS, json=request.model_dump())
+        return EndUser(**response)
+
+    def get(self, end_user_id: str) -> EndUser:
+        """
+        Get an end user by ID.
+
+        Args:
+            end_user_id: The end user ID to retrieve
+
+        Returns:
+            EndUser object
+
+        Example:
+            end_user = client.v1.end_user.get(end_user_id="user-123")
+            print(f"End user name: {end_user.name}")
+        """
+        response = self._http.get(Routes.end_user(end_user_id))
+        return EndUser(**response)
+
+    def query(
+        self,
+        name: Optional[str] = None,
+        external_id: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        actor_id: Optional[str] = None,
+    ) -> list[EndUser]:
+        """
+        Query end users with optional filters.
+
+        All parameters are optional. If no filters are provided, returns all
+        accessible end users.
+
+        Args:
+            name: Filter by end user name (optional)
+            external_id: Filter by external ID (optional)
+            tenant_id: Filter by tenant ID (optional)
+            actor_id: Filter by actor ID (optional)
+
+        Returns:
+            List of EndUser objects matching the query
+
+        Example:
+            # Get all end users for a tenant
+            end_users = client.v1.end_user.query(tenant_id="tenant-123")
+            for user in end_users:
+                print(f"- {user.name}")
+
+            # Search by external ID
+            user = client.v1.end_user.query(external_id="ext-789")
+        """
+        params = {}
+        if name is not None:
+            params["name"] = name
+        if external_id is not None:
+            params["external_id"] = external_id
+        if tenant_id is not None:
+            params["tenant_id"] = tenant_id
+        if actor_id is not None:
+            params["actor_id"] = actor_id
+
+        response = self._http.get(Routes.END_USERS, params=params)
+        query_response = QueryEndUserResponse(**response)
+        return query_response.data
+
+    def update(
+        self,
+        end_user_id: str,
+        name: Optional[str] = None,
+        external_id: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ) -> EndUser:
+        """
+        Update an existing end user.
+
+        All update fields are optional. Only provided fields will be updated.
+
+        Args:
+            end_user_id: The end user ID to update
+            name: New end user name (optional)
+            external_id: New external ID (optional)
+            tenant_id: New tenant ID (optional)
+
+        Returns:
+            Updated EndUser object
+
+        Example:
+            updated = client.v1.end_user.update(
+                end_user_id="user-123",
+                name="Jane Doe",
+                external_id="new-ext-id"
+            )
+            print(f"Updated end user: {updated.name}")
+        """
+        request = UpdateEndUserRequest(
+            name=name,
+            external_id=external_id,
+            tenant_id=tenant_id,
+        )
+
+        response = self._http.put(
+            Routes.end_user(end_user_id), json=request.model_dump(exclude_none=True)
+        )
+        return EndUser(**response)
+
+    def delete(self, end_user_id: str) -> None:
+        """
+        Delete an end user.
+
+        Args:
+            end_user_id: The end user ID to delete
+
+        Example:
+            client.v1.end_user.delete(end_user_id="user-123")
+            print("End user deleted successfully")
+        """
+        self._http.delete(Routes.end_user(end_user_id))

magick_mind/resources/v1/history.py

@@ -0,0 +1,88 @@
+"""
+History resource for Magick Mind SDK v1 API.
+
+Provides methods to fetch chat history with pagination.
+"""
+
+from typing import Optional
+
+from magick_mind.models.v1.history import HistoryResponse
+from magick_mind.resources.base import BaseResource
+from magick_mind.routes import Routes
+
+
+class HistoryResourceV1(BaseResource):
+    """
+    History resource for fetching chat messages.
+
+    Supports three pagination modes:
+    1. Latest: Get most recent N messages
+    2. Forward: Get messages after a specific message_id
+    3. Backward: Get messages before a specific message_id
+    """
+
+    def get_messages(
+        self,
+        mindspace_id: str,
+        after_id: Optional[str] = None,
+        before_id: Optional[str] = None,
+        limit: int = 50,
+    ) -> HistoryResponse:
+        """
+        Fetch chat history with keyset pagination.
+
+        Three modes based on parameters:
+        - Latest: Just mindspace_id + limit (most recent messages)
+        - Forward: mindspace_id + after_id + limit (messages after a point)
+        - Backward: mindspace_id + before_id + limit (messages before a point)
+
+        Args:
+            mindspace_id: Mindspace to fetch messages from
+            after_id: Get messages after this message ID (forward pagination)
+            before_id: Get messages before this message ID (backward pagination)
+            limit: Maximum number of messages to return (default: 50)
+
+        Returns:
+            HistoryResponse with messages and pagination cursors
+
+        Raises:
+            ValueError: If both after_id and before_id are provided
+
+        Example:
+            # Get latest 50 messages
+            history = client.v1.history.get_messages(mindspace_id="mind-123")
+
+            # Forward pagination (newer messages)
+            more = client.v1.history.get_messages(
+                mindspace_id="mind-123",
+                after_id=history.last_id,
+                limit=50
+            )
+
+            # Backward pagination (older messages)
+            older = client.v1.history.get_messages(
+                mindspace_id="mind-123",
+                before_id=history.chat_histories[0].id,
+                limit=50
+            )
+        """
+        # Validate mutually exclusive parameters
+        if after_id and before_id:
+            raise ValueError("Cannot specify both after_id and before_id")
+
+        # Build query parameters
+        params = {
+            "mindspace_id": mindspace_id,
+            "limit": limit,
+        }
+
+        if after_id:
+            params["after_id"] = after_id
+        if before_id:
+            params["before_id"] = before_id
+
+        # Make request
+        response = self._http.get(Routes.HISTORY_MESSAGES, params=params)
+
+        # Parse and return
+        return HistoryResponse(**response.json())