tool_tailor 0.1.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33d87f65353ea72f0715a86b7759529f68f6678eb6a24d47fac0547bade1b59e
-  data.tar.gz: 874c949f555e93aa445147d89981e1207e11fdc4520977a668e9724354ca7d95
+  metadata.gz: 908a6461c07d131d14e6bd8be1a3fa6fa578e4f0261110d084238dbc657e8f33
+  data.tar.gz: 65541821e6c287d82e1bffd57e04da0c541654ea3e8edc84621cc0fbfbe11604
 SHA512:
-  metadata.gz: 4500dc6778e3bb5373a4630160b22a2ad7f0669ddb097d221eb93b3f1c27a93b48310ef4fcc434ec2c154ea004beb84d157bd1550d4ada0eb1e8fe7b8daa83da
-  data.tar.gz: 036f48ffa4b31354b24c85392cf52520215afcb02afac201289e19e650f4491be5fa0122aca606fc6d421d833ee2b8a64533b53a5936ea90608d2197caecd2b2
+  metadata.gz: 798fb99b7ac1fba192eec08684ac51d1f39f11e7bb6ff79757987a2aaabba1bb749ed865278dc37639e08ef6cd04b11de68f461ebbb0ee09433db3cb3d090f97
+  data.tar.gz: 4a2aeda57a2757776a05845d29fb1a09c479d2352820d5be0930c6b7b75c01c59f4712cd9367cda3e758e5c1d3c6d00385080b1768be256a1fde20ea73eb871d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    tool_tailor (0.1.3)
+    tool_tailor (0.2.0)
       yard (~> 0.9.36)
 
 GEM

data/README.md

@@ -1,6 +1,6 @@
 # ToolTailor
 
-ToolTailor is a Ruby gem that converts methods to OpenAI JSON schemas for use with tools, making it easier to integrate with OpenAI's API.
+ToolTailor is a Ruby gem that converts methods and classes to OpenAI JSON schemas for use with tools, making it easier to integrate with OpenAI's API.
 
 ## Installation
 
@@ -20,116 +20,116 @@ Or install it yourself as:
 
 ## Usage
 
-```rb
-class TestClass
+ToolTailor can convert both methods and classes to JSON schemas:
+
+### Converting Methods
+
+```ruby
+class WeatherService
   # Get the current weather in a given location.
   #
   # @param location [String] The city and state, e.g., San Francisco, CA.
-  # @param unit [String] The unit of temperature, either 'celsius' or 'fahrenheit'.
-  def get_current_weather(location:, unit: 'celsius')
+  # @param unit [String] The temperature unit to use. Infer this from the user's location.
+  # @values unit ["Celsius", "Fahrenheit"]
+  def get_current_temperature(location:, unit:)
     # Function implementation goes here
   end
 end
 
