@runanywhere/core

Core SDK for RunAnywhere React Native. Foundation package providing the public API, events, model management, and native bridge infrastructure.

Overview

@runanywhere/core is the foundation package of the RunAnywhere React Native SDK. It provides:

• RunAnywhere API — Main SDK singleton with all public methods
• EventBus — Event subscription system for SDK events
• ModelRegistry — Model metadata management and discovery
• DownloadService — Model downloads with progress and resume
• FileSystem — Cross-platform file operations
• Native Bridge — Nitrogen/Nitro JSI bindings to C++ core
• Error Handling — Structured SDK errors with recovery suggestions
• Logging — Configurable logging with multiple levels

This package is required for all RunAnywhere functionality. Additional capabilities are provided by:

• @runanywhere/llamacpp — LLM text generation (GGUF models)
• @runanywhere/onnx — Speech-to-Text and Text-to-Speech

Installation

npm install @runanywhere/core
# or
yarn add @runanywhere/core

Peer Dependencies

The following peer dependencies are optional but recommended:

npm install react-native-nitro-modules react-native-fs react-native-blob-util react-native-device-info react-native-zip-archive

iOS Setup

cd ios && pod install && cd ..

Android Setup

No additional setup required.

Quick Start

import { RunAnywhere, SDKEnvironment } from '@runanywhere/core';

// Initialize SDK
await RunAnywhere.initialize({
  environment: SDKEnvironment.Development,
});

// Check initialization
const isReady = await RunAnywhere.isInitialized();
console.log('SDK ready:', isReady);

// Get SDK version
console.log('Version:', RunAnywhere.version);

API Reference

RunAnywhere (Main API)

The RunAnywhere object is the main entry point for all SDK functionality.

Initialization

// Initialize SDK
await RunAnywhere.initialize({
  apiKey?: string,           // API key (production/staging)
  baseURL?: string,          // API base URL
  environment?: SDKEnvironment,
  debug?: boolean,
});

// Check status
const isInit = await RunAnywhere.isInitialized();
const isActive = RunAnywhere.isSDKInitialized;

// Reset SDK
await RunAnywhere.reset();

Properties

| Property | Type | Description | |----------|------|-------------| | isSDKInitialized | boolean | Whether SDK is initialized | | areServicesReady | boolean | Whether services are ready | | currentEnvironment | SDKEnvironment | Current environment | | version | string | SDK version | | deviceId | string | Persistent device ID | | events | EventBus | Event subscription system |

Model Management

// Get available models
const models = await RunAnywhere.getAvailableModels();

// Get specific model info
const model = await RunAnywhere.getModelInfo('model-id');

// Check if downloaded
const isDownloaded = await RunAnywhere.isModelDownloaded('model-id');

// Download with progress
await RunAnywhere.downloadModel('model-id', (progress) => {
  console.log(`${(progress.progress * 100).toFixed(1)}%`);
});

// Delete model
await RunAnywhere.deleteModel('model-id');

Storage Management

// Get storage info
const storage = await RunAnywhere.getStorageInfo();
console.log('Free:', storage.freeSpace);
console.log('Used:', storage.usedSpace);

// Clear cache
await RunAnywhere.clearCache();
await RunAnywhere.cleanTempFiles();

EventBus

Subscribe to SDK events for reactive updates.

import { EventBus, EventCategory } from '@runanywhere/core';

// Subscribe to events
const unsubscribe = EventBus.on('Generation', (event) => {
  console.log('Event:', event.type);
});

// Shorthand methods
RunAnywhere.events.onInitialization((event) => { ... });
RunAnywhere.events.onGeneration((event) => { ... });
RunAnywhere.events.onModel((event) => { ... });
RunAnywhere.events.onVoice((event) => { ... });

// Unsubscribe
unsubscribe();

Event Categories

| Category | Events | |----------|--------| | Initialization | started, completed, failed | | Generation | started, tokenGenerated, completed, failed | | Model | downloadStarted, downloadProgress, downloadCompleted, loadCompleted | | Voice | sttStarted, sttCompleted, ttsStarted, ttsCompleted |

ModelRegistry

Manage model metadata and discovery.

import { ModelRegistry } from '@runanywhere/core';

// Initialize (called automatically)
await ModelRegistry.initialize();

// Register a model
await ModelRegistry.registerModel({
  id: 'my-model',
  name: 'My Model',
  category: ModelCategory.Language,
  format: ModelFormat.GGUF,
  downloadURL: 'https://...',
  // ...
});

// Get model
const model = await ModelRegistry.getModel('my-model');

// List models by category
const llmModels = await ModelRegistry.getModelsByCategory(ModelCategory.Language);

// Update model
await ModelRegistry.updateModel('my-model', { isDownloaded: true });

DownloadService

Download models with progress tracking.

