Raix 2.0.0 - RubyLLM backend and before_completion hook

Breaking Changes:
- Migrated from OpenRouter/OpenAI gems to RubyLLM for unified multi-provider support
- API keys now configured through RubyLLM instead of separate client instances

New Features:
- Added before_completion hook for intercepting/modifying requests
  - Supports global, class, and instance-level configuration
  - Enables dynamic params, logging, PII redaction, content filtering
- Added CompletionContext for hook access to messages and params
- Added FunctionToolAdapter and TranscriptAdapter for RubyLLM integration

Documentation:
- Updated README with RubyLLM configuration and before_completion examples
- Added migration guide for upgrading from 1.x

Author: obie

CHANGELOG.md

@@ -1,3 +1,44 @@
+## [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

Gemfile.lock

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

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.

lib/raix.rb

@@ -2,8 +2,9 @@
 
 require "ruby_llm"
 
-require_relative "raix/version"
+require_relative "raix/completion_context"
 require_relative "raix/configuration"
+require_relative "raix/version"
 require_relative "raix/transcript_adapter"
 require_relative "raix/function_tool_adapter"
 require_relative "raix/chat_completion"

lib/raix/chat_completion.rb

@@ -42,10 +42,10 @@ class UndeclaredToolError < StandardError; end
   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.
@@ -144,6 +144,10 @@ def chat_completion(params: {}, loop: false, json: false, raw: false, openai: ni
       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 = ruby_llm_request(params:, model: openai || model, messages:, openai_override: openai)
         retry_count = 0
@@ -313,6 +317,31 @@ def filtered_tools(tool_names)
       tools.select { |tool| requested_tools.include?(tool.dig(:function, :name).to_sym) }
     end
 
+    def run_before_completion_hooks(params, messages)
+      hooks = [
+        Raix.configuration.before_completion,
+        self.class.configuration.before_completion,
+        before_completion
+      ].compact
+
+      return if hooks.empty?
+
+      context = CompletionContext.new(
+        chat_completion: self,
+        messages:,
+        params:
+      )
+
+      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 ruby_llm_request(params:, model:, messages:, openai_override: nil)
       # Create a temporary chat instance for this request
       provider = determine_provider(model, openai_override)