ruby_llm 2.1.0 → 2.2.0

data/lib/generators/ruby_llm/evaluation/evaluation_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RubyLLM
+  module Generators
+    # Generator for evaluations and their datasets.
+    class EvaluationGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'ruby_llm:evaluation'
+
+      desc 'Creates an evaluation class and its dataset in app/evals'
+
+      def check_evaluation_class_collision
+        class_collisions evaluation_class_name
+      end
+
+      def create_evaluation_file
+        template 'evaluation.rb.tt', File.join('app/evals', class_path, "#{evaluation_file_name}.rb")
+      end
+
+      def create_dataset_file
+        template 'evaluation.yml.tt', File.join('app/evals', class_path, "#{evaluation_file_name}.yml")
+      end
+
+      private
+
+      def evaluation_class_name
+        class_name.end_with?('Evaluation') ? class_name : "#{class_name}Evaluation"
+      end
+
+      def evaluation_file_name
+        evaluation_class_name.demodulize.underscore
+      end
+
+      def agent_class_name
+        name = "#{evaluation_class_name.delete_suffix('Evaluation')}Agent"
+        name if File.exist?(File.join(destination_root, 'app/agents', "#{name.underscore}.rb"))
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/evaluation/templates/evaluation.rb.tt

@@ -0,0 +1,9 @@
+class <%= evaluation_class_name %> < RubyLLM::Evaluation
+  def perform(input)
+<% if agent_class_name -%>
+    <%= agent_class_name %>.new.ask(input)
+<% else -%>
+    RubyLLM.chat.ask(input)
+<% end -%>
+  end
+end

data/lib/generators/ruby_llm/evaluation/templates/evaluation.yml.tt

@@ -0,0 +1,4 @@
+cases:
+  - name: first_case
+    inputs: ""
+    expected_output: ""

data/lib/generators/ruby_llm/generator_helpers.rb

@@ -1,15 +1,128 @@
 # frozen_string_literal: true
 
+require 'ripper'
+
 module RubyLLM
   module Generators
     # Shared helpers for RubyLLM generators
     module GeneratorHelpers
       APPLICATION_MODEL_TYPES = %w[chat message].freeze
+      APPLICATION_AGENT_PATH = 'app/agents/application_agent.rb'
       DEFAULT_MODEL_NAMES = {
         chat: 'Chat',
         message: 'Message'
       }.freeze
 
