Import LLMChats3 master as CCAI baseline

Co-authored-by: Cursor <cursoragent@cursor.com>

.env.example

@@ -0,0 +1,25 @@
+# HANA API (Neon BrainForge)
+HANA_BASE_URL=https://hana.neonaialpha.com
+HANA_USERNAME=guest
+HANA_PASSWORD=password
+# BrainForge/Security (4090-x1-3): OpenAI-compatible API key for direct vLLM (same as HF Space API_KEY in brainforge-webapp).
+# NOT used for HANA /auth/login — see NeonGeckoCom/brainforge-webapp docker_overlay/config/config.yaml
+HANA_KLATCHAT_PASSWORD=sk_klatchat2024
+# Direct vLLM host (default matches demo 4090-x1-3)
+# NEON_SECURITY_VLLM_BASE_URL=https://4090-x1-3.neonaiservices2.com/vllm0
+
+# Neon vLLM direct access
+VLLM_API_KEY=sk_n30nn30n
+
+# Comparison providers
+FIREWORKS_API_KEY=your-fireworks-api-key-here
+TOGETHER_API_KEY=your-together-api-key-here
+OPENAI_API_KEY=your-openai-api-key-here
+GEMINI_API_KEY=your-gemini-api-key-here
+
+# Orchestrator LLM (used to monitor conversation endings)
+# Defaults to gpt-4o-mini via OpenAI if OPENAI_API_KEY is set
+ORCHESTRATOR_MODEL=gpt-4o-mini
+
+# App
+CORS_ORIGINS=http://localhost:3000

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.env
+node_modules/
+frontend/build/
+.DS_Store
+*.egg-info/
+dist/
+.venv/
+venv/
+*.log

Dockerfile

