Metadata-Version: 2.4
Name: xrag-temporal
Version: 0.1.0
Summary: Time-aware uncertainty for RAG — temporal decay of evidence confidence using Subjective Logic
Project-URL: Repository, https://github.com/jemsbhai/subjective-logic-rag
Author: Muntaser Syed
License: MIT
Keywords: llm,nlp,rag,subjective-logic,temporal,uncertainty
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: jsonld-ex>=0.5.0
Requires-Dist: numpy>=1.24
Provides-Extra: demo
Requires-Dist: matplotlib>=3.7; extra == 'demo'
Requires-Dist: plotly>=5.15; extra == 'demo'
Description-Content-Type: text/markdown

# xrag-temporal

**Time-aware uncertainty for RAG** — temporal decay of evidence confidence using Subjective Logic.

Your RAG system treats every retrieved document as equally valid — whether it was written yesterday or three years ago. `xrag-temporal` fixes this by applying subjective logic temporal decay: as evidence ages, belief migrates into uncertainty.

## Install

```bash
pip install xrag-temporal
```

## Quick Start

```python
from xrag_temporal import opinion, decay, decay_series, should_abstain

# Create an opinion from evidence
ev = opinion(belief=0.8, disbelief=0.1)  # strong evidence

# Decay it: 30 days old, 7-day half-life
stale = decay(ev, elapsed_days=30, half_life_days=7)
print(stale)
# → Opinion(b=0.0442, d=0.0055, u=0.9503)  — almost all uncertainty!

# Should the system abstain?
print(should_abstain(stale))  # True — uncertainty > 0.7
```

## The Problem

Standard RAG pipelines retrieve documents and feed them to an LLM without considering **when** the evidence was created. A 3-year-old article about "the CEO of Twitter" will confidently produce the wrong answer.

## The Solution

`xrag-temporal` decays belief and disbelief into uncertainty as evidence ages:

- **Fresh evidence** (age ≈ 0): original confidence preserved
- **Aging evidence**: belief/disbelief shrink, uncertainty grows  
- **Stale evidence**: nearly all mass is uncertainty → system knows it doesn't know

Three decay functions:
- **Exponential** (default): smooth, never fully zero — `λ = 2^(-t/τ)`
- **Linear**: reaches zero at 2× half-life — `λ = max(0, 1 - t/2τ)`  
- **Step**: binary fresh/stale — `λ = 1 if t < τ else 0`

## License

MIT
