From a31f6e21b11a07e6db0529f439f2a44e78b9cd32 Mon Sep 17 00:00:00 2001
From: OpenSquared <opensquaredgeneva@gmail.com>
Date: Tue, 23 Jun 2026 18:59:24 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20v6.1=20=E2=80=94=20Specialist=20Desks?=
 =?UTF-8?q?=20v2=20(COT,=20Forward=20Curves,=20Surprise,=20Hawk/Dove)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Section 12 refonte complète : 4 nouvelles sous-sections documentant le
COT CFTC (19 marchés par codes contrat stables), les Forward Curves
yfinance (contango/backwardation), le Surprise Index (actual-consensus)
et le Hawk/Dove Text Scorer GPT-4o-mini. Architecture : +2 tables DB
(cot_data, forward_curve_data), +6 colonnes specialist_reports. Schéma
et étape 4b mis à jour avec les nouvelles sources injectées dans le
contexte IA.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 GeoOptions_Documentation_Complete.html | 156 ++++++++++++++++++++++---
 1 file changed, 137 insertions(+), 19 deletions(-)

diff --git a/GeoOptions_Documentation_Complete.html b/GeoOptions_Documentation_Complete.html
index d6c34e5..16f7d7f 100644
--- a/GeoOptions_Documentation_Complete.html
+++ b/GeoOptions_Documentation_Complete.html
@@ -186,10 +186,14 @@ li { margin-bottom: 4px; font-size: 9.5pt; }
     <li><a href="#s2c-diagram">2c.1 Graphe Visuel du Pipeline</a></li>
     <li><a href="#s2c-formulas">2c.2 Démonstration des Calculs Étape par Étape</a></li>
   </ul>
-  <li><a href="#s12">12. Specialist Desks — Configuration par Asset Class</a></li>
+  <li><a href="#s12">12. Specialist Desks v2 — COT · Forward Curves · Surprise · Hawk/Dove</a></li>
   <ul class="toc-list toc-indent">
     <li><a href="#s12-1">12.1 Architecture et tables DB</a></li>
     <li><a href="#s12-2">12.2 Injection dans les prompts IA</a></li>
+    <li><a href="#s12-3">12.3 COT Positioning — CFTC Socrata</a></li>
+    <li><a href="#s12-4">12.4 Forward Curves</a></li>
+    <li><a href="#s12-5">12.5 Surprise Index</a></li>
+    <li><a href="#s12-6">12.6 Hawk/Dove Text Scorer</a></li>
   </ul>
   <li><a href="#s13">13. Bibliothèque Patterns — Find Similar &amp; Merge</a></li>
   <ul class="toc-list toc-indent">
@@ -316,7 +320,7 @@ li { margin-bottom: 4px; font-size: 9.5pt; }
       <div class="arch-module">
         <span class="arch-module-icon">🏦</span>
         <div class="arch-module-name">Specialist Desks</div>
-        <div class="arch-module-detail">7 desks · rapports · injection IA duale</div>
+        <div class="arch-module-detail">7 desks · COT 19 marchés · Forward Curves · Surprise · Hawk/Dove</div>
       </div>
     </div>
   </div>
@@ -344,6 +348,8 @@ li { margin-bottom: 4px; font-size: 9.5pt; }
       <span class="arch-db-chip">asset_class_configs</span>
       <span class="arch-db-chip">ai_call_logs</span>
       <span class="arch-db-chip">fred_data</span>
+      <span class="arch-db-chip">cot_data</span>
+      <span class="arch-db-chip">forward_curve_data</span>
     </div>
   </div>
 
@@ -375,6 +381,11 @@ li { margin-bottom: 4px; font-size: 9.5pt; }
       <div class="arch-ext-name">FRED API</div>
       <div class="arch-ext-detail">CPI · NFP · Taux Fed · PCE · Chômage</div>
     </div>
