ruby_llm-agents 3.8.0 → 3.10.0

data/lib/generators/ruby_llm_agents/demo_generator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RubyLlmAgents
+  # Demo generator — scaffolds a working HelloAgent with a smoke-test script.
+  #
+  # Usage:
+  #   rails generate ruby_llm_agents:demo
+  #
+  # Creates:
+  #   - app/agents/hello_agent.rb        — minimal working agent
+  #   - bin/smoke_test_agent             — one-command verification script
+  #
+  class DemoGenerator < ::Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def ensure_base_class
+      agents_dir = "app/agents"
+      empty_directory agents_dir
+
+      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
+    end
+
+    def create_hello_agent
+      create_file "app/agents/hello_agent.rb", <<~RUBY
+        # frozen_string_literal: true
+
+        class HelloAgent < ApplicationAgent
+          system "You are a friendly assistant. Keep responses under 2 sentences."
+
+          prompt "Say hello to {name} and tell them one fun fact."
+        end
+      RUBY
+    end
+
+    def create_smoke_test
+      create_file "bin/smoke_test_agent", <<~RUBY
+        #!/usr/bin/env ruby
+        # frozen_string_literal: true
+
+        # Smoke test — verifies your RubyLLM::Agents setup end-to-end.
+        #
+        # Usage:
+        #   bin/rails runner bin/smoke_test_agent
+        #
+        puts "Running RubyLLM::Agents smoke test..."
+        puts ""
+
+        # 1. Check configuration
+        config = RubyLLM::Agents.configuration
+        model = config.default_model
+        puts "Default model: \#{model}"
+
+        # 2. Dry-run (no API call)
+        puts ""
+        puts "Dry run:"
+        dry = HelloAgent.call(name: "World", dry_run: true)
+        puts "  System prompt: \#{dry.system_prompt[0..80]}..."
+        puts "  User prompt:   \#{dry.user_prompt}"
+        puts "  Model:         \#{dry.model}"
+        puts "  Dry run OK!"
+
+        # 3. Live call
+        puts ""
+        puts "Live call (calling \#{model})..."
+        begin
+          result = HelloAgent.call(name: "World")
+          puts "  Response: \#{result.content}"
+          puts ""
+          puts "Success! Your setup is working."
+        rescue => e
+          puts "  Error: \#{e.class}: \#{e.message}"
+          puts ""
+          puts "The dry run worked but the live call failed."
+          puts "This usually means your API key is missing or invalid."
+          puts ""
+          puts "Run 'rails ruby_llm_agents:doctor' for detailed diagnostics."
+          exit 1
+        end
+      RUBY
+
+      chmod "bin/smoke_test_agent", 0o755
+    end
+
+    def show_next_steps
+      say ""
+      say "Demo agent created!", :green
+      say ""
+      say "Try it:"
+      say "  bin/rails runner bin/smoke_test_agent"
+      say ""
+      say "Or in the Rails console:"
+      say "  HelloAgent.call(name: \"World\")"
+      say "  HelloAgent.call(name: \"World\", dry_run: true)"
+      say ""
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/doctor_generator.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RubyLlmAgents
+  # Doctor generator — validates that setup is complete and working.
+  #
+  # Usage:
+  #   rails generate ruby_llm_agents:doctor
+  #   rails ruby_llm_agents:doctor   (rake task alias)
+  #
+  # Checks:
+  #   1. API keys — at least one provider key is configured
+  #   2. Migrations — required tables exist
+  #   3. Routes — engine is mounted
+  #   4. Background jobs — ActiveJob adapter is configured (not :async/:inline in prod)
+  #   5. Agents — at least one agent file exists
+  #
+  class DoctorGenerator < ::Rails::Generators::Base
+    desc "Validate your RubyLLM::Agents setup and print actionable fixes"
+
+    def run_checks
+      @pass = 0
+      @fail = 0
+      @warn = 0
+
+      say ""
+      say "RubyLLM::Agents Doctor", :bold
+      say "=" * 40
+
+      check_api_keys
+      check_migrations
+      check_routes
+      check_background_jobs
+      check_agents
+
+      say ""
+      say "=" * 40
+      summary = "#{@pass} passed, #{@fail} failed, #{@warn} warnings"
+      if @fail > 0
+        say "Result: #{summary}", :red
+      elsif @warn > 0
+        say "Result: #{summary}", :yellow
+      else
+        say "Result: #{summary} — you're all set!", :green
+      end
+      say ""
+    end
+
+    private
+
+    def check_api_keys
+      say ""
+      say "API Keys", :bold
+
+      config = RubyLLM::Agents.configuration
+      providers = {
+        "OpenAI" => -> { config.openai_api_key },
+        "Anthropic" => -> { config.anthropic_api_key },
+        "Gemini" => -> { config.gemini_api_key },
+        "DeepSeek" => -> { config.deepseek_api_key },
+        "OpenRouter" => -> { config.openrouter_api_key },
+        "Mistral" => -> { config.mistral_api_key }
+      }
+
+      configured = providers.select { |_, v| v.call.present? }.keys
+
+      if configured.any?
+        configured.each { |name| pass "#{name} API key configured" }
+      else
+        fail_check "No API keys configured"
+        fix "Add to config/initializers/ruby_llm_agents.rb:"
+        fix "  config.openai_api_key = ENV[\"OPENAI_API_KEY\"]"
+        fix "Then set the environment variable in .env or credentials."
+      end
+    end
+
+    def check_migrations
+      say ""
+      say "Database", :bold
+
+      tables = {
+        "ruby_llm_agents_executions" => "rails generate ruby_llm_agents:install && rails db:migrate",
+        "ruby_llm_agents_execution_details" => "rails generate ruby_llm_agents:upgrade && rails db:migrate"
+      }
+
+      tables.each do |table, fix_cmd|
+        if table_exists?(table)
+          pass "Table #{table} exists"
+        else
+          fail_check "Table #{table} missing"
+          fix fix_cmd
+        end
+      end
+    end
+
+    def check_routes
+      say ""
+      say "Routes", :bold
+
+      routes_file = File.join(destination_root, "config/routes.rb")
+      if File.exist?(routes_file)
+        content = File.read(routes_file)
+        if content.include?("RubyLLM::Agents::Engine")
+          pass "Dashboard engine mounted"
+        else
+          warn_check "Dashboard engine not mounted in routes"
+          fix "Add to config/routes.rb:"
+          fix "  mount RubyLLM::Agents::Engine => \"/agents\""
+        end
+      else
+        warn_check "Could not find config/routes.rb"
+      end
+    end
+
+    def check_background_jobs
+      say ""
+      say "Background Jobs", :bold
+
+      adapter = ActiveJob::Base.queue_adapter.class.name
+      async_logging = RubyLLM::Agents.configuration.async_logging
+
+      if !async_logging
+        pass "Async logging disabled (synchronous mode)"
+      elsif adapter.include?("Async") || adapter.include?("Inline")
+        if Rails.env.production?
+          warn_check "ActiveJob adapter is #{adapter} — execution logging may be lost in production"
+          fix "Configure a persistent adapter (Sidekiq, GoodJob, SolidQueue, etc.)"
+          fix "Or set config.async_logging = false for synchronous logging."
+        else
+          pass "ActiveJob adapter: #{adapter} (OK for development)"
+        end
+      else
+        pass "ActiveJob adapter: #{adapter}"
+      end
+    end
+
+    def check_agents
+      say ""
+      say "Agents", :bold
+
+      agents_dir = File.join(destination_root, "app/agents")
+      if Dir.exist?(agents_dir)
+        agent_files = Dir.glob(File.join(agents_dir, "**/*_agent.rb"))
+          .reject { |f| f.end_with?("application_agent.rb") }
+
+        if agent_files.any?
+          pass "Found #{agent_files.size} agent(s)"
+        else
+          warn_check "No agents found (only application_agent.rb)"
+          fix "rails generate ruby_llm_agents:agent HelloWorld query:required"
+          fix "Or: rails generate ruby_llm_agents:demo"
+        end
+      else
+        fail_check "app/agents/ directory missing"
+        fix "rails generate ruby_llm_agents:install"
+      end
+    end
+
+    # Helpers
+
+    def table_exists?(name)
+      ActiveRecord::Base.connection.table_exists?(name)
+    rescue => e
+      say "  (Could not check database: #{e.message})", :yellow
+      false
+    end
+
+    def pass(msg)
+      @pass += 1
+      say "  #{status_icon(:pass)} #{msg}", :green
+    end
+
+    def fail_check(msg)
+      @fail += 1
+      say "  #{status_icon(:fail)} #{msg}", :red
+    end
+
+    def warn_check(msg)
+      @warn += 1
+      say "  #{status_icon(:warn)} #{msg}", :yellow
+    end
+
+    def fix(msg)
+      say "    Fix: #{msg}"
+    end
+
+    def status_icon(type)
+      case type
+      when :pass then "OK"
+      when :fail then "FAIL"
+      when :warn then "WARN"
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm_agents/install_generator.rb

