more work to normalize chunk format

Author: leafo

README.md

@@ -124,8 +124,9 @@ client:create_response({
 }, {
   stream = true
 }, function(chunk)
-  if chunk.text_delta then
-    io.stdout:write(chunk.text_delta)
+  -- Raw event object from API: check type and access delta directly
+  if chunk.type == "response.output_text.delta" then
+    io.stdout:write(chunk.delta)
     io.stdout:flush()
   end
 end)
@@ -246,7 +247,7 @@ Sends a request to the `/responses` endpoint (Responses API).
 
 - `input`: A string or array of message objects (with `role` and `content` fields)
 - `opts`: Additional options passed directly to the API (eg. model, temperature, instructions, tools, previous_response_id, etc.) https://platform.openai.com/docs/api-reference/responses
-- `stream_callback`: Optional function called for each parsed chunk when `stream = true` is passed in opts
+- `stream_callback`: Optional function called for each raw event object when `stream = true` is passed in opts (eg. `{type = "response.output_text.delta", delta = "Hello"}`)
 
 Returns HTTP status, response object, and output headers. The response object
 will be decoded from JSON if possible, otherwise the raw string is returned.
@@ -320,6 +321,57 @@ Sends a request to the `/images/generations` endpoint to generate images.
 
 Returns HTTP status, response object, and output headers.
 
