Broco - Seu Copiloto Inteligente para Windows

Introducao

O BrocoEngine e o nucleo do assistente Broco. E um sistema modular de automacao e inteligencia artificial que conecta servicos externos (email, calendario, CRM, ERP, arquivos) atraves de uma interface unificada de linguagem natural.

O sistema processa comandos de voz ou texto, identifica a intencao do usuario, seleciona a skill adequada e executa a acao de forma autonoma - retornando feedback em tempo real.

Capacidades Principais

•27 skills nativas cobrindo comunicacao, produtividade, CRM, arquivos e IA
•Workflows multi-step com encadeamento de skills (BrocoFlows)
•Agendamento com cron expressions para automacao recorrente
•Sistema de memoria persistente entre sessoes
•Processamento local com suporte a LLMs on-premise (Broco I)

Arquitetura

O BrocoEngine segue uma arquitetura modular baseada em Python/FastAPI. Cada componente e independente e se comunica via interfaces bem definidas.

Arquitetura do Sistema

BrocoEngine (Orquestrador Principal)
  |
  +-- SkillManager ........... Gerencia 27 skills nativas
  |     +-- EmailSkill
  |     +-- CalendarSkill
  |     +-- CRMSkill
  |     +-- FileSkill
  |     +-- AIGenerationSkill
  |     +-- ... (22 outras)
  |
  +-- WorkflowEngine ........ Executa BrocoFlows
  |     +-- StepExecutor
  |     +-- ConditionalRouter
  |     +-- ParallelRunner
  |
  +-- Scheduler .............. Agendamento com cron
  |     +-- CronParser
  |     +-- JobQueue
  |
  +-- MemorySystem ........... Contexto persistente
  |     +-- ShortTermMemory
  |     +-- LongTermMemory
  |     +-- VectorStore
  |
  +-- IntentParser ........... NLU + classificacao
  +-- VoiceProcessor ......... STT + TTS
  +-- APIGateway ............. REST API (FastAPI)

Todas as integracoes externas sao feitas via HTTP/REST APIs com retry automatico, circuit breaker e rate limiting configuravel.

Instalacao

O Broco e compativel com Windows 10 (versao 1903+) e Windows 11. Requer no minimo 4GB de RAM e 500MB de espaco em disco. Para IA local, recomendamos 8GB+ de RAM e GPU com DirectML.

Via Instalador (Recomendado)

# Baixe o instalador oficial
https://broco.app/download

# Ou via winget
winget install Broco.Desktop

Via CLI (Desenvolvedores)

npm install -g @broco/cli
broco init
broco login

Configuracao Inicial

~/.broco/config.json

{
  "apiKey": "broco_sk_...",
  "language": "pt-BR",
  "theme": "dark",
  "voiceEnabled": true,
  "hotkey": "Ctrl+Space",
  "localAI": false
}

BrocoEngine

O BrocoEngine e o orquestrador principal. Ele recebe comandos (texto ou voz), processa a intencao, roteia para a skill correta e gerencia o ciclo de vida da execucao.

Fluxo de Processamento

1. Entrada (voz/texto)
   |
2. VoiceProcessor.transcribe()  [se voz]
   |
3. IntentParser.parse(text)
   -> Identifica: skill, acao, parametros, contexto
   |
4. SkillManager.execute(skill, params)
   -> Executa a skill com parametros parseados
   |
5. MemorySystem.store(result)
   -> Salva contexto para futuras interacoes
   |
6. Response (texto/voz)
   -> Retorna resultado formatado

O engine suporta execucao sincrona e assincrona. Skills de longa duracao (como geracao de relatorios) rodam em background com notificacao ao completar.

SkillManager

O SkillManager gerencia o registro, descoberta e execucao de todas as skills. Cada skill segue uma interface padrao que garante consistencia.

Interface de uma Skill

