raix 0.9.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5464c46a401957877b024ec9a1140b6f2624add3f21c172253663988c74baa49
-  data.tar.gz: a556464db7a06866cf6ecd27530b7ddcbbc372fa8e4f96f7ba84f0c6467de3b1
+  metadata.gz: 56a4f5695ac0b5685715aa48e1bbb926efd05c5bd15b2f2198df3acda3ef30e4
+  data.tar.gz: e46d6284e3d4201fa6a8bc5b59403b41434d9e92ce131944d5d20d896925402f
 SHA512:
-  metadata.gz: c99d540f8f8c7c0c35a57628d322ff0eef31803c0bee7244476633bd092320bd7040ceebb4b20126b55529bfe0fb373fee01e4977871a3eedf1e135331e9b4e2
-  data.tar.gz: 53e124ebdf99b0b176fb0c30d15c40e9a3156e210686d705237aa43fc02e2ca0e71a63e5efd75deffaf1f5565a34837ccd6d7f1b1dd6f2cbf6b6d9d5c3f137d2
+  metadata.gz: 07224f3ff3b8ea20b01d77bd149f7aa3afc597c145db34cf65ecf188a4e2fb2f366729cd8b8c671783346ce743106a234bbf8e551b2243f5a5f8fb9f652ed28b
+  data.tar.gz: ed03422c1168de36a21729ed75281ff6dcfabead31232cefc22201fb670a18bae57877fc4e440aa8bffaf0705c1288511369f0e040757e92198e702922c407be

data/.rubocop.yml

@@ -1,7 +1,14 @@
 AllCops:
+  NewCops: enable
   SuggestExtensions: false
   TargetRubyVersion: 3.2.1
 
+Gemspec/RequireMFA:
+  Enabled: false
+
+Style/OpenStructUse:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [1.0.0] - 2025-06-04
+### Breaking Changes
+- **Deprecated `loop` parameter in ChatCompletion** - The system now automatically continues conversations after tool calls until the AI provides a text response. The `loop` parameter shows a deprecation warning but still works for backwards compatibility.
+- **Tool-based completions now return strings instead of arrays** - When functions are called, the final response is a string containing the AI's text response, not an array of function results.
+- **`stop_looping!` renamed to `stop_tool_calls_and_respond!`** - Better reflects the new automatic continuation behavior.
+
+### Added
+- **Automatic conversation continuation** - Chat completions automatically continue after tool execution without needing the `loop` parameter.
+- **`max_tool_calls` parameter** - Controls the maximum number of tool invocations to prevent infinite loops (default: 25).
+- **Configuration for `max_tool_calls`** - Added `max_tool_calls` to the Configuration class with sensible defaults.
+
+### Changed
+- ChatCompletion handles continuation after tool function calls automatically.
+- Improved CI/CD workflow to use `bundle exec rake ci` for consistent testing.
+
+### Fixed
+- Resolved conflict between `loop` attribute and Ruby's `Kernel.loop` method (fixes #11).
+- Fixed various RuboCop warnings using keyword argument forwarding.
+- Improved error handling with proper warning messages instead of puts.
+
 ## [0.9.2] - 2025-06-03
 ### Fixed
 - Fixed OpenAI chat completion compatibility

data/CLAUDE.md

@@ -0,0 +1,13 @@
+This is a Ruby gem called Raix. Its purpose is to facilitate chat completion style AI text generation using LLMs provided by OpenAI and OpenRouter.
+
+- When running all tests just do `bundle exec rake` since it automatically runs the linter with autocorrect
+- Documentation: Include method/class documentation with examples when appropriate
+- Add runtime dependencies to `raix.gemspec`.
+- Add development dependencies to `Gemfile`.
+- Don't ever test private methods directly. Specs should test behavior, not implementation.
+- Never add test-specific code embedded in production code
+- **Do not use require_relative**
+- Require statements should always be in alphabetical order
+- Always leave a blank line after module includes and before the rest of the class
+- Do not decide unilaterally to leave code for the sake of "backwards compatibility"... always run those decisions by me first.
+- Don't ever commit and push changes unless directly told to do so

data/README.llm

@@ -42,7 +42,7 @@ class WhatIsTheWeather
 end
 ```
 
-If the AI calls multiple functions at once, Raix handles them in sequence and returns an array of results. Call `stop_looping!` inside a function to end the loop.
+If the AI calls multiple functions at once, Raix handles them in sequence and returns an array of results. Call `stop_tool_calls_and_respond!` inside a function to end the loop.
 
 ## Prompt Declarations
 Include `Raix::PromptDeclarations` to define a chain of prompts in order. Each prompt can be inline text or a callable class that also includes `ChatCompletion`.

data/README.md

@@ -107,9 +107,15 @@ When using JSON mode with non-OpenAI providers, Raix automatically sets the `req
 
 ### Use of Tools/Functions
 
-The second (optional) module that you can add to your Ruby classes after `ChatCompletion` is `FunctionDispatch`. It lets you declare and implement functions to be called at the AI's discretion as part of a chat completion "loop" in a declarative, Rails-like "DSL" fashion.
+The second (optional) module that you can add to your Ruby classes after `ChatCompletion` is `FunctionDispatch`. It lets you declare and implement functions to be called at the AI's discretion in a declarative, Rails-like "DSL" fashion.
 
-Most end-user facing AI components that include functions should be invoked using `chat_completion(loop: true)`, so that the results of each function call are added to the transcript and chat completion is triggered again. The looping will continue until the AI generates a plain text response.
+When the AI responds with tool function calls instead of a text message, Raix automatically:
+1. Executes the requested tool functions
+2. Adds the function results to the conversation transcript  
+3. Sends the updated transcript back to the AI for another completion
+4. Repeats this process until the AI responds with a regular text message
+
+This automatic continuation ensures that tool calls are seamlessly integrated into the conversation flow. The AI can use tool results to formulate its final response to the user. You can limit the number of tool calls using the `max_tool_calls` parameter to prevent excessive function invocations.
 
 ```ruby
 class WhatIsTheWeather
@@ -126,9 +132,9 @@ end
 RSpec.describe WhatIsTheWeather do
   subject { described_class.new }
 
-  it "can call a function and loop to provide text response" do
+  it "provides a text response after automatically calling weather function" do
     subject.transcript << { user: "What is the weather in Zipolite, Oaxaca?" }
-    response = subject.chat_completion(openai: "gpt-4o", loop: true)
+    response = subject.chat_completion(openai: "gpt-4o")
     expect(response).to include("hot and sunny")
   end
 end
@@ -264,9 +270,23 @@ This is particularly useful for:
 - Resource-intensive computations
 - Functions with deterministic outputs for the same inputs
 
-#### Manually Stopping a Loop
+#### Limiting Tool Calls
 
-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.
+You can control the maximum number of tool calls before the AI must provide a text response:
+
+```ruby
+# Limit to 5 tool calls (default is 25)
+response = my_ai.chat_completion(max_tool_calls: 5)
+
+# Configure globally
+Raix.configure do |config|
+  config.max_tool_calls = 10
+end
+```
+
+#### Manually Stopping Tool Calls
+
+For AI components that process tasks without end-user interaction, you can use `stop_tool_calls_and_respond!` within a function to force the AI to provide a text response without making additional tool calls.
 
 ```ruby
 class OrderProcessor
@@ -285,8 +305,8 @@ class OrderProcessor
   end
 
   def perform
-    # will continue looping until `stop_looping!` is called
-    chat_completion(loop: true)
+    # will automatically continue after tool calls until finished_processing is called
+    chat_completion
   end
 
 
@@ -317,7 +337,8 @@ class OrderProcessor
 
   function :finished_processing do
     order.update!(transcript:, processed_at: Time.current)
-    stop_looping!
+    stop_tool_calls_and_respond!
+    "Order processing completed successfully"
   end
 end
 ```

data/Rakefile

@@ -7,6 +7,12 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"
 
-RuboCop::RakeTask.new
+RuboCop::RakeTask.new(:rubocop_ci)
+
+task ci: %i[spec rubocop_ci]
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = ["--autocorrect"]
+end
 
 task default: %i[spec rubocop]

data/lib/mcp/sse_client.rb

@@ -257,9 +257,7 @@ module Raix
 
           if event[:error]
             raise ProtocolError, "SSE error: #{event[:error].message}"
-          elsif event[:id] == request_id && event[:result]
-            return event[:result]
-          elsif event[:result] && !event[:id]
+          elsif event[:result] && (event[:id] == request_id || !event[:id])
             return event[:result]
           else
             @event_queue << event

data/lib/raix/chat_completion.rb

@@ -11,32 +11,39 @@ require_relative "message_adapters/base"
 module Raix
   class UndeclaredToolError < StandardError; end
 
-  # The `ChatCompletion`` module is a Rails concern that provides a way to interact
+  # 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
   # the API for completion. The API will return a response that you can use however
   # you see fit.
   #
