dandelion-memory 1.0.0rc15__py3-none-any.whl

benchmarks/adapters/controlled/extract_resolve.py

@@ -0,0 +1,130 @@
+"""Controlled Architectural Baseline: Extract & Resolve (Mem0 Legacy / Entity-RAG paradigm).
+
+Characteristics:
+- Extracts discrete facts into an Entity Store with conflict resolution (ADD / UPDATE).
+- Episodic memory passages are stored as static text strings.
+- When a fact updates, its entity record updates, but past episodic texts remain unchanged.
+- Demonstrates why updating facts alone does not fix historical timeline rewriting or stale state in episodic memory.
+"""
+
+import re
+from typing import Any, Optional
+from dandelion.store_vector import VectorStore
+from benchmarks.adapters.base import BaseMemoryAdapter
+
+
+class ExtractResolveAdapter(BaseMemoryAdapter):
+    """Extract & Resolve baseline representing entity extraction with fact overwrite."""
+
+    def __init__(self) -> None:
+        self.entity_facts: dict[str, dict[str, Any]] = {}
+        self.vec: Optional[VectorStore] = None
+        self.reset()
+
+    @property
+    def name(self) -> str:
+        return "extract_resolve"
+
+    def reset(self) -> None:
+        self.entity_facts.clear()
+        self.vec = VectorStore(in_memory=True)
+        import dandelion.store_kv
+        dandelion.store_kv._store = None
+
+    def ingest_fact(
+        self,
+        key: str,
+        value: str,
+        timestamp: float,
+        domain: str = "general",
+        source: str = "config_read",
+    ) -> None:
+        # Conflict resolution: update entity record with latest observation
+        self.entity_facts[key] = {
+            "value": value,
+            "domain": domain,
+            "updated_at": timestamp,
+            "source": source,
+        }
+        # Also index fact representation in vector store
+        fact_repr = f"Fact: {key} is {value} in domain {domain}."
+        self.vec.save_chunk(
+            domain=domain,
+            template=fact_repr,
+            source=source,
+            created_at=timestamp,
+            event_id=f"fact_{key}",
+        )
+
+    def ingest_memory(
+        self,
+        event_id: str,
+        template: str,
+        domain: str,
+        timestamp: float,
+        supersedes: Optional[str] = None,
+        source: str = "tool_observed",
+    ) -> str:
+        # Resolve entities eagerly against the current entity store at ingestion time
+        def _resolve(m: re.Match) -> str:
+            raw_key = m.group(1).split("@rev:")[0]
+            if domain:
+                qual_key = f"{domain}.{raw_key}"
+                if qual_key in self.entity_facts:
+                    return str(self.entity_facts[qual_key]["value"])
+            if raw_key in self.entity_facts:
+                return str(self.entity_facts[raw_key]["value"])
+            return f"[UNKNOWN: {raw_key}]"
+
+        inlined = re.sub(r"\{\{(?:ref|snapshot):([\w.:\-]+)\}\}", _resolve, template)
+        if domain:
+            inlined = inlined.replace("{{domain}}", domain)
+
+        return self.vec.save_chunk(
+            domain=domain,
+            template=inlined,
+            supersedes=supersedes,
+            source=source,
+            created_at=timestamp,
+            event_id=event_id,
+        )
+
+    def recall(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+        limit: int = 3,
+    ) -> list[dict[str, Any]]:
+        domains = [domain] if domain and not domain.endswith(".*") else None
+        raw_results = self.vec.search_chunks(
+            query=query,
+            domains=domains,
+            limit=limit,
+            use_reverse_index=False,
+            use_lexical_rerank=False,
+        )
+        return [
+            {
+                "id": r["id"],
+                "event_id": r.get("event_id", ""),
+                "text": r["template"],
+                "domain": r["domain"],
+                "score": r.get("score", 0.0),
+                "vector_score": r.get("vector_score", 0.0),
+            }
+            for r in raw_results
+        ]
+
+    def get_fact(
+        self,
+        key: str,
+        domain: Optional[str] = None,
+        at: Optional[float] = None,
+    ) -> Optional[str]:
+        if domain:
+            qual_key = f"{domain}.{key}"
+            if qual_key in self.entity_facts:
+                return str(self.entity_facts[qual_key]["value"])
+        if key in self.entity_facts:
+            return str(self.entity_facts[key]["value"])
+        return None

