DSPy.rb

https://oss.vicente.services/dspy.rb/
Admin
The Ruby port of Stanford's DSPy framework that enables developers to write modular, testable,...
Tokens:217,469
Snippets:2,050
Trust Score:5.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Local Workflow Router Setup and Execution

Source: https://oss.vicente.services/dspy.rb/blog/articles/workflow-routing-with-dspy.rb

Instructions for setting up the local environment by setting the ANTHROPIC_API_KEY, installing dependencies with Bundler, and running the workflow router example.

```bash
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
bundle install
bundle exec ruby examples/workflow_router.rb
```

--------------------------------

### DSPy GEPA Optimization Setup

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Initialize the GEPA optimizer with a metric, a feedback map, and an experiment tracker. Ensure the `dspy-gepa` gem is installed.

```ruby
feedback_map = {
  'self' => ->(predictor_output:, predictor_inputs:, module_inputs:, module_outputs:, captured_trace:) do
    DSPy::Prediction.new(
      score: predictor_output[:answer] == module_outputs[:answer] ? 1.0 : 0.2,
      feedback: "Tie feedback to the original question: #{module_inputs.input_values[:question]}"
    )
  end
}

optimizer = DSPy::Teleprompt::GEPA.new(
  metric: metric,
  feedback_map: feedback_map,
  experiment_tracker: GEPA::Logging::ExperimentTracker.new
)

program = DSPy::Predict.new(YourSignature)
result = optimizer.compile(program, trainset: train_examples, valset: val_examples)

puts "GEPA trials: #{result.history.count}"
puts "Latest reflection: #{result.history.last&.reflection}"
```

--------------------------------

### Install Ollama and Pull a Model

Source: https://oss.vicente.services/dspy.rb/blog/articles/run-llms-locally-with-ollama-and-type-safe-ruby

Instructions for setting up Ollama on macOS using Homebrew and pulling the 'llama3.2' model. This is the initial setup required before using local LLMs with DSPy.rb.

```bash
# Install Ollama
brew install ollama  # or see ollama.com for other platforms

# Pull a model
ollama pull llama3.2

```

--------------------------------

### Integrate Examples with Evaluation Framework

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Shows how to create a list of DSPy Examples and use them with the DSPy::Evals framework to evaluate a predictor's performance.

```ruby
# Examples work with the evaluation framework
examples = [
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "Great product!" },
    expected: { sentiment: ClassifyText::Sentiment::Positive, confidence: 0.9 }
  ),
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "Terrible service." },
    expected: { sentiment: ClassifyText::Sentiment::Negative, confidence: 0.8 }
  )
]

# Use with DSPy::Evals
predictor = DSPy::Predict.new(ClassifyText)
evaluator = DSPy::Evals.new(metric: :exact_match)

results = evaluator.evaluate(examples: examples) do |example|
  predictor.call(example.input_values)
end

puts results.score  # Accuracy score
```

--------------------------------

### Serialization of Basic Examples

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Shows how to create a basic DSPy example with optional `id` and `metadata` fields, which are useful for serialization and tracking.

```ruby
# Save and load examples
example = DSPy::Example.new(
  signature_class: ClassifyText,
  input: { text: "Sample text" },
  expected: { sentiment: ClassifyText::Sentiment::Positive, confidence: 0.8 },
  id: "example_1",
  metadata: { source: "manual", created_at: Time.current }
)


```

--------------------------------

### Convert Example to Hash and Recreate

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Demonstrates how to serialize a DSPy Example to a hash for persistence and then recreate it using the hash and a signature registry.

```ruby
example_hash = example.to_h

registry = { "ClassifyText" => ClassifyText }
reloaded_example = DSPy::Example.from_h(example_hash, signature_registry: registry)
```

--------------------------------

### Accessing Example Data

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Shows how to create a DSPy example and access its input values, expected output values, and convert it to a hash for serialization.

```ruby
example = DSPy::Example.new(
  signature_class: ClassifyText,
  input: { text: "Great product!" },
  expected: { sentiment: ClassifyText::Sentiment::Positive, confidence: 0.9 }
)

# Access input values
input_values = example.input_values
# => { text: "Great product!" }

# Access expected output values
expected_values = example.expected_values  
# => { sentiment: #<Sentiment::Positive>, confidence: 0.9 }

# Convert to hash for serialization
example.to_h
# => { signature_class: "ClassifyText", input: {...}, expected: {...} }

```

--------------------------------

### Demonstrate Progressive Prompting for Sentiment Analysis

Source: https://oss.vicente.services/dspy.rb/optimization/prompt-optimization

Illustrates how to build a prompt incrementally, starting simple and adding complexity (details, examples, confidence requirements) to observe performance changes. Uses DSPy and a ClassifyText module.

```ruby
# Start simple, add complexity progressively
simple_prompt = prompt.with_instruction("Classify sentiment")

# Add details
detailed_prompt = simple_prompt.with_instruction(
  "Classify the sentiment of the text as positive, negative, or neutral. Consider the overall emotional tone and context."
)

# Add examples
enhanced_prompt = detailed_prompt.with_examples(training_examples.sample(3))

# Add confidence requirement
final_prompt = enhanced_prompt.with_instruction(
  "Classify the sentiment of the text as positive, negative, or neutral. Provide a confidence score between 0 and 1. Consider context, tone, and emotional indicators."
)

# Test progression
[simple_prompt, detailed_prompt, enhanced_prompt, final_prompt].each_with_index do |p, i|
  test_predictor = DSPy::Predict.new(ClassifyText)
  test_predictor.prompt = p
  
  evaluator = DSPy::Evals.new(test_predictor, metric: :exact_match)
  result = evaluator.evaluate(test_examples)
  score = result.pass_rate
  
  puts "Step #{i + 1}: #{score}"
end
```

