ask-tools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41146df4fa3ec2cec15d6085c09d14204cedba968ea1afab6afa72cadf2ec971
+  data.tar.gz: 7592284b53e742c81654504d8e9c4b25e8f93c7876cd2a6b6fad2cc7dc8aa0c3
+SHA512:
+  metadata.gz: 8de6e0c216ab3432b59c016e0edcee9a2de8e303e83b73655e49d7b75a71c08deff8dc22ea917d2ebd9c6f30f667dc6aede63c3fce61bcbce30a10cc4e09c127
+  data.tar.gz: f7b0709e856f0f4e6eceaf21e7117bb59095fd6eebba267559fe0651468932b20e3d926feab4509145e4053ede86a41b70fcdc45deca176f2cb84dbfba9b0f84

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+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,205 @@
+# ask-tools
+
+The foundational gem for the ask-rb ecosystem. Defines `Ask::Tool` — the base class every tool inherits from — along with `Ask::Result` (standardized return value), tool discovery/registration, and a scaffold generator. **Zero external dependencies.**
+
+This gem does **not** ship any executable tools. It only provides the contract that tool gems (e.g., `ask-tools-shell`, `ask-tools-filesystem`) implement.
+
+## Installation
+
+Add this line to your `Gemfile`:
+
+```ruby
+gem "ask-tools"
+```
+
+Or install it directly:
+
+```bash
+gem install ask-tools
+```
+
+## Quick Start
+
+```ruby
+require "ask-tools"
+
+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
+
+# Use it
+tool = Greeter.new
+tool.name          # => "greeter"
+tool.description   # => "Greets a person by name"
+
+result = tool.call(name: "World")
+result.ok?         # => true
+result.output      # => "Hello, World!"
+```
+
+## API Reference
+
+### `Ask::Tool` — Base Class
+
+Subclass `Ask::Tool` to define a tool that an LLM can call.
+
+#### Class DSL
+
+| Method | Description |
+|--------|-------------|
+| `description(text)` | Sets or retrieves the tool's human-readable description. Alias: `desc` |
+| `param(name, type:, desc:, required:)` | Declares a parameter. `type` must be a valid JSON Schema type (`:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`) |
+
+#### Instance Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `name` | `String` | Auto-derived from the class name: CamelCase → snake_case, strips `_tool` suffix |
+| `description` | `String?, nil` | The tool's description |
+| `parameters` | `Hash{Symbol => Parameter}` | Declared parameter definitions |
+| `call(args = {})` | `Ask::Result` | Normalizes args (symbolizes keys), validates required params, delegates to `execute`. Catches `Halt` and `StandardError` |
+| `execute(**args)` | `Ask::Result` | **Override this.** Implement the tool's logic. |
+| `params_schema` | `Hash?, nil` | JSON Schema hash for LLM function-calling APIs. Returns `nil` when no params declared |
+| `tool_definition` | `Hash` | Full tool definition hash with `:name`, `:description`, and `:input_schema` |
+
+#### Error Handling
+
+- **`Ask::Tool::Halt`** — Raise this inside `execute` to signal the conversation loop should stop after this tool's result. `call` returns an `Ask::Result` with `metadata[:halted] = true`.
+- **`StandardError`** — Any other exception raised in `execute` is caught by `call` and returned as an error `Ask::Result`.
+
+### `Ask::Result` — Return Value
+
+A value object representing the outcome of a tool execution.
+
+#### Factory Methods
+
+```ruby
+# Successful result
+Ask::Result.ok(data: "output", metadata: { key: "val" })
+
+# Failed result
+Ask::Result.error(message: "Something went wrong", metadata: { code: 500 })
+```
+
+#### Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `ok?` / `ok` | `Boolean` | Whether the tool completed successfully |
+| `output` | `Object?, nil` | Output data (success) |
+| `error` | `String?, nil` | Error message (failure) |
+| `metadata` | `Hash` | Arbitrary metadata |
+
+#### Instance Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `to_s` | `String` | Returns `output.to_s` for success, `error` for failure |
+| `to_h` | `Hash` | Serialized hash with `:ok`, `:output`, `:error`, `:metadata` |
+| `inspect` | `String` | Human-readable representation |
+
+### `Ask::Tool::Parameter` — Parameter Definition
+
+Internal value object describing a declared parameter. Accessible via `Tool.parameters[name]`.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | `Symbol` | Parameter name |
+| `type` | `String` | JSON Schema type string |
+| `description` | `String?, nil` | Human-readable description |
+| `required` / `required?` | `Boolean` | Whether the parameter is mandatory |
+
+### `Ask::Tools` — Registry & Discovery
+
+Central registry for tool classes.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.register(tool_class)` | `void` | Manually register a tool class |
+| `.all` | `Array<Tool>` | Instantiated list of all registered tools |
+| `.discover` | `Array<Class>` | Auto-discover loaded `Ask::Tool` subclasses via `ObjectSpace` |
+| `.[](name)` | `Tool?, nil` | Find a registered tool by its derived name |
+| `.clear` | `void` | Remove all registered tools |
+| `.count` | `Integer` | Number of registered tool classes |
+
+```ruby
+# Manual registration
+Ask::Tools.register(MyTool)
+
+# Auto-discover all loaded Ask::Tool subclasses
+Ask::Tools.discover
+
+# Find by name
+tool = Ask::Tools["my_tool"]
+tool.call(input: "hello")
+
+# List all
+Ask::Tools.all.each { |t| puts t.name }
+```
+
+## Defining a Custom Tool
+
+```ruby
+class SearchTool < Ask::Tool
+  description "Searches a knowledge base"
+  param :query, type: :string, desc: "Search query", required: true
+  param :limit, type: :integer, desc: "Max results", required: false
+
+  def execute(query:, limit: 10)
+    results = perform_search(query, limit)
+    Ask::Result.ok(data: results)
+  rescue SearchError => e
+    Ask::Result.error(message: e.message)
+  end
+
+  private
+
+  def perform_search(query, limit)
+    # ... implementation
+  end
+end
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake test
+
+# Build the gem
+gem build ask-tools.gemspec
+```
+
+## Testing
+
+ask-tools uses **Minitest** with **Mocha** for mocking.
+
+```bash
+# Run the full test suite
+bundle exec rake test
+```
+
+## Release Process
+
+1. Update `CHANGELOG.md`
+2. Update `lib/ask/version.rb` if needed
+3. Build the gem: `gem build ask-tools.gemspec`
+4. Push to GitHub Packages: `gem push ask-tools-*.gem`
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- **Source:** https://github.com/ask-rb/ask-tools
+- **Issues:** https://github.com/ask-rb/ask-tools/issues
+- **Docs:** https://github.com/ask-rb/ask-docs

data/lib/ask/tools/result.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ask
+  # Standardized return value for tool execution.
+  #
+  # Every tool's #execute method should return an Ask::Result.
+  # Use the factory methods +.ok+ and +.error+ for common cases.
+  #
+  #   Ask::Result.ok(data: "hello world")
+  #   Ask::Result.error(message: "something went wrong")
+  #
+  class Result
+    # @return [Boolean] whether the tool completed successfully
+    attr_reader :ok
+
+    # @return [Object, nil] the output data when the tool succeeded
+    attr_reader :output
+
+    # @return [String, nil] the error message when the tool failed
+    attr_reader :error
+
+    # @return [Hash] arbitrary metadata attached to the result
+    attr_reader :metadata
+
+    alias ok? ok
+
+    def initialize(ok:, output: nil, error: nil, metadata: {})
+      @ok = ok
+      @output = output
+      @error = error
+      @metadata = metadata
+    end
+
+    # Create a successful result.
+    #
+    # @param data [Object] the tool's output
+    # @param metadata [Hash] optional metadata
+    # @return [Ask::Result]
+    def self.ok(data:, metadata: {})
+      new(ok: true, output: data, error: nil, metadata: metadata)
+    end
+
+    # Create a failed result.
+    #
+    # @param message [String] description of the failure
+    # @param metadata [Hash] optional metadata
+    # @return [Ask::Result]
+    def self.error(message:, metadata: {})
+      new(ok: false, output: nil, error: message, metadata: metadata)
+    end
+
+    # Human-readable representation.
+    # Returns the output for success or the error message for failure.
+    #
+    # @return [String]
+    def to_s
+      ok? ? output.to_s : error.to_s
+    end
+
+    # Hash representation suitable for serialization.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        ok: ok,
+        output: output,
+        error: error,
+        metadata: metadata
+      }
+    end
+
+    # @return [String] inspect string
+    def inspect
+      if ok?
+        "#<Ask::Result ok=true output=#{output.inspect}>"
+      else
+        "#<Ask::Result ok=false error=#{error.inspect}>"
+      end
+    end
+  end
+end

data/lib/ask/tools/tool.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+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)
+      end
+    end
+
+    class << self
+      # @api private
+      def inherited(subclass)
+        super
+        @parameters = {} if @parameters.nil?
+        subclass.instance_variable_set(:@description, nil)
+        subclass.instance_variable_set(:@parameters, {})
+      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
+        )
+      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 provider_params
+        @provider_params ||= {}
+      end
+    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
+      normalized = klass_name.dup.force_encoding("UTF-8").unicode_normalize(:nfkd)
+      normalized.encode("ASCII", replace: "")
+                .gsub(/[^a-zA-Z0-9_-]/, "-")
+                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .downcase
+                .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
+
+      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}")
+    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
+        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
+          }
+        end
+      end
+    end
+
+    # Full tool definition hash for LLM API calls.
+    #
+    # @return [Hash]
+    def tool_definition
+      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 normalize_args(args)
+      return {} if args.nil?
+
+      args.respond_to?(:transform_keys) ? args.transform_keys(&:to_sym) : {}
+    end
+
+    def validate(normalized)
+      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
+
+      alias required? required
+
+      def initialize(name:, type:, description: nil, required: true)
+        @name = name
+        @type = type
+        @description = description
+        @required = required
+      end
+
+      # @return [Hash]
+      def to_h
+        {
+          name: name,
+          type: type,
+          description: description,
+          required: required
+        }
+      end
+    end
+  end
+end

data/lib/ask/tools.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Ask
+  # Tool registry and discovery.
+  #
+  # Provides a central registry for tool classes and auto-discovery
+  # of Ask::Tool subclasses via ObjectSpace. Thread-safe.
+  #
+  #   Ask::Tools.register(MyTool)
+  #   Ask::Tools.all        # => [MyTool.new, ...]
+  #   Ask::Tools["my_tool"] # => instance of MyTool
+  #   Ask::Tools.discover   # auto-register all loaded Ask::Tool subclasses
+  #
+  module Tools
+    class << self
+      # Register a tool class manually.
+      #
+      # @param tool_class [Class < Ask::Tool]
+      # @return [void]
+      def register(tool_class)
+        monitor.synchronize { registry[tool_class.name] = tool_class }
+      end
+
+      # Return an array of instantiated registered tools.
+      #
+      # @return [Array<Ask::Tool>]
+      def all
+        monitor.synchronize { registry.values.map(&:new) }
+      end
+
+      # Auto-discover loaded +Ask::Tool+ subclasses via +ObjectSpace+
+      # and register any that aren't already registered.
+      #
+      # @return [Array<Class>] the newly discovered classes
+      def discover
+        monitor.synchronize do
+          discovered = ObjectSpace.each_object(Class).select do |klass|
+            klass < Ask::Tool && !registry.value?(klass) && klass.name
+          end
+          discovered.each { |klass| register(klass) }
+          discovered
+        end
+      end
+
+      # Find a registered tool by its derived name.
+      #
+      # @param name [String, Symbol] the tool name to look up
+      # @return [Ask::Tool, nil] an instance of the matching tool, or nil
+      def [](name)
+        name_str = name.to_s
+        monitor.synchronize do
+          registry.each_value do |klass|
+            instance = klass.new
+            return instance if instance.name == name_str
+          end
+          nil
+        end
+      end
+
+      # Remove all registered tools.
+      #
+      # @return [void]
+      def clear
+        monitor.synchronize { registry.clear }
+      end
+
+      # Number of registered tool classes.
+      #
+      # @return [Integer]
+      def count
+        monitor.synchronize { registry.size }
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+
+      def monitor
+        @monitor ||= Monitor.new
+      end
+    end
+  end
+end

data/lib/ask/version.rb

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

data/lib/ask-tools.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "ask/version"
+require_relative "ask/tools"
+require_relative "ask/tools/result"
+require_relative "ask/tools/tool"
+
+module Ask
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: ask-tools
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !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: Defines Ask::Tool (base class), Ask::Result, and tool discovery. Zero
+  dependencies.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask-tools.rb
+- lib/ask/tools.rb
+- lib/ask/tools/result.rb
+- lib/ask/tools/tool.rb
+- lib/ask/version.rb
+homepage: https://github.com/ask-rb/ask-tools
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Tool framework for the ask-rb ecosystem
+test_files: []