@micrantha/react-native-amaryllis 0.1.0

package/Amaryllis.podspec

@@ -0,0 +1,22 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "Amaryllis"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/hackelia-micrantha/react-native-amaryllis.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,cpp}"
+  s.private_header_files = "ios/**/*.h"
+   
+  s.dependency "MediaPipeTasksGenAI"
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Micrantha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# react-native-amaryllis
+
+![amaryllis](docs/amaryllis-128.png)
+
+[![npm version](https://img.shields.io/npm/v/react-native-amaryllis.svg)](https://www.npmjs.com/package/react-native-amaryllis) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> **Amaryllis Hippeastrum**: Symbolizes hope and emergence, blooming even in tough conditions.
+
+A modern AI module for native mobile apps in React Native, supporting multimodal inference and streaming results.
+
+---
+
+## 🚀 Installation
+
+```sh
+npm install react-native-amaryllis
+# or
+yarn add react-native-amaryllis
+# or
+pnpm add react-native-amaryllis
+```
+
+---
+
+## 📦 Features
+
+- Native LLM engine for Android & iOS
+- Multimodal support (text + images)
+- Streaming inference with hooks & observables
+- Easy integration with React Native context/provider
+- LoRA customization (GPU only)
+
+---
+
+## 🛠️ Usage
+
+### Provider Setup
+
+Wrap your application with `LLMProvider` and provide the necessary model paths. The models should be downloaded to the device.
+
+```tsx
+import { LLMProvider } from 'react-native-amaryllis';
+
+<LLMProvider
+  config={{
+    modelPath: 'gemma3-1b-it-int4.task',
+    visionEncoderPath: 'mobilenet_v3_small.tflite',
+    visionAdapterPath: 'mobilenet_v3_small.tflite',
+    maxTopK: 32,
+    maxNumImages: 2,
+    maxTokens: 512,
+  }}
+>
+  {/* Your app components */}
+</LLMProvider>
+```
+
+You can access the LLM controller with a `useLLMContext` hook. See **Core API** for details on the controller API.
+
+```tsx
+const {
+  config, // original config param
+  controller, // native controller
+  error, // any error
+  isReady, // is controller initialized
+} = useLLMContext();
+```
+
+### Inference Hook
+
+Use the `useInference` hook to access the LLM's capabilities.
+
+```tsx
+import { useInferenceAsync } from 'react-native-amaryllis';
+import { useCallback, useState } from 'react';
+import { View, TextInput, Button, Text } from 'react-native';
+
+const LLMPrompt = () => {
+  const [prompt, setPrompt] = useState('');
+  const [results, setResults] = useState([]);
+  const [images, setImages] = useState([]);
+  const [error, setError] = useState(undefined);
+  const [isBusy, setIsBusy] = useState(false);
+
+  const props = useMemo(() => ({
+    onGenerate: () => {
+      setError(undefined);
+      setIsBusy(true);
+    },
+    onResult: (result, isFinal) => {
+      setResults((prev) => [...prev, result]);
+      if (isFinal) {
+        setIsBusy(false);
+      }
+    },
+    onError: (err) => setError(err)
+  }), [setError, setIsBusy, setResults])
+
+  const generate = useInferenceAsync(props);
+
+  const infer = useCallback(async () => {
+    await generate({ prompt, images });
+  }, [prompt, generate, images]);
+
+  return (
+    <View>
+      <TextInput
+        value={prompt}
+        onChangeText={setPrompt}
+        placeholder="Enter prompt..."
+      />
+      <Button title="Generate" onPress={infer} />
+      <Text>
+        {error ? error.message : results.join('\n')}
+      </Text>
+      {/* image controls */}
+    </View>
+  );
+};
+```
+
+Substitute the `useInferenceAsync` hook to stream the results.
+
+### Core API
+
+For more advanced use cases, you can use the core `Amaryllis` API directly.
+This is the same controller passed from `useLLMContext`.
+
+#### Initialization
+
+```javascript
+import { Amaryllis } from 'react-native-amaryllis';
+
+const amaryllis = new Amaryllis();
+
+await amaryllis.init({
+  modelPath: '/path/to/your/model.task',
+  visionEncoderPath: '/path/to/vision/encoder.tflite',
+  visionAdapterPath: '/path/to/vision/adapter.tflite',
+});
+```
+
+A session is required for working with images.
+
+```javascript
+await amaryllis.newSession({
+  topK: 40, // only top results
+  topP: 0.95, // only top percentage match
+  temperature: 0.8,
+  randomSeed: 0, // for reproducing
+  loraPath: "", // LoRA customization (GPU only)
+  enableVisionModality: true // for vision
+})
+```
+
+#### Generate Response
+
+```javascript
+const result = await amaryllis.generate({
+  prompt: 'Your prompt here',
+  images: ['file:///path/to/image.png'],
+});
+```
+
+#### Streaming Response
+
+```javascript
+amaryllis.generateAsync(
+  {
+    prompt: 'Your prompt here',
+    images: ['file:///path/to/image.png'],
+  },
+  {
+    onPartialResult: (partial) => {
+      console.log('Partial result:', partial);
+    },
+    onFinalResult: (final) => {
+      console.log('Final result:', final);
+    },
+    onError: (err) => {
+      console.error('Error:', err);
+    },
+  }
+);
+```
+
+You can cancel an async generate if needed.
+
+```javascript
+amaryllis.cancelAsync();
+```
+
+---
+
+## 📚 Documentation
+
+- [API Reference](src/Types.ts)
+- [Example App](example/)
+- [Demo Video](docs/demo.mp4)
+- [Development workflow](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## 📄 License
+
+This project is [MIT licensed](LICENSE).

package/android/build.gradle

@@ -0,0 +1,81 @@
+buildscript {
+  ext {
+    getExtOrDefault = {name ->
+      return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['Amaryllis_' + name]
+    }
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.12.1"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["Amaryllis_" + name]).toInteger()
+}
+
+android {
+  namespace "com.micrantha.amaryllis"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+  implementation 'com.google.mediapipe:tasks-core:latest.release'
+  implementation 'com.google.mediapipe:tasks-genai:latest.release'
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+Amaryllis_kotlinVersion=2.2.10
+Amaryllis_minSdkVersion=29
+Amaryllis_targetSdkVersion=34
+Amaryllis_compileSdkVersion=35
+Amaryllis_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/micrantha/amaryllis/Amaryllis.kt

@@ -0,0 +1,198 @@
+package com.micrantha.amaryllis
+
+import android.content.Context
+import android.graphics.BitmapFactory
+import android.util.Log
+import androidx.core.graphics.scale
+import androidx.core.net.toFile
+import androidx.core.net.toUri
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.google.mediapipe.framework.image.BitmapImageBuilder
+import com.google.mediapipe.framework.image.MPImage
+import com.google.mediapipe.tasks.genai.llminference.GraphOptions
+import com.google.mediapipe.tasks.genai.llminference.LlmInference
+import com.google.mediapipe.tasks.genai.llminference.LlmInferenceSession
+import com.google.mediapipe.tasks.genai.llminference.ProgressListener
+import com.google.mediapipe.tasks.genai.llminference.VisionModelOptions
+import com.micrantha.amaryllis.AmaryllisModule.Companion.NAME
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_ENABLE_VISION
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_IMAGES
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_LORA_PATH
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_MAX_NUM_IMAGES
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_MAX_TOKENS
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_MAX_TOP_K
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_MODEL_PATH
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_PROMPT
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_RANDOM_SEED
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_TEMPERATURE
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_TOP_K
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_TOP_P
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_VISION_ADAPTER
+import com.micrantha.amaryllis.AmaryllisModule.Companion.PARAM_VISION_ENCODER
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+
+
+class Amaryllis {
+
+    private var llmInference: LlmInference? = null
+    private var session: LlmInferenceSession? = null
+
+    fun init(context: Context, config: ReadableMap) {
+        val modelPath = config.getString(PARAM_MODEL_PATH) ?: throw InvalidModelPathException()
+
+        val taskOptions = LlmInference.LlmInferenceOptions.builder()
+            .setModelPath(modelPath).apply {
+                if (config.hasKey(PARAM_MAX_TOP_K))
+                  setMaxTopK(config.getInt(PARAM_MAX_TOP_K))
+                if (config.hasKey(PARAM_MAX_TOKENS))
+                  setMaxTokens(config.getInt(PARAM_MAX_TOKENS))
+                if (config.hasKey(PARAM_MAX_NUM_IMAGES))
+                  setMaxNumImages(config.getInt(PARAM_MAX_NUM_IMAGES))
+            }
+            .setVisionModelOptions(
+                VisionModelOptions.builder().apply {
+                    config.getString(PARAM_VISION_ADAPTER)?.let {
+                        setAdapterPath(it)
+                    }
+                    config.getString(PARAM_VISION_ENCODER)?.let {
+                        setEncoderPath(it)
+                    }
+                }.build()
+            )
+            .build()
+
+        Log.d(NAME, "initializing llm inference")
+
+        this.llmInference = LlmInference.createFromOptions(context, taskOptions)
+    }
+
+    fun newSession(params: ReadableMap?) {
+        val inference = this.llmInference ?: throw NotInitializedException()
+
+        val sessionOptions = LlmInferenceSession.LlmInferenceSessionOptions.builder()
+
+        if (params?.hasKey(PARAM_TOP_K) == true)
+            sessionOptions.setTopK(params.getInt(PARAM_TOP_K))
+        if (params?.hasKey(PARAM_TOP_P) == true)
+            sessionOptions.setTopP(params.getDouble(PARAM_TOP_P).toFloat())
+        if (params?.hasKey(PARAM_TEMPERATURE) == true)
+            sessionOptions.setTemperature(params.getDouble(PARAM_TEMPERATURE).toFloat())
+        if (params?.hasKey(PARAM_RANDOM_SEED) == true)
+            sessionOptions.setRandomSeed(params.getInt(PARAM_RANDOM_SEED))
+        params?.getString(PARAM_LORA_PATH)?.let { sessionOptions.setLoraPath(it) }
+        params?.getBoolean(PARAM_ENABLE_VISION)?.let {
+            sessionOptions.setGraphOptions(
+                GraphOptions.builder()
+                    .setEnableVisionModality(it)
+                    .build()
+            )
+        }
+
+        Log.d(NAME, "starting new session")
+
+        this.session = LlmInferenceSession.createFromOptions(
+            inference,
+            sessionOptions.build()
+        )
+    }
+
+    fun generate(params: ReadableMap) {
+        val llm = llmInference ?: throw NotInitializedException()
+
+        val prompt = params.validateAndGetPrompt()
+
+        if (session == null) {
+            params.validateNoSession()
+            llm.generateResponse(prompt)
+        } else {
+            this.session?.updateQueryFromParams(params)
+            this.session?.generateResponse()
+        }
+    }
+
+    fun generateAsync(params: ReadableMap, listener: ProgressListener<String>) {
+        val llm = llmInference ?: throw NotInitializedException()
+
+        val prompt = params.validateAndGetPrompt()
+
+        if (session == null) {
+            params.validateNoSession()
+            llm.generateResponseAsync(prompt, listener)
+        } else {
+            this.session?.updateQueryFromParams(params)
+            this.session?.generateResponseAsync(listener)
+        }
+    }
+
+    fun close() {
+        session?.close()
+        llmInference?.close()
+        session = null
+        llmInference = null
+    }
+
+    fun cancelAsync() {
+        session?.cancelGenerateResponseAsync()
+    }
+
+    private fun LlmInferenceSession.updateQueryFromParams(params: ReadableMap): LlmInferenceSession {
+        addQueryChunk(params.getString(PARAM_PROMPT) ?: "")
+        params.getArray(PARAM_IMAGES)?.run {
+            preprocessImages(this).forEach {
+                addImage(it)
+            }
+        }
+        return this
+    }
+
+    private fun ReadableMap.validateNoSession() {
+        if (getArray(PARAM_IMAGES) != null) {
+            throw SessionRequiredException()
+        }
+    }
+
+    private fun ReadableMap.validateAndGetPrompt(): String {
+        return getString(PARAM_PROMPT) ?: throw IllegalArgumentException("prompt is required")
+    }
+
+    /**
+     * Loads and preprocesses an image for the LLM session.
+     * - Resizes to targetWidth x targetHeight (default 512x512)
+     * - Converts to MPImage for inference
+     */
+    internal fun preprocessImage(
+        uri: String,
+        targetWidth: Int = 512,
+        targetHeight: Int = 512
+    ): MPImage? {
+        val file = uri.toUri().toFile()
+
+        if (!file.exists()) return null
+
+        // Decode bitmap
+        val bitmap = BitmapFactory.decodeFile(file.absolutePath)
+            ?: return null
+
+        // Resize bitmap
+        val resized = bitmap.scale(targetWidth, targetHeight)
+
+        // Convert to MPImage
+        return BitmapImageBuilder(resized).build()
+    }
+
+    internal fun preprocessImages(
+        uris: ReadableArray,
+        targetWidth: Int = 512,
+        targetHeight: Int = 512
+    ) = uris.toArrayList().mapNotNull {
+        val uri = it as? String ?: return@mapNotNull null
+        preprocessImage(uri, targetWidth, targetHeight)
+    }
+
+    inner class NotInitializedException : Exception()
+    inner class SessionRequiredException : Exception()
+    inner class InvalidModelPathException : Exception()
+}