magickmind 0.1.1__py3-none-any.whl

magick_mind/models/v1/project.py

@@ -0,0 +1,73 @@
+"""
+Project models for Magick Mind SDK v1 API.
+
+Mirrors Bifrost's /v1/projects endpoint request/response schemas.
+"""
+
+from typing import Optional, List
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from magick_mind.models.v1.end_user import PageInfo
+
+
+class Project(BaseModel):
+    """
+    Project schema from Bifrost.
+
+    Represents an agentic SaaS project with associated corpus IDs.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(..., description="Project ID")
+    name: str = Field(..., description="Project name")
+    description: Optional[str] = Field(None, description="Project description")
+    corpus_ids: Optional[list[str]] = Field(
+        None,
+        description="List of corpus IDs associated with this project",
+    )
+    created_by: str = Field(..., description="User ID of creator")
+    created_at: str = Field(..., description="Creation timestamp (ISO8601)")
+    updated_at: str = Field(..., description="Last update timestamp (ISO8601)")
+
+
+class CreateProjectRequest(BaseModel):
+    """
+    Request schema for creating a new project.
+    """
+
+    name: str = Field(..., description="Project name (required)")
+    description: str = Field(
+        default="", description="Project description (optional, max 256 chars)"
+    )
+    corpus_ids: list[str] = Field(
+        default_factory=list, description="List of corpus IDs to associate with project"
+    )
+
+
+class GetProjectListResponse(BaseModel):
+    """
+    Response schema for listing projects.
+
+    Matches Bifrost's {data: list[Project], paging: PageInfo} structure.
+    """
+
+    data: list[Project] = Field(..., description="List of projects")
+    paging: PageInfo = Field(..., description="Pagination information")
+
+
+class UpdateProjectRequest(BaseModel):
+    """
+    Request schema for updating a project.
+
+    Both name and corpus_ids are REQUIRED (matching Bifrost API).
+    """
+
+    name: str = Field(..., description="Project name (required)")
+    description: Optional[str] = Field(
+        None, description="Project description (optional, max 256 chars)"
+    )
+    corpus_ids: list[str] = Field(
+        ..., description="List of corpus IDs to associate with project (required)"
+    )

magick_mind/realtime/__init__.py

@@ -0,0 +1,5 @@
+"""Realtime module for WebSocket connections using Centrifugo."""
+
+from .client import RealtimeClient
+
+__all__ = ["RealtimeClient"]

magick_mind/realtime/client.py

@@ -0,0 +1,202 @@
+"""Realtime client implementation using centrifuge-python."""
+
+import asyncio
+import base64
+import json
+import logging
+from typing import Optional, List
+
+from centrifuge import (
+    Client,
+    ClientEventHandler,
+    PublicationContext,
+    SubscriptionEventHandler,
+)
+
+from ..auth.base import AuthProvider
+from ..exceptions import MagickMindError
+
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_jwt_sub(token: str) -> Optional[str]:
+    """
+    Decode JWT without verification to extract 'sub'.
+    Returns None if parsing fails.
+    """
+    try:
+        parts = token.split(".")
+        if len(parts) < 2:
+            return None
+        payload_b64 = parts[1]
+        payload_b64 += "=" * ((4 - len(payload_b64) % 4) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64).decode("utf-8"))
+        sub = payload.get("sub")
+        return sub if isinstance(sub, str) else None
+    except Exception:
+        return None
+
+
+class _DelegatingSubscriptionHandler(SubscriptionEventHandler):
+    """Routes client-side subscription publications to ClientEventHandler.on_publication."""
+
+    def __init__(self, client_handler: ClientEventHandler, channel: str):
+        self._client_handler = client_handler
+        self._channel = channel
+
+    async def on_publication(self, ctx: PublicationContext) -> None:
+        """Route client-side publication to the ClientEventHandler."""
+        logger.debug(f"Publication on {self._channel}: {ctx.pub.data}")
+
+        # Wrap in adapter for ClientEventHandler
+        server_ctx = _PublicationAdapter(ctx, self._channel)
+        try:
+            await self._client_handler.on_publication(server_ctx)
+        except Exception:
+            logger.exception(f"Error in on_publication handler for {self._channel}")
+
+    async def on_subscribed(self, ctx) -> None:
+        logger.info(f"✅ Subscribed to channel: {self._channel}")
+
+    async def on_unsubscribed(self, ctx) -> None:
+        logger.info(f"Unsubscribed from channel: {self._channel}")
+
+    async def on_error(self, ctx) -> None:
+        logger.error(f"Subscription error on {self._channel}: {ctx}")
+
+
+class _PublicationAdapter:
+    """Adapts PublicationContext to look like ServerPublicationContext."""
+
+    def __init__(self, client_ctx: PublicationContext, channel: str):
+        self.pub = client_ctx.pub
+        self.channel = channel
+
+
+class RealtimeClient:
+    """
+    Async client for real-time features using WebSockets.
+    Uses pure client-side subscriptions for reliability.
+    """
+
+    def __init__(self, auth: AuthProvider, ws_url: str):
+        self.auth = auth
+        self.ws_url = ws_url
+        self._client: Optional[Client] = None
+        self._events: Optional[ClientEventHandler] = None
+
+    async def _get_token(self) -> str:
+        """Get token wrapper for centrifuge client."""
+        try:
+            return await self.auth.get_token_async()
+        except Exception:
+            raise
+
+    async def connect(self, events: Optional[ClientEventHandler] = None) -> None:
+        """Connect to the realtime service."""
+        if self._client:
+            return
+
+        self._events = events or ClientEventHandler()
+
+        self._client = Client(
+            self.ws_url,
+            events=self._events,
+            get_token=self._get_token,
+            use_protobuf=False,
+        )
+
+        await self._client.connect()
+        await self._client.ready()
+
+    async def disconnect(self) -> None:
+        """Disconnect from the realtime service."""
+        if self._client:
+            await self._client.disconnect()
+            self._client = None
+
+    async def subscribe(self, target_user_id: str) -> None:
+        """
+        Subscribe to a user's channel using client-side subscription.
+
+        Args:
+            target_user_id: ID of the user to subscribe to
+        """
+        if not self._client:
+            raise MagickMindError("Realtime client not connected")
+
+        # Build channel name
+        token = await self._get_token()
+        service_user_id = _extract_jwt_sub(token)
+        if not service_user_id:
+            raise MagickMindError("Failed to extract service_user_id from JWT")
+
+        channel = f"personal:{target_user_id}#{service_user_id}"
+        logger.debug(f"Subscribing to channel: {channel}")
+
+        # Create client-side subscription with handler
+        await self._ensure_subscription(channel)
+
+    async def _ensure_subscription(self, channel: str) -> None:
+        """Ensure client-side subscription exists with proper event handler."""
+        if not self._client or not self._events:
+            return
+
+        sub_events = _DelegatingSubscriptionHandler(self._events, channel)
+
+        try:
+            existing_sub = self._client.get_subscription(channel)
+            if existing_sub:
+                state = getattr(existing_sub, "state", None)
+                state_name = getattr(state, "name", "")
+                if state_name == "UNSUBSCRIBED":
+                    await existing_sub.subscribe()
+                    logger.info(f"Resubscribed to {channel}")
+            else:
+                sub = self._client.new_subscription(channel, events=sub_events)
+                await sub.subscribe()
+                logger.info(f"Subscribed to {channel}")
+        except Exception as e:
+            logger.error(f"Subscription failed for {channel}: {e}")
+            raise MagickMindError(f"Subscribe failed: {e}")
+
+    async def subscribe_many(self, target_user_ids: List[str]) -> None:
+        """Subscribe to multiple users concurrently."""
+        if not target_user_ids:
+            return
+
+        tasks = [self.subscribe(uid) for uid in target_user_ids]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        errors = [r for r in results if isinstance(r, Exception)]
+        if errors:
+            raise errors[0]
+
+    async def unsubscribe(self, target_user_id: str) -> None:
+        """Unsubscribe from a user's channel."""
+        if not self._client:
+            raise MagickMindError("Realtime client not connected")
+
+        token = await self._get_token()
+        service_user_id = _extract_jwt_sub(token)
+        if not service_user_id:
+            return
+
+        channel = f"personal:{target_user_id}#{service_user_id}"
+        sub = self._client.get_subscription(channel)
+        if sub:
+            await sub.unsubscribe()
+
+    async def unsubscribe_many(self, target_user_ids: List[str]) -> None:
+        """Unsubscribe from multiple users concurrently."""
+        if not target_user_ids:
+            return
+
+        tasks = [self.unsubscribe(uid) for uid in target_user_ids]
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    @property
+    def client(self) -> Optional[Client]:
+        """Get underlying centrifuge client."""
+        return self._client

