Déploiement et Pratique de Dexter : Laissez l'IA lire les documents SEC et réaliser des valorisations DCF pour vous

Introduction

Dexter est un Agent de recherche financière autonome s'exécutant dans le terminal. Posez-lui une question complexe, et il décomposera automatiquement la tâche, appellera plusieurs outils de données et procédera à une vérification croisée des résultats jusqu'à fournir une conclusion étayée par des données — comme si vous aviez un analyste senior infatigable à vos côtés.

Ses capacités principales incluent :

• Lecture de documents SEC : Extraction automatique des rapports 10-K, 10-Q, 8-K et autres documents de divulgation.
• Consultation de données en temps réel : Cours de bourse, indicateurs financiers, flux de trésorerie (cash flow), bilans.
• Estimation de la valeur intrinsèque DCF : Compétence DCF intégrée pilotée par un fichier SKILL.md pour exécuter des actualisations de flux de trésorerie.
• Boucle d'auto-vérification : Vérifie ses propres résultats intermédiaires et itère jusqu'à ce que la conclusion soit valide.
• Protection contre les boucles infinies : Limite de pas intégrée pour éviter que l'Agent ne devienne incontrôlable.

L'ensemble du projet est écrit en TypeScript, reposant sur LangChain + Ink (React pour le CLI), et fonctionne sous l'environnement Bun 1.0+. Si vous souhaitez exploiter ces capacités à moindre coût, vous pouvez basculer le fournisseur de LLM vers Defapi, dont le prix de l'API est environ la moitié du tarif officiel.

---

Profil des lecteurs cibles

• Développeurs ayant 1 à 5 ans d'expérience, avec une compréhension de base de l'architecture des Agents IA (Tool Calling, Agentic Loop).
• Investisseurs indépendants ou professionnels de la Fintech souhaitant utiliser des outils IA pour assister leur recherche fondamentale.
• Ingénieurs voulant apprendre à intégrer de multiples sources de données (SEC, Financial Datasets, Exa) dans un projet réel.
• Utilisateurs intéressés par la recherche quantitative financière souhaitant mettre en place un pipeline de recherche local.

---

Dépendances et Environnement

---

Arborescence complète du projet

dexter/
├── .dexter/
│   └── settings.json          # Configuration de l'Agent (choix modèle/fournisseur)
├── src/
│   ├── agent/                  # Cœur de l'Agent : logique de boucle, prompts, scratchpad
│   │   ├── agent.ts           # Boucle principale Agentic Loop
│   │   ├── prompts.ts         # Prompts système
│   │   └── scratchpad.ts      # Historique des appels d'outils
│   ├── cli.tsx                # Point d'entrée du rendu Ink/React CLI
│   ├── index.tsx              # Point d'entrée du programme
│   ├── components/            # Composants UI CLI (Ink)
│   ├── hooks/                 # Hooks React (AgentRunner, ModelSelector)
│   ├── model/
│   │   └── llm.ts            # Couche d'abstraction LLM multi-fournisseurs
│   ├── tools/
│   │   ├── registry.ts       # Registre des outils
│   │   ├── finance/          # Outils financiers : cours, finances, rapports, transactions d'initiés
│   │   ├── search/           # Outils de recherche web (Exa / Tavily)
│   │   ├── browser/          # Automatisation de navigateur Playwright
│   │   └── descriptions/     # Descriptions des outils (injectées dans le prompt système)
│   ├── skills/               # Répertoire des compétences SKILL.md
│   │   └── dcf/
│   │       └── SKILL.md     # Compétence d'estimation de valeur intrinsèque DCF
│   ├── evals/               # Framework d'évaluation LangSmith
│   └── utils/               # Variables d'environnement, config, cache
├── scripts/
│   └── release.sh
├── .env                     # Clés API (ignorées par git)
└── package.json

---

Étapes pas à pas

Étape 1 : Installation de Bun et clonage du projet

Si Bun n'est pas installé sur votre machine, installez-le d'abord. Compatible Windows/macOS/Linux :

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

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

Vérifier l'installation :

bun --version
# Affiche par ex. : Bun v1.2.x

Ensuite, clonez le dépôt Dexter :

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

Étape 2 : Configuration des variables d'environnement .env

Copiez le fichier de modèle d'environnement :

cp env.example .env

Ouvrez .env avec votre éditeur et saisissez vos clés. Point important sur l'intégration Defapi — si vous voulez utiliser Defapi à la place d'OpenAI (économie de 50%), configurez comme suit :

# .env

# ── Fournisseurs LLM ──────────────────────────────────
# Option A : Utilisation directe d'OpenAI (défaut)
OPENAI_API_KEY=sk-votre-cle-openai

# Option B : Accès à OpenAI via Defapi (recommandé, économise 50%)
# OPENAI_API_KEY=sk-votre-cle-defapi
# OPENAI_BASE_URL=https://api.defapi.com/v1

