Metadata-Version: 2.4
Name: sovereign-metal
Version: 1.0.1
Summary: Lightweight, zero-dependency Python-to-Metal GPGPU advection engine & local transformer
Author: Antigravity
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pyobjc-core
Requires-Dist: pyobjc-framework-Metal
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ⚜️ Sovereign-Metal

[![Mac OS](https://img.shields.io/badge/OS-macOS-blue.svg?style=flat-square)](https://www.apple.com/macos/)
[![Metal](https://img.shields.io/badge/GPU-Metal_2-orange.svg?style=flat-square)](https://developer.apple.com/metal/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)

A zero-dependency, high-throughput Python-to-Metal GPGPU advection engine and local transformer pipeline. Program custom MSL (Metal Shading Language) kernels directly from Python with **zero-copy unified memory alignment** and zero PCIe bus latency.

---

## 🔱 Core Features

*   **Zero-Copy Unified Memory:** Directly maps NumPy arrays into shared CPU/GPU buffers (`MTLResourceStorageModeShared`), completely bypassing PCIe transfer bottlenecks.
*   **Branchless Toroidal Boundary Wrapping:** Implements hardware-level bitwise wrapping `(x - 1u) & (dim - 1u)` inside MSL shaders, avoiding thread divergence and division stalls on integrated Apple/Intel GPUs.
*   **Zero-Latency Reduction Tree:** Runs a dedicated Shannon entropy, localization intensity, and energy proxy reduction kernel entirely in threadgroup scratchpad memory.
*   **Standalone GPGPU Transformer:** Runs FP16 BERT-style embeddings (`all-MiniLM-L6-v2`) locally on Metal with strict GPGPU acceleration.

---

## 📐 Mathematical Framework

### Toroidal Fluid Dynamics (Soliton Advection)
The advection advects a continuous scalar field $S$ through a density field $\rho$ on a conjoined toroidal manifold:

$$\frac{\partial S}{\partial t} = -\nu \nabla^2 S - \alpha (\nabla \rho) \cdot \nabla S + \kappa |S|^2 S$$

Where:
*   $\nu$ represents the dissipation/damping coefficient.
*   $\alpha$ is the advection coupling strength.
*   $\kappa$ is the non-linear soliton crystallization rate.

---

## 🚀 Quick Start

### 1. Installation
Clone the repository and install the dependencies:
```bash
cd sovereign-metal
pip install -e .
```

### 2. Run Semantic Embeddings Demo
Verify the local GPGPU transformer inference:
```bash
python examples/local_embeddings.py
```

### 3. Run Toroidal Advection Benchmark
Execute the soliton advection simulation and watch the real-time crystallization metrics stream from the GPU:
```bash
python examples/benchmark_advection.py
```

---

## ⚜️ License
MIT License. Crafted for the GPGPU developer community.
