refactor: move provider model helpers into plugins

This commit is contained in:
Peter Steinberger
2026-03-27 20:16:35 +00:00
parent 5d3d54ee36
commit c28e76c490
94 changed files with 3455 additions and 611 deletions

View File

@@ -1,44 +1,8 @@
import type { ModelDefinitionConfig } from "../config/types.js";
export const CLOUDFLARE_AI_GATEWAY_PROVIDER_ID = "cloudflare-ai-gateway";
export const CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_ID = "claude-sonnet-4-5";
export const CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_REF = `${CLOUDFLARE_AI_GATEWAY_PROVIDER_ID}/${CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_ID}`;
export const CLOUDFLARE_AI_GATEWAY_DEFAULT_CONTEXT_WINDOW = 200_000;
export const CLOUDFLARE_AI_GATEWAY_DEFAULT_MAX_TOKENS = 64_000;
export const CLOUDFLARE_AI_GATEWAY_DEFAULT_COST = {
input: 3,
output: 15,
cacheRead: 0.3,
cacheWrite: 3.75,
};
export function buildCloudflareAiGatewayModelDefinition(params?: {
id?: string;
name?: string;
reasoning?: boolean;
input?: Array<"text" | "image">;
}): ModelDefinitionConfig {
const id = params?.id?.trim() || CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_ID;
return {
id,
name: params?.name ?? "Claude Sonnet 4.5",
reasoning: params?.reasoning ?? true,
input: params?.input ?? ["text", "image"],
cost: CLOUDFLARE_AI_GATEWAY_DEFAULT_COST,
contextWindow: CLOUDFLARE_AI_GATEWAY_DEFAULT_CONTEXT_WINDOW,
maxTokens: CLOUDFLARE_AI_GATEWAY_DEFAULT_MAX_TOKENS,
};
}
export function resolveCloudflareAiGatewayBaseUrl(params: {
accountId: string;
gatewayId: string;
}): string {
const accountId = params.accountId.trim();
const gatewayId = params.gatewayId.trim();
if (!accountId || !gatewayId) {
return "";
}
return `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/anthropic`;
}
// Deprecated compat shim. Prefer openclaw/plugin-sdk/cloudflare-ai-gateway.
export {
buildCloudflareAiGatewayModelDefinition,
CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_ID,
CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_REF,
CLOUDFLARE_AI_GATEWAY_PROVIDER_ID,
resolveCloudflareAiGatewayBaseUrl,
} from "../plugin-sdk/cloudflare-ai-gateway.js";

View File

