Build reliable LLM applications in Ruby using composable, type-safe modules.
DSPy.rb brings structured LLM programming to Ruby developers. Instead of wrestling with prompt strings and parsing responses, you define typed signatures and compose them into pipelines that just work.
Traditional prompting is like writing code with string concatenation: it works until it doesn't. DSPy.rb brings you the programming approach pioneered by dspy.ai: instead of crafting fragile prompts, you define modular signatures and let the framework handle the messy details.
The result? LLM applications that actually scale and don't break when you sneeze.
Core Building Blocks:
- Signatures - Define input/output schemas using Sorbet types
- Predict - Basic LLM completion with structured data
- Chain of Thought - Step-by-step reasoning for complex problems
- ReAct - Tool-using agents with basic tool integration
- CodeAct - Dynamic code execution agents for programming tasks
- Manual Composition - Combine multiple LLM calls into workflows
Optimization & Evaluation:
- Prompt Objects - Manipulate prompts as first-class objects instead of strings
- Typed Examples - Type-safe training data with automatic validation
- Evaluation Framework - Basic testing with simple metrics
- Basic Optimization - Simple prompt optimization techniques
Production Features:
- Reliable JSON Extraction - Native OpenAI structured outputs, Anthropic extraction patterns, and automatic strategy selection with fallback
- Type-Safe Configuration - Strategy enums with automatic provider optimization (Strict/Compatible modes)
- Smart Retry Logic - Progressive fallback with exponential backoff for handling transient failures
- Performance Caching - Schema and capability caching for faster repeated operations
- File-based Storage - Optimization result persistence with versioning
- Multi-Platform Observability - OpenTelemetry, New Relic, and Langfuse integration
- Comprehensive Instrumentation - Event tracking, performance monitoring, and detailed logging
Developer Experience:
- LLM provider support using official Ruby clients:
- Runtime type checking with Sorbet
- Type-safe tool definitions for ReAct agents
- Comprehensive instrumentation and observability
DSPy.rb is actively developed and approaching stability at v0.13.0. The core framework is production-ready with comprehensive documentation, but I'm battle-testing features through the 0.x series before committing to a stable v1.0 API.
Real-world usage feedback is invaluable - if you encounter issues or have suggestions, please open a GitHub issue!
gem 'dspy', '~> 0.13'
Or add to your Gemfile:
gem 'dspy'
Then run:
bundle install
If you need to compile the polars-df
dependency from source (used for data processing in evaluations), install these system packages:
# Update package list
sudo apt-get update
# Install Ruby development files (if not already installed)
sudo apt-get install ruby-full ruby-dev
# Install essential build tools
sudo apt-get install build-essential
# Install Rust and Cargo (required for polars-df compilation)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
# Install CMake (often needed for Rust projects)
sudo apt-get install cmake
Note: The polars-df
gem compilation can take 15-20 minutes. Pre-built binaries are available for most platforms, so compilation is only needed if a pre-built binary isn't available for your system.
# Define a signature for sentiment classification
class Classify < DSPy::Signature
description "Classify sentiment of a given sentence."
class Sentiment < T::Enum
enums do
Positive = new('positive')
Negative = new('negative')
Neutral = new('neutral')
end
end
input do
const :sentence, String
end
output do
const :sentiment, Sentiment
const :confidence, Float
end
end
# Configure DSPy with your LLM
DSPy.configure do |c|
c.lm = DSPy::LM.new('openai/gpt-4o-mini',
api_key: ENV['OPENAI_API_KEY'],
structured_outputs: true) # Enable OpenAI's native JSON mode
end
# Create the predictor and run inference
classify = DSPy::Predict.new(Classify)
result = classify.call(sentence: "This book was super fun to read!")
puts result.sentiment # => #<Sentiment::Positive>
puts result.confidence # => 0.85
📖 Complete Documentation Website
- Installation & Setup - Detailed installation and configuration
- Quick Start Guide - Your first DSPy programs
- Core Concepts - Understanding signatures, predictors, and modules
- Signatures & Types - Define typed interfaces for LLM operations
- Predictors - Predict, ChainOfThought, ReAct, and more
- Modules & Pipelines - Compose complex multi-stage workflows
- Examples & Validation - Type-safe training data
- Evaluation Framework - Basic testing with simple metrics
- Prompt Optimization - Manipulate prompts as objects
- MIPROv2 Optimizer - Basic automatic optimization
- Storage System - Basic file-based persistence
- Observability - Multi-platform monitoring and metrics
- Complex Types - Sorbet type integration with automatic coercion for structs, enums, and arrays
- Manual Pipelines - Manual module composition patterns
- RAG Patterns - Manual RAG implementation with external services
- Custom Metrics - Proc-based evaluation logic
DSPy.rb has rapidly evolved from experimental to production-ready:
- ✅ JSON Parsing Reliability (v0.8.0) - Native OpenAI structured outputs, strategy selection, retry logic
- ✅ Type-Safe Strategy Configuration (v0.9.0) - Provider-optimized automatic strategy selection
- ✅ Documentation Website (v0.6.4) - Comprehensive docs at vicentereig.github.io/dspy.rb
- ✅ Production Observability - OpenTelemetry, New Relic, and Langfuse integration
- ✅ Optimization Framework - MIPROv2 algorithm with storage & persistence
- ✅ Core Module System - Predict, ChainOfThought, ReAct, CodeAct with type safety
DSPy.rb is currently at v0.13.0 and approaching stability. I'm focusing on real-world usage and refinement through the 0.14, 0.15+ series before committing to a stable v1.0 API.
Current Focus Areas:
- 🚧 Ollama Support - Local model integration
- 🚧 Context Engineering - Advanced prompt optimization techniques
- 🚧 MCP Support - Model Context Protocol integration
- 🚧 Agentic Memory - Persistent agent state management
- 🚧 Performance Optimization - Based on production usage patterns
v1.0 Philosophy: v1.0 will be released after extensive production battle-testing, not after checking off features. This ensures a stable, reliable API backed by real-world validation.
This project is licensed under the MIT License.