ruby_llm-agents 1.0.0 → 1.2.0

data/lib/generators/ruby_llm_agents/templates/skills/WORKFLOWS.md.tt

@@ -1,4 +1,4 @@
-# <%= @root_namespace %> Workflows
+# Workflows
 
 This directory contains workflow orchestration classes that compose multiple agents. Workflows provide patterns for sequential, parallel, and conditional agent execution.
 
@@ -6,18 +6,254 @@ This directory contains workflow orchestration classes that compose multiple age
 
 | Type | Class | Description |
 |------|-------|-------------|
-| Pipeline | `Workflow::Pipeline` | Sequential execution, data flows between steps |
-| Parallel | `Workflow::Parallel` | Concurrent execution with aggregation |
-| Router | `Workflow::Router` | Conditional dispatch based on classification |
+| **DSL Workflow** | `Workflow` | Declarative DSL for mixed sequential/parallel/routing |
+| Pipeline | `Workflow::Pipeline` | Legacy: Sequential execution, data flows between steps |
+| Parallel | `Workflow::Parallel` | Legacy: Concurrent execution with aggregation |
+| Router | `Workflow::Router` | Legacy: Conditional dispatch based on classification |
 
-## Creating Workflows
+## Declarative DSL Workflows (Recommended)
+
+The new declarative DSL provides a clean, expressive syntax for defining workflows with minimal boilerplate. It supports sequential steps, parallel execution, conditional routing, and input validation all in one workflow class.
+
+### Minimal Workflow
+
+```ruby
+module Workflows
+  class SimpleWorkflow < RubyLLM::Agents::Workflow
+    step :fetch, FetcherAgent
+    step :process, ProcessorAgent
+    step :save, SaverAgent
+  end
+end
+
+# Usage
+result = Workflows::SimpleWorkflow.call(order_id: "ORD-123")
+result.success?          # => true
+result.content           # => final step output
+result.steps[:process]   # => ProcessorAgent result
+```
+
+### Full-Featured Workflow
+
+```ruby
+module Workflows
+  class OrderWorkflow < RubyLLM::Agents::Workflow
+    description "Process customer orders end-to-end"
+    version "2.0"
+    timeout 300
+    max_cost 2.00
+
+    # Input validation with defaults
+    input do
+      required :order_id, String
+      required :user_id, Integer
+      optional :priority, String, default: "normal"
+      optional :expedited, :boolean, default: false
+    end
+
+    # Sequential steps
+    step :fetch, FetcherAgent, timeout: 30
+    step :validate, ValidatorAgent
+
+    # Conditional routing based on previous step result
+    step :process, on: -> { validate.tier } do |route|
+      route.premium  PremiumProcessorAgent
+      route.standard StandardProcessorAgent
+      route.default  BasicProcessorAgent
+    end
+
+    # Parallel execution block
+    parallel do
+      step :analyze, AnalyzerAgent
+      step :summarize, SummarizerAgent
+      step :notify, NotifierAgent
+    end
+
+    # Conditional step execution
+    step :expedite, ExpediteAgent, if: :expedited?
+
+    private
+
+    def expedited?
+      input.expedited == true
+    end
+  end
+end
+```
+
+### DSL Reference
+
+#### Input Schema
+
+Define required and optional inputs with type validation:
+
+```ruby
+input do
+  required :order_id, String
+  required :amount, Numeric
+  optional :priority, String, default: "normal"
+  optional :debug, :boolean, default: false
+
+  # With enum validation
+  optional :status, String, in: %w[pending active completed]
+end
+```
+
+#### Step Options
+
+```ruby
+# Basic step
+step :name, AgentClass
+
+# With description
+step :validate, ValidatorAgent, "Validates order data"
+
+# With timeout (seconds)
+step :fetch, FetcherAgent, timeout: 30
+
+# Optional step (workflow continues on failure)
+step :enrich, EnricherAgent, optional: true
+
+# With default value on failure
+step :lookup, LookupAgent, optional: true, default: { found: false }
+
+# Conditional execution
+step :notify, NotifierAgent, if: :should_notify?
+step :skip_this, SkipAgent, unless: :condition_met?
+
+# With retry
+step :api_call, ApiAgent, retry: 3
+step :api_call, ApiAgent, retry: { max: 3, delay: 2, backoff: :exponential }
+```
+
+#### Conditional Routing
+
+Route to different agents based on a value:
+
+```ruby
+# Route based on lambda returning a value
+step :process, on: -> { validate.tier } do |route|
+  route.premium  PremiumAgent
+  route.standard StandardAgent
+  route.default  FallbackAgent  # Required fallback
+end
+
+# With custom input mapping per route
+step :handle, on: -> { classify.type } do |route|
+  route.billing  BillingAgent,  input: -> { { account: input.account_id } }
+  route.support  SupportAgent,  input: -> { { ticket: input.ticket_id } }
+  route.default  GeneralAgent
+end
+```
+
+#### Parallel Execution
+
+Execute steps concurrently:
+
+```ruby
+# Anonymous parallel group
+parallel do
+  step :sentiment, SentimentAgent
+  step :keywords, KeywordAgent
+  step :entities, EntityAgent
+end
+
+# Named parallel group with options
+parallel :analysis, fail_fast: true, concurrency: 2 do
+  step :deep_analyze, DeepAnalyzer
+  step :quick_scan, QuickScanner
+end
+```
+
+#### Lifecycle Hooks
+
+```ruby
+class MyWorkflow < RubyLLM::Agents::Workflow
+  step :process, ProcessorAgent
+  step :save, SaverAgent
+
+  # Workflow-level hooks
+  before_workflow { Rails.logger.info("Starting workflow") }
+  after_workflow { Rails.logger.info("Workflow complete") }
+
+  # Step-level hooks
+  before_step(:process) { |context| log_step_start(:process) }
+  after_step(:process) { |result, duration_ms| log_step_end(:process, duration_ms) }
+
+  # Error hooks
+  on_step_failure(:process) { |error, context| handle_error(error) }
+end
+```
+
+#### Accessing Step Results
+
+Within the workflow, access previous step results:
+
+```ruby
+step :validate, ValidatorAgent
+
+# In routing lambda
+step :process, on: -> { validate.tier } do |route|
+  # validate.tier returns validate step's result[:tier]
+end
+
+# In condition methods
+def should_notify?
+  validate.valid? && input.callback_url.present?
+end
+```
+
+### Workflow Result API
+
+```ruby
+result = MyWorkflow.call(order_id: "123")
+
+# Status
+result.success?    # All steps succeeded
+result.partial?    # Some optional steps failed
+result.error?      # Required step failed
+result.status      # "success", "partial", or "error"
+
+# Content
+result.content     # Final step output
+
+# Step results
+result.steps                      # Hash of all step results
+result.steps[:validate]           # Specific step result
+result.steps[:validate].content   # Step output content
+
+# Metrics
+result.total_cost      # Combined cost of all steps
+result.input_tokens    # Total input tokens
+result.output_tokens   # Total output tokens
+result.duration_ms     # Total workflow duration
+
+# Errors
+result.errors          # Hash of step errors
+```
+
+### Dry Run / Validation
+
+Validate workflow configuration without executing:
+
+```ruby
+validation = MyWorkflow.dry_run(order_id: "123")
+
+validation[:valid]         # true/false
+validation[:input_errors]  # Array of validation errors
+validation[:steps]         # List of step names
+validation[:agents]        # List of agent classes
+validation[:parallel_groups]  # Parallel group info
+```
+
+## Creating Workflows (Legacy Patterns)
 
 ### Pipeline (Sequential)
 
 Execute agents in order, passing each step's output to the next:
 
 ```ruby
-module <%= @root_namespace %>
+module Workflows
   class ContentPipeline < RubyLLM::Agents::Workflow::Pipeline
     version "1.0"
     timeout 120
@@ -35,7 +271,7 @@ end
 Execute multiple agents simultaneously:
 
 ```ruby
