magickmind 0.1.1__py3-none-any.whl

magick_mind/models/v1/artifact.py

@@ -0,0 +1,151 @@
+"""
+Artifact models for Magick Mind SDK v1 API.
+
+Provides Pydantic models for file upload and artifact management using
+presigned S3 URLs and webhook-based completion confirmation.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Artifact(BaseModel):
+    """
+    Canonical artifact model representing an uploaded file.
+
+    Artifacts are files (documents, images, etc.) uploaded to S3 and
+    associated with a corpus or other container in the bifrost backend.
+    """
+
+    model_config = ConfigDict(
+        extra="allow"
+    )  # Allow additional fields from API responses
+
+    id: str = Field(..., description="Unique artifact identifier")
+    bucket: str = Field(..., description="S3 bucket name")
+    key: str = Field(..., description="S3 object key")
+    s3_url: str = Field(..., description="S3 URL (s3://bucket/key)")
+    content_type: str = Field(..., description="MIME type of the artifact")
+    size_bytes: int = Field(..., description="Size in bytes")
+    etag: Optional[str] = Field(None, description="S3 ETag")
+    version_id: Optional[str] = Field(None, description="S3 version ID")
+    status: str = Field(
+        ..., description="Artifact status (uploaded, processing, ready, failed)"
+    )
+    corpus_id: Optional[str] = Field(None, description="Associated corpus ID")
+    end_user_id: Optional[str] = Field(
+        None, description="End user who uploaded the artifact"
+    )
+    created_by: Optional[str] = Field(
+        None, description="Account ID that created the artifact"
+    )
+    created_at: Optional[int] = Field(
+        None, description="Creation timestamp (unix seconds)"
+    )
+    updated_at: Optional[int] = Field(
+        None, description="Last update timestamp (unix seconds)"
+    )
+    error_code: Optional[str] = Field(
+        None, description="Error code if status is failed"
+    )
+
+
+class PresignArtifactRequest(BaseModel):
+    """Request for obtaining a presigned S3 upload URL."""
+
+    file_name: str = Field(..., description="Name of the file to upload")
+    content_type: str = Field(..., description="MIME type of the file")
+    size_bytes: int = Field(..., description="File size in bytes", gt=0)
+    end_user_id: Optional[str] = Field(
+        None, description="End user identifier (optional)"
+    )
+    corpus_id: Optional[str] = Field(
+        None, description="Corpus to associate with (optional)"
+    )
+
+
+class PresignArtifactResponse(BaseModel):
+    """
+    Response containing presigned upload URL and metadata.
+    """
+
+    success: Optional[bool] = Field(None, description="Request success status")
+    message: Optional[str] = Field(None, description="Response message")
+    id: Optional[str] = Field(None, description="Artifact ID (Relaxed)")
+    bucket: Optional[str] = Field(None, description="S3 bucket (Relaxed)")
+    key: Optional[str] = Field(None, description="S3 object key (Relaxed)")
+    s3_url: Optional[str] = Field(None, description="S3 URL (Relaxed)")
+    upload_url: Optional[str] = Field(None, description="Presigned PUT URL (Relaxed)")
+    expires_at: Optional[int] = Field(None, description="URL expiration time (Relaxed)")
+    required_headers: Optional[dict[str, str]] = Field(
+        None, description="HTTP headers (Relaxed)"
+    )
+
+
+class GetArtifactResponse(BaseModel):
+    """Response for getting a single artifact by ID."""
+
+    success: bool = Field(..., description="Request success status")
+    message: str = Field(..., description="Response message")
+    artifact: Artifact = Field(..., description="The artifact data")
+
+
+class ListArtifactsResponse(BaseModel):
+    """Response for listing/querying artifacts."""
+
+    success: bool = Field(..., description="Request success status")
+    message: str = Field(..., description="Response message")
+    artifacts: list[Artifact] = Field(..., description="List of artifacts")
+
+
+class DeleteArtifactResponse(BaseModel):
+    """Response for deleting an artifact."""
+
+    success: bool = Field(..., description="Request success status")
+    message: str = Field(..., description="Response message")
+
+
+class FinalizeArtifactRequest(BaseModel):
+    """
+    Client-driven finalize request (fallback when webhook is unavailable).
+    """
+
+    artifact_id: str = Field(..., description="Artifact ID")
+    bucket: str = Field(..., description="S3 bucket")
+    key: str = Field(..., description="S3 object key")
+    version_id: Optional[str] = Field(None, description="S3 version ID")
+    size_bytes: Optional[int] = Field(None, description="Actual uploaded size")
+    content_type: Optional[str] = Field(None, description="Content type")
+    etag: Optional[str] = Field(None, description="S3 ETag")
+    checksum_sha256: Optional[str] = Field(None, description="SHA256 checksum")
+
+
+class FinalizeArtifactResponse(BaseModel):
+    """Response for finalize operation."""
+
+    success: Optional[bool] = Field(None, description="Request success status")
+    message: Optional[str] = Field(None, description="Response message")
+
+
+class ArtifactWebhookPayload(BaseModel):
+    """
+    Webhook payload sent from S3 Lambda or client finalize.
+
+    This is the shape of data sent to the webhook endpoint after
+    an artifact upload is complete.
+    """
+
+    artifact_id: str = Field(..., description="Artifact ID")
+    corpus_id: Optional[str] = Field(None, description="Corpus ID if applicable")
+    bucket: str = Field(..., description="S3 bucket")
+    key: str = Field(..., description="S3 object key")
+    version_id: Optional[str] = Field(None, description="S3 version ID")
+    size_bytes: Optional[int] = Field(None, description="File size in bytes")
+    content_type: Optional[str] = Field(None, description="MIME type")
+    etag: Optional[str] = Field(None, description="S3 ETag")
+    checksum_sha256: Optional[str] = Field(None, description="SHA256 checksum")
+    status: str = Field(..., description="Status: uploaded, processing, ready, failed")
+    error_code: Optional[str] = Field(None, description="Error code if failed")

magick_mind/models/v1/chat.py

@@ -0,0 +1,104 @@
+"""V1 chat API models.
+
+These models mirror the bifrost API types for /v1/magickmind/chat endpoint.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_serializer
+
+
+class ConfigSchema(BaseModel):
+    """
+    Configuration for chat request.
+
+    Contains model selection and compute settings.
+    """
+
+    fast_model_id: str = Field(..., description="Model ID for fast brain")
+    smart_model_ids: list[str] = Field(..., description="Model IDs for smart brain")
+    compute_power: int = Field(default=0, description="Compute power setting (0-100)")
+
+
+class ChatSendRequest(BaseModel):
+    """
+    Request to send a chat message to a mindspace.
+
+    Example:
+        request = ChatSendRequest(
+            api_key="sk-...",
+            mindspace_id="mind-123",
+            message="Hello!",
+            enduser_id="user-456",
+            config=ConfigSchema(
+                fast_model_id="gpt-4",
+                smart_model_ids=["gpt-4"],
+                compute_power=50,
+            ),
+        )
+    """
+
+    api_key: str = Field(..., description="API key for LLM access")
+    mindspace_id: str = Field(..., description="Mindspace/chat conversation ID")
+    message: str = Field(..., description="User message text to send")
+    enduser_id: str = Field(..., description="End-user identifier")
+    config: ConfigSchema = Field(..., description="Model configuration")
+    reply_to_message_id: Optional[str] = Field(
+        default=None, description="ID of message being replied to"
+    )
+    additional_context: Optional[str] = Field(
+        default=None, description="Additional context for the message"
+    )
+    artifact_ids: Optional[list[str]] = Field(
+        default=None, description="List of artifact IDs to attach to message"
+    )
+
+    # =========================================================================
+    # Serializers: Transform None → default values for API contract compliance
+    # SDK users can omit these fields, but API expects them in the payload
+    # =========================================================================
+
+    @field_serializer("artifact_ids")
+    def serialize_artifact_ids(self, v: list[str] | None) -> list[str]:
+        """API requires this field; default to empty list if not provided."""
+        return v or []
+
+
+class ChatPayload(BaseModel):
+    """
+    Chat response payload schema.
+
+    Flexible data container for chat response with message metadata.
+    Can be extended to support various response formats.
+    """
+
+    message_id: Optional[str] = Field(
+        None, description="Generated message ID (Relaxed)"
+    )
+    task_id: Optional[str] = Field(None, description="Associated task ID (Relaxed)")
+    content: Optional[str] = Field(None, description="AI response text (Relaxed)")
+    reply_to: Optional[str] = Field(
+        default=None, description="ID of message being replied to"
+    )
+
+
+class ChatSendResponse(BaseModel):
+    """
+    Response from sending a chat message.
+
+    Matches Bifrost ChatResponse structure with only content field.
+
+    Example:
+        {
+            "content": {
+                "message_id": "msg-789",
+                "task_id": "task-123",
+                "content": "Hello! How can I help you?",
+                "reply_to": null
+            }
+        }
+    """
+
+    content: Optional[ChatPayload] = Field(
+        default=None, description="Chat response payload"
+    )

