feat(kosong): support structured response formats

.changeset/structured-output-provider-format.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kosong": patch
+---
+
+Add provider-level structured response format support.

packages/kosong/src/provider.ts

@@ -2,6 +2,24 @@ import type { Message, StreamedMessagePart, VideoURLPart } from './message';
 import type { Tool } from './tool';
 import type { TokenUsage } from './usage';
 
+export type JsonSchemaObject = Record<string, unknown>;
+
+export interface JsonObjectResponseFormat {
+  readonly type: 'json_object';
+}
+
+export interface JsonSchemaResponseFormat {
+  readonly type: 'json_schema';
+  readonly jsonSchema: {
+    readonly name: string;
+    readonly schema: JsonSchemaObject;
+    readonly strict?: boolean | undefined;
+    readonly description?: string | undefined;
+  };
+}
+
+export type ResponseFormat = JsonObjectResponseFormat | JsonSchemaResponseFormat;
+
 /**
  * Thinking effort passed to {@link ChatProvider.withThinking}.
  *
@@ -118,6 +136,11 @@ export interface GenerateOptions {
    * each request/retry so providers never retain mutable credential state.
    */
   auth?: ProviderRequestAuth;
+  /**
+   * Optional model-output format constraint. Providers map this to their native
+   * structured-output field when supported.
+   */
+  responseFormat?: ResponseFormat;
   /**
    * Host-side instrumentation hook fired immediately before invoking the
    * provider adapter's generate call.

packages/kosong/src/providers/anthropic.ts

@@ -11,6 +11,7 @@ import type {
   FinishReason,
   GenerateOptions,
   ProviderRequestAuth,
+  ResponseFormat,
   StreamedMessage,
   ThinkingEffort,
 } from '#/provider';
@@ -128,6 +129,27 @@ const ANTHROPIC_TOOL_CALL_ID_POLICY: ToolCallIdPolicy = {
   maxLength: 64,
 };
 
+function applyResponseFormat(
+  kwargs: Record<string, unknown>,
+  format: ResponseFormat | undefined,
+): void {
+  if (format === undefined) return;
+  if (format.type === 'json_object') {
+    throw new ChatProviderError(
+      'Anthropic provider requires a JSON schema for structured response output.',
+    );
+  }
+  const outputConfig =
+    kwargs['output_config'] !== undefined && kwargs['output_config'] !== null
+      ? { ...(kwargs['output_config'] as Record<string, unknown>) }
+      : {};
+  outputConfig['format'] = {
+    type: 'json_schema',
+    schema: format.jsonSchema.schema,
+  };
+  kwargs['output_config'] = outputConfig;
+}
+
 /**
  * Per-version default output ceilings sourced from Anthropic's Messages
  * API model cards (platform.claude.com/docs/en/about-claude/models/overview).
@@ -1076,6 +1098,7 @@ export class AnthropicChatProvider implements ChatProvider {
     if (this._generationKwargs.output_config !== undefined) {
       kwargs['output_config'] = this._generationKwargs.output_config;
     }
+    applyResponseFormat(kwargs, options?.responseFormat);
 
     // Build the beta feature list. On the standard Messages API these travel
     // via the `anthropic-beta` header; on the beta Messages API (`betaApi`) the

packages/kosong/src/providers/google-genai.ts

@@ -10,6 +10,7 @@ import type {
   FinishReason,
   GenerateOptions,
   ProviderRequestAuth,
+  ResponseFormat,
   StreamedMessage,
   ThinkingEffort,
 } from '#/provider';
@@ -126,6 +127,19 @@ function toolToGoogleGenAI(tool: Tool): GoogleTool {
     ],
   };
 }
+
+function applyResponseFormat(
+  config: Record<string, unknown>,
+  format: ResponseFormat | undefined,
+): void {
+  if (format === undefined) return;
+  config['responseMimeType'] = 'application/json';
+  delete config['responseSchema'];
+  delete config['responseJsonSchema'];
+  if (format.type === 'json_schema') {
+    config['responseJsonSchema'] = format.jsonSchema.schema;
+  }
+}
 interface GoogleContent {
   role: string;
   parts: GooglePart[];
@@ -804,6 +818,7 @@ export class GoogleGenAIChatProvider implements ChatProvider {
       systemInstruction: systemPrompt,
       ...(tools.length > 0 ? { tools: tools.map((t) => toolToGoogleGenAI(t)) } : {}),
     };
+    applyResponseFormat(config, options?.responseFormat);
 
     try {
       const client = this._createClient(options?.auth);

packages/kosong/src/providers/kimi.ts

@@ -6,6 +6,7 @@ import type {
   GenerateOptions,
   MaxCompletionTokensOptions,
   ProviderRequestAuth,
+  ResponseFormat,
   StreamedMessage,
   ThinkingEffort,
   VideoUploadInput,
@@ -188,6 +189,21 @@ function convertTool(tool: Tool): OpenAIToolParam {
     },
   };
 }
+
+function responseFormatToOpenAI(format: ResponseFormat): Record<string, unknown> {
+  if (format.type === 'json_object') {
+    return { type: 'json_object' };
+  }
+  return {
+    type: 'json_schema',
+    json_schema: {
+      name: format.jsonSchema.name,
+      schema: format.jsonSchema.schema,
+      strict: format.jsonSchema.strict,
+      description: format.jsonSchema.description,
+    },
+  };
+}
 /**
  * Extract usage from a streaming chunk. Moonshot may place usage in
  * `choices[0].usage` in addition to the top-level `usage` field.
@@ -484,6 +500,9 @@ export class KimiChatProvider implements ChatProvider {
       ...requestKwargs,
       ...(extraBody as Record<string, unknown> | undefined),
     };
+    if (options?.responseFormat !== undefined) {
+      createParams['response_format'] = responseFormatToOpenAI(options.responseFormat);
+    }
 
     if (tools.length > 0) {
       createParams['tools'] = tools.map((t) => convertTool(t));

packages/kosong/src/providers/openai-legacy.ts

@@ -5,6 +5,7 @@ import type {
   GenerateOptions,
   MaxCompletionTokensOptions,
   ProviderRequestAuth,
+  ResponseFormat,
   StreamedMessage,
   ThinkingEffort,
 } from '#/provider';
@@ -59,6 +60,21 @@ const OPENAI_CHAT_TOOL_CALL_ID_POLICY: ToolCallIdPolicy = {
   maxLength: 64,
 };
 
+function responseFormatToOpenAI(format: ResponseFormat): Record<string, unknown> {
+  if (format.type === 'json_object') {
+    return { type: 'json_object' };
+  }
+  return {
+    type: 'json_schema',
+    json_schema: {
+      name: format.jsonSchema.name,
+      schema: format.jsonSchema.schema,
+      strict: format.jsonSchema.strict,
+      description: format.jsonSchema.description,
+    },
+  };
+}
+
 function extractReasoningContent(
   source: unknown,
   explicitKey: string | undefined,
@@ -556,6 +572,9 @@ export class OpenAILegacyChatProvider implements ChatProvider {
       stream: this._stream,
       ...kwargs,
     };
+    if (options?.responseFormat !== undefined) {
+      createParams['response_format'] = responseFormatToOpenAI(options.responseFormat);
+    }
 
     if (tools.length > 0) {
       createParams['tools'] = tools.map((t) => toolToOpenAI(t));

packages/kosong/src/providers/openai-responses.ts

@@ -11,6 +11,7 @@ import type {
   FinishReason,
   GenerateOptions,
   ProviderRequestAuth,
+  ResponseFormat,
   StreamedMessage,
   ThinkingEffort,
 } from '#/provider';
@@ -362,6 +363,22 @@ interface ResponseToolParam {
   parameters: Record<string, unknown>;
   strict: boolean;
 }
+
+function responseFormatToResponsesText(format: ResponseFormat): Record<string, unknown> {
+  if (format.type === 'json_object') {
+    return { format: { type: 'json_object' } };
+  }
+  return {
+    format: {
+      type: 'json_schema',
+      name: format.jsonSchema.name,
+      schema: format.jsonSchema.schema,
+      strict: format.jsonSchema.strict,
+      description: format.jsonSchema.description,
+    },
+  };
+}
+
 // The Responses API has no input type for video, and only mp3/wav audio can
 // be inlined as input_file data. Degrade such parts to placeholder text so
 // the model still learns an attachment existed instead of silently losing it.
@@ -1074,6 +1091,9 @@ export class OpenAIResponsesChatProvider implements ChatProvider {
       if (systemPrompt) {
         createParams['instructions'] = systemPrompt;
       }
+      if (options?.responseFormat !== undefined) {
+        createParams['text'] = responseFormatToResponsesText(options.responseFormat);
+      }
 
       if (
         !('responses' in client) ||

packages/kosong/test/anthropic.test.ts

@@ -1,6 +1,7 @@
 import { ChatProviderError } from '#/errors';
 import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
 import { AnthropicChatProvider, resolveDefaultMaxTokens } from '#/providers/anthropic';
+import type { GenerateOptions } from '#/provider';
 import type { Tool } from '#/tool';
 import { describe, it, expect, vi } from 'vitest';
 
@@ -62,6 +63,7 @@ async function captureRequestBody(
   systemPrompt: string,
   tools: Tool[],
   history: Message[],
+  options?: GenerateOptions,
 ): Promise<Record<string, unknown>> {
   let capturedParams: Record<string, unknown> | undefined;
   let capturedOptions: Record<string, unknown> | undefined;
@@ -74,7 +76,7 @@ async function captureRequestBody(
       return Promise.resolve(makeAnthropicResponse());
     });
 
-  const stream = await provider.generate(systemPrompt, tools, history);
+  const stream = await provider.generate(systemPrompt, tools, history, options);
   for await (const part of stream) {
     void part;
   }
@@ -281,6 +283,50 @@ describe('AnthropicChatProvider', () => {
       ]);
     });
 
+    it('maps json_schema response format to output_config.format', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Extract contact' }], toolCalls: [] },
+      ];
+      const schema = {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+        additionalProperties: false,
+      };
+
+      const body = await captureRequestBody(provider, '', [], history, {
+        responseFormat: {
+          type: 'json_schema',
+          jsonSchema: {
+            name: 'contact',
+            schema,
+            strict: true,
+          },
+        },
+      });
+
+      expect(body['output_config']).toEqual({
+        format: {
+          type: 'json_schema',
+          schema,
+        },
+      });
+    });
+
+    it('rejects json_object response format because Anthropic requires a schema', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Extract contact' }], toolCalls: [] },
+      ];
+
+      await expect(
+        provider.generate('', [], history, {
+          responseFormat: { type: 'json_object' },
+        }),
+      ).rejects.toThrow('Anthropic provider requires a JSON schema for structured response output.');
+    });
+
     it('multi-turn conversation', async () => {
       const provider = createProvider();
       const history: Message[] = [