magickmind 0.1.1__py3-none-any.whl

magick_mind/http/client.py

@@ -0,0 +1,313 @@
+"""HTTP client for making API requests."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+from pydantic import ValidationError as PydanticValidationError
+
+from magick_mind.auth.base import AuthProvider
+from magick_mind.config import SDKConfig
+from magick_mind.exceptions import (
+    MagickMindError,
+    ProblemDetailsException,
+    RateLimitError,
+    ValidationError,
+)
+from magick_mind.models.errors import ErrorResponse, ProblemDetails
+
+logger = logging.getLogger(__name__)
+
+
+class HTTPClient:
+    """
+    HTTP client wrapper for making authenticated API requests.
+
+    Handles:
+    - Authentication header injection
+    - Error handling and response parsing
+    - Retry logic
+    - Request/response logging
+    """
+
+    def __init__(self, config: SDKConfig, auth: AuthProvider):
+        """
+        Initialize HTTP client.
+
+        Args:
+            config: SDK configuration
+            auth: Authentication provider
+        """
+        self.config = config
+        self.auth = auth
+        self._client = httpx.Client(
+            timeout=config.timeout,
+            verify=config.verify_ssl,
+        )
+
+    def _get_headers(
+        self, extra_headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, str]:
+        """Build request headers with authentication."""
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+        # Add auth headers
+        auth_headers = self.auth.get_headers()
+        headers.update(auth_headers)
+
+        # Add any extra headers
+        if extra_headers:
+            headers.update(extra_headers)
+
+        return headers
+
+    def _build_url(self, path: str) -> str:
+        """Build full URL from path."""
+        base = self.config.normalized_base_url()
+        # Ensure path starts with /
+        if not path.startswith("/"):
+            path = f"/{path}"
+        return f"{base}{path}"
+
+    def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        """
+        Handle HTTP response and raise appropriate exceptions.
+
+        Args:
+            response: HTTP response object
+
+        Returns:
+            Parsed JSON response data
+
+        Raises:
+            ProblemDetailsException: For RFC 7807 errors
+            ValidationError: For 400 Bad Request with field errors
+            RateLimitError: For rate limiting
+            MagickMindError: For malformed responses
+        """
+        # Success path
+        if response.status_code < 400:
+            try:
+                return response.json()
+            except Exception:
+                return {}
+
+        # Rate limiting (special case)
+        if response.status_code == 429:
+            # Try RFC 7807 first
+            try:
+                error_response = ErrorResponse.model_validate(response.json())
+                raise RateLimitError(
+                    error_response.error.detail,
+                    status_code=429,
+                )
+            except (json.JSONDecodeError, PydanticValidationError):
+                raise RateLimitError(
+                    "Rate limit exceeded",
+                    status_code=429,
+                )
+
+        # Parse error response
+        try:
+            data = response.json()
+        except json.JSONDecodeError:
+            raise MagickMindError(
+                f"Non-JSON error response: {response.text[:200]}",
+                status_code=response.status_code,
+            )
+
+        # RFC 7807 format (98% of Bifrost endpoints)
+        if "error" in data and isinstance(data["error"], dict):
+            try:
+                error_response = ErrorResponse.model_validate(data)
+                problem = error_response.error
+
+                # Raise ValidationError for 400 with field errors
+                if problem.status == 400 and problem.errors:
+                    raise ValidationError(problem, raw_response=data)
+
+                # Generic ProblemDetailsException
+                raise ProblemDetailsException(problem, raw_response=data)
+
+            except PydanticValidationError as e:
+                # Malformed RFC 7807 response
+                logger.warning("Malformed RFC 7807 response: %s", e)
+                raise MagickMindError(
+                    f"Malformed error response: {data.get('error', {}).get('detail', 'Unknown error')}",
+                    status_code=response.status_code,
+                )
+
+        # Fallback: OpenAI middleware format {"code": 401, "message": "..."}
+        if "code" in data and "message" in data:
+            logger.debug("Received legacy error format from OpenAI middleware")
+            # Convert to RFC 7807 structure
+            problem = ProblemDetails(
+                type="about:blank",
+                title=http.client.responses.get(data["code"], "Error"),
+                status=data["code"],
+                detail=data["message"],
+            )
+            raise ProblemDetailsException(problem, raw_response=data)
+
+        # Unknown format
+        raise MagickMindError(
+            f"Unknown error response format: {data}",
+            status_code=response.status_code,
+        )
+
+    def get(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make a GET request.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+            headers: Additional headers
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            AuthenticationError: If JWT token is invalid (auto-refreshed if expired)
+            ProblemDetailsException: For API errors (4xx, 5xx) following RFC 7807
+            ValidationError: For 400 Bad Request with field-level errors
+            RateLimitError: For 429 Too Many Requests
+            MagickMindError: For unexpected errors or malformed responses
+
+        Example:
+            >>> response = client.http.get("/v1/mindspaces")
+            >>> print(response['data'])
+        """
+        # Refresh auth if needed
+        self.auth.refresh_if_needed()
+
+        url = self._build_url(path)
+        request_headers = self._get_headers(headers)
+
+        response = self._client.get(url, params=params, headers=request_headers)
+        return self._handle_response(response)
+
+    def post(
+        self,
+        path: str,
+        json: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make a POST request.
+
+        Args:
+            path: API endpoint path
+            json: Request body as dictionary
+            headers: Additional headers
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            AuthenticationError: If JWT token is invalid (auto-refreshed if expired)
+            ProblemDetailsException: For API errors (4xx, 5xx) following RFC 7807
+            ValidationError: For 400 Bad Request with field-level validation errors
+            RateLimitError: For 429 Too Many Requests
+            MagickMindError: For unexpected errors or malformed responses
+
+        Example:
+            >>> response = client.http.post(
+            ...     "/v1/magickmind/chat",
+            ...     json={"message": "Hello", "mindspace_id": "mind-123"}
+            ... )
+        """
+        # Refresh auth if needed
+        self.auth.refresh_if_needed()
+
+        url = self._build_url(path)
+        request_headers = self._get_headers(headers)
+
+        response = self._client.post(url, json=json, headers=request_headers)
+        return self._handle_response(response)
+
+    def put(
+        self,
+        path: str,
+        json: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make a PUT request.
+
+        Args:
+            path: API endpoint path
+            json: Request body as dictionary
+            headers: Additional headers
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            AuthenticationError: If JWT token is invalid (auto-refreshed if expired)
+            ProblemDetailsException: For API errors (4xx, 5xx) following RFC 7807
+            ValidationError: For 400 Bad Request with field-level validation errors
+            RateLimitError: For 429 Too Many Requests
+            MagickMindError: For unexpected errors or malformed responses
+        """
+        # Refresh auth if needed
+        self.auth.refresh_if_needed()
+
+        url = self._build_url(path)
+        request_headers = self._get_headers(headers)
+
+        response = self._client.put(url, json=json, headers=request_headers)
+        return self._handle_response(response)
+
+    def delete(
+        self, path: str, headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Make a DELETE request.
+
+        Args:
+            path: API endpoint path
+            headers: Additional headers
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            AuthenticationError: If JWT token is invalid (auto-refreshed if expired)
+            ProblemDetailsException: For API errors (4xx, 5xx) following RFC 7807
+            ValidationError: For 400 Bad Request with field-level validation errors
+            RateLimitError: For 429 Too Many Requests
+            MagickMindError: For unexpected errors or malformed responses
+        """
+        # Refresh auth if needed
+        self.auth.refresh_if_needed()
+
+        url = self._build_url(path)
+        request_headers = self._get_headers(headers)
+
+        response = self._client.delete(url, headers=request_headers)
+        return self._handle_response(response)
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()

magick_mind/models/__init__.py

@@ -0,0 +1,17 @@
+"""Pydantic models for API requests and responses."""
+
+# Models are organized by version
+# Each version has its own submodule with request/response schemas
+
+# RFC 7807 error models (version-agnostic)
+from magick_mind.models.errors import (
+    ErrorResponse,
+    ProblemDetails,
+    ValidationErrorField,
+)
+
+__all__ = [
+    "ErrorResponse",
+    "ProblemDetails",
+    "ValidationErrorField",
+]

magick_mind/models/auth.py

@@ -0,0 +1,30 @@
+"""Authentication-related Pydantic models."""
+
+from pydantic import BaseModel, Field
+
+
+class LoginRequest(BaseModel):
+    """Request model for /v1/auth/login."""
+
+    email: str
+    password: str
+
+
+class RefreshRequest(BaseModel):
+    """Request model for /v1/auth/refresh."""
+
+    refresh_token: str
+
+
+class TokenResponse(BaseModel):
+    """Response model from /v1/auth/login."""
+
+    access_token: str
+    expires_in: int
+    refresh_expires_in: int
+    refresh_token: str
+    token_type: str
+    id_token: str
+    not_before_policy: int = Field(..., alias="not-before-policy")
+    session_state: str
+    scope: str

magick_mind/models/common.py

@@ -0,0 +1,32 @@
+"""Common Pydantic models used across versions."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class BaseResponse(BaseModel):
+    """Base response structure from Bifrost API."""
+
+    success: bool
+    message: str
+
+
+class Cursors(BaseModel):
+    """Pagination cursors for Bifrost paginated responses."""
+
+    after: Optional[str] = Field(default=None, description="Cursor for next page")
+    before: Optional[str] = Field(default=None, description="Cursor for previous page")
+
+
+class PageInfo(BaseModel):
+    """Pagination information for Bifrost paginated responses."""
+
+    cursors: Cursors = Field(
+        default_factory=lambda: Cursors(after=None, before=None),
+        description="Pagination cursors",
+    )
+    has_more: bool = Field(default=False, description="Whether there are more results")
+    has_previous: bool = Field(
+        default=False, description="Whether there are previous results"
+    )

magick_mind/models/errors.py

@@ -0,0 +1,73 @@
+"""RFC 7807 Problem Details error models for Bifrost API responses.
+
+This module defines Pydantic models for parsing RFC 7807 compliant error
+responses from the Bifrost API.
+
+See: https://datatracker.ietf.org/doc/html/rfc7807
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ValidationErrorField(BaseModel):
+    """RFC 7807 field-level validation error.
+
+    Represents a single field validation error, typically used in 400 Bad Request
+    responses with field-specific validation failures.
+
+    Attributes:
+        field: The field name that failed validation
+        message: Human-readable error message for this field
+        code: Optional error code (e.g., "required", "invalid_format")
+    """
+
+    field: str
+    message: str
+    code: str | None = None
+
+
+class ProblemDetails(BaseModel):
+    """RFC 7807 Problem Details structure.
+
+    Standard structure for HTTP API error responses. This is the Pydantic model
+    representing the data structure, NOT the exception class.
+
+    The exception class that wraps this is ProblemDetailsException (created in task 02).
+
+    Attributes:
+        type: URI reference identifying the problem type (default: "about:blank")
+        title: Short, human-readable summary of the problem type
+        status: HTTP status code (400-599)
+        detail: Human-readable explanation specific to this occurrence
+        instance: URI reference identifying the specific occurrence (e.g., request path)
+        request_id: Trace ID for debugging (Bifrost extension field)
+        errors: List of field-level validation errors (Bifrost extension field)
+
+    Additional fields are allowed per RFC 7807 extension mechanism.
+    """
+
+    type: str = "about:blank"
+    title: str
+    status: int = Field(ge=400, le=599)
+    detail: str
+    instance: str | None = None
+    request_id: str | None = None
+    errors: list[ValidationErrorField] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ErrorResponse(BaseModel):
+    """Bifrost error response wrapper.
+
+    Wraps the RFC 7807 ProblemDetails in an "error" envelope as returned by Bifrost.
+
+    Bifrost returns: {"error": {...problem details...}}
+
+    Attributes:
+        error: The RFC 7807 problem details
+    """
+
+    error: ProblemDetails

magick_mind/models/v1/__init__.py

@@ -0,0 +1,83 @@
+"""V1 API models."""
+
+from magick_mind.models.v1.artifact import (
+    Artifact,
+    ArtifactWebhookPayload,
+    DeleteArtifactResponse,
+    FinalizeArtifactRequest,
+    FinalizeArtifactResponse,
+    GetArtifactResponse,
+    ListArtifactsResponse,
+    PresignArtifactRequest,
+    PresignArtifactResponse,
+)
+from magick_mind.models.v1.chat import ChatPayload, ChatSendRequest, ChatSendResponse
+from magick_mind.models.v1.corpus import (
+    Corpus,
+    CreateCorpusRequest,
+    ListCorpusResponse,
+    UpdateCorpusRequest,
+)
+from magick_mind.models.v1.end_user import (
+    CreateEndUserRequest,
+    EndUser,
+    QueryEndUserResponse,
+    UpdateEndUserRequest,
+)
+from magick_mind.models.v1.history import ChatHistoryMessage, HistoryResponse
+from magick_mind.models.v1.api_keys import (
+    ApiKey,
+    CreateApiKeyRequest,
+    CreateApiKeyResponse,
+    DeleteApiKeyResponse,
+    KeyResponse,
+    ListApiKeysResponse,
+    UpdateApiKeyRequest,
+    UpdateApiKeyResponse,
+)
+from magick_mind.models.v1.project import (
+    CreateProjectRequest,
+    GetProjectListResponse,
+    Project,
+    UpdateProjectRequest,
+)
+from magick_mind.models.v1.model import Model, ModelsListResponse
+
+
+__all__ = [
+    "ChatSendRequest",
+    "ChatPayload",
+    "ChatSendResponse",
+    "ChatHistoryMessage",
+    "HistoryResponse",
+    "Project",
+    "CreateProjectRequest",
+    "GetProjectListResponse",
+    "EndUser",
+    "CreateEndUserRequest",
+    "QueryEndUserResponse",
+    "UpdateEndUserRequest",
+    "Artifact",
+    "PresignArtifactRequest",
+    "PresignArtifactResponse",
+    "GetArtifactResponse",
+    "ListArtifactsResponse",
+    "DeleteArtifactResponse",
+    "FinalizeArtifactRequest",
+    "FinalizeArtifactResponse",
+    "ArtifactWebhookPayload",
+    "Corpus",
+    "CreateCorpusRequest",
+    "ListCorpusResponse",
+    "UpdateCorpusRequest",
+    "ApiKey",
+    "KeyResponse",
+    "CreateApiKeyRequest",
+    "CreateApiKeyResponse",
+    "ListApiKeysResponse",
+    "UpdateApiKeyRequest",
+    "UpdateApiKeyResponse",
+    "DeleteApiKeyResponse",
+    "Model",
+    "ModelsListResponse",
+]

magick_mind/models/v1/api_keys.py

@@ -0,0 +1,115 @@
+"""
+API Keys models for Magick Mind SDK v1 API.
+
+Provides Pydantic models for creating and managing API keys
+for authenticating requests to the Bifrost backend.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApiKey(BaseModel):
+    """
+    API key metadata (does not include the actual key value).
+
+    Represents an API key for making authenticated requests.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    key_id: str = Field(..., description="Unique key identifier")
+    key_alias: str = Field(..., description="Human-readable key alias/name")
+    user_id: str = Field(..., description="Owner user ID")
+    project_id: str = Field(..., description="Associated project ID")
+    update_at: str = Field(..., description="Last update timestamp")
+    create_at: str = Field(..., description="Creation timestamp")
+
+
+class KeyResponse(BaseModel):
+    """
+    Response containing the actual API key value.
+
+    Only returned when creating or updating a key.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    key: Optional[str] = Field(None, description="The actual API key (only shown once)")
+    key_alias: Optional[str] = Field(None, description="Key alias/name")
+    key_id: Optional[str] = Field(None, description="Key identifier")
+    expires: Optional[str] = Field(None, description="Expiration timestamp")
+
+
+class CreateApiKeyRequest(BaseModel):
+    """Request for creating a new API key."""
+
+    user_id: Optional[str] = Field(
+        None, description="User ID that owns this key (Relaxed)"
+    )
+    project_id: Optional[str] = Field(
+        None, description="Project ID to associate with (Relaxed)"
+    )
+    models: Optional[list[str]] = Field(None, description="Allowed models (Relaxed)")
+    key_alias: Optional[str] = Field(
+        None, description="Human-readable key name (Relaxed)"
+    )
+    duration: Optional[str] = Field(
+        None, description="Key validity duration (e.g., '30d', '1y')"
+    )
+    team_id: Optional[str] = Field(None, description="Optional team ID")
+    max_budget: Optional[float] = Field(None, description="Optional spending limit")
+
+
+class CreateApiKeyResponse(BaseModel):
+    """Response for API key creation."""
+
+    success: bool = Field(..., description="Request success status")
+    message: str = Field(..., description="Response message")
+    key: KeyResponse = Field(..., description="The created API key details")
+
+
+class ListApiKeysResponse(BaseModel):
+    """Response for listing API keys."""
+
+    success: bool = Field(..., description="Request success status")
+    message: str = Field(..., description="Response message")
+    keys: list[ApiKey] = Field(..., description="List of API keys (metadata only)")
+
+
+class UpdateApiKeyRequest(BaseModel):
+    """Request for updating an existing API key."""
+
+    key: Optional[str] = Field(None, description="The API key to update (Relaxed)")
+    models: Optional[list[str]] = Field(
+        None, description="Updated allowed models (Relaxed)"
+    )
+    key_alias: Optional[str] = Field(
+        None, description="Updated key alias/name (Relaxed)"
+    )
+    duration: Optional[str] = Field(None, description="Updated validity duration")
+    max_budget: Optional[float] = Field(None, description="Updated spending limit")
+
+
+class UpdateApiKeyResponse(BaseModel):
+    """Response for API key update."""
+
+    success: Optional[bool] = Field(None, description="Request success status")
+    message: Optional[str] = Field(None, description="Response message")
+    key: Optional[KeyResponse] = Field(
+        None, description="The updated API key details (Optional in Apidog)"
+    )
+
+
+class DeleteApiKeyRequest(BaseModel):
+    """Request for deleting an API key."""
+
+    key_id: str = Field(..., description="Key ID to delete")
+
+
+class DeleteApiKeyResponse(BaseModel):
+    """Response for API key deletion."""
+
+    success: bool = Field(..., description="Request success status")
+    message: str = Field(..., description="Deletion confirmation message")