/dspy-ruby

name: dspy-ruby
description: This skill should be used when working with DSPy.rb, a Ruby framework for building type-safe, composable LLM applications. Use this when implementing predictable AI features, creating LLM signatures and modules, configuring language model providers (OpenAI, Anthropic, Gemini, Ollama), building agent systems with tools, optimizing prompts, or testing LLM-powered functionality in Ruby applications.

DSPy.rb Expert

Overview

DSPy.rb is a Ruby framework that enables developers to **program LLMs, not prompt them**. Instead of manually crafting prompts, define application requirements through type-safe, composable modules that can be tested, optimized, and version-controlled like regular code.

This skill provides comprehensive guidance on:

• Creating type-safe signatures for LLM operations
• Building composable modules and workflows
• Configuring multiple LLM providers
• Implementing agents with tools
• Testing and optimizing LLM applications
• Production deployment patterns

Core Capabilities

1. Type-Safe Signatures

Create input/output contracts for LLM operations with runtime type checking.

**When to use**: Defining any LLM task, from simple classification to complex analysis.

**Quick reference**:

class EmailClassificationSignature < DSPy::Signature
  description "Classify customer support emails"

  input do
    const :email_subject, String
    const :email_body, String
  end

  output do
    const :category, T.enum(["Technical", "Billing", "General"])
    const :priority, T.enum(["Low", "Medium", "High"])
  end
end

**Templates**: See `assets/signature-template.rb` for comprehensive examples including:

• Basic signatures with multiple field types
• Vision signatures for multimodal tasks
• Sentiment analysis signatures
• Code generation signatures

**Best practices**:

• Always provide clear, specific descriptions
• Use enums for constrained outputs
• Include field descriptions with `desc:` parameter
• Prefer specific types over generic String when possible

**Full documentation**: See `references/core-concepts.md` sections on Signatures and Type Safety.

2. Composable Modules

Build reusable, chainable modules that encapsulate LLM operations.

**When to use**: Implementing any LLM-powered feature, especially complex multi-step workflows.

**Quick reference**:

class EmailProcessor < DSPy::Module
  def initialize
    super
    @classifier = DSPy::Predict.new(EmailClassificationSignature)
  end

  def forward(email_subject:, email_body:)
    @classifier.forward(
      email_subject: email_subject,
      email_body: email_body
    )
  end
end

**Templates**: See `assets/module-template.rb` for comprehensive examples including:

• Basic modules with single predictors
• Multi-step pipelines that chain modules
• Modules with conditional logic
• Error handling and retry patterns
• Stateful modules with history
• Caching implementations

**Module composition**: Chain modules together to create complex workflows:

class Pipeline < DSPy::Module
  def initialize
    super
    @step1 = Classifier.new
    @step2 = Analyzer.new
    @step3 = Responder.new
  end

  def forward(input)
    result1 = @step1.forward(input)
    result2 = @step2.forward(result1)
    @step3.forward(result2)
  end
end

**Full documentation**: See `references/core-concepts.md` sections on Modules and Module Composition.

3. Multiple Predictor Types

Choose the right predictor for your task:

**Predict**: Basic LLM inference with type-safe inputs/outputs

predictor = DSPy::Predict.new(TaskSignature)
result = predictor.forward(input: "data")

**ChainOfThought**: Adds automatic reasoning for improved accuracy

predictor = DSPy::ChainOfThought.new(TaskSignature)
result = predictor.forward(input: "data")
# Returns: { reasoning: "...", output: "..." }

**ReAct**: Tool-using agents with iterative reasoning

predictor = DSPy::ReAct.new(
  TaskSignature,
  tools: [SearchTool.new, CalculatorTool.new],
  max_iterations: 5
)

**CodeAct**: Dynamic code generation (requires `dspy-code_act` gem)

predictor = DSPy::CodeAct.new(TaskSignature)
result = predictor.forward(task: "Calculate factorial of 5")

**When to use each**:

• **Predict**: Simple tasks, classification, extraction
• **ChainOfThought**: Complex reasoning, analysis, multi-step thinking
• **ReAct**: Tasks requiring external tools (search, calculation, API calls)
• **CodeAct**: Tasks best solved with generated code

**Full documentation**: See `references/core-concepts.md` section on Predictors.

4. LLM Provider Configuration

Support for OpenAI, Anthropic Claude, Google Gemini, Ollama, and OpenRouter.

**Quick configuration examples**:

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

# Anthropic Claude
DSPy.configure do |c|
  c.lm = DSPy::LM.new('anthropic/claude-3-5-sonnet-20241022',
    api_key: ENV['ANTHROPIC_API_KEY'])
end

# Google Gemini
DSPy.configure do |c|
  c.lm = DSPy::LM.new('gemini/gemini-1.5-pro',
    api_key: ENV['GOOGLE_API_KEY'])
end

# Local Ollama (free, private)
DSPy.configure do |c|
  c.lm = DSPy::LM.new('ollama/llama3.1')
end

**Templates**: See `assets/config-template.rb` for comprehensive examples including:

• Environment-based configuration
• Multi-model setups for different tasks
• Configuration with observability (OpenTelemetry, Langfuse)
• Retry logic and fallback strategies
• Budget tracking
• Rails initializer patterns

**Provider compatibility matrix**:

| Feature | OpenAI | Anthropic | Gemini | Ollama | |---------|--------|-----------|--------|--------| | Structured Output | ✅ | ✅ | ✅ | ✅ | | Vision (Images) | ✅ | ✅ | ✅ | ⚠️ Limited | | Image URLs | ✅ | ❌ | ❌ | ❌ | | Tool Calling | ✅ | ✅ | ✅ | Varies |

**Cost optimization strategy**:

• Development: Ollama (free) or gpt-4o-mini (cheap)
• Testing: gpt-4o-mini with temperature=0.0
• Prod