{"id":37330520,"url":"https://github.com/drewalth/react-native-foundation-models","last_synced_at":"2026-01-16T03:35:14.877Z","repository":{"id":332021312,"uuid":"1132408771","full_name":"drewalth/react-native-foundation-models","owner":"drewalth","description":"React Native bindings for Apple's on-device FoundationModels framework","archived":false,"fork":false,"pushed_at":"2026-01-12T03:01:48.000Z","size":230,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T08:15:46.019Z","etag":null,"topics":["foundation-models","ios","react-native"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/drewalth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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":"2026-01-11T22:42:03.000Z","updated_at":"2026-01-12T03:01:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/drewalth/react-native-foundation-models","commit_stats":null,"previous_names":["drewalth/react-native-foundation-models"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/drewalth/react-native-foundation-models","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Freact-native-foundation-models","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Freact-native-foundation-models/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Freact-native-foundation-models/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Freact-native-foundation-models/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drewalth","download_url":"https://codeload.github.com/drewalth/react-native-foundation-models/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Freact-native-foundation-models/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"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":["foundation-models","ios","react-native"],"created_at":"2026-01-16T03:35:13.955Z","updated_at":"2026-01-16T03:35:14.852Z","avatar_url":"https://github.com/drewalth.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-native-foundation-models\n\nReact Native bindings for Apple's on-device [FoundationModels](https://developer.apple.com/documentation/FoundationModels) framework.\n\n\u003e **⚠️ Experimental**  \n\u003e This library is under active development. The API may change.\n\n## Requirements\n\n- iOS 26.0+\n- Apple Silicon (iPhone 15 Pro or later, M-series Macs)\n- Apple Intelligence enabled on device\n\n## Installation\n\n```bash\nnpx expo install @drewalth/react-native-foundation-models\n```\n\n## Usage\n\n### Basic Usage\n\n```typescript\nimport {\n  FoundationModelSession,\n  isAvailable,\n} from \"@drewalth/react-native-foundation-models\";\n\nif (isAvailable()) {\n  // Create a session\n  const session = new FoundationModelSession({\n    instructions: \"You are a concise science educator.\",\n  });\n\n  // Send a message\n  const response = await session.sendMessage(\n    \"Explain quantum computing in one sentence.\"\n  );\n  console.log(response.content);\n\n  // Multi-turn conversation - history is maintained automatically\n  const followUp = await session.sendMessage(\"Can you give me an example?\");\n  console.log(followUp.content);\n\n  // Clean up when done\n  session.destroy();\n}\n```\n\n### Multi-turn Conversations\n\nThe session maintains conversation history automatically, enabling contextual follow-up questions:\n\n```typescript\nconst session = new FoundationModelSession({\n  instructions: \"You are a helpful math tutor.\",\n});\n\nawait session.sendMessage(\"What is 25 * 4?\");\n// → \"25 × 4 = 100\"\n\nawait session.sendMessage(\"Now divide that by 5\");\n// → \"100 ÷ 5 = 20\" (remembers the previous result)\n\n// Access conversation history\nconst history = session.getHistory();\n// [\n//   { role: \"user\", content: \"What is 25 * 4?\" },\n//   { role: \"assistant\", content: \"25 × 4 = 100\" },\n//   { role: \"user\", content: \"Now divide that by 5\" },\n//   { role: \"assistant\", content: \"100 ÷ 5 = 20\" }\n// ]\n\n// Clear history to start fresh (keeps same instructions)\nsession.clearHistory();\n```\n\n### Tool Calling\n\nExtend the model's capabilities with custom tools. Tools are defined at build time via the Expo config plugin and implemented at runtime via JavaScript handlers passed to the session constructor.\n\n#### 1. Configure Tools in Expo\n\nDefine your tools schema in `app.json` or `app.config.js`:\n\n```javascript\n// app.config.js\nexport default {\n  expo: {\n    plugins: [\n      [\n        \"@drewalth/react-native-foundation-models\",\n        {\n          tools: [\n            {\n              name: \"getCurrentTime\",\n              description: \"Get the current date and time\",\n              parameters: {\n                type: \"object\",\n                properties: {\n                  timezone: {\n                    type: \"string\",\n                    description: \"IANA timezone (e.g., 'America/New_York')\",\n                  },\n                  format: {\n                    type: \"string\",\n                    enum: [\"short\", \"long\"],\n                    description: \"Output format\",\n                  },\n                },\n                required: [],\n              },\n            },\n            {\n              name: \"calculate\",\n              description: \"Evaluate a mathematical expression\",\n              parameters: {\n                type: \"object\",\n                properties: {\n                  expression: {\n                    type: \"string\",\n                    description: \"Math expression (e.g., '2 + 2 * 3')\",\n                  },\n                },\n                required: [\"expression\"],\n              },\n            },\n            {\n              name: \"fetchWeather\",\n              description: \"Get current weather for a city\",\n              parameters: {\n                type: \"object\",\n                properties: {\n                  city: {\n                    type: \"string\",\n                    description: \"City name\",\n                  },\n                },\n                required: [\"city\"],\n              },\n            },\n          ],\n        },\n      ],\n    ],\n  },\n};\n```\n\n#### 2. Implement Tool Handlers\n\nPass tool handlers directly to the session constructor:\n\n```typescript\nimport { FoundationModelSession } from \"@drewalth/react-native-foundation-models\";\n\nconst session = new FoundationModelSession({\n  instructions:\n    \"You are a helpful assistant with access to time, calculator, and weather tools.\",\n  tools: {\n    getCurrentTime: ({ timezone, format }) =\u003e {\n      const now = new Date();\n      if (format === \"short\") {\n        return now.toLocaleTimeString(\"en-US\", {\n          timeZone: timezone || undefined,\n        });\n      }\n      return now.toLocaleString(\"en-US\", {\n        timeZone: timezone || undefined,\n        weekday: \"long\",\n        year: \"numeric\",\n        month: \"long\",\n        day: \"numeric\",\n        hour: \"numeric\",\n        minute: \"numeric\",\n      });\n    },\n\n    calculate: ({ expression }) =\u003e {\n      // Sanitize and evaluate\n      const sanitized = expression.replace(/[^0-9+\\-*/().%\\s]/g, \"\");\n      const result = new Function(`return (${sanitized})`)();\n      return String(result);\n    },\n\n    // Async handlers are supported\n    fetchWeather: async ({ city }) =\u003e {\n      const response = await fetch(\n        `https://api.weather.example/current?city=${encodeURIComponent(city)}`\n      );\n      const data = await response.json();\n      return `${data.temp}°F, ${data.condition}`;\n    },\n  },\n});\n\n// The model will automatically use tools when appropriate\nconst response = await session.sendMessage(\n  \"What time is it in Tokyo, and what's 15% of 85?\"\n);\n```\n\n#### 3. Run Prebuild\n\nAfter configuring tools, regenerate native code:\n\n```bash\nnpx expo prebuild\n```\n\n### Using in React Components\n\n```tsx\nimport { useMemo, useState } from \"react\";\nimport {\n  FoundationModelSession,\n  isAvailable,\n  type Message,\n} from \"@drewalth/react-native-foundation-models\";\n\nfunction ChatScreen() {\n  const [messages, setMessages] = useState\u003cMessage[]\u003e([]);\n\n  // Create session once - no useEffect needed for tool registration\n  const session = useMemo(() =\u003e {\n    if (!isAvailable()) return null;\n\n    return new FoundationModelSession({\n      instructions: \"You are a helpful assistant.\",\n      tools: {\n        getCurrentTime: () =\u003e new Date().toLocaleTimeString(),\n      },\n    });\n  }, []);\n\n  const sendMessage = async (text: string) =\u003e {\n    if (!session) return;\n\n    await session.sendMessage(text);\n    setMessages(session.getHistory());\n  };\n\n  // ...render UI\n}\n```\n\n## API Reference\n\n### `isAvailable(): boolean`\n\nReturns `true` if FoundationModels is available on the current device.\n\n### `FoundationModelSession`\n\nA stateful session for conversing with the on-device language model.\n\n#### Constructor\n\n```typescript\nnew FoundationModelSession(config?: {\n  instructions?: string;\n  tools?: ToolHandlers;\n})\n```\n\n| Option         | Type           | Description                                    |\n| -------------- | -------------- | ---------------------------------------------- |\n| `instructions` | `string?`      | System instructions to guide model behavior    |\n| `tools`        | `ToolHandlers` | Object mapping tool names to handler functions |\n\n#### Methods\n\n| Method                                           | Description                               |\n| ------------------------------------------------ | ----------------------------------------- |\n| `sendMessage(prompt: string): Promise\u003cResponse\u003e` | Send a message and get a response         |\n| `getHistory(): Message[]`                        | Get all messages in the conversation      |\n| `clearHistory(): void`                           | Clear conversation history (keeps config) |\n| `destroy(): void`                                | Clean up session resources                |\n| `isDestroyed: boolean`                           | Whether the session has been destroyed    |\n\n### Types\n\n```typescript\ninterface Message {\n  role: \"user\" | \"assistant\";\n  content: string;\n}\n\ninterface GenerateResponse {\n  content: string;\n}\n```\n\n## Roadmap\n\n- [x] Stateful sessions (multi-turn conversations)\n- [x] Tool calling\n- [x] Streaming responses\n- [ ] Guided generation (response schemas)\n\n## Contributing\n\nContributions are welcome! This is a new framework and there's a lot to explore.\n\n- Check the [roadmap](#roadmap) for planned features\n- Open an [issue](https://github.com/drewalth/react-native-foundation-models/issues) to discuss ideas or report bugs\n- PRs for bug fixes, documentation, and new features are appreciated\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewalth%2Freact-native-foundation-models","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrewalth%2Freact-native-foundation-models","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewalth%2Freact-native-foundation-models/lists"}