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