benchmarks/adapters/controlled/hybrid_rag.py

@@ -0,0 +1,120 @@
+"""Controlled Architectural Baseline: Hybrid RAG (Dense + BM25 Lexical + RRF).
+
+Characteristics:
+- Full state-of-the-art hybrid search (Dense FastEmbed ONNX + Lexical tokens via RRF K=60).
+- Eager static text chunks: facts are inlined directly at ingestion time.
+- No symbolic fact store, no late-binding hydration, no reverse fact index.
+- Raw retrieved content returned without server-enforced secret redaction.
+"""
+
+import re
+from typing import Any, Optional
+from dandelion.store_vector import VectorStore
+from benchmarks.adapters.base import BaseMemoryAdapter
+
+
+class HybridRAGAdapter(BaseMemoryAdapter):
+    """Hybrid RAG baseline combining Dense vector search and BM25-style lexical search."""
+
+    def __init__(self) -> None:
+        self.facts: dict[str, str] = {}
+        self.vec: Optional[VectorStore] = None
+        self.reset()
+
+    @property
+    def name(self) -> str:
+        return "hybrid_rag"
+
+    def reset(self) -> None:
+        self.facts.clear()
+        self.vec = VectorStore(in_memory=True)
+        import dandelion.store_kv
+        dandelion.store_kv._store = None
+
+    def ingest_fact(
+        self,
+        key: str,
+        value: str,
+        timestamp: float,
+        domain: str = "general",
+        source: str = "config_read",
+    ) -> None:
+        self.facts[key] = value
+        # Index fact as a standalone passage in hybrid store
+        fact_sentence = f"Configuration fact '{key}' is set to '{value}' in domain '{domain}'."
+        self.vec.save_chunk(
+            domain=domain,
+            template=fact_sentence,
+            source=source,
+            created_at=timestamp,
+            event_id=f"fact_{key}",
+        )
+
+    def ingest_memory(
+        self,
+        event_id: str,
+        template: str,
+        domain: str,
+        timestamp: float,
+        supersedes: Optional[str] = None,
+        source: str = "tool_observed",
+    ) -> str:
+        def _resolve_eager(m: re.Match) -> str:
+            raw_key = m.group(1).split("@rev:")[0]
+            if domain:
+                qual_key = f"{domain}.{raw_key}"
+                if qual_key in self.facts:
+                    return self.facts[qual_key]
+            return self.facts.get(raw_key, f"[MISSING: {raw_key}]")
+
+        inlined = re.sub(r"\{\{(?:ref|snapshot):([\w.:\-]+)\}\}", _resolve_eager, template)
+        if domain:
+            inlined = inlined.replace("{{domain}}", domain)
+
+        return self.vec.save_chunk(
+            domain=domain,
+            template=inlined,
+            supersedes=supersedes,
+            source=source,
+            created_at=timestamp,
+            event_id=event_id,
+        )
+
+    def recall(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+        limit: int = 3,
+    ) -> list[dict[str, Any]]:
+        domains = [domain] if domain and not domain.endswith(".*") else None
+        # Full hybrid search (Dense + Lexical via RRF) without Dandelion reverse lookup
+        raw_results = self.vec.search_chunks(
+            query=query,
+            domains=domains,
+            limit=limit,
+            use_reverse_index=False,
+            use_lexical_rerank=True,
+        )
+        return [
+            {
+                "id": r["id"],
+                "event_id": r.get("event_id", ""),
+                "text": r["template"],
+                "domain": r["domain"],
+                "score": r.get("score", 0.0),
+                "vector_score": r.get("vector_score", 0.0),
+            }
+            for r in raw_results
+        ]
+
+    def get_fact(
+        self,
+        key: str,
+        domain: Optional[str] = None,
+        at: Optional[float] = None,
+    ) -> Optional[str]:
+        if domain:
+            qual_key = f"{domain}.{key}"
+            if qual_key in self.facts:
+                return self.facts[qual_key]
+        return self.facts.get(key)

