@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
• Tool Calling — Register tools and let LLMs call them during generation
• Structured Output — Generate type-safe JSON responses with schema validation
• 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();

Tool Calling

Register tools that LLMs can invoke during generation. Tool calling enables models to request external actions (API calls, device functions, calculations, etc.) and incorporate the results into their responses.

Register a Tool

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

RunAnywhere.registerTool(
  {
    name: 'get_weather',
    description: 'Get the current weather for a location',
    parameters: [
      {
        name: 'location',
        type: 'string',
        description: 'City name or coordinates',
        required: true,
      },
      {
        name: 'units',
        type: 'string',
        description: 'Temperature units',
        required: false,
        enum: ['celsius', 'fahrenheit'],
      },
    ],
  },
  async (args) => {
    // Your tool implementation
    const response = await fetch(`https://api.weather.com?q=${args.location}`);
    const data = await response.json();
    return { temperature: data.temp, condition: data.condition };
  }
);

Generate with Tools

const result = await RunAnywhere.generateWithTools(
  'What is the weather in San Francisco?',
  {
    autoExecute: true,         // Automatically execute tool calls
    maxToolCalls: 3,           // Max tool invocations per turn
    temperature: 0.7,
    maxTokens: 512,
    format: 'default',         // 'default' or 'lfm2' for Liquid AI models
    keepToolsAvailable: false, // Remove tools after first call
  }
);

console.log('Response:', result.text);
console.log('Tool calls made:', result.toolCalls.length);
console.log('Tool results:', result.toolResults);

Manual Tool Execution

// Step-by-step control over tool execution
const result = await RunAnywhere.generateWithTools(prompt, {
  autoExecute: false, // Don't auto-execute
});

// Check if the LLM wants to call a tool
if (result.toolCalls.length > 0) {
  const toolCall = result.toolCalls[0];
  console.log(`LLM wants to call: ${toolCall.toolName}`);
  console.log('Arguments:', toolCall.arguments);

  // Execute manually
  const toolResult = await RunAnywhere.executeTool(
    toolCall.toolName,
    toolCall.arguments
  );

  // Continue generation with the tool result
  const finalResult = await RunAnywhere.continueWithToolResult(
    prompt,
    toolCall.toolName,
    toolResult
  );
  console.log('Final response:', finalResult.text);
}

Parse Tool Calls from Output

// Parse LLM output for tool call tags
const parsed = await RunAnywhere.parseToolCall(llmOutput);
if (parsed.hasToolCall) {
  console.log('Tool:', parsed.toolName);
  console.log('Args:', parsed.argumentsJson);
}

Tool Calling Types

import type {
  ToolDefinition,
  ToolParameter,
  ToolCall,
  ToolResult,
  ToolExecutor,
  RegisteredTool,
  ToolCallingOptions,
  ToolCallingResult,
} from '@runanywhere/core';

Structured Output

Generate type-safe JSON responses with schema validation.

Generate Structured Data

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

// Generate JSON matching a schema
const result = await RunAnywhere.generateStructured(
  {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Product name' },
      price: { type: 'number', description: 'Price in USD' },
      inStock: { type: 'boolean' },
    },
    required: ['name', 'price'],
  },
  'Extract the product info: The new Widget Pro costs $29.99 and is available now',
  { temperature: 0.3, maxTokens: 256 }
);

console.log(result.data); // { name: "Widget Pro", price: 29.99, inStock: true }

Extract Entities

const entities = await RunAnywhere.extractEntities(
  'John Smith from Acme Corp called about order #12345',
  {
    type: 'object',
    properties: {
      person: { type: 'string' },
      company: { type: 'string' },
      orderId: { type: 'string' },
    },
  }
);
// { entities: { person: "John Smith", company: "Acme Corp", orderId: "12345" }, confidence: 0.95 }

Classify Text

const classification = await RunAnywhere.classify(
  'I love this product! Best purchase ever.',
  ['positive', 'negative', 'neutral']
);
// { category: "positive", confidence: 0.97 }

Structured Output Types

import type {
  JSONSchema,
  StructuredOutputOptions,
  StructuredOutputResult,
  EntityExtractionResult,
  ClassificationResult,
} from '@runanywhere/core';

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,

  // Tool Calling
  ToolDefinition,
  ToolParameter,
  ToolCall,
  ToolResult,
  ToolExecutor,
  RegisteredTool,
  ToolCallingOptions,
  ToolCallingResult,

  // Structured Output
  JSONSchema,
  StructuredOutputOptions,
  StructuredOutputResult,
  EntityExtractionResult,
  ClassificationResult,

  // 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
│   │       ├── RunAnywhere+TextGeneration.ts
│   │       ├── RunAnywhere+ToolCalling.ts
│   │       ├── RunAnywhere+StructuredOutput.ts
│   │       ├── RunAnywhere+STT.ts
│   │       ├── RunAnywhere+TTS.ts
│   │       ├── RunAnywhere+VAD.ts
│   │       ├── RunAnywhere+VoiceAgent.ts
│   │       └── ...
│   ├── 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
│   │   ├── ToolCallingTypes.ts     # Tool calling types
│   │   ├── StructuredOutputTypes.ts # Structured output types
│   │   └── ...
│   └── native/                     # Native module access
├── cpp/                            # C++ HybridObject bridges
│   ├── HybridRunAnywhereCore.cpp   # Core native bridge
│   └── ToolCallingBridge.cpp       # Tool calling C++ bridge
├── ios/                            # iOS native module
├── android/                        # Android 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