+#### ResponsesChatSession
+
+This class manages chat sessions using OpenAI's Responses API. Unlike
+ChatSession, conversation state is maintained server-side via
+`previous_response_id`. Typically created with `new_responses_chat_session`.
+
+The field `response_history` stores an array of response objects from past
+interactions. The field `current_response_id` holds the ID of the most recent
+response, used to maintain conversation continuity.
+
+##### `new(client, opts)`
+
+Constructor for the ResponsesChatSession.
+
+- `client`: An instance of the OpenAI client.
+- `opts`: An optional table of options.
+  - `model`: Model to use (defaults to client's default_model)
+  - `instructions`: System instructions for the conversation
+  - `tools`: Array of tool definitions
+  - `previous_response_id`: Resume from a previous response
+
+##### `session:send(input, stream_callback)`
+
+Sends input and returns the response, maintaining conversation state
+automatically.
+
+- `input`: A string or array of message objects.
+- `stream_callback`: Optional function for streaming responses.
+
+Returns a response object on success (or accumulated text string when
+streaming). On failure, returns `nil`, an error message, and the raw response.
+
+Response objects have helper methods:
+- `response:get_output_text()`: Extract all text content as a string
+- `response:get_images()`: Extract generated images (when using image_generation tool)
+- `tostring(response)`: Converts to text string
+
+The `stream_callback` receives two arguments: the delta text string and the raw
+event object. Each call provides an incremental piece of the response text.
+
+##### `session:create_response(input, opts, stream_callback)`
+
+Lower-level method to create a response with additional options.
+
+- `input`: A string or array of message objects.
+- `opts`: Additional options (model, temperature, tools, previous_response_id, etc.)
+- `stream_callback`: Optional function for streaming responses.
+
+Returns a response object on success. On failure, returns `nil`, an error
+message, and the raw response.
+
 #### ChatSession
 
 This class manages chat sessions and history with the OpenAI API. Typically

examples/chat_completions/streaming.lua

@@ -7,8 +7,12 @@ client:create_chat_completion({
 }, {
   stream = true
 }, function(chunk)
-  io.stdout:write(chunk.content)
-  io.stdout:flush()
+  -- Raw event object from API: access content via choices[1].delta.content
+  local delta = chunk.choices and chunk.choices[1] and chunk.choices[1].delta
+  if delta and delta.content then
+    io.stdout:write(delta.content)
+    io.stdout:flush()
+  end
 end)
 
 print() -- print a newline

examples/responses/basic.lua

@@ -27,17 +27,14 @@ print(response.output[1].content[1].text)
 print("\n== Streaming example (via session) ==")
 local stream_session = client:new_responses_chat_session()
 
-local streamed_text, err, raw = stream_session:send("Stream a brief greeting.", function(chunk)
-  if chunk.text_delta then
-    io.write(chunk.text_delta)
-    io.flush()
-  end
-
-  if chunk.response then
-    print("\n\nCompleted response ID: " .. chunk.response.id)
-  end
+local streamed_text, err, raw = stream_session:send("Stream a brief greeting.", function(delta)
+  -- delta is the text string, second arg (raw) is the raw event object
+  io.write(delta)
+  io.flush()
 end)
 
+print() -- newline after streaming
+
 if not streamed_text then
   io.stderr:write("Streaming request failed: " .. err .. "\n")
   if raw then

openai/responses.lua

@@ -124,45 +124,6 @@ local parse_responses_response = types.partial({
   usage = empty + types.table:tag("usage"),
   status = empty + types.string:tag("status")
 })
-local parse_response_stream_chunk
-parse_response_stream_chunk = function(chunk)
-  if not (type(chunk) == "table") then
-    return 
-  end
-  if not (chunk.type) then
-    return 
-  end
-  if chunk.type == "response.output_text.delta" and type(chunk.delta) == "string" then
-    return {
-      type = chunk.type,
-      text_delta = chunk.delta,
-      raw = chunk
-    }
-  end
-  if chunk.type == "response.completed" and type(chunk.response) == "table" then
-    local parsed, err = parse_responses_response(chunk.response)
-    if parsed then
-      chunk.response = parsed
-      return chunk
-    else
-      return nil, err
-    end
-  end
-  if chunk.delta and type(chunk.delta.text) == "string" then
-    return {
-      type = chunk.type,
-      text_delta = chunk.delta.text,
-      raw = chunk
-    }
-  end
-  if chunk.content_block_delta and type(chunk.content_block_delta.text) == "string" then
-    return {
-      type = chunk.type,
-      text_delta = chunk.content_block_delta.text,
-      raw = chunk
-    }
-  end
-end
 local create_response_stream_filter
 create_response_stream_filter = function(chunk_callback)
   assert(types["function"](chunk_callback), "Must provide chunk_callback function when streaming response")
@@ -186,12 +147,7 @@ create_response_stream_filter = function(chunk_callback)
               return cjson.decode(json_data)
             end)
             if success then
-              do
-                local chunk_data = parse_response_stream_chunk(parsed)
-                if chunk_data then
-                  chunk_callback(chunk_data)
-                end
-              end
+              chunk_callback(parsed)
             end
           end
         end
@@ -245,15 +201,20 @@ do
       local wrapped_callback
       if merged_opts.stream then
         wrapped_callback = function(chunk)
-          if chunk.text_delta then
-            table.insert(accumulated_text, chunk.text_delta)
-          end
-          if chunk.response then
-            add_response_helpers(chunk.response)
-            final_response = chunk.response
-          end
-          if stream_callback then
-            return stream_callback(chunk)
+          local _exp_0 = chunk.type
+          if "response.output_text.delta" == _exp_0 then
+            table.insert(accumulated_text, chunk.delta)
+            if stream_callback then
+              return stream_callback(chunk.delta, chunk)
+            end
+          elseif "response.completed" == _exp_0 then
+            if type(chunk.response) == "table" then
+              local parsed = parse_responses_response(chunk.response)
+              if parsed then
+                add_response_helpers(parsed)
+                final_response = parsed
+              end
+            end
           end
         end
       end

openai/responses.moon

@@ -95,42 +95,6 @@ parse_responses_response = types.partial {
   status: empty + types.string\tag "status"
 }
 
-parse_response_stream_chunk = (chunk) ->
-  return unless type(chunk) == "table"
-  return unless chunk.type
-
-  -- New Responses streaming format
-  if chunk.type == "response.output_text.delta" and type(chunk.delta) == "string"
-    return {
-      type: chunk.type
-      text_delta: chunk.delta
-      raw: chunk
-    }
-
-  if chunk.type == "response.completed" and type(chunk.response) == "table"
-    parsed, err = parse_responses_response chunk.response
-    if parsed
-      chunk.response = parsed
-      return chunk
-    else
-      return nil, err
-
-  -- Support older/alternate streaming formats
-  if chunk.delta and type(chunk.delta.text) == "string"
-    return {
-      type: chunk.type
-      text_delta: chunk.delta.text
-      raw: chunk
-    }
-
-  if chunk.content_block_delta and type(chunk.content_block_delta.text) == "string"
-    return {
-      type: chunk.type
-      text_delta: chunk.content_block_delta.text
-      raw: chunk
-    }
-
-
 -- creates a ltn12 compatible filter function that will call chunk_callback
 -- for each parsed json chunk from the server-sent events api response
 create_response_stream_filter = (chunk_callback) ->
@@ -159,8 +123,7 @@ create_response_stream_filter = (chunk_callback) ->
           if json_data != "[DONE]"
             success, parsed = pcall -> cjson.decode json_data
             if success
-              if chunk_data = parse_response_stream_chunk parsed
-                chunk_callback chunk_data
+              chunk_callback parsed
 
     ...
 
@@ -212,15 +175,17 @@ class ResponsesChatSession
 
     wrapped_callback = if merged_opts.stream
       (chunk) ->
-        if chunk.text_delta
-          table.insert accumulated_text, chunk.text_delta
-
-        if chunk.response
-          add_response_helpers chunk.response
-          final_response = chunk.response
-
-        if stream_callback
-          stream_callback chunk
+        switch chunk.type
+          when "response.output_text.delta"
+            table.insert accumulated_text, chunk.delta
+            if stream_callback
+              stream_callback chunk.delta, chunk
+          when "response.completed"
+            if type(chunk.response) == "table"
+              parsed = parse_responses_response chunk.response
+              if parsed
+                add_response_helpers parsed
+                final_response = parsed
 
     status, response = @client\create_response input, merged_opts, wrapped_callback
 

spec/openai_spec.moon

@@ -588,10 +588,10 @@ describe "OpenAI API Client", ->
       -- Raw API returns the concatenated SSE data
       assert.truthy response
 
-      -- Stream callback received parsed chunks
+      -- Stream callback received raw event objects
       assert.same 3, #received
-      assert.same "Hello", received[1].text_delta
-      assert.same " world", received[2].text_delta
+      assert.same {type: "response.output_text.delta", delta: "Hello"}, received[1]
+      assert.same {type: "response.output_text.delta", delta: " world"}, received[2]
       assert.same "response.completed", received[3].type
 
     it "streams response deltas via session", ->
@@ -612,33 +612,17 @@ describe "OpenAI API Client", ->
         200, table.concat chunks
 
       received = {}
-      stream_callback = (chunk) ->
-        table.insert received, chunk
-
-        if chunk.response
-          assert.same "resp_stream", chunk.response.id
-          assert.same "Hello world", chunk.response\get_output_text!
+      stream_callback = (delta, raw) ->
+        table.insert received, {delta, raw}
 
       session = client\new_responses_chat_session { model: "gpt-4.1-mini" }
       out = assert session\send "Say hello back", stream_callback
 
       -- Session returns accumulated text
       assert.same "Hello world", out
 
+      -- Callback receives delta string and raw event object
       assert.same {
-        { type: "response.output_text.delta", text_delta: "Hello", raw: { type: "response.output_text.delta", delta: "Hello" } }
-        { type: "response.output_text.delta", text_delta: " world", raw: { type: "response.output_text.delta", delta: " world" } }
-        { type: "response.completed", response: {
-            id: "resp_stream"
-            object: "response"
-            output: {
-              {
-                type: "message"
-                role: "assistant"
-                content: {
-                  { type: "output_text", text: "Hello world" }
-                }
-              }
-            }
-          }}
+        {"Hello", {type: "response.output_text.delta", delta: "Hello"}}
+        {" world", {type: "response.output_text.delta", delta: " world"}}
       }, received