magickmind 0.1.1__py3-none-any.whl

magick_mind/__init__.py

@@ -0,0 +1,39 @@
+"""
+Magick Mind SDK - Python client for Bifrost Magick Mind AI platform.
+
+Simple, powerful SDK for authentication and interaction with the Magick Mind API.
+"""
+
+from magick_mind.client import MagickMind
+from magick_mind.exceptions import (
+    AuthenticationError,
+    MagickMindError,
+    ProblemDetailsException,
+    RateLimitError,
+    TokenExpiredError,
+    ValidationError,
+)
+from magick_mind.models.v1 import (
+    ChatPayload,
+    ChatSendRequest,
+    ChatSendResponse,
+    ChatHistoryMessage,
+    HistoryResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MagickMind",
+    "AuthenticationError",
+    "MagickMindError",
+    "ProblemDetailsException",
+    "RateLimitError",
+    "TokenExpiredError",
+    "ValidationError",
+    "ChatSendRequest",
+    "ChatPayload",
+    "ChatSendResponse",
+    "ChatHistoryMessage",
+    "HistoryResponse",
+]

magick_mind/auth/__init__.py

@@ -0,0 +1,9 @@
+"""Authentication module for Magick Mind SDK."""
+
+from magick_mind.auth.base import AuthProvider
+from magick_mind.auth.email_password import EmailPasswordAuth
+
+__all__ = [
+    "AuthProvider",
+    "EmailPasswordAuth",
+]

magick_mind/auth/base.py

@@ -0,0 +1,46 @@
+"""Base authentication provider interface."""
+
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class AuthProvider(ABC):
+    """Base class for authentication providers."""
+
+    @abstractmethod
+    def get_headers(self) -> Dict[str, str]:
+        """
+        Get authentication headers for API requests.
+
+        Returns:
+            Dictionary of HTTP headers to include in requests
+        """
+        pass
+
+    @abstractmethod
+    def is_authenticated(self) -> bool:
+        """
+        Check if the provider is currently authenticated.
+
+        Returns:
+            True if authenticated, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_token(self) -> str:
+        """
+        Get the raw access token.
+        Should handle refresh if needed.
+
+        Returns:
+            Raw access token string
+        """
+        pass
+
+    def refresh_if_needed(self) -> None:
+        """
+        Refresh authentication credentials if needed.
+        Override this method in subclasses that support token refresh.
+        """
+        pass

magick_mind/auth/email_password.py

@@ -0,0 +1,268 @@
+"""Email/password authentication provider."""
+
+import time
+from typing import Dict, Optional
+import httpx
+
+from magick_mind.auth.base import AuthProvider
+from magick_mind.exceptions import AuthenticationError, TokenExpiredError
+from magick_mind.models.auth import LoginRequest, RefreshRequest, TokenResponse
+from magick_mind.routes import Routes
+
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class EmailPasswordAuth(AuthProvider):
+    """
+    Email/password authentication using bifrost's /v1/auth/login endpoint.
+
+    Automatically handles token refresh when the access token expires.
+
+    Example:
+        auth = EmailPasswordAuth(
+            email="user@example.com",
+            password="your_password",
+            base_url="https://bifrost.example.com"
+        )
+        # Login happens automatically on first request
+        headers = auth.get_headers()
+    """
+
+    def __init__(self, email: str, password: str, base_url: str, timeout: float = 30.0):
+        """
+        Initialize email/password authentication.
+
+        Args:
+            email: User email address
+            password: User password
+            base_url: Base URL of the Bifrost API
+            timeout: Request timeout in seconds
+        """
+        if not email or not password:
+            raise ValueError("Email and password are required")
+
+        self.email = email
+        self.password = password
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        # Token storage
+        self._access_token: Optional[str] = None
+        self._refresh_token: Optional[str] = None
+        self._token_expires_at: float = 0.0
+        self._refresh_expires_at: float = 0.0
+
+    def get_headers(self) -> Dict[str, str]:
+        """
+        Get authorization header with access token.
+        Automatically logs in or refreshes token if needed.
+        """
+        self.refresh_if_needed()
+
+        if not self._access_token:
+            raise AuthenticationError(
+                "Not authenticated. Failed to obtain access token."
+            )
+
+        return {"Authorization": f"Bearer {self._access_token}"}
+
+    def is_authenticated(self) -> bool:
+        """Check if currently authenticated with a valid token."""
+        return bool(self._access_token) and time.time() < self._token_expires_at
+
+    def get_token(self) -> str:
+        """Get raw access token, refreshing if needed."""
+        self.refresh_if_needed()
+        if not self._access_token:
+            raise AuthenticationError(
+                "Not authenticated. Failed to obtain access token."
+            )
+        return self._access_token
+
+    def refresh_if_needed(self) -> None:
+        """
+        Refresh authentication if needed.
+
+        Logic:
+        1. If no access token, perform login
+        2. If access token expired but refresh token valid, refresh
+        3. If both expired, perform login
+        """
+        current_time = time.time()
+
+        # No token yet - need to login
+        if not self._access_token:
+            self._login()
+            return
+
+        # Access token still valid
+        if current_time < self._token_expires_at:
+            return
+
+        # Access token expired - try refresh if refresh token is valid
+        if self._refresh_token and current_time < self._refresh_expires_at:
+            try:
+                self._refresh()
+                return
+            except Exception:
+                # Refresh failed, fall back to login
+                pass
+
+        # Refresh not available or failed - do full login
+        self._login()
+
+    def _login(self) -> None:
+        """Perform login to get initial tokens."""
+        login_url = f"{self.base_url}{Routes.AUTH_LOGIN}"
+
+        payload = LoginRequest(email=self.email, password=self.password)
+
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.post(login_url, json=payload.model_dump())
+                response.raise_for_status()
+
+                # Parse and validate response (flat TokenResponse, no wrapper)
+                data = TokenResponse(**response.json())
+                self._store_tokens(data)
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise AuthenticationError("Invalid email or password", status_code=401)
+            raise AuthenticationError(
+                f"Login failed: {str(e)}", status_code=e.response.status_code
+            )
+        except httpx.RequestError as e:
+            raise AuthenticationError(f"Network error during login: {str(e)}")
+
+    def _refresh(self) -> None:
+        """Refresh the access token using the refresh token."""
+        # Note: Bifrost might have a refresh endpoint, but if not,
+        # we'll just re-login. This can be updated when the endpoint is available.
+        refresh_url = f"{self.base_url}{Routes.AUTH_REFRESH}"
+
+        if not self._refresh_token:
+            raise TokenExpiredError("No refresh token available")
+
+        try:
+            refresh_req = RefreshRequest(refresh_token=self._refresh_token)
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.post(refresh_url, json=refresh_req.model_dump())
+                response.raise_for_status()
+
+                # Parse and validate response (flat TokenResponse, no wrapper)
+                data = TokenResponse(**response.json())
+                self._store_tokens(data)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise TokenExpiredError("Refresh token expired or invalid")
+            raise AuthenticationError(
+                f"Token refresh failed: {str(e)}", status_code=e.response.status_code
+            )
+        except httpx.RequestError as e:
+            raise AuthenticationError(f"Network error during token refresh: {str(e)}")
+
+    def _store_tokens(self, token_data: TokenResponse) -> None:
+        """Store tokens and calculate expiration times."""
+        current_time = time.time()
+
+        # Access via attributes (Pydantic model)
+        self._access_token = token_data.access_token
+        self._refresh_token = token_data.refresh_token
+
+        # Add buffer of 10 seconds to avoid edge cases
+        # Default fallback values handled by Pydantic model structure if strict
+        # But here fields are required except options.
+        # API should ensure these exist.
+        expires_in = token_data.expires_in - 10
+        self._token_expires_at = current_time + max(expires_in, 0)
+
+        refresh_expires_in = token_data.refresh_expires_in - 10
+        self._refresh_expires_at = current_time + max(refresh_expires_in, 0)
+
+    async def get_token_async(self) -> str:
+        """Get raw access token asynchronously, refreshing if needed."""
+        await self.refresh_if_needed_async()
+        if not self._access_token:
+            raise AuthenticationError(
+                "Not authenticated. Failed to obtain access token."
+            )
+        return self._access_token
+
+    async def refresh_if_needed_async(self) -> None:
+        """Async version of refresh_if_needed."""
+        current_time = time.time()
+
+        if not self._access_token:
+            await self._login_async()
+            return
+
+        if current_time < self._token_expires_at:
+            return
+
+        if self._refresh_token and current_time < self._refresh_expires_at:
+            try:
+                await self._refresh_async()
+                return
+            except Exception:
+                pass
+
+        await self._login_async()
+
+    async def _login_async(self) -> None:
+        """Async login."""
+        login_url = f"{self.base_url}{Routes.AUTH_LOGIN}"
+        payload = LoginRequest(email=self.email, password=self.password)
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(login_url, json=payload.model_dump())
+                response.raise_for_status()
+
+                # Parse and validate response (flat TokenResponse, no wrapper)
+                data = TokenResponse(**response.json())
+                self._store_tokens(data)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise AuthenticationError("Invalid email or password", status_code=401)
+            raise AuthenticationError(
+                f"Login failed: {str(e)}", status_code=e.response.status_code
+            )
+        except httpx.RequestError as e:
+            raise AuthenticationError(f"Network error during login: {str(e)}")
+
+    async def _refresh_async(self) -> None:
+        """Async refresh."""
+        refresh_url = f"{self.base_url}{Routes.AUTH_REFRESH}"
+        if not self._refresh_token:
+            raise TokenExpiredError("No refresh token available")
+
+        try:
+            refresh_req = RefreshRequest(refresh_token=self._refresh_token)
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(refresh_url, json=refresh_req.model_dump())
+                response.raise_for_status()
+
+                # Parse and validate response (flat TokenResponse, no wrapper)
+                data = TokenResponse(**response.json())
+                self._store_tokens(data)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise TokenExpiredError("Refresh token expired or invalid")
+            raise AuthenticationError(
+                f"Token refresh failed: {str(e)}", status_code=e.response.status_code
+            )
+        except httpx.RequestError as e:
+            raise AuthenticationError(f"Network error during token refresh: {str(e)}")
+
+    async def get_headers_async(self) -> Dict[str, str]:
+        """
+        Async version of get_headers.
+        """
+        await self.refresh_if_needed_async()
+        if not self._access_token:
+            raise AuthenticationError("Not authenticated.")
+        return {"Authorization": f"Bearer {self._access_token}"}

magick_mind/client.py

@@ -0,0 +1,188 @@
+"""Main Magick Mind SDK client."""
+
+from typing import Optional
+
+from magick_mind.auth import AuthProvider, EmailPasswordAuth
+from magick_mind.config import SDKConfig
+from magick_mind.http import HTTPClient
+from magick_mind.realtime import RealtimeClient
+
+
+class MagickMind:
+    """
+    Main client for the Magick Mind SDK.
+
+    This is the primary interface for interacting with the Bifrost Magick Mind API.
+
+    Provides:
+    - Authentication (email/password with JWT, automatic refresh)
+    - Typed resources (v1.chat, etc.) with Pydantic validation
+    - HTTP client for direct API access
+    - Realtime client for WebSocket connections (async)
+
+    Example:
+        # Initialize client
+        client = MagickMind(
+            email="user@example.com",
+            password="your_password",
+            base_url="https://bifrost.example.com"
+        )
+
+        # Use typed resources (recommended)
+        response = client.v1.chat.send(
+            api_key="sk-...",
+            mindspace_id="mind-123",
+            message="Hello!",
+            sender_id="user-456"
+        )
+        print(response.content.content)  # AI response
+
+        # Or use convenience alias
+        response = client.chat.send(...)
+
+        # Use HTTP client directly for experimental endpoints
+        response = client.http.post("/experimental/endpoint", json={...})
+
+        # Use Realtime client (in async context)
+        async def main():
+            await client.realtime.connect(events=MyHandler())
+            await client.realtime.subscribe(target_user_id="user-456")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        email: str,
+        password: str,
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+        ws_endpoint: Optional[str] = None,
+    ):
+        """
+        Initialize the Magick Mind client.
+
+        Args:
+            base_url: Base URL of the Bifrost API (e.g., https://bifrost.example.com)
+            email: User email for authentication
+            password: User password for authentication
+            timeout: Request timeout in seconds
+            verify_ssl: Whether to verify SSL certificates
+            ws_endpoint: WebSocket URL (Required for .realtime usage)
+        """
+        if not email or not password:
+            raise ValueError("Email and password are required for authentication")
+
+        # Create configuration
+        self.config = SDKConfig(
+            base_url=base_url,
+            timeout=timeout,
+            verify_ssl=verify_ssl,
+            ws_endpoint=ws_endpoint,
+        )
+
+        # Create authentication provider (email/password with JWT)
+        self.auth: AuthProvider = EmailPasswordAuth(
+            email=email, password=password, base_url=base_url, timeout=timeout
+        )
+
+        # Create HTTP client (private, accessed via property)
+        self._http = HTTPClient(config=self.config, auth=self.auth)
+
+        # Create Realtime client (private, accessed via property)
+        self._realtime = RealtimeClient(auth=self.auth, ws_url=ws_endpoint)
+
+        # Initialize typed resources
+        from magick_mind.resources import V1Resources
+
+        self.v1 = V1Resources(self._http)
+
+        # Convenience alias for default version
+        self.chat = self.v1.chat
+        self.mindspace = self.v1.mindspace
+        self.models = self.v1.models
+
+    @property
+    def http(self) -> HTTPClient:
+        """
+        Low-level HTTP client bound to this MagickMind instance.
+
+        Features:
+        - Uses same base_url and configuration
+        - Automatically attaches authentication tokens
+        - Applies centralized error mapping
+        - Auto-refreshes expired tokens
+
+        Intended for:
+        - Bifrost developers testing new endpoints
+        - Power users needing direct API access
+        - Experimenting with endpoints before implementing resources
+
+        Example:
+            # Test a new endpoint directly
+            response = client.http.post(
+                "/experimental/new-feature",
+                json={"test": "data"}
+            )
+
+            # Quick one-off calls
+            response = client.http.get("/v1/status")
+
+        Returns:
+            HTTPClient: Configured HTTP client instance
+        """
+        return self._http
+
+    @property
+    def realtime(self) -> RealtimeClient:
+        """
+        Realtime WebSocket client.
+
+        Note: This client is ASYNC. You must use it within an async context.
+
+        Features:
+        - Authenticated WebSocket connection
+        - RPC subscriptions (Bifrost specific)
+        - Handling disconnects/reconnects (via centrifuge-python)
+
+        Returns:
+            RealtimeClient: Configured async realtime client
+        """
+        return self._realtime
+
+    def test_connection(self) -> bool:
+        """Test the connection to the API."""
+        try:
+            # This assumes there's a health check or similar endpoint
+            response = self.http.get("/health")
+            return response.get("success", False)
+        except Exception:
+            return False
+
+    def is_authenticated(self) -> bool:
+        """
+        Check if the client is authenticated.
+
+        Returns:
+            True if authenticated, False otherwise
+        """
+        """Check if the client is authenticated."""
+        return self.auth.is_authenticated()
+
+    def close(self) -> None:
+        """Close the client and cleanup resources."""
+        self._http.close()
+        # Realtime client might need async close?
+        # But close() here is typically sync.
+        # User should probably manage realtime lifecycle themselves if async.
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+
+    def __repr__(self) -> str:
+        """String representation of the client."""
+        return f"MagickMind(base_url='{self.config.base_url}', auth='EmailPassword')"

magick_mind/config.py

@@ -0,0 +1,28 @@
+"""Configuration models for Magick Mind SDK."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class SDKConfig:
+    """Configuration for the Magick Mind SDK."""
+
+    base_url: str
+    """Base URL for the Bifrost API (e.g., https://bifrost.example.com)"""
+
+    timeout: float = 30.0
+    """Request timeout in seconds"""
+
+    max_retries: int = 3
+    """Maximum number of retries for failed requests"""
+
+    verify_ssl: bool = True
+    """Whether to verify SSL certificates"""
+
+    ws_endpoint: Optional[str] = None
+    """Explicit WebSocket endpoint URL (optional)"""
+
+    def normalized_base_url(self) -> str:
+        """Return base URL without trailing slash."""
+        return self.base_url.rstrip("/")

magick_mind/exceptions.py

@@ -0,0 +1,107 @@
+"""Custom exceptions for Magick Mind SDK."""
+
+from __future__ import annotations
+
+import logging
+
+from magick_mind.models.errors import ProblemDetails
+
+logger = logging.getLogger(__name__)
+
+
+class MagickMindError(Exception):
+    """Base exception for all Magick Mind SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(self.message)
+
+
+class AuthenticationError(MagickMindError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class TokenExpiredError(AuthenticationError):
+    """Raised when a token has expired."""
+
+    pass
+
+
+class RateLimitError(MagickMindError):
+    """Raised when rate limit is exceeded."""
+
+    pass
+
+
+class ProblemDetailsException(MagickMindError):
+    """RFC 7807 Problem Details error from Bifrost."""
+
+    def __init__(
+        self,
+        problem: ProblemDetails,
+        raw_response: dict | None = None,
+    ):
+        self.type_uri = problem.type
+        self.title = problem.title
+        self.status = problem.status
+        self.detail = problem.detail
+        self.instance = problem.instance
+        self.request_id = problem.request_id
+        self.validation_errors = problem.errors
+        self.problem = problem  # Full Pydantic model
+
+        # Log with request_id for tracing
+        logger.debug(
+            "API error: %s [%d] %s (request_id=%s, instance=%s)",
+            self.title,
+            self.status,
+            self.detail,
+            self.request_id or "none",
+            self.instance or "none",
+        )
+
+        super().__init__(self.detail, status_code=self.status)
+        self.response_data = raw_response
+
+    def __str__(self) -> str:
+        msg = f"[{self.status}] {self.title}: {self.detail}"
+        if self.request_id:
+            msg += f" (request_id: {self.request_id})"
+        if self.validation_errors:
+            msg += f"\nValidation errors ({len(self.validation_errors)}):"
+            for err in self.validation_errors:
+                msg += f"\n  - {err.field}: {err.message}"
+        return msg
+
+    def __repr__(self) -> str:
+        return f"ProblemDetailsException(status={self.status}, title={self.title!r}, request_id={self.request_id!r})"
+
+
+class ValidationError(ProblemDetailsException):
+    """400 Bad Request with field-level validation errors."""
+
+    def __init__(self, problem: ProblemDetails, raw_response: dict | None = None):
+        if problem.status != 400:
+            raise ValueError(
+                f"ValidationError must have status 400, got {problem.status}"
+            )
+        if not problem.errors:
+            logger.warning("ValidationError created without field errors")
+        super().__init__(problem, raw_response)
+
+    def get_field_errors(self) -> dict[str, list[str]]:
+        """
+        Get errors grouped by field name for UI display.
+
+        Note: Returns simplified dict[field, messages]. Access validation_errors
+        directly if you need error codes (e.g., "required", "invalid_format").
+        """
+        errors_by_field: dict[str, list[str]] = {}
+        for err in self.validation_errors:
+            if err.field not in errors_by_field:
+                errors_by_field[err.field] = []
+            errors_by_field[err.field].append(err.message)
+        return errors_by_field

magick_mind/http/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP client module for Magick Mind SDK."""
+
+from magick_mind.http.client import HTTPClient
+
+__all__ = ["HTTPClient"]