stillvalid 0.1.0__py3-none-any.whl

stillvalid/integrations/common.py

@@ -0,0 +1,185 @@
+"""Shared glue — build a stillvalid Doc from a framework metadata dict.
+
+Frameworks disagree on metadata key names and time formats; this module
+normalizes both so the two wrappers (and any future one) stay thin.
+"""
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Any, Mapping, Sequence
+
+from ..doc import Doc
+
+#: metadata keys tried in order, per Doc field. "stillvalid_*" prefixed keys
+#: always win so callers can be explicit without renaming their pipeline.
+#: The rest are what real loaders actually write — verified against
+#: LangChain's TextLoader/DirectoryLoader and LlamaIndex's
+#: SimpleDirectoryReader rather than guessed.
+DEFAULT_KEYS: dict[str, Sequence[str]] = {
+    "last_verified_at": ("stillvalid_last_verified_at", "last_verified_at",
+                         "indexed_at", "index_time"),
+    "last_changed_at": ("stillvalid_last_changed_at", "last_changed_at",
+                        "last_modified", "modified_at", "updated_at",
+                        "last_modified_date"),     # LlamaIndex
+    "expires_at": ("stillvalid_expires_at", "expires_at", "expiry"),
+    "source_hash": ("stillvalid_source_hash", "source_hash"),
+    "verified_hash": ("stillvalid_verified_hash", "verified_hash",
+                      "content_hash"),
+    "source_modified_at": ("stillvalid_source_modified_at",
+                           "source_modified_at"),
+}
+
+#: metadata keys tried in order to identify a document. A stable id is not
+#: cosmetic: observations are keyed by it, so falling back to a per-run UUID
+#: would scatter one document's history across many ids and the change-rate
+#: and survival layers could never light up.
+DEFAULT_ID_KEYS: Sequence[str] = (
+    "stillvalid_doc_id", "source", "file_path", "url", "id", "doc_id",
+    "file_name",
+)
+
+_TIME_FIELDS = {"last_verified_at", "last_changed_at", "expires_at",
+                "source_modified_at"}
+
+
+def doc_id_from_metadata(metadata: Mapping[str, Any],
+                         id_key: str | None = None,
+                         *fallbacks: Any) -> str | None:
+    """Pick a stable document id: explicit key, then common loader keys,
+    then framework-supplied fallbacks (ref_doc_id, node id …)."""
+    keys = (id_key, *DEFAULT_ID_KEYS) if id_key else DEFAULT_ID_KEYS
+    for k in keys:
+        v = metadata.get(k)
+        if v:
+            return str(v)
+    for f in fallbacks:
+        if f:
+            return str(f)
+    return None
+
+
+def to_epoch(value: Any) -> float | None:
+    """Accept epoch numbers, ISO-8601 strings, or datetime objects.
+
+    Naive values (no offset) are read as UTC. That is the only defensible
+    default — guessing the machine's zone would make the same metadata mean
+    different things on different hosts — but it is a real trap: a naive
+    local timestamp from, say, UTC+9 lands nine hours off, which is enough
+    to turn "just edited" into "edited this morning" and flip a verdict.
+    Pass offsets (or epoch seconds) when the source has a zone.
+    """
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.timestamp()
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            pass
+        try:
+            dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    return None
+
+
+def doc_from_metadata(doc_id: str, metadata: Mapping[str, Any],
+                      keys: Mapping[str, Sequence[str]] | None = None) -> Doc:
+    keys = keys or DEFAULT_KEYS
+    fields: dict[str, Any] = {}
+    for field, candidates in keys.items():
+        for k in candidates:
+            if k in metadata and metadata[k] is not None:
+                v = metadata[k]
+                fields[field] = to_epoch(v) if field in _TIME_FIELDS else str(v)
+                break
+    return Doc(id=doc_id, **fields)
+
+
+def live_signals(ids: Sequence[str], *, timeout: float = 5.0,
+                 allow_private: bool = False) -> dict[str, dict]:
+    """Fetch CURRENT source signals for document ids, cheaply.
+
+    Index metadata is always a past snapshot, so on its own it can never
+    tell you whether the source has moved since — without this, a freshly
+    installed wrapper can only answer UNKNOWN. Two sources of truth are
+    cheap enough to consult at query time:
+
+      local path  → os.stat().st_mtime       (no I/O on the content)
+      http(s) URL → conditional HEAD request (no body, batched)
+
+    Returns {id: {"source_modified_at": …, "source_hash": …}} for the ids
+    it could resolve; unresolvable ids are simply absent.
+    """
+    import os
+
+    out: dict[str, dict] = {}
+    urls = []
+    for ident in ids:
+        if not ident:
+            continue
+        low = ident.lower()
+        if low.startswith(("http://", "https://")):
+            urls.append(ident)
+            continue
+        try:                      # local file: current mtime is the signal
+            st = os.stat(ident)
+        except (OSError, ValueError):
+            continue
+        out[ident] = {"source_modified_at": st.st_mtime}
+    if urls:
+        from ..probe import probe_many
+        for ident, r in zip(urls, probe_many(urls, timeout=timeout,
+                                             allow_private=allow_private)):
+            if not r.ok:
+                continue
+            sig = {}
+            if r.last_modified is not None:
+                sig["source_modified_at"] = r.last_modified
+            if r.etag:
+                sig["source_hash"] = r.etag
+            if sig:
+                out[ident] = sig
+    return out
+
+
+def verdict_metadata(v) -> dict:
+    """Verdict → JSON-safe dict to attach to framework metadata."""
+    return {
+        "state": v.state.value,
+        "action": v.action,
+        "usable": v.usable,
+        "layer": v.layer,
+        "reason": v.reason,
+        "summary": v.summary,
+        "probability": v.probability,
+        "calibrated": v.calibrated,
+    }
+
+
+#: auto-record: identical-hash sightings within this window are not re-logged
+AUTO_RECORD_DEDUP_S = 3600.0
+
+
+def auto_record(checker, doc_id: str, content: str, now: float) -> None:
+    """Log a sighting of retrieved content, if the checker keeps history.
+
+    Semantics worth knowing: this observes YOUR INDEX's copy, so a change
+    becomes visible only after a reindex — timestamps carry that lag. That
+    is exactly the fidelity the crude change-rate layer claims (uncalibrated
+    hint), so it feeds layer 5 legitimately; calibrated training should
+    prefer source-side timestamps when available.
+    """
+    if checker.history is None or not doc_id or content is None:
+        return
+    h = hashlib.sha256(content.encode("utf-8", "replace")).hexdigest()
+    checker.record(doc_id, h, ts=now, dedup_s=AUTO_RECORD_DEDUP_S)

