lqft-python-engine 0.1.9__tar.gz → 0.3.0__tar.gz

{lqft_python_engine-0.1.9 → lqft_python_engine-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: lqft-python-engine
-Version: 0.1.9
-Summary: LQFT Engine: Full CRUD Support (v4.5 Stable)
+Version: 0.3.0
+Summary: LQFT Engine: Memory Circuit Breaker & Strict Type Safety (v5.0 Stable)
 Home-page: https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-
 Author: Parjad Minooei
 License: MIT

{lqft_python_engine-0.1.9 → lqft_python_engine-0.3.0}/lqft_engine.c

@@ -11,24 +11,28 @@
 #include <stdint.h>
 
 /**
- * LQFT C-Engine - V4.5 (Full CRUD & Large Payload)
+ * LQFT C-Engine - V5.0 (Active ARC Deletion & Full CRUD)
  * Architect: Parjad Minooei
  * * CHANGE LOG:
- * - Added 'delete' method with bottom-up path reconstruction.
- * - Maintains Incremental FNV-1a Hashing for large payloads.
- * - Fixed Stack-to-Heap collision for multi-MB data.
+ * - Implemented Automatic Reference Counting (ARC).
+ * - Added cascading `decref` for immediate RAM reclamation on deletion.
+ * - Added Open-Addressing Tombstones to the Global Registry.
+ * - Resolved all GCC -Wsign-compare warnings for production-grade builds.
  */
 
 #define BIT_PARTITION 5
 #define MAX_BITS 64 
 #define MASK 0x1F 
 #define REGISTRY_SIZE 8000009 
+#define TOMBSTONE ((LQFTNode*)1) // Special pointer for freed registry slots
 
 typedef struct LQFTNode {
     void* value;
     uint64_t key_hash;
     struct LQFTNode* children[32]; 
     char struct_hash[17]; 
+    uint64_t full_hash_val; // Cached for O(1) registry removal
+    int ref_count;          // Tracks active branch dependencies
 } LQFTNode;
 
 static LQFTNode** registry = NULL;
@@ -38,6 +42,9 @@ static LQFTNode* global_root = NULL;
 const uint64_t FNV_OFFSET_BASIS = 14695981039346656037ULL;
 const uint64_t FNV_PRIME = 1099511628211ULL;
 
+// -------------------------------------------------------------------
+// Core Hashing & Memory Utilities
+// -------------------------------------------------------------------
 uint64_t fnv1a_update(uint64_t hash, const void* data, size_t len) {
     const uint8_t* p = (const uint8_t*)data;
     for (size_t i = 0; i < len; i++) {
@@ -69,10 +76,52 @@ LQFTNode* create_node(void* value, uint64_t key_hash) {
     if (!node) return NULL;
     node->value = value;
     node->key_hash = key_hash;
+    node->full_hash_val = 0;
+    node->ref_count = 0; // Starts at 0 until adopted by a parent
     for (int i = 0; i < 32; i++) node->children[i] = NULL;
     return node;
 }
 
+// -------------------------------------------------------------------
+// Active ARC Deletion Logic
+// -------------------------------------------------------------------
+void decref(LQFTNode* node) {
+    if (!node) return;
+    
+    node->ref_count--;
+    
+    // If no branches point to this node anymore, obliterate it.
+    if (node->ref_count <= 0) {
+        // 1. Cascade destruction to children
+        for (int i = 0; i < 32; i++) {
+            if (node->children[i]) {
+                decref(node->children[i]);
+            }
+        }
+        
+        // 2. Remove from global registry (Replace with Tombstone)
+        uint32_t idx = node->full_hash_val % REGISTRY_SIZE;
+        uint32_t start_idx = idx;
+        
+        while (registry[idx] != NULL) {
+            if (registry[idx] == node) {
+                registry[idx] = TOMBSTONE;
+                break;
+            }
+            idx = (idx + 1) % REGISTRY_SIZE;
+            if (idx == start_idx) break;
+        }
+        
+        // 3. Physically free memory back to the OS
+        if (node->value) free(node->value);
+        free(node);
+        physical_node_count--;
+    }
+}
+
+// -------------------------------------------------------------------
+// Merkle-DAG Deduplication
+// -------------------------------------------------------------------
 LQFTNode* get_canonical(void* value, uint64_t key_hash, LQFTNode** children) {
     if (!init_registry()) return NULL;
 
@@ -97,27 +146,47 @@ LQFTNode* get_canonical(void* value, uint64_t key_hash, LQFTNode** children) {
     sprintf(lookup_hash, "%016llx", (unsigned long long)full_hash);
     uint32_t idx = full_hash % REGISTRY_SIZE;
     uint32_t start_idx = idx;
+    int first_tombstone = -1;
 
+    // Search registry (Skipping Tomestones)
     while (registry[idx] != NULL) {
-        if (strcmp(registry[idx]->struct_hash, lookup_hash) == 0) {
-            if (value) free(value); 
+        if (registry[idx] == TOMBSTONE) {
+            if (first_tombstone == -1) first_tombstone = (int)idx;
+        } else if (registry[idx]->full_hash_val == full_hash && strcmp(registry[idx]->struct_hash, lookup_hash) == 0) {
+            if (value) free(value); // Free duplicate string payload
             return registry[idx];
         }
         idx = (idx + 1) % REGISTRY_SIZE;
         if (idx == start_idx) break; 
     }
 
+    // Create a physical new node if identity doesn't exist
     LQFTNode* new_node = create_node(value, key_hash);
     if (!new_node) return NULL;
+    
     if (children) {
-        for (int i = 0; i < 32; i++) new_node->children[i] = children[i];
+        for (int i = 0; i < 32; i++) {
+            new_node->children[i] = children[i];
+            // Anchor the child to this new parent
+            if (children[i]) children[i]->ref_count++; 
+        }
     }
+    
     strcpy(new_node->struct_hash, lookup_hash);
-    registry[idx] = new_node;
+    new_node->full_hash_val = full_hash;
+    
+    // Insert into registry (Reusing tombstones if possible)
+    // SYSTEM FIX: Explicitly cast first_tombstone to uint32_t to match idx
+    uint32_t insert_idx = (first_tombstone != -1) ? (uint32_t)first_tombstone : idx;
+    registry[insert_idx] = new_node;
     physical_node_count++;
+    
     return new_node;
 }
 
+// -------------------------------------------------------------------
+// Python Wrapper API
+// -------------------------------------------------------------------
 static PyObject* method_delete(PyObject* self, PyObject* args) {
     unsigned long long h;
     if (!PyArg_ParseTuple(args, "K", &h)) return NULL;
@@ -129,7 +198,6 @@ static PyObject* method_delete(PyObject* self, PyObject* args) {
     LQFTNode* curr = global_root;
     int bit_depth = 0;
 
-    // Trace path to target
     while (curr != NULL && curr->value == NULL) {
         uint32_t segment = (h >> bit_depth) & MASK;
         path_nodes[path_len] = curr;
@@ -139,10 +207,10 @@ static PyObject* method_delete(PyObject* self, PyObject* args) {
         bit_depth += BIT_PARTITION;
     }
 
-    // If not found, exit
+    // Key not found, abort
     if (curr == NULL || curr->key_hash != h) Py_RETURN_NONE;
 
-    // Rebuild bottom-up: start with NULL (the deleted leaf)
+    LQFTNode* old_root = global_root;
     LQFTNode* new_sub_node = NULL;
 
     for (int i = path_len - 1; i >= 0; i--) {
@@ -151,7 +219,8 @@ static PyObject* method_delete(PyObject* self, PyObject* args) {
         LQFTNode* new_children[32];
         int has_other_children = 0;
 
-        for (int j = 0; j < 32; j++) {
+        // SYSTEM FIX: Use uint32_t for j to safely compare with segment
+        for (uint32_t j = 0; j < 32; j++) {
             if (j == segment) new_children[j] = new_sub_node;
             else {
                 new_children[j] = p_node->children[j];
@@ -159,31 +228,15 @@ static PyObject* method_delete(PyObject* self, PyObject* args) {
             }
         }
 
-        if (!has_other_children && i > 0) {
-            new_sub_node = NULL; // Contract empty branch
-        } else {
-            new_sub_node = get_canonical(NULL, 0, new_children);
-        }
+        if (!has_other_children && i > 0) new_sub_node = NULL;
+        else new_sub_node = get_canonical(NULL, 0, new_children);
     }
 
+    // Anchor new root and release the old one
     global_root = (new_sub_node) ? new_sub_node : get_canonical(NULL, 0, NULL);
-    Py_RETURN_NONE;
-}
+    if (global_root) global_root->ref_count++;
+    if (old_root) decref(old_root); // Trigger Active Deletion Cascade
 
-static PyObject* method_free_all(PyObject* self, PyObject* args) {
-    if (registry != NULL) {
-        for (int i = 0; i < REGISTRY_SIZE; i++) {
-            if (registry[i] != NULL) {
-                if (registry[i]->value) free(registry[i]->value);
-                free(registry[i]);
-                registry[i] = NULL;
-            }
-        }
-        free(registry);
-        registry = NULL;
-    }
-    physical_node_count = 0;
-    global_root = NULL;
     Py_RETURN_NONE;
 }
 
@@ -191,15 +244,20 @@ static PyObject* method_insert(PyObject* self, PyObject* args) {
     unsigned long long h;
     char* val_str;
     if (!PyArg_ParseTuple(args, "Ks", &h, &val_str)) return NULL;
+    
     if (!global_root) {
         if (!init_registry()) return PyErr_NoMemory();
         global_root = get_canonical(NULL, 0, NULL);
+        global_root->ref_count++;
     }
+    
+    LQFTNode* old_root = global_root;
     LQFTNode* path_nodes[20];
     uint32_t path_segs[20];
     int path_len = 0;
     LQFTNode* curr = global_root;
     int bit_depth = 0;
+    
     while (curr != NULL && curr->value == NULL) {
         uint32_t segment = (h >> bit_depth) & MASK;
         path_nodes[path_len] = curr;
@@ -209,10 +267,13 @@ static PyObject* method_insert(PyObject* self, PyObject* args) {
         curr = curr->children[segment];
         bit_depth += BIT_PARTITION;
     }
+    
     LQFTNode* new_sub_node = NULL;
-    if (curr == NULL) { new_sub_node = get_canonical(portable_strdup(val_str), h, NULL); }
-    else if (curr->key_hash == h) { new_sub_node = get_canonical(portable_strdup(val_str), h, curr->children); }
-    else {
+    if (curr == NULL) { 
+        new_sub_node = get_canonical(portable_strdup(val_str), h, NULL); 
+    } else if (curr->key_hash == h) { 
+        new_sub_node = get_canonical(portable_strdup(val_str), h, curr->children); 
+    } else {
         unsigned long long old_h = curr->key_hash;
         char* old_val = portable_strdup((char*)curr->value);
         int temp_depth = bit_depth;
@@ -227,10 +288,16 @@ static PyObject* method_insert(PyObject* self, PyObject* args) {
                 new_children[s_new] = c_new;
                 new_sub_node = get_canonical(NULL, 0, new_children);
                 break;
-            } else { path_nodes[path_len] = NULL; path_segs[path_len] = s_old; path_len++; temp_depth += BIT_PARTITION; }
+            } else { 
+                path_nodes[path_len] = NULL; 
+                path_segs[path_len] = s_old; 
+                path_len++; 
+                temp_depth += BIT_PARTITION; 
+            }
         }
         if (new_sub_node == NULL) new_sub_node = get_canonical(portable_strdup(val_str), h, curr->children);
     }
+    
     for (int i = path_len - 1; i >= 0; i--) {
         if (path_nodes[i] == NULL) {
             LQFTNode* new_children[32] = {NULL};
@@ -245,7 +312,12 @@ static PyObject* method_insert(PyObject* self, PyObject* args) {
             new_sub_node = get_canonical(p_node->value, p_node->key_hash, new_children);
         }
     }
+    
+    // Anchor new root and release the old one
     global_root = new_sub_node;
+    global_root->ref_count++;
+    if (old_root) decref(old_root); // Trigger Active Deletion Cascade
+
     Py_RETURN_NONE;
 }
 
@@ -253,6 +325,7 @@ static PyObject* method_search(PyObject* self, PyObject* args) {
     unsigned long long h;
     if (!PyArg_ParseTuple(args, "K", &h)) return NULL;
     if (!global_root) Py_RETURN_NONE;
+    
     LQFTNode* curr = global_root;
     int bit_depth = 0;
     while (curr != NULL && curr->value == NULL) {
@@ -260,17 +333,35 @@ static PyObject* method_search(PyObject* self, PyObject* args) {
         curr = curr->children[segment];
         bit_depth += BIT_PARTITION;
     }
+    
     if (curr != NULL && curr->key_hash == h) return PyUnicode_FromString((char*)curr->value);
     Py_RETURN_NONE;
 }
 
+static PyObject* method_free_all(PyObject* self, PyObject* args) {
+    if (registry != NULL) {
+        for (int i = 0; i < REGISTRY_SIZE; i++) {
+            if (registry[i] != NULL && registry[i] != TOMBSTONE) {
+                if (registry[i]->value) free(registry[i]->value);
+                free(registry[i]);
+            }
+            registry[i] = NULL;
+        }
+        free(registry);
+        registry = NULL;
+    }
+    physical_node_count = 0;
+    global_root = NULL;
+    Py_RETURN_NONE;
+}
+
 static PyObject* method_get_metrics(PyObject* self, PyObject* args) {
     return Py_BuildValue("{s:i}", "physical_nodes", physical_node_count);
 }
 
 static PyMethodDef LQFTMethods[] = {
     {"insert", method_insert, METH_VARARGS, "Insert key-value"},
-    {"delete", method_delete, METH_VARARGS, "Delete key"},
+    {"delete", method_delete, METH_VARARGS, "Active ARC Delete key"},
     {"search", method_search, METH_VARARGS, "Search key"},
     {"get_metrics", method_get_metrics, METH_VARARGS, "Get engine stats"},
     {"free_all", method_free_all, METH_VARARGS, "Total memory wipe"},

{lqft_python_engine-0.1.9 → lqft_python_engine-0.3.0}/lqft_engine.py

@@ -1,5 +1,7 @@
 import hashlib
 import weakref
+import psutil
+import os
 
 # ---------------------------------------------------------
 # LEGACY PURE PYTHON LQFT (For reference/fallback)
@@ -39,7 +41,6 @@ class LQFTNode:
         return cls._null_cache['null']
 
 class LQFT:
-    """Legacy Pure Python Iterative Implementation."""
     def __init__(self, bit_partition=5, max_bits=256):
         self.partition = bit_partition 
         self.max_bits = max_bits 
@@ -62,7 +63,7 @@ class LQFT:
                 break
             curr = curr.children[segment]
             bit_depth += self.partition
-
+            
         new_sub_node = None
         if curr is null_node:
             new_sub_node = LQFTNode.get_canonical(value, None, h)
@@ -82,7 +83,7 @@ class LQFT:
                     temp_depth += self.partition
             if new_sub_node is None:
                 new_sub_node = LQFTNode.get_canonical(value, curr.children, h)
-
+                
         for entry in reversed(path):
             if entry[0] == "split":
                 new_sub_node = LQFTNode.get_canonical(None, {entry[1]: new_sub_node}, None)
@@ -103,8 +104,9 @@ class LQFT:
             if bit_depth >= self.max_bits: break
         return None
 
+
 # ---------------------------------------------------------
-# NEW: ADAPTIVE ENTERPRISE ENGINE (MScAC Portfolio)
+# ADAPTIVE ENTERPRISE ENGINE (v0.3.0)
 # ---------------------------------------------------------
 try:
     import lqft_c_engine
@@ -115,21 +117,40 @@ except ImportError:
 class AdaptiveLQFT:
     """
     A polymorphic, heuristic-driven data structure wrapper.
-    - Scale < 50,000: Acts as an ultra-lightweight C-Hash (Python Dict).
-    - Scale > 50,000: Automatically migrates to the Native C-Engine LQFT 
+    - Scale < threshold: Acts as an ultra-lightweight C-Hash (Python Dict).
+    - Scale > threshold: Automatically migrates to the Native C-Engine LQFT 
       for Merkle-DAG deduplication and folding.
     """
     def __init__(self, migration_threshold=50000):
         self.threshold = migration_threshold
         self.size = 0
         self.is_native = False
-        
-        # The "Mini Version": Python's highly optimized built-in dictionary
         self._light_store = {} 
+        
+        # --- Systems Architecture: Process Memory Limit ---
+        self.auto_purge_enabled = True
+        # Instead of global OS RAM, we set a hard cap for THIS specific process.
+        self.max_memory_mb = 1000.0 # 1 Gigabyte Limit
+        self.total_ops = 0
+        self._process = psutil.Process(os.getpid())
+
+    def _validate_type(self, key, value=None):
+        """Strict type guarding to prevent arbitrary objects from bleeding into C-Memory."""
+        if not isinstance(key, str):
+            raise TypeError(f"LQFT keys must be strings. Received: {type(key).__name__}")
+        if value is not None and not isinstance(value, str):
+            raise TypeError(f"LQFT values must be strings. Received: {type(value).__name__}")
 
     def _get_64bit_hash(self, key):
         """Generates a 64-bit unsigned hash for the C-Engine."""
-        return int(hashlib.md5(str(key).encode()).hexdigest()[:16], 16)
+        return int(hashlib.md5(key.encode()).hexdigest()[:16], 16)
+
+    def purge(self):
+        """Manual Purge Override to instantly free RAM."""
+        current_mb = self._process.memory_info().rss / (1024 * 1024)
+        if current_mb >= self.max_memory_mb:
+            print(f"\n[⚠️ CIRCUIT Breaker] Engine exceeded {self.max_memory_mb} MB limit (Currently {current_mb:.1f} MB). Auto-Purging!")
+        self.clear()
 
     def _migrate_to_native(self):
         """The 'Curve Flip' mechanism: moves all data to the Heavy Engine."""
@@ -142,58 +163,75 @@ class AdaptiveLQFT:
             h = self._get_64bit_hash(key)
             lqft_c_engine.insert(h, val)
             
-        # Clear the lightweight store to free up memory
         self._light_store.clear()
         self.is_native = True
 
     def insert(self, key, value):
+        # 1. Type Guard (Blocks the Poison Pill test)
+        self._validate_type(key, value)
+
+        # 2. Performance Safety: Process Memory Check
+        self.total_ops += 1
+        if self.auto_purge_enabled and self.total_ops % 5000 == 0:
+            current_mb = self._process.memory_info().rss / (1024 * 1024)
+            if current_mb >= self.max_memory_mb:
+                self.purge()
+
         if not self.is_native:
-            # Phase 1: Small Data Operations
-            if key not in self._light_store:
+            if key not in self._light_store: 
                 self.size += 1
             self._light_store[key] = value
             
-            # Check for migration threshold
-            if self.size >= self.threshold:
+            if self.size >= self.threshold: 
                 self._migrate_to_native()
         else:
-            # Phase 2: Massive Data Operations (Native C-Heap)
             h = self._get_64bit_hash(key)
             lqft_c_engine.insert(h, value)
 
-    def search(self, key):
+    def remove(self, key):
+        self._validate_type(key)
+        
         if not self.is_native:
+            if key in self._light_store:
+                del self._light_store[key]
+                self.size -= 1
+        else:
+            h = self._get_64bit_hash(key)
+            lqft_c_engine.delete(h)
+
+    def delete(self, key):
+        self.remove(key)
+
+    def search(self, key):
+        self._validate_type(key)
+        
+        if not self.is_native: 
             return self._light_store.get(key, None)
         else:
             h = self._get_64bit_hash(key)
             return lqft_c_engine.search(h)
 
     def clear(self):
-        """
-        Memory Reclamation: Manually trigger C-level heap cleanup.
-        In the Adaptive model, this handles both the Python dict and the C-Registry.
-        """
         self._light_store.clear()
         self.size = 0
-        if C_ENGINE_READY:
+        if C_ENGINE_READY: 
             return lqft_c_engine.free_all()
         return 0
 
+    def get_stats(self):
+        if self.is_native and C_ENGINE_READY: 
+            return lqft_c_engine.get_metrics()
+        return {"physical_nodes": 0}
+
     def __del__(self):
-        """
-        Finalizer: Reclaims unmanaged C memory when the Python object is deleted.
-        Crucial for preventing memory leaks in long-running systems.
-        """
-        try:
+        try: 
             self.clear()
-        except:
-            # Silence errors during late interpreter shutdown/garbage collection
+        except: 
             pass
 
     def status(self):
-        """Returns the current state of the engine."""
         return {
             "mode": "Native Merkle-DAG" if self.is_native else "Lightweight C-Hash",
-            "items": self.size,
+            "items": self.size if not self.is_native else lqft_c_engine.get_metrics().get('physical_nodes', self.size),
             "threshold": self.threshold
         }

{lqft_python_engine-0.1.9 → lqft_python_engine-0.3.0}/lqft_python_engine.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: lqft-python-engine
-Version: 0.1.9
-Summary: LQFT Engine: Full CRUD Support (v4.5 Stable)
+Version: 0.3.0
+Summary: LQFT Engine: Memory Circuit Breaker & Strict Type Safety (v5.0 Stable)
 Home-page: https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-
 Author: Parjad Minooei
 License: MIT

{lqft_python_engine-0.1.9 → lqft_python_engine-0.3.0}/setup.py

@@ -27,8 +27,8 @@ lqft_extension = Extension(
 
 setup(
     name="lqft-python-engine",
-    version="0.1.9", 
-    description="LQFT Engine: Full CRUD Support (v4.5 Stable)",
+    version="0.3.0", 
+    description="LQFT Engine: Memory Circuit Breaker & Strict Type Safety (v5.0 Stable)",
     long_description=long_description,
     long_description_content_type="text/markdown",
     author="Parjad Minooei",