llm.rb 0.11.0 → 0.13.0

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

@@ -2,36 +2,17 @@
 
 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

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

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

@@ -2,9 +2,8 @@
 
 class LLM::OpenAI
   ##
-  # The {LLM::OpenAI::VectorStore LLM::OpenAI::VectorStore} class provides
-  # an interface to OpenAI's vector stores API
-  # @see https://platform.openai.com/docs/api-reference/vector_stores/create OpenAI docs
+  # 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
@@ -97,6 +96,89 @@ class LLM::OpenAI
       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|

data/lib/llm/providers/openai.rb

@@ -3,7 +3,16 @@
 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"

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(prompt:, model: "grok-2-image-1212", **params)
+      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,6 +1,11 @@
 # 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"
 

data/lib/llm/{json/schema → schema}/array.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::Array JSON::Schema::Array} class represents an
+  # The {LLM::Schema::Array LLM::Schema::Array} class represents an
   # array value in a JSON schema. It is a subclass of
-  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
   # can act as constraints.
   class Array < Leaf
     def initialize(items)

data/lib/llm/{json/schema → schema}/boolean.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::Boolean JSON::Schema::Boolean} class represents a
+  # The {LLM::Schema::Boolean LLM::Schema::Boolean} class represents a
   # boolean value in a JSON schema. It is a subclass of
-  # {JSON::Schema::Leaf JSON::Schema::Leaf}.
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
   class Boolean < Leaf
     def to_h
       super.merge!({type: "boolean"})

data/lib/llm/{json/schema → schema}/integer.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::Integer JSON::Schema::Integer} class represents a
+  # The {LLM::Schema::Integer LLM::Schema::Integer} class represents a
   # whole number value in a JSON schema. It is a subclass of
-  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
   # can act as constraints.
   class Integer < Leaf
     ##
     # Constrain the number to a minimum value
     # @param [Integer] i The minimum value
-    # @return [JSON::Schema::Number] Returns self
+    # @return [LLM::Schema::Number] Returns self
     def min(i)
       tap { @minimum = i }
     end
@@ -18,7 +18,7 @@ class JSON::Schema
     ##
     # Constrain the number to a maximum value
     # @param [Integer] i The maximum value
-    # @return [JSON::Schema::Number] Returns self
+    # @return [LLM::Schema::Number] Returns self
     def max(i)
       tap { @maximum = i }
     end
@@ -26,7 +26,7 @@ class JSON::Schema
     ##
     # Constrain the number to a multiple of a given value
     # @param [Integer] i The multiple
-    # @return [JSON::Schema::Number] Returns self
+    # @return [LLM::Schema::Number] Returns self
     def multiple_of(i)
       tap { @multiple_of = i }
     end

data/lib/llm/{json/schema → schema}/leaf.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::Leaf JSON::Schema::Leaf} class is the
+  # The {LLM::Schema::Leaf LLM::Schema::Leaf} class is the
   # superclass of all values that can appear in a JSON schema.
-  # See the instance methods of {JSON::Schema JSON::Schema} for
-  # an example of how to create instances of {JSON::Schema::Leaf JSON::Schema::Leaf}
+  # See the instance methods of {LLM::Schema LLM::Schema} for
+  # an example of how to create instances of {LLM::Schema::Leaf LLM::Schema::Leaf}
   # through its subclasses.
   class Leaf
     def initialize
@@ -19,7 +19,7 @@ class JSON::Schema
     ##
     # Set the description of a leaf
     # @param [String] str The description
-    # @return [JSON::Schema::Leaf]
+    # @return [LLM::Schema::Leaf]
     def description(str)
       tap { @description = str }
     end
@@ -27,7 +27,7 @@ class JSON::Schema
     ##
     # Set the default value of a leaf
     # @param [Object] value The default value
-    # @return [JSON::Schema::Leaf]
+    # @return [LLM::Schema::Leaf]
     def default(value)
       tap { @default = value }
     end
@@ -36,7 +36,7 @@ class JSON::Schema
     # Set the allowed values of a leaf
     # @see https://tour.json-schema.org/content/02-Primitive-Types/07-Enumerated-Values-II Enumerated Values
     # @param [Array] values The allowed values
-    # @return [JSON::Schema::Leaf]
+    # @return [LLM::Schema::Leaf]
     def enum(*values)
       tap { @enum = values }
     end
@@ -45,14 +45,14 @@ class JSON::Schema
     # Set the value of a leaf to be a constant value
     # @see https://tour.json-schema.org/content/02-Primitive-Types/08-Defining-Constant-Values Constant Values
     # @param [Object] value The constant value
-    # @return [JSON::Schema::Leaf]
+    # @return [LLM::Schema::Leaf]
     def const(value)
       tap { @const = value }
     end
 
     ##
     # Denote a leaf as required
-    # @return [JSON::Schema::Leaf]
+    # @return [LLM::Schema::Leaf]
     def required
       tap { @required = true }
     end

data/lib/llm/{json/schema → schema}/null.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::Null JSON::Schema::Null} class represents a
+  # The {LLM::Schema::Null LLM::Schema::Null} class represents a
   # null value in a JSON schema. It is a subclass of
-  # {JSON::Schema::Leaf JSON::Schema::Leaf}.
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
   class Null < Leaf
     def to_h
       super.merge!({type: "null"})

