ruby-openai 7.3.0 → 7.4.0

data/README.md

@@ -1,14 +1,17 @@
 # Ruby OpenAI
-
 [![Gem Version](https://img.shields.io/gem/v/ruby-openai.svg)](https://rubygems.org/gems/ruby-openai)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/alexrudall/ruby-openai/blob/main/LICENSE.txt)
 [![CircleCI Build Status](https://circleci.com/gh/alexrudall/ruby-openai.svg?style=shield)](https://circleci.com/gh/alexrudall/ruby-openai)
 
 Use the [OpenAI API](https://openai.com/blog/openai-api/) with Ruby! 🤖❤️
 
-Stream text with GPT-4o, transcribe and translate audio with Whisper, or create images with DALL·E...
+Stream text with GPT-4, transcribe and translate audio with Whisper, or create images with DALL·E...
+
+💥 Click [subscribe now](https://mailchi.mp/8c7b574726a9/ruby-openai) to hear first about new releases in the Rails AI newsletter!
 
-[📚 Rails AI (FREE Book)](https://railsai.com) | [🎮 Ruby AI Builders Discord](https://discord.gg/k4Uc224xVD) | [🐦 X](https://x.com/alexrudall) | [🧠 Anthropic Gem](https://github.com/alexrudall/anthropic) | [🚂 Midjourney Gem](https://github.com/alexrudall/midjourney)
+[![RailsAI Newsletter](https://github.com/user-attachments/assets/737cbb99-6029-42b8-9f22-a106725a4b1f)](https://mailchi.mp/8c7b574726a9/ruby-openai)
+
+[🎮 Ruby AI Builders Discord](https://discord.gg/k4Uc224xVD) | [🐦 X](https://x.com/alexrudall) | [🧠 Anthropic Gem](https://github.com/alexrudall/anthropic) | [🚂 Midjourney Gem](https://github.com/alexrudall/midjourney)
 
 ## Contents
 
@@ -17,7 +20,7 @@ Stream text with GPT-4o, transcribe and translate audio with Whisper, or create
   - [Installation](#installation)
     - [Bundler](#bundler)
     - [Gem install](#gem-install)
-  - [Usage](#usage)
+  - [How to use](#how-to-use)
     - [Quickstart](#quickstart)
     - [With Config](#with-config)
       - [Custom timeout or base URI](#custom-timeout-or-base-uri)
@@ -49,7 +52,9 @@ Stream text with GPT-4o, transcribe and translate audio with Whisper, or create
     - [Threads and Messages](#threads-and-messages)
     - [Runs](#runs)
       - [Create and Run](#create-and-run)
+      - [Vision in a thread](#vision-in-a-thread)
       - [Runs involving function tools](#runs-involving-function-tools)
+      - [Exploring chunks used in File Search](#exploring-chunks-used-in-file-search)
     - [Image Generation](#image-generation)
       - [DALL·E 2](#dalle-2)
       - [DALL·E 3](#dalle-3)
@@ -60,6 +65,7 @@ Stream text with GPT-4o, transcribe and translate audio with Whisper, or create
       - [Translate](#translate)
       - [Transcribe](#transcribe)
       - [Speech](#speech)
+    - [Usage](#usage)
     - [Errors](#errors-1)
   - [Development](#development)
   - [Release](#release)
@@ -97,7 +103,7 @@ and require with:
 require "openai"
 ```
 
-## Usage
+## How to use
 
 - Get your API key from [https://platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys)
 - If you belong to multiple organizations, you can get your Organization ID from [https://platform.openai.com/account/org-settings](https://platform.openai.com/account/org-settings)
@@ -120,6 +126,7 @@ For a more robust setup, you can configure the gem with your API keys, for examp
 ```ruby
 OpenAI.configure do |config|
   config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
+  config.admin_token = ENV.fetch("OPENAI_ADMIN_TOKEN") # Optional, used for admin endpoints, created here: https://platform.openai.com/settings/organization/admin-keys
   config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional
   config.log_errors = true # Highly recommended in development, so you can see what errors OpenAI is returning. Not recommended in production because it could leak private data to your logs.
 end
@@ -131,10 +138,10 @@ Then you can create a client like this:
 client = OpenAI::Client.new
 ```
 
-You can still override the config defaults when making new clients; any options not included will fall back to any global config set with OpenAI.configure. e.g. in this example the organization_id, request_timeout, etc. will fallback to any set globally using OpenAI.configure, with only the access_token overridden:
+You can still override the config defaults when making new clients; any options not included will fall back to any global config set with OpenAI.configure. e.g. in this example the organization_id, request_timeout, etc. will fallback to any set globally using OpenAI.configure, with only the access_token and admin_token overridden:
 
 ```ruby
-client = OpenAI::Client.new(access_token: "access_token_goes_here")
+client = OpenAI::Client.new(access_token: "access_token_goes_here", admin_token: "admin_token_goes_here")
 ```
 
 #### Custom timeout or base URI
@@ -145,15 +152,15 @@ client = OpenAI::Client.new(access_token: "access_token_goes_here")
 
 ```ruby
 client = OpenAI::Client.new(
-    access_token: "access_token_goes_here",
-    uri_base: "https://oai.hconeai.com/",
-    request_timeout: 240,
-    extra_headers: {
-      "X-Proxy-TTL" => "43200", # For https://github.com/6/openai-caching-proxy-worker#specifying-a-cache-ttl
-      "X-Proxy-Refresh": "true", # For https://github.com/6/openai-caching-proxy-worker#refreshing-the-cache
-      "Helicone-Auth": "Bearer HELICONE_API_KEY", # For https://docs.helicone.ai/getting-started/integration-method/openai-proxy
-      "helicone-stream-force-format" => "true", # Use this with Helicone otherwise streaming drops chunks # https://github.com/alexrudall/ruby-openai/issues/251
-    }
+  access_token: "access_token_goes_here",
+  uri_base: "https://oai.hconeai.com/",
+  request_timeout: 240,
+  extra_headers: {
+    "X-Proxy-TTL" => "43200", # For https://github.com/6/openai-caching-proxy-worker#specifying-a-cache-ttl
+    "X-Proxy-Refresh": "true", # For https://github.com/6/openai-caching-proxy-worker#refreshing-the-cache
+    "Helicone-Auth": "Bearer HELICONE_API_KEY", # For https://docs.helicone.ai/getting-started/integration-method/openai-proxy
+    "helicone-stream-force-format" => "true", # Use this with Helicone otherwise streaming drops chunks # https://github.com/alexrudall/ruby-openai/issues/251
+  }
 )
 ```
 
@@ -161,16 +168,17 @@ or when configuring the gem:
 
 ```ruby
 OpenAI.configure do |config|
-    config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
-    config.log_errors = true # Optional
-    config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional
-    config.uri_base = "https://oai.hconeai.com/" # Optional
-    config.request_timeout = 240 # Optional
-    config.extra_headers = {
-      "X-Proxy-TTL" => "43200", # For https://github.com/6/openai-caching-proxy-worker#specifying-a-cache-ttl
-      "X-Proxy-Refresh": "true", # For https://github.com/6/openai-caching-proxy-worker#refreshing-the-cache
-      "Helicone-Auth": "Bearer HELICONE_API_KEY" # For https://docs.helicone.ai/getting-started/integration-method/openai-proxy
-    } # Optional
+  config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
+  config.admin_token = ENV.fetch("OPENAI_ADMIN_TOKEN") # Optional, used for admin endpoints, created here: https://platform.openai.com/settings/organization/admin-keys
+  config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional
+  config.log_errors = true # Optional
+  config.uri_base = "https://oai.hconeai.com/" # Optional
+  config.request_timeout = 240 # Optional
+  config.extra_headers = {
+    "X-Proxy-TTL" => "43200", # For https://github.com/6/openai-caching-proxy-worker#specifying-a-cache-ttl
+    "X-Proxy-Refresh": "true", # For https://github.com/6/openai-caching-proxy-worker#refreshing-the-cache
+    "Helicone-Auth": "Bearer HELICONE_API_KEY" # For https://docs.helicone.ai/getting-started/integration-method/openai-proxy
+  } # Optional
 end
 ```
 
@@ -192,7 +200,7 @@ By default, `ruby-openai` does not log any `Faraday::Error`s encountered while e
 If you would like to enable this functionality, you can set `log_errors` to `true` when configuring the client:
 
 ```ruby
-  client = OpenAI::Client.new(log_errors: true)
+client = OpenAI::Client.new(log_errors: true)
 ```
 
 ##### Faraday middleware
@@ -200,9 +208,9 @@ If you would like to enable this functionality, you can set `log_errors` to `tru
 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):
 
 ```ruby
-  client = OpenAI::Client.new do |f|
-    f.response :logger, Logger.new($stdout), bodies: true
-  end
+client = OpenAI::Client.new do |f|
+  f.response :logger, Logger.new($stdout), bodies: true
+end
 ```
 
 #### Azure
@@ -210,12 +218,12 @@ You can pass [Faraday middleware](https://lostisland.github.io/faraday/#/middlew
 To use the [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/cognitive-services/openai/) API, you can configure the gem like this:
 
 ```ruby
-    OpenAI.configure do |config|
-        config.access_token = ENV.fetch("AZURE_OPENAI_API_KEY")
-        config.uri_base = ENV.fetch("AZURE_OPENAI_URI")
-        config.api_type = :azure
-        config.api_version = "2023-03-15-preview"
-    end
+OpenAI.configure do |config|
+  config.access_token = ENV.fetch("AZURE_OPENAI_API_KEY")
+  config.uri_base = ENV.fetch("AZURE_OPENAI_URI")
+  config.api_type = :azure
+  config.api_version = "2023-03-15-preview"
+end
 ```
 
 where `AZURE_OPENAI_URI` is e.g. `https://custom-domain.openai.azure.com/openai/deployments/gpt-35-turbo`
@@ -240,14 +248,15 @@ client = OpenAI::Client.new(
 )
 
 client.chat(
-    parameters: {
-        model: "llama3", # Required.
-        messages: [{ role: "user", content: "Hello!"}], # Required.
-        temperature: 0.7,
-        stream: proc do |chunk, _bytesize|
-            print chunk.dig("choices", 0, "delta", "content")
-        end
-    })
+  parameters: {
+    model: "llama3", # Required.
+    messages: [{ role: "user", content: "Hello!"}], # Required.
+    temperature: 0.7,
+    stream: proc do |chunk, _bytesize|
+      print chunk.dig("choices", 0, "delta", "content")
+    end
+  }
+)
 
 # => Hi! It's nice to meet you. Is there something I can help you with, or would you like to chat?
 ```
@@ -257,20 +266,21 @@ client.chat(
 [Groq API Chat](https://console.groq.com/docs/quickstart) is broadly compatible with the OpenAI API, with a [few minor differences](https://console.groq.com/docs/openai). Get an access token from [here](https://console.groq.com/keys), then:
 
 ```ruby
-  client = OpenAI::Client.new(
-    access_token: "groq_access_token_goes_here",
-    uri_base: "https://api.groq.com/openai"
-  )
+client = OpenAI::Client.new(
+  access_token: "groq_access_token_goes_here",
+  uri_base: "https://api.groq.com/openai"
+)
 
-  client.chat(
-    parameters: {
-        model: "llama3-8b-8192", # Required.
-        messages: [{ role: "user", content: "Hello!"}], # Required.
-        temperature: 0.7,
-        stream: proc do |chunk, _bytesize|
-            print chunk.dig("choices", 0, "delta", "content")
-        end
-    })
+client.chat(
+  parameters: {
+    model: "llama3-8b-8192", # Required.
+    messages: [{ role: "user", content: "Hello!"}], # Required.
+    temperature: 0.7,
+    stream: proc do |chunk, _bytesize|
+     print chunk.dig("choices", 0, "delta", "content")
+    end
+  }
+)
 ```
 
 ### Counting Tokens
@@ -300,11 +310,12 @@ GPT is a model that can be used to generate text in a conversational style. You
 
 ```ruby
 response = client.chat(
-    parameters: {
-        model: "gpt-4o", # Required.
-        messages: [{ role: "user", content: "Hello!"}], # Required.
-        temperature: 0.7,
-    })
+  parameters: {
+    model: "gpt-4o", # Required.
+    messages: [{ role: "user", content: "Hello!"}], # Required.
+    temperature: 0.7,
+  }
+)
 puts response.dig("choices", 0, "message", "content")
 # => "Hello! How may I assist you today?"
 ```
@@ -317,14 +328,15 @@ You can stream from the API in realtime, which can be much faster and used to cr
 
 ```ruby
 client.chat(
-    parameters: {
-        model: "gpt-4o", # Required.
-        messages: [{ role: "user", content: "Describe a character called Anna!"}], # Required.
-        temperature: 0.7,
-        stream: proc do |chunk, _bytesize|
-            print chunk.dig("choices", 0, "delta", "content")
-        end
-    })
+  parameters: {
+    model: "gpt-4o", # Required.
+    messages: [{ role: "user", content: "Describe a character called Anna!"}], # Required.
+    temperature: 0.7,
+    stream: proc do |chunk, _bytesize|
+      print chunk.dig("choices", 0, "delta", "content")
+    end
+  }
+)
 # => "Anna is a young woman in her mid-twenties, with wavy chestnut hair that falls to her shoulders..."
 ```
 
@@ -333,12 +345,13 @@ Note: In order to get usage information, you can provide the [`stream_options` p
 ```ruby
 stream_proc = proc { |chunk, _bytesize| puts "--------------"; puts chunk.inspect; }
 client.chat(
-    parameters: {
-        model: "gpt-4o",
-        stream: stream_proc,
-        stream_options: { include_usage: true },
-        messages: [{ role: "user", content: "Hello!"}],
-    })
+  parameters: {
+    model: "gpt-4o",
+    stream: stream_proc,
+    stream_options: { include_usage: true },
+    messages: [{ role: "user", content: "Hello!"}],
+  }
+)
 # => --------------
 # => {"id"=>"chatcmpl-7bbq05PiZqlHxjV1j7OHnKKDURKaf", "object"=>"chat.completion.chunk", "created"=>1718750612, "model"=>"gpt-4o-2024-05-13", "system_fingerprint"=>"fp_9cb5d38cf7", "choices"=>[{"index"=>0, "delta"=>{"role"=>"assistant", "content"=>""}, "logprobs"=>nil, "finish_reason"=>nil}], "usage"=>nil}
 # => --------------
@@ -365,10 +378,11 @@ messages = [
   }
 ]
 response = client.chat(
-    parameters: {
-        model: "gpt-4-vision-preview", # Required.
-        messages: [{ role: "user", content: messages}], # Required.
-    })
+  parameters: {
+    model: "gpt-4-vision-preview", # Required.
+    messages: [{ role: "user", content: messages}], # Required.
+  }
+)
 puts response.dig("choices", 0, "message", "content")
 # => "The image depicts a serene natural landscape featuring a long wooden boardwalk extending straight ahead"
 ```
@@ -378,21 +392,22 @@ puts response.dig("choices", 0, "message", "content")
 You can set the response_format to ask for responses in JSON:
 
 ```ruby
-  response = client.chat(
-    parameters: {
-        model: "gpt-4o",
-        response_format: { type: "json_object" },
-        messages: [{ role: "user", content: "Hello! Give me some JSON please."}],
-        temperature: 0.7,
-    })
-    puts response.dig("choices", 0, "message", "content")
-    {
-      "name": "John",
-      "age": 30,
-      "city": "New York",
-      "hobbies": ["reading", "traveling", "hiking"],
-      "isStudent": false
-    }
+response = client.chat(
+  parameters: {
+    model: "gpt-4o",
+    response_format: { type: "json_object" },
+    messages: [{ role: "user", content: "Hello! Give me some JSON please."}],
+    temperature: 0.7,
+  })
+  puts response.dig("choices", 0, "message", "content")
+  # =>
+  # {
+  #   "name": "John",
+  #   "age": 30,
+  #   "city": "New York",
+  #   "hobbies": ["reading", "traveling", "hiking"],
+  #   "isStudent": false
+  # }
 ```
 
 You can stream it as well!
@@ -402,26 +417,28 @@ You can stream it as well!
     parameters: {
       model: "gpt-4o",
       messages: [{ role: "user", content: "Can I have some JSON please?"}],
-        response_format: { type: "json_object" },
-        stream: proc do |chunk, _bytesize|
-          print chunk.dig("choices", 0, "delta", "content")
-        end
-  })
-  {
-    "message": "Sure, please let me know what specific JSON data you are looking for.",
-    "JSON_data": {
-      "example_1": {
-        "key_1": "value_1",
-        "key_2": "value_2",
-        "key_3": "value_3"
-      },
-      "example_2": {
-        "key_4": "value_4",
-        "key_5": "value_5",
-        "key_6": "value_6"
-      }
+      response_format: { type: "json_object" },
+      stream: proc do |chunk, _bytesize|
+        print chunk.dig("choices", 0, "delta", "content")
+      end
     }
-  }
+  )
+  # =>
+  # {
+  #   "message": "Sure, please let me know what specific JSON data you are looking for.",
+  #   "JSON_data": {
+  #     "example_1": {
+  #       "key_1": "value_1",
+  #       "key_2": "value_2",
+  #       "key_3": "value_3"
+  #     },
+  #     "example_2": {
+  #       "key_4": "value_4",
+  #       "key_5": "value_5",
+  #       "key_6": "value_6"
+  #     }
+  #   }
+  # }
 ```
 
 ### Functions
@@ -429,7 +446,6 @@ You can stream it as well!
 You can describe and pass in functions and the model will intelligently choose to output a JSON object containing arguments to call them - eg., to use your method `get_current_weather` to get the weather in a given location. Note that tool_choice is optional, but if you exclude it, the model will choose whether to use the function or not ([see here](https://platform.openai.com/docs/api-reference/chat/create#chat-create-tool_choice)).
 
 ```ruby
-
 def get_current_weather(location:, unit: "fahrenheit")
   # Here you could use a weather api to fetch the weather.
   "The weather in #{location} is nice 🌞 #{unit}"
@@ -470,8 +486,9 @@ response =
           },
         }
       ],
-      tool_choice: "required"  # Optional, defaults to "auto"
-                               # Can also put "none" or specific functions, see docs
+      # Optional, defaults to "auto"
+      # Can also put "none" or specific functions, see docs
+      tool_choice: "required"
     },
   )
 
@@ -485,12 +502,13 @@ if message["role"] == "assistant" && message["tool_calls"]
       tool_call.dig("function", "arguments"),
       { symbolize_names: true },
     )
-    function_response = case function_name
+    function_response =
+      case function_name
       when "get_current_weather"
         get_current_weather(**function_args)  # => "The weather is nice 🌞"
       else
         # decide how to handle
-    end
+      end
 
     # For a subsequent message with the role "tool", OpenAI requires the preceding message to have a tool_calls argument.
     messages << message
@@ -507,7 +525,8 @@ if message["role"] == "assistant" && message["tool_calls"]
     parameters: {
       model: "gpt-4o",
       messages: messages
-  })
+    }
+  )
 
   puts second_response.dig("choices", 0, "message", "content")
 
@@ -523,11 +542,12 @@ Hit the OpenAI API for a completion using other GPT-3 models:
 
 ```ruby
 response = client.completions(
-    parameters: {
-        model: "gpt-4o",
-        prompt: "Once upon a time",
-        max_tokens: 5
-    })
+  parameters: {
+    model: "gpt-4o",
+    prompt: "Once upon a time",
+    max_tokens: 5
+  }
+)
 puts response["choices"].map { |c| c["text"] }
 # => [", there lived a great"]
 ```
@@ -538,10 +558,10 @@ You can use the embeddings endpoint to get a vector of numbers representing an i
 
 ```ruby
 response = client.embeddings(
-    parameters: {
-        model: "text-embedding-ada-002",
-        input: "The food was delicious and the waiter..."
-    }
+  parameters: {
+    model: "text-embedding-ada-002",
+    input: "The food was delicious and the waiter..."
+  }
 )
 
 puts response.dig("data", 0, "embedding")
@@ -687,9 +707,9 @@ You can then use this file ID to create a fine tuning job:
 
 ```ruby
 response = client.finetunes.create(
-    parameters: {
-    training_file: file_id,
-    model: "gpt-4o"
+  parameters: {
+  training_file: file_id,
+  model: "gpt-4o"
 })
 fine_tune_id = response["id"]
 ```
@@ -712,17 +732,17 @@ This fine-tuned model name can then be used in chat completions:
 
 ```ruby
 response = client.chat(
-    parameters: {
-        model: fine_tuned_model,
-        messages: [{ role: "user", content: "I love Mondays!"}]
-    }
+  parameters: {
+    model: fine_tuned_model,
+    messages: [{ role: "user", content: "I love Mondays!" }]
+  }
 )
 response.dig("choices", 0, "message", "content")
 ```
 
 You can also capture the events for a job:
 
-```
+```ruby
 client.finetunes.list_events(id: fine_tune_id)
 ```
 
@@ -867,25 +887,26 @@ To create a new assistant:
 
 ```ruby
 response = client.assistants.create(
-    parameters: {
-        model: "gpt-4o",
-        name: "OpenAI-Ruby test assistant",
-        description: nil,
-        instructions: "You are a Ruby dev bot. When asked a question, write and run Ruby code to answer the question",
-        tools: [
-            { type: "code_interpreter" },
-            { type: "file_search" }
-        ],
-        tool_resources: {
-          code_interpreter: {
-            file_ids: [] # See Files section above for how to upload files
-          },
-          file_search: {
-            vector_store_ids: [] # See Vector Stores section above for how to add vector stores
-          }
-        },
-        "metadata": { my_internal_version_id: "1.0.0" }
-    })
+  parameters: {
+    model: "gpt-4o",
+    name: "OpenAI-Ruby test assistant",
+    description: nil,
+    instructions: "You are a Ruby dev bot. When asked a question, write and run Ruby code to answer the question",
+    tools: [
+      { type: "code_interpreter" },
+      { type: "file_search" }
+    ],
+    tool_resources: {
+      code_interpreter: {
+        file_ids: [] # See Files section above for how to upload files
+      },
+      file_search: {
+        vector_store_ids: [] # See Vector Stores section above for how to add vector stores
+      }
+    },
+    "metadata": { my_internal_version_id: "1.0.0" }
+  }
+)
 assistant_id = response["id"]
 ```
 
@@ -905,16 +926,17 @@ You can modify an existing assistant using the assistant's id (see [API document
 
 ```ruby
 response = client.assistants.modify(
-        id: assistant_id,
-        parameters: {
-            name: "Modified Test Assistant for OpenAI-Ruby",
-            metadata: { my_internal_version_id: '1.0.1' }
-        })
+  id: assistant_id,
+  parameters: {
+    name: "Modified Test Assistant for OpenAI-Ruby",
+    metadata: { my_internal_version_id: '1.0.1' }
+  }
+)
 ```
 
 You can delete assistants:
 
-```
+```ruby
 client.assistants.delete(id: assistant_id)
 ```
 
@@ -930,11 +952,12 @@ 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"]
+  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)
@@ -958,32 +981,38 @@ To submit a thread to be evaluated with the model of an assistant, create a `Run
 
 ```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,
-        max_prompt_tokens: 256,
-        max_completion_tokens: 16
-    })
+response = client.runs.create(
+  thread_id: thread_id,
+  parameters: {
+    assistant_id: assistant_id,
+    max_prompt_tokens: 256,
+    max_completion_tokens: 16
+  }
+)
 run_id = response['id']
 ```
 
 You can stream the message chunks as they come through:
 
 ```ruby
-client.runs.create(thread_id: thread_id,
-    parameters: {
-        assistant_id: assistant_id,
-        max_prompt_tokens: 256,
-        max_completion_tokens: 16,
-        stream: proc do |chunk, _bytesize|
-          print chunk.dig("delta", "content", 0, "text", "value") if chunk["object"] == "thread.message.delta"
-        end
-    })
+client.runs.create(
+  thread_id: thread_id,
+  parameters: {
+    assistant_id: assistant_id,
+    max_prompt_tokens: 256,
+    max_completion_tokens: 16,
+    stream: proc do |chunk, _bytesize|
+      if chunk["object"] == "thread.message.delta"
+        print chunk.dig("delta", "content", 0, "text", "value")
+      end
+    end
+  }
+)
 ```
 
 To get the status of a Run:
 
-```
+```ruby
 response = client.runs.retrieve(id: run_id, thread_id: thread_id)
 status = response['status']
 ```
@@ -992,23 +1021,23 @@ The `status` response can include the following strings `queued`, `in_progress`,
 
 ```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
+  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
 ```
 
@@ -1020,30 +1049,30 @@ messages = client.messages.list(thread_id: thread_id, parameters: { order: 'asc'
 
 # 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, parameters: { order: 'asc' })
-new_message_ids = run_steps['data'].filter_map { |step|
+new_message_ids = run_steps['data'].filter_map do |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.
-}
+end
 
 # Retrieve the individual messages
-new_messages = new_message_ids.map { |msg_id|
+new_messages = new_message_ids.map do |msg_id|
   client.messages.retrieve(id: msg_id, thread_id: thread_id)
-}
+end
 
 # 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
-    }
-}
+new_messages.each do |msg|
+  msg['content'].each do |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
+  end
+end
 ```
 
 You can also update the metadata on messages, including messages that come from the assistant.
@@ -1052,7 +1081,11 @@ You can also update the metadata on messages, including messages that come from
 metadata = {
   user_id: "abc123"
 }
-message = client.messages.modify(id: message_id, thread_id: thread_id, parameters: { metadata: metadata })
+message = client.messages.modify(
+  id: message_id,
+  thread_id: thread_id,
+  parameters: { metadata: metadata },
+)
 ```
 
 At any time you can list all runs which have been performed on a particular thread or are currently running:
@@ -1071,41 +1104,117 @@ run_id = response['id']
 thread_id = response['thread_id']
 ```
 
+#### Vision in a thread
+
+You can include images in a thread and they will be described & read by the LLM. In this example I'm using [this file](https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png):
+
+```ruby
+require "openai"
+
+# Make a client
+client = OpenAI::Client.new(
+  access_token: "access_token_goes_here",
+  log_errors: true # Don't log errors in production.
+)
+
+# Upload image as a file
+file_id = client.files.upload(
+  parameters: {
+    file: "path/to/example.png",
+    purpose: "assistants",
+  }
+)["id"]
+
+# Create assistant (You could also use an existing one here)
+assistant_id = client.assistants.create(
+  parameters: {
+    model: "gpt-4o",
+    name: "Image reader",
+    instructions: "You are an image describer. You describe the contents of images.",
+  }
+)["id"]
+
+# Create thread
+thread_id = client.threads.create["id"]
+
+# Add image in message
+client.messages.create(
+  thread_id: thread_id,
+  parameters: {
+    role: "user", # Required for manually created messages
+    content: [
+      {
+        "type": "text",
+        "text": "What's in this image?"
+      },
+      {
+        "type": "image_file",
+        "image_file": { "file_id": file_id }
+      }
+    ]
+  }
+)
+
+# Run thread
+run_id = client.runs.create(
+  thread_id: thread_id,
+  parameters: { assistant_id: assistant_id }
+)["id"]
+
+# Wait until run in complete
+status = nil
+until status == "completed" do
+  sleep(0.1)
+  status = client.runs.retrieve(id: run_id, thread_id: thread_id)['status']
+end
+
+# Get the response
+messages = client.messages.list(thread_id: thread_id, parameters: { order: 'asc' })
+messages.dig("data", -1, "content", 0, "text", "value")
+=> "The image contains a placeholder graphic with a tilted, stylized representation of a postage stamp in the top part, which includes an abstract landscape with hills and a sun. Below the stamp, in the middle of the image, there is italicized text in a light golden color that reads, \"This is just an example.\" The background is a light pastel shade, and a yellow border frames the entire image."
+```
+
 #### 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
+  # 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')
 
-    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 },
-        )
+  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_output = case function_name
+    when "get_current_weather"
+      get_current_weather(**arguments)
+    end
 
-        { tool_call_id: tool['id'], output: tool_output }
+    {
+      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 })
+  client.runs.submit_tool_outputs(
+    thread_id: thread_id,
+    run_id: run_id,
+    parameters: { tool_outputs: my_tool_outputs }
+  )
 end
 ```
 
@@ -1115,19 +1224,19 @@ Note that you have 10 minutes to submit your tool output before the run expires.
 
 Take a deep breath. You might need a drink for this one.
 
-It's possible for OpenAI to share what chunks it used in its internal RAG Pipeline to create its filesearch example.
+It's possible for OpenAI to share what chunks it used in its internal RAG Pipeline to create its filesearch results.
 
 An example spec can be found [here](https://github.com/alexrudall/ruby-openai/blob/main/spec/openai/client/assistant_file_search_spec.rb) that does this, just so you know it's possible.
 
 Here's how to get the chunks used in a file search. In this example I'm using [this file](https://css4.pub/2015/textbook/somatosensory.pdf):
 
-```
+```ruby
 require "openai"
 
 # Make a client
 client = OpenAI::Client.new(
   access_token: "access_token_goes_here",
-  log_errors: true # Don't do this in production.
+  log_errors: true # Don't log errors in production.
 )
 
 # Upload your file(s)
@@ -1191,9 +1300,6 @@ steps = client.run_steps.list(
   parameters: { order: "asc" }
 )
 
-# Get the last step ID (or whichever one you want to look at)
-step_id = steps["data"].first["id"]
-
 # Retrieve all the steps. Include the "GIVE ME THE CHUNKS" incantation again.
 steps = steps["data"].map do |step|
   client.run_steps.retrieve(
@@ -1230,7 +1336,12 @@ Generate images using DALL·E 2 or DALL·E 3!
 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" })
+response = client.images.generate(
+  parameters: {
+    prompt: "A baby sea otter cooking pasta wearing a hat of some sort",
+    size: "256x256",
+  }
+)
 puts response.dig("data", 0, "url")
 # => "https://oaidalleapiprodscus.blob.core.windows.net/private/org-Rf437IxKhh..."
 ```
@@ -1242,7 +1353,14 @@ puts response.dig("data", 0, "url")
 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", model: "dall-e-3", size: "1024x1792", quality: "standard" })
+response = client.images.generate(
+  parameters: {
+    prompt: "A springer spaniel cooking pasta wearing a hat of some sort",
+    model: "dall-e-3",
+    size: "1024x1792",
+    quality: "standard",
+  }
+)
 puts response.dig("data", 0, "url")
 # => "https://oaidalleapiprodscus.blob.core.windows.net/private/org-Rf437IxKhh..."
 ```
@@ -1254,7 +1372,13 @@ puts response.dig("data", 0, "url")
 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...
 
 ```ruby
-response = client.images.edit(parameters: { prompt: "A solid red Ruby on a blue background", image: "image.png", mask: "mask.png" })
+response = client.images.edit(
+  parameters: {
+    prompt: "A solid red Ruby on a blue background",
+    image: "image.png",
+    mask: "mask.png",
+  }
+)
 puts response.dig("data", 0, "url")
 # => "https://oaidalleapiprodscus.blob.core.windows.net/private/org-Rf437IxKhh..."
 ```
@@ -1294,10 +1418,11 @@ The translations API takes as input the audio file in any of the supported langu
 
 ```ruby
 response = client.audio.translate(
-    parameters: {
-        model: "whisper-1",
-        file: File.open("path_to_file", "rb"),
-    })
+  parameters: {
+    model: "whisper-1",
+    file: File.open("path_to_file", "rb"),
+  }
+)
 puts response["text"]
 # => "Translation of the text"
 ```
@@ -1310,11 +1435,12 @@ You can pass the language of the audio file to improve transcription quality. Su
 
 ```ruby
 response = client.audio.transcribe(
-    parameters: {
-        model: "whisper-1",
-        file: File.open("path_to_file", "rb"),
-        language: "en" # Optional
-    })
+  parameters: {
+    model: "whisper-1",
+    file: File.open("path_to_file", "rb"),
+    language: "en", # Optional
+  }
+)
 puts response["text"]
 # => "Transcription of the text"
 ```
@@ -1330,23 +1456,81 @@ response = client.audio.speech(
     input: "This is a speech test!",
     voice: "alloy",
     response_format: "mp3", # Optional
-    speed: 1.0 # Optional
+    speed: 1.0, # Optional
   }
 )
 File.binwrite('demo.mp3', response)
 # => mp3 file that plays: "This is a speech test!"
 ```
 
-### Errors
+### Usage
+The Usage API provides information about the cost of various OpenAI services within your organization.
+To use Admin APIs like Usage, you need to set an OPENAI_ADMIN_TOKEN, which can be generated [here](https://platform.openai.com/settings/organization/admin-keys).
 
-HTTP errors can be caught like this:
+```ruby
+OpenAI.configure do |config|
+  config.admin_token = ENV.fetch("OPENAI_ADMIN_TOKEN")
+end
+
+# or
 
+client = OpenAI::Client.new(admin_token: "123abc")
 ```
-  begin
-    OpenAI::Client.new.models.retrieve(id: "gpt-4o")
-  rescue Faraday::Error => e
-    raise "Got a Faraday error: #{e}"
+
+You can retrieve usage data for different endpoints and time periods:
+
+```ruby
+one_day_ago = Time.now.to_i - 86_400
+
+# Retrieve costs data
+response = client.usage.costs(parameters: { start_time: one_day_ago })
+response["data"].each do |bucket|
+  bucket["results"].each do |result|
+    puts "#{Time.at(bucket["start_time"]).to_date}: $#{result.dig("amount", "value").round(2)}"
   end
+end
+=> 2025-02-09: $0.0
+=> 2025-02-10: $0.42
+
+# Retrieve completions usage data
+response = client.usage.completions(parameters: { start_time: one_day_ago })
+puts response["data"]
+
+# Retrieve embeddings usage data
+response = client.usage.embeddings(parameters: { start_time: one_day_ago })
+puts response["data"]
+
+# Retrieve moderations usage data
+response = client.usage.moderations(parameters: { start_time: one_day_ago })
+puts response["data"]
+
+# Retrieve image generation usage data
+response = client.usage.images(parameters: { start_time: one_day_ago })
+puts response["data"]
+
+# Retrieve audio speech usage data
+response = client.usage.audio_speeches(parameters: { start_time: one_day_ago })
+puts response["data"]
+
+# Retrieve audio transcription usage data
+response = client.usage.audio_transcriptions(parameters: { start_time: one_day_ago })
+puts response["data"]
+
+# Retrieve vector stores usage data
+response = client.usage.vector_stores(parameters: { start_time: one_day_ago })
+puts response["data"]
+```
+
+### Errors
+
+HTTP errors can be caught like this:
+
+```ruby
+begin
+  OpenAI::Client.new.models.retrieve(id: "gpt-4o")
+rescue Faraday::Error => e
+  raise "Got a Faraday error: #{e}"
+end
 ```
 
 ## Development
@@ -1358,15 +1542,11 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 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.
 
 > [!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.
+> If you have an `OPENAI_ACCESS_TOKEN` and `OPENAI_ADMIN_TOKEN` in your `ENV`, running the specs will hit the actual API, which will be slow and cost you money - 2 cents or more! Remove them from your environment with `unset` or similar if you just want to run the specs against the stored VCR responses.
 
 ## Release
 
-First run the specs without VCR so they actually hit the API. This will cost 2 cents or more. Set OPENAI_ACCESS_TOKEN in your environment or pass it in like this:
-
-```
-OPENAI_ACCESS_TOKEN=123abc bundle exec rspec
-```
+First run the specs without VCR so they actually hit the API. This will cost 2 cents or more. Set OPENAI_ACCESS_TOKEN and OPENAI_ADMIN_TOKEN in your environment.
 
 Then update the version number in `version.rb`, update `CHANGELOG.md`, run `bundle install` to update Gemfile.lock, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).