mangaba 3.3.0

Professional multi-agent AI framework with ReAct reasoning, RAG, memory, and function calling

🥭 Mangaba AI

Framework profissional de orquestração multi-agente com ReAct reasoning, function calling nativo, RAG, memória persistente, protocolos A2A/MCP, vector stores avançadas e suporte resiliente a múltiplos provedores LLM.

Alternativa leve e completa a CrewAI + LangChain em um único pacote, com interoperabilidade real entre provedores, arquitetura resiliente e comunicação entre agentes via protocolos padrão.

✨ Destaques v3.3.0

• 🤝 Protocolos A2A & MCP — Agent-to-Agent messaging com request/response/broadcast + Multi-Context Protocol para contextos hierárquicos entre agentes
• 🗄️ Vector Stores Avançadas — ChromaDB, PostgreSQL+pgvector, Redis+RediSearch, SQLite + factory create_vectorstore() para troca transparente
• 🧩 Prompt Templates — PromptTemplate, ChatPromptTemplate, SystemPromptBuilder para engenharia de prompt reutilizável
• 📋 Task Planner — Decomposição automática de tarefas complexas em planos de execução com dependências
• 🧰 Toolkits — Agrupamento lógico de ferramentas com BaseToolkit, FileToolkit, WebToolkit
• 🤗 HuggingFace Embeddings — Sentence-transformers como terceiro provedor de embedding
• 👤 Entity Memory — Rastreamento de entidades e relacionamentos entre interações
• 📊 UsageTracker — Controle acumulativo de tokens por provedor em toda a execução
• ⚙️ Config System — Configuração unificada via Config class com suporte a .env e JSON
• 🔄 CallbackManager — Gerencie callbacks customizados com filtro por tipo de evento

Features consolidadas (desde v3.0)

• 🚀 OpenRouter Native Support — Roteamento dinâmico com fallback automático entre modelos
• 🔄 Multi-Provider Interoperability — Misture agentes de diferentes provedores (ex: Gemini + Llama) na mesma Crew
• 🧠 ReAct Reasoning — Loop Thought→Action→Observation com function calling nativo
• 🤖 5 Provedores LLM — Google Gemini, OpenAI GPT, Anthropic Claude, HuggingFace e OpenRouter
• 👥 4 Processos de Crew — Sequential, Hierarchical, Parallel (asyncio), Consensual
• 🔧 Tool System — @tool decorator, Pydantic schemas, JSON schema automático para LLM
• 📚 RAG Pipeline — Document loaders, text splitters, embeddings, vector store, retriever
• 💾 Memória — Curto prazo (sliding window), longo prazo (SQLite), entidades
• 🛡️ Guardrails — Validação de tamanho, filtro de conteúdo, schema validation
• 📊 Observabilidade — EventBus com 22+ tipos de evento, callbacks console/arquivo
• 🔄 Workflow Engine — Pipelines com stages sequenciais, paralelos e condicionais
• ⚡ Cache & Retry — Cache LRU + disco (SQLite), retry com backoff exponencial + fallback automático

🚀 Instalação

pip install mangaba

# Com RAG e embeddings
pip install mangaba[all]

# Desenvolvimento
pip install mangaba[dev]

⚡ Quick Start

Agente simples com ferramenta

from mangaba.core import Agent, Task, Crew, Process, tool
from mangaba.core.types import LLMConfig

@tool
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

researcher = Agent(
    role="Research Analyst",
    goal="Find accurate information",
    backstory="Expert researcher with 10 years of experience",
    tools=[search],
    llm_config=LLMConfig(provider="google", model="gemini-2.5-flash", api_key="sua-chave"),
)

task = Task(
    description="Research the latest AI trends in 2026",
    expected_output="A list of the top 5 trends with explanations",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[task],
    process=Process.SEQUENTIAL,
)

result = crew.kickoff()
print(result.final_output)

Multi-Provider Crew com fallback

from mangaba.core import Agent, Task, Crew
from mangaba.core.crew import Process
from mangaba.core.types import OpenRouterConfig, LLMConfig

