From bf74a00d78373d86da0b5ec095b7825bd0ce4c9e Mon Sep 17 00:00:00 2001 From: Eric Gourlaouen Date: Thu, 18 Jun 2026 16:13:42 -0700 Subject: [PATCH 1/2] Return specific error when the package is built with an Xcode version that does not support image inputs --- docs/source/getting_started.rst | 12 +++++++++ .../FoundationModelsCBindings.swift | 18 +++++++++---- .../include/FoundationModels.h | 3 ++- src/apple_fm_sdk/prompt.py | 27 +++++++++++-------- 4 files changed, 43 insertions(+), 17 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 008327f..418c6f9 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -109,6 +109,18 @@ If you see "Foundation Models not available", check: 3. You're running a compatible OS version (macOS 26.0+) 4. Verify that your Xcode version matches your macOS version exactly. +Newer Features Not Available +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some newer features of the Foundation Models Framework might only be available when building this package with an up-to-date SDK. +If you see an "unsupported" error when using those features, check: + +- Your device is up-to-date and supports this feature +- The Xcode version used when installing this package has up-to-date SDKs + - You can otherwise switch the default version of Xcode on your system by executing `xcode-select --switch ` in a shell + - You can also otherwise set the environment variable `DEVELOPER_DIR` to point to a specific Xcode installation on your device +- Reinstall your package + Next Steps ---------- diff --git a/foundation-models-c/Sources/FoundationModelsCBindings/FoundationModelsCBindings.swift b/foundation-models-c/Sources/FoundationModelsCBindings/FoundationModelsCBindings.swift index b58917b..174da41 100644 --- a/foundation-models-c/Sources/FoundationModelsCBindings/FoundationModelsCBindings.swift +++ b/foundation-models-c/Sources/FoundationModelsCBindings/FoundationModelsCBindings.swift @@ -9,7 +9,10 @@ import FoundationModelsCDeclarations import Synchronization enum ComposedPromptError: Error { - case unsupported + // Error thrown when the SDK, at build time, does not support attachments + case unsupportedSDK + // Error thrown when the runtime OS does not support attachments + case unsupportedOS } /// Builder class for a `Prompt`. @@ -36,10 +39,12 @@ public class ComposedPrompt: NSObject, PromptRepresentable { } self.components.append(attachment) return + } else { + throw ComposedPromptError.unsupportedOS } + #else + throw ComposedPromptError.unsupportedSDK #endif - - throw ComposedPromptError.unsupported } public var promptRepresentation: Prompt { @@ -74,8 +79,11 @@ public func FMComposedPromptAddAttachment( do { try composedPrompt.add(attachmentFromPath: imageURLToAddToPrompt, label: labelString) return true - } catch ComposedPromptError.unsupported { - error?.pointee = FMComposedPromptAddImageErrorUnsupported + } catch ComposedPromptError.unsupportedOS { + error?.pointee = FMComposedPromptAddImageErrorUnsupportedOS + return false + } catch ComposedPromptError.unsupportedSDK { + error?.pointee = FMComposedPromptAddImageErrorUnsupportedSDK return false } catch _ { error?.pointee = FMComposedPromptAddImageErrorUnknown diff --git a/foundation-models-c/Sources/FoundationModelsCBindings/include/FoundationModels.h b/foundation-models-c/Sources/FoundationModelsCBindings/include/FoundationModels.h index 91db347..29c13d5 100644 --- a/foundation-models-c/Sources/FoundationModelsCBindings/include/FoundationModels.h +++ b/foundation-models-c/Sources/FoundationModelsCBindings/include/FoundationModels.h @@ -64,7 +64,8 @@ FMComposedPrompt _Nonnull FMComposedPromptInitialize(); typedef enum { FMComposedPromptAddImageErrorNone, - FMComposedPromptAddImageErrorUnsupported, + FMComposedPromptAddImageErrorUnsupportedOS, + FMComposedPromptAddImageErrorUnsupportedSDK, FMComposedPromptAddImageErrorUnknown } FMComposedPromptAddImageError; diff --git a/src/apple_fm_sdk/prompt.py b/src/apple_fm_sdk/prompt.py index a3a9300..0414147 100644 --- a/src/apple_fm_sdk/prompt.py +++ b/src/apple_fm_sdk/prompt.py @@ -3,9 +3,6 @@ from abc import ABC, abstractmethod import logging -from .c_helpers import ( - _get_error_string, -) from typing import Optional, Union from pathlib import Path @@ -15,6 +12,10 @@ try: from . import _ctypes_bindings as lib + from ._ctypes_bindings import ( + FMComposedPromptAddImageErrorUnsupportedOS, + FMComposedPromptAddImageErrorUnsupportedSDK, + ) except ImportError: raise ImportError( "Foundation Models C bindings not found. Please ensure _foundationmodels_ctypes.py is available." @@ -158,7 +159,8 @@ def add_to_composed_prompt(self, composed_prompt): :param composed_prompt: The native composed prompt object to add this attachment to :type composed_prompt: ctypes pointer :raises ImagePromptError: If the attachment cannot be added, either because - the image format is not supported or another error occurs + the runtime OS or the build-time SDK doesn't support attachments, or + another error occurs. """ label_bytes = self._label.encode("utf-8") if self._label else None error_reason = ctypes.c_int() @@ -168,11 +170,13 @@ def add_to_composed_prompt(self, composed_prompt): label_bytes, ctypes.byref(error_reason), ): - error = _get_error_string(error_reason, None) - error_message = error[1] if error[1] else "Attachment prompts not supported" - raise ImagePromptError( - f"Failed to add attachment to prompt: {error_message}" - ) + if error_reason.value == FMComposedPromptAddImageErrorUnsupportedOS: + detail = "the current OS does not support attachment prompts" + elif error_reason.value == FMComposedPromptAddImageErrorUnsupportedSDK: + detail = "the Xcode version used to build this package doesn't include macOS 27 SDKs" + else: + detail = "an unknown error occurred while adding the attachment" + raise ImagePromptError(f"Failed to add attachment to prompt: {detail}") PromptComponent = Union[str, Attachment] @@ -251,8 +255,9 @@ class ImagePromptError(PromptError): This exception is raised when there are issues with image attachments, such as: - Image file not found at the specified path - - Unsupported image format - - Failure to add the image to the prompt + - The current OS does not support attachment prompts + - The Xcode version used to build this package doesn't include the right SDKs for + image input support Examples: Handling image prompt errors:: From c75cb5928309fc1e4b2cd39826dfd60e2f5e154a Mon Sep 17 00:00:00 2001 From: Eric Gourlaouen Date: Thu, 18 Jun 2026 16:16:11 -0700 Subject: [PATCH 2/2] Remove docs re: image input SDKs The error message should be self-explanatory. --- docs/source/getting_started.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 418c6f9..008327f 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -109,18 +109,6 @@ If you see "Foundation Models not available", check: 3. You're running a compatible OS version (macOS 26.0+) 4. Verify that your Xcode version matches your macOS version exactly. -Newer Features Not Available -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some newer features of the Foundation Models Framework might only be available when building this package with an up-to-date SDK. -If you see an "unsupported" error when using those features, check: - -- Your device is up-to-date and supports this feature -- The Xcode version used when installing this package has up-to-date SDKs - - You can otherwise switch the default version of Xcode on your system by executing `xcode-select --switch ` in a shell - - You can also otherwise set the environment variable `DEVELOPER_DIR` to point to a specific Xcode installation on your device -- Reinstall your package - Next Steps ----------