Overview
This guide covers SDK initialization options, environment configuration, logging, and event subscriptions.
SDK Initialization
Basic Initialization
import { RunAnywhere, SDKEnvironment } from '@runanywhere/core'
// Development mode (no API key required)
await RunAnywhere.initialize({
environment: SDKEnvironment.Development,
})
Production Initialization
await RunAnywhere.initialize({
apiKey: 'your-api-key',
baseURL: 'https://api.runanywhere.ai',
environment: SDKEnvironment.Production,
})
Full Configuration
interface SDKInitOptions {
/** API key for authentication (production/staging) */
apiKey?: string
/** Base URL for API requests */
baseURL?: string
/** SDK environment */
environment?: SDKEnvironment
/** Supabase project URL (development mode only) */
supabaseURL?: string
/** Supabase anon key (development mode only) */
supabaseKey?: string
/** Enable debug logging */
debug?: boolean
}
Environment Modes
| Environment | Description | API Key | Logging |
|---|
Development | Local development, full debugging | Optional | Debug |
Staging | Testing with real services | Required | Info |
Production | Production deployment | Required | Warning |
enum SDKEnvironment {
Development = 'development',
Staging = 'staging',
Production = 'production',
}
Logging
Set Log Level
import { RunAnywhere, LogLevel } from '@runanywhere/core'
// Set minimum log level
RunAnywhere.setLogLevel(LogLevel.Debug)
Log Levels
| Level | Description | Use Case |
|---|
Debug | Detailed debugging info | Development |
Info | General information | Staging |
Warning | Potential issues | Production |
Error | Errors and failures | Production |
Fault | Critical failures | Always |
Custom Logger (Advanced)
SDKLogger is used internally by the SDK. For most apps, the built-in logging controlled by
setLogLevel() is sufficient.
import { SDKLogger } from '@runanywhere/core'
// Create a custom logger
const logger = new SDKLogger('MyApp')
logger.debug('Debug message', { modelId: 'llama-2' })
logger.info('Info message')
logger.warning('Warning message')
logger.error('Error message', new Error('Something went wrong'))
Events
EventBus
The SDK provides a comprehensive event system for monitoring SDK activities.
import { RunAnywhere, EventBus, EventCategory } from '@runanywhere/core'
// Access EventBus via RunAnywhere
RunAnywhere.events.onGeneration((event) => {
console.log('Generation event:', event.type)
})
// Or use EventBus directly
EventBus.on('Generation', (event) => {
console.log('Event:', event)
})
Event Categories
| Category | Events |
|---|
Initialization | started, completed, failed |
Generation | started, tokenGenerated, completed, failed, cancelled |
Model | downloadStarted, downloadProgress, downloadCompleted, loadStarted, loadCompleted, unloaded |
Voice | sttStarted, sttCompleted, ttsStarted, ttsCompleted, vadSpeechStarted, vadSpeechEnded |
Storage | cleared, modelDeleted |
Error | Various error events |
Event Subscription Examples
// Initialization events
const unsubInit = RunAnywhere.events.onInitialization((event) => {
switch (event.type) {
case 'started':
console.log('SDK initializing...')
break
case 'completed':
console.log('SDK ready!')
break
case 'failed':
console.error('Init failed:', event.error)
break
}
})
// Generation events
const unsubGen = RunAnywhere.events.onGeneration((event) => {
switch (event.type) {
case 'started':
console.log('Generation started')
break
case 'tokenGenerated':
// Append token to your UI state
setResponse((prev) => prev + event.token)
break
case 'completed':
console.log('Done:', event.response.text)
break
case 'failed':
console.error('Failed:', event.error)
break
}
})
// Model events
const unsubModel = RunAnywhere.events.onModel((event) => {
switch (event.type) {
case 'downloadProgress':
console.log(`${event.modelId}: ${(event.progress * 100).toFixed(1)}%`)
break
case 'downloadCompleted':
console.log(`${event.modelId} downloaded`)
break
case 'loadCompleted':
console.log(`${event.modelId} loaded`)
break
}
})
// Voice events
const unsubVoice = RunAnywhere.events.onVoice((event) => {
switch (event.type) {
case 'sttStarted':
console.log('Transcription started')
break
case 'sttCompleted':
console.log('Transcript:', event.result.text)
break
case 'vadSpeechStarted':
console.log('Speech detected')
break
case 'vadSpeechEnded':
console.log('Speech ended')
break
}
})
// Clean up subscriptions
unsubInit()
unsubGen()
unsubModel()
unsubVoice()
SDK State
Check Initialization
// Check if SDK is initialized
const isInit = await RunAnywhere.isInitialized()
// Check properties
console.log('Initialized:', RunAnywhere.isSDKInitialized)
console.log('Services ready:', RunAnywhere.areServicesReady)
console.log('Environment:', RunAnywhere.currentEnvironment)
console.log('Version:', RunAnywhere.version)
console.log('Device ID:', RunAnywhere.deviceId)
Reset SDK
// Reset to uninitialized state
await RunAnywhere.reset()
// Or use destroy (alias)
await RunAnywhere.destroy()
// Can now reinitialize with different options
await RunAnywhere.initialize({
environment: SDKEnvironment.Production,
apiKey: 'new-api-key',
})
Model Configuration
Generation Options
const options: GenerationOptions = {
maxTokens: 256, // Max tokens to generate
temperature: 0.7, // Sampling temperature (0.0-2.0)
topP: 0.95, // Nucleus sampling
stopSequences: ['END'], // Stop sequences
systemPrompt: 'You are helpful.', // System prompt
preferredExecutionTarget: ExecutionTarget.OnDevice,
preferredFramework: LLMFramework.LlamaCpp,
}
STT Options
const sttOptions: STTOptions = {
language: 'en', // Language code
punctuation: true, // Add punctuation
wordTimestamps: true, // Include word timing
sampleRate: 16000, // Audio sample rate
}
TTS Options
const ttsOptions: TTSConfiguration = {
voice: 'en-US-female-1', // Voice ID
rate: 1.0, // Speech rate (0.5-2.0)
pitch: 1.0, // Pitch (0.5-2.0)
volume: 1.0, // Volume (0.0-1.0)
}
Storage Configuration
Get Storage Info
const storage = await RunAnywhere.getStorageInfo()
console.log('Total space:', storage.totalSpace)
console.log('Used by SDK:', storage.usedSpace)
console.log('Free space:', storage.freeSpace)
console.log('Models path:', storage.modelsPath)
Clean Up Storage
// Clear SDK cache
await RunAnywhere.clearCache()
// Clean temp files
await RunAnywhere.cleanTempFiles()
// Delete a specific model
await RunAnywhere.deleteModel('model-id')
React Native Specific
App Lifecycle
import { AppState, AppStateStatus } from 'react-native'
// Handle app state changes
useEffect(() => {
const subscription = AppState.addEventListener('change', (state: AppStateStatus) => {
if (state === 'background') {
// Optionally unload models to free memory
RunAnywhere.unloadModel()
} else if (state === 'active') {
// Reload model if needed
}
})
return () => subscription.remove()
}, [])
Memory Warnings
Use the SDK’s event system to handle low-memory situations:
import { AppState } from 'react-native'
import { RunAnywhere } from '@runanywhere/core'
// Listen for OS memory warnings via the performance event bus
RunAnywhere.events.onPerformance((event) => {
if (event.type === 'memoryWarning') {
console.log('Memory warning — usage:', event.usage)
// Free memory by unloading unused models
RunAnywhere.unloadModel()
}
})
// Also listen for unexpected model unloads
RunAnywhere.events.onModel((event) => {
if (event.type === 'unloadCompleted') {
console.log('Model was unloaded')
}
})
// Proactively unload models when the app backgrounds
useEffect(() => {
const subscription = AppState.addEventListener('change', (state) => {
if (state === 'background') {
RunAnywhere.unloadModel()
}
})
return () => subscription.remove()
}, [])
Model Management
Check Model Status
// Check if a specific model is loaded in memory
const loaded = await RunAnywhere.isModelLoaded()
// Check if a model has been downloaded
const downloaded = await RunAnywhere.isModelDownloaded('smollm2-360m')
// Get all registered models
const models = await RunAnywhere.getAvailableModels()
for (const model of models) {
console.log(
`${model.id}: ${model.name} (${model.isDownloaded ? 'downloaded' : 'not downloaded'})`
)
}
// Get detailed info for a model
const info = await RunAnywhere.getModelInfo('smollm2-360m')
console.log('Local path:', info.localPath)
Audio Utilities
The SDK provides a built-in RunAnywhere.Audio utility for recording, playback, and audio conversion in React Native.
Constants
RunAnywhere.Audio.SAMPLE_RATE // 16000 (STT default)
RunAnywhere.Audio.TTS_SAMPLE_RATE // 22050 (TTS default)
Recording
// Request microphone permission
await RunAnywhere.Audio.requestPermission()
// Start recording audio
await RunAnywhere.Audio.startRecording()
// Stop recording and get the recorded file
const recording = await RunAnywhere.Audio.stopRecording()
// recording.uri - path to the recorded WAV file
// recording.durationMs - recording duration in milliseconds
// Cancel recording without saving
await RunAnywhere.Audio.cancelRecording()
Playback
// Play base64-encoded audio
await RunAnywhere.Audio.playAudio(wavBase64)
// Playback controls
await RunAnywhere.Audio.stopPlayback()
await RunAnywhere.Audio.pausePlayback()
await RunAnywhere.Audio.resumePlayback()
Audio Conversion
// Convert TTS output (float32 PCM) to playable WAV format
const wavBase64 = RunAnywhere.Audio.createWavFromPCMFloat32(ttsResult.audio, ttsResult.sampleRate)
// Then play it
await RunAnywhere.Audio.playAudio(wavBase64)
Cleanup
// Release audio resources
await RunAnywhere.Audio.cleanup()
Helper
// Format seconds to "mm:ss" string
const formatted = RunAnywhere.Audio.formatDuration(125) // "2:05"