benchmarks/adapters/controlled/no_late_binding.py

@@ -0,0 +1,113 @@
+"""Controlled Architectural Ablation: NoLateBinding (Eager Dandelion).
+
+Characteristics:
+- Identical primitives to full Dandelion: KVStore, FastEmbed ONNX, Lexical matching, Reverse Index, RRF.
+- Identical server-side secret filtering policy.
+- ONLY difference: {{ref:key}} and {{snapshot:key}} are resolved and inlined at write-time (ingest_memory)
+  rather than hydrated at read-time (recall).
+- Isolates the exact marginal causal lift of Late-Binding Hydration.
+"""
+
+import re
+from typing import Any, Optional
+from dandelion.store_kv import KVStore
+from dandelion.store_vector import VectorStore
+from benchmarks.adapters.base import BaseMemoryAdapter
+
+
+class NoLateBindingAdapter(BaseMemoryAdapter):
+    """Full Dandelion architecture with late-binding hydration disabled (eager inlining)."""
+
+    def __init__(self) -> None:
+        self.kv: Optional[KVStore] = None
+        self.vec: Optional[VectorStore] = None
+        self.reset()
+
+    @property
+    def name(self) -> str:
+        return "no_late_binding"
+
+    def reset(self) -> None:
+        import dandelion.store_kv
+        dandelion.store_kv._store = None
+        self.kv = KVStore(path=None)
+        dandelion.store_kv._store = self.kv
+        self.vec = VectorStore(in_memory=True)
+
+    def ingest_fact(
+        self,
+        key: str,
+        value: str,
+        timestamp: float,
+        domain: str = "general",
+        source: str = "config_read",
+    ) -> None:
+        self.kv.set_fact(key, value, source=source, confidence=1.0, timestamp=timestamp)
+
+    def ingest_memory(
+        self,
+        event_id: str,
+        template: str,
+        domain: str,
+        timestamp: float,
+        supersedes: Optional[str] = None,
+        source: str = "tool_observed",
+    ) -> str:
+        # Eager resolution at ingestion time
+        def _resolve_eager(m: re.Match) -> str:
+            raw_key = m.group(1).split("@rev:")[0]
+            val = None
+            if domain:
+                val = self.kv.get_fact(f"{domain}.{raw_key}", at_timestamp=timestamp)
+            if val is None:
+                val = self.kv.get_fact(raw_key, at_timestamp=timestamp)
+            return str(val) if val is not None else f"[UNKNOWN: {raw_key}]"
+
+        inlined = re.sub(r"\{\{(?:ref|snapshot):([\w.:\-]+)\}\}", _resolve_eager, template)
+        if domain:
+            inlined = inlined.replace("{{domain}}", domain)
+
+        return self.vec.save_chunk(
+            domain=domain,
+            template=inlined,
+            supersedes=supersedes,
+            source=source,
+            created_at=timestamp,
+            event_id=event_id,
+        )
+
+    def recall(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+        limit: int = 3,
+    ) -> list[dict[str, Any]]:
+        domains = [domain] if domain and not domain.endswith(".*") else None
+        raw_results = self.vec.search_chunks(
+            query=query,
+            domains=domains,
+            limit=limit,
+            use_reverse_index=True,
+            use_lexical_rerank=True,
+        )
+        return [
+            {
+                "id": r["id"],
+                "event_id": r.get("event_id", ""),
+                "text": r["template"],  # Raw static text, no runtime hydration
+                "domain": r["domain"],
+                "score": r.get("score", 0.0),
+                "vector_score": r.get("vector_score", 0.0),
+            }
+            for r in raw_results
+        ]
+
+    def get_fact(
+        self,
+        key: str,
+        domain: Optional[str] = None,
+        at: Optional[float] = None,
+    ) -> Optional[str]:
+        if at is not None:
+            return self.kv.get_fact(key, at_timestamp=at)
+        return self.kv.resolve_ref(key, domain=domain)

