Skip to main content

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

EnvironmentDescriptionAPI KeyLogging
DevelopmentLocal development, full debuggingOptionalDebug
StagingTesting with real servicesRequiredInfo
ProductionProduction deploymentRequiredWarning
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

LevelDescriptionUse Case
DebugDetailed debugging infoDevelopment
InfoGeneral informationStaging
WarningPotential issuesProduction
ErrorErrors and failuresProduction
FaultCritical failuresAlways

Custom Logger

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

CategoryEvents
Initializationstarted, completed, failed
Generationstarted, tokenGenerated, completed, failed, cancelled
ModeldownloadStarted, downloadProgress, downloadCompleted, loadStarted, loadCompleted, unloaded
VoicesttStarted, sttCompleted, ttsStarted, ttsCompleted, vadSpeechStarted, vadSpeechEnded
Storagecleared, modelDeleted
ErrorVarious 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':
      process.stdout.write(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

import { NativeEventEmitter, NativeModules } from 'react-native'

// iOS memory warning handling
if (Platform.OS === 'ios') {
  const emitter = new NativeEventEmitter(NativeModules.RunAnywhereCore)
  emitter.addListener('memoryWarning', () => {
    // Free memory by unloading unused models
    RunAnywhere.unloadModel()
  })
}