Chapters
Chapters

Chapters

Hide chapters

Apple Foundation Models

First Edition · iOS 26.5 · Swift 6.3 · Xcode 26.4

Before You Begin

Section 0: 5 chapters
Show chapters Hide chapters

Section I: Apple Foundation Models

Section 1: 9 chapters
Show chapters Hide chapters

5. Guided Generation
Written by Bill Morefield

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now

To this point in the book, you’ve produced a text response for each prompt in Foundation Explorer. Given that the app is by nature a chat-style app, a text response was a logical choice. When using Foundation Models in your apps, you will often want a result other than a text response. For this, Apple Foundation Models supports the generating parameter when calling either the LanguageModelSession respond(to:options:) or streamResponse(to:options:) methods. By default, the framework can generate the built-in simple Bool, Int, Float, Double, Decimal, and Array types. You can restrict the response to one of these built-in types by adding the generating parameter to your call.

Open the starter project for this chapter. You’ll see a new project that lets you select meal options. You will expand this app to use Foundation Models to build a dining menu in this chapter. The app lets the user select breakfast, lunch, dinner, or dessert. You can then select a cuisine type for the menu. The next step will be to select the menu ingredients, but the app doesn’t generate them yet.

Menu Generation App
Menu Generation App

You will also see a toolbar button that will allow you to view the current transcript of the session property of this view. It starts with a default LanguageModelSession, but you’ll later tie this session into the menu generation.

While there are times when producing a built-in type is helpful, the true power of this guided generation comes when you define your data structure and provide guidance on generating it. While generating data with LLMs has always been possible with the right prompts, this has typically required careful tuning to produce a format such as JSON and meticulous text parsing. The native inclusion of this ability may be the most important feature of Foundation Models compared to general-purpose LLMs.

Imagine a scenario where you want to provide a realistic menu in a game when the player enters a restaurant. You could enter a prompt in the Foundation Explorer app from earlier chapters, such as:

Create a lunch menu for a casual dining restaurant.

The result will be a plausible menu that reads like a wall of text. For a case where the user only needs to read the result, this works fine. But if you want to put this into a data structure, you need to parse the result. Traditionally, you’d do this by producing the information in JSON. You would need to refine your prompts to create a format that you can interpret as a structure. Instead, you will let Foundation Models do this work for you.

Menu created by asking Foundation Explorer app.
Menu created by asking Foundation Explorer app.

Before using guided generation, you must first define the data structures to fill with the generated information. Create a new file under the Models folder named CuisineIngredients.swift and replace the code with:

import SwiftUI
import FoundationModels

struct CuisineIngredients {
  let ingredients: [String]
}

This is a pretty simple structure that contains a single string array property called ingredients. Open FoodMenuView.swift. Add the following new method after generateCuisineList():

func generateIngredients() -> [String] {
  return ["salmon", "beef", "mushrooms", "salt"]
}

This is about as simple a list as you could create. You return four static string ingredients. Now, to call this method, find the Task modifier on the VStack that contains the view just before the navigationTitle("Menu Maker") modifier. Add the following code after the Task and before navigationTitle:

.onChange(of: cuisine) { _ , _ in
  selectedIngredients = []
  ingredientList = generateIngredients()
}

Whenever the user selects a different cuisine from the picker, this method clears the selected ingredients, then calls the new generateIngredients() method. Run the app and select a cuisine. You’ll see those four ingredients. Tap any ingredient, and you’ll see a check appear next to it. Tap an ingredient again to unselect it.

Ingredient Selection
Ingredient Selection

Now that you’ve explored the user interface, you’ll adapt the app to generate a list of ingredients for the selected cuisine.

Generating Custom Data Structures

Foundation Models provides two macros that let you assist the model and guide the generated data. The first is Generable(description:), which marks structures and enumerations for guided generation and provides context to the model. You will use it along with Guide(description:) on each property in these Generable types. The framework allows nesting Generable types to support complex data hierarchies.

Foundation Models require Generable(description:) for any type that you wish to create. To see this, add the following code above the definition of CuisineIngredients:

@Generable(description: "A list of ingredients common in a specific type of cuisine.")

The parameter to the Generable macro is a textual description of the data structure’s purpose. To provide more guidance for the properties of the structure, use Guide(description:). Add the following code before the ingredients property:

@Guide(description: "A list of individual food ingredients.")

With these defined, you can now use Foundation Models to generate the ingredient list. Go back to FoodMenuView.swift and replace generateIngredients() with:

