grafomem 0.2.0__py3-none-any.whl

aml/__init__.py

@@ -0,0 +1,3 @@
+"""GRAFOMEM — agent-memory benchmark framework."""
+
+__version__ = "0.1.3"

aml/adapter_check.py

@@ -0,0 +1,136 @@
+"""
+GRAFOMEM adapter pre-flight checker.
+
+    grafomem check -b my_module:MyBackend
+
+Quick structural validation BEFORE running the full conformance suite:
+checks Protocol compliance, method signatures, capability coherence,
+and basic round-trip. Fails fast with actionable error messages.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+
+def check_adapter(cls: type) -> list[str]:
+    """Run pre-flight checks against a backend class. Returns a list of errors.
+    Empty list means the adapter is structurally conformant."""
+    errors: list[str] = []
+
+    # 1. Check required methods exist
+    required_methods = ["capabilities", "write", "retrieve", "delete",
+                         "supersede", "audit", "flush"]
+    for method in required_methods:
+        if not hasattr(cls, method):
+            errors.append(f"Missing required method: {method}()")
+        elif not callable(getattr(cls, method)):
+            errors.append(f"{method} exists but is not callable")
+
+    if errors:
+        return errors  # can't proceed without basic methods
+
+    # 2. Try to instantiate
+    instance = None
+    try:
+        # Check if __init__ needs arguments beyond self
+        sig = inspect.signature(cls.__init__)
+        params = [p for p in sig.parameters.values()
+                  if p.name != "self" and p.default is inspect.Parameter.empty]
+        if params:
+            errors.append(
+                f"Constructor requires arguments: {[p.name for p in params]}. "
+                f"The conformance suite needs a zero-arg factory. Consider using "
+                f"a wrapper lambda: lambda: MyBackend(arg1, arg2)"
+            )
+            return errors
+        instance = cls()
+    except Exception as e:
+        errors.append(f"Failed to instantiate {cls.__name__}(): {e}")
+        return errors
+
+    # 3. Check capabilities() returns set[Capability]
+    try:
+        from aml.backends.interface import Capability
+        caps = instance.capabilities()
+        if not isinstance(caps, set):
+            errors.append(f"capabilities() returned {type(caps).__name__}, expected set")
+        else:
+            for c in caps:
+                if not isinstance(c, Capability):
+                    errors.append(f"capabilities() contains {c!r} which is not a Capability enum member")
+    except Exception as e:
+        errors.append(f"capabilities() raised: {e}")
+
+    # 4. Check Protocol compliance
+    try:
+        from aml.backends.interface import MemoryBackend
+        if not isinstance(instance, MemoryBackend):
+            errors.append(
+                f"{cls.__name__} does not satisfy the MemoryBackend Protocol. "
+                f"Check method signatures match the Protocol definition."
+            )
+    except Exception as e:
+        errors.append(f"Protocol check failed: {e}")
+
+    # 5. Basic round-trip: write + retrieve
+    try:
+        from aml.backends.interface import WriteOptions, RetrieveOptions
+        ref = instance.write("test content", WriteOptions())
+        if ref is None:
+            errors.append("write() returned None; must return a MemoryRef")
+        instance.flush()
+        mems = instance.retrieve("test", RetrieveOptions(budget_tokens=1024))
+        if not isinstance(mems, list):
+            errors.append(f"retrieve() returned {type(mems).__name__}, expected list")
+    except Exception as e:
+        errors.append(f"Basic write/retrieve round-trip failed: {e}")
+
+    return errors
+
+
+def print_check(cls: type) -> bool:
+    """Run and print pre-flight check results. Returns True if all pass."""
+    print(f"GRAFOMEM adapter check — {cls.__name__}\n")
+
+    errors = check_adapter(cls)
+
+    if not errors:
+        # Also show declared capabilities
+        try:
+            instance = cls()
+            caps = instance.capabilities()
+            print(f"✓ Protocol compliance         OK")
+            print(f"✓ Method signatures            OK")
+            print(f"✓ Write/retrieve round-trip    OK")
+            print(f"✓ Declared capabilities:       {{{', '.join(sorted(c.value for c in caps))}}}")
+            print(f"\nAdapter is structurally conformant. Run `grafomem conformance` for full suite.")
+        except Exception:
+            print(f"✓ Structural checks passed")
+        return True
+    else:
+        for e in errors:
+            print(f"✗ {e}")
+        print(f"\n{len(errors)} error(s). Fix these before running the conformance suite.")
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Smoke
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    from aml.backends.gmp_reference import GMPReferenceBackend
+    from aml.backends.vector_only import _stub_embedder, VectorOnlyBackend
+    from aml.backends.persistence import PersistenceBackend
+
+    for cls_factory in [
+        lambda: PersistenceBackend,
+        lambda: type("BadBackend", (), {}),  # deliberately broken
+    ]:
+        cls = cls_factory()
+        print_check(cls)
+        print()
+
+    print("✓ Adapter check module smoke green.")

aml/backends/__init__.py

@@ -0,0 +1 @@
+"""Backend adapters + the MemoryBackend interface contract."""

aml/backends/bi_temporal.py

@@ -0,0 +1,225 @@
+"""
+GRAFOMEM bi_temporal reference adapter.
+
+Same pinned BGE-small vector store as vector_only / supersession_chain, but it
+keeps a valid-time interval [valid_from, valid_until) per version and resolves
+retrieve(as_of=t) to the version valid at t. This is a strict superset of
+supersession_chain:
+
+  - as_of = None  -> current query: candidates are open-interval heads
+                     (valid_until is None) -> identical to supersession_chain.
+  - as_of = t     -> historical query: candidates are versions whose interval
+                     contains t (valid_from <= t < valid_until) -> one version
+                     per chain, the slice that was valid then.
+
+It learns each interval the way the trace defines it (w2.py): a version's
+valid_from arrives on write/supersede via WriteOptions; its valid_until is the
+NEXT version's valid_from, which the harness hands to supersede() as the new
+version's valid_from. So supersede(old, new) closes old at opts.valid_from and
+reconstructs the oracle's contiguous windows exactly, with no extra plumbing.
+
+Why it matters: historical (as_of) queries are N/A for every non-BI_TEMPORAL
+backend (the harness skips them, E1). This adapter is the only one that can
+answer them, so on W2 those queries flip from unscored to scored — the second
+capability axis. Claims {BI_TEMPORAL, SUPERSESSION_CHAIN, AUDIT}; it must claim
+SUPERSESSION_CHAIN so the harness dispatches supersede() and the intervals get
+closed. Requires grafomem[backends].
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import datetime, timezone
+
+import numpy as np
+
+from aml.backends.interface import (
+    Capability,
+    CapabilityNotSupported,
+    Memory,
+    RetrieveOptions,
+    WriteOptions,
+)
+from aml.backends.vector_only import REFERENCE_MODEL, EmbedFn, _default_embedder
+
+__grafomem_interface__ = "0.1.1"
+
+
+class BiTemporalVectorBackend:
+    """BGE vector store with per-version valid-time intervals + as_of resolution."""
+
+    __grafomem_interface__ = "0.1.1"
+    __grafomem_adapter_metadata__ = {
+        "underlying_system": "reference",
+        "embedding_model": REFERENCE_MODEL,
+        "vector_store": "numpy-bruteforce-cosine-exact",
+        "temporal_policy": "valid-time intervals [valid_from, valid_until); "
+                           "as_of resolves to the version valid at t",
+        "notes": "Same embedder as vector_only/supersession_chain; the "
+                 "difference is the BI_TEMPORAL capability, not the model.",
+    }
+
+    def __init__(self, embed_fn: EmbedFn | None = None) -> None:
+        self._embed_fn = embed_fn
+        self._store: dict[int, Memory] = {}
+        self._vec: dict[int, np.ndarray] = {}
+        self._vfrom: dict[int, datetime | None] = {}
+        self._vuntil: dict[int, datetime | None] = {}   # None = open (head)
+        self._next = 0
+
+    def _embed(self, texts: list[str]) -> np.ndarray:
+        if self._embed_fn is None:
+            self._embed_fn = _default_embedder()
+        return self._embed_fn(texts)
+
+    def capabilities(self) -> set[Capability]:
+        return {Capability.BI_TEMPORAL, Capability.SUPERSESSION_CHAIN,
+                Capability.AUDIT}
+
+    def write(self, content: str, options: WriteOptions) -> int:
+        if options.tenant_id is not None:
+            raise CapabilityNotSupported(Capability.MULTI_TENANT, "write")
+        if options.signing_key is not None:
+            raise CapabilityNotSupported(
+                Capability.CRYPTOGRAPHIC_PROVENANCE, "write")
+        ref = self._next
+        self._next += 1
+        self._store[ref] = Memory(
+            ref=ref, content=content,
+            written_at=datetime.now(tz=timezone.utc),
+            metadata=dict(options.metadata),
+        )
+        self._vec[ref] = self._embed([content])[0]
+        self._vfrom[ref] = options.valid_from   # None for non-temporal workloads
+        self._vuntil[ref] = None                 # open until superseded
+        return ref
+
+    def supersede(self, old_ref, content: str, options: WriteOptions) -> int:
+        # New version's valid_from == predecessor's valid_until (contiguous, w2.py).
+        new_ref = self.write(content, options)
+        if old_ref in self._store:
+            self._vuntil[old_ref] = options.valid_from
+            self._store[old_ref].superseded_by = new_ref
+        return new_ref
+
+    def delete(self, ref) -> bool:
+        # No deletes in W1-W6; a bi-temporal tombstone would close the interval
+        # with no successor, but no workload exercises it, so we don't claim it.
+        raise CapabilityNotSupported(Capability.HARD_DELETE, "delete")
+
+    def _valid_at(self, ref: int, t: datetime | None) -> bool:
+        if t is None:                            # current: open intervals only
+            return self._vuntil[ref] is None
+        vf, vu = self._vfrom[ref], self._vuntil[ref]
+        return (vf is None or vf <= t) and (vu is None or t < vu)
+
+    def retrieve(self, query: str, options: RetrieveOptions) -> list[Memory]:
+        if options.tenant_id is not None:
+            raise CapabilityNotSupported(Capability.MULTI_TENANT, "retrieve")
+        t = options.as_of
+        refs = [r for r in self._store if self._valid_at(r, t)]
+        if not refs:
+            return []
+        qv = self._embed([query])[0]
+        mat = np.stack([self._vec[r] for r in refs])
+        sims = mat @ qv
+        order = sorted(range(len(refs)),
+                       key=lambda i: (-float(sims[i]), refs[i]))
+        out: list[Memory] = []
+        used = 0
+        for i in order:
+            m = self._store[refs[i]]
+            cost = len(m.content)
+            if used + cost > options.budget_tokens:
+                break
+            out.append(m)
+            used += cost
+        return out
+
+    def audit(self) -> Iterator[Memory]:
+        return iter(list(self._store.values()))
+
+    def flush(self) -> None:
+        pass
+
+
+# ============================================================================
+# Smoke check — run `python -m aml.backends.bi_temporal`
+# ============================================================================
+
+if __name__ == "__main__":
+    from datetime import timedelta
+
+    from aml.backends.interface import MemoryBackend
+    from aml.backends.vector_only import VectorOnlyBackend, _stub_embedder
+    from aml.eval.harness import run_trace
+    from aml.generator.trace import Difficulty
+    from aml.generator.workloads.w2 import generate_w2
+
+    print("GRAFOMEM bi_temporal.py — valid-time as_of resolution (STUB embedder)\n")
+
+    b = BiTemporalVectorBackend(embed_fn=_stub_embedder())
+
+    assert isinstance(b, MemoryBackend)
+    assert b.capabilities() == {Capability.BI_TEMPORAL,
+                                Capability.SUPERSESSION_CHAIN, Capability.AUDIT}
+    print("✓ Protocol + capabilities            ({BI_TEMPORAL, SUPERSESSION_CHAIN, AUDIT})")
+
+    # Hand-built chain with explicit contiguous windows:
+    #   Rome  [t0, t1)   Milan [t1, t2)   Turin [t2, open)
+    t0 = datetime(2026, 1, 1, tzinfo=timezone.utc)
+    t1 = t0 + timedelta(days=30)
+    t2 = t0 + timedelta(days=60)
+    r0 = b.write("Aria lives in Rome", WriteOptions(valid_from=t0))
+    r1 = b.supersede(r0, "Aria lives in Milan", WriteOptions(valid_from=t1))
+    r2 = b.supersede(r1, "Aria lives in Turin", WriteOptions(valid_from=t2))
+    b.flush()
+
+    q = "Where does Aria live?"
+    now = [m.content for m in b.retrieve(q, RetrieveOptions(as_of=None))]
+    assert now == ["Aria lives in Turin"], now
+    print("✓ as_of=None -> head                 (Turin)")
+
+    # Time-travel: midpoint of each window resolves to that version.
+    for label, t, expected in (
+        ("inside Rome window ", t0 + timedelta(days=15), "Aria lives in Rome"),
+        ("inside Milan window", t1 + timedelta(days=15), "Aria lives in Milan"),
+        ("inside Turin window", t2 + timedelta(days=15), "Aria lives in Turin"),
+    ):
+        got = [m.content for m in b.retrieve(q, RetrieveOptions(as_of=t))]
+        assert got == [expected], f"{label}: {got}"
+    print("✓ as_of=t -> version valid at t      (Rome / Milan / Turin by window)")
+
+    audited = {m.content: m for m in b.audit()}
+    assert len(audited) == 3 and audited["Aria lives in Milan"].superseded_by == r2
+    print("✓ audit() yields full history        (3 versions, superseded_by linked)")
+
+    for op, call in (
+        ("tenant", lambda: b.retrieve("x", RetrieveOptions(tenant_id="t"))),
+        ("delete", lambda: b.delete(r0)),
+    ):
+        try:
+            call()
+        except CapabilityNotSupported:
+            pass
+        else:
+            raise AssertionError(f"{op}: expected CapabilityNotSupported")
+    print("✓ Capability guards                  (tenant -> no MULTI_TENANT; delete -> no HARD_DELETE)")
+
+    # Reclamation on a real W2 hard trace, through the actual harness:
+    # bi_temporal answers every query (n_na=0); vector_only skips all historical.
+    tr = generate_w2(seed=0, difficulty=Difficulty.HARD)
+    bt_run = run_trace(BiTemporalVectorBackend(embed_fn=_stub_embedder()),
+                       tr, budget_tokens=512)
+    vec_run = run_trace(VectorOnlyBackend(embed_fn=_stub_embedder()),
+                        tr, budget_tokens=512)
+    assert bt_run.n_na == 0, f"bi_temporal should answer all queries, n_na={bt_run.n_na}"
+    assert vec_run.n_na > 0, "vector_only should skip historical queries"
+    reclaimed = vec_run.n_na
+    answered = len(bt_run.per_query)
+    print(f"✓ Reclaims historical queries        (bi_temporal n_na=0 / {answered} scored; "
+          f"vector_only n_na={reclaimed})")
+
+    print(f"\nAll bi_temporal smoke checks green. {reclaimed} historical queries that are "
+          f"N/A for every\nother backend are now answerable. Wire into run_w2 for the "
+          f"current/historical split.")

