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

package/src/__tests__/reasoning-utils.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Tests for multi-turn reasoning utilities.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { analyzeReasoningPreservation, recommendThinkingModel } from '../core';
+
+describe('analyzeReasoningPreservation', () => {
+  it('should detect messages with reasoning content', () => {
+    const messages = [
+      { role: 'user', content: 'What is 2+2?' },
+      {
+        role: 'assistant',
+        content: 'The answer is 4.',
+        reasoning_content: 'Let me calculate: 2+2 = 4'
+      }
+    ];
+
+    const analysis = analyzeReasoningPreservation(messages);
+
+    expect(analysis.messagesWithReasoning).toBe(1);
+    expect(analysis.isPreserved).toBe(true);
+    expect(analysis.missingReasoningIndices).toHaveLength(0);
+  });
+
+  it('should handle reasoning field variant', () => {
+    const messages = [
+      { role: 'user', content: 'Test' },
+      {
+        role: 'assistant',
+        content: 'Answer',
+        reasoning: 'My reasoning process...'
+      }
+    ];
+
+    const analysis = analyzeReasoningPreservation(messages);
+
+    expect(analysis.messagesWithReasoning).toBe(1);
+  });
+
+  it('should estimate reasoning tokens', () => {
+    const messages = [
+      { role: 'user', content: 'Test' },
+      {
+        role: 'assistant',
+        content: 'Answer',
+        reasoning_content: 'A'.repeat(400) // 400 chars ≈ 100 tokens
+      }
+    ];
+
+    const analysis = analyzeReasoningPreservation(messages);
+
+    expect(analysis.estimatedReasoningTokens).toBe(100);
+  });
+
+  it('should detect missing reasoning after tool calls', () => {
+    const messages = [
+      { role: 'user', content: 'Search for X' },
+      {
+        role: 'assistant',
+        content: null,
+        reasoning_content: 'I need to search...',
+        tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'search', arguments: '{}' } }]
+      },
+      { role: 'tool', tool_call_id: 'call_1', content: 'Search results...' },
+      {
+        role: 'assistant',
+        content: 'Here are the results', // Missing reasoning!
+        reasoning_content: null
+      }
+    ];
+
+    const analysis = analyzeReasoningPreservation(messages);
+
+    expect(analysis.isPreserved).toBe(false);
+    expect(analysis.missingReasoningIndices).toContain(3);
+  });
+
+  it('should handle proper reasoning preservation in tool loops', () => {
+    const messages = [
+      { role: 'user', content: 'Search for X' },
+      {
+        role: 'assistant',
+        content: null,
+        reasoning_content: 'I need to search...',
+        tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'search', arguments: '{}' } }]
+      },
+      { role: 'tool', tool_call_id: 'call_1', content: 'Search results...' },
+      {
+        role: 'assistant',
+        content: 'Here are the results',
+        reasoning_content: 'Based on the search results, I can now answer...'
+      }
+    ];
+
+    const analysis = analyzeReasoningPreservation(messages);
+
+    expect(analysis.isPreserved).toBe(true);
+    expect(analysis.messagesWithReasoning).toBe(2);
+  });
+
+  it('should handle empty conversations', () => {
+    const analysis = analyzeReasoningPreservation([]);
+
+    expect(analysis.messagesWithReasoning).toBe(0);
+    expect(analysis.isPreserved).toBe(true);
+    expect(analysis.estimatedReasoningTokens).toBe(0);
+  });
+
+  it('should handle conversations without assistant messages', () => {
+    const messages = [
+      { role: 'user', content: 'Hello' },
+      { role: 'system', content: 'You are helpful' }
+    ];
+
+    const analysis = analyzeReasoningPreservation(messages);
+
+    expect(analysis.messagesWithReasoning).toBe(0);
+    expect(analysis.isPreserved).toBe(true);
+  });
+});
+
+describe('recommendThinkingModel', () => {
+  it('should recommend for high complexity tasks', () => {
+    const recommendation = recommendThinkingModel(1, false, 0.8);
+
+    expect(recommendation.recommended).toBe(true);
+    expect(recommendation.reason).toContain('High complexity');
+  });
+
+  it('should recommend for multi-turn tool usage', () => {
+    const recommendation = recommendThinkingModel(5, true, 0.3);
+
+    expect(recommendation.recommended).toBe(true);
+    expect(recommendation.reason).toContain('tool usage');
+  });
+
+  it('should recommend for moderate complexity', () => {
+    const recommendation = recommendThinkingModel(1, false, 0.6);
+
+    expect(recommendation.recommended).toBe(true);
+    expect(recommendation.reason).toContain('Moderate complexity');
+  });
+
+  it('should not recommend for simple tasks', () => {
+    const recommendation = recommendThinkingModel(1, false, 0.2);
+
+    expect(recommendation.recommended).toBe(false);
+    expect(recommendation.reason).toContain('Standard model sufficient');
+  });
+
+  it('should not recommend for short tool conversations', () => {
+    const recommendation = recommendThinkingModel(2, true, 0.3);
+
+    expect(recommendation.recommended).toBe(false);
+  });
+
+  it('should prioritize high complexity over other factors', () => {
+    const recommendation = recommendThinkingModel(1, false, 0.9);
+
+    expect(recommendation.recommended).toBe(true);
+    expect(recommendation.reason).toContain('High complexity');
+  });
+});

