convmemory 0.5.0__tar.gz → 0.6.0__tar.gz

{convmemory-0.5.0 → convmemory-0.6.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: convmemory
-Version: 0.5.0
+Version: 0.6.0
 Summary: Lightweight temporal memory reranking for long-term conversational memory.
 Author: ConvMemory contributors
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/pth2002/ConvMemory
 Project-URL: Issues, https://github.com/pth2002/ConvMemory/issues
 Keywords: memory,retrieval,reranking,rag,agents
@@ -25,6 +25,7 @@ Requires-Dist: tqdm>=4.60
 Requires-Dist: scikit-learn>=1.2
 Provides-Extra: hub
 Requires-Dist: huggingface_hub>=0.20; extra == "hub"
+Dynamic: license-file
 
 # ConvMemory
 
@@ -54,7 +55,7 @@ reranker. Its intended use is recall-oriented memory selection for structured
 memory streams: conversations, user histories, agent traces, task logs, and
 session-level notes.
 
-Current package version: `0.5.0`
+Current package version: `0.6.0`
 
 ## When To Use It
 
@@ -312,6 +313,31 @@ ranked = model.retrieve(
 See [Evidence Reranker](docs/EVIDENCE_RERANKER.md) for the v363 headline
 numbers, v364 load-bearing ablations, anti-leak guards, and limitations.
 
+### ConvMemory v3: Validity Context Layer
+
+ConvMemory v3 adds validity evidence for agent memory without changing v1/v2
+ranking by default. In `validity_mode="context"`, returned memories can carry a
+structured `validity` note with possible update evidence; the rank order and
+candidate set are preserved. Automatic demotion is available only as an explicit
+opt-in mode for dense current-state/update workloads.
+
+```python
+model.load_validity_module("Purdy0228/ConvMemory-v3-Validity-Context")
+
+ranked = model.retrieve(
+    query=query,
+    memories=candidates,
+    evidence_reranker="v2",
+    validity_mode="context",
+    top_k=10,
+)
+```
+
+See [Validity Context](docs/VALIDITY_CONTEXT.md) for mode semantics and safety
+contracts. See [V3 Model Card](docs/V3_MODEL_CARD.md) for checkpoint
+provenance, package-level benchmark numbers, latency, and the source-of-truth
+ledger.
+
 ### Experimental Memory-MLA Recall Expander
 
 This is **not** the v0.5.0 evidence reranker. See "ConvMemory v2: Evidence

{convmemory-0.5.0 → convmemory-0.6.0}/README.md

@@ -26,7 +26,7 @@ reranker. Its intended use is recall-oriented memory selection for structured
 memory streams: conversations, user histories, agent traces, task logs, and
 session-level notes.
 
-Current package version: `0.5.0`
+Current package version: `0.6.0`
 
 ## When To Use It
 
@@ -281,13 +281,38 @@ ranked = model.retrieve(
 )
 ```
 
-See [Evidence Reranker](docs/EVIDENCE_RERANKER.md) for the v363 headline
-numbers, v364 load-bearing ablations, anti-leak guards, and limitations.
-
-### Experimental Memory-MLA Recall Expander
-
-This is **not** the v0.5.0 evidence reranker. See "ConvMemory v2: Evidence
-Reranker" above for the v2 release.
+See [Evidence Reranker](docs/EVIDENCE_RERANKER.md) for the v363 headline
+numbers, v364 load-bearing ablations, anti-leak guards, and limitations.
+
+### ConvMemory v3: Validity Context Layer
+
+ConvMemory v3 adds validity evidence for agent memory without changing v1/v2
+ranking by default. In `validity_mode="context"`, returned memories can carry a
+structured `validity` note with possible update evidence; the rank order and
+candidate set are preserved. Automatic demotion is available only as an explicit
+opt-in mode for dense current-state/update workloads.
+
+```python
+model.load_validity_module("Purdy0228/ConvMemory-v3-Validity-Context")
+
+ranked = model.retrieve(
+    query=query,
+    memories=candidates,
+    evidence_reranker="v2",
+    validity_mode="context",
+    top_k=10,
+)
+```
+
+See [Validity Context](docs/VALIDITY_CONTEXT.md) for mode semantics and safety
+contracts. See [V3 Model Card](docs/V3_MODEL_CARD.md) for checkpoint
+provenance, package-level benchmark numbers, latency, and the source-of-truth
+ledger.
+
+### Experimental Memory-MLA Recall Expander
+
+This is **not** the v0.5.0 evidence reranker. See "ConvMemory v2: Evidence
+Reranker" above for the v2 release.
 
 Memory-MLA is an opt-in prefix-protected recall expander. It is not a
 replacement for v1, and it is off by default: `retrieve(query, memories)` remains

{convmemory-0.5.0 → convmemory-0.6.0}/convmemory/__init__.py

@@ -9,14 +9,15 @@ from .ccge import (
 from .api import ConvMemory
 from .evidence_reranker import EvidenceReranker, EvidenceRerankerConfig
 from .memory_mla import MemoryMLAConfig, MemoryMLAExpander
-from .reranker import ConvMemoryReranker, RerankConfig, RerankResult
-from .routing import (
-    CompressedNoteConfig,
-    CompressionRouteConfig,
-    CompressionRouteResult,
+from .reranker import ConvMemoryReranker, RerankConfig, RerankResult
+from .routing import (
+    CompressedNoteConfig,
+    CompressionRouteConfig,
+    CompressionRouteResult,
     CompressionRouter,
-    build_compressed_notes,
-)
+    build_compressed_notes,
+)
+from .validity import ValidityAnnotation, ValidityEvidenceConfig, ValidityEvidenceModule
 
 __all__ = [
     "CompressedNoteConfig",
@@ -32,9 +33,12 @@ __all__ = [
     "CompressionRouteConfig",
     "CompressionRouteResult",
     "CompressionRouter",
-    "RerankConfig",
-    "RerankResult",
-    "build_ccge_features",
+    "RerankConfig",
+    "RerankResult",
+    "ValidityAnnotation",
+    "ValidityEvidenceConfig",
+    "ValidityEvidenceModule",
+    "build_ccge_features",
     "build_compressed_notes",
     "multi_positive_retrieval_loss",
     "rank_candidates",

{convmemory-0.5.0 → convmemory-0.6.0}/convmemory/api.py

@@ -15,6 +15,8 @@ from .memory_mla import MemoryMLAExpander
 from .models import build_default_components
 from .reranker import ConvMemoryReranker, RerankConfig, RerankResult
 from .scoring import cosine_scores, lexical_signature
+from .validity import FORBIDDEN_FIELDS as VALIDITY_FORBIDDEN_FIELDS
+from .validity import ValidityEvidenceModule
 
 
 _POSITION_RE = re.compile(r"-?\d+(?:\.\d+)?")
@@ -39,6 +41,7 @@ class ConvMemory:
         ccge_editor=None,
         expander=None,
         evidence_reranker=None,
+        validity_module=None,
     ):
         self.device = device
         self.config = config or RerankConfig()
@@ -48,6 +51,7 @@ class ConvMemory:
         self.ccge_editor = None
         self.memory_mla_expander = None
         self._evidence_reranker = None
+        self._validity_module = None
         self.reranker = ConvMemoryReranker(
             conv_model=conv_model,
             scorer=scorer,
@@ -62,6 +66,8 @@ class ConvMemory:
             self.attach_expander(expander)
         if evidence_reranker is not None:
             self.attach_evidence_reranker(evidence_reranker)
+        if validity_module is not None:
+            self.attach_validity_module(validity_module)
 
     @classmethod
     def from_config(
@@ -73,6 +79,7 @@ class ConvMemory:
         ccge_editor=None,
         expander=None,
         evidence_reranker=None,
+        validity_module=None,
         **model_kwargs,
     ):
         """Create a ConvMemory instance from dimensions and config.
@@ -114,6 +121,7 @@ class ConvMemory:
             ccge_editor=ccge_editor,
             expander=expander,
             evidence_reranker=evidence_reranker,
+            validity_module=validity_module,
         )
 
     @classmethod
@@ -310,6 +318,34 @@ class ConvMemory:
             device=device or self.device,
         )
         return self.attach_evidence_reranker(reranker)
+
+    def attach_validity_module(self, validity_module):
+        """Attach a ConvMemory v3 validity context module.
+
+        The module is disabled unless callers pass `validity_mode="context"`
+        or `validity_mode="demote"`. Context mode annotates results without
+        changing order; demote mode is explicit opt-in and preserves the
+        candidate set while allowing score-based reordering.
+        """
+
+        if not isinstance(validity_module, ValidityEvidenceModule):
+            raise TypeError("validity_module must be a ValidityEvidenceModule")
+        self._validity_module = validity_module
+        return self
+
+    def load_validity_module(self, path_or_hub_id: str, device=None):
+        """Load and attach a ConvMemory v3 validity context module.
+
+        `path_or_hub_id` may be a local checkpoint directory or a Hugging Face
+        Hub repo id. Loading is explicit so the plain v1/v2 retrieval path
+        remains backward-compatible.
+        """
+
+        validity_module = ValidityEvidenceModule.from_pretrained(
+            path_or_hub_id,
+            device=device or self.device,
+        )
+        return self.attach_validity_module(validity_module)
 
     def encode(self, texts):
         """Encode texts with the attached sentence-transformer encoder.
@@ -353,6 +389,7 @@ class ConvMemory:
         protect_top_k: int = 7,
         expand_window: int = 16,
         evidence_reranker=None,
+        validity_mode=None,
     ):
         """Rerank text memories and return `list[RerankResult]`.
 
@@ -367,7 +404,9 @@ class ConvMemory:
         reranker, or window-mode settings.
         """
 
-        memory_ids, memory_texts = self._parse_memories(memories)
+        memories = list(memories)
+        self._validate_validity_memory_input(memories, validity_mode)
+        memory_ids, memory_texts = self._parse_memories(memories)
         embeddings = self.encode([query, *memory_texts])
         query_embedding = embeddings[0]
         memory_embeddings = embeddings[1:]
@@ -393,6 +432,7 @@ class ConvMemory:
             protect_top_k=protect_top_k,
             expand_window=expand_window,
             evidence_reranker=evidence_reranker,
+            validity_mode=validity_mode,
         )
         return results[:top_k] if top_k is not None else results
 
@@ -414,6 +454,7 @@ class ConvMemory:
         protect_top_k: int = 7,
         expand_window: int = 16,
         evidence_reranker=None,
+        validity_mode=None,
     ):
         """Retrieve memories and return `list[RerankResult]`.
 
@@ -441,6 +482,7 @@ class ConvMemory:
                 protect_top_k=protect_top_k,
                 expand_window=expand_window,
                 evidence_reranker=evidence_reranker,
+                validity_mode=validity_mode,
             )
         if selected_mode not in {"expand", "context", "expand_context"}:
             raise ValueError("mode must be either 'rerank' or 'expand'")
@@ -466,6 +508,7 @@ class ConvMemory:
             protect_top_k=protect_top_k,
             expand_window=expand_window,
             evidence_reranker=evidence_reranker,
+            validity_mode=validity_mode,
         )
 
     def expand_context(
@@ -484,6 +527,7 @@ class ConvMemory:
         protect_top_k: int = 7,
         expand_window: int = 16,
         evidence_reranker=None,
+        validity_mode=None,
     ):
         """Build a wider memory context and return `list[RerankResult]`.
 
@@ -496,7 +540,9 @@ class ConvMemory:
         Raises `ValueError` for invalid expansion policies, editor settings,
         expander settings, or evidence-reranker settings.
         """
-        memory_ids, memory_texts = self._parse_memories(memories)
+        memories = list(memories)
+        self._validate_validity_memory_input(memories, validity_mode)
+        memory_ids, memory_texts = self._parse_memories(memories)
         embeddings = self.encode([query, *memory_texts])
         query_embedding = embeddings[0]
         memory_embeddings = embeddings[1:]
@@ -526,6 +572,7 @@ class ConvMemory:
             protect_top_k=protect_top_k,
             expand_window=expand_window,
             evidence_reranker=evidence_reranker,
+            validity_mode=validity_mode,
         )
 
     def rerank_embeddings(
@@ -544,6 +591,7 @@ class ConvMemory:
         protect_top_k: int = 7,
         expand_window: int = 16,
         evidence_reranker=None,
+        validity_mode=None,
     ):
         """Rerank precomputed embeddings and return `list[RerankResult]`.
 
@@ -596,6 +644,13 @@ class ConvMemory:
             query=query,
             evidence_reranker=evidence_reranker,
         )
+        results = self._maybe_apply_validity_module(
+            results=results,
+            memory_ids=memory_ids,
+            memory_texts=memory_texts,
+            query=query,
+            validity_mode=validity_mode,
+        )
         return results[:top_k] if top_k is not None else results
 
     def expand_context_embeddings(
@@ -617,6 +672,7 @@ class ConvMemory:
         protect_top_k: int = 7,
         expand_window: int = 16,
         evidence_reranker=None,
+        validity_mode=None,
     ):
         """Expand context over precomputed embeddings.
 
@@ -652,6 +708,7 @@ class ConvMemory:
             protect_top_k=protect_top_k,
             expand_window=expand_window,
             evidence_reranker=evidence_reranker,
+            validity_mode=validity_mode,
         )
         if context_budget <= protected_k:
             return self._rerank_with_new_positions(base_results[:context_budget])
@@ -687,6 +744,7 @@ class ConvMemory:
                 protect_top_k=protect_top_k,
                 expand_window=expand_window,
                 evidence_reranker=evidence_reranker,
+                validity_mode=validity_mode,
             )
             rankings.append([result.memory_id for result in local_results])
             result_by_id.update({result.memory_id: result for result in local_results})
@@ -800,6 +858,70 @@ class ConvMemory:
         tail = [result for result in results if result.memory_id not in prefix_ids]
         return self._rerank_with_new_positions([*reordered, *tail])
 
+    def _resolve_validity_mode(self, validity_mode):
+        if validity_mode is None:
+            return None
+        if isinstance(validity_mode, str):
+            mode = validity_mode.lower().strip()
+            if mode == "off":
+                return None
+            if mode in {"context", "demote"}:
+                if self._validity_module is None:
+                    raise ValueError(
+                        "No validity module is attached. Call "
+                        "`load_validity_module(path)` or "
+                        "`attach_validity_module(module)` before using "
+                        f"validity_mode='{mode}'."
+                    )
+                return mode
+        raise ValueError("validity_mode must be None, 'off', 'context', or 'demote'")
+
+    def _maybe_apply_validity_module(
+        self,
+        *,
+        results,
+        memory_ids,
+        memory_texts,
+        query,
+        validity_mode,
+    ):
+        mode = self._resolve_validity_mode(validity_mode)
+        if mode is None or not results:
+            return results
+        memories = self._validity_memories(memory_ids, memory_texts)
+        return self._validity_module.apply(
+            query=query,
+            results=results,
+            memories=memories,
+            mode=mode,
+        )
+
+    @staticmethod
+    def _validity_memories(memory_ids, memory_texts):
+        if memory_texts is None:
+            memory_texts = ["" for _ in memory_ids]
+        memories = []
+        for idx, (memory_id, text) in enumerate(zip(memory_ids, memory_texts)):
+            memories.append(
+                {
+                    "id": str(memory_id),
+                    "text": str(text),
+                    "position": idx,
+                }
+            )
+        return memories
+
+    def _validate_validity_memory_input(self, memories, validity_mode):
+        if self._resolve_validity_mode(validity_mode) is None:
+            return
+        for memory in memories:
+            if isinstance(memory, str):
+                continue
+            blocked = VALIDITY_FORBIDDEN_FIELDS.intersection(memory.keys())
+            if blocked:
+                field = sorted(blocked)[0]
+                raise ValueError(f"field '{field}' is not allowed at inference")
+
     def _resolve_expander(self, expander):
         message = "expander must be None, 'memory_mla', or a MemoryMLAExpander instance"
         if expander is None:
@@ -1011,10 +1133,11 @@ class ConvMemory:
             RerankResult(
                 memory_id=result.memory_id,
                 score=result.score,
-                raw_score=result.raw_score,
-                rank=rank,
-                text=result.text,
-            )
+                raw_score=result.raw_score,
+                rank=rank,
+                text=result.text,
+                validity=result.validity,
+            )
             for rank, result in enumerate(results, start=1)
         ]
 

convmemory-0.6.0/convmemory/hub.py

@@ -0,0 +1,87 @@
+"""Optional Hugging Face Hub path resolution helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+try:
+    from huggingface_hub import HfApi as _HfApi
+    from huggingface_hub import hf_hub_download as _hf_hub_download
+    from huggingface_hub import snapshot_download as _hf_snapshot_download
+except Exception:  # pragma: no cover - exercised when optional dep is absent
+    _HfApi = None
+    _hf_hub_download = None
+    _hf_snapshot_download = None
+
+
+def looks_like_hub_id(path: str | Path) -> bool:
+    """Return whether a missing path looks like a `namespace/repo` Hub id."""
+
+    text = str(path).replace("\\", "/").strip()
+    if not text or "://" in text or ":" in text:
+        return False
+    if text.startswith(("/", "./", "../", "~")):
+        return False
+    parts = text.split("/")
+    return len(parts) == 2 and all(parts)
+
+
+def resolve_checkpoint_path(path: str | Path, *, repo_type: str = "model") -> Path:
+    """Resolve a local checkpoint path or download a Hugging Face Hub repo id."""
+
+    candidate = Path(path)
+    if candidate.exists():
+        return candidate
+    if not looks_like_hub_id(path):
+        return candidate
+    if _hf_snapshot_download is None:
+        raise ValueError(
+            "Checkpoint path does not exist and looks like a Hugging Face Hub "
+            "repo id, but `huggingface_hub` is not installed. Install it with "
+            "`pip install huggingface_hub` or pass a local checkpoint path."
+        )
+    try:
+        return Path(_hf_snapshot_download(repo_id=str(path), repo_type=repo_type))
+    except Exception as exc:
+        try:
+            return _download_hub_repo_without_snapshot_symlinks(str(path), repo_type=repo_type)
+        except Exception as fallback_exc:
+            raise ValueError(
+                f"Could not download Hugging Face Hub checkpoint repo '{path}'. "
+                "Pass a local checkpoint path or verify repo access."
+            ) from fallback_exc
+
+
+def _download_hub_repo_without_snapshot_symlinks(repo_id: str, *, repo_type: str = "model") -> Path:
+    """Download a small checkpoint repo without relying on snapshot symlinks.
+
+    Some Windows environments do not allow symlink creation. Hugging Face Hub's
+    snapshot cache can fail there before it has a chance to fall back cleanly, so
+    ConvMemory downloads each file into a plain local directory as a compatibility
+    path.
+    """
+
+    if _HfApi is None or _hf_hub_download is None:
+        raise RuntimeError("huggingface_hub is not installed")
+    cache_root = os.environ.get("CONVMEMORY_CACHE")
+    if cache_root:
+        base = Path(cache_root)
+    else:
+        base = Path.home() / ".cache" / "convmemory"
+    digest = hashlib.sha1(repo_id.encode("utf-8")).hexdigest()[:12]
+    target = base / "hub" / f"{repo_id.replace('/', '--')}-{digest}"
+    target.mkdir(parents=True, exist_ok=True)
+
+    files = _HfApi().list_repo_files(repo_id=repo_id, repo_type=repo_type)
+    for filename in files:
+        if filename.endswith("/"):
+            continue
+        _hf_hub_download(
+            repo_id=repo_id,
+            filename=filename,
+            repo_type=repo_type,
+            local_dir=target,
+        )
+    return target

{convmemory-0.5.0 → convmemory-0.6.0}/convmemory/reranker.py

@@ -31,6 +31,7 @@ class RerankResult:
     raw_score: float
     rank: int
     text: Optional[str] = None
+    validity: Optional[dict] = None
 
 
 def sliding_windows(num_items: int, window_size: int, stride: int):