### Local Setup and Execution

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/workflow-routing-with-dspy.rb.md

Commands to set up your environment and run the workflow routing example locally. Ensure you have the necessary API keys and dependencies installed.

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

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

### Before Callback for Setup

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/module-runtime-context.md

Implements a 'before' callback to execute setup logic, such as recording the start time and logging, before the main forward method is called.

```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"
```

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

### Install Dependencies and Setup Environment

Source: https://github.com/vicentereig/dspy.rb/blob/main/examples/deep_research_cli/README.md

Install project dependencies using Bundler and set up the Ruby version. Ensure your .env file contains necessary API keys for services like OpenAI, Anthropic, and Exa.

```bash
rbenv install 3.4.5   # once
bundle install
```

```bash
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=...          # optional fallback
EXA_API_KEY=exa_dev_...
DEEP_RESEARCH_MODEL=openai/gpt-4.1   # optional override
```

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

### Quick Start with CodeAct

Source: https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/code_act/README.md

Demonstrates basic setup and usage of CodeAct to generate and execute Ruby code for a given task. It shows how to configure the language model, instantiate the agent, and process the results, including the history of generated code and execution outcomes.

```ruby
require 'dspy'
require 'dspy/code_act'

DSPy.configure do |config|
  config.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV.fetch('OPENAI_API_KEY'))
end

agent = DSPy::CodeAct.new

result = agent.forward(
  task: "Calculate the Fibonacci sequence up to the 10th number",
  context: "You have access to standard Ruby libraries"
)

puts result.final_answer
# => [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

result.history.each do |step|
  puts "Step #{step.step}"
  puts "Thought: #{step.thought}"
  puts "Code: #{step.ruby_code}"
  puts "Result: #{step.execution_result}"
end
```

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

### Navigate to Example Directory

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/evaluating-llm-applications.md

Change the current directory to the sentiment-evaluation example folder.

```bash
cd examples/sentiment-evaluation
```

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

### Run an Example Script

Source: https://github.com/vicentereig/dspy.rb/blob/main/AGENTS.md

Executes a specific example script from the examples directory. Replace 'first_predictor.rb' with the desired script name.

```bash
rbenv exec bundle exec ruby examples/first_predictor.rb
```

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

### Start Development Server

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/README.md

Start the Bridgetown development server to view the site locally.

```bash
bundle exec bridgetown start
```

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

### Build Documentation Site

Source: https://github.com/vicentereig/dspy.rb/blob/main/CONTRIBUTING.md

Installs necessary tools (Bun, Playwright), navigates to the docs directory, installs dependencies, and builds the documentation site for production.

```bash
# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Navigate to docs directory
cd docs

# Install npm dependencies
bun install

# Install Playwright browsers for OG image generation
npx playwright install --with-deps chromium

# Install Ruby dependencies
bundle install

# Verify the build works
BRIDGETOWN_ENV=production bun run build
```

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

### Run Basic Search Agent Example

Source: https://github.com/vicentereig/dspy.rb/blob/main/README.md

Execute the basic search agent example using bundle exec ruby. This command runs a common pattern found in the examples directory.

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

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

### Install Dependencies

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/README.md

Install project dependencies using Bundler and Bun.

```bash
bundle install
bun install
```

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

### Create Few-Shot Examples for Prompt Enhancement

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/examples.md

Create few-shot examples with input, output, and reasoning. These examples are used to provide context and improve model performance when used with a predictor.

```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!")
```

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

### Install Ollama and Pull a Model

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/run-llms-locally-with-ollama-and-type-safe-ruby.md

Install Ollama on macOS using Homebrew, start the Ollama server, and pull the llama3.2 model for local use.

```bash
brew install ollama

ollama serve

ollama pull llama3.2
```

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

### Set API Keys for DSPy.rb

Source: https://github.com/vicentereig/dspy.rb/blob/main/examples/README.md

