Metadata-Version: 2.4
Name: holographic-memory-engine
Version: 1.0.5
Summary: A universal phase-space memory engine that retrieves knowledge via holographic interference instead of vector similarity search.
Home-page: https://github.com/Luckyy0311
Author: Abdul Mofique Siddiqui
Author-email: mofique7860@gmail.com
License: MIT
Keywords: holographic-memory,rag,vector-search,ai,retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: gpu
Requires-Dist: cupy>=12.0; extra == "gpu"
Provides-Extra: neural
Requires-Dist: sentence-transformers>=2.2; extra == "neural"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# holographic-memory-engine

[![PyPI version](https://img.shields.io/pypi/v/holographic-memory-engine.svg)](https://pypi.org/project/holographic-memory-engine/)
[![Python](https://img.shields.io/pypi/pyversions/holographic-memory-engine.svg)](https://pypi.org/project/holographic-memory-engine/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**A universal phase-space memory engine that retrieves knowledge via holographic interference instead of vector similarity search.**

> **Note:** The package is installed via pip as `holographic-memory-engine`, but imported in Python as `import holographic`.

---

## 🚀 The Problem with Classic RAG

Classic Retrieval-Augmented Generation (RAG) retrieves text chunks by cosine similarity and stuffs them into an LLM prompt. This approach has fundamental flaws:
1. It returns **passages**, not answers.
2. It pollutes the context window with irrelevant noise.
3. It forces the LLM to do the heavy lifting of extraction, increasing latency and token costs.

## 💡 The Holographic Solution

`holographic-memory-engine` binds `key -> value` pairs into complex phase vectors and retrieves them via **constructive and destructive wave interference**. 

When you query the memory, matching keys resonate (constructive interference) and instantly surface their exact bound values, while non-matching keys cancel out to zero (destructive interference). The result is the **exact answer**, directly, with zero chunk stuffing and zero context pollution.

| Feature | Classic RAG | holographic-memory |
| :--- | :--- | :--- |
| **Retrieval Signal** | Cosine similarity | Phase interference |
| **Returns** | Text chunk / Paragraph | Exact bound value |
| **Context Pollution** | High | None |
| **Answer Verbosity** | High (noisy) | Minimal & Precise |
| **Vector Math** | Real-valued Dot Product | Complex Conjugate Unbinding |

---

## ✨ Key Features

- **🎯 Exact Answer Retrieval:** Bypasses chunk-stuffing to return precise, bound values.
- **⚡ Blazing Fast:** Vectorized matrix operations with optional GPU acceleration via CuPy.
- **🧠 Pluggable Encoders:** Use the built-in deterministic `HashPhaseEncoder` or swap in a `NeuralPhaseEncoder` (SentenceTransformers) for semantic understanding.
- **💾 Disk Persistence:** Save and load massive memory states to JSON instantly.
- **📄 Auto-Ingestion:** Built-in document chunking and fact extraction pipelines.
- **📈 Infinite Scale:** Automatic sharding prevents Signal-to-Noise Ratio (SNR) collapse at scale.

---

## 📦 Installation

Install the core engine (requires only `numpy`):

```bash
pip install holographic-memory-engine
```

### Optional Extras

```bash
# GPU acceleration via CuPy (Requires NVIDIA GPU + CUDA)
pip install holographic-memory-engine[gpu]

# Neural encoder via sentence-transformers (Grasps semantic meaning)
pip install holographic-memory-engine[neural]

# Install both
pip install holographic-memory-engine[gpu,neural]
```

---

## ⚡ Quick Start

```python
from holographic import HolographicEngine, HashPhaseEncoder

# 1. Initialize the engine
engine = HolographicEngine(encoder=HashPhaseEncoder(dim=2048))

# 2. Add key-value facts
engine.add("capital France", "Paris")
engine.add("capital Japan", "Tokyo")
engine.add("ceo Tesla", "Elon Musk")

# 3. Build the interference matrices (REQUIRED before querying)
engine.build()

# 4. Query the memory
result = engine.ask("What is the capital of France?")
print(result["answer"])  
# Output: Paris
```

---

## 📖 Detailed Usage

### Document Ingestion
You don't have to manually extract facts. The engine includes built-in chunking and fact extraction.

```python
# Ingest raw text directly (auto-chunks and extracts facts)
engine.ingest(
    "The headquarters of Apple is in Cupertino. The CEO is Tim Cook.", 
    source="wiki"
)

# Or ingest an entire text file from disk
engine.ingest_file("company_handbook.txt")

# Always build after bulk ingestion
engine.build()
```

### Persistence (Save / Load)
Save your entire memory state to disk and reload it instantly in another session.

```python
# Save the memory state to disk
engine.save("memory.json")

# Reload it later instantly
engine.load("memory.json")
```

---

## 🧠 Advanced Encoders

### 1. Neural Encoder (Semantic Understanding)
Swap the deterministic hash encoder for a neural model to understand synonyms, intent, and semantic meaning.

```python
from holographic import HolographicEngine, NeuralPhaseEncoder

# Requires: pip install holographic-memory-engine[neural]
engine = HolographicEngine(encoder=NeuralPhaseEncoder(dim=2048))
engine.add("automobile manufacturer", "Tesla")
engine.build()

# Will successfully retrieve "Tesla" even though words don't exactly match
print(engine.ask("Who makes electric cars?")["answer"]) 
```

### 2. Custom Encoder
The engine is completely encoder-agnostic. Any object with a `dim` attribute and an `encode(text) -> complex ndarray` method works:

```python
import numpy as np
from holographic import HolographicEngine

class MyCustomEncoder:
    dim = 2048
    def encode(self, text: str) -> np.ndarray:
        # Your custom logic here
        # Must return a complex64 vector of shape (dim,)
        return np.ones(self.dim, dtype=np.complex64)

engine = HolographicEngine(encoder=MyCustomEncoder())
```

---

## 📚 API Reference

### `HolographicEngine`

The core engine class.

| Method | Description |
| :--- | :--- |
| `__init__(encoder, config)` | Initialize with an encoder and optional `HolographicConfig`. |
| `add(key, value, metadata)` | Bind a single key-value pair into memory. |
| `add_many(items)` | Bulk add a list of `{"key": ..., "value": ...}` dicts. |
| `build()` | **(Required)** Pre-compute conjugate matrices. Must be called before querying. |
| `ingest(text, source)` | Chunk raw text, extract facts, and add them to memory. |
| `ingest_file(path)` | Read a text file and ingest its contents. |
| `retrieve(question, top_k)` | Return a list of evidence dicts sorted by interference score. |
| `ask(question, top_k)` | Return the single best answer with a confidence score. |
| `save(path)` | Persist engine state to a JSON file. |
| `load(path)` | Load engine state from JSON and rebuild matrices. |
| `clear()` | Wipe all shards and reset the engine. |
| `stats()` | Return a dict of engine statistics (fact count, shards, etc). |

### `HolographicConfig`

Fine-tune the engine's behavior:

```python
from holographic import HolographicConfig

config = HolographicConfig(
    dim=4096,             # Vector dimensionality (higher = more capacity)
    shard_capacity=0,     # Facts per shard. 0 = single large shard (fastest)
    default_top_k=5,      # Default number of results to retrieve
    score_threshold=0.0,  # Minimum score to accept an answer
    margin_ratio=1.02,    # Top answer must beat second by this ratio
    use_gpu=False,        # Set to True if cupy is installed
)
```

---

## 🔬 How It Works (The Math)

Holographic memory relies on the mathematics of complex phase spaces rather than standard linear algebra.

1. **Bind** — `key` ($K$) and `value` ($V$) are encoded to constant-modulus complex vectors, then bound via element-wise multiplication: $K \odot V$.
2. **Superpose** — all bindings are summed into a single holographic memory vector: $M = \sum (K_i \odot V_i)$.
3. **Retrieve** — the query ($Q$) is multiplied by the conjugate of the memory. Matching keys resonate (constructive interference) and surface their bound values; non-matches cancel out (destructive interference): $Retrieved = M \odot \overline{Q}$.

Because every dimension has a magnitude of 1, the signal-to-noise ratio remains stable even when millions of facts are superposed into a single vector.

---

## 📂 Project Structure

```text
holographic-memory-engine/
├── src/holographic/       # Core package
│   ├── __init__.py        # Public API
│   ├── config.py          # HolographicConfig
│   ├── tokenization.py    # Tokenization utilities
│   ├── backends.py        # Numpy / CuPy selection
│   ├── encoders.py        # Hash and Neural encoders
│   ├── memory.py          # Core Engine & Shards
│   ├── ingestion.py       # Document chunking/extraction
│   └── persistence.py     # JSON save/load
├── examples/              # Usage examples & benchmark harness
├── tests/                 # Pytest suite
└── setup.py               # PyPI configuration
```

---

## 🤝 Contributing

Contributions are welcome! If you have ideas for new encoders, backend optimizations, or documentation improvements, please open an issue or submit a pull request on GitHub.

1. Fork the repository.
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
4. Push to the branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request.

---

## 📜 License

MIT — see [LICENSE](LICENSE).
