kimi-vercel-ai-sdk-provider 0.2.0

package/src/chat/kimi-chat-messages.ts

@@ -0,0 +1,297 @@
+/**
+ * Message conversion utilities for Kimi API.
+ * @module
+ */
+
+import {
+  type LanguageModelV3Prompt,
+  type LanguageModelV3ToolResultPart,
+  UnsupportedFunctionalityError
+} from '@ai-sdk/provider';
+import { convertToBase64 } from '@ai-sdk/provider-utils';
+import { isBuiltinToolName } from '../tools';
+
+// ============================================================================
+// Message Types
+// ============================================================================
+
+/**
+ * A Kimi chat message.
+ */
+export type KimiChatMessage =
+  | {
+      role: 'system';
+      content: string;
+    }
+  | {
+      role: 'user';
+      content: string | Array<KimiChatContentPart>;
+    }
+  | {
+      role: 'assistant';
+      content: string | null;
+      reasoning_content?: string;
+      tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: { name: string; arguments: string };
+      }>;
+    }
+  | {
+      role: 'tool';
+      tool_call_id: string;
+      content: string;
+    };
+
+/**
+ * A content part in a user message.
+ */
+export type KimiChatContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string } }
+  | { type: 'video_url'; video_url: { url: string } };
+
+/**
+ * A sequence of Kimi chat messages.
+ */
+export type KimiChatPrompt = Array<KimiChatMessage>;
+
+// ============================================================================
+// Supported Media Types
+// ============================================================================
+
+const SUPPORTED_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/*'];
+
+const SUPPORTED_VIDEO_TYPES = ['video/mp4', 'video/webm', 'video/ogg', 'video/*'];
+
+// ============================================================================
+// Message Conversion
+// ============================================================================
+
+/**
+ * Convert AI SDK prompt format to Kimi chat messages.
+ *
+ * @param prompt - The AI SDK prompt
+ * @returns Kimi chat messages
+ */
+export function convertToKimiChatMessages(prompt: LanguageModelV3Prompt): KimiChatPrompt {
+  const messages: KimiChatPrompt = [];
+
+  for (const { role, content } of prompt) {
+    switch (role) {
+      case 'system': {
+        messages.push({ role: 'system', content });
+        break;
+      }
+      case 'user': {
+        if (content.length === 1 && content[0].type === 'text') {
+          messages.push({ role: 'user', content: content[0].text });
+          break;
+        }
+
+        messages.push({
+          role: 'user',
+          content: content.map((part) => {
+            switch (part.type) {
+              case 'text':
+                return { type: 'text' as const, text: part.text };
+              case 'file': {
+                // Handle image files
+                if (isImageMediaType(part.mediaType)) {
+                  return convertImagePart(part);
+                }
+
+                // Handle video files (Kimi K2.5 supports video)
+                if (isVideoMediaType(part.mediaType)) {
+                  return convertVideoPart(part);
+                }
+
+                // Handle text files
+                if (part.mediaType.startsWith('text/')) {
+                  const text =
+                    part.data instanceof URL
+                      ? part.data.toString()
+                      : typeof part.data === 'string'
+                        ? part.data
+                        : new TextDecoder().decode(part.data);
+
+                  return { type: 'text' as const, text };
+                }
+
+                throw new UnsupportedFunctionalityError({
+                  functionality: `file part media type ${part.mediaType}`
+                });
+              }
+              default: {
+                const _exhaustiveCheck: never = part;
+                throw new Error(`Unsupported part type: ${_exhaustiveCheck}`);
+              }
+            }
+          })
+        });
+        break;
+      }
+      case 'assistant': {
+        let text = '';
+        let reasoning = '';
+        const toolCalls: Array<{
+          id: string;
+          type: 'function';
+          function: { name: string; arguments: string };
+        }> = [];
+
+        for (const part of content) {
+          switch (part.type) {
+            case 'text': {
+              text += part.text;
+              break;
+            }
+            case 'reasoning': {
+              reasoning += part.text;
+              break;
+            }
+            case 'tool-call': {
+              toolCalls.push({
+                id: part.toolCallId,
+                type: 'function',
+                function: {
+                  name: part.toolName,
+                  arguments: JSON.stringify(part.input)
+                }
+              });
+              break;
+            }
+            case 'file': {
+              // Assistant file parts are not directly supported by Kimi API
+              // We could convert images to text descriptions, but for now skip
+              break;
+            }
+            case 'tool-result': {
+              // Tool results in assistant messages are unusual but handle gracefully
+              // These would typically be in a 'tool' role message
+              break;
+            }
+            default: {
+              const _exhaustiveCheck: never = part;
+              throw new Error(`Unsupported assistant part: ${_exhaustiveCheck}`);
+            }
+          }
+        }
+
+        messages.push({
+          role: 'assistant',
+          content: text.length > 0 ? text : null,
+          ...(reasoning.length > 0 ? { reasoning_content: reasoning } : {}),
+          ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {})
+        });
+        break;
+      }
+      case 'tool': {
+        for (const toolResponse of content) {
+          if (toolResponse.type === 'tool-approval-response') {
+            continue;
+          }
+
+          messages.push({
+            role: 'tool',
+            tool_call_id: toolResponse.toolCallId,
+            content: serializeToolResult(toolResponse)
+          });
+        }
+        break;
+      }
+      default: {
+        const _exhaustiveCheck: never = role;
+        throw new Error(`Unsupported role: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+
+  return messages;
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function isImageMediaType(mediaType: string): boolean {
+  return mediaType.startsWith('image/') || SUPPORTED_IMAGE_TYPES.includes(mediaType);
+}
+
+function isVideoMediaType(mediaType: string): boolean {
+  return mediaType.startsWith('video/') || SUPPORTED_VIDEO_TYPES.includes(mediaType);
+}
+
+function convertImagePart(part: { mediaType: string; data: URL | Uint8Array | string }): {
+  type: 'image_url';
+  image_url: { url: string };
+} {
+  const mediaType = part.mediaType === 'image/*' ? 'image/jpeg' : part.mediaType;
+
+  const url =
+    part.data instanceof URL ? part.data.toString() : `data:${mediaType};base64,${convertToBase64(part.data)}`;
+
+  return { type: 'image_url', image_url: { url } };
+}
+
+function convertVideoPart(part: { mediaType: string; data: URL | Uint8Array | string }): {
+  type: 'video_url';
+  video_url: { url: string };
+} {
+  // Video must be provided as a URL - base64 inline video is not practical
+  if (!(part.data instanceof URL)) {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'inline video data (video must be provided as a URL)'
+    });
+  }
+
+  return { type: 'video_url', video_url: { url: part.data.toString() } };
+}
+
+function serializeToolResult(toolResponse: LanguageModelV3ToolResultPart): string {
+  const { toolName } = toolResponse;
+  const output = toolResponse.output;
+
+  // For built-in tools like $web_search, just pass through the arguments
+  // The Kimi API expects the tool result to be the same as what was passed
+  if (isBuiltinToolName(toolName)) {
+    return serializeBuiltinToolResult(output);
+  }
+
+  // Standard tool result serialization
+  switch (output.type) {
+    case 'text':
+    case 'error-text':
+      return output.value;
+    case 'execution-denied':
+      return output.reason ?? 'Tool execution denied.';
+    case 'json':
+    case 'error-json':
+    case 'content':
+      return JSON.stringify(output.value);
+    default: {
+      const _exhaustiveCheck: never = output;
+      return JSON.stringify(_exhaustiveCheck);
+    }
+  }
+}
+
+function serializeBuiltinToolResult(output: LanguageModelV3ToolResultPart['output']): string {
+  // For built-in tools, we need to pass through the result as-is
+  // The model expects the arguments it passed to be echoed back
+  switch (output.type) {
+    case 'text':
+    case 'error-text':
+      return output.value;
+    case 'json':
+    case 'error-json':
+    case 'content':
+      return JSON.stringify(output.value);
+    case 'execution-denied':
+      return output.reason ?? 'Tool execution denied.';
+    default: {
+      const _exhaustiveCheck: never = output;
+      return JSON.stringify(_exhaustiveCheck);
+    }
+  }
+}

package/src/chat/kimi-chat-response.ts

@@ -0,0 +1,84 @@
+/**
+ * Response processing utilities for Kimi API.
+ * @module
+ */
+
+import { KIMI_CODE_INTERPRETER_TOOL_NAME, KIMI_WEB_SEARCH_TOOL_NAME } from '../tools';
+
+export type { KimiExtendedUsage, KimiTokenUsage } from '../core';
+export {
+  convertKimiUsage,
+  extractMessageContent,
+  getKimiRequestId,
+  getResponseMetadata,
+  mapKimiFinishReason
+} from '../core';
+
+// ============================================================================
+// Built-in Tool Token Extraction
+// ============================================================================
+
+/**
+ * Tool call structure for token extraction.
+ */
+interface ToolCallForTokens {
+  function: { name: string; arguments?: string | null };
+}
+
+/**
+ * Extract total_tokens from $web_search tool call arguments.
+ * The Kimi API includes usage information in the tool call arguments.
+ *
+ * @param toolCalls - The tool calls from the response
+ * @returns The total web search tokens, or undefined if no web search was used
+ */
+export function extractWebSearchTokens(toolCalls: Array<ToolCallForTokens> | null | undefined): number | undefined {
+  return extractBuiltinToolTokens(toolCalls, KIMI_WEB_SEARCH_TOOL_NAME);
+}
+
+/**
+ * Extract total_tokens from $code tool call arguments.
+ * The Kimi API includes usage information in the tool call arguments.
+ *
+ * @param toolCalls - The tool calls from the response
+ * @returns The total code interpreter tokens, or undefined if no code was executed
+ */
+export function extractCodeInterpreterTokens(
+  toolCalls: Array<ToolCallForTokens> | null | undefined
+): number | undefined {
+  return extractBuiltinToolTokens(toolCalls, KIMI_CODE_INTERPRETER_TOOL_NAME);
+}
+
+/**
+ * Extract tokens from a specific built-in tool.
+ */
+function extractBuiltinToolTokens(
+  toolCalls: Array<ToolCallForTokens> | null | undefined,
+  toolName: string
+): number | undefined {
+  if (!toolCalls) {
+    return undefined;
+  }
+
+  let totalTokens = 0;
+  let foundTool = false;
+
+  for (const toolCall of toolCalls) {
+    if (toolCall.function.name === toolName) {
+      foundTool = true;
+
+      if (toolCall.function.arguments) {
+        try {
+          const args = JSON.parse(toolCall.function.arguments);
+          if (typeof args.total_tokens === 'number') {
+            totalTokens += args.total_tokens;
+          }
+        } catch {
+          // Ignore parse errors
+        }
+      }
+    }
+  }
+
+  return foundTool ? totalTokens : undefined;
+}

package/src/chat/kimi-chat-settings.ts

@@ -0,0 +1,216 @@
+/**
+ * Chat model settings and provider options schema.
+ * @module
+ */
+
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { KimiModelCapabilities } from '../core';
+import type { KimiCodeInterpreterToolOptions, KimiWebSearchToolOptions } from '../tools';
+import { z } from 'zod/v4';
+
+// ============================================================================
+// Re-exports
+// ============================================================================
+
+export type {
+  KimiChatConfig,
+  KimiChatModelId,
+  KimiModelCapabilities
+} from '../core';
+export { inferModelCapabilities } from '../core';
+
+// ============================================================================
+// Context Caching Types
+// ============================================================================
+
+/**
+ * Configuration for context caching.
+ * Enables cost reduction for long, repeated prompts.
+ */
+export interface KimiCachingConfig {
+  /**
+   * Enable context caching for this request.
+   */
+  enabled: boolean;
+
+  /**
+   * Optional cache key for identifying cached context.
+   * Use the same key across requests to hit the same cache.
+   */
+  cacheKey?: string;
+
+  /**
+   * Time-to-live for the cache in seconds.
+   * Defaults to API default (typically 3600 seconds / 1 hour).
+   */
+  ttlSeconds?: number;
+
+  /**
+   * Reset the cache even if a matching cache exists.
+   */
+  resetCache?: boolean;
+}
+
+// ============================================================================
+// Chat Settings
+// ============================================================================
+
+/**
+ * Settings for creating a Kimi chat model instance.
+ */
+export interface KimiChatSettings {
+  /**
+   * Enable JSON schema structured outputs when a schema is provided.
+   */
+  supportsStructuredOutputs?: boolean;
+
+  /**
+   * Request usage metrics during streaming (if supported by the API).
+   */
+  includeUsageInStream?: boolean;
+
+  /**
+   * Override supported URL patterns for file parts.
+   */
+  supportedUrls?: LanguageModelV3['supportedUrls'];
+
+  /**
+   * Enable the built-in web search tool.
+   * When true, Kimi can search the web to answer questions.
+   * You can also pass a configuration object for more control.
+   */
+  webSearch?: boolean | KimiWebSearchToolOptions;
+
+  /**
+   * Enable the built-in code interpreter tool.
+   * When true, Kimi can execute code to solve problems.
+   * You can also pass a configuration object for more control.
+   */
+  codeInterpreter?: boolean | KimiCodeInterpreterToolOptions;
+
+  /**
+   * Override inferred model capabilities.
+   */
+  capabilities?: Partial<KimiModelCapabilities>;
+
+  /**
+   * Enable tool choice polyfill for unsupported tool choice modes.
+   * When true (default), uses system message injection to simulate
+   * `required` and `tool` choices that Kimi doesn't natively support.
+   *
+   * @default true
+   */
+  toolChoicePolyfill?: boolean;
+
+  /**
+   * Enable automatic file handling for experimental_attachments.
+   * When true, PDFs and documents will be automatically uploaded
+   * to Kimi's file API and their content injected into the context.
+   *
+   * @default false
+   */
+  autoFileUpload?: boolean;
+
+  /**
+   * Context caching configuration.
+   * Reduces costs by up to 90% for repeated long prompts.
+   */
+  caching?: boolean | KimiCachingConfig;
+}
+
+// ============================================================================
+// Provider Options Schema
+// ============================================================================
+
+/**
+ * Zod schema for caching configuration.
+ */
+export const kimiCachingConfigSchema = z.object({
+  enabled: z.boolean(),
+  cacheKey: z.string().optional(),
+  ttlSeconds: z.number().optional(),
+  resetCache: z.boolean().optional()
+});
+
+/**
+ * Zod schema for validating provider options passed to individual calls.
+ */
+export const kimiProviderOptionsSchema = z.object({
+  /**
+   * A unique identifier representing your end-user.
+   */
+  user: z.string().optional(),
+
+  /**
+   * Whether to use strict JSON schema validation when supported.
+   */
+  strictJsonSchema: z.boolean().optional(),
+
+  /**
+   * Optional request ID to correlate logs.
+   */
+  requestId: z.string().optional(),
+
+  /**
+   * Optional extra headers for this call.
+   */
+  extraHeaders: z.record(z.string(), z.string()).optional(),
+
+  /**
+   * Whether the provider should allow parallel tool calls.
+   */
+  parallelToolCalls: z.boolean().optional(),
+
+  /**
+   * Enable or configure the built-in web search tool for this request.
+   * This allows Kimi to search the web to help answer questions.
+   */
+  webSearch: z
+    .union([
+      z.boolean(),
+      z.object({
+        enabled: z.boolean(),
+        config: z
+          .object({
+            search_result: z.boolean().optional()
+          })
+          .optional()
+      })
+    ])
+    .optional(),
+
+  /**
+   * Enable or configure the built-in code interpreter tool for this request.
+   * This allows Kimi to execute code to help solve problems.
+   */
+  codeInterpreter: z
+    .union([
+      z.boolean(),
+      z.object({
+        enabled: z.boolean(),
+        config: z
+          .object({
+            timeout: z.number().optional(),
+            include_output: z.boolean().optional()
+          })
+          .optional()
+      })
+    ])
+    .optional(),
+
+  /**
+   * Enable or configure context caching for this request.
+   * Reduces costs for repeated long prompts.
+   */
+  caching: z.union([z.boolean(), kimiCachingConfigSchema]).optional(),
+
+  /**
+   * Enable tool choice polyfill for this request.
+   */
+  toolChoicePolyfill: z.boolean().optional()
+});
+
+/**
+ * Type for provider options passed to individual calls.
+ */
+export type KimiProviderOptions = z.infer<typeof kimiProviderOptionsSchema>;

package/src/code/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Kimi Code module - Premium coding service with extended thinking support.
+ *
+ * @remarks
+ * Kimi Code provides high-speed coding assistance (up to 100 tokens/s)
+ * with full compatibility for Claude Code and Roo Code agents.
+ *
+ * **Quick Start:**
+ * ```ts
+ * import { kimiCode } from 'kimi-vercel-ai-sdk-provider
+';
+ *
+ * const result = await generateText({
+ *   model: kimiCode(), // Uses 'kimi-for-coding' by default
+ *   prompt: 'Write a function to merge sorted arrays',
+ * });
+ * ```
+ *
+ * @see https://www.kimi.com/code/docs/en/
+ * @module
+ */
+
+// Messages
+export type { KimiCodeContentPart, KimiCodeMessage, KimiCodePrompt } from './kimi-code-messages';
+// Provider
+export type { KimiCodeProvider, KimiCodeProviderSettings } from './kimi-code-provider';
+// Settings
+export type { KimiCodeProviderOptions, KimiCodeSettings } from './kimi-code-settings';
+// Types
+export type {
+  ExtendedThinkingConfig,
+  KimiCodeCapabilities,
+  KimiCodeConfig,
+  KimiCodeContentBlock,
+  KimiCodeDeltaType,
+  KimiCodeModelId,
+  KimiCodeResponseMetadata,
+  KimiCodeStopReason,
+  KimiCodeStreamEventType,
+  KimiCodeTextBlock,
+  KimiCodeThinkingBlock,
+  KimiCodeTokenUsage,
+  KimiCodeToolUseBlock,
+  ReasoningEffort
+} from './kimi-code-types';
+// Language Model
+export { KimiCodeLanguageModel } from './kimi-code-language-model';
+export { convertToKimiCodePrompt } from './kimi-code-messages';
+export { createKimiCode, kimiCode } from './kimi-code-provider';
+export {
+  effortToBudgetTokens,
+  kimiCodeProviderOptionsSchema,
+  normalizeExtendedThinkingConfig,
+  toAnthropicThinking
+} from './kimi-code-settings';
+export {
+  KIMI_CODE_ANTHROPIC_VERSION,
+  KIMI_CODE_BASE_URL,
+  KIMI_CODE_DEFAULT_CONTEXT_WINDOW,
+  KIMI_CODE_DEFAULT_MAX_TOKENS,
+  KIMI_CODE_DEFAULT_MODEL,
+  KIMI_CODE_MODELS,
+  KIMI_CODE_OPENAI_BASE_URL,
+  KIMI_CODE_THINKING_MODEL,
+  inferKimiCodeCapabilities
+} from './kimi-code-types';