class BaseSkill:
    name: str
    description: str
    triggers: list[str]      # Palavras-chave que ativam
    required_params: list     # Parametros obrigatorios
    optional_params: list     # Parametros opcionais

    async def execute(self, params: dict) -> SkillResult:
        """Executa a skill e retorna resultado"""
        ...

    async def validate(self, params: dict) -> bool:
        """Valida parametros antes de executar"""
        ...

Skills customizadas podem ser registradas via API, permitindo que desenvolvedores estendam o Broco com funcionalidades especificas do seu negocio.

WorkflowEngine (BrocoFlows)

O WorkflowEngine permite criar automacoes multi-step chamadas BrocoFlows. Um workflow encadeia multiplas skills com logica condicional e execucao paralela.

Exemplo de BrocoFlow

{
  "name": "Relatorio Semanal",
  "trigger": "cron:0 9 * * MON",
  "steps": [
    {
      "id": "buscar-dados",
      "skill": "crm.pipeline_report",
      "params": { "period": "last_week" }
    },
    {
      "id": "gerar-resumo",
      "skill": "ai.summarize",
      "params": { "input": "{{buscar-dados.output}}" }
    },
    {
      "id": "enviar-email",
      "skill": "email.send",
      "params": {
        "to": "time@empresa.com",
        "subject": "Relatorio Semanal - Pipeline",
        "body": "{{gerar-resumo.output}}"
      }
    }
  ]
}

Recursos do WorkflowEngine

•Encadeamento: Output de um step vira input do proximo via template strings
•Condicionais: Rotas if/else baseadas em resultados de steps anteriores
•Parallelismo: Steps independentes rodam em paralelo automaticamente
•Error handling: Retry automatico, fallback skills e notificacao de falhas

Scheduler (Agendador)

O Scheduler permite agendar execucoes recorrentes usando cron expressions. Qualquer skill ou workflow pode ser agendado.

Exemplos de Agendamento

# Enviar relatorio toda segunda as 9h
broco schedule "Envie relatorio semanal" --cron "0 9 * * MON"

# Backup diario as 23h
broco schedule "Faca backup dos arquivos do projeto" --cron "0 23 * * *"

# Verificar emails a cada 30 minutos
broco schedule "Verifique emails nao lidos" --cron "*/30 * * * *"

# Lembrete mensal
broco schedule "Lembre-me de renovar licencas" --cron "0 10 1 * *"

Jobs agendados persistem entre reinicializacoes do sistema. O scheduler usa uma fila de prioridades com dead-letter queue para jobs falhos.

Sistema de Memoria

O MemorySystem mantem contexto entre interacoes, permitindo que o Broco entenda referencias a conversas anteriores e aprenda preferencias do usuario.

Tres Camadas de Memoria

Short-Term Memory

Contexto da sessao atual. Mantem historico da conversa, parametros recentes e estado das skills ativas. Expira ao fechar o Broco.

Long-Term Memory

Preferencias e padroes do usuario persistidos em SQLite local. Aprende horarios preferidos, contatos frequentes e fluxos comuns.

Vector Store

Busca semantica sobre documentos e historico. Permite perguntas como "O que eu falei sobre o projeto Alpha semana passada?"

Skills - Visao Geral

O Broco vem com 27 skills nativas organizadas em 6 categorias. Cada skill e uma unidade autonoma que sabe se conectar a um servico externo e executar acoes especificas.

Comunicacao6 skills

Email, WhatsApp, Slack, Discord, Teams, SMS

Produtividade5 skills

Calendar, Notion, Trello, Jira, Tasks

CRM & Vendas4 skills

Salesforce, HubSpot, Pipedrive, Reports

Arquivos & Sistema4 skills

FileManager, Drive, OneDrive, Backup

IA & Geracao5 skills

TextGen, ImageGen, Summarize, Translate, Analysis

Utilitarios3 skills

WebSearch, Calculator, Timer

Skills de Comunicacao

As skills de comunicacao permitem enviar, ler e gerenciar mensagens em multiplas plataformas com um unico comando.

Exemplos de Uso

