Merge pull request #563 from alexrudall/feature/usage

Add Admin tokens and Usage endpoints

Author: alexrudall

CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [7.4.0] - 2024-02-10
+
+### Added
+
+- Add support for OPENAI_ADMIN_TOKEN to allow for administrative endpoints to be called.
+- Add support for Usage endpoints.
+
 ## [7.3.1] - 2024-10-15
 
 ### Fixed

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-openai (7.3.1)
+    ruby-openai (7.4.0)
       event_stream_parser (>= 0.3.0, < 2.0.0)
       faraday (>= 1)
       faraday-multipart (>= 1)

README.md

@@ -20,7 +20,7 @@ Stream text with GPT-4, transcribe and translate audio with Whisper, or create i
   - [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)
@@ -65,6 +65,7 @@ Stream text with GPT-4, transcribe and translate audio with Whisper, or create i
       - [Translate](#translate)
       - [Transcribe](#transcribe)
       - [Speech](#speech)
+    - [Usage](#usage)
     - [Errors](#errors-1)
   - [Development](#development)
   - [Release](#release)
@@ -102,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)
@@ -125,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
@@ -136,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
@@ -167,8 +169,9 @@ or when configuring the gem:
 ```ruby
 OpenAI.configure do |config|
   config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
-  config.log_errors = true # Optional
+  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 = {
@@ -1460,6 +1463,64 @@ File.binwrite('demo.mp3', response)
 # => mp3 file that plays: "This is a speech test!"
 ```
 
+### 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).
+
+```ruby
+OpenAI.configure do |config|
+  config.admin_token = ENV.fetch("OPENAI_ADMIN_TOKEN")
+end
+
+# or
+
+client = OpenAI::Client.new(admin_token: "123abc")
+```
+
+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:
@@ -1481,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).
 

lib/openai.rb

@@ -18,10 +18,12 @@
 require_relative "openai/audio"
 require_relative "openai/version"
 require_relative "openai/batches"
+require_relative "openai/usage"
 
 module OpenAI
   class Error < StandardError; end
   class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
 
   class MiddlewareErrors < Faraday::Middleware
     def call(env)
@@ -41,6 +43,7 @@ def call(env)
 
   class Configuration
     attr_accessor :access_token,
+                  :admin_token,
                   :api_type,
                   :api_version,
                   :log_errors,
@@ -56,6 +59,7 @@ class Configuration
 
     def initialize
       @access_token = nil
+      @admin_token = nil
       @api_type = nil
       @api_version = DEFAULT_API_VERSION
       @log_errors = DEFAULT_LOG_ERRORS

lib/openai/client.rb

@@ -2,18 +2,11 @@ module OpenAI
   class Client
     include OpenAI::HTTP
 
-    SENSITIVE_ATTRIBUTES = %i[@access_token @organization_id @extra_headers].freeze
-    CONFIG_KEYS = %i[
-      api_type
-      api_version
-      access_token
-      log_errors
-      organization_id
-      uri_base
-      request_timeout
-      extra_headers
-    ].freeze
+    SENSITIVE_ATTRIBUTES = %i[@access_token @admin_token @organization_id @extra_headers].freeze
+    CONFIG_KEYS = %i[access_token admin_token api_type api_version extra_headers
+                     log_errors organization_id request_timeout uri_base].freeze
     attr_reader *CONFIG_KEYS, :faraday_middleware
+    attr_writer :access_token
 
     def initialize(config = {}, &faraday_middleware)
       CONFIG_KEYS.each do |key|
@@ -99,10 +92,25 @@ def moderations(parameters: {})
       json_post(path: "/moderations", parameters: parameters)
     end
 
+    def usage
+      @usage ||= OpenAI::Usage.new(client: self)
+    end
+
     def azure?
       @api_type&.to_sym == :azure
     end
 
+    def admin
+      unless admin_token
+        e = "You must set an OPENAI_ADMIN_TOKEN= to use administrative endpoints:\n\n  https://platform.openai.com/settings/organization/admin-keys"
+        raise AuthenticationError, e
+      end
+
+      dup.tap do |client|
+        client.access_token = client.admin_token
+      end
+    end
+
     def beta(apis)
       dup.tap do |client|
         client.add_headers("OpenAI-Beta": apis.map { |k, v| "#{k}=#{v}" }.join(";"))

lib/openai/compatibility.rb

@@ -3,6 +3,7 @@ module OpenAI
     VERSION = ::OpenAI::VERSION
 
     Error = ::OpenAI::Error
+    AuthenticationError = ::OpenAI::AuthenticationError
     ConfigurationError = ::OpenAI::ConfigurationError
     Configuration = ::OpenAI::Configuration
     MiddlewareErrors = ::OpenAI::MiddlewareErrors

lib/openai/usage.rb

@@ -0,0 +1,70 @@
+module OpenAI
+  class Usage
+    def initialize(client:)
+      @client = client
+    end
+
+    def completions(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/completions",
+        parameters: parameters
+      )
+    end
+
+    def embeddings(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/embeddings",
+        parameters: parameters
+      )
+    end
+
+    def moderations(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/moderations",
+        parameters: parameters
+      )
+    end
+
+    def images(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/images",
+        parameters: parameters
+      )
+    end
+
+    def audio_speeches(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/audio_speeches",
+        parameters: parameters
+      )
+    end
+
+    def audio_transcriptions(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/audio_transcriptions",
+        parameters: parameters
+      )
+    end
+
+    def vector_stores(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/vector_stores",
+        parameters: parameters
+      )
+    end
+
+    def code_interpreter_sessions(parameters: {})
+      @client.admin.get(
+        path: "/organization/usage/code_interpreter_sessions",
+        parameters: parameters
+      )
+    end
+
+    def costs(parameters: {})
+      @client.admin.get(
+        path: "/organization/costs",
+        parameters: parameters
+      )
+    end
+  end
+end

lib/openai/version.rb

@@ -1,3 +1,3 @@
 module OpenAI
-  VERSION = "7.3.1".freeze
+  VERSION = "7.4.0".freeze
 end