@xiaozhiclaw/provider-core 0.1.0

package/dist/model-detection.js

@@ -0,0 +1,28 @@
+/**
+ * Model detection helpers shared between OpenAI transport implementations.
+ *
+ * These are used by both openai-chat.ts and openai-responses.ts to detect
+ * model families and apply family-specific constraints:
+ *   - GPT-5.x: unified reasoning, temperature allowed, reasoning object format
+ *   - GPT-5.4-nano: reasoning effort capped at medium
+ *   - o-series (legacy): reasoning_effort flat string, temperature suppressed
+ */
+/** GPT-5.x models (new generation with unified reasoning). */
+export function isGPT5xModel(model) {
+    return model.toLowerCase().startsWith("gpt-5");
+}
+/**
+ * GPT-5.4-nano models 鈥?reasoning effort capped at medium.
+ * openai-ProviderMax 搂3: gpt-5.4-nano only supports none/low/medium effort.
+ */
+export function isGPT5NanoModel(model) {
+    return model.toLowerCase().includes("5.4-nano");
+}
+/**
+ * OpenAI o-series reasoning models (legacy, kept for 3rd-party provider compat).
+ * These suppress temperature/top_p and use reasoning_effort as flat string.
+ * Matches: o1, o1-mini, o1-pro, o3, o3-mini, o3-pro, o4-mini, etc.
+ */
+export function isOpenAIReasoningModel(model) {
+    return /^o[1-4](-|$)/.test(model.toLowerCase());
+}

package/dist/paths.d.ts

@@ -0,0 +1,2 @@
+export declare function getUserCacheDir(): string;
+export declare function getUserDebugLogsDir(): string;

package/dist/paths.js

@@ -0,0 +1,11 @@
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+function baseDir() {
+    return process.env.QLOGICAGENT_HOME ?? join(homedir() || tmpdir(), ".qlogicagent");
+}
+export function getUserCacheDir() {
+    return process.env.QLOGICAGENT_CACHE_DIR ?? join(baseDir(), "cache");
+}
+export function getUserDebugLogsDir() {
+    return process.env.QLOGICAGENT_DEBUG_LOG_DIR ?? join(baseDir(), "debug-logs");
+}

package/dist/provider-def.d.ts

