ruby-openai 6.3.1 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 958a72f1590182a35f447bb66e286adde77217e58b5d81e9621cd00e7f62cf58
-  data.tar.gz: 46729b5fc28187ba376af8c24d02e6b96f8dd4a18dca5cd19ad6fcea09e9d6a1
+  metadata.gz: fb6b0c3d7f87d9db80a130891489e538f5abe737edd0faac2d95305b6b4f2071
+  data.tar.gz: 79ca8323159be1b6b4aadac2712535a8ac09ca658d3b9b9312b753f625cf9546
 SHA512:
-  metadata.gz: f50b6b5044c70a5e549600c5563ec57daf1aefd4301cf04ca5bb992942d5ff3a361ad26e1defefa9cdc490b4eeae7ced18c4b304a6b44245516501286005c159
-  data.tar.gz: 26ce015243210f29239e4f993baabdee6e5a0265708ee407d5f7d3bef17db50b398e35c7ab225724aaec8519abc35f80e2d928d44e821bdfe27f6ff9db2bcc79
+  metadata.gz: d3370f207d43c390ee0c0fd8d6fa7a3860877f0f6fefe27c0dfd17ae5d629162e37b5f02e627eb60737a47eef16f98a91f91fb10815256cb883b89e395f8a344
+  data.tar.gz: 22c23aeda4f01a56d285a76c86dc36e6175ce95e027b69dbf69cc306953a612dd994b55f7e4966f9bfc751c5c6afa677acbc0339cc54a2cd4f1482a2b0594ab2

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.4.0] - 2024-03-27
+
+### Added
+
+- Add DALL·E 3 to specs and README - thanks to [@Gary-H9](https://github.com/Gary-H9)
+- Add Whisper transcription language selection parameter to README - thanks to [@nfedyashev](https://github.com/nfedyashev)
+- Add bundle exec rake lint and bundle exec rake test to make development easier - thanks to [@ignacio-chiazzo](https://github.com/ignacio-chiazzo)
+- Add link to [https://github.com/sponsors/alexrudall](https://github.com/sponsors/alexrudall) when users run `bundle fund`
+
+### Fixed
+
+- Update README and spec to use tool calls instead of functions - thanks to [@mpallenjr](https://github.com/mpallenjr)
+- Remove nonexistent Thread#list method - thanks again! to [@ignacio-chiazzo](https://github.com/ignacio-chiazzo)
+- Update finetunes docs in README to use chat instead of completions endpoint - thanks to [@blefev](https://github.com/blefev)
+
 ## [6.3.1] - 2023-12-04
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-openai (6.3.1)
+    ruby-openai (6.4.0)
       event_stream_parser (>= 0.3.0, < 2.0.0)
       faraday (>= 1)
       faraday-multipart (>= 1)
@@ -12,14 +12,14 @@ GEM
     addressable (2.8.5)
       public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
-    base64 (0.1.1)
+    base64 (0.2.0)
     byebug (11.1.3)
     crack (0.4.5)
       rexml
     diff-lcs (1.5.0)
     dotenv (2.8.1)
     event_stream_parser (1.0.0)
-    faraday (2.7.11)
+    faraday (2.7.12)
       base64
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)

data/README.md

@@ -10,6 +10,55 @@ Stream text with GPT-4, transcribe and translate audio with Whisper, or create i
 
 [🚢 Hire me](https://peaceterms.com?utm_source=ruby-openai&utm_medium=readme&utm_id=26072023) | [🎮 Ruby AI Builders Discord](https://discord.gg/k4Uc224xVD) | [🐦 Twitter](https://twitter.com/alexrudall) | [🧠 Anthropic Gem](https://github.com/alexrudall/anthropic) | [🚂 Midjourney Gem](https://github.com/alexrudall/midjourney)
 
+# Table of Contents
+
+- [Ruby OpenAI](#ruby-openai)
+- [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [Bundler](#bundler)
+    - [Gem install](#gem-install)
+  - [Usage](#usage)
+    - [Quickstart](#quickstart)
+    - [With Config](#with-config)
+      - [Custom timeout or base URI](#custom-timeout-or-base-uri)
+      - [Extra Headers per Client](#extra-headers-per-client)
+      - [Verbose Logging](#verbose-logging)
+      - [Azure](#azure)
+    - [Counting Tokens](#counting-tokens)
+    - [Models](#models)
+      - [Examples](#examples)
+    - [Chat](#chat)
+      - [Streaming Chat](#streaming-chat)
+      - [Vision](#vision)
+      - [JSON Mode](#json-mode)
+    - [Functions](#functions)
+    - [Edits](#edits)
+    - [Embeddings](#embeddings)
+    - [Files](#files)
+    - [Finetunes](#finetunes)
+    - [Assistants](#assistants)
+    - [Threads and Messages](#threads-and-messages)
+    - [Runs](#runs)
+      - [Runs involving function tools](#runs-involving-function-tools)
+    - [Image Generation](#image-generation)
+      - [DALL·E 2](#dalle-2)
+      - [DALL·E 3](#dalle-3)
+    - [Image Edit](#image-edit)
+    - [Image Variations](#image-variations)
+    - [Moderations](#moderations)
+    - [Whisper](#whisper)
+      - [Translate](#translate)
+      - [Transcribe](#transcribe)
+      - [Speech](#speech)
+    - [Errors](#errors)
+  - [Development](#development)
+  - [Release](#release)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Code of Conduct](#code-of-conduct)
+
+## Installation
+
 ### Bundler
 
 Add this line to your application's Gemfile:
@@ -108,6 +157,15 @@ OpenAI.configure do |config|
 end
 ```
 
+#### Extra Headers per Client
+
+You can dynamically pass headers per client object, which will be merged with any headers set globally with OpenAI.configure:
+
+```ruby
+client = OpenAI::Client.new(access_token: "access_token_goes_here")
+client.add_headers("X-Proxy-TTL" => "43200")
+```
+
 #### Verbose Logging
 
 You can pass [Faraday middleware](https://lostisland.github.io/faraday/#/middleware/index) to the client in a block, eg. to enable verbose logging with Ruby's [Logger](https://ruby-doc.org/3.2.2/stdlibs/logger/Logger.html):
@@ -297,36 +355,39 @@ response =
           "content": "What is the weather like in San Francisco?",
         },
       ],
-      functions: [
+      tools: [
         {
-          name: "get_current_weather",
-          description: "Get the current weather in a given location",
-          parameters: {
-            type: :object,
-            properties: {
-              location: {
-                type: :string,
-                description: "The city and state, e.g. San Francisco, CA",
-              },
-              unit: {
-                type: "string",
-                enum: %w[celsius fahrenheit],
+          type: "function",
+          function: {
+            name: "get_current_weather",
+            description: "Get the current weather in a given location",
+            parameters: {
+              type: :object,
+              properties: {
+                location: {
+                  type: :string,
+                  description: "The city and state, e.g. San Francisco, CA",
+                },
+                unit: {
+                  type: "string",
+                  enum: %w[celsius fahrenheit],
+                },
               },
+              required: ["location"],
             },
-            required: ["location"],
           },
-        },
+        }
       ],
     },
   )
 
 message = response.dig("choices", 0, "message")
 
-if message["role"] == "assistant" && message["function_call"]
-  function_name = message.dig("function_call", "name")
+if message["role"] == "assistant" && message["tool_calls"]
+  function_name = message.dig("tool_calls", "function",  "name")
   args =
     JSON.parse(
-      message.dig("function_call", "arguments"),
+      message.dig("tool_calls", "function", "arguments"),
       { symbolize_names: true },
     )
 
@@ -423,16 +484,16 @@ response = client.finetunes.retrieve(id: fine_tune_id)
 fine_tuned_model = response["fine_tuned_model"]
 ```
 
-This fine-tuned model name can then be used in completions:
+This fine-tuned model name can then be used in chat completions:
 
 ```ruby
-response = client.completions(
+response = client.chat(
     parameters: {
         model: fine_tuned_model,
-        prompt: "I love Mondays!"
+        messages: [{ role: "user", content: "I love Mondays!"}]
     }
 )
-response.dig("choices", 0, "text")
+response.dig("choices", 0, "message", "content")
 ```
 
 You can also capture the events for a job:
@@ -441,10 +502,221 @@ You can also capture the events for a job:
 client.finetunes.list_events(id: fine_tune_id)
 ```
 
+### Assistants
+
+Assistants can call models to interact with threads and use tools to perform tasks (see [Assistant Overview](https://platform.openai.com/docs/assistants/overview)).
+
+To create a new assistant (see [API documentation](https://platform.openai.com/docs/api-reference/assistants/createAssistant)):
+
+```ruby
+response = client.assistants.create(
+    parameters: {
+        model: "gpt-3.5-turbo-1106",         # Retrieve via client.models.list. Assistants need 'gpt-3.5-turbo-1106' or later.
+        name: "OpenAI-Ruby test assistant",
+        description: nil,
+        instructions: "You are a helpful assistant for coding a OpenAI API client using the OpenAI-Ruby gem.",
+        tools: [
+            { type: 'retrieval' },           # Allow access to files attached using file_ids
+            { type: 'code_interpreter' },    # Allow access to Python code interpreter
+        ],
+        "file_ids": ["file-123"],            # See Files section above for how to upload files
+        "metadata": { my_internal_version_id: '1.0.0' }
+    })
+assistant_id = response["id"]
+```
+
+Given an `assistant_id` you can `retrieve` the current field values:
+
+```ruby
+client.assistants.retrieve(id: assistant_id)
+```
+
+You can get a `list` of all assistants currently available under the organization:
+
+```ruby
+client.assistants.list
+```
+
+You can modify an existing assistant using the assistant's id (see [API documentation](https://platform.openai.com/docs/api-reference/assistants/modifyAssistant)):
+
+```ruby
+response = client.assistants.modify(
+        id: assistant_id,
+        parameters: {
+            name: "Modified Test Assistant for OpenAI-Ruby",
+            metadata: { my_internal_version_id: '1.0.1' }
+        })
+```
+
+You can delete assistants:
+
+```
+client.assistants.delete(id: assistant_id)
+```
+
+### Threads and Messages
+
+Once you have created an assistant as described above, you need to prepare a `Thread` of `Messages` for the assistant to work on (see [introduction on Assistants](https://platform.openai.com/docs/assistants/how-it-works)). For example, as an initial setup you could do:
+
+```ruby
+# Create thread
+response = client.threads.create # Note: Once you create a thread, there is no way to list it
+                                 # or recover it currently (as of 2023-12-10). So hold onto the `id`
+thread_id = response["id"]
+
+# Add initial message from user (see https://platform.openai.com/docs/api-reference/messages/createMessage)
+message_id = client.messages.create(
+    thread_id: thread_id,
+    parameters: {
+        role: "user", # Required for manually created messages
+        content: "Can you help me write an API library to interact with the OpenAI API please?"
+    })["id"]
+
+# Retrieve individual message
+message = client.messages.retrieve(thread_id: thread_id, id: message_id)
+
+# Review all messages on the thread
+messages = client.messages.list(thread_id: thread_id)
+```
+
+To clean up after a thread is no longer needed:
+
+```ruby
+# To delete the thread (and all associated messages):
+client.threads.delete(id: thread_id)
+
+client.messages.retrieve(thread_id: thread_id, id: message_id) # -> Fails after thread is deleted
+```
+
+### Runs
+
+To submit a thread to be evaluated with the model of an assistant, create a `Run` as follows (Note: This is one place where OpenAI will take your money):
+
+```ruby
+# Create run (will use instruction/model/tools from Assistant's definition)
+response = client.runs.create(thread_id: thread_id,
+    parameters: {
+        assistant_id: assistant_id
+    })
+run_id = response['id']
+
+# Retrieve/poll Run to observe status
+response = client.runs.retrieve(id: run_id, thread_id: thread_id)
+status = response['status']
+```
+
+The `status` response can include the following strings `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, or `expired` which you can handle as follows:
+
+```ruby
+while true do
+
+    response = client.runs.retrieve(id: run_id, thread_id: thread_id)
+    status = response['status']
+
+    case status
+    when 'queued', 'in_progress', 'cancelling'
+        puts 'Sleeping'
+        sleep 1 # Wait one second and poll again
+    when 'completed'
+        break # Exit loop and report result to user
+    when 'requires_action'
+        # Handle tool calls (see below)
+    when 'cancelled', 'failed', 'expired'
+        puts response['last_error'].inspect
+        break # or `exit`
+    else
+        puts "Unknown status response: #{status}"
+    end
+end
+```
+
+If the `status` response indicates that the `run` is `completed`, the associated `thread` will have one or more new `messages` attached:
+
+```ruby
+# Either retrieve all messages in bulk again, or...
+messages = client.messages.list(thread_id: thread_id) # Note: as of 2023-12-11 adding limit or order options isn't working, yet
+
+# Alternatively retrieve the `run steps` for the run which link to the messages:
+run_steps = client.run_steps.list(thread_id: thread_id, run_id: run_id)
+new_message_ids = run_steps['data'].filter_map { |step|
+  if step['type'] == 'message_creation'
+    step.dig('step_details', "message_creation", "message_id")
+  end # Ignore tool calls, because they don't create new messages.
+}
+
+# Retrieve the individual messages
+new_messages = new_message_ids.map { |msg_id|
+  client.messages.retrieve(id: msg_id, thread_id: thread_id)
+}
+
+# Find the actual response text in the content array of the messages
+new_messages.each { |msg|
+    msg['content'].each { |content_item|
+        case content_item['type']
+        when 'text'
+            puts content_item.dig('text', 'value')
+            # Also handle annotations
+        when 'image_file'
+            # Use File endpoint to retrieve file contents via id
+            id = content_item.dig('image_file', 'file_id')
+        end
+    }
+}
+```
+
+At any time you can list all runs which have been performed on a particular thread or are currently running (in descending/newest first order):
+
+```ruby
+client.runs.list(thread_id: thread_id)
+```
+
+#### Runs involving function tools
+
+In case you are allowing the assistant to access `function` tools (they are defined in the same way as functions during chat completion), you might get a status code of `requires_action` when the assistant wants you to evaluate one or more function tools:
+
+```ruby
+def get_current_weather(location:, unit: "celsius")
+    # Your function code goes here
+    if location =~ /San Francisco/i
+        return unit == "celsius" ? "The weather is nice 🌞 at 27°C" : "The weather is nice 🌞 at 80°F"
+    else
+        return unit == "celsius" ? "The weather is icy 🥶 at -5°C" : "The weather is icy 🥶 at 23°F"
+    end
+end
+
+if status == 'requires_action'
+
+    tools_to_call = response.dig('required_action', 'submit_tool_outputs', 'tool_calls')
+
+    my_tool_outputs = tools_to_call.map { |tool|
+        # Call the functions based on the tool's name
+        function_name = tool.dig('function', 'name')
+        arguments = JSON.parse(
+              tool.dig("function", "arguments"),
+              { symbolize_names: true },
+        )
+
+        tool_output = case function_name
+        when "get_current_weather"
+            get_current_weather(**arguments)
+        end
+
+        { tool_call_id: tool['id'], output: tool_output }
+    }
+
+    client.runs.submit_tool_outputs(thread_id: thread_id, run_id: run_id, parameters: { tool_outputs: my_tool_outputs })
+end
+```
+
+Note that you have 10 minutes to submit your tool output before the run expires.
+
 ### Image Generation
 
-Generate an image using DALL·E! The size of any generated images must be one of `256x256`, `512x512` or `1024x1024` -
-if not specified the image will default to `1024x1024`.
+Generate images using DALL·E 2 or DALL·E 3!
+
+#### DALL·E 2
+
+For DALL·E 2 the size of any generated images must be one of `256x256`, `512x512` or `1024x1024` - if not specified the image will default to `1024x1024`.
 
 ```ruby
 response = client.images.generate(parameters: { prompt: "A baby sea otter cooking pasta wearing a hat of some sort", size: "256x256" })
@@ -454,6 +726,18 @@ puts response.dig("data", 0, "url")
 
 ![Ruby](https://i.ibb.co/6y4HJFx/img-d-Tx-Rf-RHj-SO5-Gho-Cbd8o-LJvw3.png)
 
+#### DALL·E 3
+
+For DALL·E 3 the size of any generated images must be one of `1024x1024`, `1024x1792` or `1792x1024`. Additionally the quality of the image can be specified to either `standard` or `hd`.
+
+```ruby
+response = client.images.generate(parameters: { prompt: "A springer spaniel cooking pasta wearing a hat of some sort", size: "1024x1792", quality: "standard" })
+puts response.dig("data", 0, "url")
+# => "https://oaidalleapiprodscus.blob.core.windows.net/private/org-Rf437IxKhh..."
+```
+
+![Ruby](https://i.ibb.co/z2tCKv9/img-Goio0l-S0i81-NUNa-BIx-Eh-CT6-L.png)
+
 ### Image Edit
 
 Fill in the transparent part of an image, or upload a mask with transparent sections to indicate the parts of an image that can be changed according to your prompt...
@@ -511,11 +795,14 @@ puts response["text"]
 
 The transcriptions API takes as input the audio file you want to transcribe and returns the text in the desired output file format.
 
+You can pass the language of the audio file to improve transcription quality. Supported languages are listed [here](https://github.com/openai/whisper#available-models-and-languages). You need to provide the language as an ISO-639-1 code, eg. "en" for English or "ne" for Nepali. You can look up the codes [here](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).
+
 ```ruby
 response = client.audio.transcribe(
     parameters: {
         model: "whisper-1",
         file: File.open("path_to_file", "rb"),
+        language: "en" # Optional.
     })
 puts response["text"]
 # => "Transcription of the text"
@@ -555,9 +842,10 @@ After checking out the repo, run `bin/setup` to install dependencies. You can ru
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
-### Warning
+To run all tests, execute the command `bundle exec rake`, which will also run the linter (Rubocop). This repository uses [VCR](https://github.com/vcr/vcr) to log API requests.
 
-If you have an `OPENAI_ACCESS_TOKEN` in your `ENV`, running the specs will use this to run the specs against the actual API, which will be slow and cost you money - 2 cents or more! Remove it from your environment with `unset` or similar if you just want to run the specs against the stored VCR responses.
+> [!WARNING]
+> If you have an `OPENAI_ACCESS_TOKEN` in your `ENV`, running the specs will use this to run the specs against the actual API, which will be slow and cost you money - 2 cents or more! Remove it from your environment with `unset` or similar if you just want to run the specs against the stored VCR responses.
 
 ## Release
 

data/Rakefile

@@ -1,6 +1,19 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+task :default do
+  Rake::Task["test"].invoke
+  Rake::Task["lint"].invoke
+end
+
+task :test do
+  Rake::Task["spec"].invoke
+end
+
+task :lint do
+  RuboCop::RakeTask.new(:rubocop)
+  Rake::Task["rubocop"].invoke
+end

data/lib/openai/threads.rb

@@ -4,10 +4,6 @@ module OpenAI
       @client = client.beta(assistants: "v1")
     end
 
-    def list
-      @client.get(path: "/threads")
-    end
-
     def retrieve(id:)
       @client.get(path: "/threads/#{id}")
     end

data/lib/openai/version.rb

@@ -1,3 +1,3 @@
 module OpenAI
-  VERSION = "6.3.1".freeze
+  VERSION = "6.4.0".freeze
 end

data/ruby-openai.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = "https://github.com/alexrudall/ruby-openai"
   spec.metadata["changelog_uri"] = "https://github.com/alexrudall/ruby-openai/blob/main/CHANGELOG.md"
   spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["funding_uri"] = "https://github.com/sponsors/alexrudall"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-openai
 version: !ruby/object:Gem::Version
-  version: 6.3.1
+  version: 6.4.0
 platform: ruby
 authors:
 - Alex
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-04 00:00:00.000000000 Z
+date: 2024-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -58,7 +58,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1'
-description: 
+description:
 email:
 - alexrudall@users.noreply.github.com
 executables: []
@@ -113,7 +113,8 @@ metadata:
   source_code_uri: https://github.com/alexrudall/ruby-openai
   changelog_uri: https://github.com/alexrudall/ruby-openai/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message: 
+  funding_uri: https://github.com/sponsors/alexrudall
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -128,8 +129,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key: 
+rubygems_version: 3.4.22
+signing_key:
 specification_version: 4
 summary: "OpenAI API + Ruby! \U0001F916\U0001FA75"
 test_files: []