--------------------------------

### Install DSPy.rb Gem

Source: https://oss.vicente.services/dspy.rb/blog/articles/dspy-rb-0-20-0-release-announcement

Install the DSPy.rb gem to start using its features. This command is run in the terminal.

```bash
gem install dspy

```

--------------------------------

### Install DSPy.rb from GitHub

Source: https://oss.vicente.services/dspy.rb/getting-started/installation

Install the latest development version of DSPy.rb directly from its GitHub repository.

```ruby
gem 'dspy', github: 'vicentereig/dspy.rb'
```

--------------------------------

### Adding Few-Shot Examples to Prompts

Source: https://oss.vicente.services/dspy.rb/optimization/prompt-optimization

Enhance prompts by adding few-shot examples. This snippet demonstrates creating examples and combining them with existing ones.

```ruby
# Create few-shot examples
examples = [
  DSPy::FewShotExample.new(
    input: { text: "I love this product!" },
    output: { sentiment: "positive", confidence: 0.9 }
  ),
  DSPy::FewShotExample.new(
    input: { text: "This is terrible quality." },
    output: { sentiment: "negative", confidence: 0.85 }
  ),
  DSPy::FewShotExample.new(
    input: { text: "It's an okay product." },
    output: { sentiment: "neutral", confidence: 0.7 }
  )
]

# Create new prompt with examples
enhanced_prompt = prompt.with_examples(examples)

# Add more examples
additional_examples = [
  DSPy::FewShotExample.new(
    input: { text: "Outstanding service!" },
    output: { sentiment: "positive", confidence: 0.95 }
  )
]

final_prompt = enhanced_prompt.with_examples(
  enhanced_prompt.few_shot_examples + additional_examples
)

```

--------------------------------

### Install DSPy.rb Gem

Source: https://oss.vicente.services/dspy.rb/blog/articles/dspy-rb-1-0-0-release

Install the core DSPy.rb gem using the standard RubyGems command. This is the basic installation for using the library.

```bash
gem install dspy
```

--------------------------------

### OpenAI Provider Setup

Source: https://oss.vicente.services/dspy.rb/getting-started/installation

Steps to set up the OpenAI provider, including API key configuration.

```bash
export OPENAI_API_KEY=sk-your-key-here
```

```ruby
DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
end
```

--------------------------------

### Create Few-Shot Examples

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Create few-shot examples for DSPy.rb, including input, output, and reasoning, to provide context and improve model performance.

```ruby
# Create few-shot examples
few_shot_examples = [
  DSPy::FewShotExample.new(
    input: { text: "I love this product!" },
    output: { sentiment: "positive", confidence: 0.95 },
    reasoning: "The phrase 'I love' indicates strong positive sentiment."
  ),
  DSPy::FewShotExample.new(
    input: { text: "This is terrible." },
    output: { sentiment: "negative", confidence: 0.9 },
    reasoning: "The word 'terrible' clearly indicates negative sentiment."
  )
]

# Use with predictor
predictor = DSPy::Predict.new(ClassifyText)
optimized_predictor = predictor.with_examples(few_shot_examples)

result = optimized_predictor.call(text: "This movie was incredible!")

```

--------------------------------

### Evaluating Predictions Against Examples

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Demonstrates how to use a predictor to get a result and then check if that prediction matches the expected output of a DSPy example.

```ruby
# Test if a prediction matches the expected output
predictor = DSPy::Predict.new(ClassifyText)
result = predictor.call(text: "Great product!")

# Check if prediction matches expected
if example.matches_prediction?(result)
  puts "Prediction matches expected output!"
else
  puts "Prediction differs from expected output"
end

```

--------------------------------

### Evolving Signatures from Basic to Domain-Specific Types

Source: https://oss.vicente.services/dspy.rb/blog/articles/type-safe-prediction-objects

Provides a step-by-step example of how to start with simple string-based signatures and gradually evolve them to use domain-specific types like T::Struct for more robust and type-safe AI outputs.

```ruby
# 1. Start with basic types
class MySignature < DSPy::Signature
  input { const :question, String }
  output { const :answer, String }
end

# 2. Evolve to domain-specific types
class SupportTicket < T::Struct
  const :category, String
  const :urgency, Priority
end

class AdvancedSignature < DSPy::Signature
  input { const :ticket_text, String }
  output { const :analysis, SupportTicket }
end

# 3. Get type-safe results that match your domain
predictor = DSPy::Predict.new(AdvancedSignature)
result = predictor.call(ticket_text: "Login broken for all users")
puts result.analysis.urgency.serialize  # Fully typed and safe
```

--------------------------------

### Run DSPy.rb Example

Source: https://oss.vicente.services/dspy.rb/blog/articles/evaluator_loop_in_ruby

Execute the evaluator loop example using the provided Ruby command. Ensure your environment variables, such as `ANTHROPIC_API_KEY`, are set.

```bash
bundle exec ruby examples/evaluator_loop.rb

```

--------------------------------

### Install and Configure DSPy.rb

Source: https://oss.vicente.services/dspy.rb/llms.txt

Install the `dspy` gem and configure the language model (LM) to use. Supports OpenAI and local models via Ollama.

```ruby
# Install
gem 'dspy'

# Configure
DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
  # or use Ollama for local models
  # c.lm = DSPy::LM.new('ollama/llama3.2')
end
```

--------------------------------

### Running the Sentiment Classification Example

Source: https://oss.vicente.services/dspy.rb/blog/articles/evaluating-llm-applications

Navigate to the example directory and run the Ruby script to execute the sentiment classification evaluation. This demonstrates the complete workflow.

```bash
cd examples/sentiment-evaluation
ruby sentiment_classifier.rb
```

--------------------------------

### Start Ollama Server

Source: https://oss.vicente.services/dspy.rb/getting-started/installation

