feat: chat completion streaming helpers (#828)

* add chat completion streaming helpers

* add basic sorbet types

* temp: add big demo

* simplify parsed fields for tool calls

* refactor parse methods

* remove anonymous tool default

* rm ParsedChatCompletionMessage

* update naming

* fix docs

* remove redundant filter

* undo

* update event methods to return values

* style

* remove big demo

---------

Co-authored-by: dogisgreat <[email protected]>

Author: renfredxh

examples/chat/streaming_basic.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+stream = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  messages: [
+    {role: :user, content: "Write a creative haiku about the ocean."}
+  ]
+)
+
+stream.each do |event|
+  case event
+  when OpenAI::Streaming::ChatContentDeltaEvent
+    print(event.delta)
+  when OpenAI::Streaming::ChatContentDoneEvent
+    puts
+  end
+end

examples/chat/streaming_follow_up.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+# This example demonstrates how to start a new streamed chat completion that includes prior turns by
+# resending the conversation messages.
+#
+# 1. Start with an initial user turn and stream the assistant reply.
+messages = [
+  {role: :user, content: "Tell me a short story about a robot. Stop after 2 sentences."}
+]
+
+puts "First streamed completion:"
+assistant_text = ""
+
+stream1 = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  messages: messages
+)
+
+stream1.each do |event|
+  case event
+  when OpenAI::Streaming::ChatContentDeltaEvent
+    assistant_text += event.delta
+    print(event.delta)
+  when OpenAI::Streaming::ChatContentDoneEvent
+    puts
+  end
+end
+
+# 2. Start a new streamed completion that includes the prior assistant turn
+#    and adds a follow-up user instruction.
+messages << {role: :assistant, content: assistant_text}
+messages << {role: :user, content: "Continue the story with 2 more sentences while keeping the same style."}
+
+puts
+puts "Second streamed completion (with prior turns included):"
+
+stream2 = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  messages: messages
+)
+
+stream2.each do |event|
+  case event
+  when OpenAI::Streaming::ChatContentDeltaEvent
+    print(event.delta)
+  when OpenAI::Streaming::ChatContentDoneEvent
+    puts
+  end
+end
+
+puts
+puts "Done. The second stream is a new completion that used the prior turns as context."

examples/chat/streaming_logprobs.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+stream = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  logprobs: true,
+  top_logprobs: 3,
+  messages: [
+    {role: :user, content: "Finish the sentence: The capital of France is"}
+  ]
+)
+
+stream.each do |event|
+  case event
+  when OpenAI::Streaming::ChatContentDeltaEvent
+    print(event.delta)
+  when OpenAI::Streaming::ChatLogprobsContentDeltaEvent
+    # Print top logprobs for the last token in the delta
+    tokens = event.content
+    last = tokens.last
+    next unless last
+    alts = last.top_logprobs.map { |t| "#{t.token}=#{format('%.2f', t.logprob)}" }.join(", ")
+    puts("\nlogprobs: [#{alts}]")
+  when OpenAI::Streaming::ChatLogprobsContentDoneEvent
+    puts("\n--- logprobs collection finished (#{event.content.length} tokens) ---")
+  end
+end

examples/chat/streaming_multi_choice.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+stream = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  n: 2,
+  messages: [
+    {role: :user, content: "Give me two short taglines for a beach resort."}
+  ]
+)
+
+choice_contents = {}
+choice_finished = {}
+
+stream.each do |event|
+  case event
+  when OpenAI::Streaming::ChatChunkEvent
+    # Access the full snapshot with all choices:
+    event.snapshot.choices.each_with_index do |choice, index|
+      if choice.message.content
+        choice_contents[index] = choice.message.content
+      end
+
+      next unless choice.finish_reason && !choice_finished[index]
+      choice_finished[index] = true
+      # Print the complete content for this choice when it finishes:
+      puts("[choice #{index}] complete:")
+      puts(choice_contents[index])
+      puts("--- choice #{index} done ---")
+      puts
+    end
+  end
+end
+
+puts("------ final choices ------")
+choice_contents.keys.sort.each do |i|
+  puts("[#{i}] #{choice_contents[i]}")
+end

examples/chat/streaming_structured_outputs.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+class Step < OpenAI::BaseModel
+  required :explanation, String
+  required :output, String
+end
+
+class MathResponse < OpenAI::BaseModel
+  required :steps, OpenAI::ArrayOf[Step]
+  required :final_answer, String
+end
+
+client = OpenAI::Client.new
+
+stream = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  response_format: MathResponse,
+  messages: [
+    {role: :user, content: "solve 8x + 31 = 2, show all steps"}
+  ]
+)
+
+stream.each do |event|
+  case event
+  when OpenAI::Streaming::ChatContentDeltaEvent
+    print(event.delta)
+  when OpenAI::Streaming::ChatContentDoneEvent
+    puts
+    puts("--- parsed object ---")
+    pp(event.parsed)
+  end
+end
+
+response = stream.get_final_completion
+
+puts
+puts("----- parsed outputs from final response -----")
+response
+  .choices
+  .each do |choice|
+    # parsed is an instance of `MathResponse`
+    pp(choice.message.parsed)
+  end

examples/chat/streaming_text.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+stream = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  messages: [
+    {role: :user, content: "List three fun facts about dolphins."}
+  ]
+)
+
+stream.text.each do |text|
+  print(text)
+end
+puts

examples/chat/streaming_tools.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+class GetWeather < OpenAI::BaseModel
+  required :location, String
+end
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+stream = client.chat.completions.stream(
+  model: "gpt-4o-mini",
+  tools: [GetWeather],
+  messages: [
+    {role: :user, content: "Call get_weather with location San Francisco in JSON."}
+  ]
+)
+
+stream.each do |event|
+  case event
+  when OpenAI::Streaming::ChatFunctionToolCallArgumentsDeltaEvent
+    puts("delta: #{event.arguments_delta}")
+    pp(event.parsed)
+  when OpenAI::Streaming::ChatFunctionToolCallArgumentsDoneEvent
+    puts("--- Tool call finalized ---")
+    puts("name: #{event.name}")
+    puts("args: #{event.arguments}")
+    pp(event.parsed)
+  end
+end