benchmarks/adapters/dandelion.py

@@ -0,0 +1,94 @@
+"""Dandelion adapter for DandelionBench evaluation."""
+
+from typing import Any, Optional
+import dandelion.store_kv
+from dandelion.store_kv import KVStore
+from dandelion.store_vector import VectorStore
+from dandelion.hydrator import hydrate_template, pin_snapshots
+from benchmarks.adapters.base import BaseMemoryAdapter
+
+
+class DandelionAdapter(BaseMemoryAdapter):
+    """Full Dandelion adapter with symbolic KV, RRF, snapshots, and reverse index."""
+
+    def __init__(self) -> None:
+        self.kv: Optional[KVStore] = None
+        self.vec: Optional[VectorStore] = None
+        self.reset()
+
+    @property
+    def name(self) -> str:
+        return "dandelion"
+
+    def reset(self) -> None:
+        """Reset internal stores to empty state in memory."""
+        self.kv = KVStore(path=None)
+        dandelion.store_kv._store = self.kv
+        self.vec = VectorStore(in_memory=True)
+
+    def ingest_fact(
+        self,
+        key: str,
+        value: str,
+        timestamp: float,
+        domain: str = "general",
+        source: str = "config_read",
+    ) -> None:
+        self.kv.set_fact(key=key, value=value, source=source, timestamp=timestamp)
+
+    def ingest_memory(
+        self,
+        event_id: str,
+        template: str,
+        domain: str,
+        timestamp: float,
+        supersedes: Optional[str] = None,
+        source: str = "tool_observed",
+    ) -> str:
+        # Pin snapshots at remember-time to lock historical facts
+        pinned = pin_snapshots(template, self.kv.get_current_revision, domain)
+        return self.vec.save_chunk(
+            domain=domain,
+            template=pinned,
+            supersedes=supersedes,
+            source=source,
+            created_at=timestamp,
+            event_id=event_id,
+        )
+
+    def recall(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+        limit: int = 3,
+    ) -> list[dict[str, Any]]:
+        domains = [domain] if domain and not domain.endswith(".*") else None
+        raw_results = self.vec.search_chunks(query=query, domains=domains, limit=limit)
+
+        out = []
+        for r in raw_results:
+            hydrated = hydrate_template(
+                r["template"],
+                kv_resolver=self.kv.resolve_ref,
+                chunk_domain=r["domain"],
+                allow_secrets=False,
+            )
+            out.append({
+                "id": r["id"],
+                "event_id": r.get("event_id", r["id"]),
+                "text": hydrated,
+                "template": r["template"],
+                "domain": r["domain"],
+                "score": r["score"],
+            })
+        return out
+
+    def get_fact(
+        self,
+        key: str,
+        domain: Optional[str] = None,
+        at: Optional[float] = None,
+    ) -> Optional[str]:
+        if at is not None:
+            return self.kv.get_fact(key, at_timestamp=at)
+        return self.kv.resolve_ref(key, domain=domain)

benchmarks/adapters/native/__init__.py

