Add clearing house simulation with 10 members (USR01-USR10)

- New clearing_house/ Flask service (port 5004) with dedicated dark-themed portal
- SQLite persistence: member capital, holdings, daily trade counters, settlements
- Members start with €100,000; must trade ≥10 securities per trading day
- Password = member ID (e.g. USR01 logs in with password USR01)
- Real users log in to trade manually; AI (LLM via Groq→HF→Ollama) simulates unoccupied members
- Trade attribution via Kafka trades consumer — detects USRxx- cl_ord_id prefix
- EOD settlement triggered by dashboard session end; calculates unrealized P&L
- Leaderboard at /ch/ with real-time auto-refresh and Human/AI badges
- Member portfolio view: holdings, order entry, trade history, settlement history
- Integrated into nginx (/ch/), entrypoint.sh, docker-compose, and HF Dockerfile

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

Dockerfile

@@ -73,6 +73,9 @@ COPY client_hf.cfg                    /app/fix_ui/client_hf.cfg
 # AI Analyst service
 COPY ai_analyst/ai_analyst.py         /app/ai_analyst.py
 
+# Clearing House service
+COPY clearing_house/                  /app/clearing_house/
+
 # ── Kafka KRaft configuration ─────────────────────────────────────────────────
 COPY kafka-kraft.properties           /opt/kafka/config/kraft/server.properties
 

clearing_house/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+RUN pip install --no-cache-dir flask kafka-python requests
+
+WORKDIR /app
+
+# shared/ is mounted as /app/shared at runtime (via docker-compose volume)
+# Copy clearing house service files
+COPY clearing_house/ /app/clearing_house/
+
+RUN mkdir -p /app/data
+
+WORKDIR /app/clearing_house
+
+ENV PYTHONPATH=/app
+
+CMD ["python", "app.py"]

clearing_house/app.py

