feat(model-management): Add device compatibility check for models using RACommons (#357)

Author: JoshuaChil

sdk/runanywhere-commons/CMakeLists.txt

@@ -205,6 +205,7 @@ set(RAC_INFRASTRUCTURE_SOURCES
     src/infrastructure/model_management/model_paths.cpp
     src/infrastructure/model_management/model_strategy.cpp
     src/infrastructure/model_management/model_assignment.cpp
+    src/infrastructure/model_management/model_compatibility.cpp
     src/infrastructure/storage/storage_analyzer.cpp
     src/infrastructure/network/environment.cpp
     src/infrastructure/network/endpoints.cpp

sdk/runanywhere-commons/exports/RACommons.exports

@@ -118,6 +118,7 @@ _rac_model_info_copy
 _rac_model_info_free
 _rac_model_info_is_downloaded
 _rac_model_matches_filter
+_rac_model_check_compatibility
 
 # Model Paths
 _rac_model_paths_extract_framework

sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_compatibility.h

@@ -0,0 +1,69 @@
+/**
+ * @file rac_model_compatibility.h
+ * @brief Model Compatibility Check - Checks device RAM/storage against model requirements
+ *
+ * Minimalist check: compares the model's memory_required and download_size
+ * against the device's available RAM and free storage.
+ */
+
+#ifndef RAC_MODEL_COMPATIBILITY_H
+#define RAC_MODEL_COMPATIBILITY_H
+
+#include "rac/core/rac_types.h"
+#include "rac/infrastructure/model_management/rac_model_registry.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Result of a model compatibility check
+ */
+typedef struct rac_model_compatibility_result {
+    /** Overall compatibility (canRun AND canFit) */
+    rac_bool_t is_compatible;
+
+    /** Whether the device has enough RAM to run the model */
+    rac_bool_t can_run;
+
+    /** Whether the device has enough free storage to download/store the model */
+    rac_bool_t can_fit;
+
+    /** Model's required RAM in bytes (from model registry) */
+    int64_t required_memory;
+
+    /** Device's available RAM in bytes */
+    int64_t available_memory;
+
+    /** Model's download/storage size in bytes (from model registry) */
+    int64_t required_storage;
+
+    /** Device's available storage in bytes */
+    int64_t available_storage;
+} rac_model_compatibility_result_t;
+
+/**
+ * @brief Check if a model is compatible with the current device
+ *
+ * Looks up the model in the registry, reads its memory_required and download_size,
+ * then compares against the provided available RAM and storage values.
+ *
+ * @param registry_handle    Model registry handle (to look up model metadata)
+ * @param model_id          Model identifier string
+ * @param available_ram     Available RAM in bytes (provided by caller)
+ * @param available_storage Available storage in bytes (provided by caller)
+ * @param out_result        Output: compatibility result
+ * @return RAC_SUCCESS, RAC_ERROR_NOT_FOUND if model not in registry, or other error
+ */
+RAC_API rac_result_t rac_model_check_compatibility(
+    rac_model_registry_handle_t registry_handle,
+    const char* model_id,
+    int64_t available_ram,
+    int64_t available_storage,
+    rac_model_compatibility_result_t* out_result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_MODEL_COMPATIBILITY_H */

sdk/runanywhere-commons/src/infrastructure/model_management/model_compatibility.cpp

@@ -0,0 +1,92 @@
+/**
+ * @file model_compatibility.cpp
+ * @brief Implementation of model compatibility checks
+ *
+ * C++ implementation. The C API is declared in the header with extern "C".
+ * Follows the same pattern as model_paths.cpp, model_registry.cpp, etc.
+ */
+
+#include "rac/infrastructure/model_management/rac_model_compatibility.h"
+#include "rac/core/rac_logger.h"
+#include "rac/infrastructure/model_management/rac_model_registry.h"
+
+#include <cstring>
+
+// =============================================================================
+// COMPATIBILITY CHECK IMPLEMENTATION
+// =============================================================================
+
+rac_result_t rac_model_check_compatibility(
+    rac_model_registry_handle_t registry_handle,
+    const char* model_id,
+    int64_t available_ram,
+    int64_t available_storage,
+    rac_model_compatibility_result_t* out_result) {
+
+    if (!registry_handle || !model_id || !out_result) {
+        RAC_LOG_ERROR("ModelCompatibility", "Invalid arguments");
+        return RAC_ERROR_INVALID_ARGUMENT;
+    }
+
+    // Zero-initialize the result
+    std::memset(out_result, 0, sizeof(rac_model_compatibility_result_t));
+
+    // Look up the model in the registry
+    rac_model_info_t* model = nullptr;
+    rac_result_t result = rac_model_registry_get(registry_handle, model_id, &model);
+    
+    if (result != RAC_SUCCESS) {
+        RAC_LOG_WARNING("ModelCompatibility", 
+                        "Failed to get model from registry: %s (error: %d)", 
+                        model_id, result);
+        return result;
+    }
+    
+    if (!model) {
+        RAC_LOG_WARNING("ModelCompatibility", "Model not found: %s", model_id);
+        return RAC_ERROR_NOT_FOUND;
+    }
+
+    // Extract model requirements
+    int64_t required_memory = model->memory_required;   // bytes
+    int64_t required_storage = model->download_size;     // bytes
+
+    RAC_LOG_DEBUG("ModelCompatibility", 
+                "Model %s requirements: memory=%lld bytes, storage=%lld bytes",
+                model_id,
+                static_cast<long long>(required_memory),
+                static_cast<long long>(required_storage));
+
+    // Determine compatibility
+    // can_run:  available RAM >= required memory (or requirement is 0/unknown)
+    // can_fit:  available storage >= required storage (or requirement is 0/unknown)
+    rac_bool_t can_run = (required_memory <= 0 || available_ram >= required_memory)
+                             ? RAC_TRUE : RAC_FALSE;
+    rac_bool_t can_fit = (required_storage <= 0 || available_storage >= required_storage)
+                             ? RAC_TRUE : RAC_FALSE;
+
+    // Populate result
+    out_result->can_run = can_run;
+    out_result->can_fit = can_fit;
+    out_result->is_compatible = (can_run == RAC_TRUE && can_fit == RAC_TRUE)
+                                    ? RAC_TRUE : RAC_FALSE;
+    out_result->required_memory = required_memory;
+    out_result->available_memory = available_ram;
+    out_result->required_storage = required_storage;
+    out_result->available_storage = available_storage;
+
+    RAC_LOG_INFO("ModelCompatibility",
+                 "Model %s: canRun=%d canFit=%d isCompatible=%d "
+                 "(RAM: %lld/%lld, Storage: %lld/%lld)",
+                 model_id,
+                 can_run, can_fit, out_result->is_compatible,
+                 static_cast<long long>(available_ram), 
+                 static_cast<long long>(required_memory),
+                 static_cast<long long>(available_storage), 
+                 static_cast<long long>(required_storage));
+
+    // Free the model info (allocated by rac_model_registry_get)
+    rac_model_info_free(model);
+
+    return RAC_SUCCESS;
+}

sdk/runanywhere-react-native/packages/core/cpp/HybridRunAnywhereCore.cpp

@@ -31,6 +31,7 @@
 #include "bridges/AuthBridge.hpp"
 #include "bridges/StorageBridge.hpp"
 #include "bridges/ModelRegistryBridge.hpp"
+#include "bridges/CompatibilityBridge.hpp"
 #include "bridges/EventBridge.hpp"
 #include "bridges/HTTPBridge.hpp"
 #include "bridges/DownloadBridge.hpp"
@@ -1007,10 +1008,38 @@ std::shared_ptr<Promise<bool>> HybridRunAnywhereCore::registerModel(
     });
 }
 
+// ============================================================================
+// Compatibility Service
+// ============================================================================
+
+std::shared_ptr<Promise<std::string>> HybridRunAnywhereCore::checkCompatibility(
+    const std::string& modelId) {
+    return Promise<std::string>::async([modelId]() -> std::string {
+        auto registryHandle = ModelRegistryBridge::shared().getHandle();
+        if (!registryHandle) {
+            LOGE("Model registry not initialized");
+            return "{}";
+        }
+
+        // Delegate to CompatibilityBridge - it handles querying device capabilities
+        auto result = CompatibilityBridge::checkCompatibility(modelId, registryHandle);
+
+        return buildJsonObject({
+            {"isCompatible", result.isCompatible ? "true" : "false"},
+            {"canRun", result.canRun ? "true" : "false"},
+            {"canFit", result.canFit ? "true" : "false"},
+            {"requiredMemory", std::to_string(result.requiredMemory)},
+            {"availableMemory", std::to_string(result.availableMemory)},
+            {"requiredStorage", std::to_string(result.requiredStorage)},
+            {"availableStorage", std::to_string(result.availableStorage)}
+        });
+    });
+}
 // ============================================================================
 // Download Service
 // ============================================================================
 
+
 std::shared_ptr<Promise<bool>> HybridRunAnywhereCore::downloadModel(
     const std::string& modelId,
     const std::string& url,

sdk/runanywhere-react-native/packages/core/cpp/HybridRunAnywhereCore.hpp

@@ -92,6 +92,7 @@ class HybridRunAnywhereCore : public HybridRunAnywhereCoreSpec {
   std::shared_ptr<Promise<bool>> isModelDownloaded(const std::string& modelId) override;
   std::shared_ptr<Promise<std::string>> getModelPath(const std::string& modelId) override;
   std::shared_ptr<Promise<bool>> registerModel(const std::string& modelJson) override;
+  std::shared_ptr<Promise<std::string>> checkCompatibility(const std::string& modelId) override;
 
   // ============================================================================
   // Download Service - Delegates to DownloadBridge

sdk/runanywhere-react-native/packages/core/cpp/bridges/CompatibilityBridge.cpp

@@ -0,0 +1,107 @@
+/**
+ * @file CompatibilityBridge.cpp
+ * @brief C++ bridge for model compatibility checks.
+ *
+ * Uses DeviceBridge for RAM and POSIX statvfs for disk space,
+ * then calls rac_model_check_compatibility() from runanywhere-commons.
+ */
+
+#include "CompatibilityBridge.hpp"
+#include "DeviceBridge.hpp"
+
+#include <sys/statvfs.h>  // POSIX filesystem statistics
+
+// Platform-specific logging
+#if defined(ANDROID) || defined(__ANDROID__)
+#include <android/log.h>
+#define LOG_TAG "CompatibilityBridge"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGD(...) __android_log_print(ANDROID_LOG_DEBUG, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+#else
+#include <cstdio>
+#define LOGI(...) printf("[CompatibilityBridge] "); printf(__VA_ARGS__); printf("\n")
+#define LOGD(...) printf("[CompatibilityBridge DEBUG] "); printf(__VA_ARGS__); printf("\n")
+#define LOGE(...) printf("[CompatibilityBridge ERROR] "); printf(__VA_ARGS__); printf("\n")
+#endif
+
+namespace runanywhere {
+namespace bridges {
+
+CompatibilityResult CompatibilityBridge::checkCompatibility(
+    const std::string& modelId,
+    rac_model_registry_handle_t registryHandle) {
+    
+    CompatibilityResult result;
+
+    if (!registryHandle) {
+        LOGE("Model registry handle is null");
+        return result;
+    }
+
+    // Get available RAM from DeviceBridge
+    int64_t availableRAM = 0;
+    if (DeviceBridge::shared().isCallbacksRegistered()) {
+        auto deviceInfo = DeviceBridge::shared().getDeviceInfo();
+        availableRAM = deviceInfo.availableMemory;
+        LOGD("Available RAM from DeviceBridge: %lld bytes", 
+             static_cast<long long>(availableRAM));
+    } else {
+        LOGD("DeviceBridge not initialized, RAM check will be skipped");
+    }
+
+    // Get available storage using POSIX statvfs
+    // This queries the filesystem directly - same as what FileManager/StatFs use underneath
+    int64_t availableStorage = 0;
+    {
+        struct statvfs stat;
+        // Query root filesystem - works on both iOS and Android
+        if (statvfs("/", &stat) == 0) {
+            // f_bavail = available blocks for unprivileged users
+            // f_frsize = fragment size (fundamental block size)
+            availableStorage = static_cast<int64_t>(stat.f_bavail) * static_cast<int64_t>(stat.f_frsize);
+            
+            LOGD("Available storage from statvfs: %lld bytes (%.2f GB)",
+                 static_cast<long long>(availableStorage),
+                 static_cast<double>(availableStorage) / (1024.0 * 1024.0 * 1024.0));
+        } else {
+            LOGE("statvfs failed (errno=%d), storage check will be skipped", errno);
+        }
+    }
+
+    // Call the RACommons C API
+    rac_model_compatibility_result_t cResult;
+    rac_result_t rc = rac_model_check_compatibility(
+        registryHandle,
+        modelId.c_str(),
+        availableRAM,
+        availableStorage,
+        &cResult);
+
+    if (rc == RAC_SUCCESS) {
+        result.isCompatible = cResult.is_compatible == RAC_TRUE;
+        result.canRun = cResult.can_run == RAC_TRUE;
+        result.canFit = cResult.can_fit == RAC_TRUE;
+        result.requiredMemory = cResult.required_memory;
+        result.availableMemory = cResult.available_memory;
+        result.requiredStorage = cResult.required_storage;
+        result.availableStorage = cResult.available_storage;
+        
+        LOGI("Compatibility check for %s: compatible=%d, canRun=%d, canFit=%d, RAM=%lld/%lld, Storage=%lld/%lld",
+             modelId.c_str(), 
+             result.isCompatible, 
+             result.canRun, 
+             result.canFit,
+             static_cast<long long>(result.availableMemory),
+             static_cast<long long>(result.requiredMemory),
+             static_cast<long long>(result.availableStorage),
+             static_cast<long long>(result.requiredStorage));
+    } else {
+        LOGE("Compatibility check failed for %s: error %d", modelId.c_str(), rc);
+    }
+
+    return result;
+}
+
+} // namespace bridges
+} // namespace runanywhere