Provider System

Baleybots uses the AI SDK (v6) under the hood for all LLM interactions. Provider resolution is automatic based on model strings and environment variables.

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: 'bot',
  goal: 'Help users',
  model: 'openai|gpt-4.1-mini',
});

// Anthropic
const bot2 = Baleybot.create({
  name: 'bot',
  goal: 'Help users',
  model: 'anthropic|claude-sonnet-4-20250514',
});

// Google
const bot3 = Baleybot.create({
  name: 'bot',
  goal: 'Help users',
  model: 'google|gemini-2.0-flash',
});

// Ollama (local)
const bot4 = Baleybot.create({
  name: 'bot',
  goal: 'Help users',
  model: 'ollama|llama3.2',
});

Resolution priority

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

1. Explicit model string -- model: 'openai|gpt-4.1-mini' always wins
2. Environment variables -- if no model is set, checks for OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
3. Local Ollama -- falls back to a local Ollama instance if available

Provider configuration

For more control, pass a model config object:

const bot = new Baleybot({
  name: 'bot',
  goal: 'Help users',
  model: {
    id: 'gpt-4.1',
    provider: {
      apiKey: 'sk-...',
      baseUrl: 'https://custom-endpoint.com/v1',
    },
  },
});

Custom fetch

For special environments like Tauri or React Native, provide a custom fetch function:

import { fetch as expoFetch } from 'expo/fetch';

const bot = new Baleybot({
  name: 'bot',
  goal: 'Help users',
  model: {
    id: 'gpt-4.1-mini',
    provider: {
      fetch: expoFetch,
    },
  },
});

This replaces the old transport layer. Any environment that can provide 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 = new Baleybot({
  name: 'bot',
  goal: 'Help users',
  model: {
    id: 'gpt-4.1',
    provider: { fetch: mockFetch },
  },
});

Supported providers

Any provider supported by the AI SDK works with Baleybots. Common providers 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)

See the Provider Setup guide for detailed setup instructions.