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
