llm-shell 0.9.2 → 0.10.0

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::Response
+  ##
+  # The {LLM::Gemini::Response::WebSearch LLM::Gemini::Response::WebSearch}
+  # module provides methods for accessing web search results from a web search
+  # tool call made via the {LLM::Provider#web_search LLM::Provider#web_search}
+  # method.
+  module WebSearch
+    ##
+    # Returns one or more search results
+    # @return [Array<LLM::Object>]
+    def search_results
+      LLM::Object.from_hash(
+        candidates[0]
+          .groundingMetadata
+          .groundingChunks
+          .map { {"url" => _1.web.uri, "title" => _1.web.title} }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # @private
+  class StreamParser
+    ##
+    # Returns the fully constructed response body
+    # @return [LLM::Object]
+    attr_reader :body
+
+    ##
+    # @param [#<<] io An IO-like object
+    # @return [LLM::Gemini::StreamParser]
+    def initialize(io)
+      @body = LLM::Object.from_hash({candidates: []})
+      @io = io
+    end
+
+    ##
+    # @param [Hash] chunk
+    # @return [LLM::Gemini::StreamParser]
+    def parse!(chunk)
+      tap { merge_chunk!(LLM::Object.from_hash(chunk)) }
+    end
+
+    private
+
+    def merge_chunk!(chunk)
+      chunk.each do |key, value|
+        if key.to_s == "candidates"
+          merge_candidates!(value)
+        elsif key.to_s == "usageMetadata" &&
+            @body.usageMetadata.is_a?(LLM::Object) &&
+            value.is_a?(LLM::Object)
+          @body.usageMetadata = LLM::Object.from_hash(@body.usageMetadata.to_h.merge(value.to_h))
+        else
+          @body[key] = value
+        end
+      end
+    end
+
+    def merge_candidates!(new_candidates_list)
+      new_candidates_list.each do |new_candidate_delta|
+        index = new_candidate_delta.index
+        @body.candidates[index] ||= LLM::Object.from_hash({content: {parts: []}})
+        existing_candidate = @body.candidates[index]
+        new_candidate_delta.each do |key, value|
+          if key.to_s == "content"
+            merge_candidate_content!(existing_candidate.content, value) if value
+          else
+            existing_candidate[key] = value # Overwrite other fields
+          end
+        end
+      end
+    end
+
+    def merge_candidate_content!(existing_content, new_content_delta)
+      new_content_delta.each do |key, value|
+        if key.to_s == "parts"
+          existing_content.parts ||= []
+          merge_content_parts!(existing_content.parts, value) if value
+        else
+          existing_content[key] = value
+        end
+      end
+    end
+
+    def merge_content_parts!(existing_parts, new_parts_delta)
+      new_parts_delta.each do |new_part_delta|
+        if new_part_delta.text
+          last_existing_part = existing_parts.last
+          if last_existing_part&.text
+            last_existing_part.text << new_part_delta.text
+            @io << new_part_delta.text if @io.respond_to?(:<<)
+          else
+            existing_parts << new_part_delta
+            @io << new_part_delta.text if @io.respond_to?(:<<)
+          end
+        elsif new_part_delta.functionCall
+          existing_parts << new_part_delta
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The Gemini class implements a provider for
+  # [Gemini](https://ai.google.dev/). The Gemini provider
+  # can accept multiple inputs (text, images, audio, and video).
+  # The inputs can be provided inline via the prompt for files
+  # under 20MB or via the Gemini Files API for files
+  # that are over 20MB.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/horse.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class Gemini < Provider
+    require_relative "gemini/response/embedding"
+    require_relative "gemini/response/completion"
+    require_relative "gemini/response/web_search"
+    require_relative "gemini/error_handler"
+    require_relative "gemini/format"
+    require_relative "gemini/stream_parser"
+    require_relative "gemini/models"
+    require_relative "gemini/images"
+    require_relative "gemini/files"
+    require_relative "gemini/audio"
+
+    include Format
+
+    HOST = "generativelanguage.googleapis.com"
+
+    ##
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, **)
+    end
+
+    ##
+    # Provides an embedding
+    # @param input (see LLM::Provider#embed)
+    # @param model (see LLM::Provider#embed)
+    # @param params (see LLM::Provider#embed)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def embed(input, model: "text-embedding-004", **params)
+      model = model.respond_to?(:id) ? model.id : model
+      path = ["/v1beta/models/#{model}", "embedContent?key=#{@key}"].join(":")
+      req = Net::HTTP::Post.new(path, headers)
+      req.body = JSON.dump({content: {parts: [{text: input}]}})
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Gemini::Response::Embedding)
+    end
+
+    ##
+    # Provides an interface to the chat completions API
+    # @see https://ai.google.dev/api/generate-content#v1beta.models.generateContent Gemini 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 [LLM::Response]
+    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, model, stream = [:role, :model, :stream].map { params.delete(_1) }
+      action = stream ? "streamGenerateContent?key=#{@key}&alt=sse" : "generateContent?key=#{@key}"
+      model.respond_to?(:id) ? model.id : model
+      path = ["/v1beta/models/#{model}", action].join(":")
+      req  = Net::HTTP::Post.new(path, headers)
+      messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
+      body = JSON.dump({contents: format(messages)}.merge!(params))
+      set_body_stream(req, StringIO.new(body))
+      res = execute(request: req, stream:)
+      LLM::Response.new(res)
+        .extend(LLM::Gemini::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
+    end
+
+    ##
+    # Provides an interface to Gemini's audio API
+    # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs
+    # @return [LLM::Gemini::Audio]
+    def audio
+      LLM::Gemini::Audio.new(self)
+    end
+
+    ##
+    # Provides an interface to Gemini's image generation API
+    # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
+    # @return [see LLM::Gemini::Images]
+    def images
+      LLM::Gemini::Images.new(self)
+    end
+
+    ##
+    # Provides an interface to Gemini's file management API
+    # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
+    # @return [LLM::Gemini::Files]
+    def files
+      LLM::Gemini::Files.new(self)
+    end
+
+    ##
+    # Provides an interface to Gemini's models API
+    # @see https://ai.google.dev/gemini-api/docs/models Gemini docs
+    # @return [LLM::Gemini::Models]
+    def models
+      LLM::Gemini::Models.new(self)
+    end
+
+    ##
+    # @return (see LLM::Provider#assistant_role)
+    def assistant_role
+      "model"
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash gemini-2.5-flash
+    # @return [String]
+    def default_model
+      "gemini-2.5-flash"
+    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.
+    # @see https://ai.google.dev/gemini-api/docs/google-search Gemini docs
+    # @return (see LLM::Provider#server_tools)
+    def server_tools
+      {
+        google_search: server_tool(:google_search),
+        code_execution: server_tool(:code_execution),
+        url_context: server_tool(:url_context)
+      }
+    end
+
+    ##
+    # A convenience method for performing a web search using the
+    # Google Search tool.
+    # @param query [String] The search query.
+    # @return [LLM::Response] The response from the LLM provider.
+    def web_search(query:)
+      complete(query, tools: [server_tools[:google_search]])
+        .extend(LLM::Gemini::Response::WebSearch)
+    end
+
+    private
+
+    def headers
+      (@headers || {}).merge(
+        "Content-Type" => "application/json"
+      )
+    end
+
+    def stream_parser
+      LLM::Gemini::StreamParser
+    end
+
+    def error_handler
+      LLM::Gemini::ErrorHandler
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/llamacpp.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The LlamaCpp class implements a provider for
+  # [llama.cpp](https://github.com/ggml-org/llama.cpp)
+  # through the OpenAI-compatible API provided by the
+  # llama-server binary. Similar to the ollama provider,
+  # this provider supports a wide range of models and
+  # is straightforward to run on your own hardware.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.llamacpp(key: nil)
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/frog.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class LlamaCpp < OpenAI
+    ##
+    # @param (see LLM::Provider#initialize)
+    # @return [LLM::LlamaCpp]
+    def initialize(host: "localhost", port: 8080, ssl: false, **)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def files
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def images
+      raise NotImplementedError
+    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://ollama.com/library/qwen3 qwen3
+    # @return [String]
+    def default_model
+      "qwen3"
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class LLM::Ollama
+  ##
+  # @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::OpenAI::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::HTTPUnauthorized
+        raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
+      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
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/ollama/format/completion_format.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module LLM::Ollama::Format
+  ##
+  # @private
+  class CompletionFormat
+    ##
+    # @param [LLM::Message] message
+    #  The message to format
+    def initialize(message)
+      @message = message
+    end
+
+    ##
+    # Returns the message for the Ollama chat completions API
+    # @return [Hash]
+    def format
+      catch(:abort) do
+        if Hash === message
+          {role: message[:role]}.merge(format_content(message[:content]))
+        else
+          format_message
+        end
+      end
+    end
+
+    private
+
+    def format_content(content)
+      case content
+      when File
+        content.close unless content.closed?
+        format_content(LLM.File(content.path))
+      when LLM::File
+        if content.image?
+          {content: "This message has an image associated with it", images: [content.to_b64]}
+        else
+          raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                                  "is not an image, and therefore not supported by the " \
+                                  "Ollama API"
+        end
+      when String
+        {content:}
+      when LLM::Message
+        format_content(content.content)
+      when LLM::Function::Return
+        throw(:abort, {role: "tool", tool_call_id: content.id, content: JSON.dump(content.value)})
+      else
+        raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                                "is not supported by the Ollama API"
+      end
+    end
+
+    def format_message
+      case content
+      when Array
+        format_array
+      else
+        {role: message.role}.merge(format_content(content))
+      end
+    end
+
+    def format_array
+      if content.empty?
+        nil
+      elsif returns.any?
+        returns.map { {role: "tool", tool_call_id: _1.id, content: JSON.dump(_1.value)} }
+      else
+        content.flat_map { {role: message.role}.merge(format_content(_1)) }
+      end
+    end
+
+    def message = @message
+    def content = message.content
+    def returns = content.grep(LLM::Function::Return)
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class LLM::Ollama
+  ##
+  # @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_tools(tools)
+      return {} unless tools&.any?
+      {tools: tools.map { _1.format(self) }}
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/ollama/models.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class LLM::Ollama
+  ##
+  # The {LLM::Ollama::Models LLM::Ollama::Models} class provides a model
+  # object for interacting with [Ollama's models API](https://github.com/ollama/ollama/blob/main/docs/api.md#list-local-models).
+  # The models API allows a client to query Ollama for a list of models
+  # that are available for use with the Ollama API.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.ollama(nil)
+  #   res = llm.models.all
+  #   res.each do |model|
+  #     print "id: ", model.id, "\n"
+  #   end
+  class Models
+    include LLM::Utils
+
+    ##
+    # Returns a new Models object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Ollama::Models]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all models
+    # @example
+    #   llm = LLM.ollama(nil)
+    #   res = llm.models.all
+    #   res.each do |model|
+    #     print "id: ", model.id, "\n"
+    #   end
+    # @see https://github.com/ollama/ollama/blob/main/docs/api.md#list-local-models Ollama docs
+    # @see https://ollama.com/library Ollama library
+    # @param [Hash] params Other parameters (see Ollama docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def all(**params)
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/api/tags?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    private
+
+    [: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/ollama/response/completion.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LLM::Ollama::Response
+  module Completion
+    def model = body.model
+    def prompt_tokens = body.prompt_eval_count || 0
+    def completion_tokens = body.eval_count || 0
+    def total_tokens = prompt_tokens + completion_tokens
+    def message = body.message
+    def choices = [format_choices]
+
+    private
+
+    def format_choices
+      role, content, calls = message.to_h.values_at("role", "content", "tool_calls")
+      extra = {response: self, tool_calls: format_tool_calls(calls)}
+      LLM::Message.new(role, content, extra)
+    end
+
+    def format_tool_calls(tools)
+      return [] unless tools
+      tools.filter_map do |tool|
+        next unless tool["function"]
+        LLM::Object.new(tool["function"])
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class LLM::Ollama
+  ##
+  # @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 == "message"
+          if @body[key]
+            @body[key]["content"] << value["content"]
+            @io << value["content"] if @io.respond_to?(:<<)
+          else
+            @body[key] = value
+            @io << value["content"] if @io.respond_to?(:<<)
+          end
+        else
+          @body[key] = value
+        end
+      end
+    end
+  end
+end