rag-staleness-auditor-py 0.1.0

Find stale RAG chunks by age, version, and freshness requirements. Python port of @mukundakatta/rag-staleness-auditor.

rag-staleness-auditor-py

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.

Install

pip install rag-staleness-auditor-py

Usage

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 for the full design notes.