@runanywhere/llamacpp 0.18.1 → 0.19.13

package/src/LlamaCPP.ts

@@ -2,205 +2,77 @@
  * @runanywhere/llamacpp - LlamaCPP Module
  *
  * LlamaCPP module wrapper for RunAnywhere React Native SDK.
- * Provides public API for module registration and model declaration.
+ * Provides public API for module registration only.
  *
- * This mirrors the Swift SDK's LlamaCPP module pattern:
- * - LlamaCPP.register() - Register the module with ServiceRegistry
- * - LlamaCPP.addModel() - Declare a model for this module
+ * Model registration is done via RunAnywhere.registerModel() / RunAnywhere.registerMultiFileModel()
+ * on the core SDK, matching the Swift SDK pattern where LlamaCPP only exposes
+ * register() and unregister().
  *
- * Reference: sdk/runanywhere-swift/Sources/LlamaCPPRuntime/LlamaCPPServiceProvider.swift
+ * Reference: sdk/runanywhere-swift/Sources/LlamaCPPRuntime/LlamaCPP.swift
  */
 
 import { LlamaCppProvider } from './LlamaCppProvider';
-import {
-  ModelRegistry,
-  FileSystem,
-  LLMFramework,
-  ModelCategory,
-  ModelFormat,
-  ConfigurationSource,
-  SDKLogger,
-  type ModelInfo,
-} from '@runanywhere/core';
+import { SDKLogger } from '@runanywhere/core/internal';
 
-// SDKLogger instance for this module
 const log = new SDKLogger('LLM.LlamaCpp');
 