func generateIngredients() async -> [String] {
  // 1
  guard cuisine != "N/A" else { return [] }
  isGenerating = true
  defer { isGenerating = false }
  
  // 2
  let ingredientPrompt = """
    Give me a list of ingredients used in \(cuisine) for \(selectedMeal).
    Do not repeat ingredients. Do not provide examples of ingredients.
    """
  let session = LanguageModelSession()
  
  // 3
  let response = try? await session.respond(to: ingredientPrompt, generating: CuisineIngredients.self)
  
  // 4
  if let response = response {
    return response.content.ingredients
  } else {
    return []
  }
}

Most of this should look familiar from the earlier chapters. You change the method to async as with most methods related to Foundation Models. Inside the method, you:

  1. You ensure the user has selected a cuisine, then set a property to show an indicator that the app is working. Even with asynchronous streaming responses, an indicator helps the user feel the app is more responsive.
  2. This prompt asks for a list of ingredients, and fills in the type of cuisine and meal from the values selected in the view. A simple prompt will suffice thanks to guided generation. Without it, you would need a lengthy prompt that specifies a format and provides examples to get useful results. Note that since the user selects cuisine and selectedMeal from a list of choices, you avoid many of the risks of user-generated content while still allowing users to make choices.
  3. The significant change to this method is adding the generating: CuisineIngredients.self parameter when calling respond(to:generating:includeSchemaInPrompt:options:). This tells Foundation Models to produce a structure of the CuisineIngredients you defined. Note that you must mark this type as Generable, which you did by adding the macro earlier.
  4. As before, when using the try? await pattern, you attempt to unwrap the returned value. If successful, you access the returned CuisineIngredients struct through response.content. Since you only need the string array with the ingredients, you return the generated ingredients property. If the unwrap failed, you return an empty array.

You need to make one more change since this method is now async. Find your call to generateIngredients() inside the view and change it to:

Task {
  ingredientList = []
  selectedIngredients = []
  await ingredientList = generateIngredients()
}

This change first wraps the code inside a Task. Since generating ingredients takes a few seconds, you clear the ingredients array first. After clearing the selected ingredients, you add an await call to the now asynchronous method.

Run the app, select a meal and cuisine from the menu. After a few seconds, an appropriate ingredient list will appear.

Generated French Dinner Ingredients in French
Generated French Dinner Ingredients in French

Depending on the combination you chose, you could see a large number of ingredients. It would be useful to narrow this list a bit. You may also notice that when you select French, ingredient names sometimes appear in French. Let’s adjust both of those. Go back to CuisineIngredients.swift and change the declaration of ingredients to:

@Guide(description: "An array of individual ingredients specified by their English name.", .count(10...15))
let ingredients: [String]

The description now specifies that ingredients should be in English, which should give you “chicken” instead of “poulet”. The .count(10...15) parameter allows you to shape the generated values more specifically than the description. You can apply the .count(10...15) parameter to @Guide to an array providing a closed range. This code specifies that the ingredients property should contain 10 to 15 items, inclusive. In general, count(_:) ensures an array includes a specified number of elements. You can specify these in addition to or instead of the description. This example applied both the description and count(_:) in one macro. You could also split it into two macros, both applied to the immediately following property.

Run the app to see your changes. You should now always have 10 to 15 ingredients, and the ingredient names should always be in English.

Adjust ingredients to ensure English and produce 10 to 15 ingredients.
Adjust ingredients to ensure English and produce 10 to 15 ingredients.

There are several more common properties to add restrictions for generated data:

  • Arrays can also specify .maximumCount(_:), which specifies a maximum length of the array, and .minimumCount(_:), which specifies a minimum length for the array.
  • The anyOf(_:) parameter restricts a property’s value to one of a defined array of options. The format would resemble @Guide(.anyOf(["Apple", "Banana", "Grape", "Strawberry"])).
  • For String properties, you can specify the pattern(_:) parameter that ensures the string follows a specified regular expression.
  • The Int type allows you to specify minimum(_:) or maximum(_:) values or a range(_:) to constrain the value.

Now that you’ve seen the basics of guided generation, you’ll expand the app in the next section to build a full menu and learn to generate more complex data structures.

Guided Generation on Complex Structures

Open the Models folder. In addition to the CuisineIngredients.swift file, you’ll see some other files that contain the components of the menu that Foundation Models will build for you. The MealType enumeration defines the different meal types. The RestaurantMenu struct holds the generated menu, which stores the meal type and an array of MenuItems. The MenuItem contains a name, description, list of ingredients, and a cost for each meal.

@Generable(description: "A menu of offerings for a restaurant for a single meal.")

