llm.rb 0.10.1 → 0.12.0

data/lib/llm/providers/openai/format/completion_format.rb

@@ -32,10 +32,13 @@ module LLM::OpenAI::Format
       case content
       when URI
         [{type: :image_url, image_url: {url: content.to_s}}]
+      when File
+        content.close unless content.closed?
+        format_content(LLM.File(content.path))
       when LLM::File
         format_file(content)
-      when LLM::Response::File
-        [{type: :file, file: {file_id: content.id}}]
+      when LLM::Response
+        content.file? ? [{type: :file, file: {file_id: content.id}}] : prompt_error!(content)
       when String
         [{type: :text, text: content.to_s}]
       when LLM::Message
@@ -43,8 +46,7 @@ module LLM::OpenAI::Format
       when LLM::Function::Return
         throw(:abort, {role: "tool", tool_call_id: content.id, content: JSON.dump(content.value)})
       else
-        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
-                                       "is not supported by the OpenAI chat completions API"
+        prompt_error!(content)
       end
     end
 
@@ -76,6 +78,11 @@ module LLM::OpenAI::Format
       end
     end
 
+    def prompt_error!(content)
+      raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                              "is not supported by the OpenAI chat completions API"
+    end
+
     def message = @message
     def content = message.content
     def returns = content.grep(LLM::Function::Return)

data/lib/llm/providers/openai/format/moderation_format.rb

@@ -22,8 +22,8 @@ module LLM::OpenAI::Format
         elsif URI === input
           {type: :image_url, url: input.to_s}
         else
-          raise LLM::Error::FormatError, "The given object (an instance of #{input.class}) " \
-                                         "is not supported by OpenAI moderations API"
+          raise LLM::FormatError, "The given object (an instance of #{input.class}) " \
+                                  "is not supported by OpenAI moderations API"
         end
       end
     end

data/lib/llm/providers/openai/format/respond_format.rb

@@ -22,15 +22,14 @@ module LLM::OpenAI::Format
 
     def format_content(content)
       case content
-      when LLM::Response::File
-        format_file(content)
+      when LLM::Response
+        content.file? ? format_file(content) : prompt_error!(content)
       when String
         [{type: :input_text, text: content.to_s}]
       when LLM::Message
         format_content(content.content)
       else
-        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
-                                       "is not supported by the OpenAI responses API"
+        prompt_error!(content)
       end
     end
 
@@ -62,6 +61,10 @@ module LLM::OpenAI::Format
       end
     end
 
+    def prompt_error!(content)
+      raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                              "is not supported by the OpenAI responses API"
+    end
     def message = @message
     def content = message.content
     def returns = content.grep(LLM::Function::Return)

data/lib/llm/providers/openai/images.rb

@@ -2,31 +2,32 @@
 
 class LLM::OpenAI
   ##
-  # The {LLM::OpenAI::Images LLM::OpenAI::Images} class provides an images
-  # object for interacting with [OpenAI's images API](https://platform.openai.com/docs/api-reference/images).
+  # The {LLM::OpenAI::Images LLM::OpenAI::Images} class provides an interface
+  # for [OpenAI's images API](https://platform.openai.com/docs/api-reference/images).
   # OpenAI supports multiple response formats: temporary URLs, or binary strings
   # encoded in base64. The default is to return temporary URLs.
   #
-  # @example example #1
+  # @example Temporary URLs
   #   #!/usr/bin/env ruby
   #   require "llm"
   #   require "open-uri"
   #   require "fileutils"
   #
-  #   llm = LLM.openai(ENV["KEY"])
+  #   llm = LLM.openai(key: ENV["KEY"])
   #   res = llm.images.create prompt: "A dog on a rocket to the moon"
   #   FileUtils.mv OpenURI.open_uri(res.urls[0]).path,
   #                "rocket.png"
   #
-  # @example example #2
+  # @example Binary strings
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.openai(ENV["KEY"])
+  #   llm = LLM.openai(key: ENV["KEY"])
   #   res = llm.images.create prompt: "A dog on a rocket to the moon",
   #                           response_format: "b64_json"
   #   IO.copy_stream res.images[0], "rocket.png"
   class Images
+    require_relative "response/image"
     ##
     # Returns a new Images object
     # @param provider [LLM::Provider]
@@ -38,26 +39,26 @@ class LLM::OpenAI
     ##
     # Create an image
     # @example
-    #   llm = LLM.openai(ENV["KEY"])
+    #   llm = LLM.openai(key: ENV["KEY"])
     #   res = llm.images.create prompt: "A dog on a rocket to the moon"
-    #   p res.urls
+    #   res.urls.each { print _1, "\n" }
     # @see https://platform.openai.com/docs/api-reference/images/create OpenAI docs
     # @param [String] prompt The prompt
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
     # @raise (see LLM::Provider#request)