+      def create_application_agent
+        return if application_agent?
+
+        create_file APPLICATION_AGENT_PATH, <<~RUBY
+          class ApplicationAgent < RubyLLM::Agent
+            chat_class #{chat_model_name}
+          end
+        RUBY
+      end
+
+      def application_agent?
+        File.exist?(File.join(destination_root, APPLICATION_AGENT_PATH))
+      end
+
+      # Removes the broadcasting code and attachment declaration earlier
+      # versions wrote into the message model, which acts_as_message now
+      # provides, and explains what to do with broadcasting code RubyLLM
+      # did not write.
+      def remove_generated_message_code
+        return unless behavior == :invoke
+
+        path = "app/models/#{message_model_name.underscore}.rb"
+        model = File.join(destination_root, path)
+        return unless File.exist?(model)
+
+        source = File.read(model)
+        (generated_broadcasting_blocks + ["  has_many_attached :attachments\n"]).each do |code|
+          gsub_file(path, code, '') if source.include?(code)
+        end
+        explain_own_broadcasting(File.read(model))
+        generated_broadcasting_blocks.any? { |block| source.include?(block) }
+      end
+
+      # Turns on Configuration#broadcast_messages in the RubyLLM initializer.
+      def enable_message_broadcasting
+        configure_initializer(:broadcast_messages, 'true')
+      end
+
+      # Sets +setting+ to +value+ at the end of the initializer's
+      # RubyLLM.configure block, unless the initializer already sets it.
+      def configure_initializer(setting, value)
+        path = 'config/initializers/ruby_llm.rb'
+        initializer = File.join(destination_root, path)
+        source = File.exist?(initializer) ? File.read(initializer) : ''
+        block = configure_block(source)
+        return say("Add config.#{setting} = #{value} to your RubyLLM configuration", :yellow) unless block
+
+        indent, name = block.captures
+        return if block[0].match?(/^\s*#{name}\.#{setting}\s*=/)
+        return if source.match?(/^\s*RubyLLM\.config\.#{setting}\s*=/)
+
+        inject_into_file path, "#{indent}  #{name}.#{setting} = #{value}\n", after: block[0]
+      end
+
+      # The RubyLLM.configure block up to its closing +end+, or +nil+ unless
+      # Ruby reads both lines as code and that +end+ as the one closing the
+      # block. Lines inside a heredoc can look like either.
+      def configure_block(source)
+        block = source.match(/^( *)RubyLLM\.configure do \|(\w+)\|\n.*?(?=^\1end\b)/m)
+        return unless block
+
+        tokens = Ripper.lex(source).to_h { |at, type| [at, type] }
+        column = block[1].length
+        opening = [source[0...block.begin(0)].count("\n") + 1, column]
+        closing = [source[0...block.end(0)].count("\n") + 1, column]
+        return unless tokens[opening] == :on_const && tokens[closing] == :on_kw
+
+        block if Ripper.sexp("#{block[0]}#{block[1]}end\n")
+      end
+
+      def explain_own_broadcasting(source)
+        return unless source.match?(/\b(?:broadcast_\w+_to|broadcasts_to|broadcasts_refreshes|broadcast_append_chunk)/)
+        return if source.include?('broadcasts: false')
+
+        say "#{message_model_name} broadcasts with Turbo itself: remove that code, or write acts_as_message " \
+            'broadcasts: false', :yellow
+      end
+
+      # The broadcasting blocks earlier versions of ruby_llm:chat_ui wrote:
+      # releases 1.14 through 2.1, and the numbered-chunk block before
+      # acts_as_message broadcast.
+      def generated_broadcasting_blocks
+        message = message_variable_name
+        chat = chat_variable_name
+        association = chat_table_name.singularize
+        stream = %("#{chat}_\#{#{association}_id}")
+        [<<-RELEASED, <<-NUMBERED]
+
+  broadcasts_to ->(#{message}) { "#{chat}_\#{#{message}.#{association}_id}" }, inserts_by: :append
+
+  def broadcast_append_chunk(content)
+    broadcast_append_to #{stream},
+      target: "#{message}_\#{id}_content",
+      content: ERB::Util.html_escape(content.to_s)
+  end
+        RELEASED
+
+  after_create_commit -> { broadcast_append_to #{stream} if role.to_s == "assistant" && content.blank? }
+  after_update_commit -> { broadcast_replace_to #{stream} }
+  after_destroy_commit -> { broadcast_remove_to #{stream} }
+  after_commit -> { broadcast_refresh_to #{stream} }
+
+  def broadcast_append_chunk(content, sequence)
+    broadcast_append_to #{stream},
+      target: "#{message}_\#{id}_stream",
+      content: %(<span data-seq="\#{sequence}">\#{ERB::Util.html_escape(content)}</span>)
+  end
+        NUMBERED
+      end
+
       def parse_model_mappings(allowed_types: APPLICATION_MODEL_TYPES, defaults: DEFAULT_MODEL_NAMES)
         @model_names = defaults.dup
         @explicit_model_mappings = []
@@ -104,20 +217,20 @@ module RubyLLM
 
         [chat_model_name, message_model_name].each do |model_name|
           if model_name.include?('::')
-            namespace = model_name.split('::').first
+            namespace = model_name.deconstantize
             namespaces << namespace unless namespaces.include?(namespace)
           end
         end
 
         namespaces.each do |namespace|
           module_path = "app/models/#{namespace.underscore}.rb"
-          next if File.exist?(Rails.root.join(module_path))
+          next if File.exist?(File.join(destination_root, module_path))
 
           create_file module_path do
             <<~RUBY
               module #{namespace}
                 def self.table_name_prefix
-                  "#{namespace.underscore}_"
+                  "#{namespace.underscore.tr('/', '_')}_"
                 end
               end
             RUBY

data/lib/generators/ruby_llm/install/install_generator.rb

@@ -17,10 +17,7 @@ module RubyLLM
 
       argument :model_mappings, type: :array, default: [], banner: 'chat:ChatName message:MessageName ...'
 
-      class_option :skip_active_storage, type: :boolean, default: false,
-                                         desc: 'Skip ActiveStorage installation and attachment setup'
-
-      desc 'Creates models and migrations for RubyLLM Rails integration\n' \
+      desc "Creates models and migrations for RubyLLM Rails integration\n" \
            'Usage: bin/rails g ruby_llm:install [chat:ChatName] [message:MessageName] ...'
 
       def self.next_migration_number(dirname)
@@ -47,55 +44,16 @@ module RubyLLM
         template 'initializer.rb.tt', 'config/initializers/ruby_llm.rb'
       end
 
-      def create_convention_directories
-        %w[agents tools schemas prompts].each do |name|
-          empty_directory "app/#{name}"
-          create_file "app/#{name}/.gitkeep" unless File.exist?(Rails.root.join("app/#{name}/.gitkeep"))
-        end
+      def create_application_agent_file
+        create_application_agent
       end
 
       def install_active_storage
-        return if options[:skip_active_storage]
-
-        say '  Installing ActiveStorage for file attachments...', :cyan
         rails_command 'active_storage:install'
       end
 
-      def show_install_info
-        say "\n  ✅ RubyLLM installed!", :green
-
-        say '  ✅ ActiveStorage configured for file attachments support', :green unless options[:skip_active_storage]
-
-        say "\n  Next steps:", :yellow
-        say '     1. Run: bin/rails db:migrate'
-        say '     2. Run: bin/rails ruby_llm:load_models'
-        say '     3. Set your API keys in config/initializers/ruby_llm.rb'
-
-        say "     4. Start chatting: #{chat_model_name}.create!(model: 'gpt-5.6-luna').ask('Hello!')"
-        say "     5. Optional UI: #{chat_ui_generator_command}"
-
-        if options[:skip_active_storage]
-          say "\n  📎 Note: ActiveStorage was skipped", :yellow
-          say '     File attachments won\'t work without ActiveStorage.'
-          say '     To enable later:'
-          say '       1. Run: bin/rails active_storage:install && bin/rails db:migrate'
-          say "       2. Add to your #{message_model_name} model: has_many_attached :attachments"
-        end
-
-        say "\n  📚 Documentation: https://rubyllm.com", :cyan
-
-        say "\n  ❤️  Love RubyLLM?", :magenta
-        say '     • ⭐ Star on GitHub: https://github.com/crmne/ruby_llm'
-        say '     • 🐦 Follow for updates: https://x.com/paolino'
-        say "\n"
-      end
-
-      private
-
-      def chat_ui_generator_command
-        mappings = model_mappings.join(' ')
-        mappings = " #{mappings}" unless mappings.empty?
-        "bin/rails generate ruby_llm:chat_ui#{mappings}"
+      def show_next_step
+        say "\nRun bin/rails db:migrate" if behavior == :invoke
       end
     end
   end

data/lib/generators/ruby_llm/install/templates/create_chats_migration.rb.tt

@@ -3,7 +3,11 @@ class <%= create_migration_class_name(chat_table_name) %> < ActiveRecord::Migrat
     create_table :<%= chat_table_name %>, id: :<%= reference_type %> do |t|
       t.references :ruby_llm_model, null: false, foreign_key: { to_table: :ruby_llm_models }, type: :<%= reference_type %>
       t.boolean :cancelled, null: false, default: false
+      t.string :claim_token
+      t.datetime :claimed_until
       t.timestamps
+
+      t.index :claimed_until<%= ', where: "claim_token IS NOT NULL"' unless mysql? %>
     end
   end
 end

data/lib/generators/ruby_llm/install/templates/create_messages_migration.rb.tt

@@ -3,11 +3,11 @@ class <%= create_migration_class_name(message_table_name) %> < ActiveRecord::Mig
     create_table :<%= message_table_name %>, id: :<%= reference_type %> do |t|
       t.references :<%= chat_table_name.singularize %>, null: false, foreign_key: { to_table: :<%= chat_table_name %> }, type: :<%= reference_type %>
       t.string :role, null: false
-      t.text :content
+      t.text :content<%= ', size: :long' if mysql? %>
       t.boolean :cache_until_here, null: false, default: false
       t.string :cache_ttl
-      t.text :thinking_text
-      t.text :thinking_signature
+      t.text :thinking_text<%= ', size: :long' if mysql? %>
+      t.text :thinking_signature<%= ', size: :long' if mysql? %>
 <% if postgresql? %>
       t.jsonb :citations
       t.jsonb :server_tool_calls
@@ -19,6 +19,8 @@ class <%= create_migration_class_name(message_table_name) %> < ActiveRecord::Mig
       t.json :raw_content
       t.json :raw_reasoning
 <% end %>
+      t.string :phase
+      t.text :continuation<%= ', size: :long' if mysql? %>
       t.string :finish_reason
       t.timestamps
     end

data/lib/generators/ruby_llm/install/templates/create_ruby_llm_records_migration.rb.tt

@@ -41,10 +41,13 @@ class <%= create_migration_class_name('ruby_llm_records') %> < ActiveRecord::Mig
       t.references :message, polymorphic: true, null: false, type: :<%= reference_type %>, index: false
       t.references :result, polymorphic: true, type: :<%= reference_type %>, index: false
       t.string :tool_call_id, null: false
+      t.string :provider_call_id
+      t.string :namespace
       t.string :name, null: false
-      t.text :thought_signature
+      t.text :thought_signature<%= ', size: :long' if mysql? %>
       t.string :approval
       t.boolean :remote, default: false, null: false
+      t.datetime :claimed_until
 <% if postgresql? %>
       t.jsonb :arguments, default: {}
       t.jsonb :mcp_state
@@ -88,6 +91,9 @@ class <%= create_migration_class_name('ruby_llm_records') %> < ActiveRecord::Mig
       t.integer :cache_read_tokens
       t.integer :cache_write_tokens
       t.integer :thinking_tokens
+      t.integer :characters
+      t.decimal :audio_seconds, precision: 16, scale: 6
+      t.integer :search_units
 <% if postgresql? %>
       t.jsonb :server_tool_use
 <% else %>
@@ -98,17 +104,51 @@ class <%= create_migration_class_name('ruby_llm_records') %> < ActiveRecord::Mig
       t.decimal :cache_read_cost, precision: 16, scale: 10
       t.decimal :cache_write_cost, precision: 16, scale: 10
       t.decimal :thinking_cost, precision: 16, scale: 10
+      t.decimal :characters_cost, precision: 16, scale: 10
+      t.decimal :audio_seconds_cost, precision: 16, scale: 10
+      t.decimal :search_units_cost, precision: 16, scale: 10
       t.decimal :total_cost, precision: 16, scale: 10
+      t.string :workflow_id
+      t.string :workflow_name
+      t.string :workflow_step_id
+      t.string :workflow_step_name
       t.timestamps
 
       t.index [ :chat_type, :chat_id ]
       t.index [ :message_type, :message_id ]
       t.index [ :owner_type, :owner_id ]
       t.index :status
+      t.index :workflow_id
       t.check_constraint "operation<%= '::text' if postgresql? %> IN (<%= usage_operations_sql %>)"
       t.check_constraint "status<%= '::text' if postgresql? %> IN (<%= usage_statuses_sql %>)"
     end
 
+    create_table :ruby_llm_queued_messages, id: :<%= reference_type %> do |t|
+      t.references :chat, polymorphic: true, null: false, type: :<%= reference_type %>, index: false
+      t.references :sender, polymorphic: true, type: :<%= reference_type %>, index: false
+      t.text :content<%= ', size: :long' if mysql? %>
+      t.boolean :steer, default: true, null: false
+      t.timestamps
+
+      t.index [ :chat_type, :chat_id ]
+      t.index [ :sender_type, :sender_id ]
+    end
+
+    create_table :ruby_llm_chat_files, id: :<%= reference_type %> do |t|
+      t.references :chat, polymorphic: true, null: false, type: :<%= reference_type %>, index: false
+      t.references :owner, polymorphic: true, type: :<%= reference_type %>, index: false
+      t.string :path, null: false
+      t.string :content_type
+      t.bigint :byte_size
+      t.string :digest
+      t.text :text<%= ', size: :long' if mysql? %>
+      t.string :read_digest
+      t.timestamps
+
+      t.index [ :chat_type, :chat_id, :path ]
+      t.index [ :owner_type, :owner_id ]
+    end
+
     create_table :ruby_llm_batches, id: :<%= reference_type %> do |t|
       t.string :provider_batch_id, null: false
       t.string :provider, null: false

data/lib/generators/ruby_llm/install/templates/initializer.rb.tt

@@ -1,4 +1,5 @@
 RubyLLM.configure do |config|
   config.openai_api_key = ENV.fetch("OPENAI_API_KEY", Rails.application.credentials.dig(:openai_api_key))
-  # config.default_model = "gpt-5-nano"
+  # config.default_model = "gpt-6-luna"
+  config.context_budget = { per_result: 0.25, per_request: 0.7 }
 end

data/lib/generators/ruby_llm/install/templates/message_model.rb.tt

@@ -1,4 +1,3 @@
 class <%= message_model_name %> < ApplicationRecord
-  <%= acts_as_message_declaration %><% unless options[:skip_active_storage] %>
-  has_many_attached :attachments<% end %>
+  <%= acts_as_message_declaration %>
 end

data/lib/generators/ruby_llm/judge/judge_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RubyLLM
+  module Generators
+    # Generator for judge classes that ask judgment models for probabilities,
+    # choices, and scores.
+    class JudgeGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'ruby_llm:judge'
+
+      desc 'Creates a judge class in app/judges'
+
+      def check_judge_class_collision
+        class_collisions judge_class_name
+      end
+
+      def create_judge_file
+        template 'judge.rb.tt', File.join('app/judges', class_path, "#{judge_file_name}.rb")
+      end
+
+      private
+
+      def judge_class_name
+        class_name.end_with?('Judge') ? class_name : "#{class_name}Judge"
+      end
+
+      def judge_file_name
+        judge_class_name.demodulize.underscore
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/judge/templates/judge.rb.tt

@@ -0,0 +1,2 @@
+class <%= judge_class_name %> < RubyLLM::Judge
+end

data/lib/generators/ruby_llm/mcp/mcp_generator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'shellwords'
+
+module RubyLLM
+  module Generators
+    # Generator for MCP server classes.
+    class MCPGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'ruby_llm:mcp'
+
+      def self.exit_on_failure?
+        true
+      end
+
+      argument :url, type: :string, required: false, banner: 'URL'
+
+      class_option :command, type: :string, desc: 'The command that starts a local server, for stdio'
+
+      desc "Creates an MCP server class in app/mcp\n" \
+           'Usage: bin/rails g ruby_llm:mcp Linear https://mcp.linear.app/mcp ' \
+           'or bin/rails g ruby_llm:mcp Files --command "npx -y @modelcontextprotocol/server-filesystem ."'
+
+      def check_server
+        return if url.present? ^ options[:command].present?
+
+        raise Thor::Error, "Pass the server's URL or --command, not both"
+      end
+
+      def check_server_class_collision
+        class_collisions mcp_class_name
+      end
+
+      def create_server_file
+        template 'mcp.rb.tt', File.join('app/mcp', class_path, "#{mcp_file_name}.rb")
+      end
+
+      private
+
+      # Follows the application's inflections, so it is LinearMcp, or
+      # LinearMCP where MCP is an acronym, as Zeitwerk expects either way.
+      def mcp_class_name
+        suffix = 'mcp'.camelize
+        class_name.end_with?(suffix) ? class_name : "#{class_name}#{suffix}"
+      end
+
+      def mcp_file_name
+        mcp_class_name.demodulize.underscore
+      end
+
+      def command_arguments
+        Shellwords.split(options[:command]).map(&:inspect).join(', ')
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/mcp/templates/mcp.rb.tt

@@ -0,0 +1,7 @@
+class <%= mcp_class_name %> < RubyLLM::MCP
+<% if url.present? -%>
+  url <%= url.inspect %>
+<% else -%>
+  command <%= command_arguments %>
+<% end -%>
+end

data/lib/generators/ruby_llm/provider/scaffold.rb

@@ -112,10 +112,9 @@ module RubyLLM
           write_template 'core/provider_spec.rb.erb', "spec/ruby_llm/providers/#{slug}_spec.rb"
 
           update_core_registration
-          update_core_env_example
+          update_core_env
           update_core_spec_configuration
           update_core_vcr_configuration
-          update_core_models_dev_map if models_dev_provider
         end
 
         def generate_provider_gem
@@ -168,11 +167,12 @@ module RubyLLM
           )
         end
 
-        def update_core_env_example
-          path = file_path('.env.example')
+        def update_core_env
+          path = file_path('.env')
           return unless File.exist?(path)
 
-          insert_sorted_line(path, "#{api_key_env}=$(op read \"op://RubyLLM/#{class_name}/credential\")", ENV_LINE)
+          insert_sorted_line(path, "#{api_key_env}=$(op-cache read \"op://RubyLLM/#{class_name}/credential\")",
+                             ENV_LINE)
           insert_sorted_line(path, "#{api_base_env}=#{api_base}", ENV_LINE)
         end
 
@@ -195,13 +195,6 @@ module RubyLLM
           insert_sorted_line(path, line, /^\s+config\.filter_sensitive_data\('<[A-Z0-9_]+>'\)/)
         end
 
-        def update_core_models_dev_map
-          path = file_path('lib/ruby_llm/models.rb')
-          return unless File.exist?(path)
-
-          insert_sorted_entry(path, "      '#{models_dev_provider}' => '#{slug}'")
-        end
-
         def write_template(template, relative_path, executable: false)
           content = ERB.new(File.read(template_path(template)), trim_mode: '-').result(binding)
           write_file(relative_path, content, executable:)

data/lib/generators/ruby_llm/provider/templates/core/provider.rb.erb

@@ -25,6 +25,12 @@ module RubyLLM
         def configuration_requirements
           %i[<%= api_key_config %>]
         end
+<% if models_dev_provider -%>
+
+        def models_dev_provider_ids # :nodoc:
+          %w[<%= models_dev_provider %>]
+        end
+<% end -%>
 <% if dynamic_models? -%>
 
         def assume_models_exist?

data/lib/generators/ruby_llm/provider/templates/gem/chat_spec.rb.erb

@@ -22,7 +22,6 @@ RSpec.describe RubyLLM::Chat, :live do
       expect(response.raw.status).to eq(200)
       expect(response.raw.headers).not_to be_empty
       expect(response.raw.body).not_to be_empty
-      expect(response.raw.env.request_body).not_to be_empty
     end
 
     it "#{provider}/#{model} can handle a multi-turn conversation" do

data/lib/generators/ruby_llm/provider/templates/gem/chat_streaming_spec.rb.erb

@@ -16,7 +16,6 @@ RSpec.describe RubyLLM::Chat, :live do
       expect(chunks.first).to be_a(RubyLLM::Chunk)
       expect(response.raw.status).to eq(200)
       expect(response.raw.headers).not_to be_empty
-      expect(response.raw.env.request_body).not_to be_empty
     end
   end
 end

data/lib/generators/ruby_llm/provider/templates/gem/moderation_spec.rb.erb

@@ -16,7 +16,7 @@ RSpec.describe RubyLLM::Moderation, :live do
 
       expect(moderation).to be_a(described_class)
       expect(moderation.results).to all(be_a(RubyLLM::Moderation::Result))
-      expect(moderation.flagged?).to be_in([true, false])
+      expect(moderation.flagged?).to be(true).or be(false)
     end
   end
 end