Variable: AI

const AI: object;

Primary runtime facade for the Robo AI plugin. Provides chat completions, voice orchestration, image generation, and detailed usage tracking through a single cohesive interface. Import this singleton when integrating AI features inside commands, web handlers, or other Robo plugins.

Type declaration

chat()

chat: (messages, options) => Promise<void>;

Executes a chat completion using the registered engine. Handles typing indicators, task context, tool invocation scheduling, and token limit errors.

Parameters

Parameter	Type	Description
messages	ChatMessage[]	Message history including system prompts and user turns.
options	ChatOptions	Chat execution options including Discord context and callbacks.

Returns

Promise<void>

Resolves when the chat flow has completed and replies (if any) were dispatched.

Remarks

Tool calls are scheduled asynchronously through the tool executor. Token limit errors are surfaced to the caller via onReply to provide user-friendly messaging.

chatSync()

chatSync: (messages, options) => Promise<ChatReply>;

Helper that wraps chat and resolves with the first reply payload.

Parameters

Parameter	Type	Description
messages	ChatMessage[]	Message array provided to chat.
options	Omit<ChatOptions, "onReply">	Chat options excluding onReply.

Returns

Promise<ChatReply>

Resolves with the reply emitted by the engine or rejects on error.

generateImage()

generateImage: (options) => Promise<GenerateImageResult>;

Generates an image by delegating to the configured engine.

Parameters

Parameter	Type	Description
options	GenerateImageOptions	Image prompt and configuration.

Returns

Promise<GenerateImageResult>

Image generation result containing URLs or base64 payloads.

getActiveTasks()

getActiveTasks: (channelId?) => BackgroundTaskSnapshot[];

Retrieves background task snapshots associated with the optional channel.

Parameters

Parameter	Type
channelId?	string

Returns

BackgroundTaskSnapshot[]

getLifetimeUsage()

getLifetimeUsage: (model?) => Promise<Record<string, TokenWindowTotals>>;

Retrieves lifetime token totals aggregated by model.

Parameters

Parameter	Type
model?	string

Returns

Promise<Record<string, TokenWindowTotals>>

getUsageSummary()

getUsageSummary: (query?) => Promise<TokenSummaryResult>;

Resolves summary statistics for token usage within the configured ledger windows.

Parameters

Parameter	Type
query?	TokenSummaryQuery

Returns

Promise<TokenSummaryResult>

getVoiceMetrics()

getVoiceMetrics: () => VoiceMetricsSnapshot;

Returns aggregate metrics describing active voice sessions.

Returns

VoiceMetricsSnapshot

getVoiceStatus()

getVoiceStatus: (guildId?) => Promise<object>;

Retrieves voice subsystem status for the optional guild.

Parameters

Parameter	Type
guildId?	string

Returns

Promise<object>

baseConfig

baseConfig: VoiceRuntimeConfig;

guildConfigs

guildConfigs: Record<string, VoiceRuntimeConfig>;

sessions

sessions: object[] = sessionStatuses;

isReady()

isReady: () => boolean;

Returns

boolean

offUsageEvent()

offUsageEvent: <T>(event, listener) => void;

Removes a usage event listener from the token ledger.

Type Parameters

Type Parameter
T extends keyof UsageEventPayloads

Parameters

Parameter	Type
event	T
listener	UsageEventListener<T>

Returns

void

offVoiceEvent()

offVoiceEvent: <T>(event, listener) => void;

Removes a previously registered voice event listener.

Type Parameters

Type Parameter
T extends keyof VoiceEventMap

Parameters

Parameter	Type
event	T
listener	(payload) => void

Returns

void

onceUsageEvent()

onceUsageEvent: <T>(event, listener) => void;

Attaches a one-time usage event listener to the token ledger.

Type Parameters

Type Parameter
T extends keyof UsageEventPayloads

Parameters

Parameter	Type
event	T
listener	UsageEventListener<T>

Returns

void

onUsageEvent()

onUsageEvent: <T>(event, listener) => void;

Attaches a usage event listener to the token ledger.

Type Parameters

Type Parameter
T extends keyof UsageEventPayloads

Parameters

Parameter	Type
event	T
listener	UsageEventListener<T>

Returns

void

onVoiceEvent()

onVoiceEvent: <T>(event, listener) => void;

Registers a voice event listener on the shared voice manager.

Type Parameters

Type Parameter
T extends keyof VoiceEventMap

Parameters

Parameter	Type
event	T
listener	(payload) => void

Returns

void

setVoiceConfig()

setVoiceConfig: (options) => Promise<void>;

Applies a voice configuration patch either globally or for a specific guild.

Parameters

Parameter	Type
options	SetVoiceConfigOptions

Returns

Promise<void>

startVoice()

startVoice: (options) => Promise<void>;

Starts the shared voice manager in a Discord guild, joining the specified voice channel and configuring transcription playback streams.

Parameters

Parameter	Type	Description
options	StartVoiceOptions	Voice join options including guild and channel identifiers.

Returns

Promise<void>

Throws

OptionalDependencyError Wrapped when the Discord voice dependency is absent.

stopVoice()

stopVoice: (options) => Promise<void>;

Stops the voice manager within the given guild and disconnects from the active channel.

Parameters

Parameter	Type	Description
options	StopVoiceOptions	Guild identifier and optional channel override.

Returns

Promise<void>

Throws

Error When no voice connection exists for the guild.

Examples

import { AI } from '@robojs/ai'

await AI.chat({
  messages: [
    { role: 'system', content: 'Provide concise answers.' },
    { role: 'user', content: 'Summarize the changelog.' }
  ],
  channel,
  member,
  onReply: ({ text }) => channel.send(text)
})

import { AI } from '@robojs/ai'

await AI.startVoice({ guildId: guild.id, channelId: voiceChannel.id })

AI.onVoiceEvent('playback', ({ delta }) => {
  console.log('Streaming voice chunk', delta.timestamp)
})

await AI.stopVoice({ guildId: guild.id })

import { AI } from '@robojs/ai'

const summary = await AI.getUsageSummary({ window: 'day' })
console.log('Prompt tokens today', summary.windowTotals.prompt)

AI.onUsageEvent('usage.limitReached', (event) => {
  console.warn('Token limit exceeded for', event.breach.model)
})

AI.onUsageEvent('usage.recorded', (event) => {
  console.log('Token usage recorded:', event.usage.tokens)
})

Remarks

Engines lazily initialize. Call AI.isReady() before executing intensive workloads or await project startup hooks to guarantee availability.

See

• BaseEngine
• tokenLedger
• ChatOptions
• VoiceSessionStartOptions