pesquisador = Agent(
    role="Pesquisador",
    goal="Analisar vulnerabilidades",
    llm_config=OpenRouterConfig(
        provider="openrouter",
        model=[
            "google/gemini-2.5-flash",
            "anthropic/claude-3.5-sonnet"
        ],
        api_key="SUA_KEY"
    )
)

revisor = Agent(
    role="Revisor",
    goal="Revisar análise técnica",
    llm_config=LLMConfig(
        provider="hf",
        model="meta-llama/Meta-Llama-3-8B-Instruct",
        api_key="SUA_KEY"
    )
)

task = Task(
    description="Explique buffer overflow",
    expected_output="Análise técnica detalhada",
    agent=pesquisador,
)

review = Task(
    description="Revise a análise",
    expected_output="Pontos fortes e fracos",
    agent=revisor,
)

crew = Crew(
    agents=[pesquisador, revisor],
    tasks=[task, review],
    process=Process.SEQUENTIAL,
)

result = crew.kickoff()
print(result.final_output)

Pipeline com stages

from mangaba import Pipeline, Stage, ParallelStage

pipeline = Pipeline(stages=[
    Stage("research", [research_task]),
    ParallelStage("analysis", [task_a, task_b]),
    Stage("report", [write_task]),
])

result = pipeline.run({"topic": "AI"})

RAG (Retrieval-Augmented Generation)

from mangaba.rag import TextLoader, RecursiveTextSplitter, RAGChain, Retriever
from mangaba.embeddings import OpenAIEmbedding
from mangaba.vectorstores import InMemoryVectorStore

docs = TextLoader("data.txt").load()
chunks = RecursiveTextSplitter(chunk_size=500).split_documents(docs)

embedding = OpenAIEmbedding(api_key="YOUR_KEY")
store = InMemoryVectorStore(embedding)
store.add(chunks)
retriever = Retriever(embedding=embedding, vector_store=store)

from mangaba.core.llm import create_llm_client
llm = create_llm_client(provider="google", api_key="YOUR_KEY")
chain = RAGChain(llm=llm, retriever=retriever)
answer = chain.query("What are the main topics?")

Memória persistente

from mangaba.memory import ShortTermMemory, LongTermMemory

short = ShortTermMemory(max_items=50)
short.add("User asked about Python")

long_mem = LongTermMemory(storage_path="memory.db")
long_mem.add("User prefers concise answers")
results = long_mem.search("preferences")

Guardrails e Output Parsers

from mangaba import Agent, Task
from mangaba.core.guardrails import LengthGuardrail, GuardrailChain
from mangaba.core.output_parsers import JSONOutputParser

task = Task(
    description="List the top 3 programming languages",
    expected_output="JSON with name and reason",
    agent=agent,
    guardrails=[LengthGuardrail(max_length=2000)],
    output_parser=JSONOutputParser(),
)

Comunicação entre agentes (A2A Protocol — NOVO v3.3.0)

from protocols.a2a import A2AProtocol, A2AMessage

protocolo = A2AProtocol()

# Enviar mensagem de um agente para outro
msg = A2AMessage(
    sender="pesquisador",
    recipient="revisor",
    content="Análise de vulnerabilidade concluída",
    msg_type="request"
)
protocolo.send(msg)

# Broadcast para todos os agentes
protocolo.broadcast(A2AMessage(
    sender="manager",
    recipient="*",
    content="Iniciando nova tarefa",
    msg_type="broadcast"
))

Vector store com ChromaDB (NOVO v3.3.0)

from mangaba.vectorstores import ChromaVectorStore, create_vectorstore
from mangaba.embeddings import OpenAIEmbedding

embedding = OpenAIEmbedding(api_key="KEY")

# Via factory
store = create_vectorstore("chroma", embedding=embedding, persist_directory="./chroma_db")

# Adicionar e buscar
store.add(chunks)
results = store.similarity_search("machine learning", k=5)

🗄️ Vector Stores

Store	Persistência	Ideal para
InMemoryVectorStore	Volátil (RAM)	Testes e protótipos
ChromaVectorStore	Disco (ChromaDB)	Aplicações standalone
PostgresVectorStore	PostgreSQL + pgvector	Produção, dados relacionais
RedisVectorStore	Redis + RediSearch	Alta performance, caching
SQLiteVectorStore	SQLite local	Embeddings simples, sem infra

Todas implementam BaseVectorStore e são intercambiáveis via create_vectorstore().

🤝 Protocolos de Comunicação

A2A (Agent-to-Agent)

Mensageria direta entre agentes com suporte a request/response e broadcast:

from protocols.a2a import A2AProtocol, A2AMessage

protocol = A2AProtocol()
protocol.send(A2AMessage(sender="agent_a", recipient="agent_b", content="..."))

MCP (Multi-Context Protocol)

Compartilhamento de contexto hierárquico entre agentes com prioridade, tags e busca por relevância:

from protocols.mcp import MCPProtocol, MCPContext

mcp = MCPProtocol()
ctx = MCPContext(content="Dados da análise", priority=8, tags=["analise", "vulnerabilidade"])
mcp.share_context("sessao_1", ctx)
resultados = mcp.query_context("sessao_1", "vulnerabilidade")

🧩 Prompt Templates

from mangaba.core.llm.prompt_templates import PromptTemplate, ChatPromptTemplate, SystemPromptBuilder

# Template simples
template = PromptTemplate("Responda em {idioma}: {pergunta}")
result = template.format(idioma="português", pergunta="o que é IA?")

# Template de chat
chat = ChatPromptTemplate([
    ("system", "Você é um especialista em {topico}"),
    ("user", "{pergunta}"),
])
messages = chat.format_messages(topico="segurança", pergunta="O que é XSS?")

# Builder pattern
builder = SystemPromptBuilder()
builder.add_role("Analista de Segurança")
builder.add_context("Você trabalha com pentest há 10 anos")
builder.add_instruction("Responda em markdown")
prompt = builder.build()

🏛️ Padrões de Projeto

O Mangaba aplica padrões GoF de forma consistente em toda a base de código:

Padrão	Onde é usado
Factory	create_llm_client() / create_vectorstore() — instancia provedores por nome
Abstract Factory	BaseLLMProvider / BaseVectorStore — interface comum; cada provider é uma família concreta
Facade	LLMClient — esconde a complexidade dos provedores atrás de uma API uniforme
Decorator	@tool — converte funções Python em BaseTool com schema automático
Composite	Crew / Toolkit — agrega múltiplos agentes/tarefas/ferramentas como unidade
Strategy	Process (sequential/hierarchical/parallel/consensual); providers como strategies
Observer	EventBus + callbacks (ConsoleCallback, FileCallback)
Template Method	BaseLLMProvider.generate/stream/generate_with_tools — subclasses implementam os passos
Chain of Responsibility	GuardrailChain — passa o output por validadores em sequência
Command	Task — encapsula instrução, agente e ferramentas
Iterator	stream() — retorna Iterator[str] token a token
Pipes & Filters	Pipeline → Stage[] → ParallelStage / ConditionalStage
Builder	SystemPromptBuilder — constrói system prompts passo a passo
Singleton	EventBus — instância única de barramento de eventos

🏗️ Arquitetura

mangaba/
├── core/                   # Cérebro do framework
│   ├── agent.py                # Agent com ReAct reasoning
│   ├── task.py                 # Tasks com guardrails e retry
│   ├── crew.py                 # Orquestração (4 processos)
│   ├── workflow.py             # Pipeline engine
│   ├── reasoning.py            # ReAct loop (Think→Act→Observe)
│   ├── planner.py              # Decomposição automática de tarefas
│   ├── guardrails.py           # LengthGuardrail, ContentFilter, Schema
│   ├── output_parsers.py       # JSON, Pydantic, List, Markdown
│   ├── types.py                # Tipos Pydantic v2 (LLMConfig, AgentState...)
│   ├── exceptions.py           # Hierarquia de 19+ exceções
│   ├── events.py               # EventBus (22+ event types)
│   └── llm/                    # Engine LLM multi-provider
│       ├── client.py               # 5 providers + OpenRouter + fallback
│       ├── retry.py                # Retry com backoff exponencial
│       ├── cache.py                # LRU (memória) + SQLite (disco)
│       ├── token_counter.py        # TokenCounter + UsageTracker
│       └── prompt_templates.py     # PromptTemplate, ChatPromptTemplate, SystemPromptBuilder
├── tools/                  # Sistema de ferramentas
│   ├── base.py                 # BaseTool + JSON schema automático
│   ├── decorator.py            # @tool decorator
│   ├── toolkit.py              # BaseToolkit, FileToolkit, WebToolkit
│   ├── file_tools.py           # FileReader, FileWriter, DirectoryList
│   ├── web_search.py           # Serper, DuckDuckGo
│   ├── math_tools.py           # Calculadora segura (AST)
│   └── text_tools.py           # TextSplitter, WordCounter
├── memory/                 # Sistema de memória
│   ├── base.py                 # BaseMemory ABC
│   ├── short_term.py           # Sliding window (deque)
│   ├── long_term.py            # SQLite + embeddings opcionais
│   └── entity.py               # Memória de entidades
├── embeddings/             # Provedores de embedding
│   ├── base.py                 # BaseEmbedding ABC
│   ├── openai_embed.py         # text-embedding-3-small
│   ├── google_embed.py         # text-embedding-004
│   └── huggingface_embed.py    # Sentence-transformers
├── vectorstores/           # Armazenamento vetorial
│   ├── base.py                 # BaseVectorStore ABC
│   ├── factory.py              # create_vectorstore() + register_store()
│   ├── in_memory.py            # Cosine similarity (numpy)
│   ├── chroma_db.py            # ChromaDB
│   ├── postgres.py             # PostgreSQL + pgvector
│   ├── redis.py                # Redis + RediSearch
│   └── sqlite.py               # SQLite vector store
├── rag/                    # Pipeline RAG
│   ├── document.py             # Modelo de documento
│   ├── loaders.py              # Text, CSV
│   ├── splitters.py            # RecursiveTextSplitter
│   ├── retriever.py            # Embedding + vector store
│   └── chain.py                # RAGChain com fontes
├── callbacks/              # Observabilidade
│   ├── console.py              # Print formatado de eventos
│   └── file.py                 # Log JSONL
├── __init__.py              # API pública do pacote
├── config.py                # Config system (leituta .env)
└── exceptions.py            # (legado)

protocols/                 # Protocolos de comunicação entre agentes
├── a2a.py                     # Agent-to-Agent protocol
└── mcp.py                     # Multi-Context Protocol

utils/                     # Utilitários
└── logger.py                  # Logger colorido (Loguru)

docs/                       # Documentação completa
├── API-Reference.md
├── CHANGELOG.md
├── Core-Components.md
├── Events.md
├── Guardrails.md
├── LLM-Providers.md
├── Memory.md
├── RAG.md
├── Tools.md
├── Vector-Stores.md
├── Workflows.md
├── Getting-Started.md
├── CURSO_BASICO.md
├── Examples.md
├── FAQ.md
└── ...

examples/                  # Exemplos práticos
├── basic_example.py
├── crew_example.py
├── finance_example.py
├── legal_example.py
├── medical_example.py
├── marketing_example.py
├── text_analysis_example.py
├── translation_example.py
├── document_analysis_example.py
├── vectorstores_example.py
└── ...

🔄 Processos de Crew

Processo	Descrição	Uso
SEQUENTIAL	Tarefas executadas em ordem, uma após a outra	Workflows lineares
HIERARCHICAL	Primeiro agente é manager, delega e revisa	Equipes com líder
PARALLEL	Tarefas executadas concorrentemente (asyncio)	Tarefas independentes
CONSENSUAL	Todos os agentes executam cada tarefa, resultado sintetizado	Decisões críticas

🌐 Provedores LLM

