Metadata-Version: 2.4
Name: neruva-langchain
Version: 0.2.0
Summary: Drop-in LangChain integration for Neruva agent memory substrate. v0.2.0 adds AUTO-PILOT: NeruvaAutoPilot (classify intent + reflect + extract via your LangChain LLM) and NeruvaAutoPilotCallback (BaseCallbackHandler). Plus NeruvaChatMessageHistory + NeruvaContextRetriever for memory + KG recall, NeruvaCodeGraph (5 code nav methods), NeruvaCognitive (13 cognitive primitives). Pattern-C: substrate stays $0/call.
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: langchain,neruva,agent-memory,memory,ai,llm,rag
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: langchain-core>=0.3.0
Dynamic: license-file

# neruva-langchain

Drop-in LangChain integration for [Neruva](https://neruva.io) agent
memory + reasoning substrate. Three wrappers cover the common LangChain
plug points: chat history, document retriever, and (new in 0.2.0)
auto-pilot intent routing + reflection.

```bash
pip install neruva-langchain
```

## What's new in 0.2.0 — Auto-pilot

Two new exports complete the auto-pilot integration. The agent now
proactively uses the right Neruva cognitive tool (counterfactual /
analogy / theory-of-mind / rule induction / EFE planning / causal /
etc.) based on the user's intent — without you wiring each one.

- **`NeruvaAutoPilot`** — framework-agnostic core. Pass your
  LangChain LLM; get back `classify_intent()`, `reflect()`, and
  `extract_facts()` methods that round-trip through the substrate's
  canonical prompts (Layer 2 / 3 / 1 respectively).
- **`NeruvaAutoPilotCallback`** — `BaseCallbackHandler` subclass that
  auto-fires intent classification on `on_chain_start` and (opt-in)
  reflection on `on_chain_end` after every 10 turns. Drop into any
  chain via `callbacks=[NeruvaAutoPilotCallback(...)]`.

Plus **`NeruvaCodeGraph`** (5 sub-ms code-navigation methods —
callers / callees / class_of / module_of / imports) and
**`NeruvaCognitive`** (13 cognitive-primitive methods —
counterfactual rollout / theory-of-mind / schema lifting / EFE
planning / continual K-gram / hierarchical chunking / rule
induction). Thin wrappers over `NeruvaClient` so they're callable
from anywhere in your chain.

Pattern-C: substrate stays $0/call. The classification + extraction
work runs in YOUR LangChain LLM's turn.

```python
from langchain_anthropic import ChatAnthropic
from neruva_langchain import NeruvaAutoPilot, NeruvaAutoPilotCallback

llm = ChatAnthropic(model="claude-3-7-sonnet-20250219")
ap = NeruvaAutoPilot(api_key="nv_...", namespace="my_app", llm=llm)

# Layer 2 — classify a user message
result = ap.classify_intent("what if we had picked Mailgun?")
# {'primary_intent': 'counterfactual', 'confidence': 0.92,
#  'suggested_tool': 'agent_counterfactual_rollout', ...}

# Layer 3 — reflect over recent turns + auto-write durable records
ap.reflect(recent_turns=[
    {"role": "user", "text": "ship the ticket system"},
    {"role": "assistant", "text": "shipped 5 phases including notes + audit"},
])
# Auto-writes decisions/facts/mistakes to substrate.

# Or auto-fire via callback in any LCEL chain / agent:
chain = prompt | llm | parser
result = chain.invoke({"q": "..."}, config={"callbacks": [
    NeruvaAutoPilotCallback(api_key="nv_...", namespace="my_app", llm=llm,
                            enable_route=True, enable_reflect=True),
]})
```

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

The substrate this adapter wraps has gained a lot since the last release.
All of it is available via the same `agent_*` API the wrappers already
call, so existing code keeps working — new capabilities just become
available.

- **Deterministic replay** — every query is bit-identical across reruns
  from the same seed. Replay any past 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. Natural fit for tool-calling
  chains that need a specific output schema.
- **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.

## NeruvaChatMessageHistory

Auto-records every turn into the Neruva Records substrate. Drop into any
LangChain primitive that accepts a `BaseChatMessageHistory`:

```python
from neruva_langchain import NeruvaChatMessageHistory

history = NeruvaChatMessageHistory(
    api_key="nv_...",          # or env NERUVA_API_KEY
    namespace="user_alice",    # one per user / session
)

history.add_user_message("My name is Alice and I live in Toronto.")
history.add_ai_message("Nice to meet you, Alice!")

# Later — even after process restart, substrate-backed:
print(history.messages)
```

## Use with RunnableWithMessageHistory (modern pattern)

```python
from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.runnables.history import RunnableWithMessageHistory
from neruva_langchain import NeruvaChatMessageHistory

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}"),
])
chain = prompt | ChatAnthropic(model="claude-opus-4-7")

chain_with_history = RunnableWithMessageHistory(
    chain,
    lambda session_id: NeruvaChatMessageHistory(namespace=session_id),
    input_messages_key="input",
    history_messages_key="history",
)
chain_with_history.invoke(
    {"input": "What did I tell you about my project last week?"},
    config={"configurable": {"session_id": "user_alice"}},
)
```

## NeruvaContextRetriever

`BaseRetriever` for `RetrievalQA` chains. Returns `Document` objects
sourced from federated `agent_recall`:

```python
from neruva_langchain import NeruvaContextRetriever
from langchain.chains import RetrievalQA
from langchain_anthropic import ChatAnthropic

retriever = NeruvaContextRetriever(
    api_key="nv_...",
    namespaces=["session_a", "session_b"],   # multi-session fan-out
)
qa = RetrievalQA.from_chain_type(
    llm=ChatAnthropic(model="claude-opus-4-7"),
    retriever=retriever,
)
qa.invoke("Where does Alice work?")
```

## Why use Neruva instead of LangChain's built-in memory?

| Feature | LangChain default | Neruva |
|---|---|---|
| Persists across process restart | Manual setup | Built-in (GCS-backed) |
| Cross-session recall | No | Yes via `namespaces=[...]` |
| Fact extraction (KG) | No | Auto (`hd_kg_extraction_prompt` + caller LLM) |
| GDPR forget by user | Manual | `user_id=` auto-folds, one-call forget |
| Determinism / replayability | No | Bit-identical from seed |
| Portability | Pickle | `.neruva` zip container |

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