-    # @return [LLM::Response::Image]
+    # @return [LLM::Response]
     def create(prompt:, model: "dall-e-3", **params)
       req = Net::HTTP::Post.new("/v1/images/generations", headers)
       req.body = JSON.dump({prompt:, n: 1, model:}.merge!(params))
       res = execute(request: req)
-      LLM::Response::Image.new(res).extend(response_parser)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Image)
     end
 
     ##
     # Create image variations
     # @example
-    #   llm = LLM.openai(ENV["KEY"])
+    #   llm = LLM.openai(key: ENV["KEY"])
     #   res = llm.images.create_variation(image: "/images/hat.png", n: 5)
     #   p res.urls
     # @see https://platform.openai.com/docs/api-reference/images/createVariation OpenAI docs
@@ -65,7 +66,7 @@ class LLM::OpenAI
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
     # @raise (see LLM::Provider#request)
-    # @return [LLM::Response::Image]
+    # @return [LLM::Response]
     def create_variation(image:, model: "dall-e-2", **params)
       image = LLM.File(image)
       multi = LLM::Multipart.new(params.merge!(image:, model:))
@@ -73,13 +74,13 @@ class LLM::OpenAI
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
       res = execute(request: req)
-      LLM::Response::Image.new(res).extend(response_parser)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Image)
     end
 
     ##
     # Edit an image
     # @example
-    #   llm = LLM.openai(ENV["KEY"])
+    #   llm = LLM.openai(key: ENV["KEY"])
     #   res = llm.images.edit(image: "/images/hat.png", prompt: "A cat wearing this hat")
     #   p res.urls
     # @see https://platform.openai.com/docs/api-reference/images/createEdit OpenAI docs
@@ -88,7 +89,7 @@ class LLM::OpenAI
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
     # @raise (see LLM::Provider#request)
-    # @return [LLM::Response::Image]
+    # @return [LLM::Response]
     def edit(image:, prompt:, model: "dall-e-2", **params)
       image = LLM.File(image)
       multi = LLM::Multipart.new(params.merge!(image:, prompt:, model:))
@@ -96,12 +97,12 @@ class LLM::OpenAI
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
       res = execute(request: req)
-      LLM::Response::Image.new(res).extend(response_parser)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Image)
     end
 
     private
 
-    [:response_parser, :headers, :execute, :set_body_stream].each do |m|
+    [:headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/openai/models.rb

@@ -11,7 +11,7 @@ class LLM::OpenAI
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.openai(ENV["KEY"])
+  #   llm = LLM.openai(key: ENV["KEY"])
   #   res = llm.models.all
   #   res.each do |model|
   #     print "id: ", model.id, "\n"
@@ -28,7 +28,7 @@ class LLM::OpenAI
     ##
     # List all models
     # @example
-    #   llm = LLM.openai(ENV["KEY"])
+    #   llm = LLM.openai(key: ENV["KEY"])
     #   res = llm.models.all
     #   res.each do |model|
     #     print "id: ", model.id, "\n"
@@ -36,17 +36,12 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/models/list OpenAI docs
     # @param [Hash] params Other parameters (see OpenAI docs)
     # @raise (see LLM::Provider#request)
-    # @return [LLM::Response::FileList]
+    # @return [LLM::Response]
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/models?#{query}", headers)
       res = execute(request: req)
-      LLM::Response::ModelList.new(res).tap { |modellist|
-        models = modellist.body["data"].map do |model|
-          LLM::Model.from_hash(model).tap { _1.provider = @provider }
-        end
-        modellist.models = models
-      }
+      LLM::Response.new(res)
     end
 
     private

data/lib/llm/providers/openai/moderations.rb

@@ -13,7 +13,8 @@ class LLM::OpenAI
   #   require "llm"
   #
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   mod = llm.moderations.create input: "I hate you"
+  #   res = llm.moderations.create input: "I hate you"
+  #   mod = res.moderations[0]
   #   print "categories: #{mod.categories}", "\n"
   #   print "scores: #{mod.scores}", "\n"
   #
@@ -22,13 +23,16 @@ class LLM::OpenAI
   #   require "llm"
   #
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   mod = llm.moderations.create input: URI.parse("https://example.com/image.png")
+  #   res = llm.moderations.create input: URI.parse("https://example.com/image.png")
+  #   mod = res.moderations[0]
   #   print "categories: #{mod.categories}", "\n"
   #   print "scores: #{mod.scores}", "\n"
   #
   # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
   # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
   class Moderations
+    require_relative "response/moderations"
+
     ##
     # Returns a new Moderations object
     # @param [LLM::Provider] provider
@@ -41,26 +45,20 @@ class LLM::OpenAI
     # Create a moderation
     # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
     # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
-    # @note
-    # Although OpenAI mentions an array as a valid input, and that it can return one
-    # or more moderations, in practice the API only returns one moderation object. We
-    # recommend using a single input string or URI, and to keep in mind that llm.rb
-    # returns a Moderation object but has code in place to return multiple objects in
-    # the future (in case OpenAI documentation ever matches the actual API).
     # @param [String, URI, Array<String, URI>] input
     # @param [String, LLM::Model] model The model to use
-    # @return [LLM::Response::ModerationList::Moderation]
+    # @return [LLM::Response]
     def create(input:, model: "omni-moderation-latest", **params)
       req = Net::HTTP::Post.new("/v1/moderations", headers)
       input = Format::ModerationFormat.new(input).format
       req.body = JSON.dump({input:, model:}.merge!(params))
       res = execute(request: req)
-      LLM::Response::ModerationList.new(res).extend(response_parser).first
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Moderations)
     end
 
     private
 