-# Simple
-ToolTailor.convert(TestClass.instance_method(:get_current_weather))
-
-# Unbound method with to_json_schema
-TestClass.instance_method(:get_current_weather).to_json_schema # => {
-#   "type" => "function",
-#   "function" => {
-#     "name" => "get_current_weather",
-#     "description" => "Get the current weather in a given location.",
-#     "parameters" => {
-#       "type" => "object",
-#       "properties" => {
-#         "location" => {
-#           "type" => "string",
-#           "description" => "The city and state, e.g., San Francisco, CA."
-#         },
-#         "unit" => {
-#           "type" => "string",
-#           "description" => "The unit of temperature, either 'celsius' or 'fahrenheit'."
-#         },
-#         "api_key" => {
-#           "type" => "number",
-#           "description" => "The API key for the weather service."
-#         }
-#       },
-#       "required" => ["location", "unit", "api_key"]
-#     }
-#   }
-
-# Bound method with to_json_schema
-example_instance = TestClass.new
-example_instance.method(:get_current_weather).to_json_schema # => {
-#   "type" => "function",
-#   "function" => {
-#     "name" => "get_current_weather",
-#     "description" => "Get the current weather in a given location.",
-#     "parameters" => {
-#       "type" => "object",
-#       "properties" => {
-#         "location" => {
-#           "type" => "string",
-#           "description" => "The city and state, e.g., San Francisco, CA."
-#         },
-#         "unit" => {
-#           "type" => "string",
-#           "description" => "The unit of temperature, either 'celsius' or 'fahrenheit'."
-#         },
-#         "api_key" => {
-#           "type" => "number",
-#           "description" => "The API key for the weather service."
-#         }
-#       },
-#       "required" => ["location", "unit", "api_key"]
-#     }
-#   }
-# }
+# Convert an instance method
+schema = ToolTailor.convert(WeatherService.instance_method(:get_current_temperature))
+
+# Using to_json_schema on an unbound method
+schema = WeatherService.instance_method(:get_current_temperature).to_json_schema
+
+# Using to_json_schema on a bound method
+weather_service = WeatherService.new
+schema = weather_service.method(:get_current_temperature).to_json_schema
+```
+
+### Converting Classes
+
+When passing a class, ToolTailor assumes you want to use the `new` method and generates the schema based on the `initialize` method:
+
+```ruby
+class User
+  # Create a new user
+  #
+  # @param name [String] The user's name
+  # @param age [Integer] The user's age
+  def initialize(name:, age:)
+    @name = name
+    @age = age
+  end
+end
+
+# Convert a class
+schema = ToolTailor.convert(User)
+
+# or
+schema = User.to_json_schema
+
+# This is equivalent to:
+schema = ToolTailor.convert(User.instance_method(:initialize))
 ```
 
-And with [ruby-openai](https://github.com/alexrudall/ruby-openai):
-
-```rb
-response =
-  client.chat(
-    parameters: {
-      model: "gpt-4o",
-      messages: [
-        {
-          "role": "user",
-          "content": "What is the weather like in San Francisco?",
+The resulting schema will look like this:
+
+```ruby
+{
+  "type" => "function",
+  "function" => {
+    "name" => "User",
+    "description" => "Create a new user",
+    "parameters" => {
+      "type" => "object",
+      "properties" => {
+        "name" => {
+          "type" => "string",
+          "description" => "The user's name"
         },
-      ],
-      tools: [
-        TestClass.instance_method(:get_current_weather).to_json_schema
-      ],
-      tool_choice: {
-        type: "function",
-        function: {
-          name: "get_current_weather"
+        "age" => {
+          "type" => "integer",
+          "description" => "The user's age"
         }
-      }
-    },
-  )
+      },
+      "required" => ["name", "age"]
+    }
+  }
+}
+```
+
+### Using with ruby-openai
+
+Here's an example of how to use ToolTailor with the [ruby-openai](https://github.com/alexrudall/ruby-openai) gem:
+
+```ruby
+response = client.chat(
+  parameters: {
+    model: "gpt-4",
+    messages: [
+      { role: "user", content: "Create a user named Alice who is 30 years old" }
+    ],
+    tools: [ToolTailor.convert(User)],
+    tool_choice: { type: "function", function: { name: "User" } }
+  }
+)
 
 message = response.dig("choices", 0, "message")
 
 if message["role"] == "assistant" && message["tool_calls"]
   function_name = message.dig("tool_calls", 0, "function", "name")
-  args =
-    JSON.parse(
-      message.dig("tool_calls", 0, "function", "arguments"),
-      { symbolize_names: true },
-    )
+  args = JSON.parse(
+    message.dig("tool_calls", 0, "function", "arguments"),
+    { symbolize_names: true }
+  )
 
   case function_name
-  when "get_current_weather"
-    TestClass.get_current_weather(**args)
+  when "User"
+    user = User.new(**args)
+    puts "Created user: #{user.name}, age #{user.age}"
   end
 end
-# => "The weather is nice 🌞"
 ```
 
 ## Development
@@ -140,10 +140,12 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/tool_tailor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/tool_tailor/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/kieranklaassen/tool_tailor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/kieranklaassen/tool_tailor/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
+
+Everyone interacting in the ToolTailor project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kieranklaassen/tool_tailor/blob/master/CODE_OF_CONDUCT.md).

data/lib/tool_tailor/version.rb

@@ -1,3 +1,3 @@
 module ToolTailor
-  VERSION = "0.1.3"
+  VERSION = "0.2.1"
 end

data/lib/tool_tailor.rb

@@ -1,51 +1,73 @@
 require "tool_tailor/version"
 require "json"
 require "yard"
+require "yard_custom_tags"
 
 module ToolTailor
   class Error < StandardError; end
 
-  # Converts a function to a JSON schema representation.
+  # Converts a function or class to a JSON schema representation.
   #
-  # @param function [Method, UnboundMethod] The function to convert.
-  # @return [String] The JSON schema representation of the function.
-  # @raise [ArgumentError] If the provided object is not a Method or UnboundMethod.
+  # @param object [Method, UnboundMethod, Class] The function or class to convert.
+  # @return [String] The JSON schema representation of the function or class.
+  # @raise [ArgumentError] If the provided object is not a Method, UnboundMethod, or Class.
   #
   # @example
-  #   def example_method(param1, param2)
+  #   def example_method(param1:, param2:)
   #     # method implementation
   #   end
   #
   #   ToolTailor.convert(method(:example_method))
-  def self.convert(function)
-    unless function.is_a?(Method) || function.is_a?(UnboundMethod)
-      raise ArgumentError, "Unsupported object type: #{function.class}"
+  #
+  # @example
+  #   class ExampleClass
+  #     def initialize(param1:, param2:)
+  #       # initialization
+  #     end
+  #   end
+  #
+  #   ToolTailor.convert(ExampleClass)
+  def self.convert(object)
+    case object
+    when Method, UnboundMethod
+      convert_method(object)
+    when Class
+      convert_class(object)
+    else
+      raise ArgumentError, "Unsupported object type: #{object.class}"
     end
+  end
 
+  # Converts a method to a JSON schema representation.
+  #
+  # @param method [Method, UnboundMethod] The method to convert.
+  # @return [String] The JSON schema representation of the method.
+  def self.convert_method(method)
     # Ensure only named arguments are allowed
-    unless function.parameters.all? { |type, _| type == :keyreq || type == :key }
+    unless method.parameters.all? { |type, _| type == :keyreq || type == :key }
       raise ArgumentError, "Only named arguments are supported"
     end
 
-    file_path, line_number = function.source_location
+    file_path, line_number = method.source_location
     YARD.parse(file_path)
 
-    method_path = "#{function.owner}##{function.name}"
+    method_path = "#{method.owner}##{method.name}"
     yard_object = YARD::Registry.at(method_path)
 
-    # Extract parameters from the function definition
-    parameters = function.parameters.map do |_, name|
+    # Extract parameters from the method definition
+    parameters = method.parameters.map do |_, name|
       {
         name: name.to_s,
         type: "string",
-        description: ""
+        description: "",
+        enum: nil
       }
     end
 
-    function_description = ""
+    method_description = ""
 
     if yard_object
-      function_description = yard_object.docstring
+      method_description = yard_object.docstring
 
       yard_object.tags("param").each do |tag|
         param_name = tag.name.chomp(':')
@@ -55,13 +77,19 @@ module ToolTailor
           param[:description] = tag.text
         end
       end
+
+      yard_object.tags("values").each do |tag|
+        param_name = tag.name.chomp(':')
+        param = parameters.find { |p| p[:name] == param_name }
+        param[:enum] = tag.text if param
+      end
     end
 
     {
       type: "function",
       function: {
-        name: function.name.to_s,
-        description: function_description,
+        name: method.name.to_s,
+        description: method_description,
         parameters: {
           type: "object",
           properties: parameters.map do |param|
@@ -69,16 +97,34 @@ module ToolTailor
               param[:name],
               {
                 type: param[:type],
-                description: param[:description]
-              }
+                description: param[:description],
+                enum: param[:enum]
+              }.compact
             ]
           end.to_h,
-          required: function.parameters.select { |type, _| type == :keyreq }.map { |_, name| name.to_s }
+          required: method.parameters.select { |type, _| type == :keyreq }.map { |_, name| name.to_s }
         }
       }
     }.to_json
   end
 
+  def self.convert_class(klass)
+    initialize_method = klass.instance_method(:initialize)
+    schema = JSON.parse(convert_method(initialize_method))
+    schema["function"]["name"] = klass.name
+
+    # Re-parse YARD documentation for the class
+    file_path, _ = initialize_method.source_location
+    YARD.parse(file_path)
+    class_object = YARD::Registry.at(klass.name)
+
+    if class_object
+      schema["function"]["description"] = class_object.docstring.to_s
+    end
+
+    schema.to_json
+  end
+
   # Maps Ruby types to JSON schema types.
   #
   # @param type [String] The Ruby type to map.
@@ -102,38 +148,6 @@ end
 class UnboundMethod
   # Converts an UnboundMethod to a JSON schema.
   #
-  # @example
-  #   class ExampleClass
-  #     # @param name [String] The name of the person.
-  #     # @param age [Integer] The age of the person.
-  #     def greet(name, age)
-  #       puts "Hello, #{name}! You are #{age} years old."
-  #     end
-  #   end
-  #
-  #   ExampleClass.instance_method(:greet).to_json_schema
-  #   # => {
-  #   #   "type" => "function",
-  #   #   "function" => {
-  #   #     "name" => "greet",
-  #   #     "description" => "",
-  #   #     "parameters" => {
-  #   #       "type" => "object",
-  #   #       "properties" => {
-  #   #         "name" => {
-  #   #           "type" => "string",
-  #   #           "description" => "The name of the person."
-  #   #         },
-  #   #         "age" => {
-  #   #           "type" => "integer",
-  #   #           "description" => "The age of the person."
-  #   #         }
-  #   #       },
-  #   #       "required" => ["name", "age"]
-  #   #     }
-  #   #   }
-  #   # }
-  #
   # @return [String] The JSON schema representation of the method.
   def to_json_schema
     ToolTailor.convert(self)
@@ -143,40 +157,17 @@ end
 class Method
   # Converts a Method to a JSON schema.
   #
-  # @example
-  #   class ExampleClass
-  #     # @param name [String] The name of the person.
-  #     # @param age [Integer] The age of the person.
-  #     def greet(name, age)
-  #       puts "Hello, #{name}! You are #{age} years old."
-  #     end
-  #   end
-  #
-  #   ExampleClass.new.method(:greet).to_json_schema
-  #   # => {
-  #   #   "type" => "function",
-  #   #   "function" => {
-  #   #     "name" => "greet",
-  #   #     "description" => "",
-  #   #     "parameters" => {
-  #   #       "type" => "object",
-  #   #       "properties" => {
-  #   #         "name" => {
-  #   #           "type" => "string",
-  #   #           "description" => "The name of the person."
-  #   #         },
-  #   #         "age" => {
-  #   #           "type" => "integer",
-  #   #           "description" => "The age of the person."
-  #   #         }
-  #   #       },
-  #   #       "required" => ["name", "age"]
-  #   #     }
-  #   #   }
-  #   # }
-  #
   # @return [String] The JSON schema representation of the method.
   def to_json_schema
     ToolTailor.convert(self)
   end
 end
+
+class Class
+  # Converts a Class to a JSON schema.
+  #
+  # @return [String] The JSON schema representation of the class's initialize method.
+  def to_json_schema
+    ToolTailor.convert(self)
+  end
+end

data/lib/yard_custom_tags.rb

@@ -0,0 +1,46 @@
+require "yard"
+
+module YARD
+  module Tags
+    # Custom tag class for handling `@values` tags.
+    class ValuesTag < YARD::Tags::Tag
+      TAG_FORMAT = /^(\S+)\s+\[(.+)\]$/
+
+      def initialize(tag_name, text)
+        name, values = parse_text(text)
+        super(tag_name, values, nil, name)
+      end
+
+      private
+
+      # Parses the text to match the expected format and extract the name and values.
+      def parse_text(text)
+        match = text.match(TAG_FORMAT)
+        unless match
+          raise ArgumentError, "Invalid @values tag format. Expected: @values <name> [value1, value2, ...]. Values should be a JSON array."
+        end
+
+        name, values_text = match.captures
+        values = parse_values(values_text)
+        [name, values]
+      end
+
+      # Parses the values text as a JSON array to ensure correct types.
+      def parse_values(values_text)
+        json_text = "[#{values_text}]"
+        JSON.parse(json_text)
+      rescue JSON::ParserError => e
+        raise ArgumentError, "Invalid values format: #{e.message}"
+      end
+    end
+
+    class Library
+      def self.define_custom_tag
+        # Defines a new custom tag `@values` using the ValuesTag class.
+        YARD::Tags::Library.define_tag("Values", :values, ValuesTag)
+      end
+    end
+  end
+end
+
+YARD::Tags::Library.define_custom_tag

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tool_tailor
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.1
 platform: ruby
 authors:
 - Kieran Klaassen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-30 00:00:00.000000000 Z
+date: 2024-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -45,6 +45,7 @@ files:
 - bin/setup
 - lib/tool_tailor.rb
 - lib/tool_tailor/version.rb
+- lib/yard_custom_tags.rb
 - tool_tailor.gemspec
 homepage: https://github.com/kieranklaassen/tool_tailor
 licenses: