Providers - core-ai

Overview

Providers are the bridge between core-ai and LLM services like OpenAI, Azure OpenAI, Anthropic, Google GenAI, Vertex AI, and Mistral. Each provider implements a unified interface that abstracts away provider-specific details, allowing you to switch between providers with minimal code changes.

Provider Interface

All providers implement methods to create model instances:

type Provider = {
    chatModel(modelId: string): ChatModel;
    embeddingModel?(modelId: string): EmbeddingModel;
    imageModel?(modelId: string): ImageModel;
};

Not all providers support all model types. For example, Anthropic only supports chat models, while OpenAI and Google GenAI support chat, embedding, and image models.

OpenAI

OpenAI is one of the most popular providers, offering chat, embedding, and image generation models.

Creating a Provider

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

const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY, // Optional: defaults to OPENAI_API_KEY env var
    baseURL: 'https://api.openai.com/v1', // Optional: custom base URL
});

Provider Options

type OpenAIProviderOptions = {
    apiKey?: string;
    baseURL?: string;
    client?: OpenAI; // Optional: bring your own OpenAI client
};

Getting Models

const gpt5 = openai.chatModel('gpt-5-mini');
const gpt5Chat = openai.chat.chatModel('gpt-5-mini');
const embeddings = openai.embeddingModel('text-embedding-3-small');
const imageModel = openai.imageModel('gpt-image-1');

createOpenAI().chatModel() uses the Responses API. openai.chat.chatModel() uses strict Chat Completions. Use @core-ai/openai-compat for third-party compatible endpoints.

Azure OpenAI

Azure OpenAI provides chat models deployed in your Azure resource. Azure v1 uses Responses by default and exposes Chat Completions through azure.chat.chatModel(). Classic mode supports Chat Completions only.

Creating a Provider

import { createAzureOpenAI } from '@core-ai/azure-openai';

const azure = createAzureOpenAI({
    apiKey: process.env.AZURE_OPENAI_API_KEY,
    endpoint: process.env.AZURE_OPENAI_ENDPOINT,
});

Provider Options

type AzureOpenAIProviderOptions = {
    api?: 'v1' | 'classic';
    apiKey?: string;
    endpoint?: string;
    apiVersion?: string;
    deployment?: string;
    azureADTokenProvider?: () => Promise<string>;
    client?: OpenAIChatClient;
};

Getting Models

const model = azure.chatModel('gpt-5-mini-deployment');

Use your Azure OpenAI deployment name as the model id.

Anthropic

Anthropic provides powerful chat models like Claude, with advanced capabilities for extended thinking and reasoning.

Creating a Provider

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

const anthropic = createAnthropic({
    apiKey: process.env.ANTHROPIC_API_KEY,
    defaultMaxTokens: 4096, // Optional: default max tokens for responses
});

Provider Options

type AnthropicProviderOptions = {
    apiKey?: string;
    baseURL?: string;
    client?: AnthropicChatClient; // Optional: bring your own Anthropic client
    defaultMaxTokens?: number; // Optional: defaults to 4096
};

Getting Models

const claude = anthropic.chatModel('claude-sonnet-4-6');
const claudeOpus = anthropic.chatModel('claude-opus-4-6');

Anthropic requires a maxTokens value for all requests. The defaultMaxTokens option sets a default value that can be overridden per request.

Anthropic on Vertex AI

Anthropic on Vertex AI provides Claude models hosted on Google Cloud, sharing its request, streaming, and reasoning behavior with the direct Anthropic provider.

Creating a Provider

import { createAnthropicVertex } from '@core-ai/anthropic-vertex';

const anthropicVertex = createAnthropicVertex({
    projectId: process.env.GOOGLE_VERTEX_PROJECT,
    region: 'europe-west1',
});

Provider Options

type AnthropicVertexProviderOptions = {
    projectId?: string; // Required unless client is provided
    region?: string; // Required unless client is provided
    credentials?: Record<string, unknown>; // Optional: service account JSON; falls back to ADC
    client?: AnthropicChatClient; // Optional: bring your own client
    defaultMaxTokens?: number; // Optional: defaults to 4096
};

Getting Models

const claude = anthropicVertex.chatModel('claude-sonnet-4-6');

Without explicit credentials, the provider uses Application Default Credentials (ADC). A provider instance targets a single region — create separate providers for models hosted in different regions.

Google GenAI

Google GenAI provides access to Gemini models for chat, embeddings, and native image generation, plus dedicated Imagen models.

Creating a Provider

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

const google = createGoogleGenAI({
    apiKey: process.env.GOOGLE_API_KEY,
    apiVersion: 'v1beta', // Optional: API version
    baseUrl: 'https://generativelanguage.googleapis.com', // Optional
});

Provider Options

type GoogleGenAIProviderOptions = {
    apiKey?: string;
    apiVersion?: string;
    baseUrl?: string;
    client?: GoogleGenAIClient; // Optional: bring your own GoogleGenAI client
};

Getting Models

const gemini = google.chatModel('gemini-3.1-pro');
const embeddings = google.embeddingModel('text-embedding-004');
const image = google.imageModel('gemini-2.5-flash-image');
const imagen = google.imageModel('imagen-4.0-generate-001');

Google on Vertex AI

Google on Vertex AI provides Gemini chat, embedding, and native image models plus Imagen through regional Google Cloud endpoints.

Creating a Provider

import { createGoogleVertex } from '@core-ai/google-vertex';

const googleVertex = createGoogleVertex({
    projectId: process.env.GOOGLE_VERTEX_PROJECT,
    region: 'europe-west1',
});

Provider Options

type GoogleVertexProviderOptions = {
    projectId?: string; // Required unless client is provided
    region?: string; // Required unless client is provided
    credentials?: GoogleVertexServiceAccountCredentials; // Optional: service account JSON; falls back to ADC
    client?: GoogleGenAIClient; // Optional: bring your own client
};

Getting Models

const gemini = googleVertex.chatModel('gemini-2.5-flash');
const embeddings = googleVertex.embeddingModel('gemini-embedding-001');
const image = googleVertex.imageModel('gemini-2.5-flash-image');
const imagen = googleVertex.imageModel('imagen-4.0-generate-001');

Without explicit credentials, the provider uses Application Default Credentials (ADC). A provider instance targets a single region.

Mistral

Mistral provides efficient open-source and proprietary models for chat and embeddings.

Creating a Provider

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

const mistral = createMistral({
    apiKey: process.env.MISTRAL_API_KEY,
    baseURL: 'https://api.mistral.ai', // Optional
});

Provider Options

type MistralProviderOptions = {
    apiKey?: string;
    baseURL?: string;
    client?: Mistral; // Optional: bring your own Mistral client
};

Getting Models

// Chat models
const mistralLarge = mistral.chatModel('mistral-large-2512');
const mistralMedium = mistral.chatModel('mistral-medium-2508');
const mistralSmall = mistral.chatModel('mistral-small');

// Embedding models
const embeddings = mistral.embeddingModel('mistral-embed');

Omnifact

Omnifact provides access to the Omnifact API Gateway — an OpenAI-compatible endpoint for chat completions backed by your organization’s enabled models.

Creating a Provider

import { createOmnifact } from '@core-ai/omnifact';

const omnifact = createOmnifact({
    apiKey: process.env.OMNIFACT_API_KEY,
    // baseURL defaults to https://connect.omnifact.ai/v1/gateway
});

Provider Options

type OmnifactProviderOptions = {
    apiKey?: string;
    baseURL?: string;
};

Getting Models

// EU-hosted models use the eu/ prefix.
const model = omnifact.chatModel('eu/gpt-5-mini');

Use model IDs enabled for your organization in Omnifact. Pass providerOptions.openai for supported Chat Completions options. Omnifact also accepts the nonstandard reasoning fields documented by @core-ai/openai-compat.

Kimi

Kimi provides access to Moonshot AI models through the Kimi API, including native reasoning_content support for thinking models.

Creating a Provider

import { createKimi } from '@core-ai/kimi';

const kimi = createKimi({
  apiKey: process.env.KIMI_API_KEY,
});

Getting Models

const model = kimi.chatModel('kimi-k2.7-code');

Pass providerOptions.kimi for Kimi-specific Chat Completions options. Kimi K2.7 Code always runs in thinking mode; core-ai preserves reasoning_content across turns via resultToMessage().

Using Custom Clients

All providers support bringing your own client instance, which is useful for advanced configuration:

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

const customClient = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY,
    timeout: 30000,
    maxRetries: 3,
    // Any other OpenAI client options
});

const openai = createOpenAI({ client: customClient });

Provider Comparison

Provider	Chat	Embeddings	Images	Special Features
OpenAI	✓	✓	✓	Most comprehensive model selection
Azure OpenAI	✓	✗	✗	Azure deployments and Entra ID auth
Anthropic	✓	✗	✗	Extended thinking, prompt caching
Anthropic on Vertex AI	✓	✗	✗	Claude on Google Cloud, ADC auth
Google GenAI	✓	✓	✓	Gemini native images and Imagen
Google on Vertex AI	✓	✓	✓	Gemini native images and Imagen on Vertex
Mistral	✓	✓	✗	Efficient open-source options
Omnifact	✓	✗	✗	Organization gateway for enabled models
Kimi	✓	✗	✗	Preserved thinking, coding focus

Next Steps

Learn about Models to understand different model types
Explore Messages to see how to structure conversations
Configure models with Configuration options

​Overview

​Provider Interface

​OpenAI

​Creating a Provider

​Provider Options

​Getting Models

​Azure OpenAI

​Creating a Provider

​Provider Options

​Getting Models

​Anthropic

​Creating a Provider

​Provider Options

​Getting Models

​Anthropic on Vertex AI

​Creating a Provider

​Provider Options

​Getting Models

​Google GenAI

​Creating a Provider

​Provider Options

​Getting Models

​Google on Vertex AI

​Creating a Provider

​Provider Options

​Getting Models

​Mistral

​Creating a Provider

​Provider Options

​Getting Models

​Omnifact

​Creating a Provider

​Provider Options

​Getting Models

​Kimi

​Creating a Provider

​Getting Models

​Using Custom Clients

​Provider Comparison

​Next Steps

Overview

Provider Interface

OpenAI

Creating a Provider

Provider Options

Getting Models

Azure OpenAI

Creating a Provider

Provider Options

Getting Models

Anthropic

Creating a Provider

Provider Options

Getting Models

Anthropic on Vertex AI

Creating a Provider

Provider Options

Getting Models

Google GenAI

Creating a Provider

Provider Options

Getting Models

Google on Vertex AI

Creating a Provider

Provider Options

Getting Models

Mistral

Creating a Provider

Provider Options

Getting Models

Omnifact

Creating a Provider

Provider Options

Getting Models

Kimi

Creating a Provider

Getting Models

Using Custom Clients

Provider Comparison

Next Steps