Implantação e Prática do Dexter: Deixe a IA ler documentos da SEC e fazer Valuation DCF para você

Introdução

Dexter é um Agent de pesquisa financeira autônomo que roda no terminal. Você faz uma pergunta complexa e ele decompõe automaticamente a tarefa, chama múltiplas ferramentas de dados e cruza os resultados até fornecer uma conclusão baseada em dados — como se você tivesse um analista sênior que nunca se cansa.

Suas principais capacidades incluem:

• Leitura de documentos da SEC: Captura automática de documentos como 10-K, 10-Q, 8-K, etc.
• Consulta de cotações em tempo real: Preços de ações, indicadores financeiros, fluxo de caixa, balanço patrimonial.
• Estimativa de valor intrínseco DCF: Habilidade DCF integrada via SKILL.md, executando o fluxo de caixa descontado por conta própria.
• Loop de auto-verificação: Verifica seus próprios resultados intermediários e itera até que a conclusão seja sólida.
• Proteção de Loop: Limite de passos integrado para evitar que o Agent saia do controle.

Todo o projeto é escrito em TypeScript, tendo como núcleo LangChain + Ink (React para CLI), rodando no ambiente Bun 1.0+. Se você deseja executar essas capacidades com um custo menor, pode mudar o provedor de LLM para o Defapi, onde o preço da API é cerca de metade do oficial.

---

Perfil do Público-Alvo

• Desenvolvedores com 1 a 5 anos de experiência, com conhecimento básico de arquitetura de AI Agents (tool calling, Agentic Loop).
• Investidores independentes ou profissionais de fintech que desejam usar ferramentas de IA para auxiliar na pesquisa fundamentalista.
• Engenheiros que querem entender como integrar múltiplas fontes de dados (SEC, Financial Datasets, Exa) em projetos reais.
• Usuários interessados em pesquisa quantitativa financeira que desejam montar um pipeline de pesquisa local.

---

Dependências Principais e Ambiente

---

Árvore de Estrutura do Projeto

dexter/
├── .dexter/
│   └── settings.json          # Configuração de execução do Agent (seleção de modelo/provedor)
├── src/
│   ├── agent/                  # Núcleo do Agent: lógica de loop, prompts, scratchpad
│   │   ├── agent.ts           # Loop principal Agentic
│   │   ├── prompts.ts         # Prompts de sistema
│   │   └── scratchpad.ts      # Histórico de chamadas de ferramentas
│   ├── cli.tsx                # Entrada de renderização Ink/React CLI
│   ├── index.tsx              # Entrada do programa
│   ├── components/            # Componentes de UI CLI (Ink)
│   ├── hooks/                 # React hooks (AgentRunner, ModelSelector)
│   ├── model/
│   │   └── llm.ts            # Camada de abstração de LLM multi-provedor
│   ├── tools/
│   │   ├── registry.ts       # Registro de ferramentas
│   │   ├── finance/          # Ferramentas financeiras: cotações, finanças, relatórios, insider trading
│   │   ├── search/           # Ferramentas de busca web (Exa / Tavily)
│   │   ├── browser/          # Automação de navegador Playwright
│   │   └── descriptions/     # Descrições de ferramentas (injetadas no prompt de sistema)
│   ├── skills/               # Diretório de habilidades SKILL.md
│   │   └── dcf/
│   │       └── SKILL.md     # Habilidade de estimativa de valor intrínseco DCF
│   ├── evals/               # Framework de avaliação LangSmith
│   └── utils/               # Variáveis de ambiente, config, cache
├── scripts/
│   └── release.sh
├── .env                     # Chaves de API (gitignored)
└── package.json

---

Passo a Passo

Passo 1: Instalar Bun e Clonar o Projeto

Se você não tem o Bun instalado, instale-o primeiro. Funciona em Windows/macOS/Linux:

# macOS / Linux
curl -fsSL https://bun.com/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1|iex"

Verifique a instalação:

bun --version
# Saída similar: Bun v1.2.x

Em seguida, clone o repositório do Dexter:

git clone https://github.com/virattt/dexter.git
cd dexter

Passo 2: Configurar Variáveis de Ambiente .env

Copie o arquivo de template de variáveis de ambiente:

cp env.example .env

Abra o .env com um editor e insira suas chaves. Destaque para o método de acesso via Defapi — se quiser usar Defapi em vez de OpenAI (economizando 50%), configure da seguinte forma:

# .env

# ── Provedores de LLM ──────────────────────────────────────
# Opção A: Usar OpenAI diretamente (padrão)
OPENAI_API_KEY=sk-sua-chave-openai

# Opção B: Acesso via Defapi para OpenAI (recomendado, economiza 50%)
# OPENAI_API_KEY=sk-sua-chave-defapi
# OPENAI_BASE_URL=https://api.defapi.com/v1

# Outros provedores opcionais
ANTHROPIC_API_KEY=sk-ant-sua-chave-anthropic
GOOGLE_API_KEY=sua-chave-google
XAI_API_KEY=sua-chave-xai
OPENROUTER_API_KEY=sua-chave-openrouter

