@micrantha/react-native-amaryllis 0.1.0

package/src/Amaryllis.ts

@@ -0,0 +1,91 @@
+import type {
+  LlmEngine,
+  LlmEngineConfig,
+  LlmSessionParams,
+  LlmCallbacks,
+  LlmRequestParams,
+  LlmEventEmitter,
+  LlmEventSubscription,
+  LlmPipeParams,
+  LlmNativeEngine,
+} from './Types';
+
+const EVENT_ON_PARTIAL_RESULT = 'onPartialResult';
+const EVENT_ON_FINAL_RESULT = 'onFinalResult';
+const EVENT_ON_ERROR = 'onError';
+
+export class LlmPipe implements LlmEngine {
+  subscriptions: LlmEventSubscription[] = [];
+  llmEmitter: LlmEventEmitter;
+  llmNative: LlmNativeEngine;
+
+  constructor(params: LlmPipeParams) {
+    this.llmNative = params.nativeModule;
+    this.llmEmitter = params.eventEmitter;
+  }
+
+  async init(params: LlmEngineConfig): Promise<void> {
+    await this.llmNative.init(params);
+  }
+
+  newSession(params: LlmSessionParams): Promise<void> {
+    return this.llmNative.newSession(params);
+  }
+
+  async generate(params: LlmRequestParams): Promise<string> {
+    return await this.llmNative.generate(params);
+  }
+
+  async generateAsync(
+    params: LlmRequestParams,
+    callbacks?: LlmCallbacks
+  ): Promise<void> {
+    if (callbacks) {
+      this.setupAsyncCallbacks(callbacks);
+    }
+
+    return await this.llmNative.generateAsync(params);
+  }
+
+  close(): void {
+    this.llmNative.close();
+    this.cancelAsync();
+  }
+
+  cancelAsync(): void {
+    this.llmNative.cancelAsync();
+    this.subscriptions.forEach((sub) => sub.remove());
+  }
+
+  setupAsyncCallbacks(callbacks: LlmCallbacks): void {
+    if (callbacks.onPartialResult) {
+      this.subscriptions.push(
+        this.llmEmitter.addListener(
+          EVENT_ON_PARTIAL_RESULT,
+          (result: string) => {
+            callbacks.onPartialResult?.(result);
+          }
+        )
+      );
+    }
+
+    if (callbacks.onFinalResult) {
+      this.subscriptions.push(
+        this.llmEmitter.addListener(EVENT_ON_FINAL_RESULT, (result: string) => {
+          callbacks.onFinalResult?.(result);
+          this.cancelAsync();
+        })
+      );
+    }
+    if (callbacks.onError) {
+      this.subscriptions.push(
+        this.llmEmitter.addListener(EVENT_ON_ERROR, (error: string) => {
+          callbacks.onError?.(new Error(error));
+          this.cancelAsync();
+        })
+      );
+    }
+  }
+}
+
+export default LlmPipe;

package/src/AmaryllisContext.tsx

@@ -0,0 +1,53 @@
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import type { LLMContextValue, LLMProviderProps } from './Types';
+import { newLlmPipe } from './NativePipe';
+
+const LLMContext = createContext<LLMContextValue>({
+  config: null,
+  controller: null,
+  error: undefined,
+  isReady: false,
+});
+
+export const useLLMContext = () => useContext(LLMContext);
+
+/**
+ * Provides LLM configuration state to child components.
+ * Configures LLM once on mount.
+ */
+export const LLMProvider = ({
+  config,
+  llmPipe,
+  children,
+}: LLMProviderProps) => {
+  const [error, setError] = useState<Error | undefined>();
+  const [ready, setReady] = useState(false);
+  const controller = useMemo(() => {
+    try {
+      return llmPipe ?? newLlmPipe();
+    } catch (e: any) {
+      setError(e);
+      return null;
+    }
+  }, [llmPipe]);
+
+  useEffect(() => {
+    const start = async () => {
+      try {
+        await controller?.init(config);
+        setReady(true);
+      } catch (e: any) {
+        console.error('unable to start amaryllis', e);
+        setError(e);
+      }
+    };
+    start();
+    return () => controller?.close();
+  }, [config, controller]);
+
+  return (
+    <LLMContext.Provider value={{ config, controller, isReady: ready, error }}>
+      {children}
+    </LLMContext.Provider>
+  );
+};