magick_mind/models/v1/corpus.py

@@ -0,0 +1,82 @@
+"""
+Corpus models for Magick Mind SDK v1 API.
+
+Provides Pydantic models for corpus (knowledge base) management.
+Corpus represents a collection of artifacts that can be used for
+RAG (Retrieval Augmented Generation) workflows.
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from magick_mind.models.v1.end_user import PageInfo
+
+
+class Corpus(BaseModel):
+    """
+    Canonical corpus model representing a knowledge base.
+
+    A corpus is a collection of artifacts (documents, files) that can be
+    used for semantic search and retrieval augmented generation.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(..., description="Unique corpus identifier")
+    name: str = Field(..., description="Corpus name")
+    description: Optional[str] = Field(None, description="Corpus description")
+    artifact_ids: Optional[list[str]] = Field(
+        None, description="List of artifact IDs in this corpus"
+    )
+    created_by: Optional[str] = Field(
+        None, description="Account ID that created the corpus"
+    )
+    created_at: Optional[str] = Field(
+        None, description="Creation timestamp (ISO format)"
+    )
+    updated_at: Optional[str] = Field(
+        None, description="Last update timestamp (ISO format)"
+    )
+
+
+class CreateCorpusRequest(BaseModel):
+    """Request for creating a new corpus."""
+
+    name: Optional[str] = Field(None, description="Corpus name (Relaxed)")
+    description: Optional[str] = Field(None, description="Corpus description (Relaxed)")
+    artifact_ids: Optional[list[str]] = Field(
+        None, description="Optional list of artifact IDs (Relaxed)"
+    )
+
+
+class ListCorpusResponse(BaseModel):
+    """
+    Response for listing corpus.
+
+    Matches Bifrost's {data: list[Corpus], paging: PageInfo} structure.
+    """
+
+    data: list[Corpus] = Field(..., description="List of corpus")
+    paging: "PageInfo" = Field(..., description="Pagination information")
+
+
+class UpdateCorpusRequest(BaseModel):
+    """Request for updating an existing corpus."""
+
+    name: Optional[str] = Field(None, description="Corpus name (Relaxed)")
+    description: Optional[str] = Field(None, description="Corpus description (Relaxed)")
+    artifact_ids: Optional[list[str]] = Field(
+        None, description="List of artifact IDs (Relaxed)"
+    )
+
+
+class DeleteCorpusResponse:
+    """
+    Response for deleting a corpus.
+
+    Bifrost returns 204 No Content with no response body.
+    """
+
+    pass

