apple-foundation-models

Apple Foundation Models for JavaScript

A TypeScript wrapper providing 1-to-1 API translation of Apple's FoundationModels framework for use in Node.js and JavaScript applications.

Features

• 🎯 1-to-1 API Translation: Direct mapping from Swift to TypeScript/JavaScript
• 📦 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🔄 Instance & Session APIs: Both single-generation and conversational interfaces
• 🛠️ Tool Support: Complete tool/function calling support with automatic execution ✅
• 🚀 Auto-Build: Swift wrapper builds automatically during npm install
• 🍎 Native Performance: Leverages Apple's on-device AI models
• 🔒 Privacy-First: All processing happens on-device

Requirements

• macOS: 15.0 (Sequoia) or later
• Node.js: 18.0.0+
• Swift: 6.0+ (included with Xcode)
• Architecture: ARM64 (Apple Silicon) or x64 (Intel)

Installation

npm install apple-foundation-models

The Swift wrapper builds automatically during installation. To rebuild manually:

npm run build:swift

Quick Start

SystemLanguageModel (Instance-based API)

import { SystemLanguageModel, LanguageModelSession }
  from 'apple-foundation-models';

// Get default model
const model = SystemLanguageModel.default;

// Check availability
if (!model.isAvailable) {
  console.log('Model not available');
  return;
}

// Create session and generate
const session = new LanguageModelSession(model);
const response = await session.respond('Write a haiku about TypeScript');

console.log(response.content);

LanguageModelSession (Conversational API)

import { SystemLanguageModel, LanguageModelSession, Instructions }
  from 'apple-foundation-models';

// Create session with instructions
const model = SystemLanguageModel.default;
const session = new LanguageModelSession(
  model,
  undefined, // guardrails (use default)
  [],        // tools
  new Instructions('You are a helpful coding assistant.')
);

// Multi-turn conversation
const response1 = await session.respond('What is TypeScript?');
console.log(response1.content);

const response2 = await session.respond('How is it different from JavaScript?');
console.log(response2.content);

// Access conversation history
console.log('Transcript entries:', session.transcript.length);

API Overview

Swift vs JavaScript/TypeScript

This library provides a 1-to-1 translation of Apple's FoundationModels API:

Swift	JavaScript/TypeScript
SystemLanguageModel.default	SystemLanguageModel.default
model.availability	model.availability (getter)
model.isAvailable	model.isAvailable (getter)
LanguageModelSession(model:)	new LanguageModelSession(model)
session.respond(to:)	await session.respond(prompt)
session.streamResponse(to:)	session.streamResponse(prompt)
session.transcript	session.transcript (getter)
session.isResponding	session.isResponding (getter)

See API_REFERENCE.md for complete API documentation with side-by-side examples.

Architecture

┌─────────────────┐
│  JavaScript App │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  TypeScript API │  SystemLanguageModel, LanguageModelSession
└────────┬────────┘
         │ JSON over stdin/stdout
         ▼
┌─────────────────┐
│ Swift Executable│  AppleFoundationModelsWrapper
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│FoundationModels│  Apple's Native Framework
│   (Apple SDK)   │
└─────────────────┘

See ARCHITECTURE.md for detailed technical architecture.

Tool Support ✅

NEW: Complete tool/function calling support with automatic execution!

import { LanguageModelSession, ToolOutput } from 'apple-foundation-models';

// Define tools the model can use
const weatherTool = {
  name: 'getWeather',
  description: 'Get current weather for a city',
  async call(args) {
    const weather = await fetchWeatherAPI(args.city);
    return new ToolOutput(weather);
  }
};

const calcTool = {
  name: 'calculate',
  description: 'Perform mathematical calculations',
  async call(args) {
    const result = eval(`${args.a} ${args.op} ${args.b}`);
    return new ToolOutput(result);
  }
};

// Create session with tools
const session = new LanguageModelSession(
  undefined,        // model (uses default)
  undefined,        // guardrails
  [weatherTool, calcTool]  // tools
);

// Model can now call tools automatically
const response = await session.respond("What's 25 * 4?");
console.log(response.content);

// Important: Close session to cleanup server
await session.close();

Key Features:

• 🔧 Zero-config automatic tool execution
• 🚀 Modal architecture - zero performance impact for sessions without tools
• 🔒 Unix domain socket for secure bidirectional communication
• 📝 Full TypeScript types for tool definitions

See IMPLEMENTATION_COMPLETE.md for complete documentation.

Examples

Check Model Availability

import { SystemLanguageModel, Availability }
  from 'apple-foundation-models';

const model = SystemLanguageModel.default;
const availability = model.availability;

switch (availability) {
  case Availability.Available:
    console.log('Model is ready!');
    break;
  case Availability.DeviceNotEligible:
    console.log('Device not eligible');
    break;
  case Availability.AppleIntelligenceNotEnabled:
    console.log('Apple Intelligence not enabled');
    break;
  case Availability.ModelNotReady:
    console.log('Model is downloading');
    break;
}

Use Case-Specific Models

import { SystemLanguageModel, UseCase, LanguageModelSession }
  from 'apple-foundation-models';

// Create model for content tagging
const model = new SystemLanguageModel(UseCase.ContentTagging);
const session = new LanguageModelSession(model);

const response = await session.respond(
  'Extract tags from: "TypeScript is a typed superset of JavaScript"'
);

Streaming Responses

import { SystemLanguageModel, LanguageModelSession }
  from 'apple-foundation-models';

const session = new LanguageModelSession(SystemLanguageModel.default);
const stream = session.streamResponse('Write a story about AI');

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

Generation Options

import { LanguageModelSession, SamplingMode }
  from 'apple-foundation-models';

const session = new LanguageModelSession();
const options = {
  sampling: SamplingMode.Random,
  temperature: 0.8,
  maximumResponseTokens: 200
};

const response = await session.respond('Write a creative poem', options);

Documentation

• API Reference - Complete API with Swift ↔ JavaScript examples
• Architecture - Technical implementation details
• Tool Execution Architecture - Solutions for automatic tool execution
• Unix Socket Modal Design - Recommended architecture with zero performance impact
• Contributing - Development and contribution guide
• Changelog - Version history

Limitations

• Platform: macOS 15.0+ only
• Offline: Requires internet for initial model download
• Tool Execution: Automatic tool execution not yet implemented (see TOOL_EXECUTION_ARCHITECTURE.md)

Related Projects

• llm-cli - Command-line interface for LLMs
• Apple FoundationModels - Official Swift documentation

License

MIT

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.