raix 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08737974243ed41d4db2406405a4d081e31972cf173cfc3b2859cb97eabf0848'
-  data.tar.gz: 0d78927f5a35fad586f300bff4d86ce773d7bb7cd9f6787320e1cff6297f1aed
+  metadata.gz: 04e086a8f8f010507fef64ba8f2a1fa7c4508b34d85b39d8d045088410ba041c
+  data.tar.gz: b6ddc5948d4d71a967321cfe664a6fb2ad6f38833c7067e0915216ce7fc64646
 SHA512:
-  metadata.gz: c0eec6ef99a37cd8ba69dfec62c8be70c9a8f6ed0be78b24ed184bde364c78f5189ccac71e3196f56af4c85390844b044c30be1b69172fe4e0f3c584903ea7c0
-  data.tar.gz: 90f084213b11dd737b55ed89fd21e75cf23b4c0ef5ab0daca8652f974b9fdb0f40a68ee07ea2abcd0b6af715ae3edc684643034b7e7e3455f7d05fae9ee1e473
+  metadata.gz: 1558de827080ea2fb1c0ab0a953ae4d4cb1a9f8ad1aaae0690942f78bfde31275739857948b064721aa83b0f9b963c91c4bcb8dc5be460283e88ee2294e10e64
+  data.tar.gz: 001c63730739473375f0bff5c7e4edb78e4247000825799cff5cd98f9ae56bf6f2a5c436f1334b03e05de3257ef081498e2c456567a70e65417c19b70ab8918b

data/CHANGELOG.md

@@ -1,4 +1,11 @@
-## [0.8.0] - 2024-05-08
+## [0.8.2] - 2025-04-29
+- Extracts function call dispatch into a public `dispatch_tool_function` that can be overridden in subclasses
+- Uses `public_send` instead of `send` for better security and explicitness
+
+## [0.8.1] - 2025-04-24
+Added ability to filter tool functions (or disable completely) when calling `chat_completion`. Thanks to @parruda for the contribution.
+
+## [0.8.0] - 2025-04-23
 ### Added
 * **MCP integration (Experimental)** — new `Raix::MCP` concern and `mcp` DSL for declaring remote MCP servers.
   * Automatically fetches `tools/list`, registers remote tools as OpenAI‑compatible function schemas, and defines proxy methods that forward `tools/call`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    raix (0.8.0)
+    raix (0.8.2)
       activesupport (>= 6.0)
       faraday-retry (~> 2.0)
       open_router (~> 0.2)

data/README.md

@@ -134,6 +134,41 @@ end
 
 Note that for security reasons, dispatching functions only works with functions implemented using `Raix::FunctionDispatch#function` or directly on the class.
 
+#### Tool Filtering
+
+You can control which tools are available to the AI on a given chat completion request using the `tools` parameter in the `chat_completion` method:
+
+```ruby
+class WeatherAndTime
+  include Raix::ChatCompletion
+  include Raix::FunctionDispatch
+
+  function :check_weather, "Check the weather for a location", location: { type: "string" } do |arguments|
+    "The weather in #{arguments[:location]} is sunny"
+  end
+
+  function :get_time, "Get the current time" do |_arguments|
+    "The time is 12:00 PM"
+  end
+end
+
+weather = WeatherAndTime.new
+
+# Don't pass any tools to the LLM
+weather.chat_completion(tools: false)
+
+# Only pass specific tools to the LLM
+weather.chat_completion(tools: [:check_weather])
+
+# Pass all declared tools (default behavior)
+weather.chat_completion
+```
+
+The `tools` parameter accepts three types of values:
+- `false`: No tools are passed to the LLM
+- An array of symbols: Only the specified tools are passed (raises `Raix::UndeclaredToolError` if any tool is not declared)
+- Not provided: All declared tools are passed (default behavior)
+
 #### Multiple Tool Calls
 
 Some AI models (like GPT-4) can make multiple tool calls in a single response. When this happens, Raix will automatically handle all the function calls sequentially.
@@ -171,6 +206,28 @@ example.invocations
 # => [:first, :second]
 ```
 
+#### Customizing Function Dispatch
+
+You can customize how function calls are handled by overriding the `dispatch_tool_function` in your class. This is useful if you need to add logging, caching, error handling, or other custom behavior around function calls.
+
+```ruby
+class CustomDispatchExample
+  include Raix::ChatCompletion
+  include Raix::FunctionDispatch
+
+  function :example_tool do |arguments|
+    "Result from example tool"
+  end
+
+  def dispatch_tool_function(function_name, arguments)
+    puts "Calling #{function_name} with #{arguments}"
+    result = super
+    puts "Result: #{result}"
+    result
+  end
+end
+```
+
 #### Manually Stopping a Loop
 
 To loop AI components that don't interact with end users, at least one function block should invoke `stop_looping!` whenever you're ready to stop processing.

data/lib/raix/chat_completion.rb

@@ -9,6 +9,8 @@ require "openai"
 require_relative "message_adapters/base"
 
 module Raix
+  class UndeclaredToolError < StandardError; end
+
   # The `ChatCompletion`` module is a Rails concern that provides a way to interact
   # with the OpenRouter Chat Completion API via its client. The module includes a few
   # methods that allow you to build a transcript of messages and then send them to
@@ -44,8 +46,9 @@ module Raix
     # @option params [Boolean] :openai (false) Whether to use OpenAI's API instead of OpenRouter's.
     # @option params [Boolean] :raw (false) Whether to return the raw response or dig the text content.
     # @option params [Array] :messages (nil) An array of messages to use instead of the transcript.
+    # @option tools [Array|false] :tools (nil) Tools to pass to the LLM. If false, no tools are passed. If an array, only declared tools in the array are passed.
     # @return [String|Hash] The completed chat response.
-    def chat_completion(params: {}, loop: false, json: false, raw: false, openai: false, save_response: true, messages: nil)
+    def chat_completion(params: {}, loop: false, json: false, raw: false, openai: false, save_response: true, messages: nil, tools: nil)
       # set params to default values if not provided
       params[:cache_at] ||= cache_at.presence
       params[:frequency_penalty] ||= frequency_penalty.presence
@@ -63,7 +66,13 @@ module Raix
       params[:stop] ||= stop.presence
       params[:temperature] ||= temperature.presence || Raix.configuration.temperature
       params[:tool_choice] ||= tool_choice.presence
-      params[:tools] ||= tools.presence
+      params[:tools] = if tools == false
+                         nil
+                       elsif tools.is_a?(Array)
+                         filtered_tools(tools)
+                       else
+                         self.tools.presence
+                       end
       params[:top_a] ||= top_a.presence
       params[:top_k] ||= top_k.presence
       params[:top_logprobs] ||= top_logprobs.presence
@@ -123,7 +132,7 @@ module Raix
             function_name = tool_call["function"]["name"]
             raise "Unauthorized function call: #{function_name}" unless self.class.functions.map { |f| f[:name].to_sym }.include?(function_name.to_sym)
 
-            send(function_name, arguments.with_indifferent_access)
+            dispatch_tool_function(function_name, arguments.with_indifferent_access)
           end
         end
 
@@ -180,8 +189,30 @@ module Raix
       @transcript ||= []
     end
 
+    # Dispatches a tool function call with the given function name and arguments.
+    # This method can be overridden in subclasses to customize how function calls are handled.
+    #
+    # @param function_name [String] The name of the function to call
+    # @param arguments [Hash] The arguments to pass to the function
+    # @return [Object] The result of the function call
+    def dispatch_tool_function(function_name, arguments)
+      public_send(function_name, arguments)
+    end
+
     private
 
+    def filtered_tools(tool_names)
+      return nil if tool_names.blank?
+
+      requested_tools = tool_names.map(&:to_sym)
+      available_tool_names = tools.map { |tool| tool.dig(:function, :name).to_sym }
+
+      undeclared_tools = requested_tools - available_tool_names
+      raise UndeclaredToolError, "Undeclared tools: #{undeclared_tools.join(", ")}" if undeclared_tools.any?
+
+      tools.select { |tool| requested_tools.include?(tool.dig(:function, :name).to_sym) }
+    end
+
     def openai_request(params:, model:, messages:)
       if params[:prediction]
         params.delete(:max_completion_tokens)

data/lib/raix/function_dispatch.rb

@@ -94,10 +94,7 @@ module Raix
     end
 
     def chat_completion(**chat_completion_args)
-      raise "No functions defined" if self.class.functions.blank?
-
       self.chat_completion_args = chat_completion_args
-
       super
     end
 
@@ -109,6 +106,8 @@ module Raix
     end
 
     def tools
+      return [] unless self.class.functions
+
       self.class.functions.map { |function| { type: "function", function: } }
     end
   end

data/lib/raix/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Obie Fernandez
 bindir: exe
 cert_chain: []
-date: 2025-04-23 00:00:00.000000000 Z
+date: 2025-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport