Despliegue y Práctica de Dexter: Deja que la IA lea documentos de la SEC y realice valoraciones DCF por ti

Introducción

Dexter es un Agente de investigación financiera autónomo que se ejecuta en la terminal. Si le haces una pregunta compleja, descompondrá automáticamente la tarea, llamará a múltiples herramientas de datos y cruzará los resultados hasta ofrecer una conclusión respaldada por datos, como si tuvieras a un analista senior que nunca se cansa.

Sus capacidades principales incluyen:

• Lectura de documentos de la SEC: Captura automática de informes 10-K, 10-Q, 8-K y otros documentos regulatorios.
• Consulta de cotizaciones en tiempo real: Precios de acciones, indicadores financieros, flujo de caja y balances generales.
• Estimación de valor intrínseco DCF: Habilidad DCF integrada impulsada por SKILL.md para ejecutar descuentos de flujo de caja de forma autónoma.
• Bucle de auto-verificación: Revisa sus propios resultados intermedios e itera hasta que la conclusión sea sólida.
• Protección de bucle: Límite de pasos integrado para evitar que el Agente pierda el control.

Todo el proyecto está escrito en TypeScript, basado en LangChain + Ink (React para CLI) y se ejecuta en un entorno Bun 1.0+. Si deseas aprovechar estas capacidades a un costo menor, puedes cambiar el proveedor de LLM a Defapi, donde el precio de la API es solo la mitad del oficial.

---

Perfil del Lector Objetivo

• Desarrolladores con 1-5 años de experiencia con conocimientos básicos en arquitecturas de IA (Tool Calling, Agentic Loop).
• Inversores independientes o profesionales de Fintech que deseen utilizar herramientas de IA para apoyar la investigación fundamental.
• Ingenieros que quieran aprender a integrar múltiples fuentes de datos (SEC, Financial Datasets, Exa) en proyectos reales.
• Usuarios interesados en la investigación cuantitativa financiera que deseen construir un flujo de trabajo de investigación local.

---

Dependencias y Entorno Principales

---

Árbol de Estructura Completa del Proyecto

dexter/
├── .dexter/
│   └── settings.json          # Configuración del Agente (selección de modelo/proveedor)
├── src/
│   ├── agent/                  # Núcleo del Agente: lógica de bucle, prompts, scratchpad
│   │   ├── agent.ts           # Bucle principal Agentic Loop
│   │   ├── prompts.ts         # Prompts del sistema
│   │   └── scratchpad.ts      # Historial de llamadas a herramientas
│   ├── cli.tsx                # Punto de entrada de renderizado CLI Ink/React
│   ├── index.tsx              # Punto de entrada del programa
│   ├── components/            # Componentes UI de CLI (Ink)
│   ├── hooks/                 # React hooks (AgentRunner, ModelSelector)
│   ├── model/
│   │   └── llm.ts            # Capa de abstracción de LLM para múltiples proveedores
│   ├── tools/
│   │   ├── registry.ts       # Registro de herramientas
│   │   ├── finance/          # Herramientas financieras: cotizaciones, finanzas, informes
│   │   ├── search/           # Herramientas de búsqueda web (Exa / Tavily)
│   │   ├── browser/          # Automatización de navegador Playwright
│   │   └── descriptions/     # Descripciones de herramientas (inyectadas en prompts)
│   ├── skills/               # Directorio de habilidades SKILL.md
│   │   └── dcf/
│   │       └── SKILL.md     # Habilidad de valoración de valor intrínseco DCF
│   ├── evals/               # Framework de evaluación LangSmith
│   └── utils/               # Variables de entorno, configuración, caché
├── scripts/
│   └── release.sh
├── .env                     # Claves API (gitignored)
└── package.json

---

Pasos Detallados

Paso 1: Instalar Bun y Clonar el Proyecto

Si no tienes Bun en tu máquina, instálalo primero. Compatible con Windows/macOS/Linux:

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

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

Verifica la instalación:

bun --version
# Salida similar a: Bun v1.2.x

Luego clona el repositorio de Dexter:

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

Paso 2: Configurar Variables de Entorno .env

Copia el archivo de plantilla de variables de entorno:

cp env.example .env

Abre .env con un editor y rellena tus claves. Nota importante sobre el acceso a Defapi: si deseas usar Defapi en lugar de OpenAI (ahorrando un 50%), configúralo de la siguiente manera:

# .env

# ── Proveedores de LLM ──────────────────────────────────────
# Opción A: Usar OpenAI directamente (por defecto)
OPENAI_API_KEY=sk-tu-clave-openai

# Opción B: Acceso a OpenAI vía Defapi (Recomendado, ahorro del 50%)
# OPENAI_API_KEY=sk-tu-clave-defapi
# OPENAI_BASE_URL=https://api.defapi.com/v1

