react-native-executorch 0.7.0-nightly-b4770df-20260205 → 0.7.0

package/src/hooks/natural_language_processing/useSpeechToText.ts

@@ -1,16 +1,24 @@
 import { useEffect, useCallback, useState } from 'react';
 import { SpeechToTextModule } from '../../modules/natural_language_processing/SpeechToTextModule';
-import { DecodingOptions, SpeechToTextModelConfig } from '../../types/stt';
+import {
+  DecodingOptions,
+  SpeechToTextType,
+  SpeechToTextProps,
+} from '../../types/stt';
 import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError, parseUnknownError } from '../../errors/errorUtils';
 
+/**
+ * React hook for managing a Speech to Text (STT) instance.
+ *
+ * @category Hooks
+ * @param speechToTextProps - Configuration object containing `model` source and optional `preventLoad` flag.
+ * @returns Ready to use Speech to Text model.
+ */
 export const useSpeechToText = ({
   model,
   preventLoad = false,
-}: {
-  model: SpeechToTextModelConfig;
-  preventLoad?: boolean;
-}) => {
+}: SpeechToTextProps): SpeechToTextType => {
   const [error, setError] = useState<null | RnExecutorchError>(null);
   const [isReady, setIsReady] = useState(false);
   const [isGenerating, setIsGenerating] = useState(false);

package/src/hooks/natural_language_processing/useTextEmbeddings.ts

@@ -1,16 +1,21 @@
 import { TextEmbeddingsModule } from '../../modules/natural_language_processing/TextEmbeddingsModule';
-import { ResourceSource } from '../../types/common';
 import { useModule } from '../useModule';
+import {
+  TextEmbeddingsType,
+  TextEmbeddingsProps,
+} from '../../types/textEmbeddings';
 
-interface Props {
-  model: {
-    modelSource: ResourceSource;
-    tokenizerSource: ResourceSource;
-  };
-  preventLoad?: boolean;
-}
-
-export const useTextEmbeddings = ({ model, preventLoad = false }: Props) =>
+/**
+ * React hook for managing a Text Embeddings model instance.
+ *
+ * @category Hooks
+ * @param TextEmbeddingsProps - Configuration object containing `model` source and optional `preventLoad` flag.
+ * @returns Ready to use Text Embeddings model.
+ */
+export const useTextEmbeddings = ({
+  model,
+  preventLoad = false,
+}: TextEmbeddingsProps): TextEmbeddingsType =>
   useModule({
     module: TextEmbeddingsModule,
     model,

package/src/hooks/natural_language_processing/useTextToSpeech.ts

@@ -1,22 +1,26 @@
 import { useCallback, useEffect, useState } from 'react';
 import { TextToSpeechModule } from '../../modules/natural_language_processing/TextToSpeechModule';
 import {
-  TextToSpeechConfig,
+  TextToSpeechProps,
   TextToSpeechInput,
+  TextToSpeechType,
   TextToSpeechStreamingInput,
 } from '../../types/tts';
 import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError, parseUnknownError } from '../../errors/errorUtils';
 
-interface Props extends TextToSpeechConfig {
-  preventLoad?: boolean;
-}
-
+/**
+ * React hook for managing Text to Speech instance.
+ *
+ * @category Hooks
+ * @param TextToSpeechProps - Configuration object containing `model` source, `voice` and optional `preventLoad`.
+ * @returns Ready to use Text to Speech model.
+ */
 export const useTextToSpeech = ({
   model,
   voice,
   preventLoad = false,
-}: Props) => {
+}: TextToSpeechProps): TextToSpeechType => {
   const [error, setError] = useState<RnExecutorchError | null>(null);
   const [isReady, setIsReady] = useState(false);
   const [isGenerating, setIsGenerating] = useState(false);

package/src/hooks/natural_language_processing/useTokenizer.ts

@@ -1,16 +1,20 @@
 import { useEffect, useState } from 'react';
 import { TokenizerModule } from '../../modules/natural_language_processing/TokenizerModule';
-import { ResourceSource } from '../../types/common';
 import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError, parseUnknownError } from '../../errors/errorUtils';
+import { TokenizerProps, TokenizerType } from '../../types/tokenizer';
 
+/**
+ * React hook for managing a Tokenizer instance.
+ *
+ * @category Hooks
+ * @param tokenizerProps - Configuration object containing `tokenizer` source and optional `preventLoad` flag.
+ * @returns Ready to use Tokenizer model.
+ */
 export const useTokenizer = ({
   tokenizer,
   preventLoad = false,
-}: {
-  tokenizer: { tokenizerSource: ResourceSource };
-  preventLoad?: boolean;
-}) => {
+}: TokenizerProps): TokenizerType => {
   const [error, setError] = useState<null | RnExecutorchError>(null);
   const [isReady, setIsReady] = useState(false);
   const [isGenerating, setIsGenerating] = useState(false);
@@ -36,7 +40,7 @@ export const useTokenizer = ({
   }, [tokenizerInstance, tokenizer.tokenizerSource, preventLoad]);
 
   const stateWrapper = <T extends (...args: any[]) => Promise<any>>(fn: T) => {
-    return (...args: Parameters<T>): Promise<ReturnType<T>> => {
+    return (...args: Parameters<T>): Promise<Awaited<ReturnType<T>>> => {
       if (!isReady)
         throw new RnExecutorchError(
           RnExecutorchErrorCode.ModuleNotLoaded,

package/src/hooks/natural_language_processing/useVAD.ts

@@ -1,13 +1,15 @@
-import { ResourceSource } from '../../types/common';
 import { useModule } from '../useModule';
 import { VADModule } from '../../modules/natural_language_processing/VADModule';
+import { VADType, VADProps } from '../../types/vad';
 
-interface Props {
-  model: { modelSource: ResourceSource };
-  preventLoad?: boolean;
-}
-
-export const useVAD = ({ model, preventLoad = false }: Props) =>
+/**
+ * React hook for managing a VAD model instance.
+ *
+ * @category Hooks
+ * @param VADProps - Configuration object containing `model` source and optional `preventLoad` flag.
+ * @returns Ready to use VAD model.
+ */
+export const useVAD = ({ model, preventLoad = false }: VADProps): VADType =>
   useModule({
     module: VADModule,
     model,

package/src/hooks/useModule.ts

@@ -74,9 +74,24 @@ export const useModule = <
   };
 
   return {
+    /**
+     * Contains the error message if the model failed to load.
+     */
     error,
+
+    /**
+     * Indicates whether the model is ready.
+     */
     isReady,
+
+    /**
+     * Indicates whether the model is currently generating a response.
+     */
     isGenerating,
+
+    /**
+     * Represents the download progress as a value between 0 and 1, indicating the extent of the model file retrieval.
+     */
     downloadProgress,
     forward,
   };

package/src/index.ts

@@ -104,6 +104,7 @@ export * from './modules/computer_vision/TextToImageModule';
 
 export * from './modules/natural_language_processing/LLMModule';
 export * from './modules/natural_language_processing/SpeechToTextModule';
+export * from './modules/natural_language_processing/TextToSpeechModule';
 export * from './modules/natural_language_processing/TextEmbeddingsModule';
 export * from './modules/natural_language_processing/TokenizerModule';
 export * from './modules/natural_language_processing/VADModule';
@@ -121,11 +122,15 @@ export * from './types/imageSegmentation';
 export * from './types/llm';
 export * from './types/vad';
 export * from './types/common';
-export {
-  SpeechToTextLanguage,
-  SpeechToTextModelConfig,
-  DecodingOptions,
-} from './types/stt';
+export * from './types/stt';
+export * from './types/textEmbeddings';
+export * from './types/tts';
+export * from './types/tokenizer';
+export * from './types/executorchModule';
+export * from './types/classification';
+export * from './types/imageEmbeddings';
+export * from './types/styleTransfer';
+export * from './types/tti';
 
 // constants
 export * from './constants/modelUrls';

package/src/modules/BaseModule.ts

@@ -2,6 +2,9 @@ import { ResourceSource } from '../types/common';
 import { TensorPtr } from '../types/common';
 
 export abstract class BaseModule {
+  /**
+   * Native module instance
+   */
   nativeModule: any = null;
 
   abstract load(
@@ -10,14 +13,31 @@ export abstract class BaseModule {
     ...args: any[]
   ): Promise<void>;
 
+  /**
+   * Runs the model's forward method with the given input tensors.
+   * It returns the output tensors that mimic the structure of output from ExecuTorch.
+   *
+   * @param inputTensor - Array of input tensors.
+   * @returns Array of output tensors.
+   */
   protected async forwardET(inputTensor: TensorPtr[]): Promise<TensorPtr[]> {
     return await this.nativeModule.forward(inputTensor);
   }
 
+  /**
+   * Gets the input shape for a given method and index.
+   *
+   * @param methodName method name
+   * @param index index of the argument which shape is requested
+   * @returns The input shape as an array of numbers.
+   */
   async getInputShape(methodName: string, index: number): Promise<number[]> {
     return this.nativeModule.getInputShape(methodName, index);
   }
 
+  /**
+   * Unloads the model from memory.
+   */
   delete() {
     if (this.nativeModule !== null) {
       this.nativeModule.unload();

package/src/modules/computer_vision/ClassificationModule.ts

@@ -4,7 +4,19 @@ import { BaseModule } from '../BaseModule';
 import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 
+/**
+ * Module for image classification tasks.
+ *
+ * @category Typescript API
+ */
 export class ClassificationModule extends BaseModule {
+  /**
+   * Loads the model, where `modelSource` is a string that specifies the location of the model binary.
+   * To track the download progress, supply a callback function `onDownloadProgressCallback`.
+   *
+   * @param model - Object containing `modelSource`.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: { modelSource: ResourceSource },
     onDownloadProgressCallback: (progress: number) => void = () => {}
@@ -22,7 +34,13 @@ export class ClassificationModule extends BaseModule {
     this.nativeModule = global.loadClassification(paths[0] || '');
   }
 
-  async forward(imageSource: string) {
+  /**
+   * Executes the model's forward pass, where `imageSource` can be a fetchable resource or a Base64-encoded string.
+   *
+   * @param imageSource - The image source to be classified.
+   * @returns The classification result.
+   */
+  async forward(imageSource: string): Promise<{ [category: string]: number }> {
     if (this.nativeModule == null)
       throw new RnExecutorchError(
         RnExecutorchErrorCode.ModuleNotLoaded,

package/src/modules/computer_vision/ImageEmbeddingsModule.ts

@@ -4,7 +4,18 @@ import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 import { BaseModule } from '../BaseModule';
 
+/**
+ * Module for generating image embeddings from input images.
+ *
+ * @category Typescript API
+ */
 export class ImageEmbeddingsModule extends BaseModule {
+  /**
+   * Loads the model, where `modelSource` is a string that specifies the location of the model binary.
+   *
+   * @param model - Object containing `modelSource`.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: { modelSource: ResourceSource },
     onDownloadProgressCallback: (progress: number) => void = () => {}
@@ -22,6 +33,12 @@ export class ImageEmbeddingsModule extends BaseModule {
     this.nativeModule = global.loadImageEmbeddings(paths[0] || '');
   }
 
+  /**
+   * Executes the model's forward pass. Returns an embedding array for a given sentence.
+   *
+   * @param imageSource - The image source (URI/URL) to image that will be embedded.
+   * @returns A Float32Array containing the image embeddings.
+   */
   async forward(imageSource: string): Promise<Float32Array> {
     if (this.nativeModule == null)
       throw new RnExecutorchError(

package/src/modules/computer_vision/ImageSegmentationModule.ts

@@ -5,7 +5,19 @@ import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 import { BaseModule } from '../BaseModule';
 
+/**
+ * Module for image segmentation tasks.
+ *
+ * @category Typescript API
+ */
 export class ImageSegmentationModule extends BaseModule {
+  /**
+   * Loads the model, where `modelSource` is a string that specifies the location of the model binary.
+   * To track the download progress, supply a callback function `onDownloadProgressCallback`.
+   *
+   * @param model - Object containing `modelSource`.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: { modelSource: ResourceSource },
     onDownloadProgressCallback: (progress: number) => void = () => {}
@@ -23,11 +35,19 @@ export class ImageSegmentationModule extends BaseModule {
     this.nativeModule = global.loadImageSegmentation(paths[0] || '');
   }
 
+  /**
+   * Executes the model's forward pass
+   *
+   * @param imageSource - a fetchable resource or a Base64-encoded string.
+   * @param classesOfInterest - an optional list of DeeplabLabel used to indicate additional arrays of probabilities to output (see section "Running the model"). The default is an empty list.
+   * @param resize - an optional boolean to indicate whether the output should be resized to the original image dimensions, or left in the size of the model (see section "Running the model"). The default is `false`.
+   * @returns A dictionary where keys are `DeeplabLabel` and values are arrays of probabilities for each pixel belonging to the corresponding class.
+   */
   async forward(
     imageSource: string,
     classesOfInterest?: DeeplabLabel[],
     resize?: boolean
-  ): Promise<{ [key in DeeplabLabel]?: number[] }> {
+  ): Promise<Partial<Record<DeeplabLabel, number[]>>> {
     if (this.nativeModule == null) {
       throw new RnExecutorchError(
         RnExecutorchErrorCode.ModuleNotLoaded,

package/src/modules/computer_vision/OCRModule.ts

@@ -1,7 +1,12 @@
 import { OCRController } from '../../controllers/OCRController';
 import { ResourceSource } from '../../types/common';
-import { OCRLanguage } from '../../types/ocr';
+import { OCRDetection, OCRLanguage } from '../../types/ocr';
 
+/**
+ * Module for Optical Character Recognition (OCR) tasks.
+ *
+ * @category Typescript API
+ */
 export class OCRModule {
   private controller: OCRController;
 
@@ -9,6 +14,14 @@ export class OCRModule {
     this.controller = new OCRController();
   }
 
+  /**
+   * Loads the model, where `detectorSource` is a string that specifies the location of the detector binary,
+   * `recognizerSource` is a string that specifies the location of the recognizer binary,
+   * and `language` is a parameter that specifies the language of the text to be recognized by the OCR.
+   *
+   * @param model - Object containing `detectorSource`, `recognizerSource`, and `language`.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: {
       detectorSource: ResourceSource;
@@ -25,10 +38,20 @@ export class OCRModule {
     );
   }
 
-  async forward(imageSource: string) {
+  /**
+   * Executes the model's forward pass, where `imageSource` can be a fetchable resource or a Base64-encoded string.
+   *
+   * @param imageSource - The image source to be processed.
+   * @returns The OCR result as a `OCRDetection[]`.
+   */
+  async forward(imageSource: string): Promise<OCRDetection[]> {
     return await this.controller.forward(imageSource);
   }
 
+  /**
+   * Release the memory held by the module. Calling `forward` afterwards is invalid.
+   * Note that you cannot delete model while it's generating.
+   */
   delete() {
     this.controller.delete();
   }

package/src/modules/computer_vision/ObjectDetectionModule.ts

@@ -5,7 +5,19 @@ import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 import { BaseModule } from '../BaseModule';
 
+/**
+ * Module for object detection tasks.
+ *
+ * @category Typescript API
+ */
 export class ObjectDetectionModule extends BaseModule {
+  /**
+   * Loads the model, where `modelSource` is a string that specifies the location of the model binary.
+   * To track the download progress, supply a callback function `onDownloadProgressCallback`.
+   *
+   * @param model - Object containing `modelSource`.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: { modelSource: ResourceSource },
     onDownloadProgressCallback: (progress: number) => void = () => {}
@@ -23,6 +35,14 @@ export class ObjectDetectionModule extends BaseModule {
     this.nativeModule = global.loadObjectDetection(paths[0] || '');
   }
 
+  /**
+   * Executes the model's forward pass, where `imageSource` can be a fetchable resource or a Base64-encoded string.
+   * `detectionThreshold` can be supplied to alter the sensitivity of the detection.
+   *
+   * @param imageSource - The image source to be processed.
+   * @param detectionThreshold - The threshold for detection sensitivity. Default is 0.7.
+   * @returns An array of Detection objects representing detected items in the image.
+   */
   async forward(
     imageSource: string,
     detectionThreshold: number = 0.7

package/src/modules/computer_vision/StyleTransferModule.ts

@@ -4,7 +4,19 @@ import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 import { BaseModule } from '../BaseModule';
 
+/**
+ * Module for style transfer tasks.
+ *
+ * @category Typescript API
+ */
 export class StyleTransferModule extends BaseModule {
+  /**
+   * Loads the model, where `modelSource` is a string that specifies the location of the model binary.
+   * To track the download progress, supply a callback function `onDownloadProgressCallback`.
+   *
+   * @param model - Object containing `modelSource`.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: { modelSource: ResourceSource },
     onDownloadProgressCallback: (progress: number) => void = () => {}
@@ -22,6 +34,12 @@ export class StyleTransferModule extends BaseModule {
     this.nativeModule = global.loadStyleTransfer(paths[0] || '');
   }
 
+  /**
+   * Executes the model's forward pass, where `imageSource` can be a fetchable resource or a Base64-encoded string.
+   *
+   * @param imageSource - The image source to be processed.
+   * @returns The stylized image as a Base64-encoded string.
+   */
   async forward(imageSource: string): Promise<string> {
     if (this.nativeModule == null)
       throw new RnExecutorchError(

package/src/modules/computer_vision/TextToImageModule.ts

@@ -6,9 +6,19 @@ import { PNG } from 'pngjs/browser';
 import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 
+/**
+ * Module for text-to-image generation tasks.
+ *
+ * @category Typescript API
+ */
 export class TextToImageModule extends BaseModule {
   private inferenceCallback: (stepIdx: number) => void;
 
+  /**
+   * Creates a new instance of `TextToImageModule` with optional callback on inference step.
+   *
+   * @param inferenceCallback - Optional callback function that receives the current step index during inference.
+   */
   constructor(inferenceCallback?: (stepIdx: number) => void) {
     super();
     this.inferenceCallback = (stepIdx: number) => {
@@ -16,6 +26,12 @@ export class TextToImageModule extends BaseModule {
     };
   }
 
+  /**
+   * Loads the model from specified resources.
+   *
+   * @param model - Object containing sources for tokenizer, scheduler, encoder, unet, and decoder.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: {
       tokenizerSource: ResourceSource;
@@ -71,6 +87,16 @@ export class TextToImageModule extends BaseModule {
     );
   }
 
+  /**
+   * Runs the model to generate an image described by `input`, and conditioned by `seed`, performing `numSteps` inference steps.
+   * The resulting image, with dimensions `imageSize`×`imageSize` pixels, is returned as a base64-encoded string.
+   *
+   * @param input - The text prompt to generate the image from.
+   * @param imageSize - The desired width and height of the output image in pixels.
+   * @param numSteps - The number of inference steps to perform.
+   * @param seed - An optional seed for random number generation to ensure reproducibility.
+   * @returns A Base64-encoded string representing the generated PNG image.
+   */
   async forward(
     input: string,
     imageSize: number = 512,
@@ -95,6 +121,9 @@ export class TextToImageModule extends BaseModule {
     return pngString;
   }
 
+  /**
+   * Interrupts model generation. The model is stopped in the nearest step.
+   */
   public interrupt(): void {
     this.nativeModule.interrupt();
   }

package/src/modules/computer_vision/VerticalOCRModule.ts

@@ -1,7 +1,12 @@
 import { VerticalOCRController } from '../../controllers/VerticalOCRController';
 import { ResourceSource } from '../../types/common';
-import { OCRLanguage } from '../../types/ocr';
+import { OCRDetection, OCRLanguage } from '../../types/ocr';
 
+/**
+ * Module for Vertical Optical Character Recognition (Vertical OCR) tasks.
+ *
+ * @category Typescript API
+ */
 export class VerticalOCRModule {
   private controller: VerticalOCRController;
 
@@ -9,6 +14,15 @@ export class VerticalOCRModule {
     this.controller = new VerticalOCRController();
   }
 
+  /**
+   * Loads the model, where `detectorSource` is a string that specifies the location of the detector binary,
+   * `recognizerSource` is a string that specifies the location of the recognizer binary,
+   * and `language` is a parameter that specifies the language of the text to be recognized by the OCR.
+   *
+   * @param model - Object containing `detectorSource`, `recognizerSource`, and `language`.
+   * @param independentCharacters - Whether to treat characters independently during recognition.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     model: {
       detectorSource: ResourceSource;
@@ -27,10 +41,20 @@ export class VerticalOCRModule {
     );
   }
 
-  async forward(imageSource: string) {
+  /**
+   * Executes the model's forward pass, where `imageSource` can be a fetchable resource or a Base64-encoded string.
+   *
+   * @param imageSource - The image source to be processed.
+   * @returns The OCR result as a `OCRDetection[]`.
+   */
+  async forward(imageSource: string): Promise<OCRDetection[]> {
     return await this.controller.forward(imageSource);
   }
 
+  /**
+   * Release the memory held by the module. Calling `forward` afterwards is invalid.
+   * Note that you cannot delete model while it's generating.
+   */
   delete() {
     this.controller.delete();
   }

package/src/modules/general/ExecutorchModule.ts

@@ -5,7 +5,19 @@ import { ResourceFetcher } from '../../utils/ResourceFetcher';
 import { RnExecutorchErrorCode } from '../../errors/ErrorCodes';
 import { RnExecutorchError } from '../../errors/errorUtils';
 
+/**
+ * General module for executing custom Executorch models.
+ *
+ * @category Typescript API
+ */
 export class ExecutorchModule extends BaseModule {
+  /**
+   * Loads the model, where `modelSource` is a string, number, or object that specifies the location of the model binary.
+   * Optionally accepts a download progress callback.
+   *
+   * @param modelSource - Source of the model to be loaded.
+   * @param onDownloadProgressCallback - Optional callback to monitor download progress.
+   */
   async load(
     modelSource: ResourceSource,
     onDownloadProgressCallback: (progress: number) => void = () => {}
@@ -23,6 +35,13 @@ export class ExecutorchModule extends BaseModule {
     this.nativeModule = global.loadExecutorchModule(paths[0] || '');
   }
 
+  /**
+   * Executes the model's forward pass, where input is an array of `TensorPtr` objects.
+   * If the inference is successful, an array of tensor pointers is returned.
+   *
+   * @param inputTensor - Array of input tensor pointers.
+   * @returns An array of output tensor pointers.
+   */
   async forward(inputTensor: TensorPtr[]): Promise<TensorPtr[]> {
     return await this.forwardET(inputTensor);
   }