Foundation Lab：Apple Foundation Models 框架的原生 iOS/macOS 实验工作台

Foundation Lab is a native iOS and macOS workbench for learning, testing, and shipping with Apple's Foundation Models framework. It keeps the prompt, configuration, tools, transcript, and run evidence in one place while still providing focused labs for APIs that need a specialized interface.

The app is designed for two complementary workflows:

Open a working recipe, change one thing, and run it immediately.
Compose custom prompts and tools, inspect every run, compare adapters, and export reproducible evidence from the app.

Library

App Structure

Foundation Lab has three primary destinations:

Destination	Purpose
Library	Browse 18 editable recipes, 14 guided labs, three workshops, saved experiments, and one workspace.
Playground	Edit prompts and instructions, configure the model and tools, stream responses, use voice input, save experiments, and export Swift.
Runs	Inspect persisted run status, configuration, transcript events, tool calls, timing, and token usage.

Library entries identify how they open:

Recipe opens in Playground and can be edited, run, and saved.
Guided Lab uses a focused interface for a specific Foundation Models API.
Workshop groups related schema, language, or Xcode 27 examples without adding another top-level destination.
Workspace opens a dedicated tool such as Adapter Comparison.

Requirements

iOS 26.0+ or macOS 26.0+
watchOS 27.0+ for the Foundation Lab Watch companion, which ships inside the iOS app and runs prompts on Private Cloud Compute
Apple Silicon for on-device model execution
Apple Intelligence enabled for live model runs
Xcode 27.2 or later

The app still runs on OS 26. APIs introduced with OS 27 are availability-gated, so the newest labs appear only on an OS 27 runtime.

Getting Started

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

Build from the command line:

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

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

Live model execution requires a compatible physical device. Simulator builds remain useful for compilation and interface validation.

Capabilities

Experiments and conversations

Streaming multi-turn conversations with context-window management
Editable instructions, sampling, response limits, runtime, and reasoning controls
Saved experiment configurations and persistent run history
Swift export for Playground configurations
Speech recognition and synthesis integrated into Playground

Built-in tools

Nine ready-made tool recipes use the shared FoundationModelsTools package:

Weather through Open-Meteo
Keyless Search1 web search
Contacts
Calendar
Reminders
Location and place search
Authorized HealthKit data
Apple Music
Web metadata

Tool recipes open in Playground, where tools can be combined or removed. Tools that can change user data require confirmation through the app-owned workflow.

Structured output and applied projects

@Generable models and @Guide constraints
Dynamic schemas, nested objects, unions, forms, and invoice extraction
Multilingual sessions and supported-language inspection
RAG document indexing and semantic retrieval with LumoKit and VecturaKit
A HealthKit dashboard and chat grounded only in authorized Health data

Xcode 27 labs

When built with Xcode 27, Foundation Lab also 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
Custom model executors, including a video-capable provider bridge

The image-input probe under Tools/ImageInputProbe can measure the current SDK's practical decoded-buffer boundary.

Workspaces

Adapter Comparison

On macOS, import a .fmadapter package and run the same prompt through fresh base-model and adapter sessions. The workspace shows both streams and diagnostic time-to-first-token and total-duration measurements.

Training and export remain in the companion fmas CLI:

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

See Tools/AdapterStudio for the full workflow.

Command-Line Interface

The afm CLI now ships from the standalone rudrankriyam/Foundation-Models-Framework-CLI repository. It uses the public FoundationModelsKit package and keeps CLI releases independent from Foundation Lab app releases.

brew tap rudrankriyam/tap
brew install afm

See the CLI repository for source, documentation, release automation, and server-mode implementation.

Repository Map

Surface	Location	Purpose
Foundation Lab	`Foundation Lab`	Native Library, Playground, Runs, guided labs, and workspaces
FoundationLabCore	`FoundationLabCore`	UI-independent requests, results, use cases, providers, and experiment models
FoundationModelsKit	`rryam/FoundationModelsKit`	External transcript, context, history, and system-tool package
AFM CLI	`rudrankriyam/Foundation-Models-Framework-CLI`	Scriptable Foundation Models workflows
FoundationModelsBench	`rudrankriyam/FoundationModelsBench`	External quality, safety, tool-use, on-device, and Private Cloud Compute benchmark
Adapter tooling	`Tools/AdapterStudio`	Adapter training and export with `fmas`
Book playgrounds	`BookPlaygrounds`	Chapter-oriented `#Playground` examples

FoundationModelsBench and the AFM CLI are developed and released from their standalone repositories. Foundation Lab keeps the native app, app runtime, and adapter tooling here.

Swift Package Products

FoundationModelsKit and FoundationModelsTools are defined in the external rryam/FoundationModelsKit package. Local package consumers should depend on that package URL directly rather than requesting those products from this repository's root manifest.

FoundationModelsKit provides transcript history transforms, provenance-aware token accounting shared by the app and CLI, calibrated estimation, and context-budget utilities.
FoundationModelsTools provides calendar, contacts, health, location, music, reminders, weather, web search, and web metadata tools.
FoundationLabCore provides the shared capability and experiment runtime.

Localization and Permissions

The app ships English, German, Spanish, French, Italian, Japanese, Korean, Portuguese (Brazil), Simplified Chinese, and Traditional Chinese localizations.

Features request permissions only when needed. Depending on the selected recipe or lab, the app may request microphone, speech recognition, contacts, calendar, reminders, location, HealthKit, or Apple Music access.

Validation

swiftlint lint --strict --config .swiftlint.yml
swift test

On pull requests, CI runs the FoundationLabCore test suite (swift test) and typechecks the book playgrounds via Tools/BookPlaygrounds/typecheck.sh (foundation-lab-pr.yml). A separate adapter-studio.yml workflow lints and builds Foundation Lab for macOS and iOS Simulator when Adapter Studio files change.

TestFlight

Join the Foundation Lab beta on TestFlight.

Pushes to main that affect the app can run the repository-local ASC workflow in .asc/workflow.json through foundation-lab-testflight.yml.

Agent Skills

Reusable Foundation Models skills now live in rryam/FoundationModelsKit:

foundation-models-app-builder for production Foundation Models patterns
foundation-models-os27-updater for Xcode 27 and OS 27 migrations

npx skills add rryam/FoundationModelsKit \
  --skill foundation-models-app-builder

npx skills add rryam/FoundationModelsKit \
  --skill foundation-models-os27-updater

Contributing

Contributions are welcome. Please open an issue or pull request with a focused change and include the relevant lint, test, and build results.

License

Foundation Lab is available under the MIT License. See LICENSE.