import { DownloadService, DownloadState } from '@runanywhere/core';

// Create download task
const task = await DownloadService.downloadModel(
  'model-id',
  'https://download-url.com/model.gguf',
  (progress) => {
    console.log(`Progress: ${progress.progress * 100}%`);
    console.log(`State: ${progress.state}`);
  }
);

// Cancel download
await DownloadService.cancelDownload('model-id');

// Get active downloads
const activeDownloads = DownloadService.getActiveDownloads();

FileSystem

Cross-platform file operations.

import { FileSystem } from '@runanywhere/core';

// Check availability
if (FileSystem.isAvailable()) {
  // Get directories
  const docs = FileSystem.getDocumentsDirectory();
  const cache = FileSystem.getCacheDirectory();

  // Model operations
  const exists = await FileSystem.modelExists('model-id', 'LlamaCpp');
  const path = await FileSystem.getModelPath('model-id', 'LlamaCpp');

  // File operations
  const fileExists = await FileSystem.exists('/path/to/file');
  const size = await FileSystem.getFileSize('/path/to/file');
  await FileSystem.deleteFile('/path/to/file');
}

Error Handling

import {
  SDKError,
  SDKErrorCode,
  isSDKError,
  notInitializedError,
  modelNotFoundError,
} from '@runanywhere/core';

try {
  await RunAnywhere.generate('Hello');
} catch (error) {
  if (isSDKError(error)) {
    console.log('Code:', error.code);
    console.log('Category:', error.category);
    console.log('Suggestion:', error.recoverySuggestion);
  }
}

// Create errors
throw notInitializedError();
throw modelNotFoundError('model-id');

Logging

import { SDKLogger, LogLevel } from '@runanywhere/core';

// Set global log level
RunAnywhere.setLogLevel(LogLevel.Debug);

// Create custom logger
const logger = new SDKLogger('MyModule');
logger.debug('Debug message', { data: 'value' });
logger.info('Info message');
logger.warning('Warning message');
logger.error('Error message', new Error('...'));

Types

Enums

import {
  SDKEnvironment,
  ExecutionTarget,
  LLMFramework,
  ModelCategory,
  ModelFormat,
  HardwareAcceleration,
  ComponentState,
} from '@runanywhere/core';

Interfaces

import type {
  // Models
  ModelInfo,
  StorageInfo,

  // Generation
  GenerationOptions,
  GenerationResult,
  PerformanceMetrics,

  // Voice
  STTOptions,
  STTResult,
  TTSConfiguration,
  TTSResult,
  VADConfiguration,

  // Events
  SDKEvent,
  SDKGenerationEvent,
  SDKModelEvent,
  SDKVoiceEvent,

  // Download
  DownloadProgress,
  DownloadConfiguration,
} from '@runanywhere/core';

Package Structure

packages/core/
├── src/
│   ├── index.ts                    # Package exports
│   ├── Public/
│   │   ├── RunAnywhere.ts          # Main API singleton
│   │   ├── Events/
│   │   │   └── EventBus.ts         # Event pub/sub
│   │   └── Extensions/             # API method implementations
│   ├── Foundation/
│   │   ├── ErrorTypes/             # SDK errors
│   │   ├── Initialization/         # Init state machine
│   │   ├── Security/               # Secure storage
│   │   ├── Logging/                # Logger
│   │   └── DependencyInjection/    # Service registry
│   ├── Infrastructure/
│   │   └── Events/                 # Event internals
│   ├── Features/
│   │   └── VoiceSession/           # Voice session
│   ├── services/
│   │   ├── ModelRegistry.ts        # Model metadata
│   │   ├── DownloadService.ts      # Downloads
│   │   ├── FileSystem.ts           # File ops
│   │   └── Network/                # HTTP, telemetry
│   ├── types/                      # TypeScript types
│   └── native/                     # Native module access
├── cpp/                            # C++ HybridObject bridges
├── ios/                            # Swift native module
├── android/                        # Kotlin native module
└── nitrogen/                       # Generated Nitro specs

Native Integration

This package includes native bindings via Nitrogen/Nitro for:

• RACommons — Core C++ infrastructure
• PlatformAdapter — Platform-specific implementations
• SecureStorage — Keychain (iOS) / EncryptedSharedPreferences (Android)
• SDKLogger — Native logging
• AudioDecoder — Audio file decoding

iOS

The package uses RACommons.xcframework which is automatically downloaded during pod install.

Android

Native libraries (librac_commons.so, librunanywhere_jni.so) are automatically downloaded during Gradle build.

See Also

• Main SDK README — Full SDK documentation
• ARCHITECTURE.md — System architecture
• API Reference — Complete API docs
• @runanywhere/llamacpp — LLM backend
• @runanywhere/onnx — STT/TTS backend

License

MIT License