nni-sdk 0.1.0__tar.gz

nni_sdk-0.1.0/Cargo.lock

@@ -0,0 +1,181 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "nni_engine"
+version = "0.1.0"
+dependencies = [
+ "libc",
+ "pyo3",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

nni_sdk-0.1.0/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "nni_engine"
+version = "0.1.0"
+edition = "2021"
+readme = "README.md"
+
+[lib]
+name = "nni"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.22", features = ["extension-module", "abi3-py38"] }
+
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
+[target.'cfg(windows)'.dependencies]
+libc = "0.2"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"
+strip = "symbols"

nni_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: nni-sdk
+Version: 0.1.0
+Summary: Sub-Microsecond Zero-Copy AI Tensor IPC Engine
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+"# NNI SDK`nZero-Copy High-Speed Sparse Tensor Acceleration Engine" | Out-File -Encoding utf8 README.md

nni_sdk-0.1.0/README.md

@@ -0,0 +1 @@
+"# NNI SDK`nZero-Copy High-Speed Sparse Tensor Acceleration Engine" | Out-File -Encoding utf8 README.md

nni_sdk-0.1.0/nni_sdk.py

@@ -0,0 +1,103 @@
+import ctypes
+import os
+import sys
+import numpy as np
+
+# Locate compiled C-FFI library
+def _load_nni_library():
+    base_dir = os.path.abspath(os.path.dirname(__file__))
+    target_dir = os.path.join(base_dir, "target", "release")
+    
+    if sys.platform == "darwin":
+        lib_name = "libnni_engine.dylib"
+    elif sys.platform == "win32":
+        lib_name = "nni_engine.dll"
+    else:
+        lib_name = "libnni_engine.so"
+        
+    lib_path = os.path.join(target_dir, lib_name)
+    if not os.path.exists(lib_path):
+        raise FileNotFoundError(f"NNI Core Library not found at {lib_path}. Run 'cargo build --release' first.")
+    return ctypes.CDLL(lib_path)
+
+_lib = _load_nni_library()
+
+class C_NniPacket(ctypes.Structure):
+    _pack_ = 1
+    _fields_ = [
+        ("sparsity_mask", ctypes.c_uint8 * 16),
+        ("scale", ctypes.c_float),
+        ("anchor_id", ctypes.c_uint32),
+        ("signature", ctypes.c_uint32),
+        ("active_values", ctypes.c_float * 9),
+    ]
+
+# C Function Prototypes
+_lib.nni_init_slate.argtypes = [ctypes.c_char_p]
+_lib.nni_init_slate.restype = ctypes.c_void_p
+
+_lib.nni_cleanup_slate.argtypes = [ctypes.c_char_p]
+
+_lib.nni_compress_sparse.argtypes = [
+    ctypes.POINTER(ctypes.c_float), ctypes.c_size_t, ctypes.c_float, ctypes.c_uint32, ctypes.POINTER(C_NniPacket)
+]
+
+_lib.nni_decompress_to_npu.argtypes = [
+    ctypes.POINTER(C_NniPacket), ctypes.POINTER(ctypes.c_float)
+]
+
+_lib.nni_write_slot.argtypes = [ctypes.c_void_p, ctypes.c_uint32, C_NniPacket]
+
+_lib.nni_wait_for_slot.argtypes = [
+    ctypes.c_void_p, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(C_NniPacket)
+]
+_lib.nni_wait_for_slot.restype = ctypes.c_uint32
+
+# ===================================================================== #
+#                  PYTHON DEVELOPER API LAYER                           #
+# ===================================================================== #
+
+class NNISlate:
+    """Zero-Copy Memory Mapped Slate Manager"""
+    def __init__(self, name: str = "nni_shared_slate"):
+        self.name_bytes = name.encode('utf-8')
+        self.slate_ptr = _lib.nni_init_slate(self.name_bytes)
+        if not self.slate_ptr:
+            raise RuntimeError("Failed to initialize NNI Memory Mapped Slate.")
+
+    def write_slot(self, slot_id: int, packet: C_NniPacket):
+        _lib.nni_write_slot(self.slate_ptr, slot_id, packet)
+
+    def wait_for_slot(self, slot_id: int, last_seen_version: int):
+        out_packet = C_NniPacket()
+        new_version = _lib.nni_wait_for_slot(self.slate_ptr, slot_id, last_seen_version, ctypes.byref(out_packet))
+        return out_packet, new_version
+
+    def close(self):
+        if self.slate_ptr:
+            _lib.nni_cleanup_slate(self.name_bytes)
+            self.slate_ptr = None
+
+class NNIEngine:
+    """High-Speed Sparse Accelerator Engine for PyTorch / NumPy Arrays"""
+    
+    @staticmethod
+    def compress_tensor(tensor_array, threshold: float = 0.5, anchor_id: int = 1) -> C_NniPacket:
+        """Compresses 128-element float tensor into sub-10ns NNI Packet"""
+        flat_data = np.ascontiguousarray(tensor_array, dtype=np.float32)
+        assert flat_data.size >= 128, "Input tensor must have at least 128 elements."
+        
+        c_float_ptr = flat_data.ctypes.data_as(ctypes.POINTER(ctypes.c_float))
+        out_packet = C_NniPacket()
+        
+        _lib.nni_compress_sparse(c_float_ptr, 128, ctypes.c_float(threshold), anchor_id, ctypes.byref(out_packet))
+        return out_packet
+
+    @staticmethod
+    def decompress_to_npu(packet: C_NniPacket) -> np.ndarray:
+        """Decompresses sparse packet directly into a 128-float NumPy / NPU scratchpad"""
+        output = np.zeros(128, dtype=np.float32)
+        c_output_ptr = output.ctypes.data_as(ctypes.POINTER(ctypes.c_float))
+        
+        _lib.nni_decompress_to_npu(ctypes.byref(packet), c_output_ptr)
+        return output

nni_sdk-0.1.0/note.txt

@@ -0,0 +1,17 @@
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+
+python -m maturin develop --release
+
+
+
+--------
+
+# 1. Bypass the Python 3.14 version lock check
+$env:PYO3_USE_ABI3_FORWARD_COMPATIBILITY="1"
+
+# 2. Build the Native C-Extension
+maturin develop --release
+
+# 3. Run the Native PyO3 Illusion Test!
+python test_pyo3_native.py

nni_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["maturin>=1.0,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "nni-sdk"
+version = "0.1.0"
+description = "Sub-Microsecond Zero-Copy AI Tensor IPC Engine"
+readme = "README.md"
+requires-python = ">=3.8"
+
+[tool.maturin]
+module-name = "nni"

nni_sdk-0.1.0/run_demo.py

@@ -0,0 +1,21 @@
+import nni_engine
+
+# 1. Initialize Zero-Copy Memory Slate
+slate = nni_engine.PySharedSlate("ai_pipeline")
+
+# 2. Compress 128 Floats
+packet = nni_engine.compress_sparse([1.0, 2.0, 3.0] + [0.0] * 125, 0.5, 999)
+
+# 3. Write to Slate
+slate.write_slot(0, packet)
+
+# 4. Read back
+read_packet, version = slate.wait_for_slot(0, last_seen_version=0)
+scratchpad = read_packet.decompress_to_npu()
+
+print("--------------------------------------------------")
+print(">>> NNI ENGINE RUNNING AT NANOSECOND SPEED! <<<")
+print("Recovered Scratchpad[0]:", scratchpad[0])
+print("Recovered Scratchpad[1]:", scratchpad[1])
+print("Recovered Scratchpad[2]:", scratchpad[2])
+print("--------------------------------------------------")

nni_sdk-0.1.0/src/lib.rs

@@ -0,0 +1,269 @@
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::ffi::CString;
+
+use pyo3::prelude::*;
+use pyo3::types::PyModule;
+use pyo3::Bound;
+
+pub const MAX_SLOTS: usize = 100;
+
+#[repr(C, align(64))]
+#[derive(Copy, Clone, Debug)]
+pub struct NniPacket {
+    pub sparsity_mask: [u8; 16],
+    pub scale: f32,              
+    pub anchor_id: u32,          
+    pub signature: u32,          
+    pub active_values: [f32; 9], 
+}
+
+#[repr(C, align(64))]
+pub struct SharedSlate {
+    pub total_slots: u32,
+    pub flags: [AtomicU32; MAX_SLOTS], 
+    pub packets: [NniPacket; MAX_SLOTS],
+}
+
+impl NniPacket {
+    pub fn compress_sparse(floats: &[f32], threshold: f32, anchor_id: u32) -> Self {
+        let mut sparsity_mask = [0u8; 16];
+        let mut active_values = [0.0f32; 9];
+        let mut active_count = 0;
+        let mut abs_sum = 0.0;
+        
+        let limit = floats.len().min(128);
+        for i in 0..limit {
+            let val = floats[i];
+            if val.abs() >= threshold {
+                sparsity_mask[i / 8] |= 1 << (i % 8);
+                abs_sum += val.abs();
+                if active_count < 9 {
+                    active_values[active_count] = val;
+                    active_count += 1;
+                }
+            }
+        }
+        
+        let scale = if active_count > 0 { abs_sum / active_count as f32 } else { 0.0 };
+        let signature = generate_signature(&sparsity_mask, anchor_id);
+        
+        NniPacket { sparsity_mask, scale, anchor_id, signature, active_values }
+    }
+
+    pub fn decompress_to_npu(&self, scratchpad: &mut [f32; 128]) {
+        let mut active_idx = 0;
+        for i in 0..128 {
+            let mask_byte = self.sparsity_mask[i / 8];
+            let bit_active = (mask_byte >> (i % 8)) & 1;
+            if bit_active == 1 {
+                if active_idx < 9 {
+                    scratchpad[i] = self.active_values[active_idx];
+                    active_idx += 1;
+                }
+            } else {
+                scratchpad[i] = 0.0;
+            }
+        }
+    }
+}
+
+fn generate_signature(mask: &[u8; 16], anchor_id: u32) -> u32 {
+    let mut sig: u32 = 0x811C9DC5;
+    for &byte in mask.iter() {
+        sig ^= byte as u32;
+        sig = sig.wrapping_mul(0x01000193);
+    }
+    sig ^= anchor_id;
+    sig = sig.wrapping_mul(0x01000193);
+    sig
+}
+
+// ==========================================
+// WINDOWS KERNEL MMAP & SIGNALING
+// ==========================================
+#[cfg(windows)]
+extern "system" {
+    fn CreateFileMappingA(hFile: *mut libc::c_void, lpAttr: *mut libc::c_void, protect: u32, max_high: u32, max_low: u32, name: *const u8) -> *mut libc::c_void;
+    fn MapViewOfFile(hObj: *mut libc::c_void, access: u32, offset_high: u32, offset_low: u32, bytes: usize) -> *mut libc::c_void;
+    fn CloseHandle(hObj: *mut libc::c_void) -> i32;
+    fn CreateEventA(lpAttr: *mut libc::c_void, bManualReset: i32, bInitialState: i32, lpName: *const u8) -> *mut libc::c_void;
+    fn SetEvent(hEvent: *mut libc::c_void) -> i32;
+    fn WaitForSingleObject(hHandle: *mut libc::c_void, dwMilliseconds: u32) -> u32;
+}
+
+#[cfg(windows)] static mut EVENT_HANDLES: [usize; MAX_SLOTS] = [0; MAX_SLOTS];
+#[cfg(windows)] static INIT_HANDLES: std::sync::Once = std::sync::Once::new();
+#[cfg(windows)] static mut SHM_HANDLE: *mut libc::c_void = std::ptr::null_mut();
+#[cfg(windows)] static mut SHM_VIEW_PTR: *mut libc::c_void = std::ptr::null_mut();
+
+#[cfg(windows)]
+unsafe fn get_event_handle(slot_id: u32) -> *mut libc::c_void {
+    INIT_HANDLES.call_once(|| {});
+    let slot_idx = slot_id as usize;
+    if slot_idx < MAX_SLOTS && EVENT_HANDLES[slot_idx] == 0 {
+        let event_name = CString::new(format!("nni_event_slot_{}", slot_id)).unwrap();
+        let handle = CreateEventA(std::ptr::null_mut(), 0, 0, event_name.as_ptr() as *const u8);
+        EVENT_HANDLES[slot_idx] = handle as usize;
+    }
+    if slot_idx < MAX_SLOTS { EVENT_HANDLES[slot_idx] as *mut libc::c_void } else { std::ptr::null_mut() }
+}
+
+#[cfg(windows)] unsafe fn trigger_kernel_event(slot_id: u32) { let h = get_event_handle(slot_id); if !h.is_null() { SetEvent(h); } }
+#[cfg(windows)] unsafe fn wait_on_kernel_event(slot_id: u32) { let h = get_event_handle(slot_id); if !h.is_null() { WaitForSingleObject(h, 0xFFFFFFFF); } }
+
+#[cfg(windows)]
+unsafe fn init_slate_native(name: &str) -> *mut SharedSlate {
+    let size = std::mem::size_of::<SharedSlate>();
+    let c_name = CString::new(name).unwrap();
+    let handle = CreateFileMappingA(-1isize as *mut libc::c_void, std::ptr::null_mut(), 0x04, 0, size as u32, c_name.as_ptr() as *const u8);
+    if handle.is_null() { return std::ptr::null_mut(); }
+    let ptr = MapViewOfFile(handle, 0x000F001F, 0, 0, size);
+    if ptr.is_null() { CloseHandle(handle); return std::ptr::null_mut(); }
+    SHM_HANDLE = handle; SHM_VIEW_PTR = ptr;
+    let slate = ptr as *mut SharedSlate;
+    if (*slate).total_slots == 0 {
+        (*slate).total_slots = MAX_SLOTS as u32;
+        for i in 0..MAX_SLOTS { (*slate).flags[i].store(0, Ordering::Relaxed); }
+    }
+    slate
+}
+
+// ==========================================
+// UNIX KERNEL MMAP & SIGNALING
+// ==========================================
+#[cfg(unix)]
+use libc::{shm_open, mmap, ftruncate, close, PROT_READ, PROT_WRITE, MAP_SHARED, O_CREAT, O_RDWR, S_IRUSR, S_IWUSR};
+
+#[cfg(unix)] unsafe fn trigger_kernel_event(_slot_id: u32) {}
+#[cfg(unix)] unsafe fn wait_on_kernel_event(_slot_id: u32) {
+    for _ in 0..64 { std::hint::spin_loop(); }
+    std::thread::yield_now();
+}
+
+#[cfg(unix)]
+unsafe fn init_slate_native(name: &str) -> *mut SharedSlate {
+    let c_name = CString::new(name).unwrap();
+    #[cfg(target_os = "macos")]
+    let fd = shm_open(c_name.as_ptr(), O_CREAT | O_RDWR, (S_IRUSR | S_IWUSR) as libc::c_uint);
+
+    #[cfg(not(target_os = "macos"))]
+    let fd = shm_open(c_name.as_ptr(), O_CREAT | O_RDWR, (S_IRUSR | S_IWUSR) as libc::mode_t);
+
+    if fd < 0 { return std::ptr::null_mut(); }
+    let size = std::mem::size_of::<SharedSlate>();
+    ftruncate(fd, size as libc::off_t);
+    let ptr = mmap(std::ptr::null_mut(), size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+    close(fd);
+    if ptr == libc::MAP_FAILED { return std::ptr::null_mut(); }
+    let slate = ptr as *mut SharedSlate;
+    if (*slate).total_slots == 0 {
+        (*slate).total_slots = MAX_SLOTS as u32;
+        for i in 0..MAX_SLOTS { (*slate).flags[i].store(0, Ordering::Relaxed); }
+    }
+    slate
+}
+
+// ===================================================================== //
+//            PyO3 NATIVE EXTENSION WRAPPERS (ZERO-GIL EXECUTION)        //
+// ===================================================================== //
+
+/// Native Python Wrapper for NniPacket
+#[pyclass]
+#[derive(Clone)]
+pub struct PyNniPacket {
+    pub inner: NniPacket,
+}
+
+#[pymethods]
+impl PyNniPacket {
+    #[getter]
+    fn scale(&self) -> f32 { self.inner.scale }
+
+    #[getter]
+    fn anchor_id(&self) -> u32 { self.inner.anchor_id }
+
+    #[getter]
+    fn signature(&self) -> u32 { self.inner.signature }
+
+    /// Zero-GIL Hardware Decompression directly into a Python Float List
+    fn decompress_to_npu(&self, py: Python<'_>) -> Vec<f32> {
+        py.allow_threads(|| {
+            let mut scratchpad = [0.0f32; 128];
+            self.inner.decompress_to_npu(&mut scratchpad);
+            scratchpad.to_vec()
+        })
+    }
+}
+
+/// Native Python Wrapper for Shared Slate
+#[pyclass]
+pub struct PySharedSlate {
+    slate_ptr: *mut SharedSlate,
+}
+
+unsafe impl Send for PySharedSlate {}
+unsafe impl Sync for PySharedSlate {}
+
+#[pymethods]
+impl PySharedSlate {
+    #[new]
+    fn new(name: String) -> PyResult<Self> {
+        let slate_ptr = unsafe { init_slate_native(&name) };
+        if slate_ptr.is_null() {
+            return Err(pyo3::exceptions::PyRuntimeError::new_err("Failed to initialize Shared Memory Slate."));
+        }
+        Ok(PySharedSlate { slate_ptr })
+    }
+
+    /// Writes packet with ZERO-GIL overhead!
+    fn write_slot(&mut self, py: Python<'_>, slot_id: u32, packet: PyNniPacket) -> PyResult<()> {
+        if slot_id >= MAX_SLOTS as u32 {
+            return Err(pyo3::exceptions::PyValueError::new_err("Slot ID out of bounds."));
+        }
+        let slate_addr = self.slate_ptr as usize;
+        py.allow_threads(move || unsafe {
+            let slate = slate_addr as *mut SharedSlate;
+            (*slate).packets[slot_id as usize] = packet.inner;
+            (*slate).flags[slot_id as usize].fetch_add(1, Ordering::Release);
+            trigger_kernel_event(slot_id);
+        });
+        Ok(())
+    }
+
+    /// Waits for slot with ZERO-GIL overhead! (Python sleeps, Rust executes)
+    fn wait_for_slot(&self, py: Python<'_>, slot_id: u32, last_seen_version: u32) -> PyResult<(PyNniPacket, u32)> {
+        if slot_id >= MAX_SLOTS as u32 {
+            return Err(pyo3::exceptions::PyValueError::new_err("Slot ID out of bounds."));
+        }
+        let slate_addr = self.slate_ptr as usize;
+        let (packet, new_ver) = py.allow_threads(move || unsafe {
+            let slate = slate_addr as *mut SharedSlate;
+            let mut current_version = (*slate).flags[slot_id as usize].load(Ordering::Acquire);
+            while current_version <= last_seen_version {
+                wait_on_kernel_event(slot_id);
+                current_version = (*slate).flags[slot_id as usize].load(Ordering::Acquire);
+            }
+            ((*slate).packets[slot_id as usize], current_version)
+        });
+        
+        Ok((PyNniPacket { inner: packet }, new_ver))
+    }
+}
+
+/// Native High-Speed Sparse Compression Function
+#[pyfunction]
+fn compress_sparse(py: Python<'_>, floats: Vec<f32>, threshold: f32, anchor_id: u32) -> PyNniPacket {
+    let packet = py.allow_threads(|| {
+        NniPacket::compress_sparse(&floats, threshold, anchor_id)
+    });
+    PyNniPacket { inner: packet }
+}
+
+/// PyO3 0.22 Native Module Entry Point
+#[pymodule]
+fn nni(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<PyNniPacket>()?;
+    m.add_class::<PySharedSlate>()?;
+    m.add_function(wrap_pyfunction!(compress_sparse, m)?)?;
+    Ok(())
+}

nni_sdk-0.1.0/test_pyo3_native.py

@@ -0,0 +1,51 @@
+import time
+import nni_engine # NATIVE RUST EXTENSION IMPORTED DIRECTLY!
+
+def main():
+    print("==================================================")
+    print("      NNI-ENGINE PyO3 NATIVE EXTENSION DEMO       ")
+    print("==================================================")
+
+    # 1. Initialize Native Shared Slate
+    slate = nni_engine.PySharedSlate("pyo3_slate_demo")
+    print("[1] Slate Initialized via Native Rust Memory Mapping.")
+
+    # 2. Prepare 128-float Python List
+    raw_tensor = [0.0] * 128
+    raw_tensor[3] = 42.5
+    raw_tensor[88] = -15.25  # Binary exact 32-bit float fraction
+
+    # 3. Compress using Native Zero-GIL Rust
+    start = time.perf_counter_ns()
+    packet = nni_engine.compress_sparse(raw_tensor, 0.5, 9999)
+    compress_ns = time.perf_counter_ns() - start
+
+    print(f"[2] Native Sparse Packet Compressed in {compress_ns} ns ({compress_ns / 1000:.2f} µs).")
+    print(f"     -> Scale: {packet.scale:.4f}")
+    print(f"     -> Signature: 0x{packet.signature:X}")
+
+    # 4. Write Slot (Python GIL is released during write!)
+    slate.write_slot(0, packet)
+    print("[3] Packet Written to Shared Slate Slot #0.")
+
+    # 5. Read Back Slot (Python GIL is released during wait!)
+    read_packet, new_version = slate.wait_for_slot(0, last_seen_version=0)
+    print(f"[4] Read Packet Version #{new_version} from Slate.")
+
+    # 6. Decompress directly into Python
+    scratchpad = read_packet.decompress_to_npu()
+    print("[5] Decompressed directly into Target Scratchpad Array.")
+
+    # 7. Verification
+    assert scratchpad[3] == 42.5
+    assert scratchpad[88] == -15.25
+    assert scratchpad[0] == 0.0
+
+    print("--------------------------------------------------")
+    print("VERIFICATION SUCCESS: 100% Native PyO3 Illusion!")
+    print(f"Scratchpad[3]:  {scratchpad[3]} (Expected 42.5)")
+    print(f"Scratchpad[88]: {scratchpad[88]} (Expected -15.25)")
+    print("==================================================")
+
+if __name__ == "__main__":
+    main()