staleguard 0.1.0__py3-none-any.whl

staleguard/__init__.py

@@ -0,0 +1,64 @@
+__version__ = "0.1.0"
+
+from .api import StaleGuard
+from .auditor import (
+    audit as audit_chunks,
+    audit_chroma_result,
+    audit_langchain_docs,
+    audit_retrieved,
+)
+from .config import StaleGuardConfig
+from .audit_types import AuditResult
+from .providers import ConflictProvider, EmbeddingProvider, register_conflict_provider, register_embedding_provider
+
+
+def audit(
+    query: str,
+    retrieved: object | None = None,
+    corpus: list[dict] | None = None,
+    *,
+    retrieved_chunks: list[dict] | None = None,
+    use_nli: bool = False,
+    block_on_conflict: bool = False,
+    config: StaleGuardConfig | None = None,
+):
+    if retrieved_chunks is not None:
+        if retrieved is not None:
+            raise TypeError("Pass either retrieved or retrieved_chunks, not both.")
+        return audit_chunks(
+            query=query,
+            retrieved_chunks=retrieved_chunks,
+            corpus=corpus,
+            use_nli=use_nli,
+            block_on_conflict=block_on_conflict,
+            config=config,
+        )
+
+    return audit_retrieved(
+        query=query,
+        retrieved=retrieved,
+        corpus=corpus,
+        use_nli=use_nli,
+        block_on_conflict=block_on_conflict,
+        config=config,
+    )
+
+
+def evaluate_case(*args, **kwargs):
+    from .eval import evaluate_case as _evaluate_case
+
+    return _evaluate_case(*args, **kwargs)
+
+
+def run_eval(*args, **kwargs):
+    from .eval import run_eval as _run_eval
+
+    return _run_eval(*args, **kwargs)
+
+__all__ = [
+    "audit",
+    "__version__",
+    "StaleGuard",
+    "StaleGuardConfig",
+    "AuditResult",
+]

staleguard/adapters/__init__.py

@@ -0,0 +1,11 @@
+from .chroma import normalize_chroma_result
+from .json_adapter import normalize_chunk, normalize_chunks
+from .langchain import normalize_langchain_doc, normalize_langchain_docs
+
+__all__ = [
+    "normalize_chunk",
+    "normalize_chunks",
+    "normalize_chroma_result",
+    "normalize_langchain_doc",
+    "normalize_langchain_docs",
+]

staleguard/adapters/chroma.py

@@ -0,0 +1,50 @@
+from collections.abc import Mapping
+from typing import Any
+
+from .json_adapter import normalize_chunk
+
+
+def _unwrap_rows(values: Any) -> list[Any]:
+    if values is None:
+        return []
+
+    if isinstance(values, list) and values and isinstance(values[0], list):
+        return values[0]
+
+    return list(values)
+
+
+def _value_at(values: list[Any], index: int) -> Any:
+    if index >= len(values):
+        return None
+
+    return values[index]
+
+
+def normalize_chroma_result(result: Mapping[str, Any]) -> list[dict[str, Any]]:
+    ids = _unwrap_rows(result.get("ids"))
+    documents = _unwrap_rows(result.get("documents"))
+    metadatas = _unwrap_rows(result.get("metadatas"))
+    distances = _unwrap_rows(result.get("distances"))
+
+    count = max(len(ids), len(documents), len(metadatas), len(distances))
+    chunks = []
+
+    for index in range(count):
+        current_metadata = dict(_value_at(metadatas, index) or {})
+        current_distance = _value_at(distances, index)
+
+        if current_distance is not None:
+            current_metadata["chroma_distance"] = current_distance
+
+        raw_chunk = {
+            "id": _value_at(ids, index),
+            "text": _value_at(documents, index),
+            "metadata": current_metadata,
+        }
+
+        chunks.append(normalize_chunk(raw_chunk, index=index))
+
+    return chunks
+
+

staleguard/adapters/json_adapter.py

