langchainrb 0.14.0 → 0.15.1

data/lib/langchain/llm/unified_parameters.rb

@@ -77,8 +77,8 @@ module Langchain::LLM
       @parameters.to_h
     end
 
-    def each(&)
-      to_params.each(&)
+    def each(&block)
+      to_params.each(&block)
     end
 
     def <=>(other)

data/lib/langchain/tool/calculator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Langchain::Tool
+  #
+  # A calculator tool that falls back to the Google calculator widget
+  #
+  # Gem requirements:
+  #     gem "eqn", "~> 1.6.5"
+  #     gem "google_search_results", "~> 2.0.0"
+  #
+  # Usage:
+  #     calculator = Langchain::Tool::Calculator.new
+  #
+  class Calculator
+    extend Langchain::ToolDefinition
+    include Langchain::DependencyHelper
+
+    define_function :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" do
+      property :input, type: "string", description: "Math expression", required: true
+    end
+
+    def initialize
+      depends_on "eqn"
+    end
+
+    # 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
+    #
+    # @param input [String] math expression
+    # @return [String] Answer
+    def execute(input:)
+      Langchain.logger.info("Executing \"#{input}\"", for: self.class)
+
+      Eqn::Calculator.calc(input)
+    rescue Eqn::ParseError, Eqn::NoVariableValueError
+      "\"#{input}\" is an invalid mathematical expression"
+    end
+  end
+end

data/lib/langchain/tool/{database/database.rb → database.rb}

@@ -1,16 +1,28 @@
 module Langchain::Tool
-  class Database < Base
-    #
-    # Connects to a database, executes SQL queries, and outputs DB schema for Agents to use
-    #
-    # Gem requirements:
-    #     gem "sequel", "~> 5.68.0"
-    #
-    # Usage:
-    #     database = Langchain::Tool::Database.new(connection_string: "postgres://user:password@localhost:5432/db_name")
-    #
-    NAME = "database"
-    ANNOTATIONS_PATH = Langchain.root.join("./langchain/tool/#{NAME}/#{NAME}.json").to_path
+  #
+  # Connects to a database, executes SQL queries, and outputs DB schema for Agents to use
+  #
+  # Gem requirements:
+  #     gem "sequel", "~> 5.68.0"
+  #
+  # Usage:
+  #     database = Langchain::Tool::Database.new(connection_string: "postgres://user:password@localhost:5432/db_name")
+  #
+  class Database
+    extend Langchain::ToolDefinition
+    include Langchain::DependencyHelper
+
+    define_function :list_tables, description: "Database Tool: Returns a list of tables in the database"
+
+    define_function :describe_tables, description: "Database Tool: Returns the schema for a list of tables" do
+      property :tables, type: "string", description: "The tables to describe", required: true
+    end
+
+    define_function :dump_schema, description: "Database Tool: Returns the database schema"
+
+    define_function :execute, description: "Database Tool: Executes a SQL query and returns the results" do
+      property :input, type: "string", description: "SQL query to be executed", required: true
+    end
 
     attr_reader :db, :requested_tables, :excluded_tables
 

data/lib/langchain/tool/file_system.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Langchain::Tool
+  #
+  # A tool that wraps the Ruby file system classes.
+  #
+  # Usage:
+  #    file_system = Langchain::Tool::FileSystem.new
+  #
+  class FileSystem
+    extend Langchain::ToolDefinition
+
+    define_function :list_directory, description: "File System Tool: Lists out the content of a specified directory" do
+      property :directory_path, type: "string", description: "Directory path to list", required: true
+    end
+
+    define_function :read_file, description: "File System Tool: Reads the contents of a file" do
+      property :file_path, type: "string", description: "Path to the file to read from", required: true
+    end
+
+    define_function :write_to_file, description: "File System Tool: Write content to a file" do
+      property :file_path, type: "string", description: "Path to the file to write", required: true
+      property :content, type: "string", description: "Content to write to the file", required: true
+    end
+
+    def list_directory(directory_path:)
+      Dir.entries(directory_path)
+    rescue Errno::ENOENT
+      "No such directory: #{directory_path}"
+    end
+
+    def read_file(file_path:)
+      File.read(file_path)
+    rescue Errno::ENOENT
+      "No such file: #{file_path}"
+    end
+
+    def write_to_file(file_path:, content:)
+      File.write(file_path, content)
+    rescue Errno::EACCES
+      "Permission denied: #{file_path}"
+    end
+  end
+end

data/lib/langchain/tool/{google_search/google_search.rb → google_search.rb}

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
 module Langchain::Tool
