Adding the ability to load a session from a saved transcript (#8)

Author: mkery

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

@@ -127,6 +127,45 @@ public func FMLanguageModelSessionCreateFromSystemLanguageModel(
   return FMLanguageModelSessionRef(Unmanaged.passRetained(session).toOpaque())
 }
 
+@_cdecl("FMLanguageModelSessionCreateFromTranscript")
+public func FMLanguageModelSessionCreateFromTranscript(
+  transcriptSession: FMLanguageModelSessionRef,
+  model: UnsafePointer<FMSystemLanguageModelRef>?,
+  tools: UnsafeMutablePointer<FMBridgedToolRef>?,
+  toolCount: Int32
+) -> FMLanguageModelSessionRef {
+  // Extract the transcript from the existing session
+  let existingSession = Unmanaged<LanguageModelSession>.fromOpaque(transcriptSession)
+    .takeUnretainedValue()
+  let transcript = existingSession.transcript
+
+  // Get the model to use
+  var modelChoice: SystemLanguageModel
+  if let model = model {
+    modelChoice = Unmanaged<SystemLanguageModel>.fromOpaque(model).takeUnretainedValue()
+  } else {
+    modelChoice = SystemLanguageModel.default
+  }
+
+  // Convert the C array of tool refs to Swift array of Tool objects
+  var toolArray: [any Tool] = []
+  if let tools = tools, toolCount > 0 {
+    for i in 0..<Int(toolCount) {
+      let toolRef = tools[i]
+      let bridgedTool = Unmanaged<BridgedTool>.fromOpaque(toolRef).takeUnretainedValue()
+      toolArray.append(bridgedTool)
+    }
+  }
+
+  // Create a new session from the transcript
+  let session = LanguageModelSession(
+    model: modelChoice,
+    tools: toolArray,
+    transcript: transcript,
+  )
+  return FMLanguageModelSessionRef(Unmanaged.passRetained(session).toOpaque())
+}
+
 @_cdecl("FMLanguageModelSessionIsResponding")
 public func FMLanguageModelSessionIsResponding(session: FMLanguageModelSessionRef) -> Bool {
   let session = Unmanaged<LanguageModelSession>.fromOpaque(session).takeUnretainedValue()
@@ -525,6 +564,29 @@ public func FMLanguageModelSessionRespondWithSchemaFromJSON(
 
 // MARK: - Transcript
 
+@_cdecl("FMTranscriptCreateFromJSONString")
+public func FMTranscriptCreateFromJSONString(
+  jsonString: UnsafePointer<CChar>,
+  outErrorCode: UnsafeMutablePointer<Int32>?,
+  outErrorDescription: UnsafeMutablePointer<UnsafePointer<CChar>?>?
+) -> FMLanguageModelSessionRef? {
+  let jsonStr = String(cString: jsonString)
+
+  do {
+    let transcript = try JSONDecoder().decode(Transcript.self, from: Data(jsonStr.utf8))
+    // Create a new session initialized with the transcript
+    let session = LanguageModelSession(transcript: transcript)
+    return FMLanguageModelSessionRef(Unmanaged.passRetained(session).toOpaque())
+  } catch {
+    let debugDescription = formatErrorDescription(error)
+    debugDescription.withCString { cString in
+      outErrorCode?.pointee = StatusCode.decodingFailure.rawValue
+      outErrorDescription?.pointee = UnsafePointer(strdup(cString))
+    }
+    return nil
+  }
+}
+
 /// Returns a JSON string representation of the session transcript.
 ///
 /// - Parameters:

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

@@ -52,13 +52,15 @@ FMSystemLanguageModelRef _Nonnull FMSystemLanguageModelCreate(FMSystemLanguageMo
 bool FMSystemLanguageModelIsAvailable(FMSystemLanguageModelRef _Nonnull ref, FMSystemLanguageModelUnavailableReason *_Nullable unavailableReason);
 FMLanguageModelSessionRef _Nonnull FMLanguageModelSessionCreateDefault();
 FMLanguageModelSessionRef _Nonnull FMLanguageModelSessionCreateFromSystemLanguageModel(FMSystemLanguageModelRef _Nullable model, const char *_Nullable instructions, FMBridgedToolRef _Nullable *_Nullable tools, int toolCount);
+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);
 void FMLanguageModelSessionResponseStreamIterate(FMLanguageModelSessionResponseStreamRef _Nonnull stream, void *_Nullable userInfo, FMLanguageModelSessionResponseCallback callback);
 
 // Transcript functions
+FMLanguageModelSessionRef _Nullable FMTranscriptCreateFromJSONString(const char *_Nonnull jsonString, int *_Nullable outErrorCode, char *_Nullable *_Nullable outErrorDescription);
 char *_Nullable FMLanguageModelSessionGetTranscriptJSONString(FMLanguageModelSessionRef _Nonnull session, int *_Nullable outErrorCode, char *_Nullable *_Nullable outErrorDescription);
 
 // GenerationSchema functions

pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["."]
 
 [project]
 name = "apple-fm-sdk"
-version = "0.1.0"
+version = "0.1.1"
 description = "Python bindings for Apple's Foundation Models Swift framework"
 readme = "README.md"
 requires-python = ">=3.10"

src/apple_fm_sdk/__init__.py

@@ -14,6 +14,8 @@
 
 from .session import LanguageModelSession
 
+from .transcript import Transcript
+
 from .errors import (
     FoundationModelsError,
     GenerationError,
@@ -51,6 +53,7 @@
 __all__ = [
     "SystemLanguageModel",
     "LanguageModelSession",
+    "Transcript",
     "SystemLanguageModelUseCase",
     "SystemLanguageModelGuardrails",
     "SystemLanguageModelUnavailableReason",

src/apple_fm_sdk/session.py

@@ -168,6 +168,106 @@ def __init__(
             super().__init__(ptr)
         # This opaque pointer already has 1 ref count by `passRetained`
 
+    @classmethod
+    def from_transcript(
+        cls,
+        transcript: Transcript,
+        model: Optional[SystemLanguageModel] = None,
+        tools: Optional[list[Tool]] = None,
+    ) -> "LanguageModelSession":
+        """Create a new session from an existing transcript.
+
+        This method creates a new LanguageModelSession initialized from an existing transcript.
+        The new session will contain all the conversation history from the transcript, including
+        user messages, model responses, and tool interactions.
+
+        :param transcript: The Transcript instance to initialize the session from.
+            This transcript contains the complete conversation history.
+        :type transcript: Transcript
+        :param model: Optional SystemLanguageModel to use for the new session. If not
+            provided, uses the default model. This allows you to continue a conversation
+            with a different model configuration than the original.
+        :type model: Optional[SystemLanguageModel]
+        :param tools: **IMPORTANT**: Tool mentions loaded from a Transcript are historical only.
+            You must **also** pass tool instances here if you want to allow the model to make new
+            tool calls in this session.
+        :type tools: Optional[list[Tool]]
+        :return: A new LanguageModelSession initialized with the transcript's history
+        :rtype: LanguageModelSession
+        :raises FoundationModelsError: If session creation fails
+
+        Examples:
+            Resume a conversation from a saved transcript::
+
+                import apple_fm_sdk as fm
+                import json
+
+                # Load a saved transcript
+                with open("transcript.json", "r") as f:
+                    transcript_dict = json.load(f)
+
+                transcript = await fm.Transcript.from_dict(transcript_dict)
+
+                # Create a new session from the transcript
+                session = fm.LanguageModelSession.from_transcript(transcript)
+
+                # Continue the session
+                response = await session.respond("Summarize the session so far.")
+
+            Resume with tools::
+
+                import apple_fm_sdk as fm
+                from my_tools import CalculatorTool, WeatherTool
+
+                # Load transcript that had tool calls
+                transcript = await fm.Transcript.from_dict(transcript_dict)
+
+                # IMPORTANT: You must pass the tool instances explicitly.
+                # The transcript contains the history of tool calls, but not
+                # the ability to make new tool calls unless you provide them.
+                session = fm.LanguageModelSession.from_transcript(
+                    transcript,
+                    tools=[CalculatorTool(), WeatherTool()]
+                )
+
+                # Now the model can make new tool calls
+                response = await session.respond("Calculate 15 * 24")
+
+        Note:
+            - The transcript contains the session instructions, so you don't need to
+              pass instructions separately
+            - The new session shares the transcript object with the original
+            - Any new interactions will update the transcript
+            - Tool mentions from the transcript are historical only. To allow the model to
+              make new tool calls, you must explicitly pass the tool instances in the ``tools`` parameter.
+        See Also:
+            - :class:`~apple_fm_sdk.transcript.Transcript`: For working with transcripts
+            - :meth:`~apple_fm_sdk.transcript.Transcript.from_dict`: For loading transcripts from JSON
+            - :class:`~apple_fm_sdk.tool.Tool`: For creating custom tools
+        """
+        # Create model pointer
+        model_ptr = model._ptr if model else None
+
+        # Create array of tool pointers
+        tool_count = len(tools) if tools else 0
+        tool_refs = (ctypes.c_void_p * tool_count)()
+        if tools:
+            for i, tool in enumerate(tools):
+                tool_refs[i] = tool._ptr
+
+        # Create the session via C binding - use the new function that takes a transcript session
+        ptr = lib.FMLanguageModelSessionCreateFromTranscript(
+            transcript.session_ptr, model_ptr, tool_refs, tool_count
+        )
+
+        # Update transcript to use the new session pointer
+        transcript._update_session_ptr(ptr)
+
+        # Create session instance
+        session = cls(_ptr=ptr)
+        session.transcript = transcript  # Use the provided transcript
+        return session
+
     @property
     def is_responding(self) -> bool:
         """Check if the session is currently responding to a request.

src/apple_fm_sdk/transcript.py

@@ -225,3 +225,113 @@ async def to_dict(self) -> dict:
         json_str = str(jsn_string)
         result = json.loads(json_str)
         return result
+
+    @classmethod
+    async def from_dict(cls, dict: dict) -> "Transcript":
+        """Create a Transcript from a dictionary representation.
+
+        This method deserializes a transcript dictionary (typically loaded from JSON)
+        and creates a Transcript instance. This is useful for loading saved session
+        transcripts and resuming sessions with the full history intact.
+
+        :param dict: Dictionary representation of a transcript, typically loaded from
+            a JSON file. Must match the Foundation Models transcript format.
+        :type dict: dict
+        :return: A new Transcript instance initialized with the provided data
+        :rtype: Transcript
+        :raises GenerationError: If the dictionary format is invalid or cannot be parsed
+
+        .. warning::
+            **Tools in a transcript:**
+
+            The transcript preserves the *history* of tool calls (what was called and
+            what the results were), but not the *capability* to make new tool calls.
+            Tool definitions stored in a transcript JSON will appear in the transcript's
+            content history, but they will **not** be automatically available for the model
+            to call. That's because the transcript doesn't actually contain the tool
+            implementations. To allow the model to invoke tools mentioned in the transcript,
+            implement each tool in Python and then create a session with both the transcript
+            and tools using :meth:`~apple_fm_sdk.session.LanguageModelSession.from_transcript`
+
+        Examples:
+            Load a transcript from a JSON file::
+
+                import apple_fm_sdk as fm
+                import json
+
+                # Load transcript from file
+                with open("transcript.json", "r") as f:
+                    transcript_dict = json.load(f)
+
+                # Create Transcript instance
+                transcript = await fm.Transcript.from_dict(transcript_dict)
+
+                # Now you can create a session starting from this transcript
+                session = fm.LanguageModelSession.from_transcript(transcript)
+
+            Load and resume with tools::
+
+                import apple_fm_sdk as fm
+                import json
+                from my_tools import CalculatorTool, WeatherTool
+
+                # Load transcript that had tool calls
+                with open("transcript_with_tools.json", "r") as f:
+                    transcript_dict = json.load(f)
+
+                transcript = await fm.Transcript.from_dict(transcript_dict)
+
+                # IMPORTANT: Tools in the transcript are historical mentions only.
+                # To allow the model to call a tool, you must explicitly instantiate each
+                # tool in Python and then pass them to the session initializer.
+                session = fm.LanguageModelSession.from_transcript(
+                    transcript,
+                    tools=[CalculatorTool(), WeatherTool()]
+                )
+
+        Note:
+            - The dictionary must follow the Foundation Models transcript format
+            - Tool definitions in the transcript are for historical reference only
+            - To use tools with the transcript, pass them to
+              :meth:`~apple_fm_sdk.session.LanguageModelSession.from_transcript`
+
+        See Also:
+            - :meth:`to_dict`: For converting a Transcript to a dictionary
+            - :meth:`~apple_fm_sdk.session.LanguageModelSession.from_transcript`: For creating sessions from transcripts
+            - :class:`~apple_fm_sdk.tool.Tool`: For creating custom tools
+        """
+        error_code = ctypes.c_int32()  # C error status code
+        error_description = ctypes.POINTER(
+            ctypes.c_char
+        )()  # C error description pointer
+
+        # Create a session pointer initialized with the transcript data from the dictionary
+        # We can't create transcript pointer directly, so we create a new session pointer that
+        # holds the Transcript.
+        session_ptr = lib.FMTranscriptCreateFromJSONString(
+            json.dumps(dict), ctypes.byref(error_code), ctypes.byref(error_description)
+        )
+
+        # Check if we got a valid result or an error
+        if session_ptr is None:
+            # An error occurred, raise appropriate exception
+            err_code, err_desc = _get_error_string(error_code, error_description)
+            error_msg = "Failed to create transcript from dictionary"
+            if err_desc:
+                error_msg = error_msg + ": " + err_desc
+            raise _status_code_to_exception(err_code or error_code.value, error_msg)
+
+        return cls(_ptr=session_ptr)
+
+    def _update_session_ptr(self, new_ptr):
+        """Update the session pointer associated with this transcript.
+
+        This is used internally to keep the transcript's session pointer in sync
+        with the LanguageModelSession's pointer after interactions that may change it.
+
+        Note:
+            - This method is for internal use only and should not be called directly.
+            - The transcript shares the session's pointer, so updating it ensures the
+              transcript reflects the current session state.
+        """
+        self.session_ptr = new_ptr