ask-tools 0.2.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10504b125a562dba192ed5c432608b54e3140ea5f38822e5e045a1f8546f7609
-  data.tar.gz: afd13e8a2a242e095ac71bc7c9f02cac14931e3966664dd6e3a88995869f6840
+  metadata.gz: 549044a60c0528c6cd72c66bdcada359b56e106a169237d17661841f751a090f
+  data.tar.gz: e315d06d73942a45c0cf0835069e403f221d89322ed2f456ea1ac7879db21ab8
 SHA512:
-  metadata.gz: 1bdeed01d810365cb450ec8548ee6815718e51df479de5f8ef9ea6105cfd97ce31e872eaec98b93e4be36ac67368dcaf726b96b343fa7d393d42dcb73cb5c9cd
-  data.tar.gz: b9ed6b94f72cd3ec96a18faac67ae85e9f4593859069f216632d8a8f78111b432680ca8bbc19f736f4ed5c0976b913d9b2afdeb6ec2ed46e88516e859db9b57e
+  metadata.gz: 4145513e16e503594071295d6e244ce6afad3fa55b83dbe33d88620226e0f4e152ec8837560fb85d89a5c992e19ce345fcc93775396af7e9471517cbc3c9ca91
+  data.tar.gz: 19a7e533b4d2614ff2842cbcac201393c79bc7d4fafe63e1b3c72592b63bddc887f6d517b726aabad51bbc19d916df4b06d688dd9818172c5f0ba40c4c525443

data/CHANGELOG.md

@@ -1,3 +1,85 @@
+## [0.5.0] — 2026-08-03
+
+### Changed
+
+- **`Ask::Result` now comes from ask-core.** The duplicated `Ask::Result`
+  definition in this gem is removed; ask-tools depends on ask-core
+  (>= 0.9.0), which owns the single result type for the whole ecosystem with
+  both the foundational API (`success`/`failure`/`aborted`/`blocked`) and the
+  tool API (`ok`/`error`/`output`/`ok?`/`error_message`). Previously the two
+  gems' incompatible constructors meant whichever loaded last broke the
+  other's factories (`Ask::Result.success` raised `ArgumentError` in any app
+  loading both).
+
+  The tool API is unchanged:
+
+  ```ruby
+  Ask::Result.ok(data: "hello").output    # => "hello"
+  Ask::Result.error(message: "fail").error  # => "fail"
+  ```
+
+### Tested
+
+- 71 tests, 159 assertions, 0 failures.
+
+## [0.4.0] — 2026-07-26
+
+### Added
+
+- **`name` class DSL for custom tool names** — tools can now declare a
+  custom name with `name "my_tool"` at the class level instead of
+  overriding `def name`. The class method safely shadows `Module#name`
+  by detecting arguments: `ClassName.name` returns the Ruby class path,
+  `name "foo"` sets the tool name. Instance `#name` returns the custom
+  name if set, otherwise auto-derives from the class name.
+
+### Removed
+
+- **`Ask::Tools::SubAgent`** — removed in favor of `Ask::Agent::SubAgent`
+  in ask-agent v0.18.0. Sub-agent delegation now lives in the agent
+  runtime where it can automatically build sessions.
+
+## [0.3.0] — 2026-07-26
+
+### Added
+
+- **`Ask::Tools::SubAgent` — delegate tasks to a specialized sub-agent tool**.
+  An `Ask::Tool` subclass that wraps a runner callable. When the LLM calls it,
+  the sub-agent runs independently with its own model, tools, and instructions.
+
+  The tool supports per-instance `name:` and `description:` overrides so that
+  multiple sub-agents can coexist in the same tool list with distinct identities.
+
+  ```ruby
+  search = Ask::Tools::SubAgent.new(
+    name: "web_search",
+    description: "Search the web for current information",
+    runner: ->(task) {
+      Ask::Agent::Session.new(model: "gpt-4o-mini", tools: [Search])
+        .run(task).to_s
+    }
+  )
+  ```
+
+### Fixed
+
+- **Tool discovery no longer breaks on tools with required constructor args**.
+  `Ask::Tools::SubAgent` makes its `runner:` parameter optional so that tool
+  discovery (which instantiates via `klass.new`) works without error. An
+  unconfigured SubAgent returns a clear error message at call time.
+
+## [0.2.6] — 2026-07-18
+
+### Fixed
+
+- **`Tool#call` filters `_abort_controller` before passing to `execute`** — The internal `_abort_controller` key was being passed as a keyword argument to tool `execute` methods. Tools with explicit keyword arguments (e.g., `def execute(title:, extraction_scope:)`) crashed with `ArgumentError: unknown keyword` because they didn't accept `_abort_controller`. Now filtered before the `execute(**kwargs)` call.
+
+## [0.2.5] — 2026-07-18
+
+### Fixed
+
+- **`Tool#normalize_args` parses JSON string arguments from LLMs** — Tool call arguments arrive as JSON strings from the LLM, but `normalize_args` only handled Hash arguments. JSON strings were silently ignored, returning an empty args hash and causing "missing required parameters" errors. Now parses JSON strings before normalizing keys to symbols.
+
 ## [0.2.4] - 2026-06-25
 
 ### Changed

data/README.md

@@ -1,23 +1,15 @@
 # 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.