Verify that the Ollama service is running to enable connections from DSPy.

```bash
ollama serve
```

--------------------------------

### Install DSPy.rb and Set API Key

Source: https://oss.vicente.services/dspy.rb/blog/articles/introducing-google-gemini-support

Instructions to install the DSPy.rb gem and set your Gemini API key as an environment variable to begin using Gemini models.

```bash
# Update to DSPy.rb v0.20.0
gem install dspy

# Set your API key
export GEMINI_API_KEY=your-key-here

# Start building with Gemini!

```

--------------------------------

### Install Ollama and Pull a Model

Source: https://oss.vicente.services/dspy.rb/blog/articles/run-llms-locally-with-ollama-and-type-safe-ruby

Install Ollama using Homebrew and pull the Llama 3.2 model. This is a prerequisite for using Ollama locally.

```bash
# Install Ollama (macOS)
brew install ollama

# Start Ollama
ollama serve

# Pull a model
ollama pull llama3.2

```

--------------------------------

### Include Edge Cases in Examples

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Illustrates the creation of DSPy Examples that cover edge cases, such as minimal text input or text with mixed sentiment.

```ruby
# Include edge cases and boundary conditions
edge_case_examples = [
  # Minimal text
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "Ok." },
    expected: { sentiment: ClassifyText::Sentiment::Neutral, confidence: 0.6 }
  ),
  
  # Mixed sentiment
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "I love the product but hate the price." },
    expected: { sentiment: ClassifyText::Sentiment::Neutral, confidence: 0.7 }
  )
]
```

--------------------------------

### Create Type-Safe Training Examples

Source: https://oss.vicente.services/dspy.rb/getting-started/core-concepts

Generates a list of DSPy::Example objects for training or evaluation. Each example links a signature class with input and expected output values.

```ruby
examples = [
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "This movie was amazing!" },
    expected: { sentiment: ClassifyText::Sentiment::Positive, confidence: 0.9 }
  ),
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "Terrible service, would not recommend." },
    expected: { sentiment: ClassifyText::Sentiment::Negative, confidence: 0.95 }
  )
]

```

--------------------------------

### Anthropic Provider Setup

Source: https://oss.vicente.services/dspy.rb/getting-started/installation

Steps to set up the Anthropic provider, including API key configuration.

```bash
export ANTHROPIC_API_KEY=sk-ant-your-key-here
```

```ruby
DSPy.configure do |c|
  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514', api_key: ENV['ANTHROPIC_API_KEY'])
end
```

--------------------------------

### Text Processing Toolset Example

Source: https://oss.vicente.services/dspy.rb/core-concepts/toolsets

Demonstrates using the built-in TextProcessingToolset with a ReAct agent for text analysis. This example shows how to define a signature and integrate the toolset.

```ruby
# Define a signature for text analysis
class AnalyzeText < DSPy::Signature
  description "Analyze text content using available text processing tools"

  input do
    const :text, String
    const :question, String
  end

  output do
    const :answer, String
  end
end

# The LLM sees these individual tools:
# - text_processing_grep
# - text_wc
# - text_rg
# - text_processing_extract_lines
# - text_processing_filter_lines
# - text_processing_unique_lines
# - text_processing_sort_lines
# - text_processing_summarize_text

# Create ReAct agent with toolset
agent = DSPy::ReAct.new(
  AnalyzeText,
  tools: DSPy::Tools::TextProcessingToolset.to_tools
)

```

--------------------------------

### LM Resolution Hierarchy Example

Source: https://oss.vicente.services/dspy.rb/core-concepts/module-runtime-context

Illustrates the LM resolution hierarchy: instance-level LM, fiber-local LM, and global LM. This example shows how different LM settings take precedence.

```ruby
# Global configuration
DSPy.configure do |config|
  config.lm = DSPy::LM.new("openai/gpt-4o", api_key: ENV['OPENAI_API_KEY'])
end

# Create module with instance-level LM
classifier = Classifier.new
classifier.config.lm = DSPy::LM.new("anthropic/claude-sonnet-4-20250514", api_key: ENV['ANTHROPIC_API_KEY'])

# Instance-level LM takes precedence
result1 = classifier.call(text: "Test") # Uses Claude Sonnet

# Fiber-local LM doesn't override instance-level
fast_model = DSPy::LM.new("openai/gpt-4o-mini", api_key: ENV['OPENAI_API_KEY'])
DSPy.with_lm(fast_model) do
  result2 = classifier.call(text: "Test") # Still uses Claude Sonnet
end

# Create module without instance-level LM
classifier2 = Classifier.new

DSPy.with_lm(fast_model) do
  result3 = classifier2.call(text: "Test") # Uses gpt-4o-mini (fiber-local)
end

result4 = classifier2.call(text: "Test") # Uses gpt-4o (global)

```

--------------------------------

### Install DSPy.rb with Ecosystem Gems

Source: https://oss.vicente.services/dspy.rb/blog/articles/dspy-rb-1-0-0-release

Install DSPy.rb along with common ecosystem gems for expanded functionality, such as OpenAI, Anthropic, Gemini, and RubyLLM integrations. Add these lines to your Gemfile.

```ruby
gem "dspy"
gem "dspy-openai"
gem "dspy-anthropic"
gem "dspy-gemini"
gem "dspy-ruby_llm"
```

--------------------------------

### Adding Few-Shot Examples to a Predictor

Source: https://oss.vicente.services/dspy.rb/core-concepts/predictors

Illustrates how to enhance a DSPy predictor with few-shot examples to improve its performance on specific tasks. It shows the creation of DSPy::FewShotExample objects and their application using the `with_examples` method.