Configure your environment with necessary API keys for different LLM providers. This setup is required for most examples to function correctly.

```bash
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
```

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

### Install and Authenticate GitHub CLI

Source: https://github.com/vicentereig/dspy.rb/blob/main/examples/github-assistant/README.md

Installs the GitHub CLI and authenticates it for use. Ensure you have Homebrew installed for macOS or download from the official website.

```bash
# Install GitHub CLI (macOS)
brew install gh

# Or download from: https://cli.github.com/

# Authenticate
gh auth login
```

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

### Create DSPy Registry with Default Configuration

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/production/registry.md

Instantiate a new signature registry using default settings. This is the simplest way to get started.

```ruby
# Create a registry with default configuration
registry = DSPy::Registry::SignatureRegistry.new
```

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

### Add and Combine Few-Shot Examples

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/optimization/prompt-optimization.md

Few-shot examples can be created and added to a prompt. Existing examples can be combined with new ones to create a more comprehensive set of training data for the prompt.

```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
)
```

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

### Running DSPy.rb Examples

Source: https://github.com/vicentereig/dspy.rb/blob/main/examples/README.md

Provides commands to execute specific examples and enable debug output. Ensure all necessary API keys are set in your environment.

```bash
# Run a specific example
bundle exec ruby examples/sentiment-evaluation/sentiment_classifier.rb

# Run with debug output
DEBUG=true bundle exec ruby examples/sentiment-evaluation/sentiment_classifier.rb
```

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

### Install Dependencies and Set Up Environment Variables

Source: https://github.com/vicentereig/dspy.rb/blob/main/CLAUDE.md

Installs project dependencies using Bundler and sets environment variables for API access. Essential for running the interactive console.

```bash
# Install dependencies
bundle install

# Set up environment variables for API access
export OPENAI_API_KEY=your-openai-api-key
export ANTHROPIC_API_KEY=your-anthropic-api-key

# Run interactive console
bundle exec irb -r ./lib/dspy.rb
```

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

### Example Frontmatter

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/README.md

Example frontmatter for a documentation page, including layout, title, description, breadcrumb, and navigation links.

```yaml
---
layout: docs
title: Your Page Title
description: Brief description for SEO
breadcrumb:
  - title: Parent Section
    url: /parent-section/
  - title: This Page
    url: /parent-section/this-page/
prev:
  title: Previous Page
  url: /previous-page/
next:
  title: Next Page
  url: /next-page/
---

```

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

### Install System Dependencies (Linux)

Source: https://github.com/vicentereig/dspy.rb/blob/main/CONTRIBUTING.md

Installs required libraries for Apache Arrow and OpenBLAS on Linux systems.

```bash
# Ubuntu/Debian
sudo apt-get install libarrow-glib-dev libopenblas-dev

# Fedora/RHEL
sudo dnf install arrow-glib-devel openblas-devel
```

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

### Creating Training Examples in DSPy.rb

Source: https://github.com/vicentereig/dspy.rb/blob/main/examples/README.md

Shows the structure for creating training examples, including the signature class, input, and expected output. This is useful for fine-tuning models.

```ruby
examples = [
  DSPy::Example.new(
    signature_class: QASignature,
    input: { question: "What is the capital of France?" },
    expected: { answer: "Paris" }
  )
]
```

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

### Install DSPy.rb from GitHub

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/getting-started/installation.md

Install the bleeding-edge version of DSPy.rb directly from its GitHub repository.

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

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

### Install System Dependencies (macOS)

Source: https://github.com/vicentereig/dspy.rb/blob/main/CONTRIBUTING.md

Installs required libraries for Apache Arrow and Numo-Tiny-Linalg on macOS using Homebrew.

```bash
# Required for red-arrow (Parquet dataset support)
brew install apache-arrow-glib

# Required for numo-tiny_linalg (MIPROv2 optimizer)
brew install openblas
```

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

### Comparing Example Selection Strategies

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/optimization/prompt-optimization.md

