React Native bindings for Apple's on-device FoundationModels framework.
⚠️ Experimental
This library is under active development. The API may change.
- iOS 26.0+
- Apple Silicon (iPhone 15 Pro or later, M-series Macs)
- Apple Intelligence enabled on device
npx expo install @drewalth/react-native-foundation-modelsimport {
FoundationModelSession,
isAvailable,
} from "@drewalth/react-native-foundation-models";
if (isAvailable()) {
// Create a session
const session = new FoundationModelSession({
instructions: "You are a concise science educator.",
});
// Send a message
const response = await session.sendMessage(
"Explain quantum computing in one sentence."
);
console.log(response.content);
// Multi-turn conversation - history is maintained automatically
const followUp = await session.sendMessage("Can you give me an example?");
console.log(followUp.content);
// Clean up when done
session.destroy();
}The session maintains conversation history automatically, enabling contextual follow-up questions:
const session = new FoundationModelSession({
instructions: "You are a helpful math tutor.",
});
await session.sendMessage("What is 25 * 4?");
// → "25 × 4 = 100"
await session.sendMessage("Now divide that by 5");
// → "100 ÷ 5 = 20" (remembers the previous result)
// Access conversation history
const history = session.getHistory();
// [
// { role: "user", content: "What is 25 * 4?" },
// { role: "assistant", content: "25 × 4 = 100" },
// { role: "user", content: "Now divide that by 5" },
// { role: "assistant", content: "100 ÷ 5 = 20" }
// ]
// Clear history to start fresh (keeps same instructions)
session.clearHistory();Extend 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.
Define your tools schema in app.json or app.config.js:
// app.config.js
export default {
expo: {
plugins: [
[
"@drewalth/react-native-foundation-models",
{
tools: [
{
name: "getCurrentTime",
description: "Get the current date and time",
parameters: {
type: "object",
properties: {
timezone: {
type: "string",
description: "IANA timezone (e.g., 'America/New_York')",
},
format: {
type: "string",
enum: ["short", "long"],
description: "Output format",
},
},
required: [],
},
},
{
name: "calculate",
description: "Evaluate a mathematical expression",
parameters: {
type: "object",
properties: {
expression: {
type: "string",
description: "Math expression (e.g., '2 + 2 * 3')",
},
},
required: ["expression"],
},
},
{
name: "fetchWeather",
description: "Get current weather for a city",
parameters: {
type: "object",
properties: {
city: {
type: "string",
description: "City name",
},
},
required: ["city"],
},
},
],
},
],
],
},
};Pass tool handlers directly to the session constructor:
import { FoundationModelSession } from "@drewalth/react-native-foundation-models";
const session = new FoundationModelSession({
instructions:
"You are a helpful assistant with access to time, calculator, and weather tools.",
tools: {
getCurrentTime: ({ timezone, format }) => {
const now = new Date();
if (format === "short") {
return now.toLocaleTimeString("en-US", {
timeZone: timezone || undefined,
});
}
return now.toLocaleString("en-US", {
timeZone: timezone || undefined,
weekday: "long",
year: "numeric",
month: "long",
day: "numeric",
hour: "numeric",
minute: "numeric",
});
},
calculate: ({ expression }) => {
// Sanitize and evaluate
const sanitized = expression.replace(/[^0-9+\-*/().%\s]/g, "");
const result = new Function(`return (${sanitized})`)();
return String(result);
},
// Async handlers are supported
fetchWeather: async ({ city }) => {
const response = await fetch(
`https://api.weather.example/current?city=${encodeURIComponent(city)}`
);
const data = await response.json();
return `${data.temp}°F, ${data.condition}`;
},
},
});
// The model will automatically use tools when appropriate
const response = await session.sendMessage(
"What time is it in Tokyo, and what's 15% of 85?"
);After configuring tools, regenerate native code:
npx expo prebuildimport { useMemo, useState } from "react";
import {
FoundationModelSession,
isAvailable,
type Message,
} from "@drewalth/react-native-foundation-models";
function ChatScreen() {
const [messages, setMessages] = useState<Message[]>([]);
// Create session once - no useEffect needed for tool registration
const session = useMemo(() => {
if (!isAvailable()) return null;
return new FoundationModelSession({
instructions: "You are a helpful assistant.",
tools: {
getCurrentTime: () => new Date().toLocaleTimeString(),
},
});
}, []);
const sendMessage = async (text: string) => {
if (!session) return;
await session.sendMessage(text);
setMessages(session.getHistory());
};
// ...render UI
}Returns true if FoundationModels is available on the current device.
A stateful session for conversing with the on-device language model.
new FoundationModelSession(config?: {
instructions?: string;
tools?: ToolHandlers;
})| Option | Type | Description |
|---|---|---|
instructions |
string? |
System instructions to guide model behavior |
tools |
ToolHandlers |
Object mapping tool names to handler functions |
| Method | Description |
|---|---|
sendMessage(prompt: string): Promise<Response> |
Send a message and get a response |
getHistory(): Message[] |
Get all messages in the conversation |
clearHistory(): void |
Clear conversation history (keeps config) |
destroy(): void |
Clean up session resources |
isDestroyed: boolean |
Whether the session has been destroyed |
interface Message {
role: "user" | "assistant";
content: string;
}
interface GenerateResponse {
content: string;
}- Stateful sessions (multi-turn conversations)
- Tool calling
- Streaming responses
- Guided generation (response schemas)
Contributions are welcome! This is a new framework and there's a lot to explore.
- Check the roadmap for planned features
- Open an issue to discuss ideas or report bugs
- PRs for bug fixes, documentation, and new features are appreciated
MIT