stillvalid/integrations/langchain.py

@@ -0,0 +1,86 @@
+"""LangChain integration — a document compressor that judges validity.
+
+Use with ContextualCompressionRetriever so every retrieved document is
+checked between retrieval and the LLM:
+
+    from stillvalid import Checker
+    from stillvalid.integrations.langchain import StillValidCompressor
+    from langchain.retrievers import ContextualCompressionRetriever
+
+    retriever = ContextualCompressionRetriever(
+        base_compressor=StillValidCompressor(checker=Checker(...)),
+        base_retriever=vectorstore.as_retriever(),
+    )
+
+mode="annotate" (default) attaches the verdict to doc.metadata["stillvalid"]
+so your chain/agent can decide; mode="filter" drops non-usable documents
+outright (UNKNOWN kept unless drop_unknown=True — absence of evidence is
+not evidence of staleness).
+
+Requires langchain-core: pip install "stillvalid[langchain]".
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Optional, Sequence
+
+try:
+    from langchain_core.callbacks import Callbacks
+    from langchain_core.documents import Document
+    from langchain_core.documents.compressor import BaseDocumentCompressor
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "stillvalid.integrations.langchain requires langchain-core - "
+        "pip install 'stillvalid[langchain]'") from exc
+
+from ..cascade import Checker
+from .common import (DEFAULT_KEYS, auto_record, doc_from_metadata,
+                     doc_id_from_metadata, live_signals, verdict_metadata)
+
+
+class StillValidCompressor(BaseDocumentCompressor):
+    """Judge each retrieved document's validity; annotate or filter."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    checker: Any                      # stillvalid.Checker
+    mode: str = "annotate"            # "annotate" | "filter"
+    drop_unknown: bool = False        # filter mode: drop UNKNOWN too?
+    id_key: str | None = None         # metadata key holding the document id
+    metadata_keys: dict = dict(DEFAULT_KEYS)
+    record: bool = True               # auto-log sightings when history exists
+    live: bool = False                # consult the source for CURRENT signals
+    live_timeout: float = 5.0
+    allow_private: bool = False       # live: permit internal addresses
+
+    def compress_documents(
+        self, documents: Sequence[Document], query: str,
+        callbacks: Optional[Callbacks] = None,
+    ) -> Sequence[Document]:
+        now = time.time()   # one clock for the batch
+        checker: Checker = self.checker
+        ids = [doc_id_from_metadata(d.metadata, self.id_key, d.id)
+               for d in documents]
+        signals = live_signals([i for i in ids if i],
+                               timeout=self.live_timeout,
+                               allow_private=self.allow_private) \
+            if self.live else {}
+        out: list[Document] = []
+        for d, doc_id in zip(documents, ids):
+            if doc_id is None:
+                out.append(d)   # unidentifiable — nothing to judge or learn
+                continue
+            if self.record:
+                auto_record(checker, doc_id, d.page_content, now)
+            meta = d.metadata
+            if doc_id in signals:
+                meta = {**meta, **signals[doc_id]}
+            v = checker.check(
+                doc_from_metadata(doc_id, meta, self.metadata_keys),
+                now=now)
+            if self.mode == "filter" and not v.usable:
+                if v.state.value != "UNKNOWN" or self.drop_unknown:
+                    continue
+            d.metadata["stillvalid"] = verdict_metadata(v)
+            out.append(d)
+        return out