-module <%= @root_namespace %>
+module Workflows
   class ReviewAnalyzer < RubyLLM::Agents::Workflow::Parallel
     version "1.0"
 
@@ -59,7 +295,7 @@ end
 Route to different agents based on classification:
 
 ```ruby
-module <%= @root_namespace %>
+module Workflows
   class SupportRouter < RubyLLM::Agents::Workflow::Router
     version "1.0"
     classifier ClassificationAgent
@@ -145,7 +381,7 @@ end
 ### Basic Execution
 
 ```ruby
-result = <%= @root_namespace %>::ContentPipeline.call(text: "raw input")
+result = Workflows::ContentPipeline.call(text: "raw input")
 
 result.success?      # All steps succeeded
 result.partial?      # Some steps succeeded
@@ -158,7 +394,7 @@ result.duration_ms   # Total duration
 ### Pipeline Results
 
 ```ruby
-result = <%= @root_namespace %>::ContentPipeline.call(text: "input")
+result = Workflows::ContentPipeline.call(text: "input")
 
 result.steps                     # Hash of all step results
 result.steps[:extract].content   # Specific step output
@@ -168,7 +404,7 @@ result.errors                    # Hash of step errors
 ### Parallel Results
 
 ```ruby
-result = <%= @root_namespace %>::ReviewAnalyzer.call(text: "Great product!")
+result = Workflows::ReviewAnalyzer.call(text: "Great product!")
 
 result.branches                     # Hash of branch results
 result.branches[:sentiment].content # Specific branch output
