raix 1.0.3 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdc9196b3303997d22de645ce00fe6484d0fedf9d06e2956f2e7177b59d11401
-  data.tar.gz: ab99e48389368036196b6e3c338ce09df5ada2a25baa4b32b1d841477ba260eb
+  metadata.gz: 101c916df93e569b21330ea028dafac8d095021a7c2c27bb91a911fffc55bc29
+  data.tar.gz: 1b4498f818350fab8823a66535334f24f2b89ede02d79cadcc23e052e3cd0dcb
 SHA512:
-  metadata.gz: 244865e9128cc0984221413957a3471789ff8bfbadbb70dd9639474176ccbc4789b8abdde361f24734b3ec9fea40b388aa3f93f299f96f5ff32002c14d0a290b
-  data.tar.gz: a3023e275d0afef0260327e94f7600a9a85c85bc646875a2f822a03aaff0262354fff315f1d6a9c4572e6d0a62577d90623c7315e69556620732d1adb21c2a79
+  metadata.gz: e5953aa12e7918e5b0266e23017c5c11874d919c4b83a10403c10a75d6998c2d8f2d3f8a11ab3d6abcf996f0ee30d827a564bd9ed5fd5862f673c689c6e8a06a
+  data.tar.gz: 41aabaa233555d191a02628055465e5759aea86de69c321ff43145b6ddcc1714d5c2828ebf659d7f4773e6de8d04ec647435c5c7e1a001b196bea7c6dee8c0f7

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [2.0.1] - 2026-03-20
+
+### Changed
+- Replaced `require_relative` with Zeitwerk autoloading (thanks @seuros, PR #47)
+
+## [2.0.0] - 2025-12-17
+
+### Breaking Changes
+- **Migrated from OpenRouter/OpenAI gems to RubyLLM** - Raix now uses [RubyLLM](https://github.com/crmne/ruby_llm) as its unified backend for all LLM providers. This provides better multi-provider support and a more consistent API.
+- **Configuration changes** - API keys are now configured through RubyLLM's configuration system instead of separate client instances.
+- **Removed direct client dependencies** - `openrouter` and `ruby-openai` gems are no longer direct dependencies; RubyLLM handles provider connections.
+
+### Added
+- **`before_completion` hook** - New hook system for intercepting and modifying chat completion requests before they're sent to the AI provider.
+  - Configure at global, class, or instance levels
+  - Hooks receive a `CompletionContext` with access to messages, params, and the chat completion instance
+  - Messages are mutable for content filtering, PII redaction, adding system prompts, etc.
+  - Params can be modified for dynamic model selection, A/B testing, and more
+  - Supports any callable object (Proc, Lambda, or object responding to `#call`)
+  - Use cases: database-backed configuration, logging, PII redaction, content filtering, cost tracking
+- **`FunctionToolAdapter`** - New adapter for converting Raix function declarations to RubyLLM tool format
+- **`TranscriptAdapter`** - New adapter for bridging Raix's abbreviated message format with standard OpenAI format
+
+### Changed
+- Chat completions now use RubyLLM's unified API for all providers (OpenAI, Anthropic, Google, etc.)
+- Improved provider detection based on model name patterns
+- Streamlined internal architecture with dedicated adapters
+
+### Migration Guide
+Update your configuration from:
+```ruby
+Raix.configure do |config|
+  config.openrouter_client = OpenRouter::Client.new(access_token: "...")
+  config.openai_client = OpenAI::Client.new(access_token: "...")
+end
+```
+
+To:
+```ruby
+RubyLLM.configure do |config|
+  config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  # Also supports: anthropic_api_key, gemini_api_key
+end
+```
+
 ## [1.0.2] - 2025-07-16
 ### Added
 - Added method to check for API client availability in Configuration

data/Gemfile.lock

@@ -1,26 +1,28 @@
 PATH
   remote: .
   specs:
-    raix (1.0.2)
+    raix (2.0.1)
       activesupport (>= 6.0)
       faraday-retry (~> 2.0)
-      open_router (~> 0.2)
       ostruct
-      ruby-openai (~> 8.1)
+      ruby_llm (~> 1.9)
+      zeitwerk (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.1.3.4)
+    activesupport (7.2.3)
       base64
+      benchmark (>= 0.3)
       bigdecimal
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+      concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
       minitest (>= 5.1)
-      mutex_m
-      tzinfo (~> 2.0)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
     addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
@@ -41,14 +43,14 @@ GEM
     event_stream_parser (1.0.0)
     faraday (2.9.2)
       faraday-net_http (>= 2.0, < 3.2)
-    faraday-multipart (1.0.4)
-      multipart-post (~> 2)
+    faraday-multipart (1.2.0)
+      multipart-post (~> 2.0)
     faraday-net_http (3.1.0)
       net-http
-    faraday-retry (2.3.1)
+    faraday-retry (2.4.0)
       faraday (~> 2.0)
+    ffi (1.17.2)
     ffi (1.17.2-arm64-darwin)
-    ffi (1.17.2-x86_64-linux-gnu)
     formatador (1.1.0)
     guard (2.18.1)
       formatador (>= 0.2.4)
@@ -77,27 +79,25 @@ GEM
     listen (3.9.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     lumberjack (1.2.10)
+    marcel (1.1.0)
     method_source (1.1.0)
-    minitest (5.24.0)
+    mini_portile2 (2.8.9)
+    minitest (5.27.0)
     multipart-post (2.4.1)
-    mutex_m (0.2.0)
     nenv (0.3.0)
     net-http (0.4.1)
       uri
     netrc (0.11.0)
-    nokogiri (1.18.8-arm64-darwin)
+    nokogiri (1.18.8)
+      mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-gnu)
+    nokogiri (1.18.8-arm64-darwin)
       racc (~> 1.4)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    open_router (0.3.3)
-      activesupport (>= 6.0)
-      dotenv (>= 2)
-      faraday (>= 1)
-      faraday-multipart (>= 1)
     ostruct (0.6.1)
     parallel (1.24.0)
     parser (3.3.0.5)
@@ -148,11 +148,19 @@ GEM
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.31.2)
       parser (>= 3.3.0.4)
-    ruby-openai (8.1.0)
-      event_stream_parser (>= 0.3.0, < 2.0.0)
-      faraday (>= 1)
-      faraday-multipart (>= 1)
     ruby-progressbar (1.13.0)
+    ruby_llm (1.14.0)
+      base64
+      event_stream_parser (~> 1)
+      faraday (>= 1.10.0)
+      faraday-multipart (>= 1)
+      faraday-net_http (>= 1)
+      faraday-retry (>= 1)
+      marcel (~> 1)
+      ruby_llm-schema (~> 0)
+      zeitwerk (~> 2)
+    ruby_llm-schema (0.2.5)
+    securerandom (0.4.1)
     shellany (0.0.1)
     solargraph (0.50.0)
       backport (~> 1.2)
@@ -210,6 +218,7 @@ GEM
     yard-sorbet (0.8.1)
       sorbet-runtime (>= 0.5)
       yard (>= 0.9)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-21

data/README.md

@@ -6,7 +6,7 @@ Raix (pronounced "ray" because the x is silent) is a library that gives you ever
 
 Understanding how to use discrete AI components in otherwise normal code is key to productively leveraging Raix, and the subject of a book written by Raix's author Obie Fernandez, titled [Patterns of Application Development Using AI](https://leanpub.com/patterns-of-application-development-using-ai). You can easily support the ongoing development of this project by buying the book at Leanpub.
 
-At the moment, Raix natively supports use of either OpenAI or OpenRouter as its underlying AI provider. Eventually you will be able to specify your AI provider via an adapter, kind of like ActiveRecord maps to databases. Note that you can also use Raix to add AI capabilities to non-Rails applications as long as you include ActiveSupport as a dependency. Extracting the base code to its own standalone library without Rails dependencies is on the roadmap, but not a high priority.
+Raix 2.0 is powered by [RubyLLM](https://github.com/crmne/ruby_llm), giving you unified access to OpenAI, Anthropic, Google Gemini, and dozens of other providers through OpenRouter. Note that you can use Raix to add AI capabilities to non-Rails applications as long as you include ActiveSupport as a dependency.
 
 ### Chat Completions
 
@@ -105,6 +105,148 @@ When using JSON mode with non-OpenAI providers, Raix automatically sets the `req
 => { "key": "value" }
 ```
 
+### before_completion Hook
+
+The `before_completion` hook lets you intercept and modify chat completion requests before they're sent to the AI provider. This is useful for dynamic parameter resolution, logging, content filtering, PII redaction, and more.
+
+#### Configuration Levels
+
+Hooks can be configured at three levels, with later levels overriding earlier ones:
+
+```ruby
+# Global level - applies to all chat completions
+Raix.configure do |config|
+  config.before_completion = ->(context) {
+    # Return a hash of params to merge, or modify context.messages directly
+    { temperature: 0.7 }
+  }
+end
+
+# Class level - applies to all instances of a class
+class MyAssistant
+  include Raix::ChatCompletion
+
+  configure do |config|
+    config.before_completion = ->(context) { { model: "gpt-4o" } }
+  end
+end
+
+# Instance level - applies to a single instance
+assistant = MyAssistant.new
+assistant.before_completion = ->(context) { { max_tokens: 500 } }
+```
+
+When hooks exist at multiple levels, they're called in order (global → class → instance), with returned params merged together. Later hooks override earlier ones for the same parameter.
+
+#### The CompletionContext Object
+
+Hooks receive a `CompletionContext` object with access to:
+
+```ruby
+context.chat_completion       # The ChatCompletion instance
+context.messages              # Array of messages (mutable, in OpenAI format)
+context.params                # Hash of params (mutable)
+context.transcript            # The instance's transcript
+context.current_model         # Currently configured model
+context.chat_completion_class # The class including ChatCompletion
+context.configuration         # The instance's configuration
+```
+
+#### Use Cases
+
+**Dynamic model selection from database:**
+
+```ruby
+Raix.configure do |config|
+  config.before_completion = ->(context) {
+    settings = TenantSettings.find_by(tenant: Current.tenant)
+    {
+      model: settings.preferred_model,
+      temperature: settings.temperature,
+      max_tokens: settings.max_tokens
+    }
+  }
+end
+```
+
+**PII redaction:**
+
+```ruby
+class SecureAssistant
+  include Raix::ChatCompletion
+
+  before_completion = ->(context) {
+    context.messages.each do |msg|
+      next unless msg[:content].is_a?(String)
+      # Redact SSN patterns
+      msg[:content] = msg[:content].gsub(/\d{3}-\d{2}-\d{4}/, "[SSN REDACTED]")
+      # Redact email addresses
+      msg[:content] = msg[:content].gsub(/[\w.-]+@[\w.-]+\.\w+/, "[EMAIL REDACTED]")
+    end
+    {} # Return empty hash if not modifying params
+  }
+end
+```
+
+**Request logging:**
+
+```ruby
+Raix.configure do |config|
+  config.before_completion = ->(context) {
+    Rails.logger.info({
+      event: "chat_completion_request",
+      model: context.current_model,
+      message_count: context.messages.length,
+      params: context.params.except(:messages)
+    }.to_json)
+    {} # Return empty hash, just logging
+  }
+end
+```
+
+**Adding system prompts:**
+
+```ruby
+assistant.before_completion = ->(context) {
+  context.messages.unshift({
+    role: "system",
+    content: "Always be helpful and respectful."
+  })
+  {}
+}
+```
+
+**A/B testing models:**
+
+```ruby
+Raix.configure do |config|
+  config.before_completion = ->(context) {
+    if Flipper.enabled?(:new_model, Current.user)
+      { model: "gpt-4o" }
+    else
+      { model: "gpt-4o-mini" }
+    end
+  }
+end
+```
+
+Hooks can also be any object that responds to `#call`:
+
+```ruby
+class CostTracker
+  def call(context)
+    # Track estimated cost based on message length
+    estimated_tokens = context.messages.sum { |m| m[:content].to_s.length / 4 }
+    StatsD.gauge("ai.estimated_input_tokens", estimated_tokens)
+    {}
+  end
+end
+
+Raix.configure do |config|
+  config.before_completion = CostTracker.new
+end
+```
+
 ### 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 in a declarative, Rails-like "DSL" fashion.
@@ -711,49 +853,63 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install raix
 
-If you are using the default OpenRouter API, Raix expects `Raix.configuration.openrouter_client` to initialized with the OpenRouter API client instance.
+### Configuration
 
-You can add an initializer to your application's `config/initializers` directory that looks like this example (setting up both providers, OpenRouter and OpenAI):
+Raix 2.0 uses [RubyLLM](https://github.com/crmne/ruby_llm) as its backend for LLM provider connections. Configure your API keys through RubyLLM:
 
 ```ruby
-  # config/initializers/raix.rb
-  OpenRouter.configure do |config|
-    config.faraday do |f|
-      f.request :retry, retry_options
-      f.response :logger, Logger.new($stdout), { headers: true, bodies: true, errors: true } do |logger|
-        logger.filter(/(Bearer) (\S+)/, '\1[REDACTED]')
-      end
-    end
-  end
-
-  Raix.configure do |config|
-    config.openrouter_client = OpenRouter::Client.new(access_token: ENV.fetch("OR_ACCESS_TOKEN", nil))
-    config.openai_client = OpenAI::Client.new(access_token: ENV.fetch("OAI_ACCESS_TOKEN", nil)) do |f|
-      f.request :retry, retry_options
-      f.response :logger, Logger.new($stdout), { headers: true, bodies: true, errors: true } do |logger|
-        logger.filter(/(Bearer) (\S+)/, '\1[REDACTED]')
-      end
-    end
-  end
+# config/initializers/raix.rb
+RubyLLM.configure do |config|
+  config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  # Optional: configure other providers
+  # config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  # config.gemini_api_key = ENV["GEMINI_API_KEY"]
+end
 ```
 
-You will also need to configure the OpenRouter API access token as per the instructions here: https://github.com/OlympiaAI/open_router?tab=readme-ov-file#quickstart
+Raix will automatically use the appropriate provider based on the model name:
+- Models starting with `gpt-` or `o1` use OpenAI directly
+- All other models route through OpenRouter
 
-### Global vs class level configuration
+### Global vs Class-Level Configuration
 
-You can either configure Raix globally or at the class level. The global configuration is set in the initializer as shown above. You can however also override all configuration options of the `Configuration` class on the class level with the
-same syntax:
+You can configure Raix options globally or at the class level:
 
 ```ruby
-class MyClass
+# Global configuration
+Raix.configure do |config|
+  config.temperature = 0.7
+  config.max_tokens = 1000
+  config.model = "gpt-4o"
+  config.max_tool_calls = 25
+end
+
+# Class-level configuration (overrides global)
+class MyAssistant
   include Raix::ChatCompletion
 
   configure do |config|
-    config.openrouter_client = OpenRouter::Client.new # with my special options
+    config.model = "anthropic/claude-3-opus"
+    config.temperature = 0.5
   end
 end
 ```
 
+### Upgrading from Raix 1.x
+
+If upgrading from Raix 1.x, update your configuration from:
+
+```ruby
+# Old 1.x configuration
+Raix.configure do |config|
+  config.openrouter_client = OpenRouter::Client.new(access_token: "...")
+  config.openai_client = OpenAI::Client.new(access_token: "...")
+end
+```
+
+To the new RubyLLM-based configuration shown above.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/raix/chat_completion.rb

@@ -3,10 +3,8 @@
 require "active_support/concern"
 require "active_support/core_ext/object/blank"
 require "active_support/core_ext/string/filters"
-require "open_router"
-require "openai"
-
-require_relative "message_adapters/base"
+require "active_support/core_ext/hash/indifferent_access"
+require "ruby_llm"
 
 module Raix
   class UndeclaredToolError < StandardError; end
@@ -40,10 +38,10 @@ module Raix
   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_tool_calls, :stop_tool_calls_and_respond
+    attr_accessor :before_completion, :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_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.
@@ -142,12 +140,12 @@ module Raix
       messages = messages.map { |msg| adapter.transform(msg) }.dup
       raise "Can't complete an empty transcript" if messages.blank?
 
+      # Run before_completion hooks (global -> class -> instance)
+      # Hooks can modify params and messages for logging, filtering, PII redaction, etc.
+      run_before_completion_hooks(params, messages)
+
       begin
-        response = if openai
-                     openai_request(params:, model: openai, messages:)
-                   else
-                     openrouter_request(params:, model:, messages:)
-                   end
+        response = ruby_llm_request(params:, model: openai || model, messages:, openai_override: openai)
         retry_count = 0
         content = nil
 
@@ -155,7 +153,7 @@ module Raix
         return if stream && response.blank?
 
         # tuck the full response into a thread local in case needed
-        Thread.current[:chat_completion_response] = response.with_indifferent_access
+        Thread.current[:chat_completion_response] = response.is_a?(Hash) ? response.with_indifferent_access : response
 
         # TODO: add a standardized callback hook for usage events
         # broadcast(:usage_event, usage_subject, self.class.name.to_s, response, premium?)
@@ -171,11 +169,7 @@ module Raix
 
             # 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
+            response = ruby_llm_request(params:, model: openai || model, messages:, openai_override: openai)
 
             # Process the final response
             content = response.dig("choices", 0, "message", "content")
@@ -217,11 +211,7 @@ module Raix
           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
+            response = ruby_llm_request(params:, model: openai || model, messages:, openai_override: openai)
 
             content = response.dig("choices", 0, "message", "content")
             transcript << { assistant: content } if save_response
@@ -279,7 +269,23 @@ module Raix
     #
     # @return [Array] The transcript array.
     def transcript
-      @transcript ||= []
+      @transcript ||= TranscriptAdapter.new(ruby_llm_chat)
+    end
+
+    # Returns the RubyLLM::Chat instance for this conversation
+    def ruby_llm_chat
+      @ruby_llm_chat ||= begin
+        model_id = model || configuration.model
+
+        # Determine provider based on model format or explicit openai flag
+        provider = if model_id.to_s.start_with?("openai/") || model_id.to_s.match?(/^gpt-/)
+                     :openai
+                   else
+                     :openrouter
+                   end
+
+        RubyLLM.chat(model: model_id, provider:, assume_model_exists: true)
+      end
     end
 
     # Dispatches a tool function call with the given function name and arguments.
@@ -307,42 +313,121 @@ module Raix
       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)
-      else
-        params[:max_completion_tokens] ||= params[:max_tokens]
-        params.delete(:max_tokens)
-      end
+    def run_before_completion_hooks(params, messages)
+      hooks = [
+        Raix.configuration.before_completion,
+        self.class.configuration.before_completion,
+        before_completion
+      ].compact
 
-      params[:stream] ||= stream.presence
-      params[:stream_options] = { include_usage: true } if params[:stream]
+      return if hooks.empty?
 
-      params.delete(:temperature) if model.start_with?("o") || model.include?("gpt-5")
+      context = CompletionContext.new(
+        chat_completion: self,
+        messages:,
+        params:
+      )
 
-      configuration.openai_client.chat(parameters: params.compact.merge(model:, messages:))
+      hooks.each do |hook|
+        result = hook.call(context) if hook.respond_to?(:call)
+        next unless result.is_a?(Hash)
+
+        # Handle model separately since it's passed as a keyword arg to ruby_llm_request
+        self.model = result[:model] if result.key?(:model)
+        params.merge!(result.compact)
+      end
     end
 
-    def openrouter_request(params:, model:, messages:)
-      # max_completion_tokens is not supported by OpenRouter
-      params.delete(:max_completion_tokens)
+    def ruby_llm_request(params:, model:, messages:, openai_override: nil)
+      # Create a temporary chat instance for this request
+      provider = determine_provider(model, openai_override)
+      chat = RubyLLM.chat(model:, provider:, assume_model_exists: true)
+
+      # Apply messages to the chat
+      # Track if we have a user message to determine how to call ask
+      has_user_message = false
+
+      messages.each do |msg|
+        role = msg[:role] || msg["role"]
+        content = msg[:content] || msg["content"]
+
+        case role.to_s
+        when "system"
+          chat.with_instructions(content)
+        when "user"
+          has_user_message = true
+          chat.add_message(role: :user, content:)
+        when "assistant"
+          if msg[:tool_calls] || msg["tool_calls"]
+            chat.add_message(role: :assistant, content:, tool_calls: msg[:tool_calls] || msg["tool_calls"])
+          else
+            chat.add_message(role: :assistant, content:)
+          end
+        when "tool"
+          chat.add_message(
+            role: :tool,
+            content:,
+            tool_call_id: msg[:tool_call_id] || msg["tool_call_id"]
+          )
+        end
+      end
 
-      retry_count = 0
+      # Apply configuration parameters
+      chat.with_temperature(params[:temperature]) if params[:temperature]
 
-      params.delete(:temperature) if model.start_with?("openai/o") || model.include?("gpt-5")
+      # Apply additional params (RubyLLM with_params expects keyword args)
+      additional_params = params.compact.except(:temperature, :tools, :max_tokens, :max_completion_tokens)
+      chat.with_params(**additional_params) if additional_params.any?
 
-      begin
-        configuration.openrouter_client.complete(messages, model:, extras: params.compact, stream:)
-      rescue OpenRouter::ServerError => e
-        if e.message.include?("retry")
-          warn "Retrying OpenRouter request... (#{retry_count} attempts) #{e.message}"
-          retry_count += 1
-          sleep 1 * retry_count # backoff
-          retry if retry_count < 5
-        end
+      # Handle tools - convert Raix function declarations to RubyLLM tools
+      if params[:tools].present? && respond_to?(:class) && self.class.respond_to?(:functions)
+        ruby_llm_tools = FunctionToolAdapter.convert_tools_for_ruby_llm(self)
+        ruby_llm_tools.each { |tool| chat.with_tool(tool) }
+      end
 
-        raise e
+      # Execute the completion
+      if stream.present?
+        # Streaming mode
+        if has_user_message
+          chat.complete(&stream)
+        else
+          chat.ask(&stream)
+        end
+        nil # Return nil for streaming as per original behavior
+      else
+        # Non-streaming mode - return OpenAI-compatible response format
+        response_message = has_user_message ? chat.complete : chat.ask
+
+        # Convert RubyLLM response to OpenAI format for compatibility
+        {
+          "choices" => [
+            {
+              "message" => {
+                "role" => "assistant",
+                "content" => response_message.content,
+                "tool_calls" => response_message.tool_calls
+              },
+              "finish_reason" => response_message.tool_call? ? "tool_calls" : "stop"
+            }
+          ],
+          "usage" => {
+            "prompt_tokens" => response_message.input_tokens,
+            "completion_tokens" => response_message.output_tokens,
+            "total_tokens" => (response_message.input_tokens || 0) + (response_message.output_tokens || 0)
+          }
+        }
       end
+    rescue StandardError => e
+      warn "RubyLLM request failed: #{e.message}"
+      raise e
+    end
+
+    def determine_provider(model, openai_override)
+      return :openai if openai_override
+      return :openai if model.to_s.match?(/^gpt-/) || model.to_s.match?(/^o\d/)
+
+      # Default to openrouter for model IDs with provider prefix
+      :openrouter
     end
   end
 end

data/lib/raix/completion_context.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Raix
+  # Context object passed to before_completion hooks.
+  # Provides access to the chat completion instance, messages, and request parameters.
+  # Messages can be mutated for content filtering, PII redaction, etc.
+  class CompletionContext
+    attr_reader :chat_completion, :messages, :params
+
+    def initialize(chat_completion:, messages:, params:)
+      @chat_completion = chat_completion
+      @messages = messages # mutable - hooks can modify for filtering, redaction, etc.
+      @params = params # mutable - hooks can modify parameters
+    end
+
+    # Convenience accessor for the transcript
+    def transcript
+      chat_completion.transcript
+    end
+
+    # Get the currently configured model
+    def current_model
+      chat_completion.model || chat_completion.configuration.model
+    end
+
+    # Get the class that includes ChatCompletion
+    def chat_completion_class
+      chat_completion.class
+    end
+
+    # Get the current configuration
+    def configuration
+      chat_completion.configuration
+    end
+  end
+end

data/lib/raix/configuration.rb

@@ -30,16 +30,24 @@ module Raix
     # is normally set in each class that includes the ChatCompletion module.
     attr_accessor_with_fallback :model
 
-    # The openrouter_client option determines the default client to use for communication.
+    # DEPRECATED: Use ruby_llm_config.openrouter_api_key instead
     attr_accessor_with_fallback :openrouter_client
 
-    # The openai_client option determines the OpenAI client to use for communication.
+    # DEPRECATED: Use ruby_llm_config.openai_api_key instead
     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
 
+    # Access to RubyLLM configuration
+    attr_accessor_with_fallback :ruby_llm_config
+
+    # A callable hook that runs before each chat completion request.
+    # Receives a CompletionContext and can modify params and messages.
+    # Use for: dynamic parameter resolution, logging, content filtering, PII redaction, etc.
+    attr_accessor_with_fallback :before_completion
+
     DEFAULT_MAX_TOKENS = 1000
     DEFAULT_MAX_COMPLETION_TOKENS = 16_384
     DEFAULT_MODEL = "meta-llama/llama-3.3-8b-instruct:free"
@@ -53,11 +61,18 @@ module Raix
       self.max_tokens = DEFAULT_MAX_TOKENS
       self.model = DEFAULT_MODEL
       self.max_tool_calls = DEFAULT_MAX_TOOL_CALLS
+      self.ruby_llm_config = RubyLLM.config
       self.fallback = fallback
     end
 
     def client?
-      !!(openrouter_client || openai_client)
+      # Support legacy openrouter_client/openai_client or new RubyLLM config
+      !!(openrouter_client || openai_client || ruby_llm_configured?)
+    end
+
+    def ruby_llm_configured?
+      ruby_llm_config&.openai_api_key || ruby_llm_config&.openrouter_api_key ||
+        ruby_llm_config&.anthropic_api_key || ruby_llm_config&.gemini_api_key
     end
 
     private

data/lib/raix/function_tool_adapter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Raix
+  # Adapter to convert Raix function declarations to RubyLLM::Tool instances
+  class FunctionToolAdapter
+    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:
+        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
+        define_method(:execute) do |**args|
+          raix_instance.public_send(raix_function_name, args.with_indifferent_access, nil)
+        end
+      end
+
+      # Set a meaningful name for the tool class
+      tool_class.define_singleton_method(:name) do
+        "Raix::GeneratedTool::#{function_def[:name].to_s.camelize}"
+      end
+
+      tool_instance = tool_class.new
+
+      # Override the name method to return the original function name
+      # This ensures RubyLLM can match the tool call from the AI
+      tool_instance.define_singleton_method(:name) do
+        function_def[:name].to_s
+      end
+
+      tool_instance
+    end
+
+    def self.convert_tools_for_ruby_llm(raix_instance)
+      return [] unless raix_instance.class.respond_to?(:functions)
+      return [] if raix_instance.class.functions.blank?
+
+      raix_instance.class.functions.map do |function_def|
+        create_tool_from_function(function_def, raix_instance)
+      end
+    end
+  end
+end

data/lib/{mcp → raix/mcp}/sse_client.rb

@@ -1,4 +1,3 @@
-require_relative "tool"
 require "json"
 require "securerandom"
 require "faraday"
@@ -138,7 +137,7 @@ module Raix
       # Process SSE buffer for complete events
       def process_sse_buffer
         while (idx = @buffer.index("\n\n"))
-          event_text = @buffer.slice!(0..idx + 1)
+          event_text = @buffer.slice!(0..(idx + 1))
           event_type, event_data = parse_sse_fields(event_text)
 
           case event_type

data/lib/{mcp → raix/mcp}/stdio_client.rb

@@ -1,4 +1,3 @@
-require_relative "tool"
 require "json"
 require "securerandom"
 require "digest"

data/lib/raix/mcp.rb

@@ -16,9 +16,6 @@ require "active_support/inflector"
 require "securerandom"
 require "uri"
 
-require_relative "../mcp/sse_client"
-require_relative "../mcp/stdio_client"
-
 module Raix
   # Model Context Protocol integration for Raix
   #

data/lib/raix/transcript_adapter.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Raix
+  # Adapter to convert between Raix's transcript array format and RubyLLM's Message objects
+  class TranscriptAdapter
+    attr_reader :ruby_llm_chat
+
+    def initialize(ruby_llm_chat)
+      @ruby_llm_chat = ruby_llm_chat
+      @pending_messages = []
+    end
+
+    # Add a message in Raix format (hash) to the transcript
+    def <<(message_hash)
+      case message_hash
+      when Array
+        # Handle nested arrays (from function dispatch)
+        message_hash.each { |msg| self << msg }
+      when Hash
+        add_message_from_hash(message_hash)
+      end
+      self
+    end
+
+    # Return all messages in Raix-compatible format
+    def flatten
+      ruby_llm_messages = @ruby_llm_chat.messages.map { |msg| message_to_raix_format(msg) }
+      pending = @pending_messages.map { |msg| normalize_message_format(msg) }
+      (ruby_llm_messages + pending).flatten
+    end
+
+    # Get all messages including pending ones
+    def to_a
+      flatten
+    end
+
+    # Allow iteration
+    def compact
+      flatten.compact
+    end
+
+    # Clear all messages
+    def clear
+      @ruby_llm_chat.reset_messages!
+      @pending_messages.clear
+      self
+    end
+
+    # Get last message
+    def last
+      flatten.last
+    end
+
+    # Get size of transcript
+    def size
+      flatten.size
+    end
+
+    alias length size
+
+    private
+
+    def add_message_from_hash(hash)
+      # Raix abbreviated format: { system: "text" }, { user: "text" }, { assistant: "text" }
+      if hash.key?(:system) || hash.key?("system")
+        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"]
+        # Don't add to ruby_llm_chat yet - wait for chat_completion call
+        @pending_messages << { role: "user", content: }
+      elsif hash.key?(:assistant) || hash.key?("assistant")
+        content = hash[:assistant] || hash["assistant"]
+        @pending_messages << { role: "assistant", content: }
+      elsif hash[:role] || hash["role"]
+        # Standard OpenAI format (tool messages, assistant with tool_calls, etc.)
+        @pending_messages << hash.with_indifferent_access
+      end
+    end
+
+    def message_to_raix_format(message)
+      # Return in Raix abbreviated format { system: "...", user: "...", assistant: "..." }
+      # unless it's a tool message which needs full format
+      if message.tool_call? || message.tool_result?
+        result = {
+          role: message.role.to_s,
+          content: message.content
+        }
+        result[:tool_calls] = message.tool_calls if message.tool_call?
+        result[:tool_call_id] = message.tool_call_id if message.tool_result?
+        result
+      else
+        # Use abbreviated format
+        { message.role.to_sym => message.content }
+      end
+    end
+
+    def normalize_message_format(msg)
+      # If already in abbreviated format, return as-is
+      return msg if msg.key?(:system) || msg.key?(:user) || msg.key?(:assistant)
+      return msg if msg["system"] || msg["user"] || msg["assistant"]
+
+      # If in standard format with role/content, convert to abbreviated
+      if msg[:role] || msg["role"]
+        role = (msg[:role] || msg["role"]).to_sym
+        content = msg[:content] || msg["content"]
+
+        # Tool messages stay in full format
+        if msg[:tool_calls] || msg["tool_calls"] || msg[:tool_call_id] || msg["tool_call_id"]
+          return msg
+        end
+
+        # Convert to abbreviated format
+        { role => content }
+      else
+        msg
+      end
+    end
+  end
+end

data/lib/raix/version.rb

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

data/lib/raix.rb

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "raix/version"
-require_relative "raix/configuration"
-require_relative "raix/chat_completion"
-require_relative "raix/function_dispatch"
-require_relative "raix/prompt_declarations"
-require_relative "raix/predicate"
-require_relative "raix/response_format"
-require_relative "raix/mcp"
+require "ruby_llm"
+require "zeitwerk"
 
-# The Raix module provides configuration options for the Raix gem.
+# Ruby AI eXtensions
 module Raix
   class << self
     attr_writer :configuration
@@ -25,3 +19,7 @@ module Raix
     yield(configuration)
   end
 end
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("mcp" => "MCP")
+loader.setup

data/raix.gemspec

@@ -30,7 +30,7 @@ Gem::Specification.new do |spec|
 
   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", "~> 8.1"
+  spec.add_dependency "ruby_llm", "~> 1.9"
+  spec.add_dependency "zeitwerk", "~> 2.7"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 2.0.1
 platform: ruby
 authors:
 - Obie Fernandez
 bindir: exe
 cert_chain: []
-date: 2025-08-08 00:00:00.000000000 Z
+date: 2026-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -38,47 +38,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: open_router
+  name: ostruct
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: ostruct
+  name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
-  name: ruby-openai
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '2.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '2.7'
 email:
 - obiefernandez@gmail.com
 executables: []
@@ -98,18 +98,21 @@ files:
 - README.llm
 - README.md
 - Rakefile
-- lib/mcp/sse_client.rb
-- lib/mcp/stdio_client.rb
-- lib/mcp/tool.rb
 - lib/raix.rb
 - lib/raix/chat_completion.rb
+- lib/raix/completion_context.rb
 - lib/raix/configuration.rb
 - lib/raix/function_dispatch.rb
+- lib/raix/function_tool_adapter.rb
 - lib/raix/mcp.rb
+- lib/raix/mcp/sse_client.rb
+- lib/raix/mcp/stdio_client.rb
+- lib/raix/mcp/tool.rb
 - lib/raix/message_adapters/base.rb
 - lib/raix/predicate.rb
 - lib/raix/prompt_declarations.rb
 - lib/raix/response_format.rb
+- lib/raix/transcript_adapter.rb
 - lib/raix/version.rb
 - raix.gemspec
 - sig/raix.rbs