data/lib/llm/{json/schema → schema}/number.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::Number JSON::Schema::Number} class represents a
+  # The {LLM::Schema::Number LLM::Schema::Number} class represents a
   # a number (either whole or decimal) value in a JSON schema. It is a
-  # subclass of {JSON::Schema::Leaf JSON::Schema::Leaf} and provides
+  # subclass of {LLM::Schema::Leaf LLM::Schema::Leaf} and provides
   # methods that can act as constraints.
   class Number < Leaf
     ##
     # Constrain the number to a minimum value
     # @param [Integer, Float] i The minimum value
-    # @return [JSON::Schema::Number] Returns self
+    # @return [LLM::Schema::Number] Returns self
     def min(i)
       tap { @minimum = i }
     end
@@ -18,7 +18,7 @@ class JSON::Schema
     ##
     # Constrain the number to a maximum value
     # @param [Integer, Float] i The maximum value
-    # @return [JSON::Schema::Number] Returns self
+    # @return [LLM::Schema::Number] Returns self
     def max(i)
       tap { @maximum = i }
     end
@@ -26,7 +26,7 @@ class JSON::Schema
     ##
     # Constrain the number to a multiple of a given value
     # @param [Integer, Float] i The multiple
-    # @return [JSON::Schema::Number] Returns self
+    # @return [LLM::Schema::Number] Returns self
     def multiple_of(i)
       tap { @multiple_of = i }
     end

data/lib/llm/{json/schema → schema}/object.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::Object JSON::Schema::Object} class represents an
+  # The {LLM::Schema::Object LLM::Schema::Object} class represents an
   # object value in a JSON schema. It is a subclass of
-  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
   # can act as constraints.
   class Object < Leaf
     def initialize(properties)

data/lib/llm/{json/schema → schema}/string.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-class JSON::Schema
+class LLM::Schema
   ##
-  # The {JSON::Schema::String JSON::Schema::String} class represents a
+  # The {LLM::Schema::String LLM::Schema::String} class represents a
   # string value in a JSON schema. It is a subclass of
-  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
   # can act as constraints.
   class String < Leaf
     ##
     # Constrain the string to a minimum length
     # @param [Integer] i The minimum length
-    # @return [JSON::Schema::String] Returns self
+    # @return [LLM::Schema::String] Returns self
     def min(i)
       tap { @minimum = i }
     end
@@ -18,7 +18,7 @@ class JSON::Schema
     ##
     # Constrain the string to a maximum length
     # @param [Integer] i The maximum length
-    # @return [JSON::Schema::String] Returns self
+    # @return [LLM::Schema::String] Returns self
     def max(i)
       tap { @maximum = i }
     end

data/lib/llm/{json/schema → schema}/version.rb

@@ -3,6 +3,6 @@
 module JSON
 end unless defined?(JSON)
 
-class JSON::Schema
+class LLM::Schema
   VERSION = "0.1.0"
 end

data/lib/llm/{json/schema.rb → schema.rb}

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-module JSON
-end unless defined?(JSON)
-
 ##
-# The {JSON::Schema JSON::Schema} class represents a JSON schema,
+# The {LLM::Schema LLM::Schema} class represents a JSON schema,
 # and provides methods that let you describe and produce a schema
 # that can be used in various contexts that include the validation
 # and generation of JSON data.
@@ -13,14 +10,14 @@ end unless defined?(JSON)
 # @see https://tour.json-schema.org/ JSON Schema Tour
 #
 # @example
-#  schema = JSON::Schema.new
+#  schema = LLM::Schema.new
 #  schema.object({
 #    name: schema.string.enum("John", "Jane").required,
 #    age: schema.integer.required,
 #    hobbies: schema.array(schema.string, schema.null).required,
 #    address: schema.object({street: schema.string}).required,
 #  })
-class JSON::Schema
+class LLM::Schema
   require_relative "schema/version"
   require_relative "schema/leaf"
   require_relative "schema/object"
@@ -34,7 +31,7 @@ class JSON::Schema
   ##
   # Returns an object
   # @param [Hash] properties A hash of properties
-  # @return [JSON::Schema::Object]
+  # @return [LLM::Schema::Object]
   def object(properties)
     Object.new(properties)
   end
@@ -42,42 +39,42 @@ class JSON::Schema
   ##
   # Returns an array
   # @param [Array] items An array of items
-  # @return [JSON::Schema::Array]
+  # @return [LLM::Schema::Array]
   def array(*items)
     Array.new(*items)
   end
 
   ##
   # Returns a string
-  # @return [JSON::Schema::String]
+  # @return [LLM::Schema::String]
   def string
     String.new
   end
 
   ##
   # Returns a number
-  # @return [JSON::Schema::Number] a number
+  # @return [LLM::Schema::Number] a number
   def number
     Number.new
   end
 
   ##
   # Returns an integer
-  # @return [JSON::Schema::Integer]
+  # @return [LLM::Schema::Integer]
   def integer
     Integer.new
   end
 
   ##
   # Returns a boolean
-  # @return [JSON::Schema::Boolean]
+  # @return [LLM::Schema::Boolean]
   def boolean
     Boolean.new
   end
 
   ##
   # Returns null
-  # @return [JSON::Schema::Null]
+  # @return [LLM::Schema::Null]
   def null
     Null.new
   end

data/lib/llm/version.rb

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