@@ -96,28 +96,16 @@ module RubyLlmAgents
       say ""
       say "RubyLLM::Agents has been installed!", :green
       say ""
-      say "Directory structure created:"
-      say "  app/"
-      say "  ├── agents/"
-      say "  │   ├── application_agent.rb"
-      say "  │   ├── concerns/"
-      say "  │   └── AGENTS.md"
-      say "  └── tools/"
-      say "      └── TOOLS.md"
-      say ""
-      say "Skill files (*.md) help AI coding assistants understand how to use this gem."
-      say ""
       say "Next steps:"
-      say "  1. Set your API keys in config/initializers/ruby_llm_agents.rb"
+      say "  1. Set your API key in config/initializers/ruby_llm_agents.rb"
       say "  2. Run migrations: rails db:migrate"
-      say "  3. Generate an agent: rails generate ruby_llm_agents:agent MyAgent query:required"
-      say "  4. Access the dashboard at: /agents"
+      say "  3. Verify setup:   rails ruby_llm_agents:doctor"
+      say "  4. Try it out:     rails generate ruby_llm_agents:demo"
+      say ""
+      say "Or generate a custom agent:"
+      say "  rails generate ruby_llm_agents:agent MyAgent query:required"
       say ""
-      say "Generator commands:"
-      say "  rails generate ruby_llm_agents:agent CustomerSupport query:required"
-      say "  rails generate ruby_llm_agents:image_generator Product"
-      say "  rails generate ruby_llm_agents:transcriber Meeting"
-      say "  rails generate ruby_llm_agents:embedder Semantic"
+      say "Dashboard: /agents"
       say ""
     end
 

data/lib/generators/ruby_llm_agents/templates/agent.rb.tt

@@ -8,108 +8,55 @@
 <%- else -%>
 class <%= class_name %>Agent < ApplicationAgent
 <%- end -%>
-    # ============================================
-    # Model Configuration
-    # ============================================
-
+<% if options[:model] != "default" -%>
     model "<%= options[:model] %>"
+<% end -%>
+<% if options[:temperature] != 0.0 -%>
     temperature <%= options[:temperature] %>
-    # timeout 30  # Per-request timeout in seconds (default: 60)
-
-    # ============================================
-    # Caching
-    # ============================================
-
-<% if options[:cache] -%>
-    cache <%= options[:cache] %>
-<% else -%>
-    # cache 1.hour  # Enable response caching with TTL
 <% end -%>
 
     # ============================================
-    # Reliability (Retries & Fallbacks)
+    # Prompts
     # ============================================
+    # Use {placeholder} syntax — placeholders become required params automatically.
 
-    # Automatic retries with exponential backoff
-    # - max: Number of retry attempts
-    # - backoff: :constant or :exponential
-    # - base: Base delay in seconds
-    # - max_delay: Maximum delay between retries
-    # - on: Additional error classes to retry on
-    # retries max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0
-
-    # Fallback models (tried in order when primary model fails)
-    # fallback_models ["gpt-4o-mini", "claude-3-haiku"]
-
-    # Total timeout across all retry/fallback attempts
-    # total_timeout 30
-
-    # Circuit breaker (prevents repeated calls to failing models)
-    # - errors: Number of errors to trigger open state
-    # - within: Rolling window in seconds
-    # - cooldown: Time to wait before allowing requests again
-    # circuit_breaker errors: 5, within: 60, cooldown: 300
-
-    # ============================================
-    # Parameters
-    # ============================================
+    system "You are a helpful assistant."
 
