{"id":29228113,"url":"https://github.com/deveix/react-native-apple-llm","last_synced_at":"2026-04-01T17:02:11.012Z","repository":{"id":299474675,"uuid":"1003127414","full_name":"deveix/react-native-apple-llm","owner":"deveix","description":"React Native Apple LLM plugin using Foundation Models","archived":false,"fork":false,"pushed_at":"2026-01-17T12:30:17.000Z","size":502,"stargazers_count":320,"open_issues_count":0,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-27T23:42:22.017Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deveix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-16T17:02:56.000Z","updated_at":"2026-03-26T17:32:38.000Z","dependencies_parsed_at":"2025-07-16T04:13:12.981Z","dependency_job_id":"624b73c5-01fd-49b8-b808-d404b4a696a5","html_url":"https://github.com/deveix/react-native-apple-llm","commit_stats":null,"previous_names":["deveix/react-native-apple-llm"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/deveix/react-native-apple-llm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deveix%2Freact-native-apple-llm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deveix%2Freact-native-apple-llm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deveix%2Freact-native-apple-llm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deveix%2Freact-native-apple-llm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deveix","download_url":"https://codeload.github.com/deveix/react-native-apple-llm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deveix%2Freact-native-apple-llm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2025-07-03T10:01:57.297Z","updated_at":"2026-04-01T17:02:10.985Z","avatar_url":"https://github.com/deveix.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Native Apple LLM Plugin\n\nA 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**.\n\n## Features\n\n- **On-device Apple Intelligence** - Access Apple's Foundation Models locally\n- **Privacy-focused** - All processing happens on-device, no data sent to servers\n- **Structured JSON output** - Generate structured data with JSON schemas\n- **Text generation** - Create human-like text responses\n- **Session management** - Configure and manage LLM sessions\n- **TypeScript support** - Full type safety and IntelliSense\n- **Custom tools** - User defined tool-box available for LLM use\n\n## Requirements\n\n- iOS 26.0\n- Xcode 26\n- Apple Intelligence enabled device (iPhone 15 Pro, iPhone 16 series, M1+ iPad/Mac) or simulator (MacOS 26 required)\n\n\u003cdiv align=\"center\"\u003e\n\n[![mit licence](https://img.shields.io/dub/l/vibe-d.svg?style=for-the-badge)](https://github.com/deveix/react-native-apple-llm/blob/main/LICENSE.md)\n[![npm version](https://img.shields.io/npm/v/react-native-apple-llm?style=for-the-badge)](https://www.npmjs.com/package/react-native-apple-llm)\n[![npm downloads](https://img.shields.io/npm/dt/react-native-apple-llm.svg?style=for-the-badge)](https://www.npmjs.org/package/react-native-apple-llm)\n[![npm downloads](https://img.shields.io/npm/dm/react-native-apple-llm.svg?style=for-the-badge)](https://www.npmjs.org/package/react-native-apple-llm)\n\n\u003c/div\u003e\n\n\u003ca href=\"https://x.com/aykasem001\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Follow_on_X-000000?logo=x\u0026logoColor=white\u0026style=flat-square\" alt=\"Follow on X\"/\u003e\n\u003c/a\u003e\n\n## Installation\n\n1. Install the package:\n\n```sh\nnpm install react-native-apple-llm\n# or\nyarn add react-native-apple-llm\n# or\npnpm add react-native-apple-llm\n```\n\n2. Link the native module (if not autolinked):\n\n```sh\nnpx pod-install\n# or if using CocoaPods directly\ncd ios \u0026\u0026 pod install\n```\n\n## Use Cases\n\nThis plugin is perfect for building:\n\n- **AI-powered mobile apps** with privacy-first approach\n- **Chatbots and virtual assistants** that work offline\n- **Content generation tools** for social media and blogs\n- **Data extraction and structuring** from user input\n- **Smart forms** that auto-fill based on natural language\n- **Educational apps** with personalized AI tutoring\n- **Accessibility tools** with intelligent text processing\n\n## Quick Start\n\n```tsx\nimport {\n  isFoundationModelsEnabled,\n  AppleLLMSession\n} from \"react-native-apple-llm\";\n\n// Check if Apple Intelligence is available\nconst checkAvailability = async () =\u003e {\n  const status = await isFoundationModelsEnabled();\n  console.log(\"Apple Intelligence status:\", status);\n};\n\n// Generate simple text\nconst generateSimpleText = async () =\u003e {\n  const session = new AppleLLMSession();\n  await session.configure({\n    instructions: \"You are a helpful assistant.\"\n  });\n\n  const response = await session.generateText({\n    prompt: \"Explain React Native in one sentence\"\n  });\n\n  console.log(response);\n  session.dispose();\n};\n```\n\n## Tool Usage\n\n```tsx\nimport {\n  AppleLLMSession,\n  ToolDefinition,\n  ToolSchema\n} from \"react-native-apple-llm\";\n\n// Define your tools\nconst weatherSchema: ToolSchema = {\n  name: \"weather\",\n  description: \"Get the current weather in a given location\",\n  parameters: {\n    city: {\n      type: \"string\",\n      description: \"The city to get the weather for\",\n      name: \"city\"\n    }\n  }\n};\n\nconst weatherHandler = async (param: any) =\u003e {\n  return `The weather in ${param.city.value} is severe thunderstorms. Take shelter immediately.`;\n};\n\nconst weatherTool: ToolDefinition = {\n  schema: weatherSchema,\n  handler: weatherHandler\n};\n\n// Use with session, don't forget to check availability first like above\nconst session = new AppleLLMSession();\nawait session.configure(\n  {\n    instructions: \"You are a helpful assistant.\"\n  },\n  [weatherTool]\n);\n\nconst response = await session.generateWithTools({\n  prompt: \"What is the weather in Monrovia, California?\"\n});\n\nconsole.log(response);\nsession.dispose();\n```\n\n## Streaming\n\nThe library supports streaming text generation in two ways, allowing you to display results as they're being generated:\n\n### Method 1: Using `generateTextStream()` with async iteration\n\n```tsx\nimport { AppleLLMSession } from \"react-native-apple-llm\";\n\nconst streamExample = async () =\u003e {\n  const session = new AppleLLMSession();\n  await session.configure({\n    instructions: \"You are an amazing storyteller.\"\n  });\n\n  // Use generateTextStream for streaming responses\n  const result = await session.generateTextStream({\n    prompt: \"Tell me a story (in less than 100 words).\"\n  });\n\n  // Iterate through the stream chunks\n  for await (const chunk of result) {\n    console.log(chunk); // Each chunk contains the full response text so far\n    // Update your UI with the chunk\n  }\n\n  session.dispose();\n};\n```\n\n### Method 2: Using EventEmitter with `generateText()` or `generateWithTools()`\n\nBoth `generateText()` and `generateWithTools()` accept an optional `stream` parameter that receives chunks via events:\n\n```tsx\nimport { AppleLLMSession } from \"react-native-apple-llm\";\nimport { EventEmitter } from \"events\";\n\nconst streamWithEventEmitter = async () =\u003e {\n  const session = new AppleLLMSession();\n  await session.configure({\n    instructions: \"You are a helpful assistant.\"\n  });\n\n  // Create an EventEmitter for streaming\n  const streamEmitter = new EventEmitter();\n\n  // Listen for data events\n  streamEmitter.on(\"data\", (chunk: string) =\u003e {\n    console.log(\"Received chunk:\", chunk);\n    // Update your UI with the chunk\n  });\n\n  // Pass the emitter to generateText or generateWithTools\n  await session.generateText({\n    prompt: \"Explain React Native in detail.\",\n    stream: streamEmitter\n  });\n\n  session.dispose();\n};\n```\n\n## TODO\n\n- [ ] Schema as zod\n- [X] Function calling capabilities\n- [X] Text Streaming\n\n## API Reference\n\n### AppleLLMSession Class\n\nThe `AppleLLMSession` class provides context and tool management for each isolated session:\n\n#### Constructor\n\n```tsx\nconst session = new AppleLLMSession();\n```\n\n#### `configure(options: LLMConfigOptions, tools?: ToolDefinition[]): Promise\u003cboolean\u003e`\n\nConfigures the session with instructions and optional tools.\n\n```tsx\nawait session.configure(\n  {\n    instructions: \"You are a helpful assistant.\"\n  },\n  [weatherTool]\n);\n```\n\n#### `generateText(options: LLMGenerateTextOptions): Promise\u003cany\u003e`\n\nGenerates natural text responses.\n\n```tsx\nconst response = await session.generateText({\n  prompt: \"Explain React Native\"\n});\n```\n\n#### `generateStructuredOutput(options: LLMGenerateOptions): Promise\u003cany\u003e`\n\nGenerates structured JSON output.\n\n```tsx\nconst data = await session.generateStructuredOutput({\n  structure: { name: { type: \"string\" } },\n  prompt: \"Extract name from: John Smith\"\n});\n```\n\n#### `generateWithTools(options: LLMGenerateWithToolsOptions): Promise\u003cany\u003e`\n\nGenerates text with tool calling capabilities.\n\n```tsx\nconst response = await session.generateWithTools({\n  prompt: \"What's the weather like?\"\n});\n```\n\n#### `generateTextStream(options: LLMGenerateTextStreamOptions): ReadableStream\u003cstring\u003e`\n\nGenerate text as a stream.\n\n```tsx\nconst stream = await session.generateTextStream({\n  prompt: \"Tell me a story\"\n});\n```\n\n#### `reset(): Promise\u003cboolean\u003e`\n\nResets the session state.\n\n```tsx\nawait session.reset();\n```\n\n#### `dispose(): void`\n\nCleans up resources and event listeners.\n\n```tsx\nsession.dispose();\n```\n\n### Global Functions\n\n#### `isFoundationModelsEnabled(): Promise\u003cFoundationModelsAvailability\u003e`\n\nChecks if Foundation Models (Apple Intelligence) are enabled and available on the device.\n\n**Returns:**\n\n- `\"available\"` - Apple Intelligence is ready to use\n- `\"appleIntelligenceNotEnabled\"` - User needs to enable Apple Intelligence in Settings\n- `\"modelNotReady\"` - Model is downloading or preparing (or mysterious system issues)\n- `\"unavailable\"` - Device doesn't support Apple Intelligence\n\n```tsx\nconst status = await isFoundationModelsEnabled();\nif (status === \"available\") {\n  // Proceed with LLM operations\n}\n```\n\n### Legacy Functions (Deprecated)\n\n\u003e **Deprecated**: These functions are maintained for backward compatibility but are deprecated. Use the `AppleLLMSession` class instead for better session management.\n\n#### `configureSession(options: LLMConfigOptions): Promise\u003cboolean\u003e`\n\n**Deprecated**: Use `AppleLLMSession.configure()` instead.\n\nConfigures the LLM session with system instructions and behavior.\n\n```tsx\n// Deprecated\nawait configureSession({\n  instructions: \"You are an expert React Native developer.\"\n});\n\n// Recommended\nconst session = new AppleLLMSession();\nawait session.configure({\n  instructions: \"You are an expert React Native developer.\"\n});\n```\n\n#### `generateStructuredOutput(options: LLMGenerateOptions): Promise\u003cany\u003e`\n\n**Deprecated**: Use `AppleLLMSession.generateStructuredOutput()` instead.\n\n```tsx\n// Deprecated\nconst userInfo = await generateStructuredOutput({\n  structure: {\n    name: { type: \"string\", description: \"User's full name\" },\n    age: { type: \"number\", description: \"User's age\" }\n  },\n  prompt: \"Extract user information: John is 25 years old\"\n});\n\n// Recommended\nconst session = new AppleLLMSession();\nawait session.configure({ instructions: \"Extract user data.\" });\nconst userInfo = await session.generateStructuredOutput({\n  structure: {\n    name: { type: \"string\", description: \"User's full name\" },\n    age: { type: \"number\", description: \"User's age\" }\n  },\n  prompt: \"Extract user information: John is 25 years old\"\n});\n```\n\n#### `generateText(options: LLMGenerateTextOptions): Promise\u003cstring\u003e`\n\n**Deprecated**: Use `AppleLLMSession.generateText()` instead.\n\n```tsx\n// Deprecated\nconst explanation = await generateText({\n  prompt: \"Explain the benefits of on-device AI processing\"\n});\n\n// Recommended\nconst session = new AppleLLMSession();\nawait session.configure({ instructions: \"Be helpful and informative.\" });\nconst explanation = await session.generateText({\n  prompt: \"Explain the benefits of on-device AI processing\"\n});\n```\n\n#### `resetSession(): Promise\u003cboolean\u003e`\n\n**Deprecated**: Use `AppleLLMSession.reset()` instead.\n\n```tsx\n// Deprecated\nawait resetSession();\n\n// Recommended\nawait session.reset();\n```\n\n### Types\n\n#### StructureProperty\n\nDefines a property in your JSON schema:\n\n```tsx\ninterface StructureProperty {\n  type?: \"string\" | \"integer\" | \"number\" | \"boolean\" | \"object\";\n  description?: string;\n  enum?: string[];\n  properties?: StructureSchema;\n}\n```\n\n#### StructureSchema\n\nA key-value mapping for defining structured output:\n\n```tsx\ntype StructureSchema = {\n  [key: string]: StructureProperty;\n};\n```\n\n#### Configuration Options\n\n```tsx\ninterface LLMConfigOptions {\n  instructions?: string;\n}\n\ninterface LLMGenerateOptions {\n  structure: StructureSchema;\n  prompt: string;\n}\n\ninterface LLMGenerateTextOptions {\n  prompt: string;\n  stream?: EventEmitter;\n}\n\ninterface LLMGenerateTextStreamOptions {\n  prompt: string;\n}\n\ninterface LLMGenerateWithToolsOptions {\n  prompt: string;\n  maxTokens?: number;\n  temperature?: number;\n  toolTimeout?: number; // in milliseconds\n  stream?: EventEmitter;\n}\n```\n\n#### Tool Definition\n\n```tsx\ninterface ToolSchema {\n  name: string;\n  description: string;\n  parameters: { [key: string]: ToolParameter };\n}\ninterface ToolDefinition {\n  handler: (parameters: any) =\u003e Promise\u003cany\u003e; // parameter should always look like a json\n  schema: ToolSchema;\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Apple Intelligence not available:**\n\n```tsx\nconst status = await isFoundationModelsEnabled();\nif (status === \"appleIntelligenceNotEnabled\") {\n  // Guide user to enable Apple Intelligence in Settings \u003e Apple Intelligence \u0026 Siri\n}\n```\n\n**Model not ready:**\n\n```tsx\nif (status === \"modelNotReady\") {\n  // Apple Intelligence is downloading. Ask user to wait and try again. Or double check the device is properly configured\n}\n```\n\n**Device not supported:**\n\n```tsx\nif (status === \"unavailable\") {\n  // Device doesn't support Apple Intelligence. Consider fallback options.\n}\n```\n\n## Contributing\n\nContributions 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.\n\n### Development Setup\n\n1. Clone the repository\n2. Install dependencies: `yarn install`\n3. Build the project: `yarn build`\n4. Link the library: `npm link`\n5. Get the example project found [here](https://github.com/ecoArcGaming/foundation-model-react-native-test) (or your own project).\n6. Add the library `npm link react-native-apple-llm`\n\n## License\n\nMIT License - see [LICENSE.md](LICENSE.md) for details.\n\n## Related Projects\n\n- [Apple's Foundation Models Documentation](https://developer.apple.com/documentation/foundationmodels/)\n- [React Native Documentation](https://reactnative.dev/)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Star this repo if you find it helpful!**\n\nCreated by [Ahmed Kasem](https://github.com/deveix), [Erik](https://github.com/ecoArcGaming), and future contributors!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveix%2Freact-native-apple-llm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeveix%2Freact-native-apple-llm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveix%2Freact-native-apple-llm/lists"}