react-native-ai-core 0.1.0

package/lib/typescript/src/NativeAiCore.d.ts

@@ -0,0 +1,46 @@
+/**
+ * NativeAICore — TurboModule Spec (New Architecture)
+ *
+ * Puente JSI de alto rendimiento hacia el SDK de Google AI Edge (MediaPipe)
+ * para ejecutar Gemini Nano en local mediante la NPU del dispositivo.
+ */
+import { type TurboModule } from 'react-native';
+export interface Spec extends TurboModule {
+    /**
+     * Inicializa el motor de inferencia LLM con el modelo en `modelPath`.
+     * Devuelve `true` si la inicialización fue exitosa.
+     */
+    initialize(modelPath: string): Promise<boolean>;
+    /**
+     * Genera una respuesta completa para el prompt dado (no streaming).
+     */
+    generateResponse(prompt: string): Promise<string>;
+    /**
+     * Inicia la generación en modo streaming.
+     * Los tokens se emiten a través de eventos NativeEventEmitter:
+     *   - 'AICore_streamToken'   → { token: string, done: boolean }
+     *   - 'AICore_streamComplete' → {}
+     *   - 'AICore_streamError'   → { code: string, message: string }
+     */
+    generateResponseStream(prompt: string): void;
+    /**
+     * Comprueba la disponibilidad de Gemini Nano en el dispositivo.
+     * Retorna: 'AVAILABLE' | 'NEED_DOWNLOAD' | 'UNSUPPORTED'
+     */
+    checkAvailability(): Promise<string>;
+    /**
+     * Libera el modelo de la memoria de la NPU.
+     * Debe llamarse cuando el componente se desmonte para evitar fugas.
+     */
+    release(): Promise<void>;
+    /**
+     * Limpia el historial de conversación sin liberar el modelo.
+     * El próximo mensaje comenzará una conversación nueva.
+     */
+    resetConversation(): Promise<void>;
+    addListener(eventName: string): void;
+    removeListeners(count: number): void;
+}
+declare const _default: Spec;
+export default _default;
+//# sourceMappingURL=NativeAiCore.d.ts.map

package/lib/typescript/src/NativeAiCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeAiCore.d.ts","sourceRoot":"","sources":["../../../src/NativeAiCore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhD;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAErC;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;;OAGG;IACH,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAGnC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;;AAED,wBAAgE"}

package/lib/typescript/src/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * react-native-ai-core
+ *
+ * Capa de abstracción JS sobre el TurboModule nativo.
+ * Proporciona una API limpia y tipada para usar Gemini Nano
+ * en local a través del SDK de Google AI Edge (MediaPipe).
+ *
+ * @example
+ * import AICore from 'react-native-ai-core';
+ *
+ * await AICore.initialize('/data/local/tmp/gemini-nano.bin');
+ * const answer = await AICore.generateResponse('¿Qué es JSI?');
+ */
+/** Estado de disponibilidad de Gemini Nano en el dispositivo */
+export type AvailabilityStatus = 'AVAILABLE' | 'AVAILABLE_NPU' | 'NEED_DOWNLOAD' | 'UNSUPPORTED';
+/** Callbacks del streaming de respuesta */
+export interface StreamCallbacks {
+    /**
+     * Invocado por cada token recibido.
+     * @param token  Fragmento de texto parcial.
+     * @param done   `true` cuando el modelo ha terminado de generar.
+     */
+    onToken: (token: string, done: boolean) => void;
+    /** Invocado cuando la generación completa ha finalizado. */
+    onComplete: () => void;
+    /** Invocado si ocurre un error durante el streaming. */
+    onError: (error: AIError) => void;
+}
+/** Estructura de error normalizada */
+export interface AIError {
+    code: string;
+    message: string;
+}
+/**
+ * Inicializa el motor de inferencia LLM con el modelo indicado.
+ *
+ * @param modelPath  Ruta absoluta al archivo `.bin` del modelo en el dispositivo.
+ * @returns          `true` si la inicialización fue correcta.
+ *
+ * @throws `MODEL_NOT_FOUND`  si el archivo no existe en `modelPath`.
+ * @throws `NPU_UNSUPPORTED`  si la NPU del dispositivo no es compatible.
+ * @throws `INIT_FAILED`      si el motor no pudo arrancar por otro motivo.
+ *
+ * @example
+ * const ok = await initialize('/data/local/tmp/gemini-nano.bin');
+ */
+export declare function initialize(modelPath: string): Promise<boolean>;
+/**
+ * Genera una respuesta completa (no streaming) para el prompt dado.
+ *
+ * @param prompt  Texto de entrada para el modelo.
+ * @returns       Respuesta completa como string.
+ *
+ * @throws `NOT_INITIALIZED`  si `initialize()` no fue llamado antes.
+ * @throws `GENERATION_ERROR` si el modelo falla durante la inferencia.
+ *
+ * @example
+ * const response = await generateResponse('Explícame los TurboModules');
+ */
+export declare function generateResponse(prompt: string): Promise<string>;
+/**
+ * Genera una respuesta token a token mediante streaming.
+ * Los tokens se entregan en tiempo real a través de los callbacks.
+ *
+ * @param prompt     Texto de entrada para el modelo.
+ * @param callbacks  `{ onToken, onComplete, onError }`.
+ * @returns          Función de limpieza — llámala para cancelar las suscripciones.
+ *
+ * @example
+ * const unsubscribe = generateResponseStream('¿Qué es MediaPipe?', {
+ *   onToken:    (token, done) => console.log(token),
+ *   onComplete: ()            => console.log('¡Listo!'),
+ *   onError:    (err)         => console.error(err),
+ * });
+ *
+ * // Al desmontar el componente:
+ * unsubscribe();
+ */
+export declare function generateResponseStream(prompt: string, callbacks: StreamCallbacks): () => void;
+/**
+ * Comprueba si Gemini Nano está disponible en este dispositivo.
+ *
+ * @returns
+ *  - `'AVAILABLE'`     → El modelo está listo para usarse.
+ *  - `'NEED_DOWNLOAD'` → El dispositivo es compatible pero el modelo no está descargado.
+ *  - `'UNSUPPORTED'`   → El dispositivo no cumple los requisitos mínimos.
+ *
+ * @example
+ * const status = await checkAvailability();
+ * if (status === 'NEED_DOWNLOAD') {
+ *   // Mostrar UI de descarga del modelo
+ * }
+ */
+export declare function checkAvailability(): Promise<AvailabilityStatus>;
+/**
+ * Libera el modelo de la memoria de la NPU.
+ * **Recomendado**: llamar en el `useEffect` cleanup del componente raíz.
+ *
+ * @example
+ * useEffect(() => {
+ *   initialize(MODEL_PATH);
+ *   return () => { release(); };
+ * }, []);
+ */
+export declare function release(): Promise<void>;
+/**
+ * Limpia el historial de conversación en el motor nativo sin liberar el modelo.
+ * El siguiente `generateResponse` comenzará sin contexto previo.
+ *
+ * @example
+ * await resetConversation(); // nueva conversación, mismo motor
+ */
+export declare function resetConversation(): Promise<void>;
+declare const AICore: {
+    initialize: typeof initialize;
+    generateResponse: typeof generateResponse;
+    generateResponseStream: typeof generateResponseStream;
+    checkAvailability: typeof checkAvailability;
+    release: typeof release;
+    resetConversation: typeof resetConversation;
+};
+export default AICore;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC;AAEjG,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,4DAA4D;IAC5D,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,wDAAwD;IACxD,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED,sCAAsC;AACtC,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,eAAe,GACzB,MAAM,IAAI,CAyCZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAGrE;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAG7C;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGvD;AAID,QAAA,MAAM,MAAM;;;;;;;CAOX,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/package.json

@@ -0,0 +1,164 @@
+{
+  "name": "react-native-ai-core",
+  "version": "0.1.0",
+  "description": "High-performance AI bridge for React Native using Google AI Edge MediaPipe and Gemini Nano",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-ai-core-example",
+    "clean": "del-cli lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "release": "release-it --only-version",
+    "lint": "eslint \"**/*.{js,ts,tsx}\""
+  },
+  "keywords": [
+    "react-native",
+    "android",
+    "ai",
+    "llm",
+    "gemini",
+    "gemini-nano",
+    "on-device",
+    "npu",
+    "mediapipe",
+    "ml-kit",
+    "aicore",
+    "inference",
+    "turbo-module",
+    "new-architecture",
+    "streaming",
+    "local-llm",
+    "privacy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/albertofernandezroda/react-native-ai-core.git"
+  },
+  "author": "Alberto Fernandez <dev@example.com> (https://github.com/albertofernandezroda)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/albertofernandezroda/react-native-ai-core/issues"
+  },
+  "homepage": "https://github.com/albertofernandezroda/react-native-ai-core#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.0.3",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@react-native/babel-preset": "0.83.0",
+    "@react-native/eslint-config": "0.83.0",
+    "@release-it/conventional-changelog": "^10.0.6",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-builder-bob": "^0.41.0",
+    "release-it": "^19.2.4",
+    "turbo": "^2.8.21",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "AiCoreSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.aicore"
+    }
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "release-it",
+      "eslint"
+    ],
+    "version": "0.60.0"
+  }
+}

package/src/NativeAiCore.ts

@@ -0,0 +1,53 @@
+/**
+ * NativeAICore — TurboModule Spec (New Architecture)
+ *
+ * Puente JSI de alto rendimiento hacia el SDK de Google AI Edge (MediaPipe)
+ * para ejecutar Gemini Nano en local mediante la NPU del dispositivo.
+ */
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+export interface Spec extends TurboModule {
+  /**
+   * Inicializa el motor de inferencia LLM con el modelo en `modelPath`.
+   * Devuelve `true` si la inicialización fue exitosa.
+   */
+  initialize(modelPath: string): Promise<boolean>;
+
+  /**
+   * Genera una respuesta completa para el prompt dado (no streaming).
+   */
+  generateResponse(prompt: string): Promise<string>;
+
+  /**
+   * Inicia la generación en modo streaming.
+   * Los tokens se emiten a través de eventos NativeEventEmitter:
+   *   - 'AICore_streamToken'   → { token: string, done: boolean }
+   *   - 'AICore_streamComplete' → {}
+   *   - 'AICore_streamError'   → { code: string, message: string }
+   */
+  generateResponseStream(prompt: string): void;
+
+  /**
+   * Comprueba la disponibilidad de Gemini Nano en el dispositivo.
+   * Retorna: 'AVAILABLE' | 'NEED_DOWNLOAD' | 'UNSUPPORTED'
+   */
+  checkAvailability(): Promise<string>;
+
+  /**
+   * Libera el modelo de la memoria de la NPU.
+   * Debe llamarse cuando el componente se desmonte para evitar fugas.
+   */
+  release(): Promise<void>;
+
+  /**
+   * Limpia el historial de conversación sin liberar el modelo.
+   * El próximo mensaje comenzará una conversación nueva.
+   */
+  resetConversation(): Promise<void>;
+
+  // Requeridos por NativeEventEmitter
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('AiCore');

package/src/index.tsx

@@ -0,0 +1,221 @@
+/**
+ * react-native-ai-core
+ *
+ * Capa de abstracción JS sobre el TurboModule nativo.
+ * Proporciona una API limpia y tipada para usar Gemini Nano
+ * en local a través del SDK de Google AI Edge (MediaPipe).
+ *
+ * @example
+ * import AICore from 'react-native-ai-core';
+ *
+ * await AICore.initialize('/data/local/tmp/gemini-nano.bin');
+ * const answer = await AICore.generateResponse('¿Qué es JSI?');
+ */
+
+import { NativeEventEmitter, Platform } from 'react-native';
+import NativeAiCore from './NativeAiCore';
+
+// ── Tipos públicos ────────────────────────────────────────────────────────────
+
+/** Estado de disponibilidad de Gemini Nano en el dispositivo */
+export type AvailabilityStatus = 'AVAILABLE' | 'AVAILABLE_NPU' | 'NEED_DOWNLOAD' | 'UNSUPPORTED';
+
+/** Callbacks del streaming de respuesta */
+export interface StreamCallbacks {
+  /**
+   * Invocado por cada token recibido.
+   * @param token  Fragmento de texto parcial.
+   * @param done   `true` cuando el modelo ha terminado de generar.
+   */
+  onToken: (token: string, done: boolean) => void;
+  /** Invocado cuando la generación completa ha finalizado. */
+  onComplete: () => void;
+  /** Invocado si ocurre un error durante el streaming. */
+  onError: (error: AIError) => void;
+}
+
+/** Estructura de error normalizada */
+export interface AIError {
+  code: string;
+  message: string;
+}
+
+// ── Nombres de eventos (deben coincidir con los del módulo Kotlin) ─────────────
+const EVENT_STREAM_TOKEN    = 'AICore_streamToken';
+const EVENT_STREAM_COMPLETE = 'AICore_streamComplete';
+const EVENT_STREAM_ERROR    = 'AICore_streamError';
+
+// Instancia del emisor de eventos nativo (null en plataformas no soportadas)
+const emitter =
+  NativeAiCore != null ? new NativeEventEmitter(NativeAiCore) : null;
+
+// ── Guarda de plataforma ──────────────────────────────────────────────────────
+
+function assertAvailable(): void {
+  if (!NativeAiCore) {
+    throw new Error(
+      `react-native-ai-core: módulo nativo no disponible en ${Platform.OS}. ` +
+        'Este módulo requiere Android con soporte de NPU.'
+    );
+  }
+}
+
+// ── API pública ───────────────────────────────────────────────────────────────
+
+/**
+ * Inicializa el motor de inferencia LLM con el modelo indicado.
+ *
+ * @param modelPath  Ruta absoluta al archivo `.bin` del modelo en el dispositivo.
+ * @returns          `true` si la inicialización fue correcta.
+ *
+ * @throws `MODEL_NOT_FOUND`  si el archivo no existe en `modelPath`.
+ * @throws `NPU_UNSUPPORTED`  si la NPU del dispositivo no es compatible.
+ * @throws `INIT_FAILED`      si el motor no pudo arrancar por otro motivo.
+ *
+ * @example
+ * const ok = await initialize('/data/local/tmp/gemini-nano.bin');
+ */
+export async function initialize(modelPath: string): Promise<boolean> {
+  assertAvailable();
+  return NativeAiCore!.initialize(modelPath);
+}
+
+/**
+ * Genera una respuesta completa (no streaming) para el prompt dado.
+ *
+ * @param prompt  Texto de entrada para el modelo.
+ * @returns       Respuesta completa como string.
+ *
+ * @throws `NOT_INITIALIZED`  si `initialize()` no fue llamado antes.
+ * @throws `GENERATION_ERROR` si el modelo falla durante la inferencia.
+ *
+ * @example
+ * const response = await generateResponse('Explícame los TurboModules');
+ */
+export async function generateResponse(prompt: string): Promise<string> {
+  assertAvailable();
+  return NativeAiCore!.generateResponse(prompt);
+}
+
+/**
+ * Genera una respuesta token a token mediante streaming.
+ * Los tokens se entregan en tiempo real a través de los callbacks.
+ *
+ * @param prompt     Texto de entrada para el modelo.
+ * @param callbacks  `{ onToken, onComplete, onError }`.
+ * @returns          Función de limpieza — llámala para cancelar las suscripciones.
+ *
+ * @example
+ * const unsubscribe = generateResponseStream('¿Qué es MediaPipe?', {
+ *   onToken:    (token, done) => console.log(token),
+ *   onComplete: ()            => console.log('¡Listo!'),
+ *   onError:    (err)         => console.error(err),
+ * });
+ *
+ * // Al desmontar el componente:
+ * unsubscribe();
+ */
+export function generateResponseStream(
+  prompt: string,
+  callbacks: StreamCallbacks
+): () => void {
+  if (!NativeAiCore || !emitter) {
+    callbacks.onError({
+      code: 'UNAVAILABLE',
+      message: `react-native-ai-core no está disponible en ${Platform.OS}.`,
+    });
+    return () => {};
+  }
+
+  const tokenSub = emitter.addListener(
+    EVENT_STREAM_TOKEN,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (event: any) => {
+      callbacks.onToken(
+        (event as { token: string; done: boolean }).token,
+        (event as { token: string; done: boolean }).done
+      );
+    }
+  );
+
+  const completeSub = emitter.addListener(EVENT_STREAM_COMPLETE, () => {
+    callbacks.onComplete();
+  });
+
+  const errorSub = emitter.addListener(
+    EVENT_STREAM_ERROR,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (error: any) => {
+      callbacks.onError(error as AIError);
+    }
+  );
+
+  // Arrancar la inferencia en el lado nativo
+  NativeAiCore.generateResponseStream(prompt);
+
+  // Devuelve función de limpieza para remover los listeners
+  return () => {
+    tokenSub.remove();
+    completeSub.remove();
+    errorSub.remove();
+  };
+}
+
+/**
+ * Comprueba si Gemini Nano está disponible en este dispositivo.
+ *
+ * @returns
+ *  - `'AVAILABLE'`     → El modelo está listo para usarse.
+ *  - `'NEED_DOWNLOAD'` → El dispositivo es compatible pero el modelo no está descargado.
+ *  - `'UNSUPPORTED'`   → El dispositivo no cumple los requisitos mínimos.
+ *
+ * @example
+ * const status = await checkAvailability();
+ * if (status === 'NEED_DOWNLOAD') {
+ *   // Mostrar UI de descarga del modelo
+ * }
+ */
+export async function checkAvailability(): Promise<AvailabilityStatus> {
+  if (!NativeAiCore) return 'UNSUPPORTED';
+  return NativeAiCore.checkAvailability() as Promise<AvailabilityStatus>;
+}
+
+/**
+ * Libera el modelo de la memoria de la NPU.
+ * **Recomendado**: llamar en el `useEffect` cleanup del componente raíz.
+ *
+ * @example
+ * useEffect(() => {
+ *   initialize(MODEL_PATH);
+ *   return () => { release(); };
+ * }, []);
+ */
+export async function release(): Promise<void> {
+  if (!NativeAiCore) return;
+  return NativeAiCore.release();
+}
+
+/**
+ * Limpia el historial de conversación en el motor nativo sin liberar el modelo.
+ * El siguiente `generateResponse` comenzará sin contexto previo.
+ *
+ * @example
+ * await resetConversation(); // nueva conversación, mismo motor
+ */
+export async function resetConversation(): Promise<void> {
+  if (!NativeAiCore) return;
+  return NativeAiCore.resetConversation();
+}
+
+// ── Exportación por defecto (objeto API) ─────────────────────────────────────
+
+const AICore = {
+  initialize,
+  generateResponse,
+  generateResponseStream,
+  checkAvailability,
+  release,
+  resetConversation,
+};
+
+export default AICore;