ruby_llm-agents 3.8.0 → 3.9.0

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
   # ============================================

data/lib/ruby_llm/agents/base_agent.rb

@@ -332,6 +332,14 @@ module RubyLLM
       # @param temperature [Float] Override the class-level temperature
       # @param options [Hash] Agent parameters defined via the param DSL
       def initialize(model: self.class.model, temperature: self.class.temperature, **options)
+        # Merge tracker defaults (shared options like tenant) — explicit opts win
+        tracker = Thread.current[:ruby_llm_agents_tracker]
+        if tracker
+          options = tracker.defaults.merge(options)
+          @_track_request_id = tracker.request_id
+          @_track_tags = tracker.tags
+        end
+
         @ask_message = options.delete(:_ask_message)
         @parent_execution_id = options.delete(:_parent_execution_id)
         @root_execution_id = options.delete(:_root_execution_id)
@@ -506,6 +514,7 @@ module RubyLLM
           stream_block: (block if streaming_enabled?),
           parent_execution_id: @parent_execution_id,
           root_execution_id: @root_execution_id,
+          debug: @options[:debug],
           options: execution_options
         )
       end
@@ -721,6 +730,10 @@ module RubyLLM
         capture_response(response, context)
         result = build_result(process_response(response), response, context)
         context.output = result
+      rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
+        raise_with_setup_hint(e, context)
+      rescue RubyLLM::ModelNotFoundError => e
+        raise_with_model_hint(e, context)
       ensure
         Thread.current[:ruby_llm_agents_caller_context] = previous_context
       end
@@ -733,12 +746,16 @@ module RubyLLM
         effective_model = context&.model || model
         chat_opts = {model: effective_model}
 
-        # Pass scoped RubyLLM context for thread-safe per-tenant API keys
+        # Use scoped RubyLLM::Context for thread-safe per-tenant API keys.
+        # RubyLLM::Context#chat creates a Chat with the scoped config,
+        # so we call .chat on the context instead of RubyLLM.chat.
         llm_ctx = context&.llm
-        chat_opts[:context] = llm_ctx if llm_ctx.is_a?(RubyLLM::Context)
-
-        client = RubyLLM.chat(**chat_opts)
-          .with_temperature(temperature)
+        client = if llm_ctx.is_a?(RubyLLM::Context)
+          llm_ctx.chat(**chat_opts)
+        else
+          RubyLLM.chat(**chat_opts)
+        end
+        client = client.with_temperature(temperature)
 
         client = client.with_instructions(system_prompt) if system_prompt
         client = client.with_schema(schema) if schema
@@ -889,8 +906,9 @@ module RubyLLM
       # @param context [Pipeline::Context] The context
       # @return [Result] The result object
       def build_result(content, response, context)
-        Result.new(
+        result_opts = {
           content: content,
+          agent_class_name: self.class.name,
           input_tokens: context.input_tokens,
           output_tokens: context.output_tokens,
           input_cost: context.input_cost,
@@ -907,7 +925,12 @@ module RubyLLM
           streaming: streaming_enabled?,
           attempts_count: context.attempts_made || 1,
           execution_id: context.execution_id
-        )
+        }
+
+        # Attach pipeline trace when debug mode is enabled
+        result_opts[:trace] = context.trace if context.trace_enabled? && context.trace.any?
+
+        Result.new(**result_opts)
       end
 
       # Extracts thinking data from a response for inclusion in Result
@@ -1077,6 +1100,44 @@ module RubyLLM
           tool_call[key] || tool_call[key.to_s]
         end
       end
+
+      # Re-raises auth errors with actionable setup guidance
+      def raise_with_setup_hint(error, context)
+        effective_model = context&.model || model
+        provider = detect_provider(effective_model)
+
+        hint = "#{self.class.name} failed: #{error.message}\n\n" \
+               "The API key for #{provider || "your provider"} is missing or invalid.\n" \
+               "Fix: Set the key in config/initializers/ruby_llm_agents.rb\n" \
+               "     or run: rails ruby_llm_agents:doctor"
+
+        raise RubyLLM::Agents::ConfigurationError, hint
+      end
+
+      # Re-raises model errors with actionable guidance
+      def raise_with_model_hint(error, context)
+        effective_model = context&.model || model
+
+        hint = "#{self.class.name} failed: #{error.message}\n\n" \
+               "Model '#{effective_model}' was not found.\n" \
+               "Fix: Check the model name or set a default in your initializer:\n" \
+               "     config.default_model = \"gpt-4o\""
+
+        raise RubyLLM::Agents::ConfigurationError, hint
+      end
+
+      # Best-effort provider detection from model name
+      def detect_provider(model_id)
+        return nil unless model_id
+
+        case model_id.to_s
+        when /gpt|o[1-9]|dall-e|whisper|tts/i then "OpenAI"
+        when /claude/i then "Anthropic"
+        when /gemini|gemma/i then "Google (Gemini)"
+        when /deepseek/i then "DeepSeek"
+        when /mistral|mixtral/i then "Mistral"
+        end
+      end
     end
   end
 end

data/lib/ruby_llm/agents/core/base.rb

@@ -87,6 +87,10 @@ module RubyLLM
         run_callbacks(:after, context, response)
 
         context.output = build_result(processed_content, response, context)
+      rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
+        raise_with_setup_hint(e, context)
+      rescue RubyLLM::ModelNotFoundError => e
+        raise_with_model_hint(e, context)
       end
 
       # Returns the resolved tenant ID for tracking

data/lib/ruby_llm/agents/core/configuration.rb

@@ -819,6 +819,16 @@ module RubyLLM
         tenant_resolver&.call
       end
 
+      # Returns a concise string representation for debugging
+      #
+      # @return [String] Summary of key configuration values
+      def inspect
+        "#<#{self.class} model=#{default_model.inspect} temperature=#{default_temperature} " \
+          "timeout=#{default_timeout} streaming=#{default_streaming} " \
+          "multi_tenancy=#{multi_tenancy_enabled} async_logging=#{async_logging} " \
+          "track_executions=#{track_executions}>"
+      end
+
       # Returns whether the async gem is available
       #
       # @return [Boolean] true if async gem is loaded

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.8.0"
+    VERSION = "3.9.0"
   end
 end