magick_mind/models/v1/end_user.py

@@ -0,0 +1,75 @@
+"""
+End user models for Magick Mind SDK v1 API.
+
+Mirrors Bifrost's /v1/end-users endpoint request/response schemas.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from magick_mind.models.common import Cursors, PageInfo
+
+
+class EndUser(BaseModel):
+    """
+    End user schema from Bifrost.
+
+    Represents an end user in a multi-tenant agentic SaaS application.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(..., description="End user ID")
+    name: str = Field(..., description="End user name")
+    external_id: Optional[str] = Field(
+        default=None,
+        description="Optional external ID for mapping to external systems",
+    )
+    tenant_id: str = Field(..., description="Tenant ID this end user belongs to")
+    created_by: Optional[str] = Field(default=None, description="User ID of creator")
+    updated_by: Optional[str] = Field(
+        default=None, description="User ID of last updater"
+    )
+    created_at: str = Field(..., description="Creation timestamp (ISO8601)")
+    updated_at: str = Field(..., description="Last update timestamp (ISO8601)")
+
+
+class CreateEndUserRequest(BaseModel):
+    """
+    Request schema for creating a new end user.
+    """
+
+    name: str = Field(..., description="End user name (required)")
+    external_id: Optional[str] = Field(
+        default=None,
+        description="Optional external ID for mapping to external systems",
+    )
+    tenant_id: Optional[str] = Field(None, description="Tenant ID (Relaxed)")
+    actor_id: Optional[str] = Field(None, description="Actor ID (Relaxed)")
+
+
+class QueryEndUserResponse(BaseModel):
+    """
+    Response schema for querying end users.
+
+    Uses new pagination pattern: {data: [], paging: {}}
+    """
+
+    data: list[EndUser] = Field(
+        default_factory=list, description="List of end users matching the query"
+    )
+    paging: PageInfo = Field(..., description="Pagination information")
+
+
+class UpdateEndUserRequest(BaseModel):
+    """
+    Request schema for updating an end user.
+    """
+
+    name: Optional[str] = Field(default=None, description="End user name (optional)")
+    external_id: Optional[str] = Field(
+        default=None,
+        description="External ID for mapping to external systems (optional)",
+    )
+    tenant_id: Optional[str] = Field(None, description="Tenant ID (Relaxed)")