# Email
"Envie um email pro Ricardo com o relatorio anexo"
"Resuma meus emails nao lidos de hoje"
"Responda o ultimo email da Marina dizendo que aceito"

# WhatsApp Business
"Mande pro cliente confirmando entrega pra sexta"
"Envie a proposta comercial pro grupo do projeto"

# Slack
"Avise o canal #vendas que a meta foi batida"
"Mande uma mensagem pro Luan no Slack"

# Teams / Discord
"Crie uma reuniao no Teams pra amanha 10h"
"Poste o changelog no canal #updates do Discord"

Skills de Produtividade

Exemplos de Uso

# Google Calendar / Outlook Calendar
"Marque reuniao com time de vendas amanha 14h"
"Quais sao meus compromissos de hoje?"
"Mova a reuniao de quarta pra quinta 15h"

# Notion
"Adicione tarefa no board do projeto Alpha"
"Crie uma pagina com ata da reuniao de hoje"

# Trello / Jira
"Mova o card 'Bug Fix' pra coluna Done"
"Crie um ticket de bug para o problema de login mobile"

Skills de CRM & Vendas

Exemplos de Uso

# Salesforce
"Atualize o deal do cliente Acme para fechado-ganho"
"Qual o valor total do pipeline esse mes?"

# HubSpot
"Crie um contato com os dados do ultimo email"
"Atualize o status do lead para qualificado"

# Reports
"Gere relatorio de vendas da semana"
"Compare performance Q1 vs Q2"

Skills de Arquivos & Sistema

Exemplos de Uso

# FileManager (Windows)
"Organize os downloads por tipo de arquivo"
"Encontre todos os PDFs modificados essa semana"
"Mova os relatorios pra pasta Relatorios/2026"

# Google Drive / OneDrive
"Compartilhe a proposta com o time de vendas"
"Faca backup da pasta de projetos no Drive"

# Backup
"Backup incremental dos documentos as 23h"

Skills de IA & Geracao

Exemplos de Uso

# TextGen
"Escreva um email formal agradecendo a parceria"
"Gere 5 opcoes de titulo pra esse artigo"

# ImageGen
"Crie uma thumbnail pro post do blog sobre IA"
"Gere um banner para o evento de lancamento"

# Summarize
"Resuma esse documento de 50 paginas em 5 topicos"
"Faca um resumo executivo da reuniao de hoje"

# Translate
"Traduza esse contrato pra ingles"

# Analysis
"Analise os dados de vendas e identifique tendencias"

BrocoFlows - Como Funciona

BrocoFlows sao workflows automatizados que encadeiam multiplas skills. Voce pode criar flows via comando de voz, texto ou JSON.

Criando via Comando de Voz

"Hey Broco, crie um flow que toda segunda as 9h:
  1. Busque o relatorio de vendas da semana
  2. Resuma em 5 pontos
  3. Envie por email pro time de gestao"

-> Broco cria o BrocoFlow automaticamente
-> Agenda com cron: 0 9 * * MON
-> Executa toda segunda sem intervencao

Criando Workflows

Workflows podem ser criados de 3 formas: linguagem natural, JSON ou pelo editor visual.

Via JSON (Avancado)

POST /api/workflows
{
  "name": "Onboarding Novo Cliente",
  "steps": [
    {
      "skill": "crm.create_contact",
      "params": { "source": "{{trigger.data}}" }
    },
    {
      "skill": "email.send_template",
      "params": {
        "template": "welcome",
        "to": "{{step_0.email}}"
      }
    },
    {
      "skill": "calendar.create_event",
      "params": {
        "title": "Kickoff - {{step_0.name}}",
        "duration": "30min",
        "invitees": ["{{step_0.email}}"]
      }
    },
    {
      "skill": "slack.notify",
      "params": {
        "channel": "#novos-clientes",
        "message": "Novo cliente: {{step_0.name}}"
      }
    }
  ]
}

Templates Prontos

O Broco vem com templates de workflows prontos para cenarios comuns.

Relatorio Semanal

Coleta dados + resume + envia email

