ask-tools 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41146df4fa3ec2cec15d6085c09d14204cedba968ea1afab6afa72cadf2ec971
-  data.tar.gz: 7592284b53e742c81654504d8e9c4b25e8f93c7876cd2a6b6fad2cc7dc8aa0c3
+  metadata.gz: 1a85f7d9d66c347416e813fa6f74b5f1d6f44f75107422d6d2de79f31318aa21
+  data.tar.gz: deab76f0fdde304174f3d6d11de03c556024b23e3163f0b4b51d2efbf74d834d
 SHA512:
-  metadata.gz: 8de6e0c216ab3432b59c016e0edcee9a2de8e303e83b73655e49d7b75a71c08deff8dc22ea917d2ebd9c6f30f667dc6aede63c3fce61bcbce30a10cc4e09c127
-  data.tar.gz: f7b0709e856f0f4e6eceaf21e7117bb59095fd6eebba267559fe0651468932b20e3d926feab4509145e4053ede86a41b70fcdc45deca176f2cb84dbfba9b0f84
+  metadata.gz: 20ea10459f3cef2feb1d59633d661a0fdd935c372d06d63967055a08723635999272cb5ff6f50115b06c797bb3a00e5fba61f5d580f365fe4de919d7a23aa9c2
+  data.tar.gz: f6e37198ee07a2bf183d6c46ee6c6d51fd638e48f71333c25cb3cb5870725da9ef36efc84439396f392132c3889e5c42835db771dfbafd5f220d3a95435ee0d5

data/lib/ask/tools/tool.rb

@@ -1,30 +1,11 @@
 # frozen_string_literal: true
 
+require "ask-schema"
+
 module Ask
-  # Base class for defining tools that LLMs can call.
-  #
-  # Subclass +Ask::Tool+, use the DSL to declare metadata and parameters,
-  # and implement +#execute+ to perform the work.
-  #
-  #   class Greeter < Ask::Tool
-  #     description "Greets a person by name"
-  #     param :name, type: :string, desc: "The person's name", required: true
-  #
-  #     def execute(name:)
-  #       Ask::Result.ok(data: "Hello, #{name}!")
-  #     end
-  #   end
-  #
-  #   Greeter.new.name         # => "greeter"
-  #   Greeter.new.call(name: "World")
-  #   # => #<Ask::Result ok=true output="Hello, World!">
-  #
   class Tool
-    # Raised (or returned from +#call+) to signal the conversation loop
-    # should stop rather than continuing after this tool's result.
     class Halt < StandardError
       attr_reader :content
-
       def initialize(content)
         @content = content
         super(content.to_s)
@@ -32,81 +13,65 @@ module Ask
     end
 
     class << self
-      # @api private
       def inherited(subclass)
         super
         @parameters = {} if @parameters.nil?
         subclass.instance_variable_set(:@description, nil)
         subclass.instance_variable_set(:@parameters, {})
+        subclass.instance_variable_set(:@params_schema_definition, nil)
       end
 
-      # Set or retrieve the tool's human-readable description.
-      #
-      # @param text [String, nil] when provided, sets the description
-      # @return [String, nil]
       def description(text = nil)
         return @description unless text
-
         @description = text
       end
       alias desc description
 
-      # Declare a parameter the tool accepts.
-      #
-      # @param name [Symbol] parameter name
-      # @param type [Symbol] JSON Schema type (+:string+, +:integer+, +:number+,
-      #   +:boolean+, +:array+, +:object+)
-      # @param desc [String] human-readable description of the parameter
-      # @param required [Boolean] whether the parameter is mandatory
-      # @return [void]
       def param(name, type:, desc: nil, description: nil, required: true)
         type = type.to_s.downcase.to_sym
         validate_param_type!(type, name)
         parameters[name] = Parameter.new(
-          name: name,
-          type: map_type(type),
-          description: desc || description,
-          required: required
+          name: name, type: map_type(type),
+          description: desc || description, required: required
         )
       end
 
-      # @api private
-      # @return [Hash{Symbol => Ask::Tool::Parameter}]
-      def parameters
-        @parameters ||= {}
-      end
-
-      # @api private
-      # Define tool parameters using the {Ask::Schema} DSL.
-      #
-      # When a block is provided, it takes precedence over individual
-      # +param+ declarations for schema generation.
-      #
-      # @example
-      #   params do
-      #     string :location, description: "City name"
-      #     string :unit, enum: %w[celsius fahrenheit]
-      #   end
-      #
-      # @param schema [Ask::Schema, Class<Ask::Schema>, Hash, nil] A pre-built schema
-      # @param block [Proc] DSL block evaluated by Ask::Schema
-      # @return [void]
       def params(schema = nil, &block)
         @params_schema_definition = schema || block
       end
 
+      def parameters
+        @parameters ||= {}
+      end
+
       def provider_params
         @provider_params ||= {}
       end
+
+      private
+
+      def validate_param_type!(type, name)
+        return if VALID_JSON_SCHEMA_TYPES.include?(type)
+        raise ArgumentError,
+          "Invalid type #{type.inspect} for parameter #{name.inspect}. " \
+          "Valid types: #{VALID_JSON_SCHEMA_TYPES.map(&:inspect).join(', ')}"
+      end
+
+      def map_type(type)
+        case type
+        when :int then "integer"
+        when :float, :double then "number"
+        else type.to_s
+        end
+      end
+    end
+
+    def provider_params
+      self.class.provider_params
     end
 
-    # Auto-derive the tool name from the class name.
-    # Converts CamelCase to snake_case and strips a trailing +_tool+ suffix.
-    #
-    # @return [String]
     def name
-      # Use only the class name (last segment), ignoring module nesting
-      klass_name = self.class.name.to_s.split("::").last || self.class.name.to_s
+      klass_name = self.class.name.to_s || ""
       normalized = klass_name.dup.force_encoding("UTF-8").unicode_normalize(:nfkd)
       normalized.encode("ASCII", replace: "")
                 .gsub(/[^a-zA-Z0-9_-]/, "-")
@@ -116,157 +81,113 @@ module Ask
                 .delete_suffix("_tool")
     end
 
-    # @return [String, nil] the tool's description
     def description
       self.class.description
     end
 
-    # @return [Hash{Symbol => Ask::Tool::Parameter}]
     def parameters
       self.class.parameters
     end
 
-    # Call the tool with the given arguments.
-    #
-    # Normalizes keys to symbols, validates required parameters,
-    # and delegates to +#execute+.
-    #
-    # @param args [Hash, nil] keyword arguments for the tool
-    # @return [Ask::Result] the tool's result
     def call(args = {})
       normalized = normalize_args(args)
       validation = validate(normalized)
-      return Ask::Result.error(message: validation) if validation
-
+      return Ask::Result.failure(validation) if validation
       execute(**normalized)
     rescue Halt => e
       Ask::Result.ok(data: e.content, metadata: { halted: true })
     rescue StandardError => e
-      Ask::Result.error(message: "#{self.class.name.split('::').last} raised #{e.class}: #{e.message}")
+      Ask::Result.failure("#{self.class.name.split('::').last} raised #{e.class}: #{e.message}")
     end
 
-    # Subclasses must implement this method.
-    #
-    # @param args [Hash] normalized keyword arguments
-    # @return [Ask::Result] the tool's result
     def execute(**)
       raise NotImplementedError, "#{self.class} must implement #execute(**args)"
     end
 
-    # Generate a JSON Schema hash describing this tool's parameters.
-    # Suitable for LLM function-calling APIs (OpenAI, Anthropic, etc.).
-    #
-    # @return [Hash]
     def params_schema
       return @params_schema if defined?(@params_schema)
-
       @params_schema = begin
-        if parameters.empty?
-          nil
+        if params_schema_definition
+          deep_stringify_keys(resolve_params_schema(params_schema_definition))
+        elsif parameters.any?
+          build_schema_from_params
         else