-/**
- * Model registration options for LlamaCPP models
- *
- * Matches iOS: LlamaCPP.addModel() parameter structure
- */
-export interface LlamaCPPModelOptions {
-  /** Unique model ID. If not provided, generated from URL filename */
-  id?: string;
-  /** Display name for the model */
-  name: string;
-  /** Download URL for the model */
-  url: string;
-  /** Model category (defaults to Language for LLM models) */
-  modality?: ModelCategory;
-  /** Memory requirement in bytes */
-  memoryRequirement?: number;
-  /** Whether model supports reasoning/thinking tokens */
-  supportsThinking?: boolean;
-}
-
 /**
  * LlamaCPP Module
  *
- * Public API for registering LlamaCPP module and declaring GGUF models.
- * This provides the same developer experience as the iOS SDK.
+ * Matches iOS: public enum LlamaCPP: RunAnywhereModule
+ *
+ * Only provides backend registration. Model registration is done via
+ * RunAnywhere.registerModel() on the core SDK.
  *
  * ## Usage
  *
  * ```typescript
  * import { LlamaCPP } from '@runanywhere/llamacpp';
+ * import { RunAnywhere } from '@runanywhere/core';
+ * // Register LlamaCPP backend
+ * await LlamaCPP.register();
  *
- * // Register module
- * LlamaCPP.register();
- *
- * // Add models
- * LlamaCPP.addModel({
+ * // Register models via RunAnywhere (matching iOS pattern)
+ * await RunAnywhere.registerModel({
  *   id: 'smollm2-360m-q8_0',
  *   name: 'SmolLM2 360M Q8_0',
- *   url: 'https://huggingface.co/prithivMLmods/SmolLM2-360M-GGUF/resolve/main/SmolLM2-360M.Q8_0.gguf',
+ *   url: '...',
+ *   framework: InferenceFramework.INFERENCE_FRAMEWORK_LLAMA_CPP,
  *   memoryRequirement: 500_000_000
  * });
  * ```
- *
- * Matches iOS: public enum LlamaCPP: RunAnywhereModule
  */
 export const LlamaCPP = {
-  /**
-   * Module metadata
-   * Matches iOS: static let moduleId, moduleName, inferenceFramework
-   */
-  moduleId: 'llamacpp',
-  moduleName: 'LlamaCPP',
-  inferenceFramework: LLMFramework.LlamaCpp,
-  capabilities: ['llm'] as const,
-  defaultPriority: 100,
-
   /**
    * Register LlamaCPP module with the SDK
    *
-   * This registers the LlamaCPP provider with ServiceRegistry,
-   * enabling it to handle GGUF models.
+   * Registers the LlamaCPP LLM and VLM providers with ServiceRegistry.
    *
    * Matches iOS: static func register(priority: Int = defaultPriority)
-   *
-   * @example
-   * ```typescript
-   * LlamaCPP.register();
-   * ```
    */
-  register(): void {
+  async register(): Promise<boolean> {
     log.debug('Registering LlamaCPP module');
-    LlamaCppProvider.register();
-    log.info('LlamaCPP module registered');
+    const registered = await LlamaCppProvider.register();
+    if (registered) {
+      log.info('LlamaCPP module registered');
+    }
+    return registered;
   },
 
   /**
-   * Add a model to this module
+   * Unregister LlamaCPP module from the SDK
    *
-   * Registers a GGUF model with the ModelRegistry.
-   * The model will use LlamaCPP framework automatically.
-   *
-   * Matches iOS: static func addModel(id:name:url:modality:memoryRequirement:supportsThinking:)
-   *
-   * @param options - Model registration options
-   * @returns Promise resolving to the created ModelInfo
-   *
-   * @example
-   * ```typescript
-   * await LlamaCPP.addModel({
-   *   id: 'llama-2-7b-chat-q4_k_m',
-   *   name: 'Llama 2 7B Chat Q4_K_M',
-   *   url: 'https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/main/llama-2-7b-chat.Q4_K_M.gguf',
-   *   memoryRequirement: 4_000_000_000
-   * });
-   * ```
+   * Matches iOS: static func unregister()
    */
-  async addModel(options: LlamaCPPModelOptions): Promise<ModelInfo> {
-    // Generate stable ID from URL if not provided
-    const modelId = options.id ?? this._generateModelId(options.url);
-
-    // Determine modality (default to Language for LLM)
-    const category = options.modality ?? ModelCategory.Language;
-
-    // Infer format from URL
-    const format = options.url.toLowerCase().includes('.gguf')
-      ? ModelFormat.GGUF
-      : ModelFormat.GGML;
-
-    const now = new Date().toISOString();
-
-    // Check if model already exists on disk (persistence across sessions)
-    let isDownloaded = false;
-    let localPath: string | undefined;
-
-    if (FileSystem.isAvailable()) {
-      try {
-        const exists = await FileSystem.modelExists(modelId, 'LlamaCpp');
-        if (exists) {
-          localPath = await FileSystem.getModelPath(modelId, 'LlamaCpp');
-          isDownloaded = true;
-          log.debug(`Model ${modelId} found on disk: ${localPath}`);
-        }
-      } catch (error) {
-        // Ignore errors checking for existing model
-        log.debug(`Could not check for existing model ${modelId}: ${error}`);
-      }
-    }
-
-    const modelInfo: ModelInfo = {
-      id: modelId,
-      name: options.name,
-      category,
-      format,
-      downloadURL: options.url,
-      localPath,
-      downloadSize: undefined,
-      memoryRequired: options.memoryRequirement,
-      compatibleFrameworks: [LLMFramework.LlamaCpp],
-      preferredFramework: LLMFramework.LlamaCpp,
-      supportsThinking: options.supportsThinking ?? false,
-      metadata: { tags: [] },
-      source: ConfigurationSource.Local,
-      createdAt: now,
-      updatedAt: now,
-      syncPending: false,
-      usageCount: 0,
-      isDownloaded,
-      isAvailable: true,
-    };
-
-    // Register with ModelRegistry and wait for completion
-    await ModelRegistry.registerModel(modelInfo);
-
-    log.info(`Added model: ${modelId} (${options.name})`, {
-      modelId,
-      isDownloaded,
-    });
-
-    return modelInfo;
+  async unregister(): Promise<boolean> {
+    log.info('Unregistering LlamaCPP module');
+    return LlamaCppProvider.unregister();
   },
 
   /**
-   * Generate a stable model ID from URL
-   * @internal
+   * Check if this module is registered with the native backend registry.
    */
-  _generateModelId(url: string): string {
-    try {
-      const urlObj = new URL(url);
-      const pathname = urlObj.pathname;
-      const filename = pathname.split('/').pop() ?? 'model';
-      // Remove common extensions
-      return filename.replace(/\.(gguf|ggml|bin)$/i, '');
-    } catch {
-      // Fallback for invalid URLs
-      return `model-${Date.now()}`;
-    }
+  async isRegistered(): Promise<boolean> {
+    return LlamaCppProvider.isRegistered();
   },
 };

package/src/LlamaCppProvider.ts

@@ -1,49 +1,44 @@
 /**
  * @runanywhere/llamacpp - LlamaCPP Provider
  *
- * LlamaCPP module registration for React Native SDK.
- * Thin wrapper that triggers C++ backend registration.
+ * Internal LlamaCPP module registration for React Native SDK.
+ * Thin wrapper that triggers C++ backend registration behind the LlamaCPP facade.
  *
  * Reference: sdk/runanywhere-swift/Sources/LlamaCPPRuntime/LlamaCPP.swift
  */
 
 import { requireNativeLlamaModule, isNativeLlamaModuleAvailable } from './native/NativeRunAnywhereLlama';
-import { SDKLogger } from '@runanywhere/core';
+import { SDKLogger } from '@runanywhere/core/internal';
 
 // SDKLogger instance for this module
 const log = new SDKLogger('LLM.LlamaCppProvider');
 
 /**
- * LlamaCPP Module
+ * Internal LlamaCPP provider implementation.
  *
- * Provides LLM capabilities using llama.cpp with GGUF models.
- * The actual service is provided by the C++ backend.
+ * Registers the llama.cpp backend provider; the single C++ registration call
+ * covers both LLM and VLM modalities. Core owns public model lifecycle and
+ * inference surfaces.
  *
- * ## Registration
- *
- * ```typescript
- * import { LlamaCppProvider } from '@runanywhere/llamacpp';
- *
- * // Register the backend
- * await LlamaCppProvider.register();
- * ```
+ * @internal
  */
 export class LlamaCppProvider {
   static readonly moduleId = 'llamacpp';
   static readonly moduleName = 'LlamaCPP';
   static readonly version = '2.0.0';
 
-  private static isRegistered = false;
+  private static registered = false;
 
   /**
    * Register LlamaCPP backend with the C++ service registry.
    * Calls rac_backend_llamacpp_register() to register the
-   * LlamaCPP service provider with the C++ commons layer.
+   * LlamaCPP service provider with the C++ commons layer; the single call
+   * covers both LLM and VLM modalities.
    * Safe to call multiple times - subsequent calls are no-ops.
    * @returns Promise<boolean> true if registered successfully
    */
   static async register(): Promise<boolean> {
-    if (this.isRegistered) {
+    if (this.registered) {
       log.debug('LlamaCPP already registered, returning');
       return true;
     }
@@ -60,8 +55,8 @@ export class LlamaCppProvider {
       // Call the native registration method from the Llama module
       const success = await native.registerBackend();
       if (success) {
-        this.isRegistered = true;
-        log.info('LlamaCPP backend registered successfully');
+        this.registered = true;
+        log.info('LlamaCPP backend registered successfully (covers LLM and VLM)');
       }
       return success;
     } catch (error) {
@@ -73,10 +68,11 @@ export class LlamaCppProvider {
 
   /**
    * Unregister the LlamaCPP backend from C++ registry.
+   * The single unregistration call covers both LLM and VLM modalities.
    * @returns Promise<boolean> true if unregistered successfully
    */
   static async unregister(): Promise<boolean> {
-    if (!this.isRegistered) {
+    if (!this.registered) {
       return true;
     }
 
@@ -84,11 +80,12 @@ export class LlamaCppProvider {
       return false;
     }
 
+    const native = requireNativeLlamaModule();
+
     try {
-      const native = requireNativeLlamaModule();
       const success = await native.unregisterBackend();
       if (success) {
-        this.isRegistered = false;
+        this.registered = false;
         log.debug('LlamaCPP backend unregistered');
       }
       return success;
@@ -99,22 +96,21 @@ export class LlamaCppProvider {
   }
 
   /**
-   * Check if LlamaCPP can handle a given model
+   * Check native registration state. Falls back to JS state if the native
+   * object cannot be created.
    */
-  static canHandle(modelId: string | null | undefined): boolean {
-    if (!modelId) {
+  static async isRegistered(): Promise<boolean> {
+    if (!isNativeLlamaModuleAvailable()) {
       return false;
     }
-    const lowercased = modelId.toLowerCase();
-    return lowercased.includes('gguf') || lowercased.endsWith('.gguf');
-  }
-}
 
-/**
- * Auto-register when module is imported
- */
-export function autoRegister(): void {
-  LlamaCppProvider.register().catch(() => {
-    // Silently handle registration failure during auto-registration
-  });
+    try {
+      const native = requireNativeLlamaModule();
+      const registered = await native.isBackendRegistered();
+      this.registered = registered;
+      return registered;
+    } catch {
+      return this.registered;
+    }
+  }
 }

package/src/index.ts

@@ -1,32 +1,40 @@
 /**
  * @runanywhere/llamacpp - LlamaCPP Backend for RunAnywhere React Native SDK
  *
- * This package provides the LlamaCPP backend for on-device LLM inference.
- * It supports GGUF models and provides the same API as the iOS SDK.
+ * This package registers the LlamaCPP native providers. Public model
+ * lifecycle, generation, VLM, structured-output, and LoRA APIs live in
+ * @runanywhere/core.
  *
  * ## Usage
  *
  * ```typescript
  * import { RunAnywhere } from '@runanywhere/core';
- * import { LlamaCPP, LlamaCppProvider } from '@runanywhere/llamacpp';
+ * import { InferenceFramework, ModelCategory } from '@runanywhere/proto-ts/model_types';
+ * import { ModelLoadRequest } from '@runanywhere/proto-ts/model_types';
+ * import { LlamaCPP } from '@runanywhere/llamacpp';
  *
  * // Initialize core SDK
  * await RunAnywhere.initialize({ apiKey: 'your-key' });
  *
- * // Register LlamaCPP backend (calls native rac_backend_llamacpp_register)
- * await LlamaCppProvider.register();
+ * // Register LlamaCPP backend providers
+ * await LlamaCPP.register();
  *
- * // Add a model
- * LlamaCPP.addModel({
+ * // Register models via RunAnywhere (matching iOS pattern)
+ * await RunAnywhere.registerModel({
  *   id: 'smollm2-360m-q8_0',
  *   name: 'SmolLM2 360M Q8_0',
  *   url: 'https://huggingface.co/.../SmolLM2-360M.Q8_0.gguf',
+ *   framework: InferenceFramework.INFERENCE_FRAMEWORK_LLAMA_CPP,
  *   memoryRequirement: 500_000_000
  * });
  *
  * // Download and use
- * await RunAnywhere.downloadModel('smollm2-360m-q8_0');
- * await RunAnywhere.loadModel('smollm2-360m-q8_0');
+ * const download = RunAnywhere.downloadModel('smollm2-360m-q8_0')[Symbol.asyncIterator]();
+ * while (!(await download.next()).done) {}
+ * await RunAnywhere.loadModel(ModelLoadRequest.fromPartial({
+ *   modelId: 'smollm2-360m-q8_0',
+ *   category: ModelCategory.MODEL_CATEGORY_LANGUAGE,
+ * }));
  * const result = await RunAnywhere.generate('Hello, world!');
  * ```
  *
@@ -37,20 +45,7 @@
 // Main API
 // =============================================================================
 
-export { LlamaCPP, type LlamaCPPModelOptions } from './LlamaCPP';
-export { LlamaCppProvider, autoRegister } from './LlamaCppProvider';
-
-// =============================================================================
-// Native Module
-// =============================================================================
-
-export {
-  NativeRunAnywhereLlama,
-  getNativeLlamaModule,
-  requireNativeLlamaModule,
-  isNativeLlamaModuleAvailable,
-} from './native/NativeRunAnywhereLlama';
-export type { NativeRunAnywhereLlamaModule } from './native/NativeRunAnywhereLlama';
+export { LlamaCPP } from './LlamaCPP';
 
 // =============================================================================
 // Nitrogen Spec Types

package/src/native/NativeRunAnywhereLlama.ts

@@ -2,11 +2,16 @@
  * NativeRunAnywhereLlama.ts
  *
  * Exports the native RunAnywhereLlama Hybrid Object from Nitro Modules.
- * This module provides Llama-based text generation capabilities.
+ * This module provides LlamaCPP backend registration hooks.
  */
 
-import { NitroModules } from 'react-native-nitro-modules';
 import type { RunAnywhereLlama } from '../specs/RunAnywhereLlama.nitro';
+import { getNitroModulesProxySync, type NitroProxy } from '@runanywhere/core/internal';
+
+// Use the global NitroModules initialization
+function getNitroModulesProxy(): NitroProxy | null {
+  return getNitroModulesProxySync();
+}
 
 /**
  * The native RunAnywhereLlama module type
@@ -17,15 +22,24 @@ export type NativeRunAnywhereLlamaModule = RunAnywhereLlama;
  * Get the native RunAnywhereLlama Hybrid Object
  */
 export function requireNativeLlamaModule(): NativeRunAnywhereLlamaModule {
-  return NitroModules.createHybridObject<RunAnywhereLlama>('RunAnywhereLlama');
+  const NitroProxy = getNitroModulesProxy();
+  if (!NitroProxy) {
+    throw new Error(
+      'NitroModules is not available. This can happen in Bridgeless mode if ' +
+      'react-native-nitro-modules is not properly linked.'
+    );
+  }
+  return NitroProxy.createHybridObject('RunAnywhereLlama') as RunAnywhereLlama;
 }
 
 /**
- * Check if the native Llama module is available
+ * Check if the native Llama module is available.
+ * Uses the singleton getter to avoid creating throwaway HybridObject instances
+ * whose C++ destructors could tear down shared bridge state.
  */
 export function isNativeLlamaModuleAvailable(): boolean {
   try {
-    requireNativeLlamaModule();
+    getNativeLlamaModule();
     return true;
   } catch {
     return false;

package/src/specs/RunAnywhereLlama.nitro.ts

@@ -1,35 +1,37 @@
 /**
  * RunAnywhereLlama Nitrogen Spec
  *
- * LlamaCPP backend interface for Llama-based text generation:
- * - Backend Registration
- * - Model Loading/Unloading
- * - Text Generation (non-streaming and streaming)
- * - Structured Output (JSON schema generation)
+ * LlamaCPP backend registration hooks.
  *
- * Matches Swift SDK: LlamaCPPRuntime/LlamaCPP.swift + CppBridge+LLM.swift
+ * Public lifecycle, generation, structured-output, LoRA, and VLM APIs live in
+ * @runanywhere/core and route through commons proto/lifecycle bridges. This
+ * backend package only registers native providers.
+ *
+ * NOTE: After editing this file, run `npx nitro-codegen` (or
+ * `yarn llamacpp:nitrogen`) to regenerate the bridge code under
+ * `nitrogen/generated/`. Those files are auto-generated and must not be
+ * hand-edited; until regeneration they may still reference the removed
+ * VLM register/unregister hooks.
  */
 import type { HybridObject } from 'react-native-nitro-modules';
 
 /**
- * Llama text generation native interface
+ * LlamaCPP native registration interface.
  *
- * This interface provides Llama-based LLM capabilities.
- * Requires @runanywhere/core to be initialized first.
+ * The single `registerBackend()` / `unregisterBackend()` pair covers both LLM
+ * and VLM modalities — the underlying C++ symbol `rac_backend_llamacpp_register()`
+ * was unified and the separate `rac_backend_llamacpp_vlm_register()` symbol no
+ * longer exists.
  */
 export interface RunAnywhereLlama
   extends HybridObject<{
     ios: 'c++';
     android: 'c++';
   }> {
-  // ============================================================================
-  // Backend Registration
-  // Matches Swift: LlamaCPP.register(), LlamaCPP.unregister()
-  // ============================================================================
-
   /**
    * Register the LlamaCPP backend with the C++ service registry.
-   * Calls rac_backend_llamacpp_register() from runanywhere-binaries.
+   * Calls rac_backend_llamacpp_register() from runanywhere-binaries; this
+   * single call covers both LLM and VLM modalities.
    * Safe to call multiple times - subsequent calls are no-ops.
    * @returns true if registered successfully (or already registered)
    */
@@ -46,115 +48,4 @@ export interface RunAnywhereLlama
    * @returns true if backend is registered
    */
   isBackendRegistered(): Promise<boolean>;
-
-  // ============================================================================
-  // Model Loading
-  // Matches Swift: CppBridge+LLM.swift loadTextModel/unloadTextModel
-  // ============================================================================
-
-  /**
-   * Load a Llama model for text generation
-   * @param path Path to the model file (.gguf)
-   * @param modelId Optional unique identifier for the model
-   * @param modelName Optional human-readable name for the model
-   * @param configJson Optional JSON configuration (context_length, gpu_layers, etc.)
-   * @returns true if loaded successfully
-   */
-  loadModel(
-    path: string,
-    modelId?: string,
-    modelName?: string,
-    configJson?: string
-  ): Promise<boolean>;
-
-  /**
-   * Check if a Llama model is loaded
-   */
-  isModelLoaded(): Promise<boolean>;
-
-  /**
-   * Unload the current Llama model
-   */
-  unloadModel(): Promise<boolean>;
-
-  /**
-   * Get info about the currently loaded model
-   * @returns JSON with model info or empty if not loaded
-   */
-  getModelInfo(): Promise<string>;
-
-  // ============================================================================
-  // Text Generation
-  // Matches Swift: RunAnywhere+TextGeneration.swift
-  // ============================================================================
-
-  /**
-   * Generate text (non-streaming)
-   * @param prompt The prompt text
-   * @param optionsJson JSON string with generation options:
-   *   - max_tokens: Maximum tokens to generate (default: 512)
-   *   - temperature: Sampling temperature (default: 0.7)
-   *   - top_p: Nucleus sampling parameter (default: 0.9)
-   *   - top_k: Top-k sampling parameter (default: 40)
-   *   - system_prompt: Optional system prompt
-   * @returns JSON string with generation result:
-   *   - text: Generated text
-   *   - tokensUsed: Number of tokens generated
-   *   - latencyMs: Generation time in milliseconds
-   *   - cancelled: Whether generation was cancelled
-   */
-  generate(prompt: string, optionsJson?: string): Promise<string>;
-
-  /**
-   * Generate text with streaming callback
-   * @param prompt The prompt text
-   * @param optionsJson JSON string with generation options
-   * @param callback Called for each token with (token, isComplete)
-   * @returns Complete generated text
-   */
-  generateStream(
-    prompt: string,
-    optionsJson: string,
-    callback: (token: string, isComplete: boolean) => void
-  ): Promise<string>;
-
-  /**
-   * Cancel ongoing text generation
-   * @returns true if cancellation was successful
-   */
-  cancelGeneration(): Promise<boolean>;
-
-  // ============================================================================
-  // Structured Output
-  // Matches Swift: RunAnywhere+StructuredOutput.swift
-  // ============================================================================
-
-  /**
-   * Generate structured output following a JSON schema
-   * Uses constrained generation to ensure output conforms to schema
-   * @param prompt The prompt text
-   * @param schema JSON schema string defining the output structure
-   * @param optionsJson Optional generation options
-   * @returns JSON string conforming to the provided schema
-   */
-  generateStructured(
-    prompt: string,
-    schema: string,
-    optionsJson?: string
-  ): Promise<string>;
-
-  // ============================================================================
-  // Utilities
-  // ============================================================================
-
-  /**
-   * Get the last error message from the Llama backend
-   */
-  getLastError(): Promise<string>;
-
-  /**
-   * Get current memory usage of the Llama backend
-   * @returns Memory usage in bytes
-   */
-  getMemoryUsage(): Promise<number>;
 }

package/android/src/main/AndroidManifest.xml

@@ -1,3 +0,0 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.margelo.nitro.runanywhere.llama">
-</manifest>

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

@@ -1,14 +0,0 @@
-/**
- * cpp-adapter.cpp
- *
- * Android JNI entry point for RunAnywhereLlama native module.
- * This file is required by React Native's CMake build system.
- */
-
-#include <jni.h>
-#include "runanywherellamaOnLoad.hpp"
-
-extern "C" JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void* reserved) {
-    // Initialize nitrogen module and register HybridObjects
-    return margelo::nitro::runanywhere::llama::initialize(vm);
-}