Construindo um Agente de IA Auditável no Seu Terminal com deepstrain

Por que deepstrain?

A maioria dos agentes de codificação de IA são caixas pretas. Você lhes dá um prompt, eles começam a disparar ferramentas e você torce para que tudo dê certo. Se algo quebrar, boa sorte para descobrir o porquê.

deepstrain adota uma abordagem diferente: execução inspecionável e com planejamento prévio. Cada decisão é registrada, cada plano é revisado antes de tocar em arquivos, e você pode executá-lo totalmente offline com modelos locais.

Este tutorial orienta sobre como instalar o deepstrain, configurá-lo com seu modelo preferido e executar uma tarefa prática.

Passo 1: Instalar

deepstrain é um pacote Python, disponível via pip:

pip install deepstrain

É isso. Sem Docker, sem configuração em nuvem, sem dependências ocultas. O nível gratuito inclui todas as 52 ferramentas integradas e 19 domínios de capacidade.

Passo 2: Configurar um Backend de Modelo

deepstrain é agnóstico em relação a modelos. Você pode usar:

• Ollama (grátis, local)
• Claude (API da Anthropic)
• GPT-4o (API da OpenAI)
• DeepSeek (barato, ~$0.009/tarefa)
• Qualquer endpoint compatível com OpenAI

Defina seu backend via variáveis de ambiente. Por exemplo, com Ollama:

export DEEPSTRAIN_MODEL="ollama:llama3.1:70b"
export OLLAMA_HOST="http://localhost:11434"

Ou com DeepSeek:

export DEEPSTRAIN_MODEL="deepseek:deepseek-chat"
export DEEPSEEK_API_KEY="sk-your-key"

Se você tiver um modelo local em execução, o deepstrain funciona totalmente offline — nenhum dado sai da sua máquina.

Passo 3: Execute Sua Primeira Tarefa

Vamos pedir ao deepstrain para refatorar um arquivo Python. Crie um script bagunçado:

# messy.py
def a(x,y):return x+y
def b(x,y):return x*y
def c(x,y):return x-y

Agora execute:

deepstrain run "Refactor messy.py: renomear funções para nomes descritivos, adicionar dicas de tipo e escrever uma docstring para cada uma. Mostre-me o plano primeiro."

O deepstrain irá:

1. Gerar um plano (e pausar para sua aprovação)
2. Executar o plano passo a passo
3. Registrar cada decisão com todo o contexto

Você verá uma saída como:

[PLANO] Passo 1: Ler messy.py
[PLANO] Passo 2: Renomear a() -> add()
[PLANO] Passo 3: Renomear b() -> multiply()
[PLANO] Passo 4: Renomear c() -> subtract()
[PLANO] Passo 5: Adicionar dicas de tipo (int, int) -> int
[PLANO] Passo 6: Adicionar docstrings
[PLANO] Passo 7: Escrever mudanças em messy.py

Revisar plano? (s/n): s

[LOG] Executando passo 1...
[LOG] Executando passo 2...
...
[FIM] Refatorado messy.py

Passo 4: Inspecionar os Logs

Cada execução cria um arquivo de log com timestamp em ~/.deepstrain/logs/. Abra-o para ver todo o histórico de decisões:

cat ~/.deepstrain/logs/$(ls -t ~/.deepstrain/logs/ | head -1)

Você verá as respostas exatas do modelo, chamadas de ferramentas e rastreamentos de pilha. Isso é cognição inspecionável — sem caixa preta.

Passo 5: Usar Ferramentas Integradas

deepstrain vem com 52 ferramentas em 19 domínios. Aqui está uma amostra rápida:

• File I/O: read, write, edit, patch
• Git: git_status, git_diff, git_commit
• Bash: run_shell, run_script
• Network: http_get, http_post
• Database: sql_query (sqlite, postgres)
• MCP: mcp_call (conectar a servidores MCP)

Para listar todas as ferramentas:

deepstrain list-tools

Limitações a Conhecer

• deepstrain é nativo do terminal — sem GUI. É projetado para desenvolvedores que vivem no terminal.
• O nível gratuito é totalmente funcional, mas limitado a 100 tarefas por dia. O Pro ($9/mês) remove esse limite e adiciona ativação HMAC para uso em equipe.
• A análise de código determinística (via atlas) funciona apenas para Python e JavaScript atualmente. Outras linguagens recorrem à análise baseada em LLM.
• Se você usar um modelo local pequeno (por exemplo, 7B), a qualidade do plano pode sofrer. Um modelo 70B+ ou GPT-4o oferece os melhores resultados.

Próximos Passos

• Executá-lo no CI: deepstrain funciona muito bem no GitHub Actions para revisões automáticas de PR ou geração de testes.
• Usá-lo offline: Combine com Ollama e um modelo local para ambientes isolados.
• Estender com MCP: Conecte-se aos seus próprios servidores MCP para capacidades personalizadas.

Verifique o repositório para exemplos e configuração avançada: https://github.com/mete-dotcom/deepstrain

Ou apenas instale e experimente:

pip install deepstrain