Metadata-Version: 2.4
Name: neruva-langgraph
Version: 0.1.0
Summary: Drop-in LangGraph integration for Neruva agent memory. Wraps BaseCheckpointSaver + BaseStore to persist graph checkpoints and cross-thread KV state into the Neruva substrate (records + KG + federated agent_context). One-line install, works with every LangGraph StateGraph.
Author-email: Clouthier Simulation Labs <info@neruva.io>
License: MIT
Project-URL: Homepage, https://neruva.io/integrations/
Project-URL: Documentation, https://neruva.io/docs/
Project-URL: Source, https://github.com/CloutSimLabs/neruva
Keywords: langgraph,langchain,neruva,agent-memory,memory,checkpoint,ai,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: langgraph>=0.2.0
Dynamic: license-file

# neruva-langgraph

[![PyPI](https://img.shields.io/badge/pypi-neruva--langgraph-blue)](https://pypi.org/project/neruva-langgraph/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

Drop-in LangGraph integration for [Neruva](https://neruva.io) agent
memory. Two wrappers cover the canonical LangGraph plug points:
graph checkpoints and the cross-thread KV store.

```bash
pip install neruva-langgraph
```

## NeruvaCheckpointSaver

Persists every graph checkpoint into Neruva Records. One namespace per
`thread_id`, so each conversation gets its own replayable timeline.
Drop into any `StateGraph.compile()`:

```python
from langgraph.graph import StateGraph
from neruva_langgraph import NeruvaCheckpointSaver

graph = builder.compile(
    checkpointer=NeruvaCheckpointSaver(api_key="nv_..."),
)
graph.invoke(
    {"input": "hello"},
    config={"configurable": {"thread_id": "user_alice"}},
)
```

## Realistic example -- multi-turn StateGraph with persistent checkpoints

```python
from typing import TypedDict
from langgraph.graph import StateGraph, END
from langchain_anthropic import ChatAnthropic
from neruva_langgraph import NeruvaCheckpointSaver

class State(TypedDict):
    messages: list

def call_model(state: State) -> State:
    llm = ChatAnthropic(model="claude-opus-4-7")
    state["messages"].append(llm.invoke(state["messages"]))
    return state

builder = StateGraph(State)
builder.add_node("model", call_model)
builder.set_entry_point("model")
builder.add_edge("model", END)
graph = builder.compile(checkpointer=NeruvaCheckpointSaver())
graph.invoke({"messages": ["What did I tell you last week?"]},
             config={"configurable": {"thread_id": "user_alice"}})
```

## NeruvaContextStore

LangGraph's `BaseStore` for cross-thread KV (e.g. user preferences,
shared facts). Backed by Records + agent_recall for semantic search:

```python
from neruva_langgraph import NeruvaContextStore

store = NeruvaContextStore(api_key="nv_...")
graph = builder.compile(
    checkpointer=NeruvaCheckpointSaver(),
    store=store,
)
store.put(("users", "alice"), "profile", {"city": "Toronto"})
hit = store.get(("users", "alice"), "profile")
print(hit)   # -> Item(value={'city': 'Toronto'}, ...)
```

## Why Neruva instead of LangGraph's built-in checkpointers?

| Feature | LangGraph defaults | Neruva |
|---|---|---|
| Persists across process restart | sqlite / postgres setup | Built-in (GCS-backed) |
| Cross-session recall | No | Yes via `namespaces=[...]` |
| Vector / semantic store search | No (KV only) | Yes via `agent_recall` |
| Auto fact extraction (KG) | No | Auto (`hd_kg_extraction_prompt`) |
| Determinism / replayability | No | Bit-identical from seed |
| Portability | DB-locked | `.neruva` zip container |

[Get an API key](https://app.neruva.io) - [Docs](https://neruva.io/docs/) - [Status](https://status.neruva.io)
