> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core-ai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> Core type definitions for messages, models, and usage tracking

## 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.

```typescript theme={null}
type Message =
    | SystemMessage
    | UserMessage
    | AssistantMessage
    | ToolResultMessage;
```

### SystemMessage

```typescript theme={null}
type SystemMessage = {
    role: 'system';
    content: string;
};
```

### UserMessage

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

type UserContentPart = TextPart | ImagePart | FilePart;
```

### TextPart

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

### ImagePart

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

### FilePart

```typescript theme={null}
type FilePart = {
    type: 'file';
    data: string;
    mimeType: string;
    filename?: string;
};
```

### AssistantMessage

```typescript theme={null}
type AssistantMessage = {
    role: 'assistant';
    parts: AssistantContentPart[];
};

type AssistantContentPart = AssistantTextPart | ReasoningPart | ToolCallPart;
```

### AssistantTextPart

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

### ReasoningPart

```typescript theme={null}
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'`, or `'openai'`). Use [`getProviderMetadata()`](/api/core/utilities) for typed access.

### ToolCallPart

```typescript theme={null}
type ToolCallPart = {
    type: 'tool-call';
    toolCall: ToolCall;
};
```

### ToolCall

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

### ToolResultMessage

```typescript theme={null}
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

```typescript theme={null}
type ToolDefinition = {
    name: string;
    description: string;
    parameters: z.ZodType;
};
```

### ToolSet

```typescript theme={null}
type ToolSet = Record<string, ToolDefinition>;
```

### ToolChoice

```typescript theme={null}
type ToolChoice =
    | 'auto'
    | 'none'
    | 'required'
    | { type: 'tool'; toolName: string };
```

## Model types

### ChatModel

```typescript theme={null}
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 what the model supports for the unified API. Use it to decide whether to pass `reasoning` and which effort levels are valid.

### ModelCapabilities

```typescript theme={null}
type ModelCapabilities = {
    reasoning: {
        supported: boolean;
        supportedEfforts: readonly ReasoningEffort[];
        /**
         * When true, sampling parameters such as `temperature` and `topP`
         * must not be set alongside `reasoning`.
         */
        restrictsSamplingParams: boolean;
    };
};
```

| Field                               | Meaning                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------ |
| `reasoning.supported`               | Whether the model accepts `reasoning.effort` on generate/stream requests |
| `reasoning.supportedEfforts`        | Effort values the adapter accepts (empty when unsupported)               |
| `reasoning.restrictsSamplingParams` | When `true`, omit `temperature` / `topP` while reasoning is enabled      |

Provider packages also export `get*ModelCapabilities(modelId)` helpers that return the same data without constructing a `ChatModel`.

### EmbeddingModel

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

### ImageModel

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

## Configuration types

### ReasoningConfig

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
providerOptions: {
  openai: { user: 'user-123', store: true },
}
```

## Generation options

### BaseGenerateOptions

Shared options for all generation functions.

```typescript theme={null}
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.

```typescript theme={null}
type GenerateOptions = BaseGenerateOptions & {
    tools?: ToolSet;
    toolChoice?: ToolChoice;
};
```

### GenerateObjectOptions

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

### StreamObjectOptions

```typescript theme={null}
type StreamObjectOptions<TSchema extends z.ZodType> =
    GenerateObjectOptions<TSchema>;
```

## Result types

### GenerateResult

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

### GenerateObjectResult

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

### FinishReason

```typescript theme={null}
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.

```typescript theme={null}
type ChatStream = AsyncIterable<StreamEvent> & {
    readonly result: Promise<GenerateResult>;
    readonly events: Promise<readonly StreamEvent[]>;
};
```

### StreamEvent

```typescript theme={null}
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 }
    | { type: 'finish'; finishReason: FinishReason; usage: ChatUsage };
```

### ObjectStream

Replayable handle for a structured object streaming operation.

```typescript theme={null}
type ObjectStream<TSchema extends z.ZodType> = AsyncIterable<
    ObjectStreamEvent<TSchema>
> & {
    readonly result: Promise<GenerateObjectResult<TSchema>>;
    readonly events: Promise<readonly ObjectStreamEvent<TSchema>[]>;
};
```

### ObjectStreamEvent

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
type ChatInputTokenDetails = {
    cacheReadTokens: number;
    cacheWriteTokens: number;
};
```

### ChatOutputTokenDetails

```typescript theme={null}
type ChatOutputTokenDetails = {
    reasoningTokens?: number;
};
```

### EmbeddingUsage

```typescript theme={null}
type EmbeddingUsage = {
    inputTokens: number;
};
```

## Embedding types

### EmbedOptions

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

### EmbedResult

```typescript theme={null}
type EmbedResult = {
    embeddings: number[][];
    usage?: EmbeddingUsage;
};
```

## Image generation types

### ImageGenerateOptions

```typescript theme={null}
type ImageGenerateOptions = {
    prompt: string;
    n?: number;
    size?: string;
    providerOptions?: ImageProviderOptions;
};
```

### ImageGenerateResult

```typescript theme={null}
type ImageGenerateResult = {
    images: GeneratedImage[];
};
```

### GeneratedImage

```typescript theme={null}
type GeneratedImage = {
    base64?: string;
    url?: string;
    revisedPrompt?: string;
};
```

## Type usage examples

### Building type-safe conversations

```typescript theme={null}
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

```typescript theme={null}
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' }),
    };
}
```