# Autres fournisseurs optionnels
ANTHROPIC_API_KEY=sk-ant-votre-cle-anthropic
GOOGLE_API_KEY=votre-cle-google
XAI_API_KEY=votre-cle-xai
OPENROUTER_API_KEY=votre-cle-openrouter

# Modèles locaux (OLLAMA)
OLLAMA_BASE_URL=http://127.0.0.1:11434

# ── Données Financières ───────────────────────────────
# Données institutionnelles, AAPL/NVDA/MSFT gratuits
FINANCIAL_DATASETS_API_KEY=votre-cle-financial-datasets

# ── Recherche Web ────────────────────────────────────
# Priorité à Exa, Tavily en secours
EXASEARCH_API_KEY=votre-cle-exa
TAVILY_API_KEY=votre-cle-tavily

Installez les dépendances :

bun install

Étape 3 : Lancer Dexter en mode interactif

Démarrez le CLI interactif :

bun start

Vous verrez une interface colorée basée sur Ink dans le terminal. Saisissez directement votre question financière, par exemple :

Quelle a été la croissance du chiffre d'affaires d'AAPL ces 5 dernières années ? Quelle est sa valeur intrinsèque DCF actuelle ?

Dexter commencera automatiquement son travail : décomposition de la tâche → recherche de données financières → lecture des documents SEC → exécution de la compétence DCF → synthèse de la conclusion. Chaque appel d'outil s'affiche en temps réel.

Pour déboguer tout en modifiant le code, utilisez le mode watch :

bun dev

Étape 4 : Changer de modèle / fournisseur

Dans le CLI, tapez la commande /model pour basculer entre les fournisseurs et modèles. Dexter reconnaît automatiquement les préfixes suivants :

Par exemple, pour passer à Claude :

/model claude-sonnet-4-7

Étape 5 : Utiliser les outils financiers pour analyser des actions

Le cœur de Dexter est l'outil financial_search, qui délègue la tâche au sous-outil le plus approprié selon votre question. Voici des exemples de requêtes typiques :

Recherche de revenus et profits :

Donne-moi le chiffre d'affaires, le résultat net et le free cash-flow de TSLA pour les 3 dernières années.

Dexter appellera get_income_statements (compte de résultat) et get_cash_flow_statements (tableau des flux de trésorerie) pour les présenter sous forme de tableau.

Consultation du bilan :

Quel est le ratio d'endettement actuel de NVDA ? Quel est son montant de trésorerie et équivalents ?

Lecture de documents SEC :

Aide-moi à lire la section "Risk Factors" du dernier 10-K d'AAPL.

Dexter utilisera read_filings pour extraire le contenu du 10-K et cibler la section correspondante.

Transactions d'initiés :

Quelles ont été les transactions d'initiés pour les actions FAANG au cours du dernier trimestre ?

Toutes les données brutes des appels d'outils sont enregistrées dans des fichiers JSONL dans le répertoire .dexter/scratchpad/ pour audit ultérieur.

Étape 6 : Déclencher la compétence de valorisation DCF

La valorisation DCF (Discounted Cash Flow) est l'une des compétences intégrées de Dexter. Lorsque votre question porte sur la "valeur intrinsèque" ou la "valorisation", l'Agent appelle automatiquement l'outil skill pour charger src/skills/dcf/SKILL.md et suit les étapes :

1. Récupération de l'historique des flux de trésorerie disponibles (FCF).
2. Estimation des hypothèses de taux de croissance pour les 5-10 prochaines années.
3. Calcul du coût moyen pondéré du capital (WACC).
4. Actualisation à la date présente.
5. Sortie d'une plage de valorisation finale + analyse de sensibilité.

Exemple de requête :

Quelle est la valeur intrinsèque DCF de MSFT ? Donne-moi les résultats selon trois scénarios : conservateur, de base et optimiste.

Étape 7 : Débogage et consultation des journaux Scratchpad

Chaque requête génère un fichier JSONL dans .dexter/scratchpad/ avec le format suivant :

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

Chaque ligne est un enregistrement structuré :

{"type":"init","timestamp":"2026-03-27T10:00:00.000Z","query":"Quelle est la valeur intrinsèque DCF d'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":"Le FCF d'AAPL a cru continuellement ces 5 dernières années, avec un TCAC d'environ 9,2%"}
{"type":"thinking","timestamp":"2026-03-27T10:00:05.000Z","content":"Données FCF obtenues, maintenant besoin des prévisions de croissance des analystes et des paramètres WACC..."}

Si un appel d'outil semble incorrect, ouvrez ce fichier pour localiser le problème. Utilisez jq pour un filtrage rapide :

# Voir uniquement les résultats des outils
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "tool_result")'

# Voir le raisonnement de l'Agent
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "thinking")'

---

Dépannage des problèmes courants

1. Message OPENAI_API_KEY not found au lancement

C'est l'erreur la plus fréquente. Vérifiez que le fichier .env existe et que son chemin est correct :

ls -la .env

