react-native-ai-core 0.1.0

package/AiCore.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "AiCore"
+  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/albertofernandezroda/react-native-ai-core.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Alberto Fernandez
+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,273 @@
+# react-native-ai-core
+
+[![npm version](https://img.shields.io/npm/v/react-native-ai-core.svg)](https://www.npmjs.com/package/react-native-ai-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Platform: Android](https://img.shields.io/badge/Platform-Android-green.svg)](https://developer.android.com)
+[![New Architecture](https://img.shields.io/badge/New%20Architecture-TurboModule-blue.svg)](https://reactnative.dev/docs/the-new-architecture/landing-page)
+
+> **⚠️ Development in Progress** — This library is under active development. APIs may change between minor versions. Not recommended for production use yet.
+
+On-device LLM inference for React Native using **Gemini Nano** via Google's AI Edge SDKs. Runs entirely on-device — no internet connection required, full privacy.
+
+Supports two backends:
+- **ML Kit AICore** (`genai-prompt`) — hardware-accelerated via the device NPU (Pixel 9+, Android 14+)
+- **MediaPipe Tasks GenAI** — file-based inference using a local `.bin` model (any Android device with API ≥ 26)
+
+Built with TurboModules (New Architecture), JSI bridge, zero-overhead streaming via `NativeEventEmitter`.
+
+---
+
+## Requirements
+
+| | Minimum |
+|---|---|
+| React Native | 0.76+ (New Architecture) |
+| Android API | 26 (Android 8) |
+| Kotlin | 1.9+ |
+
+**For ML Kit AICore backend:** Pixel 9 or any device with `Feature.AI_CORE` support (Android 14+, NPU required).
+
+**For MediaPipe backend:** Any Android device API ≥ 26. Requires a downloaded Gemini Nano `.bin` model file on the device.
+
+---
+
+## Installation
+
+```sh
+npm install react-native-ai-core
+# or
+yarn add react-native-ai-core
+```
+
+### Android setup
+
+Add to `android/gradle.properties`:
+
+```properties
+minSdkVersion=26
+```
+
+No additional permissions are required. The native module is auto-linked.
+
+---
+
+## Quick Start
+
+```tsx
+import AICore from 'react-native-ai-core';
+
+// 1. Check availability
+const status = await AICore.checkAvailability();
+// 'AVAILABLE' | 'AVAILABLE_NPU' | 'NEED_DOWNLOAD' | 'UNSUPPORTED'
+
+// 2. Initialize the engine
+// Pass an empty string '' to use the ML Kit AICore backend (Pixel 9+).
+// Pass an absolute path to a .bin file to use the MediaPipe backend.
+await AICore.initialize(''); // AICore native (NPU)
+
+// 3. Generate a response
+const answer = await AICore.generateResponse('What is React Native?');
+console.log(answer);
+
+// 4. Release resources when done
+await AICore.release();
+```
+
+### Streaming
+
+```tsx
+const unsubscribe = AICore.generateResponseStream('Explain JSI in detail', {
+  onToken: (token, done) => {
+    process.stdout.write(token);
+    if (done) console.log('\n[stream ended]');
+  },
+  onComplete: () => console.log('Done!'),
+  onError: (err) => console.error(err.code, err.message),
+});
+
+// Cancel subscriptions when component unmounts
+return () => unsubscribe();
+```
+
+### Multi-turn conversation
+
+The native engine keeps a conversation history automatically. Each call to `generateResponse` / `generateResponseStream` includes previous turns as context.
+
+To start a fresh conversation without releasing the model:
+
+```tsx
+await AICore.resetConversation();
+```
+
+---
+
+## API Reference
+
+### `initialize(modelPath: string): Promise<boolean>`
+
+Initializes the inference engine.
+
+| Argument | Type | Description |
+|---|---|---|
+| `modelPath` | `string` | Pass `''` to use ML Kit AICore (native NPU). Pass an absolute path to a `.bin` file to use MediaPipe. |
+
+Returns `true` on success. Throws on failure.
+
+**Error codes:**
+- `MODEL_NOT_FOUND` — file at `modelPath` does not exist
+- `NPU_UNSUPPORTED` — device NPU is not compatible
+- `INIT_FAILED` — engine failed to start
+
+---
+
+### `generateResponse(prompt: string): Promise<string>`
+
+Generates a complete response synchronously (waits for the full output).
+
+```tsx
+const response = await AICore.generateResponse('Tell me a joke');
+```
+
+**Error codes:**
+- `NOT_INITIALIZED` — `initialize()` was not called first
+- `GENERATION_ERROR` — model failed during inference
+
+---
+
+### `generateResponseStream(prompt: string, callbacks: StreamCallbacks): () => void`
+
+Generates a response token by token via streaming. Returns a cleanup function to remove event listeners.
+
+```tsx
+const StreamCallbacks = {
+  onToken:    (token: string, done: boolean) => void,
+  onComplete: () => void,
+  onError:    (error: AIError) => void,
+}
+```
+
+Events are delivered through `NativeEventEmitter`:
+- `AICore_streamToken` → `{ token: string, done: boolean }`
+- `AICore_streamComplete` → `{}`
+- `AICore_streamError` → `{ code: string, message: string }`
+
+---
+
+### `checkAvailability(): Promise<AvailabilityStatus>`
+
+Returns the current availability status of Gemini Nano on this device.
+
+| Value | Meaning |
+|---|---|
+| `'AVAILABLE'` | Model is ready to use (file-based) |
+| `'AVAILABLE_NPU'` | Model is ready and hardware-accelerated (AICore) |
+| `'NEED_DOWNLOAD'` | Device is compatible but model needs to be downloaded |
+| `'UNSUPPORTED'` | Device does not meet minimum requirements |
+
+---
+
+### `release(): Promise<void>`
+
+Releases the model from NPU/CPU memory. Call this in your cleanup effect.
+
+```tsx
+useEffect(() => {
+  AICore.initialize('');
+  return () => { AICore.release(); };
+}, []);
+```
+
+---
+
+### `resetConversation(): Promise<void>`
+
+Clears the conversation history in the native engine without releasing the model. The next call to `generateResponse` will start a new conversation.
+
+---
+
+## Types
+
+```typescript
+export type AvailabilityStatus =
+  | 'AVAILABLE'
+  | 'AVAILABLE_NPU'
+  | 'NEED_DOWNLOAD'
+  | 'UNSUPPORTED';
+
+export interface StreamCallbacks {
+  onToken:    (token: string, done: boolean) => void;
+  onComplete: () => void;
+  onError:    (error: AIError) => void;
+}
+
+export interface AIError {
+  code:    string;
+  message: string;
+}
+```
+
+---
+
+## `useAICore` Hook
+
+A ready-to-use React hook is available in the example app as a reference implementation. It handles:
+
+- Availability check on mount
+- Engine lifecycle (initialize / release)
+- Streaming with incremental message updates
+- Conversation history reset on clear
+- Error state management
+
+See [`example/src/hooks/useAICore.ts`](example/src/hooks/useAICore.ts).
+
+---
+
+## Backends
+
+### ML Kit AICore (native NPU)
+
+Used when `modelPath = ''`. Requires a Pixel 9 or compatible device with Android's [AICore](https://developer.android.com/ml/gemini-nano) feature. The model runs fully on the device NPU with no file management needed — Google handles the model download automatically via system updates.
+
+Dependency: `com.google.mlkit:genai-prompt:1.0.0-beta2`
+
+### MediaPipe Tasks GenAI (file-based)
+
+Used when `modelPath` points to a valid `.bin` file. Works on any Android device with API ≥ 26. You are responsible for placing the model file on the device (e.g., via `adb push` or a download manager).
+
+```sh
+adb push gemini-nano.bin /data/local/tmp/gemini-nano.bin
+```
+
+Dependency: `com.google.mediapipe:tasks-genai:0.10.22`
+
+---
+
+## Roadmap
+
+- [ ] iOS support (Core ML / Apple Neural Engine)
+- [ ] Automatic model download manager
+- [ ] Model quantization options
+- [ ] System prompt / persona configuration
+- [ ] Token count estimation
+- [ ] Abort/cancel streaming mid-generation
+- [ ] Web support (WebGPU / WASM)
+
+---
+
+## Contributing
+
+Contributions, issues and feature requests are welcome.
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+---
+
+## License
+
+MIT © [Alberto Fernandez](https://github.com/albertofernandezroda)
+
+---
+
+<sub>Built with [react-native-builder-bob](https://github.com/callstack/react-native-builder-bob)</sub>

package/android/build.gradle

@@ -0,0 +1,76 @@
+buildscript {
+  ext.AiCore = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 26,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return AiCore[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // 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"
+
+android {
+  namespace "com.aicore"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+
+  // Google AI Edge — MediaPipe Tasks GenAI (modelo de archivo local)
+  implementation "com.google.mediapipe:tasks-genai:0.10.22"
+
+  // ML Kit GenAI Prompt API — accede a Gemini Nano vía AICore (Pixel 8+, sin archivo)
+  implementation "com.google.mlkit:genai-prompt:1.0.0-beta2"
+
+  // Coroutines (requerido por ML Kit Flow API)
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
+}

package/android/src/main/AndroidManifest.xml

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