AbstractMemory 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

abstractmemory/__init__.py

@@ -1,41 +1,15 @@
-"""
-AbstractMemory - PLACEHOLDER PROJECT
-
-This is a placeholder package to reserve the 'AbstractMemory' name on PyPI.
-
-AbstractMemory will be a memory system designed to transform stateless LLMs 
-into stateful LLMs, with primary integration planned for AbstractLLM.
-
-The actual implementation is currently part of AbstractLLM and will be 
-modularized into this separate package in the future to enable:
-- Cleaner separation of concerns
-- Better evolution and maintenance over time
-- Reusability across different LLM frameworks
-
-WARNING: This is a placeholder. Do not use in production.
-"""
-
-__version__ = "0.0.1"
-__author__ = "AbstractMemory Team"
-__email__ = "contact@example.com"
-
-# Placeholder exception to prevent accidental usage
-class PlaceholderError(Exception):
-    """Raised when attempting to use placeholder functionality."""
-    pass
-
-def placeholder_warning():
-    """
-    Warn users that this is a placeholder package.
-    
-    Raises:
-        PlaceholderError: Always raised to prevent usage
-    """
-    raise PlaceholderError(
-        "AbstractMemory is currently a placeholder package. "
-        "The actual memory system implementation is part of AbstractLLM. "
-        "This package reserves the name for future modularization."
-    )
-
-# Make it clear this is a placeholder
-__all__ = ["placeholder_warning", "PlaceholderError", "__version__"]
+from .models import TripleAssertion
+from .embeddings import AbstractGatewayTextEmbedder, TextEmbedder
+from .in_memory_store import InMemoryTripleStore
+from .lancedb_store import LanceDBTripleStore
+from .store import TripleStore, TripleQuery
+
+__all__ = [
+    "AbstractGatewayTextEmbedder",
+    "InMemoryTripleStore",
+    "LanceDBTripleStore",
+    "TextEmbedder",
+    "TripleAssertion",
+    "TripleQuery",
+    "TripleStore",
+]

abstractmemory/embeddings.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+from typing import List, Protocol, Sequence
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+class TextEmbedder(Protocol):
+    """Minimal text embedding interface used by AbstractMemory stores."""
+
+    def embed_texts(self, texts: Sequence[str]) -> List[List[float]]: ...
+
+
+class AbstractGatewayTextEmbedder:
+    """Text embedder that calls AbstractGateway's embeddings API.
+
+    AbstractMemory intentionally does not depend on AbstractCore directly. The gateway is responsible for:
+    - selecting the embedding provider/model (singleton per gateway instance)
+    - generating embeddings via AbstractRuntime+AbstractCore integration
+    - enforcing a stable embedding space
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth_token: str | None = None,
+        endpoint_path: str = "/api/gateway/embeddings",
+        timeout_s: float = 30.0,
+    ) -> None:
+        root = str(base_url or "").strip().rstrip("/")
+        if not root:
+            raise ValueError("base_url is required")
+        path = str(endpoint_path or "").strip()
+        if not path.startswith("/"):
+            path = "/" + path
+        self._url = root + path
+        self._timeout_s = float(timeout_s)
+        self._headers = {"Content-Type": "application/json"}
+        if isinstance(auth_token, str) and auth_token.strip():
+            self._headers["Authorization"] = f"Bearer {auth_token.strip()}"
+
+    def embed_texts(self, texts: Sequence[str]) -> List[List[float]]:
+        items = [str(t or "") for t in texts]
+        payload = {"input": items}
+        req = Request(
+            self._url,
+            data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+            headers=dict(self._headers),
+            method="POST",
+        )
+        try:
+            with urlopen(req, timeout=self._timeout_s) as resp:
+                raw = resp.read().decode("utf-8")
+        except HTTPError as e:
+            detail = ""
+            try:
+                detail = e.read().decode("utf-8")
+            except Exception:
+                detail = ""
+            hint = ""
+            if int(getattr(e, "code", 0) or 0) == 401:
+                hint = (
+                    " (Set `ABSTRACTGATEWAY_AUTH_TOKEN` / `ABSTRACTFLOW_GATEWAY_AUTH_TOKEN` "
+                    "for the caller process, or pass a Bearer token to the gateway embeddings endpoint.)"
+                )
+            raise RuntimeError(f"Gateway embeddings HTTP {e.code}: {detail or e.reason}{hint}") from e
+        except URLError as e:
+            raise RuntimeError(f"Gateway embeddings request failed: {e}") from e
+
+        try:
+            data = json.loads(raw)
+        except Exception as e:
+            raise RuntimeError(f"Gateway embeddings returned invalid JSON: {e}") from e
+
+        rows = data.get("data") if isinstance(data, dict) else None
+        if not isinstance(rows, list):
+            raise RuntimeError("Gateway embeddings response missing 'data' list")
+
+        # Preserve order via `index` when present.
+        parsed: list[tuple[int, List[float]]] = []
+        for i, row_any in enumerate(rows):
+            row = row_any if isinstance(row_any, dict) else {}
+            idx = row.get("index")
+            try:
+                index = int(idx) if idx is not None else i
+            except Exception:
+                index = i
+            emb = row.get("embedding")
+            if not isinstance(emb, list):
+                raise RuntimeError("Gateway embeddings response contains non-list embedding")
+            parsed.append((index, [float(x) for x in emb]))
+
+        parsed.sort(key=lambda t: t[0])
+        return [v for _, v in parsed]

abstractmemory/in_memory_store.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import math
+import uuid
+from typing import Any, Iterable, List, Optional, Sequence
+
+from .embeddings import TextEmbedder
+from .models import TripleAssertion, normalize_term
+from .store import TripleQuery
+
+
+def _canonical_text(a: TripleAssertion) -> str:
+    base = f"{a.subject} {a.predicate} {a.object}".strip()
+    attrs = a.attributes if isinstance(a.attributes, dict) else {}
+
+    parts: list[str] = [base]
+    st = attrs.get("subject_type")
+    ot = attrs.get("object_type")
+    if isinstance(st, str) and st.strip():
+        parts.append(f"subject_type: {st.strip()}")
+    if isinstance(ot, str) and ot.strip():
+        parts.append(f"object_type: {ot.strip()}")
+
+    eq = attrs.get("evidence_quote")
+    if isinstance(eq, str) and eq.strip():
+        parts.append(f"evidence: {eq.strip()}")
+
+    ctx = attrs.get("original_context")
+    if isinstance(ctx, str) and ctx.strip():
+        ctx2 = ctx.strip()
+        if len(ctx2) > 400:
+            ctx2 = ctx2[:400] + "…"
+        parts.append(f"context: {ctx2}")
+
+    return "\n".join(parts)
+
+
+def _cosine(a: Sequence[float], b: Sequence[float]) -> float:
+    # Defensive: handle empty vectors.
+    if not a or not b:
+        return 0.0
+    n = min(len(a), len(b))
+    dot = 0.0
+    na = 0.0
+    nb = 0.0
+    for i in range(n):
+        ax = float(a[i])
+        bx = float(b[i])
+        dot += ax * bx
+        na += ax * ax
+        nb += bx * bx
+    if na <= 0.0 or nb <= 0.0:
+        return 0.0
+    return dot / (math.sqrt(na) * math.sqrt(nb))
+
+
+class InMemoryTripleStore:
+    """A dependency-free triple store (best-effort).
+
+    Notes:
+    - Intended for tests/dev and hosts without LanceDB installed.
+    - Append-only: updates are represented as new assertions.
+    - Vector search is optional and stores vectors in-memory only.
+    """
+
+    def __init__(
+        self,
+        *,
+        embedder: Optional[TextEmbedder] = None,
+        vector_column: str = "vector",
+    ) -> None:
+        self._embedder = embedder
+        self._vector_column = str(vector_column or "vector")
+        self._rows: list[dict[str, Any]] = []
+
+    def close(self) -> None:
+        return None
+
+    def add(self, assertions: Iterable[TripleAssertion]) -> List[str]:
+        pending: list[TripleAssertion] = [a for a in assertions]
+        if not pending:
+            return []
+
+        vectors: Optional[List[List[float]]] = None
+        if self._embedder is not None:
+            vectors = self._embedder.embed_texts([_canonical_text(a) for a in pending])
+
+        ids: list[str] = []
+        for i, a in enumerate(pending):
+            assertion_id = str(uuid.uuid4())
+            ids.append(assertion_id)
+            row: dict[str, Any] = {"assertion_id": assertion_id, "assertion": a}
+            if vectors is not None and i < len(vectors):
+                row[self._vector_column] = vectors[i]
+            self._rows.append(row)
+        return ids
+
+    def query(self, q: TripleQuery) -> List[TripleAssertion]:
+        raw_limit = int(q.limit) if isinstance(q.limit, int) else 100
+        limit: Optional[int]
+        if raw_limit <= 0:
+            limit = None
+        else:
+            limit = max(1, raw_limit)
+
+        def _match(a: TripleAssertion) -> bool:
+            if q.subject and normalize_term(a.subject) != normalize_term(q.subject):
+                return False
+            if q.predicate and normalize_term(a.predicate) != normalize_term(q.predicate):
+                return False
+            if q.object and normalize_term(a.object) != normalize_term(q.object):
+                return False
+            if q.scope and a.scope != q.scope:
+                return False
+            if q.owner_id and (a.owner_id or "") != q.owner_id:
+                return False
+            if q.since and (a.observed_at or "") < q.since:
+                return False
+            if q.until and (a.observed_at or "") > q.until:
+                return False
+            if q.active_at:
+                at = q.active_at
+                if a.valid_from and a.valid_from > at:
+                    return False
+                if a.valid_until and a.valid_until <= at:
+                    return False
+            return True
+
+        rows = [r for r in self._rows if isinstance(r, dict) and isinstance(r.get("assertion"), TripleAssertion)]
+        filtered: list[dict[str, Any]] = []
+        for r in rows:
+            a = r["assertion"]
+            if _match(a):
+                filtered.append(r)
+
+        query_vector: Optional[Sequence[float]] = None
+        if q.query_vector:
+            query_vector = q.query_vector
+        elif q.query_text:
+            if self._embedder is None:
+                raise ValueError("query_text requires a configured embedder (vector search); keyword fallback is disabled")
+            query_vector = self._embedder.embed_texts([q.query_text])[0]
+
+        if query_vector is not None:
+            ranked: list[tuple[float, TripleAssertion]] = []
+            for r in filtered:
+                v = r.get(q.vector_column or self._vector_column)
+                if not isinstance(v, list):
+                    continue
+                try:
+                    score = _cosine(query_vector, v)
+                except Exception:
+                    score = 0.0
+                if q.min_score is not None and score < float(q.min_score):
+                    continue
+                ranked.append((score, r["assertion"]))
+            ranked.sort(key=lambda t: t[0], reverse=True)
+
+            out: list[TripleAssertion] = []
+            for score, a in (ranked if limit is None else ranked[:limit]):
+                attrs = dict(a.attributes) if isinstance(a.attributes, dict) else {}
+                retrieval = attrs.get("_retrieval") if isinstance(attrs.get("_retrieval"), dict) else {}
+                retrieval2 = dict(retrieval)
+                retrieval2["score"] = float(score)
+                retrieval2.setdefault("metric", "cosine")
+                attrs["_retrieval"] = retrieval2
+                out.append(
+                    TripleAssertion(
+                        subject=a.subject,
+                        predicate=a.predicate,
+                        object=a.object,
+                        scope=a.scope,
+                        owner_id=a.owner_id,
+                        observed_at=a.observed_at,
+                        valid_from=a.valid_from,
+                        valid_until=a.valid_until,
+                        confidence=a.confidence,
+                        provenance=dict(a.provenance),
+                        attributes=attrs,
+                    )
+                )
+            return out
+
+        out: list[TripleAssertion] = [r["assertion"] for r in filtered]
+        out.sort(key=lambda a: a.observed_at or "", reverse=(str(q.order).lower() != "asc"))
+        return out if limit is None else out[:limit]

abstractmemory/lancedb_store.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence
+
+from .embeddings import TextEmbedder
+from .models import TripleAssertion, normalize_term
+from .store import TripleQuery
+
+
+def _import_lancedb():
+    try:
+        import lancedb  # type: ignore
+
+        return lancedb
+    except Exception as e:  # pragma: no cover
+        raise ImportError(
+            "LanceDB support requires `lancedb` (and its dependencies). "
+            "Install it in your environment (offline/local install is fine), e.g. `pip install lancedb`."
+        ) from e
+
+
+def _escape_sql_string(value: str) -> str:
+    # LanceDB uses SQL-like filter strings; escape single quotes.
+    return str(value).replace("'", "''")
+
+
+def _build_where_clause(q: TripleQuery) -> str:
+    parts: list[str] = []
+
+    if q.subject:
+        parts.append(f"lower(subject) = '{_escape_sql_string(normalize_term(q.subject))}'")
+    if q.predicate:
+        parts.append(f"lower(predicate) = '{_escape_sql_string(normalize_term(q.predicate))}'")
+    if q.object:
+        parts.append(f"lower(object) = '{_escape_sql_string(normalize_term(q.object))}'")
+    if q.scope:
+        parts.append(f"scope = '{_escape_sql_string(q.scope)}'")
+    if q.owner_id:
+        parts.append(f"owner_id = '{_escape_sql_string(q.owner_id)}'")
+
+    if q.since:
+        parts.append(f"observed_at >= '{_escape_sql_string(q.since)}'")
+    if q.until:
+        parts.append(f"observed_at <= '{_escape_sql_string(q.until)}'")
+
+    if q.active_at:
+        at = _escape_sql_string(q.active_at)
+        parts.append(f"(valid_from IS NULL OR valid_from <= '{at}')")
+        parts.append(f"(valid_until IS NULL OR valid_until > '{at}')")
+
+    return " AND ".join(parts)
+
+
+def _canonical_text(a: TripleAssertion) -> str:
+    # Stable, information-rich representation for embedding retrieval.
+    #
+    # Why include more than "s p o":
+    # - semantic queries often refer to details that aren't present in the triple surface form
+    # - extractor-provided evidence/context improves retrieval selectivity without requiring
+    #   a separate episodic document store in v0
+    base = f"{a.subject} {a.predicate} {a.object}".strip()
+    attrs = a.attributes if isinstance(a.attributes, dict) else {}
+
+    parts: list[str] = [base]
+    st = attrs.get("subject_type")
+    ot = attrs.get("object_type")
+    if isinstance(st, str) and st.strip():
+        parts.append(f"subject_type: {st.strip()}")
+    if isinstance(ot, str) and ot.strip():
+        parts.append(f"object_type: {ot.strip()}")
+
+    eq = attrs.get("evidence_quote")
+    if isinstance(eq, str) and eq.strip():
+        parts.append(f"evidence: {eq.strip()}")
+
+    ctx = attrs.get("original_context")
+    if isinstance(ctx, str) and ctx.strip():
+        ctx2 = ctx.strip()
+        if len(ctx2) > 400:
+            ctx2 = ctx2[:400] + "…"
+        parts.append(f"context: {ctx2}")
+
+    return "\n".join(parts)
+
+
+def _loads_json(raw: object) -> dict:
+    if not isinstance(raw, str) or not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+        return parsed if isinstance(parsed, dict) else {}
+    except Exception:
+        return {}
+
+
+class LanceDBTripleStore:
+    """LanceDB-backed append-only triple store with optional vector search.
+
+    Notes:
+    - Append-only: updates are represented as new assertions.
+    - Vector search is optional and requires `embedder` (for query_text) or query_vector.
+    """
+
+    def __init__(
+        self,
+        uri: str | Path,
+        *,
+        table_name: str = "triple_assertions",
+        embedder: Optional[TextEmbedder] = None,
+        vector_column: str = "vector",
+    ):
+        self._lancedb = _import_lancedb()
+        self._db = self._lancedb.connect(str(uri))
+        self._table_name = str(table_name)
+        self._vector_column = str(vector_column or "vector")
+        self._embedder = embedder
+
+        self._table = None
+        try:
+            # `table_names()` is deprecated upstream but is stable and sufficient for local stores.
+            if self._table_name in set(self._db.table_names()):
+                self._table = self._db.open_table(self._table_name)
+        except Exception:
+            self._table = None
+
+    def close(self) -> None:
+        # LanceDB tables/connections are managed by the library; nothing required here.
+        return None
+
+    def add(self, assertions: Iterable[TripleAssertion]) -> List[str]:
+        rows: list[dict[str, Any]] = []
+        ids: List[str] = []
+        pending: List[TripleAssertion] = []
+
+        for a in assertions:
+            pending.append(a)
+
+        if not pending:
+            return []
+
+        # Always store a canonical text column (useful for debugging and future indexing).
+        texts: List[str] = [_canonical_text(a) for a in pending]
+        vectors: Optional[List[List[float]]] = None
+        if self._embedder is not None:
+            vectors = self._embedder.embed_texts(texts)
+
+        for idx, a in enumerate(pending):
+            assertion_id = str(uuid.uuid4())
+            ids.append(assertion_id)
+            row: Dict[str, Any] = {
+                "assertion_id": assertion_id,
+                "subject": a.subject,
+                "predicate": a.predicate,
+                "object": a.object,
+                "scope": a.scope,
+                "owner_id": a.owner_id,
+                "observed_at": a.observed_at,
+                "valid_from": a.valid_from,
+                "valid_until": a.valid_until,
+                "confidence": a.confidence,
+                "provenance_json": json.dumps(a.provenance, ensure_ascii=False, separators=(",", ":")),
+                "attributes_json": json.dumps(a.attributes, ensure_ascii=False, separators=(",", ":")),
+                "text": texts[idx],
+            }
+
+            if vectors is not None and idx < len(vectors):
+                row[self._vector_column] = vectors[idx]
+
+            # Keep JSON compact (omit nulls).
+            row = {k: v for k, v in row.items() if v is not None}
+            rows.append(row)
+
+        if self._table is None:
+            # Create on first insert so we can infer vector dimensionality from real data.
+            self._table = self._db.create_table(self._table_name, data=rows, mode="create")
+        else:
+            self._table.add(rows)
+        return ids
+
+    def query(self, q: TripleQuery) -> List[TripleAssertion]:
+        if self._table is None:
+            return []
+
+        raw_limit = int(q.limit) if isinstance(q.limit, int) else 100
+        limit: Optional[int]
+        if raw_limit <= 0:
+            limit = None
+        else:
+            limit = max(1, raw_limit)
+
+        where = _build_where_clause(q)
+
+        query_vector: Optional[Sequence[float]] = None
+        if q.query_vector:
+            query_vector = q.query_vector
+        elif q.query_text:
+            if self._embedder is None:
+                raise ValueError("query_text requires a configured embedder (vector search); keyword fallback is disabled")
+            query_vector = self._embedder.embed_texts([q.query_text])[0]
+
+        qb = None
+        if query_vector is not None:
+            # Use cosine metric so `min_score` can be expressed as cosine similarity.
+            qb = self._table.search(query_vector, vector_column_name=q.vector_column or self._vector_column).metric("cosine")
+        if qb is None:
+            qb = self._table.search()
+
+        if where:
+            qb = qb.where(where)
+
+        if query_vector is None:
+            # LanceDB does not currently expose an order_by API on query builders. For deterministic
+            # observed_at ordering (and correct limit semantics), fetch all matching rows then sort
+            # in Python and apply the limit after sorting.
+            rows = qb.to_list()
+        else:
+            rows = qb.limit(limit).to_list() if limit is not None else qb.to_list()
+
+        out: List[TripleAssertion] = []
+        for r in rows:
+            if not isinstance(r, dict):
+                continue
+            provenance = _loads_json(r.get("provenance_json"))
+            attributes = _loads_json(r.get("attributes_json"))
+
+            # Attach retrieval metadata for semantic queries.
+            # LanceDB returns `_distance` for vector searches; with metric=cosine, similarity = 1 - distance.
+            if query_vector is not None:
+                dist_raw = r.get("_distance")
+                dist: Optional[float] = None
+                try:
+                    dist = float(dist_raw) if dist_raw is not None else None
+                except Exception:
+                    dist = None
+                score: Optional[float] = None
+                if dist is not None:
+                    score = 1.0 - dist
+
+                if q.min_score is not None and score is not None and score < float(q.min_score):
+                    continue
+
+                retrieval = attributes.get("_retrieval") if isinstance(attributes.get("_retrieval"), dict) else {}
+                retrieval2 = dict(retrieval)
+                if score is not None:
+                    retrieval2["score"] = score
+                if dist is not None:
+                    retrieval2["distance"] = dist
+                retrieval2.setdefault("metric", "cosine")
+                attributes = dict(attributes)
+                attributes["_retrieval"] = retrieval2
+            out.append(
+                TripleAssertion(
+                    subject=str(r.get("subject") or ""),
+                    predicate=str(r.get("predicate") or ""),
+                    object=str(r.get("object") or ""),
+                    scope=str(r.get("scope") or "run"),
+                    owner_id=str(r.get("owner_id")) if r.get("owner_id") is not None else None,
+                    observed_at=str(r.get("observed_at") or ""),
+                    valid_from=str(r.get("valid_from")) if r.get("valid_from") is not None else None,
+                    valid_until=str(r.get("valid_until")) if r.get("valid_until") is not None else None,
+                    confidence=r.get("confidence") if isinstance(r.get("confidence"), (int, float)) else None,
+                    provenance=provenance,
+                    attributes=attributes,
+                )
+            )
+
+        # For non-semantic queries, keep compatibility with SQLite semantics: order by observed_at.
+        # For semantic queries, LanceDB already returns similarity-ranked results.
+        if query_vector is None:
+            out.sort(key=lambda a: a.observed_at or "", reverse=(str(q.order).lower() != "asc"))
+        return out if limit is None else out[:limit]

abstractmemory/models.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+def utc_now_iso_seconds() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def canonicalize_term(value: str) -> str:
+    """Canonicalize a KG term for stable matching.
+
+    Policy (v0):
+    - trim surrounding whitespace
+    - lowercase (avoids missed matches due to casing drift)
+    """
+    return str(value or "").strip().lower()
+
+
+def normalize_term(value: str) -> str:
+    """Normalize a KG term for case-insensitive matching (query-time)."""
+    # `canonicalize_term` already lowercases; keep this for clarity/compatibility.
+    return canonicalize_term(value).lower()
+
+
+@dataclass(frozen=True)
+class TripleAssertion:
+    """An append-only semantic assertion with temporal and provenance metadata."""
+
+    subject: str
+    predicate: str
+    object: str
+    scope: str = "run"  # run|session|global
+    owner_id: Optional[str] = None  # scope owner identifier (e.g. run_id, session_memory_*, global_memory)
+    observed_at: str = field(default_factory=utc_now_iso_seconds)
+
+    valid_from: Optional[str] = None
+    valid_until: Optional[str] = None
+    confidence: Optional[float] = None
+
+    provenance: Dict[str, Any] = field(default_factory=dict)
+    attributes: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # Canonicalize KG terms (trim + lower) for stable matching.
+        object.__setattr__(self, "subject", canonicalize_term(self.subject))
+        object.__setattr__(self, "predicate", canonicalize_term(self.predicate))
+        object.__setattr__(self, "object", canonicalize_term(self.object))
+
+        # Keep scope canonical (it is part of the partitioning key).
+        object.__setattr__(self, "scope", str(self.scope or "").strip().lower() or "run")
+
+        # Defensive trimming for timestamps/ids without altering semantics.
+        if isinstance(self.owner_id, str):
+            oid = self.owner_id.strip()
+            object.__setattr__(self, "owner_id", oid if oid else None)
+        object.__setattr__(self, "observed_at", str(self.observed_at or "").strip() or utc_now_iso_seconds())
+        if isinstance(self.valid_from, str):
+            vf = self.valid_from.strip()
+            object.__setattr__(self, "valid_from", vf if vf else None)
+        if isinstance(self.valid_until, str):
+            vu = self.valid_until.strip()
+            object.__setattr__(self, "valid_until", vu if vu else None)
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {
+            "subject": self.subject,
+            "predicate": self.predicate,
+            "object": self.object,
+            "scope": self.scope,
+            "owner_id": self.owner_id,
+            "observed_at": self.observed_at,
+            "valid_from": self.valid_from,
+            "valid_until": self.valid_until,
+            "confidence": self.confidence,
+            "provenance": dict(self.provenance),
+            "attributes": dict(self.attributes),
+        }
+        # Keep JSON compact (omit nulls).
+        return {k: v for k, v in out.items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TripleAssertion":
+        if not isinstance(data, dict):
+            raise TypeError("TripleAssertion.from_dict expects a dict")
+
+        subject = data.get("subject")
+        predicate = data.get("predicate")
+        obj = data.get("object")
+        if not isinstance(subject, str) or not subject.strip():
+            raise ValueError("TripleAssertion.subject must be a non-empty string")
+        if not isinstance(predicate, str) or not predicate.strip():
+            raise ValueError("TripleAssertion.predicate must be a non-empty string")
+        if not isinstance(obj, str) or not obj.strip():
+            raise ValueError("TripleAssertion.object must be a non-empty string")
+
+        scope = data.get("scope") if isinstance(data.get("scope"), str) else "run"
+        owner_id = data.get("owner_id") if isinstance(data.get("owner_id"), str) else None
+        observed_at = data.get("observed_at") if isinstance(data.get("observed_at"), str) else utc_now_iso_seconds()
+
+        provenance = data.get("provenance") if isinstance(data.get("provenance"), dict) else {}
+        attributes = data.get("attributes") if isinstance(data.get("attributes"), dict) else {}
+
+        confidence_raw = data.get("confidence")
+        confidence: Optional[float] = None
+        if confidence_raw is not None:
+            try:
+                confidence = float(confidence_raw)
+            except Exception:
+                confidence = None
+
+        return cls(
+            subject=subject,
+            predicate=predicate,
+            object=obj,
+            scope=scope,
+            owner_id=owner_id.strip() if isinstance(owner_id, str) and owner_id.strip() else None,
+            observed_at=observed_at.strip() or utc_now_iso_seconds(),
+            valid_from=data.get("valid_from") if isinstance(data.get("valid_from"), str) else None,
+            valid_until=data.get("valid_until") if isinstance(data.get("valid_until"), str) else None,
+            confidence=confidence,
+            provenance=dict(provenance),
+            attributes=dict(attributes),
+        )

abstractmemory/store.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Protocol
+
+from .models import TripleAssertion, canonicalize_term
+
+
+@dataclass(frozen=True)
+class TripleQuery:
+    subject: Optional[str] = None
+    predicate: Optional[str] = None
+    object: Optional[str] = None
+    scope: Optional[str] = None  # run|session|global
+    owner_id: Optional[str] = None  # owner identifier within the selected scope
+
+    since: Optional[str] = None  # observed_at >= since
+    until: Optional[str] = None  # observed_at <= until
+    active_at: Optional[str] = None  # valid_from/valid_until window intersection
+
+    # Optional semantic search:
+    # - query_text requires a store-configured embedder
+    # - query_vector bypasses embedding generation
+    query_text: Optional[str] = None
+    query_vector: Optional[List[float]] = None
+    vector_column: str = "vector"
+    min_score: Optional[float] = None  # cosine similarity threshold (semantic queries)
+
+    limit: int = 100
+    order: str = "desc"  # asc|desc by observed_at
+
+    def __post_init__(self) -> None:
+        # Canonicalize KG terms once (trim + lower; stable exact match).
+        if isinstance(self.subject, str):
+            s = canonicalize_term(self.subject)
+            object.__setattr__(self, "subject", s if s else None)
+        if isinstance(self.predicate, str):
+            p = canonicalize_term(self.predicate)
+            object.__setattr__(self, "predicate", p if p else None)
+        if isinstance(self.object, str):
+            o = canonicalize_term(self.object)
+            object.__setattr__(self, "object", o if o else None)
+
+        if isinstance(self.scope, str):
+            sc = str(self.scope or "").strip().lower()
+            object.__setattr__(self, "scope", sc if sc else None)
+
+        # Keep metadata trimmed without changing semantics.
+        if isinstance(self.owner_id, str):
+            oid = self.owner_id.strip()
+            object.__setattr__(self, "owner_id", oid if oid else None)
+        if isinstance(self.since, str):
+            s = self.since.strip()
+            object.__setattr__(self, "since", s if s else None)
+        if isinstance(self.until, str):
+            u = self.until.strip()
+            object.__setattr__(self, "until", u if u else None)
+        if isinstance(self.active_at, str):
+            a = self.active_at.strip()
+            object.__setattr__(self, "active_at", a if a else None)
+
+        # For semantic retrieval, normalize text input once.
+        if isinstance(self.query_text, str):
+            qt = str(self.query_text or "").strip()
+            object.__setattr__(self, "query_text", qt if qt else None)
+
+        if isinstance(self.vector_column, str):
+            vc = self.vector_column.strip() or "vector"
+            object.__setattr__(self, "vector_column", vc)
+
+        if self.min_score is not None:
+            try:
+                ms = float(self.min_score)
+            except Exception:
+                ms = None
+            if ms is None or not (ms == ms):  # NaN
+                object.__setattr__(self, "min_score", None)
+            else:
+                object.__setattr__(self, "min_score", ms)
+
+        if isinstance(self.order, str):
+            object.__setattr__(self, "order", self.order.strip().lower() or "desc")
+
+
+class TripleStore(Protocol):
+    def add(self, assertions: Iterable[TripleAssertion]) -> List[str]: ...
+
+    def query(self, q: TripleQuery) -> List[TripleAssertion]: ...
+
+    def close(self) -> None: ...

abstractmemory-0.0.2.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: AbstractMemory
+Version: 0.0.2
+Summary: AbstractMemory: temporal, provenance-aware semantic memory primitives for AbstractFramework.
+Project-URL: AbstractFramework (monorepo), https://github.com/lpalbou/abstractframework
+Author: Laurent-Philippe Albou
+License: MIT
+License-File: LICENSE
+Keywords: agents,knowledge-graph,memory,temporal,triples
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: lancedb; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: lancedb
+Requires-Dist: lancedb; extra == 'lancedb'
+Description-Content-Type: text/markdown
+
+# AbstractMemory (early / WIP)
+
+AbstractMemory is a small Python library for **append-only, temporal, provenance-aware triple assertions** with a **deterministic query API** and optional **vector/semantic retrieval**.
+
+## Status
+- This package is still early: API and storage details may change.
+- Implemented today: `TripleAssertion`, `TripleQuery`, `InMemoryTripleStore`, `LanceDBTripleStore`, `AbstractGatewayTextEmbedder`.
+  - Source of truth for exports: [`src/abstractmemory/__init__.py`](src/abstractmemory/__init__.py)
+- Requires Python 3.10+ (see [`pyproject.toml`](pyproject.toml))
+
+## Install
+
+From PyPI (when published):
+
+```bash
+python -m pip install AbstractMemory
+```
+
+Optional persistent backend + vector search:
+
+```bash
+python -m pip install "AbstractMemory[lancedb]"
+```
+
+Note: the distribution name is `AbstractMemory` (pip is case-insensitive). The import name is `abstractmemory`.
+
+From source (recommended for this monorepo package):
+
+```bash
+python -m pip install -e .
+```
+
+Optional persistent backend + vector search:
+
+```bash
+python -m pip install -e ".[lancedb]"
+```
+
+## Quick example
+
+```python
+from abstractmemory import InMemoryTripleStore, TripleAssertion, TripleQuery
+
+store = InMemoryTripleStore()
+store.add(
+    [
+        TripleAssertion(
+            subject="Scrooge",
+            predicate="related_to",
+            object="Christmas",
+            scope="session",
+            owner_id="sess-1",
+            provenance={"span_id": "span_123"},
+        )
+    ]
+)
+
+hits = store.query(TripleQuery(subject="scrooge", scope="session", owner_id="sess-1"))
+assert hits[0].object == "christmas"  # terms are canonicalized (trim + lowercase)
+```
+
+## Documentation
+
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- FAQ: [`docs/faq.md`](docs/faq.md)
+- Architecture (with diagrams): [`docs/architecture.md`](docs/architecture.md)
+- Stores/backends: [`docs/stores.md`](docs/stores.md)
+- API reference: [`docs/api.md`](docs/api.md)
+- Development: [`docs/development.md`](docs/development.md)
+
+## Project
+
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+- License: [`LICENSE`](LICENSE)
+- Acknowledgments: [`ACKNOWLEDGMENTS.md`](ACKNOWLEDGMENTS.md)
+
+## Design principles (v0)
+
+- **Triples-first** representation with temporal fields (`observed_at`, `valid_from`, `valid_until`).
+  - Implemented in `TripleAssertion`: [`src/abstractmemory/models.py`](src/abstractmemory/models.py)
+- **Append-only**: represent updates by adding a new assertion with fresh provenance.
+  - Implemented by both stores: [`src/abstractmemory/in_memory_store.py`](src/abstractmemory/in_memory_store.py), [`src/abstractmemory/lancedb_store.py`](src/abstractmemory/lancedb_store.py)
+- **No direct AbstractCore dependency**: embeddings can be obtained via an AbstractGateway HTTP API.
+  - Implemented by `AbstractGatewayTextEmbedder`: [`src/abstractmemory/embeddings.py`](src/abstractmemory/embeddings.py)

abstractmemory-0.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+abstractmemory/__init__.py,sha256=diBIm5YRxFmn-rKSu6CVW6rZGEuiDFWi1mwK8Jdwj84,425
+abstractmemory/embeddings.py,sha256=QpBDNNTr1TVzhZoSPoLNa5XASAcQfUvAFKrHlEdo9Zw,3741
+abstractmemory/in_memory_store.py,sha256=ZkQ7KNznVkJqHgzZDAg_OCDtZi1DUJnCFkqxWGtRCEo,6861
+abstractmemory/lancedb_store.py,sha256=4D6hiabFjbB65VLyIjX9CA57NyvMU9p3GMGdXr3s4vY,10650
+abstractmemory/models.py,sha256=35dAm8ofIZVzn6mtd28SfRYesHL40AJ3Z3UfZHWUsvs,5335
+abstractmemory/store.py,sha256=rG_DtBL_InnTgxybfzmLH6R6GdvVeEE7dwnI1g-ksu0,3534
+abstractmemory-0.0.2.dist-info/METADATA,sha256=sWmn-qhXOAkcNqZChs7g7xftb-gAhdIEXUCJf0wvNSw,4091
+abstractmemory-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+abstractmemory-0.0.2.dist-info/licenses/LICENSE,sha256=7t9ARuV3s_QVhJahnkFBnX_E5GPLW8BE9geplO1CGko,1079
+abstractmemory-0.0.2.dist-info/RECORD,,

{abstractmemory-0.0.1.dist-info → abstractmemory-0.0.2.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

{abstractmemory-0.0.1.dist-info → abstractmemory-0.0.2.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 AbstractMemory Team
+Copyright (c) 2024 Laurent-Philippe Albou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

abstractmemory-0.0.1.dist-info/METADATA

@@ -1,94 +0,0 @@
-Metadata-Version: 2.4
-Name: AbstractMemory
-Version: 0.0.1
-Summary: PLACEHOLDER: Memory system for transforming stateless LLMs into stateful LLMs - primarily designed for AbstractLLM integration
-Author-email: AbstractMemory Team <contact@example.com>
-Maintainer-email: AbstractMemory Team <contact@example.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/abstractmemory/abstractmemory
-Project-URL: Documentation, https://github.com/abstractmemory/abstractmemory#readme
-Project-URL: Repository, https://github.com/abstractmemory/abstractmemory
-Project-URL: Bug Reports, https://github.com/abstractmemory/abstractmemory/issues
-Keywords: llm,memory,stateful,ai,placeholder
-Classifier: Development Status :: 1 - Planning
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# AbstractMemory - PLACEHOLDER PROJECT
-
-⚠️ **WARNING: This is a placeholder package** ⚠️
-
-## Overview
-
-AbstractMemory is a placeholder package that reserves the name on PyPI for a future memory system designed to transform stateless LLMs into stateful LLMs.
-
-## Current Status
-
-**This package is currently a PLACEHOLDER and should NOT be used in production.**
-
-The actual memory system implementation is currently integrated within the AbstractLLM project. This separate package exists to:
-
-1. **Reserve the PyPI name** for future modularization
-2. **Enable clean separation of concerns** when the code is extracted from AbstractLLM
-3. **Facilitate better evolution and maintenance** of the memory system as a standalone component
-4. **Allow reusability** across different LLM frameworks in the future
-
-## Future Vision
-
-AbstractMemory will provide:
-
-- **Stateful Memory Management**: Transform stateless LLMs into stateful systems
-- **Primary AbstractLLM Integration**: Seamless integration with AbstractLLM
-- **Modular Architecture**: Clean separation from core LLM functionality
-- **Extensible Framework**: Support for various memory strategies and backends
-
-## Installation
-
-```bash
-pip install AbstractMemory
-```
-
-## Usage
-
-Currently, attempting to use any functionality will raise a `PlaceholderError`:
-
-```python
-import abstractmemory
-
-# This will raise PlaceholderError
-abstractmemory.placeholder_warning()
-```
-
-## Development Timeline
-
-The actual implementation will be extracted and modularized from AbstractLLM when:
-- The AbstractLLM memory system reaches sufficient maturity
-- Clean interfaces are established
-- Comprehensive testing framework is in place
-
-## Contributing
-
-This is a placeholder project. For memory-related contributions, please refer to the AbstractLLM project until the code is modularized.
-
-## License
-
-MIT License - See LICENSE file for details.
-
-## Contact
-
-For questions about future development plans, please refer to the AbstractLLM project documentation.
-
----
-
-**Remember: This is a placeholder. The real implementation is coming soon!**

abstractmemory-0.0.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-abstractmemory/__init__.py,sha256=56ZUm3WI5FFZRBoPwwAC4Zj0lK1vglE7RTj3a6yAFFY,1362
-abstractmemory-0.0.1.dist-info/licenses/LICENSE,sha256=lPn7wpbMAgGyv2OAhgHtW_bZHq4Hnm7Gx28-8m82Nt4,1076
-abstractmemory-0.0.1.dist-info/METADATA,sha256=2kDPyAPoE1e7XGR0_zvRWYp2FmbkHDJRN3vqv17m2XA,3420
-abstractmemory-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-abstractmemory-0.0.1.dist-info/top_level.txt,sha256=ALpTfrLlzRBy55aam5M8YuOi-4i_shfsq1DcgTR6_NQ,15
-abstractmemory-0.0.1.dist-info/RECORD,,

abstractmemory-0.0.1.dist-info/top_level.txt

@@ -1 +0,0 @@
-abstractmemory