free-coding-models 0.5.59 → 0.5.61

package/src/core/model-merger.js

@@ -1,4 +1,5 @@
 import { parseCtxToK, parseSweToNum } from './utils.js'
+import { lookupExtendedBenchmark, mergeExtendedBenchmark, getCatalogStats as getExtendedBenchStats } from './extended-benchmarks.js'
 
 const TIER_RANK = { 'S+': 0, 'S': 1, 'A+': 2, 'A': 3, 'A-': 4, 'B+': 5, 'B': 6, 'C': 7 }
 
@@ -67,3 +68,157 @@ export function buildMergedModels(models) {
     providerCount: g.providers.length,
   }))
 }
+
+// ─── Extended-benchmark overlay (t4) ─────────────────────────────────────────
+
+/**
+ * 📖 Overlay the extended-benchmark catalog (Coding/Math/Agentic/Reasoning/MMLU-Pro/
+ * 📖 GPQA/HLE + reasoning/vision flags) onto every merged model. The catalog is
+ * 📖 a static JSON in `src/data/benchmarks.json`, looked up via prefix-index for
+ * 📖 O(key length) cost. We try the group's primary modelId first, then any of its
+ * 📖 provider variants as a fallback.
+ *
+ * 📖 Returns a NEW array of merged models — does not mutate the input.
+ *
+ * @param {Array} mergedModels — Output of buildMergedModels
+ * @returns {Array} The same models with `extendedBench` + `metaSourceExt` set
+ */
+export function overlayExtendedBenchmarks(mergedModels) {
+  if (!Array.isArray(mergedModels)) return mergedModels
+  return mergedModels.map(m => {
+    // 📖 Try the primary modelId first, then provider variants
+    let entry = null
+    if (m.providers && m.providers.length > 0) {
+      for (const p of m.providers) {
+        entry = lookupExtendedBenchmark(p.modelId)
+        if (entry) break
+      }
+    }
+    return mergeExtendedBenchmark(m, entry)
+  })
+}
+
+// ─── models.dev overlay (t5) ──────────────────────────────────────────────────
+
+/**
+ * 📖 Async: enrich every merged model with live metadata from models.dev
+ * 📖 (context window, max output tokens, reasoning/vision/thinking flags). This
+ * 📖 runs in the background — the TUI renders with sources.js values first, then
+ * 📖 re-renders once the fetch resolves. If the fetch fails, the overlay is a
+ * 📖 no-op and `metaSource` stays at 'sources.js'.
+ *
+ * 📖 `metaSource` reflects which layer currently holds the values:
+ * 📖   - 'sources.js'      — curated only (no live data, or fetch failed)
+ * 📖   - 'models.dev'      — live values replaced the curated ones
+ * 📖   - 'sources.js+md'   — live overlay + curated (no overrides applied)
+ *
+ * @param {Array} mergedModels — Output of buildMergedModels (or overlayExtendedBenchmarks)
+ * @param {object} [opts]
+ * @param {Function} [opts.fetchCatalog] — Injected fetcher (defaults to fetchModelsDevCatalog)
+ * @param {Function} [opts.buildIndex]  — Injected indexer (defaults to buildModelIndex)
+ * @param {Function} [opts.lookup]      — Injected lookup (defaults to lookupModelDevMeta)
+ * @param {boolean} [opts.mutate=false] — Mutate input in place
+ * @returns {Promise<Array>} The same models with `modelsDevMeta` + `metaSource` set
+ */
+export async function overlayModelsDevMetadata(mergedModels, opts = {}) {
+  if (!Array.isArray(mergedModels)) return mergedModels
+
+  // 📖 Resolve dependencies (with lazy import to avoid a hard dep when t5 is unused)
+  const fetchCatalog = opts.fetchCatalog
+    ?? (await import('./models-dev-fetcher.js')).fetchModelsDevCatalog
+  const buildIndex = opts.buildIndex
+    ?? (await import('./models-dev-index.js')).buildModelIndex
+  const lookup = opts.lookup
+    ?? (await import('./models-dev-index.js')).lookupModelDevMeta
+
+  let catalog = null
+  try {
+    catalog = await fetchCatalog({ silent: true })
+  } catch {
+    catalog = null
+  }
+  if (!catalog || typeof catalog !== 'object') {
+    // 📖 Fetch failed — leave models untouched, mark provenance
+    return mergedModels.map(m => ({ ...m, modelsDevMeta: null, metaSource: 'sources.js' }))
+  }
+
+  const index = buildIndex(catalog)
+  const touchedAt = Date.now()
+
+  for (let i = 0; i < mergedModels.length; i++) {
+    const m = mergedModels[i]
+    let bestMatch = null
+    if (m.providers && m.providers.length > 0) {
+      // 📖 Try the full "<providerKey>/<modelId>" key first (most common case),
+      // 📖 then the bare modelId (handles the modelId-already-includes-prefix case).
+      for (const p of m.providers) {
+        const fullKey = p.providerKey ? `${p.providerKey}/${p.modelId}` : p.modelId
+        const r1 = lookup(fullKey, m.label, index)
+        if (r1) { bestMatch = r1; break }
+        const r2 = lookup(p.modelId, m.label, index)
+        if (r2) { bestMatch = r2; break }
+      }
+    }
+    if (!bestMatch && m.slug) bestMatch = lookup(m.slug, m.label, index)
+    if (!bestMatch) {
+      if (opts.mutate) {
+        Object.assign(m, { modelsDevMeta: null, metaSource: 'sources.js' })
+        mergedModels[i] = m
+      } else {
+        mergedModels[i] = { ...m, modelsDevMeta: null, metaSource: 'sources.js' }
+      }
+      continue
+    }
+    const norm = bestMatch.entry
+    const liveCtx = typeof norm.contextWindow === 'number' ? formatCtxFromNum(norm.contextWindow) : null
+    const overlay = {
+      contextWindow:    liveCtx ?? m.ctx,
+      contextWindowNum: norm.contextWindow ?? null,
+      maxOutputTokens:  norm.maxOutputTokens ?? null,
+      reasoning: norm.reasoning === true,
+      vision:    norm.vision === true,
+      thinking:  norm.thinking === true,
+      toolCall:  norm.toolCall === true,
+      matchKind: bestMatch.matchKind,
+      lastFetchedAt: touchedAt,
+    }
+    if (opts.mutate) {
+      Object.assign(m, { modelsDevMeta: overlay, metaSource: 'models.dev' })
+      mergedModels[i] = m
+    } else {
+      mergedModels[i] = { ...m, modelsDevMeta: overlay, metaSource: 'models.dev' }
+    }
+  }
+  return mergedModels
+}
+
+// 📖 formatCtxFromNum: Convert a raw token count (e.g. 128000) into a compact string
+// 📖 matching the sources.js convention ("128k", "1M"). Used by overlayModelsDevMetadata.
+function formatCtxFromNum(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) return null
+  if (n >= 1_000_000) {
+    const m = n / 1_000_000
+    return (Number.isInteger(m) ? m.toString() : m.toFixed(1)) + 'M'
+  }
+  if (n >= 1000) {
+    const k = n / 1000
+    return (Number.isInteger(k) ? k.toString() : k.toFixed(0)) + 'k'
+  }
+  return n.toString()
+}
+
+// ─── Stats helper ─────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Aggregate stats about all enrichment layers — used by the TUI footer chip,
+ * 📖 the web dashboard /stats endpoint, and the drift report.
+ *
+ * @returns {{
+ *   extendedBench: { total: number, lastUpdated: string, source: string, byField: object }
+ * }}
+ */
+export function getEnrichmentStats() {
+  return {
+    extendedBench: getExtendedBenchStats(),
+  }
+}