# Otros proveedores de LLM opcionales
ANTHROPIC_API_KEY=sk-ant-tu-clave-anthropic
GOOGLE_API_KEY=tu-clave-google
XAI_API_KEY=tu-clave-xai
OPENROUTER_API_KEY=tu-clave-openrouter

# Modelo local (OLLAMA)
OLLAMA_BASE_URL=http://127.0.0.1:11434

# ── Datos Financieros ───────────────────────────────────────
# Datos de mercado institucionales, AAPL/NVDA/MSFT gratis
FINANCIAL_DATASETS_API_KEY=tu-clave-financial-datasets

# ── Búsqueda Web ───────────────────────────────────────
# Prioridad para Exa, Tavily como respaldo
EXASEARCH_API_KEY=tu-clave-exa
TAVILY_API_KEY=tu-clave-tavily

Instala las dependencias:

bun install

Paso 3: Ejecutar Dexter en Modo Interactivo

Inicia la CLI interactiva:

bun start

Verás una interfaz colorida basada en Ink en la terminal. Escribe directamente tu pregunta financiera, por ejemplo:

¿Cómo ha sido el crecimiento de ingresos de AAPL en los últimos 5 años? ¿Cuál es su valor intrínseco DCF actual?

Dexter comenzará a trabajar automáticamente: desglosar tarea → consultar datos financieros → leer archivos SEC → ejecutar habilidad DCF → resumir conclusiones. Cada llamada a herramienta se mostrará en tiempo real.

Si deseas depurar mientras modificas el código, usa el modo watch:

bun dev

Paso 4: Cambiar de Modelo / Proveedor

Dentro de la CLI, usa el comando /model para cambiar de proveedor y modelo. Dexter soporta el reconocimiento automático mediante prefijos:

Por ejemplo, para cambiar a Claude:

/model claude-sonnet-4-7

Paso 5: Uso de Herramientas Financieras para Consultar Acciones

El núcleo de Dexter es la herramienta financial_search, que delega automáticamente a la sub-herramienta más adecuada según tu pregunta. Ejemplos típicos:

Consulta de ingresos y beneficios:

Consulta los ingresos, beneficio neto y flujo de caja libre de TSLA de los últimos 3 años

Dexter llamará a get_income_statements y get_cash_flow_statements, devolviendo una tabla organizada.

Consulta de balance general:

¿Cuál es el ratio de endeudamiento más reciente de NVDA? ¿Cuánto efectivo y equivalentes tiene?

Lectura de archivos SEC:

Ayúdame a leer la sección "Risk Factors" del último informe 10-K de AAPL

Dexter llamará a read_filings para extraer el contenido del 10-K y localizar la sección correspondiente.

Consulta de transacciones internas (insider trading):

¿Cómo han sido las transacciones de insiders de las acciones FAANG en el último trimestre?

Todos los datos brutos de las llamadas se registran en archivos JSONL en el directorio .dexter/scratchpad/ para auditoría posterior.

Paso 6: Activar la Habilidad de Valoración DCF

La valoración DCF (Descuento de Flujos de Caja) es una habilidad integrada. Cuando tu pregunta mencione "valor intrínseco" o "valoración", el Agente llamará a la herramienta skill para cargar src/skills/dcf/SKILL.md y seguirá estos pasos:

1. Obtener el flujo de caja libre (FCF) histórico de la empresa.
2. Estimar supuestos de tasa de crecimiento para los próximos 5-10 años.
3. Calcular el Costo Promedio Ponderado de Capital (WACC).
4. Descontar al momento actual.
5. Entregar un rango de valoración final + análisis de sensibilidad.

Consulta de ejemplo:

¿Cuál es el valor intrínseco DCF de MSFT? Por favor, ofrece resultados bajo supuestos conservador, base y optimista.

Paso 7: Depuración y Revisión de Logs en Scratchpad

Cada consulta genera un archivo JSONL en .dexter/scratchpad/ con el formato:

YYYY-MM-DD-HHMMSS_<session_id>.jsonl

Cada línea es un registro estructurado:

{"type":"init","timestamp":"2026-03-27T10:00:00.000Z","query":"¿Cuál es el valor intrínseco DCF de 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":"El flujo de caja libre de AAPL ha crecido constantemente en los últimos 5 años con una tasa compuesta del 9.2%"}
{"type":"thinking","timestamp":"2026-03-27T10:00:05.000Z","content":"Datos de FCF obtenidos, ahora necesito obtener las expectativas de crecimiento de analistas y parámetros WACC..."}

Si una llamada falla, abre este archivo para localizar el problema. También puedes usar jq para filtrar rápidamente:

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

# Ver el proceso de razonamiento del Agente
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "thinking")'

---

Solución de Problemas Comunes

1. Error OPENAI_API_KEY not found