-  class GoogleSearch < Base
-    #
-    # Wrapper around SerpApi's Google Search API
-    #
-    # Gem requirements:
-    #     gem "google_search_results", "~> 2.0.0"
-    #
-    # Usage:
-    #     search = Langchain::Tool::GoogleSearch.new(api_key: "YOUR_API_KEY")
-    #     search.execute(input: "What is the capital of France?")
-    #
-    NAME = "google_search"
-    ANNOTATIONS_PATH = Langchain.root.join("./langchain/tool/#{NAME}/#{NAME}.json").to_path
+  #
+  # Wrapper around SerpApi's Google Search API
+  #
+  # Gem requirements:
+  #     gem "google_search_results", "~> 2.0.0"
+  #
+  # Usage:
+  #     search = Langchain::Tool::GoogleSearch.new(api_key: "YOUR_API_KEY")
+  #     search.execute(input: "What is the capital of France?")
+  #
+  class GoogleSearch
+    extend Langchain::ToolDefinition
+    include Langchain::DependencyHelper
+
+    define_function :execute, description: "Executes Google Search and returns the result" do
+      property :input, type: "string", description: "Search query", required: true
+    end
 
     attr_reader :api_key
 
@@ -29,16 +33,6 @@ module Langchain::Tool
       @api_key = api_key
     end
 
-    #
-    # Executes Google Search and returns hash_results JSON
-    #
-    # @param input [String] search query
-    # @return [Hash] hash_results JSON
-    #
-    def self.execute_search(input:)
-      new.execute_search(input: input)
-    end
-
     # Executes Google Search and returns the result
     #
     # @param input [String] search query

data/lib/langchain/tool/{news_retriever/news_retriever.rb → news_retriever.rb}

@@ -1,16 +1,43 @@
 # 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
+  #
+  # 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"])
+  #
+  class NewsRetriever
+    extend Langchain::ToolDefinition
+
+    define_function :get_everything, description: "News Retriever: Search through millions of articles from over 150,000 large and small news sources and blogs" do
+      property :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'
+      property :search_in, type: "string", description: "The fields to restrict your q search to", enum: ["title", "description", "content"]
+      property :sources, type: "string", description: "A comma-separated 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"
+      property :domains, type: "string", description: "A comma-separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to"
+      property :exclude_domains, type: "string", description: "A comma-separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results"
+      property :from, type: "string", description: "A date and optional time for the oldest article allowed. This should be in ISO 8601 format"
+      property :to, type: "string", description: "A date and optional time for the newest article allowed. This should be in ISO 8601 format"
+      property :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"]
+      property :sort_by, type: "string", description: "The order to sort the articles in", enum: ["relevancy", "popularity", "publishedAt"]
+      property :page_size, type: "integer", description: "The number of results to return per page (request). 5 is the default, 100 is the maximum"
+      property :page, type: "integer", description: "Use this to page through the results if the total results found is greater than the page size"
+    end
+
+    define_function :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" do
+      property :country, type: "string", description: "The 2-letter ISO 3166-1 code of the country you want to get headlines for", 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"]
+      property :category, type: "string", description: "The category you want to get headlines for", enum: ["business", "entertainment", "general", "health", "science", "sports", "technology"]
+      property :q, type: "string", description: "Keywords or a phrase to search for"
+      property :page_size, type: "integer", description: "The number of results to return per page (request). 5 is the default, 100 is the maximum"
+      property :page, type: "integer", description: "Use this to page through the results if the total results found is greater than the page size"
+    end
+
+    define_function :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" do
+      property :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"]
+      property :category, type: "string", description: "The category you want to get headlines for. Default: all categories", enum: ["business", "entertainment", "general", "health", "science", "sports", "technology"]
+      property :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"]
+    end
 
     def initialize(api_key: ENV["NEWS_API_KEY"])
       @api_key = api_key
@@ -20,9 +47,9 @@ module Langchain::Tool
     #
     # @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 sources [String] A comma-separated 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-separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to.
+    # @param exclude_domains [String] A comma-separated 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.
@@ -66,7 +93,7 @@ module Langchain::Tool
     #
     # @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 sources [String] A comma-separated 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.

data/lib/langchain/tool/ruby_code_interpreter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Langchain::Tool
+  #
+  # A tool that execute Ruby code in a sandboxed environment.
+  #
+  # Gem requirements:
+  #     gem "safe_ruby", "~> 1.0.4"
+  #
+  # Usage:
+  #    interpreter = Langchain::Tool::RubyCodeInterpreter.new
+  #
+  class RubyCodeInterpreter
+    extend Langchain::ToolDefinition
+    include Langchain::DependencyHelper
+
+    define_function :execute, description: "Executes Ruby code in a sandboxes environment" do
+      property :input, type: "string", description: "Ruby code expression", required: true
+    end
+
+    def initialize(timeout: 30)
+      depends_on "safe_ruby"
+
+      @timeout = timeout
+    end
+
+    # Executes Ruby code in a sandboxes environment.
+    #
+    # @param input [String] ruby code expression
+    # @return [String] Answer
+    def execute(input:)
+      Langchain.logger.info("Executing \"#{input}\"", for: self.class)
+
+      safe_eval(input)
+    end
+
+    def safe_eval(code)
+      SafeRuby.eval(code, timeout: @timeout)
+    end
+  end
+end

data/lib/langchain/tool/{tavily/tavily.rb → tavily.rb}

@@ -1,16 +1,30 @@
 # frozen_string_literal: true
 
 module Langchain::Tool
-  class Tavily < Base
-    #
-    # Tavily Search is a robust search API tailored specifically for LLM Agents.
-    # It seamlessly integrates with diverse data sources to ensure a superior, relevant search experience.
-    #
-    # Usage:
-    #    tavily = Langchain::Tool::Tavily.new(api_key: ENV["TAVILY_API_KEY"])
-    #
-    NAME = "tavily"
-    ANNOTATIONS_PATH = Langchain.root.join("./langchain/tool/#{NAME}/#{NAME}.json").to_path
+  #
+  # Tavily Search is a robust search API tailored specifically for LLM Agents.
+  # It seamlessly integrates with diverse data sources to ensure a superior, relevant search experience.
+  #
+  # Usage:
+  #    tavily = Langchain::Tool::Tavily.new(api_key: ENV["TAVILY_API_KEY"])
+  #
+  class Tavily
+    extend Langchain::ToolDefinition
+
+    define_function :search, description: "Tavily Tool: Robust search API" do
+      property :query, type: "string", description: "The search query string", required: true
+      property :search_depth, type: "string", description: "The depth of the search: basic for quick results and advanced for indepth high quality results but longer response time", enum: ["basic", "advanced"]
+      property :include_images, type: "boolean", description: "Include a list of query related images in the response"
+      property :include_answer, type: "boolean", description: "Include answers in the search results"
+      property :include_raw_content, type: "boolean", description: "Include raw content in the search results"
+      property :max_results, type: "integer", description: "The number of maximum search results to return"
+      property :include_domains, type: "array", description: "A list of domains to specifically include in the search results" do
+        item type: "string"
+      end
+      property :exclude_domains, type: "array", description: "A list of domains to specifically exclude from the search results" do
+        item type: "string"
+      end
+    end
 
     def initialize(api_key:)
       @api_key = api_key

data/lib/langchain/tool/vectorsearch.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Langchain::Tool
+  #
+  # A tool wraps vectorsearch classes
+  #
+  # Usage:
+  #    # Initialize the LLM that will be used to generate embeddings
+  #    ollama = Langchain::LLM::Ollama.new(url: ENV["OLLAMA_URL"]
+  #    chroma = Langchain::Vectorsearch::Chroma.new(url: ENV["CHROMA_URL"], index_name: "my_index", llm: ollama)
+  #
+  #    # This tool can now be used by the Assistant
+  #    vectorsearch_tool = Langchain::Tool::Vectorsearch.new(vectorsearch: chroma)
+  #
+  class Vectorsearch
+    extend Langchain::ToolDefinition
+
+    define_function :similarity_search, description: "Vectorsearch: Retrieves relevant document for the query" do
+      property :query, type: "string", description: "Query to find similar documents for", required: true
+      property :k, type: "integer", description: "Number of similar documents to retrieve. Default value: 4"
+    end
+
+    attr_reader :vectorsearch
+
+    # Initializes the Vectorsearch tool
+    #
+    # @param vectorsearch [Langchain::Vectorsearch::Base] Vectorsearch instance to use
+    def initialize(vectorsearch:)
+      @vectorsearch = vectorsearch
+    end
+
+    # Executes the vector search and returns the results
+    #
+    # @param query [String] The query to search for
+    # @param k [Integer] The number of results to return
+    def similarity_search(query:, k: 4)
+      vectorsearch.similarity_search(query:, k: 4)
+    end
+  end
+end