Evaluate the impact of different strategies for selecting few-shot examples, such as random selection versus diverse selection, on model performance.

```ruby
# Random selection
random_examples = training_examples.sample(5)

# Diverse selection (manual)
diverse_examples = [
  training_examples.find { |e| e.expected_sentiment == "positive" },
  training_examples.find { |e| e.expected_sentiment == "negative" },
  training_examples.find { |e| e.expected_sentiment == "neutral" },
  training_examples.find { |e| e.text.length > 100 },  # Long text
  training_examples.find { |e| e.text.length < 50 }    # Short text
].compact

# Compare strategies
strategies = {
  random: random_examples,
  diverse: diverse_examples
}

strategies.each do |strategy, examples|
  test_prompt = prompt.with_examples(examples)
  test_predictor = DSPy::Predict.new(ClassifyText)
  test_predictor.prompt = test_prompt
  
  evaluator = DSPy::Evals.new(test_predictor, metric: :exact_match)
  result = evaluator.evaluate(validation_examples)
  score = result.pass_rate
  
  puts "#{strategy} selection: #{score}"
```

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

### Create Type-Safe Training Examples

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/getting-started/core-concepts.md

Examples provide type-safe training data for optimization. Use DSPy::Example to define inputs and expected outputs for a given signature.

```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 }
  )
]

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

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

### Install DSPy.rb and Set API Key

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/introducing-google-gemini-support.md

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 DSPy with Optional Observability Gems

Source: https://github.com/vicentereig/dspy.rb/blob/main/adr/013-dependency-tree.md

Use these commands to install the core DSPy gem along with observability-related sibling gems. This approach is useful when working within a monorepo structure.

```ruby
gem 'dspy'
gem 'dspy-o11y'
gem 'dspy-o11y-langfuse'
```

```bash
DSPY_WITH_O11Y=1 DSPY_WITH_O11Y_LANGFUSE=1 bundle install
```

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

### Install Project Dependencies

Source: https://github.com/vicentereig/dspy.rb/blob/main/CONTRIBUTING.md

Clones the DSPy.rb repository, installs Ruby dependencies using Bundler, and sets up API keys for testing.

```bash
# Clone the repository
git clone https://github.com/vicentereig/dspy.rb.git
cd dspy.rb

# Install dependencies
bundle install

# Set up API keys for testing
cp .env.sample .env
# Edit .env with your OPENAI_API_KEY and ANTHROPIC_API_KEY
```

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

### Observability Hook: Log Before Example

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/optimization/evaluation.md

Register a callback using `DSPy::Evals.before_example` to execute code before each example is evaluated. Useful for logging or custom 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
```

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

### Basic MIPROv2 Optimization Setup

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/miprov2-paper-implementation.md

Demonstrates setting up a task, defining a success metric, configuring MIPROv2 with a preset, and running the optimization process.

```ruby
require "dspy"
require "dspy/miprov2"

# Define your task with a typed signature
class SentimentClassifier < DSPy::Signature
  description "Classify the sentiment of customer feedback"

  input do
    const :text, String
  end

  output do
    const :sentiment, SentimentLabel  # Positive, Negative, Neutral
    const :confidence, Float
  end
end

# Create baseline program
program = DSPy::Predict.new(SentimentClassifier)

# Define your success metric
metric = proc do |example, prediction|
  prediction.sentiment == example.expected_values[:sentiment]
end

# Configure MIPROv2 with a preset
optimizer = DSPy::Teleprompt::MIPROv2.new(metric: metric)
optimizer.configure { |c| c.auto_preset = :medium }  # 12 trials

# Run optimization
result = optimizer.compile(program, trainset: train, valset: val)

# Use the optimized program
optimized = result.optimized_program
```

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

### Test DSPy Installation

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/getting-started/installation.md

Verify your DSPy installation by configuring it with a language model and running a basic setup.

```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

```

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

### Build for Production

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/README.md

Build the documentation site for production deployment. The output will be in the 'output/' directory.

```bash
BRIDGETOWN_ENV=production bundle exec bridgetown build
```

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

### Progressive Prompting for Complexity

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/optimization/prompt-optimization.md

Build prompts incrementally, starting simple and adding complexity like detailed instructions and examples. This allows for testing the impact of each addition.

```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}"
```

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

### Build Documentation Site Locally

Source: https://github.com/vicentereig/dspy.rb/blob/main/CLAUDE.md

Instructions to build the documentation site locally. This involves navigating to the docs directory, installing dependencies, and running the build command. It's crucial to verify the build before pushing changes.

```bash
# Navigate to docs directory
cd docs

# Install dependencies (if not already done)
npm ci
bundle install

# Build the site locally
BRIDGETOWN_ENV=production npm run build

# If build succeeds, you're ready to push
# If build fails, fix the issues before pushing
```

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

### Install Gems

Source: https://github.com/vicentereig/dspy.rb/blob/main/README.md

Run `bundle install` after updating your Gemfile to install the DSPy.rb gem and its provider dependencies.

```bash
bundle install
```

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

### Install Ollama and Pull a Model

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/run-llms-locally-with-ollama-and-type-safe-ruby.md

Commands to install Ollama on macOS and pull the llama3.2 model. Refer to ollama.com for installation on other platforms.

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

# Pull a model
ollama pull llama3.2
```

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

### Initialize and Use Memory System

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/medium_article.md

Set up a memory system with a store and embedding engine, then store conversational context. Retrieve relevant memories based on semantic similarity.

```ruby
# Create a memory system with embeddings
memory = DSPy::Memory.new(
  store: DSPy::InMemoryStore.new,
  embedding_engine: DSPy::LocalEmbeddingEngine.new
)

# Store conversational context
memory.store("user_123", "Customer prefers technical explanations", 
             metadata: { type: "preference", timestamp: Time.now })

# Retrieve relevant memories
relevant = memory.retrieve("user_123", "How should I explain this API error?")
# => Returns contextually relevant memories based on semantic similarity
```

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

### Batch Validate Examples

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/examples.md

Validate multiple examples at once using `DSPy::Example.validate_batch`. This method takes the signature class and an array of example data 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
```

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

### Basic Optimization Support for Modules

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/modules.md

Demonstrates basic optimization support by creating a module instance and preparing training examples for evaluation.

```ruby
# Create your module
classifier = SentimentAnalyzer.new

# Use with basic optimization if available
# (Advanced optimization features are limited)
training_examples = [
  DSPy::FewShotExample.new(
    input: { text: "I love this!" },
    output: { sentiment: "positive", confidence: 0.9 }
  )
]

# Basic evaluation
result = classifier.call(text: "Test input")
```

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

### Define Basic Examples for Text Classification

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/examples.md

Define a signature for text classification and create basic examples with known correct outputs. These examples are used for evaluation and training.

```ruby
class ClassifyText < DSPy::Signature
  description "Classify text sentiment"
  
  class Sentiment < T::Enum
    enums do
      Positive = new('positive')
      Negative = new('negative')
      Neutral = new('neutral')
    end
  end
  
  input do
    const :text, String
  end
  
  output do
    const :sentiment, Sentiment
    const :confidence, Float
  end
end

# Create examples with known correct outputs
examples = [
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "I absolutely love this product!" },
    expected: { 
      sentiment: ClassifyText::Sentiment::Positive, 
      confidence: 0.95 
    }
  ),
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "This is the worst experience ever." },
    expected: { 
      sentiment: ClassifyText::Sentiment::Negative, 
      confidence: 0.92 
    }
  ),
  DSPy::Example.new(
    signature_class: ClassifyText,
    input: { text: "The weather is okay today." },
    expected: { 
      sentiment: ClassifyText::Sentiment::Neutral, 
      confidence: 0.78 
    }
  )
]
```

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

