Local AI for Flutter iOS with Apple Foundation Models

This guide adds a short, on-device summary to a Flutter iOS app using cupertino_fundations_models. The package connects Dart to Apple’s native Foundation Models framework. The same APIs support rewriting, classification, structured JSON and tools defined by your app. Local generation needs no API key.

Español · Task recipes · FAQ

What you need

The plugin supports CocoaPods and Swift Package Manager. It does not add third-party runtime packages or require downloading a GGUF model into your app. Apple manages its system model and assets. Initial asset downloads may need network even though inference runs on the device.

Install the package

From your Flutter application:

flutter pub add cupertino_fundations_models

To choose the version explicitly, add:

dependencies:
  cupertino_fundations_models: ^0.4.4

Import the exact package name, including the existing spelling fundations:

import 'package:cupertino_fundations_models/cupertino_fundations_models.dart';

Rebuild the iOS host after adding or upgrading the plugin. Hot reload cannot install a changed Swift bridge. A local-only app can leave PCC disabled. Text generation alone does not require microphone or Speech usage descriptions.

Generate your first summary

Call this function from your Flutter application. It checks availability, creates a local session and releases it when finished. A null result lets your UI offer its usual manual flow if the model is unavailable or the request fails.

import 'package:cupertino_fundations_models/cupertino_fundations_models.dart';

Future<String?> summarizeOnDevice(String text) async {
  final models = CupertinoFoundationModels();
  FoundationModelSession? session;
  try {
    final availability = await models.checkAvailability(
      mode: ModelMode.local,
      cloudPolicy: CloudPolicy.never,
      localeIdentifier: 'en_US',
    );
    if (!availability.isAvailable) return null;

    session = await models.createSession(
      options: const SessionOptions(
        mode: ModelMode.local,
        cloudPolicy: CloudPolicy.never,
        localeIdentifier: 'en_US',
        instructions:
            'Summarize the supplied passage in three short English bullets. '
            'Use only facts present in the passage.',
      ),
    );
    final response = await session.respond(
      Prompt.text(text),
      options: const GenerationOptions(maximumResponseTokens: 180),
    );
    return response.text;
  } on FoundationModelsException {
    return null;
  } finally {
    await session?.dispose();
  }
}

Keep the input short and let the user review the result. Availability can change between the check and generation. Your app can use the typed error code and recovery guide to explain a failure rather than treating every null result as the same condition.

Choose the next API

See recipes for structured extraction and classification, and usage for complete lifecycle, token-budget and timeout semantics.

Keep local AI local

Set ModelMode.local and CloudPolicy.never explicitly. This selects on-device generation. The package does not automatically send failed requests to OpenAI, Gemini or another remote API, and it does not store API keys.

Tools are application code: a tool can access your app’s database or network. The local model policy does not make a networking tool offline. Speech’s AudioTranscriptionMode.onDevice is a separate setting; its automatic or server alternatives can allow Apple Speech networking.

PCC is an optional Apple cloud route, not a requirement for local generation. Read Private Cloud Compute for the separate iOS 27, Apple entitlement, signing, host opt-in and consent requirements. A plist flag does not grant cloud access.

Plan for the model’s limits

This package supports iOS, not macOS, Android, web or a standalone Swift application. Apple’s broader framework support does not imply plugin support on those platforms. Local generation is not available on every iPhone.

Use small, well-defined tasks. A local language model is not a web search engine, source of verified facts or general autonomous agent. Check context capacity where available and reserve space for instructions, schemas, tools and the output. File size alone does not prove a document fits.

Text and PDF input reaches the model as extracted text. Image input uses Vision OCR, classification and barcodes; native multimodal attachments remain disabled, so arbitrary visual reasoning is unavailable.

These examples were reviewed against the source and were not run during this documentation update. Try them with your app’s supported devices, languages and inputs before shipping.

References and next steps

• Apple Foundation Models
• Full usage reference
• Example application
• Document extraction example
• Choosing a local or cloud AI approach
• API reference
• Report an integration issue