llms-tool 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 070d8ae6a371038ba6c46569ab65a0cc894df15fe1d67a3bda48e8f00fd20e46
+  data.tar.gz: e6b6876a663ba7873d13eb1c87798062545415fd5fcb5c05758a87eeb3c993f8
+SHA512:
+  metadata.gz: 611bd79059dba5040db249e8348bb32d3df414cfc276c413709c36984ec5bd18eac66a5ab747d7976ea5fd4cf6511a5cf250171352ae1058bf46eb0133785ce7
+  data.tar.gz: 5250ede90c87392625bc47f18215cb0bb11f33ab8d5f2911d59c41f5acba1a58faebd1bf4f201b0df743f5da9a8eb518d70ec4c204cc8ea7b820f2b64f256862

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LLMs::Tool Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

data/README.md

@@ -0,0 +1,200 @@
+# LLMs::Tool
+
+A Ruby gem for defining LLM tools via a simple DSL. Works well with [llms](https://github.com/benlund/llms) but can be used independently too.
+
+See also llms-agent (coming soon) which ties this all together.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'llms-tool'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install llms-tool
+```
+
+## Usage
+
+### Basic Tool Definition
+
+Create a simple tool by inheriting from `LLMs::Tool::Base`:
+
+```ruby
+class LetterCounter < LLMs::Tool::Base
+  tool_name :letter_counter
+  description "Count the number of letters in a word"
+  
+  parameter :word, String, "The word to count the letters of", required: true
+  parameter :letter, String, "The letter to count", required: true
+  
+  def run(*)
+    @word.count(@letter)
+  end
+end
+
+pp LetterCounter.tool_schema # Hash suitable for conversion into the JSON schema for the tool
+```
+
+Or if you just want to use the DSL you can just include the LLMs::Tool::Definition module in any class.
+
+```ruby
+class MyTool 
+  include LLMs::Tool::Definition
+
+  tool_name :my_tool
+  description "tool description"
+  parameter :name, String, "parameter description"
+end
+  
+pp MyTool.tool_schema
+# => {:name=>:my_tool, :description=>"tool description", :parameters=>{:type=>"object",
+#     :properties=>{:name=>{:type=>"string", :description=>"parameter description"}}, :required=>[]}}
+```
+
+### Using Tools with an LLM
+
+Tools can easily be called by LLMs using the [llms](https://github.com/benlund/llms) gem
+
+```ruby
+executor = LLMs::Executors.instance(
+  model_name: 'claude-sonnet-4-0',
+  temperature: 0.0,
+  max_completion_tokens: 2048,
+)
+
+conversation = LLMs::Conversation.new.tap do |c|
+  c.set_available_tools([LLMs::Tool::Calculator]) # Calculator is a simple example tool included in the llms-tool gem
+  c.set_system_message("Always use the available tools to answer the question.")
+  c.add_user_message("What is (two plus three) times four?")
+end
+
+response = executor.execute_conversation(conversation)
+puts response.text
+# => I'll calculate (two plus three) times four for you.
+
+pp response.tool_calls
+# => [#<LLMs::ConversationToolCall:0x00000001010474a8
+#     @arguments={"expression"=>"(2 + 3) * 4"}, @index=0, @name="calculator",
+#     @tool_call_id="toolu_01G3LVCEV1XJ7hwEhzCnrz6J", @tool_call_type="tool_use">]
+
+tools = LLMs::Tool::Calculator.new(response.tool_calls.first.arguments)
+pp tools.run
+# => "20.0"
+```
+
+See `examples/llm_tool_use.rb` for a more complete example.
+
+### Complex Parameters
+
+You can define complex nested parameters:
+
+```ruby
+class PageDetails < LLMs::Tool::Base
+  tool_name :page_details
+  description "Describe structured details about a product on a web page"
+  
+  parameter :title, String, "The title of the product", required: true
+  parameter :description, String, "The description of the product"
+  parameter :dimensions, Hash, "The dimensions of the product" do
+    parameter :length, Float, "The length of the product", required: true
+    parameter :width, Float, "The width of the product", required: true
+    parameter :height, Float, "The height of the product", required: true
+  end
+  parameter :prices, Array, "List of prices by quantity" do
+    parameter :currency, String, "The currency of the price", required: true
+    parameter :amount, Float, "The amount of the price", required: true
+    parameter :order_quantity_range, String, "The quantity range of the price e.g. '1-99', '100+'", required: false
+  end
+
+  # By default run method will return the parameter values assigned by the LLM, which is what we want
+end
+
+pp PageDetails.tool_schema
+
+# =>
+# {:name=>:page_details,
+#  :description=>"Describe structured details about a product on a web page",
+#  :parameters=>
+#   {:type=>"object",
+#    :properties=>
+#     {:title=>{:type=>"string", :description=>"The title of the product"},
+#      :description=>{:type=>"string", :description=>"The description of the product"},
+#      :dimensions=>
+#       {:type=>"object",
+#        :description=>"The dimensions of the product",
+#        :properties=>
+#         {:length=>{:type=>"number", :description=>"The length of the product"},
+#          :width=>{:type=>"number", :description=>"The width of the product"},
+#          :height=>{:type=>"number", :description=>"The height of the product"}},
+#        :required=>["length", "width", "height"]},
+#      :prices=>
+#       {:type=>"array",
+#        :description=>"List of prices by quantity",
+#        :items=>
+#         {:type=>"object",
+#          :properties=>
+#           {:currency=>{:type=>"string", :description=>"The currency of the price"},
+#            :amount=>{:type=>"number", :description=>"The amount of the price"},
+#            :order_quantity_range=>{:type=>"string", :description=>"The quantity range of the price e.g. '1-99', '100+'"}},
+#          :required=>["currency", "amount"]}}},
+ #   :required=>["title"]}}
+```
+
+See the `examples/` directory for runnable examples.
+
+## API Reference
+
+### LLMs::Tool::Base
+
+The base class for all tools. Includes the Definition module and provides a default constructor.
+
+#### Methods
+
+- `initialize(arguments)` - Initialize the tool with arguments object as supplied by an LLM
+- `run(*)` - Placeholder method that subclasses should implement. By default just returns the parameter values
+
+
+### LLMs::Tool::Definition
+
+A module that provides the DSL for defining tool parameters and generating JSON schemas.
+
+#### Class Methods
+
+- `tool_name(name = nil)` - Set or get the tool name
+- `description(text = nil)` - Set or get the tool description
+- `parameter(name, type, description, required: false, default: nil, &block)` - Define a parameter
+- `tool_schema` - Generate the JSON schema for the tool
+
+#### Instance Methods
+
+- `parameter_values` - Get a hash of all parameter values
+
+### Parameter Types
+
+The following Ruby types are supported and mapped to JSON schema types:
+
+- `String` → `"string"`
+- `Integer` → `"integer"`
+- `Float` → `"number"`
+- `Array` → `"array"`
+- `Hash` → `"object"`
+- `Boolean` → `"boolean"`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/benlund/llms-tool.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/llms-tool/base.rb

@@ -0,0 +1,21 @@
+require_relative 'definition'
+
+module LLMs
+  module Tool
+    class Base
+      include Definition
+
+      def initialize(args)
+        ## TODO convert nested hashes to symbol keys too?
+        ## TODO validate args against the tool schema and raise an error if they don't match
+        initialize_parameters(args.transform_keys(&:to_sym))
+      end
+
+      def run(*)
+        # Default implementation is to return the parameter values as a hash
+        # subclasses which need to take action should override this
+        parameter_values
+      end
+    end
+  end
+end 

data/lib/llms-tool/calculator.rb

@@ -0,0 +1,126 @@
+require_relative 'base'
+
+module LLMs
+  module Tool
+    class Calculator < Base
+      tool_name "calculator"
+      description "A simple calculator that evaluates arithmetic expressions"
+
+      parameter :expression, String, "The arithmetic expression to evaluate (e.g., '2 + 3 * 4', '(5 + 3) / 2')", required: true
+
+      def run(*)
+        unless valid_expression?(@expression)
+          raise ReportableError, "Invalid expression: only numbers, operators (+, -, *, /), parentheses, and spaces are allowed"
+        end
+        evaluate_expression(@expression).to_s
+      end
+
+      private
+
+      def valid_expression?(expr)
+        # Only allow numbers, operators, parentheses, and spaces
+        expr.match?(/^[\d\s\+\-\*\/\(\)\.]+$/)
+      end
+
+      def evaluate_expression(expr)
+        # Remove all spaces
+        expr = expr.gsub(/\s+/, '')
+        
+        # Simple recursive descent parser for basic arithmetic
+        tokens = tokenize(expr)
+        parse_expression(tokens)
+      end
+
+      def tokenize(expr)
+        tokens = []
+        i = 0
+        
+        while i < expr.length
+          char = expr[i]
+          
+          case char
+          when /\d/
+            # Parse number (including decimals)
+            num_str = ""
+            while i < expr.length && (expr[i] =~ /\d/ || expr[i] == '.')
+              num_str += expr[i]
+              i += 1
+            end
+            tokens << { type: :number, value: num_str.to_f }
+            next
+          when '+', '-', '*', '/', '(', ')'
+            tokens << { type: :operator, value: char }
+          end
+          
+          i += 1
+        end
+        
+        tokens
+      end
+
+      def parse_expression(tokens)
+        left = parse_term(tokens)
+        
+        while !tokens.empty? && ['+', '-'].include?(tokens.first[:value])
+          op = tokens.shift[:value]
+          right = parse_term(tokens)
+          
+          case op
+          when '+'
+            left += right
+          when '-'
+            left -= right
+          end
+        end
+        
+        left
+      end
+
+      def parse_term(tokens)
+        left = parse_factor(tokens)
+        
+        while !tokens.empty? && ['*', '/'].include?(tokens.first[:value])
+          op = tokens.shift[:value]
+          right = parse_factor(tokens)
+          
+          case op
+          when '*'
+            left *= right
+          when '/'
+            if right == 0
+              raise ArgumentError, "Division by zero"
+            end
+            left /= right
+          end
+        end
+        
+        left
+      end
+
+      def parse_factor(tokens)
+        if tokens.empty?
+          raise ArgumentError, "Unexpected end of expression"
+        end
+        
+        token = tokens.shift
+        
+        case token[:type]
+        when :number
+          token[:value]
+        when :operator
+          if token[:value] == '('
+            result = parse_expression(tokens)
+            
+            if tokens.empty? || tokens.shift[:value] != ')'
+              raise ArgumentError, "Missing closing parenthesis"
+            end
+            
+            result
+          else
+            raise ArgumentError, "Unexpected operator: #{token[:value]}"
+          end
+        end
+      end
+    end
+  end
+end 

data/lib/llms-tool/definition.rb

@@ -0,0 +1,138 @@
+module LLMs
+  module Tool
+    module Definition
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      class PropertyDefinitionSet
+        attr_reader :property_definitions
+
+        def initialize
+          @property_definitions = {}
+        end
+
+        def parameter(name, value_type, description, required: false, default: nil, &block)
+          @property_definitions[name] = PropertyDefinition.new.tap do |d|
+            d.name = name
+            d.description = description + (default ? " (default #{default})" : "")
+            d.value_type = value_type
+            d.is_required = required
+            d.default = default
+
+            if block_given?
+              d.value_definition = PropertyDefinitionSet.new.tap do |nested_set|
+                nested_set.instance_eval(&block)
+              end
+            end
+          end
+        end
+
+        def to_json_schema
+          {
+            type: 'object',
+            properties: property_definitions.transform_values(&:to_json_schema),
+            required: property_definitions.select { |_, prop| prop.is_required }.keys.map(&:to_s)
+          }
+        end
+      end
+
+      class PropertyDefinition
+        attr_accessor :name, :description, :value_type, :is_required, :value_definition, :default
+
+        def to_json_schema
+          schema = {
+            type: json_type,
+            description: description
+          }
+
+          if value_definition
+            if value_type.to_s == 'Array'
+              schema[:items] = value_definition.to_json_schema
+            else
+              schema.merge!(value_definition.to_json_schema)
+            end
+          end
+
+          schema
+        end
+
+        private
+
+        def json_type
+          case value_type.to_s
+          when 'String'  then 'string'
+          when 'Integer' then 'integer'
+          when 'Float'   then 'number'
+          when 'Array'   then 'array'
+          when 'Hash'    then 'object'
+          when 'TrueClass', 'FalseClass', 'Boolean' then 'boolean'
+          else 'string'
+          end
+        end
+      end
+
+      module ClassMethods
+        def property_definition_set
+          @property_definition_set ||= PropertyDefinitionSet.new
+        end
+
+        def tool_name(name = nil)
+          if name.nil?
+            @tool_name ||= (self.name ? self.name.split('::').last.downcase : 'class')
+          else
+            @tool_name = name
+          end
+        end
+
+        def description(text = nil)
+          if text.nil?
+            @description
+          else
+            @description = text
+          end
+        end
+
+        def parameter(name, type, description, required: false, default: nil, &block)
+          property_definition_set.parameter(name, type, description, required: required, default: default, &block)
+        end
+
+        def tool_schema
+          {
+            name: self.tool_name,
+            description: self.description,
+            parameters: self.property_definition_set.to_json_schema
+          }
+        end
+      end
+
+      def initialize_parameters(args)
+        # Validate required parameters
+        missing = self.class.property_definition_set.property_definitions.select { |_, prop| prop.is_required }.keys.select { |param| !args.key?(param) }
+        unless missing.empty?
+          raise ArgumentError, "Missing required parameters: #{missing.join(', ')}"
+        end
+
+        # Store parameters as instance variables
+        self.class.property_definition_set.property_definitions.each do |param, definition|
+          value = args[param]
+          value = definition.default if value.nil? && !definition.default.nil?
+          instance_variable_set("@#{param}", value)
+
+          # Define accessor method for this parameter
+          self.class.class_eval do
+            attr_reader param
+          end
+        end
+      end
+
+      def parameter_values
+        {}.tap do |values|
+          self.class.property_definition_set.property_definitions.each do |param, definition|
+            values[param.to_s] = instance_variable_get("@#{param}")
+          end
+        end
+      end
+    end
+  end
+end 

data/lib/llms-tool/reportable_error.rb

@@ -0,0 +1,6 @@
+module LLMs
+  module Tool
+    class ReportableError < StandardError
+    end
+  end
+end

data/lib/llms-tool.rb

@@ -0,0 +1,10 @@
+module LLMs
+  module Tool
+    VERSION = '0.1.0'
+  end
+end 
+
+require_relative 'llms-tool/definition'
+require_relative 'llms-tool/reportable_error'
+require_relative 'llms-tool/base'
+require_relative 'llms-tool/calculator' 

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: llms-tool
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben Lund
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: LLMs::Tool provides a simple DSL for defining tools that can be serialized
+  to the correct JSON schema to be used with LLM systems
+email:
+- ben@benlund.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/llms-tool.rb
+- lib/llms-tool/base.rb
+- lib/llms-tool/calculator.rb
+- lib/llms-tool/definition.rb
+- lib/llms-tool/reportable_error.rb
+homepage: https://github.com/benlund/llms-tool
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/benlund/llms-tool
+  source_code_uri: https://github.com/benlund/llms-tool
+  changelog_uri: https://github.com/benlund/llms-tool/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Ruby library for creating LLM tools with a simple DSL
+test_files: []