langchainrb 0.12.0 → 0.13.0

data/lib/langchain/llm/response/base_response.rb

@@ -45,14 +45,14 @@ module Langchain
 
       # Return the completion candidates
       #
-      # @return [Array]
+      # @return [Array<String>]
       def completions
         raise NotImplementedError
       end
 
       # Return the chat completion candidates
       #
-      # @return [Array]
+      # @return [Array<String>]
       def chat_completions
         raise NotImplementedError
       end

data/lib/langchain/llm/response/cohere_response.rb

@@ -17,5 +17,21 @@ module Langchain::LLM
     def completion
       completions&.dig(0, "text")
     end
+
+    def chat_completion
+      raw_response.dig("text")
+    end
+
+    def role
+      raw_response.dig("chat_history").last["role"]
+    end
+
+    def prompt_tokens
+      raw_response.dig("meta", "billed_units", "input_tokens")
+    end
+
+    def completion_tokens
+      raw_response.dig("meta", "billed_units", "output_tokens")
+    end
   end
 end

data/lib/langchain/llm/response/google_gemini_response.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Langchain::LLM
+  class GoogleGeminiResponse < BaseResponse
+    def initialize(raw_response, model: nil)
+      super(raw_response, model: model)
+    end
+
+    def chat_completion
+      raw_response.dig("candidates", 0, "content", "parts", 0, "text")
+    end
+
+    def role
+      raw_response.dig("candidates", 0, "content", "role")
+    end
+
+    def tool_calls
+      if raw_response.dig("candidates", 0, "content") && raw_response.dig("candidates", 0, "content", "parts", 0).has_key?("functionCall")
+        raw_response.dig("candidates", 0, "content", "parts")
+      else
+        []
+      end
+    end
+
+    def embedding
+      embeddings.first
+    end
+
+    def embeddings
+      [raw_response.dig("predictions", 0, "embeddings", "values")]
+    end
+
+    def prompt_tokens
+      raw_response.dig("usageMetadata", "promptTokenCount")
+    end
+
+    def completion_tokens
+      raw_response.dig("usageMetadata", "candidatesTokenCount")
+    end
+
+    def total_tokens
+      raw_response.dig("usageMetadata", "totalTokenCount")
+    end
+  end
+end

data/lib/langchain/llm/response/openai_response.rb

@@ -25,7 +25,11 @@ module Langchain::LLM
     end
 
     def tool_calls
-      chat_completions&.dig(0, "message", "tool_calls")
+      if chat_completions.dig(0, "message").has_key?("tool_calls")
+        chat_completions.dig(0, "message", "tool_calls")
+      else
+        []
+      end
     end
 
     def embedding

