react-native-executorch 0.4.9 → 0.5.0-nightly-6f4dd53-20251211

package/third-party/include/executorch/ExecuTorch.h

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "ExecuTorchError.h"
+#import "ExecuTorchLog.h"
+#import "ExecuTorchModule.h"
+#import "ExecuTorchTensor.h"
+#import "ExecuTorchValue.h"

package/third-party/include/executorch/ExecuTorchError.h

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+FOUNDATION_EXPORT NSErrorDomain const
+    ExecuTorchErrorDomain NS_SWIFT_NAME(ErrorDomain);
+
+/**
+ * Enum to define the error codes.
+ * Values can be a subset, but must numerically match exactly those defined in
+ * runtime/core/error.h
+ */
+typedef NS_ERROR_ENUM(ExecuTorchErrorDomain, ExecuTorchErrorCode){
+    // System errors.
+    ExecuTorchErrorCodeOk = 0,
+    ExecuTorchErrorCodeInternal = 1,
+    ExecuTorchErrorCodeInvalidState = 2,
+    ExecuTorchErrorCodeEndOfMethod = 3,
+
+    // Logical errors.
+    ExecuTorchErrorCodeNotSupported = 16,
+    ExecuTorchErrorCodeNotImplemented = 17,
+    ExecuTorchErrorCodeInvalidArgument = 18,
+    ExecuTorchErrorCodeInvalidType = 19,
+    ExecuTorchErrorCodeOperatorMissing = 20,
+
+    // Registration errors.
+    ExecuTorchErrorCodeRegistrationExceedingMaxKernels = 21,
+    ExecuTorchErrorCodeRegistrationAlreadyRegistered = 22,
+
+    // Resource errors.
+    ExecuTorchErrorCodeNotFound = 32,
+    ExecuTorchErrorCodeMemoryAllocationFailed = 33,
+    ExecuTorchErrorCodeAccessFailed = 34,
+    ExecuTorchErrorCodeInvalidProgram = 35,
+    ExecuTorchErrorCodeInvalidExternalData = 36,
+    ExecuTorchErrorCodeOutOfResources = 37,
+
+    // Delegate errors.
+    ExecuTorchErrorCodeDelegateInvalidCompatibility = 48,
+    ExecuTorchErrorCodeDelegateMemoryAllocationFailed = 49,
+    ExecuTorchErrorCodeDelegateInvalidHandle = 50,
+} NS_SWIFT_NAME(ErrorCode);
+
+/**
+ * Returns a brief error description for the given error code.
+ *
+ * @param code An ExecuTorchErrorCode value representing the error code.
+ * @return An NSString containing the error description.
+ */
+FOUNDATION_EXPORT
+NS_RETURNS_RETAINED
+NSString *ExecuTorchErrorDescription(ExecuTorchErrorCode code)
+    NS_SWIFT_NAME(ErrorDescription(_:));
+
+/**
+ * Create an NSError in the ExecuTorch domain for the given code.
+ *
+ * @param code The ExecuTorchErrorCode to wrap.
+ * @return An NSError with ExecuTorchErrorDomain, the specified code, and a
+ * localized description.
+ */
+FOUNDATION_EXPORT
+NS_RETURNS_RETAINED
+NSError *ExecuTorchErrorWithCode(ExecuTorchErrorCode code)
+    NS_SWIFT_NAME(Error(code:));
+
+/**
+ * Create an NSError in the ExecuTorch domain for the given code.
+ *
+ * @param code The ExecuTorchErrorCode to wrap.
+ * @param description Additional error description.
+ * @return An NSError with ExecuTorchErrorDomain, the specified code, and a
+ * localized description.
+ */
+FOUNDATION_EXPORT
+NS_RETURNS_RETAINED
+NSError *ExecuTorchErrorWithCodeAndDescription(ExecuTorchErrorCode code,
+                                               NSString *__nullable description)
+    NS_SWIFT_NAME(Error(code:description:));
+
+NS_ASSUME_NONNULL_END

