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

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 } : {})
         }
       });
     }
@@ -252,18 +256,189 @@ export function prepareKimiTools({
 // Tool Choice Polyfill Messages
 // ============================================================================
 
+/**
+ * Tool descriptions for better guidance.
+ */
+const TOOL_DESCRIPTIONS: Record<string, string> = {
+  $web_search:
+    'Search the web for up-to-date information, current events, facts, news, prices, weather, or any data not available in your training',
+  $code: 'Execute code to perform calculations, data processing, algorithmic tasks, or verify code correctness'
+};
+
+/**
+ * Options for generating tool guidance messages.
+ */
+export interface ToolGuidanceOptions {
+  /**
+   * The tool names available.
+   */
+  toolNames: string[];
+
+  /**
+   * The type of tool choice.
+   */
+  choiceType: 'required' | 'tool';
+
+  /**
+   * The specific tool name if choiceType is 'tool'.
+   */
+  targetTool?: string;
+
+  /**
+   * Optional context from the user's prompt to include.
+   */
+  promptContext?: string;
+
+  /**
+   * Whether to include detailed tool descriptions.
+   * @default true
+   */
+  includeDescriptions?: boolean;
+}
+
+/**
+ * Generate a comprehensive tool guidance message.
+ *
+ * @param options - Options for generating the message
+ * @returns The generated system message
+ */
+export function generateToolGuidanceMessage(options: ToolGuidanceOptions): string {
+  const { toolNames, choiceType, targetTool, promptContext, includeDescriptions = true } = options;
+
+  const lines: string[] = ['=== TOOL USAGE GUIDANCE ===', ''];
+
+  // Add tool descriptions
+  if (includeDescriptions && toolNames.length > 0) {
+    lines.push('Available tools:');
+    for (const toolName of toolNames) {
+      const description = TOOL_DESCRIPTIONS[toolName] || 'Execute this tool';
+      lines.push(`- ${toolName}: ${description}`);
+    }
+    lines.push('');
+  }
+
+  // Add the requirement
+  if (choiceType === 'required') {
+    lines.push('⚠️ IMPORTANT: You MUST use at least one of the available tools to respond.');
+    lines.push('Do NOT provide a direct text response without first calling a tool.');
+  } else if (choiceType === 'tool' && targetTool) {
+    lines.push(`⚠️ IMPORTANT: You MUST use the "${targetTool}" tool to respond.`);
+    lines.push('Do NOT use any other tool or provide a direct text response.');
+  }
+
+  // Add context-specific guidance
+  if (promptContext) {
+    lines.push('');
+    lines.push(`Task context: ${promptContext.slice(0, 200)}${promptContext.length > 200 ? '...' : ''}`);
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Generate a system message to force the model to use a tool.
  */
 function generateRequiredToolMessage(toolNames: string): string {
-  return `IMPORTANT INSTRUCTION: You MUST use one of the available tools (${toolNames}) to respond to the user's request. Do NOT provide a direct text response without first calling a tool. Always invoke a tool to complete this task.`;
+  const tools = toolNames.split(', ');
+  return generateToolGuidanceMessage({
+    toolNames: tools,
+    choiceType: 'required',
+    includeDescriptions: true
+  });
 }
 
 /**
  * Generate a system message to force the model to use a specific tool.
  */
 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.`;
+  return generateToolGuidanceMessage({
+    toolNames: [toolName],
+    choiceType: 'tool',
+    targetTool: toolName,
+    includeDescriptions: true
+  });
+}
+
+// ============================================================================
+// 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;
 }
 
 // ============================================================================