ruby_llm-agents 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b341c701b87662c5947fec756ba5a925759f8179700683dda02c1b30951d3213
-  data.tar.gz: bec52ce05c7958b6954b8f6df23a8a9058ac2a9f900decdb858ed108623ff5af
+  metadata.gz: 0a12fa00f68f2dcc889d91017ac8a009796089b19ab81908cdbd1e33f24f9cea
+  data.tar.gz: cb1ed8fc426ed31e51b0796e5deb7f570410a562b7d579eb0e486046d3fb4d2c
 SHA512:
-  metadata.gz: fefed6d947fb4e9dc8e85a683c72754062d22c016c1de61b9922d49ae9a54cef9e84e638cadb1000e221fdd7616bfd1764fbf47bf5ba11404126acedcebe7c03
-  data.tar.gz: f93588c36b8057878b951c8411e00c2cd94ecc6189be8d33f70cb49e7d7e81098755606fbc3dcb6b2b8dfe85efc5c043a3d1884b7ecf48fc185a4863b4d0f16d
+  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-...
@@ -212,7 +227,7 @@ mount RubyLLM::Agents::Engine => "/agents"
 
 - **Ruby** >= 3.1.0
 - **Rails** >= 7.0
-- **RubyLLM** >= 1.11.0
+- **RubyLLM** >= 1.12.0
 
 ## Contributing
 

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
 
-        raise NotImplementedError, "#{self.class} must implement #user_prompt or use the prompt DSL"
+        config = self.class.user_config
+        return resolve_prompt_from_config(config) if config
+
+        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
 
-        messages
+      # 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?)
+
+        { 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

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.1.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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - adham90