🧠 Fundamentos do INTELECTO

Frameworks como LangChain e CrewAI abstraem tudo, mas adicionam camadas de complexidade desnecessária que tornam depuração e customização um pesadelo.

Entender os trade-offs permite escolher conscientemente quando usar um framework e quando construir do zero — uma habilidade rara no mercado.

Abstraction tax, vendor lock-in, zero-dependency philosophy, controle total do código.

O INTELECTO é organizado como uma mercearia: você vai em cada corredor (corredor de segurança, memória, canais...) e pega apenas o que precisa para o seu assistente.

Esse modelo mental evita over-engineering. Você não instala o que não vai usar, mantendo o sistema leve, auditável e fácil de manter.

8 corredores funcionais, composição modular, feature flags, ingredientes de framework.

Uma análise objetiva das diferenças: LangChain tem 200+ dependências, CrewAI força um modelo de agentes rígido. INTELECTO tem zero dependências obrigatórias além do Python.

Saber defender tecnicamente sua escolha é essencial para times e clientes. Você precisa dos números e argumentos.

Tamanho do pacote, tempo de startup, latência de debug, custo de manutenção, curva de aprendizado.

Jarvis conhece seu criador, lembra de conversas anteriores, age proativamente e executa tarefas no mundo real. Um chatbot genérico apenas responde perguntas.

Define o nível de ambição correto. Você está construindo algo que vai crescer com você, não uma demo descartável.

Identidade persistente, memória de longo prazo, ação no mundo real, personalização profunda.

Cada arquivo tem uma responsabilidade clara: context.py monta o system prompt, loop.py gerencia o ciclo de raciocínio, secrets.py protege credenciais.

Conhecer o mapa antes de mergulhar no código economiza horas de orientação perdida. Cada modificação acontece no lugar certo.

context.py, loop.py, secrets.py, safety.py, store.py, providers/base.py, channels/base.py, tools/base.py.

Com APIs de LLM maduras e estáveis, o custo de abstração dos frameworks supera os benefícios para projetos sérios. Python puro + contratos claros é suficiente.

O mercado está saturado de desenvolvedores que só sabem usar wrappers. Quem entende os fundamentos tem vantagem competitiva real.

Maturidade de API, custo de abstração, vantagem competitiva, contratos de interface, manutenção a longo prazo.

O INTELECTO tem exatamente 5 responsabilidades: o agente central que pensa, os provedores que acessam LLMs, os canais que recebem mensagens, a memória que persiste contexto e as ferramentas que agem no mundo.

Cada componente tem fronteira clara. Saber onde um termina e outro começa é o que permite adicionar features sem quebrar o sistema.

Separation of concerns, contratos de interface, injeção de dependência, composição modular.

Usuário → Telegram → Channel.receive() → Agent.loop() → Memory.search() → Provider.chat() → Tool.execute() → Memory.store() → Channel.send() → Usuário. Cada seta é uma chamada de função com contrato definido.

Visualizar o fluxo completo permite identificar onde debugar quando algo falha e onde otimizar quando está lento.

Pipeline de processamento, async/await, tratamento de erros em cascata, observabilidade.

O loop.py implementa um ciclo de raciocínio: recebe mensagem → pensa → decide usar tool ou responder → se usou tool, repensa com o resultado → até 5 iterações por segurança.

O limite de 5 rounds previne loops infinitos e custos descontrolados. Entender o ciclo permite ajustar a profundidade de raciocínio para cada caso de uso.

ReAct pattern, tool calling, max iterations, custo por round, circuit breaker para loops.

O diretório workspace/ contém arquivos Markdown que definem a personalidade (SOUL.md), as regras de comportamento (AGENTS.md) e os fatos de bootstrap (MEMORY.md) injetados em todo system prompt.

Toda customização da IA começa aqui. Mudar o Jarvis não requer alterar código — apenas os arquivos de workspace.

Configuration as code, system prompt construction, context injection, SOUL.md como identidade.

Cada categoria de extensão tem uma classe base abstrata com métodos obrigatórios. BaseProvider exige async chat(). BaseChannel exige start(), send(), stop(). BaseTool exige name, description, execute().

Os contratos garantem que qualquer implementação funciona com o resto do sistema automaticamente. É como um plug padronizado — qualquer dispositivo que respeita o padrão funciona na tomada.

Abstract base class, duck typing, protocol pattern, plug-and-play architecture.

Três arquivos críticos em ~/.intelecto/: memory.db (banco SQLite com histórico e fatos), .secrets (chaves criptografadas com Fernet + UUID do hardware) e audit.log (registro de todas as ações).

Entender onde os dados vivem é essencial para backup, migração e diagnóstico. Você nunca deve perder a memória do seu Jarvis por acidente.

Home directory pattern, SQLite portabilidade, encrypted secrets, audit trail, backup strategy.

Python 3.11+ é obrigatório. As dependências são mínimas: httpx para HTTP async, python-telegram-bot para o canal, cryptography para Fernet. Nenhum LangChain, nenhum CrewAI.

Conhecer as dependências reais permite auditar o que está instalado e entender por que cada pacote existe no projeto.

venv, requirements.txt minimalista, Python 3.11 features, async nativo.

OpenRouter é um proxy de LLMs que dá acesso a GPT-4, Claude, Mistral, Llama e outros 100+ modelos com uma única chave de API e billing unificado.

Evita vendor lock-in com um provedor específico. Se a Anthropic subir o preço, você muda para Mistral em 10 segundos mudando uma variável de ambiente.

API key management, model routing, cost tracking, fallback strategy, modelo por tarefa.

O arquivo .env define OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, MODEL_NAME e outros parâmetros sem hard-code no código. O .env NUNCA vai para o git.

Separar configuração de código é uma prática de segurança fundamental. Chaves no código são a causa número 1 de vazamentos em repositórios públicos.

12-factor app, .gitignore, python-dotenv, environment variables, secrets management.

O script setup.py faz perguntas interativas: qual canal usar? Docker ou nativo? Qual modelo padrão? E configura tudo automaticamente criando os arquivos necessários.

O wizard elimina erros de configuração manual e garante que nada obrigatório seja esquecido. É a porta de entrada para novos usuários.

Interactive CLI, configuration generation, guided onboarding, validation de inputs.

Docker oferece isolamento e deploy reproduzível. Nativo oferece menor overhead e debug mais direto. Para desenvolvimento use nativo; para produção, Docker Compose.

A escolha afeta como você debugga, como faz backup e como atualiza o sistema. Entender os trade-offs evita surpresas em produção.

Container isolation, volume mounts, docker-compose.yml, desenvolvimento vs produção.

O momento de validação: rodar python main.py, abrir o Telegram, enviar "Olá" e receber a primeira resposta do seu Jarvis. Se funcionar, toda a stack está correta.

O smoke test inicial valida cada componente de ponta a ponta: canal, agente, provedor, memória. É o marco que separa "configurado" de "funcionando".

Smoke test, end-to-end validation, BotFather token, webhook vs polling, debug de primeira execução.