+    <div class="arch-ext-card">
+      <span class="arch-ext-icon">📋</span>
+      <div class="arch-ext-name">CFTC Socrata</div>
+      <div class="arch-ext-detail">COT hebdo · 19 marchés · codes contrat stables · gratuit sans clé</div>
+    </div>
   </div>
 
 </div>
@@ -384,7 +395,8 @@ li { margin-bottom: 4px; font-size: 9.5pt; }
   <strong>Backend :</strong> Python 3.11, FastAPI, APScheduler, SQLite (aiosqlite), yfinance, feedparser, OpenAI SDK v1.x<br>
   <strong>Frontend :</strong> React 18, Vite, Recharts, Tailwind CSS<br>
   <strong>Déploiement :</strong> VPS Linux (Ubuntu 22.04), lancement via <code>start_all.bat</code> (Windows dev) ou <code>pm2</code> (VPS)<br>
-  <strong>IA :</strong> GPT-4o (modèle principal), GPT-4o-mini (résumés rapides, 5x moins cher)
+  <strong>IA :</strong> GPT-4o (modèle principal), GPT-4o-mini (résumés rapides, Hawk/Dove scorer, 5x moins cher)<br>
+  <strong>Données Desks :</strong> CFTC Socrata (COT gratuit, sans clé), yfinance (Forward Curves)
 </div>
 
 <h3 id="s1-4">1.4 Les 19 Pages du Cockpit</h3>
@@ -576,8 +588,13 @@ final_relevance = clamp(base_relevance + ai_alignment, 0, 100)
 
 <div class="step-block">
   <div class="step-num">Étape 4b — Chargement des Specialist Desks</div>
-  <p><strong>Input :</strong> Table <code>asset_class_configs</code> (7 desks) + <code>specialist_reports</code> + <code>report_desk_links</code></p>
-  <p><strong>Traitement :</strong> Pour chaque desk actif, le système charge les fondamentaux, la sensibilité macro par régime, les seuils de prix significatifs/extrêmes, et les 5 prochains rapports planifiés triés par date et importance.</p>
+  <p><strong>Input :</strong> Table <code>asset_class_configs</code> (7 desks) + <code>specialist_reports</code> + <code>report_desk_links</code> + <code>cot_data</code> + <code>forward_curve_data</code></p>
+  <p><strong>Traitement :</strong> Pour chaque desk actif, le système charge les fondamentaux, la sensibilité macro par régime, les seuils de prix significatifs/extrêmes, et les 5 prochains rapports planifiés triés par date et importance. Il enrichit le bloc avec :</p>
+  <ul>
+    <li><strong>COT net% OI</strong> par commodity (ex : Gold +53%, WTI +6%, 10Y T-Notes −17%) — positionnement spéculatif CFTC hebdomadaire</li>
+    <li><strong>Forward Curve structure</strong> par asset (contango / backwardation / flat) — signal de pression directionnelle physique</li>
+    <li><strong>Surprise scores</strong> des derniers rapports (actual − consensus) + estimations consensus à venir</li>
+  </ul>
   <p><strong>Output :</strong> Un bloc de contexte structuré par desk, injecté dans <strong>deux prompts distincts</strong> :</p>
   <ul>
     <li><strong>Scoring (Étape 5) :</strong> seuls les desks couverts par les patterns scorés ce cycle sont injectés — contexte ciblé pour réduire les tokens</li>
@@ -2497,17 +2514,19 @@ reliability_score = win_rate × log(n+1)
 
 <!-- SECTION 12 -->
 <h2 id="s12">12. Specialist Desks — Configuration par Asset Class</h2>
-<p>Les Specialist Desks modélisent la réalité d'un hedge fund multi-stratégies où chaque desk (forex, metals, agri, énergie, indices, crypto, obligations) a une culture, des drivers et des rapports critiques spécifiques que le trader généraliste ne connaît pas par défaut.</p>
+<p>Les Specialist Desks modélisent la réalité d'un hedge fund multi-stratégies où chaque desk (forex, metals, agri, énergie, indices, crypto, obligations) a une culture, des drivers et des rapports critiques spécifiques que le trader généraliste ne connaît pas par défaut. En Phase 6 v2, chaque desk est enrichi de données de positionnement marché en temps réel : COT CFTC, Forward Curves, Surprise Index et scorer Hawk/Dove.</p>
 
 <h3 id="s12-1">12.1 Architecture et Tables DB</h3>
