Types - core-ai

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;
    metadata?: Record<string, unknown>;
};

UserMessage

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

type UserContentPart = TextPart | ImagePart | FilePart | AudioPart;

TextPart

type TextPart = {
    type: 'text';
    text: string;
    metadata?: Record<string, unknown>;
};

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;
};

AudioPart

type AudioPart = {
    type: 'audio';
    source: {
        type: 'base64';
        mediaType: string;
        data: string;
    };
};

AssistantMessage

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

type AssistantContentPart = AssistantTextPart | ReasoningPart | ToolCallPart;

AssistantTextPart

type AssistantTextPart = {
    type: 'text';
    text: string;
    metadata?: Record<string, unknown>;
};

ReasoningPart

type ReasoningPart = {
    type: 'reasoning';
    text: string;
    metadata?: Record<string, unknown>;
    providerMetadata?: Record<string, Record<string, unknown>>;
};

The metadata field is application-owned and provider adapters ignore it. The providerMetadata field is provider-namespaced. The top-level key is the provider identifier (for example 'anthropic', 'google', 'openai', or 'azure-openai'). Adapters treat other providers’ keys as foreign and downgrade those reasoning blocks to plain text instead of forwarding opaque metadata. Use getProviderMetadata() for typed access.

ToolCallPart

type ToolCallPart = {
    type: 'tool-call';
    toolCall: ToolCall;
    providerMetadata?: Record<string, Record<string, unknown>>;
};

providerMetadata follows the same provider-namespaced convention as ReasoningPart. Keep it on the part when you replay history: Gemini 3 rejects a request when a function call from the current turn comes back without its thought signature.

ToolCall

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

ToolResultMessage

type ToolResultMessage = {
    role: 'tool';
    toolCallId: string;
    content: string;
    isError?: boolean;
    metadata?: Record<string, unknown>;
};

metadata on message parts, tool calls, and tool results is for your application and middleware. It stays in conversation history and generated results, but core-ai does not send it to provider APIs.

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;
    readonly capabilities: ModelCapabilities;
    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>>;
};

capabilities describes how a specific model accepts unified generation options. It is different from the provider-level feature lists in the provider guides: those show which APIs a provider exposes, while ModelCapabilities describes request constraints for one model ID.

ModelCapabilities

type ChatInputModality = 'text' | 'image' | 'file' | 'audio' | 'video';

type ChatOutputModality = 'text' | 'image' | 'audio' | 'video';

type ModelCapabilities = {
    reasoning: {
        mode: 'unsupported' | 'optional' | 'always-on';
        supportedEfforts: readonly ReasoningEffort[];
        /**
         * Whether reasoning changes which sampling parameters or values the
         * provider accepts.
         */
        restrictsSamplingParams: boolean;
        supportedToolChoices: readonly (
            | 'auto'
            | 'none'
            | 'required'
            | 'tool'
        )[];
    };
    modalities: {
        /** Modalities accepted in user messages. Always includes `'text'`. */
        input: readonly ChatInputModality[];
        /**
         * Modalities the model can emit as assistant content. Always includes
         * `'text'`. Does not describe dedicated `ImageModel` generation.
         */
        output: readonly ChatOutputModality[];
    };
};

Field	Meaning
`reasoning.mode`	Whether reasoning control is unsupported, optional, or always active
`reasoning.supportedEfforts`	Effort values the adapter accepts (empty when unsupported)
`reasoning.restrictsSamplingParams`	Whether reasoning changes the accepted sampling parameters or values
`reasoning.supportedToolChoices`	Tool choice modes supported while reasoning is enabled
`modalities.input`	Modalities accepted in user messages
`modalities.output`	Modalities the model can emit as assistant content

mode: 'unsupported' means the provider does not map the unified reasoning option. The model may still return reasoning output. optional means callers can enable reasoning, while always-on means the model reasons without an option and cannot disable it. An empty supportedEfforts list means the model does not accept effort control. It does not necessarily mean the model cannot produce reasoning output. When restrictsSamplingParams is true, consult the provider guide for the exact accepted values. modalities.input / modalities.output describe chat I/O modalities. Check them with .includes(...), or with the exported helpers supportsInputModality and supportsOutputModality. Core also exports the common presets TEXT_ONLY_MODALITIES (text in / text out) and MULTIMODAL_INPUT_MODALITIES (text + image + file in / text out). Providers that support AudioPart add 'audio' to their input array. 'video' is reserved until a dedicated user content part exists. Sending image, file, or audio parts when those modalities are not in modalities.input throws an UnsupportedInputModalityError before the provider call. Unrecognized model IDs are treated as multimodal capable on purpose for image and file input (fail-open), so self-hosted endpoints and newly released models are not blocked locally for those parts. Audio remains opt-in. Typos and custom deployment names that do not match a registry key therefore include 'image' and 'file' in modalities.input and still rely on the provider to reject unsupported requests. For Azure and other wrappers, pass a known registry model ID when you need accurate capability data. modalities.output currently always includes 'text'. Dedicated image generation uses ImageModel / generateImage, not chat output. Provider packages also export get*ModelCapabilities(modelId) helpers that return the same data without constructing a ChatModel. Kimi exposes this data through ChatModel.capabilities only.

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;
    metadata?: Record<string, unknown>;
    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';
          metadata?: Record<string, unknown>;
          providerMetadata?: Record<string, Record<string, unknown>>;
      }
    | { type: 'text-start' }
    | { type: 'text-delta'; text: string }
    | { type: 'text-end'; metadata?: Record<string, unknown> }
    | { type: 'tool-call-start'; toolCallId: string; toolName: string }
    | { type: 'tool-call-delta'; toolCallId: string; argumentsDelta: string }
    | {
          type: 'tool-call-end';
          toolCall: ToolCall;
          providerMetadata?: Record<string, Record<string, unknown>>;
      }
    | { 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' }),
    };
}

​Overview

​Message types

​Message

​SystemMessage

​UserMessage

​TextPart

​ImagePart

​FilePart

​AudioPart

​AssistantMessage

​AssistantTextPart

​ReasoningPart

​ToolCallPart

​ToolCall

​ToolResultMessage

​Tool types

​ToolDefinition

​ToolSet

​ToolChoice

​Model types

​ChatModel

​ModelCapabilities

​EmbeddingModel

​ImageModel

​Configuration types

​ReasoningConfig

​Provider options types

​Generation options

​BaseGenerateOptions

​GenerateOptions

​GenerateObjectOptions

​StreamObjectOptions

​Result types

​GenerateResult

​GenerateObjectResult

​FinishReason

​Streaming types

​ChatStream

​StreamEvent

​ObjectStream

​ObjectStreamEvent

​Usage types

​ChatUsage

​ChatInputTokenDetails

​ChatOutputTokenDetails

​EmbeddingUsage

​Embedding types

​EmbedOptions

​EmbedResult

​Image generation types

​ImageGenerateOptions

​ImageGenerateResult

​GeneratedImage

​Type usage examples

​Building type-safe conversations

​Type-safe tool handling