react-native-ai-core 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Alberto Fernandez
+Copyright (c) 2026 Alberto Fernandez (@albertoroda)
 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

package/README.md

@@ -99,6 +99,46 @@ To start a fresh conversation without releasing the model:
 await AICore.resetConversation();
 ```
 
+### Structured output with runtime validation
+
+For app-internal AI features such as extraction, classification, routing, or tool orchestration, use `generateStructuredResponse(...)`.
+
+- Validates optional structured input before generation
+- Forces JSON-only output
+- Extracts JSON even if the model wraps it in extra text
+- Validates the final payload with `zod`
+- Retries automatically with a repair prompt when validation fails
+- Uses a stateless native request so it does not pollute chat conversation history
+
+```tsx
+import { z } from 'zod';
+import { generateStructuredResponse } from 'react-native-ai-core';
+
+const TicketSchema = z.object({
+  category: z.enum(['bug', 'billing', 'feature']),
+  priority: z.enum(['low', 'medium', 'high']),
+  summary: z.string(),
+  needsHuman: z.boolean(),
+});
+
+const result = await generateStructuredResponse({
+  prompt: 'Classify this support request and summarize it.',
+  input: {
+    message: 'The app crashes when I try to export a PDF invoice.',
+  },
+  output: TicketSchema,
+});
+```
+
+Recommended for reliability on-device:
+- Keep the prompt short and task-specific
+- Keep `input` compact and validated before sending it
+- Prefer small output schemas over deeply nested ones
+- Use this API for internal app workflows, not long-form generation
+- Repair retries are bounded and prompt size is trimmed internally to avoid hitting the same context limits as chat flows
+
+There is also a concrete demo helper in [example/src/examples/structuredOutputExample.ts](example/src/examples/structuredOutputExample.ts).
+
 ---
 
 ## API Reference
@@ -134,6 +174,36 @@ const response = await AICore.generateResponse('Tell me a joke');
 
 ---
 
+### `generateStructuredResponse(options): Promise<T>`
+
+Generates stateless structured JSON and validates it against a user-defined `zod` schema.
+
+```tsx
+import { z } from 'zod';
+
+const OutputSchema = z.object({
+  intent: z.enum(['search', 'reply', 'ignore']),
+  confidence: z.number(),
+});
+
+const output = await generateStructuredResponse({
+  prompt: 'Determine the next action for this message.',
+  input: { message: 'Can you send me the invoice again?' },
+  output: OutputSchema,
+});
+```
+
+Options:
+- `prompt` — natural language instruction
+- `input` — optional structured input object
+- `inputSchema` — optional `zod` schema to validate the input before generation
+- `output` — required `zod` schema used to validate the model output
+- `maxRetries` — optional number of repair attempts when validation fails
+
+Throws `StructuredOutputError` if valid JSON matching the schema cannot be produced after retries.
+
+---
+
 ### `generateResponseStream(prompt: string, callbacks: StreamCallbacks): () => void`
 
 Generates a response token by token via streaming. Returns a cleanup function to remove event listeners.

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,14 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Keeps the process alive while AI generation runs in background -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+
+    <application>
+        <service
+            android:name=".InferenceService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+    </application>
+
 </manifest>