ruby_llm-agents 0.5.0 → 1.0.0

data/app/views/ruby_llm/agents/workflows/show.html.erb

@@ -0,0 +1,442 @@
+<%= render "ruby_llm/agents/shared/breadcrumbs", items: [
+  { label: "Dashboard", path: ruby_llm_agents.root_path },
+  { label: "Workflows", path: ruby_llm_agents.agents_path(tab: "workflows") },
+  { label: @workflow_type.gsub(/Workflow$|Pipeline$|Parallel$|Router$/, '') }
+] %>
+
+<!-- Header -->
+<div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6 mb-6">
+  <div class="flex items-start justify-between">
+    <div>
+      <div class="flex items-center space-x-3">
+        <%= render "ruby_llm/agents/shared/workflow_type_badge", workflow_type: @workflow_type_kind, size: :md %>
+        <h1 class="text-2xl font-bold text-gray-900 dark:text-gray-100">
+          <% name_parts = @workflow_type.gsub(/Workflow$|Pipeline$|Parallel$|Router$/, '').split('::') %>
+          <% if name_parts.length > 1 %>
+            <span class="text-gray-400 dark:text-gray-500 font-normal"><%= name_parts[0..-2].join('::') %>::</span>
+          <% end %>
+          <%= name_parts.last %>
+        </h1>
+
+        <% if @workflow_active %>
+          <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-green-100 dark:bg-green-900/50 text-green-800 dark:text-green-300">
+            Active
+          </span>
+        <% else %>
+          <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-gray-100 dark:bg-gray-700 text-gray-600 dark:text-gray-400">
+            Deleted
+          </span>
+        <% end %>
+
+        <% if @config %>
+          <span class="text-sm text-gray-500 dark:text-gray-400">
+            v<%= @config[:version] %>
+          </span>
+        <% end %>
+      </div>
+
+      <% if @config && @config[:description].present? %>
+        <p class="text-gray-600 dark:text-gray-300 mt-2 max-w-2xl">
+          <%= @config[:description] %>
+        </p>
+      <% end %>
+
+      <!-- Workflow Summary Line -->
+      <div class="flex items-center gap-4 mt-3 text-sm text-gray-500 dark:text-gray-400">
+        <% if @workflow_type_kind == "pipeline" && @steps.present? %>
+          <span><%= @steps.size %> steps</span>
+        <% elsif @workflow_type_kind == "parallel" && @branches.present? %>
+          <span><%= @branches.size %> branches</span>
+        <% elsif @workflow_type_kind == "router" && @routes.present? %>
+          <span><%= @routes.size %> routes</span>
+        <% end %>
+
+        <% if @config && @config[:timeout] %>
+          <span class="text-gray-300 dark:text-gray-600">|</span>
+          <span>timeout <%= @config[:timeout] %>s</span>
+        <% end %>
+
+        <% if @config && @config[:max_cost] %>
+          <span class="text-gray-300 dark:text-gray-600">|</span>
+          <span>max cost $<%= @config[:max_cost] %></span>
+        <% end %>
+
+        <% if @workflow_type_kind == "router" && @config && @config[:classifier_model] %>
+          <span class="text-gray-300 dark:text-gray-600">|</span>
+          <span>classifier: <%= @config[:classifier_model] %></span>
+        <% end %>
+      </div>
+    </div>
+
+    <div class="text-right">
+      <p class="text-sm text-gray-500 dark:text-gray-400">
+        <%= number_with_delimiter(@stats[:count]) %> total executions
+      </p>
+
+      <div class="flex items-center justify-end gap-3 mt-1">
+        <% status_colors = {
+            "success" => "bg-green-500",
+            "error" => "bg-red-500",
+            "timeout" => "bg-yellow-500",
+            "running" => "bg-blue-500"
+          } %>
+
+        <% @status_distribution.each do |status, count| %>
+          <div class="flex items-center gap-1">
+            <span class="w-2 h-2 rounded-full <%= status_colors[status] || 'bg-gray-400' %> <%= status == 'running' ? 'animate-pulse' : '' %>"></span>
+            <span class="text-xs text-gray-600 dark:text-gray-400">
+              <%= number_with_delimiter(count) %>
+            </span>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- Workflow Structure -->
+<div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6 mb-6">
+  <div class="flex items-center justify-between mb-4">
+    <h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100">
+      Workflow Structure
+    </h3>
+
+    <% if @workflow_type_kind == "parallel" && @config %>
+      <span class="text-sm text-gray-500 dark:text-gray-400">
+        fail_fast: <%= @config[:fail_fast] ? 'on' : 'off' %>
+      </span>
+    <% elsif @workflow_type_kind == "router" && @config && @config[:classifier_model] %>
+      <span class="text-sm text-gray-500 dark:text-gray-400">
+        classifier: <%= @config[:classifier_model] %> @ <%= @config[:classifier_temperature] || 0.0 %>
+      </span>
+    <% end %>
+  </div>
+
+  <% case @workflow_type_kind %>
+  <% when "pipeline" %>
+    <%= render "ruby_llm/agents/workflows/structure_pipeline", steps: @steps || [] %>
+  <% when "parallel" %>
+    <%= render "ruby_llm/agents/workflows/structure_parallel", branches: @branches || [] %>
+  <% when "router" %>
+    <%= render "ruby_llm/agents/workflows/structure_router", routes: @routes || [] %>
+  <% else %>
+    <p class="text-gray-500 dark:text-gray-400 italic">
+      Workflow structure unavailable
+    </p>
+  <% end %>
+</div>
+
+<!-- Stats Grid -->
+<% success_rate = @stats[:success_rate] || 0 %>
+<% success_rate_color = success_rate >= 95 ? 'text-green-600' : success_rate >= 80 ? 'text-yellow-600' : 'text-red-600' %>
+
+<div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-5 gap-4 mb-6">
+  <%= render "ruby_llm/agents/shared/stat_card",
+      title: "Executions",
+      value: number_with_delimiter(@stats[:count]),
+      subtitle: "Today: #{@stats_today[:count]}",
+      icon: "M13 10V3L4 14h7v7l9-11h-7z",
+      icon_color: "text-blue-500" %>
+
+  <%= render "ruby_llm/agents/shared/stat_card",
+      title: "Success Rate",
+      value: "#{success_rate}%",
+      subtitle: "Error rate: #{@stats[:error_rate] || 0}%",
+      icon: "M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z",
+      icon_color: "text-green-500",
+      value_color: success_rate_color %>
+
+  <%= render "ruby_llm/agents/shared/stat_card",
+      title: "Total Cost",
+      value: "$#{number_with_precision(@stats[:total_cost] || 0, precision: 4)}",
+      subtitle: "Avg: $#{number_with_precision(@stats[:avg_cost] || 0, precision: 6)}",
+      icon: "M12 8c-1.657 0-3 .895-3 2s1.343 2 3 2 3 .895 3 2-1.343 2-3 2m0-8c1.11 0 2.08.402 2.599 1M12 8V7m0 1v8m0 0v1m0-1c-1.11 0-2.08-.402-2.599-1M21 12a9 9 0 11-18 0 9 9 0 0118 0z",
+      icon_color: "text-amber-500" %>
+
+  <%= render "ruby_llm/agents/shared/stat_card",
+      title: "Total Tokens",
+      value: number_with_delimiter(@stats[:total_tokens] || 0),
+      subtitle: "Avg: #{number_with_delimiter(@stats[:avg_tokens] || 0)}",
+      icon: "M7 20l4-16m2 16l4-16M6 9h14M4 15h14",
+      icon_color: "text-indigo-500" %>
+
+  <%= render "ruby_llm/agents/shared/stat_card",
+      title: "Avg Duration",
+      value: "#{number_with_delimiter(@stats[:avg_duration_ms] || 0)} ms",
+      icon: "M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z",
+      icon_color: "text-purple-500" %>
+</div>
+
+<!-- Step/Branch/Route Performance -->
+<% if @step_stats.present? %>
+  <%= render "ruby_llm/agents/workflows/step_performance",
+      workflow_type: @workflow_type_kind,
+      step_stats: @step_stats,
+      route_distribution: @route_distribution %>
+<% end %>
+
+<!-- Charts Section -->
+<div class="grid grid-cols-1 lg:grid-cols-2 gap-6 mb-6">
+  <!-- Executions Over Time -->
+  <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6 overflow-hidden">
+    <h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-4">
+      Executions (30 days)
+    </h3>
+    <div id="executions-chart" style="height: 220px;"></div>
+  </div>
+
+  <!-- Cost Over Time -->
+  <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6 overflow-hidden">
+    <h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-4">
+      Cost (30 days)
+    </h3>
+    <div id="cost-chart" style="height: 220px;"></div>
+  </div>
+</div>
+
+<script>
+(function() {
+  const trendData = <%= raw @trend_data.to_json %>;
+  const categories = trendData.map(d => d.date.split('-').slice(1).join('/'));
+
+  // Executions chart
+  Highcharts.chart('executions-chart', {
+    chart: { type: 'areaspline', backgroundColor: 'transparent' },
+    xAxis: { categories: categories, labels: { style: { color: '#9CA3AF' } } },
+    yAxis: { min: 0, title: { text: null }, labels: { style: { color: '#9CA3AF' } } },
+    legend: { enabled: false },
+    plotOptions: { areaspline: { fillOpacity: 0.2, marker: { enabled: false } } },
+    series: [
+      { name: 'Success', color: '#10B981', data: trendData.map(d => d.count - (d.error_count || 0)) },
+      { name: 'Failed', color: '#EF4444', data: trendData.map(d => d.error_count || 0) }
+    ]
+  });
+
+  // Cost chart
+  Highcharts.chart('cost-chart', {
+    chart: { type: 'spline', backgroundColor: 'transparent' },
+    xAxis: { categories: categories, labels: { style: { color: '#9CA3AF' } } },
+    yAxis: { min: 0, title: { text: null }, labels: { style: { color: '#9CA3AF' }, format: '${value}' } },
+    legend: { enabled: false },
+    plotOptions: { spline: { marker: { enabled: false } } },
+    tooltip: { valuePrefix: '$' },
+    series: [{ name: 'Cost', color: '#10B981', data: trendData.map(d => parseFloat(d.total_cost) || 0) }]
+  });
+})();
+</script>
+
+<!-- Finish Reason Distribution -->
+<% if @finish_reason_distribution.present? && @finish_reason_distribution.any? %>
+  <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-4 mb-6">
+    <div class="flex items-center justify-between">
+      <p class="text-sm text-gray-500 dark:text-gray-400 uppercase">
+        Finish Reasons
+      </p>
+
+      <div class="flex flex-wrap gap-4">
+        <% finish_colors = {
+            'stop' => '#10B981',
+            'length' => '#F59E0B',
+            'content_filter' => '#EF4444',
+            'tool_calls' => '#3B82F6',
+            nil => '#6B7280'
+          } %>
+
+        <% @finish_reason_distribution.each do |reason, count| %>
+          <div class="flex items-center">
+            <span class="w-2 h-2 rounded-full mr-1.5" style="background-color: <%= finish_colors[reason] || '#6B7280' %>"></span>
+            <span class="text-sm text-gray-700 dark:text-gray-300">
+              <%= reason || 'unknown' %>
+            </span>
+            <span class="text-sm font-medium text-gray-900 dark:text-gray-100 ml-1">
+              (<%= number_with_delimiter(count) %>)
+            </span>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+<% end %>
+
+<% if @config %>
+  <!-- Configuration -->
+  <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6 mb-6">
+    <h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-4">
+      Configuration
+    </h3>
+
+    <!-- Basic Configuration -->
+    <p class="text-xs text-gray-500 dark:text-gray-400 uppercase tracking-wider mb-3">
+      Basic
+    </p>
+
+    <div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-6">
+      <div>
+        <p class="text-sm text-gray-500 dark:text-gray-400">Version</p>
+        <p class="font-medium text-gray-900 dark:text-gray-100">
+          <%= @config[:version] || 'N/A' %>
+        </p>
+      </div>
+
+      <div>
+        <p class="text-sm text-gray-500 dark:text-gray-400">Timeout</p>
+        <p class="font-medium text-gray-900 dark:text-gray-100">
+          <%= @config[:timeout] ? "#{@config[:timeout]}s" : 'N/A' %>
+        </p>
+      </div>
+
+      <div>
+        <p class="text-sm text-gray-500 dark:text-gray-400">Max Cost</p>
+        <p class="font-medium text-gray-900 dark:text-gray-100">
+          <%= @config[:max_cost] ? "$#{@config[:max_cost]}" : 'N/A' %>
+        </p>
+      </div>
+
+      <% if @workflow_type_kind == "parallel" %>
+        <div>
+          <p class="text-sm text-gray-500 dark:text-gray-400">Fail Fast</p>
+          <p class="font-medium text-gray-900 dark:text-gray-100">
+            <%= @config[:fail_fast] ? 'Yes' : 'No' %>
+          </p>
+        </div>
+      <% end %>
+    </div>
+
+    <% if @workflow_type_kind == "router" && @config[:classifier_model] %>
+      <!-- Router Settings -->
+      <div class="border-t border-gray-100 dark:border-gray-700 pt-4">
+        <p class="text-xs text-gray-500 dark:text-gray-400 uppercase tracking-wider mb-3">
+          Router Settings
+        </p>
+
+        <div class="grid grid-cols-2 md:grid-cols-4 gap-4">
+          <div>
+            <p class="text-sm text-gray-500 dark:text-gray-400">Classifier Model</p>
+            <p class="font-medium text-gray-900 dark:text-gray-100">
+              <%= @config[:classifier_model] %>
+            </p>
+          </div>
+
+          <div>
+            <p class="text-sm text-gray-500 dark:text-gray-400">Temperature</p>
+            <p class="font-medium text-gray-900 dark:text-gray-100">
+              <%= @config[:classifier_temperature] || 0.0 %>
+            </p>
+          </div>
+        </div>
+      </div>
+    <% end %>
+  </div>
+<% end %>
+
+<!-- Executions -->
+<div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+  <h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-4">
+    Executions
+  </h3>
+
+  <div id="executions_table">
+    <%
+      has_filters = params[:statuses].present? || params[:versions].present? || params[:models].present? || params[:temperatures].present? || params[:days].present?
+      selected_statuses = params[:statuses].present? ? (params[:statuses].is_a?(Array) ? params[:statuses] : params[:statuses].split(",")) : []
+      selected_versions = params[:versions].present? ? (params[:versions].is_a?(Array) ? params[:versions] : params[:versions].split(",")) : []
+      selected_models = params[:models].present? ? (params[:models].is_a?(Array) ? params[:models] : params[:models].split(",")) : []
+      selected_temperatures = params[:temperatures].present? ? (params[:temperatures].is_a?(Array) ? params[:temperatures] : params[:temperatures].split(",")).map(&:to_s) : []
+
+      status_options = [
+        { value: "success", label: "Success", color: "bg-green-500" },
+        { value: "error", label: "Error", color: "bg-red-500" },
+        { value: "running", label: "Running", color: "bg-blue-500" },
+        { value: "timeout", label: "Timeout", color: "bg-yellow-500" }
+      ]
+      version_options = @versions.map { |v| { value: v.to_s, label: "v#{v}" } }
+      model_options = @models.map { |m| { value: m, label: m } }
+      temperature_options = @temperatures.map { |t| { value: t.to_s, label: t.to_s } }
+      days_options = [
+        { value: "", label: "All Time" },
+        { value: "1", label: "Today" },
+        { value: "7", label: "Last 7 Days" },
+        { value: "30", label: "Last 30 Days" }
+      ]
+    %>
+
+    <%= form_with url: ruby_llm_agents.workflow_path(@workflow_type), method: :get, local: true do |f| %>
+      <div class="flex flex-wrap items-center gap-3 mb-4 pb-4 border-b border-gray-100 dark:border-gray-700">
+        <%# Status Filter (Multi-select) %>
+        <%= render "ruby_llm/agents/shared/filter_dropdown",
+            name: "statuses[]",
+            filter_id: "statuses",
+            label: "Status",
+            all_label: "All Statuses",
+            options: status_options,
+            selected: selected_statuses %>
+
+        <%# Version Filter (Multi-select) %>
+        <% if @versions.any? %>
+          <%= render "ruby_llm/agents/shared/filter_dropdown",
+              name: "versions[]",
+              filter_id: "versions",
+              label: "Version",
+              all_label: "All Versions",
+              options: version_options,
+              selected: selected_versions,
+              icon: "M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z" %>
+        <% end %>
+
+        <%# Model Filter (Multi-select) %>
+        <% if @models.length > 1 %>
+          <%= render "ruby_llm/agents/shared/filter_dropdown",
+              name: "models[]",
+              filter_id: "models",
+              label: "Model",
+              all_label: "All Models",
+              options: model_options,
+              selected: selected_models,
+              icon: "M9.75 17L9 20l-1 1h8l-1-1-.75-3M3 13h18M5 17h14a2 2 0 002-2V5a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z" %>
+        <% end %>
+
+        <%# Temperature Filter (Multi-select) %>
+        <% if @temperatures.length > 1 %>
+          <%= render "ruby_llm/agents/shared/filter_dropdown",
+              name: "temperatures[]",
+              filter_id: "temperatures",
+              label: "Temp",
+              all_label: "All Temps",
+              options: temperature_options,
+              selected: selected_temperatures,
+              icon: "M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" %>
+        <% end %>
+
+        <%# Time Range Filter (Single-select) %>
+        <%= render "ruby_llm/agents/shared/select_dropdown",
+            name: "days",
+            filter_id: "days",
+            options: days_options,
+            selected: params[:days].to_s,
+            icon: "M8 7V3m8 4V3m-9 8h10M5 21h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z" %>
+
+        <%# Clear Filters %>
+        <% if has_filters %>
+          <%= link_to ruby_llm_agents.workflow_path(@workflow_type),
+              class: "flex items-center gap-1 px-3 py-2 text-sm text-red-500 dark:text-red-400 hover:text-red-600 dark:hover:text-red-300 hover:bg-red-50 dark:hover:bg-red-900/30 rounded-lg transition-colors" do %>
+            <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/>
+            </svg>
+            Clear
+          <% end %>
+        <% end %>
+
+        <%# Stats Summary (right aligned) %>
+        <div class="ml-auto flex items-center gap-4 text-sm text-gray-500 dark:text-gray-400">
+          <span><%= number_with_delimiter(@filter_stats[:total_count]) %> executions</span>
+          <span class="text-gray-300 dark:text-gray-600">|</span>
+          <span>$<%= number_with_precision(@filter_stats[:total_cost] || 0, precision: 4) %></span>
+          <span class="text-gray-300 dark:text-gray-600">|</span>
+          <span><%= number_with_delimiter(@filter_stats[:total_tokens] || 0) %> tokens</span>
+        </div>
+      </div>
+    <% end %>
+
+    <%= render "ruby_llm/agents/shared/executions_table", executions: @executions, pagination: @pagination %>
+  </div>
+</div>

data/config/routes.rb

@@ -5,6 +5,7 @@ RubyLLM::Agents::Engine.routes.draw do
   get "chart_data", to: "dashboard#chart_data"
 
   resources :agents, only: [:index, :show]
+  resources :workflows, only: [:show]
 
   resources :executions, only: [:index, :show] do
     collection do

data/lib/generators/ruby_llm_agents/agent_generator.rb

@@ -7,9 +7,10 @@ module RubyLlmAgents
   #
   # Usage:
   #   rails generate ruby_llm_agents:agent SearchIntent query:required limit:10
+  #   rails generate ruby_llm_agents:agent SearchIntent query:required --root=ai
   #
   # This will create:
-  #   - app/agents/search_intent_agent.rb
+  #   - app/{root}/agents/search_intent_agent.rb
   #
   # Parameter syntax:
   #   name           - Optional parameter
@@ -27,28 +28,76 @@ module RubyLlmAgents
                  desc: "The temperature setting (0.0-1.0)"
     class_option :cache, type: :string, default: nil,
                  desc: "Cache TTL (e.g., '1.hour', '30.minutes')"
+    class_option :root,
+                 type: :string,
+                 default: nil,
+                 desc: "Root directory name (default: uses config or 'llm')"
+    class_option :namespace,
+                 type: :string,
+                 default: nil,
+                 desc: "Root namespace (default: camelized root or config)"
+
+    def ensure_base_class_and_skill_file
+      @root_namespace = root_namespace
+      agents_dir = "app/#{root_directory}/agents"
+
+      # Create directory if needed
+      empty_directory agents_dir
+
+      # Create base class if it doesn't exist
+      base_class_path = "#{agents_dir}/application_agent.rb"
+      unless File.exist?(File.join(destination_root, base_class_path))
+        template "application_agent.rb.tt", base_class_path
+      end
+
+      # Create skill file if it doesn't exist
+      skill_file_path = "#{agents_dir}/AGENTS.md"
+      unless File.exist?(File.join(destination_root, skill_file_path))
+        template "skills/AGENTS.md.tt", skill_file_path
+      end
+    end
 
     def create_agent_file
