[Unofficial] Apple Foundation Models bindings for Bun/NodeJS

🔥 Supports Vercel AI SDK

Features

• 🍎 Apple Intelligence Integration: Direct access to Apple's on-device models
• 🧠 Dual API Support: Use either the native Apple AI interface or Vercel AI SDK
• 🌊 Streaming Support: Real-time response streaming with OpenAI-compatible chunks
• 🎯 Object Generation: Structured data generation with Zod schemas or JSON Schema
• 💬 Chat Interface: OpenAI-style chat completions with message history
• 🔧 Tool Calling: Function/tool calling with Zod or JSON Schema
• 🔄 Cross-Platform: Works with React, Next.js, Vue, Svelte, and Node.js (Apple Silicon)
• 📝 TypeScript: Full type safety and excellent DX

Installation

bash
1# Using bun (recommended)
2bun add @meridius-labs/apple-on-device-ai
3
4# If you don't have these already
5bun add ai zod

Quick Start

Native Apple AI Interface

typescript
1import { chat } from "@meridius-labs/apple-on-device-ai";
2
3// Simple text generation
4const response = await chat({ messages: "What is the capital of France?" });
5console.log(response.text); // "Paris is the capital of France."
6
7// Chat with message history
8const chatResponse = await chat({
9  messages: [
10    { role: "system", content: "You are a helpful assistant." },
11    { role: "user", content: "Hello!" },
12  ],
13});
14console.log(chatResponse.text);
15
16// Streaming responses
17for await (const chunk of chat({ messages: "Tell me a story", stream: true })) {
18  process.stdout.write(chunk);
19}
20
21// Structured object generation (Zod)
22import { z } from "zod";
23const UserSchema = z.object({
24  name: z.string(),
25  age: z.number(),
26});
27const structured = await chat({
28  messages: "Generate a user object",
29  schema: UserSchema,
30});
31console.log(structured.object); // { name: "Alice", age: 30 }
32
33// Tool calling
34const mathTool = {
35  name: "calculator",
36  description: "Performs basic math operations",
37  jsonSchema: {
38    type: "object",
39    properties: {
40      operation: {
41        type: "string",
42        enum: ["add", "subtract", "multiply", "divide"],
43      },
44      a: { type: "number" },
45      b: { type: "number" },
46    },
47    required: ["operation", "a", "b"],
48  },
49  handler: async ({ operation, a, b }) => {
50    switch (operation) {
51      case "add":
52        return { result: a + b };
53      case "subtract":
54        return { result: a - b };
55      case "multiply":
56        return { result: a * b };
57      case "divide":
58        return { result: a / b };
59    }
60  },
61};
62const withTools = await chat({
63  messages: "What is 25 times 4?",
64  tools: [mathTool],
65});
66console.log(withTools.toolCalls); // [{ function: { name: "calculator" }, ... }]

Vercel AI SDK Integration

typescript
1import { appleAI } from "@meridius-labs/apple-on-device-ai";
2import { generateText, streamText, generateObject } from "ai";
3import { z } from "zod";
4
5// Text generation
6const { text } = await generateText({
7  model: appleAI(),
8  messages: [{ role: "user", content: "Explain quantum computing" }],
9});
10console.log(text);
11
12// Streaming
13const { textStream } = await streamText({
14  model: appleAI(),
15  messages: [{ role: "user", content: "Write a poem about technology" }],
16});
17for await (const delta of textStream) {
18  process.stdout.write(delta);
19}
20
21// Structured object generation
22const { object } = await generateObject({
23  model: appleAI(),
24  prompt: "Generate a chocolate chip cookie recipe",
25  schema: z.object({
26    recipe: z.object({
27      name: z.string(),
28      ingredients: z.array(z.string()),
29      steps: z.array(z.string()),
30    }),
31  }),
32});
33console.log(object);
34
35// Tool calling
36const { text, toolCalls } = await generateText({
37  model: appleAI(),
38  messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
39  tools: {
40    weather: {
41      description: "Get weather information",
42      parameters: z.object({ location: z.string() }),
43      execute: async ({ location }) => ({
44        temperature: 72,
45        condition: "sunny",
46        location,
47      }),
48    },
49  },
50});
51console.log(toolCalls);

Tool Calling & Structured Generation with Vercel AI SDK

Tool Calling Example

You can define tools using the tool helper and provide an inputSchema (Zod) and an execute function. The model will call your tool when appropriate, and you can handle tool calls and streaming output as follows:

typescript
1import { appleAI } from "@meridius-labs/apple-on-device-ai";
2import { streamText, tool } from "ai";
3import { z } from "zod";
4
5const result = streamText({
6  model: appleAI(),
7  messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
8  tools: {
9    weather: tool({
10      description: "Get weather information",
11      inputSchema: z.object({ location: z.string() }),
12      execute: async ({ location }) => ({
13        temperature: 72,
14        condition: "sunny",
15        location,
16      }),
17    }),
18  },
19});
20
21for await (const delta of result.fullStream) {
22  if (delta.type === "text") {
23    process.stdout.write(delta.text);
24  } else if (delta.type === "tool-call") {
25    console.log(`\n🔧 Tool call: ${delta.toolName}`);
26    console.log(`   Arguments: ${JSON.stringify(delta.input)}`);
27  } else if (delta.type === "tool-result") {
28    console.log(`✅ Tool result: ${JSON.stringify(delta.output)}`);
29  }
30}

Structured/Object Generation Example

You can generate structured objects directly from the model using Zod schemas:

typescript
1import { appleAI } from "@meridius-labs/apple-on-device-ai";
2import { generateObject } from "ai";
3import { z } from "zod";
4
5const { object } = await generateObject({
6  model: appleAI(),
7  prompt: "Generate a user profile",
8  schema: z.object({
9    name: z.string(),
10    age: z.number(),
11    email: z.string().email(),
12  }),
13});
14console.log(object); // { name: "Alice", age: 30, email: "[email protected]" }

Requirements

• macOS 26+ with Apple Intelligence enabled
• Apple Silicon: M1, M2, M3, or M4 chips
• Device Language: Set to supported language (English, Spanish, French, etc.)
• Sufficient Storage: At least 4GB available space for model files
• Bun: Use Bun for best compatibility (see workspace rules)

API Reference

Native API

chat({ messages, schema?, tools?, stream?, ...options })

• messages: string or array of chat messages ({ role, content })
• schema: Zod schema or JSON Schema for structured/object output (optional)
• tools: Array of tool definitions (see above) (optional)
• stream: boolean for streaming output (optional)
• temperature, maxTokens, etc.: generation options (optional)
• Returns: { text, object?, toolCalls? } or async iterator for streaming

appleAISDK.checkAvailability()

Check if Apple Intelligence is available.

appleAISDK.getSupportedLanguages()

Get list of supported languages.

Vercel AI SDK Provider

createAppleAI(options?)

Returns a model provider for use with Vercel AI SDK (generateText, streamText, generateObject).

generateText({ model, messages, tools?, ... })

Text generation with optional tool calling.

streamText({ model, messages, tools?, ... })

Streaming text generation with optional tool calling.

generateObject({ model, prompt, schema })

Structured/object generation.

Examples

See the /examples directory for comprehensive tests and usage:

• 15-smoke-test.ts: Native API, tool calling, streaming, structured output
• 16-smoke-test.ts: Vercel AI SDK compatibility, tool calling, streaming, object generation

Error Handling

• All methods throw on fatal errors (e.g., invalid schema, unavailable model)
• Streaming can be aborted with an AbortController (see Vercel AI SDK example)
• Tool handler errors are surfaced in the result

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License

MIT License - see LICENSE file for details.