@core-ai/core-ai 0.2.0 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # @core-ai/core-ai
 
+[![npm](https://img.shields.io/npm/v/@core-ai/core-ai.svg)](https://www.npmjs.com/package/@core-ai/core-ai)
+
 Type-safe LLM abstraction layer over native provider SDKs.
 
 ## Installation

package/dist/index.d.ts

@@ -62,6 +62,8 @@ type ChatModel = {
     readonly modelId: string;
     generate(options: GenerateOptions): Promise<GenerateResult>;
     stream(options: GenerateOptions): Promise<StreamResult>;
+    generateObject<TSchema extends z.ZodType>(options: GenerateObjectOptions<TSchema>): Promise<GenerateObjectResult<TSchema>>;
+    streamObject<TSchema extends z.ZodType>(options: StreamObjectOptions<TSchema>): Promise<StreamObjectResult<TSchema>>;
 };
 type ModelConfig = {
     temperature?: number;
@@ -85,6 +87,21 @@ type GenerateResult = {
     finishReason: FinishReason;
     usage: ChatUsage;
 };
+type GenerateObjectOptions<TSchema extends z.ZodType> = {
+    messages: Message[];
+    schema: TSchema;
+    schemaName?: string;
+    schemaDescription?: string;
+    config?: ModelConfig;
+    providerOptions?: Record<string, unknown>;
+    signal?: AbortSignal;
+};
+type StreamObjectOptions<TSchema extends z.ZodType> = GenerateObjectOptions<TSchema>;
+type GenerateObjectResult<TSchema extends z.ZodType> = {
+    object: z.infer<TSchema>;
+    finishReason: FinishReason;
+    usage: ChatUsage;
+};
 type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'unknown';
 /**
  * Token usage reported by the model after a chat completion.
@@ -134,6 +151,20 @@ type StreamEvent = {
 type StreamResult = AsyncIterable<StreamEvent> & {
     toResponse(): Promise<GenerateResult>;
 };
+type ObjectStreamEvent<TSchema extends z.ZodType> = {
+    type: 'object-delta';
+    text: string;
+} | {
+    type: 'object';
+    object: z.infer<TSchema>;
+} | {
+    type: 'finish';
+    finishReason: FinishReason;
+    usage: ChatUsage;
+};
+type StreamObjectResult<TSchema extends z.ZodType> = AsyncIterable<ObjectStreamEvent<TSchema>> & {
+    toResponse(): Promise<GenerateObjectResult<TSchema>>;
+};
 type EmbeddingModel = {
     readonly provider: string;
     readonly modelId: string;
@@ -146,9 +177,14 @@ type EmbedOptions = {
 };
 type EmbedResult = {
     embeddings: number[][];
-    usage: EmbeddingUsage;
+    /**
+     * Optional embedding usage metadata. Some providers/models do not expose
+     * token usage for embedding calls.
+     */
+    usage?: EmbeddingUsage;
 };
 type EmbeddingUsage = {
+    /** Number of tokens consumed by embedding input. */
     inputTokens: number;
 };
 type ImageModel = {
@@ -180,6 +216,25 @@ declare class ProviderError extends LLMError {
     readonly statusCode?: number;
     constructor(message: string, provider: string, statusCode?: number, cause?: unknown);
 }
+type StructuredOutputErrorOptions = {
+    statusCode?: number;
+    cause?: unknown;
+    rawOutput?: string;
+};
+declare class StructuredOutputError extends ProviderError {
+    readonly rawOutput?: string;
+    constructor(message: string, provider: string, options?: StructuredOutputErrorOptions);
+}
+declare class StructuredOutputNoObjectGeneratedError extends StructuredOutputError {
+    constructor(message: string, provider: string, options?: StructuredOutputErrorOptions);
+}
+declare class StructuredOutputParseError extends StructuredOutputError {
+    constructor(message: string, provider: string, options?: StructuredOutputErrorOptions);
+}
+declare class StructuredOutputValidationError extends StructuredOutputError {
+    readonly issues: string[];
+    constructor(message: string, provider: string, issues: string[], options?: StructuredOutputErrorOptions);
+}
 
 declare function defineTool(options: ToolDefinition): ToolDefinition;
 
@@ -188,11 +243,22 @@ type GenerateParams = GenerateOptions & {
 };
 declare function generate(params: GenerateParams): Promise<GenerateResult>;
 
+type GenerateObjectParams<TSchema extends z.ZodType> = GenerateObjectOptions<TSchema> & {
+    model: ChatModel;
+};
+declare function generateObject<TSchema extends z.ZodType>(params: GenerateObjectParams<TSchema>): Promise<GenerateObjectResult<TSchema>>;
+
 type StreamParams = GenerateOptions & {
     model: ChatModel;
 };
 declare function stream(params: StreamParams): Promise<StreamResult>;
 
+type StreamObjectParams<TSchema extends z.ZodType> = StreamObjectOptions<TSchema> & {
+    model: ChatModel;
+};
+declare function streamObject<TSchema extends z.ZodType>(params: StreamObjectParams<TSchema>): Promise<StreamObjectResult<TSchema>>;
+declare function createObjectStreamResult<TSchema extends z.ZodType>(source: AsyncIterable<ObjectStreamEvent<TSchema>>): StreamObjectResult<TSchema>;
+
 declare function createStreamResult(source: AsyncIterable<StreamEvent>): StreamResult;
 
 type EmbedParams = EmbedOptions & {
@@ -205,4 +271,4 @@ type GenerateImageParams = ImageGenerateOptions & {
 };
 declare function generateImage(params: GenerateImageParams): Promise<ImageGenerateResult>;
 
-export { type AssistantMessage, type ChatModel, type ChatUsage, type EmbedOptions, type EmbedResult, type EmbeddingModel, type EmbeddingUsage, type FilePart, type FinishReason, type GenerateOptions, type GenerateResult, type GeneratedImage, type ImageGenerateOptions, type ImageGenerateResult, type ImageModel, type ImagePart, LLMError, type Message, type ModelConfig, ProviderError, type StreamEvent, type StreamResult, type SystemMessage, type TextPart, type ToolCall, type ToolChoice, type ToolDefinition, type ToolResultMessage, type ToolSet, type UserContentPart, type UserMessage, createStreamResult, defineTool, embed, generate, generateImage, stream };
+export { type AssistantMessage, type ChatModel, type ChatUsage, type EmbedOptions, type EmbedResult, type EmbeddingModel, type EmbeddingUsage, type FilePart, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateOptions, type GenerateResult, type GeneratedImage, type ImageGenerateOptions, type ImageGenerateResult, type ImageModel, type ImagePart, LLMError, type Message, type ModelConfig, type ObjectStreamEvent, ProviderError, type StreamEvent, type StreamObjectOptions, type StreamObjectResult, type StreamResult, StructuredOutputError, StructuredOutputNoObjectGeneratedError, StructuredOutputParseError, StructuredOutputValidationError, type SystemMessage, type TextPart, type ToolCall, type ToolChoice, type ToolDefinition, type ToolResultMessage, type ToolSet, type UserContentPart, type UserMessage, createObjectStreamResult, createStreamResult, defineTool, embed, generate, generateImage, generateObject, stream, streamObject };

package/dist/index.js

@@ -17,6 +17,34 @@ var ProviderError = class extends LLMError {
     this.statusCode = statusCode;
   }
 };
+var StructuredOutputError = class extends ProviderError {
+  rawOutput;
+  constructor(message, provider, options = {}) {
+    super(message, provider, options.statusCode, options.cause);
+    this.name = "StructuredOutputError";
+    this.rawOutput = options.rawOutput;
+  }
+};
+var StructuredOutputNoObjectGeneratedError = class extends StructuredOutputError {
+  constructor(message, provider, options = {}) {
+    super(message, provider, options);
+    this.name = "StructuredOutputNoObjectGeneratedError";
+  }
+};
+var StructuredOutputParseError = class extends StructuredOutputError {
+  constructor(message, provider, options = {}) {
+    super(message, provider, options);
+    this.name = "StructuredOutputParseError";
+  }
+};
+var StructuredOutputValidationError = class extends StructuredOutputError {
+  issues;
+  constructor(message, provider, issues, options = {}) {
+    super(message, provider, options);
+    this.name = "StructuredOutputValidationError";
+    this.issues = issues;
+  }
+};
 
 // src/tool.ts
 import { zodToJsonSchema } from "zod-to-json-schema";
@@ -33,6 +61,15 @@ async function generate(params) {
   return model.generate(options);
 }
 
+// src/generate-object.ts
+async function generateObject(params) {
+  if (params.messages.length === 0) {
+    throw new LLMError("messages must not be empty");
+  }
+  const { model, ...options } = params;
+  return model.generateObject(options);
+}
+
 // src/stream-chat.ts
 async function stream(params) {
   if (params.messages.length === 0) {
@@ -42,6 +79,83 @@ async function stream(params) {
   return model.stream(options);
 }
 
+// src/stream-object.ts
+async function streamObject(params) {
+  if (params.messages.length === 0) {
+    throw new LLMError("messages must not be empty");
+  }
+  const { model, ...options } = params;
+  return model.streamObject(options);
+}
+function createObjectStreamResult(source) {
+  let resolveResponse;
+  let rejectResponse;
+  const responsePromise = new Promise(
+    (resolve, reject) => {
+      resolveResponse = resolve;
+      rejectResponse = reject;
+    }
+  );
+  let iteratorCreated = false;
+  async function* iterate() {
+    let objectResult;
+    let finishReason = "unknown";
+    let usage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      reasoningTokens: 0,
+      totalTokens: 0
+    };
+    try {
+      for await (const event of source) {
+        if (event.type === "object") {
+          objectResult = event.object;
+        } else if (event.type === "finish") {
+          finishReason = event.finishReason;
+          usage = event.usage;
+        }
+        yield event;
+      }
+      if (objectResult === void 0) {
+        throw new LLMError(
+          "object stream completed without emitting a final object"
+        );
+      }
+      resolveResponse?.({
+        object: objectResult,
+        finishReason,
+        usage
+      });
+    } catch (error) {
+      rejectResponse?.(error);
+      throw error;
+    }
+  }
+  const generator = iterate();
+  return {
+    [Symbol.asyncIterator]() {
+      if (iteratorCreated) {
+        throw new Error("Stream can only be iterated once");
+      }
+      iteratorCreated = true;
+      return generator;
+    },
+    toResponse() {
+      if (!iteratorCreated) {
+        iteratorCreated = true;
+        (async () => {
+          try {
+            for await (const _event of generator) {
+            }
+          } catch {
+          }
+        })();
+      }
+      return responsePromise;
+    }
+  };
+}
+
 // src/stream.ts
 function createStreamResult(source) {
   let resolveResponse;
@@ -123,10 +237,17 @@ async function generateImage(params) {
 export {
   LLMError,
   ProviderError,
+  StructuredOutputError,
+  StructuredOutputNoObjectGeneratedError,
+  StructuredOutputParseError,
+  StructuredOutputValidationError,
+  createObjectStreamResult,
   createStreamResult,
   defineTool,
   embed,
   generate,
   generateImage,
-  stream
+  generateObject,
+  stream,
+  streamObject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@core-ai/core-ai",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Type-safe LLM abstraction layer over native provider SDKs",
     "license": "MIT",
     "author": "Omnifact (https://omnifact.ai)",
@@ -44,8 +44,8 @@
         "test:watch": "vitest"
     },
     "dependencies": {
-        "zod": "^3.25.76",
-        "zod-to-json-schema": "^3.24.5"
+        "zod": "^3.25.0 || ^4.0.0",
+        "zod-to-json-schema": "^3.25.1"
     },
     "devDependencies": {
         "@core-ai/eslint-config": "^0.0.0",