Provider System

Baleybots routes all LLM interactions through AI SDK v7 (ai ^7.0.0). Provider resolution is automatic based on model strings, factory helpers, environment variables, or a direct LanguageModel passthrough.

Model strings

The simplest way to select a provider is with a model string:

import { Baleybot } from '@baleybots/core';

// OpenAI
const bot = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: 'openai|gpt-4.1-mini',
});

// Anthropic
const bot2 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: 'anthropic|claude-sonnet-4-20250514',
});

// Google
const bot3 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: 'google|gemini-2.0-flash',
});

// Ollama (local)
const bot4 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: 'ollama|llama3.2',
});

Factory helpers

For explicit provider configuration without constructing a LanguageModel yourself, use the re-exported factories from @baleybots/core:

import { Baleybot, openai, anthropic } from '@baleybots/core';

const gpt = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: openai('gpt-4.1-mini'),
});

const claude = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: anthropic('claude-haiku-4-5', { apiKey: process.env.ANTHROPIC_API_KEY }),
});

These return ModelConfig objects that Baleybots resolves to AI SDK LanguageModel instances internally.

LanguageModel passthrough

For community providers, custom endpoints, and the full AI SDK catalog, pass a LanguageModel instance directly as model:. Baleybots detects it via isAISDKLanguageModel and forwards it straight to AI SDK — no registration API required.

See the Custom models guide for createOpenAICompatible, community @ai-sdk/* packages, and OpenRouter.

Resolution priority

When resolving which provider to use, Baleybots follows this order:

1. Explicit model — string, ModelConfig, or LanguageModel always wins
2. Environment variables — if no model is set, checks for OPENAI_API_KEY, then ANTHROPIC_API_KEY
3. Local Ollama — falls back to a local Ollama instance if available

Legacy ModelConfig

For per-model API keys, custom base URLs, or custom fetch, you can pass a ModelConfig object. Prefer factory helpers or direct LanguageModel passthrough for new code.

const bot = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: {
    id: 'gpt-4.1',
    config: {
      apiKey: 'sk-...',
      baseUrl: 'https://custom-endpoint.com/v1',
    },
  },
});

Custom fetch

For special environments like Tauri or React Native, provide a custom fetch function via the factory helper or ModelConfig.config:

import { fetch as expoFetch } from 'expo/fetch';
import { Baleybot, openai } from '@baleybots/core';

const bot = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: openai('gpt-4.1-mini', { fetch: expoFetch }),
});

Any environment that provides a fetch-compatible function works with Baleybots.

Testing with mock fetch

Use a mock fetch to test without making real API calls:

const mockFetch = vi.fn().mockResolvedValue(
  new Response(JSON.stringify({
    choices: [{ message: { content: 'Hello!' } }],
  }))
);

const bot = Baleybot.create({
  name: 'responder',
  goal: 'Help users',
  model: { id: 'gpt-4.1', config: { fetch: mockFetch } },
});

Supported providers

Any provider supported by the AI SDK works with Baleybots. Built-in model-string prefixes include:

Provider	Model string prefix	Env variable
OpenAI	openai|	OPENAI_API_KEY
Anthropic	anthropic|	ANTHROPIC_API_KEY
Google	google|	GOOGLE_GENERATIVE_AI_API_KEY
Ollama	ollama|	None (local)

For providers outside this table, pass an AI SDK LanguageModel directly. See the Provider Setup guide for detailed setup instructions.