### Create, Serialize, and Deserialize DSPy Examples

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/examples.md

Demonstrates how to create a DSPy::Example object, convert it to a hash for persistence, and then recreate it from the hash. Ensure the signature registry is provided when deserializing.

```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 to hash for persistence
example_hash = example.to_h

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

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

### Install DSPy.rb

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/dspy-rb-1-0-0-release.md

Install the DSPy.rb gem using the standard RubyGems command.

```bash
gem install dspy
```

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

### Basic Module Usage

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/modules.md

Demonstrates the basic instantiation and calling of a module with a predefined signature.

```ruby
classifier = ReasoningClassifier.new
result = classifier.call(text: "This is a technical document")

puts result.category   # => "technical"
puts result.reasoning  # => "The document mentions APIs and code examples..."
```

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

### Example Agent Reasoning Output

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/react-agent-tutorial.md

Illustrates the expected output format when detailed observability is enabled, showing the step-by-step thought process, actions taken, and inputs used by the agent.

```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
```

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

### Program File Structure Example

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/program-persistence-and-serialization.md

Illustrates the JSON structure of an individual saved program file, including program data, optimization results, and metadata.

```json
{
  "program_id": "abc123def456",
  "saved_at": "2024-08-26T10:30:00Z",
  "program_data": {
    "class_name": "DSPy::Predict",
    "state": {
      "signature_class": "ProductReview",
      "instruction": "Focus on specific product features...",
      "few_shot_examples": [...] 
    }
  },
  "optimization_result": {
    "best_score_value": 0.92,
    "best_score_name": "f1_score",
    "scores": {...},
    "history": {...}
  },
  "metadata": {
    "dspy_version": "0.20.0",
    "ruby_version": "3.3.0",
    "task": "product_sentiment_analysis"
  }
}
```

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

### Analyze Multiple Product Images

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/multimodal.md

Prepare multiple images by reading them from files, encoding them to base64, and then sending them to the language model for comparison and analysis. Ensure the model used supports image input.

```ruby
images = ['front.jpg', 'back.jpg', 'side.jpg'].map do |filename|
  File.open(filename, 'rb') do |file|
    DSPy::Image.new(
      base64: Base64.strict_encode64(file.read),
      content_type: 'image/jpeg'
    )
  end
end

response = lm.raw_chat do |messages|
  messages.user_with_images(
    'Compare these product images and identify any defects or quality issues.',
    images
  )
end

puts response
```

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

### Example Interactive Prompts

Source: https://github.com/vicentereig/dspy.rb/blob/main/examples/github-assistant/README.md

Illustrative examples of natural language queries you can use in the interactive mode.

```text
You: List the recent issues from microsoft/vscode
You: Find pull requests in rails/rails that need review
You: Get statistics about the golang/go repository
You: Compare issue activity vs PR activity in facebook/react
```

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

### Initialize MIPROv2 Optimizer with Preset or Custom Config

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/optimization/miprov2.md

Instantiate the MIPROv2 optimizer. Use a predefined preset for common scenarios or provide a custom configuration for specific needs like trial counts, candidate numbers, and bootstrap settings.

```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
```

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

### Install Observability Gems in Monorepo

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/production/observability.md

When working within the monorepo, use this command to install the sibling gems for observability.

```bash
DSPY_WITH_O11Y=1 DSPY_WITH_O11Y_LANGFUSE=1 bundle install
```

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

### Implementing Instruction Update Hooks for a Module

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/modules.md

Provides an example of implementing `with_instruction` and `with_examples` for a module to support optimization updates.

```ruby
class SentimentPredictor < DSPy::Module
  include DSPy::Mixins::InstructionUpdatable

  def initialize
    super
    @predictor = DSPy::Predict.new(SentimentSignature)
  end

  def with_instruction(instruction)
    clone = self.class.new
    clone.instance_variable_set(:@predictor, @predictor.with_instruction(instruction))
    clone
  end

  def with_examples(examples)
    clone = self.class.new
    clone.instance_variable_set(:@predictor, @predictor.with_examples(examples))
    clone
  end
