langgraph-store-core 0.1.0__tar.gz

langgraph_store_core-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/
+uv.lock
+.env

langgraph_store_core-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: langgraph-store-core
+Version: 0.1.0
+Summary: Shared core for LangGraph long-term-memory (BaseStore) backends — implement a store with four small primitives
+Project-URL: Homepage, https://github.com/skamalj/langgraph-store
+Project-URL: Repository, https://github.com/skamalj/langgraph-store.git
+Author-email: Kamal <skamalj@gmail.com>
+Keywords: agent-memory,basestore,langgraph,long-term-memory,store
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langgraph>=0.2.60
+Description-Content-Type: text/markdown
+
+# langgraph-store-core
+
+Shared core for building [LangGraph](https://langchain-ai.github.io/langgraph/) long-term-memory stores (`BaseStore`). Implement a backend by subclassing `KVStore` and supplying four small primitives — the core handles `batch`/`abatch`, timestamps, search filters, namespace prefix/suffix matching, `list_namespaces`, and **semantic search**.
+
+```python
+from langgraph_store_core import KVStore
+
+class MyStore(KVStore):
+    def _read(self, prefix, key): ...        # -> row | None
+    def _write(self, row): ...               # row = {prefix,key,value,created_at,updated_at,embedding}
+    def _remove(self, prefix, key): ...
+    def _scan(self, prefix): ...             # rows whose prefix starts with `prefix`
+
+    # optional — native vector search; the default ranks `_scan` rows by cosine in Python
+    def _vector_search(self, prefix, vector, filter, limit): ...   # -> [(row, score), ...]
+```
+
+## Semantic search
+
+Pass LangGraph's `IndexConfig` to any store built on the core and it embeds the configured fields on `put` and answers `search(namespace, query="...")` ranked by cosine similarity, with `SearchItem.score` populated:
+
+```python
+store = MyStore(index={"dims": 1024, "embed": embedder, "fields": ["text"]})
+store.put(("memories", "u1"), "k", {"text": "the user loves sushi"})
+hits = store.search(("memories", "u1"), query="what food does the user like?")
+```
+
+- `embed`: a LangChain `Embeddings`, a `list[str] -> list[list[float]]` callable, or a provider string (`"openai:text-embedding-3-small"`). `bedrock_titan_embeddings()` is included as a ready-made callable (needs `boto3`).
+- `fields`: JSON paths to embed; default `["$"]` (whole value). `put(..., index=False)` skips one item; `put(..., index=["title"])` overrides the fields.
+- A store without `index` is filter-only and ignores `query`, exactly as LangGraph documents.
+- Backends override `_vector_search` for native ANN (pgvector, Cosmos `VectorDistance`, Firestore `find_nearest`, DynamoDB `SearchVectors`); the core re-checks namespace and filter on what comes back, so a backend may push down only part of the filter.
+
+`langgraph_store_core.testing` ships `FakeEmbeddings` (deterministic, no network) and `MemoryKVStore` for tests.
+
+Concrete backends: [`langgraph-store-dynamodb`](https://pypi.org/project/langgraph-store-dynamodb/), [`langgraph-store-postgres`](https://pypi.org/project/langgraph-store-postgres/), [`langgraph-store-cosmosdb`](https://pypi.org/project/langgraph-store-cosmosdb/), [`langgraph-store-firestore`](https://pypi.org/project/langgraph-store-firestore/).
+
+Docs: <https://skamalj.github.io/agentstate-reducer/>
+
+## License
+
+MIT

langgraph_store_core-0.1.0/README.md

@@ -0,0 +1,41 @@
+# langgraph-store-core
+
+Shared core for building [LangGraph](https://langchain-ai.github.io/langgraph/) long-term-memory stores (`BaseStore`). Implement a backend by subclassing `KVStore` and supplying four small primitives — the core handles `batch`/`abatch`, timestamps, search filters, namespace prefix/suffix matching, `list_namespaces`, and **semantic search**.
+
+```python
+from langgraph_store_core import KVStore
+
+class MyStore(KVStore):
+    def _read(self, prefix, key): ...        # -> row | None
+    def _write(self, row): ...               # row = {prefix,key,value,created_at,updated_at,embedding}
+    def _remove(self, prefix, key): ...
+    def _scan(self, prefix): ...             # rows whose prefix starts with `prefix`
+
+    # optional — native vector search; the default ranks `_scan` rows by cosine in Python
+    def _vector_search(self, prefix, vector, filter, limit): ...   # -> [(row, score), ...]
+```
+
+## Semantic search
+
+Pass LangGraph's `IndexConfig` to any store built on the core and it embeds the configured fields on `put` and answers `search(namespace, query="...")` ranked by cosine similarity, with `SearchItem.score` populated:
+
+```python
+store = MyStore(index={"dims": 1024, "embed": embedder, "fields": ["text"]})
+store.put(("memories", "u1"), "k", {"text": "the user loves sushi"})
+hits = store.search(("memories", "u1"), query="what food does the user like?")
+```
+
+- `embed`: a LangChain `Embeddings`, a `list[str] -> list[list[float]]` callable, or a provider string (`"openai:text-embedding-3-small"`). `bedrock_titan_embeddings()` is included as a ready-made callable (needs `boto3`).
+- `fields`: JSON paths to embed; default `["$"]` (whole value). `put(..., index=False)` skips one item; `put(..., index=["title"])` overrides the fields.
+- A store without `index` is filter-only and ignores `query`, exactly as LangGraph documents.
+- Backends override `_vector_search` for native ANN (pgvector, Cosmos `VectorDistance`, Firestore `find_nearest`, DynamoDB `SearchVectors`); the core re-checks namespace and filter on what comes back, so a backend may push down only part of the filter.
+
+`langgraph_store_core.testing` ships `FakeEmbeddings` (deterministic, no network) and `MemoryKVStore` for tests.
+
+Concrete backends: [`langgraph-store-dynamodb`](https://pypi.org/project/langgraph-store-dynamodb/), [`langgraph-store-postgres`](https://pypi.org/project/langgraph-store-postgres/), [`langgraph-store-cosmosdb`](https://pypi.org/project/langgraph-store-cosmosdb/), [`langgraph-store-firestore`](https://pypi.org/project/langgraph-store-firestore/).
+
+Docs: <https://skamalj.github.io/agentstate-reducer/>
+
+## License
+
+MIT

langgraph_store_core-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langgraph-store-core"
+version = "0.1.0"
+description = "Shared core for LangGraph long-term-memory (BaseStore) backends — implement a store with four small primitives"
+authors = [{name = "Kamal", email = "skamalj@gmail.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "langgraph>=0.2.60",
+]
+keywords = ["langgraph", "store", "basestore", "long-term-memory", "agent-memory"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/skamalj/langgraph-store"
+Repository = "https://github.com/skamalj/langgraph-store.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langgraph_store_core"]

langgraph_store_core-0.1.0/src/langgraph_store_core/__init__.py

@@ -0,0 +1,349 @@
+"""Shared core for LangGraph long-term-memory ``BaseStore`` backends.
+
+``KVStore`` implements the whole ``BaseStore`` surface — ``batch`` / ``abatch``
+dispatch, timestamp handling, filter evaluation, namespace prefix/suffix matching,
+``list_namespaces`` and **semantic search** — on top of a handful of primitives
+each backend supplies:
+
+    _read(prefix, key)  -> row | None
+    _write(row)         -> None
+    _remove(prefix, key)-> None
+    _scan(prefix)       -> list[row]
+    _vector_search(prefix, vector, filter, limit) -> list[(row, score)]   (optional)
+
+A ``row`` is ``{"prefix": str, "key": str, "value": dict, "created_at": iso,
+"updated_at": iso, "embedding": list[float] | None}``. Namespaces (tuples) are
+joined with a unit-separator into the ``prefix`` string.
+
+Semantic search
+---------------
+Construct a store with LangGraph's ``IndexConfig`` (``dims``, ``embed``,
+``fields``) and it embeds the configured fields of every value on ``put`` and
+answers ``search(namespace, query="...")`` by vector similarity, populating
+``SearchItem.score``. Backends with native vector search override
+``_vector_search``; the default implementation scans the prefix and ranks by
+cosine similarity in Python, so every backend gets semantic search even before
+it has a native path. Without an ``IndexConfig`` the store is filter-only and
+``query`` is ignored, exactly as LangGraph documents.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+from datetime import datetime, timezone
+from typing import Any, Callable, Iterable, List, Optional, Sequence, Tuple
+
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    IndexConfig,
+    Item,
+    ListNamespacesOp,
+    Op,
+    PutOp,
+    Result,
+    SearchItem,
+    SearchOp,
+)
+from langgraph.store.base.embed import ensure_embeddings, get_text_at_path, tokenize_path
+
+__all__ = [
+    "KVStore",
+    "IndexConfig",
+    "NS_DELIM",
+    "ns_to_str",
+    "str_to_ns",
+    "cosine_similarity",
+    "bedrock_titan_embeddings",
+]
+
+NS_DELIM = "\x1f"  # unit separator — not expected inside namespace parts
+
+
+def ns_to_str(namespace: tuple) -> str:
+    return NS_DELIM.join(namespace)
+
+
+def str_to_ns(prefix: str) -> tuple:
+    return tuple(prefix.split(NS_DELIM)) if prefix else ()
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _as_dt(value: Any) -> datetime:
+    return value if isinstance(value, datetime) else datetime.fromisoformat(value)
+
+
+def cosine_similarity(a: Sequence[float], b: Sequence[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return dot / (na * nb)
+
+
+def bedrock_titan_embeddings(
+    *,
+    model_id: str = "amazon.titan-embed-text-v2:0",
+    dimensions: int = 1024,
+    normalize: bool = True,
+    region_name: Optional[str] = None,
+    client: Any = None,
+) -> Callable[[List[str]], List[List[float]]]:
+    """An ``IndexConfig["embed"]`` callable backed by Amazon Bedrock Titan Text v2.
+
+    Titan v2 supports 256 / 512 / 1024 dimensions; ``dimensions`` must equal the
+    store's ``IndexConfig["dims"]``. Requires ``boto3`` (imported lazily).
+    """
+    import boto3  # noqa: WPS433 — optional dependency
+
+    runtime = client or boto3.client("bedrock-runtime", region_name=region_name)
+
+    def embed(texts: List[str]) -> List[List[float]]:
+        out: List[List[float]] = []
+        for text in texts:
+            body = json.dumps({"inputText": text, "dimensions": dimensions, "normalize": normalize})
+            resp = runtime.invoke_model(modelId=model_id, body=body)
+            out.append(json.loads(resp["body"].read())["embedding"])
+        return out
+
+    return embed
+
+
+def _matches_filter(value: dict, filter: Optional[dict]) -> bool:
+    """Evaluate a LangGraph search ``filter`` against a stored value.
+
+    Supports plain equality and the common Mongo-style operators
+    ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin).
+    """
+    if not filter:
+        return True
+    for field, expected in filter.items():
+        actual = value.get(field)
+        if isinstance(expected, dict):
+            for op, operand in expected.items():
+                if op == "$eq" and actual != operand:
+                    return False
+                elif op == "$ne" and actual == operand:
+                    return False
+                elif op == "$gt" and not (actual is not None and actual > operand):
+                    return False
+                elif op == "$gte" and not (actual is not None and actual >= operand):
+                    return False
+                elif op == "$lt" and not (actual is not None and actual < operand):
+                    return False
+                elif op == "$lte" and not (actual is not None and actual <= operand):
+                    return False
+                elif op == "$in" and actual not in operand:
+                    return False
+                elif op == "$nin" and actual in operand:
+                    return False
+                elif op not in ("$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin"):
+                    return False
+        elif actual != expected:
+            return False
+    return True
+
+
+def _match_path(ns_slice: tuple, path: tuple) -> bool:
+    if len(ns_slice) != len(path):
+        return False
+    return all(p == "*" or p == n for n, p in zip(ns_slice, path))
+
+
+def _match_condition(namespace: tuple, condition: Any) -> bool:
+    path = tuple(condition.path)
+    if len(path) > len(namespace):
+        return False
+    if condition.match_type == "suffix":
+        return _match_path(namespace[len(namespace) - len(path):], path)
+    return _match_path(namespace[: len(path)], path)  # "prefix" (default)
+
+
+def _in_prefix(row_prefix: str, prefix: str) -> bool:
+    return prefix == "" or row_prefix == prefix or row_prefix.startswith(prefix + NS_DELIM)
+
+
+class KVStore(BaseStore):
+    """A ``BaseStore`` implemented over a few datastore primitives.
+
+    Subclasses implement ``_read`` / ``_write`` / ``_remove`` / ``_scan`` and,
+    for native semantic search, ``_vector_search``; this class provides
+    everything the LangGraph store protocol requires, including the async
+    surface (primitives run in a thread executor).
+
+    Args:
+        index: Optional LangGraph ``IndexConfig`` (``dims``, ``embed``,
+            ``fields``). When given, values are embedded on ``put`` and
+            ``search(query=...)`` ranks by similarity. ``embed`` may be a
+            LangChain ``Embeddings``, a ``list[str] -> list[list[float]]``
+            callable, or a provider string LangChain can resolve.
+    """
+
+    supports_native_vector_search: bool = False
+
+    def __init__(self, *, index: Optional[IndexConfig] = None) -> None:
+        super().__init__()
+        self.index_config: Optional[IndexConfig] = None
+        self.embeddings = None
+        self._index_paths: List[Tuple[str, list]] = []
+        if index is not None:
+            self.index_config = dict(index)  # type: ignore[assignment]
+            self.embeddings = ensure_embeddings(index.get("embed"))
+            fields = index.get("fields") or ["$"]
+            self._index_paths = [(f, tokenize_path(f)) for f in fields]
+
+    @property
+    def dims(self) -> Optional[int]:
+        return int(self.index_config["dims"]) if self.index_config else None
+
+    # ------------------------------------------------------------------ primitives
+    def _read(self, prefix: str, key: str) -> Optional[dict]:
+        raise NotImplementedError
+
+    def _write(self, row: dict) -> None:
+        raise NotImplementedError
+
+    def _remove(self, prefix: str, key: str) -> None:
+        raise NotImplementedError
+
+    def _scan(self, prefix: str) -> List[dict]:
+        """Return every row whose ``prefix`` starts with ``prefix`` (all if "")."""
+        raise NotImplementedError
+
+    def _vector_search(
+        self, prefix: str, vector: List[float], filter: Optional[dict], limit: int
+    ) -> List[Tuple[dict, float]]:
+        """Return up to ``limit`` ``(row, score)`` pairs, most similar first.
+
+        ``score`` is cosine similarity in ``[-1, 1]`` (higher is better).
+        Backends with native vector search override this; the default scans the
+        prefix and ranks in Python, which is correct for every backend and fine
+        for small namespaces.
+        """
+        scored: List[Tuple[dict, float]] = []
+        for row in self._scan(prefix):
+            emb = row.get("embedding")
+            if not emb or not _in_prefix(row["prefix"], prefix):
+                continue
+            if not _matches_filter(row["value"], filter):
+                continue
+            scored.append((row, cosine_similarity(vector, emb)))
+        scored.sort(key=lambda rs: -rs[1])
+        return scored[:limit]
+
+    # ------------------------------------------------------------------ embedding
+    def _texts_for(self, value: dict, index: Any) -> List[str]:
+        """Texts to embed for a value, honouring the per-put ``index`` override."""
+        fields = [f for f, _ in self._index_paths] if index is None else list(index)
+        texts: List[str] = []
+        for field in fields:
+            # Pass the raw field string: get_text_at_path tokenizes it itself and
+            # handles "$" (whole value as JSON), which a pre-tokenized path does not.
+            texts.extend(get_text_at_path(value, field))
+        return [t for t in texts if t and t.strip()]
+
+    def _embed_value(self, value: dict, index: Any) -> Optional[List[float]]:
+        if self.embeddings is None or index is False:
+            return None
+        texts = self._texts_for(value, index)
+        if not texts:
+            return None
+        # One vector per item: embed the concatenation of the indexed fields.
+        return list(self.embeddings.embed_documents(["\n".join(texts)])[0])
+
+    def _embed_query(self, query: str) -> List[float]:
+        assert self.embeddings is not None
+        return list(self.embeddings.embed_query(query))
+
+    # ------------------------------------------------------------------ helpers
+    def _to_item(self, row: dict, search: bool = False, score: Optional[float] = None):
+        namespace = str_to_ns(row["prefix"])
+        created, updated = _as_dt(row["created_at"]), _as_dt(row["updated_at"])
+        if search:
+            return SearchItem(
+                namespace=namespace, key=row["key"], value=row["value"],
+                created_at=created, updated_at=updated, score=score,
+            )
+        return Item(
+            value=row["value"], key=row["key"], namespace=namespace,
+            created_at=created, updated_at=updated,
+        )
+
+    def _op_get(self, namespace: tuple, key: str) -> Optional[Item]:
+        row = self._read(ns_to_str(namespace), key)
+        return self._to_item(row) if row else None
+
+    def _op_put(self, namespace: tuple, key: str, value: dict, index: Any = None) -> None:
+        prefix = ns_to_str(namespace)
+        existing = self._read(prefix, key)
+        now = _now_iso()
+        self._write({
+            "prefix": prefix, "key": key, "value": value,
+            "created_at": existing["created_at"] if existing else now,
+            "updated_at": now,
+            "embedding": self._embed_value(value, index),
+        })
+
+    def _op_delete(self, namespace: tuple, key: str) -> None:
+        self._remove(ns_to_str(namespace), key)
+
+    def _op_search(self, namespace_prefix, filter, limit, offset, query=None) -> List[SearchItem]:
+        prefix = ns_to_str(namespace_prefix)
+        if query and self.embeddings is not None:
+            vector = self._embed_query(query)
+            hits = self._vector_search(prefix, vector, filter, (limit or 10) + (offset or 0))
+            # Defensive re-check: a backend may apply only part of the filter natively.
+            hits = [(r, s) for r, s in hits if _in_prefix(r["prefix"], prefix) and _matches_filter(r["value"], filter)]
+            hits = hits[offset : (offset + limit) if limit is not None else None]
+            return [self._to_item(r, search=True, score=s) for r, s in hits]
+        rows = [r for r in self._scan(prefix) if _in_prefix(r["prefix"], prefix)]
+        rows = [r for r in rows if _matches_filter(r["value"], filter)]
+        rows.sort(key=lambda r: (r["prefix"], r["key"]))
+        rows = rows[offset : (offset + limit) if limit is not None else None]
+        return [self._to_item(r, search=True) for r in rows]
+
+    def _op_list_namespaces(self, match_conditions, max_depth, limit, offset) -> List[tuple]:
+        conditions = match_conditions or ()
+        seen = set()
+        for row in self._scan(""):
+            namespace = str_to_ns(row["prefix"])
+            if all(_match_condition(namespace, c) for c in conditions):
+                seen.add(namespace[:max_depth] if max_depth is not None else namespace)
+        ordered = sorted(seen)
+        return ordered[offset : (offset + limit) if limit is not None else None]
+
+    # ------------------------------------------------------------------ BaseStore
+    def batch(self, ops: Iterable[Op]) -> List[Result]:
+        results: List[Result] = []
+        for op in ops:
+            if isinstance(op, GetOp):
+                results.append(self._op_get(op.namespace, op.key))
+            elif isinstance(op, PutOp):
+                if op.value is None:
+                    self._op_delete(op.namespace, op.key)
+                else:
+                    self._op_put(op.namespace, op.key, op.value, getattr(op, "index", None))
+                results.append(None)
+            elif isinstance(op, SearchOp):
+                results.append(
+                    self._op_search(
+                        op.namespace_prefix, op.filter, op.limit, op.offset,
+                        getattr(op, "query", None),
+                    )
+                )
+            elif isinstance(op, ListNamespacesOp):
+                results.append(
+                    self._op_list_namespaces(op.match_conditions, op.max_depth, op.limit, op.offset)
+                )
+            else:  # pragma: no cover
+                raise NotImplementedError(f"Unsupported op: {type(op)}")
+        return results
+
+    async def abatch(self, ops: Iterable[Op]) -> List[Result]:
+        return await asyncio.get_running_loop().run_in_executor(None, self.batch, list(ops))

langgraph_store_core-0.1.0/src/langgraph_store_core/testing.py

@@ -0,0 +1,68 @@
+"""Test helpers shared by the provider test suites (and useful for users' tests).
+
+``FakeEmbeddings`` is a deterministic, dependency-free embedder: a hashed
+bag-of-words projected into ``dims`` dimensions and L2-normalised. Texts that
+share words are close, texts that do not are far, and no network call is made.
+Good enough to exercise a store's vector path end to end.
+
+``MemoryKVStore`` is the smallest possible ``KVStore`` — a dict — used to test
+the core semantic-search machinery without any backend.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from typing import Dict, List, Optional
+
+from . import KVStore
+
+__all__ = ["FakeEmbeddings", "MemoryKVStore"]
+
+_WORD = re.compile(r"[a-z0-9]+")
+
+
+class FakeEmbeddings:
+    """Deterministic hashed bag-of-words embedder with the LangChain interface."""
+
+    def __init__(self, dims: int = 64) -> None:
+        self.dims = dims
+
+    def _embed(self, text: str) -> List[float]:
+        vec = [0.0] * self.dims
+        for word in _WORD.findall(text.lower()):
+            h = int(hashlib.md5(word.encode()).hexdigest(), 16)
+            vec[h % self.dims] += 1.0
+        norm = math.sqrt(sum(v * v for v in vec))
+        return [v / norm for v in vec] if norm else [1.0 / math.sqrt(self.dims)] * self.dims
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        return [self._embed(t) for t in texts]
+
+    def embed_query(self, text: str) -> List[float]:
+        return self._embed(text)
+
+    def __call__(self, texts: List[str]) -> List[List[float]]:  # callable form too
+        return self.embed_documents(texts)
+
+
+class MemoryKVStore(KVStore):
+    """In-process ``KVStore`` over a dict; relies on the core's default vector search."""
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._rows: Dict[tuple, dict] = {}
+
+    def _read(self, prefix: str, key: str) -> Optional[dict]:
+        row = self._rows.get((prefix, key))
+        return dict(row) if row else None
+
+    def _write(self, row: dict) -> None:
+        self._rows[(row["prefix"], row["key"])] = dict(row)
+
+    def _remove(self, prefix: str, key: str) -> None:
+        self._rows.pop((prefix, key), None)
+
+    def _scan(self, prefix: str) -> List[dict]:
+        return [dict(r) for (p, _), r in self._rows.items() if p.startswith(prefix)]

langgraph_store_core-0.1.0/tests/test_core_semantic.py

@@ -0,0 +1,118 @@
+"""Core semantic-search machinery, exercised on the dict-backed MemoryKVStore.
+
+No backend, no network: FakeEmbeddings is deterministic. Everything here holds
+for every provider because it is the shared code path.
+"""
+import pytest
+
+from langgraph_store_core import KVStore, cosine_similarity
+from langgraph_store_core.testing import FakeEmbeddings, MemoryKVStore
+
+DIMS = 32
+
+
+@pytest.fixture()
+def store():
+    return MemoryKVStore(index={"dims": DIMS, "embed": FakeEmbeddings(DIMS), "fields": ["text"]})
+
+
+def _seed(store):
+    store.put(("memories", "kamal"), "food", {"text": "the user loves sushi and japanese food", "kind": "pref"})
+    store.put(("memories", "kamal"), "lang", {"text": "the user writes python every day", "kind": "fact"})
+    store.put(("memories", "kamal"), "city", {"text": "the user lives by the sea in a big city", "kind": "fact"})
+    store.put(("memories", "priya"), "food", {"text": "loves sushi", "kind": "pref"})
+
+
+def test_put_embeds_configured_fields(store):
+    store.put(("n",), "k", {"text": "hello world", "other": "ignored"})
+    row = store._read("n", "k")
+    assert row["embedding"] is not None and len(row["embedding"]) == DIMS
+
+
+def test_put_index_false_skips_embedding(store):
+    store.put(("n",), "k", {"text": "hello"}, index=False)
+    assert store._read("n", "k")["embedding"] is None
+
+
+def test_put_index_override_fields(store):
+    store.put(("n",), "k", {"text": "aaa", "title": "sushi japanese"}, index=["title"])
+    hits = store.search(("n",), query="sushi")
+    assert hits and hits[0].key == "k" and hits[0].score > 0
+
+
+def test_query_ranks_by_similarity_and_sets_score(store):
+    _seed(store)
+    hits = store.search(("memories", "kamal"), query="sushi and japanese food")
+    assert hits[0].key == "food"
+    assert all(h.score is not None for h in hits)
+    assert hits[0].score >= hits[-1].score
+
+
+def test_query_respects_namespace_prefix(store):
+    _seed(store)
+    keys = {(h.namespace, h.key) for h in store.search(("memories",), query="sushi")}
+    assert (("memories", "kamal"), "food") in keys and (("memories", "priya"), "food") in keys
+    only_kamal = store.search(("memories", "kamal"), query="sushi")
+    assert all(h.namespace == ("memories", "kamal") for h in only_kamal)
+
+
+def test_query_combined_with_filter(store):
+    _seed(store)
+    hits = store.search(("memories", "kamal"), query="user", filter={"kind": "fact"})
+    assert hits and all(h.value["kind"] == "fact" for h in hits)
+
+
+def test_query_limit_and_offset(store):
+    _seed(store)
+    first = store.search(("memories", "kamal"), query="user", limit=2)
+    rest = store.search(("memories", "kamal"), query="user", limit=2, offset=2)
+    assert len(first) == 2 and len(rest) == 1
+    assert not {h.key for h in first} & {h.key for h in rest}
+
+
+def test_search_without_query_is_filter_only_no_score(store):
+    _seed(store)
+    hits = store.search(("memories", "kamal"))
+    assert [h.key for h in hits] == ["city", "food", "lang"]
+    assert all(h.score is None for h in hits)
+
+
+def test_store_without_index_ignores_query():
+    s = MemoryKVStore()
+    s.put(("n",), "a", {"text": "sushi"})
+    s.put(("n",), "b", {"text": "python"})
+    hits = s.search(("n",), query="sushi")
+    assert [h.key for h in hits] == ["a", "b"] and all(h.score is None for h in hits)
+    assert s._read("n", "a")["embedding"] is None
+
+
+def test_default_fields_embed_whole_value():
+    s = MemoryKVStore(index={"dims": DIMS, "embed": FakeEmbeddings(DIMS)})
+    s.put(("n",), "a", {"anything": "sushi rolls"})
+    s.put(("n",), "b", {"anything": "python code"})
+    assert s.search(("n",), query="sushi")[0].key == "a"
+
+
+def test_callable_embed_is_accepted():
+    fe = FakeEmbeddings(DIMS)
+    s = MemoryKVStore(index={"dims": DIMS, "embed": fe.embed_documents, "fields": ["text"]})
+    s.put(("n",), "a", {"text": "sushi"})
+    assert s.search(("n",), query="sushi")[0].score > 0.9
+
+
+def test_update_reembeds(store):
+    store.put(("n",), "k", {"text": "sushi"})
+    store.put(("n",), "k", {"text": "python"})
+    assert store.search(("n",), query="python")[0].score > store.search(("n",), query="sushi")[0].score
+
+
+async def test_async_query(store):
+    _seed(store)
+    hits = await store.asearch(("memories", "kamal"), query="sushi")
+    assert hits[0].key == "food"
+
+
+def test_cosine_similarity():
+    assert cosine_similarity([1, 0], [1, 0]) == pytest.approx(1.0)
+    assert cosine_similarity([1, 0], [0, 1]) == pytest.approx(0.0)
+    assert cosine_similarity([0, 0], [1, 1]) == 0.0