# Modelos locais (OLLAMA)
OLLAMA_BASE_URL=http://127.0.0.1:11434

# ── Dados Financeiros ───────────────────────────────────────
# Dados de mercado institucionais, AAPL/NVDA/MSFT grátis
FINANCIAL_DATASETS_API_KEY=sua-chave-financial-datasets

# ── Busca Web ───────────────────────────────────────
# Exa tem prioridade, Tavily como backup
EXASEARCH_API_KEY=sua-chave-exa
TAVILY_API_KEY=sua-chave-tavily

Instale as dependências:

bun install

Passo 3: Executar Dexter em Modo Interativo

Inicie a CLI interativa:

bun start

Você verá uma interface colorida renderizada pelo Ink no terminal. Digite sua pergunta financeira diretamente, por exemplo:

Como foi o crescimento da receita da AAPL nos últimos 5 anos? Qual é o valor intrínseco DCF atual?

O Dexter começará a trabalhar automaticamente: Decompor tarefa → Consultar dados financeiros → Ler documentos da SEC → Executar habilidade DCF → Resumir conclusão. Cada rodada de chamada de ferramenta será exibida em tempo real na interface.

Se quiser depurar enquanto altera o código, use o modo watch:

bun dev

Passo 4: Alternar Modelos / Provedores

Dentro da CLI, use o comando /model para alternar entre provedores e modelos de LLM. O Dexter suporta identificação automática por prefixos:

Por exemplo, para mudar para o Claude:

/model claude-sonnet-4-7

Passo 5: Usar Ferramentas Financeiras para Consultar Ações

O núcleo do Dexter é a ferramenta financial_search, que delega automaticamente para a sub-ferramenta mais adequada com base na sua pergunta. Exemplos típicos:

Consultar Receita e Lucro:

Consulte para mim a receita, lucro líquido e fluxo de caixa livre da TSLA nos últimos 3 anos

O Dexter chamará get_income_statements (DRE) e get_cash_flow_statements (DFC), organizando os dados em uma tabela.

Consultar Balanço Patrimonial:

Qual é o índice de endividamento mais recente da NVDA? Quanto ela possui em caixa e equivalentes?

Ler Documentos da SEC:

Ajude-me a ler a seção "Risk Factors" no último 10-K da AAPL

O Dexter chamará a ferramenta read_filings para capturar o conteúdo do 10-K e localizar a seção correspondente.

Consultar Insider Trading:

Como foram as transações de insiders das ações FAANG no último trimestre?

Todos os dados brutos das chamadas de ferramentas são registrados em arquivos JSONL no diretório .dexter/scratchpad/ para auditoria posterior.

Passo 6: Ativar Habilidade de Valuation DCF

O valuation DCF (Fluxo de Caixa Descontado) é uma das habilidades integradas do Dexter. Quando sua pergunta envolve "valor intrínseco" ou "valuation", o Agent chama automaticamente a ferramenta skill para carregar src/skills/dcf/SKILL.md e segue os passos:

1. Obter o Fluxo de Caixa Livre (FCF) histórico da empresa
2. Estimar premissas de taxa de crescimento para os próximos 5-10 anos
3. Calcular o Custo Médio Ponderado de Capital (WACC)
4. Descontar para o valor presente
5. Gerar o intervalo de valuation final + análise de sensibilidade

Exemplo de consulta:

Qual é o valor intrínseco DCF da MSFT? Por favor, forneça resultados sob premissas conservadoras, base e otimistas

Passo 7: Depuração e Logs do Scratchpad

Cada consulta no Dexter gera um arquivo JSONL em .dexter/scratchpad/, com o formato de nome:

AAAA-MM-DD-HHMMSS_<id_da_sessao>.jsonl

Cada linha é um registro estruturado:

{"type":"init","timestamp":"2026-03-27T10:00:00.000Z","query":"Qual é o valor intrínseco DCF da AAPL?"}
{"type":"tool_start","timestamp":"2026-03-27T10:00:01.000Z","toolName":"get_cash_flow_statements","args":{"ticker":"AAPL","period":"annual","limit":5}}
{"type":"tool_result","timestamp":"2026-03-27T10:00:03.000Z","toolName":"get_cash_flow_statements","result":{"freeCashFlow":[67800000000, 73000000000, ...]},"llmSummary":"O fluxo de caixa livre da AAPL cresceu continuamente nos últimos 5 anos, com uma taxa composta de cerca de 9,2%"}
{"type":"thinking","timestamp":"2026-03-27T10:00:05.000Z","content":"Dados de FCF obtidos, agora preciso das expectativas de crescimento de analistas e parâmetros WACC..."}

Se notar que o resultado de uma ferramenta está incorreto, basta abrir este arquivo para localizar o problema. Você também pode usar jq para filtragem rápida:

# Ver apenas resultados de ferramentas
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "tool_result")'

# Ver o processo de raciocínio do Agent
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "thinking")'

---

Solução de Problemas Comuns

