Skip to main content

Class: Baleybot<TOutputSchema, TTools>

Defined in: packages/core/src/baleybot.ts:334

Baleybot (v2)

Main class for creating AI agents with tool calling and structured outputs.

Model Selection:

  • If model is provided, uses that model
  • If model is omitted, auto-selects based on available API keys:
    • Priority: OpenAI (gpt-4.1-mini) → Anthropic (claude-haiku-4-5)

Output Type Inference:

  • When outputSchema is undefined or omitted, the output type is inferred as string.

Type Parameters​

TOutputSchema​

TOutputSchema = undefined

TTools​

TTools extends Record<string, ToolDefinition | ZodToolDefinition | Processable> = Record<string, never>

Implements​

Constructors​

Constructor​

new Baleybot<TOutputSchema, TTools>(config): Baleybot<TOutputSchema, TTools>

Defined in: packages/core/src/baleybot.ts:446

Create a new Baleybot

Prefer using Baleybot.create() for better type inference. The constructor is kept simple - use create() for proper type inference.

Parameters​

config​

BaleybotConfig<TOutputSchema, TTools>

Returns​

Baleybot<TOutputSchema, TTools>

Properties​

config​

config: BaleybotConfig<TOutputSchema, TTools>

Defined in: packages/core/src/baleybot.ts:338

Methods​

clearHistory()​

clearHistory(): Promise<void>

Defined in: packages/core/src/baleybot.ts:1274

Clear the conversation history (if keepHistory is enabled)

This removes all user messages and assistant responses from the history, allowing you to start a fresh conversation while keeping the same bot instance.

Returns​

Promise<void>

Example​

const bot = Baleybot.create({
  name: 'assistant',
  goal: 'Help users',
  keepHistory: true
});

await bot.process('Hello');
await bot.process('Tell me a joke');

// Start fresh conversation
bot.clearHistory();

await bot.process('Hello'); // Bot won't remember previous messages

getBotNames()​

getBotNames(): string[]

Defined in: packages/core/src/baleybot.ts:1105

Get bot names from this bot

Returns​

string[]

Array containing this bot's name

Implementation of​

Processable.getBotNames

getHistory()​

getHistory(): History | undefined

Defined in: packages/core/src/baleybot.ts:1247

Get the conversation history (if keepHistory is enabled)

Returns​

History | undefined

History instance or undefined if history is not enabled

Example​

const bot = Baleybot.create({
  name: 'assistant',
  goal: 'Help users',
  keepHistory: true
});

await bot.process('Hello');
await bot.process('How are you?');

const history = bot.getHistory();
if (history) {
  const messages = await history.getMessagesForAPI();
  console.log('Conversation history:', messages);
}

getId()​

getId(): string

Defined in: packages/core/src/baleybot.ts:1112

Get the unique ID of this baleybot instance

Returns​

string

Implementation of​

Processable.getId

getName()​

getName(): string

Defined in: packages/core/src/baleybot.ts:1220

Get baleybot name

Returns​

string

listen()​

listen(config?): Promise<LiveSession>

Defined in: packages/core/src/baleybot.ts:1152

Start a live audio transcription session

Creates a bidirectional WebSocket session for streaming audio transcription. Events are emitted through both direct callbacks and the subscribeToAll() system.

Parameters​

config?​

LiveSessionConfig

Session configuration (sample rate, encoding, language, callbacks)

Returns​

Promise<LiveSession>

Connected LiveSession ready to receive audio via sendAudio()

Example​

const session = await bot.listen({
  sampleRate: 16000,
  onTranscript: (event) => console.log(event.text, event.isFinal),
});
session.sendAudio(pcm16Chunk);
session.close();

process()​

process(input, options?): Promise<InferSchemaOutput<TOutputSchema>>

Defined in: packages/core/src/baleybot.ts:855

Process input and return structured output

Implements the Processable interface for universal composability. Supports both string input (text) and UnifiedMessageInput (multimodal).

Parameters​

input​

string | UnifiedMessageInput

options?​

ProcessOptions

Returns​

Promise<InferSchemaOutput<TOutputSchema>>

Implementation of​

Processable.process

speak()​

speak(text, options?): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/core/src/baleybot.ts:1129

Generate speech audio from text using this bot's model configuration

Parameters​

text​

string

Text to convert to speech

options?​

Optional voice and speed settings

speed?​

number

voice?​

string

Returns​

