dsh-model-capability-sync 0.0.0-stage → 0.1.0

package/src/match.ts

@@ -0,0 +1,130 @@
+/**
+ * Matching one configured gateway model id against the models.dev catalog.
+ *
+ * A gateway aggregates arbitrary upstreams and invents its own ids, so the
+ * match walks from strict to loose and reports which rule fired — the UI shows
+ * it, and an explicit alias always wins.
+ * @module dsh-model-capability-sync/match
+ */
+import type { Catalog, CatalogEntry } from './catalog.ts'
+import type { MatchInfo, MatchVia } from './types.ts'
+
+/**
+ * Variant suffixes a gateway appends to one upstream model. Stripping them
+ * turns `gemini-3.8-flash-high` back into the catalog's `gemini-3.8-flash`.
+ */
+const VARIANT_SUFFIX = /-(high|low|medium|minimal|max|xhigh|thinking|preview|latest|chat)$/
+
+/**
+ * First-party vendor provider ids in the models.dev catalog. The same model
+ * appears under dozens of aggregators whose capacity numbers disagree, so a
+ * vendor entry outranks every reseller when both exist.
+ */
+const FIRST_PARTY = new Set([
+  'openai', 'anthropic', 'google', 'deepseek', 'xai', 'meta', 'mistral', 'cohere',
+  'moonshotai', 'moonshotai-cn', 'zai', 'zhipuai', 'alibaba', 'alibaba-cn', 'qwen',
+  'sensenova', 'minimax', 'stepfun', 'bytedance', 'baidu', 'nvidia', 'microsoft',
+  'amazon', 'ai21', 'perplexity', 'upstage', '01-ai', 'inclusionai', 'tencent', 'kuaishou',
+])
+
+/** How complete an entry's facts are; the most complete wins a tie. */
+function score(entry: CatalogEntry): number {
+  const model = entry.model
+  let value = 0
+  if (FIRST_PARTY.has(entry.provider)) value += 5
+  if (model.limit?.context !== undefined || model.limit?.output !== undefined) value += 2
+  if (model.modalities?.input !== undefined) value += 2
+  if (model.reasoning_options !== undefined) value += 1
+  if (model.name !== undefined) value += 1
+  return value
+}
+
+/**
+ * Pick the best of several provider entries for the same id: the one carrying
+ * the most facts, then the alphabetically first provider so repeated runs are
+ * stable.
+ */
+function pickBest(entries: readonly CatalogEntry[]): CatalogEntry | undefined {
+  let best: CatalogEntry | undefined
+  let bestScore = -1
+  for (const entry of entries) {
+    const value = score(entry)
+    if (value > bestScore || value === bestScore && best !== undefined && entry.provider < best.provider) {
+      best = entry
+      bestScore = value
+    }
+  }
+  return best
+}
+
+/** The id without its vendor path prefix (`qoder-gj/DeepSeek-Flash` → `DeepSeek-Flash`). */
+function basename(id: string): string {
+  const slash = id.lastIndexOf('/')
+  return slash === -1 ? id : id.slice(slash + 1)
+}
+
+/** Look one key up exactly, then case-insensitively. */
+function lookup(catalog: Catalog, key: string): { entries: readonly CatalogEntry[]; via: MatchVia } | undefined {
+  const exact = catalog.byId.get(key)
+  if (exact !== undefined) return { entries: exact, via: 'exact' }
+  const folded = catalog.byFolded.get(key.toLowerCase())
+  if (folded !== undefined) return { entries: folded, via: 'folded' }
+  return undefined
+}
+
+/** Build the public match record for one chosen entry. */
+function describe(entry: CatalogEntry, via: MatchVia): MatchInfo {
+  return {
+    provider: entry.provider,
+    modelId: entry.id,
+    via,
+    firstParty: FIRST_PARTY.has(entry.provider),
+    ...entry.model.name === undefined ? {} : { name: entry.model.name },
+  }
+}
+
+/**
+ * Resolve one gateway model id.
+ * @param catalog - the indexed catalog.
+ * @param id - the gateway model id exactly as configured.
+ * @param aliases - explicit gateway id → catalog id overrides.
+ * @returns the match, or `undefined` when nothing fits.
+ */
+export function matchModel(
+  catalog: Catalog,
+  id: string,
+  aliases: Readonly<Record<string, string>> = {},
+): MatchInfo | undefined {
+  const alias = aliases[id]
+  if (alias !== undefined && alias.length > 0) {
+    const hit = lookup(catalog, alias)
+    const entry = hit === undefined ? undefined : pickBest(hit.entries)
+    if (entry !== undefined) return describe(entry, 'alias')
+  }
+
+  const exact = lookup(catalog, id)
+  if (exact !== undefined) {
+    const entry = pickBest(exact.entries)
+    if (entry !== undefined) return describe(entry, exact.via)
+  }
+
+  const base = basename(id)
+  if (base !== id) {
+    const hit = lookup(catalog, base)
+    if (hit !== undefined) {
+      const entry = pickBest(hit.entries)
+      if (entry !== undefined) return describe(entry, 'basename')
+    }
+  }
+
+  const stripped = base.replace(VARIANT_SUFFIX, '')
+  if (stripped !== base && stripped.length > 0) {
+    const hit = lookup(catalog, stripped)
+    if (hit !== undefined) {
+      const entry = pickBest(hit.entries)
+      if (entry !== undefined) return describe(entry, 'suffix')
+    }
+  }
+
+  return undefined
+}