-<p>Trois tables nouvelles créées en Phase 6 :</p>
+<p>Cinq tables dédiées (Phase 6) :</p>
 
 <table>
   <thead><tr><th>Table</th><th>Rôle</th><th>Colonnes clés</th></tr></thead>
   <tbody>
-    <tr><td><code>asset_class_configs</code></td><td>Configuration par desk (7 desks)</td><td>asset_class, display_name, icon, fundamentals (TEXT libre), macro_sensitivity (JSON), price_delta_thresholds (JSON)</td></tr>
-    <tr><td><code>specialist_reports</code></td><td>Catalogue de rapports (manuel + auto)</td><td>id, name, source, cadence, next_date, importance (1–3), notes</td></tr>
+    <tr><td><code>asset_class_configs</code></td><td>Configuration par desk (7 desks)</td><td>asset_class, display_name, icon, fundamentals (TEXT), macro_sensitivity (JSON), price_delta_thresholds (JSON)</td></tr>
+    <tr><td><code>specialist_reports</code></td><td>Catalogue rapports manuel + auto</td><td>id, name, source, cadence, next_date, importance (1–3), consensus_estimate, actual_value, surprise_score, text_sentiment_score, text_sentiment_label, text_sentiment_summary</td></tr>
     <tr><td><code>report_desk_links</code></td><td>Liaison N:N reports ↔ desks</td><td>report_id, asset_class</td></tr>
+    <tr><td><code>cot_data</code></td><td>Positionnement COT CFTC hebdo</td><td>commodity, asset_class, report_date, mm_long, mm_short, open_interest, net_position, net_pct_oi, change_net · UNIQUE(commodity, report_date)</td></tr>
+    <tr><td><code>forward_curve_data</code></td><td>Structure terme futures</td><td>asset, asset_class, front_price, far_price, slope_pct, structure (contango/backwardation/flat), months_spread, fetch_date · UNIQUE(asset, fetch_date)</td></tr>
   </tbody>
 </table>
 
@@ -2536,19 +2555,118 @@ reliability_score = win_rate × log(n+1)
 <table>
   <thead><tr><th>Prompt</th><th>Asset classes injectées</th><th>Contenu par desk</th></tr></thead>
   <tbody>
-    <tr><td><code>score_patterns_with_context</code></td><td>Uniquement les asset classes présentes dans les patterns scorés ce cycle</td><td>Fondamentaux (≤300 chars), macro sensitivity (4 pairs régime→effet), price thresholds, 5 prochains rapports planifiés</td></tr>
+    <tr><td><code>score_patterns_with_context</code></td><td>Uniquement les asset classes présentes dans les patterns scorés ce cycle</td><td>Fondamentaux, macro sensitivity, price thresholds, 5 prochains rapports, COT net% OI, forward curve structure, surprise scores récents</td></tr>
     <tr><td><code>suggest_patterns_from_market_context</code></td><td><strong>Tous les 7 desks</strong> systématiquement</td><td>Identique — permet à l'IA de générer des suggestions sur tous les desks même si aucun pattern existant ne les couvre</td></tr>
   </tbody>
 </table>
 
-<p>Format du bloc injecté dans le prompt (exemple desk Agri) :</p>
-<div class="arch-box">## SPECIALIST DESK — AGRI 🌾
-Key drivers: Météo, USDA stocks, cycles de plantation, demande Chine...
-Regime sensitivity: Stagflation → bullish | Goldilocks → neutral | Récession → bearish | Disinflation → bearish
+<p>Format du bloc injecté dans le prompt (exemple desk Energy enrichi v2) :</p>
+<div class="arch-box">## SPECIALIST DESK — ENERGY ⚡
+Key drivers: OPEC+, inventaires pétrole, demande transport, géopolitique Moyen-Orient, USD
+Regime sensitivity: Choc Inflationniste → bullish | Récession → bearish | Stagflation → bullish | Goldilocks → neutral
 Price thresholds: significant_week=3% extreme_week=8%
