> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runanywhere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> SDK configuration and settings

## Overview

This guide covers SDK initialization options, environment configuration, logging, and event subscriptions.

## SDK Initialization

### Basic Initialization

```typescript theme={null}
import { RunAnywhere, SDKEnvironment } from '@runanywhere/core'

// Development mode (no API key required)
await RunAnywhere.initialize({
  environment: SDKEnvironment.Development,
})
```

### Production Initialization

```typescript theme={null}
await RunAnywhere.initialize({
  apiKey: 'your-api-key',
  baseURL: 'https://api.runanywhere.ai',
  environment: SDKEnvironment.Production,
})
```

### Full Configuration

```typescript theme={null}
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 |

```typescript theme={null}
enum SDKEnvironment {
  Development = 'development',
  Staging = 'staging',
  Production = 'production',
}
```

## Logging

### Set Log Level

```typescript theme={null}
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)

<Note>
  `SDKLogger` is used internally by the SDK. For most apps, the built-in logging controlled by
  `setLogLevel()` is sufficient.
</Note>

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
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

```typescript theme={null}
const sttOptions: STTOptions = {
  language: 'en', // Language code
  punctuation: true, // Add punctuation
  wordTimestamps: true, // Include word timing
  sampleRate: 16000, // Audio sample rate
}
```

### TTS Options

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
RunAnywhere.Audio.SAMPLE_RATE // 16000 (STT default)
RunAnywhere.Audio.TTS_SAMPLE_RATE // 22050 (TTS default)
```

### Recording

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
// Release audio resources
await RunAnywhere.Audio.cleanup()
```

### Helper

```typescript theme={null}
// Format seconds to "mm:ss" string
const formatted = RunAnywhere.Audio.formatDuration(125) // "2:05"
```

## Related

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/react-native/error-handling">
    Handle errors gracefully
  </Card>

  <Card title="Best Practices" icon="star" href="/react-native/best-practices">
    Optimization tips
  </Card>
</CardGroup>