Metadata-Version: 2.4
Name: neruva-crewai
Version: 0.2.0
Summary: Drop-in CrewAI memory integration for Neruva agent memory + reasoning substrate. v0.2.0 adds AUTO-PILOT: NeruvaAutoPilot (classify intent + reflect + extract via your LLM) + NeruvaAutoPilotHooks (after_task callback that auto-extracts facts from task output to KG; reflect_on_crew_finish for cross-task self-curation). Plus NeruvaShortTermMemory / NeruvaLongTermMemory / NeruvaEntityMemory / NeruvaStorage as CrewAI memory backends. Substrate stays $0/call (pattern-C).
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: crewai,neruva,agent-memory,memory,ai,llm,multi-agent
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: crewai>=0.30.0
Dynamic: license-file

# neruva-crewai

Drop-in CrewAI memory integration for [Neruva](https://neruva.io) agent
memory + reasoning substrate. Three memory flavors backed by the Neruva
substrate, plus (new in 0.2.0) the auto-pilot surface for proactive
cognitive tool routing.

```bash
pip install neruva-crewai
```

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

- **`NeruvaAutoPilot`** — framework-agnostic core. Pass a callable
  (your CrewAI LLM's `.call` method) and get `classify_intent()`,
  `reflect()`, and `extract_facts()` methods that round-trip through
  the substrate's canonical prompts.
- **`NeruvaAutoPilotHooks`** — bundle of CrewAI task callbacks.
  `after_task` auto-extracts facts from any task output to KG.
  `reflect_on_crew_finish(agent_outputs)` self-curates substrate
  from cross-task results.

Plus **`NeruvaCodeGraph`** (5 sub-ms code-navigation methods) and
**`NeruvaCognitive`** (13 cognitive-primitive methods —
counterfactual rollout / theory-of-mind / schema lifting / EFE
planning / continual K-gram / hierarchical chunking / rule
induction). Callable from any agent tool or task callback.

Pattern-C: substrate stays $0/call. Classification + extraction runs
through YOUR caller LLM.

```python
from crewai import Task, Crew, Agent
from crewai.llm import LLM
from neruva_crewai import (
    NeruvaLongTermMemory,
    NeruvaAutoPilot,
    NeruvaAutoPilotHooks,
)

llm = LLM(model="claude-3-7-sonnet-20250219")
ap = NeruvaAutoPilot(api_key="nv_...", namespace="my_crew",
                     llm_callable=lambda p: llm.call(p))
hooks = NeruvaAutoPilotHooks(ap)

task = Task(
    description="Research X and write a brief",
    agent=agent,
    callback=hooks.after_task,  # auto-extract facts from result
)
crew = Crew(
    agents=[agent], tasks=[task],
    memory=True,
    long_term_memory=NeruvaLongTermMemory(namespace="my_crew", api_key="nv_..."),
)
result = crew.kickoff()

# Optional cross-task reflection
hooks.reflect_on_crew_finish([{"output": str(result)}])
```

## 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 crew 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 crew tool calls
  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.
- **Depth-unlimited nested-belief tracking** — store and retrieve
  chains like `Alice → Bob → Carol thinks X` at any depth, with
  inner-position-swap rejection. Useful for multi-agent crew sims.
- **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.
- **Continual K-gram learning** — provable no-forgetting via
  integer-add commutativity.

## Quick start

```python
from neruva_crewai import NeruvaLongTermMemory
from crewai import Crew

memory = NeruvaLongTermMemory(
    namespace="my_project",         # one per crew / domain
    api_key="nv_...",               # or env NERUVA_API_KEY
)

crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,
    long_term_memory=memory,        # plugged in here
)
```

## Three memory flavors

| Class | What it backs | Underlying substrate |
|---|---|---|
| `NeruvaShortTermMemory` | CrewAI ShortTermMemory (per-run scratchpad) | Records, `kind="short_term"` |
| `NeruvaLongTermMemory` | CrewAI LongTermMemory (cross-run persistent) | Records, `kind="long_term"` |
| `NeruvaEntityMemory` | CrewAI EntityMemory (named entities + relationships) | Records + HD KG triples |

All three persist across process restarts via GCS — no Redis or Postgres setup required.

## Entity memory with triple binding

Use the canonical extraction prompt to extract triples in your own LLM
turn (Claude / GPT / etc), then pass them as metadata:

```python
from neruva_crewai import NeruvaEntityMemory

entity_mem = NeruvaEntityMemory(namespace="my_project", api_key="nv_...")

# After your agent observes a fact about an entity:
entity_mem.save(
    value="Caroline researches adoption agencies",
    metadata={
        "triples": [
            ["caroline", "researches", "adoption_agencies"],
            ["caroline", "works_at", "charity"],
        ],
    },
)

# Later — sub-ms KG entity recall:
results = entity_mem.search("What did Caroline research?", limit=5)
```

Or use Neruva's `agent_remember(extract="managed")` to have the
substrate run extraction for you on every save (server-side,
sub-$0.001/turn typical).

## Why use Neruva instead of CrewAI's default storage?

| Feature | CrewAI default | Neruva |
|---|---|---|
| Persists across process restart | ChromaDB local file | GCS-backed, multi-machine |
| Cross-crew recall | Manual setup | One namespace per crew, instant federation |
| Knowledge-graph entity tracking | LLM-based, opaque | HD KG, sub-ms cosine, deterministic |
| Causal queries / Pearl do-operator | Not offered | `agent_causal_query` |
| Provable replay | Not offered | `agent_snapshot` + `agent_restore` |
| GDPR forget by user | Manual | `user_id` auto-folds, one-call forget |
| Portability | None | `.neruva` zip container |

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