stillvalid/integrations/llamaindex.py

@@ -0,0 +1,81 @@
+"""LlamaIndex integration — a node postprocessor that judges validity.
+
+    from stillvalid import Checker
+    from stillvalid.integrations.llamaindex import StillValidPostprocessor
+
+    engine = index.as_query_engine(
+        node_postprocessors=[StillValidPostprocessor(checker=Checker(...))])
+
+mode="annotate" (default) writes the verdict into node.metadata["stillvalid"];
+mode="filter" drops non-usable nodes (UNKNOWN kept unless drop_unknown=True).
+
+Requires llama-index-core: pip install "stillvalid[llamaindex]".
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, List, Optional
+
+try:
+    from llama_index.core.postprocessor.types import BaseNodePostprocessor
+    from llama_index.core.schema import NodeWithScore, QueryBundle
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "stillvalid.integrations.llamaindex requires llama-index-core - "
+        "pip install 'stillvalid[llamaindex]'") from exc
+
+from .common import (DEFAULT_KEYS, auto_record, doc_from_metadata,
+                     doc_id_from_metadata, live_signals, verdict_metadata)
+
+
+class StillValidPostprocessor(BaseNodePostprocessor):
+    """Judge each retrieved node's validity; annotate or filter."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    checker: Any                      # stillvalid.Checker
+    mode: str = "annotate"            # "annotate" | "filter"
+    drop_unknown: bool = False
+    id_key: str | None = None         # metadata key holding the document id
+    metadata_keys: dict = dict(DEFAULT_KEYS)
+    record: bool = True               # auto-log sightings when history exists
+    live: bool = False                # consult the source for CURRENT signals
+    live_timeout: float = 5.0
+    allow_private: bool = False       # live: permit internal addresses
+
+    @classmethod
+    def class_name(cls) -> str:
+        return "StillValidPostprocessor"
+
+    def _postprocess_nodes(
+        self, nodes: List[NodeWithScore],
+        query_bundle: Optional[QueryBundle] = None,
+    ) -> List[NodeWithScore]:
+        now = time.time()   # one clock for the batch
+        # node_id is a per-ingest UUID — only a last resort, and never a
+        # stable key to learn from
+        ids = [doc_id_from_metadata(n.node.metadata, self.id_key,
+                                    getattr(n.node, "ref_doc_id", None),
+                                    n.node.node_id) for n in nodes]
+        signals = live_signals([i for i in ids if i],
+                               timeout=self.live_timeout,
+                               allow_private=self.allow_private) \
+            if self.live else {}
+        out: List[NodeWithScore] = []
+        for nws, doc_id in zip(nodes, ids):
+            node = nws.node
+            if self.record:
+                auto_record(self.checker, doc_id,
+                            node.get_content(), now)
+            meta = node.metadata
+            if doc_id in signals:
+                meta = {**meta, **signals[doc_id]}
+            v = self.checker.check(
+                doc_from_metadata(doc_id, meta, self.metadata_keys),
+                now=now)
+            if self.mode == "filter" and not v.usable:
+                if v.state.value != "UNKNOWN" or self.drop_unknown:
+                    continue
+            node.metadata["stillvalid"] = verdict_metadata(v)
+            out.append(nws)
+        return out

