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

# generate()

> Generate a single response from a chat model

## Overview

The `generate()` function generates a single response from a chat model. It's the core function for synchronous text generation with support for tool calls, reasoning, and structured conversations.

## Function signature

```typescript theme={null}
export async function generate(
    params: GenerateParams
): Promise<GenerateResult>

export type GenerateParams = GenerateOptions & {
    model: ChatModel;
};
```

## Parameters

<ParamField path="model" type="ChatModel" required>
  The chat model instance to use for generation.
</ParamField>

<ParamField path="messages" type="Message[]" required>
  Array of messages in the conversation. Must not be empty.
</ParamField>

<ParamField path="temperature" type="number">
  Sampling temperature (0-2). Higher values make output more random.
</ParamField>

<ParamField path="maxTokens" type="number">
  Maximum number of tokens to generate.
</ParamField>

<ParamField path="topP" type="number">
  Nucleus sampling parameter (0-1).
</ParamField>

<ParamField path="reasoning" type="ReasoningConfig">
  Configuration for extended thinking/reasoning capabilities.

  <Expandable title="ReasoningConfig">
    <ParamField path="effort" type="ReasoningEffort" required>
      The effort level for reasoning: `'minimal'`, `'low'`, `'medium'`, `'high'`, or `'max'`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="tools" type="ToolSet">
  Object mapping tool names to tool definitions. Enables the model to call functions.
</ParamField>

<ParamField path="toolChoice" type="ToolChoice">
  Controls how the model uses tools:

  * `'auto'` - Model decides whether to use tools
  * `'none'` - Model won't use tools
  * `'required'` - Model must use a tool
  * `{ type: 'tool', toolName: string }` - Force specific tool
</ParamField>

<ParamField path="providerOptions" type="GenerateProviderOptions">
  Provider-specific options, namespaced by provider name (e.g. `{ openai: { user: '...' } }`).
</ParamField>

<ParamField path="signal" type="AbortSignal">
  AbortSignal for cancelling the request.
</ParamField>

## Return value

Returns a `Promise<GenerateResult>` with the following properties:

<ResponseField name="parts" type="AssistantContentPart[]">
  Array of content parts in the response (text, reasoning, tool calls).
</ResponseField>

<ResponseField name="content" type="string | null">
  Concatenated text content from all text parts. `null` if no text was generated.
</ResponseField>

<ResponseField name="reasoning" type="string | null">
  Concatenated reasoning content. `null` if no reasoning was generated.
</ResponseField>

<ResponseField name="toolCalls" type="ToolCall[]">
  Array of tool calls made by the model.
</ResponseField>

<ResponseField name="finishReason" type="FinishReason">
  Why generation stopped: `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'unknown'`.
</ResponseField>

<ResponseField name="usage" type="ChatUsage">
  Token usage statistics including input/output tokens and cache details.

  <Expandable title="ChatUsage">
    <ResponseField name="inputTokens" type="number">
      Total input tokens, including cached and cache-write tokens.
    </ResponseField>

    <ResponseField name="outputTokens" type="number">
      Total output tokens, including both visible text and reasoning.
    </ResponseField>

    <ResponseField name="inputTokenDetails" type="ChatInputTokenDetails">
      Breakdown of input token categories (cacheReadTokens, cacheWriteTokens).
    </ResponseField>

    <ResponseField name="outputTokenDetails" type="ChatOutputTokenDetails">
      Breakdown of output token categories (reasoningTokens if available).
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Basic text generation

```typescript theme={null}
import { generate } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

const openai = createOpenAI();
const model = openai.chatModel('gpt-5-mini');

const result = await generate({
  model,
  messages: [
    { role: 'user', content: 'What is the capital of France?' }
  ]
});

console.log(result.content);
```

### With configuration

```typescript theme={null}
const result = await generate({
  model,
  messages: [
    { role: 'user', content: 'Write a creative story' }
  ],
  temperature: 1.5,
  maxTokens: 500,
});
```

### With tools

```typescript theme={null}
import { generate, defineTool } from '@core-ai/core-ai';
import { z } from 'zod';

const weatherTool = defineTool({
  name: 'get_weather',
  description: 'Get weather for a location',
  parameters: z.object({
    location: z.string()
  })
});

const result = await generate({
  model,
  messages: [
    { role: 'user', content: 'What\'s the weather in Paris?' }
  ],
  tools: {
    get_weather: weatherTool
  }
});

if (result.toolCalls.length > 0) {
  console.log('Tool called:', result.toolCalls[0].name);
  console.log('Arguments:', result.toolCalls[0].arguments);
}
```

### Multi-turn conversation

```typescript theme={null}
const result = await generate({
  model,
  messages: [
    { 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: 'Tell me a joke' }
  ]
});
```

## Error handling

Throws `ValidationError` if:

* Messages array is empty

May also throw:

* `ProviderError` if the provider returns an error during generation

```typescript theme={null}
import { ValidationError } from '@core-ai/core-ai';

try {
  const result = await generate({
    model,
    messages: []
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Generation failed:', error.message);
  }
}
```