Metadata-Version: 2.4
Name: epistemic-vectors
Version: 0.1.0
Summary: Epistemic Vectors — a provenance-native primitive for retrieval pipelines. Drop-in Epistemic Layer for LangChain, LlamaIndex, and Mem0.
Author-email: Marshall Miller <marshall.miller3@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cruxia/sagrada
Project-URL: Repository, https://github.com/cruxia/sagrada
Project-URL: Paper, https://arxiv.org/abs/TBD
Keywords: rag,retrieval,agm,provenance,epistemic,embeddings
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: agm-r>=0.2
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.11; extra == "llamaindex"
Provides-Extra: mem0
Requires-Dist: mem0ai>=0.1; extra == "mem0"
Provides-Extra: all
Requires-Dist: langchain-core>=0.3; extra == "all"
Requires-Dist: llama-index-core>=0.11; extra == "all"
Requires-Dist: mem0ai>=0.1; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# epistemic-vectors

A provenance-native primitive for retrieval pipelines — the **Epistemic Layer** drops in between vector-store retrieval and generation in any RAG stack and attaches an **Epistemic Vector** to every returned document.

What semantic embeddings did for *meaning*, Epistemic Vectors do for *belief state*. Five typed slots per document — `revision_state`, `provenance_depth`, `consistency_score`, `authority`, `freshness` — derived deterministically from a belief graph. No LLM, no free-text classifier.

## Install

```bash
pip install epistemic-vectors[langchain]       # LangChain adapter
pip install epistemic-vectors[llamaindex]      # LlamaIndex adapter
pip install epistemic-vectors[mem0]            # Mem0 adapter
pip install epistemic-vectors[all]             # all three
```

## Quickstart — LangChain

```python
from agm_r import KnowledgeGraph, assert_belief, revise
from epistemic_layer.adapters.langchain import EpistemicRetriever

# (1) Build a belief graph
kg = KnowledgeGraph()
kg = assert_belief(kg, term="pluto_classification", source_id="doc_a",
                       claim_text="Pluto is the ninth planet",
                       timestamp="1930-02-18")
kg = revise(kg, old_source_id="doc_a", new_source_id="doc_b",
                new_claim_text="Pluto is a dwarf planet",
                timestamp="2006-08-24")

# (2) Wrap any LangChain retriever (e.g. Chroma) with the Epistemic Layer
retriever = EpistemicRetriever(base_retriever=chroma_retriever, kg=kg)

# (3) Docs now carry an Epistemic Vector in their metadata
for d in retriever.get_relevant_documents("what is Pluto?"):
    print(d.metadata["epistemic_vector"])
    # {"source_id": "doc_b", "revision_state": "asserted", ...}
```

Filter or re-rank by vector slots:

```python
retriever = EpistemicRetriever(
    base_retriever=chroma_retriever, kg=kg,
    filter_by=lambda ev: ev.revision_state != "retracted",
    rerank_by=lambda ev: 0.5 * ev.freshness + 0.5 * ev.consistency_score,
)
```

## Quickstart — LlamaIndex

```python
from epistemic_layer.adapters.llamaindex import EpistemicRetriever
retriever = EpistemicRetriever(base_retriever=vector_retriever, kg=kg)
nodes = retriever.retrieve("what is Pluto?")
for nws in nodes:
    ev = nws.node.metadata["epistemic_vector"]
```

## Quickstart — Mem0

```python
from mem0 import Memory
from epistemic_layer.adapters.mem0 import EpistemicMemory

base = Memory()
em = EpistemicMemory(base=base, kg=kg)
em.add(messages="Pluto is a dwarf planet", user_id="alice",
       metadata={"source_id": "doc_b"})
results = em.search(query="what is Pluto?", user_id="alice")
for r in results["results"]:
    print(r["epistemic_vector"])
```

## The primitive itself (no adapter)

Use `epistemic_vector()` directly against any `agm_r.KnowledgeGraph`:

```python
from agm_r import KnowledgeGraph, epistemic_vector
ev = epistemic_vector(kg, "doc_b")
print(ev)
# EV(doc_b, asserted, prov=0, cons=1.00, auth=1.00, fresh=1.00)
```

## Links

- **Paper**: *Epistemic Vectors and the Epistemic Layer: A Provenance-Native Primitive for Retrieval Pipelines* — NeurIPS 2026 (in submission)
- **AGM-R** (Python reference implementation): `agm_r/`
- **License**: MIT