package/third-party/include/executorch/ExecuTorchLLM/ExecuTorchLLM.h

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "ExecuTorchLLMConfig.h"
+#import "ExecuTorchLLMError.h"
+#import "ExecuTorchLLMMultimodalRunner.h"
+#import "ExecuTorchLLMTextRunner.h"

package/third-party/include/executorch/ExecuTorchLLM/ExecuTorchLLMConfig.h

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ A configuration object for text generation.
+
+ This class wraps the underlying C++ GenerationConfig so that default
+ values and future fields remain a single source of truth in C++.
+*/
+NS_SWIFT_NAME(Config)
+__attribute__((deprecated("This API is experimental.")))
+__attribute__((objc_subclassing_restricted))
+@interface ExecuTorchLLMConfig : NSObject<NSCopying>
+
+/** Whether to echo the input prompt in the output. */
+@property(nonatomic, getter=isEchoEnabled) BOOL echoEnabled;
+
+/** Maximum number of new tokens to generate. */
+@property(nonatomic) NSInteger maximumNewTokens;
+
+/** Whether this is a warmup run. */
+@property(nonatomic, getter=isWarming) BOOL warming;
+
+/** Maximum total sequence length. */
+@property(nonatomic) NSInteger sequenceLength;
+
+/** Temperature for sampling. */
+@property(nonatomic) double temperature;
+
+/** Number of BOS tokens to add. */
+@property(nonatomic) NSInteger bosCount;
+
+/** Number of EOS tokens to add. */
+@property(nonatomic) NSInteger eosCount;
+
+/**
+ Initializes a configuration and invokes the block to mutate it.
+
+ @param block  A block that receives the newly initialized configuration.
+ @return An initialized ExecuTorchLLMConfig instance.
+*/
+- (instancetype)initWithBlock:(NS_NOESCAPE void (^)(ExecuTorchLLMConfig *))block
+    NS_SWIFT_NAME(init(_:));
+
+@end
+
+NS_ASSUME_NONNULL_END

package/third-party/include/executorch/ExecuTorchLLM/ExecuTorchLLMError.h

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+FOUNDATION_EXPORT NSErrorDomain const
+    ExecuTorchLLMErrorDomain NS_SWIFT_NAME(ErrorDomain);
+
+NS_ASSUME_NONNULL_END

package/third-party/include/executorch/ExecuTorchLLM/ExecuTorchLLMMultimodalRunner.h

