feat: add formatModelNames option to keep raw model ids in the picker

CHANGELOG.md

@@ -1,3 +1,9 @@
+## [Unreleased]
+
+### Features
+
+* add `formatModelNames` option to keep raw model ids in the picker
+
 # [1.2.0](https://github.com/yuseferi/opencode-litellm/compare/v1.1.0...v1.2.0) (2026-09-13)
 
 

README.md

@@ -71,7 +71,7 @@ opencode
 | 🔍 **Auto-detection** | Probes `localhost:4000`, `:8000`, `:8080` and adopts the first responsive proxy. |
 | 📡 **Dynamic discovery** | Queries `/v1/models` so your OpenCode model picker always reflects your live `model_list`. |
 | ⚡ **Instant startup (SWR)** | Discovered models are cached on disk and loaded synchronously — startup never blocks on the network. A background refresh on new sessions keeps the cache fresh; entries expire after 7 days. |
-| 🏷️ **Smart formatting** | Turns `anthropic/claude-3-5-sonnet` into `Claude 3.5 Sonnet` in the picker — handles versions, sizes, quantizations, and brand-cased names like `gpt-4o`. |
+| 🏷️ **Smart formatting** | Turns `anthropic/claude-3-5-sonnet` into `Claude 3.5 Sonnet` in the picker — handles versions, sizes, quantizations, and brand-cased names like `gpt-4o`. Set `formatModelNames: false` to keep the raw LiteLLM ids instead. |
 | 🧠 **Modality-aware** | Enriches `/v1/models` entries with `/v1/model/info` (`mode`, token limits, capability flags) and hides embedding / image / audio models from the picker. |
 | 💵 **Real pricing** | Maps `input_cost_per_token` / `output_cost_per_token` (and cache read/write costs) from `/v1/model/info` into OpenCode's `cost` field, so the picker and `/cost` show what the proxy actually bills instead of `$0.00`. Models LiteLLM has no price for are left unpriced, not falsely marked free. |
 | 🧩 **Reasoning-effort variants** | When LiteLLM reports per-model effort support (`supports_low_reasoning_effort`, …), the plugin surfaces each level as a picker variant automatically. |
@@ -306,6 +306,28 @@ Model classification (tool-call badge, attachments, reasoning, input modalities)
 - Overridden flags flow into the picker exactly like natively reported ones, and the adjusted view is what gets persisted to the model cache.
 - Changing `modelCapabilities` (or `includeModels`/`excludeModels`) starts a fresh discovery on the next start — the cache is scoped by that config — so the picker reflects the new flags immediately.
 
+### Keeping raw model ids in the picker (`formatModelNames`)
+
+By default the plugin prettifies each discovered id into a display name — `anthropic/claude-3-5-sonnet` shows up as `Claude 3.5 Sonnet`. If you'd rather see your LiteLLM `model_list` aliases verbatim (for example because your team refers to models by those exact names, or the formatter mangles an internal naming scheme), turn formatting off:
+
+```jsonc
+{
+  "provider": {
+    "litellm": {
+      "options": {
+        "baseURL": "http://localhost:4000/v1",
+        "formatModelNames": false
+      }
+    }
+  }
+}
+```
+
+- The display name becomes the exact model id as returned by `/v1/models` (provider prefix, version suffixes and all). Nothing else changes — ids, capability flags, pricing and filtering behave exactly as before.
+- Only a boolean `false` disables formatting; omitting the option or setting anything else keeps the default.
+- Like the other options above, `formatModelNames` is part of the cache identity, so toggling it triggers a fresh discovery on the next start instead of serving previously cached names.
+- To rename just a handful of models while keeping smart formatting for the rest, use the per-model `name` override described in [Overriding or curating individual models](#overriding-or-curating-individual-models-optional).
+
 ## 🔧 How it works
 
 ```mermaid
@@ -485,7 +507,7 @@ src/
 │   ├── model-capabilities.ts   # per-model capability flag overrides
 │   └── opencode-auth.ts        # fallback to OpenCode's /connect-stored credentials
 └── plugin/
-    └── index.ts                # LiteLLMPlugin entry (config hook, enrichment, filtering, capability overrides)
+    └── index.ts                # LiteLLMPlugin entry (config hook, enrichment, filtering, capability overrides, naming)
 
 test/                           # vitest suite for the pure logic
 ```

src/plugin/index.ts

@@ -81,6 +81,7 @@ interface RefreshContext {
   customHeaders?: Record<string, string>
   filters: ModelFilters
   capabilities: ModelCapabilities
+  formatModelNames: boolean
   providerId: string
 }
 const refreshContexts = new Map<string, RefreshContext>()
@@ -156,6 +157,10 @@ function readModelFilters(options: Record<string, unknown>): ModelFilters {
   }
 }
 
