Magick Mind SDK

Python SDK for backend services integrating with the Magick Mind platform. Provides type-safe, validated access to chat, magickspace, and realtime features.

Installation

Using uv (recommended):

uv add magickmind

Using pip:

pip install magickmind

For development:

git clone https://github.com/General-Magick-Industries/py-magickmind
cd py-magickmind
uv sync --all-extras

Quick Start

Authentication

import asyncio
from magick_mind import MagickMind

async def main():
    async with MagickMind(
        email="user@example.com",
        password="your_password",
        base_url="https://api.magickmind.ai",
    ) as client:
        # Authentication happens automatically on first API call.
        # Tokens are automatically refreshed when needed.
        user_id = await client.get_user_id()
        print(f"Authenticated as: {user_id}")

asyncio.run(main())

Note: The api_key you might see in chat requests is not for SDK authentication. It's a parameter you pass when calling LLM endpoints (for tracking/billing). The SDK itself authenticates with JWT tokens from /v1/auth/login.

Basic Chat

import asyncio
from magick_mind import MagickMind

async def main():
    async with MagickMind(
        email="user@example.com",
        password="your_password",
        base_url="https://api.magickmind.ai",
    ) as client:
        response = await client.v1.chat.send(
            api_key="sk-your-llm-key",
            magickspace_id="mind-789",
            message="Hello!",
            enduser_id="user-456",
        )
        print(response.content.content)  # AI response text

asyncio.run(main())

Realtime (Decorator API)

import asyncio
from magick_mind import MagickMind
from magick_mind.realtime.events import ChatMessageEvent, EventContext

async def main():
    client = MagickMind(
        email="user@example.com",
        password="password", 
        base_url="https://api.magickmind.ai",
        ws_endpoint="wss://api.magickmind.ai/connection/websocket"
    )

    # Register handler — optional EventContext identifies the end user
    @client.realtime.on("chat_message")
    async def handle_chat(event: ChatMessageEvent, ctx: EventContext):
        print(f"Message for {ctx.target_user_id}: {event.payload.message}")

    # Connect and subscribe
    await client.realtime.connect()
    await client.realtime.subscribe_many(["user-1", "user-2"])

    # Keep listening...
    await asyncio.sleep(60)

asyncio.run(main())

Key Concepts

MagickSpaces

MagickSpace is the central organizing concept in the Magick Mind API - it's where conversations, knowledge, and collaboration converge:

• All chat conversations happen within a magickspace
• Knowledge (corpus) attaches to magickspaces to provide context for AI responses
• Users collaborate through magickspaces (private for individuals, group for teams)
• Most operations reference a magickspace_id

📖 Learn more: MagickSpace Resource Guide

Service Users

This SDK is designed for service-level authentication (email/password). Your backend authenticates as a service user and acts on behalf of end users.

Common architecture:

[Your Frontend/App] ←→ [Your Backend + This SDK] ←→ [Magick Mind API]

For direct device-to-API patterns (robotics/IoT), see Event-Driven Patterns.

Documentation

Architecture

• Backend Architecture - Service-level integration patterns
• Event-Driven Patterns - Events as source of truth vs. notifications
• Realtime Patterns - WebSocket subscription patterns

Guides

• Backend Integration - Production patterns for message deduplication, hybrid sync, recovery
• Error Handling - Exception types, retry patterns, production examples
• Advanced Usage - Direct HTTP client access for power users
• Persona & Prepare - AI persona creation, versioning, and system prompt generation
• Realtime Guide - Complete WebSocket guide with bulk operations and relay architecture

Resources

• MagickSpace - Central organizing concept
• Corpus - Knowledge base management
• Artifact - Document/blob storage
• End User - User identity management
• Project - Project organization

Contributing

• Contributing Guide - How to extend the SDK
• Resource Implementation Guide - Template for adding typed resources

Development

Setup

# Clone repository
git clone https://github.com/General-Magick-Industries/py-magickmind
cd py-magickmind

# Install dependencies
uv sync --all-extras

Testing

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_auth.py -v

# Run with coverage
uv run pytest tests/ --cov=magick_mind --cov-report=html

Type Checking

uv run pyright

Formatting

uv run ruff format .

Examples

The examples/ directory contains working examples demonstrating key SDK patterns:

📖 See examples/README.md for detailed descriptions and usage.

Quick start:

# 1. Set environment variables
export MAGICKMIND_BASE_URL="http://localhost:8888"
export MAGICKMIND_EMAIL="user@example.com"
export MAGICKMIND_PASSWORD="your_password"

# 2. Create test resources
uv run python examples/setup_resources.py

# 3. Run an example
uv run python examples/authentication.py

License

MIT License - see LICENSE file for details.

Authors

• Adrian (adrian@magickmind.ai)
• Minnie (minnie@magickmind.ai)
• Turtle (turtle@magickmind.ai)