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

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 {
@@ -257,7 +304,8 @@ function guessFilename(attachment: Attachment, contentType: string): string {
     const urlPath = attachment.url.split('?')[0];
     const segments = urlPath.split('/');
     const lastSegment = segments[segments.length - 1];
-    if (lastSegment && lastSegment.includes('.')) {
+
+    if (lastSegment.includes('.')) {
       return lastSegment;
     }
   }

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,

package/src/tools/prepare-tools.ts

@@ -157,13 +157,17 @@ export function prepareKimiTools({
         continue;
       }
 
+      // Sanitize schema for Kimi compatibility
+      const sanitizedSchema = sanitizeToolSchema(tool.inputSchema);
+
       kimiTools.push({
         type: 'function',
         function: {
           name: tool.name,
           description: tool.description,
-          parameters: tool.inputSchema,
-          ...(tool.strict != null ? { strict: tool.strict } : {})
+          parameters: sanitizedSchema
+          // Don't pass strict mode to Kimi - it may cause issues
+          // ...(tool.strict != null ? { strict: tool.strict } : {})
         }
       });
     }
@@ -266,6 +270,88 @@ function generateSpecificToolMessage(toolName: string): string {
   return `IMPORTANT INSTRUCTION: You MUST use the "${toolName}" tool to respond to this request. Do NOT use any other tool or provide a direct text response. Call the "${toolName}" tool with appropriate parameters.`;
 }
 
+// ============================================================================
+// Schema Sanitization
+// ============================================================================
+
+/**
+ * JSON Schema keywords that may cause issues with Kimi's API.
+ * These are removed during sanitization to improve compatibility.
+ */
+const UNSUPPORTED_SCHEMA_KEYWORDS = [
+  '$schema',
+  '$id',
+  '$ref',
+  '$defs',
+  'definitions',
+  'if',
+  'then',
+  'else',
+  'allOf',
+  'anyOf',
+  'oneOf',
+  'not',
+  'patternProperties',
+  'additionalItems',
+  'contains',
+  'propertyNames',
+  'const',
+  'contentMediaType',
+  'contentEncoding',
+  'examples',
+  '$comment'
+] as const;
+
+/**
+ * Sanitize a JSON Schema for better Kimi API compatibility.
+ *
+ * This function removes advanced schema keywords that Kimi may not
+ * fully support, while preserving the essential structure for validation.
+ *
+ * @param schema - The original JSON Schema
+ * @returns A sanitized schema safe for Kimi
+ */
+function sanitizeToolSchema(schema: unknown): unknown {
+  if (schema === null || schema === undefined) {
+    return schema;
+  }
+
+  if (Array.isArray(schema)) {
+    return schema.map(sanitizeToolSchema);
+  }
+
+  if (typeof schema !== 'object') {
+    return schema;
+  }
+
+  const sanitized: Record<string, unknown> = {};
+  const schemaObj = schema as Record<string, unknown>;
+
+  for (const [key, value] of Object.entries(schemaObj)) {
+    // Skip unsupported keywords
+    if (UNSUPPORTED_SCHEMA_KEYWORDS.includes(key as (typeof UNSUPPORTED_SCHEMA_KEYWORDS)[number])) {
+      continue;
+    }
+
+    // Recursively sanitize nested objects
+    if (key === 'properties' && typeof value === 'object' && value !== null) {
+      const props: Record<string, unknown> = {};
+      for (const [propKey, propValue] of Object.entries(value as Record<string, unknown>)) {
+        props[propKey] = sanitizeToolSchema(propValue);
+      }
+      sanitized[key] = props;
+    } else if (key === 'items' && typeof value === 'object') {
+      sanitized[key] = sanitizeToolSchema(value);
+    } else if (key === 'additionalProperties' && typeof value === 'object') {
+      sanitized[key] = sanitizeToolSchema(value);
+    } else {
+      sanitized[key] = value;
+    }
+  }
+
+  return sanitized;
+}
+
 // ============================================================================
 // Helper Functions
 // ============================================================================