-<% parsed_params.each do |param| -%>
-    param :<%= param.name %><%= ", required: true" if param.required? %><%= ", default: #{param.default.inspect}" if param.default && !param.required? %>
+<% if parsed_params.any? -%>
+    prompt "<%= parsed_params.map { |p| "{#{p.name}}" }.join(" ") %>"
+<% else -%>
+    prompt "Your prompt here"
 <% end -%>
 
-    private
+<% parsed_params.select { |p| !p.required? && p.default }.each do |param| -%>
+    param :<%= param.name %>, default: <%= param.default.inspect %>
+<% end -%>
+<% if options[:cache] -%>
 
     # ============================================
-    # Prompts (required)
+    # Caching
     # ============================================
 
-    def system_prompt
-      <<~PROMPT
-        You are a helpful assistant.
-        # Define your system instructions here
-      PROMPT
-    end
-
-    def user_prompt
-      # Build the prompt from parameters
-<% if parsed_params.any? -%>
-      <%= parsed_params.first.name %>
-<% else -%>
-      "Your prompt here"
+    cache for: <%= options[:cache] %>
 <% end -%>
-    end
 
     # ============================================
-    # Optional Overrides
+    # Error Handling (uncomment to enable)
     # ============================================
 
-    # Structured output schema (returns parsed hash instead of raw text)
-    # def schema
-    #   @schema ||= RubyLLM::Schema.create do
-    #     string :result, description: "The result"
-    #     integer :confidence, description: "Confidence score 1-100"
-    #     array :tags, description: "Relevant tags" do
-    #       string
-    #     end
-    #   end
-    # end
-
-    # Custom response processing (default: symbolize hash keys)
-    # def process_response(response)
-    #   content = response.content
-    #   # Transform or validate the response
-    #   content
+    # on_failure do
+    #   retries times: 2, backoff: :exponential
+    #   fallback to: ["gpt-4o-mini"]
+    #   timeout 30
     # end
 
-    # Custom metadata to include in execution logs
-    # def metadata
-    #   { custom_field: "value", request_id: params[:request_id] }
-    # end
+    # ============================================
+    # Structured Output (uncomment to enable)
+    # ============================================
 
-    # Custom cache key data (default: all params except skip_cache, dry_run)
-    # def cache_key_data
-    #   { query: params[:query], locale: I18n.locale }
+    # returns do
+    #   string :result, description: "The result"
+    #   integer :confidence, description: "Confidence score 1-100"
     # end
 <%- if class_name.include?("::") -%>
 <%- (class_name.split("::").length - 1).times do |i| -%>

data/lib/generators/ruby_llm_agents/templates/application_agent.rb.tt

@@ -2,15 +2,15 @@
 
 # ApplicationAgent - Base class for all agents in this application
 #
-# All agents inherit from this class. Configure shared settings here
-# that apply to all agents, or override them per-agent as needed.
+# All agents inherit from this class. Configure shared settings here.
 #
-# Example:
+# Quick reference:
 #   class MyAgent < ApplicationAgent
-#     param :query, required: true
+#     system "You are a helpful assistant."
+#     prompt "Answer this: {query}"          # {query} becomes a required param
 #
-#     def user_prompt
-#       query
+#     returns do                             # Optional: structured output
+#       string :answer, description: "The answer"
 #     end
 #   end
 #
@@ -20,50 +20,17 @@
 #   MyAgent.call(query: "hello", skip_cache: true) # Bypass cache
 #
 class ApplicationAgent < RubyLLM::Agents::Base
-  # ============================================
-  # Shared Model Configuration
-  # ============================================
-  # These settings are inherited by all agents
-
-  # model "gemini-2.0-flash"   # Default model for all agents
-  # temperature 0.0            # Default temperature (0.0 = deterministic)
-  # timeout 60                 # Default timeout in seconds
-
-  # ============================================
-  # Shared Caching
-  # ============================================
-
-  # cache 1.hour  # Enable caching for all agents (override per-agent if needed)
-
-  # ============================================
-  # Shared Reliability Settings
-  # ============================================
-  # Configure once here, all agents inherit these settings
-
-  # Automatic retries for all agents
-  # retries max: 2, backoff: :exponential, base: 0.4, max_delay: 3.0
-
-  # Shared fallback models
-  # fallback_models ["gpt-4o-mini", "claude-3-haiku"]
-
-  # Total timeout across retries/fallbacks
-  # total_timeout 30
-
-  # Circuit breaker (per agent-model pair)
-  # circuit_breaker errors: 5, within: 60, cooldown: 300
-
-  # ============================================
-  # Shared Helper Methods
-  # ============================================
-  # Define methods here that can be used by all agents
-
-  # Example: Common system prompt prefix
-  # def system_prompt_prefix
-  #   "You are an AI assistant for #{Rails.application.class.module_parent_name}."
-  # end
-
-  # Example: Common metadata
-  # def metadata
-  #   { app_version: Rails.application.config.version }
+  # Shared settings inherited by all agents.
+  # Override per-agent as needed.
+
+  # model "gpt-4o"              # Override the configured default model
+  # temperature 0.0             # 0.0 = deterministic, 2.0 = creative
+  # cache for: 1.hour           # Enable caching for all agents
+
+  # Shared error handling (uncomment to apply to all agents)
+  # on_failure do
+  #   retries times: 2, backoff: :exponential
+  #   fallback to: ["gpt-4o-mini"]
+  #   timeout 30
   # end
 end

data/lib/generators/ruby_llm_agents/templates/initializer.rb.tt

@@ -6,29 +6,14 @@
 
 RubyLLM::Agents.configure do |config|
   # ============================================
-  # LLM Provider API Keys
+  # Quick Start — set ONE API key to get going
   # ============================================
-  # Configure at least one provider. Set these in your environment
-  # or replace ENV[] calls with your keys directly.
+  # Uncomment one line below, then run: rails ruby_llm_agents:doctor
 
   # config.openai_api_key = ENV["OPENAI_API_KEY"]
   # config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
   # config.gemini_api_key = ENV["GOOGLE_API_KEY"]
 
-  # Additional providers:
-  # config.deepseek_api_key = ENV["DEEPSEEK_API_KEY"]
-  # config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
-  # config.mistral_api_key = ENV["MISTRAL_API_KEY"]
-  # config.xai_api_key = ENV["XAI_API_KEY"]
-
-  # Custom endpoints (e.g., Azure OpenAI, local Ollama):
-  # config.openai_api_base = "https://your-resource.openai.azure.com"
-  # config.ollama_api_base = "http://localhost:11434"
-
-  # Connection settings:
-  # config.request_timeout = 120
-  # config.max_retries = 3
-
   # ============================================
   # Model Defaults
   # ============================================
@@ -46,6 +31,23 @@ RubyLLM::Agents.configure do |config|
   # When enabled, agents stream responses and track time-to-first-token
   # config.default_streaming = false
 
+  # ============================================
+  # Additional Providers (uncomment as needed)
+  # ============================================
+
+  # config.deepseek_api_key = ENV["DEEPSEEK_API_KEY"]
+  # config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+  # config.mistral_api_key = ENV["MISTRAL_API_KEY"]
+  # config.xai_api_key = ENV["XAI_API_KEY"]
+
+  # Custom endpoints (e.g., Azure OpenAI, local Ollama):
+  # config.openai_api_base = "https://your-resource.openai.azure.com"
+  # config.ollama_api_base = "http://localhost:11434"
+
+  # Connection settings:
+  # config.request_timeout = 120
+  # config.max_retries = 3
+
   # ============================================
   # Caching
   # ============================================