store last response on chat completion, and return the whole object as second return value

Author: leafo

README.md

@@ -445,6 +445,11 @@ Appends a message to the chat history and triggers a completion with
 `generate_response` and returns the response as a string. On failure, returns
 `nil`, an error message, and the raw request response.
 
+On success, a second return value contains the raw API response. For
+non-streaming requests this is the decoded response object (including fields
+like `usage`); for streaming requests it is the raw SSE payload string. The
+latest raw response is also stored on `chat.last_response`.
+
 If the response includes `tool_calls` or a `function_call`, the entire message
 object is returned instead of a string. You can send the result back by passing
 a `role = "tool"` message (with `tool_call_id`) or a `role = "function"` message
@@ -488,6 +493,18 @@ Calls the OpenAI API to generate the next response for the stored chat history.
 Returns the response as a string. On failure, returns `nil`, an error message,
 and the raw request response.
 
+On success, a second return value contains the raw API response. For
+non-streaming requests this is the decoded response object, so you can inspect
+fields like `usage`:
+
+```lua
+local text, raw = chat:generate_response()
+print(text)
+print(raw.usage.total_tokens)
+```
+
+The latest raw response is also stored on `chat.last_response`.
+
 - `append_response`: Whether the response should be appended to the chat history (default: true).
 - `opts`: (optional) A table of per-request overrides. For backward compatibility, a function can be passed and will be treated as `{stream_callback = fn}`.
 

openai/chat_completions.lua

@@ -184,6 +184,7 @@ do
         end
       end
       local status, response = self.client:chat(self.messages, params, stream_callback)
+      self.last_response = response
       if status ~= 200 then
         local err_msg = "Bad status: " .. tostring(status)
         do
@@ -280,9 +281,9 @@ do
           self:append_message(message)
         end
         if message.tool_calls then
-          return message
+          return message, response
         end
-        return message.content or message
+        return message.content or message, response
       end
       local out, err = parse_chat_response(response)
       if not (out) then
@@ -302,7 +303,7 @@ do
         end
         self:append_message(message)
       end
-      return out.response or out.message
+      return out.response or out.message, response
     end
   }
   _base_0.__index = _base_0
@@ -313,6 +314,7 @@ do
       end
       self.client, self.opts = client, opts
       self.messages = { }
+      self.last_response = nil
       if type(self.opts.messages) == "table" then
         self:append_message(unpack(self.opts.messages))
       end

openai/chat_completions.moon

@@ -153,6 +153,7 @@ import create_stream_filter from require "openai.sse"
 class ChatSession
   new: (@client, @opts={}) =>
     @messages = {}
+    @last_response = nil
 
     if type(@opts.messages) == "table"
       @append_message unpack @opts.messages
@@ -218,6 +219,7 @@ class ChatSession
         params[k] = v
 
     status, response = @client\chat @messages, params, stream_callback
+    @last_response = response
 
     if status != 200
       err_msg = "Bad status: #{status}"
@@ -295,9 +297,9 @@ class ChatSession
         @append_message message
 
       if message.tool_calls
-        return message
+        return message, response
 
-      return message.content or message
+      return message.content or message, response
 
     out, err = parse_chat_response response
 
@@ -318,7 +320,7 @@ class ChatSession
       @append_message message
 
     -- response is missing for function_calls, so we return the entire message object
-    out.response or out.message
+    out.response or out.message, response
 
 {
   :ChatSession

spec/openai_spec.moon

@@ -117,8 +117,10 @@ describe "OpenAI API Client", ->
           }
         }
 
-      res = assert chat\send "Who are you?"
+      res, raw = assert chat\send "Who are you?"
       assert.same "I am you", res
+      assert.same {}, raw.usage
+      assert.same raw, chat.last_response
 
       -- verify that all the messages are stored
       assert.same {
@@ -163,7 +165,10 @@ describe "OpenAI API Client", ->
           }
         }
 
-      assert.same "You're welcome", chat\send "Thank you"
+      follow_up, raw = chat\send "Thank you"
+      assert.same "You're welcome", follow_up
+      assert.same {}, raw.usage
+      assert.same raw, chat.last_response
 
     it "handles error responses", ->
       client = OpenAI "test-api-key"
@@ -571,7 +576,7 @@ describe "OpenAI API Client", ->
       stream_callback = (chunk, raw) ->
         table.insert chunks_received, {chunk, raw}
 
-      response = assert chat\send("Why did the chicken cross the road?", stream_callback)
+      response, raw = assert chat\send("Why did the chicken cross the road?", stream_callback)
 
       -- Callback receives parsed chunk {content, index} and raw event object
       assert.same {
@@ -584,6 +589,8 @@ describe "OpenAI API Client", ->
       assert.same "This is ", tostring(chunks_received[1][1])
 
       assert.same "This is a chat response.", response
+      assert.same "string", type(raw)
+      assert.same raw, chat.last_response
 
     it "processes streaming chunks with create_chat_completion (raw)", ->
       client = OpenAI "test-api-key"