end
```

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

### Conventional Commit Examples

Source: https://github.com/vicentereig/dspy.rb/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for different types of changes.

```bash
feat(scope): add new feature
fix(scope): fix bug
docs(scope): update documentation
test(scope): add tests
refactor(scope): refactor code
```

```bash
git commit -m "feat(signatures): add support for nested types"
git commit -m "fix(anthropic): handle rate limit errors correctly"
git commit -m "docs(miprov2): clarify Bayesian optimization parameters"
```

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

### Install Dependencies with Bundler

Source: https://github.com/vicentereig/dspy.rb/blob/main/AGENTS.md

Installs project dependencies using Bundler. Provider toggles can be activated via DSPY_WITH_* environment variables.

```bash
rbenv exec bundle install
```

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

### Complete Agent System Example with Single Field Union

Source: https://github.com/vicentereig/dspy.rb/blob/main/adr/004-single-field-union-types.md

Demonstrates defining action structs and a signature using a single union field for actions. Includes example usage and automatic deserialization based on the action type.

```ruby
# Define action structs - no type fields needed!
module AgentActions
  class Search < T::Struct
    const :query, String
    const :max_results, Integer, default: 10
  end
  
  class Analyze < T::Struct
    const :data, T::Array[String]
    const :method, String
  end
  
  class Report < T::Struct
    const :findings, String
    const :confidence, Float
  end
end

# Use single union field
class ResearchAgentSignature < DSPy::Signature
  description "Research agent that can search, analyze, and report"
  
  input do
    const :task, String
    const :context, T::Hash[String, T.untyped]
  end
  
  output do
    const :action, T.any(
      AgentActions::Search,
      AgentActions::Analyze,
      AgentActions::Report
    )
    const :reasoning, String
  end
end

# Clean usage
agent = DSPy::Predict.new(ResearchAgentSignature)
result = agent.call(
  task: "Find information about climate change",
  context: { priority: "high" }
)

# Automatic deserialization to correct type
case result.action
when AgentActions::Search
  puts "Searching for: #{result.action.query}"
when AgentActions::Analyze
  puts "Analyzing #{result.action.data.length} items"
when AgentActions::Report
  puts "Report: #{result.action.findings}"
end
```

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

### DSPy.rb Sentiment Analysis Example

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/json-parsing-reliability.md

An example of a sentiment analysis signature and its usage with DSPy.rb. This code benefits from the reliability improvements automatically.

```ruby
# Existing code - no changes needed
class SentimentAnalysis < DSPy::Signature
  input do
    const :text, String
  end
  
  output do
    const :sentiment, String
    const :confidence, Float
  end
end

# This is now more reliable
analyzer = DSPy::Predict.new(SentimentAnalysis)
result = analyzer.forward(text: "This library is amazing!")
```

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

### Basic LM Configuration for Agents

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/module-runtime-context.md

Demonstrates how configuring an agent's LM using `configure` automatically propagates the LM to all its internal predictors, simplifying setup for complex agents like `ReAct`.

```ruby
# Configure a ReAct agent - LM propagates to internal predictors
agent = DSPy::ReAct.new(MySignature, tools: tools)
agent.configure { |c| c.lm = DSPy::LM.new('openai/gpt-4o', api_key: ENV['OPENAI_API_KEY']) }

# All internal predictors (thought_generator, observation_processor) now use gpt-4o
result = agent.call(question: "What is the capital of France?")
```

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

### Old Interface for Creating Few-Shot Demo Sets

Source: https://github.com/vicentereig/dspy.rb/blob/main/adr/008-miprov2-analysis.md

This code demonstrates the deprecated method for creating few-shot demo sets using `BootstrapConfig`. It requires instantiating a configuration object and passing it to the `create_n_fewshot_demo_sets` method.

```ruby
config = DSPy::Teleprompt::Utils::BootstrapConfig.new
config.max_bootstrapped_examples = 4
config.num_candidate_sets = 10

