foundation-models-utilities: Swift Extras for Apple's Foundation Models Framework

What This Package Adds to Foundation Models Framework

Apple's Foundation Models framework provides an on-device language model session API for Apple platforms and select Linux distributions including Ubuntu. The framework itself does not include a way to connect to a hosted model server using the standard chat completions protocol, nor does it provide ready-made strategies for managing a session transcript that grows past the model's context window.

foundation-models-utilities fills both gaps and adds a third capability. ChatCompletionsLanguageModel connects to any server that speaks the chat completions REST API, making it possible to use open-source models or external services inside a Foundation Models session. The history management helpers let developers compose truncation, rolling window, and summarisation strategies declaratively. The Skills system injects additional instructions into a session transcript on demand, activated by a model-generated tool call, without requiring those instructions to be present in every turn.

The package is maintained by Apple and its issues are handled through the Apple Developer Forums under the machine learning and AI section. The repository sits on GitHub at apple/foundation-models-utilities and accepts contributions through the standard GitHub pull request workflow.

ChatCompletionsLanguageModel: Connecting to External Servers

ChatCompletionsLanguageModel is the main entry point for using a server-hosted model inside a Foundation Models session. You initialise it with a model name and a URL pointing to the server's chat completions endpoint, then pass it to a LanguageModelSession the same way you would pass an on-device model:

let model = ChatCompletionsLanguageModel(
  name: "minimax-m2.5",
  url: URL(string: "http://localhost/v1:8000")!
)

let session = LanguageModelSession(model: model)

let response = try await session.respond(to: "How many folds does it take to make a paper crane?")

print(response.content)

Not every local LLM server supports guided generation, which the Foundation Models framework uses for structured output. You can disable this capability at initialisation time to avoid sending unsupported requests:

let model = ChatCompletionsLanguageModel(
  name: "minimax-m2.5",
  url: URL(string: "http://localhost/v1:8000")!,
  supportsGuidedGeneration: false
)

The README notes that ChatCompletionsLanguageModel is particularly useful for integrating with the large ecosystem of utilities built around the chat completions protocol. That applies to any server implementing the OpenAI-compatible API format, which many local and cloud-hosted models now support.

History Management for Finite Context Windows

A long conversation session eventually exceeds the context window of the underlying model. Without intervention, this produces errors or forces a reset that loses conversation context. foundation-models-utilities provides profile modifiers that address this through three composable strategies: dropping completed tool calls, applying a rolling window of recent entries, and summarising older history into a single compact entry.

The README explicitly states there is no one-size-fits-all solution and recommends composing strategies to match the application. The following example from the README combines all three. Modifiers apply in outside-in order: tool call dropping first, then the rolling window, then summarisation only when the rolling window exceeds 5000 tokens:

struct MyProfile: LanguageModelSession.DynamicProfile {
  let status: Status

  var body: some DynamicProfile {
    Profile {
      Instructions("A conversation between a user and a helpful assistant.")
      ToggleDarkModeTool()
    }
    .summarizeHistory(entryThreshold: 10, model: status.summarizerModel)
    .rollingWindow(entries: 10)
    .droppingCompletedToolCalls()
  }
}

Summarisation requires a separate model instance to perform the compression. Passing a smaller, faster model for this role is a practical optimisation when the primary model is large or expensive to run. The threshold parameters (entryThreshold: 10, 5000 tokens) are values from the README example and would need adjustment for your specific application.

Just-in-Time Skills and Key-Value Cache Preservation

The Skills system solves a specific problem: task-specific instructions that need to be present only when a particular capability is active, rather than loaded into every turn of the session. Loading all possible instructions upfront prevents the key-value cache from being reused across turns because any change to the instructions position in the transcript invalidates the cache for everything below it.

A Skill is activated when the model generates a tool call for it. The activation is tracked in a SkillActivations instance, which conforms to Observable, so it can drive SwiftUI updates. There are two initialisation paths that differ in where the skill content is inserted.

When initialised with a prompt string, the skill content is added as a tool output in the transcript. The README notes this preserves the key-value cache because the instructions block is not modified. When initialised with an instructions string, the content is appended to the first instructions entry, which typically invalidates the cache but gives the model high compliance priority. Instructions-based skills can also allow the model to deactivate them by passing allowsDeactivation: true.

The SkillActivations collection can be inspected to show which skills are currently active, making it straightforward to reflect skill state in a UI without maintaining separate state.

Installation via Xcode and Swift Package Manager

The package is available from https://github.com/apple/foundation-models-utilities and works on Apple platforms and select Linux distributions including Ubuntu.

In Xcode, choose File then Add Package Dependencies, enter the package URL, and Xcode fetches the package assets. From Swift Package Manager, add it as a dependency in Package.swift:

let package = Package(
    name: "YourApp",
    dependencies: [
        .package(url: "https://github.com/apple/foundation-models-utilities", from: "1.0.0")
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: [
                .product(name: "FoundationModelsUtilities", package: "foundation-models-utilities")
            ]
        )
    ]
)

The repository also contains a `skills/` directory described as teaching coding agents how to use the package. This is a separate set of skill files intended for use with coding tools rather than for inclusion in production apps.

Limitations and When to Look Elsewhere

foundation-models-utilities extends the Foundation Models framework and does not work without it. Developers building on other platforms, using LLMs through OpenAI's SDK, LangChain, or similar libraries will find no applicable components here. The package is not a general LLM abstraction layer.

The history management strategies are composable but not automatic. Choosing the right combination and the right threshold values requires understanding how your application's conversation patterns interact with the underlying model's context window. A badly chosen entryThreshold or token budget can either truncate too aggressively (losing important context) or not aggressively enough (still overflowing).

The repository carries no GitHub releases yet. The SPM dependency in the README references from: "1.0.0", but without a corresponding release tag in the GitHub UI, the package relies on commit-level versioning. This means upstream changes to the main branch could affect builds that do not pin to a specific commit. Pinning to a specific commit revision in Package.swift is the safer choice for production Swift projects.

LangChain and other multi-platform LLM frameworks are not direct alternatives here; this is a library for Apple platform development specifically. The closest alternative for managed context compression in a different framework would be LangChain's memory and trimming utilities, which target Python and JavaScript rather than Swift.

Maintenance and Licence

The last push to the repository was on 2026-09-21, indicating the package is under active development. It is maintained by Apple and housed in the Apple organisation on GitHub, which suggests it will track the Foundation Models framework as the framework evolves.

The project is licensed under Apache-2.0. Unlike the MIT licence, Apache-2.0 includes an explicit patent grant from contributors. This matters when a dependency is used in products that could encounter patent disputes: the grant covers use of any patent claims owned by contributors that are embodied in the licensed work.

The repository includes a CONTRIBUTING.md file. Issues are directed to the Apple Developer Forums rather than to GitHub Issues, which means questions that would normally go to the issue tracker need to be routed to the forums instead.

Editorial conclusion

foundation-models-utilities is the right choice for developers already building on Apple's Foundation Models framework who need to connect to external model servers, manage context window size across long conversations, or inject skill-specific instructions without invalidating the key-value cache. It is not a standalone LLM SDK and has no value outside the Foundation Models framework. Before adopting it, verify that the history management strategy you compose actually fits your token budget by testing against your application's typical conversation length and the specific model's context window.

Frequently asked questions

Official sources

1. apple/foundation-models-utilities on GitHub
2. Issues
3. License: Apache-2.0
4. README