-          properties = parameters.to_h do |_name, param|
-            schema = { type: param.type }
-            schema[:description] = param.description if param.description
-            schema[:items] = { type: "string" } if param.type == "array"
-            [param.name.to_s, schema]
-          end
-
-          required = parameters.select { |_, p| p.required }.keys.map(&:to_s)
-
-          {
-            type: "object",
-            properties: properties,
-            required: required,
-            additionalProperties: false
-          }
+          nil
         end
       end
     end
 
-    # Full tool definition hash for LLM API calls.
-    #
-    # @return [Hash]
     def tool_definition
-      defn = {
-        name: name,
-        description: description
-      }
+      defn = { name: name, description: description }
       defn[:input_schema] = params_schema if params_schema
       defn
     end
 
-    # @return [String] inspect string
     def inspect
       "#<#{self.class.name} name=#{name.inspect}>"
     end
 
     private
 
+    def params_schema_definition
+      self.class.instance_variable_get(:@params_schema_definition)
+    end
+
+    def resolve_params_schema(definition)
+      case definition
+      when Proc
+        schema_class = Ask::Schema.create(&definition)
+        schema_class.new.to_json_schema.dig(:schema)
+      when Hash then definition
+      when ->(d) { d.respond_to?(:to_json_schema) }
+        definition.to_json_schema.dig(:schema)
+      else nil
+      end
+    end
+
+    def build_schema_from_params
+      properties = parameters.to_h do |_name, param|
+        schema = { type: param.type }
+        schema[:description] = param.description if param.description
+        schema[:items] = { type: "string" } if param.type == "array"
+        [param.name.to_s, schema]
+      end
+      required = parameters.select { |_, p| p.required }.keys.map(&:to_s)
+      { type: "object", properties: properties, required: required, additionalProperties: false }
+    end
+
+    def deep_stringify_keys(obj)
+      case obj
+      when Hash then obj.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify_keys(v) }
+      when Array then obj.map { |v| deep_stringify_keys(v) }
+      else obj
+      end
+    end
+
     def normalize_args(args)
       return {} if args.nil?
-
       args.respond_to?(:transform_keys) ? args.transform_keys(&:to_sym) : {}
     end
 
     def validate(normalized)
+      return nil if params_schema_definition
       missing = self.class.parameters.select { |_, p| p.required && !normalized.key?(p.name) }
       return "missing required parameters: #{missing.keys.map(&:inspect).join(', ')}" unless missing.empty?
-
       unknown = normalized.keys - self.class.parameters.keys
       return "unknown parameters: #{unknown.map(&:inspect).join(', ')}" unless unknown.empty?
-
       nil
     end
 
     VALID_JSON_SCHEMA_TYPES = %i[string integer number boolean array object].freeze
 
-    def self.validate_param_type!(type, name)
-      return if VALID_JSON_SCHEMA_TYPES.include?(type)
-
-      raise ArgumentError,
-            "Invalid type #{type.inspect} for parameter #{name.inspect}. " \
-            "Valid types: #{VALID_JSON_SCHEMA_TYPES.map(&:inspect).join(', ')}"
-    end
-
-    def self.map_type(type)
-      case type
-      when :int then "integer"
-      when :float, :double then "number"
-      else type.to_s
-      end
-    end
-
-    # Internal value object for parameter metadata.
     class Parameter
-      # @return [Symbol]
-      attr_reader :name
-
-      # @return [String] JSON Schema type string
-      attr_reader :type
-
-      # @return [String, nil]
-      attr_reader :description
-
-      # @return [Boolean]
-      attr_reader :required
-
+      attr_reader :name, :type, :description, :required
       alias required? required
-
       def initialize(name:, type:, description: nil, required: true)
-        @name = name
-        @type = type
-        @description = description
-        @required = required
+        @name = name; @type = type; @description = description; @required = required
       end
-
-      # @return [Hash]
       def to_h
-        {
-          name: name,
-          type: type,
-          description: description,
-          required: required
-        }
+        { name: name, type: type, description: description, required: required }
       end
     end
   end

data/lib/ask/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Ask
-  VERSION = "0.1.0"
+  module Tools
+    VERSION = "0.1.1"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tools
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kaka Ruto