llm.rb 0.10.1 → 0.12.0

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # The {LLM::OpenAI::VectorStores LLM::OpenAI::VectorStores} class provides
+  # an interface for [OpenAI's vector stores API](https://platform.openai.com/docs/api-reference/vector_stores/create)
+  class VectorStores
+    ##
+    # @param [LLM::Provider] provider
+    #  An OpenAI provider
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all vector stores
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @return [LLM::Response]
+    def all(**params)
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/vector_stores?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Create a vector store
+    # @param [String] name The name of the vector store
+    # @param [Array<String>] file_ids The IDs of the files to include in the vector store
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores/create OpenAI docs
+    def create(name:, file_ids: [], **params)
+      req = Net::HTTP::Post.new("/v1/vector_stores", headers)
+      req.body = JSON.dump(params.merge({name:, file_ids:}).compact)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Get a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores/retrieve OpenAI docs
+    def get(vector:)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Modify an existing vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @param [String] name The new name of the vector store
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores/modify OpenAI docs
+    def modify(vector:, name: nil, **params)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}", headers)
+      req.body = JSON.dump(params.merge({name:}).compact)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Delete a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores/delete OpenAI docs
+    def delete(vector:)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      req = Net::HTTP::Delete.new("/v1/vector_stores/#{vector_id}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Search a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @param query [String] The query to search for
+    # @param params [Hash] Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores/search OpenAI docs
+    def search(vector:, query:, **params)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/search", headers)
+      req.body = JSON.dump(params.merge({query:}).compact)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # List all files in a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores_files/listFiles OpenAI docs
+    def all_files(vector:, **params)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}/files?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Add a file to a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @param [String, #id] file The ID of the file to add
+    # @param [Hash] attributes Attributes to associate with the file (optional)
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores_files/createFile OpenAI docs
+    def add_file(vector:, file:, attributes: nil, **params)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/files", headers)
+      req.body = JSON.dump(params.merge({file_id:, attributes:}).compact)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+    alias_method :create_file, :add_file
+
+    ##
+    # Update a file in a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @param [String, #id] file The ID of the file to update
+    # @param [Hash] attributes Attributes to associate with the file
+    # @param [Hash] params Other parameters (see OpenAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores_files/updateAttributes OpenAI docs
+    def update_file(vector:, file:, attributes:, **params)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/files/#{file_id}", headers)
+      req.body = JSON.dump(params.merge({attributes:}).compact)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Get a file from a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @param [String, #id] file The ID of the file to retrieve
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores_files/getFile OpenAI docs
+    def get_file(vector:, file:, **params)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      file_id = file.respond_to?(:id) ? file.id : file
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}/files/#{file_id}?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Delete a file from a vector store
+    # @param [String, #id] vector The ID of the vector store
+    # @param [String, #id] file The ID of the file to delete
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    # @see https://platform.openai.com/docs/api-reference/vector_stores_files/deleteFile OpenAI docs
+    def delete_file(vector:, file:)
+      vector_id = vector.respond_to?(:id) ? vector.id : vector
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Delete.new("/v1/vector_stores/#{vector_id}/files/#{file_id}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    private
+
+    [:headers, :execute, :set_body_stream].each do |m|
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
+    end
+  end
+end

data/lib/llm/providers/openai.rb

@@ -3,18 +3,29 @@
 module LLM
   ##
   # The OpenAI class implements a provider for
-  # [OpenAI](https://platform.openai.com/)
+  # [OpenAI](https://platform.openai.com/).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/capybara.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class OpenAI < Provider
+    require_relative "openai/response/embedding"
+    require_relative "openai/response/completion"
     require_relative "openai/error_handler"
     require_relative "openai/format"
     require_relative "openai/stream_parser"
-    require_relative "openai/response_parser"
     require_relative "openai/models"
     require_relative "openai/responses"
     require_relative "openai/images"
     require_relative "openai/audio"
     require_relative "openai/files"
     require_relative "openai/moderations"
+    require_relative "openai/vector_stores"
 
     include Format
 
@@ -38,7 +49,7 @@ module LLM
       req = Net::HTTP::Post.new("/v1/embeddings", headers)
       req.body = JSON.dump({input:, model:}.merge!(params))
       res = execute(request: req)
-      Response::Embedding.new(res).extend(response_parser)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Embedding)
     end
 
     ##
@@ -48,7 +59,7 @@ module LLM
     # @param params (see LLM::Provider#complete)
     # @example (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 (see LLM::Provider#complete)
     def complete(prompt, params = {})
@@ -61,7 +72,7 @@ module LLM
       body = JSON.dump({messages: format(messages, :complete).flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req, stream:)
-      Response::Completion.new(res).extend(response_parser)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Completion)
     end
 
     ##
@@ -113,6 +124,14 @@ module LLM
       LLM::OpenAI::Moderations.new(self)
     end
 
+    ##
+    # Provides an interface to OpenAI's vector store API
+    # @see https://platform.openai.com/docs/api-reference/vector-stores/create OpenAI docs
+    # @return [LLM::OpenAI::VectorStore]
+    def vector_stores
+      LLM::OpenAI::VectorStores.new(self)
+    end
+
     ##
     # @return (see LLM::Provider#assistant_role)
     def assistant_role
@@ -136,10 +155,6 @@ module LLM
       )
     end
 
