https://github.com/deveix/react-native-apple-llm
React Native Apple LLM plugin using Foundation Models
https://github.com/deveix/react-native-apple-llm
apple-foundation-models apple-intelligence apple-llm apple-llm-integration foundation-models local-llm nlp offline-ai react-native react-native-ai react-native-apple react-native-apple-intelligence react-native-apple-llm react-native-llm react-native-local-llm react-native-plugin structured-output text-generation zod
Last synced: about 2 months ago
JSON representation
React Native Apple LLM plugin using Foundation Models
- Host: GitHub
- URL: https://github.com/deveix/react-native-apple-llm
- Owner: deveix
- License: mit
- Created: 2025-06-16T17:02:56.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-08-06T18:23:14.000Z (2 months ago)
- Last Synced: 2025-08-06T20:28:50.535Z (2 months ago)
- Topics: apple-foundation-models, apple-intelligence, apple-llm, apple-llm-integration, foundation-models, local-llm, nlp, offline-ai, react-native, react-native-ai, react-native-apple, react-native-apple-intelligence, react-native-apple-llm, react-native-llm, react-native-local-llm, react-native-plugin, structured-output, text-generation, zod
- Language: Swift
- Homepage:
- Size: 220 KB
- Stars: 233
- Watchers: 2
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# React Native Apple LLM Plugin
A React Native plugin to access Apple Intelligence Foundation Model framework using native on-device LLM APIs. This module lets you check model availability, create sessions, generate structured outputs (JSON), and generate with tools using Apple's LLMs, all from React Native. **Note that this is a beta feature, so bugs and compatibility issues may rise. Issues are welcome**.
## Features
- **On-device Apple Intelligence** - Access Apple's Foundation Models locally
- **Privacy-focused** - All processing happens on-device, no data sent to servers
- **Structured JSON output** - Generate structured data with JSON schemas
- **Text generation** - Create human-like text responses
- **Session management** - Configure and manage LLM sessions
- **TypeScript support** - Full type safety and IntelliSense
- **Custom tools** - User defined tool-box available for LLM use
## Requirements
- iOS 26.0
- Xcode 26
- Apple Intelligence enabled device (iPhone 15 Pro, iPhone 16 series, M1+ iPad/Mac) or simulator (MacOS 26 required)
[](https://github.com/deveix/react-native-apple-llm/blob/main/LICENSE.md)
[](https://www.npmjs.com/package/react-native-apple-llm)
[](https://www.npmjs.org/package/react-native-apple-llm)
[](https://www.npmjs.org/package/react-native-apple-llm)
## Installation
1. Install the package:
```sh
npm install react-native-apple-llm
# or
yarn add react-native-apple-llm
# or
pnpm add react-native-apple-llm
```
2. Link the native module (if not autolinked):
```sh
npx pod-install
# or if using CocoaPods directly
cd ios && pod install
```
## Use Cases
This plugin is perfect for building:
- **AI-powered mobile apps** with privacy-first approach
- **Chatbots and virtual assistants** that work offline
- **Content generation tools** for social media and blogs
- **Data extraction and structuring** from user input
- **Smart forms** that auto-fill based on natural language
- **Educational apps** with personalized AI tutoring
- **Accessibility tools** with intelligent text processing
## Quick Start
```tsx
import {
isFoundationModelsEnabled,
AppleLLMSession,
} from "react-native-apple-llm";
// Check if Apple Intelligence is available
const checkAvailability = async () => {
const status = await isFoundationModelsEnabled();
console.log("Apple Intelligence status:", status);
};
// Generate simple text
const generateSimpleText = async () => {
const session = new AppleLLMSession();
await session.configure({
instructions: "You are a helpful assistant.",
});
const response = await session.generateText({
prompt: "Explain React Native in one sentence",
});
console.log(response);
session.dispose();
};
```
## Tool Usage
```tsx
import {
AppleLLMSession,
ToolDefinition,
ToolSchema
} from "react-native-apple-llm";
// Define your tools
const weatherSchema: ToolSchema = {
name: 'weather',
description: 'Get the current weather in a given location',
parameters: {
city: {
type: 'string',
description: 'The city to get the weather for',
name: 'city'
}
}
};
const weatherHandler = async (param: any) => {
return `The weather in ${param.city.value} is severe thunderstorms. Take shelter immediately.`;
};
const weatherTool: ToolDefinition = {
schema: weatherSchema,
handler: weatherHandler
};
// Use with session, don't forget to check availability first like above
const session = new AppleLLMSession();
await session.configure({
instructions: "You are a helpful assistant.",
}, [weatherTool]);
const response = await session.generateWithTools({
prompt: "What is the weather in Monrovia, California?",
});
console.log(response);
session.dispose();
```
## TODO
- [ ] Streaming support using `Event Emitters`
- [ ] Schema as zod
- [ ] Function calling capabilities
## API Reference
### AppleLLMSession Class
The `AppleLLMSession` class provides context and tool management for each isolated session:
#### Constructor
```tsx
const session = new AppleLLMSession();
```
#### `configure(options: LLMConfigOptions, tools?: ToolDefinition[]): Promise`
Configures the session with instructions and optional tools.
```tsx
await session.configure({
instructions: "You are a helpful assistant.",
}, [weatherTool]);
```
#### `generateText(options: LLMGenerateTextOptions): Promise`
Generates natural text responses.
```tsx
const response = await session.generateText({
prompt: "Explain React Native",
});
```
#### `generateStructuredOutput(options: LLMGenerateOptions): Promise`
Generates structured JSON output.
```tsx
const data = await session.generateStructuredOutput({
structure: { name: { type: "string" } },
prompt: "Extract name from: John Smith",
});
```
#### `generateWithTools(options: LLMGenerateWithToolsOptions): Promise`
Generates text with tool calling capabilities.
```tsx
const response = await session.generateWithTools({
prompt: "What's the weather like?",
});
```
#### `reset(): Promise`
Resets the session state.
```tsx
await session.reset();
```
#### `dispose(): void`
Cleans up resources and event listeners.
```tsx
session.dispose();
```
### Global Functions
#### `isFoundationModelsEnabled(): Promise`
Checks if Foundation Models (Apple Intelligence) are enabled and available on the device.
**Returns:**
- `"available"` - Apple Intelligence is ready to use
- `"appleIntelligenceNotEnabled"` - User needs to enable Apple Intelligence in Settings
- `"modelNotReady"` - Model is downloading or preparing (or mysterious system issues)
- `"unavailable"` - Device doesn't support Apple Intelligence
```tsx
const status = await isFoundationModelsEnabled();
if (status === "available") {
// Proceed with LLM operations
}
```
### Legacy Functions (Deprecated)
> **Deprecated**: These functions are maintained for backward compatibility but are deprecated. Use the `AppleLLMSession` class instead for better session management.
#### `configureSession(options: LLMConfigOptions): Promise`
**Deprecated**: Use `AppleLLMSession.configure()` instead.
Configures the LLM session with system instructions and behavior.
```tsx
// Deprecated
await configureSession({
instructions: "You are an expert React Native developer.",
});
// Recommended
const session = new AppleLLMSession();
await session.configure({
instructions: "You are an expert React Native developer.",
});
```
#### `generateStructuredOutput(options: LLMGenerateOptions): Promise`
**Deprecated**: Use `AppleLLMSession.generateStructuredOutput()` instead.
```tsx
// Deprecated
const userInfo = await generateStructuredOutput({
structure: {
name: { type: "string", description: "User's full name" },
age: { type: "number", description: "User's age" },
},
prompt: "Extract user information: John is 25 years old",
});
// Recommended
const session = new AppleLLMSession();
await session.configure({ instructions: "Extract user data." });
const userInfo = await session.generateStructuredOutput({
structure: {
name: { type: "string", description: "User's full name" },
age: { type: "number", description: "User's age" },
},
prompt: "Extract user information: John is 25 years old",
});
```
#### `generateText(options: LLMGenerateTextOptions): Promise`
**Deprecated**: Use `AppleLLMSession.generateText()` instead.
```tsx
// Deprecated
const explanation = await generateText({
prompt: "Explain the benefits of on-device AI processing",
});
// Recommended
const session = new AppleLLMSession();
await session.configure({ instructions: "Be helpful and informative." });
const explanation = await session.generateText({
prompt: "Explain the benefits of on-device AI processing",
});
```
#### `resetSession(): Promise`
**Deprecated**: Use `AppleLLMSession.reset()` instead.
```tsx
// Deprecated
await resetSession();
// Recommended
await session.reset();
```
### Types
#### StructureProperty
Defines a property in your JSON schema:
```tsx
interface StructureProperty {
type?: "string" | "integer" | "number" | "boolean" | "object";
description?: string;
enum?: string[];
properties?: StructureSchema;
}
```
#### StructureSchema
A key-value mapping for defining structured output:
```tsx
type StructureSchema = {
[key: string]: StructureProperty;
};
```
#### Configuration Options
```tsx
interface LLMConfigOptions {
instructions?: string;
}
interface LLMGenerateOptions {
structure: StructureSchema;
prompt: string;
}
interface LLMGenerateTextOptions {
prompt: string;
}
interface LLMGenerateWithToolsOptions {
prompt: string;
maxTokens?: number;
temperature?: number;
toolTimeout?: number; // in milliseconds
}
```
#### Tool Definition
```tsx
interface ToolSchema {
name: string;
description: string;
parameters: { [key: string]: ToolParameter };
}
interface ToolDefinition {
handler: (parameters: any) => Promise; // parameter should always look like a json
schema: ToolSchema;
}
```
## Troubleshooting
### Common Issues
**Apple Intelligence not available:**
```tsx
const status = await isFoundationModelsEnabled();
if (status === "appleIntelligenceNotEnabled") {
// Guide user to enable Apple Intelligence in Settings > Apple Intelligence & Siri
}
```
**Model not ready:**
```tsx
if (status === "modelNotReady") {
// Apple Intelligence is downloading. Ask user to wait and try again. Or double check the device is properly configured
}
```
**Device not supported:**
```tsx
if (status === "unavailable") {
// Device doesn't support Apple Intelligence. Consider fallback options.
}
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
### Development Setup
1. Clone the repository
2. Install dependencies: `yarn install`
3. Build the project: `yarn build`
4. Link the library: `npm link`
5. Get the example project found [here](https://github.com/ecoArcGaming/foundation-model-react-native-test) (or your own project).
6. Add the library `npm link react-native-apple-llm`
## License
MIT License - see [LICENSE.md](LICENSE.md) for details.
## Related Projects
- [Apple's Foundation Models Documentation](https://developer.apple.com/documentation/foundationmodels/)
- [React Native Documentation](https://reactnative.dev/)
---
**Star this repo if you find it helpful!**
Created by [Ahmed Kasem](https://github.com/deveix), [Erik](https://github.com/ecoArcGaming), and future contributors!