+COT positioning (2026-06-16):
+  • WTI Crude: net +6.2% OI (non-commercial) — moderately long
+  • Natural Gas: net −10.6% OI — short bias, squeeze risk if supply shock
+Forward curves:
+  • WTI: backwardation (−1.2% M+3) — marché physique tendu
+  • Natural Gas: flat
 Upcoming reports:
-  • WASDE (USDA) — 2026-07-11 [monthly] ⭐×3
-  • USDA Export Inspections (USDA) — 2026-06-30 [weekly]</div>
+  • EIA Petroleum Status (EIA) — 2026-06-25 [weekly]
+  • Baker Hughes Rig Count — 2026-06-27 [weekly]</div>
+
+<h3 id="s12-3">12.3 COT Positioning — CFTC Socrata</h3>
+<p>L'onglet <strong>COT Positioning</strong> affiche le positionnement spéculatif (non-commercial) hebdomadaire de 19 marchés, extrait directement de l'API publique CFTC (Socrata) sans clé API. Mise à jour chaque mardi soir (délai CFTC standard : données de vendredi publiées le mardi).</p>
+
+<table>
+  <thead><tr><th>Asset Class</th><th>Marchés couverts</th><th>Catégorie CFTC</th></tr></thead>
+  <tbody>
+    <tr><td>⚡ Energy</td><td>WTI Crude (067651), Natural Gas (023651)</td><td>Non-commercial long/short</td></tr>
+    <tr><td>🥇 Metals</td><td>Gold (088691), Silver (084691), Copper (085692)</td><td>Non-commercial long/short</td></tr>
+    <tr><td>🌾 Agri</td><td>Corn, Wheat SRW, Soybeans, Soybean Oil, Cocoa, Coffee</td><td>Non-commercial long/short</td></tr>
+    <tr><td>💱 Forex</td><td>Euro, Japanese Yen, British Pound, Swiss Franc, DXY Index</td><td>Non-commercial long/short</td></tr>
+    <tr><td>📉 Bonds</td><td>Fed Funds (045601), US T-Bonds (020601), 10Y T-Notes (043602)</td><td>Non-commercial long/short</td></tr>
+  </tbody>
+</table>
+
+<div class="callout blue">
+  <div class="label">Architecture robustesse : codes contrat</div>
+  La recherche par nom de marché (ex : <code>"CRUDE OIL, LIGHT SWEET - NYMEX"</code>) est fragile — le CFTC renomme les marchés à chaque rachat d'exchange (COMEX → "COMMODITY EXCHANGE INC.", CBOT → "CHICAGO BOARD OF TRADE"). La solution retenue utilise les <strong>codes contrat CFTC</strong> (ex : 067651 pour WTI), stables depuis des décennies et indépendants du nom de l'exchange. Une seule requête Socrata suffit pour tous les 19 marchés.
+</div>
+
+<p><strong>Métriques affichées par marché :</strong></p>
+<ul>
+  <li><code>net_pct_oi</code> = (long − short) / open_interest × 100 — barre de positionnement net en % OI</li>
+  <li>Badge <strong>LONG</strong> (>+5%), <strong>SHORT</strong> (&lt;−5%), <strong>NEUTRAL</strong></li>
+  <li>Flèche directionnelle avec <code>change_net</code> hebdomadaire — détecte les rotations en cours</li>
+</ul>
+
+<p><strong>Interprétation opérationnelle :</strong></p>
+<table>
+  <thead><tr><th>Signal COT</th><th>Lecture</th><th>Implication trading</th></tr></thead>
+  <tbody>
+    <tr><td>Net > +40% OI (ex : Gold +53%)</td><td>Positionnement spéculatif extrêmement long</td><td>Trade crowded — asymétrie baissière si catalyst négatif, short squeeze improbable</td></tr>
+    <tr><td>Net &lt; −30% OI (ex : JPY −29%)</td><td>Positionnement spéculatif extrêmement court</td><td>Short squeeze risk élevé si pivot hawkish BOJ</td></tr>
+    <tr><td>Change_net > +10k/semaine</td><td>Accumulation rapide</td><td>Momentum spéculatif en train de s'installer</td></tr>
+    <tr><td>Change_net inversé vs net</td><td>Rotation début de retournement</td><td>Surveiller confirmation technique</td></tr>
+  </tbody>
+</table>
+
+<h3 id="s12-4">12.4 Forward Curves</h3>
+<p>L'onglet <strong>Forward Curves</strong> compare le prix front-month au contrat M+3 pour 8 commodities (énergie + métaux + agri), via yfinance. La structure de courbe révèle la tension physique sur le marché sous-jacent.</p>
+
+<table>
+  <thead><tr><th>Structure</th><th>Condition</th><th>Lecture</th><th>Implication</th></tr></thead>
+  <tbody>
+    <tr><td><strong>Backwardation</strong></td><td>slope_pct &lt; −0.15%</td><td>Front &gt; Far — livraison immédiate prime</td><td>Marché physique tendu, stockages faibles — bullish spot</td></tr>
+    <tr><td><strong>Contango</strong></td><td>slope_pct &gt; +0.15%</td><td>Far &gt; Front — coût de portage positif</td><td>Abondance physique, storage play — pression baissière sur spot</td></tr>
+    <tr><td><strong>Flat</strong></td><td>±0.15%</td><td>Équilibre offre/demande</td><td>Pas de signal directionnel fort</td></tr>
+  </tbody>
+</table>
+
+<p><strong>Marchés couverts :</strong> WTI Crude (CL), Natural Gas (NG), Gold (GC), Silver (SI), Copper (HG), Corn (ZC), Wheat (ZW), Soybeans (ZS). Les tickers front-month et M+3 sont construits dynamiquement avec les codes mois CFTC (F=Jan, G=Feb, H=Mar, J=Apr, K=May, M=Jun, N=Jul, Q=Aug, U=Sep, V=Oct, X=Nov, Z=Dec).</p>
+
+<h3 id="s12-5">12.5 Surprise Index</h3>
+<p>Pour chaque rapport dans le catalogue Specialist Desks, le trader peut saisir la valeur de consensus avant publication et l'actual après. Le système calcule automatiquement le <strong>surprise score</strong> = actual − consensus.</p>
+
+<table>
+  <thead><tr><th>Champ</th><th>Saisie</th><th>Calcul</th></tr></thead>
+  <tbody>
+    <tr><td><code>consensus_estimate</code></td><td>Avant publication (Bloomberg/Reuters)</td><td>—</td></tr>
+    <tr><td><code>actual_value</code></td><td>Après publication</td><td>—</td></tr>
+    <tr><td><code>surprise_score</code></td><td>Auto</td><td>actual − consensus, calculé côté serveur</td></tr>
+  </tbody>
+</table>
+
+<p>Endpoint : <code>PUT /api/specialist-desks/reports/{id}/result</code> — met à jour les trois colonnes atomiquement.</p>
+
+<p>Les surprises récentes sont injectées dans le contexte IA de l'Étape 4b :</p>
+<div class="arch-box">Recent surprises:
+  • NFP (2026-06-06): actual=139k vs consensus=185k → surprise=−46k (miss massif)
+  • CPI (2026-06-11): actual=+0.2% vs consensus=+0.3% → surprise=−0.1% (légèrement dovish)
+Upcoming consensus estimates:
+  • EIA Petroleum (2026-06-25): consensus=−1.2M bbls draw</div>
+
+<h3 id="s12-6">12.6 Hawk/Dove Text Scorer (GPT-4o-mini)</h3>
+<p>Disponible sur les desks Forex et Bonds, le scorer analyse le texte d'un rapport (discours de banquier central, communiqué Fed/ECB, minutes) et retourne une évaluation directionnelle sur l'axe <strong>Hawk / Dove</strong>. Pour les desks Energy/Metals/Agri, l'axe devient <strong>Bull / Bear</strong>.</p>
+
+<table>
+  <thead><tr><th>Paramètre</th><th>Valeur</th></tr></thead>
+  <tbody>
+    <tr><td>Modèle</td><td>GPT-4o-mini (<code>response_format: json_object</code>)</td></tr>
+    <tr><td>Score output</td><td>Float −1.0 (Dovish/Bearish) … +1.0 (Hawkish/Bullish)</td></tr>
+    <tr><td>Label output</td><td>Hawkish / Slightly Hawkish / Neutral / Slightly Dovish / Dovish</td></tr>
+    <tr><td>Autres champs</td><td>summary (1 phrase), key_phrases (3–5 extraits), confidence (0–1)</td></tr>
+    <tr><td>Persistance</td><td>Colonnes <code>text_sentiment_score</code>, <code>text_sentiment_label</code>, <code>text_sentiment_summary</code> dans <code>specialist_reports</code></td></tr>
+  </tbody>
+</table>
+
+<div class="callout blue">
+  <div class="label">Logique de scoring</div>
+  Le prompt instruits GPT-4o-mini à ignorer le contexte de marché et à se concentrer uniquement sur le <em>contenu rhétorique</em> : mentions de resserrement/assouplissement futur, révisions de projections de taux, vocabulaire d'urgence vs d'attente. Le score est stocké sur le rapport et injecté dans le contexte IA au cycle suivant — permettant à l'IA de quantifier l'impact d'un discours Fed sur les patterns de taux et forex.
+</div>
+
+<p>Endpoint : <code>POST /api/specialist-desks/score-text</code> — accepte <code>{"text": "...", "report_name": "FOMC Minutes", "desk": "bonds"}</code></p>
 
 <div class="page-break"></div>
 