@Generable

@Generable(description: "A single dish for a restaurant menu.")

@Generable(description: "A single dish for a restaurant menu.")
struct MenuItem {
  @Guide(description: "Name for this dish.")
  let name: String

  @Guide(description: "The description of this dish in a style appropriate for a restaurant menu.")
  let description: String

  @Guide(description: "The main ingredients for this dish.")
  let ingredients: [String]

  @Guide(description: "A cost for this dish in US dollars, which should be appropriate for the ingredients", )
  let cost: Decimal
}

@Generable(description: "A menu of offerings for a restaurant for a single meal.")
struct RestaurantMenu {
  let type: MealType

  @Guide(description: "A list of menu items, appropriate for the selected type of meal.", .count(4...8))
  let menu: [MenuItem]
}

@State private var menu: RestaurantMenu?

func createSession() {
  let instructions = """
    You are generating a simple, plausible restaurant menu for a restaurant in a game.
    The menu must match the given cuisine and meal type.
    Use at least ONE ingredient from the provided ingredient list, but you may include additional ingredients beyond the provided list.
    Avoid repeating the same primary ingredient across all dishes.
  """
  session = LanguageModelSession(instructions: instructions)
}

// 1
func generateLunchMenu() async {
  isGenerating = true
  defer {
    isGenerating = false
  }

  // 2
  let prompt = """
    Create a menu for \(selectedMeal) at a \(cuisine)) restaurant.
    Each meal on the menu must include one of the following ingredients: \(selectedIngredients.joined(separator: ", "))

    Requirements:
    - Each dish must include at least ONE of the available ingredients.
    - Dishes should be appropriate for the cuisine and meal type.
    - Keep items simple, recognizable, and realistic (not overly complex or experimental).
    - Vary the primary ingredients across dishes when possible.
    - Prices should feel reasonable for a casual restaurant in USD.
    """
  // 3
  let response = try? await session.respond(to: prompt, generating: RestaurantMenu.self)
  // 4
  menu = response?.content
}

withAnimation {
  showControls = false
}
Task {
  createSession()
  await generateLunchMenu()
}

if let menu = menu {
  Text("\(menu.type.rawValue.capitalized) Menu")
    .font(.headline.bold())
  ForEach(menu.menu, id: \.name) { item in
    MenuItemView(menuItem: item)
    Divider()
  }
}
Complete generated menu.
Keblbuno jakonuzes kuhi.

Transcript after generating menu.
Lqejypsugf axwan kolibalosh pujo.

Streaming Guided Generation

To use guided generation with streaming, the response begins with the same changes you made in Chapter Two to stream the text response. Replace the current call to respond(to:) in generateLunchMenu() after comment three with:

let streamedResponse = session.streamResponse(to: prompt, generating: RestaurantMenu.self)

do {
  for try await partialResponse in streamedResponse {
    menu = partialResponse.content
  }
} catch {
  print(error.localizedDescription)
}

@State private var menu: RestaurantMenu.PartiallyGenerated?

if let menu = menu {
  if let type = menu.type {
    Text("\(type.rawValue.capitalized) Menu")
      .font(.headline.bold())
  }
  if let menuitems = menu.menu {
    ForEach(menuitems, id: \.name) { item in
      MenuItemView(menuItem: item)
      Divider()
    }
  }
}

var menuItem: MenuItem.PartiallyGenerated

VStack {
  HStack {
    Text(menuItem.name ?? "")
      .font(.headline.bold())
    Spacer()
    if let cost = menuItem.cost {
      Text(cost, format: .currency(code: "USD"))
        .font(.headline)
    }
  }
  .font(.title3)
  Text(menuItem.description ?? "")
    .frame(maxWidth: .infinity, alignment: .leading)
    .padding(.leading, 15.0)
    .font(.subheadline)
    .foregroundStyle(.secondary)
  if let ingredients = menuItem.ingredients {
    Text(ingredients.joined(separator: " • "))
      .font(.caption)
      .foregroundStyle(.tertiary)
  }
}
.padding(.vertical, 10)

MenuItemView(
  menuItem: item.asPartiallyGenerated()
)
Menu streaming as it is generated.
Yoho yfguorukx of iw iv hohekewec.

Dynamic Guided Generation

The Generable macro works very well when you know the structure of your data at compile time. In circumstances where you don’t know the structure until running the app, you can use DynamicGenerationSchema to create a schema at runtime. This produces a result similar to what you’ve done. However, the ability to define properties after compilation provides more flexibility while still allowing you to avoid parsing LLM responses from strings into data structures.

