responses chat session parity with regular completions chat session, rewrite example to match

Author: leafo

examples/responses/tools.lua

@@ -1,52 +1,44 @@
--- This shows how to use tool calls with the Responses API
+-- This shows how to use tool calls with the Responses API chat session,
+-- including per-request tool_choice overrides to control tool usage.
 
 local openai = require("openai")
 local cjson = require("cjson")
 
 local client = openai.new(os.getenv("OPENAI_API_KEY"))
 
--- Define a simple weather tool
+-- Define a simple addition tool
 local tools = {
   {
     type = "function",
-    name = "get_weather",
-    description = "Get the current weather for a location",
+    name = "add_numbers",
+    description = "Add two numbers and return the sum.",
     parameters = {
       type = "object",
       properties = {
-        location = {
-          type = "string",
-          description = "The city and state, e.g. San Francisco, CA"
-        },
-        unit = {
-          type = "string",
-          enum = {"celsius", "fahrenheit"},
-          description = "The temperature unit"
-        }
+        a = { type = "number" },
+        b = { type = "number" }
       },
-      required = {"location"}
+      required = { "a", "b" }
     }
   }
 }
 
--- Simulate getting weather data
-local function get_weather(location, unit)
-  unit = unit or "fahrenheit"
-  -- In a real app, you'd call a weather API here
+-- Simulate the tool locally
+local function add_numbers(a, b)
   return {
-    location = location,
-    temperature = unit == "celsius" and 22 or 72,
-    unit = unit,
-    conditions = "sunny"
+    sum = a + b,
+    explanation = ("The sum of %d and %d is %d."):format(a, b, a + b)
   }
 end
 
 local session = client:new_responses_chat_session({
-  tools = tools
+  tools = tools,
+  instructions = "You are a careful math assistant. Always call the provided tool to do arithmetic."
 })
 
-print("Asking about weather...")
-local response, err, raw = session:send("What's the weather like in San Francisco?")
+-- Send initial message, forcing a tool call
+print("Sending initial message...")
+local response, err, raw = session:send("What is 123 + 456? Respond with the total.", {tool_choice = "required"})
 
 if not response then
   print("Error:", err)
@@ -62,37 +54,34 @@ for _, output_item in ipairs(response.output or {}) do
   end
 end
 
-if #tool_calls > 0 then
-  print("Model requested tool calls:")
-
-  for _, tool_call in ipairs(tool_calls) do
-    print("  - Function:", tool_call.name)
-    print("    Arguments:", cjson.encode(tool_call.arguments))
+if #tool_calls == 0 then
+  print("Error: expected a tool call response")
+  os.exit(1)
+end
 
-    -- Execute the tool
-    if tool_call.name == "get_weather" then
-      local args = tool_call.arguments
-      local result = get_weather(args.location, args.unit)
+print("Model requested tool calls:")
+for _, tool_call in ipairs(tool_calls) do
+  print("  - Function:", tool_call.name)
+  print("    Arguments:", tool_call.arguments)
 
-      print("    Result:", cjson.encode(result))
+  -- Execute the tool (arguments is a JSON string, decode it first)
+  local args = cjson.decode(tool_call.arguments)
+  local result = add_numbers(args.a, args.b)
+  print("    Result:", cjson.encode(result))
 
-      -- Send the tool result back
-      local follow_up, err2 = session:send({
-        {
-          type = "function_call_output",
-          call_id = tool_call.call_id,
-          output = cjson.encode(result)
-        }
-      })
+  -- Send the tool result back, forcing a text response (no more tool calls)
+  local final, err2 = session:send({
+    {
+      type = "function_call_output",
+      call_id = tool_call.call_id,
+      output = cjson.encode(result)
+    }
+  }, {tool_choice = "none"})
 
-      if follow_up then
-        print("\nFinal response:", follow_up:get_output_text())
-      else
-        print("Error sending tool result:", err2)
-      end
-    end
+  if not final then
+    print("Error sending tool result:", err2)
+    os.exit(1)
   end
-else
-  -- No tool calls, just print the response
-  print("Response:", response:get_output_text())
+
+  print("\nFinal response:", final:get_output_text())
 end

openai/responses.lua

@@ -86,14 +86,20 @@ local input_content_item = types.one_of({
     filename = types.string
   })
 })
-local input_format = types.string + types.array_of(types.partial({
+local function_call_output_item = types.partial({
+  type = types.literal("function_call_output"),
+  call_id = types.string,
+  output = types.string
+})
+local input_message = types.partial({
   role = types.one_of({
     "system",
     "user",
     "assistant"
   }),
   content = types.string + types.array_of(input_content_item)
-}))
+})
+local input_format = types.string + types.array_of(input_message + function_call_output_item)
 local content_item = types.one_of({
   types.partial({
     type = "output_text",
@@ -121,10 +127,19 @@ local response_message = types.partial({
   content = types.array_of(content_item),
   status = empty + types.string
 })
+local function_call_item = types.partial({
+  id = empty + types.string,
+  type = types.literal("function_call"),
+  name = types.string,
+  arguments = types.string,
+  call_id = types.string,
+  status = empty + types.string
+})
+local output_item = response_message + function_call_item
 local parse_responses_response = types.partial({
   id = types.string:tag("id"),
   object = empty + types.literal("response"):tag("object"),
-  output = types.array_of(response_message):tag("output"),
+  output = types.array_of(output_item):tag("output"),
   model = empty + types.string:tag("model"),
   usage = empty + types.table:tag("usage"),
   status = empty + types.string:tag("status")
@@ -133,14 +148,26 @@ local ResponsesChatSession
 do
   local _class_0
   local _base_0 = {
-    send = function(self, input, stream_callback)
-      if stream_callback == nil then
-        stream_callback = nil
+    send = function(self, input, opts)
+      if opts == nil then
+        opts = { }
+      end
+      if type(opts) == "function" then
+        opts = {
+          stream_callback = opts
+        }
       end
-      return self:create_response(input, {
+      local stream_callback = opts.stream_callback
+      local request_opts = {
         previous_response_id = self.current_response_id,
         stream = stream_callback and true or nil
-      }, stream_callback)
+      }
+      for k, v in pairs(opts) do
+        if k ~= "stream_callback" then
+          request_opts[k] = v
+        end
+      end
+      return self:create_response(input, request_opts, stream_callback)
     end,
     create_response = function(self, input, opts, stream_callback)
       if opts == nil then

openai/responses.moon

@@ -54,12 +54,22 @@ input_content_item = types.one_of {
   types.partial { type: "input_file", file_data: types.string, filename: types.string } -- base64 encoded
 }
 
--- Schema for validating input parameter which can be string or array of messages
-input_format = types.string + types.array_of types.partial {
+-- Schema for validating function call output items (tool results sent back)
+function_call_output_item = types.partial {
+  type: types.literal("function_call_output")
+  call_id: types.string
+  output: types.string
+}
+
+-- Schema for input messages with a role
+input_message = types.partial {
   role: types.one_of {"system", "user", "assistant"}
   content: types.string + types.array_of(input_content_item)
 }
 
+-- Schema for validating input parameter which can be string, array of messages, or array of tool results
+input_format = types.string + types.array_of(input_message + function_call_output_item)
+
 -- Schema for validating response content items
 content_item = types.one_of {
   types.partial {
@@ -90,11 +100,22 @@ response_message = types.partial {
   status: empty + types.string
 }
 
+function_call_item = types.partial {
+  id: empty + types.string
+  type: types.literal("function_call")
+  name: types.string
+  arguments: types.string
+  call_id: types.string
+  status: empty + types.string
+}
+
+output_item = response_message + function_call_item
+
 -- Schema for validating complete response structure
 parse_responses_response = types.partial {
   id: types.string\tag "id"
   object: empty + types.literal("response")\tag "object"
-  output: types.array_of(response_message)\tag "output"
+  output: types.array_of(output_item)\tag "output"
   model: empty + types.string\tag "model"
   usage: empty + types.table\tag "usage"
   status: empty + types.string\tag "status"
@@ -108,12 +129,24 @@ class ResponsesChatSession
 
   -- Send input and get response, maintaining conversation state
   -- input: string or array of message objects
-  -- stream_callback: optional function for streaming responses
-  send: (input, stream_callback=nil) =>
-    @create_response input, {
+  -- opts: optional table with stream_callback and/or per-request overrides
+  --   (passing a function directly is supported for backward compatibility)
+  send: (input, opts={}) =>
+    if type(opts) == "function"
+      opts = { stream_callback: opts }
+
+    stream_callback = opts.stream_callback
+
+    request_opts = {
       previous_response_id: @current_response_id
       stream: stream_callback and true or nil
-    }, stream_callback
+    }
+
+    for k, v in pairs opts
+      if k != "stream_callback"
+        request_opts[k] = v
+
+    @create_response input, request_opts, stream_callback
 
   -- Create a response using the Responses API
   -- input: string or array of message objects