🔄 Os 5 Componentes Fundamentais
O INTELECTO tem exatamente 5 responsabilidades distintas. Essa divisão não é arbitrária — cada componente pode ser substituído, testado e evoluído independentemente dos outros. É o segredo que mantém o sistema gerenciável.
🧩 Os 5 Componentes
O cérebro. Recebe mensagens, monta contexto, decide usar tools ou responder diretamente, orquestra tudo.
Acesso aos LLMs. OpenRouter, Ollama, direct API. Qualquer um que implemente BaseProvider funciona.
Como o usuário se comunica. Telegram, WhatsApp, Discord, CLI. Implementam BaseChannel.
Persistência de contexto. SQLite FTS5 com busca semântica BM25 e deduplicação automática.
Ações no mundo real. Google Calendar, GitHub, browser, shell. Implementam BaseTool.
📨 Fluxo Completo de uma Mensagem
Cada mensagem percorre um caminho preciso. Entender esse fluxo é fundamental para saber onde intervir quando algo falha e onde adicionar funcionalidades novas.
📊 Diagrama de Fluxo
💡 Dica Prática
Para debugar, adicione logs em cada etapa do fluxo. O Python logging com diferentes níveis (DEBUG para Channel, INFO para Agent, WARNING para Safety) permite filtrar exatamente onde o problema ocorre.
🔁 O Agent Loop — Max 5 Rounds
O loop.py é o coração do INTELECTO. Ele implementa o padrão ReAct (Reason + Act): a IA pensa, decide agir com uma ferramenta, recebe o resultado, repensa e assim por diante — até chegar em uma resposta final ou atingir o limite de 5 rounds.
🔄 O Ciclo ReAct
LLM analisa a mensagem + contexto e decide o que fazer
Se decidiu usar uma tool → chama tool.execute() com os parâmetros
Resultado da tool entra no contexto → volta para Reason
LLM gera resposta em linguagem natural para o usuário
⚠ Por que Limite de 5 Rounds?
Sem limite, um bug na lógica da IA pode causar loop infinito — custando centenas de dólares em tokens. O limite de 5 é o circuit breaker que protege seu billing. Para tarefas complexas, ajuste o limite com cuidado e sempre com monitoramento.
📁 O Workspace — Configuração em Markdown
O diretório workspace/ é onde você define o que seu Jarvis é. Três arquivos Markdown que são lidos e injetados em cada system prompt. Mudar o comportamento da IA não requer alterar código — apenas editar esses arquivos.
🧬 SOUL.md
A personalidade da IA: nome, tom de voz, valores, estilo de comunicação, limitações éticas. Define quem é o Jarvis.
📋 AGENTS.md
Regras de comportamento: o que fazer, o que nunca fazer, como priorizar tarefas, quando pedir confirmação.
🧠 MEMORY.md
Fatos de bootstrap: informações que a IA precisa saber desde a primeira conversa sem precisar ser ensinada.
💡 Configuration as Code
Os arquivos de workspace são "code" no sentido de que controlam o comportamento do sistema. Versione-os com git, faça backup, e trate mudanças neles com o mesmo cuidado que trata mudanças de código.
🧩 Contratos de Interface
O segredo da extensibilidade do INTELECTO são os contratos de interface. Cada tipo de componente tem uma classe base abstrata com métodos obrigatórios. Se você respeita o contrato, seu componente funciona com todo o resto automaticamente.
📋 Os 3 Contratos Principais
Único método obrigatório. Qualquer LLM que implemente isso funciona com o Agent.
async def send(user_id, msg) → None
async def stop() → None
3 métodos. Telegram, WhatsApp, CLI — todos implementam esses 3.
description: str
parameters: dict # JSON Schema
async def execute(**kwargs) → str
A descrição + parâmetros são enviados ao LLM para ele saber como usar a tool.
🗄 Persistência em ~/.intelecto/
Tudo que o INTELECTO persiste fica em ~/.intelecto/. Três arquivos críticos que você precisa conhecer, fazer backup e nunca apagar acidentalmente.
memory.db
Banco SQLite com FTS5 habilitado. Armazena fatos (categoria: fact/conversation/solution), histórico de conversas e resultados de searches anteriores. BM25 para ranking de relevância.
.secrets
Chaves API criptografadas com Fernet. A chave de criptografia é derivada do UUID do hardware com PBKDF2. O arquivo só pode ser descriptografado na mesma máquina.
audit.log
Registro de todas as ações: quem pediu, o que foi executado, quando, com qual resultado. Imutável por design — cada linha é append-only.
✅ Resumo do Módulo 1.2
Próximo Módulo:
1.3 — Setup do Ambiente: do zero ao Jarvis funcionando no Telegram