@@ -0,0 +1,220 @@
+/**
+ * ProviderDef 鈥?defines how to connect to an LLM provider.
+ *
+ * Aligned with Hermes `ProviderDef` dataclass pattern:
+ *   id + name + transport type + baseUrl + auth config + model list
+ *
+ * Single curated model catalog plus optional user provider overrides.
+ */
+export type TransportType = "openai-chat" | "openai-responses" | "anthropic-messages" | "volcengine-responses" | "gemini-generatecontent";
+export type AuthType = "bearer" | "x-api-key" | "none";
+export type MediaCapability = "image" | "video" | "music" | "music_realtime" | "tts" | "3d" | "stt" | "embedding" | "video_understanding" | "image_understanding" | "voice_clone" | "rerank" | "document_parsing" | "realtime_audio" | "realtime_video";
+export type ProviderVariantKind = "standard" | "openai-compatible" | "anthropic-compatible" | "coding-plan" | "media-plan" | "realtime";
+export type ProviderBillingChannelKind = "paygo" | "plan" | "discount" | "official";
+export type ProviderVariantCapability = "thinking" | "reasoning_split" | "tool_stream" | "builtin_tools" | "vision" | "media" | "coding" | "realtime";
+export type VideoOperation = "text2video" | "img2video" | "video2video" | "edit" | "merge" | "upscale";
+export type ImageOperation = "text2image" | "img2img" | "inpainting" | "outpainting";
+export type MusicOperation = "text2music" | "cover" | "realtime";
+export type TtsOperation = "text2speech" | "voice_clone";
+export type ThreeDOperation = "text2_3d" | "img2_3d";
+export interface VideoCapabilities {
+    type: "video";
+    operations: VideoOperation[];
+    maxDurationSeconds?: number;
+    resolutions?: string[];
+    aspectRatios?: string[];
+    fps?: number[];
+}
+export interface ImageCapabilities {
+    type: "image";
+    operations: ImageOperation[];
+    sizes?: string[];
+    transparentBackground?: boolean;
+}
+export interface MusicCapabilities {
+    type: "music";
+    operations: MusicOperation[];
+    maxDurationSeconds?: number;
+    formats?: string[];
+}
+export interface TtsCapabilities {
+    type: "tts";
+    operations?: TtsOperation[];
+    voices?: string[];
+    maxCharacters?: number;
+    formats?: string[];
+}
+export interface ThreeDCapabilities {
+    type: "3d";
+    operations: ThreeDOperation[];
+    outputFormats?: string[];
+}
+export interface SttCapabilities {
+    type: "stt";
+    languages?: string[];
+    maxDurationSeconds?: number;
+    formats?: string[];
+}
+export interface EmbeddingCapabilities {
+    type: "embedding";
+    dimensions?: number;
+    maxTokens?: number;
+}
+export interface VideoUnderstandingCapabilities {
+    type: "video_understanding";
+    maxDurationSeconds?: number;
+    formats?: string[];
+}
+export interface ImageUnderstandingCapabilities {
+    type: "image_understanding";
+    formats?: string[];
+}
+export interface VoiceCloneCapabilities {
+    type: "voice_clone";
+    maxSampleDurationSeconds?: number;
+    maxSampleSizeMB?: number;
+    formats?: string[];
+}
+export interface RerankCapabilities {
+    type: "rerank";
+    maxDocuments?: number;
+    maxQueryLength?: number;
+    maxDocumentLength?: number;
+}
+export interface DocumentParsingCapabilities {
+    type: "document_parsing";
+    supportedFormats?: string[];
+    maxPageCount?: number;
+    maxFileSizeMB?: number;
+}
+export interface RealtimeAudioCapabilities {
+    type: "realtime_audio";
+    voices?: string[];
+    modalities?: Array<"text" | "audio">;
+    vad?: boolean;
+    toolCalling?: boolean;
+}
+export interface RealtimeVideoCapabilities {
+    type: "realtime_video";
+    modalities?: Array<"text" | "audio" | "video">;
+    vad?: boolean;
+    toolCalling?: boolean;
+    maxDurationSeconds?: number;
+}
+export type MediaCapabilities = VideoCapabilities | ImageCapabilities | MusicCapabilities | TtsCapabilities | ThreeDCapabilities | SttCapabilities | EmbeddingCapabilities | VideoUnderstandingCapabilities | ImageUnderstandingCapabilities | VoiceCloneCapabilities | RerankCapabilities | DocumentParsingCapabilities | RealtimeAudioCapabilities | RealtimeVideoCapabilities;
+/**
+ * Provider-specific quirks 鈥?drives conditional logic in transports.
+ * CC parity: provider detection via quirks flags instead of hardcoded if/else.
+ * altcode parity: provider auto-detect + per-provider parameter translation.
+ */
+export interface ProviderQuirks {
+    /** Provider doesn't support thinking content blocks (Qwen) */
+    filterThinkingBlocks?: boolean;
+    /** Provider doesn't support image content blocks 鈥?strip imageUrls before sending (DeepSeek, MiniMax) */
+    filterImageBlocks?: boolean;
+    /** DeepSeek: budget_tokens ignored, use output_config.effort instead */
+    useEffortInsteadOfBudget?: boolean;
+    /** Provider natively supports PDF/document content blocks (Anthropic document, Gemini fileData).
+     *  When false, PDFs are annotated as text labels and the agent must use tools to extract content. */
+    supportsDocumentVision?: boolean;
+    /** Provider supports reasoning_effort param (Kimi K2, OpenAI o-series) */
+    supportsReasoningEffort?: boolean;
+    /** Provider has built-in web search (Kimi: builtin_function.$web_search, GLM: web_search) */
+    builtinWebSearch?: boolean;
+    /** Provider has built-in code interpreter */
+    builtinCodeInterpreter?: boolean;
+    /** Provider supports native URL context fetching (Gemini urlContext tool) */
+    builtinUrlContext?: boolean;
+    /** Provider supports Google Maps Grounding (Gemini googleMaps tool) */
+    builtinMapsGrounding?: boolean;
+    /** Provider supports native file search (Gemini fileSearch tool) */
+    builtinFileSearch?: boolean;
+    /** Supports thinking.type="enabled"/"disabled" body param (Kimi K2, GLM).
+     *  Disambiguation: GLM also sets supportsToolStream; Kimi does not. */
+    supportsThinkingParam?: boolean;
+    /** When true, send thinking.type="disabled" unless the caller explicitly requests reasoning. */
+    disableThinkingByDefault?: boolean;
+    /** GLM-only: supports tool_stream=true for incremental tool call streaming */
+    supportsToolStream?: boolean;
+    /** DeepSeek only maps to "high"|"max"; low/medium鈫抙igh */
+    maxReasoningEffort?: "high" | "max";
+    /** Supports prefix completion via /beta endpoint (DeepSeek Beta) */
+    supportsPrefixCompletion?: boolean;
+    /** MiniMax OpenAI route: inject reasoning_split=true to split thinking into reasoning_details.
+     *  Streaming uses cumulative string updates (not incremental deltas). */
+    supportsReasoningSplit?: boolean;
+}
+export interface ProviderDef {
+    /** Unique provider id, e.g. "deepseek", "openai", "anthropic" */
+    id: string;
+    /** Display name, e.g. "DeepSeek" */
+    name: string;
+    /** Which transport to use for LLM calls */
+    transport: TransportType;
+    /** API base URL, e.g. "https://api.deepseek.com" */
+    baseUrl: string;
+    /**
+     * Logical provider group 鈥?links protocol variants of the same vendor.
+     * e.g. both "zhipu" (anthropic) and "zhipu-openai" share group "zhipu".
+     * Defaults to provider id if unset.
+     */
+    group?: string;
+    /** Technical protocol variant kind for resolver ranking. */
+    variantKind?: ProviderVariantKind;
+    /** Channel type hint only; commercial cost selection is owned by llmrouter. */
+    billingChannelKind?: ProviderBillingChannelKind;
+    /** Provider-level capability hints used by ProviderVariantResolver. */
+    capabilities?: ProviderVariantCapability[];
+    /** Env var names for API key (priority order) */
+    apiKeyEnvVars: string[];
+    /** Auth header style */
+    authType: AuthType;
+    /** Is an aggregator (OpenRouter, 纭呭熀) 鈥?model ids may have prefix */
+    isAggregator: boolean;
+    /** Recommended default model */
+    defaultModel?: string;
+    /** Known models for this provider */
+    models?: ModelInfo[];
+    /** Extra headers to send with every request (e.g. aggregator-specific) */
+    extraHeaders?: Record<string, string>;
+    /** Whether this provider supports stream_options (default true for openai-chat) */
+    supportsStreamOptions?: boolean;
+    /** Whether to omit temperature when it equals 0 (some providers reject 0) */
+    omitZeroTemperature?: boolean;
+    /** Provider-specific quirks for transport-level conditional logic */
+    quirks?: ProviderQuirks;
+}
+export interface ModelInfo {
+    /** Model id, e.g. "deepseek-v4-flash" */
+    id: string;
+    /** Stable public aliases exposed by llmrouter or older qlogicagent configs */
+    aliases?: string[];
+    /** Display name, e.g. "DeepSeek Chat V3" */
+    name: string;
+    /** Context window in tokens */
+    contextWindow: number;
+    /** Max output tokens */
+    maxOutput: number;
+    /** Supports function/tool calling */
+    toolCall: boolean;
+    /** Has reasoning/thinking mode */
+    reasoning: boolean;
+    /** Thinking is forced on 鈥?cannot be toggled off (e.g. QwQ, DeepSeek-R1) */
+    reasoningRequired?: boolean;
+    /** Model only supports streaming (non-stream requests will fail) */
+    streamRequired?: boolean;
+    /** Supports vision (image input) */
+    vision: boolean;
+    /** Cost per 1M input tokens (USD) */
+    costInput?: number;
+    /** Cost per 1M output tokens (USD) */
+    costOutput?: number;
+    /** Cost per 1M cache read tokens (USD) */
+    costCacheRead?: number;
+    /** Cost per 1M cache write tokens (USD) */
+    costCacheWrite?: number;
+    /** Media generation capability 鈥?undefined means chat/reasoning model */
+    mediaType?: MediaCapability;
+    /** Fine-grained media capabilities 鈥?operations, formats, limits */
+    mediaCapabilities?: MediaCapabilities;
+}