1. Mensagem OPENAI_API_KEY not found em tempo de execução

Este é o erro mais comum. Verifique se o arquivo .env existe e se o caminho está correto:

ls -la .env

Confirme se o arquivo contém OPENAI_API_KEY=... ou a combinação OPENAI_API_KEY + OPENAI_BASE_URL. Se estiver usando Defapi, ambos devem estar presentes.

2. Dados financeiros retornando resultados vazios

Os dados gratuitos do Financial Datasets são limitados a AAPL, NVDA e MSFT. Consultas de outras ações retornarão vazio. Você pode:

• Verificar seu plano de assinatura em financialdatasets.ai
• Confirmar se a FINANCIAL_DATASETS_API_KEY foi inserida corretamente no .env

3. Timeout na chamada do modelo

O timeout padrão das APIs da Anthropic e Google é de 60 segundos. Se a conexão com serviços estrangeiros estiver instável, você pode ajustar maxAttempts e o tempo de espera de reiteração em src/model/llm.ts. Para uso prolongado, recomenda-se o acesso via Defapi para maior estabilidade.

4. Agent em loop infinito

O Dexter possui uma proteção maxIterations (padrão 10 passos). Se uma tarefa exigir mais passos, você pode ajustar este parâmetro em src/agent/agent.ts. Quando os passos se esgotam, o Agent retorna a conclusão intermediária atual como resultado final.

5. Dados incompletos em chamadas de ferramentas

O parâmetro limit no Financial Datasets controla o número de anos retornados; por padrão, pode retornar apenas 1 ano. Ao fazer a pergunta, você pode instruir o Dexter a especificar limit=5 ou limit=10.

6. Arquivos Scratchpad vazios ou não gerados

O Scratchpad é gerenciado por src/agent/scratchpad.ts. Se a variável de ambiente SKIP_SCRATCHPAD=true estiver configurada, os arquivos não serão gravados. Certifique-se de que esta variável não esteja no .env.

---

Leituras Adicionais / Direções Avançadas

Integração com WhatsApp como Assistente de Pesquisa Móvel

O Dexter suporta o recebimento de mensagens via WhatsApp Gateway. Desde que seu celular e o Dexter estejam na mesma rede:

# Escaneie o QR Code para vincular a conta do WhatsApp
bun run gateway:login

# Inicie o Gateway
bun run gateway

Então, envie uma mensagem para si mesmo no WhatsApp e o Dexter responderá. Assim, você pode consultar os dados financeiros das empresas em sua carteira durante o deslocamento.

Configurações detalhadas em src/gateway/channels/whatsapp/README.md.

Executar Suíte de Avaliação para Validar Precisão

O Dexter possui um framework de avaliação integrado via LangSmith:

# Executar avaliação em todas as questões de teste
bun run src/evals/run.ts

# Amostra aleatória de 10 questões
bun run src/evals/run.ts --sample 10

A avaliação usa o método LLM-as-Judge, e os resultados são enviados para o LangSmith Dashboard.

Usar Modelos Locais com Ollama

Se você deseja total independência de APIs externas:

# Inicie o Ollama (requer instalação prévia)
ollama serve

# Configure no .env
OLLAMA_BASE_URL=http://127.0.0.1:11434

Em seguida, alterne na CLI para ollama:qwen2.5 ou outro modelo local. Nota: a capacidade de tool calling de modelos locais pode não ser tão estável quanto GPT-5.4 ou Claude Sonnet.

Personalizar SKILL.md para Novas Habilidades

As habilidades do Dexter são definidas via SKILL.md, contendo YAML frontmatter e instruções em markdown. Para criar uma nova habilidade:

1. Crie um novo diretório em src/skills/, ex: src/skills/dupont/
2. Escreva o SKILL.md:

---
name: dupont-analysis
description: Análise Dupont - Decompõe o ROE em margem líquida, giro de ativos e multiplicador de patrimônio
---

# Habilidade de Análise Dupont

Você é um analista financeiro. Execute os seguintes passos para o ticker fornecido:

1. Obtenha lucro líquido, receita, ativos totais e patrimônio líquido
2. Calcule os três indicadores de decomposição:
   - Margem Líquida = Lucro Líquido / Receita
   - Giro de Ativos = Receita / Ativos Totais
   - Multiplicador de Patrimônio = Ativos Totais / Patrimônio Líquido
3. Calcule ROE = Produto dos três indicadores
4. Compare com a média do setor e forneça uma nota (1-10)

1. Reinicie o Dexter; a nova habilidade será descoberta e injetada no prompt de sistema.

Acesso via Defapi para Reduzir Custos

Para cenários de uso de alta frequência (monitoramento automático, relatórios periódicos), os custos de API são consideráveis. O uso do Defapi pode economizar cerca de 50%:

# .env
OPENAI_API_KEY=sua-chave-api-defapi
OPENAI_BASE_URL=https://api.defapi.com/v1

O Defapi é compatível com todos os modelos da interface v1/chat/completions. O Dexter não precisa de mudanças no código, apenas da substituição da chave e da URL base.