Foundation Lab: a workbench for Apple's Foundation Models framework

What Foundation Lab solves for Apple Intelligence developers

Apple's Foundation Models framework exposes an on-device model through Swift APIs, and the hard part is rarely the first call. It is the tenth: which instruction wording changed the output, which tool the model decided to invoke, how many tokens the context window had left when the answer degraded. Foundation Lab is built around that question. The README describes it as keeping "the prompt, configuration, tools, transcript, and run evidence in one place," and the Runs destination is where that evidence lands: persisted run status, configuration, transcript events, tool calls, timing, and token usage.

The audience is narrow and specific. You need a Mac with Apple Silicon, iOS 26.0 or macOS 26.0, Apple Intelligence enabled, and Xcode 26.6 or Xcode 27. That combination excludes anyone on Intel hardware and anyone targeting an older deployment version. For the people inside it, the app is a way to move between two modes: open a working recipe, change one thing, run it immediately, or compose custom prompts and tools from scratch and export reproducible evidence. The Library ships 18 editable recipes, 14 guided labs, three workshops, saved experiments, and one workspace, which is enough surface that you should expect to spend the first session browsing rather than building.

Library, Playground, Runs: how the three destinations divide the work

The architecture is a three-destination app, and understanding the split saves time. Library is the catalogue, and every entry declares how it opens. A Recipe opens in Playground, where it can be edited, run, and saved. A Guided Lab uses a focused interface for one specific Foundation Models API, which matters because some APIs do not fit a generic prompt-and-run form. A Workshop groups related schema, language, or Xcode 27 examples without adding a fourth top-level destination. A Workspace opens a dedicated tool, and Adapter Comparison is the one listed.

Playground is the editing surface: prompts and instructions, model and tool configuration, streaming responses, voice input, saved experiments, and Swift export of the configuration. Runs is the read side. Because run history is persisted, you can compare a configuration you tried yesterday against one you just changed, which is the whole point of keeping transcript events and token usage next to each other rather than in a console log.

Underneath, the repository separates the UI from the logic. FoundationLabCore holds UI-independent requests, results, use cases, providers, and experiment models. That is a deliberate boundary: if you want to reuse the request and result types in your own target, you do not have to drag the SwiftUI layer along. The transcript, context, history, and system-tool work lives in an external package, rryam/FoundationModelsKit, rather than inside the app.

Installing Foundation Lab and running a first recipe

There is no package manager step. The README's getting-started sequence is a clone, a directory change, and opening the Xcode project:

 git clone https://github.com/rudrankriyam/Foundation-Models-Framework-Lab.git
 cd Foundation-Models-Framework-Lab
 open FoundationLab.xcodeproj

If you would rather confirm the project compiles before touching the UI, the README gives command-line builds for both platforms. Note the scheme name, which contains a space, and the CODE_SIGNING_ALLOWED=NO flag that lets the build run without a signing identity:

 xcodebuild \
   -project FoundationLab.xcodeproj \
   -scheme 'Foundation Lab' \
   -destination 'generic/platform=macOS' \
   CODE_SIGNING_ALLOWED=NO \
   build

The README also gives the iOS variant with -destination 'generic/platform=iOS Simulator'. A successful build here proves compilation only. The README is explicit that live model execution requires a compatible physical device and that simulator builds remain useful for compilation and interface validation.

Once the app is running on a device, the shortest path to a real result is Library, then a Recipe, then Playground. Pick one of the 18 recipes, change a single instruction or sampling value, and run it. The response streams into Playground, and the run is written to Runs. Open Runs and you should see the configuration you used, the transcript events, any tool calls, timing, and token usage. That loop, edit one thing, run, read the evidence, is the workflow the app is designed around.

Nine tool recipes and the confirmation boundary on user data

The built-in tools are the part most likely to save you a week, and they all use a shared FoundationModelsTools package. The README lists nine: Weather through Open-Meteo, Keyless Search1 web search, Contacts, Calendar, Reminders, Location and place search, Authorized HealthKit data, Apple Music, and Web metadata. Tool recipes open in Playground, where they can be combined or removed, so the mental model is composition rather than a fixed pipeline.

The design decision worth noting is the confirmation boundary. The README states that tools which can change user data require confirmation through an app-owned workflow. That is a sensible default for Contacts, Calendar, and Reminders, and it also means you cannot treat these tools as silent background callers. If your product needs an unattended agent that writes to the calendar, this app demonstrates the pattern but does not give you a bypass.

The HealthKit side goes further than a tool. There is a HealthKit dashboard and a chat grounded only in authorized Health data. Health data is a category where an unconstrained model call is a liability, and scoping retrieval to what the user authorized is the right shape. Whether the authorization flow covers every case your app needs is something you would have to read the lab itself to judge; the README does not enumerate the HealthKit types involved.

Structured output, RAG, and the language surface

For anything beyond free-text chat, the app covers @Generable models and @Guide constraints, dynamic schemas, nested objects, unions, forms, and invoice extraction. The @Generable and @Guide pair is the framework's mechanism for making the model emit a typed Swift value rather than prose you have to parse, and having a lab that exercises nested and union cases is more useful than a single flat example, because that is where schema design usually breaks.

