Metadata-Version: 2.4
Name: whitemagic
Version: 21.0.0
Summary: The Tool Substrate for Agentic AI — 28 PRAT Ganas, memory, ethical governance, and polyglot accelerators
Author: WhiteMagic Contributors
License: MIT
Project-URL: Homepage, https://github.com/whitemagic-ai/whitemagic
Project-URL: Documentation, https://github.com/whitemagic-ai/whitemagic/blob/main/docs/QUICKSTART.md
Project-URL: Repository, https://github.com/whitemagic-ai/whitemagic
Project-URL: Changelog, https://github.com/whitemagic-ai/whitemagic/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/whitemagic-ai/whitemagic/issues
Keywords: memory,ai,mcp,context,llm,agents,tools,governance,polyglot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.7
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "embeddings"
Requires-Dist: scipy>=1.10.0; extra == "embeddings"
Requires-Dist: faiss-cpu>=1.7.4; extra == "embeddings"
Provides-Extra: terminal
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == "cli"
Provides-Extra: tui
Requires-Dist: textual>=0.50.0; extra == "tui"
Provides-Extra: mcp
Requires-Dist: fastmcp>=0.4.1; extra == "mcp"
Provides-Extra: api
Requires-Dist: fastapi>=0.104.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "api"
Requires-Dist: python-multipart>=0.0.6; extra == "api"
Requires-Dist: email-validator>=2.0.0; extra == "api"
Requires-Dist: httpx>=0.25.0; extra == "api"
Provides-Extra: db
Requires-Dist: sqlalchemy>=2.0.0; extra == "db"
Requires-Dist: aiosqlite>=0.19.0; extra == "db"
Requires-Dist: asyncpg>=0.29.0; extra == "db"
Requires-Dist: alembic>=1.13.0; extra == "db"
Provides-Extra: encrypt
Requires-Dist: sqlcipher3>=0.5.0; extra == "encrypt"
Provides-Extra: cache
Requires-Dist: redis>=5.0.1; extra == "cache"
Provides-Extra: net
Requires-Dist: aiohttp>=3.9.0; extra == "net"
Requires-Dist: websockets>=12.0; extra == "net"
Requires-Dist: aiofiles>=23.2.1; extra == "net"
Requires-Dist: requests>=2.31.0; extra == "net"
Requires-Dist: urllib3<3.0.0,>=2.0.0; extra == "net"
Requires-Dist: chardet>=5.0.0; extra == "net"
Provides-Extra: openai
Requires-Dist: openai>=1.3.0; extra == "openai"
Requires-Dist: tiktoken>=0.5.0; extra == "openai"
Provides-Extra: auth
Requires-Dist: passlib[bcrypt]>=1.7.4; extra == "auth"
Provides-Extra: trust
Requires-Dist: xrpl-py>=3.0.0; extra == "trust"
Requires-Dist: PyNaCl>=1.5.0; extra == "trust"
Provides-Extra: numeric
Requires-Dist: numpy>=1.24.0; extra == "numeric"
Requires-Dist: scipy>=1.10.0; extra == "numeric"
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == "graph"
Provides-Extra: search
Requires-Dist: hnswlib>=0.8.0; extra == "search"
Requires-Dist: hdbscan>=0.8.33; extra == "search"
Provides-Extra: viz
Requires-Dist: umap-learn>=0.5.0; extra == "viz"
Requires-Dist: scikit-learn>=1.3.0; extra == "viz"
Provides-Extra: opt
Requires-Dist: cvxpy>=1.4.0; extra == "opt"
Provides-Extra: offline
Requires-Dist: sentence-transformers>=2.2.0; extra == "offline"
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "offline"
Requires-Dist: scipy>=1.10.0; extra == "offline"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.6; extra == "dev"
Requires-Dist: maturin>=1.3.0; extra == "dev"
Requires-Dist: nbconvert>=7.16.6; extra == "dev"
Requires-Dist: fastmcp>=0.4.1; extra == "dev"
Provides-Extra: watcher
Requires-Dist: watchdog>=3.0.0; extra == "watcher"
Provides-Extra: vision
Requires-Dist: opencv-python>=4.8.0; extra == "vision"
Requires-Dist: pytesseract>=0.3.10; extra == "vision"
Requires-Dist: Pillow>=10.0.0; extra == "vision"
Provides-Extra: dashboard
Requires-Dist: flask>=3.0.0; extra == "dashboard"
Requires-Dist: flask-cors>=4.0.0; extra == "dashboard"
Provides-Extra: heavy
Requires-Dist: sentence-transformers>=2.2.0; extra == "heavy"
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "heavy"
Requires-Dist: scipy>=1.10.0; extra == "heavy"
Requires-Dist: faiss-cpu>=1.7.4; extra == "heavy"
Requires-Dist: numpy>=1.24.0; extra == "heavy"
Requires-Dist: networkx>=3.0; extra == "heavy"
Requires-Dist: hnswlib>=0.8.0; extra == "heavy"
Requires-Dist: hdbscan>=0.8.33; extra == "heavy"
Requires-Dist: umap-learn>=0.5.0; extra == "heavy"
Requires-Dist: scikit-learn>=1.3.0; extra == "heavy"
Provides-Extra: full
Requires-Dist: aiosqlite>=0.19.0; extra == "full"
Requires-Dist: aiofiles>=23.2.1; extra == "full"
Requires-Dist: aiohttp>=3.9.0; extra == "full"
Requires-Dist: alembic>=1.13.0; extra == "full"
Requires-Dist: asyncpg>=0.29.0; extra == "full"
Requires-Dist: black>=23.0.0; extra == "full"
Requires-Dist: chardet>=5.0.0; extra == "full"
Requires-Dist: cvxpy>=1.4.0; extra == "full"
Requires-Dist: email-validator>=2.0.0; extra == "full"
Requires-Dist: faiss-cpu>=1.7.4; extra == "full"
Requires-Dist: fastapi>=0.104.0; extra == "full"
Requires-Dist: fastmcp>=0.4.1; extra == "full"
Requires-Dist: flask>=3.0.0; extra == "full"
Requires-Dist: flask-cors>=4.0.0; extra == "full"
Requires-Dist: httpx>=0.25.0; extra == "full"
Requires-Dist: isort>=5.13.0; extra == "full"
Requires-Dist: maturin>=1.3.0; extra == "full"
Requires-Dist: mypy>=1.0.0; extra == "full"
Requires-Dist: nbconvert>=7.16.6; extra == "full"
Requires-Dist: numpy>=1.24.0; extra == "full"
Requires-Dist: opencv-python>=4.8.0; extra == "full"
Requires-Dist: openai>=1.3.0; extra == "full"
Requires-Dist: passlib[bcrypt]>=1.7.4; extra == "full"
Requires-Dist: Pillow>=10.0.0; extra == "full"
Requires-Dist: pytest>=7.0.0; extra == "full"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "full"
Requires-Dist: pytest-cov>=4.1.0; extra == "full"
Requires-Dist: pytest-timeout>=2.2.0; extra == "full"
Requires-Dist: pytesseract>=0.3.10; extra == "full"
Requires-Dist: redis>=5.0.1; extra == "full"
Requires-Dist: requests>=2.31.0; extra == "full"
Requires-Dist: rich>=13.0.0; extra == "full"
Requires-Dist: ruff>=0.1.6; extra == "full"
Requires-Dist: scipy>=1.10.0; extra == "full"
Requires-Dist: sentence-transformers>=2.2.0; extra == "full"
Requires-Dist: sqlalchemy>=2.0.0; extra == "full"
Requires-Dist: textual>=0.50.0; extra == "full"
Requires-Dist: tiktoken>=0.5.0; extra == "full"
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "full"
Requires-Dist: urllib3<3.0.0,>=2.0.0; extra == "full"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "full"
Requires-Dist: watchdog>=3.0.0; extra == "full"
Requires-Dist: websockets>=12.0; extra == "full"
Requires-Dist: python-multipart>=0.0.6; extra == "full"
Requires-Dist: networkx>=3.0; extra == "full"
Requires-Dist: hnswlib>=0.8.0; extra == "full"
Requires-Dist: umap-learn>=0.5.0; extra == "full"
Requires-Dist: scikit-learn>=1.3.0; extra == "full"
Dynamic: license-file

