kimi-vercel-ai-sdk-provider 0.3.0 → 0.4.0

package/src/chat/kimi-chat-language-model.ts

@@ -205,11 +205,30 @@ export class KimiChatLanguageModel implements LanguageModelV3 {
       messages.unshift({ role: 'system', content: toolChoiceSystemMessage });
     }
 
+    // Apply model-specific defaults and constraints
+    const caps = this.capabilities;
+
+    // Resolve temperature: thinking models require locked temperature
+    let resolvedTemperature = temperature;
+    if (caps.temperatureLocked && caps.defaultTemperature !== undefined) {
+      if (temperature !== undefined && temperature !== caps.defaultTemperature) {
+        warnings.push({
+          type: 'compatibility',
+          feature: 'temperature',
+          details: `Thinking models require temperature=${caps.defaultTemperature}. Your value (${temperature}) will be overridden.`
+        });
+      }
+      resolvedTemperature = caps.defaultTemperature;
+    }
+
+    // Resolve max_tokens: use model default if not specified
+    const resolvedMaxTokens = maxOutputTokens ?? caps.defaultMaxOutputTokens;
+
     const body = removeUndefinedEntries({
       model: this.modelId,
       messages,
-      max_tokens: maxOutputTokens,
-      temperature,
+      max_tokens: resolvedMaxTokens,
+      temperature: resolvedTemperature,
       top_p: topP,
       frequency_penalty: frequencyPenalty,
       presence_penalty: presencePenalty,

package/src/core/index.ts

@@ -13,7 +13,7 @@ export type {
   KimiTokenUsage
 } from './types';
 // Utilities
-export type { KimiExtendedUsage } from './utils';
+export type { KimiExtendedUsage, ReasoningAnalysis } from './utils';
 // Errors
 export {
   KimiAuthenticationError,
@@ -26,11 +26,18 @@ export {
   kimiErrorSchema,
   kimiFailedResponseHandler
 } from './errors';
-export { inferModelCapabilities } from './types';
 export {
+  STANDARD_MODEL_DEFAULT_MAX_TOKENS,
+  THINKING_MODEL_DEFAULT_MAX_TOKENS,
+  THINKING_MODEL_TEMPERATURE,
+  inferModelCapabilities
+} from './types';
+export {
+  analyzeReasoningPreservation,
   convertKimiUsage,
   extractMessageContent,
   getKimiRequestId,
   getResponseMetadata,
-  mapKimiFinishReason
+  mapKimiFinishReason,
+  recommendThinkingModel
 } from './utils';

package/src/core/types.ts

@@ -70,18 +70,68 @@ export interface KimiModelCapabilities {
    * Whether the model supports structured outputs.
    */
   structuredOutputs?: boolean;
+
+  /**
+   * Default temperature for the model.
+   * Thinking models require temperature=1.0 for optimal reasoning.
+   */
+  defaultTemperature?: number;
+
+  /**
+   * Whether temperature is locked (cannot be changed).
+   * Thinking models have this set to true.
+   */
+  temperatureLocked?: boolean;
+
+  /**
+   * Default max output tokens for the model.
+   * Thinking models need higher limits to avoid truncated reasoning.
+   */
+  defaultMaxOutputTokens?: number;
 }
 
+/**
+ * Default temperature for thinking models.
+ * Kimi thinking models require temperature=1.0 for optimal reasoning quality.
+ */
+export const THINKING_MODEL_TEMPERATURE = 1.0;
+
+/**
+ * Default max output tokens for thinking models.
+ * Higher limit ensures reasoning traces aren't truncated.
+ */
+export const THINKING_MODEL_DEFAULT_MAX_TOKENS = 32768;
+
+/**
+ * Default max output tokens for standard models.
+ */
+export const STANDARD_MODEL_DEFAULT_MAX_TOKENS = 4096;
+
 /**
  * Infer model capabilities from the model ID.
  *
  * @param modelId - The model identifier
  * @returns Inferred capabilities based on model name patterns
  *
+ * @remarks
+ * This function automatically detects model capabilities and sets
+ * appropriate defaults:
+ * - Thinking models (`-thinking` suffix) get temperature=1.0 locked
+ * - Thinking models get 32k default max_tokens to avoid truncation
+ * - K2.5 models get video input support
+ *
  * @example
  * ```ts
  * const caps = inferModelCapabilities('kimi-k2.5-thinking');
- * // { thinking: true, alwaysThinking: true, videoInput: true, ... }
+ * // {
+ * //   thinking: true,
+ * //   alwaysThinking: true,
+ * //   videoInput: true,
+ * //   temperatureLocked: true,
+ * //   defaultTemperature: 1.0,
+ * //   defaultMaxOutputTokens: 32768,
+ * //   ...
+ * // }
  * ```
  */
 export function inferModelCapabilities(modelId: string): KimiModelCapabilities {
@@ -96,7 +146,12 @@ export function inferModelCapabilities(modelId: string): KimiModelCapabilities {
     maxContextSize: 256_000, // 256k context window
     toolCalling: true,
     jsonMode: true,
-    structuredOutputs: true
+    structuredOutputs: true,
+    // Thinking models require temperature=1.0 for optimal reasoning
+    defaultTemperature: isThinkingModel ? THINKING_MODEL_TEMPERATURE : undefined,
+    temperatureLocked: isThinkingModel,
+    // Thinking models need higher token limits to avoid truncated reasoning
+    defaultMaxOutputTokens: isThinkingModel ? THINKING_MODEL_DEFAULT_MAX_TOKENS : STANDARD_MODEL_DEFAULT_MAX_TOKENS
   };
 }
 

package/src/core/utils.ts

@@ -208,3 +208,141 @@ export function extractMessageContent(message: {
 
   return { text, reasoning };
 }
+
+// ============================================================================
+// Multi-turn Reasoning Utilities
+// ============================================================================
+
+/**
+ * Information about reasoning content in a conversation.
+ */
+export interface ReasoningAnalysis {
+  /** Total number of messages with reasoning content */
+  messagesWithReasoning: number;
+  /** Total reasoning tokens (estimated by character count / 4) */
+  estimatedReasoningTokens: number;
+  /** Whether reasoning is properly preserved in the conversation */
+  isPreserved: boolean;
+  /** Messages that are missing expected reasoning content */
+  missingReasoningIndices: number[];
+}
+
+/**
+ * Analyze reasoning content preservation in a conversation.
+ *
+ * This utility helps verify that reasoning content is being properly
+ * preserved across multi-turn conversations with thinking models.
+ * Kimi requires reasoning content to be maintained in the message
+ * history for logical continuity in agentic/tool-calling scenarios.
+ *
+ * @param messages - Array of messages to analyze
+ * @returns Analysis of reasoning preservation
+ *
+ * @example
+ * ```ts
+ * const analysis = analyzeReasoningPreservation(messages);
+ * if (!analysis.isPreserved) {
+ *   console.warn('Reasoning content missing from messages:', analysis.missingReasoningIndices);
+ * }
+ * ```
+ */
+export function analyzeReasoningPreservation(
+  messages: Array<{
+    role: string;
+    content?: unknown;
+    reasoning_content?: string | null;
+    reasoning?: string | null;
+  }>
+): ReasoningAnalysis {
+  let messagesWithReasoning = 0;
+  let totalReasoningChars = 0;
+  const missingReasoningIndices: number[] = [];
+
+  // Track whether we've seen a tool call that should have reasoning preserved
+  let expectReasoningAfterToolCall = false;
+
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i];
+
+    if (message.role === 'assistant') {
+      const { reasoning } = extractMessageContent(message);
+
+      if (reasoning.length > 0) {
+        messagesWithReasoning++;
+        totalReasoningChars += reasoning.length;
+        expectReasoningAfterToolCall = false;
+      } else if (expectReasoningAfterToolCall) {
+        // This assistant message should have reasoning from the previous turn
+        missingReasoningIndices.push(i);
+      }
+
+      // Check if this message has tool calls
+      if ('tool_calls' in message && Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
+        expectReasoningAfterToolCall = true;
+      }
+    } else if (message.role === 'tool') {
+      // After a tool response, we expect the next assistant message to potentially have reasoning
+      expectReasoningAfterToolCall = true;
+    }
+  }
+
+  return {
+    messagesWithReasoning,
+    estimatedReasoningTokens: Math.ceil(totalReasoningChars / 4),
+    isPreserved: missingReasoningIndices.length === 0,
+    missingReasoningIndices
+  };
+}
+
+/**
+ * Check if a conversation is suitable for thinking models.
+ *
+ * Thinking models work best with:
+ * - Complex reasoning tasks
+ * - Multi-step problem solving
+ * - Tasks requiring chain-of-thought
+ *
+ * This helper provides guidance on whether a thinking model would benefit
+ * the conversation.
+ *
+ * @param messageCount - Number of messages in the conversation
+ * @param hasToolCalls - Whether the conversation includes tool calls
+ * @param estimatedComplexity - Estimated task complexity (0-1)
+ * @returns Recommendation on using thinking models
+ */
+export function recommendThinkingModel(
+  messageCount: number,
+  hasToolCalls: boolean,
+  estimatedComplexity: number
+): { recommended: boolean; reason: string } {
+  // Thinking models are recommended for:
+  // 1. Complex tasks (complexity > 0.5)
+  // 2. Agentic scenarios with tool calls
+  // 3. Multi-turn conversations where reasoning continuity matters
+
+  if (estimatedComplexity > 0.7) {
+    return {
+      recommended: true,
+      reason: 'High complexity task benefits from extended reasoning'
+    };
+  }
+
+  if (hasToolCalls && messageCount > 2) {
+    return {
+      recommended: true,
+      reason: 'Multi-turn tool usage benefits from reasoning preservation'
+    };
+  }
+
+  if (estimatedComplexity > 0.5) {
+    return {
+      recommended: true,
+      reason: 'Moderate complexity may benefit from reasoning'
+    };
+  }
+
+  return {
+    recommended: false,
+    reason: 'Standard model sufficient for this task'
+  };
+}

package/src/files/attachment-processor.ts

@@ -4,6 +4,7 @@
  * @module
  */
 
+import { type FileCache, type FileCacheEntry, generateCacheKey, getDefaultFileCache } from './file-cache';
 import {
   getExtensionFromPath,
   getMediaTypeFromExtension,
@@ -64,6 +65,13 @@ export interface ProcessAttachmentsOptions {
   uploadImages?: boolean;
   /** Whether to delete files after extraction (cleanup) */
   cleanupAfterExtract?: boolean;
+  /**
+   * Enable caching of uploaded files.
+   * When true, uses the default global cache.
+   * When a FileCache instance, uses that cache.
+   * @default false
+   */
+  cache?: boolean | FileCache;
 }
 
 // ============================================================================
@@ -101,9 +109,13 @@ export async function processAttachments(options: ProcessAttachmentsOptions): Pr
     clientConfig,
     autoUploadDocuments = true,
     uploadImages = false,
-    cleanupAfterExtract = false
+    cleanupAfterExtract = false,
+    cache = false
   } = options;
 
+  // Resolve cache instance
+  const cacheInstance = cache === true ? getDefaultFileCache() : cache === false ? null : cache;
+
   const results: ProcessedAttachment[] = [];
   const client = new KimiFileClient(clientConfig);
 
@@ -112,7 +124,8 @@ export async function processAttachments(options: ProcessAttachmentsOptions): Pr
       const processed = await processAttachment(attachment, client, {
         autoUploadDocuments,
         uploadImages,
-        cleanupAfterExtract
+        cleanupAfterExtract,
+        cache: cacheInstance
       });
       results.push(processed);
     } catch (error) {
@@ -134,7 +147,12 @@ export async function processAttachments(options: ProcessAttachmentsOptions): Pr
 async function processAttachment(
   attachment: Attachment,
   client: KimiFileClient,
-  options: { autoUploadDocuments: boolean; uploadImages: boolean; cleanupAfterExtract: boolean }
+  options: {
+    autoUploadDocuments: boolean;
+    uploadImages: boolean;
+    cleanupAfterExtract: boolean;
+    cache: FileCache | null;
+  }
 ): Promise<ProcessedAttachment> {
   // Determine content type
   const contentType = resolveContentType(attachment);
@@ -196,14 +214,43 @@ async function processAttachment(
       };
     }
 
+    const filename = attachment.name ?? guessFilename(attachment, contentType);
+
+    // Check cache if enabled
+    if (options.cache) {
+      const cacheKey = generateCacheKey(data, filename);
+      const cached = options.cache.get(cacheKey);
+
+      if (cached) {
+        return {
+          original: attachment,
+          type: 'text-inject',
+          textContent: cached.content,
+          fileId: cached.fileId
+        };
+      }
+    }
+
     // Upload and extract content
     const result = await client.uploadAndExtract({
       data,
-      filename: attachment.name ?? guessFilename(attachment, contentType),
+      filename,
       mediaType: contentType,
       purpose: 'file-extract'
     });
 
+    // Store in cache if enabled (before cleanup)
+    if (options.cache && result.content) {
+      const cacheKey = generateCacheKey(data, filename);
+      const cacheEntry: FileCacheEntry = {
+        fileId: result.file.id,
+        content: result.content,
+        createdAt: Date.now(),
+        purpose: 'file-extract'
+      };
+      options.cache.set(cacheKey, cacheEntry);
+    }
+
     // Cleanup if requested
     if (options.cleanupAfterExtract && result.file.id) {
       try {

package/src/files/file-cache.ts

@@ -0,0 +1,260 @@
+/**
+ * File content caching for efficient re-use of uploaded files.
+ * @module
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Entry in the file cache.
+ */
+export interface FileCacheEntry {
+  /** The Kimi file ID */
+  fileId: string;
+  /** Extracted text content (for documents) */
+  content?: string;
+  /** Unix timestamp of creation */
+  createdAt: number;
+  /** File purpose */
+  purpose: 'file-extract' | 'image' | 'video';
+}
+
+/**
+ * Options for configuring the file cache.
+ */
+export interface FileCacheOptions {
+  /**
+   * Maximum number of entries in the cache.
+   * When exceeded, least recently used entries are evicted.
+   * @default 100
+   */
+  maxSize?: number;
+
+  /**
+   * Time-to-live for cache entries in milliseconds.
+   * Entries older than this are considered stale.
+   * @default 3600000 (1 hour)
+   */
+  ttlMs?: number;
+}
+
+// ============================================================================
+// LRU Cache Implementation
+// ============================================================================
+
+/**
+ * A simple LRU (Least Recently Used) cache for file content.
+ *
+ * This cache helps avoid re-uploading the same files multiple times
+ * by storing the mapping between content hashes and Kimi file IDs.
+ *
+ * @example
+ * ```ts
+ * const cache = new FileCache({ maxSize: 50, ttlMs: 30 * 60 * 1000 });
+ *
+ * // Check if we have this file cached
+ * const cached = cache.get(contentHash);
+ * if (cached) {
+ *   console.log('Using cached file:', cached.fileId);
+ * }
+ *
+ * // Store a new file
+ * cache.set(contentHash, {
+ *   fileId: 'file_abc123',
+ *   content: 'extracted text...',
+ *   purpose: 'file-extract',
+ *   createdAt: Date.now()
+ * });
+ * ```
+ */
+export class FileCache {
+  private readonly maxSize: number;
+  private readonly ttlMs: number;
+  private readonly cache: Map<string, FileCacheEntry>;
+
+  constructor(options: FileCacheOptions = {}) {
+    this.maxSize = options.maxSize ?? 100;
+    this.ttlMs = options.ttlMs ?? 3600000; // 1 hour
+    this.cache = new Map();
+  }
+
+  /**
+   * Get a cached entry by content hash.
+   * Returns undefined if not found or expired.
+   * Moves the entry to the end (most recently used).
+   */
+  get(contentHash: string): FileCacheEntry | undefined {
+    const entry = this.cache.get(contentHash);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    // Check if entry has expired
+    if (this.isExpired(entry)) {
+      this.cache.delete(contentHash);
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(contentHash);
+    this.cache.set(contentHash, entry);
+
+    return entry;
+  }
+
+  /**
+   * Set a cache entry.
+   * Evicts the least recently used entry if cache is full.
+   */
+  set(contentHash: string, entry: FileCacheEntry): void {
+    // Delete existing entry to update position
+    this.cache.delete(contentHash);
+
+    // Evict oldest entries if at capacity
+    while (this.cache.size >= this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.cache.delete(oldestKey);
+      } else {
+        break;
+      }
+    }
+
+    this.cache.set(contentHash, entry);
+  }
+
+  /**
+   * Check if an entry exists and is not expired.
+   */
+  has(contentHash: string): boolean {
+    return this.get(contentHash) !== undefined;
+  }
+
+  /**
+   * Delete a specific entry.
+   */
+  delete(contentHash: string): boolean {
+    return this.cache.delete(contentHash);
+  }
+
+  /**
+   * Clear all entries.
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get the current cache size.
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Remove all expired entries.
+   */
+  prune(): number {
+    let pruned = 0;
+    for (const [key, entry] of this.cache) {
+      if (this.isExpired(entry)) {
+        this.cache.delete(key);
+        pruned++;
+      }
+    }
+    return pruned;
+  }
+
+  /**
+   * Check if an entry is expired.
+   */
+  private isExpired(entry: FileCacheEntry): boolean {
+    return Date.now() - entry.createdAt > this.ttlMs;
+  }
+}
+
+// ============================================================================
+// Hash Utilities
+// ============================================================================
+
+/**
+ * Generate a hash from file content for cache lookups.
+ * Uses a simple but fast hash algorithm suitable for deduplication.
+ *
+ * @param data - The file content as Uint8Array or string
+ * @returns A hex string hash
+ */
+export function generateContentHash(data: Uint8Array | string): string {
+  const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+
+  // Simple FNV-1a hash (fast and good distribution for deduplication)
+  let hash = 2166136261; // FNV offset basis
+
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 16777619); // FNV prime
+  }
+
+  // Include length to differentiate files with same content hash but different lengths
+  hash ^= bytes.length;
+
+  // Convert to hex string
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/**
+ * Generate a more unique cache key that includes filename and size.
+ * This helps differentiate files that might have similar beginnings.
+ *
+ * @param data - The file content
+ * @param filename - The filename
+ * @returns A cache key string
+ */
+export function generateCacheKey(data: Uint8Array | string, filename: string): string {
+  const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+  const contentHash = generateContentHash(data);
+  const normalizedFilename = filename.toLowerCase().replace(/[^a-z0-9.]/g, '_');
+
+  return `${contentHash}_${bytes.length}_${normalizedFilename}`;
+}
+
+// ============================================================================
+// Global Cache Instance
+// ============================================================================
+
+/**
+ * Default global file cache instance.
+ * This is used by the attachment processor when caching is enabled.
+ */
+let defaultCache: FileCache | null = null;
+
+/**
+ * Get the default global file cache.
+ * Creates one if it doesn't exist.
+ */
+export function getDefaultFileCache(): FileCache {
+  if (!defaultCache) {
+    defaultCache = new FileCache();
+  }
+  return defaultCache;
+}
+
+/**
+ * Set a custom default file cache.
+ * Useful for testing or custom configurations.
+ */
+export function setDefaultFileCache(cache: FileCache | null): void {
+  defaultCache = cache;
+}
+
+/**
+ * Clear the default file cache.
+ */
+export function clearDefaultFileCache(): void {
+  if (defaultCache) {
+    defaultCache.clear();
+  }
+}

package/src/files/index.ts

@@ -4,7 +4,22 @@
  * @module
  */
 
-export { type Attachment, type ProcessedAttachment, processAttachments } from './attachment-processor';
+export {
+  type Attachment,
+  type ProcessAttachmentsOptions,
+  type ProcessedAttachment,
+  processAttachments
+} from './attachment-processor';
+export {
+  FileCache,
+  type FileCacheEntry,
+  type FileCacheOptions,
+  clearDefaultFileCache,
+  generateCacheKey,
+  generateContentHash,
+  getDefaultFileCache,
+  setDefaultFileCache
+} from './file-cache';
 export {
   SUPPORTED_FILE_EXTENSIONS,
   SUPPORTED_MIME_TYPES,