package/src/sort.ts

@@ -0,0 +1,62 @@
+/**
+ * Ordering for one provider's model list.
+ *
+ * A gateway id carries its vendor as a path prefix (`qoder-gj/Qwen3.8-Flash`),
+ * so sorting on the whole id would group by nothing useful: the model family
+ * is the part after the slash, and the vendor is what a reader scans for. The
+ * order is therefore: vendor prefix first, then the model name inside it. An
+ * id without a prefix has only its name to sort on.
+ *
+ * Comparison is case-insensitive, with the raw id as the final tie-break, so
+ * two runs on the same configuration always produce the same array.
+ * @module dsh-model-capability-sync/sort
+ */
+
+/** The two ordering keys of one id: the vendor group, then the model name. */
+export interface ModelSortKey {
+  /** The prefix before the last slash, or the whole id when there is none. */
+  group: string
+  /** The part after the last slash, or the whole id when there is none. */
+  name: string
+}
+
+/**
+ * Split one id into its ordering keys.
+ * @param id - the gateway model id exactly as configured.
+ * @returns folded keys; the caller compares them, never displays them.
+ */
+export function modelSortKey(id: string): ModelSortKey {
+  const slash = id.lastIndexOf('/')
+  if (slash === -1) {
+    const folded = id.toLowerCase()
+    return { group: folded, name: folded }
+  }
+  return { group: id.slice(0, slash).toLowerCase(), name: id.slice(slash + 1).toLowerCase() }
+}
+
+/**
+ * Compare two ids in display order.
+ * @param left - first id.
+ * @param right - second id.
+ * @returns negative when `left` sorts first, positive when `right` does.
+ */
+export function compareModelIds(left: string, right: string): number {
+  const a = modelSortKey(left)
+  const b = modelSortKey(right)
+  if (a.group !== b.group) return a.group < b.group ? -1 : 1
+  if (a.name !== b.name) return a.name < b.name ? -1 : 1
+  // Same folded pair: keep the raw spelling as the tie-break so the result is
+  // deterministic instead of depending on the input order.
+  if (left === right) return 0
+  return left < right ? -1 : 1
+}
+
+/**
+ * Return a sorted copy of a model list.
+ * @param items - entries in any order; the input array is never mutated.
+ * @param idOf - reads the model id out of one entry.
+ * @returns the entries in vendor-then-name order.
+ */
+export function sortByModelId<T>(items: readonly T[], idOf: (item: T) => string): T[] {
+  return [...items].sort((left, right) => compareModelIds(idOf(left), idOf(right)))
+}