-    def response_parser
-      LLM::OpenAI::ResponseParser
-    end
-
     def stream_parser
       LLM::OpenAI::StreamParser
     end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class LLM::XAI
+  ##
+  # The {LLM::XAI::Images LLM::XAI::Images} class provides an interface
+  # for [xAI's images API](https://docs.x.ai/docs/guides/image-generations).
+  # xAI supports multiple response formats: temporary URLs, or binary strings
+  # encoded in base64. The default is to return temporary URLs.
+  #
+  # @example Temporary URLs
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #   require "open-uri"
+  #   require "fileutils"
+  #
+  #   llm = LLM.xai(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 Binary strings
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.xai(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 < LLM::OpenAI::Images
+    ##
+    # Create an image
+    # @example
+    #   llm = LLM.xai(key: ENV["KEY"])
+    #   res = llm.images.create prompt: "A dog on a rocket to the moon"
+    #   res.urls.each { print _1, "\n"}
+    # @see https://docs.x.ai/docs/guides/image-generations xAI docs
+    # @param [String] prompt The prompt
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see xAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create(model: "grok-2-image-1212", **)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def edit(model: "grok-2-image-1212", **)
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def create_variation(model: "grok-2-image-1212", **)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/llm/providers/xai.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The XAI class implements a provider for [xAI](https://docs.x.ai).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.xai(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/crow.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class XAI < OpenAI
+    require_relative "xai/images"
+
+    ##
+    # @param [String] host A regional host or the default ("api.x.ai")
+    # @param key (see LLM::Provider#initialize)
+    # @see https://docs.x.ai/docs/key-information/regions Regional endpoints
+    def initialize(host: "api.x.ai", **)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def files
+      raise NotImplementedError
+    end
+
+    ##
+    # @return [LLM::XAI::Images]
+    def images
+      LLM::XAI::Images.new(self)
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def audio
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def moderations
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def responses
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def vector_stores
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # #see https://docs.x.ai/docs/models grok-4-0709
+    # @return [String]
+    def default_model
+      "grok-4-0709"
+    end
+  end
+end

data/lib/llm/response.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
 module LLM
+  ##
+  # {LLM::Response LLM::Response} encapsulates a response
+  # from an LLM provider. It is returned by all methods
+  # that make requests to a provider, and sometimes extended
+  # with provider-specific functionality.
   class Response
     require "json"
-    require_relative "response/completion"
-    require_relative "response/embedding"
-    require_relative "response/respond"
-    require_relative "response/image"
-    require_relative "response/audio"
-    require_relative "response/audio_transcription"
-    require_relative "response/audio_translation"
-    require_relative "response/file"
-    require_relative "response/filelist"
-    require_relative "response/download_file"
-    require_relative "response/modellist"
-    require_relative "response/moderationlist"
+
+    ##
+    # Returns the HTTP response
+    # @return [Net::HTTPResponse]
+    attr_reader :res
 
     ##
     # @param [Net::HTTPResponse] res
@@ -30,9 +28,40 @@ module LLM
     # @return [Hash, String]
     def body
       @body ||= case @res["content-type"]
-      when %r|\Aapplication/json\s*| then JSON.parse(@res.body)
+      when %r|\Aapplication/json\s*| then LLM::Object.from_hash(JSON.parse(@res.body))
       else @res.body
       end
     end
+
+    ##
+    # Returns an inspection of the response object
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} @body=#{body.inspect} @res=#{@res.inspect}>"
+    end
+
+    ##
+    # Returns true if the response is successful
+    # @return [Boolean]
+    def ok?
+      Net::HTTPSuccess === @res
+    end
+
+    ##
+    # Returns true if the response is from the Files API
+    # @return [Boolean]
+    def file?
+      false
+    end
+
+    private
+
+    def method_missing(m, *args, **kwargs, &b)
+      body.respond_to?(m) ? body[m.to_s] : super
+    end
+
+    def respond_to_missing?(m, include_private = false)
+      body.respond_to?(m) || super
+    end
   end
 end

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "0.10.1"
+  VERSION = "0.12.0"
 end

data/lib/llm.rb

@@ -12,13 +12,12 @@ module LLM
   require_relative "llm/mime"
   require_relative "llm/multipart"
   require_relative "llm/file"
-  require_relative "llm/model"
   require_relative "llm/provider"
   require_relative "llm/bot"
   require_relative "llm/buffer"
   require_relative "llm/function"
   require_relative "llm/eventstream"
-  require_relative "llm/event_handler"
+  require_relative "llm/eventhandler"
 
   module_function
 
@@ -27,18 +26,9 @@ module LLM
   # @return (see LLM::Anthropic#initialize)
   def anthropic(**)
     require_relative "llm/providers/anthropic" unless defined?(LLM::Anthropic)
-    require_relative "llm/providers/voyageai" unless defined?(LLM::VoyageAI)
     LLM::Anthropic.new(**)
   end
 
-  ##
-  # @param (see LLM::Provider#initialize)
-  # @return (see LLM::VoyageAI#initialize)
-  def voyageai(**)
-    require_relative "llm/providers/voyageai" unless defined?(LLM::VoyageAI)
-    LLM::VoyageAI.new(**)
-  end
-
   ##
   # @param (see LLM::Provider#initialize)
   # @return (see LLM::Gemini#initialize)
@@ -79,6 +69,15 @@ module LLM
     LLM::OpenAI.new(**)
   end
 
+  ##
+  # @param key (see LLM::XAI#initialize)
+  # @param host (see LLM::XAI#initialize)
+  # @return (see LLM::XAI#initialize)
+  def xai(**)
+    require_relative "llm/providers/xai" unless defined?(LLM::XAI)
+    LLM::XAI.new(**)
+  end
+
   ##
   # Define a function
   # @example
@@ -87,8 +86,8 @@ module LLM
   #     fn.params do |schema|
   #       schema.object(command: schema.string.required)
   #     end
-  #     fn.define do |params|
-  #       system(params.command)
+  #     fn.define do |command:|
+  #       system(command)
   #     end
   #   end
   # @param [Symbol] name The name of the function

data/llm.gemspec

@@ -10,14 +10,14 @@ Gem::Specification.new do |spec|
 
   spec.summary = <<~SUMMARY
   llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
-  includes OpenAI, Gemini, Anthropic, DeepSeek, Ollama, and LlamaCpp. The
-  toolkit includes full support for chat, streaming, tool calling, audio,
-  images, files, and JSON Schema generation.
+  includes OpenAI, Gemini, Anthropic, xAI (grok), DeepSeek, Ollama, and
+  LlamaCpp. The toolkit includes full support for chat, streaming, tool calling,
+  audio, images, files, and JSON Schema generation.
   SUMMARY
 
   spec.description = spec.summary
   spec.homepage = "https://github.com/llmrb/llm"
-  spec.license = "0BSDL"
+  spec.license = "0BSD"
   spec.required_ruby_version = ">= 3.2.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
@@ -37,7 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "test-cmd.rb", "~> 0.12.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "standard", "~> 1.40"
+  spec.add_development_dependency "standard", "~> 1.50"
   spec.add_development_dependency "vcr", "~> 6.0"
   spec.add_development_dependency "dotenv", "~> 2.8"
 end