Metadata-Version: 2.4
Name: mubit-agno
Version: 0.6.0
Summary: Agno DB and toolkit integration backed by MuBit memory engine
Author: Mubit AI
License-Expression: Apache-2.0
Keywords: agno,ai-agent,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: agno
Requires-Dist: agno<3,>=2.6; extra == 'agno'
Provides-Extra: dev
Requires-Dist: agno<3,>=2.6; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# mubit-agno

Agno (v2) DB and toolkit integration backed by the [MuBit](https://mubit.ai) memory engine.

Targets Agno v2's `agno.db.base.BaseDb`. (The pre-2.0 adapter implemented
`agno.memory.v2.db.base.MemoryDb`, which was removed in Agno 2.0.)

## Installation

```bash
pip install mubit-agno[agno]   # installs agno>=2.6,<3
```

## Quick Start

### DB — Persistent User Memory + Sessions

Use `MubitAgnoDb` as the `db` for an Agno agent. User memories persist to
MuBit and sessions are mirrored as MuBit checkpoints:

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from mubit_agno import MubitAgnoDb

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=MubitAgnoDb(
        api_key="mbt_...",
        session_id="user-session-1",
        user_id="user-42",
    ),
    enable_user_memories=True,
)

agent.run("Remember that I prefer concise answers")
agent.run("What are my preferences?")  # Recalls from MuBit
```

`MubitAgnoDb` is a genuine `BaseDb` subclass: user-memory and session methods
are MuBit-backed; the remaining BaseDb surfaces (metrics, evals, knowledge,
culture, learnings, traces, spans) use lightweight local storage so the class
is fully concrete.

### Toolkit — Direct Memory Tools

Give agents LLM-callable tools for fine-grained memory control:

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from mubit_agno import MubitToolkit

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[MubitToolkit(api_key="mbt_...", session_id="research-run-1")],
)

# Tools: mubit_remember, mubit_recall, mubit_reflect, mubit_get_context,
# mubit_checkpoint, mubit_record_outcome, mubit_diagnose, mubit_memory_health.
# mubit_recall surfaces `citations` + `entry_ids` so the agent can close the
# loop with mubit_record_outcome(entry_ids=...).
agent.run("Store a lesson: always validate input before processing")
agent.run("What lessons have we learned?")
```

### Convenience Wrapper — Full Integration

`MubitAgnoMemory` bundles both surfaces and adds MAS extensions:

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from mubit_agno import MubitAgnoMemory

mubit = MubitAgnoMemory(api_key="mbt_...", session_id="crew-run-1", user_id="user-42")

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=mubit.as_db(),
    tools=[mubit.as_toolkit()],
    enable_user_memories=True,
)

# MAS coordination
mubit.register_agent("researcher", role="researcher",
                     read_scopes=["fact", "lesson"], write_scopes=["trace", "lesson"])
mubit.checkpoint("Phase 1", "Research complete")
```

## Closing the Attribution Loop (v0.7.0)

Recall, act, then credit the exact entries that helped — verified-in-production
lessons get a ranking boost:

```python
result = mubit.recall("deployment runbook")
entry_ids = mubit.extract_entry_ids(result, cited_only=True)  # only cited evidence
mubit.record_outcome(
    "success",
    entry_ids=entry_ids,
    verified_in_production=True,
    rationale="Followed the recalled runbook and the deploy passed",
)

# Per-step process rewards
mubit.record_step_outcome("validate-inputs", outcome="success")
```

Writes are idempotent: user-memory upserts thread both an `upsert_key` and an
`idempotency_key`, so retried writes don't double-count reinforcement.

## Extended Features

The `MubitAgnoMemory` wrapper provides full MAS capabilities:

- **Recall**: `recall(query)` — evidence + citations + entry_ids
- **Context**: `get_context(query)` — pre-assembled memory context
- **Reflection**: `reflect()` — extract lessons from evidence
- **Lessons**: `lessons()` / `learned()` / `forget()`
- **Checkpoints**: `checkpoint(label, snapshot)` — durable snapshots
- **Outcomes**: `record_outcome(outcome, entry_ids=..., verified_in_production=...)`
- **Step Outcomes**: `record_step_outcome(step_id)` — per-step rewards
- **Strategies**: `surface_strategies()` — pattern discovery
- **Agent Registration**: `register_agent(id, role, scopes)` — MAS setup
- **Handoffs**: `handoff(from, to, content)` — agent coordination
- **Feedback**: `feedback(handoff_id, verdict)` — async evaluation
- **Archive**: `archive(content, kind)` / `dereference(ref_id)`
- **Diagnostics**: `diagnose(error)` — failure analysis
- **Health**: `memory_health()` — quality assessment

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MUBIT_ENDPOINT` | MuBit server URL | `http://127.0.0.1:3000` |
| `MUBIT_API_KEY` | MuBit API key | (empty for local dev) |

## License

Apache-2.0