-    [:response_parser, :headers, :execute].each do |m|
+    [:headers, :execute].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/openai/response/audio.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Audio
+    def audio = body.audio
+  end
+end

data/lib/llm/providers/openai/{response_parser/completion_parser.rb → response/completion.rb}

@@ -1,30 +1,13 @@
 # frozen_string_literal: true
 
-module LLM::OpenAI::ResponseParser
-  ##
-  # @private
-  class CompletionParser
-    def initialize(body)
-      @body = LLM::Object.from_hash(body)
-    end
-
-    def format(response)
-      {
-        model:,
-        prompt_tokens:,
-        completion_tokens:,
-        total_tokens:,
-        choices: format_choices(response)
-      }
-    end
-
-    private
-
-    def format_choices(response)
-      choices.map.with_index do |choice, index|
+module LLM::OpenAI::Response
+  module Completion
+    def choices
+      body.choices.map.with_index do |choice, index|
+        choice = LLM::Object.from_hash(choice)
         message = choice.message
         extra = {
-          index:, response:,
+          index:, response: self,
           logprobs: choice.logprobs,
           tool_calls: format_tool_calls(message.tool_calls),
           original_tool_calls: message.tool_calls
@@ -32,6 +15,14 @@ module LLM::OpenAI::ResponseParser
         LLM::Message.new(message.role, message.content, extra)
       end
     end
+    alias_method :messages, :choices
+
+    def model = body.model
+    def prompt_tokens = body.usage&.prompt_tokens
+    def completion_tokens = body.usage&.completion_tokens
+    def total_tokens = body.usage&.total_tokens
+
+    private
 
     def format_tool_calls(tools)
       (tools || []).filter_map do |tool|
@@ -44,12 +35,5 @@ module LLM::OpenAI::ResponseParser
         LLM::Object.new(tool)
       end
     end
-
-    def body = @body
-    def model = body.model
-    def prompt_tokens = body.usage&.prompt_tokens
-    def completion_tokens = body.usage&.completion_tokens
-    def total_tokens = body.usage&.total_tokens
-    def choices = body.choices
   end
 end

data/lib/llm/providers/openai/response/embedding.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Embedding
+    def embeddings = data.map { _1["embedding"] }
+    def prompt_tokens = data.dig(0, "usage", "prompt_tokens")
+    def total_tokens = data.dig(0, "usage", "total_tokens")
+  end
+end

data/lib/llm/providers/openai/response/file.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module File
+    def file? = true
+  end
+end

data/lib/llm/providers/openai/response/image.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Image
+    def urls
+      data.filter_map { _1["url"] }
+    end
+
+    def images
+      data.filter_map do
+        next unless _1["b64_json"]
+        StringIO.new(_1["b64_json"].unpack1("m0"))
+      end
+    end
+  end
+end

data/lib/llm/providers/openai/response/moderations.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Response
+  module Moderations
+    ##
+    # @return [Array<LLM::Response]
+    def moderations
+      @moderations ||= body.results.map { _1.extend(Moderation) }
+    end
+  end
+
+  module Moderation
+    ##
+    # Returns true if the moderation is flagged
+    # @return [Boolean]
+    def flagged?
+      body.flagged
+    end
+
+    ##
+    # Returns the moderation categories
+    # @return [Array<String>]
+    def categories
+      self["categories"].filter_map { _2 ? _1 : nil }
+    end
+
+    ##
+    # Returns the moderation scores
+    # @return [Hash]
+    def scores
+      self["category_scores"].select { |(key, _)| categories.include?(key) }.to_h
+    end
+  end
+end

data/lib/llm/providers/openai/{response_parser/respond_parser.rb → response/responds.rb}

@@ -1,28 +1,15 @@
 # frozen_string_literal: true
 
-module LLM::OpenAI::ResponseParser
-  ##
-  # @private
-  class RespondParser
-    def initialize(body)
-      @body = LLM::Object.from_hash(body)
-    end
-
-    def format(response)
-      {
-        id:,
-        model:,
-        input_tokens:,
-        output_tokens:,
-        total_tokens:,
-        outputs: [format_message(response)]
-      }
-    end
+module LLM::OpenAI::Response
+  module Responds
+    def outputs = [format_message]
+    def choices = body.output
+    def tools = output.select { _1.type == "function_call" }
 
     private
 
-    def format_message(response)
-      message = LLM::Message.new("assistant", +"", {response:, tool_calls: []})
+    def format_message
+      message = LLM::Message.new("assistant", +"", {response: self, tool_calls: []})
       choices.each.with_index do |choice, index|
         if choice.type == "function_call"
           message.extra[:tool_calls] << format_tool(choice)
@@ -43,14 +30,5 @@ module LLM::OpenAI::ResponseParser
         arguments: JSON.parse(tool.arguments)
       )
     end
-
-    def body = @body
-    def id = body.id
-    def model = body.model
-    def input_tokens = body.usage.input_tokens
-    def output_tokens = body.usage.output_tokens
-    def total_tokens = body.usage.total_tokens
-    def choices = body.output
-    def tools = output.select { _1.type == "function_call" }
   end
 end

data/lib/llm/providers/openai/responses.rb

@@ -2,37 +2,19 @@
 
 class LLM::OpenAI
   ##
-  # The {LLM::OpenAI::Responses LLM::OpenAI::Responses} class provides a responses
-  # object for interacting with [OpenAI's response API](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses).
-  # The responses API is similar to the chat completions API but it can maintain
-  # conversation state across multiple requests. This is useful when you want to
-  # save bandwidth and/or not maintain the message thread by yourself.
+  # The {LLM::OpenAI::Responses LLM::OpenAI::Responses} class provides
+  # an interface for [OpenAI's response API](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses).
   #
   # @example example #1
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.openai(ENV["KEY"])
-  #   res1 = llm.responses.create "Your task is to help me with math", role: :developer
-  #   res2 = llm.responses.create "5 + 5  = ?", role: :user, previous_response_id: res1.id
-  #   [res1,res2].each { llm.responses.delete(_1) }
-  #
-  # @example example #2
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm  = LLM.openai(ENV["KEY"])
-  #   file = llm.files.create file: "/images/hat.png"
-  #   res  = llm.responses.create ["Describe the image", file]
-  #
-  # @example example #3
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm  = LLM.openai(ENV["KEY"])
-  #   file = llm.files.create file: "/documents/freebsd.pdf"
-  #   res  = llm.responses.create ["Describe the document, file]
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   res1 = llm.responses.create "Your task is to answer the user's questions", role: :developer
+  #   res2 = llm.responses.create "5 + 5 = X ?", role: :user, previous_response_id: res1.id
+  #   [res1, res2].each { llm.responses.delete(_1) }
   class Responses
+    require_relative "response/responds"
     include Format
 
     ##
@@ -49,9 +31,9 @@ class LLM::OpenAI
     # @param prompt (see LLM::Provider#complete)
     # @param params (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
-    # @raise [LLM::Error::PromptError]
+    # @raise [LLM::PromptError]
     #  When given an object a provider does not understand
-    # @return [LLM::Response::Output]
+    # @return [LLM::Response]
     def create(prompt, params = {})
       params = {role: :user, model: @provider.default_model}.merge!(params)
       params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
@@ -61,7 +43,7 @@ class LLM::OpenAI
       body = JSON.dump({input: [format(messages, :response)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req)
-      LLM::Response::Respond.new(res).extend(response_parser)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Responds)
     end
 
     ##
@@ -69,13 +51,13 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/responses/get OpenAI docs
     # @param [#id, #to_s] response Response ID
     # @raise (see LLM::Provider#request)
-    # @return [LLM::Response::Output]
+    # @return [LLM::Response]
     def get(response, **params)
       response_id = response.respond_to?(:id) ? response.id : response
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/responses/#{response_id}?#{query}", headers)
       res = execute(request: req)
-      LLM::Response::Respond.new(res).extend(response_parser)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Responds)
     end
 
     ##
@@ -88,14 +70,14 @@ class LLM::OpenAI
       response_id = response.respond_to?(:id) ? response.id : response
       req = Net::HTTP::Delete.new("/v1/responses/#{response_id}", headers)
       res = execute(request: req)
-      LLM::Object.from_hash JSON.parse(res.body)
+      LLM::Response.new(res)
     end
 
     private
 
-    [:response_parser, :headers,
-     :execute, :set_body_stream,
-     :format_schema, :format_tools].each do |m|
+    [:headers, :execute,
+     :set_body_stream, :format_schema,
+     :format_tools].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/openai/stream_parser.rb

@@ -52,6 +52,7 @@ class LLM::OpenAI
                 target[key] = value
               end
             else
+              @io << value if @io.respond_to?(:<<)
               target[key] = value
             end
           end