riffer 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ace7d52275897dc91ce42de1acc67db3de289c55953a56fa833a0f92f9c48c7c
-  data.tar.gz: ddee9798fb18502bd0e0e14e61d899a3cb24b240a6e6f9ab95b00199f03f7b59
+  metadata.gz: 7aa794200e1e9eef7fff84170952900baa69535798e7bed5b67990a886edc587
+  data.tar.gz: 0cad248bb54b1814b184f4727900f22955cc62abf0b76789ef4099824d05d4c3
 SHA512:
-  metadata.gz: 6c32731c0ac374bcc90fddd3c1cf071e3e2a1a2e2ae197ffcf98aace5acc4402c38d24657b2d3c211dfbf8d951a48ab9e94087a4b3accb2e763eb6202fa07312
-  data.tar.gz: da8b8ba45b0a5e08e4f2c7b212ddba5761fd2673d1c89fea695b1cb2d60e9ba1f7a01d9138f0eed33b406a7c7e116eb219e1f7a4919a7a4183cfe2dc97f59622
+  metadata.gz: 3dceae48df77f99164eeabd11b9f29e95a980d7efbc2472ee5192512e46467dd6b17f4b2dbf3869eeb9b4a45cee18996fda7bbd6b88813e0563ee22484931ea9
+  data.tar.gz: 9ca7a462a2cdcefa0d5576b1004f5f7d70160c4ac977d4343e81c64eb61621f667f478a2bb9807ad1d348d79dde8238dbadb4f26d69cc52549538a8102ff78a0

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.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/tool.rb

@@ -98,22 +98,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.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.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