react-native-ai-core 0.1.0 → 0.2.0

package/src/index.tsx

@@ -1,76 +1,82 @@
 /**
  * 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).
+ * JS abstraction layer over the native TurboModule.
+ * Provides a clean, typed API for running Gemini Nano on-device
+ * via the Google AI Edge SDK (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?');
+ * const answer = await AICore.generateResponse('What is JSI?');
  */
 
 import { NativeEventEmitter, Platform } from 'react-native';
 import NativeAiCore from './NativeAiCore';
-
-// ── Tipos públicos ────────────────────────────────────────────────────────────
-
-/** Estado de disponibilidad de Gemini Nano en el dispositivo */
+import { generateStructuredResponse } from './structured';
+export {
+  generateStructuredResponse,
+  StructuredOutputError,
+  type StructuredGenerateOptions,
+  type StructuredSchema,
+  type StructuredValidationIssue,
+} from './structured';
+
+// ── Public types ────────────────────────────────────────────────────────────────
+
+/** Availability status of Gemini Nano on the device */
 export type AvailabilityStatus = 'AVAILABLE' | 'AVAILABLE_NPU' | 'NEED_DOWNLOAD' | 'UNSUPPORTED';
 
-/** Callbacks del streaming de respuesta */
+/** Streaming response callbacks */
 export interface StreamCallbacks {
   /**
-   * Invocado por cada token recibido.
-   * @param token  Fragmento de texto parcial.
-   * @param done   `true` cuando el modelo ha terminado de generar.
+   * Called for each received token.
+   * @param token  Partial text fragment.
+   * @param done   `true` when the model has finished generating.
    */
   onToken: (token: string, done: boolean) => void;
-  /** Invocado cuando la generación completa ha finalizado. */
+  /** Called when the full generation has completed. */
   onComplete: () => void;
-  /** Invocado si ocurre un error durante el streaming. */
+  /** Called if an error occurs during streaming. */
   onError: (error: AIError) => void;
 }
 
-/** Estructura de error normalizada */
+/** Normalised error structure */
 export interface AIError {
   code: string;
   message: string;
 }
 
-// ── Nombres de eventos (deben coincidir con los del módulo Kotlin) ─────────────
+// ── Event names (must match the Kotlin module constants) ───────────────────────
 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.'
+      `react-native-ai-core: native module unavailable on ${Platform.OS}. ` +
+        'This module requires Android with NPU support.'
     );
   }
 }
 
-// ── API pública ───────────────────────────────────────────────────────────────
+// ── Public API ───────────────────────────────────────────────────────────────────
 
 /**
- * Inicializa el motor de inferencia LLM con el modelo indicado.
+ * Initialises the LLM inference engine with the given model.
  *
- * @param modelPath  Ruta absoluta al archivo `.bin` del modelo en el dispositivo.
- * @returns          `true` si la inicialización fue correcta.
+ * @param modelPath  Absolute path to the `.bin` model file on the device.
+ *                   Pass an empty string to use ML Kit AICore (Gemini Nano NPU).
+ * @returns          `true` on success.
  *
- * @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.
+ * @throws `MODEL_NOT_FOUND`  if the file does not exist at `modelPath`.
+ * @throws `NPU_UNSUPPORTED`  if the device NPU is incompatible.
+ * @throws `INIT_FAILED`      if the engine could not start for another reason.
  *
  * @example
  * const ok = await initialize('/data/local/tmp/gemini-nano.bin');
@@ -81,16 +87,16 @@ export async function initialize(modelPath: string): Promise<boolean> {
 }
 
 /**
- * Genera una respuesta completa (no streaming) para el prompt dado.
+ * Generates a complete (non-streaming) response for the given prompt.
  *
- * @param prompt  Texto de entrada para el modelo.
- * @returns       Respuesta completa como string.
+ * @param prompt  Input text for the model.
+ * @returns       Full response as a string.
  *
- * @throws `NOT_INITIALIZED`  si `initialize()` no fue llamado antes.
- * @throws `GENERATION_ERROR` si el modelo falla durante la inferencia.
+ * @throws `NOT_INITIALIZED`  if `initialize()` was not called first.
+ * @throws `GENERATION_ERROR` if the model fails during inference.
  *
  * @example
- * const response = await generateResponse('Explícame los TurboModules');
+ * const response = await generateResponse('Explain TurboModules');
  */
 export async function generateResponse(prompt: string): Promise<string> {
   assertAvailable();
@@ -98,21 +104,21 @@ export async 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.
+ * Generates a response token-by-token via streaming.
+ * Tokens are delivered in real time through the callbacks.
  *
- * @param prompt     Texto de entrada para el modelo.
+ * @param prompt     Input text for the model.
  * @param callbacks  `{ onToken, onComplete, onError }`.
- * @returns          Función de limpieza — llámala para cancelar las suscripciones.
+ * @returns          Cleanup function — call it to remove the event subscriptions.
  *
  * @example
- * const unsubscribe = generateResponseStream('¿Qué es MediaPipe?', {
+ * const unsubscribe = generateResponseStream('What is MediaPipe?', {
  *   onToken:    (token, done) => console.log(token),
- *   onComplete: ()            => console.log('¡Listo!'),
+ *   onComplete: ()            => console.log('Done!'),
  *   onError:    (err)         => console.error(err),
  * });
  *
- * // Al desmontar el componente:
+ * // On component unmount:
  * unsubscribe();
  */
 export function generateResponseStream(
@@ -122,7 +128,7 @@ export function generateResponseStream(
   if (!NativeAiCore || !emitter) {
     callbacks.onError({
       code: 'UNAVAILABLE',
-      message: `react-native-ai-core no está disponible en ${Platform.OS}.`,
+      message: `react-native-ai-core is not available on ${Platform.OS}.`,
     });
     return () => {};
   }
@@ -150,10 +156,8 @@ export function generateResponseStream(
     }
   );
 
-  // Arrancar la inferencia en el lado nativo
   NativeAiCore.generateResponseStream(prompt);
 
-  // Devuelve función de limpieza para remover los listeners
   return () => {
     tokenSub.remove();
     completeSub.remove();
@@ -162,17 +166,17 @@ export function generateResponseStream(
 }
 
 /**
- * Comprueba si Gemini Nano está disponible en este dispositivo.
+ * Checks whether Gemini Nano is available on this device.
  *
  * @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.
+ *  - `'AVAILABLE'`     → Model is ready to use.
+ *  - `'NEED_DOWNLOAD'` → Device is compatible but the model is not yet downloaded.
+ *  - `'UNSUPPORTED'`   → Device does not meet the minimum requirements.
  *
  * @example
  * const status = await checkAvailability();
  * if (status === 'NEED_DOWNLOAD') {
- *   // Mostrar UI de descarga del modelo
+ *   // show model download UI
  * }
  */
 export async function checkAvailability(): Promise<AvailabilityStatus> {
@@ -181,8 +185,8 @@ export async function checkAvailability(): Promise<AvailabilityStatus> {
 }
 
 /**
- * Libera el modelo de la memoria de la NPU.
- * **Recomendado**: llamar en el `useEffect` cleanup del componente raíz.
+ * Releases the model from NPU memory.
+ * **Recommended**: call in the root component's `useEffect` cleanup.
  *
  * @example
  * useEffect(() => {
@@ -196,23 +200,24 @@ export async 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.
+ * Clears the conversation history in the native engine without releasing the model.
+ * The next `generateResponse` call will start without any previous context.
  *
  * @example
- * await resetConversation(); // nueva conversación, mismo motor
+ * await resetConversation(); // new conversation, same engine
  */
 export async function resetConversation(): Promise<void> {
   if (!NativeAiCore) return;
   return NativeAiCore.resetConversation();
 }
 
-// ── Exportación por defecto (objeto API) ─────────────────────────────────────
+// ── Default export (API object) ───────────────────────────────────────────────
 
 const AICore = {
   initialize,
   generateResponse,
   generateResponseStream,
+  generateStructuredResponse,
   checkAvailability,
   release,
   resetConversation,