Skip to main content

Class: Baleybot<TOutputSchema, TTools>

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

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-5.6-luna) → Anthropic (claude-sonnet-5)

Output Type Inference:

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

Type Parameters​

TOutputSchema​

TOutputSchema = undefined

TTools​

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

Implements​

Constructors​

Constructor​

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

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

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:546

emitsInvocationEvents​

readonly emitsInvocationEvents: true = true

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

All events from one process() call reach its own options.onToken callback. Enables isolated step events when the same instance runs concurrently. Subscription-only implementations must not overlap observed invocations.

Implementation of​

Processable.emitsInvocationEvents

Methods​

clearHistory()​

clearHistory(): Promise<void>

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

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:1485

Get bot names from this bot

Returns​

string[]

Array containing this bot's name

Implementation of​

Processable.getBotNames

getChildren()​

getChildren(): ProcessableChild[]

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

A bot is a leaf — it composes no other processables.

Returns​

ProcessableChild[]

Implementation of​

Processable.getChildren

getFamily()​

getFamily(): DeclaredFamily | undefined

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

The family this bot was built as a member of, or undefined.

The validated declaration, not the raw config — the same one the instance id and the family-wide override key are derived from, so a consumer asking this can never see a family the override path does not honour.

Implementing Processable.getFamily() is also what keeps a bot's own declaration authoritative when it is handed to processableFamily(): that layer attaches a declaration only to nodes that cannot already answer.

Returns​

DeclaredFamily | undefined

Implementation of​

Processable.getFamily

getHistory()​

getHistory(): History | undefined

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

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:1492

Get the unique ID of this baleybot instance

Returns​

string

Implementation of​

Processable.getId

getName()​

getName(): string

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

Get baleybot name — this bot's identity across runs.

config.name is typed as a string but nothing stops it being '', and an empty name used to collapse every such bot onto one key, so an override meant for one reached all of them. Falling back to the instance id keeps them distinct; the id changes between runs, which is the correct outcome for a bot that never claimed a stable identity.

Returns​

string

Implementation of​

Processable.getName

listen()​

listen(config?): Promise<LiveSession>

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

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​

Simple usage with callbacks

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:1261

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:1509

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:1366

Stream events as an async iterator

Parameters​

input​

string | UnifiedMessageInput

options?​

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

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:1435

Subscribe to categorized events from this bot

Parameters​

options?​

SubscribeAllCallbacks

Categorized callbacks and bot filter

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:648

Clear global provider configuration

Returns​

void

create()​

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

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

Create a new Baleybot (static factory method for convenience)

When output 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<any, any>> = 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-5.6-luna'
});
const result2: string = await bot2.process('Hello');

// With output - returns typed output
const bot3 = Baleybot.create({
  name: 'my-bot',
  goal: 'Help users',
  model: 'gpt-5.6-luna',
  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:641

Get current global provider configuration

Returns​

GlobalProviderConfig

setApiKey()​

static setApiKey(provider, key): void

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

Set API key for a provider

Convenience alias for the most common global config pattern.

Parameters​

provider​

"anthropic" | "openai" | "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:634

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') });