@@ -177,7 +413,7 @@ result.branches[:sentiment].content # Specific branch output
 ### Router Results
 
 ```ruby
-result = <%= @root_namespace %>::SupportRouter.call(question: "How do I pay?")
+result = Workflows::SupportRouter.call(question: "How do I pay?")
 
 result.classification  # What route was selected
 result.route          # Which agent handled it
@@ -191,7 +427,7 @@ result.content        # Response from routed agent
 Transform data between pipeline steps:
 
 ```ruby
-module <%= @root_namespace %>
+module Workflows
   class TransformPipeline < RubyLLM::Agents::Workflow::Pipeline
     step :analyze, agent: AnalyzerAgent
     step :enrich,  agent: EnricherAgent
@@ -212,7 +448,7 @@ end
 Combine parallel results:
 
 ```ruby
-module <%= @root_namespace %>
+module Workflows
   class SafetyChecker < RubyLLM::Agents::Workflow::Parallel
     branch :toxicity, agent: ToxicityAgent
     branch :spam,     agent: SpamAgent
@@ -233,7 +469,7 @@ end
 Handle step failures:
 
 ```ruby
-module <%= @root_namespace %>
+module Workflows
   class ResilientPipeline < RubyLLM::Agents::Workflow::Pipeline
     step :primary, agent: PrimaryAgent
     step :backup,  agent: BackupAgent, optional: true
@@ -253,7 +489,7 @@ end
 Stop workflow if cost exceeds threshold:
 
 ```ruby
-module <%= @root_namespace %>
+module Workflows
   class BudgetedWorkflow < RubyLLM::Agents::Workflow::Pipeline
     max_cost 1.00  # Stop if workflow exceeds $1.00
 
@@ -266,7 +502,7 @@ end
 ## Testing Workflows
 
 ```ruby
-RSpec.describe <%= @root_namespace %>::ContentPipeline do
+RSpec.describe Workflows::ContentPipeline do
   describe ".call" do
     it "processes content through all steps" do
       result = described_class.call(text: "test input")
@@ -289,12 +525,27 @@ end
 
 ## Best Practices
 
-1. **Version your workflows** - Track changes for debugging
-2. **Set timeouts** - Prevent runaway workflows
+### General
+
+1. **Version your workflows** - Track changes for debugging and rollback
+2. **Set timeouts** - Prevent runaway workflows at both workflow and step level
 3. **Use max_cost** - Control spending on expensive operations
