kimi-vercel-ai-sdk-provider 0.2.0

package/src/kimi-provider.ts

@@ -0,0 +1,263 @@
+/**
+ * Kimi provider factory.
+ * @module
+ */
+
+import { type LanguageModelV3, NoSuchModelError, type ProviderV3 } from '@ai-sdk/provider';
+import {
+  type FetchFunction,
+  loadApiKey,
+  loadOptionalSetting,
+  withUserAgentSuffix,
+  withoutTrailingSlash
+} from '@ai-sdk/provider-utils';
+import { KimiChatLanguageModel, type KimiChatModelId, type KimiChatSettings } from './chat';
+import { KimiFileClient } from './files';
+import { kimiTools } from './tools';
+import { VERSION } from './version';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const GLOBAL_BASE_URL = 'https://api.moonshot.ai/v1';
+const CN_BASE_URL = 'https://api.moonshot.cn/v1';
+
+// ============================================================================
+// Provider Settings
+// ============================================================================
+
+/**
+ * Settings for creating a Kimi provider instance.
+ */
+export interface KimiProviderSettings {
+  /**
+   * Moonshot AI API key. Defaults to the MOONSHOT_API_KEY environment variable.
+   */
+  apiKey?: string;
+
+  /**
+   * Base URL override. Defaults to the global or China endpoint.
+   */
+  baseURL?: string;
+
+  /**
+   * Select the regional endpoint when baseURL is not provided.
+   * - `global`: Use the global API endpoint (api.moonshot.ai)
+   * - `cn`: Use the China API endpoint (api.moonshot.cn)
+   *
+   * @default 'global'
+   */
+  endpoint?: 'global' | 'cn';
+
+  /**
+   * Default headers for all requests.
+   */
+  headers?: Record<string, string | undefined>;
+
+  /**
+   * Custom fetch implementation.
+   */
+  fetch?: FetchFunction;
+
+  /**
+   * ID generator for tool call fallback IDs.
+   */
+  generateId?: () => string;
+
+  /**
+   * Enable JSON schema structured outputs by default.
+   */
+  supportsStructuredOutputs?: boolean;
+
+  /**
+   * Include usage details in streaming responses if supported.
+   */
+  includeUsageInStream?: boolean;
+
+  /**
+   * Override supported URL patterns for file parts.
+   */
+  supportedUrls?: LanguageModelV3['supportedUrls'];
+}
+
+// ============================================================================
+// Provider Interface
+// ============================================================================
+
+/**
+ * The Kimi provider interface.
+ */
+export interface KimiProvider extends Omit<ProviderV3, 'specificationVersion'> {
+  specificationVersion: 'v3';
+
+  /**
+   * Creates a chat language model.
+   * @param modelId - The model identifier
+   * @param settings - Optional model settings
+   */
+  (modelId: KimiChatModelId, settings?: KimiChatSettings): LanguageModelV3;
+
+  /**
+   * Creates a chat language model.
+   * @param modelId - The model identifier
+   * @param settings - Optional model settings
+   */
+  languageModel(modelId: KimiChatModelId, settings?: KimiChatSettings): LanguageModelV3;
+
+  /**
+   * Creates a chat language model (alias for languageModel).
+   * @param modelId - The model identifier
+   * @param settings - Optional model settings
+   */
+  chat(modelId: KimiChatModelId, settings?: KimiChatSettings): LanguageModelV3;
+
+  /**
+   * Built-in tools that can be used with Kimi models.
+   */
+  tools: typeof kimiTools;
+
+  /**
+   * File client for uploading and extracting content from files.
+   * Pre-configured with the provider's API key and base URL.
+   *
+   * @example
+   * ```ts
+   * const kimi = createKimi();
+   * const result = await kimi.files.uploadAndExtract({
+   *   data: pdfBuffer,
+   *   filename: 'document.pdf',
+   * });
+   * console.log(result.content);
+   * ```
+   */
+  files: KimiFileClient;
+}
+
+// ============================================================================
+// Provider Factory
+// ============================================================================
+
+/**
+ * Create a Kimi provider instance.
+ *
+ * @param options - Provider settings
+ * @returns A configured Kimi provider
+ *
+ * @example
+ * ```ts
+ * import { createKimi } from 'kimi-vercel-ai-sdk-provider
+';
+ *
+ * const kimi = createKimi({
+ *   apiKey: process.env.MOONSHOT_API_KEY,
+ * });
+ *
+ * const result = await generateText({
+ *   model: kimi('kimi-k2.5'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With web search enabled
+ * const result = await generateText({
+ *   model: kimi('kimi-k2.5', { webSearch: true }),
+ *   prompt: 'What are the latest AI news?',
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With code interpreter
+ * const result = await generateText({
+ *   model: kimi('kimi-k2.5', { codeInterpreter: true }),
+ *   prompt: 'Calculate the factorial of 20',
+ * });
+ * ```
+ */
+export function createKimi(options: KimiProviderSettings = {}): KimiProvider {
+  const resolvedBaseURL =
+    loadOptionalSetting({
+      settingValue: options.baseURL,
+      environmentVariableName: 'MOONSHOT_BASE_URL'
+    }) ?? (options.endpoint === 'cn' ? CN_BASE_URL : GLOBAL_BASE_URL);
+
+  const baseURL = withoutTrailingSlash(resolvedBaseURL) ?? GLOBAL_BASE_URL;
+
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        Authorization: `Bearer ${loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'MOONSHOT_API_KEY',
+          description: 'Moonshot'
+        })}`,
+        ...options.headers
+      },
+      `ai-sdk/kimi/${VERSION}`
+    );
+
+  const createChatModel = (modelId: KimiChatModelId, settings: KimiChatSettings = {}) =>
+    new KimiChatLanguageModel(modelId, settings, {
+      provider: 'kimi.chat',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      generateId: options.generateId,
+      supportsStructuredOutputs: settings.supportsStructuredOutputs ?? options.supportsStructuredOutputs,
+      includeUsageInStream: settings.includeUsageInStream ?? options.includeUsageInStream,
+      supportedUrls: settings.supportedUrls ?? options.supportedUrls
+    });
+
+  const provider: KimiProvider = (modelId: KimiChatModelId, settings?: KimiChatSettings): KimiChatLanguageModel => {
+    if (new.target) {
+      throw new Error('The Kimi provider function cannot be called with new.');
+    }
+
+    return createChatModel(modelId, settings);
+  };
+
+  provider.specificationVersion = 'v3';
+  provider.languageModel = createChatModel;
+  provider.chat = createChatModel;
+  provider.tools = kimiTools;
+  provider.files = new KimiFileClient({
+    baseURL,
+    headers: getHeaders,
+    fetch: options.fetch
+  });
+
+  provider.embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({ modelId, modelType: 'embeddingModel' });
+  };
+
+  provider.imageModel = (modelId: string) => {
+    throw new NoSuchModelError({ modelId, modelType: 'imageModel' });
+  };
+
+  provider.rerankingModel = (modelId: string) => {
+    throw new NoSuchModelError({ modelId, modelType: 'rerankingModel' });
+  };
+
+  return provider;
+}
+
+/**
+ * Default Kimi provider instance.
+ *
+ * Uses the MOONSHOT_API_KEY environment variable for authentication.
+ *
+ * @example
+ * ```ts
+ * import { kimi } from 'kimi-vercel-ai-sdk-provider
+';
+ *
+ * const result = await generateText({
+ *   model: kimi('kimi-k2.5'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+export const kimi = createKimi();

package/src/tools/builtin-tools.ts

@@ -0,0 +1,273 @@
+/**
+ * Built-in tools for Kimi API.
+ *
+ * Kimi provides server-side tools that can be invoked during chat completions:
+ * - `$web_search`: Search the web for information
+ * - `$code`: Execute code using Kimi's code interpreter
+ *
+ * @module
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Kimi's built-in web search tool identifier.
+ * This tool allows Kimi to search the web for up-to-date information.
+ */
+export const KIMI_WEB_SEARCH_TOOL_NAME = '$web_search';
+
+/**
+ * Kimi's built-in code interpreter tool identifier.
+ * This tool allows Kimi to execute code and return results.
+ */
+export const KIMI_CODE_INTERPRETER_TOOL_NAME = '$code';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Configuration for Kimi's built-in web search tool.
+ */
+export interface KimiWebSearchConfig {
+  /**
+   * Whether to include search results in the response.
+   * When true, the search results will be included in the tool output.
+   */
+  search_result?: boolean;
+  /**
+   * Allow additional configuration options.
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Configuration for Kimi's built-in code interpreter tool.
+ */
+export interface KimiCodeInterpreterConfig {
+  /**
+   * Maximum execution time in seconds.
+   * Default varies by model and API tier.
+   */
+  timeout?: number;
+
+  /**
+   * Whether to return execution output.
+   * When true, stdout/stderr will be included in results.
+   */
+  include_output?: boolean;
+
+  /**
+   * Allow additional configuration options.
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * A Kimi built-in tool definition.
+ * These are handled server-side by Kimi's API.
+ */
+export interface KimiBuiltinTool {
+  type: 'builtin_function';
+  function: {
+    name: string;
+    config?: Record<string, unknown>;
+  };
+}
+
+// ============================================================================
+// Web Search Tool
+// ============================================================================
+
+/**
+ * Configuration options for the web search tool.
+ */
+export interface KimiWebSearchToolOptions {
+  /**
+   * Whether the web search tool is enabled.
+   */
+  enabled: boolean;
+
+  /**
+   * Optional configuration for the web search tool.
+   */
+  config?: KimiWebSearchConfig;
+}
+
+export type KimiWebSearchToolConfig = KimiWebSearchToolOptions;
+
+/**
+ * Create a Kimi built-in web search tool definition.
+ *
+ * @param config - Optional configuration for the web search tool
+ * @returns A built-in tool definition for $web_search
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const tool = createWebSearchTool();
+ *
+ * // With configuration
+ * const tool = createWebSearchTool({ search_result: true });
+ * ```
+ */
+export function createWebSearchTool(config?: KimiWebSearchConfig): KimiBuiltinTool {
+  return {
+    type: 'builtin_function',
+    function: {
+      name: KIMI_WEB_SEARCH_TOOL_NAME,
+      ...(config ? { config } : {})
+    }
+  };
+}
+
+export function createKimiWebSearchTool(config?: KimiWebSearchConfig): KimiBuiltinTool {
+  return createWebSearchTool(config);
+}
+
+// ============================================================================
+// Code Interpreter Tool
+// ============================================================================
+
+/**
+ * Configuration options for the code interpreter tool.
+ */
+export interface KimiCodeInterpreterToolOptions {
+  /**
+   * Whether the code interpreter tool is enabled.
+   */
+  enabled: boolean;
+
+  /**
+   * Optional configuration for the code interpreter tool.
+   */
+  config?: KimiCodeInterpreterConfig;
+}
+
+/**
+ * Create a Kimi built-in code interpreter tool definition.
+ *
+ * @param config - Optional configuration for the code interpreter tool
+ * @returns A built-in tool definition for $code
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const tool = createCodeInterpreterTool();
+ *
+ * // With configuration
+ * const tool = createCodeInterpreterTool({ timeout: 30, include_output: true });
+ * ```
+ */
+export function createCodeInterpreterTool(config?: KimiCodeInterpreterConfig): KimiBuiltinTool {
+  return {
+    type: 'builtin_function',
+    function: {
+      name: KIMI_CODE_INTERPRETER_TOOL_NAME,
+      ...(config ? { config } : {})
+    }
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Check if a tool name is a Kimi built-in tool.
+ * Built-in tools are prefixed with '$'.
+ *
+ * @param toolName - The tool name to check
+ * @returns True if the tool is a built-in tool
+ */
+export function isBuiltinToolName(toolName: string): boolean {
+  return toolName.startsWith('$');
+}
+
+/**
+ * Check if a tool name is the web search tool.
+ *
+ * @param toolName - The tool name to check
+ * @returns True if the tool is the web search tool
+ */
+export function isWebSearchTool(toolName: string): boolean {
+  return toolName === KIMI_WEB_SEARCH_TOOL_NAME;
+}
+
+/**
+ * Check if a tool name is the code interpreter tool.
+ *
+ * @param toolName - The tool name to check
+ * @returns True if the tool is the code interpreter tool
+ */
+export function isCodeInterpreterTool(toolName: string): boolean {
+  return toolName === KIMI_CODE_INTERPRETER_TOOL_NAME;
+}
+
+// ============================================================================
+// Provider Tool Definitions
+// ============================================================================
+
+/**
+ * Create provider-level tool definitions for use with the AI SDK.
+ * These can be passed directly to the tools option.
+ */
+export const kimiTools = {
+  /**
+   * Create a web search tool for use with Kimi models.
+   *
+   * @param config - Optional configuration
+   * @returns A provider tool definition
+   *
+   * @example
+   * ```ts
+   * import { kimi, kimiTools } from 'kimi-vercel-ai-sdk-provider
+';
+   *
+   * const result = await generateText({
+   *   model: kimi('kimi-k2.5'),
+   *   tools: {
+   *     webSearch: kimiTools.webSearch(),
+   *   },
+   *   prompt: 'What are the latest AI news?',
+   * });
+   * ```
+   */
+  webSearch: (config?: KimiWebSearchConfig) => {
+    return {
+      type: 'provider' as const,
+      id: 'kimi.webSearch',
+      args: createWebSearchTool(config)
+    };
+  },
+
+  /**
+   * Create a code interpreter tool for use with Kimi models.
+   *
+   * @param config - Optional configuration
+   * @returns A provider tool definition
+   *
+   * @example
+   * ```ts
+   * import { kimi, kimiTools } from 'kimi-vercel-ai-sdk-provider
+';
+   *
+   * const result = await generateText({
+   *   model: kimi('kimi-k2.5'),
+   *   tools: {
+   *     codeInterpreter: kimiTools.codeInterpreter(),
+   *   },
+   *   prompt: 'Calculate the factorial of 10',
+   * });
+   * ```
+   */
+  codeInterpreter: (config?: KimiCodeInterpreterConfig) => {
+    return {
+      type: 'provider' as const,
+      id: 'kimi.codeInterpreter',
+      args: createCodeInterpreterTool(config)
+    };
+  }
+};

package/src/tools/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Tools module exports.
+ * @module
+ */
+
+export type {
+  KimiBuiltinTool,
+  KimiCodeInterpreterConfig,
+  KimiCodeInterpreterToolOptions,
+  KimiWebSearchConfig,
+  KimiWebSearchToolConfig,
+  KimiWebSearchToolOptions
+} from './builtin-tools';
+export type {
+  KimiFunctionTool,
+  KimiTool,
+  PrepareToolsOptions,
+  PrepareToolsResult
+} from './prepare-tools';
+// Built-in tools
+export {
+  KIMI_CODE_INTERPRETER_TOOL_NAME,
+  KIMI_WEB_SEARCH_TOOL_NAME,
+  createCodeInterpreterTool,
+  createKimiWebSearchTool,
+  createWebSearchTool,
+  isBuiltinToolName,
+  isCodeInterpreterTool,
+  isWebSearchTool,
+  kimiTools
+} from './builtin-tools';
+// Tool preparation
+export { prepareKimiTools } from './prepare-tools';