-  # If the response includes a function call, the module will dispatch the function
-  # call and return the result. Which implies that function calls need to be defined
-  # on the class that includes this module. The `FunctionDispatch` module provides a
-  # Rails-like DSL for declaring and implementing tool functions at the top of your
-  # class instead of having to manually implement them as instance methods. The
-  # primary benefit of using the `FunctionDispatch` module is that it handles
-  # adding the function call results to the ongoing conversation transcript for you.
-  # It also triggers a new chat completion automatically if you've set the `loop`
-  # option to `true`, which is useful for implementing conversational chatbots that
-  # include tool calls.
+  # When the AI responds with tool function calls instead of a text message, this
+  # module automatically:
+  # 1. Executes the requested tool functions
+  # 2. Adds the function results to the conversation transcript
+  # 3. Sends the updated transcript back to the AI for another completion
+  # 4. Repeats this process until the AI responds with a regular text message
   #
-  # Note that some AI models can make more than a single tool function call in a
-  # single response. When that happens, the module will dispatch all of the function
-  # calls sequentially and return an array of results.
+  # This automatic continuation ensures that tool calls are seamlessly integrated
+  # into the conversation flow. The AI can use tool results to formulate its final
+  # response to the user. You can limit the number of tool calls using the
+  # `max_tool_calls` parameter to prevent excessive function invocations.
+  #
+  # Tool functions must be defined on the class that includes this module. The
+  # `FunctionDispatch` module provides a Rails-like DSL for declaring these
+  # functions at the class level, which is cleaner than implementing them as
+  # instance methods.
+  #
+  # Note that some AI models can make multiple tool function calls in a single
+  # response. When that happens, the module executes all requested functions
+  # before continuing the conversation.
   module ChatCompletion
     extend ActiveSupport::Concern
 
     attr_accessor :cache_at, :frequency_penalty, :logit_bias, :logprobs, :loop, :min_p, :model, :presence_penalty,
                   :prediction, :repetition_penalty, :response_format, :stream, :temperature, :max_completion_tokens,
-                  :max_tokens, :seed, :stop, :top_a, :top_k, :top_logprobs, :top_p, :tools, :available_tools, :tool_choice, :provider
+                  :max_tokens, :seed, :stop, :top_a, :top_k, :top_logprobs, :top_p, :tools, :available_tools, :tool_choice, :provider,
+                  :max_tool_calls, :stop_tool_calls_and_respond
 
     class_methods do
       # Returns the current configuration of this class. Falls back to global configuration for unset values.
@@ -58,14 +65,15 @@ module Raix
     # This method performs chat completion based on the provided transcript and parameters.
     #
     # @param params [Hash] The parameters for chat completion.
-    # @option loop [Boolean] :loop (false) Whether to loop the chat completion after function calls.
+    # @option loop [Boolean] :loop (false) DEPRECATED - The system now automatically continues after tool calls.
     # @option params [Boolean] :json (false) Whether to return the parse the response as a JSON object. Will search for <json> tags in the response first, then fall back to the default JSON parsing of the entire response.
     # @option params [String] :openai (nil) If non-nil, use OpenAI with the model specified in this param.
     # @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] :available_tools (nil) Tools to pass to the LLM. Ignored if nil (default). If false, no tools are passed. If an array, only declared tools in the array are passed.
+    # @option max_tool_calls [Integer] :max_tool_calls Maximum number of tool calls before forcing a text response. Defaults to the configured value.
     # @return [String|Hash] The completed chat response.
-    def chat_completion(params: {}, loop: false, json: false, raw: false, openai: nil, save_response: true, messages: nil, available_tools: nil)
+    def chat_completion(params: {}, loop: false, json: false, raw: false, openai: nil, save_response: true, messages: nil, available_tools: nil, max_tool_calls: nil)
       # set params to default values if not provided
       params[:cache_at] ||= cache_at.presence
       params[:frequency_penalty] ||= frequency_penalty.presence
@@ -108,8 +116,19 @@ module Raix
         end
       end
 
-      # used by FunctionDispatch
-      self.loop = loop
+      # Deprecation warning for loop parameter
+      if loop
+        warn "\n\nWARNING: The 'loop' parameter is DEPRECATED and will be ignored.\nChat completions now automatically continue after tool calls until the AI provides a text response.\nUse 'max_tool_calls' to limit the number of tool calls (default: #{configuration.max_tool_calls}).\n\n"
+      end
+
+      # Set max_tool_calls from parameter or configuration default
+      self.max_tool_calls = max_tool_calls || configuration.max_tool_calls
+
+      # Reset stop_tool_calls_and_respond flag
+      @stop_tool_calls_and_respond = false
+
+      # Track tool call count
+      tool_call_count = 0
 
       # set the model to the default if not provided
       self.model ||= configuration.model
