Add CH trader fine-tuning notebook and update default model

- notebooks/ch_trader_finetune.ipynb: QLoRA fine-tunes Qwen2.5-7B-Instruct
on 2500 synthetic clearing house trading scenarios (Colab A100-ready)
- Generates diverse examples: varied capital, holdings, obligation levels
- Trains with SFTTrainer + chat template formatting, merges and pushes
the model to RayMelius/stockex-ch-trader on HuggingFace Hub
- ch_ai_trader.py + docker-compose: default HF_MODEL updated to
RayMelius/stockex-ch-trader (override via HF_MODEL env var)

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

clearing_house/ch_ai_trader.py

@@ -35,7 +35,7 @@ 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", "RayMelius/stockex-analyst")
+HF_MODEL     = os.getenv("HF_MODEL", "RayMelius/stockex-ch-trader")
 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"

docker-compose.yml

@@ -204,7 +204,7 @@ services:
       - CH_DB_PATH=/app/data/clearing_house.db
       - CH_PORT=5004
       - HF_TOKEN=${HF_TOKEN:-}
-      - HF_MODEL=${HF_MODEL:-RayMelius/stockex-analyst}
+      - HF_MODEL=${HF_MODEL:-RayMelius/stockex-ch-trader}
       - GROQ_API_KEY=${GROQ_API_KEY:-}
       - GROQ_MODEL=${GROQ_MODEL:-llama-3.1-8b-instant}
       - OLLAMA_HOST=${OLLAMA_HOST:-}

notebooks/ch_trader_finetune.ipynb

@@ -0,0 +1,681 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  },
+  "accelerator": "GPU",
+  "colab": {
+   "gpuType": "A100",
+   "provenance": []
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# StockEx Clearing House — LLM Fine-Tuning\n",
+    "\n",
+    "Fine-tunes **Qwen/Qwen2.5-7B-Instruct** with QLoRA to act as a clearing house trading agent.\n",
+    "\n",
+    "Given a member's capital, holdings, and live market BBO, the model outputs a valid JSON trading decision.\n",
+    "\n",
+    "**Output model:** `RayMelius/stockex-ch-trader` on HuggingFace Hub\n",
+    "\n",
+    "---\n",
+    "**Runtime:** GPU → A100 recommended (fits on T4 with batch_size=1)\n",
+    "\n",
+    "**Required secret:** `HF_TOKEN` with write access to `RayMelius/`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "install",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Install dependencies ───────────────────────────────────────────────────────\n",
+    "!pip install -q \\\n",
+    "    transformers==4.46.3 \\\n",
+    "    peft==0.13.2 \\\n",
+    "    trl==0.12.1 \\\n",
+    "    datasets==3.1.0 \\\n",
+    "    accelerate==1.1.1 \\\n",
+    "    bitsandbytes==0.44.1 \\\n",
+    "    huggingface_hub"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os, json, random, torch\n",
+    "from datasets import Dataset\n",
+    "from transformers import (\n",
+    "    AutoTokenizer, AutoModelForCausalLM,\n",
+    "    BitsAndBytesConfig, TrainingArguments,\n",
+    ")\n",
+    "from peft import LoraConfig, get_peft_model, TaskType\n",
+    "from trl import SFTTrainer, SFTConfig\n",
+    "from huggingface_hub import login\n",
+    "\n",
+    "print(f\"CUDA available: {torch.cuda.is_available()}\")\n",
+    "if torch.cuda.is_available():\n",
+    "    print(f\"GPU: {torch.cuda.get_device_name(0)}\")\n",
+    "    print(f\"VRAM: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "config",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Configuration ─────────────────────────────────────────────────────────────\n",
+    "BASE_MODEL   = \"Qwen/Qwen2.5-7B-Instruct\"\n",
+    "OUTPUT_REPO  = \"RayMelius/stockex-ch-trader\"\n",
+    "OUTPUT_DIR   = \"./stockex-ch-trader\"\n",
+    "\n",
+    "# Lora\n",
+    "LORA_R       = 16\n",
+    "LORA_ALPHA   = 32\n",
+    "LORA_DROPOUT = 0.05\n",
+    "\n",
+    "# Training\n",
+    "NUM_EPOCHS   = 3\n",
+    "BATCH_SIZE   = 4        # reduce to 1 on T4\n",
+    "GRAD_ACCUM   = 4        # effective batch = BATCH_SIZE * GRAD_ACCUM\n",
+    "LR           = 2e-4\n",
+    "MAX_SEQ_LEN  = 512\n",
+    "DATASET_SIZE = 2500     # synthetic training examples\n",
+    "\n",
+    "# HuggingFace login\n",
+    "HF_TOKEN = os.getenv(\"HF_TOKEN\") or input(\"Enter your HF token: \")\n",
+    "login(token=HF_TOKEN)\n",
+    "print(\"Logged in to HuggingFace Hub\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dataset-header",
+   "metadata": {},
+   "source": [
+    "## 1. Synthetic Dataset Generation\n",
+    "\n",
+    "Each training example is a realistic clearing house trading scenario:\n",
+    "- Member state: capital, holdings, obligation remaining\n",
+    "- Market: BBO for each security\n",
+    "- Target: a valid JSON trading decision that respects all constraints"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dataset-gen",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Securities traded on StockEx\n",
+    "SECURITIES = [\n",
+    "    {\"symbol\": \"ALPHA\",  \"base\": 6.00},\n",
+    "    {\"symbol\": \"PEIR\",   \"base\": 8.20},\n",
+    "    {\"symbol\": \"EXAE\",   \"base\": 6.90},\n",
+    "    {\"symbol\": \"OPAP\",   \"base\": 14.50},\n",
+    "    {\"symbol\": \"MYTIL\",  \"base\": 9.80},\n",
+    "    {\"symbol\": \"ADMIE\",  \"base\": 2.45},\n",
+    "    {\"symbol\": \"ELPE\",   \"base\": 7.60},\n",
+    "    {\"symbol\": \"MOTOR\",  \"base\": 22.30},\n",
+    "    {\"symbol\": \"OTE\",    \"base\": 15.10},\n",
+    "    {\"symbol\": \"TPEIR\",  \"base\": 1.75},\n",
+    "]\n",
+    "\n",
+    "STARTING_CAPITAL = 100_000.0\n",
+    "DAILY_OBLIGATION = 10\n",
+    "\n",
+    "\n",
+    "def gen_bbo(base_price: float) -> dict:\n",
+    "    \"\"\"Generate a realistic bid/ask spread around a base price.\"\"\"\n",
+    "    drift    = random.uniform(-0.05, 0.05)\n",
+    "    mid      = round(base_price * (1 + drift), 2)\n",
+    "    spread   = round(random.choice([0.05, 0.10, 0.15]), 2)\n",
+    "    best_bid = round(mid - spread / 2, 2)\n",
+    "    best_ask = round(mid + spread / 2, 2)\n",
+    "    return {\"best_bid\": best_bid, \"best_ask\": best_ask, \"mid\": mid}\n",
+    "\n",
+    "\n",
+    "def gen_holdings(bbos: dict) -> list:\n",
+    "    \"\"\"Randomly generate some holdings for a member.\"\"\"\n",
+    "    holdings = []\n",
+    "    n = random.randint(0, 4)  # 0–4 positions\n",
+    "    for sym in random.sample(list(bbos.keys()), min(n, len(bbos))):\n",
+    "        qty = random.randint(50, 500)\n",
+    "        mid = bbos[sym][\"mid\"]\n",
+    "        avg_cost = round(mid * random.uniform(0.92, 1.08), 2)\n",
+    "        holdings.append({\"symbol\": sym, \"quantity\": qty, \"avg_cost\": avg_cost})\n",
+    "    return holdings\n",
+    "\n",
+    "\n",
+    "def build_prompt(member_id: str, capital: float, holdings: list,\n",
+    "                 obligation_remaining: int, bbos: dict) -> str:\n",
+    "    market_lines = [\n",
+    "        f\"  {sym}: Bid {bbo['best_bid']:.2f} / Ask {bbo['best_ask']:.2f}\"\n",
+    "        for sym, bbo in sorted(bbos.items())\n",
+    "    ]\n",
+    "    holding_lines = (\n",
+    "        [f\"  {h['symbol']}: {h['quantity']} shares @ avg cost {h['avg_cost']:.2f}\"\n",
+    "         for h in holdings]\n",
+    "        if holdings else [\"  None\"]\n",
+    "    )\n",
+    "    return (\n",
+    "        f\"You are simulating clearing house member {member_id} making ONE trading decision.\\n\\n\"\n",
+    "        f\"Member state:\\n\"\n",
+    "        f\"  Available capital: EUR {capital:,.2f}\\n\"\n",
+    "        f\"  Securities obligation remaining today: {obligation_remaining} more to trade\\n\"\n",
+    "        f\"  Current holdings:\\n\" + \"\\n\".join(holding_lines) + \"\\n\\n\"\n",
+    "        f\"Current market (Bid/Ask):\\n\" + \"\\n\".join(market_lines) + \"\\n\\n\"\n",
+    "        f\"Rules:\\n\"\n",
+    "        f\"- Do not spend more than your available capital\\n\"\n",
+    "        f\"- Do not sell more shares than you hold\\n\"\n",
+    "        f\"- If you have no holdings, you must BUY\\n\"\n",
+    "        f\"- Choose a realistic price close to the BBO mid-price\\n\"\n",
+    "        f\"- Quantity should be between 10 and 200\\n\\n\"\n",
+    "        f\"Respond ONLY with valid JSON, no other text:\\n\"\n",
+    "        f'Example: {{\"symbol\": \"ALPHA\", \"side\": \"BUY\", \"quantity\": 50, \"price\": 5.95}}'\n",
+    "    )\n",
+    "\n",
+    "\n",
+    "def gen_decision(capital: float, holdings: list, bbos: dict) -> dict:\n",
+    "    \"\"\"Generate a rule-valid trading decision for the given state.\"\"\"\n",
+    "    has_holdings = len(holdings) > 0\n",
+    "\n",
+    "    # Decide side: BUY if no holdings or randomly; SELL if heavy positions\n",
+    "    holdings_value = sum(\n",
+    "        h[\"quantity\"] * bbos.get(h[\"symbol\"], {}).get(\"mid\", h[\"avg_cost\"])\n",
+    "        for h in holdings\n",
+    "    )\n",
+    "    net_worth = capital + holdings_value\n",
+    "    holdings_ratio = holdings_value / net_worth if net_worth > 0 else 0\n",
+    "\n",
+    "    if not has_holdings:\n",
+    "        side = \"BUY\"\n",
+    "    elif holdings_ratio > 0.6:\n",
+    "        side = random.choices([\"SELL\", \"BUY\"], weights=[0.7, 0.3])[0]\n",
+    "    else:\n",
+    "        side = random.choices([\"BUY\", \"SELL\"], weights=[0.55, 0.45])[0]\n",
+    "\n",
+    "    if side == \"BUY\":\n",
+    "        # Pick a random affordable symbol\n",
+    "        affordable = [\n",
+    "            sym for sym, bbo in bbos.items()\n",
+    "            if 10 * bbo[\"best_ask\"] <= capital\n",
+    "        ]\n",
+    "        if not affordable:\n",
+    "            # Fall back to cheapest\n",
+    "            sym = min(bbos, key=lambda s: bbos[s][\"best_ask\"])\n",
+    "        else:\n",
+    "            # Weight toward securities we already hold (adding to position)\n",
+    "            held_syms = [h[\"symbol\"] for h in holdings]\n",
+    "            weights = [3 if s in held_syms else 1 for s in affordable]\n",
+    "            sym = random.choices(affordable, weights=weights)[0]\n",
+    "        ask = bbos[sym][\"best_ask\"]\n",
+    "        max_qty = min(200, int(capital / ask))\n",
+    "        qty = random.randint(10, max(10, max_qty))\n",
+    "        price = round(bbos[sym][\"mid\"] + random.uniform(-0.05, 0.05), 2)\n",
+    "        price = max(bbos[sym][\"best_bid\"], min(price, ask))\n",
+    "        return {\"symbol\": sym, \"side\": \"BUY\", \"quantity\": qty, \"price\": round(price, 2)}\n",
+    "    else:\n",
+    "        # Sell from existing holdings\n",
+    "        h = random.choice(holdings)\n",
+    "        sym = h[\"symbol\"]\n",
+    "        bbo = bbos[sym]\n",
+    "        qty = random.randint(10, min(200, h[\"quantity\"]))\n",
+    "        price = round(bbo[\"mid\"] + random.uniform(-0.05, 0.05), 2)\n",
+    "        price = max(bbo[\"best_bid\"] - 0.05, min(price, bbo[\"best_ask\"]))\n",
+    "        return {\"symbol\": sym, \"side\": \"SELL\", \"quantity\": qty, \"price\": round(price, 2)}\n",
+    "\n",
+    "\n",
+    "def generate_dataset(n: int) -> list:\n",
+    "    examples = []\n",
+    "    member_ids = [f\"USR{i:02d}\" for i in range(1, 11)]\n",
+    "\n",
+    "    scenarios = [\n",
+    "        # (capital_range, obligation_range, description)\n",
+    "        ((80_000, 100_000), (5, 10), \"fresh_member\"),     # new, must trade a lot\n",
+    "        ((50_000, 80_000),  (0, 5),  \"active_member\"),    # mid-session, nearly done\n",
+    "        ((20_000, 50_000),  (0, 2),  \"low_capital\"),      # low cash, mostly holdings\n",
+    "        ((5_000,  20_000),  (0, 10), \"very_low_capital\"), # near margin, careful\n",
+    "        ((90_000, 100_000), (10, 10),\"start_of_day\"),     # just started\n",
+    "    ]\n",
+    "\n",
+    "    for _ in range(n):\n",
+    "        cap_range, obl_range, _ = random.choice(scenarios)\n",
+    "        capital    = round(random.uniform(*cap_range), 2)\n",
+    "        obligation = random.randint(*obl_range)\n",
+    "        member_id  = random.choice(member_ids)\n",
+    "\n",
+    "        # Generate market state\n",
+    "        bbos = {s[\"symbol\"]: gen_bbo(s[\"base\"]) for s in SECURITIES}\n",
+    "\n",
+    "        # Generate holdings consistent with remaining capital\n",
+    "        holdings = gen_holdings(bbos)\n",
+    "\n",
+    "        # Ensure capital consistency: if holdings are expensive, reduce capital\n",
+    "        holdings_cost = sum(h[\"quantity\"] * h[\"avg_cost\"] for h in holdings)\n",
+    "        if holdings_cost > STARTING_CAPITAL - capital:\n",
+    "            # Scale down holdings to fit\n",
+    "            scale = (STARTING_CAPITAL - capital) / max(holdings_cost, 1)\n",
+    "            for h in holdings:\n",
+    "                h[\"quantity\"] = max(10, int(h[\"quantity\"] * scale))\n",
+    "\n",
+    "        prompt   = build_prompt(member_id, capital, holdings, obligation, bbos)\n",
+    "        decision = gen_decision(capital, holdings, bbos)\n",
+    "\n",
+    "        examples.append({\n",
+    "            \"prompt\": prompt,\n",
+    "            \"completion\": json.dumps(decision),\n",
+    "        })\n",
+    "\n",
+    "    return examples\n",
+    "\n",
+    "\n",
+    "print(f\"Generating {DATASET_SIZE} training examples...\")\n",
+    "raw_data = generate_dataset(DATASET_SIZE)\n",
+    "print(f\"Done. Example:\")\n",
+    "print(\"PROMPT:\\n\", raw_data[0][\"prompt\"])\n",
+    "print(\"\\nCOMPLETION:\", raw_data[0][\"completion\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dataset-split",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Train/val split (90/10)\n",
+    "random.shuffle(raw_data)\n",
+    "split = int(len(raw_data) * 0.9)\n",
+    "train_data = raw_data[:split]\n",
+    "val_data   = raw_data[split:]\n",
+    "\n",
+    "train_dataset = Dataset.from_list(train_data)\n",
+    "val_dataset   = Dataset.from_list(val_data)\n",
+    "print(f\"Train: {len(train_dataset)} | Val: {len(val_dataset)}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "model-header",
+   "metadata": {},
+   "source": [
+    "## 2. Load Base Model (4-bit QLoRA)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "load-tokenizer",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"Loading tokenizer: {BASE_MODEL}\")\n",
+    "tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)\n",
+    "tokenizer.pad_token    = tokenizer.eos_token\n",
+    "tokenizer.padding_side = \"right\"\n",
+    "print(\"Tokenizer loaded\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "format-dataset",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SYSTEM_PROMPT = (\n",
+    "    \"You are a StockEx clearing house trading agent. \"\n",
+    "    \"Given a member's financial state and live market data, \"\n",
+    "    \"you output a single valid JSON trading decision that respects all capital and holdings constraints. \"\n",
+    "    \"Never output anything other than the JSON object.\"\n",
+    ")\n",
+    "\n",
+    "\n",
+    "def format_chat(example):\n",
+    "    \"\"\"Apply the model's chat template to produce a training string.\"\"\"\n",
+    "    messages = [\n",
+    "        {\"role\": \"system\",    \"content\": SYSTEM_PROMPT},\n",
+    "        {\"role\": \"user\",      \"content\": example[\"prompt\"]},\n",
+    "        {\"role\": \"assistant\", \"content\": example[\"completion\"]},\n",
+    "    ]\n",
+    "    text = tokenizer.apply_chat_template(\n",
+    "        messages,\n",
+    "        tokenize=False,\n",
+    "        add_generation_prompt=False,\n",
+    "    )\n",
+    "    return {\"text\": text}\n",
+    "\n",
+    "\n",
+    "train_dataset = train_dataset.map(format_chat)\n",
+    "val_dataset   = val_dataset.map(format_chat)\n",
+    "\n",
+    "print(\"Sample formatted text:\")\n",
+    "print(train_dataset[0][\"text\"][:600], \"...\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "load-model",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 4-bit quantization config\n",
+    "bnb_config = BitsAndBytesConfig(\n",
+    "    load_in_4bit=True,\n",
+    "    bnb_4bit_quant_type=\"nf4\",\n",
+    "    bnb_4bit_compute_dtype=torch.bfloat16,\n",
+    "    bnb_4bit_use_double_quant=True,\n",
+    ")\n",
+    "\n",
+    "print(f\"Loading model: {BASE_MODEL} (4-bit)\")\n",
+    "model = AutoModelForCausalLM.from_pretrained(\n",
+    "    BASE_MODEL,\n",
+    "    quantization_config=bnb_config,\n",
+    "    device_map=\"auto\",\n",
+    "    trust_remote_code=True,\n",
+    "    torch_dtype=torch.bfloat16,\n",
+    ")\n",
+    "model.config.use_cache = False\n",
+    "model.config.pretraining_tp = 1\n",
+    "print(f\"Model loaded. Parameters: {model.num_parameters()/1e9:.2f}B\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "lora-header",
+   "metadata": {},
+   "source": [
+    "## 3. LoRA Configuration"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "lora-config",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "lora_config = LoraConfig(\n",
+    "    r=LORA_R,\n",
+    "    lora_alpha=LORA_ALPHA,\n",
+    "    target_modules=[\n",
+    "        \"q_proj\", \"k_proj\", \"v_proj\", \"o_proj\",\n",
+    "        \"gate_proj\", \"up_proj\", \"down_proj\",\n",
+    "    ],\n",
+    "    lora_dropout=LORA_DROPOUT,\n",
+    "    bias=\"none\",\n",
+    "    task_type=TaskType.CAUSAL_LM,\n",
+    ")\n",
+    "\n",
+    "trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)\n",
+    "total     = sum(p.numel() for p in model.parameters())\n",
+    "print(f\"Trainable parameters: {trainable/1e6:.1f}M / {total/1e6:.0f}M ({100*trainable/total:.2f}%)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "training-header",
+   "metadata": {},
+   "source": [
+    "## 4. Train"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "train",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sft_config = SFTConfig(\n",
+    "    output_dir=OUTPUT_DIR,\n",
+    "    num_train_epochs=NUM_EPOCHS,\n",
+    "    per_device_train_batch_size=BATCH_SIZE,\n",
+    "    per_device_eval_batch_size=BATCH_SIZE,\n",
+    "    gradient_accumulation_steps=GRAD_ACCUM,\n",
+    "    gradient_checkpointing=True,\n",
+    "    optim=\"paged_adamw_32bit\",\n",
+    "    learning_rate=LR,\n",
+    "    lr_scheduler_type=\"cosine\",\n",
+    "    warmup_ratio=0.05,\n",
+    "    max_seq_length=MAX_SEQ_LEN,\n",
+    "    fp16=not torch.cuda.is_bf16_supported(),\n",
+    "    bf16=torch.cuda.is_bf16_supported(),\n",
+    "    logging_steps=25,\n",
+    "    eval_strategy=\"steps\",\n",
+    "    eval_steps=100,\n",
+    "    save_strategy=\"steps\",\n",
+    "    save_steps=100,\n",
+    "    load_best_model_at_end=True,\n",
+    "    metric_for_best_model=\"eval_loss\",\n",
+    "    greater_is_better=False,\n",
+    "    report_to=\"none\",\n",
+    "    dataset_text_field=\"text\",\n",
+    "    packing=False,\n",
+    ")\n",
+    "\n",
+    "trainer = SFTTrainer(\n",
+    "    model=model,\n",
+    "    args=sft_config,\n",
+    "    train_dataset=train_dataset,\n",
+    "    eval_dataset=val_dataset,\n",
+    "    peft_config=lora_config,\n",
+    "    processing_class=tokenizer,\n",
+    ")\n",
+    "\n",
+    "print(\"Starting training...\")\n",
+    "trainer.train()\n",
+    "print(\"Training complete.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "save-header",
+   "metadata": {},
+   "source": [
+    "## 5. Save & Push to HuggingFace Hub\n",
+    "\n",
+    "Merges LoRA adapters into the base model weights and pushes the full model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "save-model",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from peft import PeftModel\n",
+    "\n",
+    "# Save best adapter checkpoint locally\n",
+    "trainer.model.save_pretrained(OUTPUT_DIR)\n",
+    "tokenizer.save_pretrained(OUTPUT_DIR)\n",
+    "print(f\"Adapter saved to {OUTPUT_DIR}\")\n",
+    "\n",
+    "# Reload base model in fp16 for merging (can't merge with 4-bit)\n",
+    "print(\"Reloading base model in fp16 for adapter merge...\")\n",
+    "del model\n",
+    "torch.cuda.empty_cache()\n",
+    "\n",
+    "base_model = AutoModelForCausalLM.from_pretrained(\n",
+    "    BASE_MODEL,\n",
+    "    torch_dtype=torch.float16,\n",
+    "    device_map=\"auto\",\n",
+    "    trust_remote_code=True,\n",
+    ")\n",
+    "merged_model = PeftModel.from_pretrained(base_model, OUTPUT_DIR)\n",
+    "merged_model = merged_model.merge_and_unload()\n",
+    "print(\"Adapters merged.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "push-hub",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"Pushing merged model to: {OUTPUT_REPO}\")\n",
+    "merged_model.push_to_hub(\n",
+    "    OUTPUT_REPO,\n",
+    "    token=HF_TOKEN,\n",
+    "    commit_message=\"StockEx CH Trader: QLoRA fine-tuned Qwen2.5-7B-Instruct\",\n",
+    ")\n",
+    "tokenizer.push_to_hub(\n",
+    "    OUTPUT_REPO,\n",
+    "    token=HF_TOKEN,\n",
+    "    commit_message=\"Tokenizer for StockEx CH Trader\",\n",
+    ")\n",
+    "print(f\"Model pushed to https://huggingface.co/{OUTPUT_REPO}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "test-header",
+   "metadata": {},
+   "source": [
+    "## 6. Inference Test\n",
+    "\n",
+    "Verify the model generates valid JSON trading decisions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "inference-test",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import re\n",
+    "from transformers import pipeline\n",
+    "\n",
+    "pipe = pipeline(\n",
+    "    \"text-generation\",\n",
+    "    model=merged_model,\n",
+    "    tokenizer=tokenizer,\n",
+    "    device_map=\"auto\",\n",
+    ")\n",
+    "\n",
+    "# Test scenarios\n",
+    "test_cases = [\n",
+    "    {\n",
+    "        \"desc\": \"New member, no holdings, must trade\",\n",
+    "        \"capital\": 100_000.0,\n",
+    "        \"holdings\": [],\n",
+    "        \"obligation\": 10,\n",
+    "    },\n",
+    "    {\n",
+    "        \"desc\": \"Experienced member with holdings, low obligation\",\n",
+    "        \"capital\": 65_000.0,\n",
+    "        \"holdings\": [\n",
+    "            {\"symbol\": \"ALPHA\", \"quantity\": 300, \"avg_cost\": 5.90},\n",
+    "            {\"symbol\": \"OPAP\",  \"quantity\": 150, \"avg_cost\": 14.20},\n",
+    "        ],\n",
+    "        \"obligation\": 2,\n",
+    "    },\n",
+    "    {\n",
+    "        \"desc\": \"Low capital, large holdings\",\n",
+    "        \"capital\": 8_000.0,\n",
+    "        \"holdings\": [\n",
+    "            {\"symbol\": \"PEIR\",  \"quantity\": 500, \"avg_cost\": 8.10},\n",
+    "            {\"symbol\": \"MYTIL\", \"quantity\": 200, \"avg_cost\": 9.50},\n",
+    "        ],\n",
+    "        \"obligation\": 5,\n",
+    "    },\n",
+    "]\n",
+    "\n",
+    "test_bbos = {s[\"symbol\"]: gen_bbo(s[\"base\"]) for s in SECURITIES}\n",
+    "\n",
+    "print(\"=\" * 70)\n",
+    "for tc in test_cases:\n",
+    "    print(f\"\\nSCENARIO: {tc['desc']}\")\n",
+    "    prompt = build_prompt(\n",
+    "        \"USR01\", tc[\"capital\"], tc[\"holdings\"], tc[\"obligation\"], test_bbos\n",
+    "    )\n",
+    "    messages = [\n",
+    "        {\"role\": \"system\",\"content\": SYSTEM_PROMPT},\n",
+    "        {\"role\": \"user\",  \"content\": prompt},\n",
+    "    ]\n",
+    "    output = pipe(\n",
+    "        messages,\n",
+    "        max_new_tokens=60,\n",
+    "        temperature=0.3,\n",
+    "        do_sample=True,\n",
+    "        pad_token_id=tokenizer.eos_token_id,\n",
+    "    )\n",
+    "    response = output[0][\"generated_text\"][-1][\"content\"].strip()\n",
+    "    print(f\"RESPONSE: {response}\")\n",
+    "\n",
+    "    # Validate JSON\n",
+    "    try:\n",
+    "        m = re.search(r\"\\{[^}]+\\}\", response)\n",
+    "        if m:\n",
+    "            d = json.loads(m.group())\n",
+    "            assert d[\"side\"] in (\"BUY\", \"SELL\")\n",
+    "            assert d[\"symbol\"] in [s[\"symbol\"] for s in SECURITIES]\n",
+    "            assert d[\"quantity\"] > 0\n",
+    "            assert d[\"price\"] > 0\n",
+    "            print(f\"✓ Valid JSON: {d}\")\n",
+    "        else:\n",
+    "            print(\"✗ No JSON found in response\")\n",
+    "    except Exception as e:\n",
+    "        print(f\"✗ Invalid: {e}\")\n",
+    "    print(\"-\" * 70)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "usage-header",
+   "metadata": {},
+   "source": [
+    "## 7. Activate in StockEx\n",
+    "\n",
+    "The clearing house already uses `RayMelius/stockex-ch-trader` as default.\n",
+    "\n",
+    "To switch to this model in a running StockEx instance:\n",
+    "\n",
+    "**HuggingFace Spaces** — add to secrets:\n",
+    "```\n",
+    "HF_MODEL = RayMelius/stockex-ch-trader\n",
+    "HF_TOKEN = <your token>\n",
+    "```\n",
+    "\n",
+    "**Docker Compose** — already set in `docker-compose.yml`:\n",
+    "```yaml\n",
+    "environment:\n",
+    "  - HF_MODEL=RayMelius/stockex-ch-trader\n",
+    "  - HF_TOKEN=<your token>\n",
+    "```\n",
+    "\n",
+    "To use a future CH-specific model later:\n",
+    "```\n",
+    "HF_MODEL = RayMelius/<new-ch-model>\n",
+    "```"
+   ]
+  }
+ ]
+}