magick_mind/models/v1/history.py

@@ -0,0 +1,94 @@
+"""
+History models for Magick Mind SDK v1 API.
+
+Mirrors Bifrost's /v1/mindspaces/messages endpoint response.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from magick_mind.models.common import Cursors, PageInfo
+
+
+class ChatHistoryMessage(BaseModel):
+    """
+    Individual chat history message from Bifrost.
+
+    Maps to ChatHistoryItem from Bifrost's magickmind.api.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: Optional[str] = Field(None, description="Message ID")
+    mindspace_id: Optional[str] = Field(
+        None, description="Mindspace this message belongs to"
+    )
+    sent_by_user_id: Optional[str] = Field(
+        None, description="User who sent the message"
+    )
+    content: Optional[str] = Field(None, description="Message content/text")
+    reply_to_message_id: Optional[str] = Field(
+        default=None, description="ID of message being replied to"
+    )
+    status: Optional[str] = Field(None, description="Message status")
+    created_at: Optional[str] = Field(
+        None, alias="create_at", description="Creation timestamp (RFC3339)"
+    )
+    updated_at: Optional[str] = Field(
+        None, alias="update_at", description="Update timestamp (RFC3339)"
+    )
+
+
+class HistoryResponse(BaseModel):
+    """
+    Response from Bifrost's /v1/mindspaces/messages endpoint.
+
+    Uses standardized Bifrost pagination format:
+    {
+        "data": [...],
+        "paging": {
+            "cursors": {"after": "...", "before": "..."},
+            "has_more": true,
+            "has_previous": false
+        }
+    }
+    """
+
+    data: list[ChatHistoryMessage] = Field(
+        default_factory=list, description="List of chat messages"
+    )
+    paging: PageInfo = Field(
+        default_factory=lambda: PageInfo(
+            cursors=Cursors(after=None, before=None),
+            has_more=False,
+            has_previous=False,
+        ),
+        description="Pagination information",
+    )
+
+    # Computed convenience properties for backward compatibility
+    @property
+    def chat_histories(self) -> list[ChatHistoryMessage]:
+        """Alias for data field (backward compatibility)."""
+        return self.data
+
+    @property
+    def has_more(self) -> bool:
+        """True if more messages exist forward."""
+        return self.paging.has_more
+
+    @property
+    def has_older(self) -> bool:
+        """True if more messages exist backward."""
+        return self.paging.has_previous
+
+    @property
+    def next_after_id(self) -> Optional[str]:
+        """Cursor for forward pagination."""
+        return self.paging.cursors.after if self.paging.cursors else None
+
+    @property
+    def next_before_id(self) -> Optional[str]:
+        """Cursor for backward pagination."""
+        return self.paging.cursors.before if self.paging.cursors else None

magick_mind/models/v1/mindspace.py