@@ -0,0 +1,27 @@
+FROM node:20-alpine AS frontend-build
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+ENV REACT_APP_API_URL=
+RUN npm run build
+
+FROM python:3.12-slim
+
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1
+
+WORKDIR $HOME/app
+
+COPY --chown=user backend/requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user backend/ ./
+COPY --chown=user --from=frontend-build /app/frontend/build ./static
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,58 @@
+---
+title: AI Conversations
+emoji: 💬
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+hf_oauth: true
+hf_oauth_scopes:
+  - read-repos
+pinned: false
+---
+
+# AI Conversations (LLMChats3)
+
+A web app that lets two LLMs have a natural conversation. Select two LLMs, configure their personas, and watch them chat — complete with an orchestrator that manages natural conversation endings.
+
+## Quick Start (local development)
+
+```bash
+# 1. Clone and set up environment
+cp .env.example .env
+# Edit .env with your API keys
+
+# 2. Backend
+cd backend
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+
+# 3. Frontend (in a separate terminal)
+cd frontend
+npm install
+npm start
+```
+
+## Docker
+
+```bash
+cp .env.example .env
+# Edit .env with your API keys
+docker compose up --build
+```
+
+## HuggingFace Spaces Deployment
+
+This app is deployed as a Docker Space at [neongeckocom/AI_Conversations](https://huggingface.co/spaces/neongeckocom/AI_Conversations). API keys are stored as Space Secrets.
+
+Rate limiting: 20 conversations/day per IP for anonymous users. Sign in with HuggingFace as a neongeckocom org member for unlimited access.
+
+## Features
+
+- Select any two LLMs from multiple providers (OpenAI, Gemini, Fireworks, Together, Neon)
+- Configure rich personas with names, profiles, identity prompts, and writing samples
+- Structured or freeform persona input modes with file upload support
+- Watch LLMs converse naturally with an orchestrator managing conversation flow
+- Automatic conversation ending detection with graceful wrap-up
+- Export chats as .txt or .md, plus full API logs for developers
+- HuggingFace OAuth integration with org-based rate limiting

backend/app/api/chat.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import StreamingResponse, JSONResponse
+from pydantic import BaseModel
+
+from app.config import settings
+from app.services.persona import generate_role_prompt, generate_role_prompt_freeform
+from app.services.orchestrator import (
+    Session, Persona, create_session, get_session, run_conversation,
+)
+
+router = APIRouter()
+LOG = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Request models
+# ---------------------------------------------------------------------------
+
+class GenerateRoleRequest(BaseModel):
+    model_id: str
+    name: str = ""
+    profile: str = ""
+    identity: str = ""
+    samples: str = ""
+    role_style: str = "exact"
+
+
+class GenerateRoleFreeformRequest(BaseModel):
+    model_id: str
+    name: str = ""
+    text: str = ""
+    role_style: str = "ai_completed"
+
+
+class SetOrchestratorRequest(BaseModel):
+    model_id: str
+
+
+class SetSpeedPriorityRequest(BaseModel):
+    enabled: bool
+
+
+class StartChatRequest(BaseModel):
+    persona_a_model_id: str
+    persona_a_name: str
+    persona_a_role: str
+
+    persona_b_model_id: str
+    persona_b_name: str
+    persona_b_role: str
+
+    starter_text: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@router.get("/chat/orchestrator")
+async def api_get_orchestrator():
+    return {"model_id": settings.orchestrator_model}
+
+
+@router.put("/chat/orchestrator")
+async def api_set_orchestrator(req: SetOrchestratorRequest):
+    settings.orchestrator_model = req.model_id
+    return {"model_id": settings.orchestrator_model}
+
+
+@router.get("/chat/speed-priority")
+async def api_get_speed_priority():
+    return {"enabled": settings.speed_priority}
+
+
+@router.put("/chat/speed-priority")
+async def api_set_speed_priority(req: SetSpeedPriorityRequest):
+    settings.speed_priority = req.enabled
+    return {"enabled": settings.speed_priority}
+
+
+@router.post("/chat/generate-role")
+async def api_generate_role(req: GenerateRoleRequest):
+    result = await generate_role_prompt(
+        model_id=req.model_id,
+        name=req.name,
+        profile=req.profile,
+        identity=req.identity,
+        samples=req.samples,
+        role_style=req.role_style,
+    )
+    if result.get("error"):
+        raise HTTPException(status_code=400, detail=result["error"])
+    return result
+
+
+@router.post("/chat/generate-role-freeform")
+async def api_generate_role_freeform(req: GenerateRoleFreeformRequest):
+    result = await generate_role_prompt_freeform(
+        model_id=req.model_id,
+        name=req.name,
+        text=req.text,
+        role_style=req.role_style,
+    )
+    if result.get("error"):
+        raise HTTPException(status_code=400, detail=result["error"])
+    return result
+
+
+@router.post("/chat/start")
+async def api_start_chat(req: StartChatRequest, request: Request):
+    """Create a session and return a streaming SSE response for the conversation."""
+    from app.middleware.rate_limit import check_rate_limit, record_conversation
+
+    allowed, remaining = check_rate_limit(request)
+    if not allowed:
+        return JSONResponse(
+            status_code=429,
+            content={
+                "detail": "Daily conversation limit reached (20/day). Sign in with HuggingFace as a neongeckocom org member for unlimited access.",
+                "remaining": 0,
+            },
+        )
+    record_conversation(request)
+
+    ra = settings.resolve_model(req.persona_a_model_id)
+    rb = settings.resolve_model(req.persona_b_model_id)
+
+    if not ra:
+        raise HTTPException(400, f"Unknown model: {req.persona_a_model_id}")
+    if not rb:
+        raise HTTPException(400, f"Unknown model: {req.persona_b_model_id}")
+
+    session = create_session()
+    session.persona_a = Persona(
+        name=req.persona_a_name or "Persona A",
+        model_id=ra["model_id"],
+        role_prompt=req.persona_a_role,
+        base_url=ra.get("base_url", ""),
+        api_key=ra.get("api_key", ""),
+        display_name=ra["display_name"],
+        is_neon=ra.get("is_neon", False),
+        hana_model_id=ra.get("hana_model_id", ""),
+        persona_name=ra.get("persona_name", ""),
+        neon_direct_vllm=ra.get("neon_direct_vllm", False),
+        vllm_base_url=ra.get("vllm_base_url", ""),
+        vllm_api_key=ra.get("vllm_api_key", ""),
+    )
+    session.persona_b = Persona(
+        name=req.persona_b_name or "Persona B",
+        model_id=rb["model_id"],
+        role_prompt=req.persona_b_role,
+        base_url=rb.get("base_url", ""),
+        api_key=rb.get("api_key", ""),
+        display_name=rb["display_name"],
+        is_neon=rb.get("is_neon", False),
+        hana_model_id=rb.get("hana_model_id", ""),
+        persona_name=rb.get("persona_name", ""),
+        neon_direct_vllm=rb.get("neon_direct_vllm", False),
+        vllm_base_url=rb.get("vllm_base_url", ""),
+        vllm_api_key=rb.get("vllm_api_key", ""),
+    )
+
+    async def event_stream():
+        yield f"event: session\ndata: {json.dumps({'session_id': session.session_id})}\n\n"
+        async for chunk in run_conversation(session, req.starter_text):
+            yield chunk
+
+    return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+
+@router.get("/chat/{session_id}/export")
+async def api_export_chat(session_id: str, fmt: str = "txt"):
+    session = get_session(session_id)
+    if not session:
+        raise HTTPException(404, "Session not found")
+
+    if fmt == "md":
+        return _export_md(session)
+    return _export_txt(session)
+
+
+@router.get("/chat/{session_id}/api-log")
+async def api_export_log(session_id: str):
+    session = get_session(session_id)
+    if not session:
+        raise HTTPException(404, "Session not found")
+
+    return {
+        "session_id": session_id,
+        "log": session.api_log,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Export helpers
+# ---------------------------------------------------------------------------
+
+def _export_txt(session: Session) -> dict:
+    lines = [f"LLMChats3 Conversation Log", "=" * 40, ""]
+    if session.persona_a:
+        lines.append(f"Participant 1: {session.persona_a.name} ({session.persona_a.display_name})")
+    if session.persona_b:
+        lines.append(f"Participant 2: {session.persona_b.name} ({session.persona_b.display_name})")
+    lines.append("")
+    for m in session.messages:
+        lines.append(f"{m['speaker']}: {m['text']}")
+        lines.append("")
+    return {"filename": "chat_export.txt", "content": "\n".join(lines)}
+
+
+def _export_md(session: Session) -> dict:
+    lines = ["# LLMChats3 Conversation Log", ""]
+    if session.persona_a:
+        lines.append(f"**Participant 1:** {session.persona_a.name} (*{session.persona_a.display_name}*)")
+    if session.persona_b:
+        lines.append(f"**Participant 2:** {session.persona_b.name} (*{session.persona_b.display_name}*)")
+    lines.append("\n---\n")
+    for m in session.messages:
+        lines.append(f"**{m['speaker']}:** {m['text']}")
+        lines.append("")
+    return {"filename": "chat_export.md", "content": "\n".join(lines)}

backend/app/api/models.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+from app.clients.hana_client import hana_client
+from app.config import settings
+
+router = APIRouter()
+LOG = logging.getLogger(__name__)
+
+
+@router.get("/models")
+async def get_models():
+    """Return all available LLMs: Neon models from HANA + comparison providers."""
+    neon_models = []
+    try:
+        neon_models = await hana_client.get_models()
+    except Exception as exc:
+        LOG.warning("HANA models unavailable: %s", exc)
+
+    providers = []
+    for p in settings.providers:
+        providers.append({
+            "id": p["id"],
+            "name": p["name"],
+            "models": [
+                {"id": m["id"], "name": m["name"], "params": m.get("params", "")}
+                for m in p["models"]
+            ],
+        })
+
+    return JSONResponse(
+        content={
+            "neon_models": neon_models,
+            "providers": providers,
+        },
+        headers={"Cache-Control": "no-store"},
+    )

backend/app/clients/hana_client.py

@@ -0,0 +1,447 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from app.config import settings
+
+LOG = logging.getLogger(__name__)
+
+
+class HanaClient:
+    """Handles HANA API authentication, model/persona discovery, and inference."""
+
+    def __init__(self) -> None:
+        self._base = settings.hana_base_url.rstrip("/")
+        self._access_token: str = ""
+        self._refresh_token: str = ""
+        self._token_expiry: float = 0
+        self._klatchat_access_token: str = ""
+        self._klatchat_refresh_token: str = ""
+        self._klatchat_token_expiry: float = 0
+        self._client = httpx.AsyncClient(timeout=30.0)
+        self._persona_cache: dict[str, str | None] = {}
+
+    def _uses_klatchat_model(self, model_id: str) -> bool:
+        """Legacy HANA-JWT path for Security — disabled when using direct vLLM (brainforge-webapp pattern)."""
+        if settings._neon_security_direct_vllm_enabled(model_id):
+            return False
+        if not (settings.hana_password_klatchat or "").strip():
+            return False
+        mid = (model_id or "").lower()
+        return "brainforge/security" in mid or "/security@" in mid
+
+    async def authenticate(self) -> None:
+        resp = await self._client.post(
+            f"{self._base}/auth/login",
+            json={
+                "username": settings.hana_username,
+                "password": settings.hana_password,
+                "token_name": "LLMChats3",
+                "client_id": "llm-chat-tool",
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        self._access_token = data["access_token"]
+        self._refresh_token = data["refresh_token"]
+        self._token_expiry = data.get("expiration", time.time() + 3600)
+        LOG.info("HANA auth success (user=%s)", data.get("username"))
+
+    async def authenticate_klatchat(self) -> None:
+        """Login for BrainForge/Security (4090) using HANA_KLATCHAT_PASSWORD."""
+        uname = (settings.hana_username_klatchat or settings.hana_username).strip()
+        pwd = (settings.hana_password_klatchat or "").strip()
+        if not pwd:
+            raise ValueError("hana_password_klatchat not set")
+        resp = await self._client.post(
+            f"{self._base}/auth/login",
+            json={
+                "username": uname,
+                "password": pwd,
+                "token_name": "LLMChats3",
+                "client_id": "llm-chat-tool",
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        self._klatchat_access_token = data["access_token"]
+        self._klatchat_refresh_token = data["refresh_token"]
+        self._klatchat_token_expiry = data.get("expiration", time.time() + 3600)
+        LOG.info("HANA klatchat auth success (user=%s)", data.get("username"))
+
+    async def _ensure_token(self) -> None:
+        if time.time() >= self._token_expiry - 60:
+            try:
+                resp = await self._client.post(
+                    f"{self._base}/auth/refresh",
+                    json={
+                        "access_token": self._access_token,
+                        "refresh_token": self._refresh_token,
+                    },
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                self._access_token = data["access_token"]
+                self._refresh_token = data["refresh_token"]
+                self._token_expiry = data.get("expiration", time.time() + 3600)
+                LOG.info("HANA token refreshed")
+            except Exception:
+                LOG.warning("Token refresh failed, re-authenticating")
+                await self.authenticate()
+
+    async def _ensure_klatchat_token(self) -> None:
+        if not (settings.hana_password_klatchat or "").strip():
+            await self._ensure_token()
+            return
+        if not self._klatchat_access_token or time.time() >= self._klatchat_token_expiry - 60:
+            try:
+                resp = await self._client.post(
+                    f"{self._base}/auth/refresh",
+                    json={
+                        "access_token": self._klatchat_access_token,
+                        "refresh_token": self._klatchat_refresh_token,
+                    },
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                self._klatchat_access_token = data["access_token"]
+                self._klatchat_refresh_token = data["refresh_token"]
+                self._klatchat_token_expiry = data.get("expiration", time.time() + 3600)
+                LOG.info("HANA klatchat token refreshed")
+            except Exception:
+                LOG.warning("Klatchat token refresh failed, re-authenticating")
+                await self.authenticate_klatchat()
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._access_token}",
+            "Content-Type": "application/json",
+        }
+
+    def _headers_klatchat(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._klatchat_access_token}",
+            "Content-Type": "application/json",
+        }
+
+    def _headers_for_model(self, model_id: str) -> dict[str, str]:
+        if self._uses_klatchat_model(model_id) and (settings.hana_password_klatchat or "").strip():
+            return self._headers_klatchat()
+        return self._headers
+
+    async def _ensure_headers_for_model(self, model_id: str) -> dict[str, str]:
+        if self._uses_klatchat_model(model_id) and (settings.hana_password_klatchat or "").strip():
+            await self._ensure_klatchat_token()
+            return self._headers_klatchat()
+        await self._ensure_token()
+        return self._headers
+
+    def _parse_models_payload(self, data: dict[str, Any]) -> list[dict[str, Any]]:
+        models: list[dict[str, Any]] = []
+        for m in data.get("models", []):
+            model_id = f"{m['name']}@{m['version']}"
+            personas = []
+            for p in m.get("personas", []):
+                pname = p.get("persona_name", "")
+                sp = p.get("system_prompt") or ""
+                cache_key = f"{model_id}:{pname}"
+                self._persona_cache[cache_key] = sp if sp else None
+                personas.append({
+                    "id": p.get("id", p.get("persona_name", "")),
+                    "persona_name": pname,
+                    "description": p.get("description"),
+                    "system_prompt": p.get("system_prompt"),
+                    "enabled": p.get("enabled", True),
+                })
+            models.append({
+                "name": m["name"],
+                "version": m["version"],
+                "model_id": model_id,
+                "personas": personas,
+            })
+        return models
+
+    async def _merge_direct_vllm_security_models(
+        self, models: list[dict[str, Any]], seen: set[str]
+    ) -> None:
+        """Merge models from OpenAI-compatible GET /v1/models (NeonGeckoCom/brainforge-webapp pattern)."""
+        base = (settings.neon_security_vllm_base_url or "").strip().rstrip("/")
+        key = (settings.hana_password_klatchat or "").strip()
+        if not base or not key:
+            return
+        url = f"{base}/v1/models"
+        try:
+            resp = await self._client.get(
+                url,
+                headers={"Authorization": f"Bearer {key}"},
+            )
+            if resp.status_code != 200:
+                LOG.warning("Neon direct vLLM %s -> %s", url, resp.status_code)
+                return
+            payload = resp.json()
+            added = 0
+            for o in payload.get("data", []) or []:
+                mid = (o.get("id") or "").strip()
+                if not mid or "@" not in mid:
+                    continue
+                if mid in seen:
+                    continue
+                name, version = mid.split("@", 1)
+                vanilla = {
+                    "id": "vanilla",
+                    "persona_name": "vanilla",
+                    "description": None,
+                    "system_prompt": None,
+                    "enabled": True,
+                }
+                self._persona_cache[f"{mid}:vanilla"] = None
+                models.append({
+                    "name": name,
+                    "version": version,
+                    "model_id": mid,
+                    "personas": [vanilla],
+                })
+                seen.add(mid)
+                added += 1
+            if added:
+                LOG.info("Merged %s model(s) from direct vLLM %s", added, base)
+            # region agent log
+            try:
+                with open(r"c:\Users\dream\CCAI-Demo-FEAT_Config\debug-c86901.log", "a", encoding="utf-8") as _df:
+                    _df.write(
+                        json.dumps(
+                            {
+                                "sessionId": "c86901",
+                                "hypothesisId": "H5",
+                                "location": "LLMChats3/hana_client._merge_direct_vllm",
+                                "message": "direct_vllm_models",
+                                "data": {
+                                    "app": "LLMChats3",
+                                    "url": url,
+                                    "http_status": resp.status_code,
+                                    "added_count": added,
+                                },
+                                "timestamp": int(time.time() * 1000),
+                            }
+                        )
+                        + "\n"
+                    )
+            except Exception:
+                pass
+            # endregion
+        except Exception as exc:
+            LOG.warning("Neon direct vLLM model merge failed: %s", exc)
+
+    async def _enrich_security_personas_from_hana(self, models: list[dict[str, Any]]) -> None:
+        """Replace Security personas with HANA get_personas when the server allows (persona prompts live on HANA)."""
+        for m in models:
+            mid = m.get("model_id") or ""
+            if "security" not in mid.lower():
+                continue
+            try:
+                plist = await self.get_personas(mid)
+                if plist:
+                    m["personas"] = plist
+                    for p in plist:
+                        pname = p.get("persona_name", "")
+                        sp = p.get("system_prompt") or ""
+                        self._persona_cache[f"{mid}:{pname}"] = sp if sp else None
+                    LOG.info("Enriched Security personas from HANA get_personas for %s", mid)
+            except Exception as exc:
+                LOG.debug("HANA get_personas enrichment skipped for %s: %s", mid, exc)
+
+    async def _ensure_security_model_stub_if_missing(self, models: list[dict[str, Any]]) -> None:
+        """If vLLM merge failed (401) and HANA supplement failed, still list Security so the UI can show it."""
+        sid = "BrainForge/Security@2026.03.18"
+        wanted = [x.strip() for x in (settings.hana_neon_model_supplement_ids or "").split(",") if x.strip()]
+        if not any((w == sid or ("security" in w.lower() and "@" in w)) for w in wanted):
+            return
+        if any((m.get("model_id") == sid) for m in models):
+            return
+        try:
+            plist = await self.get_personas(sid)
+            name, ver = sid.split("@", 1)
+            for p in plist or []:
+                pname = p.get("persona_name", "")
+                sp = p.get("system_prompt") or ""
+                self._persona_cache[f"{sid}:{pname}"] = sp if sp else None
+            models.append({
+                "name": name,
+                "version": ver,
+                "model_id": sid,
+                "personas": plist or [],
+            })
+            LOG.info("Security model added via HANA get_personas (stub path)")
+        except Exception as exc:
+            LOG.warning(
+                "Security model not in HANA/vLLM responses (%s); adding minimal stub entry.",
+                exc,
+            )
+            vanilla = {
+                "id": "vanilla",
+                "persona_name": "vanilla",
+                "description": "Set HANA_KLATCHAT_PASSWORD to the 4090-x1-3 OpenAI API key (same as HF Space) so vLLM discovery works; persona prompts come from HANA when allowed.",
+                "system_prompt": None,
+                "enabled": True,
+            }
+            self._persona_cache[f"{sid}:vanilla"] = None
+            models.append({
+                "name": "BrainForge/Security",
+                "version": "2026.03.18",
+                "model_id": sid,
+                "personas": [vanilla],
+            })
+
+    async def get_models(self) -> list[dict[str, Any]]:
+        await self._ensure_token()
+        resp = await self._client.post(
+            f"{self._base}/brainforge/get_models",
+            headers=self._headers,
+            json={},
+        )
+        resp.raise_for_status()
+        models = self._parse_models_payload(resp.json())
+        seen = {m["model_id"] for m in models}
+
+        if (settings.hana_password_klatchat or "").strip() and (settings.neon_security_vllm_base_url or "").strip():
+            await self._merge_direct_vllm_security_models(models, seen)
+
+        await self._append_supplement_models(models)
+        await self._enrich_security_personas_from_hana(models)
+        await self._ensure_security_model_stub_if_missing(models)
+        # region agent log
+        try:
+            mids = [m.get("model_id", "") for m in models]
+            with open(r"c:\Users\dream\CCAI-Demo-FEAT_Config\debug-c86901.log", "a", encoding="utf-8") as _df:
+                _df.write(
+                    json.dumps(
+                        {
+                            "sessionId": "c86901",
+                            "hypothesisId": "H3",
+                            "location": "LLMChats3/hana_client.get_models",
+                            "message": "merged_models",
+                            "data": {
+                                "app": "LLMChats3",
+                                "model_count": len(models),
+                                "has_security_in_list": any("security" in (x or "").lower() for x in mids),
+                                "model_ids_tail": mids[-8:],
+                            },
+                            "timestamp": int(time.time() * 1000),
+                        }
+                    )
+                    + "\n"
+                )
+        except Exception:
+            pass
+        # endregion
+        return models
+
+    async def get_personas(self, model_id: str) -> list[dict[str, Any]]:
+        """Fetch personas for a model_id (used when get_models omits a model)."""
+        hdrs = await self._ensure_headers_for_model(model_id)
+        resp = await self._client.post(
+            f"{self._base}/brainforge/get_personas",
+            headers=hdrs,
+            json={"model_id": model_id},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        out = []
+        for p in data.get("personas", []):
+            pname = p.get("persona_name", "")
+            sp = p.get("system_prompt") or ""
+            cache_key = f"{model_id}:{pname}"
+            self._persona_cache[cache_key] = sp if sp else None
+            out.append({
+                "id": p.get("id", p.get("persona_name", "")),
+                "persona_name": pname,
+                "description": p.get("description"),
+                "system_prompt": p.get("system_prompt"),
+                "enabled": p.get("enabled", True),
+            })
+        return out
+
+    async def _append_supplement_models(self, models: list[dict[str, Any]]) -> None:
+        """Merge models listed in settings but missing from get_models (HANA may omit some)."""
+        raw = (settings.hana_neon_model_supplement_ids or "").strip()
+        extras = [x.strip() for x in raw.split(",") if x.strip()]
+        seen = {m["model_id"] for m in models}
+        for mid in extras:
+            if mid in seen:
+                continue
+            if "@" not in mid:
+                LOG.warning("Invalid supplement model_id (expected name@version): %s", mid)
+                continue
+            try:
+                personas = await self.get_personas(mid)
+                name, version = mid.split("@", 1)
+                models.append({
+                    "name": name,
+                    "version": version,
+                    "model_id": mid,
+                    "personas": personas,
+                })
+                seen.add(mid)
+                LOG.info("Merged supplement Neon model from get_personas: %s", mid)
+            except Exception as exc:
+                LOG.debug("Supplement Neon model %s not merged: %s", mid, exc)
+
+    def get_persona_system_prompt(self, model_id: str, persona_name: str) -> str | None:
+        """Look up a persona's built-in system_prompt from the cache."""
+        return self._persona_cache.get(f"{model_id}:{persona_name}")
+
+    async def get_inference(
+        self,
+        query: str,
+        model_id: str,
+        persona_name: str,
+        system_prompt: str | None = None,
+        history: list[tuple[str, str]] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+    ) -> dict[str, Any]:
+        hdrs = await self._ensure_headers_for_model(model_id)
+        hist = [[role, content] for role, content in (history or [])]
+
+        persona_payload: dict[str, Any] = {"persona_name": persona_name}
+        if system_prompt:
+            persona_payload["system_prompt"] = system_prompt
+
+        body = {
+            "query": query,
+            "history": hist,
+            "persona": persona_payload,
+            "model": model_id,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "extra_body": {},
+            "llm_name": model_id.split("@")[0] if "@" in model_id else model_id,
+            "llm_revision": model_id.split("@")[1] if "@" in model_id else "",
+        }
+
+        t0 = time.time()
+        resp = await self._client.post(
+            f"{self._base}/brainforge/get_inference",
+            headers=hdrs,
+            json=body,
+        )
+        elapsed = time.time() - t0
+        resp.raise_for_status()
+        data = resp.json()
+        return {
+            "response": data.get("response", ""),
+            "elapsed_seconds": round(elapsed, 2),
+            "finish_reason": data.get("finish_reason", "stop"),
+        }
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+hana_client = HanaClient()

backend/app/clients/llm_router.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from app.clients.openai_compat import openai_chat_completion
+from app.clients.hana_client import hana_client
+
+LOG = logging.getLogger(__name__)
+
+RACE_DELAY_SECONDS = 5.0
+
+_FALLBACK_CHAIN = [
+    "gemini-2.0-flash",
+    "gpt-4.1-mini",
+]
+
+
+def _pick_fallback(exclude_model_id: str) -> dict | None:
+    """Return the first usable fallback model that isn't the one we're already calling."""
+    from app.config import settings
+
+    for candidate_id in _FALLBACK_CHAIN:
+        if candidate_id == exclude_model_id:
+            continue
+        resolved = settings.resolve_model(candidate_id)
+        if resolved and not resolved.get("is_neon"):
+            return resolved
+
+    for prov in settings.providers:
+        for m in prov["models"]:
+            if m["id"] == exclude_model_id:
+                continue
+            resolved = settings.resolve_model(m["id"])
+            if resolved and not resolved.get("is_neon"):
+                return resolved
+    return None
+
+
+async def chat_completion(
+    resolved: dict,
+    messages: list[dict[str, str]],
+    temperature: float = 0.7,
+    max_tokens: int = 1024,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Unified LLM call that routes Neon models through HANA and others through OpenAI-compat."""
+    if resolved.get("is_neon"):
+        return await _call_hana(resolved, messages, temperature, max_tokens)
+
+    from app.config import settings
+    if settings.speed_priority:
+        return await _racing_openai(resolved, messages, temperature, max_tokens, timeout)
+
+    return await _plain_openai(resolved, messages, temperature, max_tokens, timeout)
+
+
+async def _plain_openai(
+    resolved: dict,
+    messages: list[dict[str, str]],
+    temperature: float,
+    max_tokens: int,
+    timeout: float | None,
+) -> dict[str, Any]:
+    return await openai_chat_completion(
+        base_url=resolved["base_url"],
+        api_key=resolved["api_key"],
+        model=resolved["model_id"],
+        messages=messages,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        timeout=timeout,
+    )
+
+
+async def _racing_openai(
+    resolved: dict,
+    messages: list[dict[str, str]],
+    temperature: float,
+    max_tokens: int,
+    timeout: float | None,
+) -> dict[str, Any]:
+    """Start the primary request; after RACE_DELAY_SECONDS fire a fallback and race them."""
+    primary_task = asyncio.create_task(
+        _plain_openai(resolved, messages, temperature, max_tokens, timeout),
+        name=f"primary:{resolved['model_id']}",
+    )
+
+    done, _ = await asyncio.wait({primary_task}, timeout=RACE_DELAY_SECONDS)
+    if done:
+        return primary_task.result()
+
+    fallback_resolved = _pick_fallback(resolved["model_id"])
+    if not fallback_resolved:
+        LOG.info("Speed-priority: no fallback available, waiting for primary %s", resolved["model_id"])
+        return await primary_task
+
+    LOG.info(
+        "Speed-priority: %s still pending after %.1fs — racing with fallback %s",
+        resolved["model_id"], RACE_DELAY_SECONDS, fallback_resolved["model_id"],
+    )
+    fallback_task = asyncio.create_task(
+        _plain_openai(fallback_resolved, messages, temperature, max_tokens, timeout),
+        name=f"fallback:{fallback_resolved['model_id']}",
+    )
+
+    done, pending = await asyncio.wait(
+        {primary_task, fallback_task}, return_when=asyncio.FIRST_COMPLETED,
+    )
+    winner = done.pop()
+    result = winner.result()
+
+    if result.get("error"):
+        if pending:
+            other = pending.pop()
+            try:
+                other_result = await other
+                if not other_result.get("error"):
+                    LOG.info("Speed-priority: winner had error, using other result")
+                    return other_result
+            except Exception:
+                pass
+        return result
+
+    for task in pending:
+        task.cancel()
+
+    used_model = result.get("model", "")
+    if winner is fallback_task:
+        LOG.info("Speed-priority: fallback %s won the race", used_model)
+        result["used_fallback"] = True
+        result["original_model"] = resolved["model_id"]
+    else:
+        LOG.info("Speed-priority: primary %s won the race", used_model)
+
+    return result
+
+
+async def _call_neon_direct_vllm(
+    resolved: dict,
+    messages: list[dict[str, str]],
+    temperature: float,
+    max_tokens: int,
+) -> dict[str, Any]:
+    """BrainForge/Security on 4090-x1-3: OpenAI-compatible vLLM; still use HANA persona base when cached."""
+    builtin_sp = hana_client.get_persona_system_prompt(
+        resolved["hana_model_id"], resolved["persona_name"]
+    )
+    msgs = [dict(m) for m in messages]
+    if builtin_sp:
+        if msgs and msgs[0].get("role") == "system":
+            msgs[0] = {
+                "role": "system",
+                "content": msgs[0]["content"] + "\n\n[Neon persona base from HANA]\n" + builtin_sp,
+            }
+        else:
+            msgs.insert(0, {"role": "system", "content": "[Neon persona base from HANA]\n" + builtin_sp})
+
+    result = await openai_chat_completion(
+        base_url=resolved["vllm_base_url"],
+        api_key=resolved["vllm_api_key"],
+        model=resolved["hana_model_id"],
+        messages=msgs,
+        temperature=temperature,
+        max_tokens=max_tokens,
+    )
+    return {
+        "response": result.get("response", ""),
+        "elapsed_seconds": result.get("elapsed_seconds", 0),
+        "model": resolved["model_id"],
+    }
+
+
+async def _call_hana(
+    resolved: dict,
+    messages: list[dict[str, str]],
+    temperature: float,
+    max_tokens: int,
+) -> dict[str, Any]:
+    if resolved.get("neon_direct_vllm"):
+        return await _call_neon_direct_vllm(resolved, messages, temperature, max_tokens)
+
+    system_context = ""
+    query = ""
+    history: list[tuple[str, str]] = []
+
+    for msg in messages:
+        if msg["role"] == "system":
+            system_context = msg["content"]
+        elif msg["role"] == "user":
+            query = msg["content"]
+        elif msg["role"] == "assistant":
+            history.append(("assistant", msg["content"]))
+
+    if system_context:
+        query = f"[Context: {system_context}]\n\n{query}"
+
+    builtin_sp = hana_client.get_persona_system_prompt(
+        resolved["hana_model_id"], resolved["persona_name"]
+    )
+
+    try:
+        result = await hana_client.get_inference(
+            query=query,
+            model_id=resolved["hana_model_id"],
+            persona_name=resolved["persona_name"],
+            system_prompt=builtin_sp,
+            history=history if history else None,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return {
+            "response": result.get("response", ""),
+            "elapsed_seconds": result.get("elapsed_seconds", 0),
+            "model": resolved["model_id"],
+        }
+    except Exception as exc:
+        LOG.exception("HANA inference failed for %s: %s", resolved["model_id"], exc)
+        return {
+            "response": f"[Error]: {exc}",
+            "elapsed_seconds": 0,
+            "model": resolved["model_id"],
+            "error": True,
+        }

backend/app/clients/openai_compat.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import time
+from typing import Any
+
+import httpx
+
+LOG = logging.getLogger(__name__)
+
+_shared_client: httpx.AsyncClient | None = None
+
+_THINK_TAG_RE = re.compile(r"<think>.*?</think>", re.DOTALL)
+_REASONING_BLOCK_RE = re.compile(
+    r"<(reasoning|reflection|inner_thoughts|scratchpad)>.*?</\1>",
+    re.DOTALL,
+)
+
+_MAX_COMPLETION_TOKEN_MODELS = {
+    "o1", "o1-mini", "o1-preview", "o3", "o3-mini", "o4-mini",
+    "gpt-5", "gpt-oss",
+}
+_NO_TEMPERATURE_MODELS = {"o1", "o1-mini", "o1-preview", "o3", "o3-mini", "o4-mini"}
+
+
+def _get_client() -> httpx.AsyncClient:
+    global _shared_client
+    if _shared_client is None or _shared_client.is_closed:
+        _shared_client = httpx.AsyncClient(timeout=45.0)
+    return _shared_client
+
+
+def _strip_thinking(text: str) -> str:
+    """Remove chain-of-thought artifacts from any model's response."""
+    text = _THINK_TAG_RE.sub("", text)
+    text = _REASONING_BLOCK_RE.sub("", text)
+    return text.strip()
+
+
+def _detect_thinking_model(model: str, msg: dict) -> bool:
+    """Detect thinking models from the response itself, not just the model name."""
+    if msg.get("reasoning_content") or msg.get("reasoning"):
+        return True
+    content = msg.get("content") or ""
+    if _THINK_TAG_RE.search(content):
+        return True
+    return False
+
+
+async def openai_chat_completion(
+    base_url: str,
+    api_key: str,
+    model: str,
+    messages: list[dict[str, str]],
+    temperature: float = 0.7,
+    max_tokens: int = 1024,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Send a chat completion request to any OpenAI-compatible endpoint."""
+    url = f"{base_url.rstrip('/')}/chat/completions"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    needs_mct = any(model.startswith(prefix) for prefix in _MAX_COMPLETION_TOKEN_MODELS)
+    skip_temp = any(model.startswith(prefix) for prefix in _NO_TEMPERATURE_MODELS)
+
+    effective_max = max_tokens * 4
+    effective_timeout = max(timeout * 2, 120) if timeout else timeout
+
+    body: dict[str, Any] = {
+        "model": model,
+        "messages": messages,
+    }
+    if needs_mct:
+        body["max_completion_tokens"] = effective_max
+    else:
+        body["max_tokens"] = effective_max
+    if not skip_temp:
+        body["temperature"] = temperature
+
+    req_timeout = httpx.Timeout(effective_timeout) if effective_timeout else None
+    client = _get_client()
+    t0 = time.time()
+    for attempt in range(2):
+        try:
+            resp = await client.post(url, json=body, headers=headers, timeout=req_timeout)
+            if resp.status_code >= 400 and attempt == 0:
+                LOG.warning("Error %d on %s (attempt 1), retrying in 1.1s", resp.status_code, model)
+                await asyncio.sleep(1.1)
+                continue
+            elapsed = time.time() - t0
+            resp.raise_for_status()
+            data = resp.json()
+            choices = data.get("choices", [])
+            text = ""
+            finish_reason = ""
+            had_thinking = False
+            if choices:
+                msg = choices[0].get("message") or {}
+                text = msg.get("content") or ""
+                finish_reason = choices[0].get("finish_reason") or ""
+                had_thinking = _detect_thinking_model(model, msg)
+                text = _strip_thinking(text)
+
+            if had_thinking:
+                LOG.info("Stripped thinking content from %s response", model)
+
+            return {
+                "response": text.strip(),
+                "elapsed_seconds": round(elapsed, 2),
+                "model": data.get("model", model),
+                "finish_reason": finish_reason,
+            }
+        except httpx.HTTPStatusError as exc:
+            if attempt == 0:
+                LOG.warning("HTTPStatusError on %s (attempt 1), retrying", model)
+                await asyncio.sleep(1.1)
+                continue
+            elapsed = time.time() - t0
+            detail = exc.response.text[:300] if exc.response else str(exc)
+            LOG.error("OpenAI-compat %s error %s: %s", base_url, exc.response.status_code, detail)
+            return {
+                "response": f"[Error {exc.response.status_code}]: {detail}",
+                "elapsed_seconds": round(elapsed, 2),
+                "model": model,
+                "error": True,
+            }
+        except Exception as exc:
+            if attempt == 0:
+                LOG.warning("Exception on %s (attempt 1), retrying: %s", model, exc)
+                await asyncio.sleep(1.1)
+                continue
+            elapsed = time.time() - t0
+            LOG.exception("OpenAI-compat request failed: %s", exc)
+            return {
+                "response": f"[Error]: {exc}",
+                "elapsed_seconds": round(elapsed, 2),
+                "model": model,
+                "error": True,
+            }
+
+
+async def close_shared_client() -> None:
+    global _shared_client
+    if _shared_client and not _shared_client.is_closed:
+        await _shared_client.aclose()
+    _shared_client = None

backend/app/config.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import AliasChoices, Field
+from pydantic_settings import BaseSettings
+
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+_ENV_FILE = _PROJECT_ROOT / ".env"
+
+
+class Settings(BaseSettings):
+    hana_base_url: str = "https://hana.neonaialpha.com"
+    hana_username: str = "guest"
+    hana_password: str = "password"
+    # BrainForge/Security (4090 x1-3): separate HANA login — use HANA_KLATCHAT_PASSWORD or HANA_PASSWORD_KLATCHAT in project-root .env
+    hana_username_klatchat: str = ""
+    # Same value as HuggingFace Space secret API_KEY for 4090-x1-3 — OpenAI-compatible Bearer, NOT HANA /auth/login password.
+    hana_password_klatchat: str = Field(
+        default="",
+        validation_alias=AliasChoices("HANA_KLATCHAT_PASSWORD", "HANA_PASSWORD_KLATCHAT"),
+    )
+    # Direct vLLM base (no /v1); matches brainforge-webapp docker config 4090-x1-3 host.
+    neon_security_vllm_base_url: str = "https://4090-x1-3.neonaiservices2.com/vllm0"
+    # Comma-separated model_id values to merge via get_personas when get_models omits them (needs HANA access)
+    hana_neon_model_supplement_ids: str = "BrainForge/Security@2026.03.18"
+
+    vllm_api_key: str = ""
+
+    fireworks_api_key: str = ""
+    together_api_key: str = ""
+    openai_api_key: str = ""
+    gemini_api_key: str = ""
+    mistral_api_key: str = ""
+
+    orchestrator_model: str = "gpt-4o-mini"
+    speed_priority: bool = False
+
+    cors_origins: str = "http://localhost:3000,http://localhost:3001,http://localhost:3002"
+
+    model_config = {"env_file": str(_ENV_FILE), "env_file_encoding": "utf-8"}
+
+    @property
+    def cors_origin_list(self) -> list[str]:
+        return [o.strip() for o in self.cors_origins.split(",") if o.strip()]
+
+    def _neon_security_direct_vllm_enabled(self, hana_model_id: str) -> bool:
+        """BrainForge/Security on 4090-x1-3: same pattern as brainforge-webapp (direct vLLM + API key)."""
+        if "security" not in (hana_model_id or "").lower():
+            return False
+        return bool((self.hana_password_klatchat or "").strip() and (self.neon_security_vllm_base_url or "").strip())
+
+    @property
+    def providers(self) -> list[dict]:
+        """Build the flat list of all available LLM providers and their models."""
+        providers: list[dict] = []
+        fw_url = "https://api.fireworks.ai/inference/v1"
+        fw_key = self.fireworks_api_key
+        fw_ok = fw_key and fw_key != "your-fireworks-api-key-here"
+        tg_url = "https://api.together.xyz/v1"
+        tg_key = self.together_api_key
+        tg_ok = tg_key and tg_key != "your-together-api-key-here"
+
+        if fw_ok:
+            providers.append({
+                "id": "kimi",
+                "name": "Kimi",
+                "base_url": fw_url,
+                "api_key": fw_key,
+                "models": [
+                    {"id": "accounts/fireworks/models/kimi-k2-thinking", "name": "Kimi K2 Thinking", "params": "1T (32B active)"},
+                    {"id": "accounts/fireworks/models/kimi-k2-instruct-0905", "name": "Kimi K2 Instruct 0905", "params": "1T (32B active)"},
+                    {"id": "accounts/fireworks/models/kimi-k2p5", "name": "Kimi K2.5", "params": "1T (32B active)"},
+                ],
+            })
+            providers.append({
+                "id": "deepseek",
+                "name": "DeepSeek",
+                "base_url": fw_url,
+                "api_key": fw_key,
+                "models": [
+                    {"id": "accounts/fireworks/models/deepseek-v3p1", "name": "DeepSeek V3.1", "params": "671B (37B active)"},
+                    {"id": "accounts/fireworks/models/deepseek-v3p2", "name": "DeepSeek V3.2", "params": "671B (37B active)"},
+                ],
+            })
+
+        oai_ok = self.openai_api_key and self.openai_api_key != "your-openai-api-key-here"
+        if oai_ok or fw_ok or tg_ok:
+            oai_models = []
+            if oai_ok:
+                oai_models.extend([
+                    {"id": "gpt-5.4", "name": "GPT-5.4", "params": "Undisclosed"},
+                    {"id": "gpt-4.1", "name": "GPT-4.1", "params": "Undisclosed"},
+                    {"id": "gpt-4o", "name": "GPT-4o", "params": "~200B (estimated)"},
+                    {"id": "gpt-4o-mini", "name": "GPT-4o Mini", "params": "~8B (estimated)"},
+                    {"id": "gpt-4.1-mini", "name": "GPT-4.1 Mini", "params": "Undisclosed"},
+                    {"id": "o4-mini", "name": "o4-Mini", "params": "Undisclosed"},
+                ])
+            if fw_ok:
+                oai_models.append({
+                    "id": "accounts/fireworks/models/gpt-oss-120b",
+                    "name": "GPT-OSS 120B",
+                    "params": "117B (5.1B active)",
+                    "base_url": fw_url,
+                    "api_key": fw_key,
+                })
+            if tg_ok:
+                oai_models.append({
+                    "id": "openai/gpt-oss-20b",
+                    "name": "GPT-OSS 20B",
+                    "params": "~20B",
+                    "base_url": tg_url,
+                    "api_key": tg_key,
+                })
+            if oai_models:
+                providers.append({
+                    "id": "openai",
+                    "name": "OpenAI",
+                    "base_url": "https://api.openai.com/v1",
+                    "api_key": self.openai_api_key if oai_ok else "",
+                    "models": oai_models,
+                })
+
+        mistral_ok = self.mistral_api_key and self.mistral_api_key != "your-mistral-api-key-here"
+        if mistral_ok:
+            providers.append({
+                "id": "mistral",
+                "name": "Mistral",
+                "base_url": "https://api.mistral.ai/v1",
+                "api_key": self.mistral_api_key,
+                "models": [
+                    {"id": "mistral-small-2506", "name": "Mistral Small 3.2", "params": "24B"},
+                    {"id": "mistral-small-2603", "name": "Mistral Small 4", "params": "119B"},
+                    {"id": "devstral-2512", "name": "Devstral2", "params": "123B"},
+                ],
+            })
+            providers.append({
+                "id": "qwen",
+                "name": "Qwen",
+                "base_url": tg_url,
+                "api_key": tg_key,
+                "models": [
+                    {"id": "Qwen/Qwen3-VL-8B-Instruct", "name": "Qwen3 VL 8B", "params": "8B"},
+                ],
+            })
+            providers.append({
+                "id": "meta",
+                "name": "Meta Llama",
+                "base_url": tg_url,
+                "api_key": tg_key,
+                "models": [
+                    {"id": "meta-llama/Llama-3.3-70B-Instruct-Turbo", "name": "Llama 3.3 70B Turbo", "params": "70B"},
+                    {"id": "meta-llama/Meta-Llama-3-8B-Instruct-Lite", "name": "Llama 3 8B Lite", "params": "8B"},
+                ],
+            })
+
+        if self.gemini_api_key and self.gemini_api_key != "your-gemini-api-key-here":
+            providers.append({
+                "id": "gemini",
+                "name": "Google Gemini",
+                "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
+                "api_key": self.gemini_api_key,
+                "models": [
+                    {"id": "gemini-2.0-flash", "name": "Gemini 2.0 Flash", "params": "Undisclosed"},
+                    {"id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash", "params": "Undisclosed"},
+                    {"id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro", "params": "Undisclosed"},
+                ],
+            })
+        return providers
+
+    def resolve_model(self, model_id: str) -> dict | None:
+        """Given a model_id, return {base_url, api_key, model_id, ...} or None.
+
+        Handles both external providers and Neon HANA models (prefixed with 'neon:').
+        """
+        if model_id.startswith("neon:"):
+            parts = model_id.split(":", 2)
+            if len(parts) == 3:
+                hana_model_id = parts[1]
+                persona_name = parts[2]
+                out: dict = {
+                    "is_neon": True,
+                    "model_id": model_id,
+                    "hana_model_id": hana_model_id,
+                    "persona_name": persona_name,
+                    "display_name": persona_name,
+                    "provider": "Neon",
+                    "base_url": self.hana_base_url,
+                    "api_key": "",
+                }
+                if self._neon_security_direct_vllm_enabled(hana_model_id):
+                    out["neon_direct_vllm"] = True
+                    out["vllm_base_url"] = f"{self.neon_security_vllm_base_url.rstrip('/')}/v1"
+                    out["vllm_api_key"] = self.hana_password_klatchat
+                return out
+
+        for prov in self.providers:
+            for m in prov["models"]:
+                if m["id"] == model_id:
+                    return {
+                        "base_url": m.get("base_url", prov["base_url"]),
+                        "api_key": m.get("api_key", prov["api_key"]),
+                        "model_id": m["id"],
+                        "display_name": m["name"],
+                        "provider": prov["name"],
+                    }
+        return None
+
+
+settings = Settings()
+
+# region agent log
+def _agent_log_settings_env() -> None:
+    import json
+    import time
+
+    _path = r"c:\Users\dream\CCAI-Demo-FEAT_Config\debug-c86901.log"
+    try:
+        raw = _ENV_FILE.read_text(encoding="utf-8") if _ENV_FILE.is_file() else ""
+        data = {
+            "app": "LLMChats3",
+            "env_file": str(_ENV_FILE),
+            "env_file_exists": _ENV_FILE.is_file(),
+            "dotenv_line_HANA_KLATCHAT_PASSWORD": "HANA_KLATCHAT_PASSWORD" in raw,
+            "dotenv_line_HANA_PASSWORD_KLATCHAT": "HANA_PASSWORD_KLATCHAT" in raw,
+            "settings_hana_password_klatchat_nonempty": bool((settings.hana_password_klatchat or "").strip()),
+        }
+        with open(_path, "a", encoding="utf-8") as f:
+            f.write(
+                json.dumps(
+                    {
+                        "sessionId": "c86901",
+                        "hypothesisId": "H1",
+                        "location": "LLMChats3/config.py:settings",
+                        "message": "env_binding",
+                        "data": data,
+                        "timestamp": int(time.time() * 1000),
+                    }
+                )
+                + "\n"
+            )
+    except Exception:
+        pass
+
+
+_agent_log_settings_env()
+# endregion

backend/app/main.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from starlette.middleware.sessions import SessionMiddleware
+
+from app.config import settings
+from app.clients.hana_client import hana_client
+from app.clients.openai_compat import close_shared_client
+from app.api import models, chat
+from app.middleware.rate_limit import (
+    get_oauth_username, is_org_member, get_remaining, check_rate_limit,
+    record_conversation,
+)
+
+logging.basicConfig(level=logging.INFO)
+LOG = logging.getLogger(__name__)
+
+STATIC_DIR = Path(__file__).resolve().parent.parent / "static"
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    LOG.info("Starting up — authenticating with HANA...")
+    try:
+        await hana_client.authenticate()
+        await hana_client.get_models()
+        LOG.info("HANA auth complete, persona cache populated.")
+    except Exception as exc:
+        LOG.warning("HANA auth failed (Neon models will be unavailable): %s", exc)
+    yield
+    LOG.info("Shutting down — closing HTTP clients...")
+    await hana_client.close()
+    await close_shared_client()
+
+
+app = FastAPI(title="AI Conversations", version="1.0.0", lifespan=lifespan)
+
+app.add_middleware(
+    SessionMiddleware,
+    secret_key=os.getenv("SESSION_SECRET", secrets.token_hex(32)),
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+try:
+    from huggingface_hub import attach_huggingface_oauth
+    attach_huggingface_oauth(app)
+    LOG.info("HuggingFace OAuth endpoints registered.")
+except Exception as exc:
+    LOG.warning("HF OAuth not available (local dev mode): %s", exc)
+
+
+app.include_router(models.router, prefix="/api")
+app.include_router(chat.router, prefix="/api")
+
+
+@app.get("/api/health")
+async def health():
+    return {"status": "ok"}
+
+
+@app.get("/api/auth/status")
+async def auth_status(request: Request):
+    username = get_oauth_username(request)
+    if username is None:
+        remaining = get_remaining(request)
+        return {
+            "logged_in": False,
+            "username": None,
+            "is_org_member": False,
+            "remaining_conversations": remaining,
+        }
+    member = is_org_member(request)
+    remaining = -1 if member else get_remaining(request)
+    return {
+        "logged_in": True,
+        "username": username,
+        "is_org_member": member,
+        "remaining_conversations": remaining,
+    }
+
+
+@app.get("/api/rate-limit/status")
+async def rate_limit_status(request: Request):
+    remaining = get_remaining(request)
+    return {"remaining": remaining, "daily_limit": 20}
+
+
+if STATIC_DIR.is_dir():
+    from starlette.staticfiles import StaticFiles
+    from starlette.responses import FileResponse
+
+    @app.get("/{full_path:path}")
+    async def serve_spa(request: Request, full_path: str):
+        file_path = STATIC_DIR / full_path
+        if file_path.is_file():
+            return FileResponse(file_path)
+        return FileResponse(STATIC_DIR / "index.html")
+
+    LOG.info("Serving frontend from %s", STATIC_DIR)
+else:
+    LOG.info("No static directory found at %s — frontend not served.", STATIC_DIR)

backend/app/middleware/rate_limit.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import logging
+import os
+from collections import defaultdict
+from datetime import date
+
+from fastapi import Request
+
+LOG = logging.getLogger(__name__)
+
+ORG_NAME = os.getenv("HF_RATE_LIMIT_ORG", "neongeckocom")
+DAILY_LIMIT = int(os.getenv("HF_RATE_LIMIT_DAILY", "20"))
+
+_ip_counts: dict[str, dict] = defaultdict(lambda: {"date": "", "count": 0})
+
+
+def _today() -> str:
+    return date.today().isoformat()
+
+
+def is_org_member(request: Request) -> bool:
+    try:
+        from huggingface_hub import parse_huggingface_oauth
+        oauth_info = parse_huggingface_oauth(request)
+        if oauth_info is None:
+            return False
+        orgs = oauth_info.user_info.orgs or []
+        return any(o.preferred_username == ORG_NAME for o in orgs)
+    except Exception:
+        return False
+
+
+def get_oauth_username(request: Request) -> str | None:
+    try:
+        from huggingface_hub import parse_huggingface_oauth
+        oauth_info = parse_huggingface_oauth(request)
+        if oauth_info is None:
+            return None
+        return oauth_info.user_info.preferred_username
+    except Exception:
+        return None
+
+
+def get_client_ip(request: Request) -> str:
+    forwarded = request.headers.get("x-forwarded-for")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+def check_rate_limit(request: Request) -> tuple[bool, int]:
+    """Returns (allowed, remaining). If org member, remaining is -1 (unlimited)."""
+    if is_org_member(request):
+        return True, -1
+
+    ip = get_client_ip(request)
+    today = _today()
+
+    entry = _ip_counts[ip]
+    if entry["date"] != today:
+        entry["date"] = today
+        entry["count"] = 0
+
+    remaining = max(0, DAILY_LIMIT - entry["count"])
+    if entry["count"] >= DAILY_LIMIT:
+        return False, 0
+
+    return True, remaining
+
+
+def record_conversation(request: Request) -> None:
+    """Increment the counter after a conversation is successfully started."""
+    if is_org_member(request):
+        return
+    ip = get_client_ip(request)
+    today = _today()
+    entry = _ip_counts[ip]
+    if entry["date"] != today:
+        entry["date"] = today
+        entry["count"] = 0
+    entry["count"] += 1
+
+
+def get_remaining(request: Request) -> int:
+    """Get remaining conversations for a client. -1 means unlimited."""
+    if is_org_member(request):
+        return -1
+    ip = get_client_ip(request)
+    today = _today()
+    entry = _ip_counts[ip]
+    if entry["date"] != today:
+        return DAILY_LIMIT
+    return max(0, DAILY_LIMIT - entry["count"])

backend/app/services/orchestrator.py

@@ -0,0 +1,391 @@
+from __future__ import annotations
+
+import json
+import logging
+import random
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+from app.clients.openai_compat import openai_chat_completion
+from app.clients.llm_router import chat_completion as unified_chat_completion
+from app.config import settings
+
+LOG = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Prompt templates
+# ---------------------------------------------------------------------------
+
+_BREVITY = (
+    " Keep your reply short — 2-4 sentences, like a casual chat message, not an email or essay."
+)
+
+AUTO_START_PROMPT = (
+    "You're starting a conversation with someone new. Here is some information about them: "
+    "{other_role}\n\n"
+    "Consider connections between this information and what you know about yourself, and say "
+    "something that could start a conversation with that new person. Speak in the first person, "
+    "as if directly to the other person." + _BREVITY
+)
+
+FIRST_REPLY_PROMPT = (
+    "Someone just started a conversation with you, this is what they said: {last_message}\n\n"
+    "Consider connections between this conversation starter and what you know about yourself, "
+    "and say something that could continue the conversation with that new person. Speak in the "
+    "first person, as if directly to the other person." + _BREVITY
+)
+
+CONTINUE_PROMPT = (
+    "You are having a conversation with another person, here is the conversation so far:\n\n"
+    "{history}\n\n"
+    "Consider how human conversations generally progress, and provide a response. If the last "
+    "reply in the conversation is one which might indicate a human is losing interest in or "
+    "wrapping up the conversation, then make a response which will help wrap up and close the "
+    "conversation." + _BREVITY
+)
+
+WINDING_NEXT_PROMPT = (
+    "You are having a conversation with another person, here is the conversation so far:\n\n"
+    "{history}\n\n"
+    "Consider how human conversations generally progress, and provide a response which will "
+    "wrap up and close the conversation. This is the last reply you will give in this "
+    "conversation." + _BREVITY
+)
+
+WINDING_FINAL_PROMPT = (
+    "You are having a conversation with another person, here is the conversation so far:\n\n"
+    "{history}\n\n"
+    "Consider how human conversations generally progress, and focus on the last two messages "
+    "in this conversation. Provide a very short response which closes the conversation."
+    + _BREVITY
+)
+
+ORCHESTRATOR_CHECK_PROMPT = (
+    "You are monitoring a conversation between two people. Your job is to determine whether "
+    "the latest message indicates the speaker is losing interest or wrapping up the conversation. "
+    "Reply with ONLY a JSON object: {{\"winding_down\": true}} or {{\"winding_down\": false}}. "
+    "No other text.\n\nLatest message:\n{message}"
+)
+
+
+# ---------------------------------------------------------------------------
+# Session data
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Persona:
+    name: str
+    model_id: str
+    role_prompt: str
+    base_url: str = ""
+    api_key: str = ""
+    display_name: str = ""
+    is_neon: bool = False
+    hana_model_id: str = ""
+    persona_name: str = ""
+    neon_direct_vllm: bool = False
+    vllm_base_url: str = ""
+    vllm_api_key: str = ""
+
+
+@dataclass
+class Session:
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    persona_a: Persona | None = None
+    persona_b: Persona | None = None
+    messages: list[dict[str, str]] = field(default_factory=list)
+    api_log: list[dict[str, Any]] = field(default_factory=list)
+    a_count: int = 0
+    b_count: int = 0
+    end_mode: bool = False
+    finished: bool = False
+
+
+_sessions: dict[str, Session] = {}
+
+
+def get_session(sid: str) -> Session | None:
+    return _sessions.get(sid)
+
+
+def create_session() -> Session:
+    s = Session()
+    _sessions[s.session_id] = s
+    return s
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _format_history(messages: list[dict[str, str]]) -> str:
+    lines = []
+    for m in messages:
+        lines.append(f"{m['speaker']}: {m['text']}")
+    return "\n".join(lines)
+
+
+async def _call_llm(
+    persona: Persona,
+    system_content: str,
+    user_content: str,
+    session: Session,
+    label: str = "",
+    max_tokens: int = 500,
+    timeout: float = 20,
+) -> str:
+    system_with_directive = (
+        system_content + "\n\nIMPORTANT: Respond ONLY with your in-character dialogue. "
+        "Do NOT include your reasoning, thought process, analysis of the prompt, "
+        "meta-commentary, internal monologue, or draft notes. Output ONLY the words "
+        "your character would actually say aloud."
+    )
+    messages = [
+        {"role": "system", "content": system_with_directive},
+        {"role": "user", "content": user_content},
+    ]
+    log_entry: dict[str, Any] = {
+        "timestamp": time.time(),
+        "label": label,
+        "model": persona.model_id,
+        "request": {"messages": messages, "max_tokens": max_tokens},
+    }
+
+    resolved = {
+        "model_id": persona.model_id,
+        "base_url": persona.base_url,
+        "api_key": persona.api_key,
+        "is_neon": persona.is_neon,
+        "hana_model_id": persona.hana_model_id,
+        "persona_name": persona.persona_name,
+        "neon_direct_vllm": persona.neon_direct_vllm,
+        "vllm_base_url": persona.vllm_base_url,
+        "vllm_api_key": persona.vllm_api_key,
+    }
+    result = await unified_chat_completion(
+        resolved=resolved,
+        messages=messages,
+        temperature=0.7,
+        max_tokens=max_tokens,
+        timeout=timeout,
+    )
+
+    log_entry["response"] = result
+    session.api_log.append(log_entry)
+
+    return result.get("response", ""), result.get("elapsed_seconds", 0)
+
+
+async def _call_orchestrator(
+    prompt: str,
+    session: Session,
+    label: str = "",
+) -> str:
+    resolved = settings.resolve_model(settings.orchestrator_model)
+    if not resolved:
+        LOG.warning("Orchestrator model %s not found, using first available", settings.orchestrator_model)
+        for prov in settings.providers:
+            for m in prov["models"]:
+                resolved = {
+                    "base_url": m.get("base_url", prov["base_url"]),
+                    "api_key": m.get("api_key", prov["api_key"]),
+                    "model_id": m["id"],
+                }
+                break
+            if resolved:
+                break
+
+    if not resolved:
+        return '{"winding_down": false}'
+
+    messages = [
+        {"role": "system", "content": "You are a conversation monitor. Respond only with the requested JSON."},
+        {"role": "user", "content": prompt},
+    ]
+    log_entry: dict[str, Any] = {
+        "timestamp": time.time(),
+        "label": f"orchestrator:{label}",
+        "model": resolved["model_id"],
+        "request": {"messages": messages},
+    }
+
+    result = await openai_chat_completion(
+        base_url=resolved["base_url"],
+        api_key=resolved["api_key"],
+        model=resolved["model_id"],
+        messages=messages,
+        temperature=0.2,
+        max_tokens=256,
+        timeout=20,
+    )
+
+    log_entry["response"] = result
+    session.api_log.append(log_entry)
+
+    return result.get("response", "")
+
+
+def _parse_json_bool(raw: str, key: str) -> bool:
+    try:
+        raw = raw.strip()
+        if raw.startswith("```"):
+            raw = raw.split("\n", 1)[-1].rsplit("```", 1)[0]
+        return json.loads(raw).get(key, False)
+    except Exception:
+        lower = raw.lower()
+        return f'"{key}": true' in lower or f'"{key}":true' in lower
+
+
+# ---------------------------------------------------------------------------
+# Main conversation loop (yields SSE events)
+# ---------------------------------------------------------------------------
+
+async def run_conversation(
+    session: Session,
+    starter_text: str | None = None,
+) -> AsyncIterator[str]:
+    pa = session.persona_a
+    pb = session.persona_b
+    if not pa or not pb:
+        yield _sse("error", {"message": "Both personas must be configured"})
+        return
+
+    participants = [pa, pb]
+    starter_idx = random.randint(0, 1)
+    starter = participants[starter_idx]
+    responder = participants[1 - starter_idx]
+
+    yield _sse("status", {"message": "Starting conversation..."})
+
+    # --- First message ---
+    if starter_text:
+        # Show the user-provided starter as the first message from the starter LLM,
+        # then send it to the responder to reply to (no LLM call for the opener).
+        _add_message(session, starter, starter_text.strip(), starter_idx)
+        yield _sse("message", _msg_payload(session.messages[-1], starter_idx))
+
+        reply_prompt = FIRST_REPLY_PROMPT.format(last_message=starter_text.strip())
+        second_msg, second_elapsed = await _call_llm(
+            responder, responder.role_prompt, reply_prompt, session,
+            label=f"first_reply:{responder.name}",
+        )
+        _add_message(session, responder, second_msg, 1 - starter_idx, second_elapsed)
+        yield _sse("message", _msg_payload(session.messages[-1], 1 - starter_idx))
+    else:
+        user_prompt = AUTO_START_PROMPT.format(other_role=responder.role_prompt)
+        first_msg, first_elapsed = await _call_llm(
+            starter, starter.role_prompt, user_prompt, session,
+            label=f"start:{starter.name}",
+        )
+        _add_message(session, starter, first_msg, starter_idx, first_elapsed)
+        yield _sse("message", _msg_payload(session.messages[-1], starter_idx))
+
+        reply_prompt = FIRST_REPLY_PROMPT.format(last_message=first_msg)
+        second_msg, second_elapsed = await _call_llm(
+            responder, responder.role_prompt, reply_prompt, session,
+            label=f"first_reply:{responder.name}",
+        )
+        _add_message(session, responder, second_msg, 1 - starter_idx, second_elapsed)
+        yield _sse("message", _msg_payload(session.messages[-1], 1 - starter_idx))
+
+    # --- Continue loop ---
+    current_idx = starter_idx
+    while not session.finished:
+        current = participants[current_idx]
+        history_text = _format_history(session.messages)
+
+        # Check orchestrator on the last message
+        last_msg_text = session.messages[-1]["text"]
+
+        if not session.end_mode:
+            orch_raw = await _call_orchestrator(
+                ORCHESTRATOR_CHECK_PROMPT.format(message=last_msg_text),
+                session,
+                label="winding_check",
+            )
+            winding = _parse_json_bool(orch_raw, "winding_down")
+
+            if winding:
+                session.end_mode = True
+
+        # Force wrap-up at 8 messages each
+        if not session.end_mode:
+            if session.a_count >= 8 and session.b_count >= 8:
+                session.end_mode = True
+
+        if session.end_mode:
+            # Penultimate message: current speaker wraps up
+            history_text = _format_history(session.messages)
+            wrap_msg, wrap_elapsed = await _call_llm(
+                current, current.role_prompt,
+                WINDING_NEXT_PROMPT.format(history=history_text),
+                session, label=f"winding_next:{current.name}",
+            )
+            _add_message(session, current, wrap_msg, current_idx, wrap_elapsed)
+            yield _sse("message", _msg_payload(session.messages[-1], current_idx))
+
+            # Final message: other speaker closes
+            other_idx = 1 - current_idx
+            other = participants[other_idx]
+            history_text = _format_history(session.messages)
+            final_msg, final_elapsed = await _call_llm(
+                other, other.role_prompt,
+                WINDING_FINAL_PROMPT.format(history=history_text),
+                session, label=f"winding_final:{other.name}",
+            )
+            _add_message(session, other, final_msg, other_idx, final_elapsed)
+            yield _sse("message", _msg_payload(session.messages[-1], other_idx))
+
+            session.finished = True
+            yield _sse("system", {"text": "End of Chat"})
+            break
+
+        # Normal continue
+        prompt = CONTINUE_PROMPT.format(history=history_text)
+        response, resp_elapsed = await _call_llm(
+            current, current.role_prompt, prompt, session,
+            label=f"continue:{current.name}",
+        )
+        _add_message(session, current, response, current_idx, resp_elapsed)
+        yield _sse("message", _msg_payload(session.messages[-1], current_idx))
+
+        current_idx = 1 - current_idx
+
+    yield _sse("done", {})
+
+
+# ---------------------------------------------------------------------------
+# SSE helpers
+# ---------------------------------------------------------------------------
+
+def _add_message(session: Session, persona: Persona, text: str, speaker_idx: int, elapsed: float = 0) -> None:
+    session.messages.append({
+        "speaker": persona.name,
+        "speaker_idx": speaker_idx,
+        "model_id": persona.model_id,
+        "model_display": persona.display_name,
+        "text": text,
+        "timestamp": time.time(),
+        "elapsed_seconds": round(elapsed, 2),
+    })
+    if speaker_idx == 0:
+        session.a_count += 1
+    else:
+        session.b_count += 1
+
+
+def _msg_payload(msg: dict, speaker_idx: int) -> dict:
+    return {
+        "speaker": msg["speaker"],
+        "speaker_idx": speaker_idx,
+        "model_display": msg["model_display"],
+        "text": msg["text"],
+        "timestamp": msg["timestamp"],
+        "elapsed_seconds": msg.get("elapsed_seconds", 0),
+    }
+
+
+def _sse(event: str, data: dict) -> str:
+    return f"event: {event}\ndata: {json.dumps(data)}\n\n"

backend/app/services/persona.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import logging
+
+from app.clients.llm_router import chat_completion
+from app.config import settings
+
+LOG = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Structured input prompts
+# ---------------------------------------------------------------------------
+
+STRUCTURED_AI_COMPLETED_PROMPT = (
+    "You will receive structured information about a character or persona: a name, an identity "
+    "statement, a profile, and optionally writing/speech samples. Some fields may be sparse or "
+    "missing. Write a complete, vivid 3-5 sentence role prompt that an LLM can use to "
+    "convincingly embody this persona in a conversation.\n\n"
+    "If any fields are sparse, infer plausible personality traits, speech patterns, interests, "
+    "and conversational style from whatever clues are available. Fill in realistic detail so "
+    "the role prompt is rich and actionable — never produce a vague or skeletal prompt.\n\n"
+    "Cover: personality, tone and speech patterns, background/expertise, interests and "
+    "motivations, and how they would naturally interact in a casual conversation.\n\n"
+    "The name is: {name}\n"
+    "The identity statement is: {identity}\n"
+    "The profile is: {profile}\n"
+    "Here are the writing and/or speech samples: {samples}"
+)
+
+STRUCTURED_EXACT_PROMPT = (
+    "You will receive structured information about a character or persona: a name, an identity "
+    "statement, a profile, and optionally writing/speech samples. Combine this information into "
+    "a coherent 3-5 sentence role prompt that an LLM can use to embody this persona in a "
+    "conversation.\n\n"
+    "IMPORTANT: Use ONLY the information explicitly provided. Do not invent, assume, or infer "
+    "any traits, background, opinions, or speech patterns beyond what is stated. Your job is "
+    "purely to organize and lightly rephrase the provided facts into a smooth, usable role "
+    "prompt — add linking words and natural sentence flow, but no new content. If a field is "
+    "empty or says '(not provided)', simply omit it.\n\n"
+    "The name is: {name}\n"
+    "The identity statement is: {identity}\n"
+    "The profile is: {profile}\n"
+    "Here are the writing and/or speech samples: {samples}"
+)
+
+# ---------------------------------------------------------------------------
+# Freeform input prompts
+# ---------------------------------------------------------------------------
+
+FREEFORM_AI_COMPLETED_PROMPT = (
+    "You will receive freeform information about a character or persona. The input may be "
+    "detailed (with writing samples, background, etc.) or very brief (just a name or a short "
+    "description). Regardless of how much is provided, write a complete, vivid 3-5 sentence "
+    "role prompt that an LLM can use to convincingly embody this persona in a conversation.\n\n"
+    "If the input is sparse, infer plausible personality traits, speech patterns, interests, "
+    "and conversational style from whatever clues are available (the name, any title or "
+    "occupation, context, etc.). Fill in realistic detail so the role prompt is rich and "
+    "actionable — never produce a vague or skeletal prompt.\n\n"
+    "Cover: personality, tone and speech patterns, background/expertise, interests and "
+    "motivations, and how they would naturally interact in a casual conversation.\n\n"
+    "The persona's name is: {name}\n\n"
+    "Here is everything provided about this persona:\n"
+    "---\n{text}\n---"
+)
+
+FREEFORM_EXACT_PROMPT = (
+    "You will receive freeform information about a character or persona. Combine this "
+    "information into a coherent 3-5 sentence role prompt that an LLM can use to embody "
+    "this persona in a conversation.\n\n"
+    "IMPORTANT: Use ONLY the information explicitly provided. Do not invent, assume, or infer "
+    "any traits, background, opinions, or speech patterns beyond what is stated. Your job is "
+    "purely to organize and lightly rephrase the user's text into a smooth, usable role "
+    "prompt — add linking words and natural sentence flow, but no new content. If very little "
+    "was provided, the role prompt should be correspondingly brief.\n\n"
+    "The persona's name is: {name}\n\n"
+    "Here is everything provided about this persona:\n"
+    "---\n{text}\n---"
+)
+
+
+async def _call_llm(model_id: str, prompt_text: str) -> dict:
+    resolved = settings.resolve_model(model_id)
+    if not resolved:
+        return {"role_prompt": "", "error": f"Unknown model: {model_id}"}
+
+    messages = [
+        {"role": "system", "content": (
+            "You are a helpful assistant that creates character prompts. "
+            "Respond ONLY with the finished role prompt text. Do NOT include your reasoning, "
+            "thought process, analysis, draft notes, or any meta-commentary."
+        )},
+        {"role": "user", "content": prompt_text},
+    ]
+
+    result = await chat_completion(
+        resolved=resolved,
+        messages=messages,
+        temperature=0.7,
+        max_tokens=512,
+        timeout=45,
+    )
+
+    if result.get("error"):
+        return {"role_prompt": "", "error": result["response"]}
+
+    return {
+        "role_prompt": result["response"],
+        "elapsed_seconds": result["elapsed_seconds"],
+    }
+
+
+async def generate_role_prompt(
+    model_id: str,
+    name: str,
+    profile: str,
+    identity: str,
+    samples: str,
+    role_style: str = "exact",
+) -> dict:
+    """Use the selected LLM to distill structured persona inputs into a role prompt."""
+    template = STRUCTURED_AI_COMPLETED_PROMPT if role_style == "ai_completed" else STRUCTURED_EXACT_PROMPT
+    prompt_text = template.format(
+        name=name or "(not provided)",
+        identity=identity or "(not provided)",
+        profile=profile or "(not provided)",
+        samples=samples or "(not provided)",
+    )
+    return await _call_llm(model_id, prompt_text)
+
+
+async def generate_role_prompt_freeform(
+    model_id: str,
+    name: str,
+    text: str,
+    role_style: str = "ai_completed",
+) -> dict:
+    """Use the selected LLM to distill a single freeform text block into a role prompt."""
+    template = FREEFORM_AI_COMPLETED_PROMPT if role_style == "ai_completed" else FREEFORM_EXACT_PROMPT
+    prompt_text = template.format(
+        name=name or "(not provided)",
+        text=text or "(not provided)",
+    )
+    return await _call_llm(model_id, prompt_text)

backend/requirements.txt

@@ -0,0 +1,8 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+httpx>=0.27.0
+pydantic-settings>=2.6.0
+python-multipart>=0.0.12
+python-dotenv>=1.0.0
+huggingface_hub>=0.25.0
+itsdangerous>=2.2.0

docker-compose.yml

@@ -0,0 +1,10 @@
+services:
+  app:
+    build: .
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    environment:
+      CORS_ORIGINS: "http://localhost:8000,http://localhost:3000"
+    restart: unless-stopped

frontend/.gitignore

@@ -0,0 +1,23 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

frontend/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {
+    "lucide-react": "^0.577.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "react-scripts": "5.0.1",
+    "remark-gfm": "^4.0.1"
+  },
+  "scripts": {
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "test": "react-scripts test",
+    "eject": "react-scripts eject"
+  },
+  "eslintConfig": {
+    "extends": "react-app"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

frontend/public/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <link rel="icon" type="image/png" href="/neon-logo.png" />
+  <meta name="theme-color" content="#6366F1" />
+  <meta name="description" content="Neon.ai - AI to AI Conversations" />
+  <title>Neon.ai - AI to AI Conversations</title>
+</head>
+<body>
+  <div id="root"></div>
+</body>
+</html>

frontend/public/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "React App",
+  "name": "Create React App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

frontend/public/robots.txt

@@ -0,0 +1,2 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *

frontend/src/App.js

@@ -0,0 +1,381 @@
+import React, { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { Sun, Moon } from 'lucide-react';
+import LLMSelector from './components/LLMSelector';
+import PersonaAccordion from './components/PersonaAccordion';
+import ChatControls from './components/ChatControls';
+import ChatArea from './components/ChatArea';
+import DevMenu from './components/DevMenu';
+import AuthBadge from './components/AuthBadge';
+import { fetchModels, generateRole, generateRoleFreeform, startChat, getOrchestrator, setOrchestrator, getSpeedPriority, setSpeedPriority, exportChat, exportApiLog, getAuthStatus } from './utils/api';
+import './styles/variables.css';
+import './styles/layout.css';
+import './styles/components.css';
+
+const EMPTY_PERSONA = { name: '', profile: '', identity: '', samples: '' };
+
+function getDisplayName(modelId, providers, neonModels) {
+  if (!modelId) return '';
+  if (modelId.startsWith('neon:')) {
+    return modelId.split(':')[2] || modelId;
+  }
+  for (const p of (providers || [])) {
+    for (const m of p.models) {
+      if (m.id === modelId) return m.name;
+    }
+  }
+  return modelId;
+}
+
+export default function App() {
+  const [theme, setTheme] = useState(() =>
+    window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+  );
+  const [providers, setProviders] = useState([]);
+  const [neonModels, setNeonModels] = useState([]);
+  const [selections, setSelections] = useState([]);
+  const [personaA, setPersonaA] = useState({ ...EMPTY_PERSONA });
+  const [personaB, setPersonaB] = useState({ ...EMPTY_PERSONA });
+  const [accordionOpen, setAccordionOpen] = useState(true);
+  const [messages, setMessages] = useState([]);
+  const [systemMessages, setSystemMessages] = useState([]);
+  const [isRunning, setIsRunning] = useState(false);
+  const [statusText, setStatusText] = useState('');
+  const [sessionId, setSessionId] = useState(null);
+  const [chatFinished, setChatFinished] = useState(false);
+  const [orchestratorModel, setOrchestratorModel] = useState('');
+  const [personaMode, setPersonaMode] = useState('freeform');
+  const [roleStyle, setRoleStyle] = useState('ai_completed');
+  const [speedPriority, setSpeedPriorityState] = useState(false);
+  const [auth, setAuth] = useState(null);
+  const [showResponseTime, setShowResponseTime] = useState(false);
+  const [showChatStats, setShowChatStats] = useState(false);
+  const [rolePrompts, setRolePrompts] = useState(null);
+  const [rolePromptsOpen, setRolePromptsOpen] = useState(false);
+  const abortRef = useRef(null);
+  const lastRoleConfigRef = useRef(null);
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+  }, [theme]);
+
+
+
+  useEffect(() => {
+    fetchModels()
+      .then(data => {
+        setProviders(data.providers || []);
+        setNeonModels(data.neon_models || []);
+      })
+      .catch(err => console.error('Failed to load models:', err));
+    getOrchestrator()
+      .then(data => setOrchestratorModel(data.model_id || ''))
+      .catch(() => {});
+    getSpeedPriority()
+      .then(data => setSpeedPriorityState(!!data.enabled))
+      .catch(() => {});
+    getAuthStatus().then(setAuth).catch(() => {});
+  }, []);
+
+  const allModelsFlat = useMemo(() => {
+    const list = [];
+    for (const p of providers) {
+      for (const m of p.models) {
+        list.push({ id: m.id, name: m.name, provider: p.name });
+      }
+    }
+    for (const nm of neonModels) {
+      for (const p of (nm.personas || [])) {
+        if (p.enabled === false) continue;
+        list.push({
+          id: `neon:${nm.model_id}:${p.persona_name}`,
+          name: p.persona_name,
+          provider: `Neon / ${nm.name.split('/').pop()}`,
+        });
+      }
+    }
+    return list;
+  }, [providers, neonModels]);
+
+  const handleOrchestratorChange = useCallback(async (modelId) => {
+    try {
+      await setOrchestrator(modelId || '');
+      setOrchestratorModel(modelId || '');
+    } catch (err) {
+      console.error('Failed to set orchestrator:', err);
+    }
+  }, []);
+
+  const handlePersonaModeChange = useCallback((mode) => {
+    setPersonaMode(mode);
+    setRoleStyle(mode === 'freeform' ? 'ai_completed' : 'exact');
+  }, []);
+
+  const handleSpeedPriorityChange = useCallback(async (enabled) => {
+    try {
+      await setSpeedPriority(enabled);
+      setSpeedPriorityState(enabled);
+    } catch (err) {
+      console.error('Failed to set speed priority:', err);
+    }
+  }, []);
+
+  const downloadFile = useCallback((filename, content) => {
+    const blob = new Blob([content], { type: 'text/plain;charset=utf-8' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+  }, []);
+
+  const handleDownloadTxt = useCallback(async () => {
+    if (!sessionId) return;
+    try {
+      const result = await exportChat(sessionId, 'txt');
+      downloadFile(result.filename, result.content);
+    } catch (err) { console.error('Export failed:', err); }
+  }, [sessionId, downloadFile]);
+
+  const handleDownloadMd = useCallback(async () => {
+    if (!sessionId) return;
+    try {
+      const result = await exportChat(sessionId, 'md');
+      downloadFile(result.filename, result.content);
+    } catch (err) { console.error('Export failed:', err); }
+  }, [sessionId, downloadFile]);
+
+  const handleDownloadApiLog = useCallback(async () => {
+    if (!sessionId) return;
+    try {
+      const result = await exportApiLog(sessionId);
+      downloadFile('api_log.json', JSON.stringify(result, null, 2));
+    } catch (err) { console.error('API log export failed:', err); }
+  }, [sessionId, downloadFile]);
+
+  const selectedNameA = selections[0] ? getDisplayName(selections[0], providers, neonModels) : '';
+  const selectedNameB = selections[1] ? getDisplayName(selections[1], providers, neonModels) : '';
+
+  const canStart = selections.length === 2 && !isRunning;
+
+  const handleStop = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+      abortRef.current = null;
+    }
+    setIsRunning(false);
+    setChatFinished(true);
+    setStatusText('');
+    setSystemMessages(prev => [...prev, { text: 'Chat stopped by user.' }]);
+  }, []);
+
+  const handleStart = useCallback(async (starterText) => {
+    if (selections.length < 2) return;
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setIsRunning(true);
+    setAccordionOpen(false);
+    setMessages([]);
+    setSystemMessages([]);
+    setChatFinished(false);
+
+    try {
+      const currentConfig = JSON.stringify({
+        selections, personaMode, roleStyle,
+        a: personaMode === 'freeform'
+          ? { name: personaA.name, freeform: personaA.freeform || '' }
+          : { name: personaA.name, profile: personaA.profile, identity: personaA.identity, samples: personaA.samples },
+        b: personaMode === 'freeform'
+          ? { name: personaB.name, freeform: personaB.freeform || '' }
+          : { name: personaB.name, profile: personaB.profile, identity: personaB.identity, samples: personaB.samples },
+      });
+
+      let cachedPrompts = rolePrompts;
+      const configChanged = currentConfig !== lastRoleConfigRef.current;
+
+      if (configChanged || !cachedPrompts) {
+        setStatusText('Generating expert persona roles...');
+
+        const genA = personaMode === 'freeform'
+          ? generateRoleFreeform({ model_id: selections[0], name: personaA.name, text: personaA.freeform || '', role_style: roleStyle })
+          : generateRole({ model_id: selections[0], name: personaA.name, profile: personaA.profile, identity: personaA.identity, samples: personaA.samples, role_style: roleStyle });
+        const genB = personaMode === 'freeform'
+          ? generateRoleFreeform({ model_id: selections[1], name: personaB.name, text: personaB.freeform || '', role_style: roleStyle })
+          : generateRole({ model_id: selections[1], name: personaB.name, profile: personaB.profile, identity: personaB.identity, samples: personaB.samples, role_style: roleStyle });
+
+        const [roleA, roleB] = await Promise.all([genA, genB]);
+
+        if (controller.signal.aborted) return;
+
+        cachedPrompts = {
+          a: { name: personaA.name || 'Expert Persona A', model: getDisplayName(selections[0], providers, neonModels), prompt: roleA.role_prompt },
+          b: { name: personaB.name || 'Expert Persona B', model: getDisplayName(selections[1], providers, neonModels), prompt: roleB.role_prompt },
+        };
+        setRolePrompts(cachedPrompts);
+        lastRoleConfigRef.current = currentConfig;
+      }
+
+      setStatusText('Starting conversation...');
+
+      await startChat(
+        {
+          persona_a_model_id: selections[0],
+          persona_a_name: cachedPrompts.a.name,
+          persona_a_role: cachedPrompts.a.prompt,
+          persona_b_model_id: selections[1],
+          persona_b_name: cachedPrompts.b.name,
+          persona_b_role: cachedPrompts.b.prompt,
+          starter_text: starterText,
+        },
+        {
+          onSession: (data) => setSessionId(data.session_id),
+          onMessage: (data) => {
+            setMessages(prev => [...prev, data]);
+            setStatusText('Conversation in progress...');
+          },
+          onSystem: (data) => {
+            setSystemMessages(prev => [...prev, data]);
+            if (data.text === 'End of Chat') {
+              setChatFinished(true);
+              setStatusText('');
+            }
+          },
+          onStatus: (data) => setStatusText(data.message || ''),
+          onError: (data) => {
+            setStatusText('');
+            setSystemMessages(prev => [...prev, { text: `Error: ${data.message}` }]);
+          },
+          onDone: () => {
+            setIsRunning(false);
+            setStatusText('');
+          },
+        },
+        controller.signal,
+      );
+    } catch (err) {
+      if (err.name === 'AbortError') return;
+      console.error('Chat error:', err);
+      const isRateLimit = err.message && err.message.includes('Daily conversation limit');
+      setSystemMessages(prev => [...prev, {
+        text: isRateLimit
+          ? 'Daily conversation limit reached (20/day). Sign in with HuggingFace for unlimited access.'
+          : `Error: ${err.message}`,
+      }]);
+    } finally {
+      setIsRunning(false);
+      abortRef.current = null;
+      getAuthStatus().then(setAuth).catch(() => {});
+    }
+  }, [selections, personaA, personaB, personaMode, roleStyle, rolePrompts]);
+
+  return (
+    <div className="app">
+      <header className="app-header">
+        <div className="header-left">
+          <a href="https://www.neon.ai/" target="_blank" rel="noopener noreferrer" className="header-brand-link">
+            <img src="/neon-logo.png" alt="Neon.ai" className="app-logo" />
+          </a>
+          <h1 className="app-title"><a href="https://www.neon.ai/" target="_blank" rel="noopener noreferrer" className="app-title-link">Neon.ai</a> - AI to AI Conversations</h1>
+        </div>
+        <div className="header-right">
+          <AuthBadge auth={auth} />
+          <button
+            className="icon-btn"
+            onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}
+            title="Toggle theme"
+          >
+            {theme === 'light' ? <Moon size={16} /> : <Sun size={16} />}
+          </button>
+          <DevMenu
+            allModels={allModelsFlat}
+            orchestratorModel={orchestratorModel}
+            onOrchestratorChange={handleOrchestratorChange}
+            personaMode={personaMode}
+            onPersonaModeChange={handlePersonaModeChange}
+            roleStyle={roleStyle}
+            onRoleStyleChange={setRoleStyle}
+            speedPriority={speedPriority}
+            onSpeedPriorityChange={handleSpeedPriorityChange}
+            showResponseTime={showResponseTime}
+            onShowResponseTimeChange={setShowResponseTime}
+            showChatStats={showChatStats}
+            onShowChatStatsChange={setShowChatStats}
+            rolePrompts={rolePrompts}
+            onShowRolePrompts={() => setRolePromptsOpen(true)}
+            onDownloadChatTxt={handleDownloadTxt}
+            onDownloadChatMd={handleDownloadMd}
+            onDownloadApiLog={handleDownloadApiLog}
+            hasChat={messages.length > 0}
+            hasApiLog={!!sessionId}
+          />
+        </div>
+      </header>
+
+      <main className="app-main">
+        <LLMSelector
+          providers={providers}
+          neonModels={neonModels}
+          selections={selections}
+          onSelectionsChange={setSelections}
+        />
+
+        <div className="content">
+          <PersonaAccordion
+            isOpen={accordionOpen}
+            onToggle={() => setAccordionOpen(o => !o)}
+            personaA={personaA}
+            personaB={personaB}
+            onChangeA={setPersonaA}
+            onChangeB={setPersonaB}
+            selectedNameA={selectedNameA}
+            selectedNameB={selectedNameB}
+            mode={personaMode}
+          />
+
+          <ChatControls
+            onStart={handleStart}
+            onStop={handleStop}
+            disabled={!canStart}
+            isRunning={isRunning}
+          />
+
+          <ChatArea
+            messages={messages}
+            systemMessages={systemMessages}
+            isRunning={isRunning}
+            statusText={statusText}
+            showResponseTime={showResponseTime}
+            showChatStats={showChatStats}
+          />
+        </div>
+      </main>
+      <footer className="app-footer">
+        Copyright Neon.ai. All rights reserved.{' '}
+        <a href="https://www.neon.ai/contact" target="_blank" rel="noopener noreferrer">Patents and licensing</a>
+      </footer>
+
+      {rolePromptsOpen && rolePrompts && (
+        <div className="modal-overlay" onClick={() => setRolePromptsOpen(false)}>
+          <div className="modal-content" onClick={e => e.stopPropagation()}>
+            <div className="modal-header">
+              <h2>Generated Role Prompts</h2>
+              <button className="modal-close" onClick={() => setRolePromptsOpen(false)}>&times;</button>
+            </div>
+            <div className="modal-body">
+              <div className="role-prompt-section">
+                <h3>{rolePrompts.a.name} <span className="role-prompt-model">({rolePrompts.a.model})</span></h3>
+                <pre className="role-prompt-text">{rolePrompts.a.prompt}</pre>
+              </div>
+              <div className="role-prompt-section">
+                <h3>{rolePrompts.b.name} <span className="role-prompt-model">({rolePrompts.b.model})</span></h3>
+                <pre className="role-prompt-text">{rolePrompts.b.prompt}</pre>
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/AuthBadge.js

@@ -0,0 +1,33 @@
+import React from 'react';
+import { LogIn, LogOut, User } from 'lucide-react';
+
+export default function AuthBadge({ auth }) {
+  if (!auth) return null;
+
+  if (auth.logged_in) {
+    return (
+      <div className="auth-badge">
+        <User size={14} />
+        <span className="auth-username">{auth.username}</span>
+        {auth.is_org_member && <span className="auth-org-tag">org</span>}
+        {!auth.is_org_member && auth.remaining_conversations >= 0 && (
+          <span className="auth-remaining">{auth.remaining_conversations} left</span>
+        )}
+        <a href="/oauth/huggingface/logout" className="auth-link" title="Sign out">
+          <LogOut size={13} />
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="auth-badge">
+      {auth.remaining_conversations >= 0 && (
+        <span className="auth-remaining">{auth.remaining_conversations}/20 chats</span>
+      )}
+      <a href="/oauth/huggingface/login" className="auth-link auth-login">
+        <LogIn size={13} /> Sign in
+      </a>
+    </div>
+  );
+}

frontend/src/components/ChatArea.js

@@ -0,0 +1,57 @@
+import React, { useEffect, useRef, useMemo } from 'react';
+import MessageBubble from './MessageBubble';
+
+export default function ChatArea({ messages, systemMessages, isRunning, statusText, showResponseTime, showChatStats }) {
+  const endRef = useRef(null);
+
+  useEffect(() => {
+    endRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [messages, systemMessages]);
+
+  const hasContent = messages.length > 0 || systemMessages.length > 0;
+  const chatEnded = systemMessages.some(s => s.text === 'End of Chat');
+
+  const stats = useMemo(() => {
+    if (!chatEnded || messages.length === 0) return null;
+    const totalTime = messages.reduce((sum, m) => sum + (m.elapsed_seconds || 0), 0);
+    return { count: messages.length, totalTime: totalTime.toFixed(1) };
+  }, [chatEnded, messages]);
+
+  return (
+    <div className="chat-area">
+      {!hasContent && !isRunning && (
+        <div className="chat-empty">
+          Select two LLMs, configure expert personas, and start a conversation.
+        </div>
+      )}
+
+      {messages.map((msg, i) => (
+        <MessageBubble key={i} message={msg} showResponseTime={showResponseTime} />
+      ))}
+
+      {systemMessages.map((sys, i) => (
+        <div
+          key={`sys-${i}`}
+          className={`system-message ${sys.text === 'End of Chat' ? 'end-of-chat' : ''}`}
+        >
+          {sys.text}
+        </div>
+      ))}
+
+      {showChatStats && stats && (
+        <div className="chat-stats">
+          {stats.count} messages &middot; {stats.totalTime}s total generation time
+        </div>
+      )}
+
+      {isRunning && statusText && (
+        <div className="status-bar">
+          <div className="spinner" />
+          <span>{statusText}</span>
+        </div>
+      )}
+
+      <div ref={endRef} />
+    </div>
+  );
+}

frontend/src/components/ChatControls.js

@@ -0,0 +1,56 @@
+import React, { useState } from 'react';
+import { Play, Shuffle, Square } from 'lucide-react';
+
+export default function ChatControls({ onStart, onStop, disabled, isRunning }) {
+  const [starterText, setStarterText] = useState('');
+
+  const handleStartWithText = () => {
+    onStart(starterText.trim() || null);
+  };
+
+  const handleAutoStart = () => {
+    onStart(null);
+  };
+
+  return (
+    <div className="chat-controls">
+      {isRunning ? (
+        <button className="btn-stop" onClick={onStop} title="Stop the conversation">
+          <Square size={14} style={{ verticalAlign: 'middle', marginRight: 4 }} />
+          Stop Chat
+        </button>
+      ) : (
+        <>
+          <button
+            className="btn-primary"
+            onClick={handleAutoStart}
+            disabled={disabled}
+            title="Let the LLMs start on their own"
+          >
+            <Shuffle size={14} style={{ verticalAlign: 'middle', marginRight: 4 }} />
+            Let Them Start
+          </button>
+          <input
+            type="text"
+            placeholder="Let them start on their own, or enter a conversation starter here"
+            value={starterText}
+            onChange={e => setStarterText(e.target.value)}
+            disabled={disabled}
+            onKeyDown={e => {
+              if (e.key === 'Enter' && !disabled) handleStartWithText();
+            }}
+          />
+          <button
+            className="btn-primary"
+            onClick={handleStartWithText}
+            disabled={disabled}
+            title="Start with your message"
+          >
+            <Play size={14} style={{ verticalAlign: 'middle', marginRight: 4 }} />
+            Start Chat With My Prompt
+          </button>
+        </>
+      )}
+    </div>
+  );
+}

frontend/src/components/DevMenu.js

@@ -0,0 +1,207 @@
+import React, { useState, useMemo, useRef, useEffect } from 'react';
+import { ChevronRight, Download, Settings2, Search, Check, Eye, EyeOff, FileText, Square, CheckSquare } from 'lucide-react';
+
+export default function DevMenu({
+  allModels,
+  orchestratorModel,
+  onOrchestratorChange,
+  personaMode,
+  onPersonaModeChange,
+  roleStyle,
+  onRoleStyleChange,
+  speedPriority,
+  onSpeedPriorityChange,
+  showResponseTime,
+  onShowResponseTimeChange,
+  showChatStats,
+  onShowChatStatsChange,
+  rolePrompts,
+  onShowRolePrompts,
+  onDownloadApiLog,
+  onDownloadChatTxt,
+  onDownloadChatMd,
+  hasApiLog,
+  hasChat,
+}) {
+  const [open, setOpen] = useState(false);
+  const [orchOpen, setOrchOpen] = useState(false);
+  const [q, setQ] = useState('');
+  const wrapRef = useRef(null);
+  const searchRef = useRef(null);
+
+  useEffect(() => {
+    if (orchOpen && searchRef.current) searchRef.current.focus();
+  }, [orchOpen]);
+
+  useEffect(() => {
+    function handleClickOutside(e) {
+      if (wrapRef.current && !wrapRef.current.contains(e.target)) {
+        setOpen(false);
+        setOrchOpen(false);
+        setQ('');
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  const filtered = useMemo(() => {
+    const s = q.trim().toLowerCase();
+    if (!s) return allModels;
+    return allModels.filter(row => {
+      const hay = `${row.name} ${row.id} ${row.provider || ''}`.toLowerCase();
+      return hay.includes(s);
+    });
+  }, [allModels, q]);
+
+  const currentName = useMemo(() => {
+    if (!orchestratorModel) return 'Default (backend)';
+    const m = allModels.find(m => m.id === orchestratorModel);
+    return m ? m.name : orchestratorModel;
+  }, [orchestratorModel, allModels]);
+
+  return (
+    <div className="dev-wrap" ref={wrapRef}>
+      <div className="dev-download-btns">
+        <button className="btn-sm btn-outline" disabled={!hasChat} onClick={onDownloadChatTxt}>
+          <Download size={14} /> .txt
+        </button>
+        <button className="btn-sm btn-outline" disabled={!hasChat} onClick={onDownloadChatMd}>
+          <Download size={14} /> .md
+        </button>
+      </div>
+
+      <div className="dev-dropdown-header">
+        <button className="icon-btn" onClick={() => { setOpen(o => !o); setOrchOpen(false); setQ(''); }} title="Settings">
+          <Settings2 size={16} />
+        </button>
+        {open && (
+          <div className="dev-panel">
+            <button onClick={() => { setOrchOpen(o => !o); setQ(''); }}>
+              Orchestrator model… <ChevronRight size={12} style={{ marginLeft: 'auto', opacity: 0.5 }} />
+            </button>
+            <div className="dev-panel-divider" />
+            <div className="dev-panel-label">Response priority</div>
+            <button
+              className={`dev-panel-choice ${!speedPriority ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onSpeedPriorityChange(false)}
+            >
+              {!speedPriority ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              Prioritize model choice
+            </button>
+            <button
+              className={`dev-panel-choice ${speedPriority ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onSpeedPriorityChange(true)}
+            >
+              {speedPriority ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              Prioritize conversation speed
+            </button>
+            <div className="dev-panel-divider" />
+            <div className="dev-panel-label">Expert persona input</div>
+            <button
+              className={`dev-panel-choice ${personaMode === 'structured' ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onPersonaModeChange('structured')}
+            >
+              {personaMode === 'structured' ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              Structured expert persona input
+            </button>
+            <button
+              className={`dev-panel-choice ${personaMode === 'freeform' ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onPersonaModeChange('freeform')}
+            >
+              {personaMode === 'freeform' ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              Freeform expert persona input
+            </button>
+            <div className="dev-panel-divider" />
+            <div className="dev-panel-label">Role generation</div>
+            <button
+              className={`dev-panel-choice ${roleStyle === 'ai_completed' ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onRoleStyleChange('ai_completed')}
+            >
+              {roleStyle === 'ai_completed' ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              AI completed roles
+            </button>
+            <button
+              className={`dev-panel-choice ${roleStyle === 'exact' ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onRoleStyleChange('exact')}
+            >
+              {roleStyle === 'exact' ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              Exact user roles
+            </button>
+            <div className="dev-panel-divider" />
+            <div className="dev-panel-label">Display options</div>
+            <button
+              className={`dev-panel-choice ${showResponseTime ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onShowResponseTimeChange(!showResponseTime)}
+            >
+              {showResponseTime ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              Response times on messages
+            </button>
+            <button
+              className={`dev-panel-choice ${showChatStats ? 'dev-panel-choice-active' : ''}`}
+              onClick={() => onShowChatStatsChange(!showChatStats)}
+            >
+              {showChatStats ? <CheckSquare size={16} className="dev-check-icon" /> : <Square size={16} className="dev-check-icon" />}
+              Chat stats after end
+            </button>
+            <button className="dev-panel-choice" disabled={!rolePrompts} onClick={() => { onShowRolePrompts(); setOpen(false); }}>
+              <FileText size={14} className="dev-check-icon" />
+              View role prompts
+            </button>
+            <div className="dev-panel-divider" />
+            <button disabled={!hasChat} className="dev-panel-download-item" onClick={() => { onDownloadChatTxt(); setOpen(false); }}>
+              Download chat as .txt
+            </button>
+            <button disabled={!hasChat} className="dev-panel-download-item" onClick={() => { onDownloadChatMd(); setOpen(false); }}>
+              Download chat as .md
+            </button>
+            <button disabled={!hasApiLog} onClick={() => { onDownloadApiLog(); setOpen(false); }}>
+              Download full API history
+            </button>
+          </div>
+        )}
+
+        {open && orchOpen && (
+          <div className="dev-sub-panel">
+            <div className="dev-sub-header">
+              <span className="dev-sub-title">Orchestrator</span>
+              <span className="dev-sub-current">{currentName}</span>
+            </div>
+            <div className="dev-sub-search">
+              <Search size={14} className="dev-sub-search-icon" />
+              <input
+                ref={searchRef}
+                type="search"
+                placeholder="Search models…"
+                value={q}
+                onChange={e => setQ(e.target.value)}
+              />
+            </div>
+            <ul className="dev-sub-list">
+              <li>
+                <button
+                  className={`dev-sub-item ${!orchestratorModel ? 'dev-sub-item-active' : ''}`}
+                  onClick={() => { onOrchestratorChange(null); setOrchOpen(false); setOpen(false); setQ(''); }}
+                >
+                  <strong>Default (backend)</strong>
+                  <span className="dev-sub-provider">Use server default</span>
+                </button>
+              </li>
+              {filtered.map(m => (
+                <li key={m.id}>
+                  <button
+                    className={`dev-sub-item ${orchestratorModel === m.id ? 'dev-sub-item-active' : ''}`}
+                    onClick={() => { onOrchestratorChange(m.id); setOrchOpen(false); setOpen(false); setQ(''); }}
+                  >
+                    <strong>{m.name}</strong>
+                    <span className="dev-sub-provider">{m.provider}</span>
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/src/components/ExportBar.js

@@ -0,0 +1,79 @@
+import React, { useState, useRef, useEffect } from 'react';
+import { Download, Settings } from 'lucide-react';
+import { exportChat, exportApiLog } from '../utils/api';
+
+export default function ExportBar({ sessionId }) {
+  const [devOpen, setDevOpen] = useState(false);
+  const dropdownRef = useRef(null);
+
+  useEffect(() => {
+    const handleClickOutside = (e) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target)) {
+        setDevOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  const downloadFile = (filename, content) => {
+    const blob = new Blob([content], { type: 'text/plain;charset=utf-8' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  const handleExport = async (fmt) => {
+    try {
+      const result = await exportChat(sessionId, fmt);
+      downloadFile(result.filename, result.content);
+    } catch (err) {
+      console.error('Export failed:', err);
+    }
+  };
+
+  const handleApiLogExport = async () => {
+    try {
+      const result = await exportApiLog(sessionId);
+      downloadFile('api_log.json', JSON.stringify(result, null, 2));
+      setDevOpen(false);
+    } catch (err) {
+      console.error('API log export failed:', err);
+    }
+  };
+
+  if (!sessionId) return null;
+
+  return (
+    <div className="export-bar">
+      <button className="btn-secondary" onClick={() => handleExport('txt')}>
+        <Download size={14} style={{ verticalAlign: 'middle', marginRight: 4 }} />
+        Download .txt
+      </button>
+      <button className="btn-secondary" onClick={() => handleExport('md')}>
+        <Download size={14} style={{ verticalAlign: 'middle', marginRight: 4 }} />
+        Download .md
+      </button>
+
+      <div className="dev-dropdown" ref={dropdownRef}>
+        <button
+          className="icon-btn"
+          onClick={() => setDevOpen(o => !o)}
+          title="Developer Options"
+        >
+          <Settings size={16} />
+        </button>
+        {devOpen && (
+          <div className="dev-dropdown-menu">
+            <button onClick={handleApiLogExport}>
+              Download Full API Log
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/src/components/LLMSelector.js

@@ -0,0 +1,159 @@
+import React, { useCallback, useState } from 'react';
+import { Cloud, ChevronDown, ChevronRight, User } from 'lucide-react';
+
+export default function LLMSelector({ providers, neonModels, selections, onSelectionsChange }) {
+  const [openGroups, setOpenGroups] = useState({});
+
+  const toggleGroup = (key) => {
+    setOpenGroups(prev => ({ ...prev, [key]: !prev[key] }));
+  };
+
+  const handleClick = useCallback((modelId) => {
+    onSelectionsChange(prev => {
+      const isSelected = prev.includes(modelId);
+      const isBoth = prev.length === 2 && prev[0] === modelId && prev[1] === modelId;
+
+      if (isBoth) return [];
+
+      if (isSelected) return [modelId, modelId];
+
+      if (prev.length < 2) return [...prev, modelId];
+
+      return [prev[1], modelId];
+    });
+  }, [onSelectionsChange]);
+
+  const getIndicatorClass = (modelId) => {
+    const [a, b] = selections;
+    if (a === modelId && b === modelId) return 'select-indicator double-selected';
+    if (a === modelId) return 'select-indicator selected-a';
+    if (b === modelId) return 'select-indicator selected-b';
+    return 'select-indicator';
+  };
+
+  const getLabel = (modelId) => {
+    const [a, b] = selections;
+    if (a === modelId && b === modelId) return 'AB';
+    if (a === modelId) return 'A';
+    if (b === modelId) return 'B';
+    return '';
+  };
+
+  const shortName = (name) => name.split('/').pop() || name;
+
+  const renderModel = (model) => (
+    <button
+      key={model.id}
+      className="model-btn"
+      onClick={() => handleClick(model.id)}
+    >
+      <div className={getIndicatorClass(model.id)}>
+        {getLabel(model.id) && <span className="selection-label">{getLabel(model.id)}</span>}
+      </div>
+      <span className="model-name">{model.name}</span>
+      {model.params && <span className="model-params">{model.params}</span>}
+    </button>
+  );
+
+  const renderNeonPersona = (persona) => (
+    <button
+      key={persona.id}
+      className="neon-persona-item"
+      onClick={() => handleClick(persona.id)}
+    >
+      <div className={getIndicatorClass(persona.id)}>
+        {getLabel(persona.id) && <span className="selection-label">{getLabel(persona.id)}</span>}
+      </div>
+      <div className="persona-details">
+        <div className="persona-name-row">
+          <User size={12} />
+          {persona.name}
+        </div>
+        {persona.systemPrompt && (
+          <div className="persona-prompt-preview">
+            {persona.systemPrompt.slice(0, 120)}
+            {persona.systemPrompt.length > 120 ? '…' : ''}
+          </div>
+        )}
+        {!persona.systemPrompt && (
+          <div className="persona-prompt-preview">No system prompt (vanilla)</div>
+        )}
+      </div>
+    </button>
+  );
+
+  return (
+    <div className="sidebar">
+      <h2 className="sidebar-title">AI Models</h2>
+
+      {(neonModels || []).length > 0 && (
+        <div className="sidebar-section">
+          <h3 className="selector-title">
+            <img src="/neon-logo.png" alt="" className="selector-title-icon" />
+            Neon.ai Models
+          </h3>
+          <div className="neon-model-list">
+            {[...(neonModels || [])].sort((a, b) => shortName(a.name).localeCompare(shortName(b.name))).map(model => {
+              const key = `neon-${model.model_id}`;
+              const isOpen = !!openGroups[key];
+              const activePersonas = (model.personas || []).filter(p => p.enabled !== false);
+              return (
+                <div key={key} className="neon-model-card">
+                  <button
+                    className="neon-model-header"
+                    onClick={() => toggleGroup(key)}
+                  >
+                    <div className="neon-model-info">
+                      <span className="neon-model-name">{shortName(model.name)}</span>
+                      {model.version && <span className="neon-model-version">v{model.version}</span>}
+                    </div>
+                    <div className="neon-model-meta">
+                      {isOpen ? <ChevronDown size={16} /> : <ChevronRight size={16} />}
+                    </div>
+                  </button>
+                  {isOpen && (
+                    <div className="neon-persona-list">
+                      {activePersonas.map(persona => renderNeonPersona({
+                        id: `neon:${model.model_id}:${persona.persona_name}`,
+                        name: persona.persona_name,
+                        systemPrompt: persona.system_prompt || '',
+                      }))}
+                    </div>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      )}
+
+      {(providers || []).length > 0 && (
+        <div className="sidebar-section">
+          <h3 className="selector-title">
+            <Cloud size={16} />
+            Other Models
+          </h3>
+          {[...(providers || [])].sort((a, b) => a.name.localeCompare(b.name)).map(provider => {
+            const key = `prov-${provider.id}`;
+            const isOpen = !!openGroups[key];
+            return (
+              <div key={key} className="provider-group comp-group">
+                <button className="provider-accordion-header" onClick={() => toggleGroup(key)}>
+                  <span className="provider-accordion-title">{provider.name}</span>
+                  <span className="provider-accordion-meta">
+                    {isOpen ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
+                  </span>
+                </button>
+                {isOpen && (
+                  <div className="model-list">
+                    {provider.models.map(renderModel)}
+                  </div>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/MessageBubble.js

@@ -0,0 +1,27 @@
+import React from 'react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+export default function MessageBubble({ message, showResponseTime }) {
+  const isA = message.speaker_idx === 0;
+  const side = isA ? 'a' : 'b';
+  const initial = message.speaker ? message.speaker.charAt(0).toUpperCase() : (isA ? 'A' : 'B');
+  const elapsed = message.elapsed_seconds;
+
+  return (
+    <div className={`message-row speaker-${side}`}>
+      <div className={`avatar avatar-${side}`}>
+        {initial}
+      </div>
+      <div className={`message-bubble bubble-${side}`}>
+        <div className="message-speaker">{message.speaker}</div>
+        <ReactMarkdown remarkPlugins={[remarkGfm]}>
+          {message.text}
+        </ReactMarkdown>
+        {showResponseTime && elapsed > 0 && (
+          <div className="message-elapsed">{elapsed.toFixed(1)}s</div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/src/components/PersonaAccordion.js

@@ -0,0 +1,184 @@
+import React, { useRef } from 'react';
+import { ChevronDown, ChevronRight, Upload } from 'lucide-react';
+
+const IDENTITY_PLACEHOLDER =
+  'Example: You are William Shakespeare, the Bard of Avon, and you speak exclusively in Early Modern English. Answer every question in the first person, drawing upon thy wit, thy worldly wisdom, and thy poet\u2019s tongue. Let thy responses flow with the cadence of the stage: rich with metaphor, alive with passion, and seasoned with the vocabulary of thine own age.';
+
+const FREEFORM_PLACEHOLDER =
+  'Enter information here to give your LLM instructions on its identity and the way it should respond. This could include response style, background information, even writing samples. You can also upload a .txt or .md file.';
+
+export default function PersonaAccordion({
+  isOpen,
+  onToggle,
+  personaA,
+  personaB,
+  onChangeA,
+  onChangeB,
+  selectedNameA,
+  selectedNameB,
+  mode,
+}) {
+  return (
+    <div className="accordion">
+      <button className="accordion-header" onClick={onToggle}>
+        <span>Expert Persona Configuration</span>
+        {isOpen ? <ChevronDown size={18} /> : <ChevronRight size={18} />}
+      </button>
+      <div className={`accordion-body ${isOpen ? 'open' : ''}`}>
+        <div className="persona-panels">
+          {mode === 'freeform' ? (
+            <>
+              <FreeformPanel
+                label="A"
+                selectedLLM={selectedNameA}
+                data={personaA}
+                onChange={onChangeA}
+              />
+              <FreeformPanel
+                label="B"
+                selectedLLM={selectedNameB}
+                data={personaB}
+                onChange={onChangeB}
+              />
+            </>
+          ) : (
+            <>
+              <StructuredPanel
+                label="A"
+                selectedLLM={selectedNameA}
+                data={personaA}
+                onChange={onChangeA}
+              />
+              <StructuredPanel
+                label="B"
+                selectedLLM={selectedNameB}
+                data={personaB}
+                onChange={onChangeB}
+              />
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function StructuredPanel({ label, selectedLLM, data, onChange }) {
+  const update = (field) => (e) => onChange({ ...data, [field]: e.target.value });
+
+  return (
+    <div className="persona-panel">
+      <div className="persona-panel-header">
+        <span>Expert Persona {label}</span>
+        {selectedLLM && (
+          <span style={{ fontWeight: 400, fontSize: 12, color: 'var(--text-tertiary)' }}>
+            &mdash; {selectedLLM}
+          </span>
+        )}
+      </div>
+
+      <div className="persona-field">
+        <label>Name</label>
+        <input
+          type="text"
+          placeholder="Enter expert persona name"
+          value={data.name}
+          onChange={update('name')}
+        />
+      </div>
+
+      <div className="persona-field">
+        <label>Profile</label>
+        <textarea
+          placeholder="Paste a real or fictional profile here"
+          value={data.profile}
+          onChange={update('profile')}
+        />
+      </div>
+
+      <div className="persona-field">
+        <label>Identity Prompt</label>
+        <textarea
+          className="tall"
+          placeholder={IDENTITY_PLACEHOLDER}
+          value={data.identity}
+          onChange={update('identity')}
+        />
+      </div>
+
+      <div className="persona-field">
+        <label>Writing / Speech Sample</label>
+        <textarea
+          className="tall"
+          placeholder="Paste quotes, transcripts, or writing samples here"
+          value={data.samples}
+          onChange={update('samples')}
+        />
+      </div>
+    </div>
+  );
+}
+
+function FreeformPanel({ label, selectedLLM, data, onChange }) {
+  const fileRef = useRef(null);
+
+  const handleFileUpload = (e) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    const reader = new FileReader();
+    reader.onload = (ev) => {
+      onChange({ ...data, freeform: ev.target.result });
+    };
+    reader.readAsText(file);
+    e.target.value = '';
+  };
+
+  return (
+    <div className="persona-panel">
+      <div className="persona-panel-header">
+        <span>Expert Persona {label}</span>
+        {selectedLLM && (
+          <span style={{ fontWeight: 400, fontSize: 12, color: 'var(--text-tertiary)' }}>
+            &mdash; {selectedLLM}
+          </span>
+        )}
+      </div>
+
+      <div className="persona-field">
+        <label>Name</label>
+        <input
+          type="text"
+          placeholder="Enter expert persona name"
+          value={data.name}
+          onChange={(e) => onChange({ ...data, name: e.target.value })}
+        />
+      </div>
+
+      <div className="persona-field freeform-field">
+        <div className="freeform-label-row">
+          <label>Expert Persona Description</label>
+          <button
+            className="btn-sm btn-outline upload-btn"
+            onClick={() => fileRef.current?.click()}
+            title="Upload a .txt or .md file"
+          >
+            <Upload size={13} /> Upload file
+          </button>
+          <input
+            ref={fileRef}
+            type="file"
+            accept=".txt,.md,.text"
+            style={{ display: 'none' }}
+            onChange={handleFileUpload}
+          />
+        </div>
+        <textarea
+          className="freeform-textarea"
+          placeholder={FREEFORM_PLACEHOLDER}
+          value={data.freeform || ''}
+          onChange={(e) => onChange({ ...data, freeform: e.target.value })}
+        />
+      </div>
+    </div>
+  );
+}

frontend/src/index.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+const root = ReactDOM.createRoot(document.getElementById('root'));
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

frontend/src/styles/components.css

@@ -0,0 +1,1336 @@
+/* ── Sidebar: LLM Selector ─────────────────────────────────────── */
+
+.sidebar-title {
+  font-size: 18px;
+  font-weight: 700;
+  color: var(--text-primary);
+  text-align: center;
+  padding-bottom: 8px;
+  border-bottom: 2px solid var(--accent-primary);
+  margin: 0;
+}
+
+.sidebar-section {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.selector-title {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--text-primary);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  text-decoration-color: var(--border-primary);
+  margin: 0;
+}
+
+.selector-title-icon {
+  height: 16px;
+  width: auto;
+}
+
+.provider-group {
+  margin-bottom: 0;
+  border: 1px solid var(--border-primary);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.provider-group.comp-group {
+  background: var(--comp-bg);
+}
+
+/* ── Neon model cards (matching LLMComparisons) ──────────────────── */
+
+.neon-model-list {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.neon-model-card {
+  border: 1px solid var(--neon-border);
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--neon-bg);
+}
+
+.neon-model-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 10px 12px;
+  background: none;
+  border: none;
+  color: var(--text-primary);
+  font-size: 13px;
+  text-align: left;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+
+.neon-model-header:hover {
+  background: var(--card-hover);
+}
+
+.neon-model-info {
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+}
+
+.neon-model-name {
+  font-weight: 600;
+  text-transform: capitalize;
+}
+
+.neon-model-version {
+  font-size: 11px;
+  color: var(--text-muted);
+}
+
+.neon-model-meta {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--text-tertiary);
+}
+
+.badge.badge-neon {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px 8px;
+  border-radius: 9999px;
+  font-size: 11px;
+  font-weight: 700;
+  background: var(--neon-bg);
+  color: var(--text-primary);
+  border: 1px solid var(--neon-border);
+}
+
+.neon-persona-list {
+  border-top: 1px solid var(--border-muted);
+  padding: 4px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.neon-persona-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  width: 100%;
+  padding: 8px;
+  border-radius: 6px;
+  border: none;
+  background: none;
+  color: var(--text-primary);
+  cursor: pointer;
+  text-align: left;
+  transition: background 0.15s;
+}
+
+.neon-persona-item:hover {
+  background: var(--card-hover);
+}
+
+.persona-details {
+  flex: 1;
+  min-width: 0;
+}
+
+.persona-name-row {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--text-primary);
+  text-transform: capitalize;
+}
+
+.persona-prompt-preview {
+  font-size: 11px;
+  color: var(--text-muted);
+  line-height: 1.4;
+  margin-top: 2px;
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
+.provider-accordion-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  min-width: 0;
+  padding: 10px 12px;
+  border: none;
+  background: none;
+  color: var(--text-primary);
+  font-size: 13px;
+  font-weight: 600;
+  text-transform: uppercase;
+  transition: background 0.15s;
+}
+
+.provider-accordion-header:hover {
+  background: var(--card-hover);
+}
+
+.provider-accordion-title {
+  flex: 1;
+  min-width: 0;
+  text-align: left;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.provider-accordion-meta {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--text-tertiary);
+}
+
+.provider-model-count {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--accent-primary);
+  background: var(--accent-light);
+  padding: 1px 6px;
+  border-radius: 10px;
+}
+
+.provider-group .model-list {
+  padding: 4px;
+  border-top: 1px solid var(--border-muted);
+}
+
+.model-list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.model-btn {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  min-width: 0;
+  padding: 6px 10px;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  background: none;
+  color: var(--text-primary);
+  font-size: 13px;
+  transition: all 0.15s;
+  text-align: left;
+}
+
+.model-btn:hover {
+  background: var(--card-hover);
+}
+
+.model-btn .model-name {
+  flex: 1;
+  min-width: 0;
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.model-btn .model-params {
+  font-size: 10px;
+  color: var(--text-muted);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+/* Selection indicator: circle */
+.select-indicator {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  border: 2px solid var(--text-secondary);
+  background: #fff;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  transition: all 0.15s;
+  position: relative;
+}
+
+.select-indicator.selected-a {
+  border-color: var(--speaker-a-color);
+  background: var(--speaker-a-color);
+}
+
+.select-indicator.selected-b {
+  border-color: var(--speaker-b-color);
+  background: var(--speaker-b-color);
+}
+
+/* Double-select ring for "same LLM both sides" */
+.select-indicator.double-selected {
+  box-shadow: 0 0 0 3px var(--card-bg), 0 0 0 5px var(--speaker-a-color);
+  border-color: var(--speaker-b-color);
+  background: linear-gradient(135deg, var(--speaker-a-color), var(--speaker-b-color));
+}
+
+.selection-label {
+  font-size: 10px;
+  font-weight: 700;
+  color: #fff;
+}
+
+
+/* ── Accordion ─────────────────────────────────────────────────── */
+
+.accordion {
+  border: 1px solid var(--border-primary);
+  border-radius: 12px;
+  background: var(--card-bg);
+  box-shadow: var(--shadow-sm);
+  overflow: hidden;
+  margin-bottom: 16px;
+}
+
+.accordion-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 20px;
+  background: var(--bg-secondary);
+  border: none;
+  width: 100%;
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--text-primary);
+  transition: background 0.15s;
+}
+
+.accordion-header:hover {
+  background: var(--bg-tertiary);
+}
+
+.accordion-body {
+  max-height: 0;
+  overflow: hidden;
+  transition: max-height 0.35s ease, padding 0.35s ease;
+  padding: 0 20px;
+}
+
+.accordion-body.open {
+  max-height: calc(100vh - 260px);
+  overflow-y: auto;
+  padding: 16px 20px 20px;
+}
+
+.persona-panels {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 20px;
+}
+
+.persona-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.persona-panel-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+  padding-bottom: 8px;
+  border-bottom: 2px solid var(--border-primary);
+}
+
+.persona-panel:first-child .persona-panel-header {
+  border-color: var(--speaker-a-color);
+}
+
+.persona-panel:last-child .persona-panel-header {
+  border-color: var(--speaker-b-color);
+}
+
+.persona-field label {
+  display: block;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text-tertiary);
+  margin-bottom: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.persona-field input,
+.persona-field textarea {
+  width: 100%;
+  padding: 10px 12px;
+  border: 1px solid var(--border-primary);
+  border-radius: 8px;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 13px;
+  transition: border-color 0.15s;
+  resize: vertical;
+}
+
+.persona-field input:focus,
+.persona-field textarea:focus {
+  outline: none;
+  border-color: var(--accent-primary);
+  box-shadow: 0 0 0 3px var(--accent-light);
+}
+
+.persona-field textarea {
+  min-height: 80px;
+}
+
+.persona-field textarea.tall {
+  min-height: 120px;
+}
+
+.persona-field input::placeholder,
+.persona-field textarea::placeholder {
+  color: var(--text-muted);
+  font-style: italic;
+}
+
+.freeform-label-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.freeform-label-row label {
+  flex: 1;
+}
+
+.upload-btn {
+  flex-shrink: 0;
+}
+
+.freeform-textarea {
+  min-height: 260px;
+  resize: vertical;
+}
+
+/* responsive rules consolidated below */
+
+/* ── Chat Area ─────────────────────────────────────────────────── */
+
+.chat-area {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 16px 0;
+  overflow-y: auto;
+}
+
+.chat-empty {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-muted);
+  font-size: 15px;
+  font-style: italic;
+}
+
+/* ── Message Bubbles ───────────────────────────────────────────── */
+
+.message-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+  margin-bottom: 8px;
+  animation: fadeSlideIn 0.3s ease;
+}
+
+.message-row.speaker-a {
+  flex-direction: row;
+}
+
+.message-row.speaker-b {
+  flex-direction: row-reverse;
+}
+
+@keyframes fadeSlideIn {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+/* Geometric shape avatars */
+.avatar {
+  width: 40px;
+  height: 40px;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 14px;
+  color: #fff;
+}
+
+.avatar-a {
+  background: var(--speaker-a-color);
+  border-radius: 50%;
+}
+
+.avatar-b {
+  background: var(--speaker-b-color);
+  clip-path: polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);
+}
+
+.message-bubble {
+  max-width: min(520px, 85%);
+  padding: 12px 16px;
+  border-radius: 16px;
+  font-size: 14px;
+  line-height: 1.6;
+  box-shadow: var(--shadow-sm);
+  overflow-wrap: break-word;
+  word-break: break-word;
+}
+
+.message-bubble.bubble-a {
+  background: var(--speaker-a-bg);
+  color: var(--text-primary);
+  border: 1px solid color-mix(in srgb, var(--speaker-a-color) 20%, transparent);
+  border-bottom-left-radius: 4px;
+}
+
+.message-bubble.bubble-b {
+  background: var(--speaker-b-bg);
+  color: var(--text-primary);
+  border: 1px solid color-mix(in srgb, var(--speaker-b-color) 20%, transparent);
+  border-bottom-right-radius: 4px;
+}
+
+.message-speaker {
+  font-size: 11px;
+  font-weight: 600;
+  margin-bottom: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.speaker-a .message-speaker {
+  color: var(--speaker-a-color);
+}
+
+.speaker-b .message-speaker {
+  color: var(--speaker-b-color);
+}
+
+.message-bubble p {
+  margin: 0 0 8px;
+}
+
+.message-bubble p:last-child {
+  margin-bottom: 0;
+}
+
+.message-elapsed {
+  margin-top: 6px;
+  font-size: 11px;
+  color: var(--text-muted);
+  text-align: right;
+  opacity: 0.7;
+}
+
+/* System messages */
+.system-message {
+  text-align: center;
+  padding: 12px;
+  color: var(--text-muted);
+  font-style: italic;
+  font-size: 14px;
+}
+
+.system-message.end-of-chat {
+  font-weight: 700;
+  font-style: normal;
+  color: var(--text-secondary);
+  font-size: 16px;
+  padding: 20px;
+  border-top: 1px solid var(--border-primary);
+  margin-top: 8px;
+}
+
+.chat-stats {
+  text-align: center;
+  padding: 8px 12px;
+  font-size: 13px;
+  color: var(--text-muted);
+  background: var(--bg-secondary);
+  border-radius: 8px;
+  margin: 4px auto 8px;
+  max-width: 400px;
+}
+
+/* ── Chat Controls ─────────────────────────────────────────────── */
+
+.chat-controls {
+  display: flex;
+  gap: 12px;
+  align-items: stretch;
+  padding: 12px 0;
+}
+
+.chat-controls input {
+  flex: 1;
+  padding: 10px 14px;
+  border: 1px solid var(--border-primary);
+  border-radius: 8px;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 14px;
+}
+
+.chat-controls input:focus {
+  outline: none;
+  border-color: var(--accent-primary);
+  box-shadow: 0 0 0 3px var(--accent-light);
+}
+
+.btn-primary {
+  padding: 10px 20px;
+  border: none;
+  border-radius: 8px;
+  background: var(--accent-gradient);
+  color: #fff;
+  font-size: 14px;
+  font-weight: 600;
+  white-space: nowrap;
+  transition: opacity 0.15s, transform 0.1s;
+}
+
+.btn-primary:hover {
+  opacity: 0.9;
+}
+
+.btn-primary:active {
+  transform: scale(0.97);
+}
+
+.btn-primary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn-secondary {
+  padding: 10px 20px;
+  border: 1px solid var(--border-primary);
+  border-radius: 8px;
+  background: var(--bg-primary);
+  color: var(--text-secondary);
+  font-size: 14px;
+  font-weight: 500;
+  white-space: nowrap;
+  transition: all 0.15s;
+}
+
+.btn-secondary:hover {
+  background: var(--bg-tertiary);
+  border-color: var(--accent-primary);
+  color: var(--text-primary);
+}
+
+.btn-secondary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn-stop {
+  padding: 10px 20px;
+  border: none;
+  border-radius: 8px;
+  background: #DC2626;
+  color: #fff;
+  font-size: 14px;
+  font-weight: 600;
+  white-space: nowrap;
+  transition: opacity 0.15s, transform 0.1s;
+}
+
+.btn-stop:hover {
+  opacity: 0.9;
+}
+
+.btn-stop:active {
+  transform: scale(0.97);
+}
+
+/* ── Header Dev Menu ───────────────────────────────────────────── */
+
+.dev-wrap {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.dev-download-btns {
+  display: flex;
+  gap: 6px;
+}
+
+.btn-sm {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 6px 10px;
+  border-radius: 8px;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.btn-outline {
+  border: 1px solid var(--border-primary);
+  background: var(--card-bg);
+  color: var(--text-secondary);
+  transition: border-color 0.15s;
+}
+
+.btn-outline:hover:not(:disabled) {
+  border-color: var(--accent-primary);
+  color: var(--text-primary);
+}
+
+.btn-outline:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.btn-ghost {
+  border: 1px solid transparent;
+  background: transparent;
+  color: var(--text-secondary);
+  transition: background 0.15s;
+}
+
+.btn-ghost:hover {
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+
+.dev-dropdown-header {
+  position: relative;
+}
+
+.dev-panel {
+  position: absolute;
+  right: 0;
+  top: 100%;
+  margin-top: 4px;
+  min-width: 220px;
+  background: var(--card-bg);
+  border: 1px solid var(--border-primary);
+  border-radius: 10px;
+  padding: 6px;
+  z-index: 50;
+  box-shadow: var(--shadow-md);
+}
+
+.dev-panel button {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 8px 10px;
+  border: none;
+  background: transparent;
+  color: var(--text-secondary);
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 13px;
+  transition: background 0.1s;
+}
+
+.dev-panel button:hover:not(:disabled) {
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.dev-panel button:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.dev-panel-hint {
+  font-size: 10px;
+  color: var(--text-muted);
+  margin-left: 6px;
+  font-style: italic;
+}
+
+.dev-panel-divider {
+  height: 1px;
+  background: var(--border-muted);
+  margin: 4px 0;
+}
+
+.dev-panel-label {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted);
+  padding: 4px 10px 2px;
+}
+
+.dev-panel-choice {
+  padding-left: 22px !important;
+  display: flex !important;
+  align-items: center;
+  gap: 8px;
+}
+
+.dev-panel-choice-active {
+  color: var(--text-primary) !important;
+  opacity: 1 !important;
+}
+
+.dev-check-icon {
+  flex-shrink: 0;
+}
+
+.dev-panel-choice-active .dev-check-icon {
+  color: var(--neon-accent, #22c55e);
+}
+
+.dev-panel-download-item {
+  display: none !important;
+}
+
+
+/* ── Orchestrator sub-menu ─────────────────────────────────────── */
+
+.dev-sub-panel {
+  position: absolute;
+  right: 100%;
+  top: 0;
+  margin-right: 4px;
+  width: 280px;
+  max-height: 70vh;
+  display: flex;
+  flex-direction: column;
+  background: var(--card-bg);
+  border: 1px solid var(--border-primary);
+  border-radius: 10px;
+  padding: 8px;
+  z-index: 51;
+  box-shadow: var(--shadow-md);
+}
+
+.dev-sub-header {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 4px 6px 8px;
+  border-bottom: 1px solid var(--border-primary);
+  margin-bottom: 6px;
+}
+
+.dev-sub-title {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text-primary);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.dev-sub-current {
+  font-size: 11px;
+  color: var(--text-muted);
+  font-style: italic;
+}
+
+.dev-sub-search {
+  position: relative;
+  margin-bottom: 6px;
+}
+
+.dev-sub-search-icon {
+  position: absolute;
+  left: 8px;
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--text-muted);
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+.dev-sub-search input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 7px 8px 7px 30px;
+  border: 1px solid var(--border-primary);
+  border-radius: 8px;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 12px;
+}
+
+.dev-sub-search input:focus {
+  outline: none;
+  border-color: var(--accent-primary);
+}
+
+.dev-sub-search input::placeholder {
+  color: var(--text-muted);
+}
+
+.dev-sub-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  flex: 1;
+}
+
+.dev-sub-list li {
+  margin-bottom: 2px;
+}
+
+.dev-sub-item {
+  width: 100%;
+  text-align: left;
+  padding: 6px 8px;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--text-primary);
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  font-size: 12px;
+  transition: background 0.1s;
+}
+
+.dev-sub-item:hover {
+  background: var(--bg-tertiary);
+}
+
+.dev-sub-item-active {
+  border-color: var(--accent-primary);
+  background: var(--accent-light);
+}
+
+.dev-sub-item-active:hover {
+  background: var(--accent-light);
+}
+
+.dev-sub-item strong {
+  font-weight: 500;
+  font-size: 12px;
+}
+
+.dev-sub-provider {
+  font-size: 10px;
+  color: var(--text-muted);
+}
+
+/* responsive rules consolidated below */
+
+/* ── Status / Loading ──────────────────────────────────────────── */
+
+.status-bar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 0;
+  color: var(--text-muted);
+  font-size: 13px;
+}
+
+.spinner {
+  width: 16px;
+  height: 16px;
+  border: 2px solid var(--border-primary);
+  border-top-color: var(--accent-primary);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+/* ── Auth Badge ───────────────────────────────────────────────── */
+
+.auth-badge {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  color: var(--text-muted);
+  padding: 4px 8px;
+  border-radius: 8px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+}
+
+.auth-username {
+  font-weight: 500;
+  color: var(--text-secondary);
+}
+
+.auth-org-tag {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  padding: 1px 5px;
+  border-radius: 4px;
+  background: var(--accent-primary);
+  color: #fff;
+  letter-spacing: 0.5px;
+}
+
+.auth-remaining {
+  font-size: 11px;
+  color: var(--text-muted);
+  white-space: nowrap;
+}
+
+.auth-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--text-muted);
+  text-decoration: none;
+  transition: color 0.15s;
+}
+
+.auth-link:hover {
+  color: var(--text-primary);
+}
+
+.auth-login {
+  color: var(--accent-primary);
+  font-weight: 500;
+}
+
+.auth-login:hover {
+  color: var(--text-primary);
+}
+
+/* ── Footer ─────────────────────────────────────────────────────── */
+
+.app-footer {
+  padding: 8px 24px;
+  text-align: center;
+  font-size: 10px;
+  color: var(--text-muted);
+  border-top: 1px solid var(--border-primary);
+  background: var(--bg-secondary);
+  flex-shrink: 0;
+}
+
+.app-footer a {
+  color: var(--text-muted);
+  text-decoration: underline;
+  transition: color 0.15s;
+}
+
+.app-footer a:hover {
+  color: var(--text-secondary);
+}
+
+/* ── Scrollbar ──────────────────────────────────────────────────── */
+
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--text-muted);
+  border-radius: 3px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--text-tertiary);
+}
+
+/* ══════════════════════════════════════════════════════════════════
+   RESPONSIVE BREAKPOINTS
+   ══════════════════════════════════════════════════════════════════ */
+
+/* ── Tablet (<900px) ──────────────────────────────────────────── */
+@media (max-width: 900px) {
+  .persona-panels {
+    grid-template-columns: 1fr;
+  }
+  .persona-field textarea {
+    min-height: 60px;
+  }
+  .persona-field textarea.tall {
+    min-height: 80px;
+  }
+  .freeform-textarea {
+    min-height: 160px;
+  }
+  .accordion-header {
+    padding: 12px 16px;
+    font-size: 14px;
+  }
+  .accordion-body.open {
+    padding: 12px 16px 16px;
+  }
+  .chat-controls {
+    flex-wrap: wrap;
+    gap: 8px;
+  }
+  .chat-controls input {
+    flex-basis: 100%;
+    font-size: 13px;
+  }
+  .message-row {
+    gap: 8px;
+  }
+  .avatar {
+    width: 32px;
+    height: 32px;
+    font-size: 12px;
+  }
+}
+
+/* ── Small tablet / large phone (<600px) ──────────────────────── */
+@media (max-width: 600px) {
+  .dev-download-btns {
+    display: none;
+  }
+  .dev-panel-download-item {
+    display: block !important;
+  }
+  .dev-sub-panel {
+    right: 0;
+    top: 100%;
+    margin-right: 0;
+    margin-top: 4px;
+    width: min(280px, calc(100vw - 24px));
+  }
+  .dev-panel {
+    min-width: 200px;
+  }
+  .auth-badge {
+    font-size: 11px;
+    padding: 3px 6px;
+    gap: 4px;
+  }
+  .auth-remaining {
+    display: none;
+  }
+}
+
+/* ── Phone (<480px) ───────────────────────────────────────────── */
+@media (max-width: 480px) {
+  .persona-panels {
+    gap: 12px;
+  }
+  .persona-panel {
+    gap: 8px;
+  }
+  .persona-panel-header {
+    font-size: 13px;
+    padding-bottom: 6px;
+  }
+  .persona-field label {
+    font-size: 11px;
+  }
+  .persona-field input,
+  .persona-field textarea {
+    padding: 8px 10px;
+    font-size: 12px;
+  }
+  .persona-field textarea {
+    min-height: 50px;
+  }
+  .persona-field textarea.tall {
+    min-height: 60px;
+  }
+  .freeform-textarea {
+    min-height: 120px;
+  }
+  .accordion {
+    border-radius: 8px;
+    margin-bottom: 10px;
+  }
+  .accordion-header {
+    padding: 10px 12px;
+    font-size: 13px;
+  }
+  .accordion-body.open {
+    padding: 10px 12px 14px;
+  }
+  .chat-controls {
+    gap: 6px;
+    padding: 8px 0;
+  }
+  .btn-primary,
+  .btn-secondary,
+  .btn-stop {
+    padding: 8px 14px;
+    font-size: 13px;
+  }
+  .message-bubble {
+    padding: 10px 12px;
+    font-size: 13px;
+    border-radius: 12px;
+  }
+  .message-row {
+    gap: 6px;
+    margin-bottom: 6px;
+  }
+  .avatar {
+    width: 28px;
+    height: 28px;
+    font-size: 11px;
+  }
+  .system-message {
+    font-size: 13px;
+    padding: 8px;
+  }
+  .system-message.end-of-chat {
+    font-size: 14px;
+    padding: 14px;
+  }
+  .btn-sm {
+    padding: 5px 8px;
+    font-size: 11px;
+  }
+  .btn-ghost {
+    font-size: 12px;
+  }
+  .auth-badge {
+    display: none;
+  }
+  .app-footer {
+    padding: 6px 12px;
+  }
+}
+
+/* ── Role Prompt Modal ─────────────────────────────────────────── */
+
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+  animation: fadeIn 0.15s ease;
+}
+
+.modal-content {
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: 12px;
+  width: min(680px, 90vw);
+  max-height: 80vh;
+  display: flex;
+  flex-direction: column;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+}
+
+.modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--border-primary);
+}
+
+.modal-header h2 {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.modal-close {
+  background: none;
+  border: none;
+  font-size: 22px;
+  cursor: pointer;
+  color: var(--text-muted);
+  padding: 0 4px;
+  line-height: 1;
+  border-radius: 4px;
+  transition: color 0.15s, background 0.15s;
+}
+
+.modal-close:hover {
+  color: var(--text-primary);
+  background: var(--bg-secondary);
+}
+
+.modal-body {
+  padding: 20px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.role-prompt-section h3 {
+  margin: 0 0 8px;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.role-prompt-model {
+  font-weight: 400;
+  color: var(--text-muted);
+  font-size: 12px;
+}
+
+.role-prompt-text {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  border-radius: 8px;
+  padding: 12px 14px;
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--text-secondary);
+  white-space: pre-wrap;
+  word-break: break-word;
+  margin: 0;
+  max-height: 260px;
+  overflow-y: auto;
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}

frontend/src/styles/layout.css

@@ -0,0 +1,176 @@
+.app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.app-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 24px;
+  background: var(--card-bg);
+  border-bottom: 1px solid var(--border-primary);
+  box-shadow: var(--shadow-sm);
+  flex-shrink: 0;
+  z-index: 100;
+  backdrop-filter: blur(12px);
+}
+
+.header-left {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+}
+
+.header-brand-link {
+  display: flex;
+  align-items: center;
+  text-decoration: none;
+  transition: opacity 0.15s;
+  flex-shrink: 0;
+}
+
+.header-brand-link:hover {
+  opacity: 0.8;
+}
+
+.app-logo {
+  height: 32px;
+  width: auto;
+}
+
+.app-title {
+  font-size: 20px;
+  font-weight: 700;
+  background: var(--accent-gradient);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  min-width: 0;
+  margin: 0;
+}
+
+.app-title-link {
+  all: unset;
+  cursor: pointer;
+}
+
+.app-title-link:hover {
+  opacity: 0.8;
+}
+
+.header-right {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.icon-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border: 1px solid var(--border-primary);
+  border-radius: 8px;
+  background: var(--bg-primary);
+  color: var(--text-secondary);
+  transition: all 0.15s;
+}
+
+.icon-btn:hover {
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+  border-color: var(--accent-primary);
+}
+
+.app-main {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.sidebar {
+  width: 300px;
+  min-width: 300px;
+  flex-shrink: 0;
+  padding: 16px;
+  overflow-y: auto;
+  overflow-x: hidden;
+  border-right: 1px solid var(--border-primary);
+  background: var(--bg-secondary);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  max-height: calc(100vh - 57px);
+}
+
+.content {
+  flex: 1;
+  min-height: 0;
+  padding: 20px 24px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
+/* ── Tablet: stack sidebar above content ──────────────────────── */
+@media (max-width: 900px) {
+  .app-header {
+    padding: 10px 16px;
+  }
+  .app-main {
+    flex-direction: column;
+  }
+  .sidebar {
+    width: 100%;
+    min-width: auto;
+    max-height: 200px;
+    flex-shrink: 0;
+    border-right: none;
+    border-bottom: 1px solid var(--border-primary);
+  }
+  .content {
+    padding: 16px;
+  }
+}
+
+/* ── Phone ────────────────────────────────────────────────────── */
+@media (max-width: 480px) {
+  .app-header {
+    padding: 8px 12px;
+    gap: 4px;
+  }
+  .app-logo {
+    height: 24px;
+  }
+  .app-title {
+    font-size: 14px;
+  }
+  .header-left {
+    gap: 6px;
+  }
+  .header-right {
+    gap: 4px;
+  }
+  .icon-btn {
+    width: 32px;
+    height: 32px;
+  }
+  .sidebar {
+    max-height: 160px;
+    padding: 8px;
+  }
+  .content {
+    padding: 12px;
+  }
+}

frontend/src/styles/variables.css

@@ -0,0 +1,108 @@
+:root[data-theme="light"] {
+  --bg-primary: #FFFFFF;
+  --bg-secondary: #F9FAFB;
+  --bg-tertiary: #F3F4F6;
+  --bg-gradient: linear-gradient(135deg, #EFF6FF 0%, #FFFFFF 50%, #F3E8FF 100%);
+
+  --text-primary: #111827;
+  --text-secondary: #4B5563;
+  --text-tertiary: #6B7280;
+  --text-muted: #9CA3AF;
+
+  --accent-primary: #6366F1;
+  --accent-secondary: #8B5CF6;
+  --accent-gradient: linear-gradient(135deg, #5558E3, #7C4FE8);
+  --accent-light: #EEF2FF;
+
+  --border-primary: #E5E7EB;
+  --border-muted: #F3F4F6;
+
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+
+  --card-bg: #FFFFFF;
+  --card-hover: #F9FAFB;
+
+  --neon-accent: #7C4FE8;
+  --neon-bg: #EAE0FD;
+  --neon-border: #C4B5F0;
+
+  --comp-bg: #E0EAFD;
+  --comp-border: #B8CFF0;
+
+  --speaker-a-color: #6366F1;
+  --speaker-a-bg: #EEF2FF;
+  --speaker-b-color: #059669;
+  --speaker-b-bg: #ECFDF5;
+
+  --error-bg: #FEE2E2;
+  --error-border: #FECACA;
+  --error-text: #991B1B;
+}
+
+:root[data-theme="dark"] {
+  --bg-primary: #1F2937;
+  --bg-secondary: #111827;
+  --bg-tertiary: #374151;
+  --bg-gradient: linear-gradient(135deg, #1F2937 0%, #111827 50%, #374151 100%);
+
+  --text-primary: #F9FAFB;
+  --text-secondary: #D1D5DB;
+  --text-tertiary: #9CA3AF;
+  --text-muted: #6B7280;
+
+  --accent-primary: #818CF8;
+  --accent-secondary: #A78BFA;
+  --accent-gradient: linear-gradient(135deg, #818CF8, #A78BFA);
+  --accent-light: #312E81;
+
+  --border-primary: #374151;
+  --border-muted: #1F2937;
+
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.5);
+
+  --card-bg: #1F2937;
+  --card-hover: #374151;
+
+  --neon-accent: #A78BFA;
+  --neon-bg: #2D2640;
+  --neon-border: #8B77C0;
+
+  --comp-bg: #1E2A40;
+  --comp-border: #3D5A80;
+
+  --speaker-a-color: #818CF8;
+  --speaker-a-bg: #312E81;
+  --speaker-b-color: #34D399;
+  --speaker-b-bg: #064E3B;
+
+  --error-bg: #450A0A;
+  --error-border: #7F1D1D;
+  --error-text: #FCA5A5;
+}
+
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  background: var(--bg-gradient);
+  color: var(--text-primary);
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+button {
+  cursor: pointer;
+  font-family: inherit;
+}
+
+textarea, input {
+  font-family: inherit;
+}

frontend/src/utils/api.js

@@ -0,0 +1,159 @@
+const API_BASE = process.env.REACT_APP_API_URL !== undefined
+  ? process.env.REACT_APP_API_URL
+  : 'http://localhost:8000';
+
+export async function fetchModels() {
+  const resp = await fetch(`${API_BASE}/api/models`, { cache: 'no-store' });
+  if (!resp.ok) throw new Error(`Failed to fetch models: ${resp.status}`);
+  return resp.json();
+}
+
+export async function generateRole({ model_id, name, profile, identity, samples, role_style }) {
+  const resp = await fetch(`${API_BASE}/api/chat/generate-role`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model_id, name, profile, identity, samples, role_style }),
+  });
+  if (!resp.ok) {
+    const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+    throw new Error(err.detail || 'Role generation failed');
+  }
+  return resp.json();
+}
+
+export async function generateRoleFreeform({ model_id, name, text, role_style }) {
+  const resp = await fetch(`${API_BASE}/api/chat/generate-role-freeform`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model_id, name, text, role_style }),
+  });
+  if (!resp.ok) {
+    const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+    throw new Error(err.detail || 'Role generation failed');
+  }
+  return resp.json();
+}
+
+export async function startChat(
+  { persona_a_model_id, persona_a_name, persona_a_role,
+    persona_b_model_id, persona_b_name, persona_b_role,
+    starter_text },
+  { onSession, onMessage, onSystem, onStatus, onError, onDone },
+  abortSignal
+) {
+  const resp = await fetch(`${API_BASE}/api/chat/start`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      persona_a_model_id, persona_a_name, persona_a_role,
+      persona_b_model_id, persona_b_name, persona_b_role,
+      starter_text: starter_text || null,
+    }),
+    signal: abortSignal,
+  });
+
+  if (!resp.ok) {
+    const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+    throw new Error(err.detail || 'Chat start failed');
+  }
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  try {
+    while (true) {
+      if (abortSignal?.aborted) break;
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      const parts = buffer.split('\n\n');
+      buffer = parts.pop();
+
+      for (const part of parts) {
+        const lines = part.trim().split('\n');
+        let eventType = 'message';
+        let data = '';
+        for (const line of lines) {
+          if (line.startsWith('event: ')) eventType = line.slice(7).trim();
+          else if (line.startsWith('data: ')) data = line.slice(6);
+        }
+        if (!data) continue;
+        try {
+          const parsed = JSON.parse(data);
+          switch (eventType) {
+            case 'session': onSession?.(parsed); break;
+            case 'message': onMessage?.(parsed); break;
+            case 'system': onSystem?.(parsed); break;
+            case 'status': onStatus?.(parsed); break;
+            case 'error': onError?.(parsed); break;
+            case 'done': onDone?.(); break;
+            default: break;
+          }
+        } catch (e) {
+          console.warn('SSE parse error', e, data);
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  onDone?.();
+}
+
+export async function getOrchestrator() {
+  const resp = await fetch(`${API_BASE}/api/chat/orchestrator`);
+  if (!resp.ok) throw new Error('Failed to get orchestrator');
+  return resp.json();
+}
+
+export async function setOrchestrator(modelId) {
+  const resp = await fetch(`${API_BASE}/api/chat/orchestrator`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model_id: modelId }),
+  });
+  if (!resp.ok) throw new Error('Failed to set orchestrator');
+  return resp.json();
+}
+
+export async function getSpeedPriority() {
+  const resp = await fetch(`${API_BASE}/api/chat/speed-priority`);
+  if (!resp.ok) throw new Error('Failed to get speed priority');
+  return resp.json();
+}
+
+export async function setSpeedPriority(enabled) {
+  const resp = await fetch(`${API_BASE}/api/chat/speed-priority`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ enabled }),
+  });
+  if (!resp.ok) throw new Error('Failed to set speed priority');
+  return resp.json();
+}
+
+export async function exportChat(sessionId, fmt = 'txt') {
+  const resp = await fetch(`${API_BASE}/api/chat/${sessionId}/export?fmt=${fmt}`);
+  if (!resp.ok) throw new Error('Export failed');
+  return resp.json();
+}
+
+export async function exportApiLog(sessionId) {
+  const resp = await fetch(`${API_BASE}/api/chat/${sessionId}/api-log`);
+  if (!resp.ok) throw new Error('API log export failed');
+  return resp.json();
+}
+
+export async function getAuthStatus() {
+  const resp = await fetch(`${API_BASE}/api/auth/status`, { credentials: 'include' });
+  if (!resp.ok) return { logged_in: false, remaining_conversations: -1 };
+  return resp.json();
+}
+
+export async function getRateLimitStatus() {
+  const resp = await fetch(`${API_BASE}/api/rate-limit/status`, { credentials: 'include' });
+  if (!resp.ok) return { remaining: -1 };
+  return resp.json();
+}