raix 2.0.5 → 2.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f9cda9662a819d937b2be909563e7bbd145111b2f70006a596b6fc30cf25fe6
-  data.tar.gz: 280b9bee2cc6b3f47ded7b0ae88b406842184c48597efc4c9aa085458bff4cab
+  metadata.gz: 238b5d66fbe10f61f2264758964451d8e3a45da5b7ea0056e50a2cb87674d608
+  data.tar.gz: f80fc111967055c7d62d3facecb6e10190efaa6d9ad0e8df32034aae837bf2d2
 SHA512:
-  metadata.gz: dc7ee985af7a5b832803e7aa9300986f83fd520315e4d3668e68fa1d9084be08782517054dac91e9a187e190de2876215e0dfa71bb2f09ffb462d9f275b22e71
-  data.tar.gz: 49380b2201f8563dd7e69c30a76866b16b89d2085c6bc3e953afd6f233343d4f9c93ba891c02122228d2579341b9c64c423f16751d588d97e5105c6443d2da07
+  metadata.gz: b45d5cf20fda5333e00b563af114e670d69cb22fb32b386753b05bc85cfc5e2c88a7a627f9d759697ba0c507ab93c63b0a242099bfce47f4ea8b82b34c9267a2
+  data.tar.gz: cabedce14ff63b6b7227aa8e2457541769170a4b1a0c8a52a0eeef73a0e62c53ff567cbfdfbf15d9045dca02582dccd9daf0155878d7b59d01b55a718b4bd185

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [2.0.6] - 2026-07-23
+
+### Fixed
+- `max_tool_calls` is now enforced under the RubyLLM backend. RubyLLM drives the tool-call loop internally (`complete` → `handle_tool_calls` → `complete`) and only returns once the model stops calling tools, so the counting loop in `Raix::ChatCompletion` never saw a tool round — `max_tool_calls` was dead code and agentic loops ran unbounded. The budget is now enforced inside the generated `FunctionToolAdapter` tool wrapper, which increments a per-completion counter on each invocation and returns a `RubyLLM::Tool::Halt` (refusing to run the underlying function) once the count exceeds the budget. Enforcement is per call because a single model response can pack several parallel tool calls, all of which RubyLLM executes in one round even after one halts. On a halt, `chat_completion` issues one final completion with no tools (and drops `tool_choice`) and returns its text, appending the existing `"Maximum tool calls (N) exceeded…"` system message.
+- `stop_tool_calls_and_respond!` works again. It set a flag that only the (now unreachable) counting loop read, so under RubyLLM it did nothing. The tool wrapper now checks the flag after a successful tool execution and halts the loop, forcing a final text response.
+- `Raix::ChatCompletion` no longer crashes when RubyLLM's tool loop is halted. `chat.complete`/`#ask` return a `RubyLLM::Tool::Halt` (not a `Message`) in that case, and the response conversion called `#raw` / `#input_tokens` on it. `ruby_llm_request` now detects the `Halt` and hands it back for final-response handling.
+- Assistant tool-call messages replayed from the transcript into a fresh `RubyLLM::Chat` are now translated from Raix's OpenAI-style array-of-hashes shape into the `{ id => RubyLLM::ToolCall }` shape RubyLLM's providers expect. Previously this path (reachable via the forced final completion above) raised `NoMethodError: undefined method 'id' for nil` while rendering the request payload.
+
 ## [2.0.5] - 2026-06-04
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    raix (2.0.5)
+    raix (2.0.6)
       activesupport (>= 6.0)
       faraday-retry (~> 2.0)
       ostruct

data/lib/raix/chat_completion.rb

@@ -127,6 +127,11 @@ module Raix
       # Track tool call count
       tool_call_count = 0
 
+      # Reset the per-completion tool-call counter that FunctionToolAdapter's
+      # generated wrappers use to enforce max_tool_calls under the RubyLLM
+      # backend (see #increment_tool_call_count).
+      @tool_call_count = 0
+
       # set the model to the default if not provided
       self.model ||= configuration.model
 
@@ -144,7 +149,27 @@ module Raix
       run_before_completion_hooks(params, messages)
 
       begin
