Skip to main content

​
Overview

core-ai uses a comprehensive type system to ensure type safety across all operations. This page documents the essential types for working with messages, models, configurations, and results.

​
Message types

​
Message

Union type representing all message types in a conversation. 
type Message =
    | SystemMessage
    | UserMessage
    | AssistantMessage
    | ToolResultMessage;

​
SystemMessage

type SystemMessage = {
    role: 'system';
    content: string;
};

​
UserMessage

type UserMessage = {
    role: 'user';
    content: string | UserContentPart[];
};

type UserContentPart = TextPart | ImagePart | FilePart;

​
TextPart

type TextPart = {
    type: 'text';
    text: string;
};

​
ImagePart

type ImagePart = {
    type: 'image';
    source:
        | { type: 'base64'; mediaType: string; data: string }
        | { type: 'url'; url: string };
};

​
FilePart

type FilePart = {
    type: 'file';
    data: string;
    mimeType: string;
    filename?: string;
};

​
AssistantMessage

type AssistantMessage = {
    role: 'assistant';
    parts: AssistantContentPart[];
};

type AssistantContentPart =
    | AssistantTextPart
    | ReasoningPart
    | ToolCallPart;

​
AssistantTextPart

type AssistantTextPart = {
    type: 'text';
    text: string;
};

​
ReasoningPart

type ReasoningPart = {
    type: 'reasoning';
    text: string;
    providerMetadata?: Record<string, Record<string, unknown>>;
};
The providerMetadata is provider-namespaced. The top-level key is the provider identifier (for example 'anthropic', 'google', or 'openai'). Use getProviderMetadata() for typed access.

​
ToolCallPart

type ToolCallPart = {
    type: 'tool-call';
    toolCall: ToolCall;
};

​
ToolCall

type ToolCall = {
    id: string;
    name: string;
    arguments: Record<string, unknown>;
};

​
ToolResultMessage

type ToolResultMessage = {
    role: 'tool';
    toolCallId: string;
    content: string;
    isError?: boolean;
};

​
Tool types

​
ToolDefinition

type ToolDefinition = {
    name: string;
    description: string;
    parameters: z.ZodType;
};

​
ToolSet

type ToolSet = Record<string, ToolDefinition>;

​
ToolChoice

type ToolChoice =
    | 'auto'
    | 'none'
    | 'required'
    | { type: 'tool'; toolName: string };

​
Model types

​
ChatModel

type ChatModel = {
    readonly provider: string;
    readonly modelId: string;
    generate(options: GenerateOptions): Promise<GenerateResult>;
    stream(options: GenerateOptions): Promise<ChatStream>;
    generateObject<TSchema extends z.ZodType>(
        options: GenerateObjectOptions<TSchema>
    ): Promise<GenerateObjectResult<TSchema>>;
    streamObject<TSchema extends z.ZodType>(
        options: StreamObjectOptions<TSchema>
    ): Promise<ObjectStream<TSchema>>;
};

​
EmbeddingModel

type EmbeddingModel = {
    readonly provider: string;
    readonly modelId: string;
    embed(options: EmbedOptions): Promise<EmbedResult>;
};

​
ImageModel

type ImageModel = {
    readonly provider: string;
    readonly modelId: string;
    generate(options: ImageGenerateOptions): Promise<ImageGenerateResult>;
};

​
Configuration types

​
ReasoningConfig

type ReasoningConfig = {
    effort: ReasoningEffort;
};

type ReasoningEffort =
    | 'minimal'
    | 'low'
    | 'medium'
    | 'high'
    | 'max';

​
Provider options types

Provider-specific options are namespaced by provider name and validated with Zod schemas by each provider adapter. 
interface GenerateProviderOptions {
    [key: string]: Record<string, unknown> | undefined;
}

interface EmbedProviderOptions {
    [key: string]: Record<string, unknown> | undefined;
}

interface ImageProviderOptions {
    [key: string]: Record<string, unknown> | undefined;
}
Providers extend these via declaration merging to provide type-safe options: 
providerOptions: {
  openai: { user: 'user-123', store: true },
}

​
Generation options

​
BaseGenerateOptions

Shared options for all generation functions. 
type BaseGenerateOptions = {
    messages: Message[];
    temperature?: number;
    maxTokens?: number;
    topP?: number;
    reasoning?: ReasoningConfig;
    providerOptions?: GenerateProviderOptions;
    signal?: AbortSignal;
};

​
GenerateOptions

Extends BaseGenerateOptions with tool support. 
type GenerateOptions = BaseGenerateOptions & {
    tools?: ToolSet;
    toolChoice?: ToolChoice;
};

​
GenerateObjectOptions

type GenerateObjectOptions<TSchema extends z.ZodType> =
    BaseGenerateOptions & {
        schema: TSchema;
        schemaName?: string;
        schemaDescription?: string;
    };

​
StreamObjectOptions

type StreamObjectOptions<TSchema extends z.ZodType> =
    GenerateObjectOptions<TSchema>;

​
Result types

​
GenerateResult

type GenerateResult = {
    parts: AssistantContentPart[];
    content: string | null;
    reasoning: string | null;
    toolCalls: ToolCall[];
    finishReason: FinishReason;
    usage: ChatUsage;
};

​
GenerateObjectResult

type GenerateObjectResult<TSchema extends z.ZodType> = {
    object: z.infer<TSchema>;
    finishReason: FinishReason;
    usage: ChatUsage;
};

​
FinishReason

type FinishReason =
    | 'stop'
    | 'length'
    | 'tool-calls'
    | 'content-filter'
    | 'unknown';

​
Streaming types

​
ChatStream

Replayable handle for a chat streaming operation. Iterating after events have arrived replays the buffered history. 
type ChatStream = AsyncIterable<StreamEvent> & {
    readonly result: Promise<GenerateResult>;
    readonly events: Promise<readonly StreamEvent[]>;
};

​
StreamEvent

type StreamEvent =
    | { type: 'reasoning-start' }
    | { type: 'reasoning-delta'; text: string }
    | { type: 'reasoning-end'; providerMetadata?: Record<string, Record<string, unknown>> }
    | { type: 'text-delta'; text: string }
    | { type: 'tool-call-start'; toolCallId: string; toolName: string }
    | { type: 'tool-call-delta'; toolCallId: string; argumentsDelta: string }
    | { type: 'tool-call-end'; toolCall: ToolCall }
    | { type: 'finish'; finishReason: FinishReason; usage: ChatUsage };

​
ObjectStream

Replayable handle for a structured object streaming operation. 
type ObjectStream<TSchema extends z.ZodType> = AsyncIterable<
    ObjectStreamEvent<TSchema>
> & {
    readonly result: Promise<GenerateObjectResult<TSchema>>;
    readonly events: Promise<readonly ObjectStreamEvent<TSchema>[]>;
};

​
ObjectStreamEvent

type ObjectStreamEvent<TSchema extends z.ZodType> =
    | { type: 'object-delta'; text: string }
    | { type: 'object'; object: z.infer<TSchema> }
    | { type: 'finish'; finishReason: FinishReason; usage: ChatUsage };

​
Usage types

​
ChatUsage

type ChatUsage = {
    inputTokens: number;
    outputTokens: number;
    inputTokenDetails: ChatInputTokenDetails;
    outputTokenDetails: ChatOutputTokenDetails;
};
inputTokens is the total including cached reads and cache writes. outputTokens is the total including visible text and reasoning.

​
ChatInputTokenDetails

type ChatInputTokenDetails = {
    cacheReadTokens: number;
    cacheWriteTokens: number;
};

​
ChatOutputTokenDetails

type ChatOutputTokenDetails = {
    reasoningTokens?: number;
};

​
EmbeddingUsage

type EmbeddingUsage = {
    inputTokens: number;
};

​
Embedding types

​
EmbedOptions

type EmbedOptions = {
    input: string | string[];
    dimensions?: number;
    providerOptions?: EmbedProviderOptions;
};

​
EmbedResult

type EmbedResult = {
    embeddings: number[][];
    usage?: EmbeddingUsage;
};

​
Image generation types

​
ImageGenerateOptions

type ImageGenerateOptions = {
    prompt: string;
    n?: number;
    size?: string;
    providerOptions?: ImageProviderOptions;
};

​
ImageGenerateResult

type ImageGenerateResult = {
    images: GeneratedImage[];
};

​
GeneratedImage

type GeneratedImage = {
    base64?: string;
    url?: string;
    revisedPrompt?: string;
};

​
Type usage examples

​
Building type-safe conversations

import type { Message } from '@core-ai/core-ai';

const conversation: Message[] = [
  {
    role: 'system',
    content: 'You are a helpful assistant.'
  },
  {
    role: 'user',
    content: 'Hello!'
  },
  {
    role: 'assistant',
    parts: [{ type: 'text', text: 'Hi! How can I help?' }]
  },
  {
    role: 'user',
    content: 'What is 2+2?'
  }
];

​
Type-safe tool handling

import type { ToolCall, ToolResultMessage } from '@core-ai/core-ai';

function handleToolCall(toolCall: ToolCall): ToolResultMessage {
  return {
    role: 'tool',
    toolCallId: toolCall.id,
    content: JSON.stringify({ result: 'success' })
  };
}