ruby_llm-agents 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0cf7b20ca960eab7d26da1c568c5aa5078e12e887a4d93c9b472d6897cf1e5e
-  data.tar.gz: 59372d2c80bd8fdb23d49ffdd672911948bf1b78da8243aaac7df926a378bd59
+  metadata.gz: c2a8bd149077abc08185f8bc5c59d03323ba6adce25f1feed23dfc35d17376de
+  data.tar.gz: 4e9d466a76aa4565a6936a8d9cc7499b4b18aa6efb1e9c40baa0a28c35ca656d
 SHA512:
-  metadata.gz: 1902ad245d20d405fe69633e122a83302bbd5b95e5b65fe0d24b1da14b0effaf27e9308e4a5a42bd9072545b2d128ed173214812667727fb2ea0de43948f1ee1
-  data.tar.gz: d3937f03bc62481c6257c55c9a7f1a8c6eccc9fc08a759c8f40334b21000a12cc67e5277ca0d018b551c3abb6b077d4ffc1caa8bfaa3f2d8e784aac98c1e9bf8
+  metadata.gz: 3758ac407012134aab9fcf89f0ad7895b3cb38dd9b385772bb8102cea93a4d9247e9b3083e5eaa7e7f2d1969c4079d1b4286168c00353976af84effa6272ec2b
+  data.tar.gz: 3787b8665b33714ac6f4221e7a79753563d4b4553b8868a8dba2d9a1b2d3e310c43c3f27064fb7e0aa1bf9addad865b26626127d7862ed52221637c6b81eaa91

data/README.md

@@ -1,5 +1,7 @@
 # RubyLLM::Agents
 
