@kernl-sdk/ai 0.2.10 → 0.3.1

package/src/__tests__/integration.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeAll } from "vitest";
 import { openai } from "@ai-sdk/openai";
 import { anthropic } from "@ai-sdk/anthropic";
+import { google } from "@ai-sdk/google";
 import { IN_PROGRESS } from "@kernl-sdk/protocol";
 
 import { AISDKLanguageModel } from "../language-model";
@@ -11,12 +12,28 @@ import { AISDKLanguageModel } from "../language-model";
  * These tests require API keys to be set:
  * - OPENAI_API_KEY for OpenAI tests
  * - ANTHROPIC_API_KEY for Anthropic tests
+ * - GOOGLE_GENERATIVE_AI_API_KEY for Google tests
  *
- * Run with: OPENAI_API_KEY=your-key ANTHROPIC_API_KEY=your-key pnpm test:run
+ * Run with: OPENAI_API_KEY=your-key ANTHROPIC_API_KEY=your-key GOOGLE_GENERATIVE_AI_API_KEY=your-key pnpm test:run
  */
 
 const SKIP_OPENAI_TESTS = !process.env.OPENAI_API_KEY;
 const SKIP_ANTHROPIC_TESTS = !process.env.ANTHROPIC_API_KEY;
+const SKIP_GOOGLE_TESTS = !process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+
+/**
+ * Shared JSON schema for structured output tests.
+ * Extracts a person's name and age from text.
+ */
+const PERSON_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    name: { type: "string" as const, description: "The person's name" },
+    age: { type: "number" as const, description: "The person's age in years" },
+  },
+  required: ["name", "age"],
+  additionalProperties: false,
+};
 
 describe.skipIf(SKIP_OPENAI_TESTS)("AISDKLanguageModel - OpenAI", () => {
   let gpt41: AISDKLanguageModel;
@@ -741,6 +758,109 @@ describe.skipIf(SKIP_OPENAI_TESTS)("AISDKLanguageModel - OpenAI", () => {
       ).rejects.toThrow(/max_output_tokens/);
     });
   });