+function readFormatModelNames(options: Record<string, unknown>): boolean {
+  return options.formatModelNames !== false
+}
+
 /**
  * Overlay metadata onto a `/v1/models` entry in three tiers: the entry's
  * own fields win, `/v1/model/info` fills gaps (notably `mode`, which
@@ -211,13 +216,14 @@ const USD_PER_TOKEN_TO_PER_MILLION = 1_000_000
 function toConfigModel(
   model: LiteLLMModel,
   info?: LiteLLMModelInfo,
+  formatModelNames = true,
 ): Record<string, unknown> | null {
   const type = categorizeModel(model)
   if (type === 'embedding' || type === 'image' || type === 'audio') {
     return null
   }
   const entry: Record<string, unknown> = {
-    name: formatModelName(model),
+    name: formatModelNames ? formatModelName(model) : model.id,
   }
   // Some deployments only report the OpenAI-style `max_tokens` total;
   // use it as the context limit when `max_input_tokens` is absent.
@@ -277,10 +283,11 @@ function toConfigModel(
  *
  * Pure with respect to plugin config: it performs the network calls,
  * classifies + formats each model, and returns a `{ id -> entry }` map.
- * The provider's `includeModels`/`excludeModels` filters and
- * `modelCapabilities` overrides are applied here (not at merge time) so
- * every path that persists or serves a cache — cold discovery and
- * background refresh — writes the same adjusted view.
+ * The provider's `includeModels`/`excludeModels` filters,
+ * `modelCapabilities` overrides and `formatModelNames` choice are
+ * applied here (not at merge time) so every path that persists or
+ * serves a cache — cold discovery and background refresh — writes the
+ * same adjusted view.
  *
  * Returns `null` when the proxy is unreachable/unauthorized or exposes
  * no models, so callers can distinguish "no data" from "empty result".
@@ -292,6 +299,7 @@ async function discoverModels(
   providerId: string,
   filters: ModelFilters = {},
   capabilities: ModelCapabilities = {},
+  formatModelNames = true,
 ): Promise<Record<string, unknown> | null> {
   if (!(await checkLiteLLMHealth(baseURL, apiKey, customHeaders))) {
     log(
@@ -363,7 +371,11 @@ async function discoverModels(
     }
     const info = infoByName?.get(model.id)
     if (infoByName && !info) unmatched.push(model.id)
-    const entry = toConfigModel(enrichModel(model, info, capabilities[model.id]), info)
+    const entry = toConfigModel(
+      enrichModel(model, info, capabilities[model.id]),
+      info,
+      formatModelNames,
+    )
     if (!entry) {
       skipped++
       continue
@@ -451,6 +463,7 @@ async function backgroundRefresh(cacheKey: string): Promise<void> {
         ctx.providerId,
         ctx.filters,
         ctx.capabilities,
+        ctx.formatModelNames,
       ),
       DISCOVERY_TIMEOUT_MS,
     )
@@ -553,6 +566,7 @@ export const LiteLLMPlugin: Plugin = async (input: PluginInput) => {
         const customHeaders = readCustomHeaders(options)
         const filters = readModelFilters(options)
         const capabilities = parseModelCapabilities(options.modelCapabilities)
+        const formatModelNames = readFormatModelNames(options)
 
         // Resolve base URL
         let baseURL: string | null = null
@@ -608,10 +622,12 @@ export const LiteLLMPlugin: Plugin = async (input: PluginInput) => {
 
         const models = actualProvider.models as Record<string, unknown>
 
-        // Identity includes the filter/capability config: those are
-        // baked into cached entries, so changing them must start a
+        // Identity includes the filter/capability/naming config: those
+        // are baked into cached entries, so changing them must start a
         // fresh discovery instead of serving the old adjusted view.
-        const cacheKey = buildCacheKey(providerId, baseURL, filters, capabilities)
+        const cacheKey = buildCacheKey(providerId, baseURL, filters, capabilities, {
+          formatModelNames,
+        })
 
         // Remember how to reach this proxy so the `event` hook can
         // revalidate its cache in the background on new sessions.
@@ -621,6 +637,7 @@ export const LiteLLMPlugin: Plugin = async (input: PluginInput) => {
           customHeaders,
           filters,
           capabilities,
+          formatModelNames,
           providerId,
         })
 
@@ -654,7 +671,15 @@ export const LiteLLMPlugin: Plugin = async (input: PluginInput) => {
         // persist for subsequent startups. Capped by a timeout so a slow
         // proxy never blocks boot.
         const built = await withTimeout(
-          discoverModels(baseURL, apiKey, customHeaders, providerId, filters, capabilities),
+          discoverModels(
+            baseURL,
+            apiKey,
+            customHeaders,
+            providerId,
+            filters,
+            capabilities,
+            formatModelNames,
+          ),
           DISCOVERY_TIMEOUT_MS,
         )
         if (built && Object.keys(built).length > 0) {

src/utils/model-cache.ts

@@ -65,32 +65,38 @@ function canonicalize(value: unknown): string {
 
 /**
  * Cache identity for a provider's model view. `providerId@baseURL`
- * alone isn't enough: `includeModels`/`excludeModels` and
- * `modelCapabilities` are baked into cached entries by discovery, so a
- * config change must not reuse the old cache — it would keep serving
- * the previous adjusted view until a second restart. A fingerprint is
- * appended whenever adjustments exist (pattern order ignored); default
- * configs keep the plain key so existing caches stay warm across
- * plugin upgrades.
+ * alone isn't enough: `includeModels`/`excludeModels`,
+ * `modelCapabilities` and `formatModelNames` are baked into cached
+ * entries by discovery, so a config change must not reuse the old cache
+ * — it would keep serving the previous adjusted view until a second
+ * restart. A fingerprint is appended whenever adjustments exist
+ * (pattern order ignored); default configs keep the plain key so
+ * existing caches stay warm across plugin upgrades.
  */
 export function buildCacheKey(
   providerId: string,
   baseURL: string,
   filters: { includeModels?: string[]; excludeModels?: string[] },
   capabilities: Record<string, Record<string, boolean>>,
+  naming: { formatModelNames?: boolean } = {},
 ): string {
   const base = `${providerId}@${baseURL}`
+  const rawNames = naming.formatModelNames === false
   const hasAdjustments =
     (filters.includeModels?.length ?? 0) > 0 ||
     (filters.excludeModels?.length ?? 0) > 0 ||
-    Object.keys(capabilities).length > 0
+    Object.keys(capabilities).length > 0 ||
+    rawNames
   if (!hasAdjustments) return base
   const fingerprint = createHash('sha256')
     .update(
       canonicalize({
         includeModels: filters.includeModels ? [...filters.includeModels].sort() : undefined,
         excludeModels: filters.excludeModels ? [...filters.excludeModels].sort() : undefined,
         capabilities,
+        // Omitted (not `true`) when formatting is on, so keys for
+        // configs that never touch this option are unchanged.
+        formatModelNames: rawNames ? false : undefined,
       }),
     )
     .digest('hex')

test/model-cache.test.ts

@@ -120,6 +120,37 @@ describe('buildCacheKey', () => {
     expect(visionOn.startsWith(base)).toBe(true)
   })
 
+  it('keeps the plain key when formatModelNames is left at its default (true)', () => {
+    expect(
+      buildCacheKey('litellm', 'http://localhost:4000', {}, {}, { formatModelNames: true }),
+    ).toBe(KEY)
+    expect(buildCacheKey('litellm', 'http://localhost:4000', {}, {}, {})).toBe(KEY)
+  })
+
+  it('changes the key when formatModelNames is turned off', () => {
+    // Display names are baked into cached entries, so flipping the
+    // option must not serve the previously formatted (or raw) names.
+    const plain = buildCacheKey('litellm', 'http://localhost:4000', {}, {})
+    const raw = buildCacheKey('litellm', 'http://localhost:4000', {}, {}, { formatModelNames: false })
+    expect(raw).not.toBe(plain)
+    expect(raw.startsWith(KEY)).toBe(true)
+    // ...and is orthogonal to the other adjustments.
+    const rawWithFilters = buildCacheKey(
+      'litellm',
+      'http://localhost:4000',
+      { includeModels: ['prod/*'] },
+      {},
+      { formatModelNames: false },
+    )
+    const formattedWithFilters = buildCacheKey(
+      'litellm',
+      'http://localhost:4000',
+      { includeModels: ['prod/*'] },
+      {},
+    )
+    expect(rawWithFilters).not.toBe(formattedWithFilters)
+  })
+
   it('changes the key when includeModels/excludeModels are added', () => {
     const plain = buildCacheKey('litellm', 'http://localhost:4000', {}, {})
     const withFilters = buildCacheKey(