Assurez-vous qu'il contient OPENAI_API_KEY=... ou le combo OPENAI_API_KEY + OPENAI_BASE_URL. Si vous utilisez Defapi, les deux doivent être présents.

2. Données financières vides

Les données gratuites de Financial Datasets sont limitées à AAPL, NVDA et MSFT. Pour les autres actions, les résultats seront vides. Vous pouvez :

• Vérifier votre abonnement sur financialdatasets.ai.
• Confirmer que FINANCIAL_DATASETS_API_KEY est bien renseignée dans le .env.

3. Délai d'attente du modèle (Timeout)

Le timeout par défaut pour les API Anthropic et Google est de 60 secondes. Si votre connexion aux services étrangers est instable, ajustez maxAttempts et le temps d'attente des tentatives dans src/model/llm.ts. Pour un usage régulier, l'accès via Defapi est recommandé pour une meilleure stabilité.

4. L'Agent entre dans une boucle infinie

Dexter possède une protection maxIterations (10 étapes par défaut). Si une tâche nécessite plus d'étapes, ajustez ce paramètre dans src/agent/agent.ts. Une fois les étapes épuisées, l'Agent renvoie les conclusions intermédiaires actuelles au lieu de tourner à vide.

5. Données incomplètes via les outils

Le paramètre limit de Financial Datasets contrôle le nombre d'années retournées (souvent 1 par défaut). Lors de votre requête, demandez explicitement à Dexter de spécifier limit=5 ou limit=10.

6. Fichier Scratchpad vide ou non généré

Scratchpad est géré par src/agent/scratchpad.ts. Si la variable d'environnement SKIP_SCRATCHPAD=true est définie, aucun fichier ne sera écrit. Vérifiez son absence dans .env. De plus, chaque nouvelle requête crée un nouveau fichier.

---

Lectures complémentaires / Aller plus loin

Intégration WhatsApp pour un assistant de recherche mobile

Dexter peut recevoir des messages via une passerelle WhatsApp. Si votre téléphone et Dexter sont sur le même réseau :

# Scannez le QR code pour lier votre compte WhatsApp
bun run gateway:login

# Lancer la passerelle
bun run gateway

Envoyez-vous ensuite un message sur WhatsApp, et Dexter répondra. Pratique pour consulter les données financières de vos positions pendant vos déplacements.

Configuration détaillée dans src/gateway/channels/whatsapp/README.md.

Exécution de la suite d'évaluation pour vérifier la précision de l'Agent

Dexter inclut un framework d'évaluation piloté par LangSmith :

# Lancer l'évaluation sur toutes les questions de test
bun run src/evals/run.ts

# Tirer 10 questions au sort
bun run src/evals/run.ts --sample 10

L'évaluation utilise la méthode "LLM-as-Judge". Les résultats sont téléchargés sur le tableau de bord LangSmith.

Utiliser des modèles locaux avec Ollama

Si vous souhaitez ne dépendre d'aucune API externe :

# Lancer Ollama (doit être installé préalablement)
ollama serve

# Configurer dans .env
OLLAMA_BASE_URL=http://127.0.0.1:11434

Basculez ensuite sur ollama:qwen2.5 dans le CLI. Note : les modèles locaux peuvent être moins stables pour le Tool Calling que GPT-5.4 ou Claude Sonnet.

Personnaliser SKILL.md pour créer de nouvelles compétences

Les compétences de Dexter sont définies via SKILL.md. Chaque compétence contient un frontmatter YAML (nom, description) et des instructions Markdown. Pour en créer une nouvelle :

1. Créez un dossier sous src/skills/, ex: src/skills/dupont/.
2. Rédigez le SKILL.md :

---
name: dupont-analysis
description: Analyse DuPont - Décomposition du ROE en marge nette, rotation des actifs et levier financier
---

# Compétence Analyse DuPont

Vous êtes un analyste financier. Pour le ticker fourni, suivez ces étapes :

1. Obtenez le résultat net, le chiffre d'affaires, le total des actifs et les capitaux propres.
2. Calculez les trois indicateurs :
   - Marge nette = Résultat Net / Chiffre d'Affaires
   - Rotation des actifs = Chiffre d'Affaires / Total Actifs
   - Levier financier = Total Actifs / Capitaux Propres
3. Calculez le ROE = Produit des trois indicateurs.
4. Comparez à la moyenne du secteur et donnez une note (1-10).

1. Redémarrez Dexter ; la nouvelle compétence sera automatiquement injectée.

Utiliser Defapi pour réduire les coûts d'API

Pour des scénarios de haute fréquence (surveillance automatique, génération de rapports périodiques), les coûts d'API peuvent être significatifs. L'utilisation de Defapi permet d'économiser environ 50% :

# .env
OPENAI_API_KEY=votre-cle-api-defapi
OPENAI_BASE_URL=https://api.defapi.com/v1

Defapi est compatible avec tous les modèles via l'interface v1/chat/completions, sans modification de code.