stillvalid/mcp_server.py

@@ -0,0 +1,247 @@
+"""MCP server — expose validity checking as tools an agent can call.
+
+An agent that is about to act on retrieved evidence asks this server
+whether the evidence is still trustworthy, and records sightings so the
+cascade learns. Run over stdio:
+
+    python -m stillvalid.mcp_server
+
+Configuration via environment variables:
+    STILLVALID_HISTORY_DB  path to the observation log (created if absent;
+                           omit to run without layers 5/record)
+    STILLVALID_PARAMS      path to gate-passed survival params JSON (layer 6)
+
+Claude Desktop / MCP client config example:
+
+    {"mcpServers": {"stillvalid": {
+        "command": "python", "args": ["-m", "stillvalid.mcp_server"],
+        "env": {"STILLVALID_HISTORY_DB": "C:/data/observations.db"}}}}
+
+Requires the mcp package: pip install "stillvalid[mcp]".
+"""
+from __future__ import annotations
+
+import os
+import time
+
+from .cascade import Checker
+from .doc import Doc
+from .integrations.common import to_epoch, verdict_metadata
+
+_checker: Checker | None = None
+
+
+def get_checker() -> Checker:
+    global _checker
+    if _checker is None:
+        _checker = Checker(
+            survival_params=os.environ.get("STILLVALID_PARAMS") or None,
+            history_db=os.environ.get("STILLVALID_HISTORY_DB") or None)
+    return _checker
+
+
+# ── tool implementations (plain functions — unit-testable without MCP) ──
+
+def check_validity_impl(doc_id: str,
+                        last_verified_at: float | str | None = None,
+                        last_changed_at: float | str | None = None,
+                        expires_at: float | str | None = None,
+                        source_modified_at: float | str | None = None,
+                        source_hash: str | None = None,
+                        verified_hash: str | None = None) -> dict:
+    v = get_checker().check(Doc(
+        id=doc_id,
+        last_verified_at=to_epoch(last_verified_at),
+        last_changed_at=to_epoch(last_changed_at),
+        expires_at=to_epoch(expires_at),
+        source_modified_at=to_epoch(source_modified_at),
+        source_hash=source_hash, verified_hash=verified_hash))
+    return {"doc_id": doc_id, **verdict_metadata(v)}
+
+
+def check_validity_batch_impl(docs: list[dict]) -> dict:
+    # Agents assemble these dicts from whatever metadata they scraped, so a
+    # malformed entry is routine. Isolate it: one bad item must not discard
+    # the verdicts for the good ones.
+    verdicts = []
+    for d in docs:
+        try:
+            verdicts.append(check_validity_impl(**d))
+        except Exception as e:
+            doc_id = str(d.get("doc_id", "?")) if isinstance(d, dict) else "?"
+            verdicts.append({
+                "doc_id": doc_id, "state": "UNKNOWN", "action": "verify",
+                "usable": False, "layer": "none",
+                "reason": f"could not be read: {type(e).__name__}",
+                "summary": f"'{doc_id}' could not be judged - its input was "
+                           f"malformed ({type(e).__name__}). Treat it as "
+                           "unverified.",
+                "probability": None, "calibrated": False})
+    n = len(verdicts)
+    # stale ("known to have moved") and unknown ("no evidence either way")
+    # call for the same caution but are not the same claim — saying so keeps
+    # the relayed sentence honest.
+    stale = [v["doc_id"] for v in verdicts if v["state"] in ("STALE", "VERIFY")]
+    unknown = [v["doc_id"] for v in verdicts if v["state"] == "UNKNOWN"]
+    if not stale and not unknown:
+        digest = f"All {n} documents are safe to use - no re-verification needed."
+    else:
+        parts = []
+        if stale:
+            parts.append(f"{len(stale)} changed or uncertain "
+                         f"({', '.join(stale)}) - re-fetch before quoting")
+        if unknown:
+            parts.append(f"{len(unknown)} unjudgeable for lack of evidence "
+                         f"({', '.join(unknown)}) - treat as unverified")
+        digest = f"Of {n} documents: " + "; ".join(parts) + "."
+    return {"digest": digest, "verdicts": verdicts}
+
+
+def import_history_impl(git_repo: str | None = None,
+                        csv_path: str | None = None,
+                        prefix: str = "") -> dict:
+    from . import backfill
+
+    ck = get_checker()
+    if git_repo:
+        n = backfill.from_git(ck, git_repo, prefix=prefix)
+        src = f"git repository {git_repo}"
+    elif csv_path:
+        n = backfill.from_csv(ck, csv_path, prefix=prefix)
+        src = f"CSV {csv_path}"
+    else:
+        raise ValueError("pass git_repo or csv_path")
+    s = backfill.summarize(ck)
+    return {
+        "imported": n, "source": src, **s,
+        "summary": (f"Imported {n:,} past changes from {src}. "
+                    f"{s['change_rate_ready']:,} of {s['documents']:,} "
+                    "documents now have enough history to be judged on "
+                    "their update behavior, with no waiting."),
+    }
+
+
+def refresh_evidence_impl(doc_id: str, source: str | None = None,
+                          known_hash: str | None = None,
+                          allow_private: bool = False) -> dict:
+    from .refresh import refresh
+
+    return refresh(get_checker(), doc_id, source, known_hash=known_hash,
+                   allow_private=allow_private)
+
+
+def record_observation_impl(doc_id: str, value_hash: str,
+                            ts: float | str | None = None) -> dict:
+    get_checker().record(doc_id, value_hash, ts=to_epoch(ts))
+    return {"recorded": True, "doc_id": doc_id,
+            "ts": to_epoch(ts) or time.time(),
+            "summary": f"Recorded a sighting of '{doc_id}'. Its update "
+                       "behavior is being learned from these observations."}
+
+
+# ── MCP wiring ───────────────────────────────────────────────
+
+def build_server():
+    try:
+        from mcp.server.mcpserver import MCPServer as _Server   # mcp >= 2
+    except ImportError:
+        try:
+            from mcp.server.fastmcp import FastMCP as _Server   # mcp 1.x
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError("the MCP server requires the mcp package - "
+                              "pip install 'stillvalid[mcp]'") from exc
+
+    from . import __version__
+    try:
+        mcp = _Server("stillvalid", version=__version__)
+    except TypeError:        # mcp 1.x FastMCP takes no version
+        mcp = _Server("stillvalid")
+
+    @mcp.tool()
+    def check_validity(doc_id: str,
+                       last_verified_at: float | str | None = None,
+                       last_changed_at: float | str | None = None,
+                       expires_at: float | str | None = None,
+                       source_modified_at: float | str | None = None,
+                       source_hash: str | None = None,
+                       verified_hash: str | None = None) -> dict:
+        """Judge whether a piece of retrieved evidence is still valid.
+
+        Call BEFORE acting on a document (quoting a policy, using a price,
+        executing a workflow step). Returns state VALID / LIKELY_VALID /
+        VERIFY / STALE / UNKNOWN plus a one-sentence `summary` — relay that
+        summary to the user so they can see why evidence was trusted or
+        re-fetched. When the verdict is STALE or VERIFY, do not quote the
+        cached copy: call refresh_evidence to get the current content and
+        answer from that instead. Timestamps are epoch seconds or ISO-8601
+        strings.
+        """
+        return check_validity_impl(
+            doc_id, last_verified_at, last_changed_at, expires_at,
+            source_modified_at, source_hash, verified_hash)
+
+    @mcp.tool()
+    def check_validity_batch(docs: list[dict]) -> dict:
+        """Judge several documents at once (one shared clock).
+
+        Each item: {"doc_id": ..., "last_verified_at": ...,
+        "last_changed_at": ..., optionally expires_at /
+        source_modified_at / source_hash / verified_hash}.
+        Returns {"digest": one-sentence overview to relay to the user,
+        "verdicts": [...]}. Act on the digest: re-fetch the listed
+        documents before quoting them.
+        """
+        return check_validity_batch_impl(docs)
+
+    @mcp.tool()
+    def import_history(git_repo: str | None = None,
+                       csv_path: str | None = None,
+                       prefix: str = "") -> dict:
+        """Load a corpus's PAST changes so judging works immediately.
+
+        Use this first, whenever the user points at a knowledge base that
+        already keeps history — a git repository of docs, or an export of
+        wiki revisions / CMS audit rows as CSV (columns: doc_id, ts[, rev]).
+        It takes seconds and removes the need to observe anything for
+        weeks before the update-behavior layers can say anything.
+        Relay the returned summary so the user sees what became judgeable.
+        """
+        return import_history_impl(git_repo, csv_path, prefix)
+
+    @mcp.tool()
+    def refresh_evidence(doc_id: str, source: str | None = None,
+                         known_hash: str | None = None,
+                         allow_private: bool = False) -> dict:
+        """Fetch the CURRENT content of a stale document and use it.
+
+        Call this when check_validity says STALE or VERIFY: it retrieves
+        the live content (local path or http(s) URL; `source` defaults to
+        doc_id), logs the sighting so future judgments improve, and — when
+        you pass the hash of your cached copy as known_hash — tells you
+        whether the content actually changed. Answer the user from the
+        returned `content`, not from your cached copy, and relay the
+        `summary`. Set allow_private=True only for internal addresses.
+        """
+        return refresh_evidence_impl(doc_id, source, known_hash,
+                                     allow_private)
+
+    @mcp.tool()
+    def record_observation(doc_id: str, value_hash: str,
+                           ts: float | str | None = None) -> dict:
+        """Log that you saw a document's current content hash.
+
+        Call whenever evidence is fetched or re-verified — the validity
+        cascade learns each document's change behavior from this log.
+        Requires STILLVALID_HISTORY_DB to be configured.
+        """
+        return record_observation_impl(doc_id, value_hash, ts)
+
+    return mcp
+
+
+def main() -> None:
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()