+        # Snapshot the transcript length before the request. If a generated tool
+        # halts RubyLLM's loop, force_final_response_after_halt uses this to
+        # recover exactly the assistant/tool messages appended while executing
+        # tools and replay them after the original messages — which may not live
+        # in the transcript at all when `messages:` was passed explicitly. Only
+        # tools can trigger a halt, so skip the transcript read entirely when
+        # none are registered.
+        transcript_size_before = params[:tools].present? ? transcript.flatten.compact.size : 0
+
         response = ruby_llm_request(params:, model: openai || model, messages:, openai_override: openai)
+
+        # RubyLLM runs the entire tool-call loop inside chat.complete/#ask. When
+        # a generated tool halts that loop — because max_tool_calls was exceeded
+        # or stop_tool_calls_and_respond! was called — the return value is a
+        # RubyLLM::Tool::Halt rather than a Message. Re-issue one final
+        # completion with no tools; the shared handling below then returns its
+        # text/JSON as usual.
+        if response.is_a?(RubyLLM::Tool::Halt)
+          response = force_final_response_after_halt(response, params:, openai:, messages:, transcript_size_before:)
+        end
+
         retry_count = 0
         content = nil
 
@@ -298,8 +323,47 @@ module Raix
       public_send(function_name, arguments, cache)
     end
 
+    # Increments and returns the per-completion tool-call counter. Called by the
+    # generated FunctionToolAdapter wrappers to enforce max_tool_calls: RubyLLM
+    # runs the whole tool loop inside a single chat.complete, so Raix never sees
+    # the individual rounds and has to count from inside the tool. Internal API.
+    def increment_tool_call_count
+      @tool_call_count = @tool_call_count.to_i + 1
+    end
+
     private
 
+    # Issues the single final completion after RubyLLM's tool loop was halted,
+    # then completes once with no tools and returns the OpenAI-compatible hash.
+    #
+    # The final request is rebuilt from the original `messages` (the transcript
+    # or the caller-supplied `messages:` argument that drove the first request)
+    # plus the assistant/tool exchange FunctionDispatch appended while executing
+    # tools before the halt. `transcript_size_before` marks where that exchange
+    # begins, so the caller's system/user prompt is preserved even when it was
+    # never written into the transcript — otherwise the forced final call would
+    # answer from tool results (or stale transcript) alone.
+    def force_final_response_after_halt(halt, params:, openai:, messages:, transcript_size_before:)
+      adapter = MessageAdapters::Base.new(self)
+      tool_exchange = transcript.flatten.compact.drop(transcript_size_before).map { |msg| adapter.transform(msg) }
+      messages += tool_exchange
+
+      reason = halt.content
+      if reason.is_a?(FunctionToolAdapter::ToolCallsCapReached)
+        messages << { role: "system",
+                      content: "Maximum tool calls (#{reason.max_tool_calls}) exceeded. Please provide a final response to the user without calling any more tools." }
+      end
+
+      # Force a final response without tools. Drop tool_choice as well: a
+      # lingering tool_choice that forces tool use with no tools registered is a
+      # provider error.
+      final_params = params.dup
+      final_params[:tools] = nil
+      final_params.delete(:tool_choice)
+
+      ruby_llm_request(params: final_params, model: openai || model, messages:, openai_override: openai)
+    end
+
     def filtered_tools(tool_names)
       return nil if tool_names.blank?
 
@@ -357,8 +421,8 @@ module Raix
           has_user_message = true
           chat.add_message(role: :user, content: MultimodalContentAdapter.translate(content))
         when "assistant"
-          if msg[:tool_calls] || msg["tool_calls"]
-            chat.add_message(role: :assistant, content:, tool_calls: msg[:tool_calls] || msg["tool_calls"])
+          if (tool_calls = msg[:tool_calls] || msg["tool_calls"])
+            chat.add_message(role: :assistant, content:, tool_calls: normalize_tool_calls_for_ruby_llm(tool_calls))
           else
             chat.add_message(role: :assistant, content:)
           end
@@ -397,6 +461,13 @@ module Raix
         # Non-streaming mode - return OpenAI-compatible response format
         response_message = has_user_message ? chat.complete : chat.ask
 
