flutter_foundation_models library

Flutter Foundation Models - A direct port of Apple's Foundation Models framework.

This package provides a Flutter interface to Apple's on-device language model, available on iOS 26+ and macOS 26+. The API mirrors Swift's native Foundation Models framework as closely as possible.

Design Philosophy

This package is a direct port of Swift's Foundation Models API:

Swift	Dart
`SystemLanguageModel.default`	`SystemLanguageModel.defaultModel`
`session.respond(to:)` → `Response<String>`	`session.respondTo()` → `TextResponse`
`session.respond(to:generating:)` → `Response<T>`	`session.respondToWithSchema()` → `StructuredResponse`
`@Generable` macro	`@Generable()` annotation + codegen

Quick Start

import 'package:flutter_foundation_models/flutter_foundation_models.dart';

if (await SystemLanguageModel.isAvailable) {
  final session = await LanguageModelSession.create();
  final response = await session.respondTo("What is Flutter?");
  print(response.content);
  session.dispose();
}

Structured Output

Define data models with @Generable:

@Generable(description: "A movie recommendation")
class Movie {
  @Guide(description: "Movie title")
  final String title;

  @Guide(description: "Year released")
  final int year;

  Movie({required this.title, required this.year});
}

Generate structured content:

final response = await session.respondToWithSchema(
  "Recommend a sci-fi movie",
  schema: $MovieGenerable.generationSchema,
);
final movie = $MovieGenerable.fromGeneratedContent(response.content);
print('${movie.title} (${movie.year})');

Generating Lists

Generate arrays using GenerationSchema.array:

final response = await session.respondToWithSchema(
  "Recommend 3 sci-fi movies",
  schema: GenerationSchema.array(
    $MovieGenerable.generationSchema,
    minimumElements: 3,
  ),
);
final movies = response.content.toList($MovieGenerable.fromGeneratedContent);

Streaming

For real-time UI updates:

// Text streaming
session.streamResponseTo("Tell me a story").listen((text) {
  print(text);
});

// Structured streaming
session.streamResponseToWithSchema(
  "Generate a story",
  schema: $StoryGenerable.generationSchema,
).listen((partial) {
  final story = $StoryGenerable.fromPartialGeneratedContent(partial);
  print(story.title ?? "Loading...");
});

Tools

Enable the model to call your functions:

class WeatherTool extends Tool {
  @override
  String name = "getWeather";

  @override
  String description = "Get weather for a city";

  @override
  GenerationSchema get parameters => $WeatherArgsGenerable.generationSchema;

  @override
  Future<GeneratedContent> call(GeneratedContent arguments) async {
    final args = $WeatherArgsGenerable.fromGeneratedContent(arguments);
    return WeatherResult(city: args.city, temp: 72).toGeneratedContent();
  }
}

final session = await LanguageModelSession.create(tools: [WeatherTool()]);

Transcripts

Persist and restore conversation history:

final transcript = await session.transcript;
final json = transcript.toJson();  // Store this

// Later, restore:
final restored = Transcript.fromJson(json);
final newSession = await LanguageModelSession.createWithTranscript(
  transcript: restored,
);

Error Handling

try {
  final response = await session.respondTo("...");
} on GenerationException catch (e) {
  print('${e.type}: ${e.message}');
}

Classes

Adapter: A model adapter for customizing language model behavior.
AnyOfGenerationSchema: Schema for union types (one of several possible schemas).
AnyOfGuide: Constrains a String field to one of the specified values.
AnyOfStringsGenerationSchema: Schema for enum-like string values.
ArrayGenerationSchema: Schema for array/list types.
ConstantGuide: Constrains a String field to an exact constant value.
ConvertibleToGeneratedContent: Interface for types that can be converted to GeneratedContent.
CountRangeGuide: Constrains an array field to a range of element counts.
DynamicGenerationSchema: Base class for dynamic generation schema types.
DynamicGenerationSchemaProperty: A property definition within a StructGenerationSchema.
ElementGuide: Applies a guide to each element of an array.
ExactCountGuide: Constrains an array field to an exact number of elements.
Generable: Marks a class or enum as generable by the Foundation Models.
GenerationGuide: Base class for generation guides that constrain output values.
GenerationOptions: Options for controlling text generation behavior.
GenerationSchema: Defines the structure for generated content output.
GreedySamplingMode: Greedy sampling mode - always picks the most likely token.
Guide: Provides guidance for a field in a @Generable class.
LanguageModelSession: A session for interacting with Apple's on-device Foundation Models.
MaximumCountGuide: Constrains an array field to a maximum number of elements.
MaximumGuide: Constrains a numeric field to a maximum value.
MinimumCountGuide: Constrains an array field to a minimum number of elements.
MinimumGuide: Constrains a numeric field to a minimum value.
ModelAvailability: Represents the availability status of the language model.
PatternGuide: Constrains a String field to match a regex pattern.
RangeGuide: Constrains a numeric field to a range of values.
SamplingMode: Sampling mode for text generation.
StructGenerationSchema: Schema for structured objects with named properties.
StructuredResponse: Response from structured generation.
SystemLanguageModel: Represents a system language model for on-device AI.
TextResponse: Response from text generation.
Tool: Base class for defining tools that can be called by the language model.
TopKSamplingMode: Top-K sampling mode - samples from the top K most likely tokens.
TopPSamplingMode: Top-P (nucleus) sampling mode.
Transcript: A transcript containing the conversation history of a session.
TranscriptEntry: Base class for transcript entries.
TranscriptInstructions: System instructions entry.
TranscriptPrompt: User prompt entry.
TranscriptResponse: Model response entry.
TranscriptSegment: Base class for transcript segments.
TranscriptStructuredSegment: Structured segment containing generated content.
TranscriptTextSegment: Text segment containing plain text content.
TranscriptToolCall: A single tool call.
TranscriptToolCalls: Tool calls entry (model requesting tool invocations).
TranscriptToolDefinition: Tool definition in transcript.
TranscriptToolOutput: Tool output entry (result from a tool invocation).
TranscriptUnknown: Unknown entry type (for forward compatibility).
ValueGenerationSchema: Schema for primitive value types.

Enums

GenerationErrorType: Types of generation errors that can occur.
Guardrails: Guardrails setting for the language model.
UseCase: Use case for the language model.

Extension Types

GeneratedContent: A wrapper for content generated by the language model.

Extensions

GenerationOptionsInternal on GenerationOptions

Exceptions / Errors

GenerationException: Exception thrown when generation fails.

flutter_foundation_models library

Design Philosophy

Quick Start

Structured Output

Generating Lists

Streaming

Tools

Transcripts

Error Handling

Classes

Enums

Extension Types

Extensions

Exceptions / Errors

flutter_foundation_models package

flutter_foundation_models library