Metadata-Version: 2.4
Name: mlx-ash-kv
Version: 8.2.4
Summary: Asynchronous Self-Healing KV Cache for Silicon-Native LLMs by GDI Nexus
Author-email: GDI Nexus <contactus@gdinexus.com>
License: Apache-2.0
Project-URL: Homepage, https://gdinexus.com
Project-URL: Repository, https://github.com/iamrealvinnu/mlx-ash-kv
Project-URL: Bug Tracker, https://github.com/iamrealvinnu/mlx-ash-kv/issues
Keywords: mlx,llm,kv-cache,self-healing,apple-silicon,neural-engine,cuda,pytorch,varentropy,attention-masking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mlx>=0.18.0
Requires-Dist: numpy
Requires-Dist: rich
Requires-Dist: coremltools
Requires-Dist: gradio
Requires-Dist: mlx-lm
Requires-Dist: torch
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# ASH-KV: Hardware-Native Neural Integrity Middleware

[![Hardware](https://img.shields.io/badge/Hardware-Apple%20Silicon%20%26%20NVIDIA-blue)](#)
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](#)
[![Version](https://img.shields.io/badge/Version-8.2.4--beta-emerald)](#)
[![Company](https://img.shields.io/badge/Developed%20by-GDI%20Nexus-black)](https://gdinexus.com)

**ASH-KV** (Asynchronous Self-Healing KV Cache) is a high-performance middleware layer designed for **Runtime Neural Integrity Enforcement**. It leverages silicon-native kernels to monitor the mathematical uncertainty of the Attention Manifold and surgically prunes logical drift at the hardware level.

---

## 🔬 Technical Core

### ⚡ Deterministic Manifold Monitoring
Instead of heuristic text-scanning, ASH-KV monitors **Attention Varentropy**. By calculating the mathematical variance across the KV-Cache in real-time, the system identifies the exact moment a model's transition probability distribution collapses—the mathematical precursor to hallucination.

### 🛡️ Fused Kernel Mutation
When drift is detected, ASH-KV executes a **Gaussian Penalty Mask** directly within the model's compute graph.
*   **Apple Silicon**: Uses `@mx.compile` Fused Metal kernels for zero-latency mutation.
*   **NVIDIA**: Uses PyTorch/CUDA-synchronized tensor operations.
*   **Latency**: Measured at **< 0.9ms** on Apple M4 hardware (virtually 0% inference overhead).

### ♾️ Dynamic NVMe Paging (Context Extension)
ASH-KV breaks physical VRAM limitations by implementing an LRU-based paging system. "Cold" context chunks are offloaded to NVMe storage using zero-copy memory mapping, supporting 100k+ token windows on consumer-grade unified memory.

---

## 🚀 Performance Benchmarks (M4 Pro)
| Metric | Standard Cache | ASH-KV Protected |
| :--- | :--- | :--- |
| **Inference Latency** | 1.00x (Base) | 1.002x |
| **Healing Mutation** | N/A | **0.85 ms** |
| **Max Context (16GB)** | ~12k tokens | **100k+ tokens** (Paged) |
| **Hallucination Rate** | Baseline | **~85% Reduction** (Zero-Shot) |

---

## 🛠️ Implementation

### 1. Installation
```bash
pip install mlx-ash-kv
```

### 2. Integration
```python
from mlx_ash_kv.api import protect

# Wrap existing MLX or PyTorch model
# The HAL (Hardware Abstraction Layer) auto-detects silicon
protected_model, cache, shield, proxies = protect(model, sensitivity=0.85)
```

---

## 🏗️ Architecture (HAL)
The **Hardware Abstraction Layer** ensures the same code runs across disparate architectures:
*   **`MLXHealer`**: Fused Metal operations for Apple Silicon.
*   **`CudaHealer`**: Synchronized PyTorch operations for NVIDIA.
*   **`UniversalTensorCritic`**: Pure mathematical manifold evaluation.

---

### ⚠️ DISCLAIMER
ASH-KV is a probabilistic reliability layer for assisting professionals. It is NOT a substitute for professional clinical or legal judgment. All AI outputs must be verified by qualified humans.

---
© 2026 GDI Nexus Software Solutions LLP. All rights reserved.
