atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/embeddings/__init__.py

@@ -0,0 +1,16 @@
+"""Optional local embeddings — gated behind the ``embeddings`` extra.
+
+Install with ``pip install 'atomicmemory[embeddings]'`` to pull in
+``sentence-transformers``. Without the extra, importing
+:class:`SentenceTransformersAdapter` raises a clear actionable error;
+the protocol :class:`EmbeddingGenerator` itself is always available.
+"""
+
+from atomicmemory.embeddings.base import EmbeddingGenerator, EmbeddingResult
+from atomicmemory.embeddings.sentence_transformers import SentenceTransformersAdapter
+
+__all__ = [
+    "EmbeddingGenerator",
+    "EmbeddingResult",
+    "SentenceTransformersAdapter",
+]

atomicmemory/embeddings/base.py

@@ -0,0 +1,39 @@
+"""Embedding adapter protocol + result type.
+
+Port of `atomicmemory-sdk/src/embedding/embedding-generator.ts`'s
+public surface. Implementations live in sibling modules
+(``sentence_transformers.py``, future others).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class EmbeddingResult:
+    """A single embedding with provenance metadata."""
+
+    embedding: list[float]
+    dimensions: int
+    model: str
+    processing_time_seconds: float
+    provider: str
+    cache_hit: bool = False
+
+
+@runtime_checkable
+class EmbeddingGenerator(Protocol):
+    """Common contract for any embedding backend."""
+
+    @property
+    def dimensions(self) -> int: ...
+
+    @property
+    def model_name(self) -> str: ...
+
+    def embed(self, text: str) -> EmbeddingResult: ...
+
+    def embed_batch(self, texts: Sequence[str]) -> list[EmbeddingResult]: ...

atomicmemory/embeddings/sentence_transformers.py

@@ -0,0 +1,104 @@
+"""Sentence-Transformers adapter — local embeddings via the ``embeddings`` extra.
+
+Port of the WASM/transformers.js path in
+`atomicmemory-sdk/src/embedding/transformers-adapter.ts`. Default
+model is ``sentence-transformers/all-MiniLM-L6-v2`` (384 dims), matching
+the TS SDK's ``Xenova/all-MiniLM-L6-v2``.
+
+Lazy-imports ``sentence_transformers`` at construction time. If the
+extra was not installed, a clear actionable error is raised.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from atomicmemory.core.errors import ConfigError
+from atomicmemory.embeddings.base import EmbeddingResult
+
+if TYPE_CHECKING:
+    from sentence_transformers import SentenceTransformer
+
+DEFAULT_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+DEFAULT_DIMENSIONS = 384
+
+
+def _import_sentence_transformers() -> Any:
+    try:
+        import sentence_transformers
+    except ImportError as exc:
+        raise ConfigError(
+            "atomicmemory[embeddings] is not installed. "
+            "Install the optional extra: pip install 'atomicmemory[embeddings]'.",
+            context={"missing_dependency": "sentence_transformers"},
+        ) from exc
+    return sentence_transformers
+
+
+class SentenceTransformersAdapter:
+    """Local embedding adapter backed by ``sentence-transformers``.
+
+    Loads the model lazily on first use; subsequent calls reuse the
+    same in-memory instance.
+    """
+
+    def __init__(
+        self,
+        *,
+        model_name: str = DEFAULT_MODEL,
+        dimensions: int = DEFAULT_DIMENSIONS,
+        normalize: bool = True,
+        device: str | None = None,
+    ) -> None:
+        self._model_name = model_name
+        self._dimensions = dimensions
+        self._normalize = normalize
+        self._device = device
+        self._model: SentenceTransformer | None = None
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+    @property
+    def dimensions(self) -> int:
+        return self._dimensions
+
+    def _ensure_model(self) -> Any:
+        if self._model is None:
+            module = _import_sentence_transformers()
+            self._model = module.SentenceTransformer(self._model_name, device=self._device)
+        return self._model
+
+    def embed(self, text: str) -> EmbeddingResult:
+        model = self._ensure_model()
+        start = time.monotonic()
+        vector = model.encode(text, normalize_embeddings=self._normalize)
+        return EmbeddingResult(
+            embedding=[float(x) for x in vector.tolist()],
+            dimensions=self._dimensions,
+            model=self._model_name,
+            processing_time_seconds=time.monotonic() - start,
+            provider="sentence-transformers",
+        )
+
+    def embed_batch(self, texts: Sequence[str]) -> list[EmbeddingResult]:
+        if not texts:
+            return []
+        model = self._ensure_model()
+        start = time.monotonic()
+        vectors = model.encode(list(texts), normalize_embeddings=self._normalize)
+        elapsed = time.monotonic() - start
+        per_item = elapsed / len(texts) if texts else 0.0
+        return [
+            EmbeddingResult(
+                embedding=[float(x) for x in v.tolist()],
+                dimensions=self._dimensions,
+                model=self._model_name,
+                processing_time_seconds=per_item,
+                provider="sentence-transformers",
+            )
+            for v in vectors
+        ]

atomicmemory/kv_cache/__init__.py

@@ -0,0 +1,17 @@
+"""Local key/value cache adapters — in-memory + SQLite.
+
+Port of the kv-cache layer in `atomicmemory-sdk/src/kv-cache/`. The
+``StorageAdapter`` Protocol is the contract every adapter satisfies;
+two concrete implementations ship with the SDK:
+
+- :class:`MemoryStorageAdapter` — pure-Python dict-backed store, useful
+  for tests and short-lived agent runs.
+- :class:`SQLiteStorageAdapter` — stdlib ``sqlite3``-backed store with
+  TTL support, suitable for local persistence in CLIs and notebooks.
+"""
+
+from atomicmemory.kv_cache.adapter import StorageAdapter
+from atomicmemory.kv_cache.memory_storage import MemoryStorageAdapter
+from atomicmemory.kv_cache.sqlite_storage import SQLiteStorageAdapter
+
+__all__ = ["MemoryStorageAdapter", "SQLiteStorageAdapter", "StorageAdapter"]

atomicmemory/kv_cache/adapter.py

@@ -0,0 +1,50 @@
+"""StorageAdapter protocol — common contract for local key/value caches.
+
+Port of `atomicmemory-sdk/src/kv-cache/storage-adapter.ts`. The methods
+mirror the TS surface, with snake_case naming.
+
+Encryption is **not** implemented in any shipped adapter. The
+``encrypt`` keyword on :meth:`set` exists for forward compatibility
+with future ciphered backends, but concrete adapters MUST fail closed:
+when a caller passes ``encrypt=True``, a conformant implementation
+raises :class:`atomicmemory.core.errors.ConfigError` rather than
+silently storing plaintext under a flag that signals confidentiality.
+:class:`MemoryStorageAdapter` and :class:`SQLiteStorageAdapter` follow
+that contract today; new adapters must too until real encryption lands.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class StorageAdapter(Protocol):
+    """Common storage contract — get/set/delete/keys + TTL + size."""
+
+    def initialize(self) -> None: ...
+
+    def close(self) -> None: ...
+
+    def get(self, key: str) -> Any | None: ...
+
+    def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl_seconds: float | None = None,
+        encrypt: bool = False,
+    ) -> None: ...
+
+    def delete(self, key: str) -> bool: ...
+
+    def has(self, key: str) -> bool: ...
+
+    def keys(self) -> list[str]: ...
+
+    def size(self) -> int: ...
+
+    def clear(self) -> None: ...

atomicmemory/kv_cache/memory_storage.py

@@ -0,0 +1,98 @@
+"""In-memory key/value cache adapter.
+
+Port of `atomicmemory-sdk/src/kv-cache/memory-storage.ts`. Threaded
+access is **not** safe; if you need concurrent writers, wrap your own
+lock or use the SQLite adapter.
+
+The TTL clock is injectable: pass ``clock=`` to use a deterministic
+callable in tests. Defaults to :func:`time.monotonic` so wall-clock
+changes don't affect in-memory expiry.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from atomicmemory.core.errors import ConfigError
+
+
+@dataclass
+class _MemoryItem:
+    value: Any
+    created_at: float
+    expires_at: float | None
+
+
+class MemoryStorageAdapter:
+    """Pure-Python in-memory store with TTL support."""
+
+    def __init__(self, *, clock: Callable[[], float] | None = None) -> None:
+        self._data: dict[str, _MemoryItem] = {}
+        self._clock: Callable[[], float] = clock or time.monotonic
+
+    def initialize(self) -> None:
+        """No-op; the dict is ready to use as soon as the adapter is constructed."""
+
+    def close(self) -> None:
+        self._data.clear()
+
+    def get(self, key: str) -> Any | None:
+        item = self._data.get(key)
+        if item is None:
+            return None
+        if item.expires_at is not None and self._clock() >= item.expires_at:
+            del self._data[key]
+            return None
+        return item.value
+
+    def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl_seconds: float | None = None,
+        encrypt: bool = False,
+    ) -> None:
+        if encrypt:
+            raise ConfigError(
+                "MemoryStorageAdapter does not implement encryption; "
+                "passing encrypt=True would silently store plaintext. "
+                "Omit the flag or use a backend that implements ciphered storage.",
+                context={"adapter": "MemoryStorageAdapter"},
+            )
+        now = self._clock()
+        self._data[key] = _MemoryItem(
+            value=value,
+            created_at=now,
+            expires_at=now + ttl_seconds if ttl_seconds is not None else None,
+        )
+
+    def delete(self, key: str) -> bool:
+        return self._data.pop(key, None) is not None
+
+    def has(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def keys(self) -> list[str]:
+        # Materialize the list and drop expired entries on the way through
+        # so callers don't see stale ids.
+        live: list[str] = []
+        now = self._clock()
+        expired: list[str] = []
+        for key, item in self._data.items():
+            if item.expires_at is not None and now >= item.expires_at:
+                expired.append(key)
+            else:
+                live.append(key)
+        for key in expired:
+            del self._data[key]
+        return live
+
+    def size(self) -> int:
+        return len(self.keys())
+
+    def clear(self) -> None:
+        self._data.clear()

atomicmemory/kv_cache/sqlite_storage.py

@@ -0,0 +1,122 @@
+"""SQLite-backed storage adapter.
+
+Stdlib-only — no SQLAlchemy. Stores values as JSON text. TTL is enforced
+on read (lazy eviction); a periodic ``vacuum_expired`` helper is
+provided for callers that want eager cleanup.
+
+The TTL clock defaults to :func:`time.time` (wall-clock epoch seconds)
+so persisted ``expires_at`` values remain meaningful across process
+restarts. Tests can inject a deterministic ``clock=`` callable.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from collections.abc import Callable
+from typing import Any
+
+from atomicmemory.core.errors import ConfigError
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS atomicmemory_kv (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    created_at REAL NOT NULL,
+    expires_at REAL
+);
+"""
+
+
+class SQLiteStorageAdapter:
+    """SQLite-backed key/value store with optional TTL."""
+
+    def __init__(
+        self,
+        db_path: str = ":memory:",
+        *,
+        clock: Callable[[], float] | None = None,
+    ) -> None:
+        self._db_path = db_path
+        self._conn: sqlite3.Connection | None = None
+        self._clock: Callable[[], float] = clock or time.time
+
+    def initialize(self) -> None:
+        if self._conn is None:
+            self._conn = sqlite3.connect(self._db_path, isolation_level=None)
+            self._conn.execute(_SCHEMA)
+
+    def close(self) -> None:
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+    def _require(self) -> sqlite3.Connection:
+        if self._conn is None:
+            raise RuntimeError("SQLiteStorageAdapter is not initialized; call initialize() first.")
+        return self._conn
+
+    def get(self, key: str) -> Any | None:
+        row = self._require().execute("SELECT value, expires_at FROM atomicmemory_kv WHERE key = ?", (key,)).fetchone()
+        if row is None:
+            return None
+        value_text, expires_at = row
+        if expires_at is not None and self._clock() >= expires_at:
+            self.delete(key)
+            return None
+        return json.loads(value_text)
+
+    def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl_seconds: float | None = None,
+        encrypt: bool = False,
+    ) -> None:
+        if encrypt:
+            raise ConfigError(
+                "SQLiteStorageAdapter does not implement encryption; "
+                "passing encrypt=True would silently store plaintext. "
+                "Omit the flag or use a backend that implements ciphered storage.",
+                context={"adapter": "SQLiteStorageAdapter"},
+            )
+        now = self._clock()
+        expires_at = now + ttl_seconds if ttl_seconds is not None else None
+        self._require().execute(
+            "INSERT INTO atomicmemory_kv(key, value, created_at, expires_at) "
+            "VALUES (?, ?, ?, ?) "
+            "ON CONFLICT(key) DO UPDATE SET "
+            "value=excluded.value, created_at=excluded.created_at, expires_at=excluded.expires_at",
+            (key, json.dumps(value), now, expires_at),
+        )
+
+    def delete(self, key: str) -> bool:
+        cursor = self._require().execute("DELETE FROM atomicmemory_kv WHERE key = ?", (key,))
+        return (cursor.rowcount or 0) > 0
+
+    def has(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def keys(self) -> list[str]:
+        self.vacuum_expired()
+        rows = self._require().execute("SELECT key FROM atomicmemory_kv ORDER BY key").fetchall()
+        return [row[0] for row in rows]
+
+    def size(self) -> int:
+        self.vacuum_expired()
+        row = self._require().execute("SELECT COUNT(*) FROM atomicmemory_kv").fetchone()
+        return int(row[0]) if row is not None else 0
+
+    def clear(self) -> None:
+        self._require().execute("DELETE FROM atomicmemory_kv")
+
+    def vacuum_expired(self) -> int:
+        """Delete rows whose ``expires_at`` is in the past. Returns the row count deleted."""
+        now = self._clock()
+        cursor = self._require().execute(
+            "DELETE FROM atomicmemory_kv WHERE expires_at IS NOT NULL AND expires_at <= ?",
+            (now,),
+        )
+        return cursor.rowcount or 0

atomicmemory/memory/__init__.py

@@ -0,0 +1,82 @@
+"""V3 memory provider abstractions.
+
+Port of `atomicmemory-sdk/src/memory/`. Defines the core types and
+provider interfaces; concrete providers live in
+`atomicmemory.providers`.
+"""
+
+from atomicmemory.memory.filters import FieldFilter, FieldFilterOp, FilterExpr
+from atomicmemory.memory.types import (
+    Capabilities,
+    CapabilitiesExtensions,
+    CapabilitiesRequiredScope,
+    ContextPackage,
+    GraphEdge,
+    GraphNode,
+    GraphResult,
+    GraphSearchRequest,
+    HealthStatus,
+    IngestBase,
+    IngestInput,
+    IngestResult,
+    Insight,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryKind,
+    MemoryRef,
+    MemoryVersion,
+    MemoryVersionEvent,
+    Message,
+    MessageIngest,
+    MessageRole,
+    PackageFormat,
+    PackageRequest,
+    Profile,
+    Provenance,
+    Scope,
+    SearchRequest,
+    SearchResult,
+    SearchResultPage,
+    TextIngest,
+    VerbatimIngest,
+)
+
+__all__ = [
+    "Capabilities",
+    "CapabilitiesExtensions",
+    "CapabilitiesRequiredScope",
+    "ContextPackage",
+    "FieldFilter",
+    "FieldFilterOp",
+    "FilterExpr",
+    "GraphEdge",
+    "GraphNode",
+    "GraphResult",
+    "GraphSearchRequest",
+    "HealthStatus",
+    "IngestBase",
+    "IngestInput",
+    "IngestResult",
+    "Insight",
+    "ListRequest",
+    "ListResultPage",
+    "Memory",
+    "MemoryKind",
+    "MemoryRef",
+    "MemoryVersion",
+    "MemoryVersionEvent",
+    "Message",
+    "MessageIngest",
+    "MessageRole",
+    "PackageFormat",
+    "PackageRequest",
+    "Profile",
+    "Provenance",
+    "Scope",
+    "SearchRequest",
+    "SearchResult",
+    "SearchResultPage",
+    "TextIngest",
+    "VerbatimIngest",
+]

atomicmemory/memory/filters.py

@@ -0,0 +1,68 @@
+"""Recursive filter expression types.
+
+Port of `atomicmemory-sdk/src/memory/types.ts:149-168`. `FilterExpr` is a
+recursive discriminated union of and/or/not nodes plus a leaf
+`FieldFilter`. We model it as a `RootModel` so consumers can construct
+expressions ergonomically from dicts or by hand.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+
+FieldFilterOp = Literal[
+    "eq",
+    "neq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "contains",
+    "exists",
+]
+
+FieldFilterValue = str | int | float | bool | datetime | list[str | int | float] | None
+
+
+class FieldFilter(BaseModel):
+    """Leaf filter on a single record field."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    field: str
+    op: FieldFilterOp
+    value: FieldFilterValue = None
+
+
+class FilterAnd(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    and_: list[FilterExpr] = Field(alias="and")
+
+
+class FilterOr(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    or_: list[FilterExpr] = Field(alias="or")
+
+
+class FilterNot(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    not_: FilterExpr = Field(alias="not")
+
+
+FilterExprNode = Annotated[
+    FilterAnd | FilterOr | FilterNot | FieldFilter,
+    Field(union_mode="left_to_right"),
+]
+
+
+class FilterExpr(RootModel[FilterExprNode]):
+    """A composable filter expression over memory metadata fields."""
+
+
+FilterAnd.model_rebuild()
+FilterOr.model_rebuild()
+FilterNot.model_rebuild()

atomicmemory/memory/pipeline.py

@@ -0,0 +1,42 @@
+"""Memory processing pipeline hooks.
+
+Port of `atomicmemory-sdk/src/memory/pipeline.ts`. Pipelines let
+providers (or wrappers) preprocess/postprocess ingest, search, get, and
+list operations without modifying the provider itself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from atomicmemory.memory.types import (
+    IngestInput,
+    IngestResult,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    SearchRequest,
+    SearchResultPage,
+)
+
+
+@dataclass(frozen=True)
+class MemoryProcessingPipeline:
+    """Optional hook bundle for a provider.
+
+    Each hook may be ``None``. When present, the service awaits it around
+    the corresponding provider call.
+    """
+
+    preprocess_ingest: Callable[[IngestInput], Awaitable[list[IngestInput]]] | None = None
+    postprocess_ingest: Callable[[IngestResult, IngestInput], Awaitable[None]] | None = None
+    preprocess_search: Callable[[SearchRequest], Awaitable[SearchRequest]] | None = None
+    postprocess_search: Callable[[SearchResultPage, SearchRequest], Awaitable[SearchResultPage]] | None = None
+    preprocess_get: Callable[[MemoryRef], Awaitable[MemoryRef]] | None = None
+    postprocess_get: Callable[[Memory | None, MemoryRef], Awaitable[Memory | None]] | None = None
+    postprocess_list: Callable[[ListResultPage, ListRequest], Awaitable[ListResultPage]] | None = None
+
+
+NOOP_PIPELINE = MemoryProcessingPipeline()