Promise<Uint8Array<ArrayBufferLike>>

Uint8Array of audio data

Example​

const audioData = await bot.speak('Hello world!');
// audioData is a Uint8Array of audio bytes

stream()​

stream(input, options?): AsyncGenerator<BaleybotStreamEvent>

Defined in: packages/core/src/baleybot.ts:977

Stream events as an async iterator

Parameters​

input​

string | UnifiedMessageInput

options?​

Omit<ProcessOptions, "onToken" | "onComplete" | "onError">

Returns​

AsyncGenerator<BaleybotStreamEvent>

Example​

for await (const event of bot.stream('Hello')) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.content);
  }
}

Implementation of​

Processable.stream

subscribeToAll()​

subscribeToAll(options?): Subscription

Defined in: packages/core/src/baleybot.ts:1043

Subscribe to categorized events from this bot

Parameters​

options?​

Categorized callbacks and bot filter

omit?​

string[]

onComplete?​

(botId, botName, output) => void

onError?​

(botId, botName, event) => void

onProgressUpdate?​

(botId, botName, event) => void

onStreamEvent?​

(botId, botName, event) => void

Returns​

Subscription

Subscription object with unsubscribe method

Example​

const subscription = bot.subscribeToAll({
  onStreamEvent(botId, botName, event) {
    if (event.type === 'text_delta') {
      process.stdout.write(event.content);
    }
  },
  onProgressUpdate(botId, botName, event) {
    console.log(`${botName}:`, event.type);
  },
  onComplete(botId, botName, output) {
    console.log(`${botName} done:`, output);
  }
});

await bot.process('input');
subscription.unsubscribe();

Implementation of​

Processable.subscribeToAll

clearGlobalConfig()​

static clearGlobalConfig(): void

Defined in: packages/core/src/baleybot.ts:421

Clear global provider configuration

Returns​

void

create()​

static create<TOutputSchema, TTools>(config): Baleybot<TOutputSchema, TTools>

Defined in: packages/core/src/baleybot.ts:385

Create a new Baleybot (static factory method for convenience)

When outputSchema is undefined or omitted, the output type is inferred as string.

Type Parameters​

TOutputSchema​

TOutputSchema = undefined

TTools​

TTools extends Record<string, Processable<unknown, unknown> | ToolDefinition<(...args) => unknown> | ZodToolDefinition<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, unknown>> = Record<string, never>

Parameters​

config​

BaleybotConfig<TOutputSchema, TTools>

Returns​

Baleybot<TOutputSchema, TTools>

Example​

// Without model - auto-selects based on available API keys
const bot = Baleybot.create({
  name: 'my-bot',
  goal: 'Help users'
  // No model specified - auto-selects!
});
const result: string = await bot.process('Hello');

// With explicit model
const bot2 = Baleybot.create({
  name: 'my-bot',
  goal: 'Help users',
  model: 'gpt-4.1-mini'
});
const result2: string = await bot2.process('Hello');

// With output - returns typed output
const bot3 = Baleybot.create({
  name: 'my-bot',
  goal: 'Help users',
  model: 'gpt-4.1-mini',
  output: Output.object({ schema: z.object({ sentiment: z.string() }) })
});
const result3: { sentiment: string } = await bot3.process('Hello');

getGlobalConfig()​

static getGlobalConfig(): GlobalProviderConfig

Defined in: packages/core/src/baleybot.ts:414

Get current global provider configuration

Returns​

GlobalProviderConfig

setApiKey()​

static setApiKey(provider, key): void

Defined in: packages/core/src/baleybot.ts:436

Set API key for a provider

Convenience alias for the most common global config pattern.

Parameters​

provider​

"openai" | "anthropic" | "ollama"

key​

string

Returns​

void

Example​

Baleybot.setApiKey('anthropic', 'sk-ant-...');
Baleybot.setApiKey('openai', 'sk-...');

setGlobalConfig()​

static setGlobalConfig(config): void

Defined in: packages/core/src/baleybot.ts:407

Set global provider configuration

Config is merged with instance-level config, with instance config taking priority.

Parameters​

config​

GlobalProviderConfig

Returns​

void

Example​

Baleybot.setGlobalConfig({
  proxyUrl: '',  // Same-origin proxy for all providers
  openai: { headers: { 'X-Custom': 'value' } },
});

// Now works without per-model proxyUrl
const bot = new Baleybot({ model: openai('gpt-4o') });