+
+  describe("structured output", () => {
+    it("should generate structured JSON output with responseType", async () => {
+      const response = await gpt41.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: John Smith is 42 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+
+      // Find the assistant message with JSON output
+      const messages = response.content.filter(
+        (item) => item.kind === "message" && item.role === "assistant",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("John Smith");
+      expect(parsed.age).toBe(42);
+    });
+
+    it("should stream structured JSON output with responseType", async () => {
+      const events = [];
+
+      for await (const event of gpt41.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Alice Wong is 28 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have text-delta events for streaming JSON
+      const textDeltas = events.filter((e) => e.kind === "text-delta");
+      expect(textDeltas.length).toBeGreaterThan(0);
+
+      // Should have a complete message with the JSON
+      const messages = events.filter((e) => e.kind === "message");
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Alice Wong");
+      expect(parsed.age).toBe(28);
+
+      // Should have finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+    });
+  });
 });
 
 describe.skipIf(SKIP_ANTHROPIC_TESTS)("AISDKLanguageModel - Anthropic", () => {
@@ -887,4 +1007,283 @@ describe.skipIf(SKIP_ANTHROPIC_TESTS)("AISDKLanguageModel - Anthropic", () => {
       expect(finishEvents.length).toBe(1);
     });
   });
+
+  describe("structured output", () => {
+    it("should generate structured JSON output with responseType", async () => {
+      const response = await claude.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Maria Garcia is 35 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+
+      // Find the assistant message with JSON output
+      const messages = response.content.filter(
+        (item) => item.kind === "message" && item.role === "assistant",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Maria Garcia");
+      expect(parsed.age).toBe(35);
+    });
+
+    it("should stream structured JSON output with responseType", async () => {
+      const events = [];
+
+      for await (const event of claude.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: David Chen is 55 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have text-delta events for streaming JSON
+      const textDeltas = events.filter((e) => e.kind === "text-delta");
+      expect(textDeltas.length).toBeGreaterThan(0);
+
+      // Should have a complete message with the JSON
+      const messages = events.filter((e) => e.kind === "message");
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("David Chen");
+      expect(parsed.age).toBe(55);
+
+      // Should have finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+    });
+  });
+});
+
+describe.skipIf(SKIP_GOOGLE_TESTS)("AISDKLanguageModel - Google", () => {
+  let gemini: AISDKLanguageModel;
+
+  beforeAll(() => {
+    gemini = new AISDKLanguageModel(google("gemini-2.5-flash-lite"));
+  });
+
+  describe("generate", () => {
+    it("should generate a simple text response", async () => {
+      const response = await gemini.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              { kind: "text", text: "Say 'Hello, World!' and nothing else." },
+            ],
+          },
+        ],
+        settings: {
+          maxTokens: 50,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+      expect(response.usage).toBeDefined();
+      expect(response.usage.totalTokens).toBeGreaterThan(0);
+
+      const messages = response.content.filter(
+        (item) => item.kind === "message",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("stream", () => {
+    it("should stream text responses", async () => {
+      const events = [];
+
+      for await (const event of gemini.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [{ kind: "text", text: "Count to 5" }],
+          },
+        ],
+        settings: {
+          maxTokens: 50,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have at least one finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+
+      // Should have usage information
+      const finishEvent = finishEvents[0] as any;
+      expect(finishEvent.usage).toBeDefined();
+      expect(finishEvent.usage.totalTokens).toBeGreaterThan(0);
+    });
+  });
+
+  describe("structured output", () => {
+    it("should generate structured JSON output with responseType", async () => {
+      const response = await gemini.generate({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Kenji Tanaka is 29 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      });
+
+      expect(response.content).toBeDefined();
+      expect(response.content.length).toBeGreaterThan(0);
+
+      // Find the assistant message with JSON output
+      const messages = response.content.filter(
+        (item) => item.kind === "message" && item.role === "assistant",
+      );
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Kenji Tanaka");
+      expect(parsed.age).toBe(29);
+    });
+
+    it("should stream structured JSON output with responseType", async () => {
+      const events = [];
+
+      for await (const event of gemini.stream({
+        input: [
+          {
+            kind: "message",
+            role: "user",
+            id: "msg-1",
+            content: [
+              {
+                kind: "text",
+                text: "Extract the person info: Sarah Johnson is 41 years old.",
+              },
+            ],
+          },
+        ],
+        responseType: {
+          kind: "json",
+          schema: PERSON_SCHEMA,
+          name: "person",
+          description: "A person with name and age",
+        },
+        settings: {
+          maxTokens: 100,
+          temperature: 0,
+        },
+      })) {
+        events.push(event);
+      }
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // Should have text-delta events for streaming JSON
+      const textDeltas = events.filter((e) => e.kind === "text-delta");
+      expect(textDeltas.length).toBeGreaterThan(0);
+
+      // Should have a complete message with the JSON
+      const messages = events.filter((e) => e.kind === "message");
+      expect(messages.length).toBeGreaterThan(0);
+
+      const msg = messages[0] as any;
+      const textContent = msg.content.find((c: any) => c.kind === "text");
+      expect(textContent).toBeDefined();
+
+      // Parse and validate the JSON output
+      const parsed = JSON.parse(textContent.text);
+      expect(parsed.name).toBe("Sarah Johnson");
+      expect(parsed.age).toBe(41);
+
+      // Should have finish event
+      const finishEvents = events.filter((e) => e.kind === "finish");
+      expect(finishEvents.length).toBe(1);
+    });
+  });
 });

package/src/convert/response.ts

@@ -5,6 +5,7 @@ import {
   FAILED,
   type LanguageModelResponse,
   type LanguageModelResponseItem,
+  type LanguageModelResponseType,
   type LanguageModelFinishReason,
   type LanguageModelUsage,
   type LanguageModelWarning,
@@ -16,6 +17,7 @@ import type {
   LanguageModelV3FinishReason,
   LanguageModelV3Usage,
   LanguageModelV3CallWarning,
+  JSONSchema7,
 } from "@ai-sdk/provider";
 
 /**
@@ -172,3 +174,42 @@ export const WARNING: Codec<LanguageModelWarning, LanguageModelV3CallWarning> =
       }
     },
   };
+
+/**
+ * AI SDK response format type.
+ *
+ * Maps to the `responseFormat` parameter in AI SDK's doGenerate/doStream.
+ */
+export interface AISdkResponseFormat {
+  type: "json";
+  schema?: JSONSchema7;
+  name?: string;
+  description?: string;
+}
+
+/**
+ * Codec for converting protocol responseType to AI SDK responseFormat.
+ *
+ * - `kind: "text"` or undefined → undefined (AI SDK defaults to text)
+ * - `kind: "json"` → `{ type: "json", schema, name, description }`
+ */
+export const RESPONSE_FORMAT: Codec<
+  LanguageModelResponseType | undefined,
+  AISdkResponseFormat | undefined
+> = {
+  encode: (responseType) => {
+    if (!responseType || responseType.kind === "text") {
+      return undefined;
+    }
+
+    return {
+      type: "json",
+      schema: responseType.schema,
+      name: responseType.name,
+      description: responseType.description,
+    };
+  },
+  decode: () => {
+    throw new Error("codec:unimplemented");
+  },
+};

package/src/language-model.ts

@@ -11,7 +11,7 @@ import { message, reasoning } from "@kernl-sdk/protocol";
 import { MESSAGE } from "./convert/message";
 import { TOOL } from "./convert/tools";
 import { MODEL_SETTINGS } from "./convert/settings";
-import { MODEL_RESPONSE } from "./convert/response";
+import { MODEL_RESPONSE, RESPONSE_FORMAT } from "./convert/response";
 import { convertStream } from "./convert/stream";
 
 /**
@@ -36,11 +36,13 @@ export class AISDKLanguageModel implements LanguageModel {
     const messages = request.input.map(MESSAGE.encode);
     const tools = request.tools ? request.tools.map(TOOL.encode) : undefined;
     const settings = MODEL_SETTINGS.encode(request.settings);
+    const responseFormat = RESPONSE_FORMAT.encode(request.responseType);
 
     const result = await this.model.doGenerate({
       prompt: messages,
       tools,
       ...settings,
+      responseFormat,
       abortSignal: request.abort,
     });
 
@@ -56,11 +58,13 @@ export class AISDKLanguageModel implements LanguageModel {
     const messages = request.input.map(MESSAGE.encode);
     const tools = request.tools ? request.tools.map(TOOL.encode) : undefined;
     const settings = MODEL_SETTINGS.encode(request.settings);
+    const responseFormat = RESPONSE_FORMAT.encode(request.responseType);
 
     const stream = await this.model.doStream({
       prompt: messages,
       tools,
       ...settings,
+      responseFormat,
       abortSignal: request.abort,
     });
 

package/src/providers/anthropic.ts

@@ -1,4 +1,4 @@
-import { anthropic as createAnthropicModel } from "@ai-sdk/anthropic";
+import { anthropic as _anthropic } from "@ai-sdk/anthropic";
 import { AISDKLanguageModel } from "../language-model";
 
 /**
@@ -13,7 +13,7 @@ import { AISDKLanguageModel } from "../language-model";
  * ```
  */
 export function anthropic(modelId: string) {
-  const model = createAnthropicModel(modelId);
+  const model = _anthropic(modelId);
   return new AISDKLanguageModel(model);
 }
 

package/src/providers/google.ts

@@ -1,4 +1,4 @@
-import { google as createGoogleModel } from "@ai-sdk/google";
+import { google as _google } from "@ai-sdk/google";
 import { AISDKLanguageModel } from "../language-model";
 import { AISDKEmbeddingModel } from "../embedding-model";
 import { registerEmbeddingProvider } from "@kernl-sdk/retrieval";
@@ -15,11 +15,12 @@ import { registerEmbeddingProvider } from "@kernl-sdk/retrieval";
  * ```
  */
 export function google(modelId: string) {
-  const model = createGoogleModel(modelId);
+  const model = _google(modelId);
   return new AISDKLanguageModel(model);
 }
 
 // Auto-register Google embedding provider
-registerEmbeddingProvider("google", (id) =>
-  new AISDKEmbeddingModel(createGoogleModel.textEmbedding(id)),
+registerEmbeddingProvider(
+  "google",
+  (id) => new AISDKEmbeddingModel(_google.textEmbedding(id)),
 );

package/src/providers/openai.ts

@@ -1,4 +1,4 @@
-import { openai as createOpenAIModel } from "@ai-sdk/openai";
+import { openai as _openai } from "@ai-sdk/openai";
 import { AISDKLanguageModel } from "../language-model";
 import { AISDKEmbeddingModel } from "../embedding-model";
 import { registerEmbeddingProvider } from "@kernl-sdk/retrieval";
@@ -15,11 +15,12 @@ import { registerEmbeddingProvider } from "@kernl-sdk/retrieval";
  * ```
  */
 export function openai(modelId: string) {
-  const model = createOpenAIModel(modelId);
+  const model = _openai(modelId);
   return new AISDKLanguageModel(model);
 }
 
 // Auto-register OpenAI embedding provider
-registerEmbeddingProvider("openai", (id) =>
-  new AISDKEmbeddingModel(createOpenAIModel.embedding(id)),
+registerEmbeddingProvider(
+  "openai",
+  (id) => new AISDKEmbeddingModel(_openai.embedding(id)),
 );

package/.turbo/turbo-check-types.log

@@ -1,4 +0,0 @@
-
-> @kernl-sdk/ai@0.2.6 check-types /Users/andjones/Documents/projects/kernl/packages/providers/ai
-> tsc --noEmit
-

package/dist/convert/messages.d.ts

@@ -1,4 +0,0 @@
-import type { Codec, LanguageModelItem } from "@kernl-sdk/protocol";
-import type { LanguageModelV3Message } from "ai";
-export declare const messages: Codec<LanguageModelItem[], LanguageModelV3Message[]>;
-//# sourceMappingURL=messages.d.ts.map

package/dist/convert/messages.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/convert/messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EACV,sBAAsB,EAMvB,MAAM,IAAI,CAAC;AAEZ,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,iBAAiB,EAAE,EAAE,sBAAsB,EAAE,CAwIzE,CAAC"}