Metadata-Version: 2.4
Name: neruva-langgraph
Version: 0.1.1
Summary: Drop-in LangGraph integration for Neruva. Wraps BaseCheckpointSaver + BaseStore to persist graph checkpoints and cross-thread KV state into the Neruva substrate. Substrate (v0.5.7) adds typed-shape context dispatch, tenant-specific PII rules, depth-unlimited nested-belief tracking, counterfactual rollouts, EFE planner, continual learning. Deterministic from seed (bit-identical replay). 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
```

## What's new in the substrate (v0.5.7, May 2026)

The substrate this adapter wraps has gained a lot since the last release.
Existing code keeps working — new capabilities are just available.

- **Deterministic replay** — every query is bit-identical across reruns
  from the same seed. Replay any past graph state for audit or debugging.
- **Typed-shape context** — pull structured JSON from records with
  per-field citations. `{question, shape: {field: type}}` → typed
  result without an LLM at query time.
- **Tenant-specific PII rules** — register your custom ID formats
  (employee codes, patient codes, order IDs) from 3-5 examples. The
  substrate redacts them automatically. Sub-microsecond per span.
- **Depth-unlimited nested-belief tracking** — store and retrieve
  chains like `Alice → Bob → Carol thinks X` at any depth, with
  inner-position-swap rejection.
- **Counterfactual rollouts** — "what if action k had been a' instead?"
  Replay an action sequence with one step substituted.
- **Active inference planning** — score candidate action sequences
  by KL distance to a goal-marginal. Caller-owned dynamics.
- **Continual K-gram learning** — provable no-forgetting via
  integer-add commutativity; repeated `train()` calls accumulate.

## 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)