-4. **Handle errors gracefully** - Use optional steps and error handlers
+4. **Handle errors gracefully** - Use optional steps, defaults, and error handlers
 5. **Keep workflows focused** - One workflow, one purpose
 6. **Test step interactions** - Unit test agents, integration test workflows
-7. **Log workflow execution** - Track step timing and costs
-8. **Use parallel for independent operations** - Improve throughput
-9. **Use router for classification** - Keep routing logic centralized
+
+### DSL Workflows (Recommended)
+
+1. **Use input schemas** - Validate inputs early with `required`/`optional` declarations
+2. **Prefer DSL over legacy patterns** - The new DSL is more flexible and composable
+3. **Use parallel for independent operations** - Group unrelated steps for concurrent execution
+4. **Use routing for classification** - Clean syntax for conditional agent selection
+5. **Leverage step result access** - Use `step_name.field` syntax in conditions/routing
+6. **Add lifecycle hooks** - Log, track, and handle errors at appropriate points
+7. **Use dry_run for validation** - Check workflow configuration before execution
+
+### Legacy Patterns
+
+1. **Use Pipeline for sequential data processing** - Data flows naturally between steps
+2. **Use Parallel for fan-out operations** - Independent operations with aggregation
+3. **Use Router for classification-based dispatch** - When route selection depends on LLM classification

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

@@ -1,56 +1,54 @@
 # frozen_string_literal: true
 
-module <%= @root_namespace %>
-  module Audio
+module Audio
 <%- if class_name.include?("::") -%>
 <%- class_name.split("::")[0..-2].each_with_index do |mod, i| -%>
-<%= "  " * (i + 2) %>module <%= mod %>
+<%= "  " * (i + 1) %>module <%= mod %>
 <%- end -%>
-<%= "  " * (class_name.split("::").length + 1) %>class <%= class_name.split("::").last %>Speaker < ApplicationSpeaker
+<%= "  " * class_name.split("::").length %>class <%= class_name.split("::").last %>Speaker < ApplicationSpeaker
 <%- else -%>
-    class <%= class_name %>Speaker < ApplicationSpeaker
+  class <%= class_name %>Speaker < ApplicationSpeaker
 <%- end -%>
-      # Provider configuration
-      provider :<%= options[:provider] %>
+    # Provider configuration
+    provider :<%= options[:provider] %>
 <% if options[:model] -%>
-      model "<%= options[:model] %>"
+    model "<%= options[:model] %>"
 <% end -%>
-      voice "<%= options[:voice] %>"
+    voice "<%= options[:voice] %>"
 <% if options[:speed] != 1.0 -%>
-      speed <%= options[:speed] %>
+    speed <%= options[:speed] %>
 <% end -%>
 <% if options[:format] != "mp3" -%>
-      output_format :<%= options[:format] %>
+    output_format :<%= options[:format] %>
 <% end -%>
 <% if options[:cache] -%>
 
-      # Caching
-      cache_for <%= options[:cache] %>
+    # Caching
+    cache_for <%= options[:cache] %>
 <% end -%>
 
-      # Optional: Custom pronunciation lexicon
-      # Define how specific words should be pronounced
-      #
-      # lexicon do
-      #   pronounce 'API', 'A P I'
-      #   pronounce 'SQL', 'sequel'
-      # end
+    # Optional: Custom pronunciation lexicon
+    # Define how specific words should be pronounced
+    #
+    # lexicon do
+    #   pronounce 'API', 'A P I'
+    #   pronounce 'SQL', 'sequel'
+    # end
 <% if options[:provider].to_s == "elevenlabs" -%>
 