@@ -1,231 +1,9 @@
import type { ModelDefinitionConfig } from "../config/types.models.js";
import { createSubsystemLogger } from "../logging/subsystem.js";
import { isReasoningModelHeuristic } from "../plugin-sdk/provider-reasoning.js";
const log = createSubsystemLogger("huggingface-models");
/** Hugging Face Inference Providers (router) — OpenAI-compatible chat completions. */
export const HUGGINGFACE_BASE_URL = "https://router.huggingface.co/v1";
/** Router policy suffixes: router picks backend by cost or speed; no specific provider selection. */
export const HUGGINGFACE_POLICY_SUFFIXES = ["cheapest", "fastest"] as const;
/**
* True when the model ref uses :cheapest or :fastest. When true, provider choice is locked
* (router decides); do not show an interactive "prefer specific backend" option.
*/
export function isHuggingfacePolicyLocked(modelRef: string): boolean {
const ref = String(modelRef).trim();
return HUGGINGFACE_POLICY_SUFFIXES.some((s) => ref.endsWith(`:${s}`) || ref === s);
}
/** Default cost when not in static catalog (HF pricing varies by provider). */
const HUGGINGFACE_DEFAULT_COST = {
input: 0,
output: 0,
cacheRead: 0,
cacheWrite: 0,
};
/** Defaults for models discovered from GET /v1/models. */
const HUGGINGFACE_DEFAULT_CONTEXT_WINDOW = 131072;
const HUGGINGFACE_DEFAULT_MAX_TOKENS = 8192;
/**
* Shape of a single model entry from GET https://router.huggingface.co/v1/models.
* Aligned with the Inference Providers API response (object, data[].id, owned_by, architecture, providers).
*/
interface HFModelEntry {
id: string;
object?: string;
created?: number;
/** Organisation that owns the model (e.g. "Qwen", "deepseek-ai"). Used for display when name/title absent. */
owned_by?: string;
/** Display name from API when present (not all responses include this). */
name?: string;
title?: string;
display_name?: string;
/** Input/output modalities; we use input_modalities for ModelDefinitionConfig.input. */
architecture?: {
input_modalities?: string[];
output_modalities?: string[];
[key: string]: unknown;
};
/** Backend providers; we use the first provider with context_length when available. */
providers?: Array<{
provider?: string;
context_length?: number;
status?: string;
pricing?: { input?: number; output?: number; [key: string]: unknown };
[key: string]: unknown;
}>;
[key: string]: unknown;
}
/** Response shape from GET https://router.huggingface.co/v1/models (OpenAI-style list). */
interface OpenAIListModelsResponse {
object?: string;
data?: HFModelEntry[];
}
export const HUGGINGFACE_MODEL_CATALOG: ModelDefinitionConfig[] = [
{
id: "deepseek-ai/DeepSeek-R1",
name: "DeepSeek R1",
reasoning: true,
input: ["text"],
contextWindow: 131072,
maxTokens: 8192,
cost: { input: 3.0, output: 7.0, cacheRead: 3.0, cacheWrite: 3.0 },
},
{
id: "deepseek-ai/DeepSeek-V3.1",
name: "DeepSeek V3.1",
reasoning: false,
input: ["text"],
contextWindow: 131072,
maxTokens: 8192,
cost: { input: 0.6, output: 1.25, cacheRead: 0.6, cacheWrite: 0.6 },
},
{
id: "meta-llama/Llama-3.3-70B-Instruct-Turbo",
name: "Llama 3.3 70B Instruct Turbo",
reasoning: false,
input: ["text"],
contextWindow: 131072,
maxTokens: 8192,
cost: { input: 0.88, output: 0.88, cacheRead: 0.88, cacheWrite: 0.88 },
},
{
id: "openai/gpt-oss-120b",
name: "GPT-OSS 120B",
reasoning: false,
input: ["text"],
contextWindow: 131072,
maxTokens: 8192,
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
},
];
export function buildHuggingfaceModelDefinition(
model: (typeof HUGGINGFACE_MODEL_CATALOG)[number],
): ModelDefinitionConfig {
return {
id: model.id,
name: model.name,
reasoning: model.reasoning,
input: model.input,
cost: model.cost,
contextWindow: model.contextWindow,
maxTokens: model.maxTokens,
};
}
/**
* Infer reasoning and display name from Hub-style model id (e.g. "deepseek-ai/DeepSeek-R1").
*/
function inferredMetaFromModelId(id: string): { name: string; reasoning: boolean } {
const base = id.split("/").pop() ?? id;
const reasoning = isReasoningModelHeuristic(id);
const name = base.replace(/-/g, " ").replace(/\b(\w)/g, (c) => c.toUpperCase());
return { name, reasoning };
}
/** Prefer API-supplied display name, then owned_by/id, then inferred from id. */
function displayNameFromApiEntry(entry: HFModelEntry, inferredName: string): string {
const fromApi =
(typeof entry.name === "string" && entry.name.trim()) ||
(typeof entry.title === "string" && entry.title.trim()) ||
(typeof entry.display_name === "string" && entry.display_name.trim());
if (fromApi) {
return fromApi;
}
if (typeof entry.owned_by === "string" && entry.owned_by.trim()) {
const base = entry.id.split("/").pop() ?? entry.id;
return `${entry.owned_by.trim()}/${base}`;
}
return inferredName;
}
/**
* Discover chat-completion models from Hugging Face Inference Providers (GET /v1/models).
* Requires a valid HF token. Falls back to static catalog on failure or in test env.
*/
export async function discoverHuggingfaceModels(apiKey: string): Promise<ModelDefinitionConfig[]> {
if (process.env.VITEST === "true" || process.env.NODE_ENV === "test") {
return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
}
const trimmedKey = apiKey?.trim();
if (!trimmedKey) {
return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
}
try {
// GET https://router.huggingface.co/v1/models — response: { object, data: [{ id, owned_by, architecture: { input_modalities }, providers: [{ provider, context_length?, pricing? }] }] }. POST /v1/chat/completions requires Authorization.
const response = await fetch(`${HUGGINGFACE_BASE_URL}/models`, {
signal: AbortSignal.timeout(10_000),
headers: {
Authorization: `Bearer ${trimmedKey}`,
"Content-Type": "application/json",
},
});
if (!response.ok) {
log.warn(`GET /v1/models failed: HTTP ${response.status}, using static catalog`);
return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
}
const body = (await response.json()) as OpenAIListModelsResponse;
const data = body?.data;
if (!Array.isArray(data) || data.length === 0) {
log.warn("No models in response, using static catalog");
return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
}
const catalogById = new Map(HUGGINGFACE_MODEL_CATALOG.map((m) => [m.id, m] as const));
const seen = new Set<string>();
const models: ModelDefinitionConfig[] = [];
for (const entry of data) {
const id = typeof entry?.id === "string" ? entry.id.trim() : "";
if (!id || seen.has(id)) {
continue;
}
seen.add(id);
const catalogEntry = catalogById.get(id);
if (catalogEntry) {
models.push(buildHuggingfaceModelDefinition(catalogEntry));
} else {
const inferred = inferredMetaFromModelId(id);
const name = displayNameFromApiEntry(entry, inferred.name);
const modalities = entry.architecture?.input_modalities;
const input: Array<"text" | "image"> =
Array.isArray(modalities) && modalities.includes("image") ? ["text", "image"] : ["text"];
const providers = Array.isArray(entry.providers) ? entry.providers : [];
const providerWithContext = providers.find(
(p) => typeof p?.context_length === "number" && p.context_length > 0,
);
const contextLength =
providerWithContext?.context_length ?? HUGGINGFACE_DEFAULT_CONTEXT_WINDOW;
models.push({
id,
name,
reasoning: inferred.reasoning,
input,
cost: HUGGINGFACE_DEFAULT_COST,
contextWindow: contextLength,
maxTokens: HUGGINGFACE_DEFAULT_MAX_TOKENS,
});
}
}
return models.length > 0
? models
: HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
} catch (error) {
log.warn(`Discovery failed: ${String(error)}, using static catalog`);
return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
}
}
// Deprecated compat shim. Prefer openclaw/plugin-sdk/huggingface.
export {
buildHuggingfaceModelDefinition,
discoverHuggingfaceModels,
HUGGINGFACE_BASE_URL,
HUGGINGFACE_MODEL_CATALOG,
HUGGINGFACE_POLICY_SUFFIXES,
isHuggingfacePolicyLocked,
} from "../plugin-sdk/huggingface.js";

View File

@@ -24,14 +24,6 @@ vi.mock("../config/config.js", async (importOriginal) => {
};
});
vi.mock("../../extensions/telegram/api.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("../../extensions/telegram/api.js")>();
return {
...actual,
deleteTelegramUpdateOffset: offsetMocks.deleteTelegramUpdateOffset,
};
});
vi.mock("../../extensions/telegram/update-offset-runtime-api.js", async (importOriginal) => {
const actual =
await importOriginal<typeof import("../../extensions/telegram/update-offset-runtime-api.js")>();

View File

@@ -1,4 +1,4 @@
export {
applyGoogleGeminiModelDefault,
GOOGLE_GEMINI_DEFAULT_MODEL,
} from "../plugins/provider-model-defaults.js";
} from "../plugin-sdk/google.js";

View File

@@ -2,4 +2,4 @@ export {
applyOpenAIConfig,
applyOpenAIProviderConfig,
OPENAI_DEFAULT_MODEL,
} from "../plugins/provider-model-defaults.js";
} from "../plugin-sdk/openai.js";

View File

@@ -1,4 +1,4 @@
export {
applyOpencodeGoModelDefault,
OPENCODE_GO_DEFAULT_MODEL_REF,
} from "../plugins/provider-model-defaults.js";
} from "../plugin-sdk/opencode-go.js";

View File

@@ -1,4 +1,4 @@
export {
applyOpencodeZenModelDefault,
OPENCODE_ZEN_DEFAULT_MODEL,
} from "../plugins/provider-model-defaults.js";
} from "../plugin-sdk/opencode.js";

View File

@@ -0,0 +1,90 @@
import { describe, expect, it } from "vitest";
import type { OpenClawConfig } from "./config.js";
import {
listLegacyWebSearchConfigPaths,
migrateLegacyWebSearchConfig,
} from "./legacy-web-search.js";
describe("legacy web search config", () => {
it("migrates legacy provider config through bundled web search ownership metadata", () => {
const res = migrateLegacyWebSearchConfig<OpenClawConfig>({
tools: {
web: {
search: {
provider: "grok",
apiKey: "brave-key",
grok: {
apiKey: "xai-key",
model: "grok-4-search",
},
kimi: {
apiKey: "kimi-key",
model: "kimi-k2.5",
},
},
},
},
});
expect(res.config.tools?.web?.search).toEqual({
provider: "grok",
});
expect(res.config.plugins?.entries?.brave).toEqual({
enabled: true,
config: {
webSearch: {
apiKey: "brave-key",
},
},
});
expect(res.config.plugins?.entries?.xai).toEqual({
enabled: true,
config: {
webSearch: {
apiKey: "xai-key",
model: "grok-4-search",
},
},
});
expect(res.config.plugins?.entries?.moonshot).toEqual({
enabled: true,
config: {
webSearch: {
apiKey: "kimi-key",
model: "kimi-k2.5",
},
},
});
expect(res.changes).toEqual([
"Moved tools.web.search.apiKey → plugins.entries.brave.config.webSearch.apiKey.",
"Moved tools.web.search.grok → plugins.entries.xai.config.webSearch.",
"Moved tools.web.search.kimi → plugins.entries.moonshot.config.webSearch.",
]);
});
it("lists legacy paths for metadata-owned provider config", () => {
expect(
listLegacyWebSearchConfigPaths({
tools: {
web: {
search: {
apiKey: "brave-key",
grok: {
apiKey: "xai-key",
model: "grok-4-search",
},
kimi: {
model: "kimi-k2.5",
},
},
},
},
}),
).toEqual([
"tools.web.search.apiKey",
"tools.web.search.grok.apiKey",
"tools.web.search.grok.model",
"tools.web.search.kimi.model",
]);
});
});

View File

@@ -1,3 +1,4 @@
import { BUNDLED_WEB_SEARCH_PROVIDER_PLUGIN_IDS } from "../plugins/bundled-capability-metadata.js";
import type { OpenClawConfig } from "./config.js";
import { mergeMissing } from "./legacy.shared.js";
@@ -11,16 +12,10 @@ const GENERIC_WEB_SEARCH_KEYS = new Set([
"cacheTtlMinutes",
]);
const LEGACY_PROVIDER_MAP = {
brave: "brave",
firecrawl: "firecrawl",
gemini: "google",
grok: "xai",
kimi: "moonshot",
perplexity: "perplexity",
} as const;
type LegacyProviderId = keyof typeof LEGACY_PROVIDER_MAP;
const LEGACY_WEB_SEARCH_PROVIDER_PLUGIN_IDS = BUNDLED_WEB_SEARCH_PROVIDER_PLUGIN_IDS;
const LEGACY_WEB_SEARCH_PROVIDER_IDS = Object.keys(LEGACY_WEB_SEARCH_PROVIDER_PLUGIN_IDS);
const LEGACY_WEB_SEARCH_PROVIDER_ID_SET = new Set(LEGACY_WEB_SEARCH_PROVIDER_IDS);
const LEGACY_GLOBAL_WEB_SEARCH_PROVIDER_ID = "brave";
function isRecord(value: unknown): value is JsonRecord {
return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -49,10 +44,7 @@ function resolveLegacySearchConfig(raw: unknown): JsonRecord | undefined {
return isRecord(web?.search) ? web.search : undefined;
}
function copyLegacyProviderConfig(
search: JsonRecord,
providerKey: LegacyProviderId,
): JsonRecord | undefined {
function copyLegacyProviderConfig(search: JsonRecord, providerKey: string): JsonRecord | undefined {
const current = search[providerKey];
return isRecord(current) ? cloneRecord(current) : undefined;
}
@@ -69,9 +61,41 @@ function hasMappedLegacyWebSearchConfig(raw: unknown): boolean {
if (hasOwnKey(search, "apiKey")) {
return true;
}
return (Object.keys(LEGACY_PROVIDER_MAP) as LegacyProviderId[]).some((providerId) =>
isRecord(search[providerId]),
return LEGACY_WEB_SEARCH_PROVIDER_IDS.some((providerId) => isRecord(search[providerId]));
}
function resolveLegacyGlobalWebSearchMigration(search: JsonRecord): {
pluginId: string;
payload: JsonRecord;
legacyPath: string;
targetPath: string;
} | null {
const legacyProviderConfig = copyLegacyProviderConfig(
search,
LEGACY_GLOBAL_WEB_SEARCH_PROVIDER_ID,
);
const payload = legacyProviderConfig ?? {};
const hasLegacyApiKey = hasOwnKey(search, "apiKey");
if (hasLegacyApiKey) {
payload.apiKey = search.apiKey;
}
if (Object.keys(payload).length === 0) {
return null;
}
const pluginId =
LEGACY_WEB_SEARCH_PROVIDER_PLUGIN_IDS[LEGACY_GLOBAL_WEB_SEARCH_PROVIDER_ID] ??
LEGACY_GLOBAL_WEB_SEARCH_PROVIDER_ID;
return {
pluginId,
payload,
legacyPath: hasLegacyApiKey
? "tools.web.search.apiKey"
: `tools.web.search.${LEGACY_GLOBAL_WEB_SEARCH_PROVIDER_ID}`,
targetPath:
hasLegacyApiKey && !legacyProviderConfig
? `plugins.entries.${pluginId}.config.webSearch.apiKey`
: `plugins.entries.${pluginId}.config.webSearch`,
};
}
function migratePluginWebSearchConfig(params: {
@@ -123,7 +147,7 @@ export function listLegacyWebSearchConfigPaths(raw: unknown): string[] {
if ("apiKey" in search) {
paths.push("tools.web.search.apiKey");
}
for (const providerId of Object.keys(LEGACY_PROVIDER_MAP) as LegacyProviderId[]) {
for (const providerId of LEGACY_WEB_SEARCH_PROVIDER_IDS) {
const scoped = search[providerId];
if (isRecord(scoped)) {
for (const key of Object.keys(scoped)) {
@@ -179,12 +203,8 @@ function normalizeLegacyWebSearchConfigRecord<T extends JsonRecord>(
if (key === "apiKey") {
continue;
}
if (
(Object.keys(LEGACY_PROVIDER_MAP) as LegacyProviderId[]).includes(key as LegacyProviderId)
) {
if (isRecord(value)) {
continue;
}
if (LEGACY_WEB_SEARCH_PROVIDER_ID_SET.has(key) && isRecord(value)) {
continue;
}
if (GENERIC_WEB_SEARCH_KEYS.has(key) || !isRecord(value)) {
nextSearch[key] = value;
@@ -192,37 +212,35 @@ function normalizeLegacyWebSearchConfigRecord<T extends JsonRecord>(
}
web.search = nextSearch;
const legacyBraveConfig = copyLegacyProviderConfig(search, "brave");
const braveConfig = legacyBraveConfig ?? {};
if (hasOwnKey(search, "apiKey")) {
braveConfig.apiKey = search.apiKey;
}
if (Object.keys(braveConfig).length > 0) {
const globalSearchMigration = resolveLegacyGlobalWebSearchMigration(search);
if (globalSearchMigration) {
migratePluginWebSearchConfig({
root: nextRoot,
legacyPath: hasOwnKey(search, "apiKey")
? "tools.web.search.apiKey"
: "tools.web.search.brave",
targetPath:
hasOwnKey(search, "apiKey") && !legacyBraveConfig
? "plugins.entries.brave.config.webSearch.apiKey"
: "plugins.entries.brave.config.webSearch",
pluginId: LEGACY_PROVIDER_MAP.brave,
payload: braveConfig,
legacyPath: globalSearchMigration.legacyPath,
targetPath: globalSearchMigration.targetPath,
pluginId: globalSearchMigration.pluginId,
payload: globalSearchMigration.payload,
changes,
});
}
for (const providerId of ["firecrawl", "gemini", "grok", "kimi", "perplexity"] as const) {
for (const providerId of LEGACY_WEB_SEARCH_PROVIDER_IDS) {
if (providerId === LEGACY_GLOBAL_WEB_SEARCH_PROVIDER_ID) {
continue;
}
const scoped = copyLegacyProviderConfig(search, providerId);
if (!scoped || Object.keys(scoped).length === 0) {
continue;
}
const pluginId = LEGACY_WEB_SEARCH_PROVIDER_PLUGIN_IDS[providerId];
if (!pluginId) {
continue;
}
migratePluginWebSearchConfig({
root: nextRoot,
legacyPath: `tools.web.search.${providerId}`,
targetPath: `plugins.entries.${LEGACY_PROVIDER_MAP[providerId]}.config.webSearch`,
pluginId: LEGACY_PROVIDER_MAP[providerId],
targetPath: `plugins.entries.${pluginId}.config.webSearch`,
pluginId,
payload: scoped,
changes,
});

View File

@@ -1,10 +1,12 @@
import {
ZAI_CN_BASE_URL,
ZAI_CODING_CN_BASE_URL,
ZAI_CODING_GLOBAL_BASE_URL,
ZAI_GLOBAL_BASE_URL,
} from "../plugin-sdk/zai.js";
import { fetchWithTimeout } from "../utils/fetch-timeout.js";
export type ZaiEndpointId = "global" | "cn" | "coding-global" | "coding-cn";
const ZAI_CODING_GLOBAL_BASE_URL = "https://api.z.ai/api/coding/paas/v4";
const ZAI_CODING_CN_BASE_URL = "https://open.bigmodel.cn/api/coding/paas/v4";
const ZAI_GLOBAL_BASE_URL = "https://api.z.ai/api/paas/v4";
const ZAI_CN_BASE_URL = "https://open.bigmodel.cn/api/paas/v4";
export type ZaiDetectedEndpoint = {
endpoint: ZaiEndpointId;