package/src/AmaryllisHooks.tsx

@@ -0,0 +1,78 @@
+import { useCallback, useMemo, useEffect } from 'react';
+import type { LlmRequestParams, InferenceProps } from './Types';
+import { useLLMContext } from './AmaryllisContext';
+import { createLLMObservable } from './AmaryllisRx';
+
+export const useInferenceAsync = (props: InferenceProps = {}) => {
+  const { controller } = useLLMContext();
+  const { onResult, onGenerate, onError, onComplete } = props;
+
+  const llm$ = useMemo(() => createLLMObservable(), []);
+
+  const generate = useCallback(
+    async (params: LlmRequestParams) => {
+      try {
+        onGenerate?.();
+        await controller?.generateAsync(params, llm$.callbacks);
+      } catch (err) {
+        onError?.(
+          err instanceof Error ? err : new Error('An unknown error occurred')
+        );
+      }
+      return () => {
+        controller?.cancelAsync();
+        onComplete?.();
+      };
+    },
+    [controller, llm$.callbacks, onComplete, onGenerate, onError]
+  );
+
+  useEffect(() => {
+    const sub = llm$.observable.subscribe({
+      next: ({ text, isFinal }) => {
+        onResult?.(text, isFinal);
+      },
+      complete: () => onComplete?.(),
+      error: (err) => onError?.(err),
+    });
+
+    return () => {
+      sub.unsubscribe();
+      controller?.cancelAsync();
+    };
+  }, [llm$.observable, controller, onResult, onComplete, onError]);
+  return generate;
+};
+
+export const useInference = (props: InferenceProps = {}) => {
+  const { controller, error: contextError } = useLLMContext();
+  const { onResult, onError, onGenerate, onComplete } = props;
+
+  useEffect(() => {
+    if (contextError) {
+      onError?.(contextError);
+    }
+  }, [contextError, onError]);
+
+  const generate = useCallback(
+    async (params: LlmRequestParams) => {
+      try {
+        onGenerate?.();
+        const response = await controller?.generate(params);
+        onResult?.(response ?? '', true);
+      } catch (err) {
+        onError?.(
+          err instanceof Error ? err : new Error('An unknown error occurred')
+        );
+      }
+
+      return () => {
+        controller?.cancelAsync();
+        onComplete?.();
+      };
+    },
+    [onGenerate, controller, onResult, onError, onComplete]
+  );
+
+  return generate;
+};

package/src/AmaryllisRx.ts

@@ -0,0 +1,24 @@
+import type { LlmCallbacks, LLMObservableResult, LLMResult } from './Types';
+import { Observable, Subscriber } from 'rxjs';
+
+export function createLLMObservable(): LLMObservableResult {
+  let subscriber: Subscriber<LLMResult>;
+
+  const observable = new Observable<LLMResult>((sub) => {
+    subscriber = sub;
+  });
+
+  const callbacks: LlmCallbacks = {
+    onPartialResult: (partial) => {
+      subscriber?.next({ text: partial, isFinal: false });
+    },
+    onFinalResult: (final) => {
+      subscriber?.next({ text: final, isFinal: true });
+    },
+    onError: (error) => {
+      subscriber?.error(error);
+    },
+  };
+
+  return { observable, callbacks };
+}

package/src/NativeAmaryllis.ts

@@ -0,0 +1,18 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  init(params: Object): Promise<void>;
+
+  newSession(params: Object): Promise<void>;
+
+  generate(params: Object): Promise<string>;
+
+  generateAsync(params: Object): Promise<void>;
+
+  close(): void;
+
+  cancelAsync(): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('Amaryllis');