@@ -143,14 +162,71 @@ module Raix
 
         tool_calls = response.dig("choices", 0, "message", "tool_calls") || []
         if tool_calls.any?
-          return tool_calls.map do |tool_call|
+          tool_call_count += tool_calls.size
+
+          # Check if we've exceeded max_tool_calls
+          if tool_call_count > self.max_tool_calls
+            # Add system message about hitting the limit
+            messages << { role: "system", content: "Maximum tool calls (#{self.max_tool_calls}) exceeded. Please provide a final response to the user without calling any more tools." }
+
+            # Force a final response without tools
+            params[:tools] = nil
+            response = if openai
+                         openai_request(params:, model: openai, messages:)
+                       else
+                         openrouter_request(params:, model:, messages:)
+                       end
+
+            # Process the final response
+            content = response.dig("choices", 0, "message", "content")
+            transcript << { assistant: content } if save_response
+            return raw ? response : content.strip
+          end
+
+          # Dispatch tool calls
+          tool_calls.each do |tool_call| # TODO: parallelize this?
             # dispatch the called function
-            arguments = JSON.parse(tool_call["function"]["arguments"].presence || "{}")
             function_name = tool_call["function"]["name"]
+            arguments = JSON.parse(tool_call["function"]["arguments"].presence || "{}")
             raise "Unauthorized function call: #{function_name}" unless self.class.functions.map { |f| f[:name].to_sym }.include?(function_name.to_sym)
 
             dispatch_tool_function(function_name, arguments.with_indifferent_access)
           end
+
+          # After executing tool calls, we need to continue the conversation
+          # to let the AI process the results and provide a text response.
+          # We continue until the AI responds with a regular assistant message
+          # (not another tool call request), unless stop_tool_calls_and_respond! was called.
+
+          # Use the updated transcript for the next call, not the original messages
+          updated_messages = transcript.flatten.compact
+          last_message = updated_messages.last
+
+          if !@stop_tool_calls_and_respond && (last_message[:role] != "assistant" || last_message[:tool_calls].present?)
+            # Send the updated transcript back to the AI
+            return chat_completion(
+              params:,
+              json:,
+              raw:,
+              openai:,
+              save_response:,
+              messages: nil, # Use transcript instead
+              available_tools:,
+              max_tool_calls: self.max_tool_calls - tool_call_count
+            )
+          elsif @stop_tool_calls_and_respond
+            # If stop_tool_calls_and_respond was set, force a final response without tools
+            params[:tools] = nil
+            response = if openai
+                         openai_request(params:, model: openai, messages:)
+                       else
+                         openrouter_request(params:, model:, messages:)
+                       end
+
+            content = response.dig("choices", 0, "message", "content")
+            transcript << { assistant: content } if save_response
+            return raw ? response : content.strip
+          end
         end
 
         response.tap do |res|
@@ -170,7 +246,7 @@ module Raix
         end
       rescue JSON::ParserError => e
         if e.message.include?("not a valid") # blank JSON
-          puts "Retrying blank JSON response... (#{retry_count} attempts) #{e.message}"
+          warn "Retrying blank JSON response... (#{retry_count} attempts) #{e.message}"
           retry_count += 1
           sleep 1 * retry_count # backoff
           retry if retry_count < 3
@@ -178,11 +254,11 @@ module Raix
           raise e # just fail if we can't get content after 3 attempts
         end
 
-        puts "Bad JSON received!!!!!!: #{content}"
+        warn "Bad JSON received!!!!!!: #{content}"
         raise e
       rescue Faraday::BadRequestError => e
         # make sure we see the actual error message on console or Honeybadger
-        puts "Chat completion failed!!!!!!!!!!!!!!!!: #{e.response[:body]}"
+        warn "Chat completion failed!!!!!!!!!!!!!!!!: #{e.response[:body]}"
         raise e
       end
     end
@@ -257,7 +333,7 @@ module Raix
         configuration.openrouter_client.complete(messages, model:, extras: params.compact, stream:)
       rescue OpenRouter::ServerError => e
         if e.message.include?("retry")