-      # Support nested paths: "chat/support" -> "app/agents/chat/support_agent.rb"
+      # Support nested paths: "chat/support" -> "app/{root}/agents/chat/support_agent.rb"
       # Rails' class_name handles namespacing: "chat/support" -> "Chat::Support"
+      @root_namespace = root_namespace
       agent_path = name.underscore
-      template "agent.rb.tt", "app/agents/#{agent_path}_agent.rb"
+      template "agent.rb.tt", "app/#{root_directory}/agents/#{agent_path}_agent.rb"
     end
 
     def show_usage
       # Build full class name from path (e.g., "chat/support" -> "Chat::Support")
-      full_class_name = name.split('/').map(&:camelize).join("::")
+      agent_class_name = name.split("/").map(&:camelize).join("::")
+      full_class_name = "#{root_namespace}::#{agent_class_name}Agent"
       say ""
-      say "Agent #{full_class_name}Agent created!", :green
+      say "Agent #{full_class_name} created!", :green
       say ""
       say "Usage:"
-      say "  #{full_class_name}Agent.call(#{usage_params})"
-      say "  #{full_class_name}Agent.call(#{usage_params}, dry_run: true)"
+      say "  #{full_class_name}.call(#{usage_params})"
+      say "  #{full_class_name}.call(#{usage_params}, dry_run: true)"
       say ""
     end
 
     private
 
+    def root_directory
+      @root_directory ||= options[:root] || RubyLLM::Agents.configuration.root_directory
+    end
+
+    def root_namespace
+      @root_namespace ||= options[:namespace] || camelize(root_directory)
+    end
+
+    def camelize(str)
+      # Handle special cases for common abbreviations
+      return "AI" if str.downcase == "ai"
+      return "ML" if str.downcase == "ml"
+      return "LLM" if str.downcase == "llm"
+
+      # Standard camelization
+      str.split(/[-_]/).map(&:capitalize).join
+    end
+
     def parsed_params
       @parsed_params ||= params.map do |param|
         name, modifier = param.split(":")

data/lib/generators/ruby_llm_agents/background_remover_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RubyLlmAgents
+  # BackgroundRemover generator for creating new background removers
+  #
+  # Usage:
+  #   rails generate ruby_llm_agents:background_remover Product
+  #   rails generate ruby_llm_agents:background_remover Portrait --model segment-anything --alpha_matting
+  #   rails generate ruby_llm_agents:background_remover Photo --refine_edges --return_mask
+  #   rails generate ruby_llm_agents:background_remover Product --root=ai
+  #
+  # This will create:
+  #   - app/{root}/image/background_removers/product_background_remover.rb
+  #
+  class BackgroundRemoverGenerator < ::Rails::Generators::NamedBase
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :model, type: :string, default: "rembg",
+                 desc: "The segmentation model to use"
+    class_option :output_format, type: :string, default: "png",
+                 desc: "Output format (png, webp)"
+    class_option :refine_edges, type: :boolean, default: false,
+                 desc: "Enable edge refinement"
+    class_option :alpha_matting, type: :boolean, default: false,
+                 desc: "Enable alpha matting for better edges"
+    class_option :return_mask, type: :boolean, default: false,
+                 desc: "Also return the segmentation mask"
+    class_option :cache, type: :string, default: nil,
+                 desc: "Cache TTL (e.g., '1.hour', '1.day')"
+    class_option :root,
+                 type: :string,
+                 default: nil,
+                 desc: "Root directory name (default: uses config or 'llm')"
+    class_option :namespace,
+                 type: :string,
+                 default: nil,
+                 desc: "Root namespace (default: camelized root or config)"
+
+    def ensure_base_class_and_skill_file
+      @root_namespace = root_namespace
+      @image_namespace = "#{root_namespace}::Image"
+      removers_dir = "app/#{root_directory}/image/background_removers"
+
+      # Create directory if needed
+      empty_directory removers_dir
+
+      # Create base class if it doesn't exist
+      base_class_path = "#{removers_dir}/application_background_remover.rb"
+      unless File.exist?(File.join(destination_root, base_class_path))
+        template "application_background_remover.rb.tt", base_class_path
+      end
+
+      # Create skill file if it doesn't exist
+      skill_file_path = "#{removers_dir}/BACKGROUND_REMOVERS.md"
+      unless File.exist?(File.join(destination_root, skill_file_path))
+        template "skills/BACKGROUND_REMOVERS.md.tt", skill_file_path
+      end
+    end
+
+    def create_background_remover_file
+      @root_namespace = root_namespace
+      @image_namespace = "#{root_namespace}::Image"
+      remover_path = name.underscore
+      template "background_remover.rb.tt", "app/#{root_directory}/image/background_removers/#{remover_path}_background_remover.rb"
+    end
+
+    def show_usage
+      remover_class_name = name.split("/").map(&:camelize).join("::")
+      full_class_name = "#{root_namespace}::Image::#{remover_class_name}BackgroundRemover"
+      say ""
+      say "Background remover #{full_class_name} created!", :green
+      say ""
+      say "Usage:"
+      say "  # Remove background from an image"
+      say "  result = #{full_class_name}.call(image: 'photo.jpg')"
+      say "  result.url        # => 'https://...' (transparent PNG)"
+      say "  result.has_alpha? # => true"
+      say ""
+      say "  # Override settings at runtime"
+      say "  result = #{full_class_name}.call("
+      say "    image: 'portrait.jpg',"
+      say "    alpha_matting: true,"
+      say "    return_mask: true"
+      say "  )"
+      say ""
+      say "  # Access the segmentation mask"
+      say "  result.mask_url  # => 'https://...' (if return_mask was enabled)"
+      say ""
+    end
+
+    private
+
+    def root_directory
+      @root_directory ||= options[:root] || RubyLLM::Agents.configuration.root_directory
+    end
+
+    def root_namespace
+      @root_namespace ||= options[:namespace] || camelize(root_directory)
+    end
+
+    def camelize(str)
+      return "AI" if str.downcase == "ai"
+      return "ML" if str.downcase == "ml"
+      return "LLM" if str.downcase == "llm"
+      str.split(/[-_]/).map(&:capitalize).join
+    end
+  end
+end