ruby_llm-agents 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f2dcacc45b93f72d6de4f0d8ac2f56d85288f9cacc5495838fbc40473714ddf
-  data.tar.gz: d6e2e7d7c78d9f6443cf8f01fa43733951e552922418ba8ee7226df4977d51a1
+  metadata.gz: 0a12fa00f68f2dcc889d91017ac8a009796089b19ab81908cdbd1e33f24f9cea
+  data.tar.gz: cb1ed8fc426ed31e51b0796e5deb7f570410a562b7d579eb0e486046d3fb4d2c
 SHA512:
-  metadata.gz: 3231be55f4d51f39bb8339ac878a82eef2c2ee5d2894a53356c43a7fc20fd9381141e19d1b447e7c755a6117d687a241e7d3be701792ebf5e97ce3f5e7cf4758
-  data.tar.gz: d89ded2027aa6ef14494216a116fcf42a6b549128677ec24a3881a63109f06a15955d0c824d7b3ff9c8aeecaa1ebdd675099d38bb5a9dce8dd4344bf045cd15f
+  metadata.gz: bf6939777a18aa2a00b213373bb3400cf17be976422bb412ef665405f5b2b2281978e025b88231816d3433c4ac2d52793aafd046372ae608a6ba6e6d70e8f771
+  data.tar.gz: 274e161fc65dd2e5f36a5c552a0e086576470505011aee2ce9713669a027e81b7e1c964e3638dca835f432b60a6a9282c2eaca72e7b2086bf469e6d6c72b35d2

data/README.md

@@ -9,6 +9,7 @@
 > **Production-ready Rails engine for building, managing, and monitoring LLM-powered AI agents**
 
 [![Gem Version](https://badge.fury.io/rb/ruby_llm-agents.svg)](https://rubygems.org/gems/ruby_llm-agents)
+[![CI](https://github.com/adham90/ruby_llm-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/adham90/ruby_llm-agents/actions/workflows/ci.yml)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg)](https://www.ruby-lang.org)
 [![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-red.svg)](https://rubyonrails.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -26,16 +27,15 @@ Build intelligent AI agents in Ruby with a clean DSL, automatic execution tracki
 ## Show Me the Code
 
 ```ruby
-# app/agents/search_intent_agent.rb
+# Template agent — structured input via .call
 class SearchIntentAgent < ApplicationAgent
   model "gpt-4o"
   temperature 0.0
 
-  # Prompts with {placeholder} syntax - params auto-registered
   system "You are a search intent analyzer. Extract structured data from queries."
-  prompt "Extract search intent from: {query}"
+  user "Extract search intent from: {query}"
+  assistant '{"refined_query":'  # Force JSON output
 
-  # Structured output with returns DSL
   returns do
     string :refined_query, description: "Cleaned search query"
     array :filters, of: :string, description: "Extracted filters"
@@ -51,15 +51,17 @@ result.duration_ms    # => 850
 ```
 
 ```ruby
-# Multi-turn conversations
-result = ChatAgent.call(
-  query: "What's my name?",
-  messages: [
-    { role: :user, content: "My name is Alice" },
-    { role: :assistant, content: "Nice to meet you, Alice!" }
-  ]
-)
-# => "Your name is Alice!"
+# Conversational agent — freeform input via .ask
+class RubyExpert < ApplicationAgent
+  model "claude-sonnet-4-5-20250929"
+  system "You are a senior Ruby developer with 20 years of experience."
+end
+
+result = RubyExpert.ask("What's the difference between proc and lambda?")
+puts result.content
+
+# Stream the response
+RubyExpert.ask("Explain metaprogramming") { |chunk| print chunk.content }
 ```
 
 ```ruby
@@ -67,7 +69,7 @@ result = ChatAgent.call(
 class ReliableAgent < ApplicationAgent
   model "gpt-4o"
 
-  prompt "{query}"
+  user "{query}"
 
   on_failure do
     retries times: 3, backoff: :exponential
@@ -152,6 +154,19 @@ rails db:migrate
 
 ### Configure API Keys
 
+Configure all provider API keys in one place (v2.1+):
+
+```ruby
+# config/initializers/ruby_llm_agents.rb
+RubyLLM::Agents.configure do |config|
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  config.gemini_api_key = ENV["GOOGLE_API_KEY"]
+end
+```
+
+Or use environment variables directly (auto-detected by RubyLLM):
+
 ```bash
 # .env
 OPENAI_API_KEY=sk-...
@@ -174,7 +189,16 @@ This creates `app/agents/search_intent_agent.rb` with the agent class ready to c
 mount RubyLLM::Agents::Engine => "/agents"
 ```
 
-![RubyLLM Agents Dashboard](screenshot.png)
+<table>
+  <tr>
+    <td><img src="screenshots/dashboard.png" alt="Dashboard Overview" width="400"></td>
+    <td><img src="screenshots/agents.png" alt="Agent Registry" width="400"></td>
+  </tr>
+  <tr>
+    <td><img src="screenshots/executions.png" alt="Execution Log" width="400"></td>
+    <td><img src="screenshots/tenants.png" alt="Multi-Tenancy" width="400"></td>
+  </tr>
+</table>
 
 ## Documentation
 
@@ -193,7 +217,7 @@ mount RubyLLM::Agents::Engine => "/agents"
 | [Testing Agents](https://github.com/adham90/ruby_llm-agents/wiki/Testing-Agents) | RSpec patterns, mocking, dry_run mode |
 | [Error Handling](https://github.com/adham90/ruby_llm-agents/wiki/Error-Handling) | Error types, recovery patterns |
 | [Embeddings](https://github.com/adham90/ruby_llm-agents/wiki/Embeddings) | Vector embeddings, batching, caching, preprocessing |
-| [Image Generation](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) | Text-to-image, templates, content policy, cost tracking |
+| [Image Generation](https://github.com/adham90/ruby_llm-agents/wiki/Image-Generation) | Text-to-image, templates, pipelines, cost tracking |
 | [Dashboard](https://github.com/adham90/ruby_llm-agents/wiki/Dashboard) | Setup, authentication, analytics |
 | [Production](https://github.com/adham90/ruby_llm-agents/wiki/Production-Deployment) | Deployment best practices, background jobs |
 | [API Reference](https://github.com/adham90/ruby_llm-agents/wiki/API-Reference) | Complete class documentation |
@@ -203,7 +227,7 @@ mount RubyLLM::Agents::Engine => "/agents"
 
 - **Ruby** >= 3.1.0
 - **Rails** >= 7.0
-- **RubyLLM** >= 1.0
+- **RubyLLM** >= 1.12.0
 
 ## Contributing
 

data/app/models/ruby_llm/agents/execution.rb

@@ -359,14 +359,18 @@ module RubyLLM
 
       # Resolves model info for cost calculation
       #
+      # Uses Models.find (local registry lookup) rather than Models.resolve
+      # because cost calculation only needs pricing data, not a provider instance.
+      # Models.resolve requires API keys to instantiate the provider, which may
+      # not be available in background jobs or instrumentation contexts.
+      #
       # @param lookup_model_id [String, nil] The model identifier (defaults to self.model_id)
       # @return [Object, nil] Model info or nil
       def resolve_model_info(lookup_model_id = nil)
         lookup_model_id ||= model_id
         return nil unless lookup_model_id
 
-        model, _provider = RubyLLM::Models.resolve(lookup_model_id)
-        model
+        RubyLLM::Models.find(lookup_model_id)
       rescue StandardError
         nil
       end

data/app/views/layouts/ruby_llm/agents/application.html.erb

@@ -148,12 +148,13 @@
 
         <!-- Desktop Navigation -->
         <nav class="hidden md:flex items-center ml-8 gap-0.5 font-mono text-xs">
-          <% [
+          <% nav_items = [
             [ruby_llm_agents.root_path, "dashboard"],
             [ruby_llm_agents.agents_path, "agents"],
-            [ruby_llm_agents.executions_path, "executions"],
-            [ruby_llm_agents.tenants_path, "tenants"]
-          ].each do |path, label| %>
+            [ruby_llm_agents.executions_path, "executions"]
+          ]
+          nav_items << [ruby_llm_agents.tenants_path, "tenants"] if tenant_filter_enabled?
+          nav_items.each do |path, label| %>
             <% active = current_page?(path) %>
             <%= link_to label, path, class: "px-2.5 py-1 rounded transition-colors #{active ? 'text-gray-900 dark:text-gray-100 bg-gray-100 dark:bg-gray-800' : 'text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300'}" %>
           <% end %>
@@ -197,12 +198,13 @@
         class="md:hidden border-t border-gray-200 dark:border-gray-800"
       >
         <nav class="max-w-7xl mx-auto px-4 py-2 font-mono text-xs space-y-0.5">
-          <% [
+          <% mobile_nav_items = [
             [ruby_llm_agents.root_path, "dashboard"],
             [ruby_llm_agents.agents_path, "agents"],
-            [ruby_llm_agents.executions_path, "executions"],
-            [ruby_llm_agents.tenants_path, "tenants"]
-          ].each do |path, label| %>
+            [ruby_llm_agents.executions_path, "executions"]
+          ]
+          mobile_nav_items << [ruby_llm_agents.tenants_path, "tenants"] if tenant_filter_enabled?
+          mobile_nav_items.each do |path, label| %>
             <% active = current_page?(path) %>
             <%= link_to label, path, class: "block px-3 py-2 rounded transition-colors #{active ? 'text-gray-900 dark:text-gray-100 bg-gray-100 dark:bg-gray-800' : 'text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300'}" %>
           <% end %>

data/lib/generators/ruby_llm_agents/install_generator.rb

@@ -108,9 +108,10 @@ module RubyLlmAgents
       say "Skill files (*.md) help AI coding assistants understand how to use this gem."
       say ""
       say "Next steps:"
-      say "  1. Run migrations: rails db:migrate"
-      say "  2. Generate an agent: rails generate ruby_llm_agents:agent MyAgent query:required"
-      say "  3. Access the dashboard at: /agents"
+      say "  1. Set your API keys 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 ""
       say "Generator commands:"
       say "  rails generate ruby_llm_agents:agent CustomerSupport query:required"

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

@@ -5,6 +5,30 @@
 # For more information, see: https://github.com/adham90/ruby_llm-agents
 
 RubyLLM::Agents.configure do |config|
+  # ============================================
+  # LLM Provider API Keys
+  # ============================================
+  # Configure at least one provider. Set these in your environment
+  # or replace ENV[] calls with your keys directly.
+
+  # 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
   # ============================================

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -60,6 +60,28 @@ module RubyLlmAgents
       )
     end
 
+    def suggest_config_consolidation
+      ruby_llm_initializer = File.join(destination_root, "config/initializers/ruby_llm.rb")
+      agents_initializer = File.join(destination_root, "config/initializers/ruby_llm_agents.rb")
+
+      return unless File.exist?(ruby_llm_initializer) && File.exist?(agents_initializer)
+
+      say ""
+      say "Optional: You can now consolidate your API key configuration.", :yellow
+      say ""
+      say "Move your API keys from config/initializers/ruby_llm.rb"
+      say "into config/initializers/ruby_llm_agents.rb:"
+      say ""
+      say "  RubyLLM::Agents.configure do |config|"
+      say "    config.openai_api_key = ENV['OPENAI_API_KEY']"
+      say "    config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']"
+      say "    # ... rest of your agent config"
+      say "  end"
+      say ""
+      say "Then delete config/initializers/ruby_llm.rb if it only contained API keys."
+      say ""
+    end
+
     def show_post_upgrade_message
       say ""
       say "RubyLLM::Agents upgrade complete!", :green

data/lib/ruby_llm/agents/base_agent.rb

@@ -76,6 +76,39 @@ module RubyLLM
           instance.call(&block)
         end
 
+        # Executes the agent with a freeform message as the user prompt
+        #
+        # Designed for conversational agents that define a persona (system +
+        # optional assistant prefill) but accept freeform input at runtime.
+        # Also works on template agents as an escape hatch to bypass the
+        # user template.
+        #
+        # @param message [String] The user message to send
+        # @param with [String, Array<String>, nil] Attachments (files, URLs)
+        # @param kwargs [Hash] Additional options (model:, temperature:, etc.)
+        # @yield [chunk] Yields chunks when streaming
+        # @return [Result] The processed response
+        #
+        # @example Basic usage
+        #   RubyExpert.ask("What is metaprogramming?")
+        #
+        # @example With streaming
+        #   RubyExpert.ask("Explain closures") { |chunk| print chunk.content }
+        #
+        # @example With attachments
+        #   RubyExpert.ask("What's in this image?", with: "photo.jpg")
+        #
+        def ask(message, with: nil, **kwargs, &block)
+          opts = kwargs.merge(_ask_message: message)
+          opts[:with] = with if with
+
+          if block
+            stream(**opts, &block)
+          else
+            call(**opts)
+          end
+        end
+
         # Returns the agent type for this class
         #
         # Used by middleware to determine which tracking/budget config to use.
@@ -221,12 +254,13 @@ 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)
+        @ask_message = options.delete(:_ask_message)
         @model = model
         @temperature = temperature
         @options = options
         @tracked_tool_calls = []
         @pending_tool_call = nil
-        validate_required_params!
+        validate_required_params! unless @ask_message
       end
 
       # Executes the agent through the middleware pipeline
@@ -245,15 +279,21 @@ module RubyLLM
 
       # User prompt to send to the LLM
       #
-      # If a class-level `prompt` DSL is defined (string template or block),
-      # it will be used. Otherwise, subclasses must implement this method.
+      # Resolution order:
+      # 1. Subclass method override (standard Ruby dispatch — this method is never called)
+      # 2. .ask(message) runtime message — bypasses template
+      # 3. Class-level `user` / `prompt` template — interpolated with {placeholders}
+      # 4. Inherited from superclass
+      # 5. NotImplementedError
       #
       # @return [String] The user prompt
       def user_prompt
-        prompt_config = self.class.prompt_config
-        return resolve_prompt_from_config(prompt_config) if prompt_config
+        return @ask_message if @ask_message
+
+        config = self.class.user_config
+        return resolve_prompt_from_config(config) if config
 
-        raise NotImplementedError, "#{self.class} must implement #user_prompt or use the prompt DSL"
+        raise NotImplementedError, "#{self.class} must implement #user_prompt, use the `user` DSL, or call with .ask(message)"
       end
 
       # System prompt for LLM instructions
@@ -269,6 +309,19 @@ module RubyLLM
         nil
       end
 
+      # Assistant prefill to prime the model's response
+      #
+      # If a class-level `assistant` DSL is defined, it will be used.
+      # Otherwise returns nil (no prefill).
+      #
+      # @return [String, nil] The assistant prefill, or nil for none
+      def assistant_prompt
+        config = self.class.assistant_config
+        return resolve_prompt_from_config(config) if config
+
+        nil
+      end
+
       # Response schema for structured output
       #
       # Delegates to the class-level schema DSL by default.
@@ -381,6 +434,7 @@ module RubyLLM
         {
           temperature: temperature,
           system_prompt: system_prompt,
+          assistant_prefill: assistant_prompt,
           schema: schema,
           messages: resolved_messages,
           tools: resolved_tools,
@@ -419,11 +473,26 @@ module RubyLLM
 
       # Resolves messages for this execution
       #
+      # Includes conversation history and assistant prefill if defined.
+      # The assistant prefill is appended as the last message so it appears
+      # after the user prompt in the conversation.
+      #
       # @return [Array<Hash>] Messages to apply
       def resolved_messages
-        return @options[:messages] if @options[:messages]&.any?
+        msgs = @options[:messages]&.any? ? @options[:messages] : messages
+        msgs.dup
+      end
+
+      # Returns the assistant prefill message if defined
+      #
+      # Called after the user prompt is sent to inject the prefill.
+      #
+      # @return [Hash, nil] The assistant prefill message hash, or nil
+      def resolved_assistant_prefill
+        prefill = assistant_prompt
+        return nil if prefill.nil? || (prefill.is_a?(String) && prefill.empty?)
 
-        messages
+        { role: :assistant, content: prefill }
       end
 
       # Returns whether streaming is enabled
@@ -446,6 +515,7 @@ module RubyLLM
             timeout: self.class.timeout,
             system_prompt: system_prompt,
             user_prompt: user_prompt,
+            assistant_prompt: assistant_prompt,
             attachments: @options[:with],
             schema: schema&.class&.name,
             streaming: self.class.streaming,
@@ -546,32 +616,75 @@ module RubyLLM
 
       # Executes the LLM call
       #
+      # When an assistant prefill is defined, messages are added manually
+      # (user, then assistant) before calling complete, so the model
+      # continues from the prefill. Otherwise, uses the standard .ask flow.
+      #
       # @param client [RubyLLM::Chat] The configured client
       # @param context [Pipeline::Context] The execution context
       # @return [RubyLLM::Message] The response
       def execute_llm_call(client, context)
         timeout = self.class.timeout
-        ask_opts = {}
-        ask_opts[:with] = @options[:with] if @options[:with]
+        prefill = resolved_assistant_prefill
 
         Timeout.timeout(timeout) do
-          if streaming_enabled? && context.stream_block
-            execute_with_streaming(client, context, ask_opts)
+          if prefill
+            execute_with_prefill(client, context, prefill)
+          elsif streaming_enabled? && context.stream_block
+            execute_with_streaming(client, context)
           else
+            ask_opts = {}
+            ask_opts[:with] = @options[:with] if @options[:with]
             client.ask(user_prompt, **ask_opts)
           end
         end
       end
 
+      # Executes with assistant prefill
+      #
+      # Manually adds the user message and assistant prefill, then calls
+      # complete so the model continues from the prefill text.
+      #
+      # @param client [RubyLLM::Chat] The client
+      # @param context [Pipeline::Context] The context
+      # @param prefill [Hash] The assistant prefill message ({role:, content:})
+      # @return [RubyLLM::Message] The response
+      def execute_with_prefill(client, context, prefill)
+        # Add user message — use .ask for attachment support, then add prefill
+        # We use add_message + complete instead of .ask so we can insert the
+        # assistant prefill between user and completion
+        client.add_message(role: :user, content: user_prompt)
+        client.add_message(**prefill)
+
+        if streaming_enabled? && context.stream_block
+          first_chunk_at = nil
+          started_at = context.started_at || Time.current
+
+          response = client.complete do |chunk|
+            first_chunk_at ||= Time.current
+            context.stream_block.call(chunk)
+          end
+
+          if first_chunk_at
+            context.time_to_first_token_ms = ((first_chunk_at - started_at) * 1000).to_i
+          end
+
+          response
+        else
+          client.complete
+        end
+      end
+
       # Executes with streaming enabled
       #
       # @param client [RubyLLM::Chat] The client
       # @param context [Pipeline::Context] The context
-      # @param ask_opts [Hash] Options for the ask call
       # @return [RubyLLM::Message] The response
-      def execute_with_streaming(client, context, ask_opts)
+      def execute_with_streaming(client, context)
         first_chunk_at = nil
         started_at = context.started_at || Time.current
+        ask_opts = {}
+        ask_opts[:with] = @options[:with] if @options[:with]
 
         response = client.ask(user_prompt, **ask_opts) do |chunk|
           first_chunk_at ||= Time.current
@@ -613,29 +726,14 @@ module RubyLLM
         input_tokens = context.input_tokens || 0
         output_tokens = context.output_tokens || 0
 
-        input_price = extract_model_price(model_info, :input_price)
-        output_price = extract_model_price(model_info, :output_price)
+        input_price = model_info.pricing&.text_tokens&.input || 0
+        output_price = model_info.pricing&.text_tokens&.output || 0
 
         context.input_cost = (input_tokens / 1_000_000.0) * input_price
         context.output_cost = (output_tokens / 1_000_000.0) * output_price
         context.total_cost = (context.input_cost + context.output_cost).round(6)
       end
 
-      # Extracts price from model info (supports both hash and object access)
-      #
-      # @param model_info [Hash, Object] Model info
-      # @param key [Symbol] The price key
-      # @return [Float] The price, or 0 if not found
-      def extract_model_price(model_info, key)
-        if model_info.respond_to?(key)
-          model_info.send(key) || 0
-        elsif model_info.respond_to?(:[])
-          model_info[key] || 0
-        else
-          0
-        end
-      end
-
       # Finds model pricing info
       #
       # @param model_id [String] The model ID

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

@@ -351,6 +351,45 @@ module RubyLLM
       #       max_value_length: 5000
       #     }
 
+      # API key and provider attributes forwarded to RubyLLM.
+      # These let users configure everything in one place through
+      # RubyLLM::Agents.configure instead of a separate RubyLLM.configure block.
+      FORWARDED_RUBY_LLM_ATTRIBUTES = %i[
+        openai_api_key
+        anthropic_api_key
+        gemini_api_key
+        deepseek_api_key
+        openrouter_api_key
+        bedrock_api_key
+        bedrock_secret_key
+        bedrock_session_token
+        bedrock_region
+        mistral_api_key
+        perplexity_api_key
+        xai_api_key
+        gpustack_api_key
+        openai_api_base
+        openai_organization_id
+        openai_project_id
+        gemini_api_base
+        gpustack_api_base
+        ollama_api_base
+        vertexai_project_id
+        vertexai_location
+        request_timeout
+        max_retries
+      ].freeze
+
+      FORWARDED_RUBY_LLM_ATTRIBUTES.each do |attr|
+        define_method(:"#{attr}=") do |value|
+          RubyLLM.config.public_send(:"#{attr}=", value)
+        end
+
+        define_method(attr) do
+          RubyLLM.config.public_send(attr)
+        end
+      end
+
       # Attributes without validation (simple accessors)
       attr_accessor :default_model,
                     :async_logging,

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 = "2.0.0"
+    VERSION = "2.2.0"
   end
 end

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

@@ -7,17 +7,23 @@ module RubyLLM
       #
       # Provides common configuration methods that every agent type needs:
       # - model: The LLM model to use
-      # - prompt: The user prompt (string with {placeholders} or block)
       # - system: System instructions
+      # - user: The user prompt (string with {placeholders})
+      # - assistant: Assistant prefill (string with optional {placeholders})
       # - description: Human-readable description
       # - timeout: Request timeout
       # - returns: Structured output schema
       #
-      # @example Simplified DSL
+      # Two levels for defining prompts:
+      # - Class-level string/heredoc for static content
+      # - Instance method override for dynamic content
+      #
+      # @example Template agent (structured input via .call)
       #   class SearchAgent < RubyLLM::Agents::BaseAgent
       #     model "gpt-4o"
       #     system "You are a helpful search assistant."
-      #     prompt "Search for: {query} (limit: {limit})"
+      #     user "Search for: {query} (limit: {limit})"
+      #     assistant '{"results":['
       #
       #     param :limit, default: 10  # Override auto-detected param
       #
@@ -29,10 +35,22 @@ module RubyLLM
       #     end
       #   end
       #
-      # @example Dynamic prompt with block
-      #   class SummaryAgent < RubyLLM::Agents::BaseAgent
-      #     prompt do
-      #       "Summarize in #{word_count} words: #{text}"
+      # @example Conversational agent (freeform input via .ask)
+      #   class RubyExpert < RubyLLM::Agents::BaseAgent
+      #     model "gpt-4o"
+      #     system "You are a senior Ruby developer."
+      #   end
+      #
+      #   RubyExpert.ask("What is metaprogramming?")
+      #
+      # @example Dynamic prompts with method overrides
+      #   class SmartAgent < RubyLLM::Agents::BaseAgent
+      #     def system_prompt
+      #       "You are helping #{company.name}. Today is #{Date.today}."
+      #     end
+      #
+      #     def user_prompt
+      #       "Question: #{params[:question]}"
       #     end
       #   end
       #
@@ -53,49 +71,70 @@ module RubyLLM
           @model || inherited_or_default(:model, default_model)
         end
 
-        # Sets the user prompt template or block
+        # Sets the user prompt template
         #
         # When a string is provided, {placeholder} syntax is used to interpolate
         # parameters. Parameters are automatically registered (as required) unless
         # already defined with `param`.
         #
-        # When a block is provided, it's evaluated in the instance context at
-        # execution time, allowing access to all instance methods and parameters.
-        #
         # @param template [String, nil] Prompt template with {placeholder} syntax
-        # @yield Block that returns the prompt string (evaluated at execution time)
-        # @return [String, Proc, nil] The current prompt configuration
+        # @return [String, nil] The current user prompt configuration
         #
         # @example With template string (parameters auto-detected)
-        #   prompt "Search for: {query} in {category}"
+        #   user "Search for: {query} in {category}"
         #   # Automatically registers :query and :category as required params
         #
-        # @example With block for dynamic prompts
-        #   prompt do
-        #     base = "Analyze the following"
-        #     base += " in #{language}" if language != "en"
-        #     "#{base}: #{text}"
-        #   end
+        # @example Multi-line with heredoc
+        #   user <<~S
+        #     Search for: {query}
+        #     Category: {category}
+        #     Limit: {limit}
+        #   S
+        #
+        def user(template = nil)
+          if template
+            @user_template = template
+            auto_register_params_from_template(template)
+          end
+          @user_template || @prompt_template || @prompt_block || inherited_or_default(:user_config, nil)
+        end
+
+        # Returns the user prompt configuration
+        #
+        # @return [String, Proc, nil] The user template, or nil
+        def user_config
+          @user_template || @prompt_template || @prompt_block || inherited_or_default(:user_config, nil)
+        end
+
+        # Backward-compatible alias for `user`
         #
+        # @deprecated Use `user` instead
+        # @param template [String, nil] Prompt template with {placeholder} syntax
+        # @yield Block that returns the prompt string (evaluated at execution time)
+        # @return [String, Proc, nil] The current prompt configuration
         def prompt(template = nil, &block)
           if template
-            @prompt_template = template
+            @user_template = template
             auto_register_params_from_template(template)
           elsif block
             @prompt_block = block
           end
-          @prompt_template || @prompt_block || inherited_or_default(:prompt_config, nil)
+          @user_template || @prompt_template || @prompt_block || inherited_or_default(:user_config, nil)
         end
 
-        # Returns the prompt configuration (template or block)
+        # Returns the prompt configuration (alias for user_config)
         #
+        # @deprecated Use `user_config` instead
         # @return [String, Proc, nil] The prompt template, block, or nil
         def prompt_config
-          @prompt_template || @prompt_block || inherited_or_default(:prompt_config, nil)
+          user_config
         end
 
         # Sets the system prompt/instructions
         #
+        # When a string is provided, {placeholder} syntax is supported for
+        # parameter interpolation, same as the `user` DSL.
+        #
         # @param text [String, nil] System instructions for the LLM
         # @yield Block that returns the system prompt (evaluated at execution time)
         # @return [String, Proc, nil] The current system prompt
@@ -103,14 +142,18 @@ module RubyLLM
         # @example Static system prompt
         #   system "You are a helpful assistant. Be concise and accurate."
         #
-        # @example Dynamic system prompt
-        #   system do
-        #     "You are helping #{user_name}. Their preferences: #{preferences}"
+        # @example With placeholders
+        #   system "You are helping {user_name} with their {task}."
+        #
+        # @example Dynamic system prompt (method override)
+        #   def system_prompt
+        #     "You are helping #{user_name}. Today is #{Date.today}."
         #   end
         #
         def system(text = nil, &block)
           if text
             @system_template = text
+            auto_register_params_from_template(text)
           elsif block
             @system_block = block
           end
@@ -124,6 +167,39 @@ module RubyLLM
           @system_template || @system_block || inherited_or_default(:system_config, nil)
         end
 
+        # Sets the assistant prefill string
+        #
+        # The assistant prefill is sent as the last message with the "assistant"
+        # role, priming the model to continue from that point. Useful for:
+        # - Forcing output format (e.g., starting with "{" for JSON)
+        # - Steering the response style
+        #
+        # Supports {placeholder} syntax for parameter interpolation.
+        #
+        # @param text [String, nil] The assistant prefill text
+        # @return [String, nil] The current assistant configuration
+        #
+        # @example Force JSON output
+        #   assistant '{"category":'
+        #
+        # @example With placeholders
+        #   assistant "Results for {query}:"
+        #
+        def assistant(text = nil)
+          if text
+            @assistant_template = text
+            auto_register_params_from_template(text)
+          end
+          @assistant_template || inherited_or_default(:assistant_config, nil)
+        end
+
+        # Returns the assistant prefill configuration
+        #
+        # @return [String, nil] The assistant template, or nil
+        def assistant_config
+          @assistant_template || inherited_or_default(:assistant_config, nil)
+        end
+
         # Sets or returns the description for this agent class
         #
         # Useful for documentation and tool registration.

data/lib/ruby_llm/agents/infrastructure/execution_logger_job.rb

@@ -25,10 +25,18 @@ module RubyLLM
       # @param execution_data [Hash] Execution attributes from instrumentation
       # @return [void]
       def perform(execution_data)
+        # Extract detail data before filtering (stored in separate table)
+        detail_data = execution_data.delete(:_detail_data) || execution_data.delete("_detail_data")
+
         # Filter to only known attributes to prevent schema mismatches
         filtered_data = filter_known_attributes(execution_data)
         execution = Execution.create!(filtered_data)
 
+        # Create detail record if present
+        if detail_data && detail_data.values.any? { |v| v.present? && v != {} && v != [] }
+          execution.create_detail!(detail_data)
+        end
+
         # Calculate costs if token data is available
         if execution.input_tokens && execution.output_tokens
           execution.calculate_costs!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - adham90
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.11.0
+        version: 1.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.11.0
+        version: 1.12.0
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement