llm-shell 0.9.2 → 0.10.0

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # @private
+  class StreamParser
+    ##
+    # Returns the fully constructed response body
+    # @return [LLM::Object]
+    attr_reader :body
+
+    ##
+    # @return [LLM::OpenAI::Chunk]
+    def initialize(io)
+      @body = LLM::Object.new
+      @io = io
+    end
+
+    ##
+    # @param [Hash] chunk
+    # @return [LLM::OpenAI::Chunk]
+    def parse!(chunk)
+      tap { merge!(chunk) }
+    end
+
+    private
+
+    def merge!(chunk)
+      chunk.each do |key, value|
+        if key == "choices"
+          @body["choices"] ||= []
+          merge_choices!(value)
+        else
+          @body[key] = value
+        end
+      end
+    end
+
+    def merge_choices!(choices)
+      choices.each do |choice|
+        if @body.choices[choice["index"]]
+          target_message = @body["choices"][choice["index"]]["message"]
+          delta = choice["delta"]
+          delta.each do |key, value|
+            if key == "content"
+              target_message[key] ||= +""
+              target_message[key] << value
+              @io << value if @io.respond_to?(:<<)
+            elsif key == "tool_calls"
+              merge_tools!(target_message, value)
+            else
+              target_message[key] = value
+            end
+          end
+        else
+          message_hash = {"role" => "assistant"}
+          @body["choices"][choice["index"]] = {"message" => message_hash}
+          choice["delta"].each do |key, value|
+            if key == "content"
+              @io << value if @io.respond_to?(:<<)
+              message_hash[key] = value
+            else
+              message_hash[key] = value
+            end
+          end
+        end
+      end
+    end
+
+    def merge_tools!(target, tools)
+      target["tool_calls"] ||= []
+      tools.each.with_index do |toola, index|
+        toolb = target["tool_calls"][index]
+        if toolb && toola["function"] && toolb["function"]
+          # Append to existing function arguments
+          toola["function"].each do |func_key, func_value|
+            toolb["function"][func_key] ||= +""
+            toolb["function"][func_key] << func_value
+          end
+        else
+          target["tool_calls"][index] = toola
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,228 @@
+# 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).
+  #
+  # @example
+  #  llm = LLM.openai(key: ENV["OPENAI_SECRET"])
+  #  files = %w(foo.pdf bar.pdf).map { llm.files.create(file: _1) }
+  #  store = llm.vector_stores.create_and_poll(name: "PDF Store", file_ids: files.map(&:id))
+  #  print "[-] store is ready", "\n"
+  #  chunks = llm.vector_stores.search(vector: store, query: "What is Ruby?")
+  #  chunks.each { |chunk| puts chunk }
+  class VectorStores
+    require_relative "response/enumerable"
+    PollError = Class.new(LLM::Error)
+
+    ##
+    # @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).extend(LLM::OpenAI::Response::Enumerable)
+    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
+
+    ##
+    # Create a vector store and poll until its status is "completed"
+    # @param (see LLM::OpenAI::VectorStores#create)
+    # @return (see LLM::OpenAI::VectorStores#poll)
+    def create_and_poll(...)
+      poll(vector: create(...))
+    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).extend(LLM::OpenAI::Response::Enumerable)
+    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).extend(LLM::OpenAI::Response::Enumerable)
+    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
+
+    ##
+    # Poll a vector store until its status is "completed"
+    # @param [String, #id] vector The ID of the vector store
+    # @param [Integer] attempts The current number of attempts (default: 0)
+    # @param [Integer] max The maximum number of iterations (default: 50)
+    # @raise [LLM::PollError] When the maximum number of iterations is reached
+    # @return [LLM::Response]
+    def poll(vector:, attempts: 0, max: 50)
+      if attempts == max
+        raise LLM::PollError, "vector store '#{vector.id}' has status '#{vector.status}' after #{max} attempts"
+      elsif vector.status == "expired"
+        raise LLM::PollError, "vector store '#{vector.id}' has expired"
+      elsif vector.status != "completed"
+        vector = get(vector:)
+        sleep(0.1 * (2**attempts))
+        poll(vector:, attempts: attempts + 1, max:)
+      else
+        vector
+      end
+    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/shell/internal/llm.rb/lib/llm/providers/openai.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The OpenAI class implements a provider for
+  # [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/response/web_search"
+    require_relative "openai/error_handler"
+    require_relative "openai/format"
+    require_relative "openai/stream_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
+
+    HOST = "api.openai.com"
+
+    ##
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, **)
+    end
+
+    ##
+    # Provides an embedding
+    # @see https://platform.openai.com/docs/api-reference/embeddings/create OpenAI docs
+    # @param input (see LLM::Provider#embed)
+    # @param model (see LLM::Provider#embed)
+    # @param params (see LLM::Provider#embed)
+    # @raise (see LLM::Provider#request)
+    # @return (see LLM::Provider#embed)
+    def embed(input, model: "text-embedding-3-small", **params)
+      req = Net::HTTP::Post.new("/v1/embeddings", headers)
+      req.body = JSON.dump({input:, model:}.merge!(params))
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::OpenAI::Response::Embedding)
+    end
+
+    ##
+    # Provides an interface to the chat completions API
+    # @see https://platform.openai.com/docs/api-reference/chat/create OpenAI docs
+    # @param prompt (see LLM::Provider#complete)
+    # @param params (see LLM::Provider#complete)
+    # @example (see LLM::Provider#complete)
+    # @raise (see LLM::Provider#request)
+    # @raise [LLM::PromptError]
+    #  When given an object a provider does not understand
+    # @return (see LLM::Provider#complete)
+    def complete(prompt, params = {})
+      params = {role: :user, model: default_model}.merge!(params)
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, format_schema(params), format_tools(tools)].inject({}, &:merge!).compact
+      role, stream = params.delete(:role), params.delete(:stream)
+      params[:stream] = true if stream.respond_to?(:<<) || stream == true
+      params[:stream_options] = {include_usage: true}.merge!(params[:stream_options] || {}) if params[:stream]
+      req = Net::HTTP::Post.new(completions_path, headers)
+      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      body = JSON.dump({messages: format(messages, :complete).flatten}.merge!(params))
+      set_body_stream(req, StringIO.new(body))
+      res = execute(request: req, stream:)
+      LLM::Response.new(res)
+        .extend(LLM::OpenAI::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
+    end
+
+    ##
+    # Provides an interface to OpenAI's response API
+    # @see https://platform.openai.com/docs/api-reference/responses/create OpenAI docs
+    # @return [LLM::OpenAI::Responses]
+    def responses
+      LLM::OpenAI::Responses.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's image generation API
+    # @see https://platform.openai.com/docs/api-reference/images/create OpenAI docs
+    # @return [LLM::OpenAI::Images]
+    def images
+      LLM::OpenAI::Images.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's audio generation API
+    # @see https://platform.openai.com/docs/api-reference/audio/createSpeech OpenAI docs
+    # @return [LLM::OpenAI::Audio]
+    def audio
+      LLM::OpenAI::Audio.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's files API
+    # @see https://platform.openai.com/docs/api-reference/files/create OpenAI docs
+    # @return [LLM::OpenAI::Files]
+    def files
+      LLM::OpenAI::Files.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's models API
+    # @see https://platform.openai.com/docs/api-reference/models/list OpenAI docs
+    # @return [LLM::OpenAI::Models]
+    def models
+      LLM::OpenAI::Models.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's moderation API
+    # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
+    # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
+    # @return [LLM::OpenAI::Moderations]
+    def moderations
+      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
+      "assistant"
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://platform.openai.com/docs/models/gpt-4.1 gpt-4.1
+    # @return [String]
+    def default_model
+      "gpt-4.1"
+    end
+
+    ##
+    # @note
+    #  This method includes certain tools that require configuration
+    #  through a set of options that are easier to set through the
+    #  {LLM::Provider#server_tool LLM::Provider#server_tool} method.
+    # @return (see LLM::Provider#server_tools)
+    def server_tools
+      {
+        web_search: server_tool(:web_search),
+        file_search: server_tool(:file_search),
+        image_generation: server_tool(:image_generation),
+        code_interpreter: server_tool(:code_interpreter),
+        computer_use: server_tool(:computer_use)
+      }
+    end
+
+    ##
+    # A convenience method for performing a web search using the
+    # OpenAI web search tool.
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   res = llm.web_search(query: "summarize today's news")
+    #   res.search_results.each { |item| print item.title, ": ", item.url, "\n" }
+    # @param query [String] The search query.
+    # @return [LLM::Response] The response from the LLM provider.
+    def web_search(query:)
+      responses
+        .create(query, store: false, tools: [server_tools[:web_search]])
+        .extend(LLM::OpenAI::Response::WebSearch)
+    end
+
+    private
+
+    def completions_path
+      "/v1/chat/completions"
+    end
+
+    def headers
+      (@headers || {}).merge(
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@key}"
+      )
+    end
+
+    def stream_parser
+      LLM::OpenAI::StreamParser
+    end
+
+    def error_handler
+      LLM::OpenAI::ErrorHandler
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/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/shell/internal/llm.rb/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