-          puts "Retrying OpenRouter request... (#{retry_count} attempts) #{e.message}"
+          warn "Retrying OpenRouter request... (#{retry_count} attempts) #{e.message}"
           retry_count += 1
           sleep 1 * retry_count # backoff
           retry if retry_count < 5

data/lib/raix/configuration.rb

@@ -36,10 +36,15 @@ module Raix
     # The openai_client option determines the OpenAI client to use for communication.
     attr_accessor_with_fallback :openai_client
 
+    # The max_tool_calls option determines the maximum number of tool calls
+    # before forcing a text response to prevent excessive function invocations.
+    attr_accessor_with_fallback :max_tool_calls
+
     DEFAULT_MAX_TOKENS = 1000
     DEFAULT_MAX_COMPLETION_TOKENS = 16_384
     DEFAULT_MODEL = "meta-llama/llama-3.3-8b-instruct:free"
     DEFAULT_TEMPERATURE = 0.0
+    DEFAULT_MAX_TOOL_CALLS = 25
 
     # Initializes a new instance of the Configuration class with default values.
     def initialize(fallback: nil)
@@ -47,6 +52,7 @@ module Raix
       self.max_completion_tokens = DEFAULT_MAX_COMPLETION_TOKENS
       self.max_tokens = DEFAULT_MAX_TOKENS
       self.model = DEFAULT_MODEL
+      self.max_tool_calls = DEFAULT_MAX_TOOL_CALLS
       self.fallback = fallback
     end
 

data/lib/raix/function_dispatch.rb

@@ -100,7 +100,9 @@ module Raix
             }
           ]
 
-          chat_completion(**chat_completion_args) if loop
+          # Return the content - ChatCompletion will automatically continue
+          # the conversation after tool execution to get a final response
+          content
         end
       end
     end
@@ -114,11 +116,11 @@ module Raix
       super
     end
 
-    # Stops the looping of chat completion after function calls.
-    # Useful for manually halting processing in workflow components
-    # that do not require a final text response to an end user.
-    def stop_looping!
-      self.loop = false
+    # Stops the automatic continuation of chat completions after this function call.
+    # Useful when you want to halt processing within a function and force the AI
+    # to provide a text response without making additional tool calls.
+    def stop_tool_calls_and_respond!
+      @stop_tool_calls_and_respond = true
     end
 
     def tools

data/lib/raix/mcp.rb

@@ -102,7 +102,7 @@ module Raix
         filtered_tools.each do |tool|
           remote_name = tool.name
           # TODO: Revisit later whether this much context is needed in the function name
-          local_name = "#{remote_name}_#{client.unique_key}".to_sym
+          local_name = :"#{remote_name}_#{client.unique_key}"
 
           description = tool.description
           input_schema = tool.input_schema || {}
@@ -154,9 +154,8 @@ module Raix
               }
             ]
 
-            # Continue the chat loop if requested (same semantics as FunctionDispatch)
-            chat_completion(**chat_completion_args) if loop
-
+            # Return the content - ChatCompletion will automatically continue
+            # the conversation after tool execution
             content_text
           end
         end

data/lib/raix/prompt_declarations.rb

@@ -170,7 +170,7 @@ module PromptDeclarations
   protected
 
   # workaround for super.chat_completion, which is not available in ruby
-  def chat_completion_from_superclass(*args, **kargs)
-    method(:chat_completion).super_method.call(*args, **kargs)
+  def chat_completion_from_superclass(*, **kargs)
+    method(:chat_completion).super_method.call(*, **kargs)
   end
 end

data/lib/raix/version.rb

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

data/raix.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/raix/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "raix"
+  spec.version = Raix::VERSION
+  spec.authors = ["Obie Fernandez"]
+  spec.email = ["obiefernandez@gmail.com"]
+
+  spec.summary = "Ruby AI eXtensions"
+  spec.homepage = "https://github.com/OlympiaAI/raix"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/OlympiaAI/raix"
+  spec.metadata["changelog_uri"] = "https://github.com/OlympiaAI/raix/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 6.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+  spec.add_dependency "open_router", "~> 0.2"
+  spec.add_dependency "ostruct"
+  spec.add_dependency "ruby-openai", "~> 7"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Obie Fernandez
@@ -89,6 +89,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -110,6 +111,7 @@ files:
 - lib/raix/prompt_declarations.rb
 - lib/raix/response_format.rb
 - lib/raix/version.rb
+- raix.gemspec
 - sig/raix.rbs
 homepage: https://github.com/OlympiaAI/raix
 licenses: