paradoxlf 0.1.0

A latent memory and active inference engine for AI agents.

Paradox: Latent Memory & Simulation Engine

Paradox is a lightweight, hardware-agnostic cognitive architecture for AI agents. It provides a dynamic "Latent Memory" that doesn't just store data but allows for active simulation, evolution, and proximity-based retrieval.

🚀 Key Features

• Hybrid Compute: Automatically runs on GPU (PyTorch) if available, gracefully falls back to CPU (NumPy/MMap).
• Active Inference: Built-in SimulationEnv allows memory vectors to evolve over time based on physics-like dynamics.
• Infinite Scaling: Supports disk-backed storage (numpy.memmap) for datasets larger than RAM.
• Plugin Architecture: Easily plug in custom Neural Encoders (BERT, CLIP, VAEs) to auto-vectorize raw data.

🌍 Innovation Impact

Paradox is a fundamental engine for Massive Scale Simulation across industries:

Domain	Problem	Paradox Solution	Impact
Software Eng	Objects consume too much RAM.	Stores recipes (vectors), reconstructs on demand.	Handle billion-scale datasets on laptops.
Scientific Sim	Simulating millions of particles requires Supercomputers.	Latent physics allows interacting with millions of entities.	Neuroscience/Physics modeling on commodity hardware.
Big Data & IoT	Searching billions of logs is slow.	Proximity search finds anomalies instantly (O(1) approx).	Real-time analytics & anomaly detection.
Game Dev	Massive procedural worlds crash memory.	Latent storage for entities; procedural reconstruction.	Infinite worlds with efficient AI.
AI / ML	Large models don't fit on GPU.	Compresses parameters/objects into latent space.	Run massive models locally.

Key Takeaways:

• 📉 Memory Efficiency: Drastically reduces RAM needs.
• 📈 Scalability: From thousands to billions of objects.
• 🚀 Production-Ready: Deployable as a library or cloud service.

📦 Installation

git clone https://github.com/ethcocoder/paradoxlf.git
cd paradoxlf
pip install .

⚡ Quick Start

1. Basic Memory & Search

from paradox.engine import LatentMemoryEngine

# Initialize (Auto-detects CPU vs GPU)
engine = LatentMemoryEngine(dimension=128)

# Add Data
engine.add([0.1, 0.5, ...], attributes={"name": "concept_A"})

# Search
results = engine.query([0.1, 0.5, ...], k=5)
print(results)

2. Auto-Encoding Raw Data

from paradox.engine import LatentMemoryEngine
from paradox.encoder import BaseEncoder

# Define a custom encoder (e.g., wrapper around OpenAI/HuggingFace)
class MyTextEncoder(BaseEncoder):
    def encode(self, text):
        # ... logic to turn text into vector ...
        return vector

engine = LatentMemoryEngine(dimension=768)
engine.set_encoder(MyTextEncoder(768))

# Now simply add text!
engine.add("Artificial Intelligence is evolving", {"category": "AI"})

3. Simulation (The "Active" Part)

Paradox allows you to run simulations on your memory, letting concepts interact or drift.

from paradox.simulation import SimulationEnv

def semantic_drift(vectors, dt, backend):
    return vectors * 0.01 # Simple example

sim = SimulationEnv(engine)
sim.run(steps=100, dynamics_fn=semantic_drift)

4. Visualization

Visualize your latent space in 2D using PCA or t-SNE.

from paradox.visualization import LatentVisualizer

viz = LatentVisualizer(engine)
viz.plot_2d(method="pca", output_file="memory_map.png")

💻 How to Use: Library vs Framework

Paradox is designed to be used in two distinct ways depending on your needs.

📚 Mode 1: The Library (Static Usage)

Use when: You want a fast vector database or smart storage for your existing application.

• You control the loop. You just push/pull data.
• Example: Storing million embeddings for a Chatbot.

from paradox import LatentMemoryEngine

db = LatentMemoryEngine(dimension=512)
db.add(vector, {"text": "hello"})
result = db.query(query_vector)

🏗️ Mode 2: The Framework (Active Usage)

Use when: You want to build a living simulation or agent that evolves on its own.

• Paradox controls the loop. You define the rules, Paradox moves the world.
• Example: A traffic simulation where cars (vectors) move closer if they are "jammed".

from paradox import SimulationEnv

def traffic_physics(vectors, dt, backend):
    # Custom logic to move vectors based on rules
    return updated_vectors

sim = SimulationEnv(engine)
sim.run(steps=1000, dynamics_fn=traffic_physics)
# The engine is actively "thinking" and updating state

🤝 Contributing

Open source contributions are welcome. Please submit a PR for review.

📄 License

MIT License