raix 2.0.6 → 3.0.0

data/lib/raix/function_dispatch.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "securerandom"
 module Raix
   # Provides declarative function definition for ChatCompletion classes.
   #
@@ -64,45 +63,18 @@ module Raix
           end
         end
 
+        # Runs the function body and returns its result. ChatCompletion owns the
+        # transcript record of the exchange: it appends the model's own tool-call
+        # turn (real ids, signatures) alongside this result, then continues the
+        # conversation to get a final response.
         define_method(name) do |arguments, cache|
-          id = SecureRandom.uuid[0, 23]
-
-          content = if cache.present?
-                      cache.fetch([name, arguments]) do
-                        instance_exec(arguments, &block)
-                      end
-                    else
-                      instance_exec(arguments, &block)
-                    end
-
-          # add in one operation to prevent race condition and potential wrong
-          # interleaving of tool calls in multi-threaded environments
-          transcript << [
-            {
-              role: "assistant",
-              content: nil,
-              tool_calls: [
-                {
-                  id:,
-                  type: "function",
-                  function: {
-                    name:,
-                    arguments: arguments.to_json
-                  }
-                }
-              ]
-            },
-            {
-              role: "tool",
-              tool_call_id: id,
-              name:,
-              content: content.to_s
-            }
-          ]
-
-          # Return the content - ChatCompletion will automatically continue
-          # the conversation after tool execution to get a final response
-          content
+          if cache.present?
+            cache.fetch([name, arguments]) do
+              instance_exec(arguments, &block)
+            end
+          else
+            instance_exec(arguments, &block)
+          end
         end
       end
     end

data/lib/raix/function_tool_adapter.rb

@@ -1,63 +1,38 @@
 # frozen_string_literal: true
 
 module Raix
-  # Adapter to convert Raix function declarations to RubyLLM::Tool instances
+  # Adapter to convert Raix function declarations to RubyLLM::Tool instances.
+  #
+  # The generated tools exist so RubyLLM sends the right schema to the
+  # provider. Raix drives the tool loop itself (see ChatCompletion), so it
+  # dispatches functions through `dispatch_tool_function` rather than letting
+  # RubyLLM execute these wrappers. `execute` is still implemented correctly so
+  # a generated tool behaves sanely if invoked directly.
   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]
 
         # 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
