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

SystemMessage

type SystemMessage = {
    role: 'system';
    content: string;
    /** Provider-specific options for this message, keyed by provider id. */
    providerOptions?: SystemMessageProviderOptions;
    metadata?: Record<string, unknown>;
};

Where a system message may appear depends on the model. See ModelCapabilities.messages.systemPlacement below and System message placement.

UserMessage

type UserMessage = {
    role: 'user';
    content: string | UserContentPart[];
    /** Provider-specific options for this message, keyed by provider id. */
    providerOptions?: UserMessageProviderOptions;
};

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

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

ToolDiscoveryCallPart

type ToolDiscoveryCall = {
    id: string;
    /** Exact tool names the model asked for. */
    names?: string[];
    /** Keywords describing the capability the model needs. */
    query?: string;
    metadata?: Record<string, unknown>;
};

type ToolDiscoveryCallPart = {
    type: 'tool-discovery-call';
    discoveryCall: ToolDiscoveryCall;
    providerMetadata?: Record<string, Record<string, unknown>>;
};

A call from the model asking for tools the request does not declare yet (see GenerateOptions.toolDiscovery). Answer it with one ToolDiscoveryResultMessage before the next request. The part wraps the call as ToolCallPart wraps a ToolCall. Discovery calls appear in GenerateResult.discoveryCalls, never in toolCalls. providerMetadata follows the same ownership rules as on ToolCallPart. See Tool Discovery.

ToolResultMessage

type ToolResultMessage = {
    role: 'tool';
    toolCallId: string;
    content: string;
    isError?: boolean;
    /** Provider-specific options for this message, keyed by provider id. */
    providerOptions?: ToolResultMessageProviderOptions;
    metadata?: Record<string, unknown>;
};

ToolDiscoveryResultMessage

type ToolDiscoveryResultMessage = {
    role: 'tool-discovery';
    /** `id` of the answered `ToolDiscoveryCallPart`. */
    discoveryCallId: string;
    tools: ToolSnapshot[];
    /** Explains an empty result to the model; only allowed without tools. */
    note?: string;
    /** Options for this discovery result, keyed by provider id. */
    providerOptions?: ToolDiscoveryResultMessageProviderOptions;
    metadata?: Record<string, unknown>;
};

Answers one ToolDiscoveryCallPart. Place it with the step’s tool results: after the assistant message, in any order relative to ToolResultMessages. tools may be empty when nothing matched; note can then tell the model why. The tools it lists stay declared on later generate() and stream() requests while the message is in the history, unless tools declares the same name. metadata on message parts, tool calls, tool results, and discovery 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.

Schema types

SchemaInput

The schema type for tool parameters and structured outputs.

type SchemaInput =
    | StandardSchemaWithJson
    | JsonSchema
    | (object & { readonly '~standard'?: never });

type JsonSchema = Record<string, unknown>;

type StandardSchemaWithJson<Input = unknown, Output = Input> = StandardSchemaV1<
    Input,
    Output
> &
    StandardJSONSchemaV1<Input, Output>;

StandardSchemaWithJson is a Standard Schema that can also produce JSON Schema, such as a Zod 4.2+ schema. core-ai converts it to the JSON Schema of its input type and validates structured output with it. validateToolCall() validates tool calls with it.
JsonSchema is a plain JSON Schema object. core-ai sends it as is and never validates against it. Any other object type is accepted as plain JSON Schema too, including interfaces such as JSONSchema7 from @types/json-schema, unless it is a Standard Schema without JSON Schema support.

See Schemas for the supported libraries. @core-ai/core-ai also exports the Standard Schema type namespaces StandardSchemaV1, StandardJSONSchemaV1, and StandardTypedV1.

InferSchemaOutput

type InferSchemaOutput<TSchema extends SchemaInput> =
    TSchema extends StandardSchemaV1
        ? StandardSchemaV1.InferOutput<TSchema>
        : unknown;

The value a schema validates to: the Standard Schema’s output type, or unknown for plain JSON Schema.

Tool types

ToolDefinition

type ToolDefinition<TParameters extends SchemaInput = SchemaInput> = {
    name: string;
    description: string;
    parameters: TParameters;
    strict?: boolean;
};

parameters is a Standard Schema with JSON Schema support, such as a Zod 4.2+ schema, or plain JSON Schema. Validate calls to tools with Standard Schema parameters with validateToolCall(), which returns a ToolCallValidation. strict: true opts the tool into provider-enforced adherence to its parameter schema; the schema must fit the strict-capable contract described in the tool-calling guide. Omitted or false keeps the tool non-strict on every provider.

ToolCallValidation

type ToolCallValidation<TParameters extends SchemaInput> =
    TParameters extends StandardSchemaV1
        ? StandardSchemaV1.Result<InferSchemaOutput<TParameters>>
        : undefined;

The result of validateToolCall(): the schema’s result, { value } or { issues }, for Standard Schema parameters, and undefined for plain JSON Schema, which core-ai never validates.

ToolSet

type ToolSet = Record<string, ToolDefinition>;

ToolSnapshot

type ToolSnapshot = ToolDefinition<JsonSchema>;

A discovered tool, returned in a ToolDiscoveryResultMessage. Its parameters are plain JSON Schema, so messages stay plain data and render byte for byte on every request. Produce them from a Standard Schema with toJsonSchema(). core-ai does not validate calls to discovered tools.

ToolDiscoveryOptions

type ToolDiscoveryOptions = {
    description?: string;
};

description is appended to the discovery tool’s default description, which only explains how discovery works. Use it, for example, to list the discoverable tool names.

ToolChoice

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

With tool discovery in use, { type: 'tool', toolName } may only name a tool in tools. 'none' also keeps the model from discovering tools, and a discovery call satisfies 'required'.

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 SchemaInput>(
        options: GenerateObjectOptions<TSchema>
    ): Promise<GenerateObjectResult<TSchema>>;
    streamObject<TSchema extends SchemaInput>(
        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 SystemMessagePlacement = 'leading' | 'before-reply' | 'anywhere';

type ToolDiscoverySupport = 'native' | 'emulated';

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[];
    };
    tools: {
        strictSchemas:
            | { supported: false }
            | {
                  supported: true;
                  maxStrictTools?: number;
                  maxUnionParameters?: number;
              };
        toolDiscovery: ToolDiscoverySupport;
    };
    messages: {
        systemPlacement: SystemMessagePlacement;
    };
    output?: {
        maxTokens: number;
    };
};

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
`tools.strictSchemas.supported`	Whether `strict: true` is available for tool schemas
`tools.strictSchemas.maxStrictTools`	Optional per-request limit on the number of strict tools
`tools.strictSchemas.maxUnionParameters`	Optional per-request limit on union-typed parameters across strict tools
`tools.toolDiscovery`	Whether discovered tools are delivered natively or emulated
`messages.systemPlacement`	Where system messages may appear after the first non-system message
`output.maxTokens`	Verified output ceiling for one response, reasoning included

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. output is present only when the provider has a verified output ceiling for the model id. It is the limit an omitted maxTokens resolves to. A missing output means the ceiling is unknown. 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. Check model.capabilities.tools.strictSchemas before setting strict: true. Setting it on a model that reports { supported: false } throws ToolSchemaStrictnessError before the provider request. Unknown and future model IDs resolve optimistically to { supported: true }, so explicit strict tools are forwarded and the provider rejects them if the model genuinely lacks support. Strict tool schemas only govern tool arguments. They are separate from the response formats used by generateObject() and streamObject(). tools.toolDiscovery is 'native' when the model delivers discovered tools through the provider’s deferred tool loading, which keeps the prompt cache when the model discovers tools. 'emulated' declares discovered tools as ordinary tools, so each discovery changes the tool declarations. Your application code is the same for both. See Native and emulated discovery. messages.systemPlacement describes where a model accepts a system message that comes after the first non-system message. 'leading' accepts none, 'before-reply' accepts one directly after a user, tool, or tool discovery result message when it is last or followed by an assistant message, and 'anywhere' accepts any position. A system message that breaks the rule throws UnsupportedSystemMessagePlacementError before the provider request. Call getSystemMessagePlacementIssues(messages, placement) to check a conversation without sending it. Unknown Claude model IDs resolve to 'before-reply'. Provider packages also export get*ModelCapabilities(modelId) helpers for registry data without constructing a ChatModel. A model factory can apply API- or endpoint-specific gates afterward; for example, OpenAI Responses has narrower legacy-model support than Chat Completions. Kimi and xAI expose 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 by each provider adapter.

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

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

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

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

interface ToolDiscoveryResultMessageProviderOptions {
    [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. The key is always the provider id reported by model.provider, so each model reads only its own entry and ignores the rest:

providerOptions: {
  openai: { user: 'user-123', store: true },
  'azure-openai': { user: 'user-123' },
}

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;
    toolDiscovery?: ToolDiscoveryOptions;
};

toolDiscovery enables tool discovery: core-ai declares its discovery tool, and the model’s calls to it arrive as ToolDiscoveryCallParts. Keep it set consistently within a conversation; switching it costs a prompt cache rewrite. See Tool Discovery.

GenerateObjectOptions

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

schema is a Standard Schema with JSON Schema support, whose validated output becomes object, or plain JSON Schema, whose parsed JSON is returned without validation.

StreamObjectOptions

type StreamObjectOptions<TSchema extends SchemaInput> =
    GenerateObjectOptions<TSchema>;

Result types

GenerateResult

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

toolCalls holds the calls to your tools and to discovered tools; discoveryCalls holds the discovery calls. Both list the calls of parts in order. finishReason is 'tool-calls' when either has pending calls: answer both before the next request.

GenerateObjectResult

type GenerateObjectResult<TSchema extends SchemaInput> = {
    object: InferSchemaOutput<TSchema>;
    finishReason: FinishReason;
    usage: ChatUsage;
};

object is the schema’s validated output for a Standard Schema and the parsed JSON, typed unknown, for plain JSON Schema.

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>>;
      }
    | ToolDiscoveryCallPart
    | { type: 'finish'; finishReason: FinishReason; usage: ChatUsage };

A discovery call streams as a single tool-discovery-call event, a complete ToolDiscoveryCallPart, when the model finishes it. It has no start or delta events.

ObjectStream

Replayable handle for a structured object streaming operation.

type ObjectStream<TSchema extends SchemaInput> = AsyncIterable<
    ObjectStreamEvent<TSchema>
> & {
    readonly result: Promise<GenerateObjectResult<TSchema>>;
    readonly events: Promise<readonly ObjectStreamEvent<TSchema>[]>;
};

ObjectStreamEvent

type ObjectStreamEvent<TSchema extends SchemaInput> =
    | { type: 'object-delta'; text: string }
    | { type: 'object'; object: InferSchemaOutput<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

​ToolDiscoveryCallPart

​ToolResultMessage

​ToolDiscoveryResultMessage

​Schema types

​SchemaInput

​InferSchemaOutput

​Tool types

​ToolDefinition

​ToolCallValidation

​ToolSet

​ToolSnapshot

​ToolDiscoveryOptions

​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