package/src/__tests__/tools.test.ts

@@ -225,7 +225,8 @@ describe('prepareKimiTools', () => {
       });
     });
 
-    it('should include strict when provided', () => {
+    it('should not pass strict mode to Kimi for better compatibility', () => {
+      // Kimi doesn't fully support strict mode, so we don't pass it
       const result = prepareKimiTools({
         tools: [
           {
@@ -238,13 +239,80 @@ describe('prepareKimiTools', () => {
         ]
       });
 
-      expect(result.tools?.[0]).toMatchObject({
-        type: 'function',
-        function: {
-          name: 'test',
-          strict: true
-        }
+      // Strict should not be present in the output
+      const tool = result.tools?.[0];
+      expect(tool).toBeDefined();
+      if (tool && 'function' in tool) {
+        expect(tool.function).not.toHaveProperty('strict');
+      }
+    });
+
+    it('should sanitize JSON schema by removing unsupported keywords', () => {
+      const result = prepareKimiTools({
+        tools: [
+          {
+            type: 'function',
+            name: 'test',
+            description: 'Test tool',
+            inputSchema: {
+              $schema: 'http://json-schema.org/draft-07/schema#',
+              $id: 'test-schema',
+              type: 'object',
+              properties: {
+                name: { type: 'string' }
+              },
+              $defs: { unused: { type: 'string' } },
+              $comment: 'This is a comment'
+            }
+          }
+        ]
+      });
+
+      const tool = result.tools?.[0];
+      expect(tool).toBeDefined();
+      expect(tool?.type).toBe('function');
+      if (tool && tool.type === 'function') {
+        const params = tool.function.parameters as Record<string, unknown>;
+        expect(params).not.toHaveProperty('$schema');
+        expect(params).not.toHaveProperty('$id');
+        expect(params).not.toHaveProperty('$defs');
+        expect(params).not.toHaveProperty('$comment');
+        expect(params.type).toBe('object');
+        expect(params.properties).toEqual({ name: { type: 'string' } });
+      }
+    });
+
+    it('should preserve basic schema properties', () => {
+      const result = prepareKimiTools({
+        tools: [
+          {
+            type: 'function',
+            name: 'test',
+            description: 'Test tool',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                name: { type: 'string', description: 'Name field' },
+                count: { type: 'number', minimum: 0 }
+              },
+              required: ['name']
+            }
+          }
+        ]
       });
+
+      const tool = result.tools?.[0];
+      expect(tool).toBeDefined();
+      expect(tool?.type).toBe('function');
+      if (tool && tool.type === 'function') {
+        const params = tool.function.parameters as Record<string, unknown>;
+        expect(params.type).toBe('object');
+        expect(params.required).toEqual(['name']);
+        expect((params.properties as Record<string, unknown>).name).toEqual({
+          type: 'string',
+          description: 'Name field'
+        });
+      }
     });
   });
 

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,
@@ -765,6 +784,26 @@ const kimiTokenUsageSchema = z
   })
   .nullish();
 
+/**
+ * Schema for content parts in response messages.
+ * Can be text, image, or other content types.
+ */
+const kimiContentPartSchema = z.union([
+  z.object({
+    type: z.literal('text'),
+    text: z.string()
+  }),
+  z.object({
+    type: z.literal('image_url'),
+    image_url: z.object({
+      url: z.string()
+    })
+  }),
+  z.looseObject({
+    type: z.string()
+  })
+]);
+
 const kimiChatResponseSchema = z.looseObject({
   id: z.string().nullish(),
   created: z.number().nullish(),
@@ -773,7 +812,7 @@ const kimiChatResponseSchema = z.looseObject({
     z.object({
       message: z.object({
         role: z.string().nullish(),
-        content: z.union([z.string(), z.array(z.any())]).nullish(),
+        content: z.union([z.string(), z.array(kimiContentPartSchema)]).nullish(),
         reasoning_content: z.string().nullish(),
         reasoning: z.string().nullish(),
         tool_calls: z

package/src/core/errors.ts

@@ -19,7 +19,7 @@ export const kimiErrorSchema = z.union([
     error: z.object({
       message: z.string(),
       type: z.string().nullish(),
-      param: z.any().nullish(),
+      param: z.string().nullish(),
       code: z.union([z.string(), z.number()]).nullish(),
       request_id: z.string().nullish()
     })

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'
+  };
+}