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: unify duplicate models across providers (#335) (#341)
Mohammed Abubaker3d3cdb640892
diff --git a/README.md b/README.mdindex a410dcc3..976cc320 100644--- a/README.md+++ b/README.md@@ -566,6 +566,7 @@ PRs should include a test, keep the existing test suite green, and match the `.e<a href="https://github.com/3215"><img src="https://images.weserv.nl/?url=github.com/3215.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@3215" /></a><a href="https://github.com/saifulaiub123"><img src="https://images.weserv.nl/?url=github.com/saifulaiub123.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@saifulaiub123" /></a><a href="https://github.com/PietFourie"><img src="https://images.weserv.nl/?url=github.com/PietFourie.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@PietFourie" /></a>+<a href="https://github.com/mhmdkrmabd"><img src="https://images.weserv.nl/?url=github.com/mhmdkrmabd.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@mhmdkrmabd" /></a>## Terms of Service reviewdiff --git a/client/src/i18n/locales/en.json b/client/src/i18n/locales/en.jsonindex 9e6f2849..a1020522 100644--- a/client/src/i18n/locales/en.json+++ b/client/src/i18n/locales/en.json@@ -85,6 +85,15 @@"rpdLimit": "{count} rpd","noKey": "no key","dragToReorder": "Drag to reorder",+ "dragToReorderGroup": "Drag to reorder model",+ "providerCount": "{count} providers",+ "aggregateBudget": "{count}/mo",+ "aggregateBudgetTitle": "Total free tokens per month across this model's providers",+ "rateRpm": "{count} RPM",+ "rateRpd": "{count} RPD",+ "rateTitle": "Rate-limited — no fixed monthly token budget",+ "unifyToggle": "Unify duplicate models",+ "unifyToggleHint": "Show a model served by several providers as one item, and fail over across its providers when it's selected.","columnModel": "Model","columnOn": "On","noModelsBefore": "No models available. Add API keys on the ",@@ -243,6 +252,9 @@"description": "Send a chat completion through the router and see which provider serves it.","autoModel": "Auto (fallback chain)","fusionModel": "Fusion (multi-model synthesis)",+ "selectModel": "Select model",+ "searchModels": "Search models…",+ "noModelsFound": "No models found","send": "Send","sending": "Sending…","clear": "Clear",diff --git a/client/src/lib/model-groups.ts b/client/src/lib/model-groups.tsnew file mode 100644index 00000000..05c4202d--- /dev/null+++ b/client/src/lib/model-groups.ts@@ -0,0 +1,40 @@+// Client-side helper for the "unify duplicate models" feature. The server sends+// each fallback entry tagged with its logical-model group (groupKey /+// canonicalId / groupLabel). When unification is ON, model pickers should show+// ONE option per group (value = canonicalId, which the proxy resolves to the+// whole group); when OFF, one option per provider row (value = model_id), as+// before. FallbackPage does its own richer grouping (it needs the members to+// render expandable rows) — this helper is just for the flat picker case.++export interface PickerEntry {+ modelDbId: number+ modelId: string+ displayName: string+ platform: string+ groupKey?: string+ canonicalId?: string+ groupLabel?: string+}++export interface ModelOption {+ value: string // what to send as `model`: canonicalId (ON) or model_id (OFF)+ label: string+ platform: string // meaningful when providerCount === 1+ providerCount: number+}++export function buildModelOptions(entries: PickerEntry[], unifyOn: boolean): ModelOption[] {+ if (!unifyOn) {+ return entries.map(e => ({ value: e.modelId, label: e.displayName, platform: e.platform, providerCount: 1 }))+ }+ // Group by groupKey (falling back to model_id for ungrouped rows), preserving+ // first-seen order so the list still respects the server's ordering.+ const groups = new Map<string, ModelOption>()+ for (const e of entries) {+ const key = e.groupKey ?? e.modelId+ const existing = groups.get(key)+ if (existing) existing.providerCount+++ else groups.set(key, { value: e.canonicalId ?? e.modelId, label: e.groupLabel ?? e.displayName, platform: e.platform, providerCount: 1 })+ }+ return [...groups.values()]+}diff --git a/client/src/pages/FallbackPage.tsx b/client/src/pages/FallbackPage.tsxindex e8bc313d..85b74f1a 100644--- a/client/src/pages/FallbackPage.tsx+++ b/client/src/pages/FallbackPage.tsx@@ -1,4 +1,4 @@-import { useEffect, useState, useRef, type ReactNode } from 'react'+import { Fragment, useEffect, useState, useRef, type ReactNode } from 'react'import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'import {DndContext,@@ -44,9 +44,17 @@ interface FallbackEntry {rpmLimit: number | nullrpdLimit: number | nullmonthlyTokenBudget: string+ // Parsed token count from the server (single source of truth — see+ // server/src/lib/budget.ts). Optional only because the dev mock omits it.+ monthlyTokenBudgetTokens?: numbersupportsVision: booleansupportsTools: booleankeyCount: number+ // Logical-model grouping (sent by the server when unify is relevant). Absent+ // for ungrouped rows; the UI falls back to a per-row "solo" group then.+ groupKey?: string+ canonicalId?: string+ groupLabel?: string}type RoutingStrategy = 'priority' | 'balanced' | 'smartest' | 'fastest' | 'reliable' | 'custom'@@ -200,6 +208,22 @@ function formatTokens(n: number): string {return String(n)}+// For models with no monthly token budget, surface their rate quota instead.+// Strips the catalog's decorative bits ("free · ", " per IP", "~", "?") so e.g.+// "free · 40 RPM" → "40 RPM", "free · 200/hr per IP" → "200/hr", "~? (anon)" →+// "anon". Returns null when nothing meaningful remains.+function cleanQuotaLabel(s: string | undefined): string | null {+ if (!s) return null+ let c = s+ .replace(/free\s*·\s*/ig, '')+ .replace(/\s*per ip\s*/ig, '')+ .replace(/[~?]/g, '')+ .replace(/\s+/g, ' ')+ .trim()+ c = c.replace(/^\(([^()]*)\)$/, '$1').trim()+ return c || null+}+interface TokenUsageData {totalBudget: numbertotalUsed: number@@ -385,9 +409,13 @@ function RowContent({)}</div><div className="text-[11px] text-muted-foreground/70 tabular-nums mt-0.5">- {t('models.tokPerMonth', { count: row.monthlyTokenBudget })}- {row.rpmLimit ? ` · ${t('models.rpmLimit', { count: row.rpmLimit })}` : ''}- {row.rpdLimit ? ` · ${t('models.rpdLimit', { count: row.rpdLimit })}` : ''}+ {/* Token budget only when it's a real token count; rate-limited models+ (NVIDIA's "free · 40 RPM") show their rate, not "… tok/mo". */}+ {[+ (row.monthlyTokenBudgetTokens ?? 0) > 0 ? t('models.tokPerMonth', { count: row.monthlyTokenBudget }) : null,+ row.rpmLimit ? t('models.rpmLimit', { count: row.rpmLimit }) : null,+ row.rpdLimit ? t('models.rpdLimit', { count: row.rpdLimit }) : null,+ ].filter(Boolean).join(' · ') || cleanQuotaLabel(row.monthlyTokenBudget) || '—'}</div></td><td className="py-2 pr-3 align-middle"><AxisBar value={row.reliability} color="#22c55e" /></td>@@ -434,6 +462,150 @@ function SortableRow({ row, rank, onToggle }: { row: Row; rank: number; onToggle)}+// ── Grouped (unified) rendering ──────────────────────────────────────────────+// One logical model and the provider rows that serve it.+interface ModelGroupRow {+ key: string+ label: string+ members: Row[]+}++// Group merged rows by their server-assigned groupKey (or a per-row "solo" key+// when ungrouped). Members are ordered like the flat chain — by manual priority+// under the priority strategy, by live score otherwise — and groups inherit the+// best member's position so the unified order matches the flat order.+function buildGroups(rows: Row[], isManual: boolean): ModelGroupRow[] {+ const map = new Map<string, Row[]>()+ for (const r of rows) {+ const key = r.groupKey ?? `solo:${r.modelDbId}`+ const arr = map.get(key)+ if (arr) arr.push(r)+ else map.set(key, [r])+ }+ const groups = [...map.entries()].map(([key, members]) => ({+ key,+ label: members[0].groupLabel ?? members[0].displayName,+ members: [...members].sort((a, b) => (isManual ? a.priority - b.priority : (b.score ?? 0) - (a.score ?? 0))),+ }))+ groups.sort((a, b) =>+ isManual+ ? Math.min(...a.members.map(m => m.priority)) - Math.min(...b.members.map(m => m.priority))+ : Math.max(...b.members.map(m => m.score ?? 0)) - Math.max(...a.members.map(m => m.score ?? 0)),+ )+ return groups+}++const dragDots = (+ <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor">+ <circle cx="9" cy="6" r="1.5" /><circle cx="15" cy="6" r="1.5" />+ <circle cx="9" cy="12" r="1.5" /><circle cx="15" cy="12" r="1.5" />+ <circle cx="9" cy="18" r="1.5" /><circle cx="15" cy="18" r="1.5" />+ </svg>+)++// The collapsed header row for a logical-model group: name, provider count,+// union vision/tools badges, the best member's axis bars + score, and a single+// switch that enables/disables every provider in the group.+function GroupHeaderCells({ group, rank, expanded, onToggleExpand, dragHandle, onToggleGroup }: {+ group: ModelGroupRow+ rank: number+ expanded: boolean+ onToggleExpand: () => void+ dragHandle?: ReactNode+ onToggleGroup: (memberIds: number[], enabled: boolean) => void+}) {+ const { t } = useI18n()+ const anyEnabled = group.members.some(m => m.enabled)+ const solo = group.members.length === 1+ const best = group.members.reduce((b, m) => ((m.score ?? -1) > (b.score ?? -1) ? m : b), group.members[0])+ const guard = (best.headroom ?? 1) * (best.rateLimit ?? 1)+ const vision = group.members.some(m => m.supportsVision)+ const tools = group.members.some(m => m.supportsTools)+ // Quota badge beside the name: the aggregated monthly token budget when the+ // group has one (summed across providers — you can spend all of them via+ // failover), otherwise the model's rate cap (RPM/RPD, or the catalog's rate+ // label) for rate-limited providers like NVIDIA.+ const totalBudget = group.members.reduce((sum, m) => sum + (m.monthlyTokenBudgetTokens ?? 0), 0)+ const maxRpm = Math.max(0, ...group.members.map(m => m.rpmLimit ?? 0))+ const maxRpd = Math.max(0, ...group.members.map(m => m.rpdLimit ?? 0))+ const rateLabelText = group.members.map(m => cleanQuotaLabel(m.monthlyTokenBudget)).find(Boolean) ?? null+ // A summed monthly token budget if the group has one, else a rate cap (RPM/RPD,+ // or the catalog's rate label) for rate-limited providers like NVIDIA.+ function quotaBadge(): { text: string; title: string } | null {+ if (totalBudget > 0) return { text: t('models.aggregateBudget', { count: formatTokens(totalBudget) }), title: t('models.aggregateBudgetTitle') }+ if (maxRpm > 0) return { text: t('models.rateRpm', { count: maxRpm }), title: t('models.rateTitle') }+ if (maxRpd > 0) return { text: t('models.rateRpd', { count: maxRpd }), title: t('models.rateTitle') }+ if (rateLabelText) return { text: rateLabelText, title: t('models.rateTitle') }+ return null+ }+ const quota = quotaBadge()+ return (+ <>+ <td className="py-2 pl-3 pr-1 w-6 align-middle">{dragHandle ?? <span className="text-muted-foreground/30 select-none">·</span>}</td>+ <td className="py-2 pr-2 w-6 text-center font-mono text-xs text-muted-foreground tabular-nums align-middle">{rank}</td>+ <td className="py-2 pr-3 align-middle">+ <button type="button" onClick={onToggleExpand} className="flex items-center gap-2 flex-wrap text-left" aria-expanded={expanded}>+ <ChevronDown className={`size-4 flex-shrink-0 text-muted-foreground transition-transform ${expanded ? '' : '-rotate-90'}`} />+ <span className="font-medium text-sm">{group.label}</span>+ {solo+ ? <span className="text-xs text-muted-foreground">{group.members[0].platform}</span>+ : <span className="text-[10px] rounded-full px-1.5 py-0.5 bg-muted text-muted-foreground">{t('models.providerCount', { count: group.members.length })}</span>}+ {quota && (+ <span title={quota.title} className="text-[10px] rounded-full px-1.5 py-0.5 bg-muted text-muted-foreground tabular-nums">+ {quota.text}+ </span>+ )}+ {vision && (+ <span title={t('models.visionTitle')} className="text-[10px] rounded-full px-1.5 py-0.5 bg-cyan-600/15 text-cyan-700 dark:bg-cyan-400/15 dark:text-cyan-400">{t('models.vision')}</span>+ )}+ {tools && (+ <span title={t('models.toolsTitle')} className="text-[10px] rounded-full px-1.5 py-0.5 bg-violet-600/15 text-violet-700 dark:bg-violet-400/15 dark:text-violet-400">{t('models.tools')}</span>+ )}+ </button>+ </td>+ <td className="py-2 pr-3 align-middle"><AxisBar value={best.reliability} color="#22c55e" /></td>+ <td className="py-2 pr-3 align-middle"><AxisBar value={best.speed} color="#3b82f6" /></td>+ <td className="py-2 pr-3 align-middle"><AxisBar value={best.intelligence} color="#a855f7" /></td>+ <td className="py-2 pr-3 align-middle font-mono text-[11px] text-muted-foreground tabular-nums">{guard < 0.999 ? `×${guard.toFixed(2)}` : '—'}</td>+ <td className="py-2 pr-3 align-middle text-right font-mono text-xs font-medium tabular-nums">{best.score !== undefined ? best.score.toFixed(3) : '–'}</td>+ <td className="py-2 pr-3 align-middle text-right">+ <Switch checked={anyEnabled} onCheckedChange={(c) => onToggleGroup(group.members.map(m => m.modelDbId), c)} />+ </td>+ </>+ )+}++function SortableGroupRow({ group, rank, expanded, onToggleExpand, onToggleGroup }: {+ group: ModelGroupRow+ rank: number+ expanded: boolean+ onToggleExpand: () => void+ onToggleGroup: (memberIds: number[], enabled: boolean) => void+}) {+ const { t } = useI18n()+ const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: `grp:${group.key}` })+ const anyEnabled = group.members.some(m => m.enabled)+ const handle = (+ <button+ {...attributes}+ {...listeners}+ className="cursor-grab active:cursor-grabbing text-muted-foreground/50 hover:text-foreground transition-colors"+ aria-label={t('models.dragToReorderGroup')}+ >+ {dragDots}+ </button>+ )+ return (+ <tr+ ref={setNodeRef}+ style={{ transform: CSS.Transform.toString(transform), transition }}+ className={`border-b last:border-0 bg-card ${isDragging ? 'opacity-50' : ''} ${anyEnabled ? '' : 'opacity-50'}`}+ >+ <GroupHeaderCells group={group} rank={rank} expanded={expanded} onToggleExpand={onToggleExpand} dragHandle={handle} onToggleGroup={onToggleGroup} />+ </tr>+ )+}+export default function FallbackPage() {const { t } = useI18n()const queryClient = useQueryClient()@@ -516,6 +688,72 @@ export default function FallbackPage() {const hasChanges = localEntries !== null+ // ── Model unification (group the same model across providers) ──────────────+ const { data: unify } = useQuery<{ enabled: boolean }>({+ queryKey: ['unify'],+ queryFn: () => apiFetch('/api/settings/unify'),+ })+ const unifyOn = unify?.enabled ?? true+ const unifyMutation = useMutation({+ mutationFn: (enabled: boolean) => apiFetch('/api/settings/unify', { method: 'PUT', body: JSON.stringify({ enabled }) }),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['unify'] })+ queryClient.invalidateQueries({ queryKey: ['fallback'] })+ },+ })+ const [expandedGroups, setExpandedGroups] = useState<Set<string>>(() => new Set())+ const orderedGroups = buildGroups(rows, isManual)++ function toggleExpand(key: string) {+ setExpandedGroups(prev => {+ const next = new Set(prev)+ if (next.has(key)) next.delete(key)+ else next.add(key)+ return next+ })+ }++ function handleGroupToggle(memberIds: number[], enabled: boolean) {+ const ids = new Set(memberIds)+ setLocalEntries(allEntries.map(e => (ids.has(e.modelDbId) ? { ...e, enabled } : e)))+ }++ // Serialize the displayed group order (group-major, member-minor) to the flat+ // priority list PUT /api/fallback expects; keyless rows keep their tail spot.+ function persistGroupOrder(groups: ModelGroupRow[]) {+ const order: number[] = []+ for (const g of groups) for (const m of g.members) order.push(m.modelDbId)+ const unconfigured = allEntries.filter(e => e.keyCount === 0).map(e => e.modelDbId)+ const prio = new Map([...order, ...unconfigured].map((id, i) => [id, i + 1]))+ setLocalEntries(allEntries.map(e => ({ ...e, priority: prio.get(e.modelDbId) ?? e.priority })))+ }++ function handleGroupedDragEnd(event: DragEndEvent) {+ const { active, over } = event+ if (!over || active.id === over.id) return+ const a = String(active.id)+ const o = String(over.id)+ if (a.startsWith('grp:')) {+ if (!o.startsWith('grp:')) return // a group dropped on a member row — ignore+ const oldI = orderedGroups.findIndex(g => `grp:${g.key}` === a)+ const newI = orderedGroups.findIndex(g => `grp:${g.key}` === o)+ if (oldI < 0 || newI < 0) return+ persistGroupOrder(arrayMove(orderedGroups, oldI, newI))+ } else {+ // Member reorder, constrained to within its own group.+ const activeId = Number(a)+ const overId = Number(o)+ const gi = orderedGroups.findIndex(g => g.members.some(m => m.modelDbId === activeId))+ if (gi < 0) return+ const members = orderedGroups[gi].members+ const oldI = members.findIndex(m => m.modelDbId === activeId)+ const newI = members.findIndex(m => m.modelDbId === overId)+ if (newI < 0) return // dropped outside its group — ignore+ const next = orderedGroups.map((g, i) => (i === gi ? { ...g, members: arrayMove(g.members, oldI, newI) } : g))+ persistGroupOrder(next)+ }+ }+const tableHead = (<thead><tr className="text-left text-muted-foreground border-b">@@ -604,6 +842,16 @@ export default function FallbackPage() {</p></section>+ {/* Unify duplicate models — collapse the same model served by several+ providers into one expandable row (and one /v1/models entry). */}+ <section className="flex items-center justify-between rounded-3xl border bg-card p-5">+ <div className="min-w-0 pr-4">+ <h2 className="text-sm font-medium">{t('models.unifyToggle')}</h2>+ <p className="mt-0.5 text-xs text-muted-foreground">{t('models.unifyToggleHint')}</p>+ </div>+ <Switch checked={unifyOn} onCheckedChange={(c) => unifyMutation.mutate(c)} disabled={unifyMutation.isPending} />+ </section>+{/* Unified routing / fallback table */}{isLoading ? (<p className="text-sm text-muted-foreground">{t('common.loading')}</p>@@ -617,7 +865,65 @@ export default function FallbackPage() {<>{/* DndContext must wrap OUTSIDE the table: it renders hidden a11ylive-region <div>s, which are invalid as direct <table> children. */}- {isManual ? (+ {unifyOn ? (+ isManual ? (+ <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleGroupedDragEnd}>+ <div className="rounded-2xl border overflow-x-auto">+ <table className="w-full text-sm">+ {tableHead}+ <SortableContext items={orderedGroups.map(g => `grp:${g.key}`)} strategy={verticalListSortingStrategy}>+ <tbody>+ {orderedGroups.map((g, gi) => (+ <Fragment key={g.key}>+ <SortableGroupRow+ group={g}+ rank={gi + 1}+ expanded={expandedGroups.has(g.key)}+ onToggleExpand={() => toggleExpand(g.key)}+ onToggleGroup={handleGroupToggle}+ />+ {expandedGroups.has(g.key) && (+ <SortableContext items={g.members.map(m => m.modelDbId)} strategy={verticalListSortingStrategy}>+ {g.members.map((m, mi) => (+ <SortableRow key={m.modelDbId} row={m} rank={mi + 1} onToggle={handleToggle} />+ ))}+ </SortableContext>+ )}+ </Fragment>+ ))}+ </tbody>+ </SortableContext>+ </table>+ </div>+ </DndContext>+ ) : (+ <div className="rounded-2xl border overflow-x-auto">+ <table className="w-full text-sm">+ {tableHead}+ <tbody>+ {orderedGroups.map((g, gi) => (+ <Fragment key={g.key}>+ <tr className={`border-b last:border-0 ${g.members.some(m => m.enabled) ? '' : 'opacity-50'}`}>+ <GroupHeaderCells+ group={g}+ rank={gi + 1}+ expanded={expandedGroups.has(g.key)}+ onToggleExpand={() => toggleExpand(g.key)}+ onToggleGroup={handleGroupToggle}+ />+ </tr>+ {expandedGroups.has(g.key) && g.members.map((m, mi) => (+ <tr key={m.modelDbId} className={`border-b last:border-0 bg-muted/20 ${m.enabled ? '' : 'opacity-50'}`}>+ <RowContent row={m} rank={mi + 1} draggable={false} onToggle={handleToggle} />+ </tr>+ ))}+ </Fragment>+ ))}+ </tbody>+ </table>+ </div>+ )+ ) : isManual ? (<DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}><div className="rounded-2xl border overflow-x-auto"><table className="w-full text-sm">diff --git a/client/src/pages/FusionPage.tsx b/client/src/pages/FusionPage.tsxindex 55e4327c..04ccadfd 100644--- a/client/src/pages/FusionPage.tsx+++ b/client/src/pages/FusionPage.tsx@@ -2,6 +2,7 @@ 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 { buildModelOptions } from '@/lib/model-groups'import { Button } from '@/components/ui/button'import { Input } from '@/components/ui/input'import { Switch } from '@/components/ui/switch'@@ -53,11 +54,21 @@ export default function FusionPage() {queryFn: () => apiFetch('/api/fallback'),})+ const { data: unify } = useQuery<{ enabled: boolean }>({+ queryKey: ['unify'],+ queryFn: () => apiFetch('/api/settings/unify'),+ })+ const unifyOn = unify?.enabled ?? true+// Models that can actually serve a request right now (enabled + a key).const availableModels = useMemo(() => fallbackEntries.filter(e => e.keyCount > 0 && e.enabled),[fallbackEntries],)+ // When unify is on, the panel/judge pickers offer ONE option per logical+ // model (value = canonical id); the fusion service resolves it to the group's+ // best member. When off, one option per provider row, as before.+ const modelOptions = useMemo(() => buildModelOptions(availableModels, unifyOn), [availableModels, unifyOn])const [mode, setMode] = useState<Mode>('auto')const [models, setModels] = useState<string[]>([])@@ -151,19 +162,19 @@ export default function FusionPage() {<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 ? (+ {modelOptions.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)+ {modelOptions.map(o => {+ const selected = models.includes(o.value)const atCap = !selected && models.length >= maxKreturn (<button- key={m.modelDbId}+ key={o.value}type="button"disabled={atCap}- onClick={() => toggleModel(m.modelId)}+ onClick={() => toggleModel(o.value)}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'}`}@@ -172,10 +183,12 @@ export default function FusionPage() {{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 className="text-sm font-medium">{o.label}</span>+ <span className="ml-2 font-mono text-[11px] text-muted-foreground">{o.value}</span></span>- <Badge variant="secondary" className="text-[10px]">{m.platform}</Badge>+ <Badge variant="secondary" className="text-[10px]">+ {o.providerCount > 1 ? t('models.providerCount', { count: o.providerCount }) : o.platform}+ </Badge></button>)})}@@ -206,16 +219,18 @@ export default function FusionPage() {<SelectValue>{(v: string) => (!v || v === JUDGE_AUTO)? t('fusion.judgeAuto')- : (availableModels.find(m => m.modelId === v)?.displayName ?? v)}+ : (modelOptions.find(o => o.value === v)?.label ?? v)}</SelectValue></SelectTrigger><SelectContent><SelectItem value={JUDGE_AUTO}>{t('fusion.judgeAuto')}</SelectItem>- {availableModels.map(m => (- <SelectItem key={m.modelDbId} value={m.modelId}>+ {modelOptions.map(o => (+ <SelectItem key={o.value} value={o.value}><span className="flex items-center gap-2">- <span>{m.displayName}</span>- <span className="text-xs text-muted-foreground">{m.platform}</span>+ <span>{o.label}</span>+ <span className="text-xs text-muted-foreground">+ {o.providerCount > 1 ? t('models.providerCount', { count: o.providerCount }) : o.platform}+ </span></span></SelectItem>))}diff --git a/client/src/pages/PlaygroundPage.tsx b/client/src/pages/PlaygroundPage.tsxindex 7c88f546..4139e646 100644--- a/client/src/pages/PlaygroundPage.tsx+++ b/client/src/pages/PlaygroundPage.tsx@@ -1,9 +1,10 @@import { useState, useRef, useEffect } from 'react'import { useQuery } from '@tanstack/react-query'-import { ChevronRight } from 'lucide-react'+import { ChevronRight, ChevronsUpDown, Check, Search } from 'lucide-react'import { apiFetch } from '@/lib/api'import { Button } from '@/components/ui/button'-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'+import { Popover, PopoverTrigger, PopoverContent } from '@/components/ui/popover'+import { buildModelOptions } from '@/lib/model-groups'import { PageHeader } from '@/components/page-header'import { Markdown } from '@/components/markdown'import { CopyButton } from '@/components/copy-button'@@ -113,6 +114,8 @@ export default function PlaygroundPage() {const [selectedModel, setSelectedModel] = useState<string>(() => localStorage.getItem('playground.model') ?? 'auto',)+ const [modelQuery, setModelQuery] = useState('')+ const [modelPickerOpen, setModelPickerOpen] = useState(false)const messagesEndRef = useRef<HTMLDivElement>(null)const inputRef = useRef<HTMLTextAreaElement>(null)@@ -126,7 +129,16 @@ export default function PlaygroundPage() {queryFn: () => apiFetch('/api/fallback'),})+ const { data: unify } = useQuery<{ enabled: boolean }>({+ queryKey: ['unify'],+ queryFn: () => apiFetch('/api/settings/unify'),+ })+ const unifyOn = unify?.enabled ?? true+const availableModels = fallbackEntries.filter(e => e.keyCount > 0 && e.enabled)+ // When unify is on, collapse the same model from multiple providers into one+ // option (value = canonical id, which the proxy resolves to the whole group).+ const modelOptions = buildModelOptions(availableModels, unifyOn)useEffect(() => {messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })@@ -283,11 +295,38 @@ export default function PlaygroundPage() {inputRef.current?.focus()}+ // Searchable picker options: auto + fusion pinned at the top, then every+ // model sorted alphabetically A–Z by name.+ const pickerOptions = [+ { value: 'auto', label: t('playground.autoModel'), sub: '', isNew: false },+ { value: 'fusion', label: t('playground.fusionModel'), sub: '', isNew: true },+ ...modelOptions+ .map(o => ({+ value: o.value,+ label: o.label,+ sub: o.providerCount > 1 ? t('models.providerCount', { count: o.providerCount }) : o.platform,+ isNew: false,+ }))+ .sort((a, b) => a.label.localeCompare(b.label, undefined, { sensitivity: 'base' })),+ ]+ // Literal, case-insensitive substring match against name, provider, and id.+ const modelQ = modelQuery.trim().toLowerCase()+ const filteredOptions = modelQ+ ? pickerOptions.filter(o => `${o.label} ${o.sub} ${o.value}`.toLowerCase().includes(modelQ))+ : pickerOptions++ function pickModel(v: string) {+ setSelectedModel(v)+ localStorage.setItem('playground.model', v)+ setModelPickerOpen(false)+ setModelQuery('')+ }+const activeModelLabel = selectedModel === 'auto'? t('playground.autoModel'): selectedModel === 'fusion'? t('playground.fusionModel')- : availableModels.find(m => m.modelId === selectedModel)?.displayName ?? selectedModel+ : modelOptions.find(o => o.value === selectedModel)?.label ?? selectedModelreturn (<div className="flex flex-col h-[calc(100vh-8rem)]">@@ -296,35 +335,51 @@ export default function PlaygroundPage() {description={t('playground.description')}actions={<>- <Select value={selectedModel} onValueChange={(v) => { const m = v ?? 'auto'; setSelectedModel(m); localStorage.setItem('playground.model', m) }}>- <SelectTrigger className="w-[260px]">- <SelectValue />- </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">- <span>{m.displayName}</span>- <span className="text-xs text-muted-foreground">{m.platform}</span>- </span>- </SelectItem>- ))}- {availableModels.length === 0 && (- // Models only appear once a platform has an enabled key. Without- // one, the list is just "Auto" and looks broken — say why. (#269)- <div className="px-2 py-1.5 text-xs text-muted-foreground">- {t('playground.noModels')}- </div>- )}- </SelectContent>- </Select>+ <Popover open={modelPickerOpen} onOpenChange={(o) => { setModelPickerOpen(o); if (!o) setModelQuery('') }}>+ <PopoverTrigger+ aria-label={t('playground.selectModel')}+ className="flex h-8 w-[260px] items-center justify-between gap-2 whitespace-nowrap rounded-lg border border-input bg-transparent px-3 text-sm outline-none transition-colors hover:bg-muted/50 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 dark:bg-input/30"+ >+ <span className="truncate">{activeModelLabel}</span>+ <ChevronsUpDown className="size-4 shrink-0 text-muted-foreground" />+ </PopoverTrigger>+ <PopoverContent align="end" className="w-[300px] p-0">+ <div className="flex items-center gap-2 border-b px-3">+ <Search className="size-4 shrink-0 text-muted-foreground" />+ <input+ autoFocus+ value={modelQuery}+ onChange={e => setModelQuery(e.target.value)}+ placeholder={t('playground.searchModels')}+ className="h-9 w-full bg-transparent text-sm outline-none placeholder:text-muted-foreground"+ />+ </div>+ <div className="max-h-72 overflow-y-auto p-1">+ {filteredOptions.length === 0 ? (+ <div className="px-2 py-6 text-center text-xs text-muted-foreground">{t('playground.noModelsFound')}</div>+ ) : (+ filteredOptions.map(o => (+ <button+ key={o.value}+ type="button"+ onClick={() => pickModel(o.value)}+ className={`flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm transition-colors hover:bg-accent hover:text-accent-foreground ${o.value === selectedModel ? 'bg-accent/50' : ''}`}+ >+ <Check className={`size-4 shrink-0 ${o.value === selectedModel ? 'opacity-100' : 'opacity-0'}`} />+ <span className="min-w-0 flex-1 truncate">{o.label}</span>+ {o.isNew && <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>}+ {o.sub && <span className="shrink-0 text-xs text-muted-foreground">{o.sub}</span>}+ </button>+ ))+ )}+ {!modelQ && availableModels.length === 0 && (+ // Models only appear once a platform has an enabled key. Without+ // one, the list is just Auto/Fusion and looks broken — say why. (#269)+ <div className="px-2 py-1.5 text-xs text-muted-foreground">{t('playground.noModels')}</div>+ )}+ </div>+ </PopoverContent>+ </Popover>{messages.length > 0 && (<Button variant="outline" size="sm" onClick={handleClear}>{t('playground.clear')}diff --git a/server/src/__tests__/lib/budget.test.ts b/server/src/__tests__/lib/budget.test.tsnew file mode 100644index 00000000..7942f9b1--- /dev/null+++ b/server/src/__tests__/lib/budget.test.ts@@ -0,0 +1,29 @@+import { describe, it, expect } from 'vitest';+import { parseBudget } from '../../lib/budget.js';++describe('parseBudget', () => {+ it('parses token-count labels to their upper bound', () => {+ expect(parseBudget('~30M')).toBe(30_000_000);+ expect(parseBudget('~120M')).toBe(120_000_000);+ expect(parseBudget('~50-100M')).toBe(100_000_000); // upper bound of a range+ expect(parseBudget('~1-3M')).toBe(3_000_000);+ expect(parseBudget('~500K')).toBe(500_000);+ });++ it('ignores trailing rate hints but keeps the token estimate', () => {+ expect(parseBudget('~2M (60-100/hr)')).toBe(2_000_000);+ expect(parseBudget('~2-3M (200/hr)')).toBe(3_000_000);+ });++ it('returns 0 for rate limits / placeholders with no token magnitude (the NVIDIA case)', () => {+ expect(parseBudget('free · 40 RPM')).toBe(0);+ expect(parseBudget('free · 200/hr per IP')).toBe(0);+ expect(parseBudget('promo (trial)')).toBe(0);+ expect(parseBudget('~? (anon)')).toBe(0);+ });++ it('returns 0 for empty/missing input', () => {+ expect(parseBudget('')).toBe(0);+ expect(parseBudget(undefined as unknown as string)).toBe(0);+ });+});diff --git a/server/src/__tests__/routes/proxy-auto-model.test.ts b/server/src/__tests__/routes/proxy-auto-model.test.tsindex 6d69527d..cd43049c 100644--- a/server/src/__tests__/routes/proxy-auto-model.test.ts+++ b/server/src/__tests__/routes/proxy-auto-model.test.ts@@ -2,6 +2,7 @@ import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'viteimport type { Express } from 'express';import { createApp } from '../../app.js';import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';+import { setUnifyEnabled } from '../../services/model-groups.js';import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';let dashToken = '';@@ -42,6 +43,11 @@ describe('Virtual "auto" model', () => {beforeEach(async () => {const db = getDb();+ // This suite asserts the legacy per-provider /v1/models catalog semantics+ // (#242/#282 — one entry per model_id, owned_by = provider). Model+ // unification (default ON) collapses those into logical-model groups, which+ // is covered separately in proxy-model-groups.test.ts; pin it OFF here.+ setUnifyEnabled(false);db.prepare('DELETE FROM api_keys').run();db.prepare('DELETE FROM requests').run();diff --git a/server/src/__tests__/routes/proxy-model-groups.test.ts b/server/src/__tests__/routes/proxy-model-groups.test.tsnew file mode 100644index 00000000..bc4aba9f--- /dev/null+++ b/server/src/__tests__/routes/proxy-model-groups.test.ts@@ -0,0 +1,223 @@+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 { encrypt } from '../../lib/crypto.js';+import { setUnifyEnabled } from '../../services/model-groups.js';+import { setRoutingStrategy } from '../../services/router.js';+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.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 data = await res.text();+ server.close();+ let json: any = null;+ try { json = JSON.parse(data); } catch { /* SSE / non-JSON */ }+ return { status: res.status, body: json, headers: res.headers };+}++function authHeaders() {+ return { Authorization: `Bearer ${getUnifiedApiKey()}` };+}++// Insert a catalog row + fallback_config entry, returning its model_db_id.+function addModel(platform: string, modelId: string, displayName: string, priority: number): number {+ const db = getDb();+ const info = db.prepare(`+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, size_label,+ rpm_limit, rpd_limit, tpm_limit, tpd_limit, monthly_token_budget, context_window, enabled, supports_vision)+ VALUES (?, ?, ?, 5, 5, 'Large', 100, NULL, NULL, NULL, '~10M', 131072, 1, 0)+ `).run(platform, modelId, displayName);+ const id = Number(info.lastInsertRowid);+ db.prepare('INSERT INTO fallback_config (model_db_id, priority, enabled) VALUES (?, ?, 1)').run(id, priority);+ return id;+}++function addKey(platform: string): void {+ const db = getDb();+ const { encrypted, iv, authTag } = encrypt(`test-key-${platform}`);+ db.prepare(`+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)+ VALUES (?, ?, ?, ?, ?, 'healthy', 1)+ `).run(platform, `${platform}-key`, encrypted, iv, authTag);+}++// A mocked upstream chat completion response (OpenAI-compatible shape).+function completion(model: string, content: string) {+ return new Response(JSON.stringify({+ id: 'chatcmpl-test', object: 'chat.completion', created: 1, model,+ choices: [{ index: 0, message: { role: 'assistant', content }, finish_reason: 'stop' }],+ usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },+ }), { status: 200, headers: { 'Content-Type': 'application/json' } });+}++// "Test Unify Model" served by both Groq and Cerebras — distinct model_ids that+// normalize to the same group key. (Groq priority 1, so it's tried first under+// the 'priority' strategy, which lets us exercise cross-provider failover.)+describe('Model unification (group the same model across providers)', () => {+ let app: Express;++ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ app = createApp();+ dashToken = mintDashboardToken();+ });++ beforeEach(() => {+ const db = getDb();+ // fallback_config FK-references models(id), so clear it before the rows.+ db.prepare("DELETE FROM fallback_config WHERE model_db_id IN (SELECT id FROM models WHERE model_id IN ('tum-groq', 'tum-cerebras'))").run();+ db.prepare("DELETE FROM models WHERE model_id IN ('tum-groq', 'tum-cerebras')").run();+ db.prepare('DELETE FROM api_keys').run();+ db.prepare('DELETE FROM rate_limit_cooldowns').run();+ db.prepare('DELETE FROM rate_limit_usage').run();+ setUnifyEnabled(true);+ setRoutingStrategy('priority');+ addModel('groq', 'tum-groq', 'Test Unify Model', 1);+ addModel('cerebras', 'tum-cerebras', 'Test Unify Model', 2);+ addKey('groq');+ addKey('cerebras');+ });++ afterEach(() => {+ vi.restoreAllMocks();+ });++ it('GET /v1/models collapses the two providers into one canonical entry', async () => {+ const { status, body } = await request(app, 'GET', '/v1/models', undefined, authHeaders());+ expect(status).toBe(200);+ const ours = body.data.filter((m: any) => m.name === 'Test Unify Model');+ expect(ours).toHaveLength(1);+ expect(ours[0].id).toBe('test-unify-model'); // canonical slug+ expect(ours[0].owned_by).toBe('freellmapi');+ // The raw per-provider ids are NOT advertised when unify is on.+ expect(body.data.some((m: any) => m.id === 'tum-groq' || m.id === 'tum-cerebras')).toBe(false);+ });++ it('pinning the canonical id fails over across providers (Groq 429 → Cerebras)', async () => {+ const orig = global.fetch;+ vi.spyOn(global, 'fetch').mockImplementation(async (url: any, init?: any) => {+ const u = String(url);+ if (u.includes('api.groq.com')) return new Response(JSON.stringify({ error: { message: 'rate limited' } }), { status: 429 });+ if (u.includes('api.cerebras.ai')) return completion('tum-cerebras', 'answer from cerebras');+ return orig(url, init);+ });++ const { status, body, headers } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'test-unify-model',+ messages: [{ role: 'user', content: 'hi' }],+ }, authHeaders());++ expect(status).toBe(200);+ expect(body.choices[0].message.content).toContain('cerebras');+ expect(headers.get('x-routed-via')).toContain('cerebras');+ });++ it('a group-pinned non-streaming session sticks to the last successful provider next turn (#341 sticky-key)', async () => {+ const db = getDb();+ const realFetch = global.fetch;+ const sess = { ...authHeaders(), 'x-session-id': 'sticky-test-1' };+ const groqId = db.prepare("SELECT id FROM models WHERE model_id = 'tum-groq'").get() as { id: number };+ const cerebrasId = db.prepare("SELECT id FROM models WHERE model_id = 'tum-cerebras'").get() as { id: number };+ const setPriority = (modelDbId: number, p: number) =>+ db.prepare('UPDATE fallback_config SET priority = ? WHERE model_db_id = ?').run(p, modelDbId);+ // Both providers stay healthy throughout, so the only thing that can move the+ // route between turns is stickiness — never a cooldown.+ vi.spyOn(global, 'fetch').mockImplementation(async (url: any, init?: any) => {+ const u = String(url);+ if (u.includes('api.groq.com')) return completion('tum-groq', 'from groq');+ if (u.includes('api.cerebras.ai')) return completion('tum-cerebras', 'from cerebras');+ return realFetch(url, init);+ });++ // Turn 1: make Cerebras priority 1 so it wins outright (no failover), recording+ // it as the sticky provider for this pinned-model session.+ setPriority(cerebrasId.id, 1);+ setPriority(groqId.id, 2);+ const turn1 = await request(app, 'POST', '/v1/chat/completions', {+ model: 'test-unify-model', messages: [{ role: 'user', content: 'first' }],+ }, sess);+ expect(turn1.status).toBe(200);+ expect(turn1.headers.get('x-routed-via')).toContain('cerebras');++ // Flip priority so plain routing would now prefer Groq — sticky must override.+ setPriority(groqId.id, 1);+ setPriority(cerebrasId.id, 2);++ // Turn 2: same session, now a multi-turn conversation (getStickyModel only+ // engages once the session has an assistant turn). Pure priority would pick+ // Groq, but the sticky entry from turn 1 keeps it on Cerebras. This passes+ // only when turn 1 wrote the sticky model under the pinned-id key+ // (stickyStrategyKey); the non-streaming bug wrote it under the (undefined)+ // global strategyKey, so this read missed and Groq won.+ const turn2 = await request(app, 'POST', '/v1/chat/completions', {+ model: 'test-unify-model',+ messages: [+ { role: 'user', content: 'first' },+ { role: 'assistant', content: 'from cerebras' },+ { role: 'user', content: 'second' },+ ],+ }, sess);+ expect(turn2.status).toBe(200);+ expect(turn2.headers.get('x-routed-via')).toContain('cerebras');+ });++ it('an old per-provider model_id still routes and now fails over within the group', async () => {+ const orig = global.fetch;+ vi.spyOn(global, 'fetch').mockImplementation(async (url: any, init?: any) => {+ const u = String(url);+ if (u.includes('api.groq.com')) return new Response('{}', { status: 429 });+ if (u.includes('api.cerebras.ai')) return completion('tum-cerebras', 'answer from cerebras');+ return orig(url, init);+ });++ // Client sends Groq's raw id — it resolves to the whole group.+ const { status, headers } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'tum-groq',+ messages: [{ role: 'user', content: 'hi' }],+ }, authHeaders());++ expect(status).toBe(200);+ expect(headers.get('x-routed-via')).toContain('cerebras');+ });++ it('returns 429 (never a different model) when all of the group\'s providers are down', async () => {+ const orig = global.fetch;+ vi.spyOn(global, 'fetch').mockImplementation(async (url: any, init?: any) => {+ const u = String(url);+ if (u.includes('api.groq.com') || u.includes('api.cerebras.ai')) {+ return new Response(JSON.stringify({ error: { message: 'rate limited' } }), { status: 429 });+ }+ return orig(url, init);+ });++ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ model: 'test-unify-model',+ messages: [{ role: 'user', content: 'hi' }],+ }, authHeaders());++ expect(status).toBe(429);+ expect(body.choices).toBeUndefined(); // no answer from any model+ });++ it('with unify OFF, /v1/models lists each provider separately again', async () => {+ setUnifyEnabled(false);+ const { status, body } = await request(app, 'GET', '/v1/models', undefined, authHeaders());+ expect(status).toBe(200);+ const groq = body.data.find((m: any) => m.id === 'tum-groq');+ const cerebras = body.data.find((m: any) => m.id === 'tum-cerebras');+ expect(groq?.owned_by).toBe('groq');+ expect(cerebras?.owned_by).toBe('cerebras');+ expect(body.data.some((m: any) => m.id === 'test-unify-model')).toBe(false);+ });+});diff --git a/server/src/__tests__/services/model-groups.test.ts b/server/src/__tests__/services/model-groups.test.tsnew file mode 100644index 00000000..1f73f8a2--- /dev/null+++ b/server/src/__tests__/services/model-groups.test.ts@@ -0,0 +1,154 @@+import { describe, it, expect } from 'vitest';+import {+ stripProviderSuffix,+ normalizeGroupKey,+ slugifyGroupLabel,+ groupRows,+ resolveRequestedIdToMembers,+ type GroupableRow,+ type UnifyOverrides,+} from '../../services/model-groups.js';++const NO_OVERRIDES: UnifyOverrides = { merges: [], splits: [] };++function row(model_db_id: number, platform: string, model_id: string, display_name: string, intelligence_rank = 50): GroupableRow {+ return { model_db_id, platform, model_id, display_name, intelligence_rank };+}++// A realistic slice of the catalog: the same logical models under many providers+// with the mixed naming the real migrations use.+function catalog(): GroupableRow[] {+ return [+ row(1, 'cerebras', 'gpt-oss-120b', 'GPT-OSS 120B', 3),+ row(2, 'groq', 'openai/gpt-oss-120b', 'GPT-OSS 120B (Groq)', 6),+ row(3, 'cloudflare', '@cf/openai/gpt-oss-120b', 'GPT-OSS 120B (CF)', 6),+ row(4, 'sambanova', 'gpt-oss-120b', 'GPT-OSS 120B (SambaNova)', 6),+ row(5, 'ollama', 'gpt-oss:120b', 'GPT-OSS 120B (Ollama)', 9),+ row(6, 'groq', 'llama-3.3-70b-versatile', 'Llama 3.3 70B', 9),+ row(7, 'openrouter', 'meta-llama/llama-3.3-70b-instruct:free', 'Llama 3.3 70B (free)', 17),+ row(8, 'huggingface', 'accounts/fireworks/models/llama-v3p3-70b-instruct', 'Llama 3.3 70B (HF)', 14),+ row(9, 'cloudflare', '@cf/meta/llama-3.3-70b-fp8-fast', 'Llama 3.3 70B fp8-fast (CF)', 12),+ ];+}++describe('stripProviderSuffix', () => {+ it('strips known provider/variant parentheticals', () => {+ for (const tag of ['Groq', 'CF', 'HF', 'NV', 'SambaNova', 'Ollama', 'Cerebras', 'GitHub', 'free']) {+ expect(stripProviderSuffix(`Llama 3.3 70B (${tag})`)).toBe('Llama 3.3 70B');+ }+ });+ it('strips a generic trailing parenthetical too', () => {+ expect(stripProviderSuffix('Some Model (whatever)')).toBe('Some Model');+ });+ it('leaves names without a trailing parenthetical alone', () => {+ expect(stripProviderSuffix('GPT-OSS 120B')).toBe('GPT-OSS 120B');+ });+});++describe('normalizeGroupKey', () => {+ it('lowercases, strips suffix, and treats hyphens/underscores/space as one separator', () => {+ expect(normalizeGroupKey('GPT-OSS 120B (Groq)')).toBe('gpt oss 120b');+ expect(normalizeGroupKey(' Llama 3.3 70B (HF) ')).toBe('llama 3.3 70b');+ // Separator-only spelling differences normalize to the same key…+ expect(normalizeGroupKey('Qwen3 Coder 480B')).toBe(normalizeGroupKey('Qwen3-Coder 480B'));+ // …but a meaningful '+' is preserved, keeping distinct models apart.+ expect(normalizeGroupKey('Command R')).not.toBe(normalizeGroupKey('Command R+'));+ });+});++describe('groupRows', () => {+ it('collapses one model served by many providers into a single group', () => {+ const groups = groupRows(catalog(), NO_OVERRIDES);+ const gptoss = groups.find(g => g.groupKey === 'gpt oss 120b');+ expect(gptoss).toBeDefined();+ expect(gptoss!.members).toHaveLength(5);+ expect(gptoss!.groupLabel).toBe('GPT-OSS 120B'); // lowest intelligence_rank member+ });++ it('groups Llama 3.3 70B across differing model_ids but keeps fp8-fast separate', () => {+ const groups = groupRows(catalog(), NO_OVERRIDES);+ const llama = groups.find(g => g.groupKey === 'llama 3.3 70b');+ expect(llama!.members.map(m => m.model_db_id).sort()).toEqual([6, 7, 8]);+ // The fp8-fast variant normalizes to a DISTINCT key (merge only via override).+ expect(groups.find(g => g.groupKey === 'llama 3.3 70b fp8 fast')).toBeDefined();+ });++ it('merges a variant into a base group via an override', () => {+ const ov: UnifyOverrides = { merges: [{ into: 'Llama 3.3 70B', keys: ['llama 3.3 70b fp8 fast'] }], splits: [] };+ const groups = groupRows(catalog(), ov);+ const llama = groups.find(g => g.groupKey === 'llama 3.3 70b');+ expect(llama!.members.map(m => m.model_db_id).sort()).toEqual([6, 7, 8, 9]);+ expect(groups.find(g => g.groupKey === 'llama 3.3 70b fp8 fast')).toBeUndefined();+ });++ it('forces a member out of its group via a split override', () => {+ const ov: UnifyOverrides = { merges: [], splits: [{ member: 'groq:openai/gpt-oss-120b' }] };+ const groups = groupRows(catalog(), ov);+ const gptoss = groups.find(g => g.groupKey === 'gpt oss 120b');+ expect(gptoss!.members.map(m => m.model_db_id)).not.toContain(2);+ expect(groups.some(g => g.members.length === 1 && g.members[0].model_db_id === 2)).toBe(true);+ });++ it('merges names that differ only by separator punctuation (Qwen3 Coder vs Qwen3-Coder)', () => {+ const rows = [+ row(1, 'openrouter', 'qwen/qwen3-coder:free', 'Qwen3 Coder 480B'),+ row(2, 'ollama', 'qwen3-coder:480b', 'Qwen3-Coder 480B'),+ ];+ const groups = groupRows(rows, NO_OVERRIDES);+ expect(groups).toHaveLength(1);+ expect(groups[0].members.map(m => m.model_db_id).sort()).toEqual([1, 2]);+ });++ it('merges a free-tier name with its base model (DeepSeek V4 Flash Free → DeepSeek V4 Flash)', () => {+ const rows = [+ row(1, 'nvidia', 'deepseek-ai/deepseek-v4-flash', 'DeepSeek V4 Flash (NV)'),+ row(2, 'huggingface', 'deepseek-ai/DeepSeek-V4-Flash', 'DeepSeek V4 Flash (HF)'),+ row(3, 'opencode', 'deepseek-v4-flash-free', 'DeepSeek V4 Flash Free (OpenCode Zen)'),+ ];+ const groups = groupRows(rows, NO_OVERRIDES);+ expect(groups).toHaveLength(1);+ expect(groups[0].groupLabel).toBe('DeepSeek V4 Flash'); // "Free" dropped from the label+ expect(groups[0].members.map(m => m.model_db_id).sort()).toEqual([1, 2, 3]);+ });++ it('keeps models that differ by a meaningful char apart (Command R vs Command R+)', () => {+ const rows = [+ row(1, 'cohere', 'command-r-08-2024', 'Command R'),+ row(2, 'cohere', 'command-r-plus-08-2024', 'Command R+'),+ ];+ expect(groupRows(rows, NO_OVERRIDES)).toHaveLength(2);+ });++ it('assigns deterministic, unique canonical ids (collisions get -2)', () => {+ const rows = [row(1, 'a', 'm1', 'Model X'), row(2, 'b', 'm2', 'Model X!')];+ const groups = groupRows(rows, NO_OVERRIDES);+ const ids = groups.map(g => g.canonicalId).sort();+ expect(ids).toEqual(['model-x', 'model-x-2']);+ });+});++describe('slugifyGroupLabel', () => {+ it('keeps digits and dots, hyphenates spaces', () => {+ expect(slugifyGroupLabel('Llama 3.3 70B')).toBe('llama-3.3-70b');+ expect(slugifyGroupLabel('GPT-OSS 120B')).toBe('gpt-oss-120b');+ });+});++describe('resolveRequestedIdToMembers', () => {+ const groups = groupRows(catalog(), NO_OVERRIDES);+ const gptoss = groups.find(g => g.groupKey === 'gpt oss 120b')!;++ it('resolves a canonical id to all member db ids', () => {+ expect(resolveRequestedIdToMembers(gptoss.canonicalId, groups)!.sort()).toEqual([1, 2, 3, 4, 5]);+ });+ it('resolves any member model_id (back-compat) to the whole group', () => {+ expect(resolveRequestedIdToMembers('gpt-oss-120b', groups)!.sort()).toEqual([1, 2, 3, 4, 5]);+ expect(resolveRequestedIdToMembers('@cf/openai/gpt-oss-120b', groups)!.sort()).toEqual([1, 2, 3, 4, 5]);+ });+ it('resolves an explicit "platform:model_id" member', () => {+ expect(resolveRequestedIdToMembers('groq:openai/gpt-oss-120b', groups)!.sort()).toEqual([1, 2, 3, 4, 5]);+ });+ it('returns null for an unknown id', () => {+ expect(resolveRequestedIdToMembers('does-not-exist', groups)).toBeNull();+ });+});diff --git a/server/src/lib/budget.ts b/server/src/lib/budget.tsindex fb7a86a7..f22e645e 100644--- a/server/src/lib/budget.ts+++ b/server/src/lib/budget.ts@@ -4,10 +4,16 @@// labels, which callers treat as "no budget info".export function parseBudget(s: string): number {if (!s) return 0;- const m = s.match(/~?([\d.]+)(?:-([\d.]+))?([MK])?/);+ // Require a magnitude unit (M/K). A bare number with no unit is a rate limit+ // or placeholder, not a monthly token budget — "free · 40 RPM",+ // "free · 200/hr per IP", "promo (trial)", "~? (anon)" — so treat those as+ // "no budget info" (0), per this function's contract. Without the required+ // unit the old regex parsed "free · 40 RPM" as 40 tokens, which showed a bogus+ // budget and made the headroom guardrail penalize the model after one request.+ const m = s.match(/~?([\d.]+)(?:-([\d.]+))?([MK])/);if (!m) return 0;const high = parseFloat(m[2] ?? m[1]);if (Number.isNaN(high)) return 0;- const unit = m[3] === 'M' ? 1_000_000 : m[3] === 'K' ? 1_000 : 1;+ const unit = m[3] === 'M' ? 1_000_000 : 1_000;return high * unit;}diff --git a/server/src/routes/fallback.ts b/server/src/routes/fallback.tsindex eaede8aa..29805fb0 100644--- a/server/src/routes/fallback.ts+++ b/server/src/routes/fallback.ts@@ -10,6 +10,7 @@ import { getDb } from '../db/index.js';import { getAllPenalties, getRoutingScores, getRoutingStrategy, setRoutingStrategy, setCustomWeights } from '../services/router.js';import { BANDIT_PRESETS, type RoutingStrategy } from '../services/scoring.js';import { parseBudget } from '../lib/budget.js';+import { getModelGroups } from '../services/model-groups.js';export const fallbackRouter = Router();@@ -81,10 +82,24 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {const penalties = getAllPenalties();const penaltyMap = new Map(penalties.map(p => [p.modelDbId, p]));+ // Logical-model grouping per row, so the dashboard can collapse the same+ // model served by several providers into one expandable group. Always sent+ // (cheap); the client renders grouped only when its unify toggle is on.+ const groupByDbId = new Map<number, { groupKey: string; canonicalId: string; groupLabel: string }>();+ for (const g of getModelGroups()) {+ for (const m of g.members) {+ groupByDbId.set(m.model_db_id, { groupKey: g.groupKey, canonicalId: g.canonicalId, groupLabel: g.groupLabel });+ }+ }+res.json(rows.map(r => {const penalty = penaltyMap.get(r.model_db_id);+ const group = groupByDbId.get(r.model_db_id);return {modelDbId: r.model_db_id,+ groupKey: group?.groupKey,+ canonicalId: group?.canonicalId,+ groupLabel: group?.groupLabel,priority: r.priority,effectivePriority: r.priority + (penalty?.penalty ?? 0),penalty: penalty?.penalty ?? 0,@@ -101,6 +116,9 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {tpmLimit: r.tpm_limit,tpdLimit: r.tpd_limit,monthlyTokenBudget: r.monthly_token_budget,+ // Parsed once here (single source of truth) so the dashboard never re-implements+ // budget-label parsing; 0 for rate-limited/placeholder labels. See lib/budget.ts.+ monthlyTokenBudgetTokens: parseBudget(r.monthly_token_budget),supportsVision: r.supports_vision === 1,supportsTools: r.supports_tools === 1,keyCount: keyCountMap.get(r.platform) ?? 0,diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.tsindex 2b7613ab..5b59c086 100644--- a/server/src/routes/proxy.ts+++ b/server/src/routes/proxy.ts@@ -3,7 +3,7 @@ import { Router } from 'express';import type { Request, Response } from 'express';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 { routeRequest, resolveRoutingChain, resolveModelGroupCandidates, recordRateLimitHit, recordSuccess, hasEnabledVisionModel, hasEnabledToolsModel, type RouteResult, type ResolvedChain, type ChainRow } from '../services/router.js';import { recordRequest, recordTokens, setCooldown, getCooldownDurationForLimit, PAYMENT_REQUIRED_COOLDOWN_MS, MODEL_FORBIDDEN_COOLDOWN_MS } from '../services/ratelimit.js';import { runEmbeddings, EmbeddingsError } from '../services/embeddings.js';import { getDb, getUnifiedApiKey } from '../db/index.js';@@ -15,6 +15,7 @@ import { getContextHandoffMode, recordIncomingMessages, maybeInjectContextHandofimport { 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';+import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from '../services/model-groups.js';export const proxyRouter = Router();@@ -181,25 +182,67 @@ proxyRouter.get('/models', (req: Request, res: Response) => {AND (m.key_id IS NULL OR k.id = m.key_id)) THEN 1 ELSE 0 END)`;const db = getDb();- const models = db.prepare(`- SELECT platform, model_id, display_name, context_window, enabled, available, intelligence_rank, id- FROM (- SELECT m.platform, m.model_id, m.display_name, m.context_window, m.intelligence_rank, m.id,- m.enabled AS enabled,- ${availableExpr} AS available,- ROW_NUMBER() OVER (- PARTITION BY m.model_id- ORDER BY ${availableExpr} DESC, m.intelligence_rank ASC, m.id ASC- ) AS rn++ // A normalized listing row, whether we're grouping (unify ON) or not (OFF).+ let allListed: {+ id: string; name: string; ownedBy: string;+ available: number; enabled: number; contextWindow: number | null; intel: number;+ }[];++ if (isUnifyEnabled()) {+ // Unify ON: one entry per logical model group. Pull per-row availability ++ // context keyed by db id, then aggregate over each group's members.+ type AvailRow = { id: number; platform: string; intelligence_rank: number; context_window: number | null; enabled: number; available: number };+ const rows = db.prepare(`+ SELECT m.id, m.platform, m.intelligence_rank, m.context_window,+ m.enabled AS enabled, ${availableExpr} AS availableFROM models m- )- WHERE rn = 1- ORDER BY available DESC, enabled DESC, intelligence_rank ASC, id ASC- `).all() as ModelListRow[];+ `).all() as AvailRow[];+ const byId = new Map(rows.map(r => [r.id, r]));+ allListed = getModelGroups().map(g => {+ const infos = g.members.map(m => byId.get(m.model_db_id)).filter(Boolean) as AvailRow[];+ const ctxs = infos.map(i => i.context_window).filter((c): c is number => c != null);+ return {+ id: g.canonicalId,+ name: g.groupLabel,+ ownedBy: 'freellmapi',+ available: infos.some(i => i.available === 1) ? 1 : 0,+ enabled: infos.some(i => i.enabled === 1) ? 1 : 0,+ contextWindow: ctxs.length ? Math.max(...ctxs) : null,+ intel: infos.length ? Math.min(...infos.map(i => i.intelligence_rank)) : Number.MAX_SAFE_INTEGER,+ };+ });+ } else {+ // Unify OFF: today's behavior — one entry per model_id (dedup picks the+ // available, smartest representative row).+ const models = db.prepare(`+ SELECT platform, model_id, display_name, context_window, enabled, available, intelligence_rank, id+ FROM (+ SELECT m.platform, m.model_id, m.display_name, m.context_window, m.intelligence_rank, m.id,+ m.enabled AS enabled,+ ${availableExpr} AS available,+ ROW_NUMBER() OVER (+ PARTITION BY m.model_id+ ORDER BY ${availableExpr} DESC, m.intelligence_rank ASC, m.id ASC+ ) AS rn+ FROM models m+ )+ WHERE rn = 1+ `).all() as (ModelListRow & { intelligence_rank: number; id: number })[];+ allListed = models.map(m => ({+ id: m.model_id, name: m.display_name, ownedBy: m.platform,+ available: m.available, enabled: m.enabled, contextWindow: m.context_window,+ intel: m.intelligence_rank,+ }));+ }++ // Stable order: usable first, then enabled, then smartest, then name.+ allListed.sort((a, b) =>+ (b.available - a.available) || (b.enabled - a.enabled) || (a.intel - b.intel) || a.name.localeCompare(b.name));const q = String(req.query.available ?? req.query.connected ?? '').toLowerCase();const onlyAvailable = q === '1' || q === 'true' || q === 'yes';- const listed = onlyAvailable ? models.filter(m => m.available === 1) : models;+ const listed = onlyAvailable ? allListed.filter(m => m.available === 1) : allListed;// "auto" routes to whichever model fits, so its honest ceiling is the largest// context window among models that can serve a request right now. Advertising@@ -208,9 +251,9 @@ proxyRouter.get('/models', (req: Request, res: Response) => {// before they ever reach us (#282). Computed over currently-available models// (not the query-filtered `listed`) so the ceiling is honest even on the// default unfiltered list; null only when nothing is connected.- const availableContextWindows = models- .filter(m => m.available === 1 && m.context_window != null)- .map(m => m.context_window as number);+ const availableContextWindows = allListed+ .filter(m => m.available === 1 && m.contextWindow != null)+ .map(m => m.contextWindow as number);const autoContextWindow = availableContextWindows.length > 0? Math.max(...availableContextWindows): null;@@ -245,13 +288,13 @@ proxyRouter.get('/models', (req: Request, res: Response) => {unavailable_reason: autoContextWindow != null ? null : 'no_models',},...listed.map(m => ({- id: m.model_id,+ id: m.id,object: 'model',created: 0,- owned_by: m.platform,- name: m.display_name,- context_window: m.context_window,- context_length: m.context_window,+ owned_by: m.ownedBy,+ name: m.name,+ context_window: m.contextWindow,+ context_length: m.contextWindow,// Non-standard but additive: OpenAI clients ignore unknown fields.available: m.available === 1,unavailable_reason: m.available === 1 ? null : (m.enabled === 1 ? 'no_key' : 'disabled'),@@ -765,24 +808,64 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {// different model would be surprising to OpenAI-compatible clients.// Sticky-session is the fallback when no `model` field was sent at all.let preferredModel: number | undefined;+ // When the pinned model is a unified group, this holds the group's ordered+ // members and is passed to routeRequest as the STRICT chain (no other model+ // is ever reached). Undefined for auto and legacy single-row pins.+ let groupChain: ChainRow[] | undefined;+ // Sticky scope: auto requests bucket by routing strategy; a unified group pin+ // buckets by the canonical id the client sent, so the group prefers its last+ // successful provider without leaking stickiness across groups.+ let stickyStrategyKey: string | undefined = strategyKey;+if (isAutoModel(requestedModel)) {preferredModel = getStickyModel(messages, sessionIdHeader, strategyKey);} else if (requestedModel) {const db = getDb();- const enabled = db.prepare('SELECT id FROM models WHERE model_id = ? AND enabled = 1').get(requestedModel) as { id: number } | undefined;- if (enabled) {- preferredModel = enabled.id;+ // Unify ON: a requested id (canonical slug OR any provider's model_id) maps+ // to the whole logical-model group, and we route STRICTLY across only its+ // providers — failing over between them, never to a different model (#335).+ const members = isUnifyEnabled() ? resolveRequestedIdToMembers(requestedModel, getModelGroups()) : null;+ if (members && members.length > 0) {+ groupChain = resolveModelGroupCandidates(members);+ if (groupChain.length === 0) {+ // Distinguish a catalog-disabled model from one whose providers are+ // present but unusable (chain-disabled / no key), so the 400 stays+ // actionable and matches the legacy single-row "is disabled" wording.+ const placeholders = members.map(() => '?').join(',');+ const anyEnabled = db.prepare(`SELECT 1 FROM models WHERE id IN (${placeholders}) AND enabled = 1 LIMIT 1`).get(...members);+ const reason = anyEnabled ? 'has no providers with an enabled key' : 'is disabled';+ res.status(400).json({+ error: {+ message: `Model '${requestedModel}' ${reason}. Use 'auto' (or omit the 'model' field) to auto-route, or call /v1/models for the available list.`,+ type: 'invalid_request_error',+ code: 'model_not_found',+ },+ });+ return;+ }+ stickyStrategyKey = requestedModel;+ const sticky = getStickyModel(messages, sessionIdHeader, stickyStrategyKey);+ // Only prefer the sticky member if it's actually IN this group — passing a+ // non-member as preferredModelDbId would make routeRequest inject an+ // off-group model and break strict pinning.+ preferredModel = (sticky != null && groupChain.some(r => r.model_db_id === sticky)) ? sticky : undefined;} else {- const disabled = db.prepare('SELECT id FROM models WHERE model_id = ?').get(requestedModel) as { id: number } | undefined;- const reason = disabled ? 'is disabled' : 'is not in the catalog';- res.status(400).json({- error: {- message: `Model '${requestedModel}' ${reason}. Use 'auto' (or omit the 'model' field) to auto-route, or call /v1/models for the available list.`,- type: 'invalid_request_error',- code: 'model_not_found',- },- });- return;+ // Unify OFF, or an id that isn't in the catalog: legacy single-row pin.+ const enabled = db.prepare('SELECT id FROM models WHERE model_id = ? AND enabled = 1').get(requestedModel) as { id: number } | undefined;+ if (enabled) {+ preferredModel = enabled.id;+ } else {+ const disabled = db.prepare('SELECT id FROM models WHERE model_id = ?').get(requestedModel) as { id: number } | undefined;+ const reason = disabled ? 'is disabled' : 'is not in the catalog';+ res.status(400).json({+ error: {+ message: `Model '${requestedModel}' ${reason}. Use 'auto' (or omit the 'model' field) to auto-route, or call /v1/models for the available list.`,+ type: 'invalid_request_error',+ code: 'model_not_found',+ },+ });+ return;+ }}} else {preferredModel = getStickyModel(messages, sessionIdHeader, strategyKey);@@ -808,7 +891,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {// model is on record). Turns where injection can't happen — every turn 1, and// sessions that never switched — pay no headroom tax.const routingEstimate = handoffPossible ? estimatedTotal + HANDOFF_MAX_TOKENS : estimatedTotal;- route = routeRequest(routingEstimate, skipKeys.size > 0 ? skipKeys : undefined, preferredModel, hasImage, wantsTools, skipModels.size > 0 ? skipModels : undefined, resolvedChain?.chain);+ route = routeRequest(routingEstimate, skipKeys.size > 0 ? skipKeys : undefined, preferredModel, hasImage, wantsTools, skipModels.size > 0 ? skipModels : undefined, groupChain ?? resolvedChain?.chain);} catch (err: any) {// No more models availableif (lastError) {@@ -1059,7 +1142,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {recordRequest(route.platform, route.modelId, route.keyId);recordTokens(route.platform, route.modelId, route.keyId, estimatedInputTokens + injectedHandoffTokens + totalOutputTokens);recordSuccess(route.modelDbId);- setStickyModel(messages, route.modelDbId, sessionIdHeader, strategyKey);+ setStickyModel(messages, route.modelDbId, sessionIdHeader, stickyStrategyKey);if (handoffMode !== 'off' && sessionKey) recordSuccessfulModel({ sessionKey, modelKey });traceRouteEvent('Proxy', {event: 'ok',@@ -1156,7 +1239,12 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {recordRequest(route.platform, route.modelId, route.keyId);recordTokens(route.platform, route.modelId, route.keyId, totalTokens);recordSuccess(route.modelDbId);- setStickyModel(messages, route.modelDbId, sessionIdHeader, strategyKey);+ // Use stickyStrategyKey (not the global strategyKey) so a group-pinned+ // request writes its sticky entry under the SAME key the next turn reads+ // from (set to the requested model id at the top of the loop). Matches the+ // streaming success path; without it, "prefer last successful provider"+ // is lost for non-streaming group-pinned sessions. (#341 review)+ setStickyModel(messages, route.modelDbId, sessionIdHeader, stickyStrategyKey);if (handoffMode !== 'off' && sessionKey) recordSuccessfulModel({ sessionKey, modelKey });res.setHeader('X-Routed-Via', `${route.platform}/${route.modelId}`);diff --git a/server/src/routes/settings.ts b/server/src/routes/settings.tsindex 68ccdf05..a5d7dc6e 100644--- a/server/src/routes/settings.ts+++ b/server/src/routes/settings.ts@@ -3,9 +3,37 @@ 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';+import { isUnifyEnabled, setUnifyEnabled, getUnifyOverrides, setUnifyOverrides, unifyOverridesSchema } from '../services/model-groups.js';+import { z } from 'zod';export const settingsRouter = Router();+// Get the model-unification setting: the global toggle (default ON) plus any+// merge/split overrides. Governs the dashboard grouping, /v1/models grouping,+// and cross-provider pin failover.+settingsRouter.get('/unify', (_req: Request, res: Response) => {+ res.json({ enabled: isUnifyEnabled(), overrides: getUnifyOverrides() });+});++const unifyPutSchema = z.object({+ enabled: z.boolean().optional(),+ overrides: unifyOverridesSchema.optional(),+});++// Update the unify toggle and/or overrides. Partial: send just `enabled` to+// flip the switch, or `overrides` to adjust grouping, or both.+settingsRouter.put('/unify', (req: Request, res: Response) => {+ const parsed = unifyPutSchema.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 unify settings: ${detail}`, type: 'invalid_request_error' } });+ return;+ }+ if (parsed.data.enabled !== undefined) setUnifyEnabled(parsed.data.enabled);+ if (parsed.data.overrides) setUnifyOverrides(parsed.data.overrides);+ res.json({ enabled: isUnifyEnabled(), overrides: getUnifyOverrides() });+});+// 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() });diff --git a/server/src/services/model-groups.ts b/server/src/services/model-groups.tsnew file mode 100644index 00000000..8f5a037f--- /dev/null+++ b/server/src/services/model-groups.ts@@ -0,0 +1,224 @@+/**+ * Model grouping — "unify" the same logical model that several providers serve+ * into ONE item. The `models` table keeps one row per (platform, model_id); a+ * model offered by N providers is N rows. This module computes a logical group+ * for those rows at runtime (NO schema change) from the curated `display_name`,+ * plus operator overrides stored as JSON in the existing `settings` table.+ *+ * Pure by design: the core functions (normalizeGroupKey / groupRows /+ * resolveRequestedIdToMembers) take rows as arguments and touch no globals, so+ * they're trivially unit-testable. Only the settings getters/setters and the+ * getModelGroups() convenience touch the DB.+ *+ * Gated by the `unify_models_enabled` setting (default ON). When OFF, callers+ * keep their pre-unification behavior.+ */+import { z } from 'zod';+import { getDb, getSetting, setSetting } from '../db/index.js';++// ── Settings keys ────────────────────────────────────────────────────────────+export const UNIFY_ENABLED_KEY = 'unify_models_enabled';+export const UNIFY_OVERRIDES_KEY = 'model_unify_overrides';++export const unifyOverridesSchema = z.object({+ // Coalesce several grouping tokens into one group keyed by `into`. Each key is+ // a normalized display-name OR an exact "platform:model_id" member id.+ merges: z.array(z.object({+ into: z.string().min(1),+ keys: z.array(z.string().min(1)).min(1),+ })).default([]),+ // Force a specific "platform:model_id" row out of its computed group into a+ // singleton (or into an explicit groupKey).+ splits: z.array(z.object({+ member: z.string().min(1),+ groupKey: z.string().optional(),+ })).default([]),+}).default({ merges: [], splits: [] });++export type UnifyOverrides = z.infer<typeof unifyOverridesSchema>;++const EMPTY_OVERRIDES: UnifyOverrides = { merges: [], splits: [] };++// ── Types ────────────────────────────────────────────────────────────────────+// The minimal row shape grouping needs. Catalog queries select more columns;+// extra fields are ignored here and preserved on `members`.+export interface GroupableRow {+ model_db_id: number;+ platform: string;+ model_id: string;+ display_name: string;+ intelligence_rank?: number;+}++export interface ModelGroup {+ groupKey: string; // normalized display name — the grouping identity+ canonicalId: string; // stable slug advertised on /v1/models+ groupLabel: string; // human label = representative member's stripped name+ members: GroupableRow[]; // all rows in the group (any enabled state)+}++// ── Settings accessors ───────────────────────────────────────────────────────+export function isUnifyEnabled(): boolean {+ const raw = getSetting(UNIFY_ENABLED_KEY);+ if (raw == null) return true; // default ON+ return raw === '1' || raw.toLowerCase() === 'true';+}++export function setUnifyEnabled(on: boolean): void {+ setSetting(UNIFY_ENABLED_KEY, on ? '1' : '0');+}++export function getUnifyOverrides(): UnifyOverrides {+ const raw = getSetting(UNIFY_OVERRIDES_KEY);+ if (!raw) return EMPTY_OVERRIDES;+ try {+ const parsed = unifyOverridesSchema.safeParse(JSON.parse(raw));+ if (parsed.success) return parsed.data;+ } catch { /* corrupt JSON → safe default */ }+ return EMPTY_OVERRIDES;+}++export function setUnifyOverrides(input: unknown): UnifyOverrides {+ const norm = unifyOverridesSchema.parse(input);+ setSetting(UNIFY_OVERRIDES_KEY, JSON.stringify(norm));+ return norm;+}++// ── Normalization ────────────────────────────────────────────────────────────+// Catalog display names tag the provider/variant in a trailing parenthetical:+// "GPT-OSS 120B (Groq)", "Llama 3.3 70B (HF)", "... (free)". Strip ONE trailing+// "(...)" (no nested parens) to recover the logical name. Genuine variants like+// "Llama 3.3 70B fp8-fast (CF)" strip to "Llama 3.3 70B fp8-fast" — a DISTINCT+// name that only merges into "Llama 3.3 70B" via an override (by design).+export function stripProviderSuffix(displayName: string): string {+ let s = (displayName ?? '').trim();+ // Iteratively drop trailing markers: a "(...)" provider/variant parenthetical,+ // or a standalone "free" word. "Free" is a pricing tier, not a different model+ // — "DeepSeek V4 Flash Free" is the same model as "DeepSeek V4 Flash" — so it's+ // normalized away so the two group together. (A model literally named just+ // "Free" is left alone: the regex needs a word before it.)+ let prev: string;+ do {+ prev = s;+ s = s.replace(/\s*\([^()]*\)\s*$/, '').trim();+ s = s.replace(/\s+free$/i, '').trim();+ } while (s !== prev);+ return s;+}++// The grouping identity: suffix-stripped, lowercased, with hyphens/underscores/+// whitespace all treated as one separator — so catalog spelling differences like+// "Qwen3 Coder" vs "Qwen3-Coder" group together. Meaningful characters such as+// '+' are kept, so "Command R" and "Command R+" stay distinct.+export function normalizeGroupKey(displayName: string): string {+ return stripProviderSuffix(displayName).toLowerCase().replace(/[\s\-_]+/g, ' ').trim();+}++// A stable, human-friendly slug for the API. Keeps digits and dots ("3.3").+export function slugifyGroupLabel(label: string): string {+ const slug = (label ?? '').toLowerCase()+ .replace(/[^a-z0-9.\s-]/g, '')+ .trim()+ .replace(/\s+/g, '-')+ .replace(/-+/g, '-')+ .replace(/^-+|-+$/g, '');+ return slug || 'model';+}++// ── Grouping ─────────────────────────────────────────────────────────────────+function memberId(row: GroupableRow): string {+ return `${row.platform}:${row.model_id}`;+}++// The grouping token for a row, after applying overrides. Split wins first+// (forces a singleton/explicit key); then a merge redirects to its target;+// otherwise the normalized display name.+function tokenForRow(row: GroupableRow, ov: UnifyOverrides): string {+ const mid = memberId(row);++ const split = ov.splits.find(s => s.member === mid);+ if (split) return split.groupKey ? normalizeGroupKey(split.groupKey) : `__split__:${mid}`;++ const base = normalizeGroupKey(row.display_name);+ const merge = ov.merges.find(mg => mg.keys.some(k => k === mid || normalizeGroupKey(k) === base));+ return merge ? normalizeGroupKey(merge.into) : base;+}++// Assign a unique canonicalId to each group. Deterministic: groups sorted by+// groupKey, slug collisions disambiguated with "-2", "-3", …+function assignCanonicalIds(groups: ModelGroup[]): void {+ const used = new Set<string>();+ for (const g of [...groups].sort((a, b) => a.groupKey.localeCompare(b.groupKey))) {+ const base = slugifyGroupLabel(g.groupLabel);+ let cand = base;+ let n = 2;+ while (used.has(cand)) cand = `${base}-${n++}`;+ used.add(cand);+ g.canonicalId = cand;+ }+}++/**+ * Group catalog rows into logical models. Pure — pass overrides explicitly in+ * tests; defaults to the persisted overrides.+ */+export function groupRows(rows: GroupableRow[], ov: UnifyOverrides): ModelGroup[] {+ const map = new Map<string, ModelGroup>();+ for (const row of rows) {+ const key = tokenForRow(row, ov);+ let g = map.get(key);+ if (!g) {+ g = { groupKey: key, canonicalId: '', groupLabel: stripProviderSuffix(row.display_name), members: [] };+ map.set(key, g);+ }+ g.members.push(row);+ }++ // Representative label = the best (lowest intelligence_rank) member, tiebroken+ // by shortest stripped name then model_db_id, so the label is deterministic.+ for (const g of map.values()) {+ const rep = [...g.members].sort((a, b) =>+ (a.intelligence_rank ?? Number.MAX_SAFE_INTEGER) - (b.intelligence_rank ?? Number.MAX_SAFE_INTEGER)+ || stripProviderSuffix(a.display_name).length - stripProviderSuffix(b.display_name).length+ || a.model_db_id - b.model_db_id)[0];+ g.groupLabel = stripProviderSuffix(rep.display_name);+ }++ const groups = [...map.values()];+ assignCanonicalIds(groups);+ return groups;+}++/**+ * Resolve a requested model id to the db ids of its group members, or null.+ * Accepts the canonical slug OR any member's `model_id`/"platform:model_id"+ * (back-compat: an old per-provider id resolves to the whole group). Member+ * order here is incidental — the router re-orders by the active strategy.+ */+export function resolveRequestedIdToMembers(requested: string, groups: ModelGroup[]): number[] | null {+ if (!requested) return null;++ const byCanonical = groups.find(g => g.canonicalId === requested);+ if (byCanonical) return byCanonical.members.map(m => m.model_db_id);++ for (const g of groups) {+ if (g.members.some(m => m.model_id === requested || memberId(m) === requested)) {+ return g.members.map(m => m.model_db_id);+ }+ }+ return null;+}++// ── DB convenience ───────────────────────────────────────────────────────────+/**+ * Group the whole catalog (enabled + disabled rows so availability can be shown+ * and resolution is complete), applying the persisted overrides.+ */+export function getModelGroups(): ModelGroup[] {+ const db = getDb();+ const rows = db.prepare(`+ SELECT m.id as model_db_id, m.platform, m.model_id, m.display_name, m.intelligence_rank+ FROM models m+ `).all() as GroupableRow[];+ return groupRows(rows, getUnifyOverrides());+}diff --git a/server/src/services/router.ts b/server/src/services/router.tsindex eadbc2cd..6aeff47b 100644--- a/server/src/services/router.ts+++ b/server/src/services/router.ts@@ -8,6 +8,7 @@ import {speedScore, intelligenceScore, headroomFactor, rateLimitFactor, combineScore,} from './scoring.js';import { parseBudget } from '../lib/budget.js';+import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from './model-groups.js';import type { BaseProvider } from '../providers/base.js';import type { Platform } from '@freellmapi/shared/types.js';import type { Database } from 'better-sqlite3';@@ -645,6 +646,45 @@ export function routePinnedModel(modelDbId: number, estimatedTokens = 1000, skipreturn selectKeyForModel(entry, estimatedTokens, skipKeys);}+/**+ * Resolve a logical model group's member db ids to an ordered ChainRow[] for+ * strict group-pin routing (the "unify" feature). Each enabled member is+ * hydrated as a ChainRow carrying its REAL fallback_config.priority, then+ * ordered by the active strategy via orderChain — so 'priority' honors the+ * manual within-group order and scored strategies use live scores (priority as+ * the tiebreaker). Members disabled in the chain (fallback_config.enabled = 0)+ * are dropped.+ *+ * Pass the result to routeRequest() as `prefetchedChain` and DO NOT pass a+ * `preferredModelDbId` that isn't already one of these rows — otherwise the+ * preferred-model injection in routeRequest would unshift an off-group model and+ * the pin would no longer be strict (it could answer with a different model).+ */+export function resolveModelGroupCandidates(memberDbIds: number[]): ChainRow[] {+ const db = getDb();+ const strategy = getRoutingStrategy();+ if (strategy !== 'priority') refreshStatsCache(db);++ const selectMember = db.prepare(`+ SELECT m.id as model_db_id, COALESCE(fc.priority, 0) as priority,+ COALESCE(fc.enabled, 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+ LEFT JOIN fallback_config fc ON fc.model_db_id = m.id+ WHERE m.id = ? AND m.enabled = 1+ `);++ const rows: ChainRow[] = [];+ for (const id of memberDbIds) {+ const row = selectMember.get(id) as ChainRow | undefined;+ if (row && row.enabled) rows.push(row);+ }+ return orderChain(rows, strategy);+}+// A panel candidate surfaced to the fusion layer: enough to pick a diverse set// and resolve each to a pinned dispatch.export interface FusionCandidate {@@ -731,16 +771,40 @@ export function resolveFusionCandidate(modelId: string): FusionCandidate | nullmodel_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,- };+ if (row) {+ 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,+ };+ }++ // Unify ON: a fusion picker value may be a canonical GROUP id rather than a+ // raw model_id. Resolve it to the group's best-ordered enabled member so+ // saved fusion configs that use canonical ids keep working. Exact model_id+ // match above always wins first, so OFF mode and legacy configs are untouched.+ if (isUnifyEnabled()) {+ const members = resolveRequestedIdToMembers(modelId, getModelGroups());+ if (members && members.length > 0) {+ const top = resolveModelGroupCandidates(members)[0];+ if (top) {+ return {+ modelDbId: top.model_db_id,+ platform: top.platform,+ modelId: top.model_id,+ displayName: top.display_name,+ sizeLabel: top.size_label,+ supportsVision: top.supports_vision,+ supportsTools: top.supports_tools,+ };+ }+ }+ }+ return null;}export function routeRequest(estimatedTokens = 1000, skipKeys?: Set<string>, preferredModelDbId?: number, requireVision = false, requireTools = false, skipModels?: Set<number>, prefetchedChain?: ChainRow[]): RouteResult {diff --git a/shared/types.ts b/shared/types.tsindex a5cbed2e..82979ade 100644--- a/shared/types.ts+++ b/shared/types.ts@@ -117,6 +117,34 @@ export interface FallbackEntry {speedRank: number;priority: number;enabled: boolean;+ // Present when model unification is enabled — identifies the logical model+ // this provider row belongs to so the dashboard can render grouped rows.+ groupKey?: string;+ canonicalId?: string;+ groupLabel?: string;+}++// ---- Model Grouping (unify the same model across providers) ----+// One logical model can be served by several providers (rows in the `models`+// table). When unification is enabled, those rows collapse into a single group+// keyed by a normalized display name; see server/src/services/model-groups.ts.+export interface ModelGroupInfo {+ groupKey: string; // normalized display name — the grouping identity+ canonicalId: string; // stable slug advertised on /v1/models+ groupLabel: string; // human label (suffix-stripped display name)+}++export interface UnifyOverrides {+ // Coalesce several normalized display-names (or exact "platform:model_id"+ // members) into one group keyed by `into`.+ merges: { into: string; keys: string[] }[];+ // Force a specific "platform:model_id" row out of its computed group.+ splits: { member: string; groupKey?: string }[];+}++export interface UnifySettings {+ enabled: boolean;+ overrides: UnifyOverrides;}// ---- OpenAI-Compatible Types ----