# Whitemagic

[![CI](https://github.com/whitemagic-ai/whitemagic/actions/workflows/ci.yml/badge.svg)](https://github.com/whitemagic-ai/whitemagic/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/whitemagic)](https://pypi.org/project/whitemagic/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**The Tool Substrate for Agentic AI.**

> Start here for the canonical introduction: [`whitemagic/grimoire/00_PROLOGUE.md`](whitemagic/grimoire/00_PROLOGUE.md)

Whitemagic is a high-performance memory and tool infrastructure designed for AI agents. Its stable MCP contract is centered on 28 PRAT Gana meta-tools, with a larger internal dispatch and nested-tool surface behind them. It also provides tiered memory with 5D holographic coordinates and a Galactic Map lifecycle, ethical governance, multi-galaxy project-scoped databases, Edgerunner Violet security layer, local AI agent loops (Ollama), and polyglot accelerators.

If you're integrating Whitemagic into an agent runtime, start with `AI_PRIMARY.md`. If you need the single documentation center first, start with `whitemagic/grimoire/00_PROLOGUE.md`.

## Core Features

1.  **Memory Substrate**: Tiered memory management with native SQLite backing, 5D holographic coordinates (XYZWV), a Galactic Map lifecycle (no memory is ever deleted — only rotated outward), constellation detection, and association mining.
2.  **Unified MCP Tool Surface** exposed through `whitemagic.tools.unified_api` with a composable middleware pipeline (input sanitizer → circuit breaker → rate limiter → RBAC → maturity gate → governor → core router → compact response).
3.  **PRAT Mode (28 Gana Meta-Tools)**: The Polymorphic Resonant Adaptive Tools router presents WhiteMagic through 28 Ganas — consciousness lenses based on the Chinese Lunar Mansions. Every call carries resonance context (predecessor output, lunar phase, Harmony Vector, Wu Xing boost, Guna adaptation). Enable with `WM_MCP_PRAT=1`.
4.  **Capability Matrix**: 25 subsystems, 28 active cross-system fusions, 0 unexplored — all queryable via `capability.matrix` MCP tool.
5.  **MCP Native**: Built from the ground up to be served via the Model Context Protocol (MCP).
6.  **Self-Regulating**: Harmony Vector (7-dimension health), Dharma Rules Engine (ethical governance with YAML hot-reload), Homeostatic Loop (auto-correction), Karma Ledger (side-effect auditing), Circuit Breakers, Maturity Gates, Agent Trust scoring.
7.  **9-Language Polyglot**: Python core with compiled accelerators in Rust (PyO3), Zig (SIMD), Haskell (FFI), Elixir (OTP), Mojo (GPU/SIMD), Go (libp2p mesh), Julia (statistical forecasting), and TypeScript (SDK). Every module has a Python bridge with graceful fallback.

### ⚡ v21 Polyglot Architecture ("The Lichen Model")

WhiteMagic v21 marks the transition to a true **Lichen Architecture**, where high-level reasoning (Python) is symbiotically fused with low-level accelerators (Rust, Elixir, Zig, Koka).

- 🦀 **Rust Supremacy**: Constellation detection and Graph engine are now primary-path Rust. 10-50x speedup on clustering.
- 🧪 **OTP Concurrency (Elixir)**: Dream Cycle is now a 12-phase GenServer state machine. Real-time event streaming via GardenPubSub.
- 🛡️ **Effect-Safe Persistence (Koka)**: Atomic memory storage verified by Koka's effect system.
- ⚡ **Zig SIMD HRR**: Circular convolution and correlation for holographic memory accelerated via Zig SIMD.
- 🎯 **LoCoMo Accuracy**: Achieved **88.0% hit rate**, outperforming major RAG baselines.

---

### 📦 v21 Installation Vectors

### From Source (Recommended For This Repo)
```bash
# A pre-configured venv exists at .venv/ with all deps + Mojo 0.26.1
source .venv/bin/activate

# Or create a fresh venv:
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev,mcp,cli]"

# One-shot "everything" install:
pip install -e ".[full]"
```

### Optional: Polyglot Accelerators
```bash
# Rust (PyO3 — recommended, biggest performance gains)
cd whitemagic-rust && maturin develop --release

# Haskell (algebraic Dharma rules, dependency graph planner)
cd haskell && cabal build

# Elixir (OTP actor-model event bus, dream scheduler)
cd elixir && mix compile --force

# Go (2 modules: whitemagic-go + mesh/libp2p)
cd whitemagic-go && go build ./...
cd mesh && go build ./...

# Zig (SIMD cosine similarity, holographic projection)
cd whitemagic-zig && zig build

# Mojo (batch encoding, neuro scoring — requires Mojo 0.26+)
cd whitemagic-mojo && mojo build src/satkona_yang.mojo
```

## Quick Start

### State Root (Important)
Whitemagic writes runtime state (DB, logs, artifacts) under `WM_STATE_ROOT` (default `~/.whitemagic`).
For demos/tests/containers, set it explicitly:
```bash
export WM_STATE_ROOT=/tmp/whitemagic_state
```
The SQLite DB path defaults to `$WM_STATE_ROOT/memory/whitemagic.db`. To override it:
```bash
export WM_DB_PATH=/tmp/whitemagic_state/memory/whitemagic.db
```

### CLI
The `wm` command line tool provides immediate access to the substrate:
```bash
wm status
wm remember "We chose SQLite for Phase 1." --title "Architectural Decision" --tags architecture,v11 --type short_term
wm recall "architecture" --limit 5
```

### MCP Server (stdio)
```bash
# PRAT mode — 28 Gana meta-tools (recommended for AI clients)
WM_MCP_PRAT=1 python -m whitemagic.run_mcp

# Lean mode — 28 Gana meta-tools with MCP 3.0 features (icons, instructions, tasks)
python -m whitemagic.run_mcp_lean

# Lean mode over HTTP (Streamable HTTP transport, port 8770)
python -m whitemagic.run_mcp_lean --http

# Classic mode — legacy broad-surface registration; verify current availability against live code before relying on exact counts
python -m whitemagic.run_mcp

# Lite mode — 92 core tools
WM_MCP_LITE=1 python -m whitemagic.run_mcp
```

If your MCP client supports per-repo server configs, see `.mcp.json.example`.
Additional client examples: `docs/MCP_CONFIG_EXAMPLES.md`.

#### MCP Quickstart for AI Clients

1. **Install**: `pip install whitemagic[mcp]` (or `pip install -e ".[mcp]"` from source)
2. **Add to MCP config** (e.g., `.mcp.json`, Claude Desktop config, or Windsurf settings):
   ```json
   {"mcpServers": {"whitemagic": {"command": "python", "args": ["-m", "whitemagic.run_mcp_lean"]}}}
   ```
3. **On first connect**: Search for `quickstart guide` — WhiteMagic ships with 12 built-in guide memories covering the full system.
4. **Orientation resources** (MCP resources readable by clients):
   - `whitemagic://orientation/prologue` — Canonical introduction
   - `whitemagic://orientation/ai-primary` — Full technical contract
   - `whitemagic://orientation/server-instructions` — Tool usage guide
   - `whitemagic://orientation/system-map` — Repo structure

### Python API
```python
from whitemagic.tools.unified_api import call_tool

# Store
out = call_tool(
    "create_memory",
    title="Architectural Decision",
    content="We chose SQLite for Phase 1.",
    tags=["architecture", "v11"],
    type="short_term",
)
assert out["status"] == "success"

# Recall
out = call_tool("search_memories", query="architecture", limit=5)
assert out["status"] == "success"
print(out["details"]["results"][0]["entry"]["content"])

# Introspection (Gnosis portal — unified health snapshot)
out = call_tool("gnosis", compact=True)
```

## Architecture

*   `whitemagic/`: Core Python package (~195K LOC) with a large internal tool and dispatch surface.
*   `whitemagic/tools/prat_router.py`: PRAT router — maps the broader internal tool surface into 28 Gana meta-tools.
*   `whitemagic/tools/`: Canonical tool registry, dispatch pipeline, and handler modules.
*   `whitemagic/core/ganas/`: 28 Gana architecture (4 quadrant files + chain + base + karma + lunar + swarm).
*   `whitemagic/core/memory/`: Memory substrate — embeddings (HNSW), entropy scoring, causal mining, UMAP projection, graph walker, surprise gate, lifecycle, galactic map.
*   `whitemagic-rust/`: Rust accelerator (~8.5K LOC) — galactic batch scoring, association mining, 5D KD-tree, SIMD search.
*   `haskell/`: Haskell accelerator (~1.7K LOC) — algebraic Dharma rules, dependency graph planner, FFI bridge.
*   `elixir/`: Elixir OTP (~1.4K LOC) — actor-model Gan Ying event bus, dream scheduler, supervision trees.
*   `whitemagic-go/` + `mesh/`: Go (~913 LOC) — libp2p P2P mesh, mDNS discovery, protobuf messaging.
*   `whitemagic-zig/`: Zig (~795 LOC) — SIMD cosine similarity, holographic projection, memory management.
*   `whitemagic-mojo/`: Mojo (~1.2K LOC) — batch coordinate encoding, neuro scoring, satkona yang.

> **Note:** Local inference (Ollama/LlamaCPP) has been decoupled from the core loop in v11. Agents should bring their own "Brain" (via MCP or direct API calls) and use Whitemagic purely as their *Hands and Memory*.
>
> Legacy embedded/local-model code is preserved under `whitemagic/_archived/` and remains disabled by default.

## Key Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `WM_STATE_ROOT` | Runtime state directory | `~/.whitemagic` |
| `WM_MCP_PRAT` | Enable 28-tool PRAT mode | unset |
| `WM_MCP_LITE` | Enable 92-tool lite mode | unset |
| `WM_MCP_CLIENT` | Schema adaptation (gemini/deepseek/qwen) | unset |
| `OLLAMA_HOST` | Ollama server for local inference | `localhost:11434` |
| `REDIS_URL` | Redis for Gan Ying events / mesh | `redis://localhost:6379` |

## Tests
```bash
python -m pytest tests/unit/ -q --no-header
```

## Contributing
See `docs/CONTRIBUTING.md`.

## Contact & Support
- **Email**: whitemagicdev@proton.me
- **GitHub**: [whitemagic-ai/whitemagic](https://github.com/whitemagic-ai/whitemagic)
- **XRP Tips**: `raakfKn96zVmXqKwRTDTH5K3j5eTBp1hPy` (gratitude-driven, always free)
- **License**: MIT
