kimi-vercel-ai-sdk-provider 0.2.0

package/src/core/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Core module exports.
+ * @module
+ */
+
+export type { KimiErrorData } from './errors';
+// Types
+export type {
+  KimiChatConfig,
+  KimiChatModelId,
+  KimiModelCapabilities,
+  KimiResponseMetadata,
+  KimiTokenUsage
+} from './types';
+// Utilities
+export type { KimiExtendedUsage } from './utils';
+// Errors
+export {
+  KimiAuthenticationError,
+  KimiContentFilterError,
+  KimiContextLengthError,
+  KimiError,
+  KimiModelNotFoundError,
+  KimiRateLimitError,
+  KimiValidationError,
+  kimiErrorSchema,
+  kimiFailedResponseHandler
+} from './errors';
+export { inferModelCapabilities } from './types';
+export {
+  convertKimiUsage,
+  extractMessageContent,
+  getKimiRequestId,
+  getResponseMetadata,
+  mapKimiFinishReason
+} from './utils';

package/src/core/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Core types for the Kimi provider.
+ * @module
+ */
+
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+
+// ============================================================================
+// Model IDs
+// ============================================================================
+
+/**
+ * Available Kimi chat model IDs.
+ *
+ * @remarks
+ * - `kimi-k2.5` - Latest flagship model with multimodal support
+ * - `kimi-k2.5-thinking` - K2.5 with always-on deep reasoning
+ * - `kimi-k2-turbo` - Fast, cost-effective model
+ * - `kimi-k2-thinking` - K2 with always-on deep reasoning
+ */
+export type KimiChatModelId = 'kimi-k2.5' | 'kimi-k2.5-thinking' | 'kimi-k2-turbo' | 'kimi-k2-thinking' | (string & {});
+
+// ============================================================================
+// Model Capabilities
+// ============================================================================
+
+/**
+ * Capabilities that can be detected from model ID patterns or explicitly set.
+ */
+export interface KimiModelCapabilities {
+  /**
+   * Whether the model supports thinking/reasoning mode.
+   * Models with `-thinking` suffix have this enabled by default.
+   */
+  thinking?: boolean;
+
+  /**
+   * Whether the model always uses thinking mode (cannot be disabled).
+   * Thinking models like `kimi-k2.5-thinking` have this set to true.
+   */
+  alwaysThinking?: boolean;
+
+  /**
+   * Whether the model supports image inputs.
+   */
+  imageInput?: boolean;
+
+  /**
+   * Whether the model supports video inputs.
+   * Currently only kimi-k2.5 models support video.
+   */
+  videoInput?: boolean;
+
+  /**
+   * Maximum context window size in tokens.
+   */
+  maxContextSize?: number;
+
+  /**
+   * Whether the model supports tool/function calling.
+   */
+  toolCalling?: boolean;
+
+  /**
+   * Whether the model supports JSON mode.
+   */
+  jsonMode?: boolean;
+
+  /**
+   * Whether the model supports structured outputs.
+   */
+  structuredOutputs?: boolean;
+}
+
+/**
+ * Infer model capabilities from the model ID.
+ *
+ * @param modelId - The model identifier
+ * @returns Inferred capabilities based on model name patterns
+ *
+ * @example
+ * ```ts
+ * const caps = inferModelCapabilities('kimi-k2.5-thinking');
+ * // { thinking: true, alwaysThinking: true, videoInput: true, ... }
+ * ```
+ */
+export function inferModelCapabilities(modelId: string): KimiModelCapabilities {
+  const isThinkingModel = modelId.includes('-thinking');
+  const isK25Model = modelId.includes('k2.5') || modelId.includes('k2-5');
+
+  return {
+    thinking: isThinkingModel,
+    alwaysThinking: isThinkingModel,
+    imageInput: true, // All Kimi models support images
+    videoInput: isK25Model, // Only K2.5 models support video
+    maxContextSize: 256_000, // 256k context window
+    toolCalling: true,
+    jsonMode: true,
+    structuredOutputs: true
+  };
+}
+
+// ============================================================================
+// Provider Configuration
+// ============================================================================
+
+/**
+ * Configuration for the chat language model.
+ * @internal
+ */
+export interface KimiChatConfig {
+  provider: string;
+  baseURL: string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: typeof globalThis.fetch;
+  generateId?: () => string;
+  supportsStructuredOutputs?: boolean;
+  includeUsageInStream?: boolean;
+  supportedUrls?: LanguageModelV3['supportedUrls'];
+}
+
+// ============================================================================
+// API Response Types
+// ============================================================================
+
+/**
+ * Token usage information from Kimi API.
+ */
+export interface KimiTokenUsage {
+  prompt_tokens?: number | null;
+  completion_tokens?: number | null;
+  total_tokens?: number | null;
+  prompt_tokens_details?: {
+    cached_tokens?: number | null;
+  } | null;
+  completion_tokens_details?: {
+    reasoning_tokens?: number | null;
+  } | null;
+}
+
+/**
+ * Response metadata from Kimi API.
+ */
+export interface KimiResponseMetadata {
+  id?: string | null;
+  model?: string | null;
+  created?: number | null;
+}