magick_mind/realtime/handler.py

@@ -0,0 +1,122 @@
+"""
+High-level event handler for Magick Mind Realtime Client.
+Abstracts away Centrifugo channel parsing details.
+"""
+
+import logging
+from typing import Any, Optional
+
+from centrifuge import (
+    ClientEventHandler,
+    ServerPublicationContext,
+    ServerSubscribedContext,
+    ServerSubscribingContext,
+    ServerUnsubscribedContext,
+    ConnectedContext,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class RealtimeEventHandler(ClientEventHandler):
+    """
+    Abstract base class for handling Realtime SDK events.
+
+    Subclass this and override `on_message` to handle incoming user updates.
+    The SDK handles channel parsing and data extraction for you.
+    """
+
+    async def on_connected(self, ctx: ConnectedContext) -> None:
+        """Called when connected to the Realtime Gateway."""
+        logger.info(f"✅ Connected to Realtime Gateway (Client ID: {ctx.client})")
+
+    async def on_subscribed(self, ctx: ServerSubscribedContext) -> None:
+        """Called when server-side subscription is established."""
+        logger.info(f"✅ Server-side subscribed to channel: {ctx.channel}")
+
+    async def on_subscribing(self, ctx: ServerSubscribingContext) -> None:
+        """Called when server-side subscription is in progress."""
+        logger.debug(f"Subscribing to server-side channel: {ctx.channel}")
+
+    async def on_unsubscribed(self, ctx: ServerUnsubscribedContext) -> None:
+        """Called when unsubscribed from server-side subscription."""
+        logger.info(f"Unsubscribed from server-side channel: {ctx.channel}")
+
+    async def on_message(self, user_id: str, payload: Any) -> None:
+        """
+        Called when a message is received for a specific user.
+
+        Args:
+            user_id: The ID of the end-user this message is for.
+            payload: The message content (dict, string, etc).
+        """
+        pass
+
+    async def on_raw_message(self, channel: str, payload: Any) -> None:
+        """
+        Called when a message is received but the user ID could not be parsed,
+        or for non-standard channels.
+        """
+        pass
+
+    async def on_publication(self, ctx: ServerPublicationContext) -> None:
+        """
+        Internal handler. Parses channel context and dispatches to on_message.
+        """
+        logger.info(f"📨 Publication received on channel: {ctx.channel}")
+
+        channel = self._extract_channel(ctx)
+        data = self._extract_data(ctx)
+
+        logger.debug(f"Channel: {channel}, Data: {data}")
+
+        user_id = self._extract_user_id(channel)
+
+        if user_id:
+            await self.on_message(user_id, data)
+        else:
+            await self.on_raw_message(channel, data)
+
+    def _extract_channel(self, ctx: ServerPublicationContext) -> str:
+        """
+        Extract channel from context in a version-resilient way.
+        """
+        # Try direct attribute
+        ch = getattr(ctx, "channel", None)
+        if ch:
+            return ch
+
+        # Try inside pub object
+        pub = getattr(ctx, "pub", None)
+        if pub:
+            return getattr(pub, "channel", "")
+
+        return ""
+
+    def _extract_data(self, ctx: ServerPublicationContext) -> Any:
+        """
+        Extract data payload from context.
+        """
+        pub = getattr(ctx, "pub", None)
+        return getattr(pub, "data", None) if pub else None
+
+    def _extract_user_id(self, channel: str) -> Optional[str]:
+        """
+        Parse User ID from channel string.
+        Format confirmed as: personal:<target_user_id>#<service_user_id>
+        """
+        if not channel:
+            return None
+
+        # 1. Remove namespace (personal:)
+        if ":" in channel:
+            without_ns = channel.split(":", 1)[1]
+        else:
+            without_ns = channel
+
+        # 2. Extract first part before '#'
+        # "user_123#service_456" -> "user_123"
+        if "#" in without_ns:
+            return without_ns.split("#")[0]
+
+        return without_ns

magick_mind/resources/README.md

@@ -0,0 +1,201 @@
+# Extending the SDK with Resource Clients
+
+This directory contains the **base structure** for API resource clients.
+
+## Recommended Pattern: Versioned Folders
+
+When implementing resources, use **explicit versioned folders** that mirror bifrost's API structure:
+
+```
+magick_mind/resources/
+├── __init__.py          # BaseResource, V1Resources, V2Resources
+├── base.py              # BaseResource class (or in __init__.py)
+├── v1/
+│   ├── __init__.py
+│   ├── chat.py          # ChatResourceV1
+│   └── history.py       # HistoryResourceV1
+└── v2/
+    ├── __init__.py
+    ├── chat.py          # ChatResourceV2
+    └── history.py       # HistoryResourceV2
+```
+
+**Why versioned folders?** They mirror bifrost's API structure and keep versions isolated.
+
+## Beta and Experimental Features
+
+Beta features can be organized in two ways depending on how bifrost implements them:
+
+### Pattern A: Beta as Separate Container
+
+Use when beta is a **full API version** with breaking changes (preparation for v2):
+
+```
+resources/
+├── v1/
+│   └── chat.py          # ChatResourceV1 → /v1/magickmind/chat
+└── beta/
+    └── chat.py          # ChatResourceBeta → /beta/magickmind/chat
+```
+
+```python
+class V1Resources:
+    def __init__(self, http_client):
+        self.chat = ChatResourceV1(http_client)
+
+class BetaResources:
+    def __init__(self, http_client):
+        self.chat = ChatResourceBeta(http_client)  # Breaking changes
+
+# Usage
+client.v1.chat.send(message="...")      # Stable
+client.beta.chat.send(content={...})    # Different API (breaking)
+```
+
+**When to use:**
+- Beta has different request/response structure
+- Testing major breaking changes
+- Beta will become v2
+
+### Pattern B: Beta as Attribute Within Version
+
+Use when beta is a **feature flag** within the same version:
+
+```
+resources/
+└── v1/
+    ├── chat.py          # ChatResourceV1 → /v1/magickmind/chat
+    └── chat_beta.py     # ChatBetaResourceV1 → /v1/magickmind/chatbeta
+```
+
+```python
+class V1Resources:
+    def __init__(self, http_client):
+        self.chat = ChatResourceV1(http_client)
+        self.chat_beta = ChatBetaResourceV1(http_client)  # Feature flag
+
+# Usage
+client.v1.chat.send(message="...")           # Stable
+client.v1.chat_beta.send(                    # Same structure, new features
+    message="...",
+    experimental_param=True  # New parameter being tested
+)
+```
+
+**When to use:**
+- Beta has same basic structure as stable
+- Testing new parameters/features
+- A/B testing
+- Beta is not a breaking change
+
+### Pattern C: Both (Flexible)
+
+You can use both patterns if bifrost has both types of beta features:
+
+```python
+class V1Resources:
+    def __init__(self, http_client):
+        self.chat = ChatResourceV1(http_client)
+        self.chat_beta = ChatBetaResourceV1(http_client)  # Feature flag
+
+class BetaResources:
+    def __init__(self, http_client):
+        self.chat = ChatResourceBeta(http_client)  # Breaking version
+
+# Usage
+client.v1.chat.send(...)        # Stable v1
+client.v1.chat_beta.send(...)   # Beta feature in v1 (non-breaking)
+client.beta.chat.send(...)      # Beta API version (breaking)
+```
+
+**Guideline:** Match the pattern to how bifrost actually implements the endpoint. Check the API path structure first.
+
+## Example: V1 Chat Resource
+
+```python
+# resources/v1/chat.py
+from typing import Optional
+from magick_mind.models.v1.chat import ChatSendRequest, ChatSendResponse
+from magick_mind.resources.base import BaseResource
+
+class ChatResourceV1(BaseResource):
+    def send(self, message: str, model: str = "gpt-4") -> ChatSendResponse:
+        """Send a chat message."""
+        payload = ChatSendRequest(message=message, model=model)
+        
+        # self.http gives access to authenticated httpx client
+        resp = self.http.post("/v1/chat/completions", json=payload.model_dump())
+        
+        return ChatSendResponse(**resp.json())
+```
+
+## Resource Containers
+
+Create version containers in `resources/__init__.py`:
+
+```python
+from .v1.chat import ChatResourceV1
+from .v1.history import HistoryResourceV1
+
+class V1Resources:
+    """Container for all v1 API resources."""
+    def __init__(self, http_client):
+        self.chat = ChatResourceV1(http_client)
+        self.history = HistoryResourceV1(http_client)
+
+class V2Resources:
+    """Container for all v2 API resources."""
+    def __init__(self, http_client):
+        from .v2.chat import ChatResourceV2
+        self.chat = ChatResourceV2(http_client)
+```
+
+## Wire to Main Client
+
+Update `client.py`:
+
+```python
+from magick_mind.resources import V1Resources, V2Resources
+
+class MagickMind:
+    def __init__(self, ...):
+        # ... auth setup ...
+        
+        # Initialize resources with http client
+        self.v1 = V1Resources(self.http)
+        self.v2 = V2Resources(self.http)
+        
+        # Default alias
+        self.chat = self.v1.chat
+```
+
+## Usage
+
+```python
+from magick_mind import MagickMind
+
+client = MagickMind(email="...", password="...", base_url="...")
+
+# Explicit version (recommended)
+response = client.v1.chat.send(
+    api_key="sk-...",
+    message="Hello!",
+    chat_id="123",
+    sender_id="user-456"
+)
+
+# Or default alias
+response = client.chat.send(...)
+```
+
+## Complete Example
+
+See **[docs/examples/chat_implementation/](../../../docs/examples/chat_implementation/)** for a complete working reference implementation.
+
+## Benefits
+
+1. **Explicit versioning** - `client.v1.chat` vs `client.v2.chat`
+2. **Type safety** - Pydantic models validate requests/responses
+3. **Mirrors Bifrost** - SDK structure matches API structure
+4. **Safe evolution** - Breaking changes require explicit opt-in
+

magick_mind/resources/__init__.py

@@ -0,0 +1,42 @@
+"""Resource clients for API endpoints."""
+
+from typing import TYPE_CHECKING
+
+from magick_mind.resources.base import BaseResource
+
+if TYPE_CHECKING:
+    from magick_mind.http import HTTPClient
+
+
+class V1Resources:
+    """Container for all v1 API resources."""
+
+    def __init__(self, http_client: "HTTPClient"):
+        """
+        Initialize V1 resources.
+
+        Args:
+            http_client: HTTP client for making API requests
+        """
+        from magick_mind.resources.v1.artifact import ArtifactResourceV1
+        from magick_mind.resources.v1.api_keys import ApiKeysResourceV1
+        from magick_mind.resources.v1.chat import ChatResourceV1
+        from magick_mind.resources.v1.corpus import CorpusResourceV1
+        from magick_mind.resources.v1.end_user import EndUserResourceV1
+        from magick_mind.resources.v1.history import HistoryResourceV1
+        from magick_mind.resources.v1.mindspace import MindspaceResourceV1
+        from magick_mind.resources.v1.project import ProjectResourceV1
+        from magick_mind.resources.v1.model import ModelsResourceV1
+
+        self.artifact = ArtifactResourceV1(http_client)
+        self.api_keys = ApiKeysResourceV1(http_client)
+        self.chat = ChatResourceV1(http_client)
+        self.corpus = CorpusResourceV1(http_client)
+        self.end_user = EndUserResourceV1(http_client)
+        self.history = HistoryResourceV1(http_client)
+        self.mindspace = MindspaceResourceV1(http_client)
+        self.project = ProjectResourceV1(http_client)
+        self.models = ModelsResourceV1(http_client)
+
+
+__all__ = ["BaseResource", "V1Resources"]

magick_mind/resources/base.py

@@ -0,0 +1,31 @@
+"""Base class for API resource clients."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from magick_mind.http import HTTPClient
+
+
+class BaseResource:
+    """
+    Base class for all resource clients.
+
+    Resource clients encapsulate API endpoints for specific domains
+    (e.g., chat, history, users, mindspaces).
+
+    For a complete implementation example, see docs/contributing/resource_implementation_guide/
+
+    Example:
+        class ChatResourceV1(BaseResource):
+            def send(self, api_key: str, message: str, **kwargs):
+                return self._http.post("/v1/magickmind/chat", json={...})
+    """
+
+    def __init__(self, http_client: "HTTPClient"):
+        """
+        Initialize resource client.
+
+        Args:
+            http_client: HTTP client for making API requests
+        """
+        self._http = http_client

magick_mind/resources/v1/__init__.py

@@ -0,0 +1,19 @@
+"""V1 API resources."""
+
+from magick_mind.resources.v1.artifact import ArtifactResourceV1
+from magick_mind.resources.v1.api_keys import ApiKeysResourceV1
+from magick_mind.resources.v1.corpus import CorpusResourceV1
+from magick_mind.resources.v1.chat import ChatResourceV1
+from magick_mind.resources.v1.end_user import EndUserResourceV1
+from magick_mind.resources.v1.mindspace import MindspaceResourceV1
+from magick_mind.resources.v1.project import ProjectResourceV1
+
+__all__ = [
+    "ArtifactResourceV1",
+    "ApiKeysResourceV1",
+    "CorpusResourceV1",
+    "ChatResourceV1",
+    "EndUserResourceV1",
+    "MindspaceResourceV1",
+    "ProjectResourceV1",
+]