-      # ElevenLabs voice settings
-      # voice_settings do
-      #   stability 0.5
-      #   similarity_boost 0.75
-      #   style 0.5
-      #   speaker_boost true
-      # end
+    # ElevenLabs voice settings
+    # voice_settings do
+    #   stability 0.5
+    #   similarity_boost 0.75
+    #   style 0.5
+    #   speaker_boost true
+    # end
 <% end -%>
 <%- if class_name.include?("::") -%>
-<%- (class_name.split("::").length + 1).times do |i| -%>
-<%= "  " * (class_name.split("::").length + 1 - i) %>end
+<%- class_name.split("::").length.times do |i| -%>
+<%= "  " * (class_name.split("::").length - i) %>end
 <%- end -%>
 <%- else -%>
-    end
-<%- end -%>
   end
+<%- end -%>
 end

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

@@ -1,51 +1,49 @@
 # frozen_string_literal: true
 
-module <%= @root_namespace %>
-  module Audio
+module Audio
 <%- if class_name.include?("::") -%>
 <%- class_name.split("::")[0..-2].each_with_index do |mod, i| -%>
-<%= "  " * (i + 2) %>module <%= mod %>
+<%= "  " * (i + 1) %>module <%= mod %>
 <%- end -%>
-<%= "  " * (class_name.split("::").length + 1) %>class <%= class_name.split("::").last %>Transcriber < ApplicationTranscriber
+<%= "  " * class_name.split("::").length %>class <%= class_name.split("::").last %>Transcriber < ApplicationTranscriber
 <%- else -%>
-    class <%= class_name %>Transcriber < ApplicationTranscriber
+  class <%= class_name %>Transcriber < ApplicationTranscriber
 <%- end -%>
-      # Model configuration
-      model "<%= options[:model] %>"
+    # Model configuration
+    model "<%= options[:model] %>"
 <% if options[:language] -%>
-      language "<%= options[:language] %>"
+    language "<%= options[:language] %>"
 <% end -%>
 <% if options[:output_format] != "text" -%>
-      output_format :<%= options[:output_format] %>
+    output_format :<%= options[:output_format] %>
 <% end -%>
 <% if options[:cache] -%>
 
-      # Caching
-      cache_for <%= options[:cache] %>
+    # Caching
+    cache_for <%= options[:cache] %>
 <% end -%>
 
-      # Optional: Provide context to improve accuracy
-      # Override this method to give the model hints about the audio content
-      #
-      # def prompt
-      #   "Technical discussion about Ruby programming"
-      # end
+    # Optional: Provide context to improve accuracy
+    # Override this method to give the model hints about the audio content
+    #
+    # def prompt
+    #   "Technical discussion about Ruby programming"
+    # end
 
-      # Optional: Clean up transcription text
-      # Override this method to post-process the transcribed text
-      #
-      # def postprocess_text(text)
-      #   text
-      #     .gsub(/\bum\b/i, '')     # Remove filler words
-      #     .gsub(/\buh\b/i, '')
-      #     .squeeze(' ')             # Remove extra spaces
-      # end
+    # Optional: Clean up transcription text
+    # Override this method to post-process the transcribed text
+    #
+    # def postprocess_text(text)
+    #   text
+    #     .gsub(/\bum\b/i, '')     # Remove filler words
+    #     .gsub(/\buh\b/i, '')
+    #     .squeeze(' ')             # Remove extra spaces
+    # end
 <%- if class_name.include?("::") -%>
-<%- (class_name.split("::").length + 1).times do |i| -%>
-<%= "  " * (class_name.split("::").length + 1 - i) %>end
+<%- class_name.split("::").length.times do |i| -%>
+<%= "  " * (class_name.split("::").length - i) %>end
 <%- end -%>
 <%- else -%>
-    end
-<%- end -%>
   end
+<%- end -%>
 end

data/lib/generators/ruby_llm_agents/transcriber_generator.rb

@@ -7,12 +7,11 @@ module RubyLlmAgents
   #
   # Usage:
   #   rails generate ruby_llm_agents:transcriber Meeting