@@ -0,0 +1,67 @@
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+FIELD_CANDIDATES = {
+    "id": ("id", "chunk_id", "document_id", "doc_id"),
+    "text": ("text", "page_content", "content", "document"),
+    "product": ("product",),
+    "topic": ("topic",),
+    "version": ("version",),
+    "date_ts": ("date_ts", "timestamp", "created_at_ts", "updated_at_ts"),
+    "source": ("source", "path", "uri", "filename", "file_name"),
+}
+
+
+def normalize_chunk(
+    raw_chunk: Mapping[str, Any],
+    index: int = 0,
+    field_map: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    metadata = raw_chunk.get("metadata")
+    metadata = dict(metadata) if isinstance(metadata, Mapping) else {}
+    resolved_map = dict(field_map or {})
+
+    normalized = {
+        "id": _resolve_value(raw_chunk, metadata, "id", resolved_map) or f"chunk_{index}",
+        "text": _resolve_value(raw_chunk, metadata, "text", resolved_map),
+        "product": _resolve_value(raw_chunk, metadata, "product", resolved_map),
+        "topic": _resolve_value(raw_chunk, metadata, "topic", resolved_map),
+        "version": _resolve_value(raw_chunk, metadata, "version", resolved_map),
+        "date_ts": _resolve_value(raw_chunk, metadata, "date_ts", resolved_map),
+        "source": _resolve_value(raw_chunk, metadata, "source", resolved_map),
+        "metadata": metadata,
+    }
+
+    if not normalized["text"]:
+        raise ValueError("retrieved chunk is missing text/page_content/content")
+
+    return normalized
+
+
+def normalize_chunks(
+    raw_chunks: Iterable[Mapping[str, Any]],
+    field_map: Mapping[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    return [
+        normalize_chunk(raw_chunk, index=index, field_map=field_map)
+        for index, raw_chunk in enumerate(raw_chunks)
+    ]
+
+
+def _resolve_value(
+    raw_chunk: Mapping[str, Any],
+    metadata: Mapping[str, Any],
+    field_name: str,
+    field_map: Mapping[str, str],
+) -> Any:
+    explicit_name = field_map.get(field_name)
+    if explicit_name:
+        return raw_chunk.get(explicit_name, metadata.get(explicit_name))
+
+    for candidate in FIELD_CANDIDATES[field_name]:
+        if candidate in raw_chunk:
+            return raw_chunk[candidate]
+        if candidate in metadata:
+            return metadata[candidate]
+
+    return None

staleguard/adapters/langchain.py

@@ -0,0 +1,34 @@
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from .json_adapter import normalize_chunk
+
+
+def normalize_langchain_doc(
+    doc: Any,
+    index: int = 0,
+    field_map: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    raw_chunk = {
+        "page_content": getattr(doc, "page_content", None),
+        "metadata": getattr(doc, "metadata", None),
+    }
+
+    if isinstance(doc, Mapping):
+        raw_chunk["page_content"] = doc.get("page_content", raw_chunk["page_content"])
+        raw_chunk["metadata"] = doc.get("metadata", raw_chunk["metadata"])
+        for key in ("id", "text", "source", "product", "topic", "version", "date_ts"):
+            if key in doc:
+                raw_chunk[key] = doc[key]
+
+    return normalize_chunk(raw_chunk, index=index, field_map=field_map)
+
+
+def normalize_langchain_docs(
+    docs: Iterable[Any],
+    field_map: Mapping[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    return [
+        normalize_langchain_doc(doc, index=index, field_map=field_map)
+        for index, doc in enumerate(docs)
+    ]

staleguard/alternatives/__init__.py

@@ -0,0 +1,3 @@
+from .finder import find_fresh_alternatives
+
+__all__ = ["find_fresh_alternatives"]

staleguard/alternatives/finder.py

@@ -0,0 +1,35 @@
+from ..config import StaleGuardConfig
+from ..scorers.freshness import find_superseding_chunk, score_chunk_freshness
+
+
+def find_fresh_alternatives(
+    retrieved_chunks: list[dict],
+    corpus: list[dict] | None,
+    query: str,
+    config: StaleGuardConfig | None = None,
+    now_ts: int | None = None,
+) -> list[dict]:
+    if not corpus:
+        return []
+
+    alternatives = []
+    for chunk in retrieved_chunks:
+        freshness = score_chunk_freshness(chunk, query, corpus, config=config, now_ts=now_ts)
+        if freshness["verdict"] != "STALE":
+            continue
+
+        replacement = find_superseding_chunk(chunk, corpus, config=config)
+        if not replacement:
+            continue
+
+        alternatives.append(
+            {
+                "instead_of": chunk["id"],
+                "use": replacement["id"],
+                "reason": (
+                    f"Same product/topic, newer version available: "
+                    f"{chunk.get('version')} -> {replacement.get('version')}"
+                ),
+            }
+        )
+    return alternatives

staleguard/api.py

@@ -0,0 +1,135 @@
+from dataclasses import fields, replace
+from pathlib import Path
+from typing import Any
+
+from .audit_types import AuditResult
+from .auditor import audit as audit_chunks_impl
+from .auditor import audit_retrieved
+from .config import StaleGuardConfig
+
+
+CONFIG_FIELD_NAMES = {field.name for field in fields(StaleGuardConfig)}
+
+
+def _clean_overrides(overrides: dict[str, Any]) -> dict[str, Any]:
+    return {
+        key: value
+        for key, value in overrides.items()
+        if key in CONFIG_FIELD_NAMES and value is not None
+    }
+
+
+class StaleGuard:
+    def __init__(
+        self,
+        config: StaleGuardConfig | None = None,
+        **overrides: Any,
+    ) -> None:
+        cleaned = _clean_overrides(overrides)
+        self.config = replace(config, **cleaned) if config is not None else StaleGuardConfig(**cleaned)
+
+    @classmethod
+    def from_backends(
+        cls,
+        *,
+        embedding_backend: str = "local",
+        conflict_backend: str = "local",
+        **overrides: Any,
+    ) -> "StaleGuard":
+        return cls(
+            embedding_backend=embedding_backend,
+            conflict_backend=conflict_backend,
+            **overrides,
+        )
+
+    @classmethod
+    def from_providers(
+        cls,
+        *,
+        embedding_provider: Any = None,
+        conflict_provider: Any = None,
+        **overrides: Any,
+    ) -> "StaleGuard":
+        return cls(
+            embedding_provider=embedding_provider,
+            conflict_provider=conflict_provider,
+            **overrides,
+        )
+
+    def audit(
+        self,
+        query: str,
+        retrieved: object,
+        corpus: list[dict] | None = None,
+    ) -> AuditResult:
+        return audit_retrieved(
+            query=query,
+            retrieved=retrieved,
+            corpus=corpus,
+            config=self.config,
+        )
+
+    def audit_chunks(
+        self,
+        query: str,
+        retrieved_chunks: list[dict],
+        corpus: list[dict] | None = None,
+    ) -> AuditResult:
+        return audit_chunks_impl(
+            query=query,
+            retrieved_chunks=retrieved_chunks,
+            corpus=corpus,
+            config=self.config,
+        )
+
+    def evaluate_case(
+        self,
+        case: dict,
+        corpus: list[dict],
+        *,
+        use_nli: bool | None = None,
+        block_on_conflict: bool | None = None,
+    ) -> dict:
+        from .eval import evaluate_case
+
+        return evaluate_case(
+            case=case,
+            corpus=corpus,
+            config=self._config_with_runtime_flags(use_nli, block_on_conflict),
+        )
+
+    def run_eval(
+        self,
+        corpus_path: str | Path,
+        cases_path: str | Path,
+        *,
+        use_nli: bool | None = None,
+        block_on_conflict: bool | None = None,
+    ) -> dict:
+        from .eval import run_eval
+
+        return run_eval(
+            corpus_path=corpus_path,
+            cases_path=cases_path,
+            config=self._config_with_runtime_flags(use_nli, block_on_conflict),
+        )
+
+    def with_config(self, **overrides: Any) -> "StaleGuard":
+        return StaleGuard(self.config, **overrides)
+
+    def _config_with_runtime_flags(
+        self,
+        use_nli: bool | None,
+        block_on_conflict: bool | None,
+    ) -> StaleGuardConfig:
+        overrides = _clean_overrides(
+            {
+                "use_nli": self.config.use_nli if use_nli is None else use_nli,
+                "block_on_conflict": (
+                    self.config.block_on_conflict
+                    if block_on_conflict is None
+                    else block_on_conflict
+                ),
+            }
+        )
+        return replace(self.config, **overrides)

staleguard/audit_types.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class AuditResult:
+    verdict: str
+    confidence: float
+    stale_chunks: list
+    conflicts: list
+    fresh_alternatives: list
+    provenance: dict