package/src/core/models-dev-fetcher.js

@@ -0,0 +1,210 @@
+/**
+ * @file models-dev-fetcher.js
+ * @description Fetcher + TTL cache for the models.dev community catalog, with retry/backoff.
+ *              Used by src/core/models-dev-index.js to enrich `sources.js` with live metadata
+ *              (context window, max output tokens, reasoning/vision/thinking support).
+ *
+ * @details
+ *   📖 Why this exists:
+ *   📖 - `sources.js` is curated (which models to ping, SWE-bench tier) but its `ctx` field
+ *   📖   drifts — vendors expand windows (128k → 256k → 1M) and we don't catch up.
+ *   📖 - models.dev is a community-maintained registry of LLM metadata (context, max
+ *   📖   tokens, reasoning/vision flags, thinking levels) that we can use as an overlay.
+ *   📖 - The fetch happens lazily and non-blocking — if the network is down or the
+ *   📖   catalog is unreachable, the TUI keeps rendering with sources.js values.
+ *
+ *   📖 Behaviour:
+ *   📖 - 3 retries with 250 ms backoff, 8s per-request timeout.
+ *   📖 - 5-min in-process cache (TTL).
+ *   📖 - Sets a custom User-Agent so the maintainers can identify us.
+ *   📖 - Returns null on failure (no throw). Callers MUST handle null gracefully.
+ *
+ *   📖 The fetched JSON shape (from models.dev):
+ *   📖   {
+ *   📖     "<providerKey>": {
+ *   📖       "id": "deepseek",
+ *   📖       "name": "DeepSeek",
+ *   📖       "models": {
+ *   📖         "<modelId>": {
+ *   📖           "id": "deepseek-chat",
+ *   📖           "name": "DeepSeek Chat",
+ *   📖           "context": 128000,
+ *   📖           "maxTokens": 8192,
+ *   📖           "reasoning": false,
+ *   📖           "vision": false,
+ *   📖           "thinking": false,
+ *   📖           "tool_call": true,
+ *   📖           ...
+ *   📖         }
+ *   📖       }
+ *   📖     }
+ *   📖   }
+ *
+ * @functions
+ *   → fetchModelsDevCatalog({ force }?)  — Returns the parsed catalog (or null on failure)
+ *   → getModelsDevCacheStats()           — { hits, misses, lastFetchAt, lastError }
+ *   → clearModelsDevCache()              — Reset the in-process cache (for tests + drift script)
+ *   → _resetModelsDevCacheForTests()     — Alias used by tests (no behaviour difference)
+ *
+ * @exports fetchModelsDevCatalog, getModelsDevCacheStats, clearModelsDevCache,
+ *          MODELS_DEV_URL, DEFAULT_FETCH_TIMEOUT_MS, MODELS_DEV_CACHE_TTL_MS
+ *
+ * @see src/core/models-dev-index.js — uses this fetcher to build the lookup index
+ * @see src/core/models-drift.js     — drift detection against sources.js
+ * @see https://models.dev           — community catalog source
+ */
+
+const MODELS_DEV_URL = 'https://models.dev/models.json'
+const DEFAULT_FETCH_TIMEOUT_MS = 8_000
+const MODELS_DEV_CACHE_TTL_MS = 5 * 60 * 1000  // 📖 5 minutes
+const MODELS_DEV_RETRIES = 3
+const MODELS_DEV_RETRY_DELAY_MS = 250
+const USER_AGENT = 'free-coding-models (+https://github.com/vava-nessa/free-coding-models)'
+
+// 📖 Re-export as ES exports so the test file (and other consumers) can import them.
+// 📖 We re-declare them as named exports here to keep the file self-documenting.
+export {
+  MODELS_DEV_URL,
+  DEFAULT_FETCH_TIMEOUT_MS,
+  MODELS_DEV_CACHE_TTL_MS,
+  MODELS_DEV_RETRIES,
+  MODELS_DEV_RETRY_DELAY_MS,
+  USER_AGENT,
+}
+
+// ─── Module-level state ──────────────────────────────────────────────────────
+
+/** 📖 Cached entry: { expiresAt, promise, resolvedAt, error, hits, misses } */
+let _cache = null
+
+/** 📖 Simple sleep helper (used between retries). */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Fetch (or return the cached) models.dev catalog. Returns the parsed JSON
+ * 📖 object on success, or null on failure (after exhausting all retries).
+ * 📖 Multiple concurrent calls share the same in-flight promise (no thundering herd).
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.force=false] — Bypass the cache and re-fetch
+ * @param {number} [opts.timeoutMs=8000] — Per-request timeout
+ * @param {number} [opts.retries=3] — Number of attempts before giving up
+ * @param {number} [opts.retryDelayMs=250] — Backoff between attempts
+ * @param {boolean} [opts.silent=true] — Suppress console.warn on fetch failure
+ * @returns {Promise<object|null>}
+ */
+export async function fetchModelsDevCatalog({
+  force = false,
+  timeoutMs = DEFAULT_FETCH_TIMEOUT_MS,
+  retries = MODELS_DEV_RETRIES,
+  retryDelayMs = MODELS_DEV_RETRY_DELAY_MS,
+  silent = true,
+} = {}) {
+  const now = Date.now()
+  if (!force && _cache && _cache.expiresAt > now && _cache.promise) {
+    _cache.hits++
+    return _cache.promise
+  }
+  if (_cache) _cache.misses++
+
+  const promise = (async () => {
+    let lastError = null
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        const ctrl = new AbortController()
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+        try {
+          const res = await fetch(MODELS_DEV_URL, {
+            headers: { 'User-Agent': USER_AGENT, 'Accept': 'application/json' },
+            signal: ctrl.signal,
+          })
+          if (!res.ok) {
+            lastError = new Error(`HTTP ${res.status} ${res.statusText}`.trim())
+          } else {
+            const data = await res.json()
+            if (data && typeof data === 'object') {
+              return data
+            }
+            lastError = new Error('models.dev returned non-object payload')
+          }
+        } finally {
+          clearTimeout(timer)
+        }
+      } catch (err) {
+        lastError = err
+      }
+      if (attempt < retries) {
+        await sleep(retryDelayMs)
+      }
+    }
+    if (!silent) {
+      console.warn(`[models.dev] fetch failed after ${retries} attempts: ${lastError?.message ?? 'unknown error'}`)
+    }
+    if (_cache) {
+      _cache.error = lastError?.message ?? 'unknown'
+      _cache.resolvedAt = Date.now()
+    }
+    return null
+  })()
+
+  _cache = {
+    expiresAt: Date.now() + MODELS_DEV_CACHE_TTL_MS,
+    promise,
+    resolvedAt: null,
+    error: null,
+    hits: _cache?.hits ?? 0,
+    misses: _cache?.misses ?? 0,
+  }
+
+  // 📖 Wrap the promise so we can capture resolvedAt + error metadata on success too
+  const wrapped = promise.then(data => {
+    if (_cache) {
+      _cache.resolvedAt = Date.now()
+      _cache.error = null
+    }
+    return data
+  })
+  return wrapped
+}
+
+/**
+ * 📖 Stats for the in-process cache. Used by the TUI footer chip and the
+ * 📖 /health endpoint of the daemon.
+ *
+ * @returns {{
+ *   hits: number,
+ *   misses: number,
+ *   lastFetchAt: number|null,    // ms timestamp of last completed fetch
+ *   lastError: string|null,
+ *   cached: boolean              // whether the current entry is still within TTL
+ * }}
+ */
+export function getModelsDevCacheStats() {
+  if (!_cache) {
+    return { hits: 0, misses: 0, lastFetchAt: null, lastError: null, cached: false }
+  }
+  return {
+    hits: _cache.hits,
+    misses: _cache.misses,
+    lastFetchAt: _cache.resolvedAt,
+    lastError: _cache.error,
+    cached: _cache.expiresAt > Date.now(),
+  }
+}
+
+/**
+ * 📖 Clear the in-process cache. The next call to fetchModelsDevCatalog will
+ * 📖 re-fetch. Used by tests + the drift script (to get a fresh view).
+ */
+export function clearModelsDevCache() {
+  _cache = null
+}
+
+/** 📖 Test-only alias. Same behaviour as clearModelsDevCache. */
+export function _resetModelsDevCacheForTests() {
+  clearModelsDevCache()
+}

