AgentBR Engine V3 ⚙️🇧🇷

O Motor de Inteligência e Orquestração do ecossistema AgentBR.

O AgentBR Engine V3 é um orquestrador agnóstico de LLMs (Large Language Models) de alta performance. Ele atua como o epicentro que interliga os requests dos usuários (via Chat ou Interfaces web), injeta memórias profundas consultando o banco de dados e roteia inferências de maneira inteligente para modelos gigantes como OpenAI, Anthropic, NVIDIA e Ollama.

---

✨ Principais Funcionalidades

• Roteamento de LLMs via LiteLLM: Suporte contínuo a centenas de providers no padrão OpenAI Compatibility, possibilitando trocar o motor cerebral (ex: LLaMA 3 70B via Nvidia) apenas editando uma linha de .env.
• Conexão Nativa com o Cerebro: Comunicação instantânea com o AgentBR Cerebro Server na busca de RAG (Retrieval-Augmented Generation) para resgate de vetores de contexto e banco de memórias.
• Orquestração de Estados (FSM): Sistema de ciclos guiado por Segmenter, Brain, Thinking, Acting e Reconciler. O mesmo padrão que agentes da deep-tech usam para pensar com autonomia.
• Segmentação Semântica (Context Bubbles): Capacidade de fatiar uma única mensagem complexa em múltiplas bolhas de intenção independentes, processando-as sequencialmente para eliminar alucinações de contexto cruzado.

---

🧩 Segmentação Semântica (Context Bubbles)

O AgentBR Engine V3 introduz o conceito de Double-Call Architecture. Quando ativado (ENABLE_CONTEXT_SEPARATION=true), o motor realiza um roteamento semântico antes de processar a resposta:

1. Fatiamento Hub (Headless): Uma LLM secundária (ex: DeepSeek-R1 ou GPT-4o-mini) analisa a entrada e a quebra em blocos JSON independentes.
2. Processamento em Bolhas: O motor principal processa cada bloco isoladamente, garantindo que o histórico de uma intenção não polua a outra.
3. Reconciliação: Os resultados são sintetizados em um único payload estruturado, separando o thinking (raciocínio interno) da resolution (resposta final).

Esse recurso é fundamental para lidar com usuários que enviam múltiplas perguntas em um único parágrafo (ex: "Qual o meu saldo? Ah, e como eu mudo minha senha?").

---

• Servidor FastAPI + Uvicorn: Respostas de sub-milissegundo para lidar com streams assíncronos via HTTP REST e WebSockets.

---

🚀 Instalação Rápida

A Engine V3 foi projetada em Python 3.12 e encapsulada para o uso de virtual environments nativos. Tudo o que você precisa fazer é chamar nossos scripts automatizados.

1. Preparando o Terreno

# Clone o repositório e entre na pasta
git clone https://github.com/AgentBR-ia/agentbr-engine.git
cd agentbr-engine

# Crie e configure sua chave de acesso (Substitua as variaveis de banco/LLM)
cp .env.example .env

(Certifique-se de configurar a sua chave do Cerebro CEREBRO_API_KEY e a sua Chave de Modelo API_KEY no arquivo .env)

2. Instalação e Boot

Nós deixamos atalhos prontos para automatizar a criação do .venv e dependências:

# Para instalar as dependências
./scripts/install.sh

# Para subir o motor de Inteligência
./scripts/dev.sh

(Nota: O Uvicorn subirá por padrão rodando na http://127.0.0.1:8001. Em caso de conflito, você pode mudar a porta rodando PORT=9000 ./scripts/dev.sh).

---

🔌 Entradas e Comunicação (APIs)

A Engine aceita requisições através do formato REST via payload JSON. O endpoint de conversação principal é o /api/v1/ingest.

Requisição de Exemplo (CURL):

curl -X POST http://localhost:8001/api/v1/ingest \
-H "Content-Type: application/json" \
-d '{  
  "session_id": "minha_conversa_1",
  "user_id": "dev123",
  "message": "Olá, AgentBR! Busque minha memória."
}'

Retorno Esperado: O Motor te retornará uma Payload validada contendo os metadados da inferência:

{
  "uuid": "6ff54c7a-8720-4550...",
  "session_id": "minha_conversa_1",
  "timestamp": "2026-04-05T19:26:00.877595",
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Olá! Verifiquei no nosso banco que..."
}

---

🛠 Arquitetura do Repositório

├── app/
│   ├── contracts/    # Pydantic schemas (Entradas Inbound e Saídas Outbound)
│   ├── core/         # Configurações dinâmicas (config.py, logger.py)
│   ├── routers/      # Endpoints FastAPI (REST e WebSockets)
│   └── services/     # O "Modus Operandi":
│       ├── brain/        # Conectividade com o Banco agentbr-cerebro
│       ├── llm/          # Proxy universal do LiteLLM
│       └── orchestrator/ # Loop FSM (Finite State Machine) de decisão
├── scripts/          # Bash helpers para instâncias
├── tests/            # Suite de Asserts Pytest (Testes sem side-effects)
├── .env.example      # Receita estrutural de variáveis obrigatórias
└── requirements.txt  # Lista rigorosa de dependências Pypi

---

🧪 Testes Unitários e CI/CD

A Engine v3 vem equipada com um Pipeline ativo no GitHub. Seus commits e pushes passarão por um fluxo de validação (.github/workflows). Se quiser executar a validação local antes de enviar código crítico:

pytest tests/unit/ -v

---

🤝 Apoio ao Projeto

O AgentBR Engine é um projeto de código aberto mantido pela comunidade. Se você gosta do nosso trabalho e quer nos ajudar a continuar inovando, considere nos apoiar:

Seu apoio nos ajuda a pagar os custos de infraestrutura e a dedicar mais tempo ao desenvolvimento de novas funcionalidades como o Fatiador Semântico.

---

Desenvolvido e orquestrado pela equipe AgentBR.
Mailon Berni - 2026