example-app

Foundation Models Example App

This is a demonstration app showcasing the capacitor-foundation-models plugin capabilities. The app provides a simple interface to test Apple's Foundation Models integration in an Ionic Angular application.

Features

• 🤖 Session Management: Start and manage Foundation Models sessions
• 💬 Text Generation: Send prompts and receive AI-generated responses
• 📋 Schema Creation: Define and use structured output schemas
• 🎯 Riddle Generation: Example implementation using schemas for structured responses
• ⚠️ Error Handling: Comprehensive error handling with user-friendly alerts
• 🔍 Availability Checking: Detect device compatibility before using the plugin

Prerequisites

Before running this example app, ensure you have:

• iOS 26.0+ device or simulator
• Apple Intelligence enabled on the device
• Xcode 16+ for iOS development
• Node.js 18+ and npm/pnpm
• Ionic CLI installed globally

Quick Start

1. Install dependencies:

   cd example-app
   npm install

2. Build the web assets:

   npm run build

3. Sync with Capacitor:

   npx cap sync ios

4. Open in Xcode:

   npx cap open ios

5. Run on device: Build and run the app on a physical iOS device with Apple Intelligence enabled.

App Structure

Main Components

• HomePage (src/app/home/): Main interface for interacting with Foundation Models
• Capacitor Config (capacitor.config.ts): Basic Capacitor configuration
• iOS Project (ios/): Native iOS project with Foundation Models integration

Key Features Demonstrated

1. Availability Checking

The app first checks if Foundation Models are available on the device:

const availability = await FoundationModels.checkAvailability();
if (!availability.available) {
  // Show appropriate error message
}

2. Session Initialization

Starts a Foundation Models session with custom instructions:

await FoundationModels.startSession({
  instructions: "You are a helpful assistant. You speak only in Portuguese. Your name is Majúlia."
});

3. Simple Text Generation

Send prompts and receive unstructured responses:

const { response } = await FoundationModels.promptWithoutSchema({ 
  prompt: this.message 
});

4. Schema-Based Generation

Create schemas for structured outputs:

// Define schema
await FoundationModels.createSchema({
  name: 'Riddle',
  schema: {
    question: 'string',
    answers: {
      name: 'string',
      isCorret: 'boolean'
    }
  }
});

// Use schema
const { response } = await FoundationModels.promptWithSchema({
  prompt: 'Crie uma charada de adivinhação. Crie 3 respostas.',
  schema: 'Riddle'
});

User Interface

The app provides a simple interface with the following controls:

• Start Session: Initialize Foundation Models session
• Text Input: Enter prompts for the AI
• Send Message: Send unstructured prompts
• Test With Schema: Create the riddle schema
• Tell a Riddle: Generate structured riddle responses

Development Commands

# Start development server
npm run start

# Build for production
npm run build

# Run tests
npm run test

# Lint code
npm run lint

# Watch for changes
npm run watch

Testing on Device

Since Foundation Models require iOS 26+ and Apple Intelligence, testing must be done on:

1. Physical Device: iPhone 15 Pro/Pro Max or newer, iPad with M1+, or Mac with Apple Silicon
2. iOS 26+: Ensure device is running iOS 26 or later
3. Apple Intelligence Enabled: Check Settings > Apple Intelligence & Siri

Common Issues & Solutions

"Foundation Models are not available"

• Verify iOS version is 26.0+
• Check that Apple Intelligence is enabled in Settings
• Ensure you're testing on a compatible physical device
• Try restarting the device if issues persist

"Session not started" Error

• Always call "Start Session" before sending messages
• Check device console for detailed error messages
• Verify the plugin is properly installed and synced

Schema Errors

• Ensure schema names are unique
• Verify schema structure matches the expected format
• Create schemas before using them in prompts

Build Issues

• Run npx cap sync ios after making changes
• Clean and rebuild the iOS project if needed
• Check that all dependencies are properly installed

Example Schema Types

The app demonstrates various schema patterns:

// Simple object schema
{
  question: 'string',
  answer: 'string',
  confidence: 'number',
  isCorrect: 'boolean'
}

// Nested object schema
{
  quiz: {
    title: 'string',
    questions: {
      text: 'string',
      options: 'string',
      correct: 'boolean'
    }
  }
}

Extending the Example

You can extend this example by:

1. Adding more schema types: Experiment with different data structures
2. Implementing conversation history: Store and display previous interactions
3. Adding temperature controls: Allow users to adjust response creativity
4. Creating specialized prompts: Build domain-specific AI assistants
5. Adding voice integration: Combine with speech recognition/synthesis

Resources

• Capacitor Documentation
• Ionic Angular Documentation
• Apple Foundation Models
• Plugin Repository

Contributing

If you find issues with the example app or have suggestions for improvements, please:

1. Check existing issues in the main repository
2. Create a new issue with detailed reproduction steps
3. Submit pull requests for bug fixes or enhancements

License

This example app is part of the capacitor-foundation-models plugin and is licensed under the MIT License.