+[![Gem Version](https://badge.fury.io/rb/ask-tools.svg)](https://badge.fury.io/rb/ask-tools)
 
-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.
+The tool framework for the ask-rb ecosystem. Defines `Ask::Tool` (the base class every tool inherits from), `Ask::Result` (standardized return value), and the `Ask::Tools` registry. This gem ships no executable tools; tool gems such as ask-tools-shell implement them.
 
 ## Installation
 
-Add this line to your `Gemfile`:
-
 ```ruby
 gem "ask-tools"
 ```
 
-Or install it directly:
-
-```bash
-gem install ask-tools
-```
-
 ## Quick Start
 
 ```ruby
@@ -32,174 +24,60 @@ class Greeter < Ask::Tool
   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!"
+result = Greeter.new.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
+## Essential API
 
-- **`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::Tool
 
-### `Ask::Result` — Return Value
+| Method | Purpose |
+|---|---|
+| `description "..."` (alias `desc`) | Set the tool description |
+| `param :name, type: :string, desc: "...", required: true` | Declare a parameter. `type` must be a JSON Schema type (`:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`) |
+| `name "custom_tool"` | Set a custom tool name (default: derived from the class name, CamelCase to snake_case, `_tool` suffix stripped) |
+| `params do ... end` | Declare parameters with the ask-schema DSL |
 
-A value object representing the outcome of a tool execution.
+Override `execute(**args)` with the tool logic. `call(args)` normalizes input (JSON strings and hash keys), validates required parameters, and returns an `Ask::Result`. Raising `Ask::Tool::Halt` inside `execute` yields a success result with `metadata[:halted] = true`; any other exception becomes a failure result.
 
-#### Factory Methods
+### Ask::Result
 
 ```ruby
-# Successful result
 Ask::Result.ok(data: "output", metadata: { key: "val" })
-
-# Failed result
 Ask::Result.error(message: "Something went wrong", metadata: { code: 500 })
+Ask::Result.failure("Something went wrong")
+
+result.ok?       # => true
+result.output    # => "output"
+result.error     # => nil
+result.metadata  # => { key: "val" }
+result.to_s      # => "output"
+result.to_h      # => { ok: true, output: "output", error: nil, metadata: { key: "val" } }
 ```
 
-#### 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
+### Ask::Tools registry
 
-```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
+| Method | Purpose |
+|---|---|
+| `Ask::Tools.register(ToolClass)` | Register a tool class manually |
+| `Ask::Tools.all` | Instances of all registered tools |
+| `Ask::Tools.discover` | Auto-register loaded `Ask::Tool` subclasses via ObjectSpace |
+| `Ask::Tools["name"]` | Find a tool instance by derived name |
+| `Ask::Tools.clear` / `Ask::Tools.count` | Reset and count the registry |
 
-  private
+## Full documentation
 
-  def perform_search(query, limit)
-    # ... implementation
-  end
-end
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-tools in depth](https://ask-rb.github.io/ask-docs/core/tools) covers the tool contract, parameter schemas, and custom tool examples. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## 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 install
 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
+MIT

data/lib/ask/tools/tool.rb

@@ -20,6 +20,7 @@ module Ask
         subclass.instance_variable_set(:@description, nil)
         subclass.instance_variable_set(:@parameters, {})
         subclass.instance_variable_set(:@params_schema_definition, nil)
+        subclass.instance_variable_set(:@tool_name, nil)
       end
 
       def description(text = nil)
@@ -28,6 +29,18 @@ module Ask
       end
       alias desc description
 
+      # Declare a custom tool name.
+      # Called with no argument returns the class name (via Module#name).
+      # Called with a string stores a custom name for the instance.
+      # Example: name "my_custom_tool"
+      def name(custom = :_no_arg_given)
+        if custom == :_no_arg_given
+          super()  # Module#name, returns the Ruby class path
+        else
+          @tool_name = custom
+        end
+      end
+
       def param(name, type:, desc: nil, description: nil, required: true)
         type = type.to_s.downcase.to_sym
         validate_param_type!(type, name)
@@ -115,6 +128,9 @@ module Ask
     end
 
     def name
+      custom = self.class.instance_variable_get(:@tool_name)
+      return custom if custom
+
       klass_name = self.class.name.to_s.split("::").last || ""
       normalized = klass_name.dup.force_encoding("UTF-8").unicode_normalize(:nfkd)
       normalized.encode("ASCII", replace: "")

data/lib/ask/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Tools
-    VERSION = "0.2.6"
+    VERSION = "0.5.0"
   end
 end

data/lib/ask-tools.rb

@@ -2,7 +2,7 @@
 
 require_relative "ask/version"
 require_relative "ask/tools"
-require_relative "ask/tools/result"
+require "ask"  # ask-core: the shared Ask::Result lives here
 require_relative "ask/tools/tool"
 
 module Ask

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tools
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.5.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: ask-schema
   requirement: !ruby/object:Gem::Requirement
@@ -65,7 +79,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Defines Ask::Tool (base class), Ask::Result, and tool discovery.
+description: Defines Ask::Tool (base class), tool discovery, and the Ask::Result returned
+  by tools.
 email:
 - kaka@myrrlabs.com
 executables: []
@@ -77,7 +92,6 @@ files:
 - 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

data/lib/ask/tools/result.rb

@@ -1,98 +0,0 @@
-# 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
-
-    # @return [Boolean] whether the tool failed
-    def error?
-      !ok
-    end
-
-    # @return [String, nil] the error message (alias for +error+)
-    alias error_message error
-
-    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 (positional message form, used by Tool#call).
-    #
-    # @param message [String] description of the failure
-    # @param metadata [Hash] optional metadata
-    # @return [Ask::Result]
-    def self.failure(message, metadata: {})
-      new(ok: false, output: nil, error: message, 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