langgraph-store-firestore 0.1.0__tar.gz

langgraph_store_firestore-0.1.0/.gitignore

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

langgraph_store_firestore-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: langgraph-store-firestore
+Version: 0.1.0
+Summary: Google Firestore long-term-memory store (BaseStore) for LangGraph — namespaced key/value memory with filters, list_namespaces and native semantic (Firestore vector) search
+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,firestore,gcp,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: google-cloud-firestore
+Requires-Dist: langgraph-store-core>=0.1.0
+Description-Content-Type: text/markdown
+
+# langgraph-store-firestore
+
+A **Google Firestore** long-term-memory store (`BaseStore`) for [LangGraph](https://langchain-ai.github.io/langgraph/) — namespaced key/value memory with prefix search, filters, `list_namespaces`, and **native semantic search via Firestore vector search**.
+
+```bash
+pip install langgraph-store-firestore
+```
+
+```python
+from langgraph_store_firestore import FirestoreStore
+
+store = FirestoreStore(project_id="my-gcp-project")
+store.put(("users", "1", "memories"), "food", {"text": "loves sushi", "kind": "pref"})
+item = store.get(("users", "1", "memories"), "food")
+hits = store.search(("users", "1"), filter={"kind": "pref"})
+```
+
+Use it as a LangGraph store: `graph.compile(store=FirestoreStore(...))`. Async methods work too (sync calls run in a thread). Authentication uses Application Default Credentials (`gcloud auth application-default login`).
+
+## Semantic search (Firestore vector search)
+
+Pass a LangGraph `IndexConfig` and the store embeds the configured fields on `put` (stored as a Firestore `Vector`) and ranks `search(query=...)` by cosine similarity using `find_nearest`:
+
+```python
+from langgraph_store_core import bedrock_titan_embeddings
+from langgraph_store_firestore import FirestoreStore
+
+store = FirestoreStore(project_id="my-gcp-project", collection="memory",
+                       index={"dims": 1024, "embed": bedrock_titan_embeddings(dimensions=1024), "fields": ["text"]})
+store.put(("memories", "kamal"), "k1", {"text": "the user loves sushi", "kind": "pref"})
+hits = store.search(("memories", "kamal"), query="what food does the user like?", filter={"kind": "pref"})
+print(hits[0].score, hits[0].value)
+```
+
+`embed` may be any LangChain `Embeddings`, a `list[str] -> list[list[float]]` callable, or a provider string. `fields` defaults to `["$"]` (whole value as JSON). `put(..., index=False)` skips embedding for one item.
+
+Firestore requires a **vector index**. With `create_index=True` (default) the store creates a composite index `prefix ASC + embedding (flat, dims)` on the collection through the Firestore Admin API if one is missing; the build is asynchronous and `query` searches fail with `FAILED_PRECONDITION` until it is READY (usually a few minutes; check `gcloud firestore indexes composite list`). The caller needs `datastore.indexes.create` / `list` permissions, or create the index yourself and pass `create_index=False`:
+
+```bash
+gcloud firestore indexes composite create --collection-group=memory --query-scope=COLLECTION \
+  --field-config=order=ASCENDING,field-path=prefix \
+  --field-config=vector-config='{"dimension":"1024","flat":"{}"}',field-path=embedding
+```
+
+The namespace prefix is a range pre-filter on the vector query. Firestore pre-filters are limited to indexed equality/range fields, so value `filter`s are applied on the returned candidates (the store oversamples when a filter is given).
+
+## Data model
+
+A single collection of documents `{prefix, key, value, created_at, updated_at[, embedding: Vector]}`, doc id = `enc(prefix)__enc(key)`. Search is a `prefix` range query; filters and namespace matching are evaluated in the [core](https://pypi.org/project/langgraph-store-core/).
+
+Docs: <https://skamalj.github.io/agentstate-reducer/>
+
+## License
+
+MIT

langgraph_store_firestore-0.1.0/README.md

@@ -0,0 +1,55 @@
+# langgraph-store-firestore
+
+A **Google Firestore** long-term-memory store (`BaseStore`) for [LangGraph](https://langchain-ai.github.io/langgraph/) — namespaced key/value memory with prefix search, filters, `list_namespaces`, and **native semantic search via Firestore vector search**.
+
+```bash
+pip install langgraph-store-firestore
+```
+
+```python
+from langgraph_store_firestore import FirestoreStore
+
+store = FirestoreStore(project_id="my-gcp-project")
+store.put(("users", "1", "memories"), "food", {"text": "loves sushi", "kind": "pref"})
+item = store.get(("users", "1", "memories"), "food")
+hits = store.search(("users", "1"), filter={"kind": "pref"})
+```
+
+Use it as a LangGraph store: `graph.compile(store=FirestoreStore(...))`. Async methods work too (sync calls run in a thread). Authentication uses Application Default Credentials (`gcloud auth application-default login`).
+
+## Semantic search (Firestore vector search)
+
+Pass a LangGraph `IndexConfig` and the store embeds the configured fields on `put` (stored as a Firestore `Vector`) and ranks `search(query=...)` by cosine similarity using `find_nearest`:
+
+```python
+from langgraph_store_core import bedrock_titan_embeddings
+from langgraph_store_firestore import FirestoreStore
+
+store = FirestoreStore(project_id="my-gcp-project", collection="memory",
+                       index={"dims": 1024, "embed": bedrock_titan_embeddings(dimensions=1024), "fields": ["text"]})
+store.put(("memories", "kamal"), "k1", {"text": "the user loves sushi", "kind": "pref"})
+hits = store.search(("memories", "kamal"), query="what food does the user like?", filter={"kind": "pref"})
+print(hits[0].score, hits[0].value)
+```
+
+`embed` may be any LangChain `Embeddings`, a `list[str] -> list[list[float]]` callable, or a provider string. `fields` defaults to `["$"]` (whole value as JSON). `put(..., index=False)` skips embedding for one item.
+
+Firestore requires a **vector index**. With `create_index=True` (default) the store creates a composite index `prefix ASC + embedding (flat, dims)` on the collection through the Firestore Admin API if one is missing; the build is asynchronous and `query` searches fail with `FAILED_PRECONDITION` until it is READY (usually a few minutes; check `gcloud firestore indexes composite list`). The caller needs `datastore.indexes.create` / `list` permissions, or create the index yourself and pass `create_index=False`:
+
+```bash
+gcloud firestore indexes composite create --collection-group=memory --query-scope=COLLECTION \
+  --field-config=order=ASCENDING,field-path=prefix \
+  --field-config=vector-config='{"dimension":"1024","flat":"{}"}',field-path=embedding
+```
+
+The namespace prefix is a range pre-filter on the vector query. Firestore pre-filters are limited to indexed equality/range fields, so value `filter`s are applied on the returned candidates (the store oversamples when a filter is given).
+
+## Data model
+
+A single collection of documents `{prefix, key, value, created_at, updated_at[, embedding: Vector]}`, doc id = `enc(prefix)__enc(key)`. Search is a `prefix` range query; filters and namespace matching are evaluated in the [core](https://pypi.org/project/langgraph-store-core/).
+
+Docs: <https://skamalj.github.io/agentstate-reducer/>
+
+## License
+
+MIT

langgraph_store_firestore-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langgraph-store-firestore"
+version = "0.1.0"
+description = "Google Firestore long-term-memory store (BaseStore) for LangGraph — namespaced key/value memory with filters, list_namespaces and native semantic (Firestore vector) search"
+authors = [{name = "Kamal", email = "skamalj@gmail.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "langgraph-store-core>=0.1.0",
+    "google-cloud-firestore",
+]
+keywords = ["langgraph", "store", "basestore", "firestore", "gcp", "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"
+
+[dependency-groups]
+dev = ["pytest>=7.0", "pytest-asyncio"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langgraph_store_firestore"]

langgraph_store_firestore-0.1.0/src/langgraph_store_firestore/__init__.py

@@ -0,0 +1,171 @@
+"""Google Firestore implementation of the LangGraph long-term-memory ``BaseStore``.
+
+``FirestoreStore`` persists namespaced key/value memory in a single collection and
+supports get / put / delete / search (namespace-prefix + filter) and
+``list_namespaces``. With an ``IndexConfig`` it also does **semantic search**
+natively via Firestore vector search (``find_nearest``, cosine). Built on
+``langgraph-store-core``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List, Optional, Tuple
+from urllib.parse import quote
+
+from google.cloud import firestore
+from google.cloud.firestore_v1.base_query import FieldFilter
+from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
+from google.cloud.firestore_v1.vector import Vector
+
+from langgraph_store_core import IndexConfig, KVStore
+
+__all__ = ["FirestoreStore"]
+
+logger = logging.getLogger(__name__)
+
+_FIELDS = ("prefix", "key", "value", "created_at", "updated_at")
+_PREFIX_HIGH = chr(0xF8FF)  # exclusive upper bound for a Firestore prefix scan
+
+
+class FirestoreStore(KVStore):
+    """LangGraph ``BaseStore`` backed by Google Firestore.
+
+    Example:
+        ```python
+        from langgraph_store_firestore import FirestoreStore
+
+        store = FirestoreStore(project_id="my-gcp-project")
+        store.put(("users", "1"), "profile", {"name": "Kamal"})
+
+        # semantic search
+        store = FirestoreStore(project_id=..., index={"dims": 1024, "embed": my_embedder, "fields": ["text"]})
+        hits = store.search(("users", "1"), query="what does the user like?")
+        ```
+
+    Authentication uses Application Default Credentials. With ``index`` the
+    embedding is stored as a Firestore ``Vector`` on ``embedding`` and queries
+    use ``find_nearest`` (cosine). Firestore requires a **vector index** on the
+    collection; when ``create_index=True`` (default) the store creates a
+    composite index ``prefix ASC + embedding (flat, dims)`` via the Admin API if
+    one is missing (index build is asynchronous; the first queries may fail
+    until it is READY).
+    """
+
+    supports_native_vector_search = True
+
+    def __init__(
+        self,
+        *,
+        project_id: str,
+        collection: str = "langgraph_store",
+        client: Optional["firestore.Client"] = None,
+        index: Optional[IndexConfig] = None,
+        create_index: bool = True,
+        database: str = "(default)",
+    ) -> None:
+        super().__init__(index=index)
+        self._project = project_id
+        self._database = database
+        self._client = client or firestore.Client(project=project_id, database=database)
+        self._col = self._client.collection(collection)
+        self._collection_name = collection
+        if self.dims and create_index:
+            self._ensure_vector_index()
+
+    # ------------------------------------------------------------------ index bootstrap
+    def _ensure_vector_index(self) -> None:
+        """Create the composite vector index (prefix ASC, embedding flat) if absent."""
+        from google.cloud import firestore_admin_v1 as fa
+
+        admin = fa.FirestoreAdminClient()
+        parent = (
+            f"projects/{self._project}/databases/{self._database}"
+            f"/collectionGroups/{self._collection_name}"
+        )
+        for ix in admin.list_indexes(parent=parent):
+            paths = [f.field_path for f in ix.fields]
+            if "embedding" in paths and "prefix" in paths:
+                return
+        index = fa.Index(
+            query_scope=fa.Index.QueryScope.COLLECTION,
+            fields=[
+                fa.Index.IndexField(field_path="prefix", order=fa.Index.IndexField.Order.ASCENDING),
+                fa.Index.IndexField(
+                    field_path="embedding",
+                    vector_config=fa.Index.IndexField.VectorConfig(
+                        dimension=self.dims, flat=fa.Index.IndexField.VectorConfig.FlatIndex()
+                    ),
+                ),
+            ],
+        )
+        try:
+            admin.create_index(parent=parent, index=index)
+            logger.info("FirestoreStore: creating vector index on %s (async)", self._collection_name)
+        except Exception as exc:  # already exists / racing creation
+            logger.info("FirestoreStore: vector index create skipped: %s", exc)
+
+    # ------------------------------------------------------------------ primitives
+    @staticmethod
+    def _docid(prefix: str, key: str) -> str:
+        # Firestore doc ids can't contain '/'; url-encode both parts, join safely.
+        return f"{quote(prefix, safe='')}__{quote(key, safe='')}"
+
+    def _row(self, d: dict) -> dict:
+        row = {f: d[f] for f in _FIELDS}
+        emb = d.get("embedding")
+        row["embedding"] = list(emb.to_map_value()["value"]) if isinstance(emb, Vector) else (
+            list(emb) if emb is not None else None
+        )
+        return row
+
+    def _read(self, prefix: str, key: str) -> Optional[dict]:
+        doc = self._col.document(self._docid(prefix, key)).get()
+        if not doc.exists:
+            return None
+        return self._row(doc.to_dict())
+
+    def _write(self, row: dict) -> None:
+        doc = {f: row[f] for f in _FIELDS}
+        if self.dims and row.get("embedding") is not None:
+            doc["embedding"] = Vector(row["embedding"])
+        self._col.document(self._docid(row["prefix"], row["key"])).set(doc)
+
+    def _remove(self, prefix: str, key: str) -> None:
+        self._col.document(self._docid(prefix, key)).delete()
+
+    def _prefix_query(self, prefix: str):
+        if prefix == "":
+            return self._col
+        return (
+            self._col.where(filter=FieldFilter("prefix", ">=", prefix))
+            .where(filter=FieldFilter("prefix", "<", prefix + _PREFIX_HIGH))
+        )
+
+    def _scan(self, prefix: str) -> List[dict]:
+        return [self._row(d.to_dict()) for d in self._prefix_query(prefix).stream()]
+
+    def _vector_search(
+        self, prefix: str, vector: List[float], filter: Optional[dict], limit: int
+    ) -> List[Tuple[dict, float]]:
+        """Native Firestore ``find_nearest`` (cosine) after a prefix range pre-filter.
+
+        Firestore pre-filters are limited to indexed equality/range fields, so
+        value filters are applied by core on the returned candidates; we
+        oversample to leave room for that.
+        """
+        oversample = limit * 4 if filter else limit
+        q = self._prefix_query(prefix).find_nearest(
+            vector_field="embedding",
+            query_vector=Vector(vector),
+            distance_measure=DistanceMeasure.COSINE,
+            limit=oversample,
+            distance_result_field="_distance",
+        )
+        out: List[Tuple[dict, float]] = []
+        for d in q.stream():
+            data = d.to_dict()
+            dist = data.pop("_distance", None)
+            row = self._row(data)
+            out.append((row, 1.0 - float(dist) if dist is not None else 0.0))
+        return out

langgraph_store_firestore-0.1.0/tests/test_firestore_semantic.py

@@ -0,0 +1,118 @@
+"""Semantic-search tests for FirestoreStore (native find_nearest path) against a real Firestore database.
+
+The store creates the composite vector index (prefix ASC + embedding flat) via the
+Admin API. Index builds are asynchronous, so the fixture waits for READY, and the
+collection name is fixed per DIMS so the index is reused across runs.
+"""
+import os
+import time
+import uuid
+
+import pytest
+
+from langgraph_store_core.testing import FakeEmbeddings
+from langgraph_store_firestore import FirestoreStore
+
+PROJECT = (
+    os.environ.get("PAI_FIRESTORE_PROJECT")
+    or os.environ.get("GCP_PROJECT")
+    or os.environ.get("GOOGLE_CLOUD_PROJECT")
+    or "gcdeveloper-new"
+)
+DIMS = 64
+COLLECTION = f"lg_vstore_test_d{DIMS}"   # stable name so the vector index persists between runs
+
+
+def _fs_available() -> bool:
+    try:
+        from google.cloud import firestore
+        firestore.Client(project=PROJECT).collection("x").limit(1).get()
+        return True
+    except Exception:
+        return False
+
+
+pytestmark = pytest.mark.skipif(not _fs_available(), reason="Firestore not reachable")
+
+
+def _wait_index_ready(project: str, collection: str, timeout: int = 600) -> None:
+    from google.cloud import firestore_admin_v1 as fa
+    admin = fa.FirestoreAdminClient()
+    parent = f"projects/{project}/databases/(default)/collectionGroups/{collection}"
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        for ix in admin.list_indexes(parent=parent):
+            paths = [f.field_path for f in ix.fields]
+            if "embedding" in paths and ix.state == fa.Index.State.READY:
+                return
+        time.sleep(10)
+    raise RuntimeError("vector index not READY in time")
+
+
+@pytest.fixture(scope="module")
+def store():
+    s = FirestoreStore(project_id=PROJECT, collection=COLLECTION,
+                       index={"dims": DIMS, "embed": FakeEmbeddings(DIMS), "fields": ["text"]})
+    _wait_index_ready(PROJECT, COLLECTION)
+    yield s
+    for row in s._scan(""):
+        s._remove(row["prefix"], row["key"])
+
+
+@pytest.fixture(autouse=True)
+def _clean(store):
+    yield
+    for row in store._scan(""):
+        store._remove(row["prefix"], row["key"])
+
+
+def _seed(s):
+    s.put(("memories", "kamal"), "food", {"text": "the user loves sushi and japanese food", "kind": "pref"})
+    s.put(("memories", "kamal"), "lang", {"text": "the user writes python every day", "kind": "fact"})
+    s.put(("memories", "kamal"), "city", {"text": "the user lives by the sea in a big city", "kind": "fact"})
+    s.put(("memories", "priya"), "food", {"text": "loves sushi", "kind": "pref"})
+
+
+def test_put_embeds_and_index_false_skips(store):
+    store.put(("n",), "k", {"text": "hello world"})
+    assert len(store._read("n", "k")["embedding"]) == DIMS
+    store.put(("n",), "k2", {"text": "hello"}, index=False)
+    assert store._read("n", "k2")["embedding"] is None
+
+
+def test_query_ranks_and_scores(store):
+    _seed(store)
+    hits = store.search(("memories", "kamal"), query="sushi and japanese food")
+    assert hits[0].key == "food" and hits[0].score is not None
+    assert hits[0].score >= hits[-1].score
+    assert all(h.namespace == ("memories", "kamal") for h in hits)
+
+
+def test_query_prefix_children_and_filter(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
+    facts = store.search(("memories", "kamal"), query="user", filter={"kind": "fact"})
+    assert facts and all(h.value["kind"] == "fact" for h in facts)
+
+
+def test_query_limit_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 and not {h.key for h in first} & {h.key for h in rest}
+
+
+def test_no_query_is_filter_only(store):
+    _seed(store)
+    hits = store.search(("memories", "kamal"))
+    assert [h.key for h in hits] == ["city", "food", "lang"] and all(h.score is None for h in hits)
+
+
+def test_native_path_used(store, monkeypatch):
+    _seed(store)
+    called = []
+    orig = store._vector_search
+    monkeypatch.setattr(store, "_vector_search", lambda *a, **k: (called.append(1), orig(*a, **k))[1])
+    store.search(("memories",), query="sushi")
+    assert called

langgraph_store_firestore-0.1.0/tests/test_firestore_store.py

@@ -0,0 +1,85 @@
+"""Tests for FirestoreStore (LangGraph BaseStore) against real Firestore.
+
+Requires a GCP project (PAI_FIRESTORE_PROJECT / GCP_PROJECT / GOOGLE_CLOUD_PROJECT)
+and Application Default Credentials. A unique collection per test isolates state.
+"""
+import os
+import uuid
+
+import pytest
+
+from langgraph_store_firestore import FirestoreStore
+
+PROJECT = (
+    os.environ.get("PAI_FIRESTORE_PROJECT")
+    or os.environ.get("GCP_PROJECT")
+    or os.environ.get("GOOGLE_CLOUD_PROJECT")
+)
+
+pytestmark = pytest.mark.skipif(not PROJECT, reason="no GCP project env var set")
+
+
+@pytest.fixture()
+def store():
+    cname = f"lg_store_test_{uuid.uuid4().hex[:8]}"
+    s = FirestoreStore(project_id=PROJECT, collection=cname)
+    yield s
+    for d in s._col.stream():
+        d.reference.delete()
+
+
+def test_put_get(store):
+    store.put(("users", "1"), "food", {"text": "sushi"})
+    it = store.get(("users", "1"), "food")
+    assert it is not None and it.value == {"text": "sushi"}
+    assert it.namespace == ("users", "1") and it.key == "food"
+
+
+def test_get_missing_is_none(store):
+    assert store.get(("nope",), "x") is None
+
+
+def test_update_preserves_created_at(store):
+    store.put(("u",), "k", {"v": 1})
+    a = store.get(("u",), "k")
+    store.put(("u",), "k", {"v": 2})
+    b = store.get(("u",), "k")
+    assert b.value == {"v": 2}
+    assert b.created_at == a.created_at
+    assert b.updated_at >= a.updated_at
+
+
+def test_delete_both_ways(store):
+    store.put(("u",), "k", {"v": 1})
+    store.delete(("u",), "k")
+    assert store.get(("u",), "k") is None
+    store.put(("u",), "k2", {"v": 1})
+    store.put(("u",), "k2", None)
+    assert store.get(("u",), "k2") is None
+
+
+def test_search_prefix_and_filter(store):
+    store.put(("users", "1", "mem"), "a", {"kind": "pref"})
+    store.put(("users", "1", "mem"), "b", {"kind": "fact"})
+    store.put(("users", "2", "mem"), "c", {"kind": "pref"})
+    assert sorted(i.key for i in store.search(("users", "1"))) == ["a", "b"]
+    assert [i.key for i in store.search(("users", "1"), filter={"kind": "pref"})] == ["a"]
+
+
+def test_list_namespaces(store):
+    store.put(("users", "1", "mem"), "a", {})
+    store.put(("users", "2", "mem"), "b", {})
+    store.put(("orgs", "x"), "c", {})
+    allns = store.list_namespaces()
+    assert ("users", "1", "mem") in allns and ("orgs", "x") in allns
+    assert all(n[0] == "users" for n in store.list_namespaces(prefix=("users",)))
+    depth1 = store.list_namespaces(max_depth=1)
+    assert ("users",) in depth1 and ("orgs",) in depth1
+
+
+async def test_async_surface(store):
+    await store.aput(("u",), "k", {"v": 1})
+    it = await store.aget(("u",), "k")
+    assert it.value == {"v": 1}
+    await store.adelete(("u",), "k")
+    assert await store.aget(("u",), "k") is None