package/dist/provider-def.js

@@ -0,0 +1,9 @@
+/**
+ * ProviderDef 鈥?defines how to connect to an LLM provider.
+ *
+ * Aligned with Hermes `ProviderDef` dataclass pattern:
+ *   id + name + transport type + baseUrl + auth config + model list
+ *
+ * Single curated model catalog plus optional user provider overrides.
+ */
+export {};

package/dist/provider-registry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ProviderRegistry 鈥?single-source curated registry for LLM providers.
+ *
+ * Layer 1: builtin-providers.ts curated providers and models
+ * Layer 2: user config override (from agent.turn.config)
+ *
+ * Model IDs are intentionally not enriched from external catalogs. llmrouter and
+ * OpenClaw consume the same curated Provider Core catalog, and upstream request
+ * IDs are resolved through model aliases/native IDs.
+ *
+ * Aligned with Hermes provider_registry.py.
+ */
+import type { ModelInfo, ProviderDef } from "./provider-def.js";
+export declare class ProviderRegistry {
+    /** Curated providers and models */
+    private builtins;
+    /** User overrides (from agent.turn.config) */
+    private overrides;
+    constructor();
+    /**
+     * Apply user config override for a provider.
+     * Typically called when agent.turn.config has baseUrl/apiKey overrides.
+     */
+    applyOverride(providerId: string, override: Partial<ProviderDef>): void;
+    /**
+     * Get merged ProviderDef by id (Layer 3 > Layer 1).
+     * Returns undefined if provider not found.
+     * Supports common aliases (e.g., "claude" 鈫?"anthropic").
+     */
+    getProvider(id: string): ProviderDef | undefined;
+    getBuiltinProvider(id: string): ProviderDef | undefined;
+    /**
+     * List all known provider ids.
+     */
+    listProviders(): ProviderDef[];
+    /**
+     * List models for a specific provider.
+     */
+    listModels(providerId: string): ModelInfo[];
+    /**
+     * Look up a single model's info by provider + model id.
+     * Returns undefined if the model is not found.
+     */
+    getModelInfo(providerId: string, modelId: string): ModelInfo | undefined;
+    /**
+     * Resolve API key for a provider:
+     *   1. Explicit key (from agent.turn.config)
+     *   2. Environment variables (ProviderDef.apiKeyEnvVars)
+     */
+    resolveApiKey(providerId: string, explicitKey?: string): string | undefined;
+}

