magickmind 0.1.1__tar.gz

magickmind-0.1.1/.env.example

@@ -0,0 +1,4 @@
+BIFROST_BASE_URL=https://dev-bifrost.magickmind.ai
+BIFROST_EMAIL="user@example.com"
+BIFROST_PASSWORD="your_secure_password"
+BIFROST_WS_ENDPOINT=wss://dev-centrifugo.magickmind.ai/connection/websocket

magickmind-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: AGD Magick Mind CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Format and/or Lint with Ruff and Push Changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # 'ref:' determines which branch, tag, or commit the action checks out.
+          # For pull request events, 'github.head_ref' contains the source branch of the PR.
+          # For push events, 'github.head_ref' is empty, so we fall back to 'github.ref',
+          # which contains the full ref (e.g., "refs/heads/main").
+          ref: ${{ github.head_ref || github.ref }}
+
+      - name: Install and Format with Ruff
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "format"
+          # args: "check --fix"
+      # - run: ruff format
+      - name: Check for modified files
+        id: git_status
+        run: echo "modified=$(if git diff-index --quiet HEAD --; then echo "false"; else echo "true"; fi)" >> $GITHUB_OUTPUT
+        # run: |
+        #   if  git diff-index --quiet HEAD; then
+        #     echo "::set-output name=modified::true"
+        #   else
+        #     echo "::set-output name=modified::false"
+        #   fi
+      # - name: Debug set-output state
+      #   run: |
+      #     echo steps.git_status.outputs.modified
+      #     echo steps.git_status.outputs.modified == 'true'
+      # - name: Ensure branch is checked out
+      #   run: |
+      #     # Determine branch name based on event type
+      #     if [ -n "${GITHUB_HEAD_REF}" ]; then
+      #       # Pull Request event: use head ref (source branch)
+      #       branch="${GITHUB_HEAD_REF}"
+      #       echo "Detected a pull request. Using head ref: $branch"
+      #       # Fetch the branch from the remote if it isn’t available locally.
+      #       git fetch origin "${branch}:${branch}"
+      #     elif [[ "${GITHUB_REF}" == refs/heads/* ]]; then
+      #       # Push event: extract branch name from GITHUB_REF
+      #       branch="${GITHUB_REF#refs/heads/}"
+      #       echo "Detected a push event on branch: $branch"
+      #     else
+      #       echo "Not a branch event (likely a tag); skipping commit step."
+      #       exit 0
+      #     fi
+      #     echo "Switching to branch: $branch"
+      #     git switch $branch
+
+      - name: Push changes
+        if: steps.git_status.outputs.modified == 'true'
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+          git commit -am "CI Workflow: Style fixes by Ruff"
+          git push
+  # test:
+  #   name: Run Tests
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Checkout code
+  #       uses: actions/checkout@v4
+  #
+  #     - name: Set up Python
+  #       uses: actions/setup-python@v4
+  #       with:
+  #         python-version: "3.x"
+  #
+  #     - name: Install dependencies
+  #       run: pip install -r requirements.txt
+  #
+  #     - name: Run tests
+  #       run: pytest
+

magickmind-0.1.1/.gitignore

@@ -0,0 +1,26 @@
+**/__pycache__/
+.vscode/
+*.tar
+logs/
+.idea/
+tmp/
+
+# StarUML temporary files
+*.mdj.bak
+*.mdj~
+semantic_working_dir
+*.log
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+*.egg-info/
+
+# Hypothesis Cache
+.hypothesis/

magickmind-0.1.1/.gitrepo

@@ -0,0 +1,12 @@
+; DO NOT EDIT (unless you know what you are doing)
+;
+; This subdirectory is a git "subrepo", and this file is maintained by the
+; git-subrepo command. See https://github.com/ingydotnet/git-subrepo#readme
+;
+[subrepo]
+	remote = git@github.com:General-Magick-Industries/AGD_Magick_Mind_SDK.git
+	branch = main
+	commit = 93b35d17bc15bb09d080da87d028101f23fe2ee8
+	parent = 34e5948f872404c27c1278d8c3ddb2116302a61c
+	method = rebase
+	cmdver = 0.4.9

magickmind-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

magickmind-0.1.1/AGENTS.md

@@ -0,0 +1,270 @@
+# SDK - Official MagickMind Python Client
+
+> Python SDK for the Bifrost API gateway. For **service users** (backends/bots) to authenticate and interact with MagickMind on behalf of their end users.
+
+**Python runtime required** - Uses `httpx` and `centrifuge-python`. Runs in Python backends, CLI, scripts, desktop apps.
+
+## Architecture: Service Users vs End Users
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  YOUR SYSTEM                                                     │
+│  ┌──────────────┐     ┌──────────────────────────────────────┐  │
+│  │  Your End    │────▶│  Your Backend (Service User)         │  │
+│  │  Users       │     │  - Authenticates with Bifrost (JWT)  │  │
+│  │  (own auth)  │◀────│  - Manages end users via end-user svc│  │
+│  └──────────────┘     │  - Calls Bifrost with sender_id param│  │
+│                       └──────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼ SDK / REST
+┌─────────────────────────────────────────────────────────────────┐
+│  MAGICKMIND                                                      │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
+│  │ Bifrost  │──│ Xavier   │──│ Cortex   │──│ Centrifugo       │ │
+│  │ (gateway)│  │ (chat)   │  │ (AI)     │  │ (streaming)      │ │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Key concepts:**
+- **Service User**: Your backend/bot that authenticates with Bifrost via JWT (email/password login)
+- **End User**: YOUR users, managed by YOU. Created via `end-user` gRPC service. No direct Bifrost auth.
+- **sender_id/user_id**: End user identifier passed in API calls (e.g., chat requests)
+
+**Centrifugo channel format:** `personal:{end_user_id}#{service_account_id}`
+- Service subscribes to channels for its end users
+- Streams responses back to end users via YOUR transport (WebSocket, Telegram, etc.)
+
+## Purpose & Responsibilities
+
+- **Authentication**: Service user email/password → JWT with auto-refresh
+- **HTTP Client**: Authenticated requests to Bifrost REST API
+- **Typed Resources**: v1/chat, mindspace, artifact, end-user, etc. with Pydantic models
+- **Real-time**: Centrifugo pub/sub for streaming responses to relay to your end users
+- **End User Management**: Create/query/update end users scoped to your service account
+
+## Key Files & Entry Points
+
+| Need | Look Here |
+|------|-----------|
+| Main client | `magick_mind/client.py` - `MagickMind` class |
+| HTTP client | `magick_mind/http/client.py` - authenticated requests |
+| Real-time | `magick_mind/realtime/client.py` - Centrifugo subscriptions |
+| Auth provider | `magick_mind/auth/email_password.py` - JWT login/refresh |
+| Chat resource | `magick_mind/resources/v1/chat.py` |
+| Mindspace resource | `magick_mind/resources/v1/mindspace.py` |
+| Artifact resource | `magick_mind/resources/v1/artifact.py` |
+| Request/Response models | `magick_mind/models/v1/` |
+| Exceptions | `magick_mind/exceptions.py` |
+| Examples | `examples/` - usage patterns |
+
+## Quick Start
+
+```python
+from magick_mind import MagickMind
+
+# Initialize client as SERVICE USER (your backend)
+client = MagickMind(
+    email="myservice@example.com",  # Your service account
+    password="secret",
+    base_url="https://bifrost.magickmind.io"
+)
+
+# Create/get an end user (YOUR user, e.g., from your auth system)
+end_user = await client.v1.end_user.create_or_get(
+    external_id="your-user-123",  # Your user ID
+    metadata={"name": "Alice"}
+)
+
+# Send chat message ON BEHALF OF your end user
+response = await client.v1.chat.send(
+    mindspace_id="ms-123",
+    sender_id=end_user.id,  # End user ID
+    message="Hello, world!"
+)
+
+# Subscribe to Centrifugo for this end user's responses
+class MyHandler:
+    async def on_message(self, user_id: str, payload: dict):
+        # Relay this to YOUR end user via your transport
+        print(f"Response for {user_id}: {payload}")
+
+await client.realtime.connect(events=MyHandler())
+await client.realtime.subscribe(end_user.id)  # Subscribe for this end user
+```
+
+## Service-Specific Patterns
+
+### Authentication (Auto-Refresh)
+```python
+# magick_mind/auth/email_password.py
+# JWT refreshed automatically (expires_in - 10s buffer)
+client = MagickMind(email="...", password="...")
+# Token injected into all requests automatically
+
+# Check auth status
+if client.is_authenticated():
+    ...
+```
+
+### HTTP Requests
+```python
+# Low-level (magick_mind/http/client.py)
+response = await client.http.request("GET", "/v1/chat/messages")
+
+# High-level via resources
+messages = await client.v1.mindspace.get_messages(
+    mindspace_id="ms-123",
+    after_id="msg-456"  # For pagination/sync
+)
+```
+
+### Real-time Subscriptions
+```python
+# magick_mind/realtime/client.py
+# Channel format: personal:{end_user_id}#{service_account_id}
+# Service subscribes to channels for its end users
+
+class EventHandler:
+    async def on_message(self, end_user_id: str, payload: dict):
+        # Relay to YOUR end user via your transport (WebSocket, Telegram, etc.)
+        your_websocket.send(end_user_id, payload)
+    
+    async def on_error(self, error: Exception):
+        # Handle connection error
+        pass
+
+await client.realtime.connect(events=EventHandler())
+await client.realtime.subscribe(end_user_id="your-end-user-123")
+```
+
+### History Sync Pattern
+```python
+# Get messages since last known, then subscribe for real-time
+last_known_id = get_last_message_id_from_db()
+messages = await client.v1.mindspace.get_messages(
+    mindspace_id="ms-123",
+    after_id=last_known_id
+)
+save_to_db(messages)
+
+# Now subscribe for new messages for this end user
+await client.realtime.subscribe(end_user_id="your-end-user-123")
+```
+
+### Error Handling
+```python
+from magick_mind.exceptions import (
+    MagickMindError,      # Base exception
+    AuthenticationError,   # Login failed
+    TokenExpiredError,     # Token refresh failed
+    APIError,              # API returned error
+    RateLimitError,        # Rate limited
+)
+
+try:
+    await client.v1.chat.send(...)
+except AuthenticationError:
+    # Re-authenticate
+except APIError as e:
+    print(f"API error: {e.message}, status: {e.status_code}")
+```
+
+## Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# With coverage
+uv run pytest --cov=magick_mind
+```
+
+**Test structure**:
+```
+tests/
+├── conftest.py              # Fixtures: mock_auth, test_client, schema_registry
+├── test_auth.py             # Auth provider tests
+├── test_resources/          # Resource client tests
+├── test_realtime/           # Real-time subscription tests
+└── contract/                # OpenAPI contract validation
+    ├── openapi.json         # API schema
+    └── test_contracts.py    # Payload validation
+```
+
+**Fixtures** (`conftest.py`):
+- `mock_client` - httpx.MockTransport for HTTP mocking
+- `authenticated_client` - Pre-authenticated MagickMind instance
+- `mock_auth` - Mocked auth provider
+- `schema_registry` - OpenAPI schema validation
+
+**Mocking patterns**:
+```python
+# Mock auth
+@patch("magick_mind.auth.email_password._login")
+def test_auth(mock_login):
+    mock_login.return_value = {"access_token": "...", "expires_in": 3600}
+    ...
+
+# Mock HTTP with pytest-httpx
+def test_chat(httpx_mock):
+    httpx_mock.add_response(json={"message_id": "123"})
+    ...
+```
+
+## Configuration
+
+```python
+from magick_mind import MagickMind
+
+client = MagickMind(
+    email="service@example.com",
+    password="secret",
+    base_url="https://bifrost.magickmind.io",  # Or from BIFROST_BASE_URL env
+)
+```
+
+**Environment variables**:
+```bash
+BIFROST_BASE_URL=https://bifrost.magickmind.io
+# Credentials typically passed directly, not via env
+```
+
+## Dependencies
+
+Key packages from `pyproject.toml`:
+- `httpx>=0.27` - HTTP client
+- `pydantic>=2.0` - Models and validation
+- `centrifuge>=0.9` - Real-time WebSocket
+- `pydantic-settings` - Configuration
+
+**Dev dependencies**:
+- `pytest`, `pytest-httpx`, `pytest-asyncio` - Testing
+
+## Common Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest -v
+
+# Type check
+uv run pyright
+
+# Format
+uv run ruff format .
+```
+
+## Gotchas
+
+1. **Service users only** - This SDK authenticates service accounts (backends/bots), not end users. End users are managed via `end-user` service and passed as `sender_id`/`user_id` params.
+2. **Python only** - Uses httpx/centrifuge-python; for other languages, use Bifrost REST directly
+3. **Async preferred** - Most methods are async; use `asyncio.to_thread` for sync contexts
+4. **Auto-refresh timing** - Token refreshes 10s before expiry; long-running ops may still fail
+5. **Real-time before REST** - For chat, subscribe to channel BEFORE sending message to catch response
+6. **Contract tests** - Tests validate against `tests/contract/openapi.json`; update if API changes
+7. **Channel format** - `personal:{end_user_id}#{service_account_id}` - service subscribes for its end users
+8. **No direct frontend access** - End users don't call Bifrost directly; your backend relays via this SDK

magickmind-0.1.1/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-01-20
+
+### Added
+- **Realtime WebSocket Client**: Full support for real-time interaction in `magick_mind.realtime`.
+- **Resources**:
+    - `Chat` and `History` resources for messaging.
+    - `Mindspace`, `Project`, `EndUser`, `Corpus` resources for management.
+- **Artifacts**: Support for file uploads and attachment handling.
+- **Examples**:
+    - Detailed `setup_resources.py` script.
+    - Complete examples for Realtime Chat and Backend integration.
+

magickmind-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to Magick Mind SDK
+
+## Development Setup
+
+```bash
+# Clone and install
+git clone <repo>
+cd AGD_Magick_Mind_SDK
+uv sync
+```
+
+## Running Tests
+
+```bash
+# All tests
+uv run pytest
+
+# Contract tests only
+uv run pytest -m contract -v
+
+# Unit tests
+uv run pytest tests/unit/ -v
+```
+
+## Contract Testing Workflow
+
+We use serialization-based contract testing to ensure SDK models match the bifrost API.
+
+### How It Works
+
+1. **Spec snapshots** in `specs/` represent the API contract
+2. **Tests** validate that SDK payloads match the spec
+3. **Serializers** transform optional SDK fields to API-required defaults
+
+### Updating Specs
+
+When bifrost API changes:
+
+```bash
+# 1. Generate new spec in bifrost
+cd ../bifrost
+goctl api plugin -p goctl-openapi -api api/v1/*.api -dir .
+
+# 2. Copy to SDK (dev or main depending on branch)
+cp api/openapi.json ../AGD_Magick_Mind_SDK/specs/openapi.dev.json
+
+# 3. Run contract tests
+cd ../AGD_Magick_Mind_SDK
+uv run pytest -m contract -v
+
+# 4. Fix any failures by updating SDK models
+```
+
+### Adding New Models
+
+1. Add model to `tests/contract/test_payloads.py` → `MODEL_REGISTRY`
+2. Add instance creation in `create_minimal_instance()`
+3. Add `@field_serializer` for optional fields if needed
+
+See `tests/contract/README.md` for detailed instructions.
+
+## Code Style
+
+- Format: `uv run ruff format .`
+- Lint: `uv run ruff check .`
+- Type check: `uv run pyright`
+
+## Pull Request Process
+
+1. Create feature branch
+2. Make changes
+3. Run tests: `uv run pytest`
+4. Run contract tests: `uv run pytest -m contract`
+5. Submit PR

magickmind-0.1.1/GETTING_STARTED.md

@@ -0,0 +1,111 @@
+# Getting Started with Magick Mind SDK
+
+A 10-minute guide to running your first examples.
+
+## Prerequisites
+
+- Python 3.8+
+- Access to a Bifrost instance
+- Service credentials (email/password)
+
+## Step 1: Install SDK
+
+```bash
+cd AGD_Magick_Mind_SDK
+pip install -e .
+```
+
+## Step 2: Set Environment Variables
+
+**Option A: Using .env file** (Easier, persists across sessions)
+
+1. Copy `test.env` to `.env`:
+```bash
+cp test.env .env
+```
+
+2. Edit `.env` with your credentials
+3. Run examples using the helper script:
+```bash
+python run_example.py examples/chat_example.py
+```
+
+The helper script loads `.env` automatically (no extra dependencies needed).
+
+**Alternative: Source manually (Bash/zsh only)**
+
+```bash
+set -a; source .env; set +a
+python examples/chat_example.py
+```
+
+**Option B: Export manually** (Quick for testing)
+
+```bash
+# Bash/zsh
+export BIFROST_BASE_URL="http://localhost:8888"
+export BIFROST_EMAIL="service@example.com"
+export BIFROST_PASSWORD="your-password"
+
+# Fish
+set -gx BIFROST_BASE_URL "http://localhost:8888"
+set -gx BIFROST_EMAIL "service@example.com"
+set -gx BIFROST_PASSWORD "your-password"
+
+python examples/chat_example.py
+```
+
+## Step 3: Try Examples (In Order)
+
+### 1. Authentication (30 seconds)
+```bash
+python examples/email_password_auth.py
+```
+**What it does:** Connects to Bifrost and authenticates.
+
+### 2. Chat Message (1 minute)
+```bash
+python examples/chat_example.py
+```
+**What it does:** Sends a message to an AI mindspace.
+
+### 3. Message History (1 minute)
+```bash
+python examples/history_example.py
+```
+**What it does:** Fetches past messages with pagination.
+
+### 4. Realtime Messages (2 minutes)
+```bash
+python examples/realtime_chat.py
+```
+**What it does:** Listens for AI responses in real-time.
+
+### 5. Complete Workflow (5 minutes)
+```bash
+python examples/complete_chat_workflow.py
+```
+**What it does:** Full loop - send via HTTP, receive via realtime.
+
+## What's Next?
+
+**Explore by Category:**
+- **CRUD**: `mindspace_example.py`, `project_example.py`, `corpus_example.py`
+- **Backend Patterns**: `caching_example.py`, `notification_pattern_example.py`
+- **Production**: `backend_service.py`, `fan_out_relay.py`
+
+**Read Documentation:**
+- [Backend Architecture](docs/architecture/backend_architecture.md)
+- [Event-Driven Patterns](docs/architecture/event_driven_patterns.md)
+- [Realtime Guide](docs/realtime_guide.md)
+
+## Troubleshooting
+
+**"Connection refused"**
+→ Start Bifrost: `docker-compose up bifrost`
+
+**"Invalid credentials"**
+→ Check `BIFROST_EMAIL` and `BIFROST_PASSWORD` in your environment
+
+**"Module not found"**
+→ Run `pip install -e .` from SDK root directory