@State private var specialIngredients = [String]()

specialIngredients = []

@Binding var specialIngredients: [String]

@Previewable @State var specialIngredients: [String] = []

  MenuOptionsView(
    /* Existing code */
    specialIngredients: $specialIngredients
  )

Text("Special Ingredients")
  .font(.subheadline)
  .foregroundStyle(.secondary)
  .textCase(.uppercase)
if !ingredientList.isEmpty {
  MultiSelectView(
    options: ingredientList,
    selections: $specialIngredients,
    maxSelect: 3
  )
}
Divider()

MenuOptionsView(
  mealtimes: mealtimes,
  selectedMeal: $selectedMeal,
  cuisineList: cuisineList,
  cuisine: $cuisine,
  ingredientList: ingredientList,
  selectedIngredients: $selectedIngredients,
  specialIngredients: $specialIngredients
)

func generateMenuSpecial() async {
  isGenerating = true
  defer {
    isGenerating = false
  }

  // 1
  let specialMealSchema = DynamicGenerationSchema(
    name: "specialmenuitem",
    // 2
    properties: [
      // 3
      DynamicGenerationSchema.Property(
        name: "ingredients",
        // 4
        schema: DynamicGenerationSchema(
          name: "ingredients",
          anyOf: specialIngredients
        )
      ),
      // 5
      DynamicGenerationSchema.Property(
        name: "name",
        schema: DynamicGenerationSchema(type: String.self)
      ),
      DynamicGenerationSchema.Property(
        name: "description",
        schema: DynamicGenerationSchema(type: String.self)
      ),
      DynamicGenerationSchema.Property(
        name: "price",
        schema: DynamicGenerationSchema(type: Decimal.self)
      )
    ]
  )
}

// 1
let schema = try? GenerationSchema(root: specialMealSchema, dependencies: [])
// 2
guard let schema = schema else { return }
// 3
let specialPrompt = """
  Create a special dish for \(selectedMeal) at a \(cuisine)) restaurant.

  Requirements:
  - Each dish must include at least ONE of the available ingredients.
  - The dishes should be appropriate for the cuisine and meal type.
  - This is the place to try more unique and authentic meals.
  - Prices may be a bit more expensive than expected at a casual restaurant in USD.
"""
let response = try? await session.respond(to: specialPrompt, schema: schema)

let name = try? response?.content.value(String.self, forProperty: "name")
let ingredients = try? response?.content.value(String.self, forProperty: "ingredients")
let description = try? response?.content.value(String.self, forProperty: "description")
let price = try? response?.content.value(Decimal.self, forProperty: "price")
let specialItem = MenuItem(
  name: name ?? "",
  description: description ?? "",
  ingredients: ingredients == nil ? [] : [ingredients!],
  cost: price ?? 0.0
)

special = specialItem

@State var special: MenuItem?

await generateMenuSpecial()

if let special = special {
  VStack {
    Text("Today's Special")
      .font(.title2)
    MenuItemView(
      menuItem: special.asPartiallyGenerated()
    )
  }
  .featuredCard()
  .padding(.bottom, 8)
}
Including the Dynamically Generated Menu Item
Oqrxojabl bve Rrvokiganvv Woqoperiv Huhe Iyiw

Challenge

The app uses an asynchronous response to generate the dynamic content. Update the app to stream the response. As a hint, create a new view to handle the GeneratedContent view. See the challenge project for one solution.

Conclusion

In this chapter, you’ve explored the rich offering of guided generation capabilities in Apple’s Foundation Models framework, starting with simple types and producing basic structured data. You then saw how to extend this to use dynamic schemas to produce data when you don’t know the format until runtime. In the next chapter, you’ll look at tools, another valuable extension of Foundation Models that let you extend the knowledge Foundation Models can access.

Key Concepts

  • Guided generation eliminates the need for error-prone text parsing while maintaining full type safety.
  • Swift built-in types already include support for guided generation.
  • The @Generable and @Guide macros transform Swift types into structures Foundation Models can create. Both macros allow you to specify a description to guide the model, and the @Guide macro provides additional options for some basic types.
  • Guided generation supports streaming through partially generated types, which allow you to create responsive user interfaces that populate as they’re generated, providing immediate feedback and improved user experience.
  • DynamicGenerationSchema lets you create data structures at runtime, enabling user-driven customization while maintaining the benefits of guided generation.
4. Context Management & Model Safety
6. Building Tools for Foundation Models
Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.
© 2026 Kodeco Inc.

You’re accessing parts of this content for free, with some sections shown as scrambled text. Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now