data/lib/langchain/tool/weather.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Langchain::Tool
+  #
+  # A weather tool that gets current weather data
+  #
+  # Current weather data is free for 1000 calls per day (https://home.openweathermap.org/api_keys)
+  # Forecast and historical data require registration with credit card, so not supported yet.
+  #
+  # Usage:
+  #     weather = Langchain::Tool::Weather.new(api_key: ENV["OPEN_WEATHER_API_KEY"])
+  #     assistant = Langchain::Assistant.new(
+  #       llm: llm,
+  #       tools: [weather]
+  #     )
+  #
+  class Weather
+    extend Langchain::ToolDefinition
+
+    define_function :get_current_weather, description: "Returns current weather for a city" do
+      property :city,
+        type: "string",
+        description: "City name",
+        required: true
+      property :state_code,
+        type: "string",
+        description: "State code",
+        required: true
+      property :country_code,
+        type: "string",
+        description: "Country code",
+        required: false
+      property :units,
+        type: "string",
+        description: "Units for temperature (imperial or metric). Default: \"imperial\"",
+        enum: ["imperial", "metric", "standard"],
+        required: false
+    end
+
+    def initialize(api_key:)
+      @api_key = api_key
+    end
+
+    def get_current_weather(city:, state_code:, country_code: nil, units: "imperial")
+      validate_input(city: city, state_code: state_code, country_code: country_code, units: units)
+
+      Langchain.logger.info("get_current_weather", for: self.class, city:, state_code:, country_code:, units:)
+
+      fetch_current_weather(city: city, state_code: state_code, country_code: country_code, units: units)
+    end
+
+    private
+
+    def fetch_current_weather(city:, state_code:, country_code:, units:)
+      params = {appid: @api_key, q: [city, state_code, country_code].compact.join(","), units: units}
+
+      location_response = send_request(path: "geo/1.0/direct", params: params.except(:units))
+      return location_response if location_response.is_a?(String) # Error occurred
+
+      location = location_response.first
+      return "Location not found" unless location
+
+      params = params.merge(lat: location["lat"], lon: location["lon"]).except(:q)
+      weather_data = send_request(path: "data/2.5/weather", params: params)
+
+      parse_weather_response(weather_data, units)
+    end
+
+    def send_request(path:, params:)
+      uri = URI.parse("https://api.openweathermap.org/#{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"
+
+      Langchain.logger.info("Sending request to OpenWeatherMap API", path: path, params: params.except(:appid))
+      response = http.request(request)
+      Langchain.logger.info("Received response from OpenWeatherMap API", status: response.code)
+
+      if response.code == "200"
+        JSON.parse(response.body)
+      else
+        "API request failed: #{response.code} - #{response.message}"
+      end
+    end
+
+    def validate_input(city:, state_code:, country_code:, units:)
+      raise ArgumentError, "City name cannot be empty" if city.to_s.strip.empty?
+      raise ArgumentError, "State code cannot be empty" if state_code.to_s.strip.empty?
+      raise ArgumentError, "Invalid units. Use \"imperial\", \"standard\" or \"metric\"" unless ["imperial", "metric", "standard"].include?(units)
+    end
+
+    def parse_weather_response(response, units)
+      temp_unit = case units
+      when "standard" then "K"
+      when "metric" then "°C"
+      when "imperial" then "°F"
+      end
+      speed_unit = (units == "imperial") ? "mph" : "m/s"
+      {
+        temperature: "#{response["main"]["temp"]} #{temp_unit}",
+        humidity: "#{response["main"]["humidity"]}%",
+        description: response["weather"][0]["description"],
+        wind_speed: "#{response["wind"]["speed"]} #{speed_unit}"
+      }
+    end
+  end
+end

data/lib/langchain/tool/{wikipedia/wikipedia.rb → wikipedia.rb}

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
 module Langchain::Tool
-  class Wikipedia < Base
-    #
-    # Tool that adds the capability to search using the Wikipedia API
-    #
-    # Gem requirements:
-    #     gem "wikipedia-client", "~> 1.17.0"
-    #
-    # Usage:
-    #     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
+  #
+  # Tool that adds the capability to search using the Wikipedia API
+  #
+  # Gem requirements:
+  #     gem "wikipedia-client", "~> 1.17.0"
+  #
+  # Usage:
+  #     wikipedia = Langchain::Tool::Wikipedia.new
+  #     wikipedia.execute(input: "The Roman Empire")
+  #
+  class Wikipedia
+    extend Langchain::ToolDefinition
+    include Langchain::DependencyHelper
+
+    define_function :execute, description: "Executes Wikipedia API search and returns the answer" do
+      property :input, type: "string", description: "Search query", required: true
+    end
 
     # Initializes the Wikipedia tool
     def initialize