Chat Completion

The generate() function provides synchronous chat completion, returning a complete response from the language model.

Basic Usage

Generate a simple chat completion:

import { generate } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chatModel('gpt-5-mini');

const result = await generate({
    model,
    messages: [
        {
            role: 'system',
            content: 'You are a concise technical assistant.',
        },
        {
            role: 'user',
            content:
                'Explain what an embedding vector is in one short paragraph.',
        },
    ],
});

console.log('Response:', result.content);
console.log('Usage:', result.usage);

Using Different Providers

core-ai supports multiple providers with the same API:

OpenAI
Anthropic
Google
Mistral

import { generate } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY
});
const model = openai.chatModel('gpt-5-mini');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
});

import { generate } from '@core-ai/core-ai';
import { createAnthropic } from '@core-ai/anthropic';

const anthropic = createAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});
const model = anthropic.chatModel('claude-haiku-4-5');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
  maxTokens: 256,
});

import { generate } from '@core-ai/core-ai';
import { createGoogleGenAI } from '@core-ai/google-genai';

const google = createGoogleGenAI({
  apiKey: process.env.GOOGLE_API_KEY
});
const model = google.chatModel('gemini-3.1-pro');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
  maxTokens: 256,
});

import { generate } from '@core-ai/core-ai';
import { createMistral } from '@core-ai/mistral';

const mistral = createMistral({
  apiKey: process.env.MISTRAL_API_KEY
});
const model = mistral.chatModel('mistral-small-2506');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
  maxTokens: 256,
});

Configuration options

Customize model behavior with configuration parameters:

import { generate } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chat.chatModel('gpt-5-mini');

const result = await generate({
    model,
    messages: [{ role: 'user', content: 'Tell me a story.' }],
    temperature: 0.7,
    maxTokens: 500,
    topP: 0.9,
    providerOptions: {
        openai: {
            stopSequences: ['\n\n'],
            frequencyPenalty: 0.5,
            presencePenalty: 0.3,
        },
    },
});

temperature, maxTokens, and topP are top-level options. stopSequences, frequencyPenalty, and presencePenalty are provider-specific and passed via providerOptions. OpenAI supports them through openai.chat.chatModel() and @core-ai/openai-compat, not through Responses models. See Configuration for details.

Response Structure

The generate() function returns a GenerateResult object:

type GenerateResult = {
    parts: AssistantContentPart[]; // Raw response parts
    content: string | null; // Text content (null if only tool calls)
    reasoning: string | null; // Reasoning content (if available)
    toolCalls: ToolCall[]; // Tool calls made by model
    finishReason: FinishReason; // Why generation stopped
    usage: ChatUsage; // Token usage information
};

Understanding Token Usage

const result = await generate({ model, messages });

console.log('Input tokens:', result.usage.inputTokens);
console.log('Output tokens:', result.usage.outputTokens);

// Token details breakdown
console.log('Cache read:', result.usage.inputTokenDetails.cacheReadTokens);
console.log('Cache write:', result.usage.inputTokenDetails.cacheWriteTokens);

if (result.usage.outputTokenDetails.reasoningTokens) {
    console.log(
        'Reasoning tokens:',
        result.usage.outputTokenDetails.reasoningTokens
    );
}

Multi-turn conversations

Build conversations by including previous messages. Use resultToMessage() to convert a GenerateResult into an AssistantMessage:

import { generate, resultToMessage } from '@core-ai/core-ai';

const messages = [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is TypeScript?' },
];

const firstResponse = await generate({ model, messages });

messages.push(resultToMessage(firstResponse));
messages.push({
    role: 'user',
    content: 'How is it different from JavaScript?',
});

const secondResponse = await generate({ model, messages });
console.log(secondResponse.content);

Error Handling

Handle errors gracefully:

import { CoreAIError, ProviderError } from '@core-ai/core-ai';

try {
    const result = await generate({ model, messages });
    console.log(result.content);
} catch (error) {
    if (error instanceof ProviderError) {
        console.error('Provider error:', error.message);
        console.error('Status code:', error.statusCode);
    } else if (error instanceof CoreAIError) {
        console.error('CoreAIError:', error.message);
    } else {
        console.error('Unknown error:', error);
    }
}

Best Practices

Use system messages for consistent behavior

System messages set the assistant’s behavior and context:

const result = await generate({
  model,
  messages: [
    {
      role: 'system',
      content: 'You are a concise technical writer. Always use examples.',
    },
    { role: 'user', content: 'Explain async/await' },
  ],
});

Set appropriate token limits

Control costs and response length with maxTokens:

const result = await generate({
  model,
  messages,
  maxTokens: 200,
});

if (result.finishReason === 'length') {
  console.warn('Response was truncated');
}

Handle finish reasons appropriately

Check why generation stopped:

const result = await generate({ model, messages });

switch (result.finishReason) {
  case 'stop':
    // Normal completion
    break;
  case 'length':
    // Hit token limit
    console.warn('Response truncated');
    break;
  case 'tool-calls':
    // Model wants to use tools
    break;
  case 'content-filter':
    // Content filtered by provider
    console.warn('Content filtered');
    break;
}

Next Steps

Streaming

Stream responses in real-time for better UX

Tool Calling

Let models use tools and functions

Multi-Modal

Work with images and files

Structured Outputs

Get type-safe JSON responses

Get Started

Core Concepts

Guides

Observability

Examples

Chat Completion

Basic Usage

Using Different Providers

Configuration options

Response Structure

Understanding Token Usage

Multi-turn conversations

Error Handling

Best Practices

Next Steps

Streaming

Tool Calling

Multi-Modal

Structured Outputs

​Basic Usage

​Using Different Providers

​Configuration options

​Response Structure

​Understanding Token Usage

​Multi-turn conversations

​Error Handling

​Best Practices

​Next Steps

Streaming

Tool Calling

Multi-Modal

Structured Outputs

Basic Usage

Using Different Providers

Configuration options

Response Structure

Understanding Token Usage

Multi-turn conversations

Error Handling

Best Practices

Next Steps