Provedor	Function Calling	Streaming	Modelo Padrão
OpenRouter	✅ Nativo + Fallback	✅	Multi-model routing
Google Gemini	✅ Nativo	✅	gemini-2.5-flash
OpenAI	✅ Nativo	✅	gpt-4o-mini
Anthropic	✅ Nativo (tool_use)	✅	claude-3-haiku-20240307
HuggingFace	✅ Nativo (11 modelos) / ⚠️ Prompt (14 modelos)	✅ via chat_completion	mistralai/Mistral-7B-Instruct-v0.3

Configure via variáveis de ambiente:

LLM_PROVIDER=google
GOOGLE_API_KEY=sua_chave
# ou OPENAI_API_KEY, ANTHROPIC_API_KEY, HUGGINGFACE_API_KEY, OPENROUTER_API_KEY

🤗 Modelos Open-Source HuggingFace

O provider HuggingFace usa chat_completion (OpenAI-compatible) com detecção automática de tool calling: modelos que suportam function calling nativo recebem tools=[...] direto na API; os demais usam prompt injection como fallback. Use hf_model_supports_tools(model_id) para verificar.

O Mangaba inclui um catálogo de 28 modelos open-source disponíveis via HuggingFace Inference API, organizados por categoria:

from mangaba import list_huggingface_models, HF_OPEN_MODELS

# Listar todos os modelos
todos = list_huggingface_models()

# Filtrar por categoria: general, code, reasoning, embedding
modelos_codigo  = list_huggingface_models(category="code")
modelos_reason  = list_huggingface_models(category="reasoning")
modelos_embed   = list_huggingface_models(category="embedding")

# Via classe do provider
from mangaba.core.llm.client import HuggingFaceLLMProvider
HuggingFaceLLMProvider.list_models(category="general")

Categoria	Modelos incluídos
general (19)	Mistral 7B/Mixtral 8x7B/8x22B, Llama 3/3.1/3.2, Qwen 2.5, Phi-3/3.5, Gemma 2
code (4)	StarCoder2 15B, Qwen 2.5 Coder 7B/32B, DeepSeek Coder 33B
reasoning (2)	DeepSeek R1 Distill Qwen 7B, DeepSeek R1 Distill Llama 70B
embedding (3)	BGE-M3, all-MiniLM-L6-v2, Multilingual E5 Large

from mangaba import hf_model_supports_tools

hf_model_supports_tools("mistralai/Mistral-7B-Instruct-v0.3")  # True  — nativo
hf_model_supports_tools("google/gemma-2-9b-it")                # False — prompt injection

📦 Dependências

Core:

• pydantic>=2.0.0 — Validação de tipos
• google-generativeai>=0.3.0 — Google Gemini
• openai>=1.6.0 — OpenAI GPT
• anthropic>=0.20.0 — Anthropic Claude
• huggingface-hub>=0.20.0 — HuggingFace
• tiktoken>=0.5.0 — Contagem de tokens
• requests>=2.25.0 — HTTP client
• loguru>=0.6.0 — Logging

Opcionais:

• numpy>=1.24.0 — RAG e embeddings (pip install mangaba[rag])
• sentence-transformers>=2.2.0 — Embeddings HF (pip install mangaba[embeddings])
• duckduckgo-search>=3.9.0 — Busca web (pip install mangaba[tools])
• redis>=5.0.0 — Redis vector store (pip install mangaba[redis])
• psycopg[binary]>=3.1.0 — Postgres vector store (pip install mangaba[postgres])
• chromadb>=0.4.0 — ChromaDB vector store (pip install mangaba[chroma])
• Tudo: pip install mangaba[all]

🧪 Testes

# Testes v3
python -m pytest tests/test_v3.py -v

# Todos os testes (14 suites)
python -m pytest tests/ -v

# Com cobertura (mínimo 80%)
python -m pytest tests/ --cov=mangaba --cov-report=term-missing

🤝 Contribuição

1. Fork o projeto
2. Crie sua branch (git checkout -b feature/nova-feature)
3. Commit (git commit -m 'Add nova feature')
4. Push (git push origin feature/nova-feature)
5. Abra um Pull Request

📄 Licença

MIT License

---