@@ -0,0 +1,227 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "ExecuTorchLLMConfig.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ Types of multimodal inputs supported by the ExecuTorch LLM APIs.
+ Must be in sync with the C++ enum in llm/runner/multimodal_input.h
+*/
+typedef NS_ENUM(NSInteger, ExecuTorchLLMMultimodalInputType) {
+  ExecuTorchLLMMultimodalInputTypeText,
+  ExecuTorchLLMMultimodalInputTypeImage,
+  ExecuTorchLLMMultimodalInputTypeAudio,
+  ExecuTorchLLMMultimodalInputTypeUnsupported,
+} NS_SWIFT_NAME(MultimodalInputType);
+
+/**
+ A container for image inputs used with multimodal generation APIs.
+*/
+NS_SWIFT_NAME(Image)
+__attribute__((deprecated("This API is experimental.")))
+__attribute__((objc_subclassing_restricted))
+@interface ExecuTorchLLMImage : NSObject<NSCopying>
+
+/**
+ Initializes an image container with the provided data and dimensions.
+
+ @param data       Raw image bytes.
+ @param width      Image width in pixels.
+ @param height     Image height in pixels.
+ @param channels   Number of channels.
+ @return An initialized ExecuTorchLLMImage instance.
+*/
+- (instancetype)initWithData:(NSData *)data
+                       width:(NSInteger)width
+                      height:(NSInteger)height
+                    channels:(NSInteger)channels NS_DESIGNATED_INITIALIZER;
+
+- (instancetype)initWithFloatData:(NSData *)data
+                            width:(NSInteger)width
+                           height:(NSInteger)height
+                         channels:(NSInteger)channels NS_DESIGNATED_INITIALIZER;
+
+@property(nonatomic, readonly) NSData *data;
+
+@property(nonatomic, readonly) NSInteger width;
+
+@property(nonatomic, readonly) NSInteger height;
+
+@property(nonatomic, readonly) NSInteger channels;
+
+@property(nonatomic, readonly) BOOL isFloat;
+
++ (instancetype)new NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/**
+ A container for pre-processed audio features.
+*/
+NS_SWIFT_NAME(Audio)
+__attribute__((deprecated("This API is experimental.")))
+__attribute__((objc_subclassing_restricted))
+@interface ExecuTorchLLMAudio : NSObject<NSCopying>
+
+/**
+ Initializes an audio features container with the provided data and shape.
+
+ @param data        Feature buffer.
+ @param batchSize   Batch dimension size.
+ @param bins        Number of frequency bins.
+ @param frames      Number of time frames.
+ @return An initialized ExecuTorchLLMAudio instance.
+*/
+- (instancetype)initWithData:(NSData *)data
+                   batchSize:(NSInteger)batchSize
+                        bins:(NSInteger)bins
+                      frames:(NSInteger)frames NS_DESIGNATED_INITIALIZER;
+
+- (instancetype)initWithFloatData:(NSData *)data
+                        batchSize:(NSInteger)batchSize
+                             bins:(NSInteger)bins
+                           frames:(NSInteger)frames NS_DESIGNATED_INITIALIZER;
+
+@property(nonatomic, readonly) NSData *data;
+
+@property(nonatomic, readonly) NSInteger batchSize;
+
+@property(nonatomic, readonly) NSInteger bins;
+
+@property(nonatomic, readonly) NSInteger frames;
+
+@property(nonatomic, readonly) BOOL isFloat;
+
++ (instancetype)new NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/**
+ A tagged container for a single multimodal input item used by
+ multimodal generation APIs.
+*/
+NS_SWIFT_NAME(MultimodalInput)
+__attribute__((deprecated("This API is experimental.")))
+__attribute__((objc_subclassing_restricted))
+@interface ExecuTorchLLMMultimodalInput : NSObject<NSCopying>
+
+/**
+ Creates a text input.
+
+ @param text  The UTF-8 text to provide as input.
+ @return A retained ExecuTorchLLMMultimodalInput instance of type Text.
+*/
++ (instancetype)inputWithText:(NSString *)text
+    NS_SWIFT_NAME(init(_:)) NS_RETURNS_RETAINED;
+
+/**
+ Creates an image input.
+
+ @param image  The image payload to provide as input.
+ @return A retained ExecuTorchLLMMultimodalInput instance of type Image.
+*/
++ (instancetype)inputWithImage:(ExecuTorchLLMImage *)image
+    NS_SWIFT_NAME(init(_:)) NS_RETURNS_RETAINED;
+
+/**
+ Creates an audio-features input.
+
+ @param audio  The pre-processed audio features to provide as input.
+ @return A retained ExecuTorchLLMMultimodalInput instance of type Audio.
+*/
++ (instancetype)inputWithAudio:(ExecuTorchLLMAudio *)audio
+    NS_SWIFT_NAME(init(_:)) NS_RETURNS_RETAINED;
+
+@property(nonatomic, readonly) ExecuTorchLLMMultimodalInputType type;
+
+@property(nonatomic, readonly, nullable) NSString *text;
+
+@property(nonatomic, readonly, nullable) ExecuTorchLLMImage *image;
+
+@property(nonatomic, readonly, nullable) ExecuTorchLLMAudio *audio;
+
++ (instancetype)new NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/**
+ A wrapper class for the C++ llm::MultimodalRunner that provides
+ Objective-C APIs to load models, manage tokenization, accept mixed
+ input modalities, generate text sequences, and stop the runner.
+*/
+NS_SWIFT_NAME(MultimodalRunner)
+__attribute__((deprecated("This API is experimental.")))
+__attribute__((objc_subclassing_restricted))
+@interface ExecuTorchLLMMultimodalRunner : NSObject
+
+/**
+ Initializes a multimodal LLM runner with the given model and tokenizer paths.
+
+ @param modelPath      File system path to the serialized model.
+ @param tokenizerPath  File system path to the tokenizer data.
+ @return An initialized ExecuTorchLLMMultimodalRunner instance.
+*/
+- (instancetype)initWithModelPath:(NSString *)modelPath
+                    tokenizerPath:(NSString *)tokenizerPath
+    NS_DESIGNATED_INITIALIZER;
+
+/**
+ Checks whether the underlying model has been successfully loaded.
+
+ @return YES if the model is loaded, NO otherwise.
+*/
+- (BOOL)isLoaded;
+
+/**
+ Loads the model into memory, returning an error if loading fails.
+
+ @param error   On failure, populated with an NSError explaining the issue.
+ @return YES if loading succeeds, NO if an error occurred.
+*/
+- (BOOL)loadWithError:(NSError **)error;
+
+/**
+ Generates text given a list of multimodal inputs. A default configuration
+ is created and passed to the configuration block for in-place mutation.
+
+ The token callback, if provided, is invoked for each generated token.
+
+ @param inputs     An ordered array of multimodal inputs.
+ @param config     A configuration object.
+ @param callback   A block called with each generated token as an NSString.
+ @param error      On failure, populated with an NSError explaining the issue.
+ @return YES if generation completes successfully, NO if an error occurred.
+*/
+- (BOOL)generateWithInputs:(NSArray<ExecuTorchLLMMultimodalInput *> *)inputs
+                    config:(ExecuTorchLLMConfig *)config
+             tokenCallback:(nullable void (^)(NSString *))callback
+                     error:(NSError **)error
+    NS_SWIFT_NAME(generate(_:_:tokenCallback:));
+
+/**
+ Stop producing new tokens and terminate the current generation process.
+*/
+- (void)stop;
+
+/**
+ Remove the prefilled tokens from the KV cache and reset the start position
+ to 0. It also clears the stats for previous runs.
+*/
+- (void)reset;
+
++ (instancetype)new NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/third-party/include/executorch/ExecuTorchLLM/ExecuTorchLLMTextRunner.h

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "ExecuTorchLLMConfig.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ A wrapper class for the C++ llm::TextLLMRunner that provides
+ Objective-C APIs to load models, manage tokenization with custom
+ special tokens, generate text sequences, and stop the runner.
+*/
+NS_SWIFT_NAME(TextRunner)
+__attribute__((deprecated("This API is experimental.")))
+@interface ExecuTorchLLMTextRunner : NSObject
+
+/**
+ Initializes a text LLM runner with the given model and tokenizer paths,
+ and a list of special tokens to include in the tokenizer.
+
+ @param modelPath      File system path to the serialized model.
+ @param tokenizerPath  File system path to the tokenizer data.
+ @return An initialized ExecuTorchLLMTextRunner instance.
+*/
+- (instancetype)initWithModelPath:(NSString *)modelPath
+                    tokenizerPath:(NSString *)tokenizerPath;
+
+/**
+ Initializes a text LLM runner with the given model and tokenizer paths,
+ and a list of special tokens to include in the tokenizer.
+
+ @param modelPath      File system path to the serialized model.
+ @param tokenizerPath  File system path to the tokenizer data.
+ @param specialTokens  An array of NSString special tokens to use during
+ tokenization.
+ @return An initialized ExecuTorchLLMTextRunner instance.
+*/
+- (instancetype)initWithModelPath:(NSString *)modelPath
+                    tokenizerPath:(NSString *)tokenizerPath
+                    specialTokens:(NSArray<NSString *> *)specialTokens
+    NS_DESIGNATED_INITIALIZER;
+
+/**
+ Checks whether the underlying model has been successfully loaded.
+
+ @return YES if the model is loaded, NO otherwise.
+*/
+- (BOOL)isLoaded;
+
+/**
+ Loads the model into memory, returning an error if loading fails.
+
+ @param error   On failure, populated with an NSError explaining the issue.
+ @return YES if loading succeeds, NO if an error occurred.
+*/
+- (BOOL)loadWithError:(NSError **)error;
+
+/**
+ Generates text given an input prompt. A default configuration
+ is created and passed to the configuration block for in-place mutation.
+
+ The token callback, if provided, is invoked for each generated token.
+
+ @param prompt     The initial text prompt to generate from.
+ @param config     A configuration object.
+ @param callback   A block called with each generated token as an NSString.
+ @param error      On failure, populated with an NSError explaining the issue.
+ @return YES if generation completes successfully, NO if an error occurred.
+*/
+- (BOOL)generateWithPrompt:(NSString *)prompt
+                    config:(ExecuTorchLLMConfig *)config
+             tokenCallback:(nullable void (^)(NSString *token))callback
+                     error:(NSError **)error
+    NS_SWIFT_NAME(generate(_:_:tokenCallback:));
+
+/**
+ Stop producing new tokens and terminate the current generation process.
+*/
+- (void)stop;
+
+/**
+ Remove the prefilled tokens from the KV cache and reset the start position
+ to 0. It also clears the stats for previous runs.
+*/
+- (void)reset;
+
++ (instancetype)new NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/third-party/include/executorch/ExecuTorchLLM/module.modulemap

