Metadata-Version: 2.4
Name: lqft-python-engine
Version: 0.7.5
Summary: LQFT Engine: Strict Native C-Core & Hardware Concurrency (v0.7.5 Stable)
Home-page: https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-
Author: Parjad Minooei
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: psutil
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Log-Quantum Fractal Tree (LQFT) 🚀

[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](#)
[![C-Engine](https://img.shields.io/badge/Native-C-red.svg)](#)
[![Concurrency](https://img.shields.io/badge/Concurrency-Strict_GIL__Bypass-success.svg)](#)
[![Systems Architecture](https://img.shields.io/badge/Architecture-Merkle_HAMT-pink.svg)](#)
[![License](https://img.shields.io/badge/License-MIT-red.svg)](LICENSE.md)

## 📌 Project Overview

The **Log-Quantum Fractal Tree (LQFT)** is a high-performance, scale-invariant data structure engine designed for massive data deduplication and persistent state management. It synthesizes **Hash Array Mapped Trie (HAMT)** routing with **Merkle-DAG structural folding** to provide deterministic $O(1)$ search latency and sub-linear $O(\Sigma)$ space complexity.

By offloading core associative logic to a native C-Extension, the LQFT completely bypasses the Python Global Interpreter Lock (GIL), providing true hardware concurrency and significant memory reduction for versioned, redundant, or patterned datasets.

---

## 🧠 Core Architecture (v0.7.5 Strict Native Release)

### 1. Strict C-Core Enforcement 
The legacy pure-Python fallback heuristics have been entirely stripped out. The LQFT now operates strictly as a zero-overhead FFI wrapper directly communicating with the underlying unmanaged C memory heap.

### 2. True Hardware Concurrency & Strict GIL Bypass (New in v0.7.5)
The engine utilizes native OS-level read-write locks (`SRWLOCK` on Windows, `pthread_rwlock_t` on POSIX) combined with strict `Py_BEGIN_ALLOW_THREADS` boundaries. 
* **Multi-Core Scaling:** Multiple Python threads can read and write to the Merkle-DAG simultaneously across all physical CPU cores without Segmentation Faults.
* **Zero GIL Contention:** The C-Engine entirely decouples from the Python interpreter during execution, ensuring the GIL never blocks concurrent array traversals.

### 3. Scale-Invariant Time Complexity: $O(1)$
The LQFT utilizes a fixed 64-bit hash space partitioned into 13 levels. 
* **Deterministic Latency:** Every search or insertion requires exactly 13 pointer hops.
* **Scale-Invariance:** Performance remains constant whether the dataset contains 10^3 or 10^9 items.

### 4. Entropy-Based Space Complexity: $O(\Sigma)$
Nodes are identified by the cryptographic hash of their contents and child pointers (Merkle-DAG).
* **Structural Folding:** Identical sub-trees are shared physically in memory across different branches or versions.

---

## 🚀 Performance Benchmarks

*Environment: Python 3.12 | GCC -O3 | MSYS2/MinGW64 | 16-Thread Concurrency*

| Metric | Result | 
| :--- | :--- | 
| **Search Latency (p50)** | ~500 ns | 
| **Concurrent Throughput** | ~1.8 Million ops/sec (True Multi-Core) | 
| **Space Efficiency** | Up to 1,500x reduction in versioned graph simulations | 
| **Stability** | 100% Memory Safe under massive multi-threaded turnover | 

---

## 🛠️ Getting Started

### Installation

The engine requires a C compiler (GCC/MinGW or MSVC) to build the native extension.

```bash
# Clone the repository
git clone [https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-.git](https://github.com/ParjadM/Log-Quantum-Fractal-Tree-LQFT-.git)
cd Log-Quantum-Fractal-Tree-LQFT-

# Build the native C-extension
python setup.py build_ext --inplace
```

### Basic Usage

The LQFT provides a Pythonic interface to its high-performance C-backend.

```python
from lqft_engine import LQFT
import threading

# Initialize the Strict Native Engine
db = LQFT()

# The C-Engine releases the GIL, allowing true multi-threading
def worker(thread_id):
    for i in range(10000):
        db.insert(f"thread_{thread_id}_key_{i}", "enterprise_payload")

threads = [threading.Thread(target=worker, args=(t,)) for t in range(16)]
for t in threads: t.start()
for t in threads: t.join()

# --- Native Disk Persistence ---
db.save_to_disk("production_state.bin")
db.clear()
db.load_from_disk("production_state.bin")
```

---

## ⚖️ License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
