Skip to content

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.md
index 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 review
diff --git a/client/src/i18n/locales/en.json b/client/src/i18n/locales/en.json
index 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.ts
new file mode 100644
index 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.tsx
index 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 | null
rpdLimit: number | null
monthlyTokenBudget: 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?: number
supportsVision: boolean
supportsTools: boolean
keyCount: 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: number
totalUsed: 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 a11y
live-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.tsx
index 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 >= maxK
return (
<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.tsx
index 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 ?? selectedModel
return (
<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.ts
new file mode 100644
index 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.ts
index 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 'vite
import 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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, maybeInjectContextHandof
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';
+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 available
FROM 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 available
if (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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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, skip
return 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 | null
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,
- };
+ 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.ts
index 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 ----