7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
feat: fusion virtual model — free multi-model synthesis (#326) (#329)
Tashfeen949cf868bdbf
diff --git a/client/src/App.tsx b/client/src/App.tsxindex a2ca23e5..26f1e938 100644--- a/client/src/App.tsx+++ b/client/src/App.tsx@@ -22,6 +22,7 @@ import { logout } from '@/lib/api'import KeysPage from '@/pages/KeysPage'import PlaygroundPage from '@/pages/PlaygroundPage'import FallbackPage from '@/pages/FallbackPage'+import FusionPage from '@/pages/FusionPage'import EmbeddingsPage from '@/pages/EmbeddingsPage'import AnalyticsPage from '@/pages/AnalyticsPage'import PremiumPage from '@/pages/PremiumPage'@@ -236,6 +237,7 @@ function App() {<Route path="/" element={<Navigate to="/models/chat" replace />} /><Route path="/models" element={<Navigate to="/models/chat" replace />} /><Route path="/models/chat" element={<FallbackPage />} />+ <Route path="/models/fusion" element={<FusionPage />} /><Route path="/models/embeddings" element={<EmbeddingsPage />} /><Route path="/playground" element={<PlaygroundPage />} /><Route path="/keys" element={<KeysPage />} />diff --git a/client/src/components/models-tabs.tsx b/client/src/components/models-tabs.tsxindex 77a77c7f..8d001b7b 100644--- a/client/src/components/models-tabs.tsx+++ b/client/src/components/models-tabs.tsx@@ -1,20 +1,33 @@import { NavLink } from 'react-router-dom'import { useI18n } from '@/i18n'-// Segmented Chat | Embeddings switcher shared by the two Models pages.+// Segmented Chat | Embeddings | Fusion switcher shared by the Models pages.// Industry-standard layout: one "Models" section, modality as a tab — chat-// routing (cross-model fallback) and embeddings routing (same-model,-// cross-provider fallback) are different machines behind one roof.+// routing (cross-model fallback), embeddings routing (same-model,+// cross-provider fallback), and fusion (multi-model synthesis) are different+// machines behind one roof.export function ModelsTabs() {const { t } = useI18n()const tab = (isActive: boolean) =>- `px-3 py-1.5 text-xs rounded-lg transition-colors ${+ `inline-flex items-center gap-1.5 px-3 py-1.5 text-xs rounded-lg transition-colors ${isActive ? 'bg-foreground text-background font-medium' : 'text-muted-foreground hover:text-foreground hover:bg-muted'}`return (<div className="inline-flex gap-1 rounded-xl border p-1"><NavLink to="/models/chat" className={({ isActive }) => tab(isActive)}>{t('models.chatModelsTab')}</NavLink><NavLink to="/models/embeddings" className={({ isActive }) => tab(isActive)}>{t('models.embeddingsTab')}</NavLink>+ <NavLink to="/models/fusion" className={({ isActive }) => tab(isActive)}>+ {({ isActive }) => (+ <>+ {t('models.fusionTab')}+ <span className={`rounded px-1 py-0.5 text-[9px] font-semibold uppercase leading-none tracking-wide ${+ isActive ? 'bg-background/20 text-background' : 'bg-emerald-500/15 text-emerald-600 dark:text-emerald-400'+ }`}>+ {t('models.newBadge')}+ </span>+ </>+ )}+ </NavLink></div>)}diff --git a/client/src/i18n/locales/en.json b/client/src/i18n/locales/en.jsonindex 6dd8ff45..9e6f2849 100644--- a/client/src/i18n/locales/en.json+++ b/client/src/i18n/locales/en.json@@ -66,7 +66,9 @@"models": {"title": "Models","chatModelsTab": "Chat models",+ "fusionTab": "Fusion","embeddingsTab": "Embeddings",+ "newBadge": "New","monthlyTokenBudget": "Monthly token budget","remaining": "remaining","of": "of",@@ -240,6 +242,7 @@"title": "Playground","description": "Send a chat completion through the router and see which provider serves it.","autoModel": "Auto (fallback chain)",+ "fusionModel": "Fusion (multi-model synthesis)","send": "Send","sending": "Sending…","clear": "Clear",@@ -250,6 +253,11 @@"copyReply": "Copy reply","fallback": "fallback","fallbacks": "fallbacks",+ "fusionPanel": "Panel",+ "fusionJudge": "Judge",+ "fusionTrace": "{count} model responses",+ "fusionFailed": "no response",+ "fusionJudgeSynth": "synthesized the final answer","errorPrefix": "Error:"},"embeddings": {@@ -267,6 +275,37 @@"savingChanges": "Saving…","tokMax": "{tokens} tok max"},+ "fusion": {+ "title": "Fusion",+ "description": "A panel of models answers in parallel, then a judge synthesizes one stronger answer. Use it by calling the API with model \"fusion\".",+ "panelSource": "Panel source",+ "panelSourceHelp": "Where the panel models come from when a request doesn't specify its own.",+ "mode": {+ "auto": "Auto (Fallback Chain)",+ "autoHelp": "Pick a diverse set of models from your Fallback Chain, ranked by your active routing strategy.",+ "explicit": "Explicit panel",+ "explicitHelp": "Always use the specific models you choose below."+ },+ "panelModels": "Panel models",+ "selectedCount": "{count} of {max} selected",+ "noModels": "No models are connected yet. Add an API key, then enable models in the Fallback Chain.",+ "panelSize": "Panel size",+ "panelSizeHelp": "How many diverse models to pick automatically (1–{max}).",+ "judge": "Judge model",+ "judgeHelp": "The model that synthesizes the panel's answers into one. Auto uses your top-ranked available model.",+ "judgeAuto": "Auto (top-ranked available)",+ "strategy": "Strategy",+ "strategySynthesize": "Synthesize — blend the panel into one answer",+ "strategyBestOf": "Best of — return the single strongest answer (no judge call)",+ "strategySynthesizeShort": "Synthesize",+ "strategyBestOfShort": "Best of",+ "exposePanel": "Expose panel details",+ "exposePanelHelp": "Attach each model's answer and the judge metadata under an x_fusion field in the response.",+ "howToUse": "How to use",+ "howToUseHelp": "Send a normal chat request with model \"fusion\". These settings are the default; any request can override them with a \"fusion\" field.",+ "unsavedChanges": "Unsaved changes",+ "save": "Save"+ },"premium": {"title": "Premium","description": "The live model catalog, on every device.",diff --git a/client/src/pages/FusionPage.tsx b/client/src/pages/FusionPage.tsxnew file mode 100644index 00000000..55e4327c--- /dev/null+++ b/client/src/pages/FusionPage.tsx@@ -0,0 +1,275 @@+import { useEffect, useMemo, useState } from 'react'+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'+import { Check, Layers } from 'lucide-react'+import { apiFetch } from '@/lib/api'+import { Button } from '@/components/ui/button'+import { Input } from '@/components/ui/input'+import { Switch } from '@/components/ui/switch'+import { Badge } from '@/components/ui/badge'+import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@/components/ui/select'+import { PageHeader } from '@/components/page-header'+import { FloatingBar } from '@/components/floating-bar'+import { ModelsTabs } from '@/components/models-tabs'+import { useI18n } from '@/i18n'++type Mode = 'auto' | 'explicit'+type Strategy = 'synthesize' | 'best_of'++interface SavedFusionConfig {+ mode: Mode+ models: string[]+ judge: string | null+ k: number+ strategy: Strategy+ expose_panel: boolean+}++interface FusionConfigResponse {+ config: SavedFusionConfig+ maxK: number+}++interface FallbackEntry {+ modelDbId: number+ platform: string+ modelId: string+ displayName: string+ enabled: boolean+ keyCount: number+}++const JUDGE_AUTO = '__auto__'++export default function FusionPage() {+ const { t } = useI18n()+ const queryClient = useQueryClient()++ const { data, isLoading } = useQuery<FusionConfigResponse>({+ queryKey: ['fusion-config'],+ queryFn: () => apiFetch('/api/settings/fusion'),+ })+ const { data: fallbackEntries = [] } = useQuery<FallbackEntry[]>({+ queryKey: ['fallback'],+ queryFn: () => apiFetch('/api/fallback'),+ })++ // Models that can actually serve a request right now (enabled + a key).+ const availableModels = useMemo(+ () => fallbackEntries.filter(e => e.keyCount > 0 && e.enabled),+ [fallbackEntries],+ )++ const [mode, setMode] = useState<Mode>('auto')+ const [models, setModels] = useState<string[]>([])+ const [judge, setJudge] = useState<string>(JUDGE_AUTO)+ const [k, setK] = useState<number>(4)+ const [strategy, setStrategy] = useState<Strategy>('synthesize')+ const [exposePanel, setExposePanel] = useState<boolean>(false)++ // Hydrate local state from the server once it loads.+ useEffect(() => {+ if (!data) return+ setMode(data.config.mode)+ setModels(data.config.models)+ setJudge(data.config.judge ?? JUDGE_AUTO)+ setK(data.config.k)+ setStrategy(data.config.strategy)+ setExposePanel(data.config.expose_panel)+ }, [data])++ const maxK = data?.maxK ?? 8++ const saveMutation = useMutation({+ mutationFn: (body: SavedFusionConfig) =>+ apiFetch<FusionConfigResponse>('/api/settings/fusion', { method: 'PUT', body: JSON.stringify(body) }),+ onSuccess: (res) => queryClient.setQueryData(['fusion-config'], res),+ })++ const draft: SavedFusionConfig = {+ mode,+ models,+ judge: judge === JUDGE_AUTO ? null : judge,+ k: Math.min(Math.max(k || 1, 1), maxK),+ strategy,+ expose_panel: exposePanel,+ }++ const hasChanges = !!data && JSON.stringify({+ ...data.config,+ judge: data.config.judge ?? null,+ }) !== JSON.stringify(draft)++ const toggleModel = (modelId: string) => {+ setModels(prev => prev.includes(modelId)+ ? prev.filter(m => m !== modelId)+ : (prev.length >= maxK ? prev : [...prev, modelId]))+ }++ return (+ <div>+ <PageHeader+ title={t('fusion.title')}+ description={t('fusion.description')}+ divider={false}+ actions={<ModelsTabs />}+ />++ {isLoading ? (+ <p className="text-sm text-muted-foreground">{t('common.loading')}</p>+ ) : (+ <div className="space-y-8">+ {/* Panel mode */}+ <section className="space-y-3">+ <div>+ <h2 className="text-sm font-medium">{t('fusion.panelSource')}</h2>+ <p className="text-xs text-muted-foreground mt-0.5">{t('fusion.panelSourceHelp')}</p>+ </div>+ <div className="grid grid-cols-2 gap-3">+ {(['auto', 'explicit'] as Mode[]).map(m => (+ <button+ key={m}+ type="button"+ onClick={() => setMode(m)}+ className={`rounded-xl border p-3 text-left transition-colors ${+ mode === m ? 'border-foreground bg-muted/50' : 'hover:bg-muted/30'+ }`}+ >+ <div className="flex items-center justify-between">+ <span className="text-sm font-medium">{t(`fusion.mode.${m}`)}</span>+ {mode === m && <Check className="size-4" />}+ </div>+ <p className="text-xs text-muted-foreground mt-1">{t(`fusion.mode.${m}Help`)}</p>+ </button>+ ))}+ </div>+ </section>++ {/* Explicit panel picker */}+ {mode === 'explicit' && (+ <section className="space-y-3">+ <div className="flex items-baseline justify-between">+ <h2 className="text-sm font-medium">{t('fusion.panelModels')}</h2>+ <span className="text-xs text-muted-foreground">{t('fusion.selectedCount', { count: models.length, max: maxK })}</span>+ </div>+ {availableModels.length === 0 ? (+ <p className="text-xs text-muted-foreground">{t('fusion.noModels')}</p>+ ) : (+ <div className="max-h-80 overflow-y-auto rounded-xl border divide-y">+ {availableModels.map(m => {+ const selected = models.includes(m.modelId)+ const atCap = !selected && models.length >= maxK+ return (+ <button+ key={m.modelDbId}+ type="button"+ disabled={atCap}+ onClick={() => toggleModel(m.modelId)}+ className={`flex w-full items-center gap-3 px-3 py-2 text-left transition-colors ${+ selected ? 'bg-muted/50' : atCap ? 'opacity-40' : 'hover:bg-muted/30'+ }`}+ >+ <span className={`flex size-4 items-center justify-center rounded border ${selected ? 'bg-foreground text-background' : ''}`}>+ {selected && <Check className="size-3" />}+ </span>+ <span className="min-w-0 flex-1">+ <span className="text-sm font-medium">{m.displayName}</span>+ <span className="ml-2 font-mono text-[11px] text-muted-foreground">{m.modelId}</span>+ </span>+ <Badge variant="secondary" className="text-[10px]">{m.platform}</Badge>+ </button>+ )+ })}+ </div>+ )}+ </section>+ )}++ {/* Auto panel size */}+ {mode === 'auto' && (+ <section className="space-y-2">+ <h2 className="text-sm font-medium">{t('fusion.panelSize')}</h2>+ <p className="text-xs text-muted-foreground">{t('fusion.panelSizeHelp', { max: maxK })}</p>+ <Input+ type="number" min={1} max={maxK} value={k}+ onChange={e => setK(Number(e.target.value))}+ className="w-28"+ />+ </section>+ )}++ {/* Judge */}+ <section className="space-y-2">+ <h2 className="text-sm font-medium">{t('fusion.judge')}</h2>+ <p className="text-xs text-muted-foreground">{t('fusion.judgeHelp')}</p>+ <Select value={judge} onValueChange={v => setJudge(v ?? JUDGE_AUTO)}>+ <SelectTrigger className="w-full max-w-md">+ <SelectValue>+ {(v: string) => (!v || v === JUDGE_AUTO)+ ? t('fusion.judgeAuto')+ : (availableModels.find(m => m.modelId === v)?.displayName ?? v)}+ </SelectValue>+ </SelectTrigger>+ <SelectContent>+ <SelectItem value={JUDGE_AUTO}>{t('fusion.judgeAuto')}</SelectItem>+ {availableModels.map(m => (+ <SelectItem key={m.modelDbId} value={m.modelId}>+ <span className="flex items-center gap-2">+ <span>{m.displayName}</span>+ <span className="text-xs text-muted-foreground">{m.platform}</span>+ </span>+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </section>++ {/* Strategy */}+ <section className="space-y-2">+ <h2 className="text-sm font-medium">{t('fusion.strategy')}</h2>+ <Select value={strategy} onValueChange={v => { if (v) setStrategy(v as Strategy) }}>+ <SelectTrigger className="w-full max-w-md">+ <SelectValue>+ {(v: string) => v === 'best_of' ? t('fusion.strategyBestOfShort') : t('fusion.strategySynthesizeShort')}+ </SelectValue>+ </SelectTrigger>+ <SelectContent>+ <SelectItem value="synthesize">{t('fusion.strategySynthesize')}</SelectItem>+ <SelectItem value="best_of">{t('fusion.strategyBestOf')}</SelectItem>+ </SelectContent>+ </Select>+ </section>++ {/* Expose panel */}+ <section className="flex items-center justify-between rounded-xl border p-3">+ <div className="min-w-0 pr-4">+ <h2 className="text-sm font-medium">{t('fusion.exposePanel')}</h2>+ <p className="text-xs text-muted-foreground mt-0.5">{t('fusion.exposePanelHelp')}</p>+ </div>+ <Switch checked={exposePanel} onCheckedChange={setExposePanel} />+ </section>++ {/* Usage hint */}+ <section className="rounded-xl border bg-muted/30 p-4">+ <div className="flex items-center gap-2 mb-2">+ <Layers className="size-4" />+ <h2 className="text-sm font-medium">{t('fusion.howToUse')}</h2>+ </div>+ <p className="text-xs text-muted-foreground mb-2">{t('fusion.howToUseHelp')}</p>+ <pre className="overflow-x-auto rounded-lg bg-background p-3 text-[11px] leading-relaxed font-mono border">{`POST /v1/chat/completions+{+ "model": "fusion",+ "messages": [ ... ]+}`}</pre>+ </section>+ </div>+ )}++ <FloatingBar show={hasChanges}>+ <span className="text-xs text-muted-foreground">{t('fusion.unsavedChanges')}</span>+ <Button size="sm" onClick={() => saveMutation.mutate(draft)} disabled={saveMutation.isPending}>+ {saveMutation.isPending ? t('common.loading') : t('fusion.save')}+ </Button>+ </FloatingBar>+ </div>+ )+}diff --git a/client/src/pages/PlaygroundPage.tsx b/client/src/pages/PlaygroundPage.tsxindex e659f048..7c88f546 100644--- a/client/src/pages/PlaygroundPage.tsx+++ b/client/src/pages/PlaygroundPage.tsx@@ -1,5 +1,6 @@import { useState, useRef, useEffect } from 'react'import { useQuery } from '@tanstack/react-query'+import { ChevronRight } from 'lucide-react'import { apiFetch } from '@/lib/api'import { Button } from '@/components/ui/button'import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'@@ -27,9 +28,83 @@ interface ChatMessage {model?: stringlatency?: numberfallbackAttempts?: number+ // Fusion responses: the panel models (with their answers, for the+ // collapsible trace) and the judge that synthesized them (null when not+ // synthesized — single survivor / best_of). `fusionStreaming` is true while+ // panel/judge frames are still arriving.+ fusionPanel?: FusionPanelEntry[]+ fusionJudge?: { platform: string; model: string } | null+ fusionStreaming?: boolean}}+interface FusionPanelEntry {+ platform: string+ model: string+ status?: 'ok' | 'failed'+ content?: string+ error?: string+}++// Render a fusion panel/judge entry as "platform/model", but avoid doubling+// the provider when the model id already carries it (e.g. openrouter/owl-alpha,+// groq/compound) — those would otherwise read "openrouter/openrouter/owl-alpha".+function fusionRouteLabel(p: { platform: string; model: string }): string {+ return p.model.startsWith(`${p.platform}/`) ? p.model : `${p.platform}/${p.model}`+}++// Collapsible, minimal-font trace shown OUTSIDE the main answer bubble: each+// panel model's raw answer as it streamed in, plus the judge that synthesized+// the final answer. Default-open so you can watch it work; collapse to tuck away.+function FusionTrace({ panel, judge, streaming, answerStarted }: {+ panel: FusionPanelEntry[]+ judge?: { platform: string; model: string } | null+ streaming?: boolean+ answerStarted?: boolean+}) {+ const { t } = useI18n()+ // Open while the panel streams in so you can watch it work; auto-collapse the+ // moment the final answer STARTS streaming (first token in the bubble), so it+ // tucks away as the answer takes over — unless the user manually toggled it.+ const [open, setOpen] = useState(true)+ const touched = useRef(false)+ useEffect(() => {+ if (answerStarted && !touched.current) setOpen(false)+ }, [answerStarted])+ return (+ <div className="w-full text-[10px] leading-snug text-muted-foreground/80">+ <button+ type="button"+ onClick={() => { touched.current = true; setOpen(o => !o) }}+ className="inline-flex items-center gap-1 font-mono hover:text-foreground transition-colors"+ >+ <ChevronRight className={`size-3 transition-transform ${open ? 'rotate-90' : ''}`} />+ {t('playground.fusionTrace', { count: panel.length })}{streaming ? ' …' : ''}+ </button>+ {open && (+ <div className="mt-1 space-y-2 border-l border-border/60 pl-2.5">+ {panel.map((p, i) => (+ <div key={i} className="space-y-0.5">+ <span className="font-mono font-medium">{fusionRouteLabel(p)}</span>+ {p.status === 'failed'+ ? <span className="ml-1.5 text-amber-600 dark:text-amber-400">{t('playground.fusionFailed')}{p.error ? `: ${p.error}` : ''}</span>+ : p.content+ ? <div className="whitespace-pre-wrap opacity-80">{p.content}</div>+ : <span className="ml-1.5 opacity-60">…</span>}+ </div>+ ))}+ {judge && (+ <div className="pt-1.5 border-t border-border/60">+ <span className="font-mono font-medium">{fusionRouteLabel(judge)}</span>+ <span className="ml-1.5 opacity-70">{t('playground.fusionJudgeSynth')}</span>+ </div>+ )}+ </div>+ )}+ </div>+ )+}+export default function PlaygroundPage() {const { t } = useI18n()const [messages, setMessages] = useState<ChatMessage[]>([])@@ -57,6 +132,58 @@ export default function PlaygroundPage() {messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })}, [messages])+ // Read a fusion SSE stream, updating the assistant message in place as panel+ // answers + the judge arrive (additive `_fusion` frames) and the final answer+ // streams as content deltas.+ const streamFusion = async (stream: ReadableStream<Uint8Array>, baseMessages: ChatMessage[], start: number) => {+ const reader = stream.getReader()+ const dec = new TextDecoder()+ let buf = ''+ let finalContent = ''+ const panel: FusionPanelEntry[] = []+ let judge: { platform: string; model: string } | null = null++ const flush = (streaming: boolean) => {+ setMessages([...baseMessages, {+ role: 'assistant',+ content: finalContent,+ meta: { latency: Date.now() - start, fusionPanel: [...panel], fusionJudge: judge, fusionStreaming: streaming },+ }])+ }+ flush(true)++ for (;;) {+ const { done, value } = await reader.read()+ if (done) break+ buf += dec.decode(value, { stream: true })+ const lines = buf.split('\n')+ buf = lines.pop() ?? ''+ for (const line of lines) {+ const tl = line.trim()+ if (!tl.startsWith('data:')) continue+ const d = tl.slice(5).trim()+ if (d === '[DONE]') continue+ let obj: any+ try { obj = JSON.parse(d) } catch { continue }+ if (obj._fusion) {+ if (obj._fusion.event === 'panel') {+ panel.push({ platform: obj._fusion.platform, model: obj._fusion.model, status: obj._fusion.status, content: obj._fusion.content, error: obj._fusion.error })+ } else if (obj._fusion.event === 'judge') {+ judge = { platform: obj._fusion.platform, model: obj._fusion.model }+ }+ flush(true)+ } else if (obj.error) {+ finalContent = `${t('playground.errorPrefix')} ${obj.error.message}`+ flush(true)+ } else if (obj.choices) {+ const delta = obj.choices[0]?.delta?.content+ if (delta) { finalContent += delta; flush(true) }+ }+ }+ }+ flush(false)+ }+const handleSend = async () => {const text = input.trim()if (!text || loading) return@@ -72,10 +199,14 @@ export default function PlaygroundPage() {const headers: Record<string, string> = { 'Content-Type': 'application/json' }if (keyData?.apiKey) headers['Authorization'] = `Bearer ${keyData.apiKey}`+ const isFusion = selectedModel === 'fusion'const body: any = {messages: newMessages.map(m => ({ role: m.role, content: m.content })),}if (selectedModel !== 'auto') body.model = selectedModel+ // Fusion streams its panel + judge trace; ask for a stream so the+ // Playground can show the other models arriving before the final answer.+ if (isFusion) body.stream = trueconst base = import.meta.env.BASE_URL.replace(/\/$/, '')const start = Date.now()@@ -98,6 +229,11 @@ export default function PlaygroundPage() {return}+ if (isFusion && res.body) {+ await streamFusion(res.body, newMessages, start)+ return+ }+const data = await res.json()const content = data.choices?.[0]?.message?.content ?? JSON.stringify(data, null, 2)const via = data._routed_via ?? (routedVia ? {@@ -105,6 +241,13 @@ export default function PlaygroundPage() {model: routedVia.split('/').slice(1).join('/'),} : undefined)+ // Fusion responses carry a structured routing summary so we can show the+ // panel models that replied + the judge, rather than parsing the compact+ // X-Routed-Via string.+ const fusion = data._fusion as+ | { panel: { platform: string; model: string }[]; judge: { platform: string; model: string } | null }+ | undefined+setMessages([...newMessages, {role: 'assistant',content,@@ -113,6 +256,8 @@ export default function PlaygroundPage() {model: via?.model,latency,fallbackAttempts: fallbackAttempts ? parseInt(fallbackAttempts) : undefined,+ fusionPanel: fusion?.panel,+ fusionJudge: fusion?.judge,},}])} catch (err: any) {@@ -140,6 +285,8 @@ export default function PlaygroundPage() {const activeModelLabel = selectedModel === 'auto'? t('playground.autoModel')+ : selectedModel === 'fusion'+ ? t('playground.fusionModel'): availableModels.find(m => m.modelId === selectedModel)?.displayName ?? selectedModelreturn (@@ -155,6 +302,12 @@ export default function PlaygroundPage() {</SelectTrigger><SelectContent><SelectItem value="auto">{t('playground.autoModel')}</SelectItem>+ <SelectItem value="fusion">+ <span className="flex items-center gap-2">+ <span>{t('playground.fusionModel')}</span>+ <span className="rounded px-1 py-0.5 text-[9px] font-semibold uppercase leading-none tracking-wide bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">{t('models.newBadge')}</span>+ </span>+ </SelectItem>{availableModels.map(m => (<SelectItem key={m.modelDbId} value={m.modelId}><span className="flex items-center gap-2">@@ -194,41 +347,78 @@ export default function PlaygroundPage() {</div>) : (<>- {messages.map((msg, i) => (- <div key={i} className={`flex ${msg.role === 'user' ? 'justify-end' : 'justify-start'}`}>- <div- className={`group relative max-w-[78%] rounded-2xl px-4 py-2.5 text-sm leading-relaxed ${- msg.role === 'user'- ? 'bg-primary text-primary-foreground'- : 'bg-muted'- }`}- >- {msg.role === 'assistant' ? (- <Markdown>{msg.content}</Markdown>- ) : (- <div className="whitespace-pre-wrap">{msg.content}</div>- )}- {msg.role === 'assistant' && msg.content && (- <CopyButton- text={msg.content}- label={t('playground.copyReply')}- className="absolute right-1.5 top-1.5 size-6 opacity-0 transition-opacity focus-visible:opacity-100 group-hover:opacity-100"- />- )}- {msg.meta && (- <div className="flex items-center gap-2 mt-2 flex-wrap text-[11px] opacity-70 tabular-nums">- {msg.meta.platform && <span>{msg.meta.platform}</span>}- {msg.meta.model && <span className="font-mono">· {msg.meta.model}</span>}- {msg.meta.latency != null && <span>· {msg.meta.latency} ms</span>}- {msg.meta.fallbackAttempts != null && msg.meta.fallbackAttempts > 0 && (- <span>· {msg.meta.fallbackAttempts} {msg.meta.fallbackAttempts > 1 ? t('playground.fallbacks') : t('playground.fallback')}</span>- )}- </div>- )}+ {messages.map((msg, i) => {+ const fusionPanel = msg.meta?.fusionPanel+ const okPanel = fusionPanel?.filter(p => p.status !== 'failed') ?? []+ // Skip an empty assistant bubble while the fusion trace is still+ // streaming in (no final answer yet) — the trace shows below.+ const showBubble = msg.role === 'user' || msg.content.length > 0+ return (+ <div key={i} className={`flex ${msg.role === 'user' ? 'justify-end' : 'justify-start'}`}>+ <div className={`flex flex-col gap-1 max-w-[80%] ${msg.role === 'user' ? 'items-end' : 'items-start'}`}>+ {showBubble && (+ <div+ className={`group relative rounded-2xl px-4 py-2.5 text-sm leading-relaxed ${+ msg.role === 'user' ? 'bg-primary text-primary-foreground' : 'bg-muted'+ }`}+ >+ {msg.role === 'assistant' ? (+ <Markdown>{msg.content}</Markdown>+ ) : (+ <div className="whitespace-pre-wrap">{msg.content}</div>+ )}+ {msg.role === 'assistant' && msg.content && (+ <CopyButton+ text={msg.content}+ label={t('playground.copyReply')}+ className="absolute right-1.5 top-1.5 size-6 opacity-0 transition-opacity focus-visible:opacity-100 group-hover:opacity-100"+ />+ )}+ {msg.meta && (+ <div className="flex items-center gap-2 mt-2 flex-wrap text-[11px] opacity-70 tabular-nums">+ {(fusionPanel || msg.meta.fusionStreaming) ? (+ <>+ {okPanel.length > 0 && (+ <span>+ {t('playground.fusionPanel')}:{' '}+ <span className="font-mono">{okPanel.map(fusionRouteLabel).join(', ')}</span>+ </span>+ )}+ {msg.meta.fusionJudge && (+ <span>+ · {t('playground.fusionJudge')}:{' '}+ <span className="font-mono">{fusionRouteLabel(msg.meta.fusionJudge)}</span>+ </span>+ )}+ {msg.meta.latency != null && <span>· {msg.meta.latency} ms</span>}+ </>+ ) : (+ <>+ {msg.meta.platform && <span>{msg.meta.platform}</span>}+ {msg.meta.model && <span className="font-mono">· {msg.meta.model}</span>}+ {msg.meta.latency != null && <span>· {msg.meta.latency} ms</span>}+ {msg.meta.fallbackAttempts != null && msg.meta.fallbackAttempts > 0 && (+ <span>· {msg.meta.fallbackAttempts} {msg.meta.fallbackAttempts > 1 ? t('playground.fallbacks') : t('playground.fallback')}</span>+ )}+ </>+ )}+ </div>+ )}+ </div>+ )}+ {msg.role === 'assistant' && fusionPanel && fusionPanel.length > 0 && (+ <FusionTrace+ panel={fusionPanel}+ judge={msg.meta?.fusionJudge}+ streaming={msg.meta?.fusionStreaming}+ answerStarted={msg.content.length > 0}+ />+ )}+ </div></div>- </div>- ))}- {loading && (+ )+ })}+ {loading && !messages[messages.length - 1]?.meta?.fusionStreaming && (<div className="flex justify-start"><div className="bg-muted rounded-2xl px-4 py-3"><div className="flex gap-1">diff --git a/server/src/__tests__/routes/fusion.test.ts b/server/src/__tests__/routes/fusion.test.tsnew file mode 100644index 00000000..ca65495d--- /dev/null+++ b/server/src/__tests__/routes/fusion.test.ts@@ -0,0 +1,411 @@+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';+import type { Express } from 'express';+import { createApp } from '../../app.js';+import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';+import { isFusionModel, fusionConfigSchema } from '../../services/fusion.js';+import { getOrderedFusionChain, setRoutingStrategy, getRoutingStrategy } from '../../services/router.js';+import { setCooldown } from '../../services/ratelimit.js';++let dashToken = '';++async function request(app: Express, method: string, path: string, body?: any, headers: Record<string, string> = {}) {+ const server = app.listen(0);+ const addr = server.address() as any;+ const url = `http://127.0.0.1:${addr.port}${path}`;+ const res = await fetch(url, {+ method,+ headers: { ...(body ? { 'Content-Type': 'application/json' } : {}), ...(isGatedApiPath(path) && !('Authorization' in headers) ? { Authorization: `Bearer ${dashToken}` } : {}), ...headers },+ body: body ? JSON.stringify(body) : undefined,+ });+ const text = await res.text();+ server.close();+ let json: any = null;+ try { json = JSON.parse(text); } catch { /* non-JSON (SSE) */ }+ return { status: res.status, body: json, text };+}++function authHeaders() {+ return { Authorization: `Bearer ${getUnifiedApiKey()}` };+}++// Build a fetch mock that returns a fixed answer for a given upstream host, or+// a 429 for hosts listed in `rateLimited`. Lets each test stage which panel+// members succeed/fail purely by URL.+// A minimal OpenAI-wire SSE body for the streaming judge path.+function sseBody(content: string): ReadableStream<Uint8Array> {+ const enc = new TextEncoder();+ const frames = [+ `data: ${JSON.stringify({ choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] })}\n\n`,+ `data: ${JSON.stringify({ choices: [{ index: 0, delta: { content }, finish_reason: null }] })}\n\n`,+ `data: ${JSON.stringify({ choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] })}\n\n`,+ 'data: [DONE]\n\n',+ ];+ return new ReadableStream({ start(c) { for (const f of frames) c.enqueue(enc.encode(f)); c.close(); } });+}++function mockUpstreams(answers: Record<string, string>, rateLimited: Set<string> = new Set(), streamAnswers: Record<string, string> = {}) {+ const origFetch = global.fetch;+ vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {+ const u = typeof url === 'string' ? url : url.toString();+ for (const host of rateLimited) {+ if (u.includes(host)) {+ return { ok: false, status: 429, headers: new Headers(), text: () => Promise.resolve('rate limited') } as any;+ }+ }+ // Streaming (judge) hosts return an SSE body consumed by streamChatCompletion.+ for (const [host, content] of Object.entries(streamAnswers)) {+ if (u.includes(host)) {+ return { ok: true, status: 200, headers: new Headers(), body: sseBody(content) } as any;+ }+ }+ for (const [host, content] of Object.entries(answers)) {+ if (u.includes(host)) {+ return {+ ok: true,+ json: () => Promise.resolve({+ id: 'chatcmpl-x', object: 'chat.completion', created: 1, model: 'm',+ choices: [{ index: 0, message: { role: 'assistant', content }, finish_reason: 'stop' }],+ usage: { prompt_tokens: 5, completion_tokens: 7, total_tokens: 12 },+ }),+ } as any;+ }+ }+ return origFetch(url as any, init as any);+ });+}++describe('isFusionModel', () => {+ it('matches the virtual fusion id and its suffix form, nothing else', () => {+ expect(isFusionModel('fusion')).toBe(true);+ expect(isFusionModel('FUSION')).toBe(true);+ expect(isFusionModel('fusion:smart')).toBe(true);+ expect(isFusionModel('auto')).toBe(false);+ expect(isFusionModel('gpt-oss-120b')).toBe(false);+ expect(isFusionModel(undefined)).toBe(false);+ });+});++describe('fusionConfigSchema', () => {+ it('accepts an empty object and a fully specified config', () => {+ expect(fusionConfigSchema.safeParse({}).success).toBe(true);+ const full = fusionConfigSchema.safeParse({ models: ['a', 'b'], k: 4, judge: 'j', strategy: 'synthesize', expose_panel: true });+ expect(full.success).toBe(true);+ });+ it('rejects a non-positive k and an unknown strategy', () => {+ expect(fusionConfigSchema.safeParse({ k: 0 }).success).toBe(false);+ expect(fusionConfigSchema.safeParse({ strategy: 'vote' }).success).toBe(false);+ });+});++describe('fusion route (/v1/chat/completions, model: "fusion")', () => {+ let app: Express;+ let groqModel: string;+ let cerebrasModel: string;+ let openrouterModel: string;++ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ app = createApp();+ dashToken = mintDashboardToken();+ const db = getDb();+ const pick = (platform: string) => (db.prepare(+ 'SELECT m.model_id FROM models m WHERE m.platform = ? AND m.enabled = 1 ORDER BY m.intelligence_rank LIMIT 1',+ ).get(platform) as { model_id: string }).model_id;+ groqModel = pick('groq');+ cerebrasModel = pick('cerebras');+ openrouterModel = pick('openrouter');+ });++ beforeEach(async () => {+ const db = getDb();+ db.prepare('DELETE FROM api_keys').run();+ db.prepare('DELETE FROM requests').run();+ db.prepare("DELETE FROM settings WHERE key = 'fusion_config'").run();+ for (const platform of ['groq', 'cerebras', 'openrouter']) {+ const r = await request(app, 'POST', '/api/keys', { platform, key: `k_${platform}_fusion`, label: 'fusion-test' });+ expect(r.status).toBe(201);+ }+ });++ afterEach(() => vi.restoreAllMocks());++ it('synthesizes one answer when ≥2 panel members succeed (judge runs)', async () => {+ mockUpstreams({+ 'api.groq.com': 'groq says alpha',+ 'api.cerebras.ai': 'cerebras says beta',+ 'openrouter.ai': 'JUDGE FINAL ANSWER',+ });+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel, cerebrasModel], judge: openrouterModel, expose_panel: true },+ }, authHeaders());++ expect(status).toBe(200);+ expect(body.model).toBe('fusion');+ expect(body.choices[0].message.content).toBe('JUDGE FINAL ANSWER');+ expect(body.x_fusion.synthesized).toBe(true);+ expect(body.x_fusion.judge).toContain('openrouter');+ expect(body.x_fusion.panel.filter((p: any) => p.status === 'ok')).toHaveLength(2);+ // Honest usage: two panel calls + judge, 12 tokens each.+ expect(body.usage.total_tokens).toBe(36);+ // Always-on routing summary: the panel models that replied + the judge.+ expect(body._fusion.panel.map((p: any) => p.model).sort()).toEqual([groqModel, cerebrasModel].sort());+ expect(body._fusion.panel.every((p: any) => typeof p.platform === 'string')).toBe(true);+ expect(body._fusion.judge).toEqual({ platform: 'openrouter', model: openrouterModel });+ expect(body._fusion.synthesized).toBe(true);+ });++ it('returns the lone survivor directly (no judge) when only one panel member succeeds', async () => {+ mockUpstreams(+ { 'api.groq.com': 'only groq survived' },+ new Set(['api.cerebras.ai']),+ );+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel, cerebrasModel], expose_panel: true },+ }, authHeaders());++ expect(status).toBe(200);+ expect(body.choices[0].message.content).toBe('only groq survived');+ expect(body.x_fusion.synthesized).toBe(false);+ expect(body.x_fusion.panel.find((p: any) => p.status === 'failed')).toBeTruthy();+ // Routing summary present even without a judge: one survivor, judge null.+ expect(body._fusion.panel).toEqual([{ platform: 'groq', model: groqModel }]);+ expect(body._fusion.judge).toBeNull();+ });++ it('best_of strategy skips the judge even with a full panel', async () => {+ mockUpstreams({+ 'api.groq.com': 'short',+ 'api.cerebras.ai': 'a noticeably longer answer that best_of should prefer',+ 'openrouter.ai': 'JUDGE SHOULD NOT RUN',+ });+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel, cerebrasModel], judge: openrouterModel, strategy: 'best_of', expose_panel: true },+ }, authHeaders());++ expect(status).toBe(200);+ expect(body.x_fusion.synthesized).toBe(false);+ expect(body.choices[0].message.content).toContain('longer answer'); // longest, not the judge+ });++ it('returns 429 when the entire panel fails', async () => {+ mockUpstreams({}, new Set(['api.groq.com', 'api.cerebras.ai']));+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel, cerebrasModel] },+ }, authHeaders());+ expect(status).toBe(429);+ expect(body.error.type).toBe('rate_limit_error');+ });++ it('drops unknown models from an explicit panel and reports them', async () => {+ mockUpstreams({ 'api.groq.com': 'groq answer' });+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel, 'no-such-model'], expose_panel: true },+ }, authHeaders());+ expect(status).toBe(200);+ expect(body.x_fusion.dropped.some((d: string) => d.includes('no-such-model'))).toBe(true);+ });++ it('rejects tool-bearing fusion requests with 422', async () => {+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ tools: [{ type: 'function', function: { name: 'f', parameters: {} } }],+ }, authHeaders());+ expect(status).toBe(422);+ expect(body.error.code).toBe('fusion_no_tools');+ });++ it('tags every panel/judge sub-call with requested_model="fusion"', async () => {+ mockUpstreams({+ 'api.groq.com': 'a', 'api.cerebras.ai': 'b', 'openrouter.ai': 'judged',+ });+ await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel, cerebrasModel], judge: openrouterModel },+ }, authHeaders());+ const rows = getDb().prepare("SELECT requested_model, status FROM requests").all() as any[];+ expect(rows.length).toBeGreaterThanOrEqual(3); // 2 panel + judge+ expect(rows.every(r => r.requested_model === 'fusion')).toBe(true);+ });++ it('GET /api/settings/fusion returns defaults; PUT round-trips, clamps k, dedupes models', async () => {+ const def = await request(app, 'GET', '/api/settings/fusion', undefined);+ expect(def.status).toBe(200);+ expect(def.body.config.mode).toBe('auto');+ expect(def.body.maxK).toBeGreaterThan(0);++ const put = await request(app, 'PUT', '/api/settings/fusion', {+ mode: 'explicit',+ models: [groqModel, groqModel, cerebrasModel], // dup groq+ judge: openrouterModel,+ k: 999, // over the cap+ strategy: 'synthesize',+ expose_panel: true,+ });+ expect(put.status).toBe(200);+ expect(put.body.config.models).toEqual([groqModel, cerebrasModel]); // deduped+ expect(put.body.config.k).toBe(put.body.maxK); // clamped++ const get = await request(app, 'GET', '/api/settings/fusion', undefined);+ expect(get.body.config.mode).toBe('explicit');+ expect(get.body.config.judge).toBe(openrouterModel);+ });++ it('uses the saved explicit panel when a request omits fusion.models', async () => {+ await request(app, 'PUT', '/api/settings/fusion', {+ mode: 'explicit', models: [groqModel, cerebrasModel], judge: openrouterModel,+ k: 4, strategy: 'synthesize', expose_panel: true,+ });+ mockUpstreams({ 'api.groq.com': 'a', 'api.cerebras.ai': 'b', 'openrouter.ai': 'SAVED PANEL JUDGE' });++ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion', messages: [{ role: 'user', content: 'q' }],+ }, authHeaders());+ expect(status).toBe(200);+ expect(body.choices[0].message.content).toBe('SAVED PANEL JUDGE');+ expect(body.x_fusion.panel_requested.sort()).toEqual([groqModel, cerebrasModel].sort());+ });++ it('a per-request fusion.models overrides the saved explicit panel', async () => {+ await request(app, 'PUT', '/api/settings/fusion', {+ mode: 'explicit', models: [cerebrasModel], judge: openrouterModel,+ k: 4, strategy: 'synthesize', expose_panel: true,+ });+ mockUpstreams({ 'api.groq.com': 'only groq', 'api.cerebras.ai': 'b' });++ const { body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion', messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel] }, // overrides the saved [cerebras]+ }, authHeaders());+ expect(body.x_fusion.panel_requested).toEqual([groqModel]);+ });++ it('auto-panel ordering follows the picked routing strategy, deterministically', () => {+ const original = getRoutingStrategy();+ try {+ // Priority mode: ordering is the manual chain order, and stable.+ setRoutingStrategy('priority');+ const p1 = getOrderedFusionChain().map(c => c.modelId);+ const p2 = getOrderedFusionChain().map(c => c.modelId);+ expect(p1.length).toBeGreaterThan(0);+ expect(p2).toEqual(p1);++ // Bandit mode: previously Thompson-sampled (random per call); now the+ // deterministic expected-score ranking, so two calls must be identical.+ setRoutingStrategy('smartest');+ const s1 = getOrderedFusionChain().map(c => c.modelId);+ const s2 = getOrderedFusionChain().map(c => c.modelId);+ expect(s2).toEqual(s1);++ // The strategy actually drives the ordering: 'smartest' (intelligence)+ // and 'priority' (manual chain order) rank the seeded catalog differently.+ expect(s1).not.toEqual(p1);+ } finally {+ setRoutingStrategy(original);+ }+ });++ it('auto-panel excludes models whose platform has no usable key', async () => {+ const db = getDb();+ // Strip every key, then configure ONLY groq — no cerebras/openrouter/etc.+ db.prepare('DELETE FROM api_keys').run();+ const r = await request(app, 'POST', '/api/keys', { platform: 'groq', key: 'k_groq_only', label: 'only-groq' });+ expect(r.status).toBe(201);++ const candidates = getOrderedFusionChain();+ expect(candidates.length).toBeGreaterThan(0);+ // Even though the seeded catalog has many higher-ranked models on other+ // platforms (cerebras, openrouter, opencode…), none are routable without a+ // key — so the panel pool is groq-only.+ expect(candidates.every(c => c.platform === 'groq')).toBe(true);+ });++ it('auto-panel excludes a model whose only key is on cooldown', async () => {+ const db = getDb();+ db.prepare('DELETE FROM api_keys').run();+ await request(app, 'POST', '/api/keys', { platform: 'groq', key: 'k_groq_cool', label: 'cool' });+ const keyId = (db.prepare("SELECT id FROM api_keys WHERE platform = 'groq'").get() as { id: number }).id;++ const before = getOrderedFusionChain().filter(c => c.platform === 'groq');+ expect(before.length).toBeGreaterThan(0);+ const target = before[0]; // the top groq model under the strategy++ // Bench that exact model+key (as a 402/429 cooldown would), then re-check.+ setCooldown('groq', target.modelId, keyId, 60_000);+ const after = getOrderedFusionChain();+ expect(after.find(c => c.modelId === target.modelId)).toBeUndefined();+ });++ it('auto-panel refills failed slots from the fallback chain', async () => {+ // groq is entirely rate-limited; cerebras + openrouter answer. The two groq+ // panel slots fail, and the panel refills from the next chain models.+ mockUpstreams(+ { 'api.cerebras.ai': 'cerebras answer', 'openrouter.ai': 'openrouter answer' },+ new Set(['api.groq.com']),+ );+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ messages: [{ role: 'user', content: 'q' }],+ fusion: { k: 3, judge: cerebrasModel, expose_panel: true },+ }, authHeaders());+ expect(status).toBe(200);++ const attempts = body.x_fusion.panel;+ // More models were tried than the initial 3-model panel → a slot refilled.+ expect(attempts.length).toBeGreaterThan(3);+ const ok = attempts.filter((p: any) => p.status === 'ok');+ expect(ok.length).toBeGreaterThanOrEqual(2);+ // The survivors came from the chain refill, not groq (which was down).+ expect(ok.every((p: any) => p.platform !== 'groq')).toBe(true);+ expect(attempts.some((p: any) => p.platform === 'groq' && p.status === 'failed')).toBe(true);+ });++ it('streams panel + judge trace frames then the final answer when stream:true', async () => {+ // Panel models answer via chatCompletion (JSON); the judge streams (SSE).+ mockUpstreams(+ { 'api.groq.com': 'panel answer A', 'api.cerebras.ai': 'panel answer B' },+ new Set(),+ { 'openrouter.ai': 'STREAMED SYNTHESIS' },+ );+ const { status, text } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'fusion',+ stream: true,+ messages: [{ role: 'user', content: 'q' }],+ fusion: { models: [groqModel, cerebrasModel], judge: openrouterModel },+ }, authHeaders());+ expect(status).toBe(200);++ // Parse the SSE frames.+ const frames = text.split('\n')+ .filter(l => l.startsWith('data: ') && l.slice(6).trim() !== '[DONE]')+ .map(l => JSON.parse(l.slice(6)));++ // Additive _fusion frames: one panel frame per member, plus a judge frame.+ const panelFrames = frames.filter(f => f._fusion?.event === 'panel');+ expect(panelFrames).toHaveLength(2);+ expect(panelFrames.map(f => f._fusion.model).sort()).toEqual([groqModel, cerebrasModel].sort());+ expect(panelFrames.every(f => f._fusion.status === 'ok' && typeof f._fusion.content === 'string')).toBe(true);+ const judgeFrame = frames.find(f => f._fusion?.event === 'judge');+ expect(judgeFrame._fusion).toMatchObject({ platform: 'openrouter', model: openrouterModel });++ // The final answer still streams as standard content deltas + terminal stop.+ expect(text).toContain('STREAMED SYNTHESIS');+ expect(text).toContain('"finish_reason":"stop"');+ expect(text.trimEnd().endsWith('data: [DONE]')).toBe(true);+ // _fusion panel frames precede the final content frame.+ expect(text.indexOf('"event":"panel"')).toBeLessThan(text.indexOf('STREAMED SYNTHESIS'));+ });+});diff --git a/server/src/lib/error-classify.ts b/server/src/lib/error-classify.tsnew file mode 100644index 00000000..fa9c9eb9--- /dev/null+++ b/server/src/lib/error-classify.ts@@ -0,0 +1,81 @@+// Upstream-error classification shared by the proxy chat path, the responses+// path, and the fusion panel. Pure functions over an error's message/status —+// no I/O — so they live in a neutral lib module that any of those can import+// without forming an import cycle (fusion ↔ proxy in particular).++export function isRetryableError(err: any): boolean {+ const msg = (err.message ?? '').toLowerCase();+ return msg.includes('429') || msg.includes('rate limit') || msg.includes('too many requests')+ || msg.includes('quota') || msg.includes('resource_exhausted')+ || msg.includes('aborted') || msg.includes('timeout') || msg.includes('etimedout')+ || msg.includes('econnrefused') || msg.includes('econnreset')+ || msg.includes('fetch failed') // undici transport error (proxy down, DNS, TLS, etc.)+ || msg.includes('503') || msg.includes('unavailable')+ || msg.includes('500') || msg.includes('internal server error')+ // 413: this model's payload limit is too small for the request, but another+ // provider in the fallback chain may have a larger limit. Same reasoning as 503.+ || msg.includes('413') || msg.includes('payload too large') || msg.includes('request body too large')+ || msg.includes('request entity too large') || msg.includes('content too large')+ // 404: model deprecated/removed upstream (e.g. OpenRouter's "no endpoints found"+ // for a model that's been pulled). Rotate to the next model in the chain —+ // setCooldown + the health checker will avoid this model on subsequent requests.+ || msg.includes('404') || msg.includes('not found') || msg.includes('no endpoints found')+ // 403: the key is valid (it passed validateKey, and the health checker+ // disables truly-forbidden keys) but this specific model is off-limits to+ // the key's tier — e.g. gpt-4o on GitHub Models' free tier, subscription-only+ // models on Cloudflare. Another model in the chain is reachable, so fail over+ // instead of 502-ing the whole request. Paired with isModelAccessForbiddenError+ // to rule the model out for this request and a day-long bench. See issue #256.+ || isModelAccessForbiddenError(err)+ // 400: one provider may reject parameters another accepts (e.g. max_tokens+ // limits, unsupported params). The matching pattern is "api error 400"+ // which comes from the OpenAI-compat provider's error formatting, not+ // a bare "400" which is deliberately non-retryable for validation errors.+ || msg.includes('api error 400')+ // 402: this provider/key is out of credits (e.g. HuggingFace Router+ // "API error 402: Payment required"). The SAME model often lives on another+ // provider (Kimi K2.6 is on HF + Cloudflare + NVIDIA), so fail over instead+ // of killing the workflow. Paired with a long cooldown (isPaymentRequiredError)+ // so we don't re-hammer the broke key every retry.+ || isPaymentRequiredError(err)+ // Dead-turn classes from the stream turn-integrity layer (#231 audit):+ // all thrown before any byte reached the client, so another model can+ // serve the request invisibly.+ || msg.includes('empty completion')+ || msg.includes('in-band provider error')+ || msg.includes('stream ended unexpectedly')+ || msg.includes('stream stalled')+ || msg.includes('unparseable inline tool-call dialect');+}++// A 402 Payment Required / out-of-credits error. Distinct from a transient 429:+// it won't recover on the next window, so the caller benches the model+key with+// PAYMENT_REQUIRED_COOLDOWN_MS (a full day) rather than the 90s transient cooldown.+export function isPaymentRequiredError(err: any): boolean {+ const msg = (err.message ?? '').toLowerCase();+ return msg.includes('402') || msg.includes('payment required')+ || msg.includes('insufficient_quota') || msg.includes('insufficient credit')+ || msg.includes('insufficient balance');+}++// A 404 "model removed/deprecated upstream" error. It's a MODEL-level failure,+// not a key-level one: every key for the platform will 404 the same way, so the+// retry loop skips the entire model for the rest of the request instead of+// burning one fallback attempt per key on the same dead route.+// (PR #111, credits @barbotkonv.)+export function isModelNotFoundError(err: any): boolean {+ const msg = (err.message ?? '').toLowerCase();+ return msg.includes('404') || msg.includes('not found') || msg.includes('no endpoints found');+}++// A 403 Forbidden returned for a specific model behind an otherwise-valid key.+// Drives the same whole-model skip as a 404: every key on this platform's tier+// would be forbidden the same model, so rule it out for the rest of the request+// rather than trying it again with a sibling key. Distinct from a dead key —+// validateKey returns false on 401/403, so the health checker disables genuinely+// forbidden keys; a 403 reaching here is model-not-on-this-tier. See issue #256.+export function isModelAccessForbiddenError(err: any): boolean {+ if (err?.status === 403) return true;+ const msg = (err?.message ?? '').toLowerCase();+ return msg.includes('403') || msg.includes('forbidden');+}diff --git a/server/src/lib/request-log.ts b/server/src/lib/request-log.tsnew file mode 100644index 00000000..ad28d9cc--- /dev/null+++ b/server/src/lib/request-log.ts@@ -0,0 +1,33 @@+import { getDb } from '../db/index.js';+import { pruneRequestAnalytics } from '../services/request-retention.js';++// Append a row to the request analytics table. Shared by the chat proxy, the+// responses path, and the fusion panel so every served (or failed) sub-request+// is logged identically. Lives in a neutral lib module to avoid an import cycle+// between the fusion service and the proxy route that both call it.+export function logRequest(+ platform: string,+ modelId: string,+ keyId: number,+ status: string,+ inputTokens: number,+ outputTokens: number,+ latencyMs: number,+ error: string | null,+ ttfbMs: number | null = null,+ // The model id the client pinned; null for auto-routed requests. Lets+ // analytics split pinned vs auto traffic and detect failover overrides+ // (requested_model set but != model_id).+ requestedModel: string | null = null,+) {+ try {+ const db = getDb();+ db.prepare(`+ INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, ttfb_ms, requested_model)+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ `).run(platform, modelId, keyId, status, inputTokens, outputTokens, latencyMs, error, ttfbMs, requestedModel);+ pruneRequestAnalytics({ db });+ } catch (e) {+ console.error('Failed to log request:', e);+ }+}diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.tsindex 169c6fd4..0c713f2f 100644--- a/server/src/routes/proxy.ts+++ b/server/src/routes/proxy.ts@@ -5,7 +5,6 @@ import { z } from 'zod';import type { ChatMessage, ModelListRow } from '@freellmapi/shared/types.js';import { routeRequest, resolveRoutingChain, recordRateLimitHit, recordSuccess, hasEnabledVisionModel, hasEnabledToolsModel, type RouteResult, type ResolvedChain } from '../services/router.js';import { recordRequest, recordTokens, setCooldown, getCooldownDurationForLimit, PAYMENT_REQUIRED_COOLDOWN_MS, MODEL_FORBIDDEN_COOLDOWN_MS } from '../services/ratelimit.js';-import { pruneRequestAnalytics } from '../services/request-retention.js';import { runEmbeddings, EmbeddingsError } from '../services/embeddings.js';import { getDb, getUnifiedApiKey } from '../db/index.js';import { contentToString, messageHasImage, normalizeOutboundContent } from '../lib/content.js';@@ -13,6 +12,9 @@ import { repairToolArguments, toolSchemaMap } from '../lib/tool-args.js';import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';import { rescueInlineToolCalls, startsWithDialectMarker, couldBecomeDialectMarker, containsDialectMarker } from '../lib/tool-call-rescue.js';import { getContextHandoffMode, recordIncomingMessages, maybeInjectContextHandoff, recordSuccessfulModel, hasPriorModel, HANDOFF_MAX_TOKENS } from '../services/context-handoff.js';+import { isFusionModel, runFusion, fusionConfigSchema, FusionError, FUSION_MODEL_ID } from '../services/fusion.js';+import { isRetryableError, isPaymentRequiredError, isModelNotFoundError, isModelAccessForbiddenError } from '../lib/error-classify.js';+import { logRequest } from '../lib/request-log.js';export const proxyRouter = Router();@@ -184,6 +186,18 @@ proxyRouter.get('/models', (req: Request, res: Response) => {available: true,unavailable_reason: null,},+ {+ id: FUSION_MODEL_ID,+ object: 'model',+ created: 0,+ owned_by: 'freellmapi',+ name: 'Fusion (panel of models answer in parallel, a judge synthesizes one answer)',+ context_window: autoContextWindow,+ context_length: autoContextWindow,+ // Available whenever auto is — fusion needs at least one routable model.+ available: autoContextWindow != null,+ unavailable_reason: autoContextWindow != null ? null : 'no_models',+ },...listed.map(m => ({id: m.model_id,object: 'model',@@ -339,84 +353,16 @@ const chatCompletionSchema = z.object({tools: z.array(toolDefinitionSchema).nullable().optional(),tool_choice: toolChoiceSchema.nullable().optional(),parallel_tool_calls: z.boolean().nullable().optional(),+ // Fusion config — only meaningful when `model` is the virtual "fusion" id.+ // Ignored for every other model. See services/fusion.ts.+ fusion: fusionConfigSchema.optional(),});-export function isRetryableError(err: any): boolean {- const msg = (err.message ?? '').toLowerCase();- return msg.includes('429') || msg.includes('rate limit') || msg.includes('too many requests')- || msg.includes('quota') || msg.includes('resource_exhausted')- || msg.includes('aborted') || msg.includes('timeout') || msg.includes('etimedout')- || msg.includes('econnrefused') || msg.includes('econnreset')- || msg.includes('fetch failed') // undici transport error (proxy down, DNS, TLS, etc.)- || msg.includes('503') || msg.includes('unavailable')- || msg.includes('500') || msg.includes('internal server error')- // 413: this model's payload limit is too small for the request, but another- // provider in the fallback chain may have a larger limit. Same reasoning as 503.- || msg.includes('413') || msg.includes('payload too large') || msg.includes('request body too large')- || msg.includes('request entity too large') || msg.includes('content too large')- // 404: model deprecated/removed upstream (e.g. OpenRouter's "no endpoints found"- // for a model that's been pulled). Rotate to the next model in the chain —- // setCooldown + the health checker will avoid this model on subsequent requests.- || msg.includes('404') || msg.includes('not found') || msg.includes('no endpoints found')- // 403: the key is valid (it passed validateKey, and the health checker- // disables truly-forbidden keys) but this specific model is off-limits to- // the key's tier — e.g. gpt-4o on GitHub Models' free tier, subscription-only- // models on Cloudflare. Another model in the chain is reachable, so fail over- // instead of 502-ing the whole request. Paired with isModelAccessForbiddenError- // to rule the model out for this request and a day-long bench. See issue #256.- || isModelAccessForbiddenError(err)- // 400: one provider may reject parameters another accepts (e.g. max_tokens- // limits, unsupported params). The matching pattern is "api error 400"- // which comes from the OpenAI-compat provider's error formatting, not- // a bare "400" which is deliberately non-retryable for validation errors.- || msg.includes('api error 400')- // 402: this provider/key is out of credits (e.g. HuggingFace Router- // "API error 402: Payment required"). The SAME model often lives on another- // provider (Kimi K2.6 is on HF + Cloudflare + NVIDIA), so fail over instead- // of killing the workflow. Paired with a long cooldown (isPaymentRequiredError)- // so we don't re-hammer the broke key every retry.- || isPaymentRequiredError(err)- // Dead-turn classes from the stream turn-integrity layer (#231 audit):- // all thrown before any byte reached the client, so another model can- // serve the request invisibly.- || msg.includes('empty completion')- || msg.includes('in-band provider error')- || msg.includes('stream ended unexpectedly')- || msg.includes('stream stalled')- || msg.includes('unparseable inline tool-call dialect');-}--// A 402 Payment Required / out-of-credits error. Distinct from a transient 429:-// it won't recover on the next window, so the caller benches the model+key with-// PAYMENT_REQUIRED_COOLDOWN_MS (a full day) rather than the 90s transient cooldown.-export function isPaymentRequiredError(err: any): boolean {- const msg = (err.message ?? '').toLowerCase();- return msg.includes('402') || msg.includes('payment required')- || msg.includes('insufficient_quota') || msg.includes('insufficient credit')- || msg.includes('insufficient balance');-}--// A 404 "model removed/deprecated upstream" error. It's a MODEL-level failure,-// not a key-level one: every key for the platform will 404 the same way, so the-// retry loop skips the entire model for the rest of the request instead of-// burning one fallback attempt per key on the same dead route.-// (PR #111, credits @barbotkonv.)-export function isModelNotFoundError(err: any): boolean {- const msg = (err.message ?? '').toLowerCase();- return msg.includes('404') || msg.includes('not found') || msg.includes('no endpoints found');-}--// A 403 Forbidden returned for a specific model behind an otherwise-valid key.-// Drives the same whole-model skip as a 404: every key on this platform's tier-// would be forbidden the same model, so rule it out for the rest of the request-// rather than trying it again with a sibling key. Distinct from a dead key —-// validateKey returns false on 401/403, so the health checker disables genuinely-// forbidden keys; a 403 reaching here is model-not-on-this-tier. See issue #256.-export function isModelAccessForbiddenError(err: any): boolean {- if (err?.status === 403) return true;- const msg = (err?.message ?? '').toLowerCase();- return msg.includes('403') || msg.includes('forbidden');-}+// Upstream-error classifiers live in lib/error-classify.ts so the fusion+// service can share them without an import cycle; imported above for internal+// use and re-exported here for existing importers (routes/responses.ts,+// proxy-retry.test.ts) that pull them from this module.+export { isRetryableError, isPaymentRequiredError, isModelNotFoundError, isModelAccessForbiddenError };// Pull the incremental text out of a streaming chunk for token counting.// Must tolerate chunks that carry no `choices` array at all: some providers@@ -648,6 +594,94 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {return;}+ // ── Fusion: multi-model synthesis ──────────────────────────────────────────+ // The virtual "fusion" model fans the prompt out to a panel of diverse models+ // in parallel, then a judge synthesizes one answer. It routes each panel/judge+ // sub-call through the normal path (cooldowns, quotas, analytics), so it+ // behaves like a normal model from the client's side — just K+1x the tokens.+ // v1 has no tools/vision/streaming-panel; reject the first two up front and+ // replay the synthesized answer as a single SSE turn when stream is set.+ if (isFusionModel(requestedModel)) {+ if (hasImage) {+ res.status(422).json({ error: { message: 'Fusion does not support image input yet. Use a vision model directly.', type: 'invalid_request_error', code: 'fusion_no_vision' } });+ return;+ }+ if (wantsTools) {+ res.status(422).json({ error: { message: 'Fusion does not support tool calling yet. Use a tool-capable model directly.', type: 'invalid_request_error', code: 'fusion_no_tools' } });+ return;+ }+ const fusionOptions = { temperature, max_tokens, top_p };+ const fusionConfig = parsed.data.fusion ?? {};++ if (stream) {+ // Streaming fusion: open the SSE response immediately and emit additive+ // `_fusion` frames (no `choices`, so standard OpenAI clients skip them) as+ // each panel model settles and when the judge runs — the Playground shows+ // these arriving in a collapsible trace. The final synthesized answer is+ // then streamed as normal content deltas, so plain clients still get it.+ res.setHeader('Content-Type', 'text/event-stream');+ res.setHeader('Cache-Control', 'no-cache');+ res.setHeader('Connection', 'keep-alive');+ const writeFrame = (o: unknown) => { try { res.write(`data: ${JSON.stringify(o)}\n\n`); } catch { /* socket gone */ } };+ const streamId = `fusion-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;+ const base = { id: streamId, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model: FUSION_MODEL_ID };+ // Track whether the judge already streamed content so we don't re-emit it.+ let answerStarted = false;+ try {+ const { response } = await runFusion({+ messages,+ config: fusionConfig,+ options: fusionOptions,+ estimatedTokens: estimatedTotal,+ hooks: {+ // `a` already carries a sanitized error for failed slots; content is+ // the model's own answer and is forwarded as-is.+ onPanel: (a) => writeFrame({ _fusion: { event: 'panel', ...a } }),+ onJudge: (j) => writeFrame({ _fusion: { event: 'judge', ...j } }),+ // Stream the judge's synthesis live as standard content deltas, so+ // the final answer appears as it's written instead of after the wait.+ onJudgeDelta: (delta) => {+ if (!answerStarted) { writeFrame({ ...base, choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] }); answerStarted = true; }+ writeFrame({ ...base, choices: [{ index: 0, delta: { content: delta }, finish_reason: null }] });+ },+ },+ });+ // best_of / single-survivor / judge-fell-back-to-best-of never streamed+ // a delta — emit the final answer as one chunk in that case.+ if (!answerStarted) {+ const finalText = contentToString(response.choices[0]?.message?.content ?? '');+ writeFrame({ ...base, choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] });+ writeFrame({ ...base, choices: [{ index: 0, delta: { content: finalText }, finish_reason: null }] });+ }+ writeFrame({ ...base, choices: [{ index: 0, delta: {}, finish_reason: 'stop' }], usage: response.usage });+ } catch (err: any) {+ const message = err instanceof FusionError ? err.message : `fusion error: ${sanitizeProviderErrorMessage(err?.message)}`;+ const type = err instanceof FusionError && err.status === 429 ? 'rate_limit_error' : 'server_error';+ writeFrame({ error: { message, type } });+ }+ try { res.write('data: [DONE]\n\n'); res.end(); } catch { /* socket gone */ }+ return;+ }++ try {+ const { response, routedVia } = await runFusion({+ messages,+ config: fusionConfig,+ options: fusionOptions,+ estimatedTokens: estimatedTotal,+ });+ res.setHeader('X-Routed-Via', routedVia);+ res.json(response);+ } catch (err: any) {+ if (err instanceof FusionError) {+ res.status(err.status).json({ error: { message: err.message, type: err.status === 429 ? 'rate_limit_error' : 'invalid_request_error' } });+ } else {+ res.status(502).json({ error: { message: `fusion error: ${sanitizeProviderErrorMessage(err?.message)}`, type: 'server_error' } });+ }+ }+ return;+ }+// Optional client-managed session affinity (see getSessionKey). Express// lower-cases header names; a repeated header arrives as an array — take// the first value.@@ -1116,29 +1150,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {});});-export function logRequest(- platform: string,- modelId: string,- keyId: number,- status: string,- inputTokens: number,- outputTokens: number,- latencyMs: number,- error: string | null,- ttfbMs: number | null = null,- // The model id the client pinned; null for auto-routed requests. Lets- // analytics split pinned vs auto traffic and detect failover overrides- // (requested_model set but != model_id).- requestedModel: string | null = null,-) {- try {- const db = getDb();- db.prepare(`- INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, ttfb_ms, requested_model)- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)- `).run(platform, modelId, keyId, status, inputTokens, outputTokens, latencyMs, error, ttfbMs, requestedModel);- pruneRequestAnalytics({ db });- } catch (e) {- console.error('Failed to log request:', e);- }-}+// logRequest moved to lib/request-log.ts (shared with the fusion service to+// avoid an import cycle); imported above for internal use and re-exported here+// for routes/responses.ts which imports it from this module.+export { logRequest };diff --git a/server/src/routes/settings.ts b/server/src/routes/settings.tsindex e4bfd9d7..68ccdf05 100644--- a/server/src/routes/settings.ts+++ b/server/src/routes/settings.ts@@ -2,9 +2,28 @@ import { Router } from 'express';import type { Request, Response } from 'express';import { getUnifiedApiKey, regenerateUnifiedKey, getSetting, setSetting } from '../db/index.js';import { applyProxyUrl, applyProxyEnabled, applyProxyBypass, isProxyActive, getProxyUrl, isProxyEnabled, getProxyBypassPlatforms } from '../lib/proxy.js';+import { getSavedFusionConfig, setSavedFusionConfig, savedFusionConfigSchema, getFusionMaxK } from '../services/fusion.js';export const settingsRouter = Router();+// Get the saved fusion default config (panel mode, models, judge, k, strategy).+settingsRouter.get('/fusion', (_req: Request, res: Response) => {+ res.json({ config: getSavedFusionConfig(), maxK: getFusionMaxK() });+});++// Save the fusion default config. A request's inline `fusion` field still+// overrides this per call (see services/fusion.ts resolveEffectiveConfig).+settingsRouter.put('/fusion', (req: Request, res: Response) => {+ const parsed = savedFusionConfigSchema.safeParse(req.body);+ if (!parsed.success) {+ const detail = parsed.error.errors.map(e => (e.path.length ? `${e.path.join('.')}: ${e.message}` : e.message)).slice(0, 5).join(', ');+ res.status(400).json({ error: { message: `Invalid fusion config: ${detail}`, type: 'invalid_request_error' } });+ return;+ }+ const saved = setSavedFusionConfig(parsed.data);+ res.json({ config: saved, maxK: getFusionMaxK() });+});+// Get the unified API keysettingsRouter.get('/api-key', (_req: Request, res: Response) => {res.json({ apiKey: getUnifiedApiKey() });diff --git a/server/src/services/fusion.ts b/server/src/services/fusion.tsnew file mode 100644index 00000000..4afcd767--- /dev/null+++ b/server/src/services/fusion.ts@@ -0,0 +1,621 @@+import { z } from 'zod';+import type { ChatMessage, ChatCompletionResponse, TokenUsage } from '@freellmapi/shared/types.js';+import {+ routePinnedModel, routeRequest, getOrderedFusionChain, resolveFusionCandidate,+ recordRateLimitHit, recordSuccess, type RouteResult, type FusionCandidate,+} from './router.js';+import {+ recordRequest, recordTokens, setCooldown, getCooldownDurationForLimit,+ PAYMENT_REQUIRED_COOLDOWN_MS, MODEL_FORBIDDEN_COOLDOWN_MS,+} from './ratelimit.js';+import { logRequest } from '../lib/request-log.js';+import {+ isRetryableError, isPaymentRequiredError,+ isModelNotFoundError, isModelAccessForbiddenError,+} from '../lib/error-classify.js';+import { contentToString } from '../lib/content.js';+import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';+import { getSetting, setSetting } from '../db/index.js';+import type { CompletionOptions } from '../providers/base.js';++// The virtual model id that triggers multi-model synthesis. Mirrors how+// `auto` is a virtual id the router intercepts (see routes/proxy.ts).+export const FUSION_MODEL_ID = 'fusion';++export function isFusionModel(modelId: string | undefined): boolean {+ if (!modelId) return false;+ const lower = modelId.toLowerCase();+ return lower === FUSION_MODEL_ID || lower.startsWith(`${FUSION_MODEL_ID}:`);+}++// Tag every panel/judge sub-call with this in the request log so fusion traffic+// is attributable in analytics exactly like a pinned model would be.+const FUSION_TAG = 'fusion';++// Panel sizing. Default is deliberately ABOVE OpenRouter's 3-model default —+// the whole point of running on free tiers is we can afford a wider, more+// diverse panel. Both are operator-overridable via settings so a deployment+// can dial the token multiplier up or down without a code change.+const DEFAULT_PANEL_K = 4;+const HARD_MAX_PANEL_K = 8; // ceiling even an explicit panel can't exceed+// A panel of fewer than this many *successful* answers isn't worth a judge+// pass — with one survivor we just return it directly.+const SYNTHESIS_QUORUM = 2;+// Per-slot key-rotation budget: a slot tries at most this many keys of its+// pinned model before it's dropped. Small — a model with every key cooled down+// should fail fast, not stall the whole panel.+const MAX_SLOT_ATTEMPTS = 4;+// Judge dispatch walks the normal auto chain; give it room to fail over.+const MAX_JUDGE_ATTEMPTS = 6;++function intSetting(key: string, fallback: number): number {+ const raw = getSetting(key);+ if (!raw) return fallback;+ const n = parseInt(raw, 10);+ return Number.isFinite(n) && n > 0 ? n : fallback;+}++function panelDefaultK(): number {+ return Math.min(intSetting('fusion_default_k', DEFAULT_PANEL_K), panelMaxK());+}+function panelMaxK(): number {+ return Math.min(intSetting('fusion_max_k', HARD_MAX_PANEL_K), HARD_MAX_PANEL_K);+}++export const fusionConfigSchema = z.object({+ // Explicit panel: the exact model ids the client wants to fuse. Any unknown+ // / disabled ids are dropped (and reported in x_fusion) rather than failing+ // the whole request — a panel is robust to missing members by design.+ models: z.array(z.string().min(1)).optional(),+ // Auto-panel size when `models` is omitted. Clamped to [1, fusion_max_k].+ k: z.number().int().positive().optional(),+ // Judge/synthesizer model id. Omit → the top-ranked available model.+ judge: z.string().min(1).optional(),+ // 'synthesize' (default): one blended answer. 'best_of': skip the judge,+ // return the longest single panel answer (cheaper; no +1 judge call).+ strategy: z.enum(['synthesize', 'best_of']).optional(),+ // Attach the per-model panel answers + judge metadata under `x_fusion`.+ expose_panel: z.boolean().optional(),+});++export type FusionConfig = z.infer<typeof fusionConfigSchema>;++export function getFusionMaxK(): number {+ return panelMaxK();+}++// ── Saved fusion config (dashboard-managed default) ─────────────────────────+// Persisted in the settings table under `fusion_config`. A request's inline+// `fusion` field always overrides the saved default field-by-field, so the UI+// sets the baseline and any client can still tweak per call. `mode` is the+// "Both, user-toggleable" toggle: 'auto' picks a diverse panel off the+// Fallback Chain (ignoring `models`); 'explicit' uses the saved `models` list.+const SAVED_FUSION_KEY = 'fusion_config';++export const savedFusionConfigSchema = z.object({+ mode: z.enum(['auto', 'explicit']),+ models: z.array(z.string().min(1)).default([]),+ judge: z.string().min(1).nullable().default(null),+ k: z.number().int().positive(),+ strategy: z.enum(['synthesize', 'best_of']),+ expose_panel: z.boolean(),+});++export type SavedFusionConfig = z.infer<typeof savedFusionConfigSchema>;++function defaultSavedConfig(): SavedFusionConfig {+ return { mode: 'auto', models: [], judge: null, k: panelDefaultK(), strategy: 'synthesize', expose_panel: false };+}++export function getSavedFusionConfig(): SavedFusionConfig {+ const raw = getSetting(SAVED_FUSION_KEY);+ if (raw) {+ try {+ const parsed = savedFusionConfigSchema.safeParse(JSON.parse(raw));+ if (parsed.success) return parsed.data;+ } catch { /* corrupt setting → fall through to default */ }+ }+ return defaultSavedConfig();+}++export function setSavedFusionConfig(input: SavedFusionConfig): SavedFusionConfig {+ const maxK = panelMaxK();+ const normalized: SavedFusionConfig = {+ mode: input.mode,+ // De-dup the explicit panel and clamp to the operator cap.+ models: [...new Set(input.models)].slice(0, maxK),+ judge: input.judge && input.judge.trim() ? input.judge.trim() : null,+ k: Math.min(Math.max(input.k, 1), maxK),+ strategy: input.strategy,+ expose_panel: input.expose_panel,+ };+ setSetting(SAVED_FUSION_KEY, JSON.stringify(normalized));+ return normalized;+}++/**+ * Merge a request's inline fusion config over the saved dashboard default.+ * Each field present on the request wins; otherwise the saved default applies.+ * An explicit panel only comes from the saved config when its mode is+ * 'explicit' — in 'auto' mode the saved `models` are ignored so the panel is+ * picked fresh off the Fallback Chain.+ */+export function resolveEffectiveConfig(req: FusionConfig): FusionConfig {+ const saved = getSavedFusionConfig();+ const models = (req.models && req.models.length > 0)+ ? req.models+ : (saved.mode === 'explicit' && saved.models.length > 0 ? saved.models : undefined);+ return {+ models,+ k: req.k ?? saved.k,+ judge: req.judge ?? saved.judge ?? undefined,+ strategy: req.strategy ?? saved.strategy,+ expose_panel: req.expose_panel ?? saved.expose_panel,+ };+}++// One panel member's outcome.+interface PanelAnswer {+ modelDbId: number;+ platform: string;+ modelId: string;+ displayName: string;+ status: 'ok' | 'failed';+ content?: string;+ error?: string;+ usage?: TokenUsage;+}++interface CallOutcome {+ ok: boolean;+ route?: RouteResult;+ text?: string;+ usage?: TokenUsage;+ error?: string;+}++const ZERO_USAGE: TokenUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };++function addUsage(a: TokenUsage, b: TokenUsage | undefined): TokenUsage {+ if (!b) return a;+ return {+ prompt_tokens: a.prompt_tokens + (b.prompt_tokens ?? 0),+ completion_tokens: a.completion_tokens + (b.completion_tokens ?? 0),+ total_tokens: a.total_tokens + (b.total_tokens ?? 0),+ };+}++/**+ * Run one model call with retry across keys/models, doing the same accounting+ * (request counts, token usage, success/penalty, cooldowns, request log) the+ * normal proxy path does — just tagged as fusion traffic. `getRoute` decides+ * WHICH model is tried: a pinned-model closure for a panel slot (never+ * substitutes), or the auto-router for the judge (falls over across the chain).+ */+async function runModelCall(+ getRoute: (skipKeys: Set<string>, skipModels: Set<number>) => RouteResult | null,+ messages: ChatMessage[],+ options: CompletionOptions,+ estimatedTokens: number,+ maxAttempts: number,+): Promise<CallOutcome> {+ const skipKeys = new Set<string>();+ const skipModels = new Set<number>();+ let lastError: string | undefined;++ for (let attempt = 0; attempt < maxAttempts; attempt++) {+ let route: RouteResult | null;+ try {+ route = getRoute(skipKeys, skipModels);+ } catch (err: any) {+ // routeRequest throws when the whole chain is exhausted (judge path).+ lastError = sanitizeProviderErrorMessage(err?.message);+ break;+ }+ if (!route) break;++ const startedAt = Date.now();+ try {+ const result = await route.provider.chatCompletion(route.apiKey, messages, route.modelId, options);+ const text = contentToString(result.choices?.[0]?.message?.content ?? '');++ if (!text) {+ // Empty completion — fail over like the main proxy path does.+ logRequest(route.platform, route.modelId, route.keyId, 'error', 0, 0, Date.now() - startedAt, 'empty completion (fusion)', null, FUSION_TAG);+ skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);+ setCooldown(route.platform, route.modelId, route.keyId, getCooldownDurationForLimit(route.platform, route.modelId, route.keyId, { rpd: route.rpdLimit, tpd: route.tpdLimit }));+ recordRateLimitHit(route.modelDbId);+ lastError = `empty completion from ${route.displayName}`;+ continue;+ }++ const usage = result.usage ?? ZERO_USAGE;+ recordRequest(route.platform, route.modelId, route.keyId);+ recordTokens(route.platform, route.modelId, route.keyId, usage.total_tokens);+ recordSuccess(route.modelDbId);+ logRequest(route.platform, route.modelId, route.keyId, 'success', usage.prompt_tokens ?? 0, usage.completion_tokens ?? 0, Date.now() - startedAt, null, null, FUSION_TAG);+ return { ok: true, route, text, usage };+ } catch (err: any) {+ const safe = sanitizeProviderErrorMessage(err?.message);+ logRequest(route.platform, route.modelId, route.keyId, 'error', 0, 0, Date.now() - startedAt, safe, null, FUSION_TAG);+ lastError = safe;++ if (isRetryableError(err)) {+ if (isModelNotFoundError(err) || isModelAccessForbiddenError(err)) skipModels.add(route.modelDbId);+ skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);+ setCooldown(+ route.platform, route.modelId, route.keyId,+ isPaymentRequiredError(err)+ ? PAYMENT_REQUIRED_COOLDOWN_MS+ : isModelAccessForbiddenError(err)+ ? MODEL_FORBIDDEN_COOLDOWN_MS+ : getCooldownDurationForLimit(route.platform, route.modelId, route.keyId, { rpd: route.rpdLimit, tpd: route.tpdLimit }, err.retryAfterMs),+ );+ recordRateLimitHit(route.modelDbId);+ continue;+ }+ // Non-retryable (auth, validation) — this slot/judge is done.+ break;+ }+ }++ return { ok: false, error: lastError ?? 'no available key for model' };+}++/**+ * Like runModelCall, but STREAMS the judge's answer so the client sees it+ * written live instead of waiting for the whole synthesis. Failover only works+ * before the first byte (`started`): once we've forwarded text to the client we+ * can't cleanly switch models, so a mid-stream error returns the partial answer.+ * Usage is estimated (streaming rarely echoes a usage block).+ */+async function runJudgeStreaming(+ getRoute: (skipKeys: Set<string>, skipModels: Set<number>) => RouteResult | null,+ messages: ChatMessage[],+ options: CompletionOptions,+ estimatedTokens: number,+ maxAttempts: number,+ cb: { onStart?: (r: { platform: string; model: string }) => void; onDelta?: (t: string) => void },+): Promise<CallOutcome> {+ const skipKeys = new Set<string>();+ const skipModels = new Set<number>();+ let lastError: string | undefined;++ for (let attempt = 0; attempt < maxAttempts; attempt++) {+ let route: RouteResult | null;+ try { route = getRoute(skipKeys, skipModels); } catch (err: any) { lastError = sanitizeProviderErrorMessage(err?.message); break; }+ if (!route) break;++ const startedAt = Date.now();+ let text = '';+ let started = false;+ try {+ for await (const chunk of route.provider.streamChatCompletion(route.apiKey, messages, route.modelId, options)) {+ const delta = (chunk as any)?.choices?.[0]?.delta?.content;+ if (typeof delta === 'string' && delta.length > 0) {+ if (!started) { started = true; cb.onStart?.({ platform: route.platform, model: route.modelId }); }+ text += delta;+ cb.onDelta?.(delta);+ }+ }+ if (!text) {+ logRequest(route.platform, route.modelId, route.keyId, 'error', 0, 0, Date.now() - startedAt, 'empty completion (fusion judge)', null, FUSION_TAG);+ skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);+ setCooldown(route.platform, route.modelId, route.keyId, getCooldownDurationForLimit(route.platform, route.modelId, route.keyId, { rpd: route.rpdLimit, tpd: route.tpdLimit }));+ recordRateLimitHit(route.modelDbId);+ lastError = `empty judge completion from ${route.displayName}`;+ continue;+ }+ const out = Math.ceil(text.length / 4);+ const usage: TokenUsage = { prompt_tokens: estimatedTokens, completion_tokens: out, total_tokens: estimatedTokens + out };+ recordRequest(route.platform, route.modelId, route.keyId);+ recordTokens(route.platform, route.modelId, route.keyId, usage.total_tokens);+ recordSuccess(route.modelDbId);+ logRequest(route.platform, route.modelId, route.keyId, 'success', estimatedTokens, out, Date.now() - startedAt, null, null, FUSION_TAG);+ return { ok: true, route, text, usage };+ } catch (err: any) {+ const safe = sanitizeProviderErrorMessage(err?.message);+ logRequest(route.platform, route.modelId, route.keyId, 'error', 0, 0, Date.now() - startedAt, safe, null, FUSION_TAG);+ lastError = safe;+ // Already streamed bytes — can't fail over without duplicating output.+ // Keep whatever the client already received.+ if (started) {+ if (text) {+ const out = Math.ceil(text.length / 4);+ return { ok: true, route, text, usage: { prompt_tokens: estimatedTokens, completion_tokens: out, total_tokens: estimatedTokens + out } };+ }+ break;+ }+ if (isRetryableError(err)) {+ if (isModelNotFoundError(err) || isModelAccessForbiddenError(err)) skipModels.add(route.modelDbId);+ skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);+ setCooldown(+ route.platform, route.modelId, route.keyId,+ isPaymentRequiredError(err) ? PAYMENT_REQUIRED_COOLDOWN_MS+ : isModelAccessForbiddenError(err) ? MODEL_FORBIDDEN_COOLDOWN_MS+ : getCooldownDurationForLimit(route.platform, route.modelId, route.keyId, { rpd: route.rpdLimit, tpd: route.tpdLimit }, err.retryAfterMs),+ );+ recordRateLimitHit(route.modelDbId);+ continue;+ }+ break;+ }+ }+ return { ok: false, error: lastError ?? 'no available key for judge' };+}++/**+ * Build the panel plus a refill queue:+ * - `panel` — the K models to run first (explicit list, or provider-diverse+ * picks off the strategy-sorted chain).+ * - `overflow` — the next servable models from the chain, used to refill a slot+ * when a panel model fails outright (auto mode only; an explicit+ * panel is run as-is with no substitution).+ * Diversity = one model per platform first, so both the panel and its refills+ * span genuinely different backends before doubling up on a platform.+ */+function selectPanel(config: FusionConfig): { panel: FusionCandidate[]; overflow: FusionCandidate[]; dropped: string[] } {+ const maxK = panelMaxK();++ if (config.models && config.models.length > 0) {+ const panel: FusionCandidate[] = [];+ const dropped: string[] = [];+ const seen = new Set<number>();+ for (const id of config.models) {+ if (panel.length >= maxK) { dropped.push(`${id} (over cap of ${maxK})`); continue; }+ const cand = resolveFusionCandidate(id);+ if (!cand) { dropped.push(`${id} (unknown or disabled)`); continue; }+ if (seen.has(cand.modelDbId)) continue; // de-dup repeats+ seen.add(cand.modelDbId);+ panel.push(cand);+ }+ // Explicit panel: the user named exact models, so don't substitute others.+ return { panel, overflow: [], dropped };+ }++ const k = Math.min(Math.max(config.k ?? panelDefaultK(), 1), maxK);+ const ordered = getOrderedFusionChain();++ // Diversity-first ordering of the whole servable chain: one model per distinct+ // platform (strategy order), then the remaining models. The first K are the+ // panel; the rest are refill candidates that stay as diverse as possible.+ const seenPlatform = new Set<string>();+ const diverse: FusionCandidate[] = [];+ const rest: FusionCandidate[] = [];+ for (const c of ordered) {+ if (seenPlatform.has(c.platform)) rest.push(c);+ else { seenPlatform.add(c.platform); diverse.push(c); }+ }+ const full = [...diverse, ...rest];++ const panel = full.slice(0, k);+ // Cap refills so a run of failures can't sweep the entire catalog: try at most+ // K extra models (≤ 2K dispatches total).+ const overflow = full.slice(k, k * 2);+ return { panel, overflow, dropped: [] };+}++// Synthesis judge instructions. Anonymized "Response N" so the judge weighs+// content, not model reputation; told to produce the final answer directly with+// no meta-commentary about merging.+const JUDGE_SYSTEM_PROMPT =+ 'You are the final author of a single answer. Several AI assistants each independently answered the user\'s most recent message; their answers are provided below, anonymized as "Response 1", "Response 2", etc. ' ++ 'IMPORTANT: the user will NEVER see any of those individual responses — they only ever see what you write — so your answer must be COMPLETE and fully STAND-ALONE on its own. ' ++ 'Take the best parts of every response, combine the correct and most useful ideas into one coherent whole, resolve any contradictions by reasoning about which is actually right (do not just average or list options), and fill in anything they all missed. ' ++ 'Then REWRITE it all from scratch, in your own words, as one clear, well-structured, self-contained answer that makes complete sense by itself. ' ++ 'Do not mention that other answers exist, do not refer to "Response 1/2/3", do not compare the responses, and do not describe your process — just deliver the final, authoritative answer directly to the user.';++function buildJudgeMessages(original: ChatMessage[], answers: PanelAnswer[]): ChatMessage[] {+ const ok = answers.filter(a => a.status === 'ok' && a.content);+ const panelBlock = ok+ .map((a, i) => `--- Response ${i + 1} ---\n${a.content}`)+ .join('\n\n');++ // Keep the full original conversation for context, then append the candidate+ // answers + synthesis instruction as a final user turn. The judge system+ // prompt leads so it frames everything that follows.+ return [+ { role: 'system', content: JUDGE_SYSTEM_PROMPT },+ ...original,+ {+ role: 'user',+ content:+ `Here are ${ok.length} independent answers to my most recent message:\n\n${panelBlock}\n\n` ++ 'Take the best parts of these, then rewrite one complete, self-contained answer to my most recent message in your own words. ' ++ 'I will only see your answer — not these — so do not reference them.',+ },+ ];+}++export interface FusionResult {+ response: ChatCompletionResponse & { x_fusion?: unknown };+ routedVia: string; // for the X-Routed-Via header+}++/**+ * Orchestrate a fusion request end to end: select the panel, fan out in+ * parallel, then synthesize survivors with a judge (or best-of). Throws a+ * FusionError when nothing usable comes back so the route can map it to an+ * HTTP status.+ */+export class FusionError extends Error {+ status: number;+ constructor(message: string, status: number) {+ super(message);+ this.status = status;+ }+}++// Progress hooks for a streaming fusion request. Fired as each panel slot+// settles and when the judge succeeds, so a client (the Playground) can show the+// panel answers arriving and the judge kicking in before the final answer.+export interface FusionHooks {+ onPanel?: (a: { platform: string; model: string; status: 'ok' | 'failed'; content?: string; error?: string }) => void;+ onJudge?: (j: { platform: string; model: string }) => void;+ // When set, the judge STREAMS: onJudge fires at the first token (so the trace+ // shows the judge model) and onJudgeDelta fires for each token, so the final+ // answer is written live instead of appearing all at once after the wait.+ onJudgeDelta?: (text: string) => void;+}++export async function runFusion(params: {+ messages: ChatMessage[];+ config: FusionConfig;+ options: CompletionOptions;+ estimatedTokens: number;+ hooks?: FusionHooks;+}): Promise<FusionResult> {+ const { messages, options, estimatedTokens, hooks } = params;+ // Apply the dashboard-saved default; the request's inline fusion field (if+ // any) has already-merged precedence field-by-field.+ const config = resolveEffectiveConfig(params.config);+ const strategy = config.strategy ?? 'synthesize';++ const { panel, overflow, dropped } = selectPanel(config);+ if (panel.length === 0) {+ throw new FusionError(+ 'fusion: no usable models for the panel. Provide `fusion.models` with enabled model ids, or enable models in the Fallback Chain.',+ 400,+ );+ }++ // Dispatch ONE panel slot: hard-pinned to its model, rotating only that+ // model's keys (so a key 429 doesn't collapse the slot onto a duplicate+ // backend — issue #326). Returns its answer and fires onPanel the moment it+ // settles so a streaming client sees answers arrive one by one.+ const runSlot = (cand: FusionCandidate): Promise<PanelAnswer> =>+ runModelCall(+ (skipKeys) => routePinnedModel(cand.modelDbId, estimatedTokens, skipKeys),+ messages, options, estimatedTokens, MAX_SLOT_ATTEMPTS,+ ).then((outcome): PanelAnswer => {+ const answer: PanelAnswer = outcome.ok+ ? { modelDbId: cand.modelDbId, platform: cand.platform, modelId: cand.modelId, displayName: cand.displayName, status: 'ok', content: outcome.text, usage: outcome.usage }+ : { modelDbId: cand.modelDbId, platform: cand.platform, modelId: cand.modelId, displayName: cand.displayName, status: 'failed', error: outcome.error };+ hooks?.onPanel?.({ platform: answer.platform, model: answer.modelId, status: answer.status, content: answer.content, error: answer.error });+ return answer;+ });++ // Run the panel in waves, REFILLING failed slots from the fallback chain:+ // we aim for `target` successful answers. Wave 1 is the K-model panel; if some+ // fail (a model 429s/413s/aborts), the next wave pulls that many more models+ // from `overflow` (the next servable models in your chain). A slot is never+ // substituted mid-model — we move to a DIFFERENT chain model — so diversity+ // holds while transient failures don't shrink the panel. Bounded by the+ // candidate pool (≤ 2K dispatches), so it can't sweep the whole catalog.+ const target = panel.length;+ const candidates = [...panel, ...overflow];+ const answers: PanelAnswer[] = [];+ let okCount = 0;+ let cursor = 0;+ while (okCount < target && cursor < candidates.length) {+ const wave = candidates.slice(cursor, cursor + (target - okCount));+ cursor += wave.length;+ const settled = await Promise.allSettled(wave.map(runSlot));+ settled.forEach((s, i) => {+ const a: PanelAnswer = s.status === 'fulfilled'+ ? s.value+ : { modelDbId: wave[i].modelDbId, platform: wave[i].platform, modelId: wave[i].modelId, displayName: wave[i].displayName, status: 'failed', error: sanitizeProviderErrorMessage((s as PromiseRejectedResult).reason?.message) };+ answers.push(a);+ if (a.status === 'ok' && a.content) okCount++;+ });+ }++ const survivors = answers.filter(a => a.status === 'ok' && a.content);+ let totalUsage: TokenUsage = { ...ZERO_USAGE };+ for (const a of survivors) totalUsage = addUsage(totalUsage, a.usage);++ if (survivors.length === 0) {+ throw new FusionError(+ 'fusion: every panel model failed or was rate-limited. Try again shortly or pick different `fusion.models`.',+ 429,+ );+ }++ // Decide the final answer.+ let finalText: string;+ let judgeModelLabel: string | null = null;+ let judgeRoute: { platform: string; model: string } | null = null;+ let synthesized = false;++ if (survivors.length < SYNTHESIS_QUORUM || strategy === 'best_of') {+ // One survivor, or best-of requested: return the strongest single answer+ // (longest as a cheap proxy for completeness) — no judge call.+ finalText = survivors.slice().sort((a, b) => (b.content!.length - a.content!.length))[0].content!;+ } else {+ const judgeMessages = buildJudgeMessages(messages, survivors);+ // The judge prompt carries every panel answer, so its input is much larger+ // than the original — size the routing estimate accordingly.+ const judgeEstimate = estimatedTokens + survivors.reduce((n, a) => n + Math.ceil((a.content?.length ?? 0) / 4), 0);++ const getJudgeRoute = config.judge+ ? (skipKeys: Set<string>) => {+ const cand = resolveFusionCandidate(config.judge!);+ return cand ? routePinnedModel(cand.modelDbId, judgeEstimate, skipKeys) : null;+ }+ : (skipKeys: Set<string>, skipModels: Set<number>) => routeRequest(judgeEstimate, skipKeys.size ? skipKeys : undefined, undefined, false, false, skipModels.size ? skipModels : undefined);++ // Stream the judge when the caller wants live tokens (Playground); otherwise+ // a single buffered call (plain API clients hitting fusion non-streaming).+ const judge = hooks?.onJudgeDelta+ ? await runJudgeStreaming(getJudgeRoute, judgeMessages, options, judgeEstimate, MAX_JUDGE_ATTEMPTS, {+ // Surface the judge model the moment it starts emitting, so the trace+ // shows it while the answer is still streaming.+ onStart: (r) => { judgeRoute = r; judgeModelLabel = `${r.platform}/${r.model}`; hooks.onJudge?.(r); },+ onDelta: hooks.onJudgeDelta,+ })+ : await runModelCall(getJudgeRoute, judgeMessages, options, judgeEstimate, MAX_JUDGE_ATTEMPTS);++ if (judge.ok && judge.text) {+ finalText = judge.text;+ synthesized = true;+ // For the streaming path judgeRoute was set in onStart; set it here for the+ // buffered path (and as a fallback).+ if (!judgeRoute && judge.route) judgeRoute = { platform: judge.route.platform, model: judge.route.modelId };+ judgeModelLabel = judgeRoute ? `${judgeRoute.platform}/${judgeRoute.model}` : null;+ if (!hooks?.onJudgeDelta && judgeRoute) hooks?.onJudge?.(judgeRoute);+ totalUsage = addUsage(totalUsage, judge.usage);+ } else {+ // Judge failed → best-of fallback rather than erroring the whole request.+ finalText = survivors.slice().sort((a, b) => (b.content!.length - a.content!.length))[0].content!;+ }+ }++ const routedModels = survivors.map(a => a.modelId);+ const routedVia = `fusion(${routedModels.join('+')}${synthesized && judgeModelLabel ? ` -> ${judgeModelLabel}` : ''})`;++ const response: ChatCompletionResponse & { x_fusion?: unknown; _fusion?: unknown } = {+ id: `fusion-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,+ object: 'chat.completion',+ created: Math.floor(Date.now() / 1000),+ model: FUSION_MODEL_ID,+ choices: [{ index: 0, message: { role: 'assistant', content: finalText }, finish_reason: 'stop' }],+ usage: totalUsage,+ };++ // Lightweight, always-on routing summary so a client (e.g. the Playground+ // footer) can show exactly which panel models replied and which judge+ // synthesized — without the heavier per-answer `x_fusion` payload.+ response._fusion = {+ panel: survivors.map(a => ({ platform: a.platform, model: a.modelId })),+ judge: synthesized ? judgeRoute : null,+ synthesized,+ };++ if (config.expose_panel) {+ response.x_fusion = {+ strategy,+ synthesized,+ judge: judgeModelLabel,+ panel_requested: panel.map(p => p.modelId),+ dropped,+ panel: answers.map(a => ({+ model: a.modelId,+ platform: a.platform,+ status: a.status,+ ...(a.status === 'ok' ? { content: a.content } : { error: a.error }),+ })),+ };+ }++ return { response, routedVia };+}diff --git a/server/src/services/router.ts b/server/src/services/router.tsindex aa080ee9..eadbc2cd 100644--- a/server/src/services/router.ts+++ b/server/src/services/router.ts@@ -32,7 +32,7 @@ interface KeyRow {}// Chain row joined with the model fields the bandit needs to score it.-interface ChainRow {+export interface ChainRow {model_db_id: number;priority: number;enabled: number;@@ -355,10 +355,17 @@ function scoreChainEntry(/*** Order the enabled fallback chain for routing.* - 'priority' strategy → legacy manual order + 429 penalty (unchanged).- * - bandit strategy → Thompson-sampled convex score, manual priority as- * the deterministic tiebreaker for (near-)equal scores.+ * - bandit strategy → convex score, manual priority as the deterministic+ * tiebreaker for (near-)equal scores.+ *+ * `sampled` controls the bandit branch: Thompson sampling (the default) for+ * live routing, where per-call randomness is the exploration the bandit needs;+ * the deterministic expected score (`sampled = false`) for callers that want a+ * STABLE ranking under the chosen strategy — the fusion panel, which should be a+ * faithful reflection of the user's picked strategy, not a re-sampled draw each+ * request. Priority mode is deterministic either way.*/-function orderChain(chain: ChainRow[], strategy: RoutingStrategy): ChainRow[] {+function orderChain(chain: ChainRow[], strategy: RoutingStrategy, sampled = true): ChainRow[] {const weights = weightsFor(strategy);if (!weights) {// Legacy priority mode: base priority + 429 penalty, ascending.@@ -373,7 +380,7 @@ function orderChain(chain: ChainRow[], strategy: RoutingStrategy): ChainRow[] {const intelMax = composites.length ? Math.max(...composites) : 0;return chain- .map(e => ({ e, s: scoreChainEntry(e, weights, intelMin, intelMax, true).score }))+ .map(e => ({ e, s: scoreChainEntry(e, weights, intelMin, intelMax, sampled).score }))// Higher score first; manual priority breaks ties so the chain still matters..sort((a, b) => b.s - a.s || a.e.priority - b.e.priority).map(x => x.e);@@ -524,6 +531,218 @@ export function resolveRoutingChain(modelString: string | undefined): ResolvedChreturn { chain, strategyKey: `auto:${suffix}` };}+/**+ * Pick a usable key for ONE model and build its RouteResult, or return null if+ * the model has no key that can serve the request right now (all cooled down,+ * over quota, undecryptable, or no provider). This is the per-model key+ * round-robin previously inlined in routeRequest, factored out so the fusion+ * panel can HARD-PIN a model: rotate across that model's keys without ever+ * falling through to a different model (issue #326 — soft preference collapses+ * panel diversity under rate limits). Request-level filters (vision/tools/+ * context window) stay in the caller; this only does key selection + accounting+ * pre-checks.+ */+function selectKeyForModel(entry: ChainRow, estimatedTokens: number, skipKeys?: Set<string>): RouteResult | null {+ const db = getDb();++ if (!hasProvider(entry.platform as Platform)) return null;+ const provider = getProvider(entry.platform as Platform)!;++ const keys = db.prepare(+ "SELECT * FROM api_keys WHERE platform = ? AND enabled = 1 AND status IN ('healthy', 'unknown')"+ ).all(entry.platform) as KeyRow[];+ if (keys.length === 0) return null;++ const limits = {+ rpm: entry.rpm_limit,+ rpd: entry.rpd_limit,+ tpm: entry.tpm_limit,+ tpd: entry.tpd_limit,+ };++ const rrKey = `${entry.platform}:${entry.model_id}`;+ let idx = roundRobinIndex.get(rrKey) ?? 0;++ for (let attempt = 0; attempt < keys.length; attempt++) {+ const key = keys[idx % keys.length];+ idx++;++ // A custom model belongs to exactly one endpoint (#212); legacy rows+ // (key_id NULL) keep the old any-key match.+ if (entry.platform === 'custom' && entry.key_id != null && key.id !== entry.key_id) continue;++ const skipId = `${entry.platform}:${entry.model_id}:${key.id}`;+ if (skipKeys?.has(skipId)) continue;++ if (isOnCooldown(entry.platform, entry.model_id, key.id)) continue;+ if (!canUseProvider(entry.platform, key.id)) continue;+ if (!canMakeRequest(entry.platform, entry.model_id, key.id, limits)) continue;+ if (!canUseTokens(entry.platform, entry.model_id, key.id, estimatedTokens, limits)) continue;++ let decryptedKey: string;+ try {+ decryptedKey = decrypt(key.encrypted_key, key.iv, key.auth_tag);+ } catch {+ db.prepare("UPDATE api_keys SET status = 'error', last_checked_at = datetime('now') WHERE id = ?")+ .run(key.id);+ continue;+ }++ const resolvedProvider = entry.platform === 'custom'+ ? resolveProvider('custom', key.base_url)+ : provider;+ if (!resolvedProvider) continue;++ roundRobinIndex.set(rrKey, idx);+ return {+ provider: resolvedProvider,+ modelId: entry.model_id,+ modelDbId: entry.model_db_id,+ apiKey: decryptedKey,+ keyId: key.id,+ platform: entry.platform,+ displayName: entry.display_name,+ rpdLimit: limits.rpd,+ tpdLimit: limits.tpd,+ };+ }++ // No usable key for this model. Advance the round-robin index anyway so we+ // don't get stuck re-trying the same exhausted key first next time.+ roundRobinIndex.set(rrKey, idx);+ return null;+}++/**+ * Fetch a single enabled model's chain row by its db id.+ */+function getModelChainRow(db: Database, modelDbId: number): ChainRow | undefined {+ return db.prepare(`+ SELECT m.id as model_db_id, 0 as priority, 1 as enabled,+ m.platform, m.model_id, m.display_name, m.intelligence_rank,+ m.size_label, m.monthly_token_budget,+ m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,+ m.supports_tools, m.context_window, m.key_id+ FROM models m+ WHERE m.id = ? AND m.enabled = 1+ `).get(modelDbId) as ChainRow | undefined;+}++/**+ * Route to ONE specific model, hard-pinned. Rotates across that model's keys+ * (cooldowns, quotas, decryption all honored) but NEVER substitutes a different+ * model — returns null if the pinned model can't serve right now. This is what+ * makes a fusion panel genuinely diverse: a rate-limited slot is dropped, not+ * silently collapsed onto whatever else is available. `skipKeys` lets a slot+ * exclude keys it already failed on this request.+ */+export function routePinnedModel(modelDbId: number, estimatedTokens = 1000, skipKeys?: Set<string>): RouteResult | null {+ const db = getDb();+ const entry = getModelChainRow(db, modelDbId);+ if (!entry) return null;+ if (entry.context_window != null && estimatedTokens > entry.context_window) return null;+ if (entry.tpm_limit != null && estimatedTokens > entry.tpm_limit) return null;+ return selectKeyForModel(entry, estimatedTokens, skipKeys);+}++// A panel candidate surfaced to the fusion layer: enough to pick a diverse set+// and resolve each to a pinned dispatch.+export interface FusionCandidate {+ modelDbId: number;+ platform: string;+ modelId: string;+ displayName: string;+ sizeLabel: string;+ supportsVision: number;+ supportsTools: number;+}++/**+ * The active fallback chain ordered by the current routing strategy, surfaced+ * for fusion panel selection. Same ordering the normal auto-router would walk,+ * so the panel's auto-pick draws from the highest-scored models first and the+ * fusion layer just needs to apply provider-diversity on top.+ */+export function getOrderedFusionChain(): FusionCandidate[] {+ const db = getDb();+ const strategy = getRoutingStrategy();+ if (strategy !== 'priority') refreshStatsCache(db);+ const chain = getActiveChain(db).filter(e => e.enabled);++ // Only consider models that can ACTUALLY be served RIGHT NOW — applying the+ // same gate selectKeyForModel uses when the router walks the chain: the model+ // must have a key that is enabled + healthy, NOT on cooldown (e.g. a+ // HuggingFace key benched for a day after a 402 "Payment Required"), within+ // the provider's daily request cap, and under its per-minute/day request+ // limits. Without this, a high-strategy-ranked model whose only key is+ // currently cooled down (huggingface/Kimi-K2.6) would claim a panel slot it+ // can't fill — surfacing as "no available key" and pushing out a usable model,+ // which also makes the panel look like it's ignoring the routing strategy.+ const usableKeys = db.prepare(+ "SELECT id, platform FROM api_keys WHERE enabled = 1 AND status IN ('healthy', 'unknown')"+ ).all() as { id: number; platform: string }[];+ const keysByPlatform = new Map<string, number[]>();+ for (const k of usableKeys) {+ const arr = keysByPlatform.get(k.platform);+ if (arr) arr.push(k.id); else keysByPlatform.set(k.platform, [k.id]);+ }+ const servable = chain.filter(e => {+ const keyIds = keysByPlatform.get(e.platform);+ if (!keyIds) return false;+ const limits = { rpm: e.rpm_limit, rpd: e.rpd_limit, tpm: e.tpm_limit, tpd: e.tpd_limit };+ return keyIds.some(kid =>+ (e.key_id == null || kid === e.key_id) &&+ !isOnCooldown(e.platform, e.model_id, kid) &&+ canUseProvider(e.platform, kid) &&+ canMakeRequest(e.platform, e.model_id, kid, limits),+ );+ });++ // Deterministic (expected-score) ordering so the panel faithfully follows the+ // user's picked routing strategy instead of re-sampling a fresh draw each call.+ const ordered = orderChain(servable, strategy, false);+ return ordered.map(e => ({+ modelDbId: e.model_db_id,+ platform: e.platform,+ modelId: e.model_id,+ displayName: e.display_name,+ sizeLabel: e.size_label,+ supportsVision: e.supports_vision,+ supportsTools: e.supports_tools,+ }));+}++/**+ * Resolve an explicit model id (as a client would type it) to a fusion+ * candidate, or null when it isn't a known enabled model. Prefers an enabled+ * row; dedupes a model id that exists on multiple platforms by intelligence+ * rank, matching how /v1/models picks a representative row.+ */+export function resolveFusionCandidate(modelId: string): FusionCandidate | null {+ const db = getDb();+ const row = db.prepare(`+ SELECT m.id as model_db_id, m.platform, m.model_id, m.display_name,+ m.size_label, m.supports_vision, m.supports_tools+ FROM models m+ WHERE m.model_id = ? AND m.enabled = 1+ ORDER BY m.intelligence_rank ASC, m.id ASC+ LIMIT 1+ `).get(modelId) as {+ model_db_id: number; platform: string; model_id: string; display_name: string;+ size_label: string; supports_vision: number; supports_tools: number;+ } | undefined;+ if (!row) return null;+ return {+ modelDbId: row.model_db_id,+ platform: row.platform,+ modelId: row.model_id,+ displayName: row.display_name,+ sizeLabel: row.size_label,+ supportsVision: row.supports_vision,+ supportsTools: row.supports_tools,+ };+}+export function routeRequest(estimatedTokens = 1000, skipKeys?: Set<string>, preferredModelDbId?: number, requireVision = false, requireTools = false, skipModels?: Set<number>, prefetchedChain?: ChainRow[]): RouteResult {const db = getDb();@@ -597,92 +816,12 @@ export function routeRequest(estimatedTokens = 1000, skipKeys?: Set<string>, pre// estimatedTokens already includes reserved output, mirroring the check above.if (entry.tpm_limit != null && estimatedTokens > entry.tpm_limit) continue;- // Check if we have a provider for this platform- if (!hasProvider(entry.platform as Platform)) continue;- const provider = getProvider(entry.platform as Platform)!;-- // Get enabled keys that have not already failed validation or decryption.- const keys = db.prepare(- "SELECT * FROM api_keys WHERE platform = ? AND enabled = 1 AND status IN ('healthy', 'unknown')"- ).all(entry.platform) as KeyRow[];-- if (keys.length === 0) continue;-- // Get limits once for this model- const limits = {- rpm: entry.rpm_limit,- rpd: entry.rpd_limit,- tpm: entry.tpm_limit,- tpd: entry.tpd_limit,- };-- // Try all keys for this model before giving up on it- const rrKey = `${entry.platform}:${entry.model_id}`;- let idx = roundRobinIndex.get(rrKey) ?? 0;-- for (let attempt = 0; attempt < keys.length; attempt++) {- const key = keys[idx % keys.length];- idx++;-- // A custom model belongs to exactly one endpoint: skip every custom key- // except the one it was registered with. Without this, multiple custom- // providers would round-robin each other's models onto the wrong- // endpoint. (#212) Legacy rows (key_id NULL) keep the old any-key match.- if (entry.platform === 'custom' && entry.key_id != null && key.id !== entry.key_id) continue;-- const skipId = `${entry.platform}:${entry.model_id}:${key.id}`;- if (skipKeys?.has(skipId)) continue;-- // Check cooldown (from previous 429s)- if (isOnCooldown(entry.platform, entry.model_id, key.id)) continue;-- // Provider-wide daily request cap (#162): providers like OpenRouter cap- // total requests/day across ALL their models for the account, not per- // model — skip every model on this provider once that key hits the cap.- if (!canUseProvider(entry.platform, key.id)) continue;-- if (!canMakeRequest(entry.platform, entry.model_id, key.id, limits)) continue;- if (!canUseTokens(entry.platform, entry.model_id, key.id, estimatedTokens, limits)) continue;-- let decryptedKey: string;- try {- decryptedKey = decrypt(key.encrypted_key, key.iv, key.auth_tag);- } catch {- db.prepare("UPDATE api_keys SET status = 'error', last_checked_at = datetime('now') WHERE id = ?")- .run(key.id);- continue;- }-- // For the 'custom' platform the real provider is built from this key's- // base_url (the registered instance is just a placeholder). A custom key- // with no base_url can't be routed — skip it.- const resolvedProvider = entry.platform === 'custom'- ? resolveProvider('custom', key.base_url)- : provider;- if (!resolvedProvider) continue;-- // We found a working key for this model!- roundRobinIndex.set(rrKey, idx);- return {- provider: resolvedProvider,- modelId: entry.model_id,- modelDbId: entry.model_db_id,- apiKey: decryptedKey,- keyId: key.id,- platform: entry.platform,- displayName: entry.display_name,- rpdLimit: limits.rpd,- tpdLimit: limits.tpd,- };- }-- // If we reach here, this specific model has NO available keys.- // Update round-robin index even if we failed so we don't get stuck.- roundRobinIndex.set(rrKey, idx);-- // We don't explicitly penalize the model here because the fact that we- // couldn't find a key means we will naturally move to the next model- // in the sortedChain for THIS specific request.+ // Key selection + accounting pre-checks for this one model. Returns the+ // first usable key's RouteResult, or null when the model has no key that+ // can serve right now — in which case we fall through to the next model in+ // the sorted chain for THIS request (no explicit penalty needed).+ const route = selectKeyForModel(entry, estimatedTokens, skipKeys);+ if (route) return route;}throw new RouteError('All models exhausted. Add more API keys or wait for rate limits to reset.', 429);