raix 2.0.4 → 2.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec3b7449e51440e1d669e323dea0c371a3d18d7d4083090d61599ff1dbce3bbe
-  data.tar.gz: 6f2029218c2099ab1172d1d458be9ccb33836078d5abc9b04865cae0d497bc07
+  metadata.gz: 238b5d66fbe10f61f2264758964451d8e3a45da5b7ea0056e50a2cb87674d608
+  data.tar.gz: f80fc111967055c7d62d3facecb6e10190efaa6d9ad0e8df32034aae837bf2d2
 SHA512:
-  metadata.gz: 76e1d77e80023dbc634e4b2f72eaa269f05d539ea97470df1355e69e73d75a6cf4bd2bd7e627ab2cf01fcb381fd85c4b153d28005f32190ff1b8ae69c3bea275
-  data.tar.gz: 6fedf4bae5c406b72b83a1aacbc985849eb7c461237e7cc1e12d9ca73ea05a861912f13739bc92ba8ad992bf88f5a31fa530dc9468c5bdb4763f53caf3833843
+  metadata.gz: b45d5cf20fda5333e00b563af114e670d69cb22fb32b386753b05bc85cfc5e2c88a7a627f9d759697ba0c507ab93c63b0a242099bfce47f4ea8b82b34c9267a2
+  data.tar.gz: cabedce14ff63b6b7227aa8e2457541769170a4b1a0c8a52a0eeef73a0e62c53ff567cbfdfbf15d9045dca02582dccd9daf0155878d7b59d01b55a718b4bd185

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [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
+- `Raix::Configuration` no longer defaults `temperature` to `0.0`. The default was being injected into every request payload, which OpenRouter rejects with `404 No endpoints found that can handle the requested parameters` when routed to providers whose `supported_parameters` list omits `temperature` (notably Anthropic's Claude 4.7 family) and `provider.require_parameters: true` is set — which Raix sets automatically whenever `json: true` is passed to `chat_completion`. Callers that want a specific temperature should set one explicitly (`self.temperature = 0.0` on the including class, or `Raix.configure { |c| c.temperature = 0.0 }` globally); when unset, Raix now omits the parameter and the provider's own server-side default applies. `max_tokens`, `max_completion_tokens`, and `model` defaults are unchanged.
+- `Raix::FunctionToolAdapter` now forwards the full JSON-Schema dict for each function parameter to RubyLLM instead of rebuilding it from `type` + `description` only. Rich schema fields like `additionalProperties`, `items`, `enum`, and nested `properties` were silently dropped, leaving providers (notably Gemini's structured output via OpenRouter) to invent degenerate shapes for `type: object` arguments — e.g. emitting `{"prefix" => false}` instead of `{"prefix:title" => "..."}`. Function declarations with rich object schemas now reach the provider intact.
+- The outer tool-args schema continues to inject `additionalProperties: false` and `strict: true` by default for OpenAI strict-mode compatibility, but consumers can override either by setting them explicitly in the function declaration.
+- Multimodal `transcript` content is no longer silently dropped on the RubyLLM backend. OpenAI-style content arrays (a `text` part plus one or more `{ type: "image_url", image_url: { url: ... } }` parts) were passed to RubyLLM verbatim, which treats the array as plain text — so a vision model received text only and confabulated an answer. Raix now translates `image_url` parts into RubyLLM attachments via `Raix::MultimodalContentAdapter`, decoding base64 `data:` URIs into binary IO (RubyLLM's `Attachment` does not natively recognize `data:` URIs) and passing http(s) URLs through. Text-only completions are unaffected (#51).
+
 ## [2.0.4] - 2026-05-19
 
 ### Fixed

data/Gemfile.lock

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

data/Rakefile

@@ -2,6 +2,8 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "shellwords"
+require "tmpdir"
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -16,3 +18,26 @@ RuboCop::RakeTask.new(:rubocop) do |task|
 end
 
 task default: %i[spec rubocop]
+
+namespace :release do
+  desc "Create a GitHub release for the current version (runs automatically after `rake release`)"
+  task :github do
+    version = Bundler::GemHelper.gemspec.version.to_s
+    tag = "v#{version}"
+    section = File.read("CHANGELOG.md").match(/^## \[#{Regexp.escape(version)}\][^\n]*\n(.*?)(?=^## \[|\z)/m)
+
+    if section.nil?
+      warn "release:github — no CHANGELOG entry for #{version}; skipping GitHub release."
+      next
+    end
+
+    notes_file = File.join(Dir.tmpdir, "raix-release-notes-#{version}.md")
+    File.write(notes_file, "#{section[1].strip}\n")
+
+    sh "gh release create #{tag.shellescape} --title #{"Release #{version}".shellescape} --notes-file #{notes_file.shellescape} --latest=true"
+  end
+end
+
+Rake::Task["release"].enhance do
+  Rake::Task["release:github"].invoke
+end

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?
 
@@ -355,10 +419,10 @@ module Raix
           chat.with_instructions(content)
         when "user"
           has_user_message = true
-          chat.add_message(role: :user, content:)
+          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/configuration.rb

@@ -51,12 +51,19 @@ module Raix
     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.
+    #
+    # Note: temperature is intentionally not defaulted. Setting a non-nil
+    # temperature here would force it into every request payload, and some
+    # providers (e.g. Anthropic's Claude 4.7 family on OpenRouter) do not list
+    # `temperature` in their supported parameters. Combined with
+    # `provider.require_parameters: true` (which Raix sets when `json: true`),
+    # an injected default of 0.0 causes OpenRouter to reject the request with
+    # "No endpoints found that can handle the requested parameters." Callers
+    # who want a specific temperature should set one explicitly.
     def initialize(fallback: nil)
-      self.temperature = DEFAULT_TEMPERATURE
       self.max_completion_tokens = DEFAULT_MAX_COMPLETION_TOKENS
       self.max_tokens = DEFAULT_MAX_TOKENS
       self.model = DEFAULT_MODEL

data/lib/raix/function_tool_adapter.rb

@@ -3,23 +3,61 @@
 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]
 
-        # Define parameters based on function definition
-        function_def[:parameters][:properties]&.each do |param_name, param_def|
-          required = function_def[:parameters][:required]&.include?(param_name)
-          param param_name.to_sym, type: param_def[:type], desc: param_def[:description], required:
+        # Forward the full JSON-schema parameter dict to RubyLLM rather than
+        # rebuilding it field-by-field via `param(...)`. The per-field path
+        # only carried `type` and `description`, which silently dropped richer
+        # schema like `additionalProperties`, `items`, `enum`, or nested
+        # `properties` — leaving providers (notably Gemini's structured output)
+        # to invent degenerate shapes for `type: object` arguments.
+        if function_def[:parameters].is_a?(Hash) && function_def[:parameters][:properties].present?
+          # RubyLLM's `params(schema)` path forwards the schema verbatim and, unlike the
+          # per-field `param(...)` path, does not inject the OpenAI strict-mode guards. Default
+          # them on so existing tools keep strict behavior, while letting a function declaration
+          # override either by setting it explicitly.
+          params({ additionalProperties: false, strict: true }.merge(function_def[:parameters]))
         end
 
         # Store reference to the instance and function name
         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/multimodal_content_adapter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+require "base64"
+require "stringio"
+
+module Raix
+  # Translates OpenAI-style multimodal content arrays (a `text` part plus one or
+  # more `image_url` parts) into a RubyLLM::Content so images survive the trip to
+  # the provider.
+  #
+  # RubyLLM's `add_message`/`ask` treat a raw array of OpenAI content hashes as
+  # plain text, so an `{ type: "image_url", image_url: { url: ... } }` part is
+  # silently dropped and a vision model receives text only. See
+  # https://github.com/OlympiaAI/raix/issues/51
+  #
+  # Anything that is not an array of hashes containing at least one `image_url`
+  # part is returned untouched, so existing text completions are unaffected.
+  class MultimodalContentAdapter
+    def self.translate(content)
+      new(content).translate
+    end
+
+    def initialize(content)
+      @content = content
+    end
+
+    def translate
+      return @content unless translatable?
+
+      parts = @content.map(&:with_indifferent_access)
+      attachments = parts.select { |part| part[:type].to_s == "image_url" }
+                         .filter_map { |part| attachment_source(part.dig(:image_url, :url)) }
+      return @content if attachments.empty?
+
+      text = parts.select { |part| part[:type].to_s == "text" }.filter_map { |part| part[:text] }.join("\n")
+      RubyLLM::Content.new(text.empty? ? nil : text, attachments)
+    end
+
+    private
+
+    def translatable?
+      @content.is_a?(Array) &&
+        @content.all? { |part| part.is_a?(Hash) } &&
+        @content.any? { |part| (part[:type] || part["type"]).to_s == "image_url" }
+    end
+
+    # RubyLLM::Attachment recognizes http(s) URLs, file paths, and IO objects, but
+    # not base64 `data:` URIs (it would treat one as a filesystem path). Decode
+    # those into a binary StringIO, which Attachment handles as an IO source.
+    def attachment_source(url)
+      return if url.nil? || url.empty?
+      return url unless url.start_with?("data:")
+
+      match = url.match(/\Adata:[^;,]*;base64,(.+)\z/m)
+      return url unless match
+
+      io = StringIO.new(Base64.decode64(match[1]))
+      io.set_encoding(Encoding::BINARY) if io.respond_to?(:set_encoding)
+      io
+    end
+  end
+end

data/lib/raix/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 2.0.4
+  version: 2.0.6
 platform: ruby
 authors:
 - Obie Fernandez
 bindir: exe
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -109,6 +109,7 @@ files:
 - lib/raix/mcp/stdio_client.rb
 - lib/raix/mcp/tool.rb
 - lib/raix/message_adapters/base.rb
+- lib/raix/multimodal_content_adapter.rb
 - lib/raix/predicate.rb
 - lib/raix/prompt_declarations.rb
 - lib/raix/response_format.rb