aegisdb-langgraph 0.8.0__tar.gz

aegisdb_langgraph-0.8.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: aegisdb-langgraph
+Version: 0.8.0
+Summary: Use AegisDB as a LangGraph long-term-memory store
+License: MIT
+Project-URL: Homepage, https://github.com/d4n-larsson/aegisdb
+Project-URL: Repository, https://github.com/d4n-larsson/aegisdb
+Project-URL: Issues, https://github.com/d4n-larsson/aegisdb/issues
+Keywords: aegisdb,langgraph,langchain,agent-memory,store
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: aegisdb
+Requires-Dist: langgraph-checkpoint<5,>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: langgraph>=0.2; extra == "dev"
+
+# aegisdb-langgraph — AegisDB as a LangGraph store
+
+Use [AegisDB](https://github.com/d4n-larsson/aegisdb) as the long-term memory
+behind a LangGraph agent.
+
+```bash
+pip install aegisdb-langgraph
+```
+
+```python
+from aegisdb_langgraph import AegisStore
+
+store = AegisStore(host="127.0.0.1", port=9470, namespace="my-agent")
+
+store.put(("users", "42"), "prefs", {"theme": "dark"})
+store.get(("users", "42"), "prefs").value        # {"theme": "dark"}
+store.search(("users",), query="dark")           # BM25 over stored values
+store.list_namespaces()                          # [("users", "42")]
+```
+
+…and inside a graph, the way LangGraph injects it:
+
+```python
+graph = builder.compile(store=AegisStore(namespace="my-agent"))
+
+def remember(state, *, store):
+    store.put(("users", state["user"]), "last", {"seen": "hello"})
+```
+
+`BaseStore` funnels `get` / `put` / `search` / `delete` / `list_namespaces`
+through one abstract `batch(ops)`, so that is all this implements — the
+concrete methods come from the base class and cannot drift from it. `aput`,
+`aget` and friends work too, on a worker thread.
+
+## The mapping
+
+LangGraph addresses items by a hierarchical `namespace: tuple[str, ...]` plus a
+`key`, and searches by namespace *prefix*. AegisDB has a flat `agent_id` that is
+an isolation boundary rather than a path, so the hierarchy is carried in tags:
+
+| | |
+|---|---|
+| `agent_id` | the store's own `namespace=` — one tenant, isolated by the server |
+| tags | a marker, a hash of `(namespace, key)`, and a hash of **every prefix** of the namespace |
+| `data` | JSON: `{"ns": [...], "key": ..., "value": {...}}` |
+
+A tag per prefix is what makes a prefix search an index lookup rather than a
+scan. Tags are hashed because AegisDB caps one at 64 bytes (and 32 per record)
+while a namespace or key can be longer; the readable copy lives in `data`,
+which is also what makes `list_namespaces` possible.
+
+The digest is length-prefixed per segment, so `("a", "bc")` and `("ab", "c")`
+cannot collide — joining on a separator would make them the same string, and
+two namespaces sharing a tag is a cross-namespace read.
+
+**Namespace depth is capped at 29.** Marker + key + one tag per prefix has to
+fit in AegisDB's 32-tag ceiling. Deeper raises `ValueError` naming the limit,
+rather than an `INVALID_REQUEST` that says nothing about namespaces.
+
+## Three things it does not do
+
+**TTL is refused, not ignored.** AegisDB expires only working memory, which is
+a per-session ring buffer rather than a store, so a TTL here would never fire.
+Silently never expiring something a caller asked to expire is a retention
+surprise. Use the server's `forget` op, which ages records out by importance
+and recency — and which the LangGraph API has no way to express.
+
+**No vector indexing.** `query=` runs the server's BM25 index: no embedding
+provider needed, and exact tokens (an error string, a flag, an identifier)
+match well, with the server's relevance score carried through to
+`SearchItem.score`. `index=` is accepted and ignored, because honouring it
+would mean this package owning an embeddings function. A server started with
+`--no-lexical-index` raises a `RuntimeError` naming that flag when a query was
+actually passed — a queryless search keeps working, and any other `NOT_READY`
+is re-raised untouched rather than blamed on an index it never used.
+
+**`filter=` is applied client-side.** AegisDB cannot filter on arbitrary JSON
+fields, so candidates are pulled back and matched here — using *LangGraph's
+own* `_compare_values`, so the semantics are identical to `InMemoryStore`
+rather than a second implementation that drifts. It inherits that function's
+limits too: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` are supported and `$in`
+is not, in both stores alike.
+
+Because filtering happens here, paging does too — asking the server for an
+`offset` would skip rows before they were filtered, so page 2 would silently
+omit matches. An **unfiltered** search does page on the server, so a deep page
+stays a small read.
+
+`search_scan_limit` (default 1000) bounds how many candidates a filtered search
+pulls back; `list_namespaces` is bounded the same way, since AegisDB indexes
+tags but cannot enumerate them. It is **clamped to 1000**, because the server
+clamps `top_k` there and says nothing — a larger value would read as "scans
+more" while changing nothing.
+
+**Past that bound the answer is short and cannot say so.** `search` and
+`list_namespaces` return plain lists, with nowhere to put a flag. A store
+holding more than `search_scan_limit` items can therefore be missing matches
+from a filtered search, or namespaces from a listing. Stated here because it
+cannot be signalled there.
+
+## Isolation
+
+`namespace=` is the AegisDB namespace, enforced by the server. Two stores with
+different ones cannot see each other's items even though they share a server —
+so one AegisDB instance can back many agents, and the LangGraph hierarchy lives
+inside each.
+
+Passing your own `client=` makes *its* `agent_id` authoritative, since that is
+what the server enforces; giving both and disagreeing raises, rather than
+reporting one namespace while writing into another.
+
+## Concurrency
+
+**One store is one connection, and `batch` holds a lock.** The client owns a
+socket and is not thread-safe, while `abatch` runs on a worker thread and
+LangGraph's sync runner executes a superstep's tasks on a pool — so without
+serialising, two nodes touching the store interleave on the same socket and one
+reads the other's response. Concurrent nodes therefore queue; for real
+parallelism, build a store per worker.
+
+Across *processes* nothing here can help: `put` is a read-modify-write and
+AegisDB has no upsert, so two racing writers can leave two records for one key.
+Reads pick deterministically (lowest id) so the store keeps answering
+consistently if that happens.
+
+## Tests
+
+```bash
+make langgraph-test        # from the repo root
+```
+
+Every behaviour meant to match the reference implementation is asserted by
+running the same case against `InMemoryStore` and comparing — an assertion
+written from a reading of the contract would only encode that reading. The
+suite also compiles a real graph with `store=` and lets LangGraph inject it,
+which is the part that would break if the class satisfied the ABC but not the
+runtime's expectations of it.

aegisdb_langgraph-0.8.0/README.md

@@ -0,0 +1,137 @@
+# aegisdb-langgraph — AegisDB as a LangGraph store
+
+Use [AegisDB](https://github.com/d4n-larsson/aegisdb) as the long-term memory
+behind a LangGraph agent.
+
+```bash
+pip install aegisdb-langgraph
+```
+
+```python
+from aegisdb_langgraph import AegisStore
+
+store = AegisStore(host="127.0.0.1", port=9470, namespace="my-agent")
+
+store.put(("users", "42"), "prefs", {"theme": "dark"})
+store.get(("users", "42"), "prefs").value        # {"theme": "dark"}
+store.search(("users",), query="dark")           # BM25 over stored values
+store.list_namespaces()                          # [("users", "42")]
+```
+
+…and inside a graph, the way LangGraph injects it:
+
+```python
+graph = builder.compile(store=AegisStore(namespace="my-agent"))
+
+def remember(state, *, store):
+    store.put(("users", state["user"]), "last", {"seen": "hello"})
+```
+
+`BaseStore` funnels `get` / `put` / `search` / `delete` / `list_namespaces`
+through one abstract `batch(ops)`, so that is all this implements — the
+concrete methods come from the base class and cannot drift from it. `aput`,
+`aget` and friends work too, on a worker thread.
+
+## The mapping
+
+LangGraph addresses items by a hierarchical `namespace: tuple[str, ...]` plus a
+`key`, and searches by namespace *prefix*. AegisDB has a flat `agent_id` that is
+an isolation boundary rather than a path, so the hierarchy is carried in tags:
+
+| | |
+|---|---|
+| `agent_id` | the store's own `namespace=` — one tenant, isolated by the server |
+| tags | a marker, a hash of `(namespace, key)`, and a hash of **every prefix** of the namespace |
+| `data` | JSON: `{"ns": [...], "key": ..., "value": {...}}` |
+
+A tag per prefix is what makes a prefix search an index lookup rather than a
+scan. Tags are hashed because AegisDB caps one at 64 bytes (and 32 per record)
+while a namespace or key can be longer; the readable copy lives in `data`,
+which is also what makes `list_namespaces` possible.
+
+The digest is length-prefixed per segment, so `("a", "bc")` and `("ab", "c")`
+cannot collide — joining on a separator would make them the same string, and
+two namespaces sharing a tag is a cross-namespace read.
+
+**Namespace depth is capped at 29.** Marker + key + one tag per prefix has to
+fit in AegisDB's 32-tag ceiling. Deeper raises `ValueError` naming the limit,
+rather than an `INVALID_REQUEST` that says nothing about namespaces.
+
+## Three things it does not do
+
+**TTL is refused, not ignored.** AegisDB expires only working memory, which is
+a per-session ring buffer rather than a store, so a TTL here would never fire.
+Silently never expiring something a caller asked to expire is a retention
+surprise. Use the server's `forget` op, which ages records out by importance
+and recency — and which the LangGraph API has no way to express.
+
+**No vector indexing.** `query=` runs the server's BM25 index: no embedding
+provider needed, and exact tokens (an error string, a flag, an identifier)
+match well, with the server's relevance score carried through to
+`SearchItem.score`. `index=` is accepted and ignored, because honouring it
+would mean this package owning an embeddings function. A server started with
+`--no-lexical-index` raises a `RuntimeError` naming that flag when a query was
+actually passed — a queryless search keeps working, and any other `NOT_READY`
+is re-raised untouched rather than blamed on an index it never used.
+
+**`filter=` is applied client-side.** AegisDB cannot filter on arbitrary JSON
+fields, so candidates are pulled back and matched here — using *LangGraph's
+own* `_compare_values`, so the semantics are identical to `InMemoryStore`
+rather than a second implementation that drifts. It inherits that function's
+limits too: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` are supported and `$in`
+is not, in both stores alike.
+
+Because filtering happens here, paging does too — asking the server for an
+`offset` would skip rows before they were filtered, so page 2 would silently
+omit matches. An **unfiltered** search does page on the server, so a deep page
+stays a small read.
+
+`search_scan_limit` (default 1000) bounds how many candidates a filtered search
+pulls back; `list_namespaces` is bounded the same way, since AegisDB indexes
+tags but cannot enumerate them. It is **clamped to 1000**, because the server
+clamps `top_k` there and says nothing — a larger value would read as "scans
+more" while changing nothing.
+
+**Past that bound the answer is short and cannot say so.** `search` and
+`list_namespaces` return plain lists, with nowhere to put a flag. A store
+holding more than `search_scan_limit` items can therefore be missing matches
+from a filtered search, or namespaces from a listing. Stated here because it
+cannot be signalled there.
+
+## Isolation
+
+`namespace=` is the AegisDB namespace, enforced by the server. Two stores with
+different ones cannot see each other's items even though they share a server —
+so one AegisDB instance can back many agents, and the LangGraph hierarchy lives
+inside each.
+
+Passing your own `client=` makes *its* `agent_id` authoritative, since that is
+what the server enforces; giving both and disagreeing raises, rather than
+reporting one namespace while writing into another.
+
+## Concurrency
+
+**One store is one connection, and `batch` holds a lock.** The client owns a
+socket and is not thread-safe, while `abatch` runs on a worker thread and
+LangGraph's sync runner executes a superstep's tasks on a pool — so without
+serialising, two nodes touching the store interleave on the same socket and one
+reads the other's response. Concurrent nodes therefore queue; for real
+parallelism, build a store per worker.
+
+Across *processes* nothing here can help: `put` is a read-modify-write and
+AegisDB has no upsert, so two racing writers can leave two records for one key.
+Reads pick deterministically (lowest id) so the store keeps answering
+consistently if that happens.
+
+## Tests
+
+```bash
+make langgraph-test        # from the repo root
+```
+
+Every behaviour meant to match the reference implementation is asserted by
+running the same case against `InMemoryStore` and comparing — an assertion
+written from a reading of the contract would only encode that reading. The
+suite also compiles a real graph with `store=` and lets LangGraph inject it,
+which is the part that would break if the class satisfied the ABC but not the
+runtime's expectations of it.

aegisdb_langgraph-0.8.0/aegisdb_langgraph/__init__.py

@@ -0,0 +1,13 @@
+"""AegisDB as a LangGraph long-term-memory store.
+
+    from aegisdb_langgraph import AegisStore
+
+    store = AegisStore(host="127.0.0.1", port=9470, namespace="my-agent")
+    store.put(("users", "42"), "prefs", {"theme": "dark"})
+
+See `store.py` for the mapping onto AegisDB and the three things it
+deliberately does not do (TTL, vector indexing, server-side filtering).
+"""
+from .store import MAX_NAMESPACE_DEPTH, AegisStore
+
+__all__ = ["AegisStore", "MAX_NAMESPACE_DEPTH"]