feat: added some usage examples

Author: ms-jpq

.github/workflows/create-releases.yml

@@ -0,0 +1,28 @@
+name: Create releases
+on:
+  schedule:
+    - cron: '0 5 * * *' # every day at 5am UTC
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: release
+    if: github.ref == 'refs/heads/main' && github.repository == 'openai/openai-ruby'
+    runs-on: ubuntu-latest
+    environment: publish
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: stainless-api/trigger-release-please@v1
+        id: release
+        with:
+          repo: ${{ github.event.repository.full_name }}
+          stainless-api-key: ${{ secrets.STAINLESS_API_KEY }}
+
+      - name: Update RubyDocs
+        if: ${{ steps.release.outputs.releases_created }}
+        run: |
+          curl -i -H "Content-Type: application/json" -X POST -d '{"repository":{"url":"https://github.com/openai/openai-ruby"}}' https://www.rubydoc.info/checkout

examples/.keep

@@ -0,0 +1,76 @@
+#!/usr/bin/env -S -- ruby
+# frozen_string_literal: true
+# typed: strong
+
+require_relative "../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+begin
+  pp("----- streams are enumerable -----")
+
+  stream = client.completions.create_streaming(
+    model: :"gpt-3.5-turbo-instruct",
+    prompt: "1,2,3,",
+    max_tokens: 5,
+    temperature: 0.0
+  )
+
+  # the `stream` itself is an `https://rubyapi.org/3.1/o/enumerable`
+  #   which means that you can work with the stream almost as if it is an array
+  all_choices =
+    stream
+    # calling any of the `enumerable` methods will block until the whole stream is consumed
+    #   it will also clean up the stream.
+    .select do |completion|
+      completion.object == :text_completion
+    end
+    .flat_map do |completion|
+      completion.choices
+    end
+
+  pp(all_choices)
+
+  # once the stream has been consumed, it will become "empty"
+  pp("this will print an empty array")
+  pp(stream.to_a)
+end
+
+begin
+  pp("----- streams can be lazy -----")
+
+  stream = client.completions.create_streaming(
+    model: :"gpt-3.5-turbo-instruct",
+    prompt: "1,2,3,",
+    max_tokens: 5,
+    temperature: 0.0
+  )
+
+  stream_of_choices =
+    stream
+    # calling `#lazy` will return a deferred `https://rubyapi.org/3.1/o/enumerator/lazy`
+    .lazy
+    # each successive calls to methods that return another `enumerable` will not consume the stream
+    #   but rather, return a transformed stream. (see link above)
+    .select do |completion|
+      completion.object == :text_completion
+    end
+    .flat_map do |completion|
+      completion.choices
+    end
+
+  # prints the suspended intermediary stream
+  pp(stream_of_choices)
+  # beware that if the intermediary stream is not used, a call to `stream.close` is required
+  #  to release the underlying connection
+
+  # method calls that do not return another `enumerable` will consume the intermediary stream
+  #   and perform cleanup
+  stream_of_choices.each do |choice|
+    pp(choice)
+  end
+
+  # at this point the stream has been consumed already, so it will return an empty array
+  pp(stream_of_choices.to_a)
+end

examples/advanced_streaming.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env -S -- ruby
+# frozen_string_literal: true
+# typed: strong
+
+require_relative "../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+begin
+  # Non-streaming:
+  pp("----- standard request -----")
+
+  completion = client.chat.completions.create(
+    model: "gpt-4",
+    messages: [
+      {
+        role: "user",
+        content: "Say this is a test"
+      }
+    ]
+  )
+
+  pp(completion.choices.first&.message&.content)
+end
+
+begin
+  # Streaming:
+  pp("----- streaming request -----")
+
+  stream = client.chat.completions.create_streaming(
+    model: "gpt-4",
+    messages: [
+      {
+        role: "user",
+        content: "How do I output all files in a directory using Python?"
+      }
+    ]
+  )
+
+  stream.each do |chunk|
+    next if chunk.choices.to_a.empty?
+
+    pp(chunk.choices.first&.delta&.content)
+  end
+end

examples/demo.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env -S -- ruby
+# frozen_string_literal: true
+# typed: strong
+
+require_relative "../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+begin
+  pp("----- named arguments in sorbet -----")
+
+  # the method signature in sorbet has named arguments
+  #   the following example type checks.
+  completion = client.chat.completions.create(
+    messages: [{role: :user, content: "Say this is a test"}],
+    model: "gpt-4"
+  )
+
+  pp(completion.choices.first&.message&.content)
+end
+
+
+begin
+  pp("----- trying to use params class in sorbet -----")
+
+  params = OpenAI::Models::Chat::CompletionCreateParams.new(
+    messages: [{role: :user, content: "Say this is a test again"}],
+    model: "gpt-4"
+  )
+
+  # if you have sorbet LSP enabled, and uncomment the two lines below 
+  #   you will see a red squiggly line on `params` due to a quirk of the sorbet type system.
+  #
+  # this file will still infact, run correctly as uncommented.
+
+  # completion = client.chat.completions.create(params)
+  # pp(completion.choices.first&.message&.content)
+end
+
+begin
+  pp("----- using params class correctly in sorbet -----")
+
+  params = OpenAI::Models::Chat::CompletionCreateParams.new(
+    messages: [{role: :user, content: "Say this is a test yet again"}],
+    model: "gpt-4"
+  )
+
+  # notice the `**` operator, it allows you to pass a parameter's class
+  #   into compatible methods that have named arguments
+  completion = client.chat.completions.create(**params)
+
+  pp(completion.choices.first&.message&.content)
+end

examples/demo_sorbet.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env -S -- ruby
+# frozen_string_literal: true
+# typed: strong
+
+require_relative "../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+prompt = "An astronaut lounging in a tropical resort in space, pixel art"
+
+# Generate an image based on the prompt
+response = client.images.generate(prompt: prompt)
+
+# Prints response containing a URL link to image
+pp(response)

examples/picture.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env -S -- ruby
+# frozen_string_literal: true
+# typed: strong
+
+require_relative "../lib/openai"
+
+# gets API Key from environment variable `OPENAI_API_KEY`
+client = OpenAI::Client.new
+
+begin
+  pp("----- streaming 101 -----")
+
+  stream = client.completions.create_streaming(
+    model: :"gpt-3.5-turbo-instruct",
+    prompt: "1,2,3,",
+    max_tokens: 5,
+    temperature: 0.0
+  )
+
+  # calling `#each` will always clean up the stream, even if an error is thrown inside the `#each` block.
+  stream.each do |data|
+    pp(data)
+
+    # it is possible to exit out of the `#each` loop early, this will also clean up the stream for you.
+    if data.choices.size > 2
+      pp("too many choices")
+      break
+    end
+  end
+
+  # once the stream has been exhausted, no more chunks will be produced.
+  stream.each do
+    pp("This will never run")
+  end
+end
+
+begin
+  pp("----- manual closing of stream -----")
+
+  stream = client.completions.create_streaming(
+    model: :"gpt-3.5-turbo-instruct",
+    prompt: "1,2,3,",
+    max_tokens: 5,
+    temperature: 0.0
+  )
+
+  # `stream` need to be manually closed if it is not consumed
+  stream.close
+end