rebase on main

Author: OriPekelman

.rubocop.yml

@@ -7,4 +7,15 @@ AllCops:
   TargetRubyVersion: 3.1
   Exclude:
     - docs/**/*
-    - vendor/**/*
+    - vendor/**/*
+
+Metrics/ClassLength:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/ModuleLength:
+  Enabled: false

docs/configuration.md

@@ -27,6 +27,7 @@ After reading this guide, you will know:
 *   How to customize connection timeouts and retries.
 *   How to connect to custom endpoints (like Azure OpenAI).
 *   How to use temporary, scoped configurations with `RubyLLM.context`.
+*   How to configure the logging location.
 
 ## Global Configuration (`RubyLLM.configure`)
 
@@ -75,6 +76,10 @@ RubyLLM.configure do |config|
   config.retry_interval = 0.1 # Initial delay in seconds (default: 0.1)
   config.retry_backoff_factor = 2 # Multiplier for subsequent retries (default: 2)
   config.retry_interval_randomness = 0.5 # Jitter factor (default: 0.5)
+
+  # --- Logging Settings ---
+  config.log_file = '/logs/ruby_llm.log'
+  config.level = :debug # debug level can also be set to debug by setting RUBYLLM_DEBUG envar to true
 end
 ```
 
@@ -134,6 +139,31 @@ Fine-tune how RubyLLM handles HTTP connections and retries.
 
 Adjust these based on network conditions and provider reliability.
 
+## Logging Settings
+
+RubyLLM provides flexible logging configuration to help you monitor and debug API interactions. You can configure both the log file location and the logging level.
+
+```ruby
+RubyLLM.configure do |config|
+  # --- Logging Settings ---
+  config.log_file = '/logs/ruby_llm.log'  # Path to log file (default: nil, logs to STDOUT)
+  config.level = :debug  # Log level (:debug, :info, :warn)
+end
+```
+
+### Log File Configuration
+
+* `config.log_file`: Specifies the path where logs should be written. If not set, logs will be written to STDOUT.
+* The log file will be created if it doesn't exist, and logs will be appended to it.
+
+### Log Levels
+
+* `:debug`: Most verbose level, includes detailed request/response information as provided by the faraday client
+* `:info`: General operational information
+* `:warn`: Warning messages for non-critical issues that may need attention
+
+You can also set the debug level by setting the `RUBYLLM_DEBUG` environment variable to `true`.
+
 ## Scoped Configuration with Contexts
 {: .d-inline-block }
 
@@ -178,4 +208,5 @@ default_response = default_chat.ask("Query using global production settings...")
 *   **Isolation:** Modifying configuration within a context block does **not** affect the global `RubyLLM.config`.
 *   **Thread Safety:** Each context is independent, making them safe for use across different threads.
 
-Contexts provide a clean and safe mechanism for managing diverse configuration needs within a single application.
+Contexts provide a clean and safe mechanism for managing diverse configuration needs within a single application.
+

docs/guides/available-models.md

@@ -90,7 +90,7 @@ claude3_sonnet_family = RubyLLM.models.by_family('claude3_sonnet')
 
 # Chain filters and use Enumerable methods
 openai_vision_models = RubyLLM.models.by_provider(:openai)
-                                   .select(&:supports_vision)
+                                   .select(&:supports_vision?)
 
 puts "Found #{openai_vision_models.count} OpenAI vision models."
 ```

docs/guides/models.md

@@ -68,9 +68,9 @@ def config
 
     def logger
       @logger ||= Logger.new(
-        $stdout,
+        config.log_file,
         progname: 'RubyLLM',
-        level: ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
+        level: config.log_level
       )
     end
   end

lib/ruby_llm.rb

@@ -24,32 +24,46 @@ def acts_as_chat(message_class: 'Message', tool_call_class: 'ToolCall')
                    to: :to_llm
         end
 
-        def acts_as_message(chat_class: 'Chat', tool_call_class: 'ToolCall', touch_chat: false) # rubocop:disable Metrics/MethodLength
+        def acts_as_message(chat_class: 'Chat', tool_call_class: 'ToolCall', **options)
           include MessageMethods
 
           @chat_class = chat_class.to_s
+          @chat_foreign_key = options[:chat_foreign_key] || @chat_class.foreign_key
           @tool_call_class = tool_call_class.to_s
+          @tool_call_foreign_key = options[:tool_call_foreign_key] || @tool_call_class.foreign_key
 
-          belongs_to :chat, class_name: @chat_class, touch: touch_chat
-          has_many :tool_calls, class_name: @tool_call_class, dependent: :destroy
+          belongs_to :chat,
+                     class_name: @chat_class,
+                     foreign_key: @chat_foreign_key,
+                     inverse_of: :messages,
+                     touch: options[:touch_chat]
+
+          has_many :tool_calls,
+                   class_name: @tool_call_class,
+                   dependent: :destroy
 
           belongs_to :parent_tool_call,
                      class_name: @tool_call_class,
-                     foreign_key: 'tool_call_id',
+                     foreign_key: @tool_call_foreign_key,
                      optional: true,
                      inverse_of: :result
 
           delegate :tool_call?, :tool_result?, :tool_results, to: :to_llm
         end
 
-        def acts_as_tool_call(message_class: 'Message')
+        def acts_as_tool_call(message_class: 'Message', **options)
           @message_class = message_class.to_s
+          @message_foreign_key = options[:message_foreign_key] || @message_class.foreign_key
+          @result_foreign_key = options[:result_foreign_key] || 'id'
 