package/src/core/models-dev-index.js

@@ -0,0 +1,311 @@
+/**
+ * @file models-dev-index.js
+ * @description Build a normalized lookup index over the models.dev catalog.
+ *              Used to enrich `sources.js` models with live metadata (context window,
+ *              max output tokens, reasoning/vision/thinking support).
+ *
+ * @details
+ *   📖 Why this exists:
+ *   📖 - models.dev returns a nested object: `{ <providerKey>: { models: { <id>: {...} } } }`.
+ *   📖 - sources.js uses a flat array with display labels. We need a fast, normalized
+ *   📖   way to look up a model by either its `provider/modelId` or by display label.
+ *   📖 - Lookup order: exact id → provider-prefixed id → display label substring.
+ *   📖 - Substring matches are a last resort — they can produce false positives
+ *   📖   (e.g. "deepseek-chat" substring of "deepseek-chat-2"). We log them via
+ *   📖   the `metaSource` field so callers can surface the uncertainty.
+ *
+ *   📖 Provider aliases: the catalog may list "together" while sources.js uses
+ *   📖 "togetherai". We provide a small alias map to bridge the two. New aliases
+ *   📖 can be added without touching the lookup logic.
+ *
+ *   📖 Cross-surface: pure logic, used by the TUI, Web Dashboard, and drift detector.
+ *
+ * @functions
+ *   → buildModelIndex(catalog)                    — Returns { byId, byProviderModel, byLabel }
+ *   → lookupModelDevMeta(modelId, label, index?)  — Returns the normalized entry or null
+ *   → normalizeModelDevEntry(rawEntry)            — Shape-validate a raw models.dev model
+ *   → PROVIDER_ALIASES                            — Map of canonical provider keys
+ *
+ * @exports buildModelIndex, lookupModelDevMeta, normalizeModelDevEntry, PROVIDER_ALIASES
+ *
+ * @see src/core/models-dev-fetcher.js — provides the catalog
+ * @see src/core/models-drift.js      — uses this for drift detection
+ */
+
+// ─── Provider alias map ──────────────────────────────────────────────────────
+
+/**
+ * 📖 Map of source provider keys (used by sources.js) to models.dev provider keys
+ * 📖 (used by their catalog). The lookup falls back to the source key if no alias
+ * 📖 matches, so adding a new provider is a no-op until a divergence shows up.
+ */
+export const PROVIDER_ALIASES = {
+  // sources.js → models.dev
+  nvidiaNim:  'nvidia',
+  nvidia:     'nvidia',
+  openrouter: 'openrouter',
+  groq:       'groq',
+  cerebras:   'cerebras',
+  github:     'github-models',
+  mistral:    'mistral',
+  cloudflare: 'cloudflare-workers-ai',
+  opencode:   'opencode',
+  scaleway:   'scaleway',
+  google:     'google',
+  zai:        'zai',
+  zaiOrg:     'zai',
+  kilocode:   'kilocode',
+  kilocodeAi: 'kilo',
+  deepseek:   'deepseek',
+  qwen:       'qwen',
+  together:   'togetherai',
+  novita:     'novita-ai',
+  ollama:     'ollama',
+  openhands:  'openhands',
+  xai:        'xai',
+  cohere:     'cohere',
+  perplexity: 'perplexity',
+  anthropic:  'anthropic',
+  openai:     'openai',
+  meta:       'meta',
+  moonshotai: 'moonshotai',
+  zhipu:      'zhipu',
+  stepfun:    'stepfun',
+  bytedance:  'bytedance',
+  stockmark:  'stockmark',
+  minimax:    'minimax',
+  minimaxai:  'minimax',
+  poolside:   'poolside',
+  cohereCommand: 'cohere',
+  llm7:       'llm7',
+  routeway:   'routeway',
+  dashscope:  'dashscope',
+}
+
+function aliasesFor(providerKey) {
+  if (!providerKey) return []
+  const lower = String(providerKey).toLowerCase()
+  const aliased = PROVIDER_ALIASES[providerKey] ?? PROVIDER_ALIASES[lower]
+  if (aliased && aliased !== providerKey) return [providerKey, aliased]
+  return [providerKey]
+}
+
+// ─── Shape normalisation ─────────────────────────────────────────────────────
+
+/**
+ * 📖 Convert a raw models.dev model entry into the normalized shape our merger
+ * 📖 consumes. Defensive: returns null if the entry is unusable, so callers can
+ * 📖 skip it without try/catch.
+ *
+ * 📖 Normalized shape:
+ * 📖   {
+ * 📖     id: string,
+ * 📖     name: string,
+ * 📖     contextWindow: number|null,
+ * 📖     maxOutputTokens: number|null,
+ * 📖     reasoning: boolean,
+ * 📖     vision: boolean,
+ * 📖     thinking: boolean,
+ * 📖     toolCall: boolean,
+ * 📖     provider: string,         // original provider key
+ * 📖     raw: object               // original entry (for debug / future fields)
+ * 📖   }
+ *
+ * @param {object} rawEntry
+ * @returns {object|null}
+ */
+export function normalizeModelDevEntry(rawEntry) {
+  if (!rawEntry || typeof rawEntry !== 'object') return null
+  const id = rawEntry.id
+  if (typeof id !== 'string' || !id) return null
+  const numOrNull = (v) => (typeof v === 'number' && Number.isFinite(v)) ? v : null
+  const boolOrFalse = (v) => v === true
+
+  // 📖 Context + max tokens come from `limit` (flat) or top-level (nested)
+  const limit = rawEntry.limit && typeof rawEntry.limit === 'object' ? rawEntry.limit : {}
+  const contextWindow = numOrNull(limit.context ?? rawEntry.context ?? rawEntry.contextWindow)
+  const maxOutputTokens = numOrNull(limit.output ?? rawEntry.max_tokens ?? rawEntry.maxTokens)
+
+  // 📖 Vision is a modality flag (flat) or a top-level boolean (nested)
+  const modalities = rawEntry.modalities && typeof rawEntry.modalities === 'object' ? rawEntry.modalities : {}
+  const visionFromModalities = Array.isArray(modalities.input)
+    ? modalities.input.some(m => typeof m === 'string' && (m.toLowerCase().includes('image') || m.toLowerCase().includes('video')))
+    : false
+  const vision = boolOrFalse(rawEntry.vision) || visionFromModalities
+
+  // 📖 Provider is the id prefix (flat) or a top-level field (nested)
+  const slashIdx = id.indexOf('/')
+  const providerFromId = slashIdx !== -1 ? id.slice(0, slashIdx) : ''
+  const provider = typeof rawEntry.provider === 'string' && rawEntry.provider
+    ? rawEntry.provider
+    : providerFromId
+
+  return {
+    id,
+    name: typeof rawEntry.name === 'string' ? rawEntry.name : id,
+    contextWindow,
+    maxOutputTokens,
+    reasoning: boolOrFalse(rawEntry.reasoning),
+    vision,
+    thinking: boolOrFalse(rawEntry.thinking),
+    toolCall: boolOrFalse(rawEntry.tool_call ?? rawEntry.toolCall),
+    provider,
+    raw: rawEntry,
+  }
+}
+
+// ─── Index builder ───────────────────────────────────────────────────────────
+
+/**
+ * 📖 Build a normalized index over the models.dev catalog. Returns three maps:
+ * 📖   - byId: "deepseek/deepseek-chat" → normalized entry
+ * 📖   - byProviderModel: "deepseek/deepseek-chat" → normalized entry (same key, exposed
+ * 📖     separately so the merger can pick whichever it prefers)
+ * 📖   - byLabel: "DeepSeek Chat" → normalized entry[]  (substring fallback)
+ *
+ * @param {object} catalog — The raw models.dev catalog
+ * @returns {{
+ *   byId: Map<string, object>,
+ *   byProviderModel: Map<string, object>,
+ *   byLabel: Map<string, object[]>,
+ *   total: number,
+ *   providers: string[]
+ * }}
+ */
+export function buildModelIndex(catalog) {
+  const byId = new Map()
+  const byProviderModel = new Map()
+  const byLabel = new Map()
+  const providers = []
+  let total = 0
+
+  if (!catalog || typeof catalog !== 'object') {
+    return { byId, byProviderModel, byLabel, total: 0, providers: [] }
+  }
+
+  // 📖 Detect format: flat catalogs have keys that look like model ids
+  // 📖 ("provider/model-name") while nested catalogs have keys that look like
+  // 📖 provider ids with a `models` sub-object.
+  const entries = Object.entries(catalog)
+  const isFlat = entries.length > 0 && entries.every(([k, v]) => {
+    if (!v || typeof v !== 'object') return false
+    if (k.includes('/')) return typeof v.limit === 'object' || typeof v.id === 'string'
+    return false
+  })
+
+  if (isFlat) {
+    // 📖 Flat format: each top-level key is "<provider>/<modelId>"
+    for (const [idKey, rawEntry] of entries) {
+      if (!rawEntry || typeof rawEntry !== 'object') continue
+      const norm = normalizeModelDevEntry(rawEntry)
+      if (!norm) continue
+      const providerKey = norm.provider || idKey.slice(0, idKey.indexOf('/'))
+      if (!providers.includes(providerKey)) providers.push(providerKey)
+      if (!byId.has(idKey)) byId.set(idKey, norm)
+      if (!byProviderModel.has(idKey)) byProviderModel.set(idKey, norm)
+      const label = norm.name || idKey
+      const arr = byLabel.get(label) ?? []
+      arr.push(norm)
+      byLabel.set(label, arr)
+      total++
+    }
+  } else {
+    // 📖 Nested format: { <provider>: { id, name, models: {...} } }
+    for (const [providerKey, providerBucket] of entries) {
+      if (!providerBucket || typeof providerBucket !== 'object') continue
+      const models = providerBucket.models
+      if (!models || typeof models !== 'object') continue
+      providers.push(providerKey)
+      for (const [modelId, rawEntry] of Object.entries(models)) {
+        const norm = normalizeModelDevEntry(rawEntry)
+        if (!norm) continue
+        norm.provider = providerKey
+        const idKey = `${providerKey}/${modelId}`
+        if (!byId.has(idKey)) byId.set(idKey, norm)
+        if (!byProviderModel.has(idKey)) byProviderModel.set(idKey, norm)
+        const label = norm.name || modelId
+        const arr = byLabel.get(label) ?? []
+        arr.push(norm)
+        byLabel.set(label, arr)
+        total++
+      }
+    }
+  }
+  return { byId, byProviderModel, byLabel, total, providers }
+}
+
+// ─── Lookup ──────────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Look up a model in the index. Tries in order:
+ * 📖   1. Exact "provider/modelId" match (O(1))
+ * 📖   2. Aliased provider variants (e.g. "nvidiaNim" → "nvidia")
+ * 📖   3. Display-label substring match (last resort, may produce false positives)
+ *
+ * 📖 Returns a small wrapper so callers know HOW the match was made:
+ * 📖   { entry, matchKind: 'exact'|'alias'|'substring' }
+ *
+ * @param {string} modelId
+ * @param {string} [label] — display label from sources.js (helps the substring fallback)
+ * @param {object} [index] — Optional pre-built index (defaults to building one)
+ * @param {object} [catalog] — Optional catalog (used when index is omitted)
+ * @returns {{ entry: object, matchKind: string }|null}
+ */
+export function lookupModelDevMeta(modelId, label, index, catalog) {
+  if (!modelId || typeof modelId !== 'string') return null
+  let idx = index
+  if (!idx) {
+    if (!catalog) return null
+    idx = buildModelIndex(catalog)
+  }
+
+  // Rule 1: exact match — supports both "provider/modelId" and bare "modelId"
+  if (idx.byProviderModel.has(modelId)) {
+    return { entry: idx.byProviderModel.get(modelId), matchKind: 'exact' }
+  }
+  // 📖 Try the bare model id in case the catalog's provider is implicit
+  if (!modelId.includes('/') && idx.byId.has(modelId)) {
+    return { entry: idx.byId.get(modelId), matchKind: 'exact' }
+  }
+
+  // Rule 2: provider alias variants. Strip the provider prefix from the input
+  // and try each alias.
+  if (modelId.includes('/')) {
+    const slash = modelId.indexOf('/')
+    const providerKey = modelId.slice(0, slash)
+    const rest = modelId.slice(slash + 1)
+    for (const alias of aliasesFor(providerKey)) {
+      const altKey = `${alias}/${rest}`
+      if (idx.byProviderModel.has(altKey)) {
+        return { entry: idx.byProviderModel.get(altKey), matchKind: 'alias' }
+      }
+    }
+    // 📖 Try the bare rest under any provider (last-ditch exact)
+    for (const providerKey2 of idx.providers ?? []) {
+      const altKey2 = `${providerKey2}/${rest}`
+      if (idx.byProviderModel.has(altKey2)) {
+        return { entry: idx.byProviderModel.get(altKey2), matchKind: 'alias' }
+      }
+    }
+  }
+
+  // Rule 3: display-label substring fallback
+  if (label && typeof label === 'string') {
+    const labelLower = label.toLowerCase()
+    // 📖 Prefer entries whose name matches the label exactly first
+    if (idx.byLabel.has(label)) {
+      const arr = idx.byLabel.get(label)
+      if (arr.length > 0) return { entry: arr[0], matchKind: 'substring' }
+    }
+    // 📖 Then scan for a substring match (lowercase)
+    for (const [key, arr] of idx.byLabel.entries()) {
+      if (!arr || arr.length === 0) continue
+      const keyLower = key.toLowerCase()
+      if (keyLower.includes(labelLower) || labelLower.includes(keyLower)) {
+        return { entry: arr[0], matchKind: 'substring' }
+      }
+    }
+  }
+
+  return null
+}