react-native-litert-lm 0.1.0

package/nitrogen/generated/shared/c++/HybridLiteRTLMSpec.hpp

@@ -0,0 +1,82 @@
+///
+/// HybridLiteRTLMSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `LLMConfig` to properly resolve imports.
+namespace margelo::nitro::litertlm { struct LLMConfig; }
+// Forward declaration of `Message` to properly resolve imports.
+namespace margelo::nitro::litertlm { struct Message; }
+// Forward declaration of `GenerationStats` to properly resolve imports.
+namespace margelo::nitro::litertlm { struct GenerationStats; }
+
+#include <string>
+#include "LLMConfig.hpp"
+#include <optional>
+#include <functional>
+#include "Message.hpp"
+#include <vector>
+#include "GenerationStats.hpp"
+
+namespace margelo::nitro::litertlm {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `LiteRTLM`
+   * Inherit this class to create instances of `HybridLiteRTLMSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridLiteRTLM: public HybridLiteRTLMSpec {
+   * public:
+   *   HybridLiteRTLM(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridLiteRTLMSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridLiteRTLMSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridLiteRTLMSpec() override = default;
+
+    public:
+      // Properties
+      
+
+    public:
+      // Methods
+      virtual void loadModel(const std::string& modelPath, const std::optional<LLMConfig>& config) = 0;
+      virtual std::string sendMessage(const std::string& message) = 0;
+      virtual std::string sendMessageWithImage(const std::string& message, const std::string& imagePath) = 0;
+      virtual std::string sendMessageWithAudio(const std::string& message, const std::string& audioPath) = 0;
+      virtual void sendMessageAsync(const std::string& message, const std::function<void(const std::string& /* token */, bool /* done */)>& onToken) = 0;
+      virtual std::vector<Message> getHistory() = 0;
+      virtual void resetConversation() = 0;
+      virtual bool isReady() = 0;
+      virtual GenerationStats getStats() = 0;
+      virtual void close() = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "LiteRTLM";
+  };
+
+} // namespace margelo::nitro::litertlm

package/nitrogen/generated/shared/c++/LLMConfig.hpp

@@ -0,0 +1,101 @@
+///
+/// LLMConfig.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `Backend` to properly resolve imports.
+namespace margelo::nitro::litertlm { enum class Backend; }
+
+#include "Backend.hpp"
+#include <optional>
+
+namespace margelo::nitro::litertlm {
+
+  /**
+   * A struct which can be represented as a JavaScript object (LLMConfig).
+   */
+  struct LLMConfig final {
+  public:
+    std::optional<Backend> backend     SWIFT_PRIVATE;
+    std::optional<double> maxTokens     SWIFT_PRIVATE;
+    std::optional<double> temperature     SWIFT_PRIVATE;
+    std::optional<double> topK     SWIFT_PRIVATE;
+    std::optional<double> topP     SWIFT_PRIVATE;
+
+  public:
+    LLMConfig() = default;
+    explicit LLMConfig(std::optional<Backend> backend, std::optional<double> maxTokens, std::optional<double> temperature, std::optional<double> topK, std::optional<double> topP): backend(backend), maxTokens(maxTokens), temperature(temperature), topK(topK), topP(topP) {}
+
+  public:
+    friend bool operator==(const LLMConfig& lhs, const LLMConfig& rhs) = default;
+  };
+
+} // namespace margelo::nitro::litertlm
+
+namespace margelo::nitro {
+
+  // C++ LLMConfig <> JS LLMConfig (object)
+  template <>
+  struct JSIConverter<margelo::nitro::litertlm::LLMConfig> final {
+    static inline margelo::nitro::litertlm::LLMConfig fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::litertlm::LLMConfig(
+        JSIConverter<std::optional<margelo::nitro::litertlm::Backend>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "backend"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "maxTokens"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "temperature"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "topK"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "topP")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::litertlm::LLMConfig& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "backend"), JSIConverter<std::optional<margelo::nitro::litertlm::Backend>>::toJSI(runtime, arg.backend));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "maxTokens"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.maxTokens));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "temperature"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.temperature));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "topK"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.topK));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "topP"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.topP));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::optional<margelo::nitro::litertlm::Backend>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "backend")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "maxTokens")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "temperature")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "topK")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "topP")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/Message.hpp

@@ -0,0 +1,89 @@
+///
+/// Message.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `Role` to properly resolve imports.
+namespace margelo::nitro::litertlm { enum class Role; }
+
+#include "Role.hpp"
+#include <string>
+
+namespace margelo::nitro::litertlm {
+
+  /**
+   * A struct which can be represented as a JavaScript object (Message).
+   */
+  struct Message final {
+  public:
+    Role role     SWIFT_PRIVATE;
+    std::string content     SWIFT_PRIVATE;
+
+  public:
+    Message() = default;
+    explicit Message(Role role, std::string content): role(role), content(content) {}
+
+  public:
+    friend bool operator==(const Message& lhs, const Message& rhs) = default;
+  };
+
+} // namespace margelo::nitro::litertlm
+
+namespace margelo::nitro {
+
+  // C++ Message <> JS Message (object)
+  template <>
+  struct JSIConverter<margelo::nitro::litertlm::Message> final {
+    static inline margelo::nitro::litertlm::Message fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::litertlm::Message(
+        JSIConverter<margelo::nitro::litertlm::Role>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "role"))),
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "content")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::litertlm::Message& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "role"), JSIConverter<margelo::nitro::litertlm::Role>::toJSI(runtime, arg.role));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "content"), JSIConverter<std::string>::toJSI(runtime, arg.content));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<margelo::nitro::litertlm::Role>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "role")))) return false;
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "content")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/Role.hpp

@@ -0,0 +1,80 @@
+///
+/// Role.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::litertlm {
+
+  /**
+   * An enum which can be represented as a JavaScript union (Role).
+   */
+  enum class Role {
+    USER      SWIFT_NAME(user) = 0,
+    MODEL      SWIFT_NAME(model) = 1,
+    SYSTEM      SWIFT_NAME(system) = 2,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::litertlm
+
+namespace margelo::nitro {
+
+  // C++ Role <> JS Role (union)
+  template <>
+  struct JSIConverter<margelo::nitro::litertlm::Role> final {
+    static inline margelo::nitro::litertlm::Role fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("user"): return margelo::nitro::litertlm::Role::USER;
+        case hashString("model"): return margelo::nitro::litertlm::Role::MODEL;
+        case hashString("system"): return margelo::nitro::litertlm::Role::SYSTEM;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum Role - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::litertlm::Role arg) {
+      switch (arg) {
+        case margelo::nitro::litertlm::Role::USER: return JSIConverter<std::string>::toJSI(runtime, "user");
+        case margelo::nitro::litertlm::Role::MODEL: return JSIConverter<std::string>::toJSI(runtime, "model");
+        case margelo::nitro::litertlm::Role::SYSTEM: return JSIConverter<std::string>::toJSI(runtime, "system");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert Role to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("user"):
+        case hashString("model"):
+        case hashString("system"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "react-native-litert-lm",
+  "version": "0.1.0",
+  "description": "High-performance LLM inference for React Native using LiteRT-LM. Optimized for Gemma 3n and other on-device language models.",
+  "license": "MIT",
+  "author": "Hugh Chen (https://github.com/hung-yueh)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hung-yueh/react-native-litert-lm.git"
+  },
+  "homepage": "https://github.com/hung-yueh/react-native-litert-lm#readme",
+  "bugs": {
+    "url": "https://github.com/hung-yueh/react-native-litert-lm/issues"
+  },
+  "keywords": [
+    "react-native",
+    "nitro",
+    "litert",
+    "litert-lm",
+    "llm",
+    "gemma",
+    "gemma-3n",
+    "ai",
+    "machine-learning",
+    "on-device",
+    "inference",
+    "expo"
+  ],
+  "main": "lib/index",
+  "module": "lib/index",
+  "types": "lib/index.d.ts",
+  "react-native": "src/index",
+  "source": "src/index",
+  "files": [
+    "src",
+    "lib",
+    "android/src",
+    "android/build.gradle",
+    "android/CMakeLists.txt",
+    "ios",
+    "cpp",
+    "nitrogen/generated",
+    "react-native.config.js",
+    "react-native-litert-lm.podspec",
+    "app.plugin.js",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"**/*.{js,ts,tsx}\" --fix",
+    "prepack": "npm run build",
+    "specs": "npx nitrogen",
+    "clean": "rm -rf lib android/build ios/build nitrogen/generated",
+    "android": "expo run:android",
+    "android:clean": "cd android && ./gradlew clean",
+    "ios": "expo run:ios",
+    "release": "release-it"
+  },
+  "devDependencies": {
+    "@expo/config-plugins": "~54.0.4",
+    "@types/react": "~19.1.10",
+    "expo": "^54.0.31",
+    "nitrogen": "^0.33.2",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "release-it": "^19.2.4",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "expo": ">=54.0.0",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "react-native-nitro-modules": "^0.33.2"
+  }
+}

package/react-native-litert-lm.podspec

@@ -0,0 +1,51 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "react-native-litert-lm"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+  s.platforms    = { :ios => "15.0" }
+  s.source       = { :git => package["repository"]["url"], :tag => "#{s.version}" }
+  
+  s.swift_version = '5.0'
+
+  s.source_files = [
+    # Implementation (C++)
+    "cpp/**/*.{hpp,cpp}",
+    # Autolinking (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Nitrogen generated iOS bridge
+    "nitrogen/generated/ios/**/*.{mm,swift}",
+  ]
+
+  s.pod_target_xcconfig = {
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++20',
+    'CLANG_CXX_LIBRARY' => 'libc++',
+    'HEADER_SEARCH_PATHS' => [
+      '"$(PODS_TARGET_SRCROOT)/cpp"',
+      '"$(PODS_TARGET_SRCROOT)/nitrogen/generated/shared/c++"',
+      '"$(PODS_TARGET_SRCROOT)/nitrogen/generated/ios"',
+    ].join(' '),
+    # Stub mode - LiteRT-LM iOS not yet available
+    'GCC_PREPROCESSOR_DEFINITIONS' => '$(inherited) LITERT_LM_IOS_STUB=1',
+  }
+
+  # Load nitrogen autolinking
+  load 'nitrogen/generated/ios/LiteRTLM+autolinking.rb'
+  add_nitrogen_files(s)
+
+  # Core dependencies only - no LLM runtime yet
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  s.dependency 'ReactCommon/turbomodule/core'
+  
+  # TODO: Add LiteRT-LM iOS dependency when officially released
+  # s.dependency 'LiteRTLM', '~> 1.0'
+
+  install_modules_dependencies(s)
+end

package/react-native.config.js

@@ -0,0 +1,16 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: "./android",
+        packageImportPath: "import dev.litert.litertlm.LiteRTLMPackage;",
+        packageInstance: "new LiteRTLMPackage()",
+        componentDescriptors: [],
+        cmakeListsPath: "CMakeLists.txt",
+      },
+      ios: {
+        podspecPath: "./react-native-litert-lm.podspec",
+      },
+    },
+  },
+};

package/src/index.ts

@@ -0,0 +1,125 @@
+import { NitroModules } from "react-native-nitro-modules";
+import { Platform } from "react-native";
+import type {
+  LiteRTLM,
+  LLMConfig,
+  Message,
+  Backend,
+  Role,
+  GenerationStats,
+} from "./specs/LiteRTLM.nitro";
+
+export type {
+  LiteRTLM,
+  LLMConfig,
+  Message,
+  Backend,
+  Role,
+  GenerationStats,
+} from "./specs/LiteRTLM.nitro";
+
+/**
+ * Creates a new LiteRT-LM inference engine instance.
+ *
+ * @example
+ * ```typescript
+ * import { createLLM } from 'react-native-litert-lm';
+ *
+ * // Basic usage with Gemma 3n
+ * const llm = createLLM();
+ * llm.loadModel('/path/to/gemma-3n-e2b.litertlm', {
+ *   backend: 'gpu',
+ *   temperature: 0.7,
+ *   maxTokens: 512
+ * });
+ *
+ * // Simple text generation
+ * const response = llm.sendMessage('Hello, how are you?');
+ * console.log(response);
+ *
+ * // Streaming generation
+ * llm.sendMessageAsync('Tell me about React Native', (token, done) => {
+ *   process.stdout.write(token);
+ *   if (done) console.log('\n--- Done ---');
+ * });
+ *
+ * // Check stats
+ * const stats = llm.getStats();
+ * console.log(`Generated at ${stats.tokensPerSecond} tokens/sec`);
+ *
+ * // Cleanup
+ * llm.close();
+ * ```
+ */
+export function createLLM(): LiteRTLM {
+  return NitroModules.createHybridObject<LiteRTLM>("LiteRTLM");
+}
+
+/**
+ * Pre-defined model identifiers for common models.
+ * Use with model download utilities or as reference.
+ */
+export const Models = {
+  /** Gemma 3n E2B (2B parameters, efficient) */
+  GEMMA_3N_E2B: "gemma-3n-E2B-it-litert-lm-preview",
+  /** Gemma 3n E4B (4B parameters, higher quality) */
+  GEMMA_3N_E4B: "gemma-3n-E4B-it-litert-lm-preview",
+  /** Gemma 3 1B (smallest Gemma) */
+  GEMMA_3_1B: "Gemma3-1B-IT_multi-prefill-seq_q4_ekv4096",
+  /** Phi-4 Mini Instruct */
+  PHI_4_MINI: "Phi-4-mini-instruct_multi-prefill-seq_q8_ekv4096",
+  /** Qwen 2.5 1.5B Instruct */
+  QWEN_2_5_1_5B: "Qwen2.5-1.5B-Instruct_multi-prefill-seq_q8_ekv4096",
+} as const;
+
+export type ModelId = (typeof Models)[keyof typeof Models];
+
+/**
+ * Get the recommended backend for the current platform.
+ * Returns 'gpu' for most devices as it provides the best balance of speed and compatibility.
+ *
+ * @returns The recommended backend ('gpu' for most cases)
+ *
+ * @example
+ * ```typescript
+ * const backend = getRecommendedBackend();
+ * llm.loadModel(path, { backend });
+ * ```
+ */
+export function getRecommendedBackend(): Backend {
+  // GPU is the recommended default for all platforms
+  // It provides good performance and broad compatibility
+  return "gpu";
+}
+
+/**
+ * Check if a backend configuration is supported on the current platform.
+ * Returns a warning message if the configuration may have issues.
+ *
+ * @param backend The backend to check
+ * @returns Warning message if there may be issues, undefined if OK
+ *
+ * @example
+ * ```typescript
+ * const warning = checkBackendSupport('npu');
+ * if (warning) {
+ *   console.warn(warning);
+ * }
+ * ```
+ */
+export function checkBackendSupport(backend: Backend): string | undefined {
+  if (backend === "npu") {
+    if (Platform.OS === "android") {
+      return "NPU backend requires compatible hardware (Qualcomm Hexagon, MediaTek APU, etc.). Will fall back to GPU if unavailable.";
+    }
+    if (Platform.OS === "ios") {
+      return "NPU/CoreML is not yet supported on iOS. LiteRT-LM iOS support is pending.";
+    }
+  }
+
+  if (Platform.OS === "ios" && backend !== "cpu") {
+    return "LiteRT-LM iOS is not yet released. Only CPU backend may work via fallback.";
+  }
+
+  return undefined;
+}