+        # rebuilding it field-by-field via `parameter(...)`. The per-field path
+        # only carries `type` and `description`, which silently drops 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
+          # RubyLLM's `parameters(schema)` path forwards the schema verbatim and, unlike the
+          # per-field `parameter(...)` 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]))
+          parameters({ 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.
-        #
-        # 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|
-          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
+          raix_instance.public_send(raix_function_name, args.with_indifferent_access, nil)
         end
       end
 
@@ -77,11 +52,16 @@ module Raix
       tool_instance
     end
 
-    def self.convert_tools_for_ruby_llm(raix_instance)
+    # Converts the instance's declared functions. Pass `only:` (an array of
+    # function names) to convert just that subset, which is how
+    # `available_tools` restricts what the model can see.
+    def self.convert_tools_for_ruby_llm(raix_instance, only: nil)
       return [] unless raix_instance.class.respond_to?(:functions)
-      return [] if raix_instance.class.functions.blank?
 
-      raix_instance.class.functions.map do |function_def|
+      functions = Array(raix_instance.class.functions)
+      functions = functions.select { |function_def| only.include?(function_def[:name].to_s) } if only
+
+      functions.map do |function_def|
         create_tool_from_function(function_def, raix_instance)
       end
     end

data/lib/raix/mcp.rb

@@ -7,13 +7,11 @@
 # `tools/list`) and exposes each remote tool as if it were an inline
 # `function` declared with Raix::FunctionDispatch.  When the tool is
 # invoked by the model, the generated instance method forwards the
-# request to the remote server using `tools/call`, captures the result,
-# and appends the appropriate messages to the transcript so that the
-# conversation history stays consistent.
+# request to the remote server using `tools/call` and returns the result.
+# ChatCompletion records the exchange in the transcript during a tool round.
 
 require "active_support/concern"
 require "active_support/inflector"
-require "securerandom"
 require "uri"
 
 module Raix
@@ -124,36 +122,10 @@ module Raix
             stored_schema = self.class.instance_variable_get(:@tool_schemas)&.dig(local_name)
             coerced_arguments = coerce_arguments(arguments, stored_schema)
 
-            content_text = client.call_tool(remote_name, **coerced_arguments)
-            call_id = SecureRandom.uuid
-
-            # Mirror FunctionDispatch transcript behaviour
-            transcript << [
-              {
-                role: "assistant",
-                content: nil,
-                tool_calls: [
-                  {
-                    id: call_id,
-                    type: "function",
-                    function: {
-                      name: local_name.to_s,
-                      arguments: arguments.to_json
-                    }
-                  }
-                ]
-              },
-              {
-                role: "tool",
-                tool_call_id: call_id,
-                name: local_name.to_s,
-                content: content_text
-              }
-            ]
-
-            # Return the content - ChatCompletion will automatically continue
-            # the conversation after tool execution
-            content_text
+            # Return the content. ChatCompletion records the exchange in the
+            # transcript (the model's own tool-call turn plus this result) and
+            # continues the conversation.
+            client.call_tool(remote_name, **coerced_arguments)
           end
         end
 

data/lib/raix/multimodal_content_adapter.rb

@@ -5,18 +5,28 @@ 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.
+  # Translates OpenAI-style structured content arrays into the pieces RubyLLM
+  # wants: a String of text, a list of attachment sources, and whether the
+  # message ends a prompt cache prefix.
   #
-  # 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
+  # RubyLLM only accepts String content, so a message whose content is an array
+  # of `{ type: "text" }` / `{ type: "image_url" }` parts has to be taken apart
+  # before it can be added to a chat. Images become attachments, text parts are
+  # joined, and a part carrying `cache_control` marks the message as a cache
+  # boundary. 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.
+  # Content that is not an array of hashes passes through untouched, so plain
+  # text completions are unaffected.
   class MultimodalContentAdapter
+    # `cache_ttl` carries the first `cache_control.ttl` seen, so the caller can
+    # pass it to RubyLLM's chat-level caching options. RubyLLM marks cache
+    # boundaries per message, so a boundary inside a content array lands at
+    # the end of that message.
+    Result = Struct.new(:content, :attachments, :cache_boundary, :cache_ttl) do
+      alias_method :cache_boundary?, :cache_boundary
+    end
+
+    # @return [Result]
     def self.translate(content)
       new(content).translate
     end
@@ -26,34 +36,40 @@ module Raix
     end
 
     def translate
-      return @content unless translatable?
+      return Result.new(@content, [], false) unless structured?
 
       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?
 
+      attachments = parts.select { |part| part[:type].to_s == "image_url" }
+                         .filter_map { |part| attachment_for(part.dig(:image_url, :url)) }
       text = parts.select { |part| part[:type].to_s == "text" }.filter_map { |part| part[:text] }.join("\n")
-      RubyLLM::Content.new(text.empty? ? nil : text, attachments)
+      cache_controls = parts.filter_map { |part| part[:cache_control].presence }
+      cache_ttl = cache_controls.filter_map { |control| control.is_a?(Hash) ? control[:ttl] : nil }.first
+
+      Result.new(text.empty? ? nil : text, attachments, cache_controls.any?, cache_ttl)
     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" }
+    # An empty array counts: dynamically assembled content whose parts were all
+    # filtered out becomes nil content, which ChatCompletion sends as "".
+    def structured?
+      @content.is_a?(Array) && @content.all? { |part| part.is_a?(Hash) }
     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)
+    # OpenAI's `image_url` accepts an http(s) URL or a base64 `data:` URI, and
+    # that is all this adapter forwards. RubyLLM::Attachment would treat any
+    # other String as a filesystem path to read, so bare paths are skipped
+    # rather than passed through.
+    #
+    # RubyLLM does not decode `data:` URIs itself; those become a binary
+    # StringIO, and RubyLLM sniffs the media type from the bytes.
+    def attachment_for(url)
       return if url.nil? || url.empty?
-      return url unless url.start_with?("data:")
+      return url if url.match?(%r{\Ahttps?://}i)
 
-      match = url.match(/\Adata:[^;,]*;base64,(.+)\z/m)
-      return url unless match
+      match = url.match(/\Adata:[^;,]*;base64,(.+)\z/mi)
+      return unless match
 
       io = StringIO.new(Base64.decode64(match[1]))
       io.set_encoding(Encoding::BINARY) if io.respond_to?(:set_encoding)

data/lib/raix/prompt_declarations.rb

@@ -95,7 +95,7 @@ module Raix
         else
           __system_prompt = instance_exec(&current_prompt.system) if current_prompt.system.present? # rubocop:disable Lint/UnderscorePrefixedVariableName
           __system_prompt ||= system_prompt if respond_to?(:system_prompt)
-          __system_prompt ||= self.class.system_prompt.presence
+          __system_prompt ||= self.class.system_prompt.presence if self.class.respond_to?(:system_prompt)
           transcript << { system: __system_prompt } if __system_prompt
           transcript << { user: instance_exec(&current_prompt.text) } # text is required
 

data/lib/raix/transcript_adapter.rb

@@ -41,7 +41,7 @@ module Raix
 
     # Clear all messages
     def clear
-      @ruby_llm_chat.reset_messages!
+      @ruby_llm_chat.messages = []
       @pending_messages.clear
       self
     end
@@ -63,8 +63,10 @@ module Raix
     def add_message_from_hash(hash)
       # Raix abbreviated format: { system: "text" }, { user: "text" }, { assistant: "text" }
       if hash.key?(:system) || hash.key?("system")
+        # Pending only, like every other role. Writing it into the memoized
+        # chat as well sent each system prompt twice and rejected structured
+        # (array) content before ChatCompletion could translate it.
         content = hash[:system] || hash["system"]
-        @ruby_llm_chat.with_instructions(content)
         @pending_messages << { role: "system", content: }
       elsif hash.key?(:user) || hash.key?("user")
         content = hash[:user] || hash["user"]

data/lib/raix/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 2.0.6
+  version: 3.0.0
 platform: ruby
 authors:
 - Obie Fernandez
 bindir: exe
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement