init: adaptive-model — handler, gateway, mcp-server, training

.env.example

@@ -0,0 +1,15 @@
+# Copy to .env and fill in real values — never commit .env
+
+# Hugging Face Inference Endpoint URL (found in HF Spaces / Endpoints dashboard)
+HF_ENDPOINT_URL=https://api-inference.huggingface.co/models/your-org/your-model
+
+# HF access token (read or write depending on endpoint privacy setting)
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
+
+# Base model ID on the Hub (used by hf-endpoint/handler.py during container build)
+BASE_MODEL=Qwen/Qwen2.5-7B-Instruct
+
+# Adapter repo IDs on the Hub (one per mode)
+ADAPTER_SUPPORT=your-org/adapter-support
+ADAPTER_ANALYTICS=your-org/adapter-analytics
+ADAPTER_FORM=your-org/adapter-form

.gitignore

@@ -0,0 +1,11 @@
+.env
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+data/*.jsonl

README.md

@@ -0,0 +1,155 @@
+# adaptive-model
+
+Multi-adapter language model with two chat surfaces:
+
+| Surface | Mechanism | UI |
+|---------|-----------|-----|
+| **Path A** — Custom GPT Action | OpenAPI schema → `/generate` | Markdown fallback |
+| **Path B** — MCP Apps | MCP tool → `structuredContent` | Real interactive iframe widget |
+
+Both surfaces share the same Hugging Face model backend and heuristic adapter router.
+
+---
+
+## Architecture
+
+```
+Chat turn
+    │
+    ▼
+lib/router.py  ──  heuristic or explicit mode
+    │
+    ▼
+HF Inference Endpoint  (handler.py)
+    │  base model + 3 LoRA adapters (support / analytics / form)
+    │  emits:  <ui>{json}</ui>  then prose
+    │
+    ├─── Path A ── gateway/app.py (FastAPI)
+    │              renders ui_spec → markdown
+    │              served via openapi-schema.yaml  →  Custom GPT Action
+    │
+    └─── Path B ── mcp-server/server.py (FastMCP)
+                   returns structuredContent
+                   widget/adaptive.html renders in iframe
+```
+
+---
+
+## Quick start
+
+```bash
+cp .env.example .env
+# fill in HF_ENDPOINT_URL, HF_TOKEN, adapter repo IDs
+```
+
+### Path A — Custom GPT gateway
+
+```bash
+pip install -r gateway/requirements.txt
+python -m gateway.app          # runs on :8000
+```
+
+Paste `gateway/openapi-schema.yaml` into your GPT's Actions editor.
+Set the server URL to your deployed gateway (ngrok / Railway / Fly.io).
+
+### Path B — MCP server
+
+```bash
+pip install -r mcp-server/requirements.txt
+
+# stdio (local MCP client, e.g. Claude Desktop)
+python mcp-server/server.py
+
+# SSE (remote clients, e.g. ChatGPT plugin host)
+python mcp-server/server.py --http      # listens on :3100
+```
+
+Add to your MCP client config:
+```json
+{
+  "mcpServers": {
+    "adaptive-model": {
+      "command": "python",
+      "args": ["mcp-server/server.py"]
+    }
+  }
+}
+```
+
+---
+
+## Hugging Face endpoint
+
+1. Push `hf-endpoint/handler.py` to your model repo on the Hub.
+2. Create an **Inference Endpoint** pointing at that repo.
+   - Hardware: minimum A10G (24 GB) for a 7B base + 3 LoRA adapters in bf16.
+   - Set env vars: `BASE_MODEL`, `ADAPTER_SUPPORT`, `ADAPTER_ANALYTICS`, `ADAPTER_FORM`.
+3. Copy the endpoint URL into `.env` as `HF_ENDPOINT_URL`.
+
+---
+
+## Adapter training
+
+Adapters must be fine-tuned to emit `<ui>{...}</ui>` followed by prose.
+Generate synthetic seed data to bootstrap each adapter:
+
+```bash
+pip install -r hf-endpoint/requirements.txt
+
+python training/generate_examples.py --all --n 200 -o data/
+# writes data/support.jsonl  data/analytics.jsonl  data/form.jsonl
+```
+
+Then fine-tune with your preferred PEFT trainer (TRL `SFTTrainer` works well):
+
+```python
+from trl import SFTTrainer, SFTConfig
+from peft import LoraConfig
+
+lora_cfg = LoraConfig(r=16, lora_alpha=32, target_modules=["q_proj","v_proj"])
+trainer  = SFTTrainer(
+    model=base_model,
+    args=SFTConfig(output_dir="./adapter-support", num_train_epochs=3),
+    train_dataset=support_dataset,
+    peft_config=lora_cfg,
+)
+trainer.train()
+trainer.push_to_hub("your-org/adapter-support")
+```
+
+---
+
+## ui_spec contract
+
+The model emits one of these component shapes:
+
+```jsonc
+// form
+{"component":"form","props":{"title":"...","fields":[{"name":"x","label":"X","type":"text","required":true}],"submitLabel":"Send"}}
+
+// chart
+{"component":"chart","props":{"title":"...","type":"bar","data":{"labels":["Jan","Feb"],"datasets":[{"label":"Revenue","data":[400,600]}]}}}
+
+// card
+{"component":"card","props":{"title":"...","body":"...","items":[{"label":"Status","value":"OK"}]}}
+
+// table
+{"component":"table","props":{"columns":["Name","Value"],"rows":[["Alpha",1],["Beta",2]]}}
+```
+
+The widget renders any of these interactively.
+Path A degrades each to markdown via `lib/markdown_renderer.py`.
+
+---
+
+## Routing
+
+The heuristic router (`lib/router.py`) scores keywords in the last user turn:
+
+| Adapter | Triggers |
+|---------|---------|
+| `support` | error, help, issue, bug, broken, fix … |
+| `analytics` | chart, graph, trend, metric, dashboard … |
+| `form` | form, fill, submit, register, sign up … |
+
+Pass `mode` explicitly to override. Default is `support`.

gateway/app.py

@@ -0,0 +1,104 @@
+"""
+FastAPI gateway — Custom GPT Action surface (Path A).
+
+Receives messages from the GPT Action, routes to the right adapter,
+calls the HF Inference Endpoint, and returns both raw ui_spec and a
+markdown fallback so the GPT can render something useful inline.
+"""
+import os
+import sys
+from pathlib import Path
+
+import httpx
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+load_dotenv()
+
+# Allow shared lib to be imported when running from repo root or this dir
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from lib.router import route
+from lib.markdown_renderer import render
+
+HF_ENDPOINT_URL = os.getenv("HF_ENDPOINT_URL", "")
+HF_TOKEN        = os.getenv("HF_TOKEN", "")
+
+app = FastAPI(
+    title="Adaptive Model Gateway",
+    version="1.0.0",
+    description="Routes chat turns to the right LoRA adapter and returns adaptive UI specs.",
+)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://chat.openai.com", "https://chatgpt.com"],
+    allow_methods=["POST", "GET"],
+    allow_headers=["*"],
+)
+
+
+# ── request / response models ─────────────────────────────────────────────────
+
+class Message(BaseModel):
+    role: str
+    content: str
+
+
+class GenerateRequest(BaseModel):
+    messages: list[Message]
+    mode: str | None = None     # explicit override; omit for heuristic routing
+
+
+class GenerateResponse(BaseModel):
+    text: str
+    ui_spec: dict | None = None
+    ui_markdown: str | None = None  # markdown fallback for Custom GPT rendering
+    adapter: str
+
+
+# ── endpoints ─────────────────────────────────────────────────────────────────
+
+@app.post("/generate", response_model=GenerateResponse)
+async def generate(req: GenerateRequest) -> GenerateResponse:
+    if not HF_ENDPOINT_URL:
+        raise HTTPException(500, "HF_ENDPOINT_URL not set — check .env")
+
+    messages  = [m.model_dump() for m in req.messages]
+    adapter   = route(messages, req.mode)
+
+    headers = {"Content-Type": "application/json"}
+    if HF_TOKEN:
+        headers["Authorization"] = f"Bearer {HF_TOKEN}"
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        resp = await client.post(
+            HF_ENDPOINT_URL,
+            json={"inputs": {"messages": messages, "mode": adapter}},
+            headers=headers,
+        )
+
+    if resp.status_code != 200:
+        raise HTTPException(resp.status_code, f"HF endpoint error: {resp.text[:400]}")
+
+    data    = resp.json()
+    ui_spec = data.get("ui_spec")
+
+    return GenerateResponse(
+        text=data.get("text", ""),
+        ui_spec=ui_spec,
+        ui_markdown=render(ui_spec),
+        adapter=data.get("adapter", adapter),
+    )
+
+
+@app.get("/health")
+async def health() -> dict:
+    return {"status": "ok", "endpoint_configured": bool(HF_ENDPOINT_URL)}
+
+
+# ── dev entry-point ───────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("gateway.app:app", host="0.0.0.0", port=8000, reload=True)

gateway/openapi-schema.yaml

@@ -0,0 +1,111 @@
+openapi: 3.1.0
+info:
+  title: Adaptive Model Gateway
+  description: >
+    Routes chat turns to a multi-adapter language model on Hugging Face and returns
+    a structured UI spec alongside the text response. Paste this into the ChatGPT
+    Action editor and set the server URL to your deployed gateway.
+  version: 1.0.0
+
+servers:
+  - url: https://your-gateway.example.com   # replace with your deployed URL
+
+paths:
+  /generate:
+    post:
+      operationId: generate
+      summary: Run the adaptive model for the current conversation turn.
+      description: >
+        Sends the full conversation history to the model. The model selects
+        the appropriate LoRA adapter (support / analytics / form) and returns
+        a prose response plus an optional ui_spec for richer rendering.
+        In the Custom GPT Action context the ui_markdown field is a markdown
+        fallback the model can include directly in its reply.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - messages
+              properties:
+                messages:
+                  type: array
+                  description: Full conversation history, oldest first.
+                  items:
+                    type: object
+                    required:
+                      - role
+                      - content
+                    properties:
+                      role:
+                        type: string
+                        enum: [user, assistant, system]
+                      content:
+                        type: string
+                mode:
+                  type: string
+                  enum: [support, analytics, form]
+                  description: >
+                    Optional explicit adapter override.
+                    Omit to let the gateway choose via heuristic routing.
+      responses:
+        "200":
+          description: Successful generation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  text:
+                    type: string
+                    description: Plain-text model response.
+                  ui_spec:
+                    type: object
+                    nullable: true
+                    description: >
+                      Structured component specification emitted by the model.
+                      null when the turn needs no interactive UI.
+                    properties:
+                      component:
+                        type: string
+                        enum: [form, chart, card, table]
+                      props:
+                        type: object
+                        additionalProperties: true
+                  ui_markdown:
+                    type: string
+                    nullable: true
+                    description: >
+                      Markdown rendering of ui_spec for use in plain-text chat.
+                      Include this verbatim in your reply when ui_spec is present.
+                  adapter:
+                    type: string
+                    description: Which adapter handled this turn.
+        "500":
+          description: Gateway or upstream model error
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  detail:
+                    type: string
+
+  /health:
+    get:
+      operationId: health
+      summary: Health check
+      responses:
+        "200":
+          description: Gateway is running
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                  endpoint_configured:
+                    type: boolean

gateway/requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.112.0
+uvicorn[standard]>=0.30.0
+httpx>=0.27.0
+pydantic>=2.8.0
+python-dotenv>=1.0.0

handler.py

@@ -0,0 +1,88 @@
+"""
+Hugging Face Inference Endpoint custom handler.
+
+Loads a base model with multiple LoRA adapters (one per mode).
+Adapters stay resident in memory; set_adapter() switches cheaply per request.
+The model is trained to emit  <ui>{...json...}</ui>  then prose.
+"""
+import json
+import os
+import re
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+BASE_MODEL = os.getenv("BASE_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+
+# Override via env vars to point at your own adapter repos on the Hub
+ADAPTERS: dict[str, str] = {
+    "support":   os.getenv("ADAPTER_SUPPORT",   "your-org/adapter-support"),
+    "analytics": os.getenv("ADAPTER_ANALYTICS", "your-org/adapter-analytics"),
+    "form":      os.getenv("ADAPTER_FORM",       "your-org/adapter-form"),
+}
+
+_UI_RE = re.compile(r"<ui>(.*?)</ui>", re.DOTALL)
+
+
+class EndpointHandler:
+    def __init__(self, path: str = ""):
+        self.tok = AutoTokenizer.from_pretrained(BASE_MODEL)
+
+        base = AutoModelForCausalLM.from_pretrained(
+            BASE_MODEL,
+            torch_dtype=torch.bfloat16,
+            device_map="auto",
+        )
+
+        names = list(ADAPTERS.keys())
+        # First adapter via from_pretrained so PEFT wraps the model
+        self.model = PeftModel.from_pretrained(
+            base, ADAPTERS[names[0]], adapter_name=names[0]
+        )
+        # Remaining adapters attached in-place
+        for name in names[1:]:
+            self.model.load_adapter(ADAPTERS[name], adapter_name=name)
+
+        self.model.eval()
+
+    def __call__(self, data: dict) -> dict:
+        inp      = data.get("inputs", {})
+        messages = inp.get("messages", [])
+        mode     = inp.get("mode", "support")
+
+        if mode not in ADAPTERS:
+            mode = "support"
+
+        self.model.set_adapter(mode)
+
+        prompt = self.tok.apply_chat_template(
+            messages, add_generation_prompt=True, tokenize=False
+        )
+        ids = self.tok(prompt, return_tensors="pt").to(self.model.device)
+
+        with torch.no_grad():
+            out = self.model.generate(
+                **ids,
+                max_new_tokens=512,
+                do_sample=False,
+            )
+
+        new_tokens = out[0][ids.input_ids.shape[1]:]
+        text = self.tok.decode(new_tokens, skip_special_tokens=True)
+
+        ui_spec, clean_text = _extract_ui_spec(text)
+
+        return {"text": clean_text, "ui_spec": ui_spec, "adapter": mode}
+
+
+def _extract_ui_spec(text: str) -> tuple[dict | None, str]:
+    m = _UI_RE.search(text)
+    if not m:
+        return None, text
+
+    try:
+        spec = json.loads(m.group(1).strip())
+    except json.JSONDecodeError:
+        return None, text
+
+    return spec, _UI_RE.sub("", text).strip()

lib/markdown_renderer.py

@@ -0,0 +1,111 @@
+"""
+Renders a ui_spec dict to GitHub-flavored markdown.
+
+Used by the Custom GPT Action path (Path A) where real interactive UI
+is not available. Interactive behaviour degrades to descriptive markdown.
+"""
+
+
+def render(spec: dict | None) -> str | None:
+    if not spec:
+        return None
+
+    component = spec.get("component", "")
+    props = spec.get("props", {})
+
+    renderers = {
+        "form":  _form,
+        "chart": _chart,
+        "card":  _card,
+        "table": _table,
+    }
+    fn = renderers.get(component)
+    return fn(props) if fn else f"*[{component} — view in full UI for interactivity]*"
+
+
+# ── form ─────────────────────────────────────────────────────────────────────
+
+def _form(props: dict) -> str:
+    lines: list[str] = []
+
+    title = props.get("title")
+    if title:
+        lines.append(f"**{title}**\n")
+
+    for f in props.get("fields", []):
+        label    = f.get("label") or f.get("name", "")
+        ftype    = f.get("type", "text")
+        required = " *(required)*" if f.get("required") else ""
+        hint     = f" — {f['hint']}" if f.get("hint") else ""
+        lines.append(f"- **{label}** `{ftype}`{required}{hint}")
+
+    submit = props.get("submitLabel", "Submit")
+    lines.append(f"\n> *(Use the full UI widget to fill and submit — **{submit}**)*")
+    return "\n".join(lines)
+
+
+# ── chart ─────────────────────────────────────────────────────────────────────
+
+def _chart(props: dict) -> str:
+    title      = props.get("title", "Chart")
+    chart_type = props.get("type", "")
+    lines      = [f"**{title}** *(interactive {chart_type} chart in full UI)*\n"]
+
+    data     = props.get("data", {})
+    labels   = data.get("labels", [])
+    datasets = data.get("datasets", [])
+
+    if labels and datasets:
+        header = "| Label | " + " | ".join(ds.get("label", "Value") for ds in datasets) + " |"
+        sep    = "|---|" + "---|" * len(datasets)
+        lines += [header, sep]
+        for i, lbl in enumerate(labels):
+            cells = [str(ds.get("data", [])[i]) if i < len(ds.get("data", [])) else "" for ds in datasets]
+            lines.append(f"| {lbl} | " + " | ".join(cells) + " |")
+
+    return "\n".join(lines)
+
+
+# ── card ──────────────────────────────────────────────────────────────────────
+
+def _card(props: dict) -> str:
+    lines: list[str] = []
+
+    if title := props.get("title"):
+        lines.append(f"### {title}")
+    if body := props.get("body"):
+        lines.append(body)
+
+    for item in props.get("items", []):
+        if isinstance(item, dict):
+            key = item.get("label") or item.get("key", "")
+            lines.append(f"- **{key}**: {item.get('value', '')}")
+        else:
+            lines.append(f"- {item}")
+
+    return "\n".join(lines)
+
+
+# ── table ─────────────────────────────────────────────────────────────────────
+
+def _table(props: dict) -> str:
+    columns = props.get("columns", [])
+    rows    = props.get("rows", [])
+
+    if not columns:
+        return "*[empty table]*"
+
+    header = "| " + " | ".join(columns) + " |"
+    sep    = "|" + "---|" * len(columns)
+    lines  = [header, sep]
+
+    for row in rows:
+        if isinstance(row, dict):
+            cells = [str(row.get(col, "")) for col in columns]
+        elif isinstance(row, list):
+            cells = [str(c) for c in row]
+        else:
+            cells = [str(row)]
+        lines.append("| " + " | ".join(cells) + " |")
+
+    return "\n".join(lines)

lib/router.py

@@ -0,0 +1,59 @@
+"""
+Heuristic adapter router.
+
+Priority: explicit `mode` override → keyword match → default "support".
+Swap in model self-classification by uncommenting _model_classify below.
+"""
+from typing import Literal
+
+AdapterName = Literal["support", "analytics", "form"]
+
+_KEYWORDS: dict[str, list[str]] = {
+    "support": [
+        "error", "help", "issue", "problem", "broken", "fix",
+        "support", "bug", "crash", "fail", "wrong", "not working",
+    ],
+    "analytics": [
+        "chart", "graph", "data", "analytics", "trend", "report",
+        "metric", "dashboard", "stat", "plot", "visuali", "insight",
+    ],
+    "form": [
+        "form", "fill", "submit", "input", "register", "sign up",
+        "signup", "onboard", "enter your", "complete", "provide",
+    ],
+}
+
+_VALID: set[str] = set(_KEYWORDS.keys())
+
+
+def route(messages: list[dict], explicit_mode: str | None = None) -> AdapterName:
+    if explicit_mode and explicit_mode in _VALID:
+        return explicit_mode  # type: ignore[return-value]
+
+    text = _last_user_content(messages).lower()
+    if not text:
+        return "support"
+
+    scores: dict[str, int] = {k: 0 for k in _KEYWORDS}
+    for name, kws in _KEYWORDS.items():
+        for kw in kws:
+            if kw in text:
+                scores[name] += 1
+
+    best = max(scores, key=lambda k: scores[k])
+    return best if scores[best] > 0 else "support"  # type: ignore[return-value]
+
+    # Uncomment to replace keyword match with model self-classification:
+    # return _model_classify(messages)
+
+
+def _last_user_content(messages: list[dict]) -> str:
+    for msg in reversed(messages):
+        if msg.get("role") == "user":
+            return str(msg.get("content", ""))
+    return ""
+
+
+# def _model_classify(messages):
+#     """Classify using a lightweight model (e.g. a 0-shot instruct call)."""
+#     raise NotImplementedError

mcp-server/requirements.txt

@@ -0,0 +1,3 @@
+mcp[cli]>=1.3.0
+httpx>=0.27.0
+python-dotenv>=1.0.0

mcp-server/server.py

@@ -0,0 +1,106 @@
+"""
+MCP server — adaptive UI surface (Path B).
+
+Tools return structuredContent that the adaptive.html widget renders
+inline in MCP Apps-compatible hosts (ChatGPT, Claude, Goose, VS Code).
+
+Run:
+    python -m mcp_server.server          # stdio (local MCP client)
+    python mcp-server/server.py --http   # SSE on :3100 (remote clients)
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+import httpx
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+load_dotenv()
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from lib.router import route
+
+HF_ENDPOINT_URL = os.getenv("HF_ENDPOINT_URL", "")
+HF_TOKEN        = os.getenv("HF_TOKEN", "")
+WIDGET_PATH     = Path(__file__).parent / "widget" / "adaptive.html"
+
+mcp = FastMCP("adaptive-model", version="1.0.0")
+
+# ── widget resource ───────────────────────────────────────────────────────────
+# MCP Apps hosts load this URI into an iframe when the tool result carries
+# a _widget key in structuredContent.
+
+@mcp.resource("ui://widget/adaptive.html", mime_type="text/html")
+def adaptive_widget() -> str:
+    return WIDGET_PATH.read_text(encoding="utf-8")
+
+
+# ── tools ─────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def respond(messages: list[dict], mode: str = "auto") -> dict:
+    """
+    Run the adaptive model for the current conversation turn.
+
+    Args:
+        messages: Full conversation history, e.g.
+                  [{"role": "user", "content": "Show me revenue trends"}]
+        mode:     Adapter override — 'support' | 'analytics' | 'form' | 'auto'
+
+    Returns a dict with:
+        content         — text for the model to reason over
+        structuredContent — ui_spec for the widget to render interactively
+    """
+    resolved = route(messages, None if mode == "auto" else mode)
+
+    headers = {"Content-Type": "application/json"}
+    if HF_TOKEN:
+        headers["Authorization"] = f"Bearer {HF_TOKEN}"
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        r = await client.post(
+            HF_ENDPOINT_URL,
+            json={"inputs": {"messages": messages, "mode": resolved}},
+            headers=headers,
+        )
+    r.raise_for_status()
+    out = r.json()
+
+    text    = out.get("text", "")
+    ui_spec = out.get("ui_spec")
+
+    result: dict = {
+        "content": [{"type": "text", "text": text}],
+    }
+    if ui_spec:
+        # _widget tells MCP Apps hosts which resource URI to iframe
+        result["structuredContent"] = {**ui_spec, "_widget": "ui://widget/adaptive.html"}
+
+    return result
+
+
+@mcp.tool()
+async def classify_mode(messages: list[dict]) -> dict:
+    """
+    Return which adapter would handle this turn without running inference.
+    Useful for debugging routing decisions.
+    """
+    adapter = route(messages, None)
+    return {"adapter": adapter}
+
+
+# ── entry-point ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--http", action="store_true",
+                        help="Serve over SSE on port 3100 instead of stdio")
+    args = parser.parse_args()
+
+    if args.http:
+        mcp.run(transport="sse", host="0.0.0.0", port=3100)
+    else:
+        mcp.run(transport="stdio")

mcp-server/widget/adaptive.html

@@ -0,0 +1,323 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Adaptive UI Widget</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+  :root {
+    --bg:       #ffffff;
+    --surface:  #f8f9fa;
+    --border:   #e2e8f0;
+    --text:     #1a202c;
+    --muted:    #718096;
+    --accent:   #3b82f6;
+    --accent-h: #2563eb;
+    --danger:   #ef4444;
+    --success:  #22c55e;
+    --radius:   8px;
+    --shadow:   0 1px 3px rgba(0,0,0,.08), 0 1px 2px rgba(0,0,0,.06);
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg:      #1a202c;
+      --surface: #2d3748;
+      --border:  #4a5568;
+      --text:    #f7fafc;
+      --muted:   #a0aec0;
+    }
+  }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    font-size: 14px;
+    line-height: 1.5;
+    color: var(--text);
+    background: var(--bg);
+    padding: 16px;
+    min-height: 100vh;
+  }
+
+  /* ── generic ── */
+  .title    { font-size: 16px; font-weight: 600; margin-bottom: 12px; }
+  .muted    { color: var(--muted); font-size: 12px; }
+  .error    { color: var(--danger); padding: 12px; background: #fff5f5;
+              border: 1px solid #fed7d7; border-radius: var(--radius); }
+  .loading  { color: var(--muted); padding: 24px; text-align: center; }
+
+  /* ── form ── */
+  .form-field         { margin-bottom: 14px; }
+  .form-field label   { display: block; font-weight: 500; margin-bottom: 4px; }
+  .form-field .hint   { color: var(--muted); font-size: 12px; margin-bottom: 4px; }
+  .form-field input,
+  .form-field select,
+  .form-field textarea {
+    width: 100%; padding: 8px 10px;
+    border: 1px solid var(--border); border-radius: var(--radius);
+    background: var(--surface); color: var(--text);
+    font-size: 14px; outline: none; transition: border-color .15s;
+  }
+  .form-field input:focus,
+  .form-field select:focus,
+  .form-field textarea:focus { border-color: var(--accent); }
+  .form-field .required-mark { color: var(--danger); margin-left: 2px; }
+  .btn {
+    display: inline-flex; align-items: center; gap: 6px;
+    padding: 8px 18px; border: none; border-radius: var(--radius);
+    background: var(--accent); color: #fff; font-size: 14px;
+    font-weight: 500; cursor: pointer; transition: background .15s;
+  }
+  .btn:hover   { background: var(--accent-h); }
+  .btn:disabled{ opacity: .5; cursor: not-allowed; }
+  .form-status { margin-top: 10px; font-size: 13px; }
+  .form-status.ok  { color: var(--success); }
+  .form-status.err { color: var(--danger); }
+
+  /* ── card ── */
+  .card {
+    background: var(--surface); border: 1px solid var(--border);
+    border-radius: var(--radius); box-shadow: var(--shadow); padding: 16px;
+  }
+  .card-item { display: flex; justify-content: space-between;
+               padding: 6px 0; border-bottom: 1px solid var(--border); }
+  .card-item:last-child { border-bottom: none; }
+  .card-item .key   { color: var(--muted); }
+  .card-item .value { font-weight: 500; }
+
+  /* ── table ── */
+  table { width: 100%; border-collapse: collapse; }
+  th    { background: var(--surface); font-weight: 600; text-align: left;
+          padding: 8px 10px; border-bottom: 2px solid var(--border); }
+  td    { padding: 7px 10px; border-bottom: 1px solid var(--border); }
+  tr:last-child td { border-bottom: none; }
+  tr:hover td { background: var(--surface); }
+
+  /* ── chart (SVG bar) ── */
+  .chart-wrap { overflow-x: auto; }
+  .chart-bars { display: flex; align-items: flex-end; gap: 8px;
+                height: 160px; padding-bottom: 24px; }
+  .bar-col    { display: flex; flex-direction: column; align-items: center;
+                gap: 4px; flex: 1; min-width: 28px; }
+  .bar-fill   { width: 100%; background: var(--accent); border-radius: 4px 4px 0 0;
+                transition: height .3s ease; cursor: pointer; }
+  .bar-fill:hover { background: var(--accent-h); }
+  .bar-label  { font-size: 10px; color: var(--muted); text-align: center;
+                white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+                max-width: 56px; }
+  .bar-val    { font-size: 10px; color: var(--muted); }
+</style>
+</head>
+<body>
+
+<div id="root"><p class="loading">Loading…</p></div>
+
+<script>
+// ── bridge: try MCP Apps / OpenAI Apps SDK, fall back to postMessage ──────────
+
+async function getSpec() {
+  // Path 1: OpenAI MCP Apps bridge
+  if (window.openai?.ready) {
+    return new Promise(resolve => {
+      window.openai.ready(async api => {
+        const state = await api.state.get();
+        resolve(state?.structuredContent ?? null);
+        api.state.onChanged(s => render(s?.structuredContent ?? null));
+      });
+    });
+  }
+
+  // Path 2: postMessage from host (generic MCP clients)
+  return new Promise(resolve => {
+    let resolved = false;
+    window.addEventListener("message", ev => {
+      const d = ev.data;
+      if (d?.type === "mcp:structuredContent") {
+        if (!resolved) { resolved = true; resolve(d.payload); }
+        else render(d.payload);
+      }
+    });
+    // Signal readiness so host knows to send data
+    window.parent?.postMessage({ type: "mcp:ready" }, "*");
+    // Resolve null after 4s if nothing arrives (show helpful empty state)
+    setTimeout(() => { if (!resolved) { resolved = true; resolve(null); } }, 4000);
+  });
+}
+
+// ── renderers ─────────────────────────────────────────────────────────────────
+
+function render(spec) {
+  const root = document.getElementById("root");
+  if (!spec) { root.innerHTML = `<p class="muted">No UI data received.</p>`; return; }
+
+  const { component, props = {}, _widget, ...rest } = spec;
+  const effectiveProps = Object.keys(props).length ? props : rest;
+
+  try {
+    const map = { form: renderForm, chart: renderChart, card: renderCard, table: renderTable };
+    const fn  = map[component];
+    root.innerHTML = fn ? fn(effectiveProps) : `<p class="muted">[${component}]</p>`;
+    if (component === "form") attachFormHandlers(effectiveProps);
+    if (component === "chart") drawBars(effectiveProps);
+  } catch (e) {
+    root.innerHTML = `<p class="error">Render error: ${e.message}</p>`;
+  }
+}
+
+// ── form ──────────────────────────────────────────────────────────────────────
+
+function renderForm(p) {
+  const fields = (p.fields || []).map(f => {
+    const req  = f.required ? `<span class="required-mark">*</span>` : "";
+    const hint = f.hint     ? `<p class="hint">${esc(f.hint)}</p>`    : "";
+    const ctrl = buildInput(f);
+    return `<div class="form-field">
+      <label for="f_${esc(f.name)}">${esc(f.label || f.name)}${req}</label>
+      ${hint}${ctrl}
+    </div>`;
+  }).join("");
+
+  return `
+    ${p.title ? `<p class="title">${esc(p.title)}</p>` : ""}
+    <form id="adaptiveForm">
+      ${fields}
+      <button type="submit" class="btn" id="submitBtn">
+        ${esc(p.submitLabel || "Submit")}
+      </button>
+      <div class="form-status" id="formStatus"></div>
+    </form>`;
+}
+
+function buildInput(f) {
+  const id   = `f_${esc(f.name)}`;
+  const base = `id="${id}" name="${esc(f.name)}" ${f.required ? "required" : ""}`;
+  if (f.type === "select") {
+    const opts = (f.options || []).map(o =>
+      `<option value="${esc(o.value ?? o)}">${esc(o.label ?? o)}</option>`).join("");
+    return `<select ${base}>${opts}</select>`;
+  }
+  if (f.type === "textarea") {
+    return `<textarea ${base} rows="3"></textarea>`;
+  }
+  return `<input type="${esc(f.type || "text")}" ${base}
+          placeholder="${esc(f.placeholder || "")}" value="${esc(f.default || "")}">`;
+}
+
+function attachFormHandlers(p) {
+  document.getElementById("adaptiveForm")?.addEventListener("submit", async ev => {
+    ev.preventDefault();
+    const btn    = document.getElementById("submitBtn");
+    const status = document.getElementById("formStatus");
+    btn.disabled = true;
+    status.textContent = "";
+
+    const fd   = new FormData(ev.target);
+    const data = Object.fromEntries(fd.entries());
+
+    try {
+      if (window.openai?.callTool) {
+        await window.openai.callTool("form_submit", { data, formId: p.formId });
+      } else {
+        window.parent?.postMessage({ type: "mcp:toolCall",
+          tool: "form_submit", args: { data, formId: p.formId } }, "*");
+      }
+      status.className    = "form-status ok";
+      status.textContent  = p.successMessage || "Submitted successfully.";
+    } catch (e) {
+      status.className    = "form-status err";
+      status.textContent  = `Error: ${e.message}`;
+    } finally {
+      btn.disabled = false;
+    }
+  });
+}
+
+// ── chart ─────────────────────────────────────────────────────────────────────
+
+function renderChart(p) {
+  return `
+    ${p.title ? `<p class="title">${esc(p.title)}</p>` : ""}
+    <div class="chart-wrap">
+      <div class="chart-bars" id="chartBars"></div>
+    </div>`;
+}
+
+function drawBars(p) {
+  const data   = p.data   || {};
+  const labels = data.labels   || p.labels   || [];
+  const ds     = data.datasets || p.datasets || [];
+  const values = ds[0]?.data || data.values || [];
+  const max    = Math.max(...values, 1);
+  const bars   = document.getElementById("chartBars");
+  if (!bars) return;
+
+  bars.innerHTML = labels.map((lbl, i) => {
+    const v   = values[i] ?? 0;
+    const pct = Math.round((v / max) * 140);
+    return `<div class="bar-col">
+      <span class="bar-val">${v}</span>
+      <div class="bar-fill" style="height:${pct}px" title="${esc(String(lbl))}: ${v}"></div>
+      <span class="bar-label">${esc(String(lbl))}</span>
+    </div>`;
+  }).join("");
+}
+
+// ── card ──────────────────────────────────────────────────────────────────────
+
+function renderCard(p) {
+  const items = (p.items || []).map(it => {
+    if (typeof it === "object") {
+      const k = it.label ?? it.key ?? "";
+      return `<div class="card-item">
+        <span class="key">${esc(k)}</span>
+        <span class="value">${esc(String(it.value ?? ""))}</span>
+      </div>`;
+    }
+    return `<div class="card-item"><span>${esc(String(it))}</span></div>`;
+  }).join("");
+
+  return `<div class="card">
+    ${p.title ? `<p class="title">${esc(p.title)}</p>` : ""}
+    ${p.body  ? `<p style="margin-bottom:10px">${esc(p.body)}</p>` : ""}
+    ${items}
+  </div>`;
+}
+
+// ── table ─────────────────────────────────────────────────────────────────────
+
+function renderTable(p) {
+  const cols = p.columns || [];
+  const rows = p.rows    || [];
+  const hdr  = cols.map(c => `<th>${esc(c)}</th>`).join("");
+  const body = rows.map(row => {
+    const cells = Array.isArray(row)
+      ? row.map(c => `<td>${esc(String(c))}</td>`).join("")
+      : cols.map(c => `<td>${esc(String(row[c] ?? ""))}</td>`).join("");
+    return `<tr>${cells}</tr>`;
+  }).join("");
+
+  return `
+    ${p.title ? `<p class="title">${esc(p.title)}</p>` : ""}
+    <div style="overflow-x:auto">
+      <table><thead><tr>${hdr}</tr></thead><tbody>${body}</tbody></table>
+    </div>`;
+}
+
+// ── utils ─────────────────────────────────────────────────────────────────────
+
+function esc(s) {
+  return String(s ?? "").replace(/&/g,"&amp;").replace(/</g,"&lt;")
+                         .replace(/>/g,"&gt;").replace(/"/g,"&quot;");
+}
+
+// ── boot ──────────────────────────────────────────────────────────────────────
+
+getSpec().then(render).catch(e => {
+  document.getElementById("root").innerHTML =
+    `<p class="error">Bridge error: ${e.message}</p>`;
+});
+</script>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,4 @@
+transformers>=4.44.0
+peft>=0.12.0
+torch>=2.3.0
+accelerate>=0.33.0

training/generate_examples.py

@@ -0,0 +1,164 @@
+"""
+Generates synthetic fine-tuning examples in the <ui>…</ui> format.
+
+Each adapter needs examples where the assistant emits a valid ui_spec
+wrapped in <ui>…</ui> tags followed by a prose explanation.
+
+Usage:
+    python training/generate_examples.py --mode support   --n 50 -o data/support.jsonl
+    python training/generate_examples.py --mode analytics --n 50 -o data/analytics.jsonl
+    python training/generate_examples.py --mode form      --n 50 -o data/form.jsonl
+    python training/generate_examples.py --all -o data/
+"""
+import argparse
+import json
+import random
+from pathlib import Path
+from typing import Callable
+
+# ── support examples ──────────────────────────────────────────────────────────
+
+_SUPPORT_ISSUES = [
+    ("login fails with 401", "Authentication error — token may be expired."),
+    ("page not loading", "Possible network timeout or server error."),
+    ("export button missing", "Feature may be behind a permission flag."),
+    ("data not syncing", "Background sync may be paused or failing silently."),
+    ("slow performance", "Cache may be stale — clearing it often helps."),
+]
+
+def _support_example() -> dict:
+    issue, summary = random.choice(_SUPPORT_ISSUES)
+    steps = ["Check console for error codes", "Clear cache and retry",
+             "Verify account permissions", "Contact support with error ID"]
+    spec = {
+        "component": "card",
+        "props": {
+            "title": f"Troubleshooting: {issue}",
+            "body": summary,
+            "items": [{"label": f"Step {i+1}", "value": s} for i, s in enumerate(steps)],
+        },
+    }
+    user    = f"I have an issue: {issue}"
+    assist  = f"<ui>{json.dumps(spec)}</ui>\n\n{summary} Here are the recommended steps."
+    return {"messages": [{"role": "user", "content": user},
+                         {"role": "assistant", "content": assist}]}
+
+
+# ── analytics examples ────────────────────────────────────────────────────────
+
+_METRICS = ["revenue", "active users", "churn rate", "conversion", "page views"]
+_PERIODS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
+
+def _analytics_example() -> dict:
+    metric  = random.choice(_METRICS)
+    values  = [random.randint(100, 900) for _ in _PERIODS]
+    spec = {
+        "component": "chart",
+        "props": {
+            "title": f"{metric.title()} — Last 6 Months",
+            "type": "bar",
+            "data": {
+                "labels": _PERIODS,
+                "datasets": [{"label": metric.title(), "data": values}],
+            },
+        },
+    }
+    user    = f"Show me {metric} trends over the last 6 months"
+    insight = f"Peak was {_PERIODS[values.index(max(values))]} at {max(values)}."
+    assist  = f"<ui>{json.dumps(spec)}</ui>\n\n{insight}"
+    return {"messages": [{"role": "user", "content": user},
+                         {"role": "assistant", "content": assist}]}
+
+
+# ── form examples ─────────────────────────────────────────────────────────────
+
+_FORMS = [
+    {
+        "title": "Contact Support",
+        "submitLabel": "Send Request",
+        "fields": [
+            {"name": "name",    "label": "Full Name",  "type": "text",  "required": True},
+            {"name": "email",   "label": "Email",      "type": "email", "required": True},
+            {"name": "subject", "label": "Subject",    "type": "text"},
+            {"name": "message", "label": "Message",    "type": "textarea", "required": True},
+        ],
+    },
+    {
+        "title": "Account Registration",
+        "submitLabel": "Create Account",
+        "fields": [
+            {"name": "username", "label": "Username",  "type": "text",     "required": True},
+            {"name": "email",    "label": "Email",     "type": "email",    "required": True},
+            {"name": "password", "label": "Password",  "type": "password", "required": True},
+            {"name": "plan",     "label": "Plan",      "type": "select",
+             "options": ["Free", "Pro", "Enterprise"]},
+        ],
+    },
+    {
+        "title": "Export Data",
+        "submitLabel": "Export",
+        "fields": [
+            {"name": "format",    "label": "Format", "type": "select",
+             "options": ["CSV", "JSON", "Excel"]},
+            {"name": "date_from", "label": "From",   "type": "date", "required": True},
+            {"name": "date_to",   "label": "To",     "type": "date", "required": True},
+        ],
+    },
+]
+
+def _form_example() -> dict:
+    form_def = random.choice(_FORMS)
+    spec = {"component": "form", "props": form_def}
+    user   = f"I need to {form_def['submitLabel'].lower()}"
+    assist = (f"<ui>{json.dumps(spec)}</ui>\n\n"
+              f"Please fill in the {form_def['title']} form below.")
+    return {"messages": [{"role": "user", "content": user},
+                         {"role": "assistant", "content": assist}]}
+
+
+# ── generator dispatch ────────────────────────────────────────────────────────
+
+_GENERATORS: dict[str, Callable[[], dict]] = {
+    "support":   _support_example,
+    "analytics": _analytics_example,
+    "form":      _form_example,
+}
+
+
+def generate(mode: str, n: int) -> list[dict]:
+    fn = _GENERATORS[mode]
+    return [fn() for _ in range(n)]
+
+
+def write_jsonl(examples: list[dict], path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        for ex in examples:
+            f.write(json.dumps(ex, ensure_ascii=False) + "\n")
+    print(f"Wrote {len(examples)} examples → {path}")
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="Generate synthetic adapter training data")
+    p.add_argument("--mode", choices=list(_GENERATORS.keys()),
+                   help="Adapter mode to generate for")
+    p.add_argument("--all",  action="store_true",
+                   help="Generate for all modes (saves to <output>/<mode>.jsonl)")
+    p.add_argument("--n",    type=int, default=50, help="Examples per mode")
+    p.add_argument("-o",     "--output", default="data", help="Output path or directory")
+    args = p.parse_args()
+
+    modes = list(_GENERATORS.keys()) if args.all else ([args.mode] if args.mode else [])
+    if not modes:
+        p.error("Specify --mode or --all")
+
+    out = Path(args.output)
+    for mode in modes:
+        dest = (out / f"{mode}.jsonl") if args.all or out.suffix != ".jsonl" else out
+        write_jsonl(generate(mode, args.n), dest)
+
+
+if __name__ == "__main__":
+    main()

training/requirements.txt

@@ -0,0 +1,8 @@
+torch>=2.3.0
+transformers>=4.44.0
+peft>=0.12.0
+trl>=0.11.0
+bitsandbytes>=0.43.0
+accelerate>=0.33.0
+datasets>=2.20.0
+huggingface-hub>=0.24.0

training/train_adapter.py

@@ -0,0 +1,262 @@
+"""
+Train one LoRA adapter per mode and push to Hugging Face Hub.
+
+Each adapter teaches the base model to emit  <ui>{json}</ui>  then prose
+for its mode, so the handler in hf-endpoint/handler.py can parse it.
+
+GPU requirements
+----------------
+QLoRA (default, --no-qlora not set):  ~8 GB VRAM  (RTX 3080 / T4 / L4)
+bf16 full precision (--no-qlora):     ~24 GB VRAM  (A10G / A100)
+
+Colab/Kaggle tip: use the free T4 with QLoRA for quick experiments.
+
+Usage
+-----
+    # Login first
+    huggingface-cli login
+
+    # Train one mode (generates data automatically)
+    python training/train_adapter.py --mode support --hub-org your-org
+
+    # Train all three modes back-to-back
+    python training/train_adapter.py --all --hub-org your-org
+
+    # Use your own JSONL instead of the synthetic generator
+    python training/train_adapter.py --mode form --data data/form.jsonl --hub-org your-org
+
+    # Smoke-test with tiny run (no push)
+    python training/train_adapter.py --mode support --hub-org your-org --n 20 --epochs 1 --dry-run
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+import torch
+from datasets import Dataset
+from peft import LoraConfig, TaskType
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+from trl import SFTConfig, SFTTrainer
+
+# Allow running from repo root or training/
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from training.generate_examples import _GENERATORS, generate
+
+# ── constants ─────────────────────────────────────────────────────────────────
+
+DEFAULT_BASE = os.getenv("BASE_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+
+# Covers Qwen2.5, Llama-3.x, Mistral-0.3.
+# For Phi-3/3.5 replace with ["qkv_proj", "o_proj", "gate_up_proj", "down_proj"].
+LORA_TARGETS = [
+    "q_proj", "k_proj", "v_proj", "o_proj",
+    "gate_proj", "up_proj", "down_proj",
+]
+
+
+# ── data helpers ──────────────────────────────────────────────────────────────
+
+def load_examples(mode: str, n: int, jsonl_path: Optional[str]) -> list[dict]:
+    if jsonl_path:
+        p = Path(jsonl_path)
+        if not p.exists():
+            raise FileNotFoundError(f"JSONL not found: {p}")
+        rows = [json.loads(l) for l in p.read_text(encoding="utf-8").splitlines() if l.strip()]
+        print(f"  Loaded {len(rows)} examples from {p}")
+        return rows
+
+    rows = generate(mode, n)
+    print(f"  Generated {len(rows)} synthetic examples for '{mode}'")
+    return rows
+
+
+def build_dataset(examples: list[dict], tokenizer) -> tuple[Dataset, Dataset]:
+    texts = [
+        tokenizer.apply_chat_template(
+            ex["messages"], tokenize=False, add_generation_prompt=False
+        )
+        for ex in examples
+    ]
+    full = Dataset.from_dict({"text": texts})
+    split = full.train_test_split(test_size=0.1, seed=42)
+    return split["train"], split["test"]
+
+
+# ── model helpers ─────────────────────────────────────────────────────────────
+
+def load_base_model(base: str, use_qlora: bool) -> AutoModelForCausalLM:
+    bnb_cfg = None
+    if use_qlora:
+        bnb_cfg = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16,
+            bnb_4bit_use_double_quant=True,
+        )
+
+    model = AutoModelForCausalLM.from_pretrained(
+        base,
+        quantization_config=bnb_cfg,
+        torch_dtype=torch.bfloat16 if not use_qlora else None,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+    model.config.use_cache = False
+    return model
+
+
+def lora_config() -> LoraConfig:
+    return LoraConfig(
+        r=16,
+        lora_alpha=32,
+        lora_dropout=0.05,
+        target_modules=LORA_TARGETS,
+        task_type=TaskType.CAUSAL_LM,
+        bias="none",
+    )
+
+
+# ── training ──────────────────────────────────────────────────────────────────
+
+def train_one(
+    mode: str,
+    base_model: str,
+    hub_org: str,
+    n_examples: int,
+    epochs: int,
+    jsonl_path: Optional[str],
+    output_root: Path,
+    use_qlora: bool,
+    dry_run: bool,
+) -> None:
+    print(f"\n{'='*60}")
+    print(f"  Adapter: {mode}")
+    print(f"  Base:    {base_model}")
+    print(f"  QLoRA:   {use_qlora}")
+    print(f"{'='*60}")
+
+    tokenizer = AutoTokenizer.from_pretrained(base_model, trust_remote_code=True)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+    tokenizer.padding_side = "right"   # prevents warning with flash-attn
+
+    examples       = load_examples(mode, n_examples, jsonl_path)
+    train_ds, eval_ds = build_dataset(examples, tokenizer)
+    print(f"  Train: {len(train_ds)}  Eval: {len(eval_ds)}")
+
+    if dry_run:
+        print("  [dry-run] skipping model load, training, and push")
+        sample = train_ds[0]["text"][:200]
+        print(f"  Sample text:\n  {sample!r}…\n")
+        return
+
+    model    = load_base_model(base_model, use_qlora)
+    out_dir  = output_root / f"adapter-{mode}"
+
+    sft_cfg = SFTConfig(
+        output_dir=str(out_dir),
+        num_train_epochs=epochs,
+        per_device_train_batch_size=2,
+        gradient_accumulation_steps=4,     # effective batch size 8
+        gradient_checkpointing=True,       # saves ~30 % VRAM
+        learning_rate=2e-4,
+        warmup_ratio=0.05,
+        lr_scheduler_type="cosine",
+        bf16=not use_qlora,
+        fp16=False,
+        logging_steps=10,
+        eval_strategy="epoch",
+        save_strategy="epoch",
+        load_best_model_at_end=True,
+        metric_for_best_model="eval_loss",
+        max_seq_length=1024,
+        dataset_text_field="text",
+        packing=True,                      # packs short examples → less padding waste
+        report_to="none",
+    )
+
+    trainer = SFTTrainer(
+        model=model,
+        args=sft_cfg,
+        train_dataset=train_ds,
+        eval_dataset=eval_ds,
+        peft_config=lora_config(),
+        processing_class=tokenizer,
+    )
+
+    print(f"\n  Training {mode} adapter…")
+    trainer.train()
+
+    trainer.save_model(str(out_dir))
+    tokenizer.save_pretrained(str(out_dir))
+    print(f"  Saved locally → {out_dir}")
+
+    hub_repo = f"{hub_org}/adapter-{mode}"
+    print(f"  Pushing → https://huggingface.co/{hub_repo}")
+    trainer.push_to_hub(hub_repo, commit_message=f"train: {mode} adapter epoch {epochs}")
+    tokenizer.push_to_hub(hub_repo)
+    print(f"  Done: https://huggingface.co/{hub_repo}")
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    p = argparse.ArgumentParser(
+        description="Train LoRA adapters for adaptive-model and push to HF Hub",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--mode", choices=list(_GENERATORS.keys()),
+                   help="Single adapter mode to train")
+    p.add_argument("--all", dest="train_all", action="store_true",
+                   help="Train all modes sequentially")
+    p.add_argument("--hub-org", required=True,
+                   help="HF Hub org or username (e.g. your-org)")
+    p.add_argument("--base-model", default=DEFAULT_BASE,
+                   help=f"Base model ID on HF Hub (default: {DEFAULT_BASE})")
+    p.add_argument("--n", type=int, default=200,
+                   help="Synthetic examples to generate per mode (default: 200)")
+    p.add_argument("--epochs", type=int, default=3,
+                   help="Training epochs per adapter (default: 3)")
+    p.add_argument("--data", metavar="JSONL",
+                   help="Path to existing JSONL — skips generation (single --mode only)")
+    p.add_argument("--output-dir", default="./trained-adapters",
+                   help="Local root for saved adapter checkpoints")
+    p.add_argument("--no-qlora", action="store_true",
+                   help="Disable 4-bit QLoRA — needs 24 GB+ VRAM")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Parse args and show dataset stats without training or pushing")
+    args = p.parse_args()
+
+    modes: list[str] = list(_GENERATORS.keys()) if args.train_all else \
+                       ([args.mode] if args.mode else [])
+    if not modes:
+        p.error("Specify --mode <name> or --all")
+    if args.data and len(modes) > 1:
+        p.error("--data can only be combined with a single --mode")
+
+    output_root = Path(args.output_dir)
+
+    for mode in modes:
+        train_one(
+            mode=mode,
+            base_model=args.base_model,
+            hub_org=args.hub_org,
+            n_examples=args.n,
+            epochs=args.epochs,
+            jsonl_path=args.data if len(modes) == 1 else None,
+            output_root=output_root,
+            use_qlora=not args.no_qlora,
+            dry_run=args.dry_run,
+        )
+
+    if not args.dry_run:
+        print("\nAll adapters pushed. Add these to your .env:")
+        for mode in modes:
+            print(f"  ADAPTER_{mode.upper()}={args.hub_org}/adapter-{mode}")
+
+
+if __name__ == "__main__":
+    main()