langgraph-store-firestore 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,4 @@
+langgraph_store_firestore/__init__.py,sha256=ShCoHiaY58TXzunNHZgwu-0ZjD-tJA9dB5H07ceRUME,7105
+langgraph_store_firestore-0.1.0.dist-info/METADATA,sha256=7eWR6VqGOO0aDDt2ZwrQDxS8INnq8CkBeZhXzqmAXQg,4126
+langgraph_store_firestore-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+langgraph_store_firestore-0.1.0.dist-info/RECORD,,

langgraph_store_firestore-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any