@@ -0,0 +1,31 @@
+"""Native competitor adapters for DandelionBench Track B.
+
+Adapters in this module wrap upstream third-party SDKs (mem0ai, letta-client)
+using pinned library versions, recorded configuration metadata, and dual
+evaluation surfaces (Native Retrieval Surface & Native End-to-End Surface).
+"""
+
+from benchmarks.adapters.native.base import NativeMemoryAdapter
+from benchmarks.adapters.native.dandelion_native import DandelionNativeAdapter
+from benchmarks.adapters.native.dandelion_native_b0 import DandelionNativeB0Adapter
+from benchmarks.adapters.native.dandelion_native_b1 import DandelionNativeB1Adapter
+from benchmarks.adapters.native.dandelion_native_b2 import DandelionNativeB2Adapter
+from benchmarks.adapters.native.dandelion_native_b3 import DandelionNativeB3Adapter
+from benchmarks.adapters.native.dandelion_native_c4 import DandelionNativeAdapterC4
+from benchmarks.adapters.native.dandelion_native_c4_1 import DandelionNativeAdapterC41
+from benchmarks.adapters.native.mem0_native import Mem0NativeAdapter
+from benchmarks.adapters.native.letta_native import LettaNativeAdapter
+
+__all__ = [
+    "NativeMemoryAdapter",
+    "DandelionNativeAdapter",
+    "DandelionNativeB0Adapter",
+    "DandelionNativeB1Adapter",
+    "DandelionNativeB2Adapter",
+    "DandelionNativeB3Adapter",
+    "DandelionNativeAdapterC4",
+    "DandelionNativeAdapterC41",
+    "Mem0NativeAdapter",
+    "LettaNativeAdapter",
+]
+

benchmarks/adapters/native/base.py

