@heventure/model-provider-x 0.2.4 → 0.2.5

package/README.md

@@ -135,6 +135,61 @@ node dist/cli/index.js setup --target codex --provider lmstudio --proxy
 node dist/cli/index.js setup --target opencode --provider lmstudio --direct
 ```
 
+## Model Metadata Registry
+
+Some OpenAI-compatible providers only return minimal `/v1/models` entries with `id`, `object`, and `owned_by`.
+For those providers, `model-provider-x` can enrich model capabilities from registries.
+
+The merge order is:
+
+1. User overrides such as `--modalities`.
+2. Provider or native runtime metadata.
+3. Project-local registry overrides.
+4. Built-in models.dev metadata (5000+ models from 140+ providers).
+5. Conservative model-name heuristics.
+
+By default, the CLI reads `model-provider-x.models.jsonc` from the current working directory when it exists.
+You can also pass one or more registry files explicitly:
+
+```bash
+node dist/cli/index.js setup \
+  --provider custom \
+  --model-registry ./model-provider-x.models.jsonc
+```
+
+Example registry:
+
+```jsonc
+{
+  "providers": {
+    "mimo-pool": {
+      "models": {
+        "mimo-v2.5-tts": {
+          "type": "tts",
+          "modalities": {
+            "input": ["text"],
+            "output": ["audio"]
+          },
+          "limit": {
+            "context": 8192
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Updating Models.dev Data
+
+The built-in models.dev data is bundled with the package. To update it to the latest version:
+
+```bash
+npm run update-models-dev
+```
+
+This fetches the latest model metadata from [models.dev](https://models.dev) and updates `src/data/models-dev.json`.
+
 ## Commands
 
 ```bash

package/dist/cli/args.js

@@ -29,6 +29,12 @@ export function parseCliArgs(argv) {
                     .map((model) => model.trim())
                     .filter(Boolean);
                 break;
+            case "--model-registry":
+                if (!options.modelRegistryPaths) {
+                    options.modelRegistryPaths = [];
+                }
+                options.modelRegistryPaths.push(next());
+                break;
             case "--modalities":
                 if (!options.modalities) {
                     options.modalities = [];
@@ -113,6 +119,8 @@ Options:
   --proxy              Write agent config through the local compatibility proxy.
   --direct             Write agent config directly to the upstream provider.
   --models <list>      Comma-separated model ids. Skips interactive model selection.
+  --model-registry <path>
+                       JSONC model metadata override. Can be repeated.
   --modalities <spec>  Model modalities in format <model>:<input>:<output>.
                        Example: --modalities qwen-vl:image,text:text
   --config <path>      OpenCode config path to write when targeting OpenCode.

package/dist/cli/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { createInterface } from "node:readline/promises";
+import { existsSync } from "node:fs";
 import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
 import { readProxyStatus, startProxyProcess, stopProxyProcess } from "../core/proxy-process.js";
 import { createProxyAuthToken, getDefaultToolConfigPath, readToolConfig, upsertProviderProfile, writeToolConfig } from "../core/tool-config.js";
 import { discoverOpenCodeConfigs, getDefaultConfigPath, writeProviderToConfig } from "../core/config.js";
 import { buildProviderConfig, detectProviderCapabilities, recommendProxyMode, validateAndFetchModels } from "../core/provider.js";
+import { DEFAULT_MODEL_REGISTRY_FILE } from "../core/model-registry.js";
 import { isKnownModel } from "../core/model-capabilities.js";
 import { startProxyServer } from "../proxy/server.js";
 import { defaultClaudeModelMapping, getDefaultClaudeSettingsPath, writeClaudeCodeSettings } from "../targets/claude-code.js";
@@ -72,12 +74,17 @@ export async function runCli(options) {
         const baseURL = await requiredOption(rl, options.baseURL ?? providerDefaults.baseURL, "API base URL");
         const apiKey = await resolveApiKey(rl, options.apiKey, providerDefaults.preset);
         output.write("Fetching models...\n");
-        const fetched = await validateAndFetchModels({ baseURL, apiKey });
+        const fetched = await validateAndFetchModels({
+            baseURL,
+            apiKey,
+            providerId,
+            modelRegistryPaths: resolveModelRegistryPaths(options)
+        });
         const selectedModels = options.models ??
             (canUseTui()
-                ? await multiSelectChoices("Select models", createModelChoices(fetched.models))
+                ? await multiSelectChoices("Select models", createModelChoices(fetched.modelDetails))
                 : parseModelSelection(await rl.question(formatModelPrompt(fetched.models)), fetched.models));
-        const modelDetails = fetched.modelDetails.filter((m) => selectedModels.includes(m.id));
+        const modelDetails = applyModelModalityOverrides(fetched.modelDetails.filter((m) => selectedModels.includes(m.id)), options);
         const fragment = buildProviderConfig({
             providerId,
             providerName,
@@ -145,10 +152,15 @@ async function collectProviderInput(rl, command) {
 }
 async function collectProviderSelection(rl, command, providerInput) {
     output.write("Fetching models...\n");
-    const fetched = await validateAndFetchModels({ baseURL: providerInput.baseURL, apiKey: providerInput.apiKey });
+    const fetched = await validateAndFetchModels({
+        baseURL: providerInput.baseURL,
+        apiKey: providerInput.apiKey,
+        providerId: providerInput.providerId,
+        modelRegistryPaths: resolveModelRegistryPaths(command.options)
+    });
     const selectedModels = command.options.models ??
         (canUseTui()
-            ? await multiSelectChoices("Select models", createModelChoices(fetched.models))
+            ? await multiSelectChoices("Select models", createModelChoices(fetched.modelDetails))
             : parseModelSelection(await rl.question(formatModelPrompt(fetched.models)), fetched.models));
     const defaultModel = await resolveDefaultModel(rl, command, selectedModels);
     if (!defaultModel) {
@@ -372,6 +384,30 @@ function tokenHint(token) {
     }
     return `${token.slice(0, 8)}...${token.slice(-4)}`;
 }
+function resolveModelRegistryPaths(options) {
+    const paths = [...(options.modelRegistryPaths ?? [])];
+    if (existsSync(DEFAULT_MODEL_REGISTRY_FILE) && !paths.includes(DEFAULT_MODEL_REGISTRY_FILE)) {
+        paths.push(DEFAULT_MODEL_REGISTRY_FILE);
+    }
+    return paths;
+}
+function applyModelModalityOverrides(modelDetails, options) {
+    if (!options.modalities?.length) {
+        return modelDetails;
+    }
+    const overrides = new Map(options.modalities.map((override) => [override.modelId, override.modalities]));
+    return modelDetails.map((model) => {
+        const modalities = overrides.get(model.id);
+        if (!modalities) {
+            return model;
+        }
+        return {
+            ...model,
+            modalities,
+            metadataSources: [...new Set([...(model.metadataSources ?? []), "user"])]
+        };
+    });
+}
 async function requiredOption(rl, value, label) {
     const answer = value ?? (await rl.question(`${label}: `));
     if (!answer.trim()) {
@@ -671,14 +707,14 @@ async function resolveModelModalities(rl, command, selectedModels, fetchedModelD
 async function promptModelModalities(rl, modelId) {
     output.write(`\nModel: ${modelId} - Capabilities unknown\n`);
     if (canUseTui()) {
-        const inputModalities = await multiSelectChoices("Input modalities", [
+        const inputModalities = await multiSelectChoices(`Input modalities: ${modelId}`, [
             { label: "text", value: "text", hint: "default" },
             { label: "image", value: "image" },
             { label: "audio", value: "audio" },
             { label: "video", value: "video" },
             { label: "pdf", value: "pdf" },
         ]);
-        const outputModalities = await multiSelectChoices("Output modalities", [
+        const outputModalities = await multiSelectChoices(`Output modalities: ${modelId}`, [
             { label: "text", value: "text", hint: "default" },
             { label: "image", value: "image" },
             { label: "audio", value: "audio" },

package/dist/cli/model-choices.js

@@ -1,17 +1,49 @@
 const likelyUnsupportedModelName = /\b(?:embed|embedding|embeddings|bge|e5|nomic-embed)\b/i;
 export function createModelChoices(models) {
     return models.map((model) => {
-        if (!isLikelyUnsupportedModelName(model)) {
-            return { label: model, value: model, selected: true };
+        const info = typeof model === "string" ? { id: model } : model;
+        const unsupported = isLikelyUnsupportedModel(info);
+        const hint = modelHint(info, unsupported);
+        if (!unsupported) {
+            return modelChoice(info.id, hint, true);
         }
-        return {
-            label: model,
-            value: model,
-            hint: "suspected unsupported model",
-            selected: false
-        };
+        return modelChoice(info.id, hint, false);
     });
 }
 export function isLikelyUnsupportedModelName(model) {
     return likelyUnsupportedModelName.test(model);
 }
+function isLikelyUnsupportedModel(model) {
+    return model.type === "embedding" || isLikelyUnsupportedModelName(model.id);
+}
+function modelHint(model, unsupported) {
+    const hints = [
+        model.type,
+        model.architecture,
+        model.quantization,
+        model.contextLength ? `${formatContextLength(model.contextLength)} ctx` : undefined,
+        model.modalities?.input?.includes("image") ? "vision" : undefined,
+        model.capabilities?.toolCall ? "tools" : undefined,
+        model.capabilities?.reasoning ? "reasoning" : undefined,
+        model.state && model.state !== "loaded" ? model.state : undefined,
+        unsupported ? "suspected unsupported model" : undefined
+    ].filter((hint) => Boolean(hint));
+    return hints.length ? hints.join(", ") : undefined;
+}
+function formatContextLength(value) {
+    if (value >= 1000 && value % 1000 === 0) {
+        return `${value / 1000}k`;
+    }
+    if (value >= 1024 && value % 1024 === 0) {
+        return `${value / 1024}k`;
+    }
+    return String(value);
+}
+function modelChoice(modelId, hint, selected) {
+    return {
+        label: modelId,
+        value: modelId,
+        ...(hint ? { hint } : {}),
+        selected
+    };
+}

package/dist/core/model-capabilities.js

@@ -113,12 +113,15 @@ export function parseCapabilitiesFromApi(model) {
     if (model.capabilities && typeof model.capabilities === "object") {
         const caps = model.capabilities;
         const input = ["text"];
-        if (caps.vision || caps.image || caps.multimodal) {
+        if (caps.vision || caps.image || caps.multimodal || caps.image_input) {
             input.push("image");
         }
         if (caps.audio || caps.speech) {
             input.push("audio");
         }
+        if (caps.video) {
+            input.push("video");
+        }
         if (input.length > 1) {
             return { input: input, output: ["text"] };
         }

package/dist/core/model-registry.js

@@ -0,0 +1,231 @@
+import { readFile } from "node:fs/promises";
+import { parse } from "jsonc-parser";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+export const DEFAULT_MODEL_REGISTRY_FILE = "model-provider-x.models.jsonc";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MODELS_DEV_DATA_PATH = resolve(__dirname, "../data/models-dev.json");
+let modelsDevCache = null;
+async function loadModelsDevRegistry() {
+    if (modelsDevCache) {
+        return modelsDevCache;
+    }
+    try {
+        const text = await readFile(MODELS_DEV_DATA_PATH, "utf-8");
+        const data = JSON.parse(text);
+        modelsDevCache = {
+            source: data.source ?? "models-dev",
+            providers: data.providers
+        };
+        return modelsDevCache;
+    }
+    catch {
+        return { source: "models-dev", providers: {} };
+    }
+}
+export async function loadModelRegistryFile(path) {
+    const text = await readFile(path, "utf8");
+    const value = parse(text);
+    if (!isObject(value)) {
+        throw new Error(`Model registry must be an object: ${path}`);
+    }
+    return normalizeRegistry(value, "local-registry");
+}
+export async function resolveModelRegistryMetadata(input) {
+    const builtInRegistry = input.includeBuiltIn === false ? undefined : await loadModelsDevRegistry();
+    const registries = [
+        ...(builtInRegistry ? [builtInRegistry] : []),
+        ...(input.registries ?? [])
+    ];
+    let result;
+    for (const registry of registries) {
+        const model = lookupRegistryModel(registry, input.providerId, input.modelId);
+        if (!model) {
+            continue;
+        }
+        const info = normalizeRegistryModel(input.modelId, model, registry.source);
+        result = result ? mergeRegistryInfo(result, info) : info;
+    }
+    return result;
+}
+function normalizeRegistry(value, fallbackSource) {
+    return {
+        source: stringValue(value.source) ?? fallbackSource,
+        providers: normalizeProviders(value.providers),
+        models: normalizeModels(value.models)
+    };
+}
+function lookupRegistryModel(registry, providerId, modelId) {
+    const aliases = modelAliases(modelId);
+    // First try the specified provider
+    if (providerId) {
+        const providerModels = registry.providers?.[providerId]?.models;
+        const match = lookupModel(providerModels, aliases);
+        if (match) {
+            return match;
+        }
+        const modelsDevProvider = registry[providerId];
+        if (isObject(modelsDevProvider)) {
+            const provider = normalizeProviders({ [providerId]: modelsDevProvider })?.[providerId];
+            const providerMatch = lookupModel(provider?.models, aliases);
+            if (providerMatch) {
+                return providerMatch;
+            }
+        }
+    }
+    // Search across all providers if not found in specified provider
+    if (registry.providers) {
+        for (const [, provider] of Object.entries(registry.providers)) {
+            const match = lookupModel(provider.models, aliases);
+            if (match) {
+                return match;
+            }
+        }
+    }
+    return lookupModel(registry.models, aliases);
+}
+function lookupModel(models, aliases) {
+    if (!models) {
+        return undefined;
+    }
+    for (const alias of aliases) {
+        if (models[alias]) {
+            return models[alias];
+        }
+    }
+    return undefined;
+}
+function normalizeRegistryModel(modelId, model, source) {
+    const modalities = normalizeModalities(model);
+    const capabilities = model.capabilities;
+    const toolCall = booleanValue(capabilities?.toolCall ?? capabilities?.tool_call ?? model.tool_call);
+    const reasoning = booleanValue(capabilities?.reasoning ?? model.reasoning);
+    return cleanModelInfo({
+        id: model.id ?? modelId,
+        type: model.type,
+        architecture: model.architecture,
+        quantization: model.quantization,
+        parameterSize: model.parameterSize,
+        state: model.state,
+        contextLength: model.contextLength ?? model.limit?.context,
+        modalities,
+        capabilities: toolCall || reasoning ? { toolCall, reasoning } : undefined,
+        metadataSources: [source]
+    });
+}
+function normalizeModalities(model) {
+    if (model.modalities) {
+        return model.modalities;
+    }
+    if (model.input_modalities || model.output_modalities) {
+        return {
+            ...(model.input_modalities ? { input: model.input_modalities } : {}),
+            ...(model.output_modalities ? { output: model.output_modalities } : {})
+        };
+    }
+    return undefined;
+}
+function mergeRegistryInfo(base, next) {
+    return cleanModelInfo({
+        ...base,
+        ...next,
+        id: base.id || next.id,
+        type: next.type ?? base.type,
+        architecture: next.architecture ?? base.architecture,
+        quantization: next.quantization ?? base.quantization,
+        parameterSize: next.parameterSize ?? base.parameterSize,
+        state: next.state ?? base.state,
+        contextLength: next.contextLength ?? base.contextLength,
+        modalities: next.modalities ?? base.modalities,
+        capabilities: base.capabilities || next.capabilities
+            ? {
+                ...base.capabilities,
+                ...next.capabilities
+            }
+            : undefined,
+        metadataSources: [...new Set([...(base.metadataSources ?? []), ...(next.metadataSources ?? [])])]
+    });
+}
+function normalizeProviders(value) {
+    if (!isObject(value)) {
+        return undefined;
+    }
+    const providers = {};
+    for (const [providerId, providerValue] of Object.entries(value)) {
+        if (!isObject(providerValue)) {
+            continue;
+        }
+        const models = normalizeModels(providerValue.models);
+        if (models) {
+            providers[providerId] = { models };
+        }
+    }
+    return Object.keys(providers).length ? providers : undefined;
+}
+function normalizeModels(value) {
+    if (!isObject(value)) {
+        return undefined;
+    }
+    const models = {};
+    for (const [modelId, modelValue] of Object.entries(value)) {
+        if (isObject(modelValue)) {
+            models[modelId] = modelValue;
+        }
+    }
+    return Object.keys(models).length ? models : undefined;
+}
+function modelAliases(modelId) {
+    const normalized = modelId.trim().toLowerCase();
+    const withoutPrefix = normalized.includes("/") ? normalized.split("/").pop() : normalized;
+    // Strip common suffixes for fuzzy matching
+    const suffixes = [
+        "-it", "-qat", "-instruct", "-chat", "-gguf", "-gptq", "-awq", "-exl2",
+        "-fp16", "-fp32", "-int4", "-int8", "-4bit", "-8bit", "-16bit",
+        "-preview", "-latest", "-beta", "-alpha", "-rc", "-snapshot",
+        "-mlx", "-mlxc", "-bnb", "-hqq",
+        "-ud", "-xl", "-xs", "-small", "-medium", "-large", "-mini", "-nano", "-micro",
+        "-turbo", "-fast", "-pro", "-plus", "-max", "-ultra", "-flash", "-lite",
+        "-mtp", "-moe", "-a17b", "-a22b", "-a3b", "-a10b", "-a12b", "-a55b",
+        "-chat", "-base", "-raw", "-uncensored", "-abliterated"
+    ];
+    let fuzzy = withoutPrefix;
+    for (const suffix of suffixes) {
+        if (fuzzy.endsWith(suffix)) {
+            fuzzy = fuzzy.slice(0, -suffix.length);
+            break;
+        }
+    }
+    // Also try removing version suffixes like "-v1", "-v2", etc.
+    const versionMatch = fuzzy.match(/-v\d+$/);
+    const withoutVersion = versionMatch ? fuzzy.slice(0, -versionMatch[0].length) : fuzzy;
+    // Try removing parameter size suffixes like "-12b", "-7b", "-70b", etc.
+    const paramMatch = fuzzy.match(/-\d+[bBmMkKtT]$/);
+    const withoutParams = paramMatch ? fuzzy.slice(0, -paramMatch[0].length) : fuzzy;
+    return [...new Set([normalized, withoutPrefix, fuzzy, withoutVersion, withoutParams])];
+}
+function cleanModelInfo(model) {
+    const capabilities = model.capabilities?.toolCall || model.capabilities?.reasoning
+        ? model.capabilities
+        : undefined;
+    return {
+        id: model.id,
+        ...(model.type ? { type: model.type } : {}),
+        ...(model.architecture ? { architecture: model.architecture } : {}),
+        ...(model.quantization ? { quantization: model.quantization } : {}),
+        ...(model.parameterSize ? { parameterSize: model.parameterSize } : {}),
+        ...(model.state ? { state: model.state } : {}),
+        ...(model.contextLength ? { contextLength: model.contextLength } : {}),
+        ...(model.modalities ? { modalities: model.modalities } : {}),
+        ...(capabilities ? { capabilities } : {}),
+        ...(model.metadataSources?.length ? { metadataSources: model.metadataSources } : {})
+    };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}