@core-ai/core-ai 0.2.1 → 0.4.0

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,32 +87,60 @@ 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.
  *
- * `outputTokens` is the **total** output token count, including both visible
- * text and any internal reasoning/thinking the model performed.
- * `reasoningTokens` is the subset of `outputTokens` consumed by reasoning.
- * For non-reasoning models (or providers that don't report it separately)
- * this will be `0`.
+ * `inputTokens` is always the **total** input token count, including cached
+ * reads and cache writes. Anthropic's `input_tokens` is normalized by adding
+ * `cache_read_input_tokens` and `cache_creation_input_tokens`.
  *
- * Provider mapping:
- * - **OpenAI**: `reasoningTokens` comes from `completion_tokens_details.reasoning_tokens`.
- * - **Google Gemini**: `reasoningTokens` comes from `thoughtsTokenCount`;
- *   `outputTokens` = `candidatesTokenCount + thoughtsTokenCount`.
- * - **Anthropic**: `reasoningTokens` is always `0` (thinking tokens are
- *   included in `output_tokens` but not reported separately by the API).
+ * `outputTokens` is always the **total** output token count, including both
+ * visible text and internal reasoning.
+ *
+ * `inputTokenDetails` and `outputTokenDetails` provide provider-independent
+ * breakdowns for cache and reasoning accounting.
  */
 type ChatUsage = {
-    /** Number of tokens in the input prompt. */
+    /** Total input tokens, including cached and cache-write tokens. */
     inputTokens: number;
     /** Total output tokens, including both visible text and reasoning. */
     outputTokens: number;
-    /** Tokens consumed by internal reasoning/thinking. Subset of `outputTokens`. */
+    /** Breakdown of input token categories. */
+    inputTokenDetails: ChatInputTokenDetails;
+    /** Breakdown of output token categories. */
+    outputTokenDetails: ChatOutputTokenDetails;
+};
+type ChatInputTokenDetails = {
+    /** Input tokens served from a prior cache entry. Subset of `inputTokens`. */
+    cacheReadTokens: number;
+    /**
+     * Input tokens written to cache for future reuse. Subset of `inputTokens`.
+     * Only Anthropic reports this; other providers report `0`.
+     */
+    cacheWriteTokens: number;
+};
+type ChatOutputTokenDetails = {
+    /**
+     * Tokens consumed by internal reasoning/thinking. Subset of `outputTokens`.
+     * For non-reasoning models (or providers that don't report it), this is `0`.
+     */
     reasoningTokens: number;
-    /** Sum of all tokens (`inputTokens + outputTokens`). */
-    totalTokens: number;
 };
 type StreamEvent = {
     type: 'content-delta';
@@ -134,6 +164,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 +190,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 +229,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 +256,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 +284,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 ChatInputTokenDetails, type ChatModel, type ChatOutputTokenDetails, 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,88 @@ 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,
+      inputTokenDetails: {
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0
+      },
+      outputTokenDetails: {
+        reasoningTokens: 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;
@@ -56,8 +175,13 @@ function createStreamResult(source) {
     let usage = {
       inputTokens: 0,
       outputTokens: 0,
-      reasoningTokens: 0,
-      totalTokens: 0
+      inputTokenDetails: {
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0
+      },
+      outputTokenDetails: {
+        reasoningTokens: 0
+      }
     };
     for await (const event of source) {
       if (event.type === "content-delta") {
@@ -123,10 +247,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.1",
+    "version": "0.4.0",
     "description": "Type-safe LLM abstraction layer over native provider SDKs",
     "license": "MIT",
     "author": "Omnifact (https://omnifact.ai)",