-  #   rails generate ruby_llm_agents:transcriber Meeting --model gpt-4o-transcribe
-  #   rails generate ruby_llm_agents:transcriber Meeting --language es
-  #   rails generate ruby_llm_agents:transcriber Meeting --root=ai
+  #   rails generate ruby_llm_agents:transcriber Interview --model whisper-1
+  #   rails generate ruby_llm_agents:transcriber Podcast --language en
   #
   # This will create:
-  #   - app/{root}/audio/transcribers/meeting_transcriber.rb
+  #   - app/agents/audio/meeting_transcriber.rb
   #
   class TranscriberGenerator < ::Rails::Generators::NamedBase
     source_root File.expand_path("templates", __dir__)
@@ -25,48 +24,36 @@ module RubyLlmAgents
                  desc: "Output format (text, srt, vtt, json)"
     class_option :cache, type: :string, default: nil,
                  desc: "Cache TTL (e.g., '30.days')"
-    class_option :root,
-                 type: :string,
-                 default: nil,
-                 desc: "Root directory name (default: uses config or 'llm')"
-    class_option :namespace,
-                 type: :string,
-                 default: nil,
-                 desc: "Root namespace (default: camelized root or config)"
 
     def ensure_base_class_and_skill_file
-      @root_namespace = root_namespace
-      @audio_namespace = "#{root_namespace}::Audio"
-      transcribers_dir = "app/#{root_directory}/audio/transcribers"
+      audio_dir = "app/agents/audio"
 
       # Create directory if needed
-      empty_directory transcribers_dir
+      empty_directory audio_dir
 
       # Create base class if it doesn't exist
-      base_class_path = "#{transcribers_dir}/application_transcriber.rb"
+      base_class_path = "#{audio_dir}/application_transcriber.rb"
       unless File.exist?(File.join(destination_root, base_class_path))
         template "application_transcriber.rb.tt", base_class_path
       end
 
       # Create skill file if it doesn't exist
-      skill_file_path = "#{transcribers_dir}/TRANSCRIBERS.md"
+      skill_file_path = "#{audio_dir}/TRANSCRIBERS.md"
       unless File.exist?(File.join(destination_root, skill_file_path))
         template "skills/TRANSCRIBERS.md.tt", skill_file_path
       end
     end
 
     def create_transcriber_file
-      # Support nested paths: "interview/meeting" -> "app/{root}/audio/transcribers/interview/meeting_transcriber.rb"
-      @root_namespace = root_namespace
-      @audio_namespace = "#{root_namespace}::Audio"
+      # Support nested paths: "interview/meeting" -> "app/agents/audio/interview/meeting_transcriber.rb"
       transcriber_path = name.underscore
-      template "transcriber.rb.tt", "app/#{root_directory}/audio/transcribers/#{transcriber_path}_transcriber.rb"
+      template "transcriber.rb.tt", "app/agents/audio/#{transcriber_path}_transcriber.rb"
     end
 
     def show_usage
       # Build full class name from path
       transcriber_class_name = name.split("/").map(&:camelize).join("::")
-      full_class_name = "#{root_namespace}::Audio::#{transcriber_class_name}Transcriber"
+      full_class_name = "Audio::#{transcriber_class_name}Transcriber"
       say ""
       say "Transcriber #{full_class_name} created!", :green
       say ""
@@ -83,25 +70,5 @@ module RubyLlmAgents
       say "  result.vtt  # VTT format"
       say ""
     end
-
-    private
-
-    def root_directory
-      @root_directory ||= options[:root] || RubyLLM::Agents.configuration.root_directory
-    end
-
-    def root_namespace
-      @root_namespace ||= options[:namespace] || camelize(root_directory)
-    end
-
-    def camelize(str)
-      # Handle special cases for common abbreviations
-      return "AI" if str.downcase == "ai"
-      return "ML" if str.downcase == "ml"
-      return "LLM" if str.downcase == "llm"
-
-      # Standard camelization
-      str.split(/[-_]/).map(&:capitalize).join
-    end
   end
 end