llm-shell 0.9.2 → 0.10.0

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/audio.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # The {LLM::Gemini::Audio LLM::Gemini::Audio} class provides an audio
+  # object for interacting with [Gemini's audio API](https://ai.google.dev/gemini-api/docs/audio).
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   res = llm.audio.create_transcription(input: "/audio/rocket.mp3")
+  #   res.text # => "A dog on a rocket to the moon"
+  class Audio
+    ##
+    # Returns a new Audio object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Gemini::Responses]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    #  This method is not implemented by Gemini
+    def create_speech
+      raise NotImplementedError
+    end
+
+    ##
+    # Create an audio transcription
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.audio.create_transcription(file: "/audio/rocket.mp3")
+    #   res.text # => "A dog on a rocket to the moon"
+    # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs
+    # @param [String, LLM::File, LLM::Response] file The input audio
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create_transcription(file:, model: "gemini-1.5-flash", **params)
+      res = @provider.complete [
+        "Your task is to transcribe the contents of an audio file",
+        "Your response should include the transcription, and nothing else",
+        LLM.File(file)
+      ], params.merge(role: :user, model:)
+      res.tap { _1.define_singleton_method(:text) { choices[0].content } }
+    end
+
+    ##
+    # Create an audio translation (in English)
+    # @example
+    #   # Arabic => English
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.audio.create_translation(file: "/audio/bismillah.mp3")
+    #   res.text # => "In the name of Allah, the Beneficent, the Merciful."
+    # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs
+    # @param [String, LLM::File, LLM::Response] file The input audio
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create_translation(file:, model: "gemini-1.5-flash", **params)
+      res = @provider.complete [
+        "Your task is to translate the contents of an audio file into English",
+        "Your response should include the translation, and nothing else",
+        LLM.File(file)
+      ], params.merge(role: :user, model:)
+      res.tap { _1.define_singleton_method(:text) { choices[0].content } }
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/error_handler.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # @private
+  class ErrorHandler
+    ##
+    # @return [Net::HTTPResponse]
+    #  Non-2XX response from the server
+    attr_reader :res
+
+    ##
+    # @param [Net::HTTPResponse] res
+    #  The response from the server
+    # @return [LLM::Gemini::ErrorHandler]
+    def initialize(res)
+      @res = res
+    end
+
+    ##
+    # @raise [LLM::Error]
+    #  Raises a subclass of {LLM::Error LLM::Error}
+    def raise_error!
+      case res
+      when Net::HTTPServerError
+        raise LLM::ServerError.new { _1.response = res }, "Server error"
+      when Net::HTTPBadRequest
+        reason = body.dig("error", "details", 0, "reason")
+        if reason == "API_KEY_INVALID"
+          raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
+        else
+          raise LLM::ResponseError.new { _1.response = res }, "Unexpected response"
+        end
+      when Net::HTTPTooManyRequests
+        raise LLM::RateLimitError.new { _1.response = res }, "Too many requests"
+      else
+        raise LLM::ResponseError.new { _1.response = res }, "Unexpected response"
+      end
+    end
+
+    private
+
+    def body
+      @body ||= JSON.parse(res.body)
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/files.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # The {LLM::Gemini::Files LLM::Gemini::Files} class provides a files
+  # object for interacting with [Gemini's Files API](https://ai.google.dev/gemini-api/docs/files).
+  # The files API allows a client to reference media files in prompts
+  # where they can be referenced by their URL.
+  #
+  # The files API is intended to preserve bandwidth and latency,
+  # especially for large files but it can be helpful for smaller files
+  # as well because it does not require the client to include a file
+  # in the prompt over and over again (which could be the case in a
+  # multi-turn conversation).
+  #
+  # @example example #1
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   file = llm.files.create(file: "/audio/haiku.mp3")
+  #   bot.chat ["Tell me about this file", file]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class Files
+    require_relative "response/file"
+    require_relative "response/files"
+
+    ##
+    # Returns a new Files object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Gemini::Files]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all files
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.files.all
+    #   res.each do |file|
+    #     print "name: ", file.name, "\n"
+    #   end
+    # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def all(**params)
+      query = URI.encode_www_form(params.merge!(key: key))
+      req = Net::HTTP::Get.new("/v1beta/files?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Gemini::Response::Files)
+    end
+
+    ##
+    # Create a file
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.files.create(file: "/audio/haiku.mp3")
+    # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
+    # @param [String, LLM::File] file The file
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create(file:, **params)
+      file = LLM.File(file)
+      req = Net::HTTP::Post.new(request_upload_url(file:), {})
+      req["content-length"] = file.bytesize
+      req["X-Goog-Upload-Offset"] = 0
+      req["X-Goog-Upload-Command"] = "upload, finalize"
+      file.with_io do |io|
+        set_body_stream(req, io)
+        res = execute(request: req)
+        LLM::Response.new(res).extend(LLM::Gemini::Response::File)
+      end
+    end
+
+    ##
+    # Get a file
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.files.get(file: "files/1234567890")
+    #   print "name: ", res.name, "\n"
+    # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
+    # @param [#name, String] file The file to get
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def get(file:, **params)
+      file_id = file.respond_to?(:name) ? file.name : file.to_s
+      query = URI.encode_www_form(params.merge!(key: key))
+      req = Net::HTTP::Get.new("/v1beta/#{file_id}?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Gemini::Response::File)
+    end
+
+    ##
+    # Delete a file
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.files.delete(file: "files/1234567890")
+    # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
+    # @param [#name, String] file The file to delete
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def delete(file:, **params)
+      file_id = file.respond_to?(:name) ? file.name : file.to_s
+      query = URI.encode_www_form(params.merge!(key: key))
+      req = Net::HTTP::Delete.new("/v1beta/#{file_id}?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    #  This method is not implemented by Gemini
+    def download
+      raise NotImplementedError
+    end
+
+    private
+
+    include LLM::Utils
+
+    def request_upload_url(file:)
+      req = Net::HTTP::Post.new("/upload/v1beta/files?key=#{key}", headers)
+      req["X-Goog-Upload-Protocol"] = "resumable"
+      req["X-Goog-Upload-Command"] = "start"
+      req["X-Goog-Upload-Header-Content-Length"] = file.bytesize
+      req["X-Goog-Upload-Header-Content-Type"] = file.mime_type
+      req.body = JSON.dump(file: {display_name: File.basename(file.path)})
+      res = execute(request: req)
+      res["x-goog-upload-url"]
+    end
+
+    def key
+      @provider.instance_variable_get(:@key)
+    end
+
+    [: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/gemini/format/completion_format.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Format
+  ##
+  # @private
+  class CompletionFormat
+    ##
+    # @param [LLM::Message, Hash] message
+    #  The message to format
+    def initialize(message)
+      @message = message
+    end
+
+    ##
+    # Formats the message for the Gemini chat completions API
+    # @return [Hash]
+    def format
+      catch(:abort) do
+        if Hash === message
+          {role: message[:role], parts: format_content(message[:content])}
+        elsif message.tool_call?
+          {role: message.role, parts: message.extra[:original_tool_calls].map { {"functionCall" => _1} }}
+        else
+          {role: message.role, parts: format_content(message.content)}
+        end
+      end
+    end
+
+    def format_content(content)
+      case content
+      when Array
+        content.empty? ? throw(:abort, nil) : content.flat_map { format_content(_1) }
+      when LLM::Response
+        format_response(content)
+      when File
+        content.close unless content.closed?
+        format_content(LLM.File(content.path))
+      when LLM::File
+        file = content
+        [{inline_data: {mime_type: file.mime_type, data: file.to_b64}}]
+      when String
+        [{text: content}]
+      when LLM::Message
+        format_content(content.content)
+      when LLM::Function::Return
+        [{functionResponse: {name: content.name, response: content.value}}]
+      else
+        prompt_error!(content)
+      end
+    end
+
+    def format_response(response)
+      if response.file?
+        file = response
+        [{file_data: {mime_type: file.mime_type, file_uri: file.uri}}]
+      else
+        prompt_error!(content)
+      end
+    end
+
+    def prompt_error!(object)
+      raise LLM::PromptError, "The given object (an instance of #{object.class}) " \
+                              "is not supported by the Gemini API"
+    end
+
+    def message = @message
+    def content = message.content
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/format.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # @private
+  module Format
+    require_relative "format/completion_format"
+
+    ##
+    # @param [Array<LLM::Message>] messages
+    #  The messages to format
+    # @return [Array<Hash>]
+    def format(messages)
+      messages.filter_map do |message|
+        CompletionFormat.new(message).format
+      end
+    end
+
+    private
+
+    ##
+    # @param [Hash] params
+    # @return [Hash]
+    def format_schema(params)
+      return {} unless params and params[:schema]
+      schema = params.delete(:schema)
+      {generationConfig: {response_mime_type: "application/json", response_schema: schema}}
+    end
+
+    ##
+    # @param [Hash] params
+    # @return [Hash]
+    def format_tools(tools)
+      return {} unless tools&.any?
+      platform, functions = [tools.grep(LLM::ServerTool), tools.grep(LLM::Function)]
+      {tools: [*platform, {functionDeclarations: functions.map { _1.format(self) }}]}
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/images.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # The {LLM::Gemini::Images LLM::Gemini::Images} class provides an images
+  # object for interacting with [Gemini's images API](https://ai.google.dev/gemini-api/docs/image-generation).
+  # Please note that unlike OpenAI, which can return either URLs or base64-encoded strings,
+  # Gemini's images API will always return an image as a base64 encoded string that
+  # can be decoded into binary.
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon"
+  #   IO.copy_stream res.images[0], "rocket.png"
+  class Images
+    require_relative "response/image"
+    include Format
+
+    ##
+    # Returns a new Images object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Gemini::Responses]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # Create an image
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.images.create prompt: "A dog on a rocket to the moon"
+    #   IO.copy_stream res.images[0], "rocket.png"
+    # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
+    # @param [String] prompt The prompt
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @raise [LLM::NoImageError] when no images are returned
+    # @note
+    #  The prompt should make it clear you want to generate an image, or you
+    #  might unexpectedly receive a purely textual response. This is due to how
+    #  Gemini implements image generation under the hood.
+    # @return [LLM::Response]
+    def create(prompt:, model: "gemini-2.5-flash-image-preview", **params)
+      req  = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
+      body = JSON.dump({
+        contents: [{parts: [{text: create_prompt}, {text: prompt}]}],
+        generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
+      }.merge!(params))
+      req.body = body
+      res = execute(request: req)
+      validate LLM::Response.new(res).extend(LLM::Gemini::Response::Image)
+    end
+
+    ##
+    # Edit an image
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.images.edit image: "cat.png", prompt: "Add a hat to the cat"
+    #   IO.copy_stream res.images[0], "hatoncat.png"
+    # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
+    # @param [String, LLM::File] image The image to edit
+    # @param [String] prompt The prompt
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @raise [LLM::NoImageError] when no images are returned
+    # @note (see LLM::Gemini::Images#create)
+    # @return [LLM::Response]
+    def edit(image:, prompt:, model: "gemini-2.5-flash-image-preview", **params)
+      req   = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
+      image = LLM.File(image)
+      body  = JSON.dump({
+        contents: [{parts: [{text: edit_prompt}, {text: prompt}, format.format_content(image)]}],
+        generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
+      }.merge!(params)).b
+      set_body_stream(req, StringIO.new(body))
+      res = execute(request: req)
+      validate LLM::Response.new(res).extend(LLM::Gemini::Response::Image)
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    #  This method is not implemented by Gemini
+    def create_variation
+      raise NotImplementedError
+    end
+
+    private
+
+    def format
+      @format ||= CompletionFormat.new(nil)
+    end
+
+    def key
+      @provider.instance_variable_get(:@key)
+    end
+
+    def create_prompt
+      <<~PROMPT
+        ## Context
+        Your task is to generate one or more image(s) based on the user's instructions.
+        The user will provide you with text only.
+
+        ## Instructions
+        1. The model *MUST* generate image(s) based on the user text alone.
+        2. The model *MUST NOT* generate anything else.
+      PROMPT
+    end
+
+    def edit_prompt
+      <<~PROMPT
+        ## Context
+        Your task is to edit the provided image based on the user's instructions.
+        The user will provide you with both text and an image.
+
+        ## Instructions
+        1. The model *MUST* edit the provided image based on the user's instructions
+        2. The model *MUST NOT* generate a new image.
+        3. The model *MUST NOT* generate anything else.
+      PROMPT
+    end
+
+    def validate(res)
+      return res unless res.images.empty?
+      raise LLM::NoImageError.new { _1.response = res.res }, "no images found in response"
+    end
+
+    [: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/gemini/models.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # The {LLM::Gemini::Models LLM::Gemini::Models} class provides a model
+  # object for interacting with [Gemini's models API](https://ai.google.dev/api/models?hl=en#method:-models.list).
+  # The models API allows a client to query Gemini for a list of models
+  # that are available for use with the Gemini API.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   res = llm.models.all
+  #   res.each do |model|
+  #     print "id: ", model.id, "\n"
+  #   end
+  class Models
+    require_relative "response/models"
+    include LLM::Utils
+
+    ##
+    # Returns a new Models object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Gemini::Models]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all models
+    # @example
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.models.all
+    #   res.each do |model|
+    #     print "id: ", model.id, "\n"
+    #   end
+    # @see https://ai.google.dev/api/models?hl=en#method:-models.list Gemini docs
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def all(**params)
+      query = URI.encode_www_form(params.merge!(key: key))
+      req = Net::HTTP::Get.new("/v1beta/models?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Gemini::Response::Models)
+    end
+
+    private
+
+    def key
+      @provider.instance_variable_get(:@key)
+    end
+
+    [:headers, :execute].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/gemini/response/completion.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Response
+  module Completion
+    def model = body.modelVersion
+    def prompt_tokens = body.usageMetadata.promptTokenCount
+    def completion_tokens = body.usageMetadata.candidatesTokenCount
+    def total_tokens = body.usageMetadata.totalTokenCount
+    def choices = format_choices
+
+    private
+
+    def format_choices
+      candidates.map.with_index do |choice, index|
+        choice = LLM::Object.from_hash(choice)
+        content = choice.content || LLM::Object.new
+        role = content.role || "model"
+        parts = content.parts || [{"text" => choice.finishReason}]
+        text  = parts.filter_map { _1["text"] }.join
+        tools = parts.filter_map { _1["functionCall"] }
+        extra = {index:, response: self, tool_calls: format_tool_calls(tools), original_tool_calls: tools}
+        LLM::Message.new(role, text, extra)
+      end
+    end
+
+    def format_tool_calls(tools)
+      (tools || []).map do |tool|
+        function = {name: tool.name, arguments: tool.args}
+        LLM::Object.new(function)
+      end
+    end
+
+    def candidates = body.candidates || []
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/response/embedding.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Response
+  module Embedding
+    def model = "text-embedding-004"
+    def embeddings = body.dig("embedding", "values")
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/response/file.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Response
+  module File
+    def name = respond_to?(:file) ? file.name : body.name
+    def display_name = respond_to?(:file) ? file.displayName : body.displayName
+    def mime_type = respond_to?(:file) ? file.mimeType : body.mimeType
+    def uri = respond_to?(:file) ? file.uri : body.uri
+    def file? = true
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/response/files.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Response
+  module Files
+    include ::Enumerable
+    def each(&)
+      return enum_for(:each) unless block_given?
+      files.each { yield(_1) }
+    end
+
+    def files
+      body.files || []
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/response/image.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Response
+  module Image
+    ##
+    # @return [Array<StringIO>]
+    def images
+      candidates.flat_map do |candidate|
+        parts = candidate&.dig(:content, :parts) || []
+        parts.filter_map do
+          data = _1.dig(:inlineData, :data)
+          next unless data
+          StringIO.new(data.unpack1("m0"))
+        end
+      end
+    end
+
+    ##
+    # Returns one or more image URLs, or an empty array
+    # @note
+    #  Gemini's image generation API does not return URLs, so this method
+    #  will always return an empty array.
+    # @return [Array<String>]
+    def urls = []
+
+    ##
+    # Returns one or more candidates, or an empty array
+    # @return [Array<Hash>]
+    def candidates = body.candidates || []
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/gemini/response/models.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Response
+  module Models
+    include ::Enumerable
+    def each(&)
+      return enum_for(:each) unless block_given?
+      models.each { yield(_1) }
+    end
+
+    def models
+      body.models || []
+    end
+  end
+end