magick_mind.client

Main Magick Mind SDK client.

MagickMind

class MagickMind()

Main client for the Magick Mind SDK.

This is the primary interface for interacting with the 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://api.magickmind.ai" )

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(...) magickspaces = await client.magickspaces.list()

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() await client.realtime.subscribe(target_user_id="user-456")

MagickMind.__init__

def __init__(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.

Arguments:

• base_url - Base URL of the Magick Mind API (e.g., https://api.magickmind.ai)
• 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)

MagickMind.http

@property
def http() -> 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:

• 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

MagickMind.realtime

@property
def realtime() -> RealtimeClient

Realtime WebSocket client.

Note: This client is ASYNC. You must use it within an async context.

Features:

• Authenticated WebSocket connection
• RPC subscriptions
• Handling disconnects/reconnects (via centrifuge-python)

Returns:

• RealtimeClient - Configured async realtime client

MagickMind.get_user_id

async def get_user_id() -> str

The authenticated user's ID (JWT sub claim).

Useful for subscribing to your own realtime events::

user_id = await client.get_user_id() await client.realtime.subscribe(target_user_id=user_id)

Raises:

• MagickMindError - If the current token does not contain a sub claim or cannot be decoded.

MagickMind.test_connection

async def test_connection() -> bool

Test the connection to the API.

MagickMind.is_authenticated

def is_authenticated() -> bool

Check if the client is authenticated.

Returns:

True if authenticated, False otherwise

MagickMind.close

async def close() -> None

Close the client and cleanup resources.

MagickMind.__aenter__

async def __aenter__() -> MagickMind

Async context manager entry.

MagickMind.__aexit__

async def __aexit__(exc_type: object, exc_val: object, exc_tb: object) -> None

Async context manager exit.

MagickMind.openai_client

def openai_client(api_key: str, compute_power: int = 1) -> AsyncOpenAI

Return a pre-configured AsyncOpenAI client pointed at the Magick Mind API.

The API exposes an OpenAI-compatible endpoint at /v1/chat/completions. Auth is a Bearer api_key (not JWT). Pass the api_key you want to use.

Usage::

oai = client.openai_client(api_key="sk-...") resp = await oai.chat.completions.create( model="openrouter/meta-llama/llama-4-maverick", messages=[{"role": "user", "content": "hello"}], )

Arguments:

• api_key - API key passed as Bearer token.
• compute_power - X-Compute-Power header value (default 1).

Returns:

• AsyncOpenAI - Pre-configured client pointed at the Magick Mind /v1 API.

Raises:

• ImportError - If the openai package is not installed. Install with: pip install magick-mind[openai]

MagickMind.__repr__

def __repr__() -> str

String representation of the client.