ruby_llm-agents 0.5.0 → 1.0.0.beta.1

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

@@ -0,0 +1,251 @@
+# <%= @root_namespace %>::Audio Transcribers
+
+This directory contains audio transcription services. All transcribers inherit from `ApplicationTranscriber`.
+
+## Creating a New Transcriber
+
+Use the generator:
+```bash
+rails generate ruby_llm_agents:transcriber TranscriberName
+rails generate ruby_llm_agents:transcriber Meeting --model whisper-1 --language en
+rails generate ruby_llm_agents:transcriber Podcast --output_format srt
+```
+
+Or create manually:
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class MeetingTranscriber < ApplicationTranscriber
+      model "whisper-1"
+      language "en"
+      output_format :text
+      include_timestamps :segment
+    end
+  end
+end
+```
+
+## DSL Reference
+
+### Model Configuration
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `model` | Transcription model | `model "whisper-1"` |
+| `language` | Audio language (nil = auto-detect) | `language "en"` |
+| `output_format` | Output format | `output_format :text` |
+| `include_timestamps` | Timestamp granularity | `include_timestamps :segment` |
+
+### Output Formats
+
+- `:text` - Plain text transcription
+- `:json` - JSON with metadata
+- `:srt` - SubRip subtitle format
+- `:vtt` - WebVTT subtitle format
+
+### Timestamp Options
+
+- `:none` - No timestamps
+- `:segment` - Timestamps per segment
+- `:word` - Word-level timestamps
+
+### Caching
+
+```ruby
+cache_for 30.days  # Cache transcriptions
+```
+
+## Optional Methods
+
+### `prompt`
+Provide context to improve accuracy:
+
+```ruby
+def prompt
+  "Technical discussion about Ruby programming and software development"
+end
+```
+
+### `postprocess_text`
+Clean up transcription output:
+
+```ruby
+def postprocess_text(text)
+  text
+    .gsub(/\bum\b/i, '')     # Remove filler words
+    .gsub(/\buh\b/i, '')
+    .gsub(/\blike\b/i, '')   # Remove verbal tics
+    .squeeze(' ')             # Remove extra spaces
+    .strip
+end
+```
+
+## Using Transcribers
+
+### Basic Transcription
+
+```ruby
+result = <%= @root_namespace %>::Audio::MeetingTranscriber.call(audio: "meeting.mp3")
+
+result.text         # The transcribed text
+result.duration     # Audio duration in seconds
+result.language     # Detected language
+result.total_cost   # Cost in USD
+```
+
+### From File Path
+
+```ruby
+result = <%= @root_namespace %>::Audio::MeetingTranscriber.call(audio: "/path/to/audio.mp3")
+```
+
+### From Binary Data
+
+```ruby
+audio_data = File.read("recording.wav", mode: "rb")
+result = <%= @root_namespace %>::Audio::MeetingTranscriber.call(audio: audio_data)
+```
+
+### From URL
+
+```ruby
+result = <%= @root_namespace %>::Audio::MeetingTranscriber.call(
+  audio: "https://example.com/audio.mp3"
+)
+```
+
+### With Timestamps (SRT)
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class SubtitleTranscriber < ApplicationTranscriber
+      model "whisper-1"
+      output_format :srt
+      include_timestamps :segment
+    end
+  end
+end
+
+result = <%= @root_namespace %>::Audio::SubtitleTranscriber.call(audio: "video.mp4")
+File.write("subtitles.srt", result.text)
+```
+
+## Use Cases
+
+### Meeting Transcription
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class MeetingTranscriber < ApplicationTranscriber
+      model "whisper-1"
+      language "en"
+      cache_for 90.days
+
+      def prompt
+        "Business meeting with technical discussions"
+      end
+
+      def postprocess_text(text)
+        text
+          .gsub(/\bum\b/i, '')
+          .gsub(/\buh\b/i, '')
+          .squeeze(' ')
+      end
+    end
+  end
+end
+```
+
+### Podcast Subtitles
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class PodcastTranscriber < ApplicationTranscriber
+      model "whisper-1"
+      output_format :vtt
+      include_timestamps :segment
+
+      def prompt
+        "Technology podcast discussing software development"
+      end
+    end
+  end
+end
+```
+
+### Voice Note Processing
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class VoiceNoteTranscriber < ApplicationTranscriber
+      model "whisper-1"
+      output_format :json
+
+      def postprocess_text(text)
+        # Clean up casual speech
+        text
+          .gsub(/\byou know\b/i, '')
+          .gsub(/\bi mean\b/i, '')
+          .gsub(/\bkind of\b/i, '')
+          .squeeze(' ')
+      end
+    end
+  end
+end
+```
+
+### Multilingual Transcription
+
+```ruby
+module <%= @root_namespace %>
+  module Audio
+    class MultilingualTranscriber < ApplicationTranscriber
+      model "whisper-1"
+      # Leave language nil for auto-detection
+      output_format :json
+    end
+  end
+end
+
+result = <%= @root_namespace %>::Audio::MultilingualTranscriber.call(audio: "spanish.mp3")
+result.language  # => "es"
+```
+
+## Testing Transcribers
+
+```ruby
+RSpec.describe <%= @root_namespace %>::Audio::MeetingTranscriber do
+  describe ".call" do
+    it "transcribes audio file" do
+      result = described_class.call(audio: fixture_file("sample.mp3"))
+
+      expect(result.text).to be_present
+      expect(result.duration).to be > 0
+    end
+  end
+
+  describe "#postprocess_text" do
+    it "removes filler words" do
+      transcriber = described_class.new(audio: "test.mp3")
+      text = "So um I think uh we should proceed"
+
+      result = transcriber.postprocess_text(text)
+
+      expect(result).to eq("So I think we should proceed")
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Provide context via prompt** - Helps with technical terms and names
+2. **Use caching** - Same audio produces same transcription
+3. **Choose appropriate format** - SRT/VTT for subtitles, text for processing
+4. **Post-process for quality** - Remove filler words, fix formatting
+5. **Specify language when known** - Improves accuracy over auto-detect
+6. **Consider file formats** - MP3, WAV, M4A, MP4 audio track supported

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

@@ -0,0 +1,300 @@
+# <%= @root_namespace %> Workflows
+
+This directory contains workflow orchestration classes that compose multiple agents. Workflows provide patterns for sequential, parallel, and conditional agent execution.
+
+## Workflow Types
+
+| 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 |
+
+## Creating Workflows
+
+### Pipeline (Sequential)
+
+Execute agents in order, passing each step's output to the next:
+
+```ruby
+module <%= @root_namespace %>
+  class ContentPipeline < RubyLLM::Agents::Workflow::Pipeline
+    version "1.0"
+    timeout 120
+    max_cost 0.50
+
+    step :extract,  agent: ExtractorAgent
+    step :validate, agent: ValidatorAgent
+    step :format,   agent: FormatterAgent
+  end
+end
+```
+
+### Parallel (Concurrent)
+
+Execute multiple agents simultaneously:
+
+```ruby
+module <%= @root_namespace %>
+  class ReviewAnalyzer < RubyLLM::Agents::Workflow::Parallel
+    version "1.0"
+
+    branch :sentiment,  agent: SentimentAgent
+    branch :summary,    agent: SummaryAgent
+    branch :categories, agent: CategoryAgent
+
+    def aggregate(results)
+      {
+        sentiment: results[:sentiment]&.content,
+        summary: results[:summary]&.content,
+        categories: results[:categories]&.content
+      }
+    end
+  end
+end
+```
+
+### Router (Conditional)
+
+Route to different agents based on classification:
+
+```ruby
+module <%= @root_namespace %>
+  class SupportRouter < RubyLLM::Agents::Workflow::Router
+    version "1.0"
+    classifier ClassificationAgent
+
+    route :billing,   agent: BillingAgent
+    route :technical, agent: TechnicalAgent
+    route :general,   agent: GeneralAgent
+
+    default_route :general
+  end
+end
+```
+
+## DSL Reference
+
+### Shared Options
+
+```ruby
+version "1.0"        # Version for tracking changes
+timeout 120          # Total workflow timeout in seconds
+max_cost 0.50        # Maximum allowed cost in USD
+description "..."    # Human-readable description
+```
+
+### Pipeline DSL
+
+```ruby
+# Define steps
+step :name, agent: AgentClass
+
+# Conditional skipping
+step :validate, agent: Validator, skip_on: ->(ctx) { ctx[:skip_validation] }
+
+# Optional steps (failures won't stop pipeline)
+step :enrich, agent: Enricher, optional: true
+
+# Continue on error
+step :notify, agent: Notifier, continue_on_error: true
+```
+
+### Parallel DSL
+
+```ruby
+# Define branches
+branch :name, agent: AgentClass
+
+# Optional branches
+branch :extra, agent: ExtraAgent, optional: true
+
+# Custom input transformation
+branch :process, agent: Processor, input: ->(opts) { { text: opts[:content] } }
+
+# Fail-fast (stop all on first required failure)
+fail_fast true
+
+# Limit concurrency
+concurrency 3
+```
+
+### Router DSL
+
+```ruby
+# Set classifier
+classifier ClassificationAgent
+
+# Define routes
+route :category, agent: AgentClass
+
+# Default route
+default_route :fallback
+
+# Custom routing logic
+def select_route(classification)
+  case classification[:type]
+  when "urgent" then :priority
+  else :standard
+  end
+end
+```
+
+## Using Workflows
+
+### Basic Execution
+
+```ruby
+result = <%= @root_namespace %>::ContentPipeline.call(text: "raw input")
+
+result.success?      # All steps succeeded
+result.partial?      # Some steps succeeded
+result.error?        # Workflow failed
+result.content       # Final output
+result.total_cost    # Combined cost
+result.duration_ms   # Total duration
+```
+
+### Pipeline Results
+
+```ruby
+result = <%= @root_namespace %>::ContentPipeline.call(text: "input")
+
+result.steps                     # Hash of all step results
+result.steps[:extract].content   # Specific step output
+result.errors                    # Hash of step errors
+```
+
+### Parallel Results
+
+```ruby
+result = <%= @root_namespace %>::ReviewAnalyzer.call(text: "Great product!")
+
+result.branches                     # Hash of branch results
+result.branches[:sentiment].content # Specific branch output
+```
+
+### Router Results
+
+```ruby
+result = <%= @root_namespace %>::SupportRouter.call(question: "How do I pay?")
+
+result.classification  # What route was selected
+result.route          # Which agent handled it
+result.content        # Response from routed agent
+```
+
+## Advanced Patterns
+
+### Input Transformation
+
+Transform data between pipeline steps:
+
+```ruby
+module <%= @root_namespace %>
+  class TransformPipeline < RubyLLM::Agents::Workflow::Pipeline
+    step :analyze, agent: AnalyzerAgent
+    step :enrich,  agent: EnricherAgent
+
+    # Called before :enrich step
+    def before_enrich(context)
+      {
+        data: context[:analyze].content,
+        extra_field: "additional context"
+      }
+    end
+  end
+end
+```
+
+### Custom Aggregation
+
+Combine parallel results:
+
+```ruby
+module <%= @root_namespace %>
+  class SafetyChecker < RubyLLM::Agents::Workflow::Parallel
+    branch :toxicity, agent: ToxicityAgent
+    branch :spam,     agent: SpamAgent
+    branch :pii,      agent: PiiAgent
+
+    def aggregate(results)
+      {
+        is_safe: results.values.none? { |r| r&.content == "flagged" },
+        flags: results.select { |_, r| r&.content == "flagged" }.keys
+      }
+    end
+  end
+end
+```
+
+### Error Handling
+
+Handle step failures:
+
+```ruby
+module <%= @root_namespace %>
+  class ResilientPipeline < RubyLLM::Agents::Workflow::Pipeline
+    step :primary, agent: PrimaryAgent
+    step :backup,  agent: BackupAgent, optional: true
+
+    # Called when :primary fails
+    def on_primary_failure(error, context)
+      Rails.logger.warn("Primary failed: #{error.message}")
+      :skip  # Continue to backup
+      # :abort would stop the pipeline
+    end
+  end
+end
+```
+
+### Cost Limits
+
+Stop workflow if cost exceeds threshold:
+
+```ruby
+module <%= @root_namespace %>
+  class BudgetedWorkflow < RubyLLM::Agents::Workflow::Pipeline
+    max_cost 1.00  # Stop if workflow exceeds $1.00
+
+    step :expensive_analysis, agent: DeepAnalysisAgent
+    step :synthesis,          agent: SynthesisAgent
+  end
+end
+```
+
+## Testing Workflows
+
+```ruby
+RSpec.describe <%= @root_namespace %>::ContentPipeline do
+  describe ".call" do
+    it "processes content through all steps" do
+      result = described_class.call(text: "test input")
+
+      expect(result.success?).to be true
+      expect(result.steps.keys).to eq([:extract, :validate, :format])
+    end
+
+    it "handles step failures" do
+      allow(ExtractorAgent).to receive(:call).and_raise("Network error")
+
+      result = described_class.call(text: "test")
+
+      expect(result.error?).to be true
+      expect(result.errors[:extract]).to be_present
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Version your workflows** - Track changes for debugging
+2. **Set timeouts** - Prevent runaway workflows
+3. **Use max_cost** - Control spending on expensive operations
+4. **Handle errors gracefully** - Use optional steps 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

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Audio
+<%- if class_name.include?("::") -%>
+<%- class_name.split("::")[0..-2].each_with_index do |mod, i| -%>
+<%= "  " * (i + 2) %>module <%= mod %>
+<%- end -%>
+<%= "  " * (class_name.split("::").length + 1) %>class <%= class_name.split("::").last %>Speaker < ApplicationSpeaker
+<%- else -%>
+    class <%= class_name %>Speaker < ApplicationSpeaker
+<%- end -%>
+      # Provider configuration
+      provider :<%= options[:provider] %>
+<% if options[:model] -%>
+      model "<%= options[:model] %>"
+<% end -%>
+      voice "<%= options[:voice] %>"
+<% if options[:speed] != 1.0 -%>
+      speed <%= options[:speed] %>
+<% end -%>
+<% if options[:format] != "mp3" -%>
+      output_format :<%= options[:format] %>
+<% end -%>
+<% if 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
+<% 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
+<% end -%>
+<%- if class_name.include?("::") -%>
+<%- (class_name.split("::").length + 1).times do |i| -%>
+<%= "  " * (class_name.split("::").length + 1 - i) %>end
+<%- end -%>
+<%- else -%>
+    end
+<%- end -%>
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module <%= @root_namespace %>
+  module Audio
+<%- if class_name.include?("::") -%>
+<%- class_name.split("::")[0..-2].each_with_index do |mod, i| -%>
+<%= "  " * (i + 2) %>module <%= mod %>
+<%- end -%>
+<%= "  " * (class_name.split("::").length + 1) %>class <%= class_name.split("::").last %>Transcriber < ApplicationTranscriber
+<%- else -%>
+    class <%= class_name %>Transcriber < ApplicationTranscriber
+<%- end -%>
+      # Model configuration
+      model "<%= options[:model] %>"
+<% if options[:language] -%>
+      language "<%= options[:language] %>"
+<% end -%>
+<% if options[:output_format] != "text" -%>
+      output_format :<%= options[:output_format] %>
+<% end -%>
+<% if 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: 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
+<%- end -%>
+<%- else -%>
+    end
+<%- end -%>
+  end
+end