data/lib/langchain/llm/unified_parameters.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Langchain::LLM
+  class UnifiedParameters
+    include Enumerable
+
+    attr_reader :schema, :aliases, :parameters, :ignored, :remapped
+
+    class Null < self
+      def initialize(parameters: {})
+        super(schema: {}, parameters: parameters)
+      end
+    end
+
+    def initialize(schema:, parameters: {})
+      @schema = schema || {}
+      @aliases = {}
+      @remapped = {}
+      @ignored = Set.new
+      @schema.each do |name, param|
+        @aliases[name] = Set.new(Array(param[:aliases])) if param[:aliases]
+      end
+      @parameters = to_params(parameters.to_h) if !parameters.to_h.empty?
+    end
+
+    def to_params(params = {})
+      # if params are provided, reset any previously initialized
+      @parameters = params if !params.empty?
+      @parameters = (@parameters || {}).merge!(params).slice(*schema.keys)
+      @aliases.each do |field, aliased_keys|
+        # favor existing keys in case of conflicts,
+        # and check for multiples
+        aliased_keys.each do |alias_key|
+          @parameters[field] ||= params[alias_key] if value_present?(params[alias_key])
+        end
+      end
+      @schema.each do |field, param_options|
+        param_options ||= {}
+        default = param_options[:default]
+        @parameters[field] ||= default if value_present?(default)
+      end
+      @remapped.each do |field, renamed_field|
+        @parameters[renamed_field] = @parameters[field] if value_present?(@parameters[field])
+      end
+      @parameters = @parameters.except(*@ignored + @remapped.keys)
+    end
+
+    def remap(field_map)
+      @remapped ||= {}
+      @remapped.merge!(field_map)
+      field_map.each do |field, renamed_field|
+        @schema[renamed_field] = @schema[field]
+      end
+    end
+
+    def update(schema = {})
+      @schema.merge!(schema)
+      schema.each do |name, param|
+        if param[:aliases]
+          @aliases[name] ||= Set.new
+          @aliases[name] << param[:aliases]
+        end
+      end
+      self
+    end
+
+    def ignore(*field_names)
+      @ignored.merge(field_names)
+    end
+
+    def alias_field(field_name, as:)
+      @aliases[field_name] ||= Set.new
+      @aliases[field_name] << as
+    end
+
+    def to_h
+      @parameters.to_h
+    end
+
+    def each(&)
+      to_params.each(&)
+    end
+
+    def <=>(other)
+      to_params.<=>(other.to_params)
+    end
+
+    def [](key)
+      to_params[key]
+    end
+
+    private
+
+    def value_present?(value)
+      !value.nil? && (!value.is_a?(Enumerable) || !value.empty?)
+    end
+  end
+end

data/lib/langchain/loader.rb

@@ -29,9 +29,11 @@ module Langchain
     # @param path [String | Pathname] path to file or URL
     # @param options [Hash] options passed to the processor class used to process the data
     # @return [Data] data loaded from path
+    # rubocop:disable Style/ArgumentsForwarding
     def self.load(path, options = {}, &block)
       new(path, options).load(&block)
     end
+    # rubocop:enable Style/ArgumentsForwarding
 
     # Initialize Langchain::Loader
     # @param path [String | Pathname] path to file or URL
@@ -76,12 +78,14 @@ module Langchain
     # @yieldreturn [String] parsed data, as a String
     #
     # @return [Data] data that was loaded
+    # rubocop:disable Style/ArgumentsForwarding
     def load(&block)
       return process_data(load_from_url, &block) if url?
       return load_from_directory(&block) if directory?
 
       process_data(load_from_path, &block)
     end
+    # rubocop:enable Style/ArgumentsForwarding
 
     private
 
@@ -95,6 +99,7 @@ module Langchain
       raise FileNotFound, "File #{@path} does not exist"
     end
 
+    # rubocop:disable Style/ArgumentsForwarding
     def load_from_directory(&block)
       Dir.glob(File.join(@path, "**/*")).map do |file|
         # Only load and add to result files with supported extensions
@@ -103,6 +108,7 @@ module Langchain
         UnknownFormatError nil
       end.flatten.compact
     end
+    # rubocop:enable Style/ArgumentsForwarding
 
     def process_data(data, &block)
       @raw_data = data

data/lib/langchain/tool/base.rb

@@ -3,13 +3,13 @@
 module Langchain::Tool
   # = Tools
   #
-  # Tools are used by Agents to perform specific tasks. Basically anything is possible with enough code!
+  # Tools are used by Agents to perform specific tasks. A 'Tool' is a collection of functions ("methods").
   #
   # == Available Tools
   #
   # - {Langchain::Tool::Calculator}: calculate the result of a math expression
   # - {Langchain::Tool::Database}: executes SQL queries
-  # - {Langchain::Tool::FileSystem}: interacts with files
+  # - {Langchain::Tool::FileSystem}: interacts with the file system
   # - {Langchain::Tool::GoogleSearch}: search on Google (via SerpAPI)
   # - {Langchain::Tool::RubyCodeInterpreter}: runs ruby code
   # - {Langchain::Tool::Weather}: gets current weather data
@@ -42,10 +42,10 @@ module Langchain::Tool
   #
   # == Adding Tools
   #
-  # 1. Create a new file in lib/langchain/tool/your_tool_name.rb
-  # 2. Create a class in the file that inherits from {Langchain::Tool::Base}
+  # 1. Create a new folder in lib/langchain/tool/your_tool_name/
+  # 2. Inside of this folder create a file with a class YourToolName that inherits from {Langchain::Tool::Base}
   # 3. Add `NAME=` and `ANNOTATIONS_PATH=` constants in your Tool class
-  # 4. Implement various methods in your tool class
+  # 4. Implement various public methods in your tool class
   # 5. Create a sidecar .json file in the same directory as your tool file annotating the methods in the Open API format
   # 6. Add your tool to the {file:README.md}
   class Base
@@ -66,11 +66,21 @@ module Langchain::Tool
 
     # Returns the tool as a list of OpenAI formatted functions
     #
-    # @return [Hash] tool as an OpenAI tool
+    # @return [Array<Hash>] List of hashes representing the tool as OpenAI formatted functions
     def to_openai_tools
       method_annotations
     end
 
+    # Returns the tool as a list of Google Gemini formatted functions
+    #
+    # @return [Array<Hash>] List of hashes representing the tool as Google Gemini formatted functions
+    def to_google_gemini_tools
+      method_annotations.map do |annotation|
+        # Slice out only the content of the "function" key
+        annotation["function"]
+      end
+    end
+
     # Return tool's method annotations as JSON
     #
     # @return [Hash] Tool's method annotations

data/lib/langchain/tool/calculator/calculator.json