package/dist/provider-registry.js

@@ -0,0 +1,130 @@
+/**
+ * ProviderRegistry 鈥?single-source curated registry for LLM providers.
+ *
+ * Layer 1: builtin-providers.ts curated providers and models
+ * Layer 2: user config override (from agent.turn.config)
+ *
+ * Model IDs are intentionally not enriched from external catalogs. llmrouter and
+ * OpenClaw consume the same curated Provider Core catalog, and upstream request
+ * IDs are resolved through model aliases/native IDs.
+ *
+ * Aligned with Hermes provider_registry.py.
+ */
+import { BUILTIN_PROVIDERS } from "./builtin-providers.js";
+// Provider alias map (Hermes-aligned): common user names 鈫?canonical ids
+const PROVIDER_ALIASES = {
+    claude: "anthropic",
+    gemini: "google",
+    doubao: "volcengine",
+};
+export class ProviderRegistry {
+    /** Curated providers and models */
+    builtins = new Map();
+    /** User overrides (from agent.turn.config) */
+    overrides = new Map();
+    constructor() {
+        for (const p of BUILTIN_PROVIDERS) {
+            this.builtins.set(p.id, p);
+        }
+    }
+    /**
+     * Apply user config override for a provider.
+     * Typically called when agent.turn.config has baseUrl/apiKey overrides.
+     */
+    applyOverride(providerId, override) {
+        this.overrides.set(providerId, {
+            ...this.overrides.get(providerId),
+            ...override,
+        });
+    }
+    /**
+     * Get merged ProviderDef by id (Layer 3 > Layer 1).
+     * Returns undefined if provider not found.
+     * Supports common aliases (e.g., "claude" 鈫?"anthropic").
+     */
+    getProvider(id) {
+        const resolvedId = PROVIDER_ALIASES[id] ?? id;
+        const builtin = this.builtins.get(resolvedId);
+        const override = this.overrides.get(resolvedId);
+        if (!builtin && !override)
+            return undefined;
+        if (!builtin && override) {
+            // User defined a custom provider entirely
+            if (!override.id || !override.transport || !override.baseUrl) {
+                return undefined;
+            }
+            return {
+                id: override.id,
+                name: override.name ?? override.id,
+                transport: override.transport,
+                baseUrl: override.baseUrl,
+                apiKeyEnvVars: override.apiKeyEnvVars ?? [],
+                authType: override.authType ?? "bearer",
+                isAggregator: override.isAggregator ?? false,
+                defaultModel: override.defaultModel,
+                models: override.models,
+            };
+        }
+        if (builtin && !override)
+            return builtin;
+        // Merge: override fields take precedence
+        return {
+            ...builtin,
+            ...override,
+            // Merge models: override models replace if provided
+            models: override.models ?? builtin.models,
+        };
+    }
+    getBuiltinProvider(id) {
+        const resolvedId = PROVIDER_ALIASES[id] ?? id;
+        return this.builtins.get(resolvedId);
+    }
+    /**
+     * List all known provider ids.
+     */
+    listProviders() {
+        const all = new Map();
+        for (const [id, p] of this.builtins) {
+            all.set(id, p);
+        }
+        // Override/custom providers
+        for (const [id] of this.overrides) {
+            const merged = this.getProvider(id);
+            if (merged)
+                all.set(id, merged);
+        }
+        return [...all.values()];
+    }
+    /**
+     * List models for a specific provider.
+     */
+    listModels(providerId) {
+        const provider = this.getProvider(providerId);
+        return provider?.models ?? [];
+    }
+    /**
+     * Look up a single model's info by provider + model id.
+     * Returns undefined if the model is not found.
+     */
+    getModelInfo(providerId, modelId) {
+        return this.listModels(providerId).find(m => m.id === modelId);
+    }
+    /**
+     * Resolve API key for a provider:
+     *   1. Explicit key (from agent.turn.config)
+     *   2. Environment variables (ProviderDef.apiKeyEnvVars)
+     */
+    resolveApiKey(providerId, explicitKey) {
+        if (explicitKey)
+            return explicitKey;
+        const provider = this.getProvider(providerId);
+        if (!provider)
+            return undefined;
+        for (const envVar of provider.apiKeyEnvVars) {
+            const value = process.env[envVar];
+            if (value?.trim())
+                return value.trim();
+        }
+        return undefined;
+    }
+}

