Adding generation options (#9)

Author: mkery

docs/source/api/generation_options.rst

@@ -0,0 +1,29 @@
+..
+    For licensing see accompanying LICENSE file.
+    Copyright (C) 2026 Apple Inc. All Rights Reserved.
+
+Generation Options
+==================
+
+This page documents the classes for controlling how the model generates responses.
+
+.. note::
+   **Swift Equivalent:** This Python API corresponds to the `GenerationOptions <https://developer.apple.com/documentation/foundationmodels/generationoptions>`_ structure in the Swift Foundation Models Framework.
+
+GenerationOptions
+-----------------
+
+.. autoclass:: apple_fm_sdk.GenerationOptions
+   :members:
+   :undoc-members:
+   :exclude-members: to_dict, __post_init__
+
+SamplingMode
+------------
+
+.. autoclass:: apple_fm_sdk.SamplingModeType
+   :exclude-members: RANDOM, GREEDY
+
+.. autoclass:: apple_fm_sdk.SamplingMode
+   :members:
+   :undoc-members:

docs/source/index.rst

@@ -82,6 +82,7 @@ Documentation Contents
 
    api/systemmodel
    api/session
+   api/generation_options
    api/generable
    api/tools
    api/transcript

foundation-models-c/Sources/FoundationModelsCBindings/FoundationModelsCBindings.swift

@@ -265,24 +265,83 @@ private func formatErrorDescription(_ error: Error, function: String = #function
 
 // MARK: - Session response
 
+// Helper function to parse GenerationOptions from JSON
+private func parseGenerationOptions(from jsonString: String?) throws -> GenerationOptions? {
+  guard let jsonString = jsonString, !jsonString.isEmpty else {
+    return nil
+  }
+
+  let data = Data(jsonString.utf8)
+  guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+    throw NSError(
+      domain: "GenerationOptions",
+      code: -1,
+      userInfo: [NSLocalizedDescriptionKey: "Invalid JSON"]
+    )
+  }
+
+  var options = GenerationOptions()
+
+  // Parse sampling mode
+  if let samplingDict = json["sampling"] as? [String: Any],
+    let mode = samplingDict["mode"] as? String
+  {
+    switch mode {
+    case "greedy":
+      options.sampling = .greedy
+    case "random":
+      let seed = samplingDict["seed"] as? UInt64
+      // Swift API supports either topK or probabilityThreshold, not both
+      if let topK = samplingDict["top_k"] as? Int {
+        options.sampling = .random(top: topK, seed: seed)
+      } else if let probabilityThreshold = samplingDict["top_p"] as? Double {
+        options.sampling = .random(probabilityThreshold: probabilityThreshold, seed: seed)
+      }
+    default:
+      break
+    }
+  }
+
+  // Parse temperature
+  if let temperature = json["temperature"] as? Double {
+    options.temperature = temperature
+  }
+
+  // Parse maximum_response_tokens
+  if let maxTokens = json["maximum_response_tokens"] as? Int {
+    options.maximumResponseTokens = maxTokens
+  }
+
+  return options
+}
+
 @_cdecl("FMLanguageModelSessionRespond")
 public func FMLanguageModelSessionRespond(
   session: FMLanguageModelSessionRef,
   prompt: UnsafePointer<CChar>,
+  optionsJSON: UnsafePointer<CChar>?,
   userInfo: UnsafeMutableRawPointer?,
   callback: FMLanguageModelSessionResponseCallback
 ) -> FMTaskRef {
   let session = Unmanaged<LanguageModelSession>.fromOpaque(session).takeUnretainedValue()
   let unsafeSendableUserInfo = UnsafeSendableUserInfo(pointer: userInfo)
 
-  let prompt = String(cString: prompt)
+  let promptString = String(cString: prompt)
+  let optionsJSONString = optionsJSON.map(String.init(cString:))
+
   let task = Task.detached {
     do {
       // Check cancellation at start
       try Task.checkCancellation()
 
-      // Perform the expensive operation
-      let response = try await session.respond(to: prompt)
+      // Parse options if provided
+      let options = try parseGenerationOptions(from: optionsJSONString)
+
+      // Perform the expensive operation with options
+      let response = try await session.respond(
+        to: promptString,
+        options: options ?? GenerationOptions()
+      )
 
       // Check cancellation before callback
       try Task.checkCancellation()
@@ -349,13 +408,22 @@ private final class UnsafeSendableResponseStreamBox<Content: Generable>: @unchec
 @_cdecl("FMLanguageModelSessionStreamResponse")
 public func FMLanguageModelSessionStreamResponse(
   session: FMLanguageModelSessionRef,
-  prompt: UnsafePointer<CChar>
+  prompt: UnsafePointer<CChar>,
+  optionsJSON: UnsafePointer<CChar>?
 ) -> FMLanguageModelSessionResponseStreamRef? {
   let session = Unmanaged<LanguageModelSession>.fromOpaque(session).takeUnretainedValue()
-  let prompt = String(cString: prompt)
-  let stream = session.streamResponse(to: prompt)
-  let box = UnsafeSendableResponseStreamBox<String>(stream: stream, session: session)
-  return FMLanguageModelSessionResponseStreamRef(Unmanaged.passRetained(box).toOpaque())
+  let promptString = String(cString: prompt)
+  let optionsJSONString = optionsJSON.map(String.init(cString:))
+
+  do {
+    let options = try parseGenerationOptions(from: optionsJSONString)
+    let stream = session.streamResponse(to: promptString, options: options ?? GenerationOptions())
+    let box = UnsafeSendableResponseStreamBox<String>(stream: stream, session: session)
+    return FMLanguageModelSessionResponseStreamRef(Unmanaged.passRetained(box).toOpaque())
+  } catch {
+    // If parsing fails, return nil
+    return nil
+  }
 }
 
 @_cdecl("FMLanguageModelSessionResponseStreamIterate")
@@ -439,12 +507,14 @@ public func FMLanguageModelSessionRespondWithSchema(
   session: FMLanguageModelSessionRef,
   prompt: UnsafePointer<CChar>,
   schema: FMGenerationSchemaRef,
+  optionsJSON: UnsafePointer<CChar>?,
   userInfo: UnsafeMutableRawPointer?,
   callback: FMLanguageModelSessionStructuredResponseCallback
 ) -> FMTaskRef {
   let session = Unmanaged<LanguageModelSession>.fromOpaque(session).takeUnretainedValue()
   let promptString = String(cString: prompt)
   let schemaBuilder = Unmanaged<GenerationSchemaBuilder>.fromOpaque(schema).takeUnretainedValue()
+  let optionsJSONString = optionsJSON.map(String.init(cString:))
   let unsafeSendableUserInfo = UnsafeSendableUserInfo(pointer: userInfo)
 
   let task = Task.detached {
@@ -455,9 +525,16 @@ public func FMLanguageModelSessionRespondWithSchema(
       // Build the final schema from the builder
       let finalSchema = try schemaBuilder.buildSchema()
 
+      // Parse options if provided
+      let options = try parseGenerationOptions(from: optionsJSONString)
+
       // Use Foundation Models guided generation API
       try Task.checkCancellation()
-      let response = try await session.respond(to: promptString, schema: finalSchema)
+      let response = try await session.respond(
+        to: promptString,
+        schema: finalSchema,
+        options: options ?? GenerationOptions()
+      )
 
       // Check cancellation before callback
       try Task.checkCancellation()
@@ -502,12 +579,14 @@ public func FMLanguageModelSessionRespondWithSchemaFromJSON(
   session: FMLanguageModelSessionRef,
   prompt: UnsafePointer<CChar>,
   jsonSchema: UnsafePointer<CChar>,
+  optionsJSON: UnsafePointer<CChar>?,
   userInfo: UnsafeMutableRawPointer?,
   callback: FMLanguageModelSessionStructuredResponseCallback
 ) -> FMTaskRef {
   let session = Unmanaged<LanguageModelSession>.fromOpaque(session).takeUnretainedValue()
   let promptString = String(cString: prompt)
   let jsonSchemaString = String(cString: jsonSchema)
+  let optionsJSONString = optionsJSON.map(String.init(cString:))
   let unsafeSendableUserInfo = UnsafeSendableUserInfo(pointer: userInfo)
 
   let task = Task.detached {
@@ -521,8 +600,15 @@ public func FMLanguageModelSessionRespondWithSchemaFromJSON(
         from: Data(jsonSchemaString.utf8)
       )
 
+      // Parse options if provided
+      let options = try parseGenerationOptions(from: optionsJSONString)
+
       try Task.checkCancellation()
-      let response = try await session.respond(to: promptString, schema: schema)
+      let response = try await session.respond(
+        to: promptString,
+        schema: schema,
+        options: options ?? GenerationOptions()
+      )
 
       // Check cancellation before callback
       try Task.checkCancellation()

foundation-models-c/Sources/FoundationModelsCBindings/include/FoundationModels.h

@@ -55,8 +55,8 @@ FMLanguageModelSessionRef _Nonnull FMLanguageModelSessionCreateFromSystemLanguag
 FMLanguageModelSessionRef _Nonnull FMLanguageModelSessionCreateFromTranscript(FMLanguageModelSessionRef _Nonnull transcriptSession, FMSystemLanguageModelRef _Nullable model, FMBridgedToolRef _Nullable *_Nullable tools, int toolCount);
 bool FMLanguageModelSessionIsResponding(FMLanguageModelSessionRef _Nonnull session);
 void FMLanguageModelSessionReset(FMLanguageModelSessionRef _Nonnull session);
-FMTaskRef FMLanguageModelSessionRespond(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt, void *_Nullable userInfo, FMLanguageModelSessionResponseCallback callback);
-FMLanguageModelSessionResponseStreamRef _Nonnull FMLanguageModelSessionStreamResponse(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt);
+FMTaskRef FMLanguageModelSessionRespond(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt, const char *_Nullable optionsJSON, void *_Nullable userInfo, FMLanguageModelSessionResponseCallback callback);
+FMLanguageModelSessionResponseStreamRef _Nonnull FMLanguageModelSessionStreamResponse(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt, const char *_Nullable optionsJSON);
 void FMLanguageModelSessionResponseStreamIterate(FMLanguageModelSessionResponseStreamRef _Nonnull stream, void *_Nullable userInfo, FMLanguageModelSessionResponseCallback callback);
 
 // Transcript functions
@@ -85,8 +85,8 @@ char *_Nullable FMGeneratedContentGetPropertyValue(FMGeneratedContentRef _Nonnul
 bool FMGeneratedContentIsComplete(FMGeneratedContentRef _Nonnull content);
 
 // Structured generation session functions
-FMTaskRef FMLanguageModelSessionRespondWithSchema(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt, FMGenerationSchemaRef _Nonnull schema, void *_Nullable userInfo, FMLanguageModelSessionStructuredResponseCallback callback);
-FMTaskRef FMLanguageModelSessionRespondWithSchemaFromJSON(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt, const char *_Nonnull schemaJSONString, void *_Nullable userInfo, FMLanguageModelSessionStructuredResponseCallback callback);
+FMTaskRef FMLanguageModelSessionRespondWithSchema(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt, FMGenerationSchemaRef _Nonnull schema, const char *_Nullable optionsJSON, void *_Nullable userInfo, FMLanguageModelSessionStructuredResponseCallback callback);
+FMTaskRef FMLanguageModelSessionRespondWithSchemaFromJSON(FMLanguageModelSessionRef _Nonnull session, const char *_Nonnull prompt, const char *_Nonnull schemaJSONString, const char *_Nullable optionsJSON, void *_Nullable userInfo, FMLanguageModelSessionStructuredResponseCallback callback);
 
 // Tool functions
 FMBridgedToolRef _Nullable FMBridgedToolCreate(const char *_Nonnull name, const char *_Nonnull description, FMGenerationSchemaRef _Nonnull parameters, void (*_Nonnull callable)(FMGeneratedContentRef _Nonnull, unsigned int), int *_Nullable outErrorCode, char *_Nullable *_Nullable outErrorDescription) __attribute__((swift_attr("@Sendable")));

foundation-models-c/Sources/fm-c-example/main.c

@@ -6,45 +6,56 @@ Copyright (C) 2026 Apple Inc. All Rights Reserved.
 #include "FoundationModels.h"
 #include <stdio.h>
 
-typedef struct {
+typedef struct
+{
   size_t lastLength;
   bool isResponding;
 } GenerationContext;
 
-void responseCallback(int status, const char *content, size_t length, void *userInfo) {
+void responseCallback(int status, const char *content, size_t length, void *userInfo)
+{
   GenerationContext *context = (GenerationContext *)userInfo;
-  if (status != 0) {
-    printf("Failed to respond (error: \(status))");
+  if (status != 0)
+  {
+    printf("Failed to respond (error: %d)\n", status);
     context->isResponding = false;
     return;
   }
-  if (content) {
+  if (content)
+  {
     printf("%s", &content[context->lastLength]);
     fflush(stdout); // Don't buffer while streaming.
     context->lastLength = length;
-  } else {
+  }
+  else
+  {
     printf("\n✅\n");
     context->isResponding = false;
   }
 }
 
-int main() {
+int main()
+{
   FMSystemLanguageModelRef model = FMSystemLanguageModelGetDefault();
   FMSystemLanguageModelUnavailableReason unavailableReason = FMSystemLanguageModelUnavailableReasonUnknown;
   bool isAvailable = FMSystemLanguageModelIsAvailable(model, &unavailableReason);
-  if (isAvailable) {
+  if (isAvailable)
+  {
     printf("Model is available\n");
-  } else {
+  }
+  else
+  {
     printf("Model is unavailable (reason: %d)\n", (int)unavailableReason);
   }
 
   FMLanguageModelSessionRef session = FMLanguageModelSessionCreateFromSystemLanguageModel(model, /*instructions*/ "Your responses MUST be full of sarcasm.", NULL, 0);
-  FMLanguageModelSessionResponseStreamRef stream = FMLanguageModelSessionStreamResponse(session, "What programming language is better, Swift or C?");
+  FMLanguageModelSessionResponseStreamRef stream = FMLanguageModelSessionStreamResponse(session, "What programming language is better, Swift or C?", NULL);
   GenerationContext context;
   context.lastLength = 0;
   context.isResponding = true;
   FMLanguageModelSessionResponseStreamIterate(stream, &context, responseCallback);
-  while (context.isResponding);
+  while (context.isResponding)
+    ;
   FMRelease(stream);
   FMRelease(session);
   FMRelease(model);

src/apple_fm_sdk/__init__.py

@@ -47,6 +47,8 @@
 
 from .generation_guide import GenerationGuide, GuideType, guide
 
+from .generation_options import GenerationOptions, SamplingMode, SamplingModeType
+
 from .tool import Tool
 
 __version__ = "0.1.0"
@@ -78,6 +80,9 @@
     "GeneratedContent",
     "GenerationGuide",
     "GuideType",
+    "GenerationOptions",
+    "SamplingMode",
+    "SamplingModeType",
     "GenerationID",
     "ConvertibleFromGeneratedContent",
     "ConvertibleToGeneratedContent",

src/apple_fm_sdk/generable_utils.py

@@ -1,38 +1,6 @@
 # For licensing see accompanying LICENSE file.
 # Copyright (C) 2026 Apple Inc. All Rights Reserved.
 
-"""
-Utilities for making Python classes generable with Foundation Models.
-
-This module provides the decorator pattern and helper functions for converting
-regular Python classes (particularly dataclasses) into generable types that can
-be used with Foundation Models' guided generation features.
-
-The main component is the :func:`generable` decorator, which transforms a class
-to support structured generation by adding schema generation, content conversion,
-and partial generation capabilities.
-
-Example:
-    Basic usage:
-        import apple_fm_sdk as fm
-
-        @generable("A cat's profile")
-        class Cat:
-            name: str = fm.guide("Cat's name")
-            age: int = fm.guide("Age in years", range=(0, 20))
-            breed: str = fm.guide("Cat breed")
-
-        # The class now has generation_schema() method
-        schema = Cat.generation_schema()
-
-        # Can be used with Session.respond() for guided generation
-        cat = session.respond(Cat, prompt="Generate a cat named Maomao who is 2 years old")
-
-.. note::
-    This module handles the internal mechanics of the generable decorator.
-    Most users will only need to use the :func:`generable` decorator itself.
-"""
-
 from .generable import (
     Generable,
     GenerationSchema,