Retrieval is present as RAG document indexing and semantic retrieval with LumoKit and VecturaKit. Two separate retrieval packages is an unusual choice and the README does not explain the division of labour between them, so treat that as an open question rather than a documented design. Multilingual sessions and supported-language inspection are also listed, which is the right place to start if your app ships outside English, since the set of supported languages is a runtime property rather than something you can assume.

The Xcode 27 labs sit on top of this and are availability-gated. Built with Xcode 27, the app demonstrates PrivateCloudComputeLanguageModel, shared LanguageModel execution, image attachments and references, explicit tool-calling modes, dynamic profiles and reasoning controls, transcript inspection and history transforms, context-budget visualization, and custom model executors including a video-capable provider bridge. The README notes that APIs introduced with the OS 27 SDK are compiler- and availability-gated so the core app stays usable with Xcode 26. That is a real constraint on what you can copy: if you are still on Xcode 26.6, those labs are visible in the repository but not runnable in your build.

Adapter Comparison and the fmas CLI split

Adapter Comparison is the one workspace, and it is macOS-only. You import a .fmadapter package and run the same prompt through fresh base-model and adapter sessions, with both streams shown side by side and diagnostic time-to-first-token and total-duration measurements. Showing the base model alongside the adapted one is the right control: an adapter that improves tone but costs latency is a different decision than one that improves accuracy for free, and the workspace surfaces both numbers.

What it does not do is train. Training and export live in a companion fmas CLI, and the README's setup runs through a Python 3.11 virtual environment:

 python3.11 -m venv .venv-fmas
 source .venv-fmas/bin/activate
 python -m pip install -e Tools/AdapterStudio
 fmas init
 fmas setup
 fmas train-adapter --help
 fmas export --help

That is a second toolchain with its own Python dependency, and it is not installed by opening the Xcode project. Budget for it separately. The README points to Tools/AdapterStudio for the full workflow rather than documenting the training flags inline, and neither fmas init nor fmas setup is explained beyond the command names, so the first run will involve reading that directory.

The older afm CLI has moved out entirely. It now ships from the standalone rudrankriyam/Foundation-Models-Framework-CLI repository, uses the public FoundationModelsKit package, and keeps CLI releases independent from app releases. Installation is a Homebrew tap:

 brew tap rudrankriyam/tap
 brew install afm

If your goal is scripting rather than exploring, that repository is where you should start, not this one.

Where Foundation Lab is the wrong tool

The clearest limitation is hardware and OS. Apple Silicon is required for on-device model execution, the floors are iOS 26.0 and macOS 26.0, and Apple Intelligence must be enabled for live runs. There is no documented fallback for an Intel Mac or an older OS, and no server-side execution path in the app. If your team's machines do not meet those requirements, this repository is a reading exercise.

The second limitation is that it is an app, not a library. FoundationLabCore is UI-independent and reusable, but the README does not present it as a published package with a versioning policy or a documented API surface. If you want a dependency you can pin in Package.swift, the external packages it points at, FoundationModelsKit and the CLI repository, are the better candidates.

Third, the evidence is local. Runs are persisted in the app, and the README describes exporting reproducible evidence and Swift export for Playground configurations, but it does not describe a CI integration, a headless runner, or a way to diff runs across machines. For a lab that is fine. For a regression suite it is not, and FoundationModelsBench is listed as a separate repository for quality, safety, tool-use, and on-device evaluation. If your actual need is scoring models rather than poking at prompts, go there.

Finally, the documentation has gaps. The README does not document rollback of a saved experiment, does not enumerate HealthKit types, and does not explain the split between LumoKit and VecturaKit.

Maintenance, licensing, and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-25. Releases are versioned and recent: 1.0.0 on 2026-06-20, 1.1.0 on 2026-06-22, and 1.2.0 on 2026-06-23, which is a tight cluster followed by a quieter period of pushes. That pattern is consistent with a project that stabilised its app surface and is now tracking SDK changes rather than adding features weekly.

The upgrade cost is dominated by Xcode. The README states the project builds with both Xcode 26.6 and Xcode 27, with OS 27 APIs compiler- and availability-gated. That gating is what keeps the core app usable on the older toolchain, but it also means the Xcode 27 labs are conditional code you cannot exercise until you move. Expect the interesting new surface to arrive with each SDK cycle, and expect your ability to follow it to be tied to your Xcode version rather than to a Foundation Lab release number.

Licensing is MIT, which is permissive and imposes no obligation on the app you build alongside it. Two caveats are worth stating without giving legal advice. First, the built-in tools call third-party services, including Open-Meteo and the Keyless Search1 web search, and those services carry their own terms that MIT does not cover. Second, the repository depends on external packages, FoundationModelsKit, LumoKit, and VecturaKit among them, whose licences are separate from this project's. Check those before shipping anything derived from a tool recipe.

Editorial conclusion

Adopt Foundation Lab if you already have an Apple Silicon Mac or device on iOS 26.0 or macOS 26.0, Apple Intelligence enabled, and you want to see what a prompt, a tool call, or a schema change actually does before committing it to your own target. Skip it if you need a headless, scriptable path: the afm CLI lives in a separate repository, and the Adapter Comparison workspace is macOS-only. Verify three things first: that your machine meets the Apple Silicon and OS floors, that you can open FoundationLab.xcodeproj with Xcode 26.6 or Xcode 27, and that a physical device is available, because the README states that live model execution requires one and simulator builds only cover compilation and interface validation.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. rudrankriyam/Foundation-Models-Framework-Lab on GitHub