riffer 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ace7d52275897dc91ce42de1acc67db3de289c55953a56fa833a0f92f9c48c7c
-  data.tar.gz: ddee9798fb18502bd0e0e14e61d899a3cb24b240a6e6f9ab95b00199f03f7b59
+  metadata.gz: d44459cec1b14508aac77178786e7230640ad1d455ced72ebda4ff02166283e4
+  data.tar.gz: 58a86d78ac5025d17245596e5ab0680d740fc0345cc3d51f2e68a65c5f3b8641
 SHA512:
-  metadata.gz: 6c32731c0ac374bcc90fddd3c1cf071e3e2a1a2e2ae197ffcf98aace5acc4402c38d24657b2d3c211dfbf8d951a48ab9e94087a4b3accb2e763eb6202fa07312
-  data.tar.gz: da8b8ba45b0a5e08e4f2c7b212ddba5761fd2673d1c89fea695b1cb2d60e9ba1f7a01d9138f0eed33b406a7c7e116eb219e1f7a4919a7a4183cfe2dc97f59622
+  metadata.gz: 9f8816ae7deb524c786afd74096f55bad54102c32d246f706f7bf15ed1c47cb7cd4f2ccb30c05af833b80e4898049febf5df45c98b8085c7b15c0ed71f425c98
+  data.tar.gz: 4c2627096ae1181b34d710d744ff339a61ebde623c30c6ea1e000ddac82bf9b374c7eb0d23364f7821856b407466332cc26fedca6288e93b23f9785515d220e7

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.0"
+  ".": "0.10.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0](https://github.com/janeapp/riffer/compare/riffer/v0.9.0...riffer/v0.10.0) (2026-01-30)
+
+
+### Features
+
+* update class name conversion to support configurable namespace separators ([#96](https://github.com/janeapp/riffer/issues/96)) ([e7091e9](https://github.com/janeapp/riffer/commit/e7091e95210c2df27138e61e64032d52ecf174e1))
+
+
+### Bug Fixes
+
+* handle multiple tools correctly for bedrock ([#95](https://github.com/janeapp/riffer/issues/95)) ([50ae6f6](https://github.com/janeapp/riffer/commit/50ae6f6cd803d5e95b79cb6ceafca5b2d9b4a52c))
+* update class name conversion to use double underscore format ([#93](https://github.com/janeapp/riffer/issues/93)) ([f6ffad7](https://github.com/janeapp/riffer/commit/f6ffad775a2d8254543dd7819dca93c15f514742))
+
+## [0.9.0](https://github.com/janeapp/riffer/compare/riffer/v0.8.0...riffer/v0.9.0) (2026-01-28)
+
+
+### Features
+
+* implement Riffer::Tools::Response for consistent tool result handling ([#91](https://github.com/janeapp/riffer/issues/91)) ([df44f1f](https://github.com/janeapp/riffer/commit/df44f1fe8ff0b5bea73a2df8d6c0b8359e6c47f3))
+
 ## [0.8.0](https://github.com/janeapp/riffer/compare/riffer/v0.7.0...riffer/v0.8.0) (2026-01-26)
 
 

data/docs/04_TOOLS.md

@@ -17,7 +17,7 @@ class WeatherTool < Riffer::Tool
 
   def call(context:, city:, units: nil)
     weather = WeatherAPI.fetch(city, units: units || "celsius")
-    "The weather in #{city} is #{weather.temperature} #{units}."
+    text("The weather in #{city} is #{weather.temperature} #{units}.")
   end
 end
 ```
@@ -110,12 +110,14 @@ Options:
 
 ## The call Method
 
-Every tool must implement the `call` method:
+Every tool must implement the `call` method and return a `Riffer::Tools::Response`:
 
 ```ruby
 def call(context:, **kwargs)
   # context - The tool_context passed to agent.generate()
   # kwargs  - Validated parameters
+  #
+  # Must return a Riffer::Tools::Response
 end
 ```
 
@@ -129,10 +131,12 @@ class UserOrdersTool < Riffer::Tool
 
   def call(context:)
     user_id = context&.dig(:user_id)
-    return "No user ID provided" unless user_id
+    unless user_id
+      return error("No user ID provided")
+    end
 
     orders = Order.where(user_id: user_id)
-    orders.map(&:to_s).join("\n")
+    text(orders.map(&:to_s).join("\n"))
   end
 end
 
@@ -140,22 +144,104 @@ end
 agent.generate("Show my orders", tool_context: {user_id: 123})
 ```
 
-### Return Values
+## Response Objects
+
+All tools must return a `Riffer::Tools::Response` object from their `call` method. Riffer::Tool provides shorthand methods for creating responses.
+
+### Success Responses
 
-Return a string that will be sent back to the LLM:
+Use `text` for string responses and `json` for structured data:
 
 ```ruby
 def call(context:, query:)
   results = Database.search(query)
 
   if results.empty?
-    "No results found for '#{query}'"
+    text("No results found for '#{query}'")
   else
-    results.map { |r| "- #{r.title}: #{r.summary}" }.join("\n")
+    text(results.map { |r| "- #{r.title}: #{r.summary}" }.join("\n"))
   end
 end
 ```
 
+#### text
+
+Converts the result to a string via `to_s`:
+
+```ruby
+text("Hello, world!")
+# => content: "Hello, world!"
+
+text(42)
+# => content: "42"
+```
+
+#### json
+
+Converts the result to JSON via `to_json`:
+
+```ruby
+json({name: "Alice", age: 30})
+# => content: '{"name":"Alice","age":30}'
+
+json([1, 2, 3])
+# => content: '[1,2,3]'
+```
+
+### Error Responses
+
+Use `error(message, type:)` for errors:
+
+```ruby
+def call(context:, user_id:)
+  user = User.find_by(id: user_id)
+
+  unless user
+    return error("User not found", type: :not_found)
+  end
+
+  text("User: #{user.name}")
+end
+```
+
+The error type is any symbol that describes the error category:
+
+```ruby
+error("Invalid input", type: :validation_error)
+error("Service unavailable", type: :service_error)
+error("Rate limit exceeded", type: :rate_limit)
+```
+
+If no type is specified, it defaults to `:execution_error`.
+
+### Using Riffer::Tools::Response Directly
+
+The shorthand methods delegate to `Riffer::Tools::Response`. You can also use the class directly if preferred:
+
+```ruby
+Riffer::Tools::Response.text("Hello")
+Riffer::Tools::Response.json({data: [1, 2, 3]})
+Riffer::Tools::Response.error("Failed", type: :custom_error)
+```
+
+### Response Methods
+
+```ruby
+response = text("result")
+response.content        # => "result"
+response.success?       # => true
+response.error?         # => false
+response.error_message  # => nil
+response.error_type     # => nil
+
+error_response = error("failed", type: :not_found)
+error_response.content        # => "failed"
+error_response.success?       # => false
+error_response.error?         # => true
+error_response.error_message  # => "failed"
+error_response.error_type     # => :not_found
+```
+
 ## Timeout Configuration
 
 Configure timeouts to prevent tools from running indefinitely. The default timeout is 10 seconds.
@@ -166,7 +252,8 @@ class SlowExternalApiTool < Riffer::Tool
   timeout 30  # 30 seconds
 
   def call(context:, query:)
-    ExternalAPI.search(query)
+    result = ExternalAPI.search(query)
+    text(result)
   end
 end
 ```
@@ -181,7 +268,7 @@ Arguments are automatically validated before `call` is invoked:
 - Types must match the schema
 - Enum values must be in the allowed list
 
-Validation errors are captured and sent back to the LLM as tool results.
+Validation errors are captured and sent back to the LLM as tool results with error type `:validation_error`.
 
 ## JSON Schema Generation
 
@@ -237,15 +324,19 @@ end
 
 ## Error Handling
 
-Errors in tools are captured and reported back to the LLM:
+Errors can be returned explicitly using `error`:
 
 ```ruby
 def call(context:, query:)
-  raise "API rate limit exceeded"
+  results = ExternalAPI.search(query)
+  json(results)
+rescue RateLimitError => e
+  error("API rate limit exceeded, please try again later", type: :rate_limit)
 rescue => e
-  # Error is caught by Riffer and sent as tool result:
-  # "Error executing tool: API rate limit exceeded"
+  error("Search failed: #{e.message}")
 end
 ```
 
-The LLM can then decide how to respond (retry, apologize, ask for different input, etc.).
+Unhandled exceptions are caught by Riffer and converted to error responses with type `:execution_error`. However, it's recommended to handle expected errors explicitly for better error messages.
+
+The LLM receives the error message and can decide how to respond (retry, apologize, ask for different input, etc.).

data/lib/riffer/agent.rb

@@ -266,11 +266,11 @@ class Riffer::Agent
     response.tool_calls.each do |tool_call|
       result = execute_tool_call(tool_call)
       add_message(Riffer::Messages::Tool.new(
-        result[:content],
+        result.content,
         tool_call_id: tool_call[:id],
         name: tool_call[:name],
-        error: result[:error],
-        error_type: result[:error_type]
+        error: result.error_message,
+        error_type: result.error_type
       ))
     end
   end
@@ -279,37 +279,23 @@ class Riffer::Agent
     tool_class = find_tool_class(tool_call[:name])
 
     if tool_class.nil?
-      return {
-        content: "Error: Unknown tool '#{tool_call[:name]}'",
-        error: "Unknown tool '#{tool_call[:name]}'",
-        error_type: :unknown_tool
-      }
+      return Riffer::Tools::Response.error(
+        "Unknown tool '#{tool_call[:name]}'",
+        type: :unknown_tool
+      )
     end
 
     tool_instance = tool_class.new
     arguments = parse_tool_arguments(tool_call[:arguments])
 
     begin
-      result = tool_instance.call_with_validation(context: @tool_context, **arguments)
-      {content: result.to_s, error: nil, error_type: nil}
+      tool_instance.call_with_validation(context: @tool_context, **arguments)
     rescue Riffer::TimeoutError => e
-      {
-        content: "Error: #{e.message}",
-        error: e.message,
-        error_type: :timeout_error
-      }
+      Riffer::Tools::Response.error(e.message, type: :timeout_error)
     rescue Riffer::ValidationError => e
-      {
-        content: "Validation error: #{e.message}",
-        error: e.message,
-        error_type: :validation_error
-      }
+      Riffer::Tools::Response.error(e.message, type: :validation_error)
     rescue => e
-      {
-        content: "Error executing tool: #{e.message}",
-        error: e.message,
-        error_type: :execution_error
-      }
+      Riffer::Tools::Response.error("Error executing tool: #{e.message}", type: :execution_error)
     end
   end
 

data/lib/riffer/helpers/class_name_converter.rb

@@ -2,15 +2,18 @@
 
 # Helper module for converting class names.
 module Riffer::Helpers::ClassNameConverter
-  # Converts a class name to snake_case path format.
+  DEFAULT_SEPARATOR = "/"
+
+  # Converts a class name to snake_case identifier format.
   #
   # class_name:: String - the class name (e.g., "Riffer::Agent")
+  # separator:: String - the separator to use for namespaces (default: "/")
   #
-  # Returns String - the snake_case path (e.g., "riffer/agent").
-  def class_name_to_path(class_name)
+  # Returns String - the snake_case identifier (e.g., "riffer/agent").
+  def class_name_to_path(class_name, separator: DEFAULT_SEPARATOR)
     class_name
       .to_s
-      .gsub("::", "/")
+      .gsub("::", separator)
       .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
       .gsub(/([a-z\d])([A-Z])/, '\1_\2')
       .downcase

data/lib/riffer/providers/amazon_bedrock.rb

@@ -137,15 +137,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       when Riffer::Messages::Assistant
         conversation_messages << convert_assistant_to_bedrock_format(message)
       when Riffer::Messages::Tool
-        conversation_messages << {
-          role: "user",
-          content: [{
-            tool_result: {
-              tool_use_id: message.tool_call_id,
-              content: [{text: message.content}]
-            }
-          }]
-        }
+        append_tool_result(conversation_messages, message)
       end
     end
 
@@ -155,6 +147,22 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     }
   end
 
+  def append_tool_result(conversation_messages, message)
+    tool_result = {
+      tool_result: {
+        tool_use_id: message.tool_call_id,
+        content: [{text: message.content}]
+      }
+    }
+
+    prev = conversation_messages.last
+    if prev && prev[:role] == "user" && prev[:content]&.first&.key?(:tool_result)
+      prev[:content] << tool_result
+    else
+      conversation_messages << {role: "user", content: [tool_result]}
+    end
+  end
+
   def convert_assistant_to_bedrock_format(message)
     content = []
     content << {text: message.content} if message.content && !message.content.empty?

data/lib/riffer/tool.rb

@@ -25,6 +25,9 @@ require "timeout"
 class Riffer::Tool
   DEFAULT_TIMEOUT = 10
 
+  # Some providers do not allow "/" in tool names, so we use "__" as separator.
+  TOOL_SEPARATOR = "__"
+
   class << self
     include Riffer::Helpers::ClassNameConverter
 
@@ -44,7 +47,7 @@ class Riffer::Tool
     #
     # Returns String - the tool identifier (defaults to snake_case class name).
     def identifier(value = nil)
-      return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self)) if value.nil?
+      return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self), separator: TOOL_SEPARATOR) if value.nil?
       @identifier = value.to_s
     end
 
@@ -98,22 +101,57 @@ class Riffer::Tool
     raise NotImplementedError, "#{self.class} must implement #call"
   end
 
+  # Creates a text response. Shorthand for Riffer::Tools::Response.text.
+  #
+  # result:: Object - the tool result (converted via to_s)
+  #
+  # Returns Riffer::Tools::Response.
+  def text(result)
+    Riffer::Tools::Response.text(result)
+  end
+
+  # Creates a JSON response. Shorthand for Riffer::Tools::Response.json.
+  #
+  # result:: Object - the tool result (converted via JSON.generate)
+  #
+  # Returns Riffer::Tools::Response.
+  def json(result)
+    Riffer::Tools::Response.json(result)
+  end
+
+  # Creates an error response. Shorthand for Riffer::Tools::Response.error.
+  #
+  # message:: String - the error message
+  # type:: Symbol - the error type (default: :execution_error)
+  #
+  # Returns Riffer::Tools::Response.
+  def error(message, type: :execution_error)
+    Riffer::Tools::Response.error(message, type: type)
+  end
+
   # Executes the tool with validation and timeout (used by Agent).
   #
   # context:: Object or nil - context passed from the agent
   # kwargs:: Hash - the tool arguments
   #
-  # Returns Object - the tool result.
+  # Returns Riffer::Tools::Response - the tool response.
   #
   # Raises Riffer::ValidationError if validation fails.
   # Raises Riffer::TimeoutError if execution exceeds the configured timeout.
+  # Raises Riffer::Error if the tool does not return a Response object.
   def call_with_validation(context:, **kwargs)
     params_builder = self.class.params
     validated_args = params_builder ? params_builder.validate(kwargs) : kwargs
 
-    Timeout.timeout(self.class.timeout) do
+    result = Timeout.timeout(self.class.timeout) do
       call(context: context, **validated_args)
     end
+
+    unless result.is_a?(Riffer::Tools::Response)
+      raise Riffer::Error, "#{self.class} must return a Riffer::Tools::Response from #call"
+    end
+
+    result
   rescue Timeout::Error
     raise Riffer::TimeoutError, "Tool execution timed out after #{self.class.timeout} seconds"
   end

data/lib/riffer/tools/response.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Riffer::Tools::Response represents the result of a tool execution.
+#
+# All tools must return a Response object from their +call+ method.
+# Use +Response.success+ for successful results and +Response.error+ for failures.
+#
+#   class MyTool < Riffer::Tool
+#     def call(context:, **kwargs)
+#       result = perform_operation
+#       Riffer::Tools::Response.success(result)
+#     rescue MyError => e
+#       Riffer::Tools::Response.error(e.message)
+#     end
+#   end
+#
+class Riffer::Tools::Response
+  VALID_FORMATS = %i[text json].freeze
+
+  attr_reader :content, :error_message, :error_type
+
+  # Creates a success response.
+  #
+  # result:: Object - the tool result
+  # format:: Symbol - the format (:text or :json; default: :text)
+  #
+  # Returns Riffer::Tools::Response.
+  #
+  # Raises Riffer::ArgumentError if format is invalid.
+  def self.success(result, format: :text)
+    unless VALID_FORMATS.include?(format)
+      raise Riffer::ArgumentError, "Invalid format: #{format}. Must be one of: #{VALID_FORMATS.join(", ")}"
+    end
+
+    content = (format == :json) ? result.to_json : result.to_s
+    new(content: content, success: true)
+  end
+
+  # Creates a success response with text format.
+  #
+  # result:: Object - the tool result (converted via to_s)
+  #
+  # Returns Riffer::Tools::Response.
+  def self.text(result)
+    success(result, format: :text)
+  end
+
+  # Creates a success response with JSON format.
+  #
+  # result:: Object - the tool result (converted via to_json)
+  #
+  # Returns Riffer::Tools::Response.
+  def self.json(result)
+    success(result, format: :json)
+  end
+
+  # Creates an error response.
+  #
+  # message:: String - the error message
+  # type:: Symbol - the error type (default: :execution_error)
+  #
+  # Returns Riffer::Tools::Response.
+  def self.error(message, type: :execution_error)
+    new(content: message, success: false, error_message: message, error_type: type)
+  end
+
+  # Returns true if the response is successful.
+  def success? = @success
+
+  # Returns true if the response is an error.
+  def error? = !@success
+
+  # Returns a hash representation of the response.
+  #
+  # Returns Hash with :content, :error, and :error_type keys.
+  def to_h
+    {content: @content, error: @error_message, error_type: @error_type}
+  end
+
+  private
+
+  def initialize(content:, success:, error_message: nil, error_type: nil)
+    @content = content
+    @success = success
+    @error_message = error_message
+    @error_type = error_type
+  end
+end

data/lib/riffer/tools.rb

@@ -3,7 +3,8 @@
 # Namespace for tool-related classes in the Riffer framework.
 #
 # Contains:
-# - Riffer::Tools::Params - DSL for defining tool parameters
 # - Riffer::Tools::Param - Individual parameter definition
+# - Riffer::Tools::Params - DSL for defining tool parameters
+# - Riffer::Tools::Response - Required return type for tool execution
 module Riffer::Tools
 end

data/lib/riffer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Riffer
-  VERSION = "0.8.0"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -214,6 +214,7 @@ files:
 - lib/riffer/tools.rb
 - lib/riffer/tools/param.rb
 - lib/riffer/tools/params.rb
+- lib/riffer/tools/response.rb
 - lib/riffer/version.rb
 - sig/riffer.rbs
 homepage: https://riffer.ai