+        # A generated tool can halt RubyLLM's internal tool loop (max_tool_calls
+        # exceeded or stop_tool_calls_and_respond!). When that happens
+        # chat.complete/#ask returns a RubyLLM::Tool::Halt, not a Message, so it
+        # has no #raw / #input_tokens. Hand it straight back to chat_completion,
+        # which forces a final tool-less completion.
+        return response_message if response_message.is_a?(RubyLLM::Tool::Halt)
+
         # Pull through the raw provider payload when available. OpenRouter's
         # `id` is the only handle we have to look up authoritative billing
         # cost via /api/v1/generation, and callers that watch the response
@@ -450,5 +521,24 @@ module Raix
       # Default to openrouter for model IDs with provider prefix
       :openrouter
     end
+
+    # Raix's transcript stores assistant tool calls in OpenAI's array-of-hashes
+    # shape (`[{ id:, type:, function: { name:, arguments: } }]`), but RubyLLM's
+    # providers format tool calls from a Hash keyed by call id whose values
+    # respond to #id/#name/#arguments (RubyLLM::ToolCall). Translate so a
+    # transcript that already contains tool exchanges can be replayed back into
+    # a fresh RubyLLM chat — notably for the forced final completion after a
+    # max_tool_calls / stop_tool_calls_and_respond! halt.
+    def normalize_tool_calls_for_ruby_llm(tool_calls)
+      return tool_calls if tool_calls.is_a?(Hash) && tool_calls.values.all?(RubyLLM::ToolCall)
+
+      Array(tool_calls).each_with_object({}) do |raw, acc|
+        tc = raw.respond_to?(:with_indifferent_access) ? raw.with_indifferent_access : raw
+        function = tc[:function] || {}
+        arguments = function[:arguments]
+        arguments = JSON.parse(arguments) if arguments.is_a?(String) && arguments.present?
+        acc[tc[:id]] = RubyLLM::ToolCall.new(id: tc[:id], name: function[:name], arguments: arguments || {})
+      end
+    end
   end
 end

data/lib/raix/function_tool_adapter.rb

@@ -3,6 +3,12 @@
 module Raix
   # Adapter to convert Raix function declarations to RubyLLM::Tool instances
   class FunctionToolAdapter
+    # Sentinels wrapped in a RubyLLM::Tool::Halt so that ChatCompletion can tell
+    # *why* RubyLLM's internal tool loop was halted from inside a generated tool
+    # wrapper. Internal API — not intended for use outside Raix.
+    ToolCallsCapReached = Struct.new(:max_tool_calls)
+    StopToolCallsRequested = Struct.new(:result)
+
     def self.create_tool_from_function(function_def, instance)
       tool_class = Class.new(RubyLLM::Tool) do
         description function_def[:description] if function_def[:description]
@@ -25,9 +31,33 @@ module Raix
         define_method(:raix_instance) { instance }
         define_method(:raix_function_name) { function_def[:name] }
 
-        # Override execute to call the Raix function
+        # Override execute to call the Raix function.
+        #
+        # The max_tool_calls budget is enforced here, inside the generated
+        # wrapper, because RubyLLM drives the tool loop internally
+        # (complete -> handle_tool_calls -> complete) and never yields control
+        # back to Raix between rounds. Counting must therefore happen per tool
+        # invocation: a single model response can pack several parallel tool
+        # calls, all of which RubyLLM executes in one round even after one has
+        # halted, so each wrapper checks the shared counter independently.
         define_method(:execute) do |**args|
-          raix_instance.public_send(raix_function_name, args.with_indifferent_access, nil)
+          if raix_instance.increment_tool_call_count > raix_instance.max_tool_calls
+            # Refuse to run the underlying function and halt the loop. RubyLLM
+            # returns this Halt from chat.complete; ChatCompletion turns it into
+            # a final, tool-less completion.
+            halt(ToolCallsCapReached.new(raix_instance.max_tool_calls))
+          else
+            result = raix_instance.public_send(raix_function_name, args.with_indifferent_access, nil)
+
+            # stop_tool_calls_and_respond! sets a flag that only the old (now
+            # unreachable) counting loop used to read. Honor it here so it still
+            # forces a final text response under the RubyLLM backend.
+            if raix_instance.stop_tool_calls_and_respond
+              halt(StopToolCallsRequested.new(result))
+            else
+              result
+            end
+          end
         end
       end
 

data/lib/raix/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 2.0.5
+  version: 2.0.6
 platform: ruby
 authors:
 - Obie Fernandez
 bindir: exe
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport