Provider Setup

Baleybots is a composition layer on top of AI SDK v7 (ai ^7.0.0). All LLM calls — streaming, structured output, tools, and stop conditions — route through AI SDK providers. Install the @ai-sdk/* packages for the models you need.

Provider resolution

Baleybots auto-detects your provider from:

1. Explicit model — a model string, ModelConfig object, or AI SDK LanguageModel instance
2. Environment variables — if OPENAI_API_KEY is set, defaults to OpenAI. If ANTHROPIC_API_KEY is set, defaults to Anthropic.

OpenAI

npm install @ai-sdk/openai
export OPENAI_API_KEY="sk-..."

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

// Auto-detected from env
const bot = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
});

// Model string
const bot2 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: 'openai|gpt-4o-mini',
});

// Factory helper (recommended)
const bot3 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: openai('gpt-4o-mini'),
});

Anthropic

npm install @ai-sdk/anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

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

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

// Or with the factory helper
const bot2 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: anthropic('claude-haiku-4-5'),
});

Ollama (local)

npm install ollama-ai-provider-v2
# Make sure Ollama is running locally

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

Direct LanguageModel (preferred for custom endpoints)

For community providers, OpenAI-compatible servers, or anything outside the built-in model strings, pass an AI SDK LanguageModel instance directly. Baleybots detects it and forwards to AI SDK with no name parsing.

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

const bot = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: createOpenAI({ apiKey: process.env.OPENAI_API_KEY })('gpt-4o-mini'),
});

See the Custom models guide for createOpenAICompatible, community providers, and OpenRouter.

Legacy ModelConfig object

You can still pass a ModelConfig object with { id, config } for per-model API keys, custom base URLs, or a custom fetch. Prefer openai() / anthropic() factories or a direct LanguageModel for new code.

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

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

Custom fetch

Override fetch for special environments (Tauri, React Native, testing):

import { Baleybot, openai } from '@baleybots/core';
import { fetch as tauriFetch } from '@tauri-apps/plugin-http';

// Via factory helper
const bot = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: openai('gpt-4o-mini', { fetch: tauriFetch }),
});

// Via ModelConfig
const bot2 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: { id: 'gpt-4o', config: { fetch: tauriFetch } },
});

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

const bot3 = Baleybot.create({
  name: 'responder',
  goal: 'Answer user questions',
  model: { id: 'gpt-4o', config: { fetch: mockFetch } },
});

Environment variable priority

When no explicit model is provided:

1. OPENAI_API_KEY — uses OpenAI (gpt-4.1-mini)
2. ANTHROPIC_API_KEY — uses Anthropic (claude-haiku-4-5)
3. Ollama — checked if running locally

Set both keys and use the model option to pick which provider to use per processor.