```ruby
# Create predictor with examples
classifier = DSPy::Predict.new(SentimentAnalysis)

# Add few-shot examples
examples = [
  DSPy::FewShotExample.new(
    input: { text: "I love this product!" },
    output: { sentiment: "positive", confidence: 0.9 }
  ),
  DSPy::FewShotExample.new(
    input: { text: "This is terrible." },
    output: { sentiment: "negative", confidence: 0.8 }
  )
]

optimized_classifier = classifier.with_examples(examples)
```

--------------------------------

### Real-World Concurrent Customer Service Example

Source: https://oss.vicente.services/dspy.rb/core-concepts/predictors

An example demonstrating concurrent processing of customer service requests using DSPy.rb's ChainOfThought predictor and the async gem. This showcases how to handle multiple independent requests efficiently.

```ruby
# Customer service agent processing multiple requests
class CustomerService < DSPy::Signature
  description "Provide customer service response"
  
  input do
    const :customer_query, String
    const :customer_mood, String
  end
  
  output do
    const :response, String
    const :escalation_needed, T::Boolean
  end
end

customer_requests = [
  { query: "How do I reset my password?", mood: "neutral" },
  { query: "This is terrible service!", mood: "angry" },
  { query: "I love your product!", mood: "happy" },
  { query: "When will my order arrive?", mood: "concerned" }
]

service_agent = DSPy::ChainOfThought.new(CustomerService)

Async do
  barrier = Async::Barrier.new
  start_time = Time.now
  
  # Process all customer requests concurrently
  tasks = customer_requests.map.with_index do |request, i|
    barrier.async do
      service_agent.call(
        customer_query: request[:query],
        customer_mood: request[:mood]
      )
    end
  end
  
  barrier.wait
  responses = tasks.map(&:wait)
  
  total_time = Time.now - start_time
  puts "Processed #{customer_requests.length} requests in #{total_time.round(2)}s"
  
  responses.each_with_index do |response, i|
    puts "\nCustomer #{i+1}: #{customer_requests[i][:query]}"
    puts "Response: #{response.response}"
    puts "Escalation needed: #{response.escalation_needed}"
  end
end

```

--------------------------------

### Image Analysis Usage Example

Source: https://oss.vicente.services/dspy.rb/core-concepts/multimodal

Instantiate and call the ImageAnalysis signature to get detailed information from an image, focusing on colors and specifying a detailed analysis level.

```ruby
# Usage
analyzer = DSPy::Predict.new(ImageAnalysis)
image = DSPy::Image.new(url: 'https://example.com/landscape.jpg')
analysis = analyzer.call(
  image: image,
  focus: 'colors',
  detail_level: ImageAnalysis::DetailLevel::Detailed
)

puts analysis.description
puts "Colors: #{analysis.dominant_colors.join(', ')}"
puts "Mood: #{analysis.mood}"
puts "Objects: #{analysis.objects.join(', ')}"
```

--------------------------------

### Example Agent Reasoning Output

Source: https://oss.vicente.services/dspy.rb/blog/articles/react-agent-tutorial

Illustrates the step-by-step reasoning process of a ReAct agent, showing its thoughts, chosen actions, and inputs for each iteration.

```text
=== Step 1 ===
Thought: I need to search for information about climate change impacts on agriculture
Action: web_search
Action Input: {"query": "climate change impact agriculture 2024"}

=== Step 2 ===
Thought: I found that yields may decline 10-25%. Let me calculate the impact for different scenarios
Action: calculator
Action Input: {"expression": "1000000 * 0.25"}

=== Step 3 ===
Thought: A 25% decline on 1 million tons of production means 250,000 tons lost. Let me search for adaptation strategies
Action: web_search
Action Input: {"query": "climate adaptation strategies agriculture"}

=== Step 4 ===
Thought: Based on my research and calculations, I have comprehensive information to provide a summary
Action: finish
Action Input: {}

Total iterations: 4

```

--------------------------------

### Convert Toolsets to Instances and Use with ReAct Agent

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Demonstrates converting custom and built-in toolsets into instances that can be used with a ReAct agent. This example shows combining database and weather tools for agent use.

```ruby
# Convert to tool instances for agents
weather_tools = WeatherToolset.to_tools
database_tools = DatabaseToolset.to_tools

# Use with ReAct agent
agent = DSPy::ReAct.new(
  WeatherSignature,
  tools: weather_tools + database_tools,
  max_iterations: 15
)
```

--------------------------------

### Content Analyzer with Callbacks

Source: https://oss.vicente.services/dspy.rb/advanced/rails-integration

This example demonstrates a DSPy module that analyzes content, logs its start and end, and tracks performance using around callbacks. It integrates with Rails logging and StatsD.

```ruby
class ContentAnalyzer < DSPy::Module
  before :log_analysis_start
  after :log_analysis_end
  around :with_performance_tracking

  def initialize
    super  # Required for DSPy::Module
    @analyzer = DSPy::Predict.new(AnalysisSignature)
  end

  def forward(content:)  # Use forward, not call - callbacks hook into forward
    @content = content
    result = @analyzer.call(content: content)

    ContentAnalysis.create!(
      content: content,
      sentiment: result.sentiment.serialize,
      topics: result.topics
    )

    result  # Return result directly
  end

  private

  def log_analysis_start
    Rails.logger.info("Starting analysis for content: #{@content[0..50]}...")
  end

  def log_analysis_end
    Rails.logger.info("Analysis completed")
  end

  def with_performance_tracking
    start_time = Time.current
    result = yield
    duration = Time.current - start_time
    Rails.logger.info("Analysis took #{duration} seconds")
    StatsD.timing('content_analyzer.duration', duration * 1000)
    result
  end
end

# Usage - call works because DSPy::Module aliases call to forward
analyzer = ContentAnalyzer.new
result = analyzer.call(content: "Some content")
```

--------------------------------

### Migration Guide: After (Simple Event System)

Source: https://oss.vicente.services/dspy.rb/advanced/observability-interception

Shows the modern approach using the DSPy.rb event system with a clean subscriber pattern for event handling.

```ruby
# Clean subscriber pattern
class MyTracker
  def initialize
    @subscriptions = []
    @subscriptions << DSPy.events.subscribe('llm.*') { |name, attrs| handle_event(attrs) }
  end

  def unsubscribe
    @subscriptions.each { |id| DSPy.events.unsubscribe(id) }
    @subscriptions.clear
  end
end

tracker = MyTracker.new

```

--------------------------------

### Before Callback for Module Initialization

Source: https://oss.vicente.services/dspy.rb/core-concepts/module-runtime-context

Implements a 'before' callback to set up context and log the start time before the main forward method execution. Useful for initialization tasks.

```ruby
class LoggingSignature < DSPy::Signature
  description "Answer questions with logging"

  input do
    const :question, String
  end

  output do
    const :answer, String
  end
end

class LoggingModule < DSPy::Module
  before :setup_context

  def initialize
    super
    @predictor = DSPy::Predict.new(LoggingSignature)
    @start_time = nil
  end

  def forward(question:)
    @predictor.call(question: question)
  end

  private

  def setup_context
    @start_time = Time.now
    puts "Starting prediction at #{@start_time}"
  end
end

# Usage
module_instance = LoggingModule.new
result = module_instance.call(question: "What is DSPy.rb?")
# Output: "Starting prediction at 2025-10-06 12:00:00 -0700"

```

--------------------------------

### Categorical Score Example

Source: https://oss.vicente.services/dspy.rb/production/observability

Example of scoring with a categorical data type.

```ruby
DSPy.score('sentiment', 'positive', data_type: DSPy::Scores::DataType::Categorical)
```

--------------------------------

### DSPy Single Example Evaluation

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Evaluate a single example by calling the evaluator instance directly. The result object contains details about whether the example passed, metric-specific details, and the actual prediction.

```ruby
example = { input: { question: "What is 2+2?" }, expected: { answer: "4" } }
result = evaluator.call(example)

puts result.passed      # => true/false
puts result.metrics     # => Hash with metric details
puts result.prediction  # => Actual prediction object
```

--------------------------------

### Access FewShotExample Properties and Serialization

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Demonstrates how to create a FewShotExample, access its properties, convert it to a hash, create it from a hash, and generate a prompt section.

```ruby
# Access FewShotExample properties
few_shot = DSPy::FewShotExample.new(
  input: { text: "Great product!" },
  output: { sentiment: "positive" },
  reasoning: "Positive language indicates good sentiment."
)

# Convert to hash
few_shot.to_h
# => { input: {...}, output: {...}, reasoning: "..." }

# Create from hash
few_shot = DSPy::FewShotExample.from_h({
  input: { text: "Bad experience" },
  output: { sentiment: "negative" },
  reasoning: "Negative words indicate poor sentiment"
})

# Generate prompt section
few_shot.to_prompt_section
# => "## Input\n```json\n{...}\n```\n## Reasoning\n...\n## Output\n```json\n{...}\n```"

```

--------------------------------

### Install DSPy Gem

Source: https://oss.vicente.services/dspy.rb/getting-started/installation

Ensure the DSPy gem is added to your Gemfile and installed using Bundler.

```bash
bundle install
```

--------------------------------

### Built-in Toolset Initialization

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Shows how to initialize instances for built-in toolsets like TextProcessingToolset and GithubCliToolset, making them available for agent use.

```ruby
# Text processing toolset
text_tools = DSPy::Tools::TextProcessingToolset.to_tools

# GitHub CLI toolset
github_tools = DSPy::Tools::GithubCliToolset.to_tools
```

--------------------------------

### Test DSPy Installation

Source: https://oss.vicente.services/dspy.rb/getting-started/installation

Verify your DSPy installation by configuring it with a provider and running a simple test signature.

```ruby
require 'dspy'

# Configure with your provider
DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
end

# Test basic functionality
class TestSignature < DSPy::Signature
  description "Test DSPy installation"

  input do
    const :message, String
  end

  output do
    const :response, String
  end
end

predictor = DSPy::Predict.new(TestSignature)
result = predictor.call(message: "Hello, DSPy!")

puts "✅ DSPy is working! Response: #{result.response}"

```

--------------------------------

### Run Summarization Comparison Example

Source: https://oss.vicente.services/dspy.rb/blog/articles/does-chain-of-thought-improve-summaries

This command executes the summarization comparison script using Ruby. It requires setting the OPENAI_API_KEY environment variable and assumes the necessary gems are bundled.

```bash
export OPENAI_API_KEY=your-key
bundle exec ruby examples/summarization_comparison.rb

```

--------------------------------

### BAML Schema Definition Example

Source: https://oss.vicente.services/dspy.rb/blog/articles/baml-schema-format

An example of a BAML schema definition for task decomposition, showcasing its compact structure.

```baml
class TaskDecomposition {
  subtasks string[]
  task_types string[]
  priority_order int[]
  estimated_effort int[]
  dependencies string[]
  agent_requirements string[]
}
```

--------------------------------

### DSPy Basic Evaluation Setup

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Create an evaluator instance with a predictor and a metric for evaluating LLM performance. The `display_progress` option shows evaluation progress.

```ruby
# Create evaluator with a predictor and metric
predictor = DSPy::Predict.new(YourSignature)
metric = DSPy::Metrics.exact_match(field: :answer)
evaluator = DSPy::Evals.new(predictor, metric: metric)

# Evaluate against test examples
result = evaluator.evaluate(test_examples, display_progress: true)

puts "Score: #{result.score}"
puts "Passed: #{result.passed_examples}/#{result.total_examples}"
```

--------------------------------

### Create a ReAct Agent with Typed Tools

Source: https://oss.vicente.services/dspy.rb/getting-started/first-program

Instantiate a ReAct agent using a defined signature and a list of typed tools. This example shows how to combine the TravelPlanner signature with the WeatherTool.

```ruby
# Create a ReAct agent with typed tools
planner = DSPy::ReAct.new(
  signature: TravelPlanner,
  tools: [WeatherTool.new]
)

result = planner.call(
  destination: "Tokyo",
  duration: 5,
  budget: 2000.0
)

```

--------------------------------

### LangChain.rb Batch Processing Example

Source: https://oss.vicente.services/dspy.rb/advanced/dspy-vs-langchain

Demonstrates how to perform batch processing with LangChain.rb's LLM module, allowing multiple prompts to be sent and processed concurrently.

```ruby
results = llm.complete_batch(prompts: batch_prompts)
```

--------------------------------

### Multi-stage Pipeline with DSPy.rb

Source: https://oss.vicente.services/dspy.rb/getting-started/quick-start

Demonstrates building a multi-stage AI pipeline using DSPy modules. This example outlines an article and then drafts its sections sequentially.

```ruby
class Outline < DSPy::Signature
  description "Outline a thorough overview of a topic."

  input do
    const :topic, String
  end

  output do
    const :title, String
    const :sections, T::Array[String]
  end
end

class DraftSection < DSPy::Signature
  description "Draft a section of an article"

  input do
    const :topic, String
    const :title, String
    const :section, String
  end

  output do
    const :content, String
  end
end

class ArticleDrafter < DSPy::Module
  def initialize
    @build_outline = DSPy::ChainOfThought.new(Outline)
    @draft_section = DSPy::ChainOfThought.new(DraftSection)
  end

  def forward(topic:)
    outline = @build_outline.call(topic: topic)
    
    sections = outline.sections.map do |section|
      @draft_section.call(
        topic: topic,
        title: outline.title,
        section: section
      )
    end

    {
      title: outline.title,
      sections: sections.map(&:content)
    }
  end
end

# Use the pipeline
drafter = ArticleDrafter.new
article = drafter.forward(topic: "The impact of AI on software development")
puts article[:title]
puts article[:sections].first

```

--------------------------------

### Run ADE Demo with MIPROv2

Source: https://oss.vicente.services/dspy.rb/optimization/miprov2

Execute the ADE demo using MIPROv2 to observe its optimization capabilities. This command provides baseline metrics, optimization trials with instruction snapshots, test-set metrics, and a summary log.

```bash
bundle exec ruby examples/ade_optimizer_miprov2/main.rb \
  --limit 300 \
  --auto light \
  --seed 42
```

--------------------------------

### Batch Validation of Examples

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Shows how to validate multiple examples at once using `DSPy::Example.validate_batch`, providing an array of input and expected output hashes.

```ruby
# Validate multiple examples at once
examples_data = [
  {
    input: { text: "Great product!" },
    expected: { sentiment: ClassifyText::Sentiment::Positive, confidence: 0.9 }
  },
  {
    input: { text: "Terrible service." },
    expected: { sentiment: ClassifyText::Sentiment::Negative, confidence: 0.8 }
  }
]

validated_examples = DSPy::Example.validate_batch(ClassifyText, examples_data)
# Returns array of validated DSPy::Example objects

```

--------------------------------

### DSPy ReAct Agent with Tools

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Demonstrates setting up a `DSPy::ReAct` agent for tool-using tasks. It requires a signature, a list of tools (like a calculator), and a maximum iteration count.

```ruby
# Define tools (you would implement CalculatorTool)
calculator = YourCalculatorTool.new

# Create agent
agent = DSPy::ReAct.new(
  ResearchSignature,
  tools: [calculator],
  max_iterations: 10
)

result = agent.call(query: "Calculate compound interest...")
```

--------------------------------

### Integrate with Production Systems using Sidekiq

Source: https://oss.vicente.services/dspy.rb/blog/articles/llm-as-judge-ai-sdr-evaluation

Demonstrates how to integrate LLM judges into a production SDR workflow using Sidekiq for background processing. This example shows the initial require statement.

```ruby
require 'sidekiq'
```

--------------------------------

### Create and Use ReAct Agent with Tools

Source: https://oss.vicente.services/dspy.rb/blog/articles/react-agent-tutorial

Initializes a DSPy ReAct agent with a specific signature and a list of tools, then executes the agent with given inputs.

```ruby
require 'dspy'

# Configure DSPy
DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
end

# Initialize tools
tools = [
  WebSearchTool.new,
  CalculatorTool.new,
  DataAnalysisTool.new
]

# Create the agent with default max_iters of 10 (as per documentation)
research_agent = DSPy::ReAct.new(ResearchAssistant, tools: tools)

# Use the agent
result = research_agent.forward(
  topic: "Ruby programming language adoption trends",
  depth: ResearchDepth::Detailed
)

puts "Summary: #{result.summary}"
puts "Key Statistics: #{result.key_statistics.join(', ')}"
puts "Sources: #{result.sources.join(', ')}"
puts "Confidence: #{result.confidence}"

```

--------------------------------

### Example Validation Error

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Demonstrates how DSPy.rb automatically validates examples against the signature's type constraints, raising an error for type mismatches.

```ruby
# This will raise a validation error
invalid_example = DSPy::Example.new(
  signature_class: ClassifyText,
  input: { text: "Sample text" },
  expected: { 
    sentiment: "positive",  # String instead of Sentiment enum - ERROR!
    confidence: 1.5
  }
)
# => ArgumentError: Type error in expected output for ClassifyText: ...

```

--------------------------------

### Initialize MIPROv2 Optimizer with Preset or Custom Configuration

Source: https://oss.vicente.services/dspy.rb/optimization/miprov2

Configure the MIPROv2 optimizer either by selecting a predefined preset or by manually setting parameters like the number of trials and examples.

```ruby
optimizer = 
  if preset
    DSPy::Teleprompt::MIPROv2.new(metric: metric).tap do |opt|
      opt.configure { |config| config.auto_preset = DSPy::Teleprompt::AutoPreset.deserialize(preset) }
    end
  else
    DSPy::Teleprompt::MIPROv2.new(metric: metric).tap do |opt|
      opt.configure do |config|
        config.num_trials = 6
        config.num_instruction_candidates = 3
        config.bootstrap_sets = 2
        config.max_bootstrapped_examples = 2
        config.max_labeled_examples = 4
        config.optimization_strategy = :adaptive
      end
    end
  end
```

--------------------------------

### Usage Example: Image Analysis

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Instantiate and call the `ImageAnalysis` predictor with a DSPy::Image object. This example demonstrates how to pass parameters and access the results.

```ruby
# Usage examples
analyzer = DSPy::Predict.new(ImageAnalysis)
image = DSPy::Image.new(url: 'https://example.com/landscape.jpg')
result = analyzer.call(
  image: image,
  focus: 'colors',
  detail_level: 'detailed'
)

puts result.description
puts "Colors: #{result.dominant_colors.join(', ')}"
puts "Objects: #{result.objects.join(', ')}"
puts "Mood: #{result.mood}"
```

--------------------------------

### Validate DSPy Example Creation

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Tests the creation of a DSPy Example, ensuring valid inputs are accepted and invalid input types raise an ArgumentError.

```ruby
RSpec.describe DSPy::Example do
  let(:signature) { ClassifyText }
  
  describe "validation" do
    it "accepts valid examples" do
      example = DSPy::Example.new(
        signature_class: signature,
        input: { text: "Sample text" },
        expected: { 
          sentiment: ClassifyText::Sentiment::Positive,
          confidence: 0.8
        }
      )
      
      expect(example.input_values[:text]).to eq("Sample text")
      expect(example.expected_values[:sentiment]).to be_a(ClassifyText::Sentiment)
    end
    
    it "rejects invalid input types" do
      expect {
        DSPy::Example.new(
          signature_class: signature,
          input: { invalid_field: "value" },
          expected: { sentiment: ClassifyText::Sentiment::Positive, confidence: 0.8 }
        )
      }.to raise_error(ArgumentError)
    end
  end
end
```

--------------------------------

### LangChain.rb Sequential Chain Example

Source: https://oss.vicente.services/dspy.rb/advanced/dspy-vs-langchain

Demonstrates a basic sequential chain in LangChain.rb, where the output of one LLMChain is used as input for the next.

```ruby
chain1 = Langchain::Chain::LLMChain.new(llm: llm, prompt: prompt1)
chain2 = Langchain::Chain::LLMChain.new(llm: llm, prompt: prompt2)
result1 = chain1.call(input: data)
result2 = chain2.call(input: result1)
```

--------------------------------

### Example Structs for Union Type Discrimination

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Provides example structs (SearchAction and AnswerAction) used to demonstrate type discrimination within union types in DSPy.rb.

```ruby
# Example structs for demonstration
class SearchAction < T::Struct
  const :query, String
  const :max_results, Integer, default: 10
end

class AnswerAction < T::Struct
  const :content, String
  const :confidence, Float
end
```

--------------------------------

### Evaluate Examples with a Custom Metric

Source: https://oss.vicente.services/dspy.rb/getting-started/core-concepts

Sets up an evaluator to assess model performance against defined examples using a custom metric (exact match for sentiment and confidence).

```ruby
# Use examples for evaluation
evaluator = DSPy::Evals.new

# Define metric
exact_match = ->(example, prediction, trace) {
  example.expected_values[:sentiment] == prediction.sentiment &&
  example.expected_values[:confidence] == prediction.confidence
}

results = evaluator.evaluate(
  examples: examples,
  signature_class: ClassifyText,
  metric: exact_match
) do |example|
  classifier.call(**example.input_values)
end

```

--------------------------------

### Ensure Type Safety in Examples

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Emphasizes the importance of using correct data types for example inputs and expected outputs to maintain type safety with signatures.

```ruby
# Always ensure types match your signature
example = DSPy::Example.new(
  signature_class: ClassifyText,
  input: { text: "Sample text" },
  expected: { 
    sentiment: ClassifyText::Sentiment::Positive,  # Use enum, not string
    confidence: 0.8                                # Use Float, not String
  }
)
```

--------------------------------

### Build Datasets and Evaluation Helpers

Source: https://oss.vicente.services/dspy.rb/optimization/gepa

Prepare datasets by building DSPy examples, splitting them into train, validation, and test sets, and evaluating the baseline program on the test set.

```ruby
examples = ADEExampleGEPA.build_examples(rows)
train, val, test = ADEExampleGEPA.split_examples(examples, train_ratio: 0.6, val_ratio: 0.2)
baseline = ADEExampleGEPA.evaluate(program, test)
```

--------------------------------

### Initialize ReAct Agent with Tools

Source: https://oss.vicente.services/dspy.rb/getting-started/quick-start

Initialize a ReAct agent by providing the task signature and an array of tool instances. This enables the agent to use the defined tools for reasoning.

```ruby
agent = DSPy::ReAct.new(
  WeatherReport,
  tools: [WeatherTool.new]
)
```

--------------------------------

### Vector Database Retriever Example

Source: https://oss.vicente.services/dspy.rb/advanced/rag

Provides an example implementation of a retriever that integrates with a vector database. It includes placeholder methods for embedding generation and vector search.

```ruby
# Example integration with a vector database
class VectorDBRetriever
  def initialize(connection_string, collection_name)
    @connection_string = connection_string
    @collection_name = collection_name
    # Initialize your vector DB client here
  end

  def search(query, k: 5, similarity_threshold: 0.7)
    # Implement vector similarity search
    # This is a placeholder - actual implementation depends on your vector DB
    
    begin
      # Convert query to embedding
      embedding = generate_embedding(query)
      
      # Search vector database
      results = vector_db_search(embedding, k: k)
      
      # Filter by similarity threshold
      relevant_results = results.select { |r| r[:similarity] >= similarity_threshold }
      
      # Extract text content
      relevant_results.map { |r| r[:text] }.join('\n\n')
    rescue => e
      puts "Vector search failed: #{e.message}"
      ""
    end
  end

  private

  def generate_embedding(text)
    # Integrate with your embedding service
    # e.g., OpenAI embeddings, SentenceTransformers, etc.
  end

  def vector_db_search(embedding, k:)
    # Implement actual vector database search
    # Return array of { text: "...", similarity: 0.85 }
  end
end
```

--------------------------------

### Simple Data Storage Toolset Implementation

Source: https://oss.vicente.services/dspy.rb/advanced/custom-toolsets

A production-ready example of a data storage toolset with operations for storing, retrieving, listing, and deleting data. It uses a hash for in-memory storage and includes basic error handling.

```ruby
class DataStorageToolset < DSPy::Tools::Toolset
  extend T::Sig
  
  toolset_name "data"
  
  tool :store_data, description: "Store data with a key"
  tool :retrieve_data, description: "Retrieve data by key"
  tool :list_keys, description: "List all stored keys"
  tool :delete_data, description: "Delete data by key"
  
  def initialize
    @data_store = {}
  end
  
  sig { params(key: String, value: String).returns(String) }
  def store_data(key:, value:)
    @data_store[key] = {
      value: value,
      stored_at: Time.now.iso8601
    }
    
    "Data stored successfully for key: #{key}"
  rescue => e
    "Error storing data: #{e.message}"
  end
  
  sig { params(key: String).returns(String) }
  def retrieve_data(key:)
    data = @data_store[key]
    
    if data
      {
        key: key,
        value: data[:value],
        stored_at: data[:stored_at]
      }.to_json
    else
      "No data found for key: #{key}"
    end
  rescue => e
    "Error retrieving data: #{e.message}"
  end
  
  sig { returns(String) }
  def list_keys
    keys = @data_store.keys
    
    {
      keys: keys,
      count: keys.length
    }.to_json
  rescue => e
    "Error listing keys: #{e.message}"
  end
  
  sig { params(key: String).returns(String) }
  def delete_data(key:)
    if @data_store.delete(key)
      "Data deleted successfully for key: #{key}"
    else
      "No data found for key: #{key}"
    end
  rescue => e
    "Error deleting data: #{e.message}"
  end
end

```

--------------------------------

### Observability Hook: Log Before Example Evaluation

Source: https://oss.vicente.services/dspy.rb/optimization/evaluation

Registers a callback using `DSPy::Evals.before_example` to log information about an example before it is scored. This hook allows for custom logging or telemetry.

```ruby
# Log each example before it is scored
DSPy::Evals.before_example do |payload|
  example = payload[:example]
  DSPy.logger.info("Evaluating example #{example.id}") if example.respond_to?(:id)
end

```

--------------------------------

### Migration Guide: Before (Complex Monkey-Patching)

Source: https://oss.vicente.services/dspy.rb/advanced/observability-interception

Illustrates the legacy approach using monkey-patching to intercept internal APIs, which is complex and fragile.

```ruby
# Required monkey-patching
module ContextInterceptor
  def with_span(operation:, **attributes)
    # Complex interception logic
    super  
  end
end
DSPy::Context.singleton_class.prepend(ContextInterceptor)

```

--------------------------------

### ReAct Agent Implementation

Source: https://oss.vicente.services/dspy.rb/llms-full.txt

Implement a ReAct agent using `DSPy::ReAct.new`. This example shows how to initialize the agent with a signature and a list of tools, such as a calculator.

```ruby
class ResearchAssistant < DSPy::Module
  def initialize
    super

    # Create tools (implement as needed for your use case)
    calculator = YourCalculatorTool.new

    @agent = DSPy::ReAct.new(
      ResearchSignature,
      tools: [calculator]
    )
  end

  def forward(query:)
    @agent.call(query: query)
  end
end
```

--------------------------------

### Create Balanced Examples Across Categories

Source: https://oss.vicente.services/dspy.rb/core-concepts/examples

Provides a Ruby method to generate a balanced set of examples, ensuring equal representation across all defined sentiment categories.

```ruby
# Ensure balanced representation across all output categories
def create_balanced_examples
  categories = ClassifyText::Sentiment.values
  examples_per_category = 20
  
  categories.flat_map do |sentiment|
    create_examples_for_sentiment(sentiment, count: examples_per_category)
  end
end
```

--------------------------------

### Module Stack Metadata Example

Source: https://oss.vicente.services/dspy.rb/core-concepts/events

An example of the metadata included in events, showing the module path, root, leaf, and scope information. This can be used for filtering and custom routing.

```json
{
  module_path: [
    {id: "root_uuid", class: "DeepSearch", label: nil},
    {id: "planner_uuid", class: "DSPy::Predict", label: "planner"}
  ],
  module_root: {...},
  module_leaf: {...},
  module_scope: {
    ancestry_token: "root_uuid>planner_uuid",
    depth: 2
  }
}

```

--------------------------------

### DSPy.rb Improved Error Message Example

Source: https://oss.vicente.services/dspy.rb/blog/articles/json-parsing-reliability

Shows an example of a more informative error message provided by DSPy.rb when JSON parsing fails, including original content length.

```text
Failed to parse LLM response as JSON: unexpected token. 
Original content length: 156 chars

```
Tokens:
Raw