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

package/src/ensemble/types.ts

@@ -0,0 +1,279 @@
+/**
+ * Types for ensemble/multi-sampling functionality.
+ * @module
+ */
+
+import type { LanguageModelV3ToolCall, LanguageModelV3ToolResult } from '@ai-sdk/provider';
+
+/**
+ * Simple usage type compatible with common AI SDK patterns.
+ * This is independent from the provider-specific V3Usage type.
+ */
+export interface LanguageModelUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+/**
+ * Re-export types for convenience.
+ */
+export type ToolCall = LanguageModelV3ToolCall;
+export type ToolResult = LanguageModelV3ToolResult;
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Selection strategy for choosing the best response from multiple samples.
+ */
+export type SelectionStrategy = 'first' | 'vote' | 'best' | 'all';
+
+/**
+ * Scoring heuristic for the 'best' selection strategy.
+ */
+export type ScoringHeuristic = 'length' | 'confidence' | 'code' | 'custom';
+
+/**
+ * Configuration for ensemble/multi-sampling.
+ */
+export interface EnsembleConfig {
+  /**
+   * Number of parallel samples to generate.
+   * @default 3
+   */
+  n: number;
+
+  /**
+   * Strategy for selecting the best result.
+   * - 'first': Return the first successful response
+   * - 'vote': Return the most common answer (majority voting)
+   * - 'best': Use heuristic scoring to pick the best
+   * - 'all': Return all responses (for manual selection)
+   * @default 'best'
+   */
+  selectionStrategy?: SelectionStrategy;
+
+  /**
+   * Temperature variation for diversity.
+   * Each sample gets temperature = baseTemp + (i * variance)
+   * @default 0.1
+   */
+  temperatureVariance?: number;
+
+  /**
+   * For 'best' strategy, the scoring heuristic.
+   * - 'length': Prefer shorter responses
+   * - 'confidence': Prefer responses with higher token count
+   * - 'code': Prefer responses with fewer error patterns
+   * - 'custom': Use custom scorer function
+   * @default 'confidence'
+   */
+  scoringHeuristic?: ScoringHeuristic;
+
+  /**
+   * Custom scoring function for 'custom' heuristic.
+   * Higher scores are better.
+   */
+  customScorer?: (response: EnsembleResponse) => number;
+
+  /**
+   * Maximum time to wait for all samples (ms).
+   * @default 60000
+   */
+  timeoutMs?: number;
+
+  /**
+   * Whether to continue if some samples fail.
+   * @default true
+   */
+  allowPartialFailure?: boolean;
+
+  /**
+   * Minimum number of successful samples required.
+   * Only relevant when allowPartialFailure is true.
+   * @default 1
+   */
+  minSuccessfulSamples?: number;
+}
+
+// ============================================================================
+// Response Types
+// ============================================================================
+
+/**
+ * A single response from the ensemble.
+ */
+export interface EnsembleResponse {
+  /**
+   * The generated text.
+   */
+  text: string;
+
+  /**
+   * Reasoning content (for thinking models).
+   */
+  reasoning?: string;
+
+  /**
+   * Tool calls made during generation.
+   */
+  toolCalls?: ToolCall[];
+
+  /**
+   * Results of tool executions.
+   */
+  toolResults?: ToolResult[];
+
+  /**
+   * Token usage for this response.
+   */
+  usage?: LanguageModelUsage;
+
+  /**
+   * Score assigned to this response (if scoring was applied).
+   */
+  score?: number;
+
+  /**
+   * Index of this sample in the ensemble.
+   */
+  sampleIndex: number;
+
+  /**
+   * Temperature used for this sample.
+   */
+  temperature: number;
+
+  /**
+   * Reason the generation finished.
+   */
+  finishReason: string;
+
+  /**
+   * Whether this sample completed successfully.
+   */
+  success: boolean;
+
+  /**
+   * Error message if the sample failed.
+   */
+  error?: string;
+
+  /**
+   * Time taken to generate this response (ms).
+   */
+  durationMs?: number;
+}
+
+/**
+ * Metadata about the ensemble execution.
+ */
+export interface EnsembleMetadata {
+  /**
+   * Number of samples requested.
+   */
+  nRequested: number;
+
+  /**
+   * Number of samples that completed successfully.
+   */
+  nCompleted: number;
+
+  /**
+   * Number of samples that failed.
+   */
+  nFailed: number;
+
+  /**
+   * Selection strategy used.
+   */
+  selectionStrategy: SelectionStrategy;
+
+  /**
+   * Index of the winning sample.
+   */
+  winningIndex: number;
+
+  /**
+   * Scores of all samples (if scoring was applied).
+   */
+  scores?: number[];
+
+  /**
+   * Total time for ensemble execution (ms).
+   */
+  durationMs: number;
+
+  /**
+   * Model ID used.
+   */
+  modelId: string;
+
+  /**
+   * Aggregated token usage across all samples.
+   */
+  totalUsage: LanguageModelUsage;
+}
+
+/**
+ * Result of an ensemble generation.
+ */
+export interface EnsembleResult {
+  /**
+   * The selected best response text.
+   */
+  text: string;
+
+  /**
+   * Reasoning content from the best response.
+   */
+  reasoning?: string;
+
+  /**
+   * Tool calls from the best response.
+   */
+  toolCalls?: ToolCall[];
+
+  /**
+   * Tool results from the best response.
+   */
+  toolResults?: ToolResult[];
+
+  /**
+   * Token usage from the best response.
+   */
+  usage: LanguageModelUsage;
+
+  /**
+   * All generated responses (populated for 'all' strategy).
+   */
+  alternatives?: EnsembleResponse[];
+
+  /**
+   * Metadata about the ensemble execution.
+   */
+  metadata: EnsembleMetadata;
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Internal state for tracking ensemble progress.
+ */
+export interface EnsembleState {
+  responses: EnsembleResponse[];
+  startTime: number;
+  completed: boolean;
+}
+
+/**
+ * Options for scoring a response.
+ */
+export interface ScoringOptions {
+  heuristic: ScoringHeuristic;
+  customScorer?: (response: EnsembleResponse) => number;
+}

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,