package/src/NativePipe.ts

@@ -0,0 +1,8 @@
+import { NativeModules, NativeEventEmitter } from 'react-native';
+import { LlmPipe } from './Amaryllis';
+
+export const newLlmPipe = () =>
+  new LlmPipe({
+    nativeModule: NativeModules.Amaryllis,
+    eventEmitter: new NativeEventEmitter(),
+  });

package/src/Types.ts

@@ -0,0 +1,115 @@
+import type { Spec } from './NativeAmaryllis';
+import type { Observable } from 'rxjs';
+
+export type LlmNativeEngine = Spec;
+
+export type LlmCallbacks = {
+  // Async streaming callbacks
+  onPartialResult?: (result: string) => void;
+  onFinalResult?: (result: string) => void;
+  onError?: (err: Error) => void;
+};
+
+// Core parameter object for configuration and request options
+export type LlmRequestParams = {
+  // Required
+  prompt: string;
+  // Multimodal support
+  images?: string[];
+};
+
+export type LlmSessionParams = {
+  // Optional generation settings
+  topK?: number; // default: 40
+  topP?: number; // default: 0.95
+  temperature?: number; // default: 0.8
+  randomSeed?: number; // default: 0
+  loraPath?: string; // LoRA customization (GPU only)
+  enableVisionModality?: boolean;
+};
+
+// Initialization/configuration for the engine
+export type LlmEngineConfig = {
+  modelPath: string; // Required: .task model path on device
+  maxTopK?: number; // default: 64 (for session initialization)
+  maxNumImages?: number; // default: 1
+  maxTokens?: number; // default: 512
+  visionEncoderPath?: string; // Optional: vision encoder model path for multimodal
+  visionAdapterPath?: string; // Optional: vision adapter model path for multimodal
+};
+
+// Unified LLM interface
+export type LlmEngine = {
+  /**
+   * Initialize the engine (creates LlmInference and LlmInferenceSession internally).
+   */
+  init(config: LlmEngineConfig): Promise<void>;
+
+  /**
+   * Start a new session.
+   */
+  newSession(params: LlmSessionParams): Promise<void>;
+
+  /**
+   * Generate a response synchronously (blocking).
+   */
+  generate(params: LlmRequestParams): Promise<string>;
+
+  /**
+   * Generate a response asynchronously (streaming).
+   */
+  generateAsync(
+    params: LlmRequestParams,
+    callbacks?: LlmCallbacks
+  ): Promise<void>;
+
+  /**
+   * Clean up resources.
+   */
+  close(): void;
+
+  cancelAsync(): void;
+};
+
+export interface LlmEventSubscription {
+  remove: () => void;
+}
+
+export interface LlmEventEmitter {
+  addListener(event: string, cb: (result: any) => void): LlmEventSubscription;
+}
+
+export interface LlmPipeParams {
+  nativeModule: LlmNativeEngine;
+  eventEmitter: LlmEventEmitter;
+}
+
+export interface LLMContextValue {
+  config: LlmEngineConfig | null;
+  controller: LlmEngine | null;
+  error: Error | undefined;
+  isReady: boolean;
+}
+
+export interface LLMProviderProps {
+  config: LlmEngineConfig;
+  llmPipe?: LlmEngine;
+  children: React.ReactNode;
+}
+
+export type InferenceProps = {
+  onGenerate?: () => void;
+  onResult?: (result: string, isFinal: boolean) => void;
+  onError?: (error: Error) => void;
+  onComplete?: () => void;
+};
+
+export interface LLMResult {
+  text: string;
+  isFinal: boolean;
+}
+
+export interface LLMObservableResult {
+  callbacks: LlmCallbacks;
+  observable: Observable<LLMResult>;
+}

package/src/index.tsx

@@ -0,0 +1,5 @@
+export { default as Amaryllis, LlmPipe } from './Amaryllis';
+export * from './AmaryllisHooks';
+export * from './AmaryllisContext';
+export * from './AmaryllisRx';
+export type * from './Types';