@@ -0,0 +1,130 @@
+"""V1 mindspace API models.
+
+These models mirror the bifrost API types for /v1/mindspaces endpoint.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from magick_mind.models.common import BaseResponse
+from magick_mind.models.v1.history import HistoryResponse
+
+
+# Type alias for mindspace type enum (uppercase to match apidog)
+MindSpaceType = Literal["PRIVATE", "GROUP"]
+
+
+class MindSpace(BaseModel):
+    """
+    Mindspace schema model.
+
+    Represents a mindspace container that can be private (single user)
+    or group (multiple users), with attached corpus for knowledge.
+
+    Example:
+        {
+            "id": "mind-123",
+            "name": "Engineering Team",
+            "description": "Team workspace",
+            "project_id": "proj-456",
+            "corpus_ids": ["corp-1", "corp-2"],
+            "user_ids": ["user-1", "user-2"],
+            "type": "GROUP",
+            "created_by": "user-1",
+            "updated_by": "user-1",
+            "created_at": "2025-12-16T09:00:00Z",
+            "updated_at": "2025-12-16T09:00:00Z"
+        }
+    """
+
+    id: str = Field(..., description="Mindspace ID")
+    name: str = Field(..., description="Mindspace name")
+    description: Optional[str] = Field(None, description="Mindspace description")
+    project_id: str = Field(..., description="Associated project ID")
+    corpus_ids: Optional[list[str]] = Field(
+        None,
+        description="List of corpus IDs attached to this mindspace",
+    )
+    user_ids: Optional[list[str]] = Field(
+        None,
+        description="List of user IDs with access to this mindspace",
+    )
+    type: MindSpaceType = Field(..., description="Mindspace type: 'PRIVATE' or 'GROUP'")
+    created_by: Optional[str] = Field(
+        None, description="User ID who created the mindspace"
+    )
+    updated_by: Optional[str] = Field(
+        None, description="User ID who last updated the mindspace"
+    )
+    created_at: Optional[str] = Field(None, description="Creation timestamp (RFC3339)")
+    updated_at: Optional[str] = Field(
+        None, description="Last update timestamp (RFC3339)"
+    )
+
+
+class CreateMindSpaceRequest(BaseModel):
+    """
+    Request to create a new mindspace.
+    """
+
+    name: Optional[str] = Field(
+        None, description="Mindspace name (Relaxed)", max_length=100
+    )
+    type: Optional[MindSpaceType] = Field(None, description="Mindspace type (Relaxed)")
+    description: Optional[str] = Field(
+        default=None, description="Mindspace description", max_length=256
+    )
+    project_id: Optional[str] = Field(default=None, description="Associated project ID")
+    corpus_ids: list[str] = Field(
+        default_factory=list, description="List of corpus IDs to attach"
+    )
+    user_ids: list[str] = Field(
+        default_factory=list, description="List of user IDs to grant access"
+    )
+
+
+class GetMindSpaceListResponse(BaseModel):
+    """
+    Response from listing mindspaces.
+    """
+
+    mindspaces: list[MindSpace] = Field(
+        default_factory=list, description="List of mindspaces"
+    )
+
+
+class UpdateMindSpaceRequest(BaseModel):
+    """
+    Request to update an existing mindspace.
+    """
+
+    name: Optional[str] = Field(
+        None, description="Mindspace name (Relaxed)", max_length=100
+    )
+    description: Optional[str] = Field(
+        default=None, description="Mindspace description", max_length=256
+    )
+    project_id: Optional[str] = Field(default=None, description="Associated project ID")
+    corpus_ids: list[str] = Field(
+        default_factory=list, description="List of corpus IDs to attach"
+    )
+    user_ids: list[str] = Field(
+        default_factory=list, description="List of user IDs to grant access"
+    )
+
+
+class AddMindSpaceUsersRequest(BaseModel):
+    """
+    Request to add users to an existing mindspace.
+    """
+
+    user_ids: list[str] = Field(
+        ..., description="List of user IDs to add to the mindspace"
+    )
+
+
+# Reuse HistoryResponse for messages endpoint since it's the same structure
+MindspaceMessagesResponse = HistoryResponse

magick_mind/models/v1/model.py

@@ -0,0 +1,25 @@
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+
+class Model(BaseModel):
+    """Model information"""
+
+    id: Optional[str] = Field(None, description="The model identifier, e.g. 'gpt-4o'")
+    object: str = Field("model", description="The object type, always 'model'")
+    created: Optional[int] = Field(
+        None, description="The unix timestamp when the model was created"
+    )
+    owned_by: Optional[str] = Field(
+        None, description="The organization that owns the model"
+    )
+    provider: Optional[str] = Field(None, description="The provider of the model")
+
+
+class ModelsListResponse(BaseModel):
+    """Response containing a list of models"""
+
+    object: str = Field("list", description="The object type, always 'list'")
+    data: List[Model] = Field(
+        default_factory=list, description="The list of available models"
+    )