Es el error más común. Verifica que el archivo .env exista y la ruta sea correcta:

ls -la .env

Confirma que contiene OPENAI_API_KEY=... o la combinación de OPENAI_API_KEY + OPENAI_BASE_URL. Si usas Defapi, ambos deben estar presentes.

2. Datos financieros devuelven resultados vacíos

Los datos gratuitos de Financial Datasets se limitan a AAPL, NVDA y MSFT. Para otras acciones, devolverá vacío. Puedes:

• Revisar tu plan de suscripción en financialdatasets.ai.
• Confirmar que FINANCIAL_DATASETS_API_KEY está correctamente en el .env.

3. Tiempo de espera del modelo (Timeout)

El timeout por defecto para Anthropic y Google es de 60s. Si la conexión es inestable, ajusta maxAttempts y el tiempo de reintento en src/model/llm.ts. Para uso prolongado, se recomienda Defapi por su estabilidad en rutas optimizadas.

4. El Agente entra en un bucle infinito

Dexter tiene una protección maxIterations (10 pasos por defecto). Si una tarea requiere más, ajústalo en src/agent/agent.ts. Al agotar los pasos, el Agente devolverá la conclusión intermedia actual en lugar de seguir girando.

5. Datos incompletos en llamadas a herramientas

El parámetro limit en Financial Datasets controla el número de años devueltos (por defecto puede ser solo 1). Al preguntar, puedes pedirle a Dexter que especifique limit=5 o limit=10.

6. Archivos Scratchpad vacíos o no generados

Gestionado por src/agent/scratchpad.ts. Si la variable SKIP_SCRATCHPAD=true está configurada, no se escribirán. Asegúrate de que no esté en el .env. Además, cada consulta crea un archivo nuevo, no se añade a los antiguos.

---

Lectura Extendida / Direcciones Avanzadas

Integración con WhatsApp para Asistente Móvil

Dexter permite recibir mensajes vía WhatsApp Gateway. Con tu teléfono y Dexter en la misma red:

# Escanea el código QR para vincular WhatsApp
bun run gateway:login

# Inicia el Gateway
bun run gateway

Luego envíate un mensaje por WhatsApp y Dexter responderá. Ideal para consultar datos financieros mientras viajas.

Configuración detallada en src/gateway/channels/whatsapp/README.md.

Ejecutar Suite de Evaluación de Precisión

Dexter incluye un framework de evaluación impulsado por LangSmith:

# Ejecutar evaluación sobre todas las preguntas de prueba
bun run src/evals/run.ts

# Muestrear 10 preguntas al azar
bun run src/evals/run.ts --sample 10

Utiliza el método LLM-as-Judge y sube los resultados al Dashboard de LangSmith. Útil para validar cambios en el cálculo de indicadores financieros.

Uso de Modelos Locales con Ollama

Si prefieres no depender de APIs externas:

# Inicia Ollama (debe estar instalado previamente)
ollama serve

# Configura en .env
OLLAMA_BASE_URL=http://127.0.0.1:11434

Cambia en la CLI a ollama:qwen2.5 u otro modelo local. Nota: la capacidad de Tool Calling de modelos locales puede ser menos estable que GPT-5.4 o Claude Sonnet.

Escribir Nuevas Habilidades en SKILL.md

Las habilidades se definen mediante SKILL.md, con un frontmatter YAML (nombre, descripción) e instrucciones en markdown. Para crear una:

1. Crea un directorio en src/skills/, ej: src/skills/dupont/.
2. Escribe el SKILL.md:

---
name: dupont-analysis
description: Análisis DuPont - Desglosa el ROE en margen neto, rotación de activos y apalancamiento.
---

# Habilidad de Análisis DuPont

Eres un analista financiero. Sigue estos pasos para el ticker ingresado:

1. Obtén el beneficio neto, ingresos operativos, activos totales y capital contable.
2. Calcula los tres componentes:
   - Margen Neto = Beneficio Neto / Ingresos
   - Rotación de Activos = Ingresos / Activos Totales
   - Multiplicador de Capital = Activos Totales / Capital Contable
3. Calcula ROE = Producto de los tres indicadores.
4. Compara con el promedio de la industria y asigna una puntuación (1-10).

1. Reinicia Dexter; la habilidad será detectada e inyectada automáticamente.

Reducir Costos con Defapi

Para casos de uso de alta frecuencia (monitoreo automático, generación de reportes periódicos), los costos de la API son relevantes. Usar Defapi permite ahorrar aproximadamente un 50%:

# .env
OPENAI_API_KEY=tu-clave-api-defapi
OPENAI_BASE_URL=https://api.defapi.com/v1

Defapi es compatible con todos los modelos de la interfaz v1/chat/completions. No requiere cambios de código, solo reemplazar la clave y la URL base.