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

package/README.md

@@ -34,6 +34,11 @@ This is a native implementation with full support for Kimi-specific features, no
 - [Reasoning/Thinking Models](#reasoningthinking-models)
 - [Video Input](#video-input-k25-models)
 - [Model Capabilities](#model-capabilities)
+- [Advanced Features](#advanced-features)
+  - [Temperature Locking](#temperature-locking-for-thinking-models)
+  - [File Content Caching](#file-content-caching)
+  - [Schema Sanitization](#schema-sanitization)
+  - [Reasoning Preservation](#reasoning-preservation-utilities)
 - [Provider Options](#provider-options)
 - [Available Models](#available-models-1)
 - [Regional Endpoints](#regional-endpoints)
@@ -56,6 +61,9 @@ This is a native implementation with full support for Kimi-specific features, no
 - **Native File & PDF Support** - Automatic file upload and content extraction
 - **Tool Choice Polyfill** - Simulates `required` and `tool` choices via system messages
 - **Context Caching** - Reduce costs by up to 90% for repeated long prompts
+- **Temperature Locking** - Automatic temperature enforcement for thinking models
+- **File Content Caching** - LRU cache to avoid re-uploading identical files
+- **Schema Sanitization** - Automatic cleanup of unsupported JSON Schema keywords
 
 ### Kimi Code (Premium Coding API)
 - High-speed output (up to 100 tokens/s)
@@ -603,6 +611,134 @@ const codeCaps = inferKimiCodeCapabilities('kimi-k2-thinking');
 // }
 ```
 
+## Advanced Features
+
+### Temperature Locking for Thinking Models
+
+Thinking models like `kimi-k2.5-thinking` require a fixed temperature of `1.0` for optimal reasoning. The provider automatically enforces this:
+
+```ts
+// Temperature is automatically set to 1.0 for thinking models
+const result = await generateText({
+  model: kimi('kimi-k2.5-thinking'),
+  temperature: 0.7, // Will be ignored with a warning
+  prompt: 'Solve this complex problem...',
+});
+
+// Check the response for warnings
+console.log(result.warnings);
+// [{ type: 'compatibility', feature: 'temperature', details: 'Thinking models require temperature=1.0...' }]
+```
+
+Thinking models also default to 32k max tokens to prevent reasoning truncation:
+
+```ts
+// No need to set maxTokens - defaults to 32768 for thinking models
+const result = await generateText({
+  model: kimi('kimi-k2.5-thinking'),
+  prompt: 'Explain quantum computing in detail...',
+});
+```
+
+### File Content Caching
+
+Avoid re-uploading the same files by enabling the LRU cache:
+
+```ts
+import { processAttachments } from 'kimi-vercel-ai-sdk-provider';
+
+// Enable caching (uses default global cache: 100 entries, 1 hour TTL)
+const processed = await processAttachments({
+  attachments: message.experimental_attachments ?? [],
+  clientConfig: {
+    baseURL: 'https://api.moonshot.ai/v1',
+    headers: () => ({ Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}` }),
+  },
+  cache: true, // Enable file caching
+});
+
+// Or provide a custom cache instance
+import { FileCache } from 'kimi-vercel-ai-sdk-provider';
+
+const customCache = new FileCache({
+  maxSize: 200,      // Max 200 entries
+  ttlMs: 2 * 60 * 60 * 1000, // 2 hour TTL
+});
+
+const processed = await processAttachments({
+  attachments,
+  clientConfig,
+  cache: customCache,
+});
+```
+
+### Schema Sanitization
+
+Tool parameters are automatically sanitized to remove JSON Schema keywords not supported by Kimi:
+
+```ts
+// This schema with advanced JSON Schema features...
+const complexTool = {
+  name: 'search',
+  parameters: z.object({
+    query: z.string(),
+    filters: z.object({
+      $schema: 'http://json-schema.org/draft-07/schema#', // Removed
+      allOf: [{ minLength: 1 }], // Removed
+      anyOf: [{ type: 'string' }], // Removed
+    }),
+  }),
+};
+
+// ...is automatically sanitized before being sent to Kimi
+// Only basic properties (type, properties, required, description) are kept
+```
+
+### Reasoning Preservation Utilities
+
+Helpers for maintaining reasoning context in multi-turn conversations:
+
+```ts
+import { 
+  analyzeReasoningPreservation, 
+  recommendThinkingModel 
+} from 'kimi-vercel-ai-sdk-provider';
+
+// Analyze if reasoning is properly preserved in a conversation
+const messages = [
+  { role: 'user', content: 'Solve this step by step: ...' },
+  { 
+    role: 'assistant', 
+    content: [
+      { type: 'reasoning', text: 'First, I need to...' },
+      { type: 'text', text: 'The answer is 42.' }
+    ]
+  },
+  { role: 'user', content: 'Explain step 2 more.' },
+];
+
+const analysis = analyzeReasoningPreservation(messages);
+// {
+//   hasReasoningContent: true,
+//   reasoningPreserved: true,
+//   turnCount: 3,
+//   reasoningTurnCount: 1,
+//   recommendations: []
+// }
+
+// Get a recommendation on whether to use a thinking model
+const recommendation = recommendThinkingModel({
+  taskDescription: 'Complex mathematical proof',
+  requiresStepByStep: true,
+  complexity: 'high',
+});
+// {
+//   recommended: true,
+//   reason: 'Task requires step-by-step reasoning with high complexity',
+//   suggestedModel: 'kimi-k2.5-thinking'
+// }
+```
+
 ## Provider Options
 
 ### Kimi Chat Options
@@ -788,6 +924,12 @@ import {
 import {
   KimiFileClient,
   processAttachments,
+  FileCache,
+  generateContentHash,
+  generateCacheKey,
+  getDefaultFileCache,
+  setDefaultFileCache,
+  clearDefaultFileCache,
   SUPPORTED_FILE_EXTENSIONS,
   SUPPORTED_MIME_TYPES,
   isImageMediaType,
@@ -803,8 +945,21 @@ import {
   FileUploadResult,
   Attachment,
   ProcessedAttachment,
-} from 'kimi-vercel-ai-sdk-provider
-';
+  FileCacheOptions,
+  FileCacheEntry,
+} from 'kimi-vercel-ai-sdk-provider';
+
+// Utilities
+import {
+  analyzeReasoningPreservation,
+  recommendThinkingModel,
+  // Constants
+  THINKING_MODEL_TEMPERATURE,
+  THINKING_MODEL_DEFAULT_MAX_TOKENS,
+  STANDARD_MODEL_DEFAULT_MAX_TOKENS,
+  // Types
+  ReasoningAnalysis,
+} from 'kimi-vercel-ai-sdk-provider';
 
 // Built-in Tools
 import {

package/dist/index.d.mts

@@ -103,6 +103,21 @@ 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;
 }
 /**
  * Infer model capabilities from the model ID.
@@ -110,10 +125,25 @@ interface KimiModelCapabilities {
  * @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,
+ * //   ...
+ * // }
  * ```
  */
 declare function inferModelCapabilities(modelId: string): KimiModelCapabilities;
@@ -488,6 +518,9 @@ declare class KimiChatLanguageModel implements LanguageModelV3 {
         toolCalling?: boolean;
         jsonMode?: boolean;
         structuredOutputs?: boolean;
+        defaultTemperature?: number;
+        temperatureLocked?: boolean;
+        defaultMaxOutputTokens?: number;
     };
     get supportedUrls(): Record<string, RegExp[]> | PromiseLike<Record<string, RegExp[]>>;
     private getArgs;
@@ -495,6 +528,107 @@ declare class KimiChatLanguageModel implements LanguageModelV3 {
     doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
 }
 
+/**
+ * File content caching for efficient re-use of uploaded files.
+ * @module
+ */
+/**
+ * Entry in the file cache.
+ */
+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.
+ */
+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;
+}
+/**
+ * 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()
+ * });
+ * ```
+ */
+declare class FileCache {
+    private readonly maxSize;
+    private readonly ttlMs;
+    private readonly cache;
+    constructor(options?: FileCacheOptions);
+    /**
+     * 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;
+    /**
+     * Set a cache entry.
+     * Evicts the least recently used entry if cache is full.
+     */
+    set(contentHash: string, entry: FileCacheEntry): void;
+    /**
+     * Check if an entry exists and is not expired.
+     */
+    has(contentHash: string): boolean;
+    /**
+     * Delete a specific entry.
+     */
+    delete(contentHash: string): boolean;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Get the current cache size.
+     */
+    get size(): number;
+    /**
+     * Remove all expired entries.
+     */
+    prune(): number;
+    /**
+     * Check if an entry is expired.
+     */
+    private isExpired;
+}
+
 /**
  * Kimi File API client for uploading and managing files.
  * @module
@@ -659,6 +793,13 @@ 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;
 }
 /**
  * Process experimental_attachments for Kimi.

package/dist/index.d.ts

@@ -103,6 +103,21 @@ 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;
 }
 /**
  * Infer model capabilities from the model ID.
@@ -110,10 +125,25 @@ interface KimiModelCapabilities {
  * @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,
+ * //   ...
+ * // }
  * ```
  */
 declare function inferModelCapabilities(modelId: string): KimiModelCapabilities;
@@ -488,6 +518,9 @@ declare class KimiChatLanguageModel implements LanguageModelV3 {
         toolCalling?: boolean;
         jsonMode?: boolean;
         structuredOutputs?: boolean;
+        defaultTemperature?: number;
+        temperatureLocked?: boolean;
+        defaultMaxOutputTokens?: number;
     };
     get supportedUrls(): Record<string, RegExp[]> | PromiseLike<Record<string, RegExp[]>>;
     private getArgs;
@@ -495,6 +528,107 @@ declare class KimiChatLanguageModel implements LanguageModelV3 {
     doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
 }
 
+/**
+ * File content caching for efficient re-use of uploaded files.
+ * @module
+ */
+/**
+ * Entry in the file cache.
+ */
+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.
+ */
+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;
+}
+/**
+ * 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()
+ * });
+ * ```
+ */
+declare class FileCache {
+    private readonly maxSize;
+    private readonly ttlMs;
+    private readonly cache;
+    constructor(options?: FileCacheOptions);
+    /**
+     * 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;
+    /**
+     * Set a cache entry.
+     * Evicts the least recently used entry if cache is full.
+     */
+    set(contentHash: string, entry: FileCacheEntry): void;
+    /**
+     * Check if an entry exists and is not expired.
+     */
+    has(contentHash: string): boolean;
+    /**
+     * Delete a specific entry.
+     */
+    delete(contentHash: string): boolean;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Get the current cache size.
+     */
+    get size(): number;
+    /**
+     * Remove all expired entries.
+     */
+    prune(): number;
+    /**
+     * Check if an entry is expired.
+     */
+    private isExpired;
+}
+
 /**
  * Kimi File API client for uploading and managing files.
  * @module
@@ -659,6 +793,13 @@ 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;
 }
 /**
  * Process experimental_attachments for Kimi.