Metadata-Version: 2.4
Name: rag-staleness-auditor-py
Version: 0.1.0
Summary: Find stale RAG chunks by age, version, and freshness requirements. Python port of @mukundakatta/rag-staleness-auditor.
Project-URL: Homepage, https://github.com/MukundaKatta/rag-staleness-auditor-py
Project-URL: Issues, https://github.com/MukundaKatta/rag-staleness-auditor-py/issues
Project-URL: Source, https://github.com/MukundaKatta/rag-staleness-auditor-py
Project-URL: JS sibling, https://github.com/MukundaKatta/rag-staleness-auditor
Author-email: Mukunda Rao Katta <mukunda.vjcs6@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,audit,evals,freshness,llm,rag,retrieval,staleness,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# rag-staleness-auditor-py

[![PyPI](https://img.shields.io/pypi/v/rag-staleness-auditor-py.svg)](https://pypi.org/project/rag-staleness-auditor-py/)
[![Python](https://img.shields.io/pypi/pyversions/rag-staleness-auditor-py.svg)](https://pypi.org/project/rag-staleness-auditor-py/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**Find stale RAG chunks by age, version, and freshness requirements.** Run a quick audit over your retrieved documents before stuffing them into a prompt. Flag anything older than your max-age, or anything pinned to a stale version. Zero runtime dependencies.

Python port of [@mukundakatta/rag-staleness-auditor](https://github.com/MukundaKatta/rag-staleness-auditor).

## Install

```bash
pip install rag-staleness-auditor-py
```

## Usage

```python
from rag_staleness_auditor import audit, filter_fresh

records = [
    {"id": "doc1", "updated_at": "2026-04-01T00:00:00Z", "version": "v3"},
    {"id": "doc2", "updated_at": "2024-01-01T00:00:00Z", "version": "v2"},
    {"id": "doc3", "updated_at": None,                    "version": "v1"},
]

report = audit(records, max_age_days=90, current_version="v3")

report.total           # 3
report.stale_count     # 2
report.fresh_count     # 1
report.stale_ids       # ["doc2", "doc3"]
report.entries[0].reasons  # [] for fresh, e.g. ["too_old", "version_mismatch"] otherwise

# Drop the stale ones from your retrieval result before building the prompt:
fresh = filter_fresh(records, max_age_days=90, current_version="v3")
```

## API

| Symbol | Behavior |
|---|---|
| `audit(records, *, max_age_days=90, current_version=None, date_field='updated_at', version_field='version', now=None)` | Returns an `AuditReport` with per-doc verdicts. |
| `audit_staleness(records, *, max_age_days=30, current_version=None, ...)` | Lower-level helper -- returns `list[StalenessEntry]` (matches the JS sibling's shape). |
| `filter_fresh(records, *, ...)` | Returns the input list with stale records dropped. |
| `AuditReport` | Dataclass with `total`, `stale_count`, `fresh_count`, `stale_ids`, `entries`. |
| `StalenessEntry` | Dataclass with `id`, `stale`, `age_days`, `reasons`. |

`reasons` values are `"too_old"` and `"version_mismatch"`, matching the JS sibling.

`date_field` and `version_field` let you swap field names without rewriting your records (e.g. `version_field="schema_version"`).

See the JS sibling's [README](https://github.com/MukundaKatta/rag-staleness-auditor) for the full design notes.
