# Apple Foundation Models for JavaScript

A TypeScript wrapper providing 1-to-1 API translation of Apple's [FoundationModels](https://developer.apple.com/documentation/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

```bash
npm install apple-foundation-models
```

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

```bash
npm run build:swift
```

## Quick Start

### SystemLanguageModel (Instance-based API)

```typescript
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)

```typescript
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](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](ARCHITECTURE.md) for detailed technical architecture.

## Tool Support ✅

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

```typescript
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](IMPLEMENTATION_COMPLETE.md) for complete documentation.

## Examples

### Check Model Availability

```typescript
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

```typescript
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

```typescript
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

```typescript
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](API_REFERENCE.md) - Complete API with Swift ↔ JavaScript examples
- [Architecture](ARCHITECTURE.md) - Technical implementation details
- [Tool Execution Architecture](TOOL_EXECUTION_ARCHITECTURE.md) - Solutions for automatic tool execution
- [Unix Socket Modal Design](UNIX_SOCKET_MODAL_DESIGN.md) - Recommended architecture with zero performance impact
- [Contributing](CONTRIBUTING.md) - Development and contribution guide
- [Changelog](CHANGELOG.md) - 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](TOOL_EXECUTION_ARCHITECTURE.md))

## Related Projects

- [llm-cli](https://github.com/johnhenry/llm-cli) - Command-line interface for LLMs
- [Apple FoundationModels](https://developer.apple.com/documentation/FoundationModels) - Official Swift documentation

## License

MIT

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
