magickmind 0.1.1__py3-none-any.whl

magick_mind/resources/v1/mindspace.py

@@ -0,0 +1,331 @@
+"""V1 mindspace resource implementation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from magick_mind.models.v1.mindspace import (
+    AddMindSpaceUsersRequest,
+    CreateMindSpaceRequest,
+    GetMindSpaceListResponse,
+    MindSpace,
+    MindSpaceType,
+    MindspaceMessagesResponse,
+    UpdateMindSpaceRequest,
+)
+from magick_mind.resources.base import BaseResource
+from magick_mind.routes import Routes
+
+if TYPE_CHECKING:
+    from magick_mind.http import HTTPClient
+
+
+class MindspaceResourceV1(BaseResource):
+    """
+    Mindspace resource client for V1 API.
+
+    Provides typed interface for managing mindspaces (organizational containers
+    for chat conversations, corpus, and users).
+
+    Example:
+        # Create a private mindspace
+        mindspace = client.v1.mindspace.create(
+            name="My Workspace",
+            type="private",
+            description="Personal workspace",
+            corpus_ids=["corp-123"]
+        )
+
+        # List all mindspaces
+        mindspaces = client.v1.mindspace.list(user_id="user-456")
+
+        # Get messages from mindspace
+        messages = client.v1.mindspace.get_messages(
+            mindspace_id="mind-123",
+            limit=50
+        )
+    """
+
+    def create(
+        self,
+        name: str,
+        type: MindSpaceType,
+        description: Optional[str] = None,
+        project_id: Optional[str] = None,
+        corpus_ids: Optional[list[str]] = None,
+        user_ids: Optional[list[str]] = None,
+    ) -> MindSpace:
+        """
+        Create a new mindspace.
+        Args:
+            name: Mindspace name (max 100 characters)
+            type: Mindspace type - either "PRIVATE" or "GROUP"
+            description: Optional description (max 256 characters)
+            project_id: Optional associated project ID
+            corpus_ids: Optional list of corpus IDs to attach
+            user_ids: Optional list of user IDs to grant access
+
+        Returns:
+            MindSpace
+
+        Raises:
+            HTTPError: If the API request fails
+            ValidationError: If parameters are invalid
+
+        Example:
+            # Create a group mindspace
+            mindspace = client.v1.mindspace.create(
+                name="Engineering Team",
+                type="GROUP",
+                description="Team collaboration space",
+                corpus_ids=["corp-1", "corp-2"],
+                user_ids=["user-1", "user-2"]
+            )
+            print(f"Created mindspace: {mindspace.id}")
+        """
+        # Build and validate request
+        request = CreateMindSpaceRequest(
+            name=name,
+            type=type,
+            description=description,
+            project_id=project_id,
+            corpus_ids=corpus_ids or [],
+            user_ids=user_ids or [],
+        )
+
+        # Make API call
+        response = self._http.post(
+            Routes.MINDSPACES, json=request.model_dump(exclude_none=True)
+        )
+
+        return MindSpace.model_validate(response)
+
+    def get(self, mindspace_id: str) -> MindSpace:
+        """
+        Get a mindspace by ID.
+
+        Args:
+            mindspace_id: Mindspace ID to retrieve
+
+        Returns:
+            MindSpace
+
+        Raises:
+            HTTPError: If the API request fails or mindspace not found
+
+        Example:
+            mindspace = client.v1.mindspace.get("mind-123")
+            print(f"Mindspace: {mindspace.name}")
+            print(f"Type: {mindspace.type}")
+            print(f"Corpus: {mindspace.corpus_ids}")
+        """
+        response_data = self._http.get(Routes.mindspace(mindspace_id))
+        return MindSpace.model_validate(response_data)
+
+    def list(self, user_id: Optional[str] = None) -> GetMindSpaceListResponse:
+        """
+        List mindspaces, optionally filtered by user.
+
+        Args:
+            user_id: Optional user ID to filter mindspaces
+
+        Returns:
+            GetMindSpaceListResponse with list of mindspaces
+
+        Raises:
+            HTTPError: If the API request fails
+
+        Example:
+            # List all mindspaces for a user
+            response = client.v1.mindspace.list(user_id="user-456")
+            for ms in response.mindspaces:
+                print(f"- {ms.name} ({ms.type})")
+        """
+        params = {}
+        if user_id:
+            params["user_id"] = user_id
+
+        response_data = self._http.get(Routes.MINDSPACES, params=params)
+        return GetMindSpaceListResponse.model_validate(response_data)
+
+    def update(
+        self,
+        mindspace_id: str,
+        name: str,
+        description: Optional[str] = None,
+        project_id: Optional[str] = None,
+        corpus_ids: Optional[list[str]] = None,
+        user_ids: Optional[list[str]] = None,
+    ) -> MindSpace:
+        """
+        Update an existing mindspace.
+
+        Args:
+            mindspace_id: Mindspace ID to update
+            name: Updated mindspace name (max 100 characters)
+            description: Updated description (max 256 characters)
+            project_id: Updated associated project ID
+            corpus_ids: Updated list of corpus IDs
+            user_ids: Updated list of user IDs
+
+        Returns:
+            MindSpace
+
+        Raises:
+            HTTPError: If the API request fails or mindspace not found
+            ValidationError: If parameters are invalid
+
+        Example:
+            # Update mindspace to add more corpus
+            mindspace = client.v1.mindspace.update(
+                mindspace_id="mind-123",
+                name="Engineering Team",
+                corpus_ids=["corp-1", "corp-2", "corp-3"]
+            )
+            print(f"Updated: {mindspace.corpus_ids}")
+        """
+        # Build and validate request
+        request = UpdateMindSpaceRequest(
+            name=name,
+            description=description,
+            project_id=project_id,
+            corpus_ids=corpus_ids or [],
+            user_ids=user_ids or [],
+        )
+
+        # Make API call
+        response = self._http.put(
+            Routes.mindspace(mindspace_id),
+            json=request.model_dump(exclude_none=True),
+        )
+
+        # Parse and validate response
+        return MindSpace.model_validate(response)
+
+    def delete(self, mindspace_id: str) -> None:
+        """
+        Delete a mindspace.
+
+        Args:
+            mindspace_id: Mindspace ID to delete
+
+        Raises:
+            HTTPError: If the API request fails or mindspace not found
+
+        Example:
+            client.v1.mindspace.delete("mind-123")
+            print("Mindspace deleted successfully")
+        """
+        self._http.delete(Routes.mindspace(mindspace_id))
+
+    def get_messages(
+        self,
+        mindspace_id: str,
+        after_id: Optional[str] = None,
+        before_id: Optional[str] = None,
+        limit: int = 50,
+    ) -> MindspaceMessagesResponse:
+        """
+        Fetch chat messages from a mindspace 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:
+            MindspaceMessagesResponse with messages and pagination cursors
+
+        Raises:
+            ValueError: If both after_id and before_id are provided
+            HTTPError: If the API request fails
+
+        Example:
+            # Get latest 50 messages
+            messages = client.v1.mindspace.get_messages(
+                mindspace_id="mind-123"
+            )
+            for msg in messages.chat_histories:
+                print(f"{msg.sent_by_user_id}: {msg.content}")
+
+            # Forward pagination (newer messages)
+            if messages.has_more:
+                more = client.v1.mindspace.get_messages(
+                    mindspace_id="mind-123",
+                    after_id=messages.next_after_id,
+                    limit=50
+                )
+
+            # Backward pagination (older messages)
+            if messages.has_older:
+                older = client.v1.mindspace.get_messages(
+                    mindspace_id="mind-123",
+                    before_id=messages.next_before_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_data = self._http.get(Routes.MINDSPACE_MESSAGES, params=params)
+
+        # Parse and return
+        return MindspaceMessagesResponse.model_validate(response_data)
+
+    def add_users(
+        self,
+        mindspace_id: str,
+        user_ids: list[str],
+    ) -> MindSpace:
+        """
+        Add users to an existing mindspace.
+
+        Args:
+            mindspace_id: Mindspace ID to add users to
+            user_ids: List of user IDs to add to the mindspace
+
+        Returns:
+            MindSpace with updated user list
+
+        Raises:
+            HTTPError: If the API request fails or mindspace not found
+            ValidationError: If parameters are invalid
+
+        Example:
+            # Add users to a group mindspace
+            mindspace = client.v1.mindspace.add_users(
+                mindspace_id="mind-123",
+                user_ids=["user-3", "user-4"]
+            )
+            print(f"Updated users: {mindspace.user_ids}")
+        """
+        # Build and validate request
+        request = AddMindSpaceUsersRequest(user_ids=user_ids)
+
+        # Make API call
+        response = self._http.post(
+            Routes.mindspace_users(mindspace_id),
+            json=request.model_dump(exclude_none=True),
+        )
+
+        # Parse and validate response
+        return MindSpace.model_validate(response)

magick_mind/resources/v1/model.py

@@ -0,0 +1,19 @@
+from typing import Optional, List
+
+from magick_mind.resources.base import BaseResource
+from magick_mind.models.v1.model import ModelsListResponse, Model
+from magick_mind.routes import Routes
+
+
+class ModelsResourceV1(BaseResource):
+    """Resource to interact with the models API."""
+
+    def list(self) -> List[Model]:
+        """
+        List all available models.
+
+        Returns:
+            List[Model]: A list of available models.
+        """
+        response = ModelsListResponse(**self._http.get(Routes.MODELS))
+        return response.data

magick_mind/resources/v1/project.py

@@ -0,0 +1,155 @@
+"""
+Project resource for Magick Mind SDK v1 API.
+
+Provides methods for CRUD operations on projects in the agentic SaaS backend.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+from magick_mind.models.v1.project import (
+    CreateProjectRequest,
+    GetProjectListResponse,
+    Project,
+    UpdateProjectRequest,
+)
+from magick_mind.resources.base import BaseResource
+from magick_mind.routes import Routes
+
+
+class ProjectResourceV1(BaseResource):
+    """
+    Project resource for managing agentic SaaS projects.
+
+    Projects organize corpus and other resources for multi-tenant backends.
+    """
+
+    def create(
+        self,
+        name: str,
+        description: str = "",
+        corpus_ids: Optional[list[str]] = None,
+    ) -> Project:
+        """
+        Create a new project.
+
+        Args:
+            name: Project name (required)
+            description: Project description (optional, max 256 chars)
+            corpus_ids: List of corpus IDs to associate with project
+
+        Returns:
+            Created Project object
+
+        Example:
+            project = client.v1.project.create(
+                name="My Agentic App",
+                description="An AI-powered assistant",
+                corpus_ids=["corpus-123"]
+            )
+            print(f"Created project: {project.id}")
+        """
+        request = CreateProjectRequest(
+            name=name,
+            description=description,
+            corpus_ids=corpus_ids or [],
+        )
+
+        response = self._http.post(Routes.PROJECTS, json=request.model_dump())
+        return Project.model_validate(response)
+
+    def get(self, project_id: str) -> Project:
+        """
+        Get a project by ID.
+
+        Args:
+            project_id: The project ID to retrieve
+
+        Returns:
+            Project object
+
+        Example:
+            project = client.v1.project.get(project_id="proj-123")
+            print(f"Project name: {project.name}")
+        """
+        response = self._http.get(Routes.project(project_id))
+        return Project.model_validate(response)
+
+    def list(self, created_by_user_id: Optional[str] = None) -> list[Project]:
+        """
+        List projects, optionally filtered by creator user ID.
+
+        Args:
+            created_by_user_id: Optional user ID to filter projects created by this user
+
+        Returns:
+            List of Project objects
+
+        Example:
+            # List all accessible projects
+            projects = client.v1.project.list()
+
+            # List projects created by specific user
+            user_projects = client.v1.project.list(created_by_user_id="user-123")
+            for project in user_projects:
+                print(f"- {project.name}")
+        """
+        params = {}
+        if created_by_user_id:
+            params["user_id"] = created_by_user_id
+
+        response = self._http.get(Routes.PROJECTS, params=params)
+        list_response = GetProjectListResponse.model_validate(response)
+        return [Project.model_validate(p) for p in list_response.data]
+
+    def update(
+        self,
+        project_id: str,
+        name: str,
+        description: str = "",
+        corpus_ids: Optional[list[str]] = None,
+    ) -> Project:
+        """
+        Update an existing project.
+
+        Args:
+            project_id: The project ID to update
+            name: New project name (required)
+            description: New project description (optional, max 256 chars)
+            corpus_ids: New list of corpus IDs to associate with project
+
+        Returns:
+            Updated Project object
+
+        Example:
+            updated = client.v1.project.update(
+                project_id="proj-123",
+                name="Updated Name",
+                description="Updated description",
+                corpus_ids=["corpus-123", "corpus-456"]
+            )
+            print(f"Updated project: {updated.name}")
+        """
+        request = UpdateProjectRequest(
+            name=name,
+            description=description,
+            corpus_ids=corpus_ids or [],
+        )
+
+        response = self._http.put(Routes.project(project_id), json=request.model_dump())
+        return Project(**response)
+
+    def delete(self, project_id: str) -> None:
+        """
+        Delete a project.
+
+        Args:
+            project_id: The project ID to delete
+
+        Example:
+            client.v1.project.delete(project_id="proj-123")
+            print("Project deleted successfully")
+        """
+        self._http.delete(Routes.project(project_id))

magick_mind/routes.py

@@ -0,0 +1,76 @@
+"""Centralized API route constants.
+
+All API endpoint paths are defined here to ensure consistency
+across the SDK and make updates easier when the API changes.
+"""
+
+
+class Routes:
+    """API v1 route paths for Bifrost."""
+
+    # Auth endpoints
+    AUTH_LOGIN = "/v1/auth/login"
+    AUTH_REFRESH = "/v1/auth/refresh"
+
+    # Chat endpoints
+    CHAT = "/v1/chat/magickmind"
+    MODELS = "/v1/models"
+
+    # Mindspace endpoints
+    MINDSPACES = "/v1/mindspaces"
+    MINDSPACE_MESSAGES = "/v1/mindspaces/messages"
+
+    @staticmethod
+    def mindspace(mindspace_id: str) -> str:
+        """Get path for a specific mindspace."""
+        return f"/v1/mindspaces/{mindspace_id}"
+
+    @staticmethod
+    def mindspace_users(mindspace_id: str) -> str:
+        """Get path to add users to a specific mindspace."""
+        return f"/v1/mindspaces/{mindspace_id}/users"
+
+    # Project endpoints
+    PROJECTS = "/v1/projects"
+
+    @staticmethod
+    def project(project_id: str) -> str:
+        """Get path for a specific project."""
+        return f"/v1/projects/{project_id}"
+
+    # End User endpoints
+    END_USERS = "/v1/end-users"
+
+    @staticmethod
+    def end_user(end_user_id: str) -> str:
+        """Get path for a specific end user."""
+        return f"/v1/end-users/{end_user_id}"
+
+    # Corpus endpoints
+    CORPUS = "/v1/corpus"
+
+    @staticmethod
+    def corpus(corpus_id: str) -> str:
+        """Get path for a specific corpus."""
+        return f"/v1/corpus/{corpus_id}"
+
+    @staticmethod
+    def corpus_artifacts_finalize(corpus_id: str) -> str:
+        """Get path for corpus artifact finalization."""
+        return f"/v1/corpus/{corpus_id}/artifacts/finalize"
+
+    # Artifact endpoints
+    ARTIFACTS = "/v1/artifacts"
+    ARTIFACTS_PRESIGN = "/v1/artifacts/presign"
+    ARTIFACTS_FINALIZE = "/v1/artifacts/finalize"
+
+    @staticmethod
+    def artifact(artifact_id: str) -> str:
+        """Get path for a specific artifact."""
+        return f"/v1/artifacts/{artifact_id}"
+
+    # API Keys endpoints
+    KEYS = "/v1/keys"
+
+    # History endpoints (alias for mindspace messages)
+    HISTORY_MESSAGES = "/v1/mindspaces/messages"