package/src/core/utils.ts

@@ -0,0 +1,210 @@
+/**
+ * Utility functions for the Kimi provider.
+ * @module
+ */
+
+import type { JSONObject, LanguageModelV3FinishReason, LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { KimiResponseMetadata, KimiTokenUsage } from './types';
+
+// ============================================================================
+// Finish Reason Mapping
+// ============================================================================
+
+/**
+ * Map Kimi finish reasons to standard AI SDK finish reasons.
+ *
+ * @param finishReason - The raw finish reason from Kimi API
+ * @returns The mapped unified finish reason
+ */
+export function mapKimiFinishReason(finishReason: string | null | undefined): LanguageModelV3FinishReason['unified'] {
+  switch (finishReason) {
+    case 'stop':
+      return 'stop';
+    case 'length':
+      return 'length';
+    case 'content_filter':
+      return 'content-filter';
+    case 'tool_calls':
+    case 'function_call':
+      return 'tool-calls';
+    default:
+      return 'other';
+  }
+}
+
+// ============================================================================
+// Usage Conversion
+// ============================================================================
+
+/**
+ * Extended usage information including web search and code interpreter tokens.
+ */
+export interface KimiExtendedUsage extends LanguageModelV3Usage {
+  /**
+   * Tokens used by the built-in web search tool.
+   */
+  webSearchTokens?: number;
+
+  /**
+   * Tokens used by the built-in code interpreter.
+   */
+  codeInterpreterTokens?: number;
+}
+
+/**
+ * Convert Kimi usage data to standard AI SDK usage format.
+ *
+ * @param usage - The raw usage data from Kimi API
+ * @param webSearchTokens - Optional web search token count
+ * @param codeInterpreterTokens - Optional code interpreter token count
+ * @returns Standardized usage object
+ */
+export function convertKimiUsage(
+  usage: KimiTokenUsage | null | undefined,
+  webSearchTokens?: number,
+  codeInterpreterTokens?: number
+): KimiExtendedUsage {
+  if (usage == null) {
+    return {
+      inputTokens: {
+        total: undefined,
+        noCache: undefined,
+        cacheRead: undefined,
+        cacheWrite: undefined
+      },
+      outputTokens: {
+        total: undefined,
+        text: undefined,
+        reasoning: undefined
+      },
+      raw: undefined,
+      ...(webSearchTokens != null ? { webSearchTokens } : {}),
+      ...(codeInterpreterTokens != null ? { codeInterpreterTokens } : {})
+    };
+  }
+
+  const promptTokens = usage.prompt_tokens ?? 0;
+  const completionTokens = usage.completion_tokens ?? 0;
+  const cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? 0;
+  const reasoningTokens = usage.completion_tokens_details?.reasoning_tokens ?? 0;
+
+  // Convert to JSONObject for the raw field
+  const rawUsage: JSONObject = {
+    prompt_tokens: usage.prompt_tokens ?? undefined,
+    completion_tokens: usage.completion_tokens ?? undefined,
+    total_tokens: usage.total_tokens ?? undefined,
+    ...(usage.prompt_tokens_details
+      ? {
+          prompt_tokens_details: {
+            cached_tokens: usage.prompt_tokens_details.cached_tokens ?? undefined
+          }
+        }
+      : {}),
+    ...(usage.completion_tokens_details
+      ? {
+          completion_tokens_details: {
+            reasoning_tokens: usage.completion_tokens_details.reasoning_tokens ?? undefined
+          }
+        }
+      : {})
+  };
+
+  return {
+    inputTokens: {
+      total: promptTokens,
+      noCache: promptTokens - cacheReadTokens,
+      cacheRead: cacheReadTokens,
+      cacheWrite: undefined
+    },
+    outputTokens: {
+      total: completionTokens,
+      text: completionTokens - reasoningTokens,
+      reasoning: reasoningTokens
+    },
+    raw: rawUsage,
+    ...(webSearchTokens != null ? { webSearchTokens } : {}),
+    ...(codeInterpreterTokens != null ? { codeInterpreterTokens } : {})
+  };
+}
+
+// ============================================================================
+// Response Metadata
+// ============================================================================
+
+/**
+ * Extract response metadata from Kimi API response.
+ *
+ * @param response - The raw response metadata
+ * @returns Formatted response metadata
+ */
+export function getResponseMetadata(response: KimiResponseMetadata) {
+  return {
+    id: response.id ?? undefined,
+    modelId: response.model ?? undefined,
+    timestamp: response.created != null ? new Date(response.created * 1000) : undefined
+  };
+}
+
+/**
+ * Extract request ID from response headers.
+ *
+ * @param headers - Response headers
+ * @returns The request ID if found
+ */
+export function getKimiRequestId(headers?: Record<string, string>): string | undefined {
+  if (!headers) {
+    return undefined;
+  }
+
+  const lowerHeaders = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+
+  return lowerHeaders['x-request-id'] || lowerHeaders['x-trace-id'] || lowerHeaders['x-moonshot-request-id'];
+}
+
+// ============================================================================
+// Message Content Extraction
+// ============================================================================
+
+/**
+ * Extract text and reasoning content from a message.
+ *
+ * @param message - The message object from API response
+ * @returns Extracted text and reasoning content
+ */
+export function extractMessageContent(message: {
+  content?: unknown;
+  reasoning_content?: string | null;
+  reasoning?: string | null;
+}): { text: string; reasoning: string } {
+  let text = '';
+  let reasoning = '';
+
+  if (typeof message.content === 'string') {
+    text = message.content;
+  } else if (Array.isArray(message.content)) {
+    for (const part of message.content) {
+      if (part && typeof part === 'object') {
+        const candidate = part as Record<string, unknown>;
+        if (candidate.type === 'text' && typeof candidate.text === 'string') {
+          text += candidate.text;
+        }
+        if (candidate.type === 'thinking' && typeof candidate.thinking === 'string') {
+          reasoning += candidate.thinking;
+        }
+        if (candidate.type === 'reasoning' && typeof candidate.text === 'string') {
+          reasoning += candidate.text;
+        }
+      }
+    }
+  }
+
+  if (typeof message.reasoning_content === 'string') {
+    reasoning += message.reasoning_content;
+  }
+
+  if (typeof message.reasoning === 'string') {
+    reasoning += message.reasoning;
+  }
+
+  return { text, reasoning };
+}

package/src/files/attachment-processor.ts

@@ -0,0 +1,276 @@
+/**
+ * Attachment processor for experimental_attachments support.
+ * Automatically uploads files to Kimi and injects content into prompts.
+ * @module
+ */
+
+import {
+  getExtensionFromPath,
+  getMediaTypeFromExtension,
+  isDocumentMediaType,
+  isFileExtractMediaType,
+  isImageMediaType,
+  isVideoMediaType
+} from './file-utils';
+import { KimiFileClient, type KimiFileClientConfig } from './kimi-file-client';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * An attachment from experimental_attachments.
+ */
+export interface Attachment {
+  /** URL of the attachment */
+  url?: string;
+  /** Name of the attachment */
+  name?: string;
+  /** MIME type */
+  contentType?: string;
+  /** Raw content data */
+  content?: Uint8Array | string;
+}
+
+/**
+ * Processed attachment result.
+ */
+export interface ProcessedAttachment {
+  /** Original attachment */
+  original: Attachment;
+  /** Processing type */
+  type: 'text-inject' | 'image-url' | 'video-url' | 'skip';
+  /** Extracted text content (for documents) */
+  textContent?: string;
+  /** URL to use in message (for images/videos) */
+  mediaUrl?: string;
+  /** Kimi file ID (if uploaded) */
+  fileId?: string;
+  /** Error if processing failed */
+  error?: string;
+}
+
+/**
+ * Options for processing attachments.
+ */
+export interface ProcessAttachmentsOptions {
+  /** Attachments to process */
+  attachments: Attachment[];
+  /** File client configuration */
+  clientConfig: KimiFileClientConfig;
+  /** Whether to auto-upload documents for extraction */
+  autoUploadDocuments?: boolean;
+  /** Whether to upload images to Kimi's file API */
+  uploadImages?: boolean;
+  /** Whether to delete files after extraction (cleanup) */
+  cleanupAfterExtract?: boolean;
+}
+
+// ============================================================================
+// Main Function
+// ============================================================================
+
+/**
+ * Process experimental_attachments for Kimi.
+ *
+ * This function handles different attachment types:
+ * - Documents (PDF, DOC, etc.): Uploads to Kimi, extracts content, returns text to inject
+ * - Images: Returns URL for vision input
+ * - Videos: Returns URL for video input
+ *
+ * @example
+ * ```ts
+ * const processed = await processAttachments({
+ *   attachments: message.experimental_attachments ?? [],
+ *   clientConfig: {
+ *     baseURL: 'https://api.moonshot.ai/v1',
+ *     headers: () => ({ Authorization: `Bearer ${apiKey}` }),
+ *   },
+ * });
+ *
+ * // Inject document content into system messages
+ * const documentContent = processed
+ *   .filter(p => p.type === 'text-inject' && p.textContent)
+ *   .map(p => p.textContent)
+ *   .join('\n');
+ * ```
+ */
+export async function processAttachments(options: ProcessAttachmentsOptions): Promise<ProcessedAttachment[]> {
+  const {
+    attachments,
+    clientConfig,
+    autoUploadDocuments = true,
+    uploadImages = false,
+    cleanupAfterExtract = false
+  } = options;
+
+  const results: ProcessedAttachment[] = [];
+  const client = new KimiFileClient(clientConfig);
+
+  for (const attachment of attachments) {
+    try {
+      const processed = await processAttachment(attachment, client, {
+        autoUploadDocuments,
+        uploadImages,
+        cleanupAfterExtract
+      });
+      results.push(processed);
+    } catch (error) {
+      results.push({
+        original: attachment,
+        type: 'skip',
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return results;
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+async function processAttachment(
+  attachment: Attachment,
+  client: KimiFileClient,
+  options: { autoUploadDocuments: boolean; uploadImages: boolean; cleanupAfterExtract: boolean }
+): Promise<ProcessedAttachment> {
+  // Determine content type
+  const contentType = resolveContentType(attachment);
+
+  // Handle images - just return URL for vision
+  if (isImageMediaType(contentType)) {
+    if (options.uploadImages && attachment.content) {
+      // Upload image if content is provided
+      const result = await client.upload({
+        data: attachment.content,
+        filename: attachment.name ?? 'image.jpg',
+        mediaType: contentType,
+        purpose: 'image'
+      });
+
+      return {
+        original: attachment,
+        type: 'image-url',
+        fileId: result.id,
+        mediaUrl: attachment.url
+      };
+    }
+
+    return {
+      original: attachment,
+      type: 'image-url',
+      mediaUrl: attachment.url
+    };
+  }
+
+  // Handle videos - just return URL for video understanding
+  if (isVideoMediaType(contentType)) {
+    return {
+      original: attachment,
+      type: 'video-url',
+      mediaUrl: attachment.url
+    };
+  }
+
+  // Handle documents that need extraction
+  if (options.autoUploadDocuments && (isDocumentMediaType(contentType) || isFileExtractMediaType(contentType))) {
+    // Need to fetch content if only URL is provided
+    let data: Uint8Array | string;
+
+    if (attachment.content) {
+      data = attachment.content;
+    } else if (attachment.url) {
+      // Fetch the file from URL
+      const response = await fetch(attachment.url);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch attachment: ${response.status}`);
+      }
+      data = new Uint8Array(await response.arrayBuffer());
+    } else {
+      return {
+        original: attachment,
+        type: 'skip',
+        error: 'No content or URL provided for document attachment'
+      };
+    }
+
+    // Upload and extract content
+    const result = await client.uploadAndExtract({
+      data,
+      filename: attachment.name ?? guessFilename(attachment, contentType),
+      mediaType: contentType,
+      purpose: 'file-extract'
+    });
+
+    // Cleanup if requested
+    if (options.cleanupAfterExtract && result.file.id) {
+      try {
+        await client.deleteFile(result.file.id);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+
+    return {
+      original: attachment,
+      type: 'text-inject',
+      textContent: result.content,
+      fileId: result.file.id
+    };
+  }
+
+  // Skip unsupported types
+  return {
+    original: attachment,
+    type: 'skip',
+    error: `Unsupported content type: ${contentType}`
+  };
+}
+
+function resolveContentType(attachment: Attachment): string {
+  // Use explicit content type if provided
+  if (attachment.contentType) {
+    return attachment.contentType;
+  }
+
+  // Try to infer from filename or URL
+  const path = attachment.name ?? attachment.url;
+  if (path) {
+    const ext = getExtensionFromPath(path);
+    if (ext) {
+      return getMediaTypeFromExtension(ext);
+    }
+  }
+
+  // Default to octet-stream
+  return 'application/octet-stream';
+}
+
+function guessFilename(attachment: Attachment, contentType: string): string {
+  if (attachment.name) {
+    return attachment.name;
+  }
+
+  if (attachment.url) {
+    const urlPath = attachment.url.split('?')[0];
+    const segments = urlPath.split('/');
+    const lastSegment = segments[segments.length - 1];
+    if (lastSegment && lastSegment.includes('.')) {
+      return lastSegment;
+    }
+  }
+
+  // Generate filename from content type
+  const extensionMap: Record<string, string> = {
+    'application/pdf': 'document.pdf',
+    'text/plain': 'document.txt',
+    'application/msword': 'document.doc',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'document.docx',
+    'image/jpeg': 'image.jpg',
+    'image/png': 'image.png'
+  };
+
+  return extensionMap[contentType] ?? 'file.bin';
+}