result = Utils.create_n_fewshot_demo_sets(program, trainset, config: config)
demo_sets = result.candidate_sets  # Array<Array<Example>>
```

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

### Run Sentiment Classifier Example

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/evaluating-llm-applications.md

Execute the Ruby script to run the sentiment classifier example, which includes various evaluation stages.

```bash
ruby sentiment_classifier.rb
```

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

### DSPy.rb Generation Trace Example

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/production/observability.md

This example shows the trace structure for a direct LLM call, detailing the model, provider, and token usage.

```text
Trace: gen-trace-123
├─ llm.generate [800ms]
│  ├─ Observation Type: generation
│  ├─ Provider: openai
│  ├─ Model: gpt-4
│  ├─ Response Model: gpt-4-0613
│  ├─ Input: [{"role":"user","content":"What is 2+2?"}]
│  ├─ Output: "4"
│  └─ Tokens: 10 in / 2 out / 12 total
```

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

### Use Database Query Tool in an Agent

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/react-agent-tutorial.md

Demonstrates how to instantiate an agent with the custom DatabaseQueryTool and forward a question to it.

```ruby
# Use it in an agent
analytics_agent = DSPy::ReAct.new(
  DataAnalytics,
  tools: [
    DatabaseQueryTool.new(allowed_models: ['User', 'Order', 'Product'])
  ]
)

result = analytics_agent.forward(
  question: "What's the average order value for customers who signed up in the last month?"
)
```

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

### Evaluate Predictions Against Examples

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/examples.md

Use the `matches_prediction?` method to check if a prediction matches the expected output of an example. This is useful for evaluating model performance.

```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
```

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

### Set Up LLM Provider API Key

Source: https://github.com/vicentereig/dspy.rb/blob/main/examples/github-assistant/README.md

Sets the API key for your chosen Language Model provider. This is necessary for the assistant to function.

```bash
# For OpenAI
export OPENAI_API_KEY=your-openai-key

# Or for Anthropic
export ANTHROPIC_API_KEY=your-anthropic-key
```

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

### Access Example Data

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/core-concepts/examples.md

Access input and expected output values from a DSPy::Example object. Examples can also be converted 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: {...} }
```

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

### Gemini JSON Request Example

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/_articles/under-the-hood-json-extraction.md

Example JSON payload for a Gemini API request, using 'response_mime_type' and 'response_schema' for structured JSON output.

```json
{
  "model": "gemini-1.5-flash",
  "contents": [{"role": "user", "parts": [{"text": "Extract: iPhone 15 Pro - $999"}]}],
  "generation_config": {
    "response_mime_type": "application/json",
    "response_schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" }
      },
      "required": ["name", "price"]
    }
  }
}
```

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

### Install Apache Arrow/Parquet on Debian/Ubuntu

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/datasets_parquet_migration_plan.md

Installs necessary packages for Apache Arrow and Parquet on Debian/Ubuntu systems, including build essentials and development headers.

```bash
sudo apt update
sudo apt install -y ca-certificates lsb-release wget build-essential ruby-dev pkg-config gobject-introspection libglib2.0-dev zlib1g-dev liblzma-dev
wget https://packages.apache.org/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
sudo apt install -y ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
sudo apt update
sudo apt install -y libarrow-glib-dev libparquet-glib-dev
```

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

### Build Datasets and Evaluate Baseline

Source: https://github.com/vicentereig/dspy.rb/blob/main/docs/src/optimization/gepa.md

Prepare datasets for GEPA optimization by building examples, splitting them into train, validation, and test sets, and evaluating the initial baseline program. A held-out test set is crucial for confirming improvements.

```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)
```