-          belongs_to :message, class_name: @message_class
+          belongs_to :message,
+                     class_name: @message_class,
+                     foreign_key: @message_foreign_key,
+                     inverse_of: :tool_calls
 
           has_one :result,
                   class_name: @message_class,
-                  foreign_key: 'tool_call_id',
+                  foreign_key: @result_foreign_key,
                   inverse_of: :parent_tool_call,
                   dependent: :nullify
         end
@@ -67,6 +81,7 @@ module ChatMethods
 
       def to_llm
         @chat ||= RubyLLM.chat(model: model_id)
+        @chat.reset_messages!
 
         # Load existing messages into chat
         messages.each do |msg|
@@ -150,22 +165,23 @@ def persist_new_message
         )
       end
 
-      def persist_message_completion(message) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      def persist_message_completion(message)
         return unless message
 
         if message.tool_call_id
           tool_call_id = self.class.tool_call_class.constantize.find_by(tool_call_id: message.tool_call_id).id
         end
 
         transaction do
-          @message.update!(
+          @message.update(
             role: message.role,
             content: message.content,
             model_id: message.model_id,
-            tool_call_id: tool_call_id,
             input_tokens: message.input_tokens,
             output_tokens: message.output_tokens
           )
+          @message.write_attribute(@message.class.tool_call_foreign_key, tool_call_id) if tool_call_id
+          @message.save!
           persist_tool_calls(message.tool_calls) if message.tool_calls.present?
         end
       end
@@ -184,6 +200,11 @@ def persist_tool_calls(tool_calls)
     module MessageMethods
       extend ActiveSupport::Concern
 
+      class_methods do
+        attr_reader :chat_class, :tool_call_class
+        attr_reader :chat_foreign_key, :tool_call_foreign_key
+      end
+
       def to_llm
         RubyLLM::Message.new(
           role: role.to_sym,

lib/ruby_llm/active_record/acts_as.rb

@@ -8,12 +8,12 @@ module RubyLLM
   #   chat = RubyLLM.chat
   #   chat.ask "What's the best way to learn Ruby?"
   #   chat.ask "Can you elaborate on that?"
-  class Chat # rubocop:disable Metrics/ClassLength
+  class Chat
     include Enumerable
 
     attr_reader :model, :messages, :tools
 
-    def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil) # rubocop:disable Metrics/MethodLength
+    def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
       if assume_model_exists && !provider
         raise ArgumentError, 'Provider must be specified if assume_model_exists is true'
       end
@@ -46,7 +46,7 @@ def with_instructions(instructions, replace: false)
     end
 
     def with_tool(tool)
-      unless @model.supports_functions
+      unless @model.supports_functions?
         raise UnsupportedFunctionsError, "Model #{@model.id} doesn't support function calling"
       end
 
@@ -84,7 +84,7 @@ def each(&)
       messages.each(&)
     end
 
-    def complete(&) # rubocop:disable Metrics/MethodLength
+    def complete(&)
       @on[:new_message]&.call
       response = @provider.complete(
         messages,
@@ -110,6 +110,10 @@ def add_message(message_or_attributes)
       message
     end
 
+    def reset_messages!
+      @messages.clear
+    end
+
     private
 
     def handle_tool_calls(response, &)

lib/ruby_llm/chat.rb

@@ -33,7 +33,10 @@ class Configuration
                   :max_retries,
                   :retry_interval,
                   :retry_backoff_factor,
-                  :retry_interval_randomness
+                  :retry_interval_randomness,
+                  # Logging configuration
+                  :log_file,
+                  :log_level
 
     def initialize
       # Connection configuration
@@ -47,9 +50,13 @@ def initialize
       @default_model = 'gpt-4.1-nano'
       @default_embedding_model = 'text-embedding-3-small'
       @default_image_model = 'dall-e-3'
+
+      # Logging configuration
+      @log_file = $stdout
+      @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
     end
 
-    def inspect # rubocop:disable Metrics/MethodLength
+    def inspect
       redacted = lambda do |name, value|
         if name.match?(/_key|_secret|_token$/)
           value.nil? ? 'nil' : '[FILTERED]'

lib/ruby_llm/configuration.rb

@@ -65,7 +65,7 @@ def setup_middleware(faraday)
       faraday.use :llm_errors, provider: @provider
     end
 
-    def retry_exceptions # rubocop:disable Metrics/MethodLength
+    def retry_exceptions
       [
         Errno::ETIMEDOUT,
         Timeout::Error,

lib/ruby_llm/connection.rb

@@ -12,15 +12,16 @@ def initialize(vectors:, model:, input_tokens: 0)
       @input_tokens = input_tokens
     end
 
-    def self.embed(text, # rubocop:disable Metrics/ParameterLists,Metrics/CyclomaticComplexity
+    def self.embed(text, # rubocop:disable Metrics/ParameterLists
                    model: nil,
                    provider: nil,
                    assume_model_exists: false,
                    context: nil,
                    dimensions: nil)
       config = context&.config || RubyLLM.config
-      model, provider = Models.resolve(model, provider: provider, assume_exists: assume_model_exists) if model
-      model_id = model&.id || config.default_embedding_model
+      model ||= config.default_embedding_model
+      model, provider = Models.resolve(model, provider: provider, assume_exists: assume_model_exists)
+      model_id = model.id
 
       provider = Provider.for(model_id) if provider.nil?
       connection = context ? context.connection_for(provider) : provider.connection(config)