@@ -2,7 +2,7 @@
   {
     "type": "function",
     "function": {
-      "name": "calculator-execute",
+      "name": "calculator__execute",
       "description": "Evaluates a pure math expression or if equation contains non-math characters (e.g.: \"12F in Celsius\") then it uses the google search calculator to evaluate the expression",
       "parameters": {
         "type": "object",

data/lib/langchain/tool/database/database.json

@@ -2,7 +2,7 @@
   {
     "type": "function",
     "function": {
-      "name": "database-describe_tables",
+      "name": "database__describe_tables",
       "description": "Database Tool: Returns the schema for a list of tables",
       "parameters": {
         "type": "object",
@@ -18,7 +18,7 @@
   }, {
     "type": "function",
     "function": {
-      "name": "database-list_tables",
+      "name": "database__list_tables",
       "description": "Database Tool: Returns a list of tables in the database",
       "parameters": {
         "type": "object",
@@ -29,7 +29,7 @@
   }, {
     "type": "function",
     "function": {
-      "name": "database-execute",
+      "name": "database__execute",
       "description": "Database Tool: Executes a SQL query and returns the results",
       "parameters": { 
         "type": "object",

data/lib/langchain/tool/file_system/file_system.json

@@ -2,7 +2,7 @@
   {
     "type": "function",
     "function": {
-      "name": "file_system-list_directory",
+      "name": "file_system__list_directory",
       "description": "File System Tool: Lists out the content of a specified directory",
       "parameters": {
         "type": "object",
@@ -19,7 +19,7 @@
   {
     "type": "function",
     "function": {
-      "name": "file_system-read_file",
+      "name": "file_system__read_file",
       "description": "File System Tool: Reads the contents of a file",
       "parameters": {
         "type": "object",
@@ -36,7 +36,7 @@
   {
     "type": "function",
     "function": {
-      "name": "file_system-write_to_file",
+      "name": "file_system__write_to_file",
       "description": "File System Tool: Write content to a file",
       "parameters": {
         "type": "object",

data/lib/langchain/tool/news_retriever/news_retriever.json

@@ -0,0 +1,121 @@
+[
+  {
+    "type": "function",
+    "function": {
+      "name": "news_retriever__get_everything",
+      "description": "News Retriever: Search through millions of articles from over 150,000 large and small news sources and blogs.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "q": {
+            "type": "string",
+            "description": "Keywords or phrases to search for in the article title and body. Surround phrases with quotes (\") for exact match. Alternatively you can use the AND / OR / NOT keywords, and optionally group these with parenthesis. Must be URL-encoded."
+          },
+          "search_in": {
+            "type": "string",
+            "description": "The fields to restrict your q search to.",
+            "enum": ["title", "description", "content"]
+          },
+          "sources": {
+            "type": "string",
+            "description": "A comma-seperated string of identifiers (maximum 20) for the news sources or blogs you want headlines from. Use the /sources endpoint to locate these programmatically or look at the sources index."
+          },
+          "domains": {
+            "type": "string",
+            "description": "A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to."
+          },
+          "exclude_domains": {
+            "type": "string",
+            "description": "A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results."
+          },
+          "from": {
+            "type": "string",
+            "description": "A date and optional time for the oldest article allowed. This should be in ISO 8601 format."
+          },
+          "to": {
+            "type": "string",
+            "description": "A date and optional time for the newest article allowed. This should be in ISO 8601 format."
+          },
+          "language": {
+            "type": "string",
+            "description": "The 2-letter ISO-639-1 code of the language you want to get headlines for.",
+            "enum": ["ar", "de", "en", "es", "fr", "he", "it", "nl", "no", "pt", "ru", "sv", "ud", "zh"]
+          },
+          "sort_by": {
+            "type": "string",
+            "description": "The order to sort the articles in.",
+            "enum": ["relevancy", "popularity", "publishedAt"]
+          },
+          "page_size": {
+            "type": "integer",
+            "description": "The number of results to return per page (request). 5 is the default, 100 is the maximum."
+          },
+          "page": {
+            "type": "integer",
+            "description": "Use this to page through the results if the total results found is greater than the page size."
+          } 
+        }
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "news_retriever__get_top_headlines",
+      "description": "News Retriever: Provides live top and breaking headlines for a country, specific category in a country, single source, or multiple sources. You can also search with keywords. Articles are sorted by the earliest date published first.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "country": {
+            "type": "string",
+            "description": "The 2-letter ISO 3166-1 code of the country you want to get headlines for."
+          },
+          "category": {
+            "type": "string",
+            "description": "The category you want to get headlines for.",
+            "enum": ["business", "entertainment", "general", "health", "science", "sports", "technology"]
+          },
+          "q": {
+            "type": "string",
+            "description": "Keywords or a phrase to search for."
+          },
+          "page_size": {
+            "type": "integer",
+            "description": "The number of results to return per page (request). 5 is the default, 100 is the maximum."
+          },
+          "page": {
+            "type": "integer",
+            "description": "Use this to page through the results if the total results found is greater than the page size."
+          } 
+        }
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "news_retriever__get_sources",
+      "description": "News Retriever: This endpoint returns the subset of news publishers that top headlines (/v2/top-headlines) are available from. It's mainly a convenience endpoint that you can use to keep track of the publishers available on the API, and you can pipe it straight through to your users.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "country": {
+            "type": "string",
+            "description": "The 2-letter ISO 3166-1 code of the country you want to get headlines for. Default: all countries.",
+            "enum": ["ae", "ar", "at", "au", "be", "bg", "br", "ca", "ch", "cn", "co", "cu", "cz", "de", "eg", "fr", "gb", "gr", "hk", "hu", "id", "ie", "il", "in", "it", "jp", "kr", "lt", "lv", "ma", "mx", "my", "ng", "nl", "no", "nz", "ph", "pl", "pt", "ro", "rs", "ru", "sa", "se", "sg", "si", "sk", "th", "tr", "tw", "ua", "us", "ve", "za"]
+          },
+          "category": {
+            "type": "string",
+            "description": "The category you want to get headlines for. Default: all categories.",
+            "enum": ["business", "entertainment", "general", "health", "science", "sports", "technology"]
+          },
+          "language": {
+            "type": "string",
+            "description": "The 2-letter ISO-639-1 code of the language you want to get headlines for.",
+            "enum": ["ar", "de", "en", "es", "fr", "he", "it", "nl", "no", "pt", "ru", "sv", "ud", "zh"]
+          }
+        }
+      }
+    }
+  }
+]

data/lib/langchain/tool/news_retriever/news_retriever.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Langchain::Tool
+  class NewsRetriever < Base
+    #
+    # A tool that retrieves latest news from various sources via https://newsapi.org/.
+    # An API key needs to be obtained from https://newsapi.org/ to use this tool.
+    #
+    # Usage:
+    #    news_retriever = Langchain::Tool::NewsRetriever.new(api_key: ENV["NEWS_API_KEY"])
+    #
+    NAME = "news_retriever"
+    ANNOTATIONS_PATH = Langchain.root.join("./langchain/tool/#{NAME}/#{NAME}.json").to_path
+
+    def initialize(api_key: ENV["NEWS_API_KEY"])
+      @api_key = api_key
+    end
+
+    # Retrieve all news
+    #
+    # @param q [String] Keywords or phrases to search for in the article title and body.
+    # @param search_in [String] The fields to restrict your q search to. The possible options are: title, description, content.
+    # @param sources [String] A comma-seperated string of identifiers (maximum 20) for the news sources or blogs you want headlines from. Use the /sources endpoint to locate these programmatically or look at the sources index.
+    # @param domains [String] A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to.
+    # @param exclude_domains [String] A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results.
+    # @param from [String] A date and optional time for the oldest article allowed. This should be in ISO 8601 format.
+    # @param to [String] A date and optional time for the newest article allowed. This should be in ISO 8601 format.
+    # @param language [String] The 2-letter ISO-639-1 code of the language you want to get headlines for. Possible options: ar, de, en, es, fr, he, it, nl, no, pt, ru, se, ud, zh.
+    # @param sort_by [String] The order to sort the articles in. Possible options: relevancy, popularity, publishedAt.
+    # @param page_size [Integer] The number of results to return per page. 20 is the API's default, 100 is the maximum. Our default is 5.
+    # @param page [Integer] Use this to page through the results.
+    #
+    # @return [String] JSON response
+    def get_everything(
+      q: nil,
+      search_in: nil,
+      sources: nil,
+      domains: nil,
+      exclude_domains: nil,
+      from: nil,
+      to: nil,
+      language: nil,
+      sort_by: nil,
+      page_size: 5, # The API default is 20 but that's too many.
+      page: nil
+    )
+      Langchain.logger.info("Retrieving all news", for: self.class)
+
+      params = {apiKey: @api_key}
+      params[:q] = q if q
+      params[:searchIn] = search_in if search_in
+      params[:sources] = sources if sources
+      params[:domains] = domains if domains
+      params[:excludeDomains] = exclude_domains if exclude_domains
+      params[:from] = from if from
+      params[:to] = to if to
+      params[:language] = language if language
+      params[:sortBy] = sort_by if sort_by
+      params[:pageSize] = page_size if page_size
+      params[:page] = page if page
+
+      send_request(path: "everything", params: params)
+    end
+
+    # Retrieve top headlines
+    #
+    # @param country [String] The 2-letter ISO 3166-1 code of the country you want to get headlines for. Possible options: ae, ar, at, au, be, bg, br, ca, ch, cn, co, cu, cz, de, eg, fr, gb, gr, hk, hu, id, ie, il, in, it, jp, kr, lt, lv, ma, mx, my, ng, nl, no, nz, ph, pl, pt, ro, rs, ru, sa, se, sg, si, sk, th, tr, tw, ua, us, ve, za.
+    # @param category [String] The category you want to get headlines for. Possible options: business, entertainment, general, health, science, sports, technology.
+    # @param sources [String] A comma-seperated string of identifiers for the news sources or blogs you want headlines from. Use the /sources endpoint to locate these programmatically.
+    # @param q [String] Keywords or a phrase to search for.
+    # @param page_size [Integer] The number of results to return per page. 20 is the API's default, 100 is the maximum. Our default is 5.
+    # @param page [Integer] Use this to page through the results.
+    #
+    # @return [String] JSON response
+    def get_top_headlines(
+      country: nil,
+      category: nil,
+      sources: nil,
+      q: nil,
+      page_size: 5,
+      page: nil
+    )
+      Langchain.logger.info("Retrieving top news headlines", for: self.class)
+
+      params = {apiKey: @api_key}
+      params[:country] = country if country
+      params[:category] = category if category
+      params[:sources] = sources if sources
+      params[:q] = q if q
+      params[:pageSize] = page_size if page_size
+      params[:page] = page if page
+
+      send_request(path: "top-headlines", params: params)
+    end
+
+    # Retrieve news sources
+    #
+    # @param category [String] The category you want to get headlines for. Possible options: business, entertainment, general, health, science, sports, technology.
+    # @param language [String] The 2-letter ISO-639-1 code of the language you want to get headlines for. Possible options: ar, de, en, es, fr, he, it, nl, no, pt, ru, se, ud, zh.
+    # @param country [String] The 2-letter ISO 3166-1 code of the country you want to get headlines for. Possible options: ae, ar, at, au, be, bg, br, ca, ch, cn, co, cu, cz, de, eg, fr, gb, gr, hk, hu, id, ie, il, in, it, jp, kr, lt, lv, ma, mx, my, ng, nl, no, nz, ph, pl, pt, ro, rs, ru, sa, se, sg, si, sk, th, tr, tw, ua, us, ve, za.
+    #
+    # @return [String] JSON response
+    def get_sources(
+      category: nil,
+      language: nil,
+      country: nil
+    )
+      Langchain.logger.info("Retrieving news sources", for: self.class)
+
+      params = {apiKey: @api_key}
+      params[:country] = country if country
+      params[:category] = category if category
+      params[:language] = language if language
+
+      send_request(path: "top-headlines/sources", params: params)
+    end
+
+    private
+
+    def send_request(path:, params:)
+      uri = URI.parse("https://newsapi.org/v2/#{path}?#{URI.encode_www_form(params)}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      request["Content-Type"] = "application/json"
+
+      response = http.request(request)
+      response.body
+    end
+  end
+end

data/lib/langchain/tool/ruby_code_interpreter/ruby_code_interpreter.json

@@ -2,7 +2,7 @@
   {
     "type": "function",
     "function": {
-      "name": "ruby_code_interpreter-execute",
+      "name": "ruby_code_interpreter__execute",
       "description": "Executes Ruby code in a sandboxes environment.",
       "parameters": {
         "type": "object",

data/lib/langchain/tool/vectorsearch/vectorsearch.json

@@ -2,7 +2,7 @@
   {
     "type": "function",
     "function": {
-      "name": "vectorsearch-similarity_search",
+      "name": "vectorsearch__similarity_search",
       "description": "Vectorsearch: Retrieves relevant document for the query",
       "parameters": {
         "type": "object",

data/lib/langchain/tool/weather/weather.json

@@ -2,7 +2,7 @@
   {
     "type": "function",
     "function": {
-      "name": "weather-execute",
+      "name": "weather__execute",
       "description": "Returns current weather for a city",
       "parameters": {
         "type": "object",

data/lib/langchain/tool/wikipedia/wikipedia.json

@@ -2,7 +2,7 @@
   {
     "type": "function",
     "function": {
-      "name": "wikipedia-execute",
+      "name": "wikipedia__execute",
       "description": "Executes Wikipedia API search and returns the answer",
       "parameters": {
         "type": "object",

data/lib/langchain/tool/wikipedia/wikipedia.rb

@@ -9,8 +9,8 @@ module Langchain::Tool
     #     gem "wikipedia-client", "~> 1.17.0"
     #
     # Usage:
-    #     weather = Langchain::Tool::Wikipedia.new
-    #     weather.execute(input: "The Roman Empire")
+    #     wikipedia = Langchain::Tool::Wikipedia.new
+    #     wikipedia.execute(input: "The Roman Empire")
     #
     NAME = "wikipedia"
     ANNOTATIONS_PATH = Langchain.root.join("./langchain/tool/#{NAME}/#{NAME}.json").to_path