v0.8.0: AI Market Analyst and Developer Message Flow Visualizer

F5: AI Analyst with three-provider fallback (Ollama/Groq/HuggingFace).
Builds market context prompt from live trades and order book, generates
3-4 sentence analysis. Provider switchable from UI. Insights broadcast
via SSE and cached in memory.

F6: Message Flow Visualizer traces the full order lifecycle through
OEG -> Book -> Match -> Trade -> DB -> CH pipeline. Uses function
patching to intercept engine methods. Shows per-stage counters and
live log with monospace formatting.

Dashboard now has 3 tabs: Trading, AI Analyst, Message Flow.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.16)
-project(EuNEx VERSION 0.7.0 LANGUAGES CXX)
+project(EuNEx VERSION 0.8.0 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)

README.md

@@ -27,7 +27,7 @@ ch_ai_trader.py          →   ClearingHouseActor        →   Clearing House (P
   AI strategies          →   AITraderActor             →   Trading obligations
 ```
 
-## Actor Topology (v0.7)
+## Actor Topology (v0.8)
 
 ```
  Core 0: OEGActor + FIXAcceptorActor     ← Order entry & FIX protocol
@@ -220,7 +220,9 @@ EuNEx/
 3. ~~FIX gateway~~ ✓ C++ FIXAcceptorActor + Python fallback
 4. ~~Clearing House~~ ✓ ClearingHouseActor + AITraderActor
 5. ~~Market simulation~~ ✓ Realistic AI trading + Dashboard auto-simulation
-6. **SBE encoding** — replace event structs with SBE-encoded messages
-7. **Master/Mirror failover** — implement full Recovery replay on Mirror node
-8. **Trading phases** — pre-open, uncrossing, continuous, close, TAL
-9. **Additional order types** — Stop, Pegged, Mid-Point, Iceberg
+6. ~~AI Analyst~~ ✓ Ollama/Groq/HuggingFace market commentary
+7. ~~Message Flow Visualizer~~ ✓ Developer pipeline tracing tool
+8. **SBE encoding** — replace event structs with SBE-encoded messages
+9. **Master/Mirror failover** — implement full Recovery replay on Mirror node
+10. **Trading phases** — pre-open, uncrossing, continuous, close, TAL
+11. **Additional order types** — Stop, Pegged, Mid-Point, Iceberg

dashboard/app.py

@@ -10,6 +10,8 @@ Provides:
   - Session controls (start/suspend/resume)
   - SSE streaming for live updates
   - Clearing House integration
+  - AI Analyst (Ollama/Groq/HuggingFace)
+  - Developer Message Flow Visualizer
 
 Run: python dashboard/app.py
 """
@@ -23,6 +25,7 @@ import sys
 import os
 import urllib.request
 import urllib.error
+from collections import deque
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
@@ -582,6 +585,274 @@ class MarketSimulator:
 simulator = MarketSimulator(engine)
 
 
+# ── AI Analyst ─────────────────────────────────────────────────────
+
+OLLAMA_HOST = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+OLLAMA_MODEL = os.environ.get("OLLAMA_MODEL", "llama3.2:3b")
+GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
+GROQ_MODEL = os.environ.get("GROQ_MODEL", "llama-3.1-8b-instant")
+HF_TOKEN = os.environ.get("HF_TOKEN", "")
+HF_MODEL = os.environ.get("HF_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+
+ai_insights = deque(maxlen=20)
+ai_provider = "auto"
+ai_model_override = None
+ai_generating = False
+
+
+def _build_market_prompt():
+    now_str = time.strftime("%H:%M:%S")
+    session = session_status.upper()
+
+    trade_lines = []
+    with state_lock:
+        by_sym = {}
+        for t in trades[-200:]:
+            sym = t.get("symbol", "?")
+            by_sym.setdefault(sym, []).append(t)
+        for sym, ts in sorted(by_sym.items()):
+            prices = [t["price"] for t in ts if t.get("price")]
+            vol = sum(t.get("quantity", 0) for t in ts)
+            if prices:
+                trade_lines.append(
+                    f"  {sym}: {len(ts)} trade(s), range {min(prices):.2f}-{max(prices):.2f}, "
+                    f"vol {vol}, last {prices[-1]:.2f}"
+                )
+
+        book_lines = []
+        for sid, snap in sorted(snapshots.items()):
+            bid = snap.get("bestBid", 0)
+            ask = snap.get("bestAsk", 0)
+            spread = ask - bid if bid > 0 and ask > 0 else 0
+            book_lines.append(
+                f"  {snap.get('symbol','?')}: Bid {bid:.2f} / Ask {ask:.2f} (spread {spread:.2f})"
+            )
+
+    trades_text = "\n".join(trade_lines) if trade_lines else "  No recent trades"
+    book_text = "\n".join(book_lines) if book_lines else "  No order book data"
+
+    return (
+        "You are a concise financial market analyst for the EuNEx simulated exchange "
+        "(Euronext Optiq architecture). "
+        f"Time: {now_str} | Session: {session}\n\n"
+        f"Recent trades:\n{trades_text}\n\n"
+        f"Order book:\n{book_text}\n\n"
+        "In 3-4 sentences: activity level, notable price moves, market sentiment. "
+        "Plain prose, no headers, no bullet points."
+    )
+
+
+def _try_ollama(prompt, model=None):
+    model = model or OLLAMA_MODEL
+    try:
+        data = json.dumps({
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "stream": False,
+        }).encode()
+        req = urllib.request.Request(
+            f"{OLLAMA_HOST}/api/chat",
+            data=data,
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=90) as resp:
+            result = json.loads(resp.read())
+            return result.get("message", {}).get("content", "")
+    except Exception:
+        return None
+
+
+def _try_groq(prompt, model=None):
+    if not GROQ_API_KEY:
+        return None
+    model = model or GROQ_MODEL
+    try:
+        data = json.dumps({
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": 300,
+            "temperature": 0.7,
+        }).encode()
+        req = urllib.request.Request(
+            "https://api.groq.com/openai/v1/chat/completions",
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {GROQ_API_KEY}",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            result = json.loads(resp.read())
+            return result["choices"][0]["message"]["content"]
+    except Exception:
+        return None
+
+
+def _try_hf(prompt, model=None):
+    if not HF_TOKEN:
+        return None
+    model = model or HF_MODEL
+    try:
+        data = json.dumps({
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": 300,
+            "temperature": 0.7,
+        }).encode()
+        req = urllib.request.Request(
+            "https://router.huggingface.co/v1/chat/completions",
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {HF_TOKEN}",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=90) as resp:
+            result = json.loads(resp.read())
+            return result["choices"][0]["message"]["content"]
+    except Exception:
+        return None
+
+
+def _call_llm(prompt):
+    provider = ai_provider
+    model = ai_model_override
+
+    if provider == "ollama":
+        return _try_ollama(prompt, model), "ollama"
+    elif provider == "groq":
+        return _try_groq(prompt, model), "groq"
+    elif provider == "hf":
+        return _try_hf(prompt, model), "hf"
+
+    for name, func in [("ollama", _try_ollama), ("groq", _try_groq), ("hf", _try_hf)]:
+        text = func(prompt, model)
+        if text:
+            return text, name
+    return None, None
+
+
+def _generate_insight():
+    global ai_generating
+    if ai_generating:
+        return
+    ai_generating = True
+    try:
+        prompt = _build_market_prompt()
+        text, source = _call_llm(prompt)
+        if text:
+            insight = {
+                "text": text.strip(),
+                "timestamp": time.time(),
+                "source": source or "unknown",
+            }
+            ai_insights.append(insight)
+            broadcast_event("ai_insight", insight)
+    finally:
+        ai_generating = False
+
+
+@app.route("/ai/generate", methods=["POST"])
+def ai_generate():
+    threading.Thread(target=_generate_insight, daemon=True).start()
+    return jsonify({"status": "generating"})
+
+
+@app.route("/ai/insights")
+def ai_insights_list():
+    return jsonify(list(ai_insights))
+
+
+@app.route("/ai/config")
+def ai_config():
+    return jsonify({
+        "provider": ai_provider,
+        "model": ai_model_override,
+        "providers": {
+            "auto": {"label": "Auto (fallback)", "available": True},
+            "ollama": {"label": f"Ollama ({OLLAMA_MODEL})", "available": bool(OLLAMA_HOST)},
+            "groq": {"label": f"Groq ({GROQ_MODEL})", "available": bool(GROQ_API_KEY)},
+            "hf": {"label": f"HuggingFace ({HF_MODEL})", "available": bool(HF_TOKEN)},
+        },
+    })
+
+
+@app.route("/ai/select", methods=["POST"])
+def ai_select():
+    global ai_provider, ai_model_override
+    d = request.json
+    ai_provider = d.get("provider", "auto")
+    ai_model_override = d.get("model") or None
+    return jsonify({"provider": ai_provider, "model": ai_model_override})
+
+
+# ── Developer Message Flow Log ─────────────────────────────────────
+
+message_log = deque(maxlen=500)
+
+
+def log_message(stage, detail):
+    entry = {
+        "timestamp": time.time(),
+        "stage": stage,
+        "detail": detail,
+    }
+    message_log.append(entry)
+    broadcast_event("msgflow", entry)
+
+
+@app.route("/dev/messages")
+def dev_messages():
+    limit = int(request.args.get("limit", 100))
+    items = list(message_log)[-limit:]
+    return jsonify(items)
+
+
+# Patch engine to log message flow
+_orig_submit = engine.submit_order
+
+def _traced_submit(symbol_id, side, order_type, price, quantity,
+                   tif="Day", source="dashboard", cl_ord_id=""):
+    sym_name = symbols.get(symbol_id, {}).get("name", "?")
+    log_message("OEG", f"NewOrder {sym_name} {side} {quantity}@{price:.2f} [{source}]")
+    result = _orig_submit(symbol_id, side, order_type, price, quantity, tif, source, cl_ord_id)
+    oid = result.get("orderId", "?")
+    status = result.get("status", "?")
+    log_message("Book", f"Order#{oid} → {status}")
+    if status == "Filled":
+        log_message("Match", f"Order#{oid} fully filled")
+    elif status == "PartiallyFilled":
+        log_message("Match", f"Order#{oid} partial fill, rem={result.get('remainingQty', '?')}")
+    return result
+
+engine.submit_order = _traced_submit
+
+_orig_cancel = engine.cancel_order
+
+def _traced_cancel(order_id):
+    log_message("OEG", f"CancelOrder #{order_id}")
+    result = _orig_cancel(order_id)
+    if result:
+        log_message("Book", f"Order#{order_id} cancelled")
+    return result
+
+engine.cancel_order = _traced_cancel
+
+# Patch trade saving to log trade and clearing steps
+_orig_broadcast = broadcast_event
+
+def _traced_broadcast(event_type, data):
+    if event_type == "trade":
+        tid = data.get("tradeId", "?")
+        sym = data.get("symbol", "?")
+        log_message("Trade", f"Trade#{tid} {sym} {data.get('quantity',0)}@{data.get('price',0):.2f}")
+        log_message("DB", f"Trade#{tid} persisted to SQLite")
+        log_message("CH", f"Trade#{tid} → clearing (buy#{data.get('buyOrderId','?')}, sell#{data.get('sellOrderId','?')})")
+    _orig_broadcast(event_type, data)
+
+broadcast_event = _traced_broadcast
+
+
 if __name__ == "__main__":
     os.makedirs(os.path.dirname(db_path), exist_ok=True)
     init_db(db_path)
@@ -590,4 +861,5 @@ if __name__ == "__main__":
     print(f"EuNEx Dashboard starting on http://localhost:{port}")
     print(f"  Database: {db_path}")
     print(f"  Simulation: every {SIM_INTERVAL}s, {SIM_ORDERS_PER_ROUND} orders/symbol/round")
+    print(f"  AI Analyst: provider={ai_provider} (Ollama={OLLAMA_HOST})")
     app.run(host="0.0.0.0", port=port, debug=True, threaded=True)

dashboard/templates/index.html

@@ -26,8 +26,18 @@ button:hover{opacity:.85}
 .btn-yellow{background:var(--yellow);color:var(--bg)}
 .btn-red{background:var(--red);color:#fff}
 .btn-blue{background:var(--blue);color:#fff}
+.btn-purple{background:var(--purple);color:#fff}
 .btn-small{padding:3px 8px;font-size:11px}
 
+/* ── Tabs ────────────────────────────────────────────── */
+.tab-bar{display:flex;gap:2px;padding:0 20px;background:var(--card);border-bottom:1px solid var(--border)}
+.tab-btn{padding:10px 20px;background:transparent;color:var(--muted);border:none;border-bottom:2px solid transparent;
+cursor:pointer;font-size:13px;font-weight:600;transition:all .2s}
+.tab-btn:hover{color:var(--text)}
+.tab-btn.active{color:var(--accent);border-bottom-color:var(--accent)}
+.tab-content{display:none}
+.tab-content.active{display:block}
+
 /* ── Ticker tape ─────────────────────────────────────── */
 .ticker-wrap{background:#0d1130;border-bottom:1px solid var(--border);overflow:hidden;height:32px;position:relative}
 .ticker-track{display:flex;align-items:center;height:100%;white-space:nowrap;animation:tickerScroll 30s linear infinite}
@@ -89,6 +99,43 @@ border-radius:6px;color:var(--text);font-size:12px}
 .lb-rank{color:var(--yellow);font-weight:700;width:20px}
 .lb-name{flex:1;margin-left:6px}
 .lb-val{font-weight:600}
+
+/* ── AI Analyst panel ────────────────────────────────── */
+.ai-panel{border-top:3px solid var(--purple);margin:12px 20px;background:var(--card);border-radius:8px;padding:14px;border:1px solid var(--border)}
+.ai-panel h3{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
+.ai-controls{display:flex;gap:6px;align-items:center;margin-left:auto}
+.ai-controls select{padding:4px 8px;background:#1a1f45;border:1px solid var(--border);border-radius:4px;color:var(--muted);font-size:11px}
+.ai-badge{font-size:10px;padding:2px 8px;border-radius:8px;background:#7c5cfc22;color:var(--purple);font-weight:600}
+.ai-status{font-size:11px;color:var(--muted)}
+.insight-card{border-left:3px solid var(--purple);background:#1a1f4566;padding:10px 14px;margin-bottom:8px;border-radius:0 6px 6px 0;animation:fadeIn .4s ease}
+.insight-time{font-size:10px;color:var(--muted);margin-bottom:4px;display:flex;gap:8px;align-items:center}
+.insight-src{font-size:9px;padding:1px 6px;border-radius:4px;background:#7c5cfc22;color:var(--purple)}
+.insight-text{line-height:1.5;font-size:12px}
+@keyframes fadeIn{from{opacity:0;transform:translateY(-5px)}to{opacity:1;transform:translateY(0)}}
+
+/* ── Message Flow Visualizer ─────────────────────────── */
+.flow-panel{margin:12px 20px;background:var(--card);border:1px solid var(--border);border-radius:8px;padding:14px}
+.flow-header{display:flex;justify-content:space-between;align-items:center;margin-bottom:12px}
+.flow-pipeline{display:flex;gap:2px;margin-bottom:16px;justify-content:center;flex-wrap:wrap}
+.flow-stage{text-align:center;padding:8px 14px;border-radius:6px;font-size:11px;font-weight:600;min-width:90px;position:relative}
+.flow-stage .count{font-size:16px;display:block;margin-bottom:2px}
+.flow-arrow{color:var(--muted);font-size:18px;display:flex;align-items:center;padding:0 2px}
+.stage-oeg{background:#4a90d922;color:var(--blue);border:1px solid #4a90d944}
+.stage-book{background:#00d4aa22;color:var(--accent);border:1px solid #00d4aa44}
+.stage-match{background:#f0c04022;color:var(--yellow);border:1px solid #f0c04044}
+.stage-trade{background:#7c5cfc22;color:var(--purple);border:1px solid #7c5cfc44}
+.stage-db{background:#ff6b6b22;color:var(--red);border:1px solid #ff6b6b44}
+.stage-ch{background:#00d4aa22;color:var(--accent);border:1px solid #00d4aa44}
+.flow-log{max-height:300px;overflow-y:auto;font-family:'Cascadia Code','Fira Code',monospace;font-size:11px}
+.flow-entry{padding:3px 8px;border-bottom:1px solid #1a1f4522;display:flex;gap:10px}
+.flow-entry:hover{background:#1a1f4544}
+.flow-ts{color:var(--muted);min-width:75px;font-size:10px}
+.flow-tag{min-width:50px;font-weight:600;font-size:10px;text-transform:uppercase}
+.flow-tag-oeg{color:var(--blue)}.flow-tag-book{color:var(--accent)}.flow-tag-match{color:var(--yellow)}
+.flow-tag-trade{color:var(--purple)}.flow-tag-db{color:var(--red)}.flow-tag-ch{color:var(--accent)}
+.flow-detail{color:var(--text)}
+.flow-active{animation:pulse .6s ease}
+@keyframes pulse{0%{background:#7c5cfc22}100%{background:transparent}}
 </style>
 </head>
 <body>
@@ -109,6 +156,16 @@ border-radius:6px;color:var(--text);font-size:12px}
   <div class="ticker-track" id="tickerTrack"></div>
 </div>
 
+<!-- Tab bar -->
+<div class="tab-bar">
+  <button class="tab-btn active" onclick="switchTab('trading')">Trading</button>
+  <button class="tab-btn" onclick="switchTab('analyst')">AI Analyst</button>
+  <button class="tab-btn" onclick="switchTab('devflow')">Message Flow</button>
+</div>
+
+<!-- ═══════════════ TAB: Trading ═══════════════ -->
+<div id="tab-trading" class="tab-content active">
+
 <!-- Row 1: Order Entry | Order Book | Market Snapshot -->
 <div class="grid">
   <div class="panel">
@@ -201,6 +258,68 @@ border-radius:6px;color:var(--text);font-size:12px}
   </div>
 </div>
 
+</div><!-- /tab-trading -->
+
+<!-- ═══════════════ TAB: AI Analyst ═══════════════ -->
+<div id="tab-analyst" class="tab-content">
+  <div class="ai-panel">
+    <h3>AI Market Analyst
+      <div class="ai-controls">
+        <select id="aiProvider" onchange="onAIProviderChange()">
+          <option value="auto">Auto</option>
+          <option value="ollama">Ollama</option>
+          <option value="groq">Groq</option>
+          <option value="hf">HuggingFace</option>
+        </select>
+        <span class="ai-badge" id="aiBadge">auto</span>
+        <button class="btn-purple" id="aiGenerateBtn" onclick="triggerAI()">Generate Analysis</button>
+        <span class="ai-status" id="aiStatus">Ready</span>
+      </div>
+    </h3>
+    <div id="aiInsights" style="max-height:500px;overflow-y:auto">
+      <div class="muted" style="padding:20px;text-align:center">
+        Click "Generate Analysis" to get AI market commentary.<br>
+        <span style="font-size:11px">Requires Ollama running locally, or GROQ_API_KEY / HF_TOKEN set.</span>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ═══════════════ TAB: Message Flow ═══════════════ -->
+<div id="tab-devflow" class="tab-content">
+  <div class="flow-panel">
+    <div class="flow-header">
+      <h3 style="color:var(--accent);margin:0">Message Flow Visualizer</h3>
+      <div style="display:flex;gap:8px;align-items:center">
+        <span class="muted" id="flowCount">0 messages</span>
+        <button class="btn-small btn-red" onclick="clearFlowLog()">Clear</button>
+      </div>
+    </div>
+
+    <!-- Pipeline diagram -->
+    <div class="flow-pipeline">
+      <div class="flow-stage stage-oeg"><span class="count" id="flowCntOEG">0</span>OEG</div>
+      <div class="flow-arrow">&#9654;</div>
+      <div class="flow-stage stage-book"><span class="count" id="flowCntBook">0</span>Book</div>
+      <div class="flow-arrow">&#9654;</div>
+      <div class="flow-stage stage-match"><span class="count" id="flowCntMatch">0</span>Match</div>
+      <div class="flow-arrow">&#9654;</div>
+      <div class="flow-stage stage-trade"><span class="count" id="flowCntTrade">0</span>Trade</div>
+      <div class="flow-arrow">&#9654;</div>
+      <div class="flow-stage stage-db"><span class="count" id="flowCntDB">0</span>DB</div>
+      <div class="flow-arrow">&#9654;</div>
+      <div class="flow-stage stage-ch"><span class="count" id="flowCntCH">0</span>CH</div>
+    </div>
+
+    <!-- Live message log -->
+    <div class="flow-log" id="flowLog">
+      <div class="muted" style="padding:20px;text-align:center">
+        Waiting for messages... Submit an order or start a session to see the flow.
+      </div>
+    </div>
+  </div>
+</div>
+
 <!-- Amend Modal -->
 <div class="modal-overlay" id="amendModal">
 <div class="modal">
@@ -218,6 +337,19 @@ const state = {orders:[], trades:[], snapshots:{}, symbols:{}, session:'idle'};
 let chartPeriod = '1h';
 let priceChart = null;
 const prevPrices = {};
+const flowCounts = {OEG:0, Book:0, Match:0, Trade:0, DB:0, CH:0};
+let flowEntries = [];
+let flowStarted = false;
+
+// ── Tab switching ─────────────────────────────────────
+function switchTab(name) {
+  document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
+  document.querySelectorAll('.tab-content').forEach(t => t.classList.remove('active'));
+  document.getElementById('tab-'+name).classList.add('active');
+  document.querySelector('.tab-btn[onclick*="'+name+'"]').classList.add('active');
+  if (name === 'analyst') loadAIInsights();
+  if (name === 'devflow') loadFlowLog();
+}
 
 async function init() {
   const resp = await fetch('/data');
@@ -278,6 +410,17 @@ function connectSSE() {
     state.session = s.status;
     renderSession();
   });
+  es.addEventListener('ai_insight', e => {
+    const insight = JSON.parse(e.data);
+    addInsightCard(insight);
+    const btn = document.getElementById('aiGenerateBtn');
+    btn.disabled = false; btn.textContent = 'Generate Analysis';
+    document.getElementById('aiStatus').textContent = 'Last: ' + new Date().toLocaleTimeString();
+  });
+  es.addEventListener('msgflow', e => {
+    const entry = JSON.parse(e.data);
+    addFlowEntry(entry);
+  });
 }
 
 // ── Ticker ────────────────────────────────────────────
@@ -404,7 +547,6 @@ function updateChart(bars, symName) {
   const opens = bars.map(b => b.open);
   const closes = bars.map(b => b.close);
   const volumes = bars.map(b => b.volume);
-  const colors = bars.map(b => b.close >= b.open ? '#00d4aa' : '#ff6b6b');
   const bgColors = bars.map(b => b.close >= b.open ? '#00d4aa44' : '#ff6b6b44');
 
   if (priceChart) priceChart.destroy();
@@ -417,7 +559,6 @@ function updateChart(bars, symName) {
       if (!meta || !meta.data.length) return;
       const yScale = chart.scales.y;
       const xScale = chart.scales.x;
-
       meta.data.forEach((point, i) => {
         if (i >= bars.length) return;
         const x = point.x;
@@ -427,20 +568,13 @@ function updateChart(bars, symName) {
         const close = yScale.getPixelForValue(closes[i]);
         const color = closes[i] >= opens[i] ? '#00d4aa' : '#ff6b6b';
         const barW = Math.max(4, (xScale.width / bars.length) * 0.6);
-
         ctx.save();
-        ctx.strokeStyle = color;
-        ctx.lineWidth = 1;
-        ctx.beginPath();
-        ctx.moveTo(x, high);
-        ctx.lineTo(x, low);
-        ctx.stroke();
-
+        ctx.strokeStyle = color; ctx.lineWidth = 1;
+        ctx.beginPath(); ctx.moveTo(x, high); ctx.lineTo(x, low); ctx.stroke();
         ctx.fillStyle = color;
         const top = Math.min(open, close);
         const bot = Math.max(open, close);
-        const bodyH = Math.max(bot - top, 1);
-        ctx.fillRect(x - barW/2, top, barW, bodyH);
+        ctx.fillRect(x - barW/2, top, barW, Math.max(bot - top, 1));
         ctx.restore();
       });
     }
@@ -451,12 +585,10 @@ function updateChart(bars, symName) {
     data: {
       labels,
       datasets: [{
-        label: symName + ' Close',
-        data: closes, borderColor: 'transparent', backgroundColor: 'transparent',
-        pointRadius: 0, borderWidth: 0, yAxisID: 'y',
+        label: symName + ' Close', data: closes, borderColor: 'transparent',
+        backgroundColor: 'transparent', pointRadius: 0, borderWidth: 0, yAxisID: 'y',
       },{
-        label: 'Volume', data: volumes, type: 'bar',
-        backgroundColor: bgColors, yAxisID: 'y1',
+        label: 'Volume', data: volumes, type: 'bar', backgroundColor: bgColors, yAxisID: 'y1',
       }]
     },
     options: {
@@ -466,11 +598,9 @@ function updateChart(bars, symName) {
         legend:{display:false},
         tooltip: {
           callbacks: {
-            label: function(ctx) {
-              const i = ctx.dataIndex;
-              if (ctx.datasetIndex === 0 && i < bars.length) {
-                return 'O:'+fmt(opens[i])+' H:'+fmt(highs[i])+' L:'+fmt(lows[i])+' C:'+fmt(closes[i]);
-              }
+            label: function(c) {
+              const i = c.dataIndex;
+              if (c.datasetIndex === 0 && i < bars.length) return 'O:'+fmt(opens[i])+' H:'+fmt(highs[i])+' L:'+fmt(lows[i])+' C:'+fmt(closes[i]);
               return 'Vol: ' + (volumes[i]||0);
             }
           }
@@ -510,6 +640,95 @@ async function loadLeaderboard() {
   }
 }
 
+// ── AI Analyst ────────────────────────────────────────
+async function loadAIInsights() {
+  try {
+    const resp = await fetch('/ai/insights');
+    const insights = await resp.json();
+    const el = document.getElementById('aiInsights');
+    if (insights.length === 0) return;
+    el.innerHTML = '';
+    insights.forEach(addInsightCard);
+  } catch(e) {}
+}
+
+function addInsightCard(insight) {
+  const el = document.getElementById('aiInsights');
+  if (el.querySelector('.muted')) el.innerHTML = '';
+  const div = document.createElement('div');
+  div.className = 'insight-card';
+  const t = new Date(insight.timestamp * 1000).toLocaleTimeString();
+  div.innerHTML = '<div class="insight-time">' + t +
+    ' <span class="insight-src">' + (insight.source||'') + '</span></div>' +
+    '<div class="insight-text">' + insight.text + '</div>';
+  el.prepend(div);
+  while (el.children.length > 10) el.removeChild(el.lastChild);
+}
+
+async function triggerAI() {
+  const btn = document.getElementById('aiGenerateBtn');
+  btn.disabled = true; btn.textContent = 'Generating...';
+  document.getElementById('aiStatus').textContent = 'Calling LLM...';
+  await fetch('/ai/generate', {method:'POST'});
+}
+
+async function onAIProviderChange() {
+  const provider = document.getElementById('aiProvider').value;
+  document.getElementById('aiBadge').textContent = provider;
+  await fetch('/ai/select', {method:'POST', headers:{'Content-Type':'application/json'},
+    body: JSON.stringify({provider})});
+}
+
+// ── Message Flow Visualizer ───────────────────────────
+async function loadFlowLog() {
+  if (flowStarted) return;
+  flowStarted = true;
+  try {
+    const resp = await fetch('/dev/messages?limit=100');
+    const msgs = await resp.json();
+    msgs.forEach(addFlowEntry);
+  } catch(e) {}
+}
+
+function addFlowEntry(entry) {
+  flowEntries.push(entry);
+  if (flowEntries.length > 500) flowEntries.shift();
+
+  const stage = entry.stage || '?';
+  if (flowCounts[stage] !== undefined) {
+    flowCounts[stage]++;
+    const el = document.getElementById('flowCnt' + stage);
+    if (el) el.textContent = flowCounts[stage];
+  }
+
+  const log = document.getElementById('flowLog');
+  if (log.querySelector('.muted')) log.innerHTML = '';
+
+  const div = document.createElement('div');
+  div.className = 'flow-entry flow-active';
+  const ts = new Date(entry.timestamp * 1000).toLocaleTimeString();
+  const tagCls = 'flow-tag-' + stage.toLowerCase();
+  div.innerHTML = '<span class="flow-ts">' + ts + '</span>' +
+    '<span class="flow-tag ' + tagCls + '">' + stage + '</span>' +
+    '<span class="flow-detail">' + (entry.detail||'') + '</span>';
+  log.prepend(div);
+
+  while (log.children.length > 200) log.removeChild(log.lastChild);
+  document.getElementById('flowCount').textContent = flowEntries.length + ' messages';
+}
+
+function clearFlowLog() {
+  flowEntries = [];
+  Object.keys(flowCounts).forEach(k => flowCounts[k] = 0);
+  document.getElementById('flowLog').innerHTML = '<div class="muted" style="padding:20px;text-align:center">Log cleared</div>';
+  ['OEG','Book','Match','Trade','DB','CH'].forEach(s => {
+    const el = document.getElementById('flowCnt'+s);
+    if (el) el.textContent = '0';
+  });
+  document.getElementById('flowCount').textContent = '0 messages';
+}
+
+// ── Order actions ─────────────────────────────────────
 async function submitOrder(side) {
   const data = {
     symbolIdx: parseInt(document.getElementById('orderSymbol').value),

docs/developers-guide.md

@@ -1,6 +1,6 @@
 # EuNEx Developers Guide
 
-**Version 0.7.0** | Euronext Optiq-Modeled Exchange Simulator
+**Version 0.8.0** | Euronext Optiq-Modeled Exchange Simulator
 
 ---
 
@@ -20,10 +20,12 @@
 12. [Clearing House](#12-clearing-house)
 13. [AI Trading Members](#13-ai-trading-members)
 14. [Market Simulation](#14-market-simulation)
-15. [Project Structure](#15-project-structure)
-16. [Build & Test](#16-build--test)
-17. [Configuration](#17-configuration)
-18. [Extending EuNEx](#18-extending-eunex)
+15. [AI Market Analyst](#15-ai-market-analyst)
+16. [Developer Message Flow Visualizer](#16-developer-message-flow-visualizer)
+17. [Project Structure](#17-project-structure)
+18. [Build & Test](#18-build--test)
+19. [Configuration](#19-configuration)
+20. [Extending EuNEx](#20-extending-eunex)
 
 ---
 
@@ -949,7 +951,101 @@ The price chart renders OHLCV data as candlestick bars using a custom Chart.js p
 
 ---
 
-## 15. Project Structure
+## 15. AI Market Analyst
+
+The dashboard includes an AI analyst powered by local or cloud LLM providers.
+
+### Provider Fallback Chain
+
+```
+ Auto mode tries in order:
+   1. Ollama (local)    → POST {OLLAMA_HOST}/api/chat
+   2. Groq (cloud)      → POST api.groq.com/openai/v1/chat/completions
+   3. HuggingFace       → POST router.huggingface.co/v1/chat/completions
+```
+
+### Environment Variables
+
+| Variable       | Default                        | Description              |
+|---------------|-------------------------------|--------------------------|
+| OLLAMA_HOST    | http://localhost:11434        | Ollama API endpoint      |
+| OLLAMA_MODEL   | llama3.2:3b                   | Default Ollama model     |
+| GROQ_API_KEY   | (empty)                       | Groq API key             |
+| GROQ_MODEL     | llama-3.1-8b-instant          | Default Groq model       |
+| HF_TOKEN       | (empty)                       | HuggingFace token        |
+| HF_MODEL       | Qwen/Qwen2.5-7B-Instruct     | Default HF model         |
+
+### Prompt Template
+
+The analyst builds a market context prompt from current trades and order book:
+
+```
+ You are a concise financial market analyst for the EuNEx simulated exchange.
+ Time: HH:MM:SS | Session: ACTIVE
+
+ Recent trades:
+   AAPL: 12 trade(s), range 153.50-154.50, vol 1200, last 154.10
+   MSFT: 8 trade(s), range 323.80-324.20, vol 800, last 324.00
+   ...
+
+ Order book:
+   AAPL: Bid 153.80 / Ask 154.20 (spread 0.40)
+   ...
+
+ In 3-4 sentences: activity level, notable moves, market sentiment.
+```
+
+### API Endpoints
+
+| Endpoint          | Method | Description                    |
+|-------------------|--------|--------------------------------|
+| /ai/generate      | POST   | Trigger async LLM generation   |
+| /ai/insights      | GET    | Get cached insight history     |
+| /ai/config        | GET    | Provider availability/status   |
+| /ai/select        | POST   | Switch provider/model          |
+
+Insights are broadcast via SSE `ai_insight` event and cached in memory (last 20).
+
+---
+
+## 16. Developer Message Flow Visualizer
+
+The dashboard includes a "Message Flow" tab that traces the full order lifecycle through all system components. This is a developer tool for understanding and debugging the Optiq-modeled pipeline.
+
+### Pipeline Stages
+
+```
+ ┌─────┐    ┌──────┐    ┌───────┐    ┌───────┐    ┌────┐    ┌────┐
+ │ OEG │ ─► │ Book │ ─► │ Match │ ─► │ Trade │ ─► │ DB │ ─► │ CH │
+ └─────┘    └──────┘    └───────┘    └───────┘    └────┘    └────┘
+   Order      Insert      Fill         Record      SQLite    Clear
+   Entry      /Status     Partial      Trade       Persist   House
+```
+
+Each stage logs a timestamped message with detail text. Messages flow via SSE `msgflow` events for real-time display.
+
+### Implementation
+
+The visualizer uses Python function patching to intercept the matching engine methods:
+- `engine.submit_order()` → logs OEG (entry) + Book (status) + Match (fill)
+- `engine.cancel_order()` → logs OEG (cancel) + Book (cancelled)
+- `broadcast_event("trade", ...)` → logs Trade + DB + CH steps
+
+### API
+
+| Endpoint          | Method | Description                     |
+|-------------------|--------|---------------------------------|
+| /dev/messages     | GET    | Get recent message log (500 max)|
+
+### UI Features
+
+- **Pipeline counter**: shows cumulative message count per stage
+- **Live log**: new messages appear at top with highlight animation
+- **Clear**: resets all counters and log entries
+
+---
+
+## 17. Project Structure
 
 ```
  EuNEx/
@@ -1011,7 +1107,7 @@ The price chart renders OHLCV data as candlestick bars using a custom Chart.js p
 
 ---
 
-## 16. Build & Test
+## 18. Build & Test
 
 ### Prerequisites
 
@@ -1070,7 +1166,7 @@ cd build && ctest -C Release --output-on-failure
 
 ---
 
-## 17. Configuration
+## 19. Configuration
 
 ### Runtime Configuration (main.cpp)
 
@@ -1099,7 +1195,7 @@ The engine pre-populates order books with spread-defining orders:
 
 ---
 
-## 18. Extending EuNEx
+## 20. Extending EuNEx
 
 ### Adding a New Symbol
 
@@ -1148,9 +1244,11 @@ The engine pre-populates order books with spread-defining orders:
  ✓ Clearing house + AI traders     □ EuroCCP/LCH integration
  ✓ IACA fragments                  □ IACA FINISH + COPY + IDS
  ✓ Python bridge (JSON)            □ SBE multicast MDG
- ✓ Market simulation (C++ + Py)    □ AI analyst (Ollama/Llama)
- ✓ Ticker tape + OHLCV charts      □ SBE multicast MDG
- ✓ Daily close persistence          □ Multi-day backtesting
+ ✓ Market simulation (C++ + Py)    □ SBE multicast MDG
+ ✓ Ticker tape + OHLCV charts      □ Multi-day backtesting
+ ✓ Daily close persistence          □ Real Simplx multi-core
+ ✓ AI Analyst (Ollama/Groq/HF)     □ EuroCCP/LCH integration
+ ✓ Message Flow Visualizer          □ FIX 5.0 SP2 + SBE binary
                                     □ SQLite trade persistence
                                     □ Developer message visualizer
                                     □ SATURN ARM (MiFID II RTS 22)