Cron (segunda 9h)

Onboarding Cliente

CRM + email + reuniao + notificacao

Novo contato

Backup Diario

Backup arquivos + compacta + upload cloud

Cron (23h)

Lead Scoring

Analisa lead + pontua + roteia vendedor

Novo lead

Daily Standup

Coleta status + gera resumo + Slack

Cron (9h30)

Invoice Follow-up

Verifica faturas + envia lembrete

Cron (10h)

Agendador (Cron)

O Scheduler usa cron expressions padrao para agendamento. Referencia rapida:

Expressao	Significado
`/30 * * *`	A cada 30 minutos
`0 9 * * MON-FRI`	Dias uteis as 9h
`0 9 * * MON`	Toda segunda as 9h
`0 23 * * *`	Todo dia as 23h
`0 10 1 * *`	Dia 1 de cada mes as 10h
`0 8 * * 1,4`	Segunda e quinta as 8h

Sistema de Memoria

O sistema de memoria permite que o Broco aprenda com o uso e mantenha contexto entre interacoes. Toda memoria e local e criptografada.

Exemplos de Memoria em Acao

Usuario: "Mande email pro Ricardo"
Broco:  -> Sabe que "Ricardo" = Ricardo Mendes (contato frequente)
        -> Sabe que prefere usar Gmail (nao Outlook)
        -> Sabe que o tom e informal com Ricardo

Usuario: "Qual era o valor daquele deal?"
Broco:  -> Busca na memoria recente por "deal"
        -> Encontra: Deal Acme Corp, R$150k, discutido ontem
        -> Responde com contexto correto

Configuracao

O Broco e configuravel via arquivo JSON ou pela interface grafica.

~/.broco/config.json (Completo)

{
  "apiKey": "broco_sk_...",
  "language": "pt-BR",
  "theme": "dark",
  "voiceEnabled": true,
  "hotkey": "Ctrl+Space",
  "localAI": false,
  "integrations": {
    "gmail": { "enabled": true },
    "calendar": { "enabled": true, "provider": "google" },
    "slack": { "enabled": true, "workspace": "minha-empresa" },
    "salesforce": { "enabled": false }
  },
  "memory": {
    "shortTerm": { "maxTokens": 4000 },
    "longTerm": { "enabled": true },
    "vectorStore": { "enabled": true, "model": "local" }
  },
  "scheduler": {
    "enabled": true,
    "maxConcurrent": 5,
    "retryAttempts": 3
  },
  "privacy": {
    "telemetry": false,
    "localProcessing": true,
    "encryptMemory": true
  }
}

API REST

O Broco expoe uma API REST local para integracao com outros sistemas. Por padrao roda em http://localhost:8420.

POST/api/commandEnviar comando (texto)

POST/api/voiceEnviar comando (audio)

GET/api/skillsListar skills disponiveis

POST/api/skills/:id/executeExecutar skill

GET/api/workflowsListar workflows

POST/api/workflowsCriar workflow

POST/api/workflows/:id/runExecutar workflow

GET/api/scheduler/jobsListar jobs agendados

POST/api/scheduler/jobsCriar job

GET/api/memory/searchBuscar na memoria

Para documentacao completa da API, visite a referencia de API.

Documentacao

Instalacao

Configure Skills

Crie Workflows

Introducao

Capacidades Principais

Arquitetura

Instalacao

Via Instalador (Recomendado)

Via CLI (Desenvolvedores)

Configuracao Inicial

BrocoEngine

SkillManager

WorkflowEngine (BrocoFlows)

Recursos do WorkflowEngine

Scheduler (Agendador)

Sistema de Memoria

Tres Camadas de Memoria

Skills - Visao Geral

Skills de Comunicacao

Skills de Produtividade

Skills de CRM & Vendas

Skills de Arquivos & Sistema

Skills de IA & Geracao

BrocoFlows - Como Funciona

Criando Workflows

Templates Prontos

Agendador (Cron)

Sistema de Memoria

Configuracao

API REST