package/dist/provider-tool-api.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ProviderToolAPI 鈥?interface for provider-specific utility endpoints
+ * that are neither LLM chat nor media generation.
+ *
+ * Examples: web search, content reader, tokenizer, moderation, realtime voice.
+ * Each provider can expose its own set of tool APIs; the agent's tool cascade
+ * mechanism (Q1) routes to these when the provider has a native capability.
+ */
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    /** Full page content if available */
+    content?: string;
+}
+export interface ReaderResult {
+    title: string;
+    content: string;
+    url: string;
+}
+export interface TokenizerResult {
+    tokenCount: number;
+    model: string;
+}
+export interface ModerationResult {
+    flagged: boolean;
+    categories: Record<string, boolean>;
+    scores?: Record<string, number>;
+}
+export interface ProviderToolAPI {
+    /** Which tool APIs this provider supports */
+    readonly capabilities: readonly ProviderToolCapability[];
+    /** Web search 鈥?returns search result list */
+    webSearch?(query: string, options?: {
+        maxResults?: number;
+    }): Promise<WebSearchResult[]>;
+    /** URL reader 鈥?extracts content from a web page */
+    reader?(url: string): Promise<ReaderResult>;
+    /** Tokenizer 鈥?count tokens for given text/model */
+    tokenize?(text: string, model: string): Promise<TokenizerResult>;
+    /** Content moderation 鈥?check text for policy violations */
+    moderate?(text: string): Promise<ModerationResult>;
+}
+export type ProviderToolCapability = "web_search" | "reader" | "tokenizer" | "moderations";

package/dist/provider-tool-api.js

@@ -0,0 +1,9 @@
+/**
+ * ProviderToolAPI 鈥?interface for provider-specific utility endpoints
+ * that are neither LLM chat nor media generation.
+ *
+ * Examples: web search, content reader, tokenizer, moderation, realtime voice.
+ * Each provider can expose its own set of tool APIs; the agent's tool cascade
+ * mechanism (Q1) routes to these when the provider has a native capability.
+ */
+export {};

package/dist/provider-variant-resolver.d.ts

@@ -0,0 +1,35 @@
+import type { ModelInfo, ProviderBillingChannelKind, ProviderDef, ProviderVariantCapability, ProviderVariantKind, TransportType } from "./provider-def.js";
+import type { ProviderRegistry } from "./provider-registry.js";
+export type RequestedProviderProtocol = TransportType | "openai" | "anthropic";
+export interface ProviderVariantResolverInput {
+    publicModel: string;
+    requestedProtocol?: RequestedProviderProtocol;
+    capabilities?: ProviderVariantCapability[];
+    purpose?: string;
+    userPreference?: {
+        providerIds?: string[];
+        preferProviderId?: string;
+        preferVariantKind?: ProviderVariantKind;
+    };
+}
+export interface ProviderVariantResolution {
+    provider: string;
+    group: string;
+    publicModel: string;
+    nativeModelId: string;
+    displayName: string;
+    transport: TransportType;
+    variantKind: ProviderVariantKind;
+    billingChannelKind: ProviderBillingChannelKind;
+    capabilities: ProviderVariantCapability[];
+    score: number;
+    reasons: string[];
+    providerDef: ProviderDef;
+    modelInfo: ModelInfo;
+}
+export declare class ProviderVariantResolver {
+    private readonly registry;
+    constructor(registry: Pick<ProviderRegistry, "listProviders" | "listModels">);
+    resolve(input: ProviderVariantResolverInput): ProviderVariantResolution[];
+    resolveBest(input: ProviderVariantResolverInput): ProviderVariantResolution | undefined;
+}