Merge pull request alexrudall#485 from krschacht/function-chat-readme

Improve README function calling for chat

Author: alexrudall

README.md

@@ -402,26 +402,29 @@ You can describe and pass in functions and the model will intelligently choose t
 ```ruby
 
 def get_current_weather(location:, unit: "fahrenheit")
-  # use a weather api to fetch weather
+  # Here you could use a weather api to fetch the weather.
+  "The weather in #{location} is nice 🌞 #{unit}"
 end
 
+messages = [
+  {
+    "role": "user",
+    "content": "What is the weather like in San Francisco?",
+  },
+]
+
 response =
   client.chat(
     parameters: {
       model: "gpt-4o",
-      messages: [
-        {
-          "role": "user",
-          "content": "What is the weather like in San Francisco?",
-        },
-      ],
+      messages: messages,  # Defined above because we'll use it again
       tools: [
         {
           type: "function",
           function: {
             name: "get_current_weather",
             description: "Get the current weather in a given location",
-            parameters: {
+            parameters: {  # Format: https://json-schema.org/understanding-json-schema
               type: :object,
               properties: {
                 location: {
@@ -438,31 +441,51 @@ response =
           },
         }
       ],
-      tool_choice: {
-        type: "function",
-        function: {
-          name: "get_current_weather"
-        }
-      }
+      tool_choice: "required"  # Optional, defaults to "auto"
+                               # Can also put "none" or specific functions, see docs
     },
   )
 
 message = response.dig("choices", 0, "message")
 
 if message["role"] == "assistant" && message["tool_calls"]
-  function_name = message.dig("tool_calls", 0, "function", "name")
-  args =
-    JSON.parse(
-      message.dig("tool_calls", 0, "function", "arguments"),
+  message["tool_calls"].each do |tool_call|
+    tool_call_id = tool_call.dig("id")
+    function_name = tool_call.dig("function", "name")
+    function_args = JSON.parse(
+      tool_call.dig("function", "arguments"),
       { symbolize_names: true },
     )
+    function_response = case function_name
+      when "get_current_weather"
+        get_current_weather(**function_args)  # => "The weather is nice 🌞"
+      else
+        # decide how to handle
+    end
+
+    # For a subsequent message with the role "tool", OpenAI requires the preceding message to have a tool_calls argument.
+    messages << message
 
-  case function_name
-  when "get_current_weather"
-    get_current_weather(**args)
+    messages << {
+      tool_call_id: tool_call_id,
+      role: "tool",
+      name: function_name,
+      content: function_response
+    }  # Extend the conversation with the results of the functions
   end
+
+  second_response = client.chat(
+    parameters: {
+      model: "gpt-4o",
+      messages: messages
+  })
+
+  puts second_response.dig("choices", 0, "message", "content")
+
+  # At this point, the model has decided to call functions, you've called the functions
+  # and provided the response back, and the model has considered this and responded.
 end
-# => "The weather is nice 🌞"
+# => "It looks like the weather is nice and sunny in San Francisco! If you're planning to go out, it should be a pleasant day."
 ```
 
 ### Completions