Metadata-Version: 2.4
Name: mubit-crewai
Version: 0.6.0
Summary: CrewAI memory backend backed by MuBit memory engine
Author: Mubit AI
License-Expression: Apache-2.0
Keywords: ai-agent,crewai,memory,mubit,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Requires-Dist: mubit-integration-base<0.7,>=0.6.0
Requires-Dist: mubit-sdk<1.0,>=0.9.0
Provides-Extra: crewai
Requires-Dist: crewai<2,>=1.14.6; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: crewai<2,>=1.14.6; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# `mubit-crewai`

CrewAI memory backend backed by [MuBit](https://mubit.ai).

This adapter provides a class that satisfies CrewAI's `crewai.memory.storage.backend.StorageBackend` protocol (verified against `crewai>=1.14.6,<2`), routing all memory operations through MuBit's control plane. Also includes an extended `MubitCrewMemory` class with MAS coordination helpers and the outcome-attribution loop.

## Install

```bash
pip install mubit-crewai[crewai]
```

## Basic usage

### Drop-in StorageBackend

```python
from mubit_crewai import MubitStorage
from crewai import Crew
from crewai.memory import Memory

storage = MubitStorage(api_key="mbt_...", session_id="crew-run-1")
crew = Crew(
    agents=[...],
    memory=Memory(storage=storage),
)
```

### Extended MuBit features

```python
from mubit_crewai import MubitCrewMemory, extract_entry_ids

memory = MubitCrewMemory(api_key="mbt_...", session_id="crew-run-1")
crew = Crew(agents=[...], memory=memory.as_crew_memory())

# Extended:
context = memory.get_context("What do we know about the customer?")
memory.checkpoint("Finished research phase")
memory.handoff("researcher", "writer", "Here are the findings...")
```

### Outcome-attribution loop (v0.7.0)

Close the `recall -> act -> credit` loop so the entries that helped get
reinforced, and process rewards land per step:

```python
result = memory.recall("How did we resolve the last billing dispute?")
entry_ids = extract_entry_ids(result)       # reference_ids of recalled evidence
# ... the crew acts on the recalled context ...
memory.record_outcome(
    "task-123", "success",
    entry_ids=entry_ids,                     # credit the entries that helped
    verified_in_production=True,             # boost lessons confirmed in live use
)
memory.record_step_outcome("plan", outcome="success")  # per-step process reward
```

## StorageBackend interface

Implements the full `StorageBackend` protocol — `save`, `search`, `delete`,
`update`, `get_record`, `list_records`, `get_scope_info`, `list_scopes`,
`list_categories`, `count`, `reset`, plus async `asave`/`asearch`/`adelete`.

| Method | MuBit mapping |
| --- | --- |
| `save(records)` | `control.ingest` (intent from categories, idempotency keyed by record id) |
| `search(query_embedding, ...)` | `control.query`, returns `(MemoryRecord, score)` tuples |
| `delete(...)` / `reset()` | local-index delete / `control.delete_run` |

A legacy `save(value, metadata, agent_id)` / `search(query, limit, score_threshold)`
shim is retained for older callers.

## Intent inference

The `memory_type` metadata key maps to MuBit intents:

| `memory_type` | MuBit intent |
| --- | --- |
| `short_term` | `trace` |
| `long_term` | `lesson` |
| `entity` | `fact` |

## MuBit extension methods

- `remember()` / `recall()` — direct write/read (idempotent writes, citations on recall)
- `get_context()` — assembled context retrieval
- `checkpoint()` — save memory state snapshot
- `record_outcome()` — outcome feedback for tasks (with `entry_ids` + `verified_in_production`)
- `record_step_outcome()` — per-step process reward
- `learned()` — persist a confirmed lesson
- `surface_strategies()` — strategy clusters from lessons
- `register_agent()` — MAS agent registration
- `handoff()` — agent-to-agent handoff
- `diagnose()` — failure-path lesson surfacing

Module helpers `extract_entry_ids(result)` and `extract_citations(result)` are
re-exported for closing the attribution loop on a `recall()` result.

## Config

| Parameter | Default | Purpose |
| --- | --- | --- |
| `endpoint` | `http://127.0.0.1:3000` | MuBit HTTP endpoint |
| `api_key` | `""` | MuBit API key |
| `session_id` | `"default"` | Session/run scope |
| `agent_id` | `"crewai"` | Default agent ID |

For tests, inject `mubit_client` directly.

## Development

```bash
PYTHONPATH=sdk/python/mubit-sdk/src:integrations/python \
python3 -m unittest integrations.python.mubit_crewai.tests.test_storage -v
```

## License

Apache-2.0
