@runanywhere/core 0.17.7 → 0.18.0

package/README.md

@@ -9,6 +9,8 @@ Core SDK for RunAnywhere React Native. Foundation package providing the public A
 `@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
@@ -143,6 +145,190 @@ 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+const classification = await RunAnywhere.classify(
+  'I love this product! Best purchase ever.',
+  ['positive', 'negative', 'neutral']
+);
+// { category: "positive", confidence: 0.97 }
+```
+
+#### Structured Output Types
+
+```typescript
+import type {
+  JSONSchema,
+  StructuredOutputOptions,
+  StructuredOutputResult,
+  EntityExtractionResult,
+  ClassificationResult,
+} from '@runanywhere/core';
+```
+
+---
+
 ### EventBus
 
 Subscribe to SDK events for reactive updates.
@@ -335,6 +521,23 @@ import type {
   GenerationResult,
   PerformanceMetrics,
 
+  // Tool Calling
+  ToolDefinition,
+  ToolParameter,
+  ToolCall,
+  ToolResult,
+  ToolExecutor,
+  RegisteredTool,
+  ToolCallingOptions,
+  ToolCallingResult,
+
+  // Structured Output
+  JSONSchema,
+  StructuredOutputOptions,
+  StructuredOutputResult,
+  EntityExtractionResult,
+  ClassificationResult,
+
   // Voice
   STTOptions,
   STTResult,
@@ -367,6 +570,14 @@ packages/core/
 │   │   ├── 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
@@ -383,10 +594,15 @@ packages/core/
 │   │   ├── 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
-├── ios/                            # Swift native module
-├── android/                        # Kotlin native module
+│   ├── HybridRunAnywhereCore.cpp   # Core native bridge
+│   └── ToolCallingBridge.cpp       # Tool calling C++ bridge
+├── ios/                            # iOS native module
+├── android/                        # Android native module
 └── nitrogen/                       # Generated Nitro specs
 ```
 

package/RunAnywhereCore.podspec

@@ -35,6 +35,7 @@ Pod::Spec.new do |s|
     "HEADER_SEARCH_PATHS" => [
       "$(PODS_TARGET_SRCROOT)/cpp",
       "$(PODS_TARGET_SRCROOT)/cpp/bridges",
+      "$(PODS_TARGET_SRCROOT)/cpp/third_party",
       "$(PODS_TARGET_SRCROOT)/ios/Binaries/RACommons.xcframework/ios-arm64/RACommons.framework/Headers",
       "$(PODS_TARGET_SRCROOT)/ios/Binaries/RACommons.xcframework/ios-arm64_x86_64-simulator/RACommons.framework/Headers",
       "$(PODS_ROOT)/Headers/Public",

package/android/CMakeLists.txt

@@ -5,6 +5,19 @@ set(PACKAGE_NAME runanywherecore)
 set(CMAKE_VERBOSE_MAKEFILE ON)
 set(CMAKE_CXX_STANDARD 20)
 
+# =============================================================================
+# nlohmann/json - Header-only JSON library for robust JSON parsing
+# Used by ToolCallingBridge for parsing tool call JSON from LLM output
+# =============================================================================
+include(FetchContent)
+FetchContent_Declare(
+    nlohmann_json
+    GIT_REPOSITORY https://github.com/nlohmann/json.git
+    GIT_TAG v3.11.3
+    GIT_SHALLOW TRUE
+)
+FetchContent_MakeAvailable(nlohmann_json)
+
 # =============================================================================
 # 16KB Page Alignment for Android 15+ (API 35) Compliance
 # Required starting November 1, 2025 for Google Play submissions
@@ -23,8 +36,13 @@ set(RAC_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/src/main/include)
 # RACommons is REQUIRED - it's downloaded via Gradle downloadNativeLibs task
 # =============================================================================
 if(NOT EXISTS "${JNILIB_DIR}/librac_commons.so")
-    message(FATAL_ERROR "[RunAnywhereCore] RACommons not found at ${JNILIB_DIR}/librac_commons.so\n"
-                        "Run: ./gradlew :runanywhere_core:downloadNativeLibs")
+    message(WARNING "[RunAnywhereCore] RACommons not found for ${ANDROID_ABI} at ${JNILIB_DIR}/librac_commons.so\n"
+                    "This ABI will not be functional. To fix, run: ./gradlew :runanywhere_core:downloadNativeLibs\n"
+                    "Or set reactNativeArchitectures=arm64-v8a in gradle.properties to skip this ABI.")
+    # Create a minimal stub library so the build can proceed for other ABIs
+    file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/stub.cpp" "// Stub for missing ABI ${ANDROID_ABI}")
+    add_library(${PACKAGE_NAME} SHARED "${CMAKE_CURRENT_BINARY_DIR}/stub.cpp")
+    return()
 endif()
 
 add_library(rac_commons SHARED IMPORTED)
@@ -73,6 +91,7 @@ include_directories(
     "src/main/cpp"
     "../cpp"
     "../cpp/bridges"
+    "../cpp/third_party"
     "${CMAKE_SOURCE_DIR}/include"
     # RAC API headers from runanywhere-commons (flat access)
     "${RAC_INCLUDE_DIR}"
@@ -111,6 +130,9 @@ target_link_libraries(
 target_link_libraries(${PACKAGE_NAME} rac_commons)
 target_compile_definitions(${PACKAGE_NAME} PRIVATE HAS_RACOMMONS=1)
 
+# Link nlohmann_json for ToolCallingBridge
+target_link_libraries(${PACKAGE_NAME} nlohmann_json::nlohmann_json)
+
 # 16KB page alignment - MUST be on target for Android 15+ compliance
 target_link_options(${PACKAGE_NAME} PRIVATE -Wl,-z,max-page-size=16384)
 

package/android/build.gradle

@@ -38,9 +38,13 @@ def getExtOrDefault(name) {
     return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['RunAnywhereCore_' + name]
 }
 
-// Only arm64-v8a is supported - native libraries are only built for 64-bit ARM
+// Supported ABIs - arm64-v8a for physical devices, x86_64 for emulators
+// Can be overridden via gradle.properties: reactNativeArchitectures=arm64-v8a
 def reactNativeArchitectures() {
-    return ["arm64-v8a"]
+    def value = rootProject.hasProperty("reactNativeArchitectures")
+        ? rootProject.property("reactNativeArchitectures")
+        : null
+    return value ? value.split(",").collect { it.trim() } : ["arm64-v8a", "x86_64"]
 }
 
 apply plugin: 'com.android.library'
@@ -113,7 +117,7 @@ android {
         targetSdkVersion getExtOrIntegerDefault('targetSdkVersion')
 
         ndk {
-            abiFilters 'arm64-v8a'
+            abiFilters(*reactNativeArchitectures())
         }
 
         externalNativeBuild {
@@ -122,7 +126,7 @@ android {
                 arguments "-DANDROID_STL=c++_shared",
                           // Fix NitroModules prefab path - use app's build directory
                           "-DREACT_NATIVE_NITRO_BUILD_DIR=${rootProject.buildDir}"
-                abiFilters 'arm64-v8a'
+                abiFilters(*reactNativeArchitectures())
             }
         }
     }
@@ -220,11 +224,59 @@ task downloadNativeLibs {
             return
         }
 
-        // Check if libs are already bundled (npm install case)
-        def bundledLibsDir = file("${jniLibsDir}/arm64-v8a")
-        def bundledLibs = bundledLibsDir.exists() ? bundledLibsDir.listFiles()?.findAll { it.name.endsWith(".so") } : []
-        if (bundledLibs?.size() > 0) {
-            logger.lifecycle("[RunAnywhereCore] ✅ Using bundled native libraries from npm package (${bundledLibs.size()} .so files)")
+        // Check if libs are already bundled for ALL requested ABIs (npm install case)
+        def requestedAbis = reactNativeArchitectures()
+        def allAbisBundled = requestedAbis.every { abi ->
+            def abiDir = file("${jniLibsDir}/${abi}")
+            def libs = abiDir.exists() ? abiDir.listFiles()?.findAll { it.name.endsWith(".so") } : []
+            return libs?.size() > 0
+        }
+        if (allAbisBundled) {
+            logger.lifecycle("[RunAnywhereCore] ✅ Using bundled native libraries from npm package for ABIs: ${requestedAbis.join(', ')}")
+            return
+        }
+        // Check if at least arm64-v8a is bundled (partial bundle - need to download missing ABIs)
+        def arm64Dir = file("${jniLibsDir}/arm64-v8a")
+        def arm64Bundled = arm64Dir.exists() && arm64Dir.listFiles()?.any { it.name.endsWith(".so") }
+        if (arm64Bundled) {
+            def missingAbis = requestedAbis.findAll { abi ->
+                def abiDir = file("${jniLibsDir}/${abi}")
+                def libs = abiDir.exists() ? abiDir.listFiles()?.findAll { it.name.endsWith(".so") } : []
+                return !libs || libs.size() == 0
+            }
+            if (missingAbis.size() > 0) {
+                logger.lifecycle("[RunAnywhereCore] ⚠️ Bundled libs found for arm64-v8a but missing for: ${missingAbis.join(', ')}")
+                logger.lifecycle("[RunAnywhereCore] Attempting to download missing ABIs from GitHub releases...")
+                // Try to download and extract only missing ABIs (don't delete existing bundled libs)
+                try {
+                    def commonsUrl = "https://github.com/${githubOrg}/${commonsRepo}/releases/download/commons-v${commonsVersion}/RACommons-android-v${commonsVersion}.zip"
+                    def tempZip = file("${downloadedLibsDir}/RACommons-supplement.zip")
+                    downloadedLibsDir.mkdirs()
+                    new URL(commonsUrl).withInputStream { input ->
+                        tempZip.withOutputStream { output -> output << input }
+                    }
+                    copy {
+                        from zipTree(tempZip)
+                        into jniLibsDir
+                        exclude "**/libc++_shared.so"
+                        eachFile { fileCopyDetails ->
+                            def pathString = fileCopyDetails.relativePath.pathString
+                            if (pathString.startsWith("jniLibs/") && pathString.endsWith(".so")) {
+                                def newPath = pathString.replaceFirst("^jniLibs/", "")
+                                fileCopyDetails.relativePath = new RelativePath(true, newPath.split("/"))
+                            } else if (!pathString.endsWith(".so")) {
+                                fileCopyDetails.exclude()
+                            }
+                        }
+                        includeEmptyDirs = false
+                    }
+                    tempZip.delete()
+                    logger.lifecycle("[RunAnywhereCore] ✅ Downloaded missing ABIs successfully")
+                } catch (Exception e) {
+                    logger.warn("[RunAnywhereCore] ⚠️ Could not download missing ABIs: ${e.message}")
+                    logger.warn("[RunAnywhereCore] Building with available ABIs only (arm64-v8a)")
+                }
+            }
             return
         }
 

package/android/src/main/cpp/cpp-adapter.cpp

@@ -2,6 +2,7 @@
 #include <string>
 #include <android/log.h>
 #include "runanywherecoreOnLoad.hpp"
+#include "PlatformDownloadBridge.h"
 
 #define LOG_TAG "ArchiveJNI"
 #define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
@@ -35,6 +36,8 @@ jmethodID g_getCoreCountMethod = nullptr;
 jmethodID g_getArchitectureMethod = nullptr;
 jmethodID g_getGPUFamilyMethod = nullptr;
 jmethodID g_isTabletMethod = nullptr;
+jmethodID g_httpDownloadMethod = nullptr;
+jmethodID g_httpDownloadCancelMethod = nullptr;
 // HttpResponse field IDs
 jfieldID g_httpResponse_successField = nullptr;
 jfieldID g_httpResponse_statusCodeField = nullptr;
@@ -101,11 +104,14 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
       g_getArchitectureMethod = env->GetStaticMethodID(g_platformAdapterBridgeClass, "getArchitecture", "()Ljava/lang/String;");
       g_getGPUFamilyMethod = env->GetStaticMethodID(g_platformAdapterBridgeClass, "getGPUFamily", "()Ljava/lang/String;");
       g_isTabletMethod = env->GetStaticMethodID(g_platformAdapterBridgeClass, "isTablet", "()Z");
+      g_httpDownloadMethod = env->GetStaticMethodID(g_platformAdapterBridgeClass, "httpDownload", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)I");
+      g_httpDownloadCancelMethod = env->GetStaticMethodID(g_platformAdapterBridgeClass, "httpDownloadCancel", "(Ljava/lang/String;)Z");
 
-      if (g_secureSetMethod && g_secureGetMethod && g_getPersistentDeviceUUIDMethod && 
+      if (g_secureSetMethod && g_secureGetMethod && g_getPersistentDeviceUUIDMethod &&
           g_getDeviceModelMethod && g_getOSVersionMethod && g_getChipNameMethod &&
-          g_getTotalMemoryMethod && g_getAvailableMemoryMethod && g_getCoreCountMethod && 
-          g_getArchitectureMethod && g_getGPUFamilyMethod && g_isTabletMethod) {
+          g_getTotalMemoryMethod && g_getAvailableMemoryMethod && g_getCoreCountMethod &&
+          g_getArchitectureMethod && g_getGPUFamilyMethod && g_isTabletMethod &&
+          g_httpDownloadMethod && g_httpDownloadCancelMethod) {
         LOGI("PlatformAdapterBridge class and methods cached successfully");
       } else {
         LOGE("Failed to cache some PlatformAdapterBridge methods");
@@ -269,3 +275,45 @@ extern "C" bool ArchiveUtility_extractAndroid(const char* archivePath, const cha
 
     return result == JNI_TRUE;
 }
+
+// =============================================================================
+// HTTP Download Callback Reporting (from Kotlin to C++)
+// =============================================================================
+
+static std::string jstringToStdString(JNIEnv* env, jstring value) {
+    if (value == nullptr) {
+        return "";
+    }
+    const char* chars = env->GetStringUTFChars(value, nullptr);
+    std::string result = chars ? chars : "";
+    if (chars) {
+        env->ReleaseStringUTFChars(value, chars);
+    }
+    return result;
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_margelo_nitro_runanywhere_PlatformAdapterBridge_nativeHttpDownloadReportProgress(
+    JNIEnv* env, jclass clazz, jstring taskId, jlong downloadedBytes, jlong totalBytes) {
+    (void)clazz;
+    std::string task = jstringToStdString(env, taskId);
+    return RunAnywhereHttpDownloadReportProgress(task.c_str(),
+                                                 static_cast<int64_t>(downloadedBytes),
+                                                 static_cast<int64_t>(totalBytes));
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_margelo_nitro_runanywhere_PlatformAdapterBridge_nativeHttpDownloadReportComplete(
+    JNIEnv* env, jclass clazz, jstring taskId, jint result, jstring downloadedPath) {
+    (void)clazz;
+    std::string task = jstringToStdString(env, taskId);
+    if (downloadedPath == nullptr) {
+        return RunAnywhereHttpDownloadReportComplete(task.c_str(),
+                                                     static_cast<int>(result),
+                                                     nullptr);
+    }
+    std::string path = jstringToStdString(env, downloadedPath);
+    return RunAnywhereHttpDownloadReportComplete(task.c_str(),
+                                                 static_cast<int>(result),
+                                                 path.c_str());
+}