@@ -0,0 +1,45 @@
+"""Base interface and telemetry structures for Track B Native Competitor Adapters."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+from benchmarks.adapters.base import BaseMemoryAdapter
+
+
+class NativeMemoryAdapter(BaseMemoryAdapter):
+    """Abstract interface for Track B native third-party memory systems."""
+
+    @property
+    @abstractmethod
+    def package_version(self) -> str:
+        """Upstream library package version (e.g. 'mem0ai==2.0.20')."""
+        pass
+
+    @property
+    @abstractmethod
+    def configuration_metadata(self) -> dict[str, Any]:
+        """Hardware, LLM, embedding model, and storage configuration dictionary."""
+        pass
+
+    @property
+    @abstractmethod
+    def telemetry(self) -> dict[str, Any]:
+        """Runtime execution telemetry (tokens, LLM calls, API calls, cost estimate)."""
+        pass
+
+    @abstractmethod
+    def answer(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """End-to-End answering surface.
+
+        Returns a dictionary containing:
+            - 'answer': str (final generated or synthesized answer)
+            - 'retrieved_context': str
+            - 'context_tokens': int
+            - 'llm_calls': int
+            - 'api_calls': int
+            - 'cost_usd': float
+        """
+        pass

benchmarks/adapters/native/dandelion_native.py

@@ -0,0 +1,164 @@
+"""Dandelion native adapter for DandelionBench Track B."""
+
+from typing import Any, Optional
+import dandelion.store_kv
+from dandelion.store_kv import KVStore
+from dandelion.store_vector import VectorStore
+from dandelion.hydrator import hydrate_template, pin_snapshots
+from benchmarks.adapters.native.base import NativeMemoryAdapter
+
+
+class DandelionNativeAdapter(NativeMemoryAdapter):
+    """Full Dandelion native memory engine with Hub & Spoke architecture."""
+
+    def __init__(self) -> None:
+        self.kv: Optional[KVStore] = None
+        self.vec: Optional[VectorStore] = None
+        self.query_count = 0
+        self.total_tokens = 0
+        self.reset()
+
+    @property
+    def name(self) -> str:
+        return "dandelion_native"
+
+    @property
+    def package_version(self) -> str:
+        return "dandelion-0.2.0 (local)"
+
+    @property
+    def configuration_metadata(self) -> dict[str, Any]:
+        return {
+            "system": "dandelion",
+            "architecture": "hub_and_spoke_symbolic_semantic",
+            "embedding_model": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+            "llm_used": "none (deterministic symbolic hydration)",
+            "vector_store": "qdrant_in_memory",
+            "hydration_policy": "read_time_late_binding",
+            "security_policy": "deny_by_default_secret_masking",
+            "reverse_index": "enabled_exact_match",
+        }
+
+    @property
+    def telemetry(self) -> dict[str, Any]:
+        avg_tok = (self.total_tokens / max(1, self.query_count)) if self.query_count else 0
+        return {
+            "query_count": self.query_count,
+            "llm_calls_total": 0,
+            "llm_calls_per_query": 0.0,
+            "api_calls_total": 0,
+            "api_calls_per_query": 0.0,
+            "cost_total_usd": 0.0,
+            "cost_per_1k_queries_usd": 0.0,
+            "mean_memory_context_tokens": round(avg_tok, 1),
+        }
+
+    def reset(self) -> None:
+        self.kv = KVStore(path=None)
+        dandelion.store_kv._store = self.kv
+        self.vec = VectorStore(in_memory=True)
+        self.query_count = 0
+        self.total_tokens = 0
+
+    def ingest_fact(
+        self,
+        key: str,
+        value: str,
+        timestamp: float,
+        domain: str = "general",
+        source: str = "config_read",
+    ) -> None:
+        self.kv.set_fact(key=key, value=value, source=source, timestamp=timestamp)
+
+    def ingest_memory(
+        self,
+        event_id: str,
+        template: str,
+        domain: str,
+        timestamp: float,
+        supersedes: Optional[str] = None,
+        source: str = "tool_observed",
+    ) -> str:
+        pinned = pin_snapshots(template, self.kv.get_current_revision, domain)
+        return self.vec.save_chunk(
+            domain=domain,
+            template=pinned,
+            supersedes=supersedes,
+            source=source,
+            created_at=timestamp,
+            event_id=event_id,
+        )
+
+    def recall(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+        limit: int = 3,
+    ) -> list[dict[str, Any]]:
+        domains = [domain] if domain else None
+        raw_results = self.vec.search_chunks(query=query, domains=domains, limit=limit)
+        hydrated: list[dict[str, Any]] = []
+
+        for r in raw_results:
+            text = hydrate_template(
+                text=r["template"],
+                kv_resolver=self.kv.resolve_ref,
+                chunk_domain=r.get("domain", "general"),
+                allow_secrets=False,
+            )
+            hydrated.append({
+                "id": r["id"],
+                "event_id": r.get("event_id", r["id"]),
+                "text": text,
+                "domain": r.get("domain", "general"),
+                "score": r.get("score", 0.0),
+                "vector_score": r.get("vector_score", 0.0),
+                "has_fact": r.get("has_fact", False),
+                "is_historical": "{{ref:" in r["template"] and "@rev:" in r["template"],
+            })
+
+        self.query_count += 1
+        tok_sum = sum(len(h["text"].split()) for h in hydrated)
+        self.total_tokens += tok_sum
+
+        return hydrated
+
+    def answer(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """End-to-end answering surface using secure context envelope."""
+        candidates = self.recall(query=query, domain=domain, limit=3)
+        if not candidates:
+            return {
+                "answer": "I have no memory regarding this topic.",
+                "retrieved_context": "",
+                "context_tokens": 0,
+                "llm_calls": 0,
+                "api_calls": 0,
+                "cost_usd": 0.0,
+            }
+
+        context_str = "\n".join(f"[{c['event_id']}] {c['text']}" for c in candidates)
+        context_tokens = len(context_str.split())
+
+        # Construct answering payload
+        return {
+            "answer": context_str,
+            "retrieved_context": context_str,
+            "context_tokens": context_tokens,
+            "llm_calls": 0,
+            "api_calls": 0,
+            "cost_usd": 0.0,
+        }
+
+    def get_fact(
+        self,
+        key: str,
+        domain: Optional[str] = None,
+        at: Optional[float] = None,
+    ) -> Optional[str]:
+        if at is not None:
+            return self.kv.get_fact(key, at_timestamp=at)
+        return self.kv.resolve_ref(key, domain=domain)