package/src/types.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared vocabulary between the host half (catalog + matching) and the browser
+ * half (preview + write). Types only — nothing here runs.
+ * @module dsh-model-capability-sync/types
+ */
+
+/** Input modalities the DeepSeek Harness LLM seam understands. */
+export type Modality = 'text' | 'image'
+
+/**
+ * The capability fields this plugin can fill into one provider model entry.
+ * The names are the provider's own field names (pi-ai uses these exact ones),
+ * so a filled entry is written verbatim into the provider configuration.
+ *
+ * `name` is deliberately absent: this plugin fills facts, it never renames a
+ * model. A label is the user's (or the gateway's) choice, and rewriting it
+ * would be a surprise no capability edit justifies.
+ */
+export interface CapabilityFields {
+  /** Total request+response context capacity in tokens. */
+  contextWindow?: number
+  /** Per-request output cap in tokens. */
+  maxTokens?: number
+  /** Accepted input modalities, always including `text`. */
+  input?: Modality[]
+  /**
+   * Reasoning-effort map for providers that take a dict (`{ low: 'low' }`),
+   * or `false` when the catalog states the model cannot reason at all.
+   */
+  reasoningEfforts?: Record<string, string> | false
+}
+
+/** How a gateway id was matched against the catalog. */
+export type MatchVia = 'alias' | 'exact' | 'folded' | 'basename' | 'suffix'
+
+/** The catalog entry a gateway id resolved to. */
+export interface MatchInfo {
+  /** models.dev provider id the entry lives under (e.g. `openai`). */
+  provider: string
+  /** models.dev model id inside that provider. */
+  modelId: string
+  /** Which rule produced this match. */
+  via: MatchVia
+  /** True when the entry belongs to the model's first-party vendor, not a reseller. */
+  firstParty?: boolean
+  /** Human name from the catalog, when present. */
+  name?: string
+}
+
+/** One preview row: a configured model and what the catalog says about it. */
+export interface PreviewRow {
+  /** The gateway model id exactly as configured. */
+  id: string
+  match?: MatchInfo
+  fields?: CapabilityFields
+  /** Why no capability could be resolved, when `fields` is absent. */
+  reason?: string
+}
+
+/** Request payload of the `preview` RPC endpoint. */
+export interface PreviewRequest {
+  /** Gateway model ids to resolve, in display order. */
+  ids: string[]
+  /** Explicit gateway id → models.dev model id overrides, applied first. */
+  aliases?: Record<string, string>
+  /** Forward-proxy URL for the catalog download. */
+  proxyUrl?: string
+  /** Bypass the in-memory catalog cache. */
+  refresh?: boolean
+}
+
+/** Response payload of the `preview` RPC endpoint. */
+export interface PreviewResponse {
+  /** Epoch milliseconds of the catalog fetch backing this answer. */
+  fetchedAt: number
+  /** Number of models in the downloaded catalog. */
+  catalogModels: number
+  /** True when the catalog came from the local copy because the download failed. */
+  stale?: boolean
+  /** One row per requested id, in request order. */
+  rows: PreviewRow[]
+}
+
+/** Envelope every RPC endpoint answers with. */
+export type RpcEnvelope<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: { code: string; message: string; details?: Record<string, unknown> } }
+
+/**
+ * What the harness resolves for one model id right now, read from the adapter
+ * that actually owns the route. This is the truth a chat request sees, which
+ * is not necessarily the configuration this plugin writes: two plugins may
+ * claim the same provider route, and only one of them serves it.
+ */
+export interface LiveRow {
+  /** The model id as configured. */
+  id: string
+  /** Input modalities the owning adapter reports, when it reports any. */
+  input?: string[]
+  /** Context window the owning adapter reports. */
+  contextWindow?: number
+  /** Default output cap the owning adapter reports. */
+  maxTokens?: number
+  /** Why the live lookup failed, when it did. */
+  error?: string
+}
+
+/** Request payload of the `live` RPC endpoint. */
+export interface LiveRequest {
+  /** Provider route to inspect (the key inside `providers`). */
+  provider: string
+  /** Model ids to resolve through the owning adapter. */
+  ids: string[]
+}
+
+/** Response payload of the `live` RPC endpoint. */
+export interface LiveResponse {
+  /** One row per requested id, in request order. */
+  rows: LiveRow[]
+}