@@ -2659,9 +2777,9 @@ calibrated_expected_move = (1 − w) × ai_estimate + w × observed_avg_win_pct
 <hr>
 
 <div class="footer-doc">
-  <p>Document généré le 23 juin 2026 · GeoOptions Intelligence v6.0</p>
-  <p>FastAPI + React + SQLite + GPT-4o · 23 pages · 6 phases · Usage interne trader</p>
-  <p>Sections : Architecture · Cycle complet simulé · Phase 5 Cycle Context Engine · Phase 1 IV/Structure + IV Gate + Watchlist · Phase 2 Fiabilité · Phase 3 Risk Engine · Pattern Convergence + IBKR Ticket · Phase 4 IA Probabiliste · 7 Prompts IA · 20+ Tables DB · Guide 19 pages · 19 Décisions conception · Glossaire 50+ termes · Specialist Desks · Calibration Progressive · Find Similar+Merge · Workflow Calculs</p>
+  <p>Document généré le 23 juin 2026 · GeoOptions Intelligence v6.1</p>
+  <p>FastAPI + React + SQLite + GPT-4o · CFTC Socrata · yfinance · 25 pages · 6 phases · Usage interne trader</p>
+  <p>Sections : Architecture · Cycle complet simulé · Phase 5 Cycle Context Engine · Phase 1 IV/Structure + IV Gate + Watchlist · Phase 2 Fiabilité · Phase 3 Risk Engine · Pattern Convergence + IBKR Ticket · Phase 4 IA Probabiliste · 7 Prompts IA · 20+ Tables DB (incl. cot_data, forward_curve_data) · Guide 19 pages · 19 Décisions conception · Glossaire 50+ termes · Specialist Desks v2 (COT 19 marchés · Forward Curves · Surprise Index · Hawk/Dove Scorer) · Calibration Progressive · Find Similar+Merge · Workflow Calculs</p>
 </div>
 
 </body>