@@ -0,0 +1,4 @@
+module ExecuTorchLLM {
+  umbrella header "ExecuTorchLLM.h"
+  export *
+}

package/third-party/include/executorch/ExecuTorchLog.h

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Defines log levels with specific character codes representing each level.
+ */
+typedef NS_ENUM(NSInteger, ExecuTorchLogLevel) {
+  ExecuTorchLogLevelDebug = 'D',
+  ExecuTorchLogLevelInfo = 'I',
+  ExecuTorchLogLevelError = 'E',
+  ExecuTorchLogLevelFatal = 'F',
+  ExecuTorchLogLevelUnknown = '?'
+} NS_SWIFT_NAME(LogLevel);
+
+/**
+ * A protocol defining the requirements for a log sink to receive log messages.
+ */
+NS_SWIFT_NAME(LogSink)
+@protocol ExecuTorchLogSink
+
+/**
+ * Logs a message with the specified additional info.
+ *
+ * @param level The log level of the message.
+ * @param timestamp The timestamp of the log message since ExecuTorch PAL start.
+ * @param filename The name of the file generating the log message.
+ * @param line The line number in the file where the log message was generated.
+ * @param message The log message text.
+ */
+- (void)logWithLevel:(ExecuTorchLogLevel)level
+           timestamp:(NSTimeInterval)timestamp
+            filename:(NSString *)filename
+                line:(NSUInteger)line
+             message:(NSString *)message
+    NS_SWIFT_NAME(log(level:timestamp:filename:line:message:));
+
+@end
+
+/**
+ * A singleton class for managing log sinks and dispatching log messages.
+ */
+NS_SWIFT_NAME(Log)
+__attribute__((objc_subclassing_restricted))
+@interface ExecuTorchLog : NSObject
+
+/// The shared singleton log instance.
+@property(class, readonly) ExecuTorchLog *sharedLog;
+
+/**
+ * Adds a log sink to receive log messages.
+ *
+ * @param sink The log sink to add.
+ */
+- (void)addSink:(id<ExecuTorchLogSink>)sink NS_SWIFT_NAME(add(sink:));
+
+/**
+ * Removes a previously added log sink.
+ *
+ * @param sink The log sink to remove.
+ */
+- (void)removeSink:(id<ExecuTorchLogSink>)sink NS_SWIFT_NAME(remove(sink:));
+
++ (instancetype)new NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+NS_ASSUME_NONNULL_END