aml/backends/bounded_vector.py

@@ -0,0 +1,197 @@
+"""
+GRAFOMEM bounded_vector reference adapter.
+
+Same pinned BGE-small vector store as vector_only, but with a fixed capacity:
+on write, once the store exceeds `capacity`, the OLDEST memory is evicted
+(FIFO — a recency window). This is the realistic "context window" model an agent
+lives inside: bounded footprint and bounded per-query scan cost, at the price of
+forgetting anything older than the window.
+
+On W4 (Long-Horizon Dependencies) this produces the recall-vs-footprint
+tradeoff: a query for a fact d facts back succeeds only if d < capacity (else it
+was evicted), so recall cliffs at d = capacity — a structural fact, independent
+of the embedder — while footprint and scan cost plateau at `capacity` instead of
+growing linearly with the horizon like an unbounded store.
+
+Claims {AUDIT}: no temporal, supersession, or hard-delete semantics. Eviction is
+capacity management, not a HARD_DELETE (the caller did not request removal), and
+is reflected in audit() — which exposes exactly the retained window.
+Requires grafomem[backends].
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterator
+from datetime import datetime, timezone
+
+import numpy as np
+
+from aml.backends.interface import (
+    Capability,
+    CapabilityNotSupported,
+    Memory,
+    RetrieveOptions,
+    WriteOptions,
+)
+from aml.backends.vector_only import REFERENCE_MODEL, EmbedFn, _default_embedder
+
+__grafomem_interface__ = "0.1.1"
+
+DEFAULT_CAPACITY = 64
+
+
+class BoundedVectorBackend:
+    """BGE vector store with a fixed-capacity recency window (FIFO eviction)."""
+
+    __grafomem_interface__ = "0.1.1"
+
+    def __init__(self, capacity: int = DEFAULT_CAPACITY,
+                 embed_fn: EmbedFn | None = None) -> None:
+        if capacity < 1:
+            raise ValueError("capacity must be >= 1")
+        self.capacity = capacity
+        self._embed_fn = embed_fn
+        self._store: dict[int, Memory] = {}
+        self._vec: dict[int, np.ndarray] = {}
+        self._order: deque[int] = deque()      # FIFO eviction order
+        self._next = 0
+        self._evicted = 0                       # bookkeeping (not retrievable)
+
+    __grafomem_adapter_metadata__ = {
+        "underlying_system": "reference",
+        "embedding_model": REFERENCE_MODEL,
+        "vector_store": "numpy-bruteforce-cosine-exact",
+        "retention_policy": "fixed-capacity recency window, FIFO eviction",
+    }
+
+    def _embed(self, texts: list[str]) -> np.ndarray:
+        if self._embed_fn is None:
+            self._embed_fn = _default_embedder()
+        return self._embed_fn(texts)
+
+    def capabilities(self) -> set[Capability]:
+        return {Capability.AUDIT}
+
+    def write(self, content: str, options: WriteOptions) -> int:
+        if options.tenant_id is not None:
+            raise CapabilityNotSupported(Capability.MULTI_TENANT, "write")
+        if options.signing_key is not None:
+            raise CapabilityNotSupported(
+                Capability.CRYPTOGRAPHIC_PROVENANCE, "write")
+        ref = self._next
+        self._next += 1
+        self._store[ref] = Memory(
+            ref=ref, content=content,
+            written_at=datetime.now(tz=timezone.utc),
+            metadata=dict(options.metadata),
+        )
+        self._vec[ref] = self._embed([content])[0]
+        self._order.append(ref)
+        while len(self._order) > self.capacity:        # evict oldest
+            old = self._order.popleft()
+            del self._store[old]
+            del self._vec[old]
+            self._evicted += 1
+        return ref
+
+    def supersede(self, old_ref, content: str, options: WriteOptions) -> int:
+        raise CapabilityNotSupported(Capability.SUPERSESSION_CHAIN, "supersede")
+
+    def delete(self, ref) -> bool:
+        raise CapabilityNotSupported(Capability.HARD_DELETE, "delete")
+
+    def retrieve(self, query: str, options: RetrieveOptions) -> list[Memory]:
+        if options.as_of is not None:
+            raise CapabilityNotSupported(Capability.BI_TEMPORAL, "retrieve")
+        if options.tenant_id is not None:
+            raise CapabilityNotSupported(Capability.MULTI_TENANT, "retrieve")
+        refs = list(self._store.keys())               # retained window only
+        if not refs:
+            return []
+        qv = self._embed([query])[0]
+        mat = np.stack([self._vec[r] for r in refs])
+        sims = mat @ qv
+        order = sorted(range(len(refs)),
+                       key=lambda i: (-float(sims[i]), refs[i]))
+        out: list[Memory] = []
+        used = 0
+        for i in order:
+            m = self._store[refs[i]]
+            cost = len(m.content)
+            if used + cost > options.budget_tokens:
+                break
+            out.append(m)
+            used += cost
+        return out
+
+    def audit(self) -> Iterator[Memory]:
+        return iter(list(self._store.values()))        # the retained window
+
+    def flush(self) -> None:
+        pass
+
+
+# ============================================================================
+# Smoke check — run `python -m aml.backends.bounded_vector`
+# ============================================================================
+
+if __name__ == "__main__":
+    from aml.backends.interface import MemoryBackend
+    from aml.backends.vector_only import _stub_embedder
+
+    print("GRAFOMEM bounded_vector.py — fixed-capacity recency window (STUB)\n")
+
+    K = 10
+    b = BoundedVectorBackend(capacity=K, embed_fn=_stub_embedder())
+
+    assert isinstance(b, MemoryBackend)
+    assert b.capabilities() == {Capability.AUDIT}
+    print(f"✓ Protocol + capabilities            ({{AUDIT}}, capacity={K})")
+
+    # Write 100 facts; only the last K survive.
+    refs = [b.write(f"Entity{i:03d} lives in City{i:03d}", WriteOptions())
+            for i in range(100)]
+    b.flush()
+    retained = {m.ref for m in b.audit()}
+    assert len(retained) == K, f"expected {K} retained, got {len(retained)}"
+    assert retained == set(refs[-K:]), "retained window is not the last K (FIFO)"
+    print(f"✓ FIFO eviction                      (100 written, last {K} retained)")
+
+    # A recent fact is retrievable; an evicted (old) one is not.
+    recent = b.retrieve("Where does Entity099 live?", RetrieveOptions(budget_tokens=512))
+    assert any("Entity099" in m.content for m in recent), "recent fact missing"
+    old = b.retrieve("Where does Entity001 live?", RetrieveOptions(budget_tokens=512))
+    assert not any("Entity001" in m.content for m in old), "evicted fact leaked"
+    print("✓ Recall cliff                       (recent retrievable; evicted absent)")
+
+    # Footprint = retained count = scan cost, plateaued at capacity.
+    assert len(list(b.audit())) == K
+    print(f"✓ Footprint plateau                  (audit/scan = {K}, not 100)")
+
+    # Capability guards.
+    for op, call in (
+        ("supersede", lambda: b.supersede(refs[-1], "x", WriteOptions())),
+        ("delete", lambda: b.delete(refs[-1])),
+        ("as_of", lambda: b.retrieve("x", RetrieveOptions(
+            as_of=datetime.now(tz=timezone.utc)))),
+    ):
+        try:
+            call()
+        except CapabilityNotSupported:
+            pass
+        else:
+            raise AssertionError(f"{op}: expected CapabilityNotSupported")
+    print("✓ Capability guards                  (supersede/delete/as_of refused)")
+
+    # Determinism: same writes -> same retained set + ranking.
+    b2 = BoundedVectorBackend(capacity=K, embed_fn=_stub_embedder())
+    for i in range(100):
+        b2.write(f"Entity{i:03d} lives in City{i:03d}", WriteOptions())
+    r1 = [m.ref for m in b.retrieve("Where does Entity095 live?", RetrieveOptions(budget_tokens=512))]
+    r2 = [m.ref for m in b2.retrieve("Where does Entity095 live?", RetrieveOptions(budget_tokens=512))]
+    assert r1 == r2
+    print("✓ Deterministic                      (same writes -> same window + ranking)")
+
+    print("\nAll bounded_vector smoke checks green. Next: run_w4 "
+          "(recall-by-distance + footprint vs unbounded).")