Metadata-Version: 2.4
Name: becomer-agents
Version: 0.1.0
Summary: Multi-tenant agent memory framework powered by BECOMER — zero tokens, any LLM
License-Expression: MIT
Project-URL: Homepage, https://becomer.net
Project-URL: Documentation, https://becomer.net/docs.html
Project-URL: Repository, https://github.com/Becomer-net/Becomer.net
Keywords: llm,memory,agents,langchain,multi-agent,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: becomer>=0.1.2
Requires-Dist: rich>=13.0
Provides-Extra: langchain
Requires-Dist: langchain>=0.2; extra == "langchain"
Requires-Dist: langchain-openai>=0.1; extra == "langchain"
Provides-Extra: all
Requires-Dist: langchain>=0.2; extra == "all"
Requires-Dist: langchain-openai>=0.1; extra == "all"

# becomer-agents

Multi-tenant agent memory framework powered by [BECOMER](https://becomer.net).

Zero tokens per recall. Any LLM. Shared memory across agents without message passing.

```
pip install becomer-agents
```

---

## Why this exists

LangChain, LlamaIndex, CrewAI, AutoGen — they all have memory. But:

- Memory dies when the process ends
- Memory is tied to one LLM provider
- Agents can't share memory without message passing
- Every recall burns 500–7,000 tokens on an LLM reasoning pass

`becomer-agents` fixes all four. Memory persists across sessions, works across every LLM simultaneously, agents share a namespace without coordination code, and retrieval costs zero tokens.

---

## How namespaces work

Every agent gets a namespace: `{task_id}.{role}`

```
task-abc.researcher   ← researcher agent's private memory
task-abc.executor     ← executor agent's private memory
task-abc.shared       ← readable and writable by all agents
```

Shared memory without message passing. No state files. No coordination logic.

---

## Quick start — multi-agent pipeline

```python
import os
from becomer_agents import MultiAgentPipeline

def researcher(task, own_ns, shared_ns):
    own_ns.store("API endpoint: POST /v1/payments, OAuth2 bearer")
    own_ns.store("Rate limit: 100 req/s")
    return "Research complete"

def executor(task, own_ns, shared_ns):
    # Recall what researcher found — no message passing
    findings = shared_ns.recall("payment API endpoint and auth", top_k=5)
    own_ns.store(f"Implementation plan based on {len(findings)} findings")
    return "Plan written"

def reviewer(task, own_ns, shared_ns):
    everything = shared_ns.recall("what was found and planned?", top_k=8)
    own_ns.store("Review: APPROVED")
    return "Approved"

pipeline = MultiAgentPipeline(
    api_key=os.environ["BECOMER_API_KEY"],
    task_id="payments-task-001",
    roles=["researcher", "executor", "reviewer"],
)

results = pipeline.run(
    task="Build a payments integration",
    agents={
        "researcher": researcher,
        "executor":   executor,
        "reviewer":   reviewer,
    },
)
```

The terminal shows a live memory activity feed as agents store and recall.

---

## Self-improving agents

```python
from becomer_agents import SelfImprovingPipeline

pipeline = SelfImprovingPipeline(
    api_key=os.environ["BECOMER_API_KEY"],
    task_id="optimizer-001",
)

def my_agent(task, context):
    # context = what worked in previous iterations
    # use it to choose a better approach this time
    approach = "zero-shot" if not context else "few-shot + CoT"
    score = run_eval(task, approach)
    return {"approach": approach, "score": score, "output": "..."}

for i in range(5):
    result = pipeline.run_iteration(
        task="classify customer sentiment",
        fn=my_agent,
    )
    print(f"Iteration {i+1}: {result['score']:.0%} — {result['approach']}")

pipeline.finish()
```

Each iteration stores its outcome. The next iteration recalls what scored highest. The system compounds in intelligence across runs — zero extra tokens.

---

## LangChain drop-in

```python
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI
from becomer_agents import BecomerMemory

chain = ConversationChain(
    llm=ChatOpenAI(model="gpt-4o"),
    memory=BecomerMemory(
        api_key=os.environ["BECOMER_API_KEY"],
        user_id="alice-123",   # per-user isolation
    ),
)
```

Memory persists across sessions automatically. One master key covers unlimited users via `user_id`.

---

## Multi-tenant — one key, many users

```python
from becomer_agents import AgentNamespace

# Alice's agent
alice = AgentNamespace(api_key, task_id="app", role="alice-123")
alice.store("Alice prefers TypeScript and dark mode")

# Bob's agent — completely isolated
bob = AgentNamespace(api_key, task_id="app", role="bob-456")
bob.recall("preferences")  # → [] — can't see Alice's memories
```

Isolation is enforced at the database level by BECOMER, not just application code.

---

## Run the demo

Works with a BECOMER key only — no LLM keys needed:

```bash
pip install becomer-agents rich
export BECOMER_API_KEY=bcm_your-key-here
python examples/demo.py
```

Get a free key at [becomer.net/signup.html](https://becomer.net/signup.html) (1,000 calls/month free).

---

## Installation

```bash
# Core (no LangChain)
pip install becomer-agents

# With LangChain support
pip install "becomer-agents[langchain]"
```

Requires Python 3.10+.

---

## Best practices

Following [BECOMER's best practices](https://becomer.net/docs.html#bestpractices) gives the best recall quality:

1. **Store atomic facts** — one fact per `store()` call
2. **Use specific queries** — `"what is the user's job title?"` not `"what do they do?"`
3. **Anchor entity names** — `"Alice prefers TypeScript"` not `"she prefers TypeScript"`
4. **Store signal not noise** — would this be useful in 3 months?
5. **Call `sync()` at session end** — consolidates working memory
6. **Use consistent `user_id`** — different string = different namespace

---

## Architecture

```
becomer-agents
├── AgentNamespace        task_id + role → BECOMER user_id
├── PipelineNamespaces    manages all namespaces for a run
├── MultiAgentPipeline    sequential agents with shared memory
├── SelfImprovingPipeline iterates, recalls best past approaches
├── PipelineVisualizer    rich terminal display
├── BecomerMemory         LangChain BaseMemory drop-in
└── BecomerAgentMemory    episodic + semantic memory for agents
```

Memory layer: [BECOMER API](https://becomer.net) — 94.4% LongMemEval, zero tokens per recall.

---

## Links

- BECOMER API: [becomer.net](https://becomer.net)
- Docs: [becomer.net/docs.html](https://becomer.net/docs.html)
- Free API key: [becomer.net/signup.html](https://becomer.net/signup.html)
- GitHub: [github.com/Becomer-net/Becomer.net](https://github.com/Becomer-net/Becomer.net)

MIT License