@@ -0,0 +1,393 @@
+"""Clearing House portal — Flask service on port 5004.
+
+Routes are mounted at /ch/ so nginx can proxy /ch/ → this service
+without stripping the prefix (proxy_pass http://...:5004).
+"""
+
+import sys
+sys.path.insert(0, "/app")
+
+import json
+import os
+import threading
+import time
+import datetime
+from queue import Empty, Queue
+
+import requests
+from flask import (
+    Flask, Response, jsonify, redirect, render_template,
+    request, session, stream_with_context, url_for,
+)
+
+from shared.config import Config
+from shared.kafka_utils import create_producer
+
+import ch_database as db
+import ch_ai_trader as ai_trader
+
+# ── App setup ──────────────────────────────────────────────────────────────────
+app = Flask(__name__, template_folder="templates")
+app.secret_key = os.getenv("CH_SECRET_KEY", "ch-stockex-secret-2024")
+app.config["TEMPLATES_AUTO_RELOAD"] = True
+
+
+@app.template_filter("ts")
+def ts_filter(ts):
+    """Format a Unix timestamp as HH:MM:SS."""
+    return datetime.datetime.fromtimestamp(float(ts)).strftime("%H:%M:%S")
+
+MATCHER_URL = os.getenv("MATCHER_URL", Config.MATCHER_URL)
+SECURITIES_FILE = os.getenv("SECURITIES_FILE", "/app/data/securities.txt")
+
+# SSE clients
+_sse_clients: list[Queue] = []
+_sse_lock = threading.Lock()
+
+_producer = None
+
+
+def get_producer():
+    global _producer
+    if _producer is None:
+        _producer = create_producer(component_name="CH-App")
+    return _producer
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def _load_symbols() -> list[str]:
+    symbols = []
+    try:
+        with open(SECURITIES_FILE) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    parts = line.split()
+                    if parts:
+                        symbols.append(parts[0])
+    except Exception:
+        pass
+    return symbols
+
+
+def _get_bbos() -> dict:
+    symbols = _load_symbols()
+    bbos = {}
+    for sym in symbols:
+        try:
+            r = requests.get(f"{MATCHER_URL}/orderbook/{sym}", timeout=2)
+            if r.status_code == 200:
+                book = r.json()
+                bids = book.get("bids", [])
+                asks = book.get("asks", [])
+                best_bid = max((b["price"] for b in bids), default=None)
+                best_ask = min((a["price"] for a in asks), default=None)
+                mid = round((best_bid + best_ask) / 2, 2) if best_bid and best_ask else None
+                bbos[sym] = {"best_bid": best_bid, "best_ask": best_ask, "mid": mid}
+        except Exception:
+            pass
+    return bbos
+
+
+def _broadcast(event_type: str, data: dict):
+    msg = f"event: {event_type}\ndata: {json.dumps(data)}\n\n"
+    with _sse_lock:
+        for q in _sse_clients:
+            try:
+                q.put_nowait(msg)
+            except Exception:
+                pass
+
+
+def _build_leaderboard(bbos: dict) -> list[dict]:
+    rows = db.get_leaderboard()
+    for row in rows:
+        holdings_value = sum(
+            h["quantity"] * (bbos.get(h["symbol"], {}).get("mid") or h["avg_cost"])
+            for h in row["holdings"]
+        )
+        row["holdings_value"] = round(holdings_value, 2)
+        row["total_value"] = round(row["capital"] + holdings_value, 2)
+        row["pnl"] = round(row["total_value"] - db.CH_STARTING_CAPITAL, 2)
+        row["is_human"] = ai_trader.is_human_active(row["member_id"])
+    # Sort by total_value descending
+    rows.sort(key=lambda r: r["total_value"], reverse=True)
+    for i, row in enumerate(rows):
+        row["rank"] = i + 1
+    return rows
+
+
+# ── Auth helpers ───────────────────────────────────────────────────────────────
+
+def current_member() -> str | None:
+    return session.get("member_id")
+
+
+def require_login():
+    if not current_member():
+        return redirect(url_for("login_page"))
+    return None
+
+
+# ── Routes ─────────────────────────────────────────────────────────────────────
+
+@app.route("/ch/")
+def index():
+    bbos = _get_bbos()
+    leaderboard = _build_leaderboard(bbos)
+    member = current_member()
+    return render_template(
+        "dashboard.html",
+        leaderboard=leaderboard,
+        symbols=list(bbos.keys()),
+        member=member,
+        obligation=db.CH_DAILY_OBLIGATION,
+    )
+
+
+@app.route("/ch/login", methods=["GET"])
+def login_page():
+    if current_member():
+        return redirect(url_for("portfolio"))
+    return render_template("login.html", members=db.CH_MEMBERS)
+
+
+@app.route("/ch/login", methods=["POST"])
+def login_post():
+    member_id = request.form.get("member_id", "").upper().strip()
+    password  = request.form.get("password", "").strip()
+
+    if not db.verify_password(member_id, password):
+        return render_template("login.html", members=db.CH_MEMBERS, error="Invalid credentials.")
+
+    session["member_id"] = member_id
+    ai_trader.set_human_active(member_id)
+    _broadcast("member_login", {"member_id": member_id})
+    return redirect(url_for("portfolio"))
+
+
+@app.route("/ch/logout", methods=["POST"])
+def logout():
+    mid = current_member()
+    if mid:
+        ai_trader.set_human_inactive(mid)
+        session.pop("member_id", None)
+        _broadcast("member_logout", {"member_id": mid})
+    return redirect(url_for("index"))
+
+
+@app.route("/ch/portfolio")
+def portfolio():
+    redir = require_login()
+    if redir:
+        return redir
+    mid = current_member()
+    member = db.get_member(mid)
+    holdings = db.get_holdings(mid)
+    daily = db.get_daily_trades(mid)
+    trades = db.get_trade_log(mid)
+    settlements = db.get_settlements(mid, limit=10)
+    bbos = _get_bbos()
+
+    # Enrich holdings with current prices and P&L
+    for h in holdings:
+        bbo = bbos.get(h["symbol"], {})
+        current_price = bbo.get("mid") or h["avg_cost"]
+        h["current_price"] = round(current_price, 2)
+        h["unrealized_pnl"] = round((current_price - h["avg_cost"]) * h["quantity"], 2)
+        h["value"] = round(current_price * h["quantity"], 2)
+
+    total_holdings_value = sum(h["value"] for h in holdings)
+    total_value = round(member["capital"] + total_holdings_value, 2)
+    total_pnl   = round(total_value - db.CH_STARTING_CAPITAL, 2)
+
+    return render_template(
+        "portfolio.html",
+        member=mid,
+        capital=round(member["capital"], 2),
+        holdings=holdings,
+        daily=daily,
+        trades=trades,
+        settlements=settlements,
+        symbols=list(bbos.keys()),
+        obligation=db.CH_DAILY_OBLIGATION,
+        total_value=total_value,
+        total_pnl=total_pnl,
+    )
+
+
+@app.route("/ch/order", methods=["POST"])
+def submit_order():
+    redir = require_login()
+    if redir:
+        return jsonify({"error": "Not logged in"}), 401
+
+    mid = current_member()
+    data = request.get_json(force=True)
+
+    symbol   = str(data.get("symbol", "")).upper()
+    side     = str(data.get("side", "")).upper()
+    quantity = int(data.get("quantity", 0))
+    price    = float(data.get("price", 0))
+
+    if side not in ("BUY", "SELL") or quantity <= 0 or price <= 0 or not symbol:
+        return jsonify({"error": "Invalid order parameters"}), 400
+
+    member = db.get_member(mid)
+    if not member:
+        return jsonify({"error": "Member not found"}), 404
+
+    # Capital check
+    if side == "BUY" and quantity * price > member["capital"]:
+        return jsonify({"error": f"Insufficient capital (have €{member['capital']:.2f})"}), 400
+
+    # Holdings check
+    if side == "SELL":
+        holding = db.get_holding(mid, symbol)
+        if holding["quantity"] < quantity:
+            return jsonify({"error": f"Insufficient holdings ({holding['quantity']} shares held)"}), 400
+
+    cl_ord_id = f"{mid}-{int(time.time()*1000)}-H"
+    msg = {
+        "cl_ord_id":    cl_ord_id,
+        "symbol":       symbol,
+        "side":         side,
+        "quantity":     quantity,
+        "price":        price,
+        "ord_type":     "LIMIT",
+        "time_in_force": "DAY",
+        "timestamp":    time.time(),
+        "source":       "CLEARINGHOUSE",
+    }
+    get_producer().send(Config.ORDERS_TOPIC, msg)
+    return jsonify({"status": "ok", "cl_ord_id": cl_ord_id})
+
+
+@app.route("/ch/eod", methods=["POST"])
+def eod_settlement():
+    """Called by dashboard at end-of-day to settle all CH members."""
+    bbos = _get_bbos()
+    today = db.today_str()
+    results = []
+
+    members = db.get_all_members()
+    for member in members:
+        mid = member["member_id"]
+        capital = member["capital"]
+        holdings = db.get_holdings(mid)
+        daily = db.get_daily_trades(mid, today)
+
+        # Unrealized P&L: current market value vs avg cost
+        unrealized_pnl = 0.0
+        for h in holdings:
+            bbo = bbos.get(h["symbol"], {})
+            current_price = bbo.get("mid") or h["avg_cost"]
+            unrealized_pnl += (current_price - h["avg_cost"]) * h["quantity"]
+
+        # Realized P&L approximation: capital change from starting capital
+        # minus current holdings cost basis
+        cost_basis = sum(h["quantity"] * h["avg_cost"] for h in holdings)
+        realized_pnl = round(capital - db.CH_STARTING_CAPITAL + cost_basis, 2)
+
+        obligation_met = daily["total_securities"] >= db.CH_DAILY_OBLIGATION
+
+        db.record_settlement(
+            member_id=mid,
+            trading_date=today,
+            opening_capital=db.CH_STARTING_CAPITAL,
+            closing_capital=round(capital, 2),
+            realized_pnl=round(realized_pnl, 2),
+            unrealized_pnl=round(unrealized_pnl, 2),
+            obligation_met=obligation_met,
+        )
+
+        results.append({
+            "member_id": mid,
+            "capital": round(capital, 2),
+            "unrealized_pnl": round(unrealized_pnl, 2),
+            "obligation_met": obligation_met,
+        })
+
+        if not obligation_met:
+            print(f"[CH-EOD] {mid} did NOT meet daily obligation "
+                  f"({daily['total_securities']}/{db.CH_DAILY_OBLIGATION})")
+
+    _broadcast("eod_settlement", {"date": today, "count": len(results)})
+    print(f"[CH-EOD] Settlement complete for {len(results)} members on {today}")
+    return jsonify({"status": "ok", "settlements": results})
+
+
+# ── JSON API ───────────────────────────────────────────────────────────────────
+
+@app.route("/ch/api/leaderboard")
+def api_leaderboard():
+    bbos = _get_bbos()
+    return jsonify(_build_leaderboard(bbos))
+
+
+@app.route("/ch/api/portfolio")
+def api_portfolio():
+    mid = current_member()
+    if not mid:
+        return jsonify({"error": "Not logged in"}), 401
+    bbos = _get_bbos()
+    member = db.get_member(mid)
+    holdings = db.get_holdings(mid)
+    daily = db.get_daily_trades(mid)
+    for h in holdings:
+        bbo = bbos.get(h["symbol"], {})
+        h["current_price"] = bbo.get("mid") or h["avg_cost"]
+        h["unrealized_pnl"] = round((h["current_price"] - h["avg_cost"]) * h["quantity"], 2)
+    return jsonify({
+        "member_id": mid,
+        "capital": round(member["capital"], 2),
+        "holdings": holdings,
+        "daily": daily,
+    })
+
+
+@app.route("/ch/api/market")
+def api_market():
+    return jsonify(_get_bbos())
+
+
+# ── SSE ────────────────────────────────────────────────────────────────────────
+
+@app.route("/ch/stream")
+def sse_stream():
+    q: Queue = Queue(maxsize=50)
+    with _sse_lock:
+        _sse_clients.append(q)
+
+    def generate():
+        try:
+            yield "data: {\"type\":\"connected\"}\n\n"
+            while True:
+                try:
+                    msg = q.get(timeout=30)
+                    yield msg
+                except Empty:
+                    yield ": heartbeat\n\n"
+        finally:
+            with _sse_lock:
+                try:
+                    _sse_clients.remove(q)
+                except ValueError:
+                    pass
+
+    return Response(
+        stream_with_context(generate()),
+        mimetype="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )
+
+
+# ── Startup ────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    db.init_db()
+    ai_trader.start()
+    port = int(os.getenv("CH_PORT", "5004"))
+    print(f"[CH] Clearing House service starting on port {port}")
+    app.run(host="0.0.0.0", port=port, debug=False, use_reloader=False)

clearing_house/ch_ai_trader.py

@@ -0,0 +1,473 @@
+"""AI-driven simulation of CH members not currently controlled by a real user.
+
+Two background threads:
+  1. _trade_consumer_thread  – Kafka consumer on 'trades' topic; attributes
+     trades back to CH members whose cl_ord_id starts with USRxx-.
+  2. _simulation_thread      – every CH_AI_INTERVAL seconds, picks an order
+     for each unoccupied member using the LLM (Groq → HF → Ollama fallback).
+
+Call start() once from app.py after init_db().
+Call set_human_active(member_id) / set_human_inactive(member_id) on login/logout.
+"""
+
+import sys
+sys.path.insert(0, "/app")
+
+import json
+import os
+import random
+import re
+import threading
+import time
+from typing import Optional
+
+import requests
+
+from shared.config import Config
+from shared.kafka_utils import create_consumer, create_producer
+
+import ch_database as db
+
+# ── Config ─────────────────────────────────────────────────────────────────────
+CH_AI_INTERVAL = int(os.getenv("CH_AI_INTERVAL", "45"))   # seconds between AI cycles
+CH_SOURCE      = "CLEARINGHOUSE"
+
+OLLAMA_HOST  = os.getenv("OLLAMA_HOST", "")
+OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "llama3.1:8b")
+HF_TOKEN     = os.getenv("HF_TOKEN", "")
+HF_MODEL     = os.getenv("HF_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "")
+GROQ_MODEL   = os.getenv("GROQ_MODEL", "llama-3.1-8b-instant")
+GROQ_URL     = "https://api.groq.com/openai/v1/chat/completions"
+
+# ── Shared state ───────────────────────────────────────────────────────────────
+_active_humans: set[str] = set()   # member_ids currently logged-in as humans
+_humans_lock = threading.Lock()
+
+_running   = False
+_suspended = False
+
+_order_seq = 0
+_seq_lock  = threading.Lock()
+
+_producer = None
+_producer_lock = threading.Lock()
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+def set_human_active(member_id: str) -> None:
+    with _humans_lock:
+        _active_humans.add(member_id)
+
+
+def set_human_inactive(member_id: str) -> None:
+    with _humans_lock:
+        _active_humans.discard(member_id)
+
+
+def is_human_active(member_id: str) -> bool:
+    with _humans_lock:
+        return member_id in _active_humans
+
+
+def start() -> None:
+    """Start background threads. Call once after app startup."""
+    global _running
+    _running = True
+    threading.Thread(target=_trade_consumer_thread, daemon=True, name="ch-trade-consumer").start()
+    threading.Thread(target=_simulation_thread,     daemon=True, name="ch-ai-sim").start()
+    threading.Thread(target=_control_listener_thread, daemon=True, name="ch-control").start()
+    print("[CH-AI] Background threads started")
+
+
+# ── Kafka helpers ──────────────────────────────────────────────────────────────
+
+def _get_producer():
+    global _producer
+    with _producer_lock:
+        if _producer is None:
+            _producer = create_producer(component_name="CH-AI")
+    return _producer
+
+
+def _next_cl_ord_id(member_id: str) -> str:
+    global _order_seq
+    with _seq_lock:
+        _order_seq += 1
+        return f"{member_id}-{int(time.time() * 1000)}-{_order_seq}"
+
+
+# ── Thread 1: Trade consumer (attribution) ─────────────────────────────────────
+
+def _trade_consumer_thread():
+    """Consume 'trades' topic and attribute CH member trades to their accounts."""
+    try:
+        consumer = create_consumer(
+            Config.TRADES_TOPIC,
+            group_id="clearing-house-trades",
+            auto_offset_reset="latest",
+            component_name="CH-TradeConsumer",
+        )
+    except Exception as e:
+        print(f"[CH-AI] Trade consumer failed to start: {e}")
+        return
+
+    for msg in consumer:
+        if not _running:
+            break
+        try:
+            trade = msg.value
+            buy_id  = trade.get("buy_order_id",  "")
+            sell_id = trade.get("sell_order_id", "")
+            symbol  = trade.get("symbol", "")
+            price   = float(trade.get("price", 0))
+            qty     = int(trade.get("quantity", 0))
+
+            if not symbol or price <= 0 or qty <= 0:
+                continue
+
+            # Detect CH member orders by cl_ord_id prefix pattern USRxx-
+            for order_id, side in [(buy_id, "BUY"), (sell_id, "SELL")]:
+                m = re.match(r"^(USR\d{2})-", order_id)
+                if m:
+                    member_id = m.group(1)
+                    db.record_trade(member_id, symbol, side, qty, price, order_id)
+                    print(f"[CH-AI] Attributed {side} {qty} {symbol}@{price:.2f} → {member_id}")
+        except Exception as e:
+            print(f"[CH-AI] Trade attribution error: {e}")
+
+
+# ── Thread 3: Control listener ─────────────────────────────────────────────────
+
+def _control_listener_thread():
+    global _running, _suspended
+    try:
+        consumer = create_consumer(
+            Config.CONTROL_TOPIC,
+            group_id="clearing-house-control",
+            auto_offset_reset="latest",
+            component_name="CH-Control",
+        )
+    except Exception as e:
+        print(f"[CH-AI] Control consumer failed: {e}")
+        return
+
+    for msg in consumer:
+        try:
+            action = msg.value.get("action", "")
+            if action in ("stop", "end"):
+                _suspended = True
+                print("[CH-AI] Session stopped — AI simulation paused")
+            elif action == "start":
+                _suspended = False
+                print("[CH-AI] Session started — AI simulation active")
+            elif action == "suspend":
+                _suspended = True
+            elif action == "resume":
+                _suspended = False
+        except Exception as e:
+            print(f"[CH-AI] Control error: {e}")
+
+
+# ── Thread 2: AI simulation ────────────────────────────────────────────────────
+
+def _simulation_thread():
+    """Every CH_AI_INTERVAL seconds, generate a trade for each unoccupied member."""
+    while _running:
+        time.sleep(CH_AI_INTERVAL)
+        if _suspended:
+            continue
+        try:
+            _run_simulation_cycle()
+        except Exception as e:
+            print(f"[CH-AI] Simulation cycle error: {e}")
+
+
+def _run_simulation_cycle():
+    # Fetch current BBO from Matcher
+    bbos = _fetch_bbos()
+    if not bbos:
+        return
+
+    today = db.today_str()
+    members = db.get_all_members()
+
+    for member in members:
+        mid = member["member_id"]
+        if is_human_active(mid):
+            continue
+
+        dt = db.get_daily_trades(mid, today)
+        obligation_remaining = max(0, db.CH_DAILY_OBLIGATION - dt["total_securities"])
+        holdings = db.get_holdings(mid)
+        capital = member["capital"]
+
+        # Skip if no market data and obligation already met
+        if obligation_remaining == 0 and random.random() > 0.3:
+            continue  # occasionally trade even after obligation met
+
+        order = _decide_order_llm(mid, capital, holdings, dt, bbos, obligation_remaining)
+        if order:
+            _submit_order(mid, order)
+            time.sleep(0.5)  # stagger submissions
+
+
+def _fetch_bbos() -> dict:
+    """Get BBO for all symbols from Matcher API."""
+    try:
+        # Load securities list to know symbols
+        secs_file = os.getenv("SECURITIES_FILE", "/app/data/securities.txt")
+        symbols = []
+        try:
+            with open(secs_file) as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#"):
+                        parts = line.split()
+                        if parts:
+                            symbols.append(parts[0])
+        except Exception:
+            pass
+
+        if not symbols:
+            return {}
+
+        bbos = {}
+        matcher_url = os.getenv("MATCHER_URL", Config.MATCHER_URL)
+        for sym in symbols:
+            try:
+                r = requests.get(f"{matcher_url}/orderbook/{sym}", timeout=2)
+                if r.status_code == 200:
+                    book = r.json()
+                    bids = book.get("bids", [])
+                    asks = book.get("asks", [])
+                    best_bid = max((b["price"] for b in bids), default=None)
+                    best_ask = min((a["price"] for a in asks), default=None)
+                    if best_bid or best_ask:
+                        bbos[sym] = {"best_bid": best_bid, "best_ask": best_ask}
+            except Exception:
+                pass
+        return bbos
+    except Exception as e:
+        print(f"[CH-AI] BBO fetch error: {e}")
+        return {}
+
+
+def _decide_order_llm(
+    member_id: str,
+    capital: float,
+    holdings: list,
+    daily_trades: dict,
+    bbos: dict,
+    obligation_remaining: int,
+) -> Optional[dict]:
+    """Call LLM to decide the next trade. Falls back to rule-based on failure."""
+    prompt = _build_prompt(member_id, capital, holdings, daily_trades, bbos, obligation_remaining)
+    text = _call_llm(prompt)
+    if text:
+        order = _parse_llm_order(text, bbos)
+        if order and _validate_order(order, capital, holdings, bbos):
+            return order
+    # Fallback: rule-based
+    return _fallback_order(capital, holdings, bbos)
+
+
+def _build_prompt(member_id, capital, holdings, daily_trades, bbos, obligation_remaining):
+    market_lines = []
+    for sym, bbo in sorted(bbos.items()):
+        bid = f"{bbo['best_bid']:.2f}" if bbo.get("best_bid") else "-"
+        ask = f"{bbo['best_ask']:.2f}" if bbo.get("best_ask") else "-"
+        market_lines.append(f"  {sym}: Bid {bid} / Ask {ask}")
+
+    holding_lines = [
+        f"  {h['symbol']}: {h['quantity']} shares @ avg cost {h['avg_cost']:.2f}"
+        for h in holdings
+    ] if holdings else ["  None"]
+
+    return (
+        f"You are simulating clearing house member {member_id} making ONE trading decision.\n\n"
+        f"Member state:\n"
+        f"  Available capital: EUR {capital:,.2f}\n"
+        f"  Securities obligation remaining today: {obligation_remaining} more to trade\n"
+        f"  Current holdings:\n" + "\n".join(holding_lines) + "\n\n"
+        f"Current market (Bid/Ask):\n" + "\n".join(market_lines) + "\n\n"
+        f"Rules:\n"
+        f"- Do not spend more than your available capital\n"
+        f"- Do not sell more shares than you hold\n"
+        f"- If you have no holdings, you must BUY\n"
+        f"- Choose a realistic price close to the BBO mid-price\n"
+        f"- Quantity should be between 10 and 200\n\n"
+        f"Respond ONLY with valid JSON, no other text:\n"
+        f'Example: {{"symbol": "ALPHA", "side": "BUY", "quantity": 50, "price": 5.95}}'
+    )
+
+
+def _parse_llm_order(text: str, bbos: dict) -> Optional[dict]:
+    try:
+        match = re.search(r"\{[^}]+\}", text, re.DOTALL)
+        if not match:
+            return None
+        data = json.loads(match.group())
+        return {
+            "symbol":   str(data.get("symbol", "")).upper(),
+            "side":     str(data.get("side", "")).upper(),
+            "quantity": int(data.get("quantity", 0)),
+            "price":    float(data.get("price", 0)),
+        }
+    except Exception:
+        return None
+
+
+def _validate_order(order: dict, capital: float, holdings: list, bbos: dict) -> bool:
+    sym = order.get("symbol", "")
+    side = order.get("side", "")
+    qty = order.get("quantity", 0)
+    price = order.get("price", 0)
+
+    if sym not in bbos or side not in ("BUY", "SELL") or qty <= 0 or price <= 0:
+        return False
+    if side == "BUY" and qty * price > capital:
+        return False
+    if side == "SELL":
+        held = next((h["quantity"] for h in holdings if h["symbol"] == sym), 0)
+        if qty > held:
+            return False
+    return True
+
+
+def _fallback_order(capital: float, holdings: list, bbos: dict) -> Optional[dict]:
+    """Rule-based fallback: prefer BUY if no holdings, SELL if heavily loaded."""
+    if not bbos:
+        return None
+
+    # Decide side
+    total_holding_value = sum(
+        h["quantity"] * (bbos.get(h["symbol"], {}).get("best_ask") or h["avg_cost"])
+        for h in holdings
+    )
+    # BUY if holdings < 30% of total net worth, else 50/50
+    net_worth = capital + total_holding_value
+    if net_worth > 0 and total_holding_value / net_worth < 0.3:
+        side = "BUY"
+    else:
+        side = random.choice(["BUY", "SELL"])
+
+    if side == "SELL" and not holdings:
+        side = "BUY"
+
+    if side == "BUY":
+        # Pick a random affordable symbol
+        affordable = [
+            sym for sym, bbo in bbos.items()
+            if bbo.get("best_ask") and 10 * bbo["best_ask"] <= capital
+        ]
+        if not affordable:
+            return None
+        sym = random.choice(affordable)
+        ask = bbos[sym]["best_ask"]
+        qty = min(random.randint(10, 100), int(capital // ask))
+        if qty <= 0:
+            return None
+        return {"symbol": sym, "side": "BUY", "quantity": qty, "price": round(ask, 2)}
+    else:
+        # Sell from existing holdings
+        h = random.choice(holdings)
+        sym = h["symbol"]
+        bbo = bbos.get(sym, {})
+        bid = bbo.get("best_bid") or h["avg_cost"]
+        qty = random.randint(10, max(10, h["quantity"] // 2))
+        qty = min(qty, h["quantity"])
+        if qty <= 0:
+            return None
+        return {"symbol": sym, "side": "SELL", "quantity": qty, "price": round(bid, 2)}
+
+
+def _submit_order(member_id: str, order: dict) -> None:
+    cl_ord_id = _next_cl_ord_id(member_id)
+    msg = {
+        "cl_ord_id":    cl_ord_id,
+        "symbol":       order["symbol"],
+        "side":         order["side"],
+        "quantity":     order["quantity"],
+        "price":        order["price"],
+        "ord_type":     "LIMIT",
+        "time_in_force": "DAY",
+        "timestamp":    time.time(),
+        "source":       CH_SOURCE,
+    }
+    try:
+        _get_producer().send(Config.ORDERS_TOPIC, msg)
+        print(f"[CH-AI] {member_id} → {order['side']} {order['quantity']} {order['symbol']}@{order['price']:.2f}")
+    except Exception as e:
+        print(f"[CH-AI] Order submit failed: {e}")
+
+
+# ── LLM (Groq → HF → Ollama fallback) ────────────────────────────────────────
+
+def _call_llm(prompt: str) -> Optional[str]:
+    return _try_groq(prompt) or _try_hf(prompt) or _try_ollama(prompt)
+
+
+def _try_groq(prompt: str) -> Optional[str]:
+    if not GROQ_API_KEY:
+        return None
+    try:
+        resp = requests.post(
+            GROQ_URL,
+            headers={"Authorization": f"Bearer {GROQ_API_KEY}", "Content-Type": "application/json"},
+            json={
+                "model": GROQ_MODEL,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": 100,
+                "temperature": 0.4,
+            },
+            timeout=20,
+        )
+        if resp.status_code == 200:
+            return resp.json()["choices"][0]["message"]["content"].strip()
+    except Exception as e:
+        print(f"[CH-AI] Groq error: {e}")
+    return None
+
+
+def _try_hf(prompt: str) -> Optional[str]:
+    if not HF_TOKEN:
+        return None
+    if HF_MODEL.startswith("RayMelius/"):
+        url = f"https://api-inference.huggingface.co/models/{HF_MODEL}/v1/chat/completions"
+    else:
+        url = "https://router.huggingface.co/v1/chat/completions"
+    try:
+        resp = requests.post(
+            url,
+            headers={"Authorization": f"Bearer {HF_TOKEN}", "Content-Type": "application/json"},
+            json={
+                "model": HF_MODEL,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": 100,
+                "temperature": 0.4,
+            },
+            timeout=30,
+        )
+        if resp.status_code == 200:
+            return resp.json()["choices"][0]["message"]["content"].strip()
+    except Exception as e:
+        print(f"[CH-AI] HF error: {e}")
+    return None
+
+
+def _try_ollama(prompt: str) -> Optional[str]:
+    if not OLLAMA_HOST:
+        return None
+    try:
+        resp = requests.post(
+            f"{OLLAMA_HOST}/api/chat",
+            json={"model": OLLAMA_MODEL, "messages": [{"role": "user", "content": prompt}], "stream": False},
+            timeout=60,
+        )
+        if resp.status_code == 200:
+            return resp.json().get("message", {}).get("content", "").strip()
+    except Exception as e:
+        print(f"[CH-AI] Ollama error: {e}")
+    return None

clearing_house/ch_database.py

@@ -0,0 +1,294 @@
+"""SQLite persistence for the Clearing House simulation.
+
+DB path: /app/data/clearing_house.db (shared volume with dashboard).
+All public functions are thread-safe via thread-local connections.
+"""
+
+import sqlite3
+import threading
+import time
+import datetime
+import os
+
+CH_DB_PATH = os.getenv("CH_DB_PATH", "/app/data/clearing_house.db")
+CH_MEMBERS = [f"USR{i:02d}" for i in range(1, 11)]
+CH_STARTING_CAPITAL = 100_000.0
+CH_DAILY_OBLIGATION = 10  # minimum securities (qty sum) per trading day
+
+_local = threading.local()
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS ch_members (
+    member_id   TEXT PRIMARY KEY,
+    capital     REAL NOT NULL DEFAULT 100000.0,
+    created_at  REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS ch_holdings (
+    member_id   TEXT NOT NULL,
+    symbol      TEXT NOT NULL,
+    quantity    INTEGER NOT NULL DEFAULT 0,
+    avg_cost    REAL NOT NULL DEFAULT 0.0,
+    PRIMARY KEY (member_id, symbol)
+);
+
+CREATE TABLE IF NOT EXISTS ch_daily_trades (
+    member_id        TEXT NOT NULL,
+    trading_date     TEXT NOT NULL,
+    buy_count        INTEGER NOT NULL DEFAULT 0,
+    sell_count       INTEGER NOT NULL DEFAULT 0,
+    total_securities INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (member_id, trading_date)
+);
+
+CREATE TABLE IF NOT EXISTS ch_trade_log (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    member_id    TEXT NOT NULL,
+    symbol       TEXT NOT NULL,
+    side         TEXT NOT NULL,
+    quantity     INTEGER NOT NULL,
+    price        REAL NOT NULL,
+    cl_ord_id    TEXT NOT NULL,
+    trading_date TEXT NOT NULL,
+    timestamp    REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS ch_settlements (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    member_id       TEXT NOT NULL,
+    trading_date    TEXT NOT NULL,
+    opening_capital REAL NOT NULL,
+    closing_capital REAL NOT NULL,
+    realized_pnl    REAL NOT NULL DEFAULT 0.0,
+    unrealized_pnl  REAL NOT NULL DEFAULT 0.0,
+    obligation_met  INTEGER NOT NULL DEFAULT 0,
+    settled_at      REAL NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_ch_trade_log_member
+    ON ch_trade_log(member_id, trading_date);
+CREATE INDEX IF NOT EXISTS idx_ch_settlements_member
+    ON ch_settlements(member_id, trading_date);
+"""
+
+
+def _conn() -> sqlite3.Connection:
+    """Thread-local SQLite connection."""
+    if not hasattr(_local, "conn") or _local.conn is None:
+        _local.conn = sqlite3.connect(CH_DB_PATH, check_same_thread=False)
+        _local.conn.row_factory = sqlite3.Row
+    return _local.conn
+
+
+def init_db() -> None:
+    """Create schema and seed the 10 members if missing."""
+    conn = _conn()
+    conn.executescript(SCHEMA)
+    conn.commit()
+    now = time.time()
+    for mid in CH_MEMBERS:
+        conn.execute(
+            "INSERT OR IGNORE INTO ch_members (member_id, capital, created_at) VALUES (?,?,?)",
+            (mid, CH_STARTING_CAPITAL, now),
+        )
+    conn.commit()
+    print(f"[CH-DB] Initialized at {CH_DB_PATH}")
+
+
+# ── Members ────────────────────────────────────────────────────────────────────
+
+def get_member(member_id: str) -> dict | None:
+    row = _conn().execute(
+        "SELECT member_id, capital FROM ch_members WHERE member_id=?", (member_id,)
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def get_all_members() -> list[dict]:
+    rows = _conn().execute(
+        "SELECT member_id, capital FROM ch_members ORDER BY member_id"
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ── Holdings ───────────────────────────────────────────────────────────────────
+
+def get_holdings(member_id: str) -> list[dict]:
+    rows = _conn().execute(
+        "SELECT symbol, quantity, avg_cost FROM ch_holdings WHERE member_id=? AND quantity>0",
+        (member_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def get_holding(member_id: str, symbol: str) -> dict:
+    row = _conn().execute(
+        "SELECT quantity, avg_cost FROM ch_holdings WHERE member_id=? AND symbol=?",
+        (member_id, symbol),
+    ).fetchone()
+    return dict(row) if row else {"quantity": 0, "avg_cost": 0.0}
+
+
+# ── Trade recording (atomic) ───────────────────────────────────────────────────
+
+def today_str() -> str:
+    return datetime.date.today().isoformat()
+
+
+def record_trade(
+    member_id: str,
+    symbol: str,
+    side: str,
+    quantity: int,
+    price: float,
+    cl_ord_id: str,
+) -> None:
+    """Atomically update holdings, capital, daily counter, and trade log."""
+    conn = _conn()
+    date = today_str()
+    value = quantity * price
+
+    with conn:  # auto-commit / rollback
+        # 1. Update holdings
+        holding = get_holding(member_id, symbol)
+        old_qty = holding["quantity"]
+        old_avg = holding["avg_cost"]
+
+        if side == "BUY":
+            new_qty = old_qty + quantity
+            new_avg = (old_qty * old_avg + quantity * price) / new_qty if new_qty else price
+            conn.execute(
+                """INSERT INTO ch_holdings (member_id, symbol, quantity, avg_cost)
+                   VALUES (?,?,?,?)
+                   ON CONFLICT(member_id, symbol) DO UPDATE
+                   SET quantity=excluded.quantity, avg_cost=excluded.avg_cost""",
+                (member_id, symbol, new_qty, round(new_avg, 4)),
+            )
+            # 2. Deduct capital
+            conn.execute(
+                "UPDATE ch_members SET capital = capital - ? WHERE member_id=?",
+                (value, member_id),
+            )
+        else:  # SELL
+            new_qty = max(0, old_qty - quantity)
+            if new_qty == 0:
+                conn.execute(
+                    "DELETE FROM ch_holdings WHERE member_id=? AND symbol=?",
+                    (member_id, symbol),
+                )
+            else:
+                conn.execute(
+                    "UPDATE ch_holdings SET quantity=? WHERE member_id=? AND symbol=?",
+                    (new_qty, member_id, symbol),
+                )
+            # 2. Add capital
+            conn.execute(
+                "UPDATE ch_members SET capital = capital + ? WHERE member_id=?",
+                (value, member_id),
+            )
+
+        # 3. Update daily trade counter
+        buy_inc = 1 if side == "BUY" else 0
+        sell_inc = 1 if side == "SELL" else 0
+        conn.execute(
+            """INSERT INTO ch_daily_trades (member_id, trading_date, buy_count, sell_count, total_securities)
+               VALUES (?,?,?,?,?)
+               ON CONFLICT(member_id, trading_date) DO UPDATE
+               SET buy_count   = buy_count + excluded.buy_count,
+                   sell_count  = sell_count + excluded.sell_count,
+                   total_securities = total_securities + excluded.total_securities""",
+            (member_id, date, buy_inc, sell_inc, quantity),
+        )
+
+        # 4. Log the trade
+        conn.execute(
+            """INSERT INTO ch_trade_log
+               (member_id, symbol, side, quantity, price, cl_ord_id, trading_date, timestamp)
+               VALUES (?,?,?,?,?,?,?,?)""",
+            (member_id, symbol, side, quantity, price, cl_ord_id, date, time.time()),
+        )
+
+
+def get_daily_trades(member_id: str, date: str | None = None) -> dict:
+    date = date or today_str()
+    row = _conn().execute(
+        "SELECT buy_count, sell_count, total_securities FROM ch_daily_trades WHERE member_id=? AND trading_date=?",
+        (member_id, date),
+    ).fetchone()
+    return dict(row) if row else {"buy_count": 0, "sell_count": 0, "total_securities": 0}
+
+
+def get_trade_log(member_id: str, date: str | None = None, limit: int = 50) -> list[dict]:
+    date = date or today_str()
+    rows = _conn().execute(
+        """SELECT symbol, side, quantity, price, cl_ord_id, timestamp
+           FROM ch_trade_log WHERE member_id=? AND trading_date=?
+           ORDER BY timestamp DESC LIMIT ?""",
+        (member_id, date, limit),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ── EOD Settlement ─────────────────────────────────────────────────────────────
+
+def record_settlement(
+    member_id: str,
+    trading_date: str,
+    opening_capital: float,
+    closing_capital: float,
+    realized_pnl: float,
+    unrealized_pnl: float,
+    obligation_met: bool,
+) -> None:
+    _conn().execute(
+        """INSERT INTO ch_settlements
+           (member_id, trading_date, opening_capital, closing_capital,
+            realized_pnl, unrealized_pnl, obligation_met, settled_at)
+           VALUES (?,?,?,?,?,?,?,?)""",
+        (
+            member_id, trading_date, opening_capital, closing_capital,
+            realized_pnl, unrealized_pnl, int(obligation_met), time.time(),
+        ),
+    )
+    _conn().commit()
+
+
+def get_settlements(member_id: str, limit: int = 30) -> list[dict]:
+    rows = _conn().execute(
+        """SELECT trading_date, opening_capital, closing_capital,
+                  realized_pnl, unrealized_pnl, obligation_met, settled_at
+           FROM ch_settlements WHERE member_id=?
+           ORDER BY settled_at DESC LIMIT ?""",
+        (member_id, limit),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ── Leaderboard ────────────────────────────────────────────────────────────────
+
+def get_leaderboard(date: str | None = None) -> list[dict]:
+    """Returns member stats. Caller adds holdings_value using live prices."""
+    date = date or today_str()
+    members = get_all_members()
+    result = []
+    for m in members:
+        mid = m["member_id"]
+        dt = get_daily_trades(mid, date)
+        holdings = get_holdings(mid)
+        result.append({
+            "member_id": mid,
+            "capital": round(m["capital"], 2),
+            "holdings": holdings,
+            "buy_count": dt["buy_count"],
+            "sell_count": dt["sell_count"],
+            "total_securities": dt["total_securities"],
+            "obligation_met": dt["total_securities"] >= CH_DAILY_OBLIGATION,
+        })
+    return result
+
+
+# ── Auth ───────────────────────────────────────────────────────────────────────
+
+def verify_password(member_id: str, password: str) -> bool:
+    """Password equals the member ID (e.g. USR01 / USR01)."""
+    return member_id in CH_MEMBERS and password == member_id

clearing_house/templates/base.html

@@ -0,0 +1,250 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{% block title %}StockEx Clearing House{% endblock %}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --bg:        #0d1117;
+      --bg2:       #161b22;
+      --bg3:       #21262d;
+      --border:    #30363d;
+      --text:      #e6edf3;
+      --muted:     #8b949e;
+      --green:     #3fb950;
+      --red:       #f85149;
+      --yellow:    #d29922;
+      --blue:      #58a6ff;
+      --purple:    #bc8cff;
+      --accent:    #1f6feb;
+    }
+
+    body {
+      background: var(--bg);
+      color: var(--text);
+      font-family: ui-monospace, SFMono-Regular, "SF Mono", Consolas, monospace;
+      font-size: 13px;
+      min-height: 100vh;
+    }
+
+    /* ── Nav ── */
+    nav {
+      background: var(--bg2);
+      border-bottom: 1px solid var(--border);
+      padding: 0 24px;
+      height: 52px;
+      display: flex;
+      align-items: center;
+      gap: 24px;
+    }
+    nav .brand {
+      font-size: 15px;
+      font-weight: 700;
+      color: var(--blue);
+      text-decoration: none;
+      letter-spacing: 0.5px;
+    }
+    nav .brand span { color: var(--muted); font-weight: 400; }
+    nav .nav-links { display: flex; gap: 16px; flex: 1; }
+    nav .nav-links a {
+      color: var(--muted);
+      text-decoration: none;
+      padding: 4px 8px;
+      border-radius: 4px;
+      transition: color .15s, background .15s;
+    }
+    nav .nav-links a:hover { color: var(--text); background: var(--bg3); }
+    nav .nav-links a.active { color: var(--text); }
+    nav .nav-right { display: flex; align-items: center; gap: 12px; }
+    nav .member-badge {
+      background: var(--accent);
+      color: #fff;
+      padding: 3px 10px;
+      border-radius: 12px;
+      font-size: 12px;
+      font-weight: 600;
+    }
+    nav form { display: inline; }
+    nav button.logout {
+      background: none;
+      border: 1px solid var(--border);
+      color: var(--muted);
+      padding: 4px 12px;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 12px;
+      font-family: inherit;
+    }
+    nav button.logout:hover { border-color: var(--red); color: var(--red); }
+    nav a.login-btn {
+      background: var(--accent);
+      color: #fff;
+      padding: 5px 14px;
+      border-radius: 4px;
+      text-decoration: none;
+      font-size: 12px;
+      font-weight: 600;
+    }
+
+    /* ── Layout ── */
+    main { padding: 24px; max-width: 1400px; margin: 0 auto; }
+
+    h1 { font-size: 20px; font-weight: 600; margin-bottom: 20px; }
+    h2 { font-size: 15px; font-weight: 600; margin-bottom: 12px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.5px; }
+
+    /* ── Cards ── */
+    .card {
+      background: var(--bg2);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 20px;
+      margin-bottom: 20px;
+    }
+
+    /* ── Tables ── */
+    table { width: 100%; border-collapse: collapse; }
+    thead th {
+      text-align: left;
+      padding: 8px 12px;
+      color: var(--muted);
+      font-size: 11px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      border-bottom: 1px solid var(--border);
+    }
+    tbody td {
+      padding: 10px 12px;
+      border-bottom: 1px solid var(--border);
+      vertical-align: middle;
+    }
+    tbody tr:last-child td { border-bottom: none; }
+    tbody tr:hover td { background: var(--bg3); }
+
+    /* ── Utilities ── */
+    .positive { color: var(--green); }
+    .negative { color: var(--red); }
+    .neutral  { color: var(--muted); }
+    .badge-ok  { background: rgba(63,185,80,.15); color: var(--green); padding: 2px 8px; border-radius: 10px; font-size: 11px; }
+    .badge-bad { background: rgba(248,81,73,.12); color: var(--red);   padding: 2px 8px; border-radius: 10px; font-size: 11px; }
+    .badge-ai  { background: rgba(188,140,255,.15); color: var(--purple); padding: 2px 8px; border-radius: 10px; font-size: 11px; }
+    .badge-human { background: rgba(88,166,255,.15); color: var(--blue); padding: 2px 8px; border-radius: 10px; font-size: 11px; }
+
+    /* ── Buttons ── */
+    .btn {
+      display: inline-block;
+      padding: 8px 18px;
+      border-radius: 6px;
+      font-size: 13px;
+      font-family: inherit;
+      cursor: pointer;
+      border: none;
+      font-weight: 600;
+      transition: opacity .15s;
+    }
+    .btn:hover { opacity: .85; }
+    .btn-primary { background: var(--accent); color: #fff; }
+    .btn-danger  { background: var(--red); color: #fff; }
+    .btn-sm { padding: 5px 12px; font-size: 12px; }
+
+    /* ── Forms ── */
+    .form-group { margin-bottom: 14px; }
+    label { display: block; margin-bottom: 4px; color: var(--muted); font-size: 12px; }
+    input, select {
+      width: 100%;
+      background: var(--bg3);
+      border: 1px solid var(--border);
+      color: var(--text);
+      padding: 8px 10px;
+      border-radius: 6px;
+      font-family: inherit;
+      font-size: 13px;
+    }
+    input:focus, select:focus {
+      outline: none;
+      border-color: var(--accent);
+    }
+
+    /* ── Flash messages ── */
+    .flash { padding: 10px 16px; border-radius: 6px; margin-bottom: 16px; font-size: 13px; }
+    .flash-error { background: rgba(248,81,73,.12); border: 1px solid var(--red); color: var(--red); }
+
+    /* ── Grid ── */
+    .grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }
+    .grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; }
+    @media (max-width: 900px) { .grid-2, .grid-3 { grid-template-columns: 1fr; } }
+
+    /* ── Stat tiles ── */
+    .stat { text-align: center; }
+    .stat .val { font-size: 24px; font-weight: 700; }
+    .stat .lbl { font-size: 11px; color: var(--muted); margin-top: 4px; }
+
+    #toast {
+      position: fixed;
+      bottom: 24px;
+      right: 24px;
+      background: var(--bg3);
+      border: 1px solid var(--border);
+      padding: 12px 20px;
+      border-radius: 8px;
+      display: none;
+      z-index: 999;
+      font-size: 13px;
+    }
+  </style>
+</head>
+<body>
+  <nav>
+    <a href="/ch/" class="brand">StockEx <span>/ Clearing House</span></a>
+    <div class="nav-links">
+      <a href="/ch/" class="{{ 'active' if request.path == '/ch/' else '' }}">Leaderboard</a>
+      {% if member %}
+      <a href="/ch/portfolio" class="{{ 'active' if '/portfolio' in request.path else '' }}">My Portfolio</a>
+      {% endif %}
+      <a href="/" target="_blank">Main Dashboard ↗</a>
+    </div>
+    <div class="nav-right">
+      {% if member %}
+        <span class="member-badge">{{ member }}</span>
+        <form action="/ch/logout" method="post">
+          <button class="logout" type="submit">Logout</button>
+        </form>
+      {% else %}
+        <a href="/ch/login" class="login-btn">Login</a>
+      {% endif %}
+    </div>
+  </nav>
+
+  <main>
+    {% block content %}{% endblock %}
+  </main>
+
+  <div id="toast"></div>
+
+  <script>
+    // SSE for real-time updates
+    const es = new EventSource('/ch/stream');
+    const toast = document.getElementById('toast');
+
+    function showToast(msg, ms=3000) {
+      toast.textContent = msg;
+      toast.style.display = 'block';
+      setTimeout(() => { toast.style.display = 'none'; }, ms);
+    }
+
+    es.addEventListener('eod_settlement', () => {
+      showToast('EOD Settlement complete — page refreshing…', 2000);
+      setTimeout(() => location.reload(), 2200);
+    });
+
+    es.addEventListener('member_login', e => {
+      const d = JSON.parse(e.data);
+      showToast(`${d.member_id} logged in`);
+    });
+
+    {% block extra_scripts %}{% endblock %}
+  </script>
+</body>
+</html>

clearing_house/templates/dashboard.html

@@ -0,0 +1,130 @@
+{% extends "base.html" %}
+{% block title %}Leaderboard — StockEx Clearing House{% endblock %}
+
+{% block content %}
+<div style="display:flex; align-items:center; justify-content:space-between; margin-bottom:20px;">
+  <h1 style="margin:0;">Clearing House Leaderboard</h1>
+  <span style="color:var(--muted); font-size:12px;" id="last-update">Live</span>
+</div>
+
+<!-- Summary stats -->
+<div class="grid-3" style="margin-bottom:20px;">
+  {% set total_capital = leaderboard | sum(attribute='capital') %}
+  {% set met_count = leaderboard | selectattr('obligation_met') | list | length %}
+  <div class="card stat">
+    <div class="val">{{ leaderboard | length }}</div>
+    <div class="lbl">Active Members</div>
+  </div>
+  <div class="card stat">
+    <div class="val positive">{{ met_count }}</div>
+    <div class="lbl">Obligation Met Today</div>
+  </div>
+  <div class="card stat">
+    <div class="val">€{{ "{:,.0f}".format(total_capital) }}</div>
+    <div class="lbl">Total Capital in Market</div>
+  </div>
+</div>
+
+<!-- Leaderboard table -->
+<div class="card" style="padding:0; overflow:hidden;">
+  <table id="lb-table">
+    <thead>
+      <tr>
+        <th>#</th>
+        <th>Member</th>
+        <th>Type</th>
+        <th style="text-align:right">Capital</th>
+        <th style="text-align:right">Holdings Value</th>
+        <th style="text-align:right">Total Value</th>
+        <th style="text-align:right">P&amp;L</th>
+        <th style="text-align:center">Buys</th>
+        <th style="text-align:center">Sells</th>
+        <th style="text-align:center">Securities</th>
+        <th style="text-align:center">Obligation</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for row in leaderboard %}
+      <tr data-member="{{ row.member_id }}">
+        <td style="color:var(--muted)">{{ row.rank }}</td>
+        <td><strong>{{ row.member_id }}</strong></td>
+        <td>
+          {% if row.is_human %}
+            <span class="badge-human">Human</span>
+          {% else %}
+            <span class="badge-ai">AI</span>
+          {% endif %}
+        </td>
+        <td style="text-align:right">€{{ "{:,.2f}".format(row.capital) }}</td>
+        <td style="text-align:right">€{{ "{:,.2f}".format(row.holdings_value) }}</td>
+        <td style="text-align:right"><strong>€{{ "{:,.2f}".format(row.total_value) }}</strong></td>
+        <td style="text-align:right" class="{{ 'positive' if row.pnl >= 0 else 'negative' }}">
+          {{ '+' if row.pnl >= 0 else '' }}€{{ "{:,.2f}".format(row.pnl) }}
+        </td>
+        <td style="text-align:center">{{ row.buy_count }}</td>
+        <td style="text-align:center">{{ row.sell_count }}</td>
+        <td style="text-align:center">{{ row.total_securities }}</td>
+        <td style="text-align:center">
+          {% if row.obligation_met %}
+            <span class="badge-ok">✓ Met ({{ obligation }})</span>
+          {% else %}
+            <span class="badge-bad">{{ row.total_securities }}/{{ obligation }}</span>
+          {% endif %}
+        </td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</div>
+
+<p style="color:var(--muted); font-size:11px; margin-top:8px;">
+  Daily obligation: each member must trade at least {{ obligation }} securities.
+  Holdings value is calculated at current market mid-price.
+  Refreshes every 10 seconds.
+</p>
+{% endblock %}
+
+{% block extra_scripts %}
+// Auto-refresh leaderboard every 10 seconds
+let refreshTimer = setInterval(refreshLeaderboard, 10000);
+
+async function refreshLeaderboard() {
+  try {
+    const resp = await fetch('/ch/api/leaderboard');
+    if (!resp.ok) return;
+    const rows = await resp.json();
+    const tbody = document.querySelector('#lb-table tbody');
+    tbody.innerHTML = '';
+    rows.forEach(row => {
+      const pnlClass = row.pnl >= 0 ? 'positive' : 'negative';
+      const pnlSign  = row.pnl >= 0 ? '+' : '';
+      const oblBadge = row.obligation_met
+        ? `<span class="badge-ok">✓ Met ({{ obligation }})</span>`
+        : `<span class="badge-bad">${row.total_securities}/{{ obligation }}</span>`;
+      const typeBadge = row.is_human
+        ? `<span class="badge-human">Human</span>`
+        : `<span class="badge-ai">AI</span>`;
+      tbody.innerHTML += `
+        <tr data-member="${row.member_id}">
+          <td style="color:var(--muted)">${row.rank}</td>
+          <td><strong>${row.member_id}</strong></td>
+          <td>${typeBadge}</td>
+          <td style="text-align:right">€${fmt(row.capital)}</td>
+          <td style="text-align:right">€${fmt(row.holdings_value)}</td>
+          <td style="text-align:right"><strong>€${fmt(row.total_value)}</strong></td>
+          <td style="text-align:right" class="${pnlClass}">${pnlSign}€${fmt(row.pnl)}</td>
+          <td style="text-align:center">${row.buy_count}</td>
+          <td style="text-align:center">${row.sell_count}</td>
+          <td style="text-align:center">${row.total_securities}</td>
+          <td style="text-align:center">${oblBadge}</td>
+        </tr>`;
+    });
+    document.getElementById('last-update').textContent =
+      'Updated ' + new Date().toLocaleTimeString();
+  } catch(e) { /* ignore */ }
+}
+
+function fmt(n) {
+  return Number(n).toLocaleString('en-US', {minimumFractionDigits:2, maximumFractionDigits:2});
+}
+{% endblock %}

clearing_house/templates/login.html

@@ -0,0 +1,39 @@
+{% extends "base.html" %}
+{% block title %}Login — StockEx Clearing House{% endblock %}
+
+{% block content %}
+<div style="max-width:400px; margin:80px auto;">
+  <div class="card">
+    <h1 style="text-align:center; margin-bottom:24px; font-size:18px;">
+      Clearing House Login
+    </h1>
+
+    {% if error %}
+    <div class="flash flash-error">{{ error }}</div>
+    {% endif %}
+
+    <form action="/ch/login" method="post">
+      <div class="form-group">
+        <label>Member ID</label>
+        <select name="member_id" required>
+          <option value="">Select member…</option>
+          {% for m in members %}
+          <option value="{{ m }}">{{ m }}</option>
+          {% endfor %}
+        </select>
+      </div>
+      <div class="form-group">
+        <label>Password</label>
+        <input type="password" name="password" placeholder="Same as your member ID" required autocomplete="current-password">
+      </div>
+      <button type="submit" class="btn btn-primary" style="width:100%; margin-top:8px;">
+        Login
+      </button>
+    </form>
+
+    <p style="margin-top:20px; color:var(--muted); text-align:center; font-size:12px;">
+      Password = your member ID &nbsp;·&nbsp; e.g. USR01 / USR01
+    </p>
+  </div>
+</div>
+{% endblock %}

clearing_house/templates/portfolio.html

@@ -0,0 +1,238 @@
+{% extends "base.html" %}
+{% block title %}{{ member }} Portfolio — StockEx Clearing House{% endblock %}
+
+{% block content %}
+<!-- Header -->
+<div style="display:flex; align-items:center; justify-content:space-between; margin-bottom:20px;">
+  <h1 style="margin:0;">{{ member }} — Portfolio</h1>
+  <div style="display:flex; gap:12px; align-items:center;">
+    <span style="color:var(--muted); font-size:12px;">
+      Obligation:
+      <strong class="{{ 'positive' if daily.total_securities >= obligation else 'negative' }}">
+        {{ daily.total_securities }}/{{ obligation }}
+      </strong> securities
+    </span>
+  </div>
+</div>
+
+<!-- Stats -->
+<div class="grid-3" style="margin-bottom:20px;">
+  <div class="card stat">
+    <div class="val">€{{ "{:,.2f}".format(capital) }}</div>
+    <div class="lbl">Available Cash</div>
+  </div>
+  <div class="card stat">
+    <div class="val">€{{ "{:,.2f}".format(total_value) }}</div>
+    <div class="lbl">Total Portfolio Value</div>
+  </div>
+  <div class="card stat">
+    <div class="val {{ 'positive' if total_pnl >= 0 else 'negative' }}">
+      {{ '+' if total_pnl >= 0 else '' }}€{{ "{:,.2f}".format(total_pnl) }}
+    </div>
+    <div class="lbl">Total P&amp;L</div>
+  </div>
+</div>
+
+<div class="grid-2">
+  <!-- Holdings -->
+  <div>
+    <div class="card" style="padding:0; overflow:hidden;">
+      <div style="padding:16px 20px 12px; border-bottom:1px solid var(--border);">
+        <h2 style="margin:0;">Holdings</h2>
+      </div>
+      {% if holdings %}
+      <table>
+        <thead>
+          <tr>
+            <th>Symbol</th>
+            <th style="text-align:right">Qty</th>
+            <th style="text-align:right">Avg Cost</th>
+            <th style="text-align:right">Price</th>
+            <th style="text-align:right">Value</th>
+            <th style="text-align:right">P&amp;L</th>
+          </tr>
+        </thead>
+        <tbody>
+          {% for h in holdings %}
+          <tr>
+            <td><strong>{{ h.symbol }}</strong></td>
+            <td style="text-align:right">{{ h.quantity }}</td>
+            <td style="text-align:right">€{{ "%.2f"|format(h.avg_cost) }}</td>
+            <td style="text-align:right">€{{ "%.2f"|format(h.current_price) }}</td>
+            <td style="text-align:right">€{{ "{:,.2f}".format(h.value) }}</td>
+            <td style="text-align:right" class="{{ 'positive' if h.unrealized_pnl >= 0 else 'negative' }}">
+              {{ '+' if h.unrealized_pnl >= 0 else '' }}€{{ "%.2f"|format(h.unrealized_pnl) }}
+            </td>
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+      {% else %}
+      <p style="padding:20px; color:var(--muted); text-align:center;">No holdings</p>
+      {% endif %}
+    </div>
+
+    <!-- Settlement history -->
+    {% if settlements %}
+    <div class="card" style="padding:0; overflow:hidden; margin-top:20px;">
+      <div style="padding:16px 20px 12px; border-bottom:1px solid var(--border);">
+        <h2 style="margin:0;">Settlement History</h2>
+      </div>
+      <table>
+        <thead>
+          <tr>
+            <th>Date</th>
+            <th style="text-align:right">Closing Capital</th>
+            <th style="text-align:right">Unrealized P&amp;L</th>
+            <th style="text-align:center">Obligation</th>
+          </tr>
+        </thead>
+        <tbody>
+          {% for s in settlements %}
+          <tr>
+            <td>{{ s.trading_date }}</td>
+            <td style="text-align:right">€{{ "{:,.2f}".format(s.closing_capital) }}</td>
+            <td style="text-align:right" class="{{ 'positive' if s.unrealized_pnl >= 0 else 'negative' }}">
+              {{ '+' if s.unrealized_pnl >= 0 else '' }}€{{ "%.2f"|format(s.unrealized_pnl) }}
+            </td>
+            <td style="text-align:center">
+              {% if s.obligation_met %}
+                <span class="badge-ok">Met</span>
+              {% else %}
+                <span class="badge-bad">Not met</span>
+              {% endif %}
+            </td>
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+    </div>
+    {% endif %}
+  </div>
+
+  <!-- Right column: Order entry + Trade history -->
+  <div>
+    <!-- Order entry -->
+    <div class="card">
+      <h2>Submit Order</h2>
+      <div id="order-msg" style="display:none;" class="flash"></div>
+      <form id="order-form">
+        <div class="form-group">
+          <label>Symbol</label>
+          <select name="symbol" id="symbol" required>
+            {% for s in symbols %}
+            <option value="{{ s }}">{{ s }}</option>
+            {% endfor %}
+          </select>
+        </div>
+        <div style="display:grid; grid-template-columns:1fr 1fr; gap:12px;">
+          <div class="form-group">
+            <label>Side</label>
+            <select name="side" id="side" required>
+              <option value="BUY">BUY</option>
+              <option value="SELL">SELL</option>
+            </select>
+          </div>
+          <div class="form-group">
+            <label>Quantity</label>
+            <input type="number" name="quantity" id="quantity" min="1" value="100" required>
+          </div>
+        </div>
+        <div class="form-group">
+          <label>Limit Price (€)</label>
+          <input type="number" name="price" id="price" min="0.01" step="0.05" value="" required>
+        </div>
+        <button type="submit" class="btn btn-primary" style="width:100%;">Submit Order</button>
+      </form>
+    </div>
+
+    <!-- Today's trades -->
+    <div class="card" style="padding:0; overflow:hidden;">
+      <div style="padding:16px 20px 12px; border-bottom:1px solid var(--border);">
+        <h2 style="margin:0;">Today's Trades</h2>
+      </div>
+      {% if trades %}
+      <table id="trades-table">
+        <thead>
+          <tr>
+            <th>Time</th>
+            <th>Symbol</th>
+            <th style="text-align:center">Side</th>
+            <th style="text-align:right">Qty</th>
+            <th style="text-align:right">Price</th>
+            <th style="text-align:right">Value</th>
+          </tr>
+        </thead>
+        <tbody>
+          {% for t in trades %}
+          <tr>
+            <td style="color:var(--muted); font-size:11px;">
+              {{ t.timestamp | ts }}
+            </td>
+            <td><strong>{{ t.symbol }}</strong></td>
+            <td style="text-align:center">
+              <span class="{{ 'positive' if t.side == 'BUY' else 'negative' }}">{{ t.side }}</span>
+            </td>
+            <td style="text-align:right">{{ t.quantity }}</td>
+            <td style="text-align:right">€{{ "%.2f"|format(t.price) }}</td>
+            <td style="text-align:right">€{{ "{:,.2f}".format(t.quantity * t.price) }}</td>
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+      {% else %}
+      <p style="padding:20px; color:var(--muted); text-align:center;">No trades today</p>
+      {% endif %}
+    </div>
+  </div>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+// Order form submission
+document.getElementById('order-form').addEventListener('submit', async function(e) {
+  e.preventDefault();
+  const msg = document.getElementById('order-msg');
+  const data = {
+    symbol:   document.getElementById('symbol').value,
+    side:     document.getElementById('side').value,
+    quantity: parseInt(document.getElementById('quantity').value),
+    price:    parseFloat(document.getElementById('price').value),
+  };
+  try {
+    const resp = await fetch('/ch/order', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify(data),
+    });
+    const result = await resp.json();
+    msg.style.display = 'block';
+    if (resp.ok) {
+      msg.className = 'flash';
+      msg.style.background = 'rgba(63,185,80,.12)';
+      msg.style.border = '1px solid var(--green)';
+      msg.style.color = 'var(--green)';
+      msg.textContent = `Order submitted: ${data.side} ${data.quantity} ${data.symbol} @ €${data.price}`;
+      setTimeout(() => location.reload(), 1500);
+    } else {
+      msg.className = 'flash flash-error';
+      msg.textContent = result.error || 'Order failed';
+    }
+  } catch(err) {
+    msg.style.display = 'block';
+    msg.className = 'flash flash-error';
+    msg.textContent = 'Network error';
+  }
+});
+
+// Auto-refresh portfolio every 15 seconds
+setInterval(async () => {
+  try {
+    const resp = await fetch('/ch/api/portfolio');
+    if (!resp.ok) return;
+    const d = await resp.json();
+    // Just reload the page for simplicity
+    // (A production app would do a DOM patch)
+  } catch(e) {}
+}, 15000);
+{% endblock %}

dashboard/dashboard.py

@@ -570,6 +570,14 @@ def _do_session_end():
     session_state["suspended"] = False
     broadcast_event("session", {"status": "ended", "time": time.time()})
 
+    # Notify Clearing House for EOD settlement
+    try:
+        ch_url = os.getenv("CH_SERVICE_URL", "http://localhost:5004")
+        requests.post(f"{ch_url}/ch/eod", timeout=10)
+        print("[Dashboard] CH EOD settlement triggered")
+    except Exception as e:
+        print(f"[Dashboard] CH EOD hook failed (non-critical): {e}")
+
 
 def schedule_runner():
     """Background thread: auto start/end session based on market_schedule.txt."""

docker-compose.yml

@@ -181,6 +181,36 @@ services:
       - FRONTEND_URL=http://localhost:5000
       - HF_TOKEN=${HF_TOKEN:-}
       - HF_MODEL=${HF_MODEL:-Qwen/Qwen2.5-7B-Instruct}
+      - CH_SERVICE_URL=http://clearing_house:5004
+
+  clearing_house:
+    build:
+      context: .
+      dockerfile: clearing_house/Dockerfile
+    container_name: clearing_house
+    ports:
+      - "5004:5004"
+    volumes:
+      - ./shared:/app/shared
+      - ./shared_data:/app/shared_data   # securities.txt read-only
+      - ch_data:/app/data                # clearing_house.db persistence
+    depends_on:
+      - kafka
+      - matcher
+    environment:
+      - KAFKA_BOOTSTRAP=kafka:9092
+      - MATCHER_URL=http://matcher:6000
+      - SECURITIES_FILE=/app/shared_data/securities.txt
+      - CH_DB_PATH=/app/data/clearing_house.db
+      - CH_PORT=5004
+      - HF_TOKEN=${HF_TOKEN:-}
+      - HF_MODEL=${HF_MODEL:-Qwen/Qwen2.5-7B-Instruct}
+      - GROQ_API_KEY=${GROQ_API_KEY:-}
+      - GROQ_MODEL=${GROQ_MODEL:-llama-3.1-8b-instant}
+      - OLLAMA_HOST=${OLLAMA_HOST:-}
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
 
 volumes:
   matcher_data:  # Persists SQLite database across container restarts
+  ch_data:       # Persists Clearing House SQLite DB and securities file

entrypoint.sh

@@ -73,6 +73,12 @@ echo "[startup] Starting Frontend on port 5003..."
 PORT=$FRONTEND_PORT TEMPLATE_FOLDER=/app/frontend_templates python3 /app/frontend.py &
 sleep 2
 
+echo "[startup] Starting Clearing House on port 5004..."
+CH_PORT=5004 CH_SERVICE_URL=http://localhost:5004 \
+  MATCHER_URL=http://localhost:6000 \
+  PYTHONPATH=/app python3 /app/clearing_house/app.py &
+sleep 3
+
 # ── nginx (reverse proxy: port 7860 → dashboard:5000 + fix-ui:5002 + frontend:5003) ──
 echo "[startup] Starting nginx on port 7860..."
 nginx

nginx.conf

@@ -44,6 +44,24 @@ http {
             proxy_redirect     / /fix/;
         }
 
+        # Clearing House SSE stream – disable buffering
+        location /ch/stream {
+            proxy_pass         http://127.0.0.1:5004/ch/stream;
+            proxy_set_header   Host $host;
+            proxy_buffering    off;
+            proxy_cache        off;
+            proxy_read_timeout 3600s;
+            chunked_transfer_encoding on;
+        }
+
+        # Clearing House portal
+        location /ch/ {
+            proxy_pass         http://127.0.0.1:5004/ch/;
+            proxy_set_header   Host $host;
+            proxy_set_header   X-Real-IP $remote_addr;
+            proxy_buffering    off;
+        }
+
         # Dashboard – everything else
         location / {
             proxy_pass         http://127.0.0.1:5000;

shared/config.py

@@ -35,3 +35,10 @@ class Config:
     # Trading simulation
     TICK_SIZE: float = float(os.getenv("TICK_SIZE", "0.05"))
     ORDERS_PER_MIN: int = int(os.getenv("ORDERS_PER_MIN", "8"))
+
+    # Clearing House
+    CH_DB_PATH: str = os.getenv("CH_DB_PATH", "/app/data/clearing_house.db")
+    CH_MEMBERS: list = [f"USR{i:02d}" for i in range(1, 11)]
+    CH_STARTING_CAPITAL: float = 100_000.0
+    CH_DAILY_OBLIGATION: int = 10
+    CH_SERVICE_URL: str = os.getenv("CH_SERVICE_URL", "http://localhost:5004")