Metadata-Version: 2.4
Name: prismresonance
Version: 0.3.0
Summary: Biologically-inspired dynamic memory layer for RAG and multi-agent systems
Author-email: Amin Parva <insightits.info@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://prismresonance.insightits.com
Project-URL: Repository, https://github.com/insightits/prismresonance
Project-URL: Documentation, https://docs.prismresonance.insightits.com
Keywords: rag,embeddings,vector-database,multi-agent,memory,onnx,wave-mechanics,llm-middleware
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: onnxruntime>=1.17
Requires-Dist: onnx>=1.15
Provides-Extra: prismlang
Requires-Dist: prismlang>=0.1.1; extra == "prismlang"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: google-genai>=1.0; extra == "dev"
Requires-Dist: psutil>=5.9; extra == "dev"
Dynamic: license-file

# PrismResonance

**Biologically-inspired dynamic memory layer for RAG and multi-agent systems.**

PrismResonance converts static text embeddings into complex-valued wavepackets
(`z = A · e^{iφ}`) so that retrieval is executed as wave interference rather than
geometric distance search.  Chunks that share the active system frequency experience
*constructive interference* and surface instantly; out-of-phase chunks are muted by
*destructive interference* — no re-embedding, no coordinate mutation.

## Why

| Problem with standard RAG | PrismResonance answer |
|---|---|
| Static embeddings are blind to runtime state | Phase angle φ carries live operational context |
| Surfacing related chunks requires expensive re-ranking | Wave interference is a single ONNX MatMul pass |
| Context window bloat → hallucination | Phase Coherence Shield hard-drops low-resonance chunks |
| Memory has no notion of recency or relatedness | Most-Recent and Most-Related indices + sleep cycle |

## Installation

```bash
pip install prismresonance           # core: numpy, onnx, onnxruntime
```

No torch dependency.  The ONNX graph is compiled with pure `onnx.helper`.

## Quick start

```python
import numpy as np
from prismresonance import PrismResonance
from prismresonance.frequency import FrequencyFamily as FF

# Create (compiles ONNX graph on first run, persists to state_path)
prism = PrismResonance.create(
    embedding_dim=384,
    onnx_path="resonance_engine.onnx",
    state_path="resonance_state.db",
)

# Ingest a chunk (your encoder produces the amplitude vector)
amplitude = np.random.randn(384).astype(np.float32)
amplitude /= np.linalg.norm(amplitude)
prism.ingest("chunk_001", amplitude, FF.EMERGENCY)

# Query
results = prism.query(
    query_amplitude=amplitude,
    query_phase=FF.EMERGENCY,
    candidate_ids=["chunk_001"],
    candidate_amplitudes=np.stack([amplitude]),
    flat=True,         # skip group scan for small corpora
)
for r in results:
    print(r.chunk_id, r.score)

# Consolidate (run in background or on idle)
prism.sleep()

# Persist
prism.save()
prism.shutdown()
```

## Frequency families

Six named phase bands with π/6 separation:

| Family | φ (radians) | Intended use |
|---|---|---|
| `NEUTRAL` | 0 | Background / default |
| `NORMAL` | π/6 | Standard operational |
| `ALERT` | π/3 | Elevated attention |
| `EMERGENCY` | π/2 | Critical exceptions |
| `RECOVERY` | 2π/3 | Recovery loops |
| `ARCHIVE` | π | Long-term cold storage |

## Architecture

```
Raw chunk ──► Semantic anchor (amplitude A, immutable)
           ──► Resonance classifier (phase φ, dynamic)
                    │
                    ▼
         ┌──────────────────────┐
         │  ResonanceRegistry   │  ← RAM sidecar (never touches source DB)
         │  · Phase registry    │
         │  · Most-Recent index │
         │  · Most-Related index│
         └──────────┬───────────┘
                    │
                    ▼
         ┌──────────────────────┐
         │  ONNX wave engine    │  ← compiled once, frozen forever
         │  MatMul + Add        │
         │  Coherence Shield    │
         └──────────────────────┘
                    │
                    ▼
            Resonant chunk IDs
```

The source database is **strictly read-only**.  All mutable state lives in the
sidecar registry (RAM) and is flushed to a SQLite file during the sleep cycle.

## Sleep cycle

```python
prism.sleep()          # blocking fast-sleep (runs all 4 passes)
```

Four passes:
1. **Temporal decay** — fades chunks not accessed recently
2. **Synaptic alignment** — pulls heavily co-activated chunks into the same frequency family
3. **Group vector recomputation** — rebuilds group centroids
4. **Group merge** — collapses very similar groups

For background operation pass `auto_sleep=True` to `PrismResonance.create()`.

## Source adapters

Read your existing vector store without touching it:

```python
from prismresonance.adapters.prismrag import PgvectorSourceAdapter, ChromaSourceAdapter

# pgvector (psycopg2 or psycopg3)
adapter = PgvectorSourceAdapter(dsn="postgresql://...", table="embeddings")

# ChromaDB
adapter = ChromaSourceAdapter(collection=client.get_collection("my_col"))
```

## Development

```bash
pip install -e ".[dev]"
python -m pytest tests/ -v
```

## License

MIT — see [LICENSE](LICENSE).

© 2026 Amin Parva, Insight IT Solutions LLC
