Metadata-Version: 2.4
Name: mambo-agents
Version: 0.2.0a4
Summary: AI Agent framework on LangChain/LangGraph — multi-backend filesystem, sub-agent scheduling, conversation summarization, security review, and skills system out of the box.
Project-URL: Homepage, https://github.com/RAmenLch/mambo_agents
Project-URL: Source, https://github.com/RAmenLch/mambo_agents
Project-URL: Issues, https://github.com/RAmenLch/mambo_agents/issues
Author: RAmenLch
License: MIT License
        
        Copyright (c) 2026 RAmenLch
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,ai,filesystem,langchain,langgraph,llm,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: langchain<2,>=1.2
Requires-Dist: langgraph<2,>=1.1
Requires-Dist: paramiko<5,>=4.0
Requires-Dist: tree-sitter-c<0.25,>=0.24.2
Requires-Dist: tree-sitter-cpp<0.24,>=0.23.4
Requires-Dist: tree-sitter-go<0.26,>=0.25.0
Requires-Dist: tree-sitter-java<0.24,>=0.23.5
Requires-Dist: tree-sitter-javascript<0.26,>=0.25
Requires-Dist: tree-sitter-rust<0.25,>=0.24.2
Requires-Dist: tree-sitter-typescript<0.24,>=0.23
Requires-Dist: tree-sitter<0.26,>=0.25
Requires-Dist: wcmatch<10,>=8.0
Description-Content-Type: text/markdown



# Mambo Agents

**AI Agent framework built on LangChain/LangGraph** — multi-backend filesystem, sub-agent parallel scheduling, conversation summarization, security review, skills system, and more, out of the box.  
**基于 LangChain/LangGraph 的 AI Agent 框架** — 提供多后端文件系统、子代理并行调度、对话摘要、安全审查、技能系统等开箱即用的能力。  
> 📖 **English** | [中文](README.cn.md)

> This project draws architectural inspiration from [deepagents](https://github.com/langchain-ai/deepagents), with independent refactoring and extensions. See [comparison with deepagents](docs/deepagents_reference.md).

## Key Features

- **Multi-backend Filesystem** — `StateBackend` (in-memory), `LocalBackend` (local disk), `SshBackend` (remote SSH), `HybridWorkspaceBackend` (hybrid routing), unified through `BackendProtocol`
- **Sub-agent System** — sync/async sub-agents with parallel scheduling, streaming events, and isolated context windows
- **Conversation Summarization** — automatic long-history compaction with chained summaries and optional backend persistence
- **Task Planning** — `MamboPlanMiddleware` provides structured TODO lists, deeply integrated with the summarization system
- **AI Security Review** — pre-approve tool calls with a cheap model, escalating only high-risk operations to human review
- **Skills System** — progressive disclosure of skills, with multi-source overlay support
- **Memory System** — persistent context loaded from `AGENTS.md`, with AI self-learning write-back
## Quick Start

```bash
pip install mambo-agents
```

```python
from mambo_agents import create_mambo_agent, StateBackend
from langchain_core.messages import HumanMessage

agent = create_mambo_agent(
    "gpt-4o",
    backend=StateBackend(),
    include_general_purpose=True,
)
result = agent.invoke({"messages": [HumanMessage("Create a hello.py file")]})
```

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│                    create_mambo_agent()                   │
│                                                          │
│  ┌─────────────┐  ┌──────────┐  ┌────────────────────┐  │
│  │   Backend   │  │  Model   │  │    Middleware Stack │  │
│  │  Protocol   │  │ (LLM)    │  │                    │  │
│  │             │  │          │  │ BackendTools       │  │
│  │ State       │  │          │  │ Skills             │  │
│  │ Local       │  │          │  │ Memory             │  │
│  │ SSH         │  │          │  │ Summarization      │  │
│  │ TempWs      │  │          │  │ Planning           │  │
│  └─────────────┘  └──────────┘  │ SubAgents          │  │
│                                 │ AsyncSubAgents     │  │
│                                 │ SecurityReview     │  │
│                                 │ Patch + Reorder    │  │
│                                 └────────────────────┘  │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │              LangGraph CompiledGraph                │ │
│  │  invoke() · astream() · astream_events()            │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
```

## Docs

- [Detailed Usage Guide](docs/usage.md) — API reference, configuration, advanced usage
- [Comparison with deepagents](docs/deepagents_reference.md) — architectural differences, feature mapping, design trade-offs

## Related Projects

- [MamboChat](https://github.com/RAmenLch/mambochat) — Full-featured Web UI built on Mambo Agents

## License

MIT License