+[![Gem Version](https://badge.fury.io/rb/ruby_llm-agents.svg)](https://badge.fury.io/rb/ruby_llm-agents)
+
 A powerful Rails engine for building, managing, and monitoring LLM-powered agents using [RubyLLM](https://github.com/crmne/ruby_llm).
 
 ## Features
@@ -12,6 +14,8 @@ A powerful Rails engine for building, managing, and monitoring LLM-powered agent
 - **🛠️ Generators** - Quickly scaffold new agents with customizable templates
 - **🔍 Anomaly Detection** - Automatic warnings for unusual cost or duration patterns
 - **🎯 Type Safety** - Structured output with RubyLLM::Schema integration
+- **⚡ Real-time Streaming** - Stream LLM responses with time-to-first-token tracking
+- **📎 Attachments** - Send images, PDFs, and files to vision-capable models
 - **🔄 Reliability** - Automatic retries, model fallbacks, and circuit breakers for resilient agents
 - **💵 Budget Controls** - Daily/monthly spending limits with hard and soft enforcement
 - **🔔 Alerts** - Slack, webhook, and custom notifications for budget and circuit breaker events
@@ -150,6 +154,123 @@ SearchIntentAgent.call(query: "test", dry_run: true)
 SearchIntentAgent.call(query: "test", skip_cache: true)
 ```
 
+### Streaming Responses
+
+Enable real-time streaming to receive LLM responses as they're generated:
+
+```ruby
+class StreamingAgent < ApplicationAgent
+  model "gpt-4o"
+  streaming true  # Enable streaming for this agent
+
+  param :prompt, required: true
+
+  def user_prompt
+    prompt
+  end
+end
+```
+
+#### Using Streaming with a Block
+
+```ruby
+# Stream responses in real-time
+StreamingAgent.call(prompt: "Write a story") do |chunk|
+  print chunk  # Process each chunk as it arrives
+end
+```
+
+#### HTTP Streaming with ActionController::Live
+
+```ruby
+class StreamingController < ApplicationController
+  include ActionController::Live
+
+  def stream_response
+    response.headers['Content-Type'] = 'text/event-stream'
+    response.headers['Cache-Control'] = 'no-cache'
+
+    StreamingAgent.call(prompt: params[:prompt]) do |chunk|
+      response.stream.write "data: #{chunk}\n\n"
+    end
+  ensure
+    response.stream.close
+  end
+end
+```
+
+#### Time-to-First-Token Tracking
+
+Streaming executions automatically track latency metrics:
+
+```ruby
+execution = RubyLLM::Agents::Execution.last
+execution.streaming?              # => true
+execution.time_to_first_token_ms  # => 245 (milliseconds to first chunk)
+```
+
+#### Global Streaming Configuration
+
+Enable streaming by default for all agents:
+
+```ruby
+# config/initializers/ruby_llm_agents.rb
+RubyLLM::Agents.configure do |config|
+  config.default_streaming = true
+end
+```
+
+### Attachments (Vision & Multimodal)
+
+Send images, PDFs, and other files to vision-capable models using the `with:` option:
+
+```ruby
+class VisionAgent < ApplicationAgent
+  model "gpt-4o"  # Use a vision-capable model
+  param :question, required: true
+
+  def user_prompt
+    question
+  end
+end
+```
+
+#### Single Attachment
+
+```ruby
+# Local file
+VisionAgent.call(question: "Describe this image", with: "photo.jpg")
+
+# URL
+VisionAgent.call(question: "What architecture is shown?", with: "https://example.com/building.jpg")
+```
+
+#### Multiple Attachments
+
+```ruby
+VisionAgent.call(
+  question: "Compare these two screenshots",
+  with: ["screenshot_v1.png", "screenshot_v2.png"]
+)
+```
+
+#### Supported File Types
+
+RubyLLM automatically detects file types:
+
+- **Images:** `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp`
+- **Videos:** `.mp4`, `.mov`, `.avi`, `.webm`
+- **Audio:** `.mp3`, `.wav`, `.m4a`, `.ogg`, `.flac`
+- **Documents:** `.pdf`, `.txt`, `.md`, `.csv`, `.json`, `.xml`
+- **Code:** `.rb`, `.py`, `.js`, `.html`, `.css`, and many others
+
+#### Debug Mode with Attachments
+
+```ruby
+VisionAgent.call(question: "test", with: "image.png", dry_run: true)
+# => { ..., attachments: "image.png", ... }
+```
+
 ## Usage Guide
 
 ### Agent DSL
@@ -680,6 +801,9 @@ RubyLLM::Agents.configure do |config|
   # Default timeout for LLM requests (in seconds)
   config.default_timeout = 60
 
+  # Enable streaming by default for all agents
+  config.default_streaming = false
+
   # ============================================================================
   # Caching Configuration
   # ============================================================================
@@ -866,6 +990,18 @@ trend = RubyLLM::Agents::Execution.trend_analysis(
 # ]
 ```
 
+### Streaming Analytics
+
+```ruby
+# Percentage of executions using streaming
+RubyLLM::Agents::Execution.streaming_rate
+# => 45.5
+
+# Average time-to-first-token for streaming executions (milliseconds)
+RubyLLM::Agents::Execution.avg_time_to_first_token
+# => 245.3
+```
+
 ### Scopes
 
 Chain scopes for complex queries:
@@ -919,6 +1055,10 @@ expensive_slow_failures = RubyLLM::Agents::Execution
 
 # Token usage
 .high_token_usage(threshold)
+
+# Streaming
+.streaming
+.non_streaming
 ```
 
 ## Generators

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

@@ -18,6 +18,10 @@ RubyLLM::Agents.configure do |config|
   # Default timeout in seconds for each LLM request
   # config.default_timeout = 60
 
+  # Enable streaming by default for all agents
+  # When enabled, agents stream responses and track time-to-first-token
+  # config.default_streaming = false
+
   # ============================================
   # Caching
   # ============================================

data/lib/ruby_llm/agents/base.rb

@@ -50,6 +50,7 @@ module RubyLLM
         # @param kwargs [Hash] Named parameters for the agent
         # @option kwargs [Boolean] :dry_run Return prompt info without API call
         # @option kwargs [Boolean] :skip_cache Bypass caching even if enabled
+        # @option kwargs [String, Array<String>] :with Attachments (files, URLs) to send with the prompt
         # @yield [chunk] Yields chunks when streaming is enabled
         # @yieldparam chunk [RubyLLM::Chunk] A streaming chunk with content
         # @return [Object] The processed response from the agent
@@ -64,6 +65,10 @@ module RubyLLM
         #   ChatAgent.call(message: "Hello") do |chunk|
         #     print chunk.content
         #   end
+        #
+        # @example With attachments
+        #   VisionAgent.call(query: "Describe this image", with: "photo.jpg")
+        #   VisionAgent.call(query: "Compare these", with: ["a.png", "b.png"])
         def call(*args, **kwargs, &block)
           new(*args, **kwargs).call(&block)
         end
@@ -429,6 +434,7 @@ module RubyLLM
           timeout: self.class.timeout,
           system_prompt: system_prompt,
           user_prompt: user_prompt,
+          attachments: @options[:with],
           schema: schema&.class&.name,
           streaming: self.class.streaming,
           tools: self.class.tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s }
@@ -465,7 +471,7 @@ module RubyLLM
           if self.class.streaming && block_given?
             execute_with_streaming(current_client, &block)
           else
-            response = current_client.ask(user_prompt)
+            response = current_client.ask(user_prompt, **ask_options)
             process_response(capture_response(response))
           end
         end
@@ -483,7 +489,7 @@ module RubyLLM
       def execute_with_streaming(current_client, &block)
         first_chunk_at = nil
 
-        response = current_client.ask(user_prompt) do |chunk|
+        response = current_client.ask(user_prompt, **ask_options) do |chunk|
           first_chunk_at ||= Time.current
           yield chunk if block_given?
         end
@@ -692,7 +698,18 @@ module RubyLLM
       #
       # @return [Hash] Data to hash for cache key
       def cache_key_data
-        @options.except(:skip_cache, :dry_run)
+        @options.except(:skip_cache, :dry_run, :with)
+      end
+
+      # Returns options to pass to the ask method
+      #
+      # Currently supports :with for attachments (images, PDFs, etc.)
+      #
+      # @return [Hash] Options for the ask call
+      def ask_options
+        opts = {}
+        opts[:with] = @options[:with] if @options[:with]
+        opts
       end
 
       # Validates that all required parameters are present

data/lib/ruby_llm/agents/redactor.rb

@@ -108,7 +108,7 @@ module RubyLLM
             redact_string(value, config)
           when defined?(ActiveRecord::Base) && ActiveRecord::Base
             # Convert ActiveRecord objects to safe references
-            { id: value.id, type: value.class.name }
+            { id: value&.id, type: value&.class&.name }
           else
             value
           end

data/lib/ruby_llm/agents/version.rb

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

metadata

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