desiru 0.1.0

data/README.md

@@ -0,0 +1,343 @@
+# DeSIRu - Declarative Self-Improving Ruby
+
+A Ruby implementation of [DSPy](https://dspy.ai/), the framework for programming—not prompting—language models. Build sophisticated AI systems with modular, composable code instead of brittle prompt strings.
+
+## Overview
+
+Desiru brings the power of DSPy to the Ruby ecosystem, enabling developers to:
+- Write declarative AI programs using Ruby's elegant syntax
+- Automatically optimize prompts and few-shot examples
+- Build portable AI systems that work across different language models
+- Create maintainable, testable AI applications
+
+Desiru leverages [Raix](https://github.com/OlympiaAI/raix) under the hood as its primary chat completion interface, providing seamless support for OpenAI and OpenRouter APIs with features like streaming, function calling, and prompt caching.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'desiru'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install desiru
+```
+
+## Quick Start
+
+```ruby
+require 'desiru'
+
+# Configure your language model
+Desiru.configure do |config|
+  config.default_model = Desiru::Models::OpenAI.new(api_key: ENV['OPENAI_API_KEY'])
+end
+
+# Define a simple question-answering signature
+math = Desiru::ChainOfThought.new("question -> answer: float")
+
+# Use it!
+result = math.call(question: "Two dice are tossed. What is the probability that the sum equals two?")
+puts result.answer # => 0.0278
+```
+
+## Core Concepts
+
+### Signatures
+
+Signatures define the input/output behavior of your AI components:
+
+```ruby
+# Simple signature
+qa = Desiru::Signature.new("question -> answer")
+
+# Typed signature with descriptions
+summarizer = Desiru::Signature.new(
+  "document: string, max_length: int -> summary: string",
+  descriptions: {
+    document: "The text to summarize",
+    max_length: "Maximum number of words in summary",
+    summary: "A concise summary of the document"
+  }
+)
+```
+
+### Modules
+
+Desiru provides several built-in modules for different reasoning patterns:
+
+```ruby
+# Basic prediction
+predict = Desiru::Predict.new("question -> answer")
+
+# Chain of Thought reasoning
+cot = Desiru::ChainOfThought.new("question -> answer")
+
+# ReAct pattern for tool use
+react = Desiru::ReAct.new("question -> answer", tools: [calculator, search])
+
+# Compose modules into programs
+class RAGPipeline < Desiru::Program
+  def initialize
+    @retrieve = Desiru::Retrieve.new(k: 3)
+    @generate = Desiru::ChainOfThought.new("context, question -> answer")
+  end
+
+  def forward(question)
+    context = @retrieve.call(question)
+    @generate.call(context: context, question: question)
+  end
+end
+```
+
+### Optimizers
+
+Automatically improve your AI programs:
+
+```ruby
+# Create a simple training set
+trainset = [
+  { question: "What is 2+2?", answer: "4" },
+  { question: "What is the capital of France?", answer: "Paris" }
+]
+
+# Optimize with few-shot examples
+optimizer = Desiru::BootstrapFewShot.new(metric: :exact_match)
+optimized_program = optimizer.compile(program, trainset: trainset)
+
+# Or use more advanced optimization
+optimizer = Desiru::MIPROv2.new(
+  metric: :f1,
+  num_candidates: 10,
+  max_bootstrapped_demos: 3
+)
+```
+
+## Advanced Usage
+
+### Custom Metrics
+
+```ruby
+def relevance_metric(prediction, ground_truth)
+  # Your custom evaluation logic
+  score = calculate_similarity(prediction.answer, ground_truth.answer)
+  score > 0.8 ? 1.0 : 0.0
+end
+
+optimizer = Desiru::BootstrapFewShot.new(metric: method(:relevance_metric))
+```
+
+### Multi-Stage Pipelines
+
+```ruby
+class AdvancedQA < Desiru::Program
+  def initialize
+    @understand = Desiru::ChainOfThought.new("question -> interpretation")
+    @decompose = Desiru::Predict.new("question -> subquestions: list[str]")
+    @answer_sub = Desiru::ChainOfThought.new("subquestion -> subanswer")
+    @synthesize = Desiru::ChainOfThought.new("subresults -> final_answer")
+  end
+
+  def forward(question)
+    interpretation = @understand.call(question: question)
+    subquestions = @decompose.call(question: question)
+    
+    subresults = subquestions.subquestions.map do |subq|
+      @answer_sub.call(subquestion: subq)
+    end
+    
+    @synthesize.call(subresults: subresults)
+  end
+end
+```
+
+### Model Adapters
+
+Desiru supports multiple language model providers:
+
+```ruby
+# OpenAI
+model = Desiru::Models::OpenAI.new(
+  api_key: ENV['OPENAI_API_KEY'],
+  model: 'gpt-4-turbo-preview'
+)
+
+# Anthropic
+model = Desiru::Models::Anthropic.new(
+  api_key: ENV['ANTHROPIC_API_KEY'],
+  model: 'claude-3-opus-20240229'
+)
+
+# Local models via Ollama
+model = Desiru::Models::Ollama.new(
+  model: 'llama2:70b',
+  base_url: 'http://localhost:11434'
+)
+
+# Use with any module
+cot = Desiru::ChainOfThought.new("question -> answer", model: model)
+```
+
+### Background Processing
+
+Desiru includes built-in support for asynchronous processing using Sidekiq:
+
+```ruby
+# Configure Redis for background jobs
+Desiru.configure do |config|
+  config.redis_url = 'redis://localhost:6379'
+end
+
+# Single async prediction
+module = Desiru::Predict.new("question -> answer")
+result = module.call_async(question: "What is 2+2?")
+
+# Check status
+result.ready? # => false (still processing)
+result.success? # => true/false (when ready)
+
+# Wait for result
+answer = result.wait(timeout: 30) # Blocks until ready
+puts answer.result # => "4"
+
+# Batch processing
+questions = [
+  { question: "What is 2+2?" },
+  { question: "What is 3+3?" }
+]
+batch_result = module.call_batch_async(questions)
+
+# Get batch statistics
+batch_result.wait
+stats = batch_result.stats
+# => { total: 2, successful: 2, failed: 0, success_rate: 1.0 }
+
+# Background optimization
+optimizer = Desiru::BootstrapFewShot.new(metric: :f1)
+job_id = optimizer.compile_async(program, trainset: examples)
+```
+
+To use background processing:
+1. Add `redis` to your Gemfile
+2. Run Sidekiq workers: `bundle exec sidekiq`
+3. Use `call_async` methods on modules
+
+### Background Processing: DSPy vs Desiru
+
+While DSPy (Python) includes async support through Python's `asyncio`, Desiru takes a different approach using Sidekiq and Redis. This design choice reflects the different ecosystems and typical deployment patterns:
+
+#### DSPy's Async Approach
+- **In-process concurrency** using Python's `asyncio`
+- Runs multiple LLM calls concurrently within the same process
+- No persistence - results are lost if the process crashes
+- Best suited for scripts, notebooks, and research
+
+```python
+# DSPy async example
+async def main():
+    output = await predict.acall(question="What is 2+2?")
+```
+
+#### Desiru's Background Jobs Approach
+- **True background processing** with separate worker processes
+- Jobs persist in Redis and survive application restarts
+- Built for production web applications (Rails, Sinatra, etc.)
+- Includes job prioritization, retries, and monitoring
+
+| Feature | DSPy (asyncio) | Desiru (Sidekiq/Redis) |
+|---------|----------------|------------------------|
+| **Architecture** | Single process | Distributed workers |
+| **Persistence** | None | Redis with configurable TTL |
+| **Failure handling** | Basic exceptions | Retries, dead letter queues |
+| **Monitoring** | None | Sidekiq Web UI |
+| **Use case** | Research, notebooks | Production web apps |
+
+This approach makes Desiru particularly well-suited for:
+- Web applications that need non-blocking LLM operations
+- Batch processing of large datasets
+- Systems requiring job persistence and reliability
+- Deployments that need to scale horizontally
+
+## Examples
+
+### Retrieval-Augmented Generation (RAG)
+
+```ruby
+class SimpleRAG < Desiru::Program
+  def initialize(vectorstore)
+    @vectorstore = vectorstore
+    @retrieve = Desiru::Retrieve.new(k: 5)
+    @generate = Desiru::ChainOfThought.new(
+      "context: list[str], question: str -> answer: str"
+    )
+  end
+
+  def forward(question)
+    docs = @retrieve.call(question, index: @vectorstore)
+    @generate.call(context: docs, question: question)
+  end
+end
+
+# Usage
+rag = SimpleRAG.new(my_vectorstore)
+result = rag.call("What are the main features of Ruby 3.0?")
+```
+
+### Classification with Reasoning
+
+```ruby
+classifier = Desiru::ChainOfThought.new(
+  "text -> sentiment: Literal['positive', 'negative', 'neutral']"
+)
+
+# Optimize with examples
+optimizer = Desiru::BootstrapFewShot.new(max_labeled_demos: 8)
+classifier = optimizer.compile(classifier, trainset: sentiment_examples)
+
+# Use it
+result = classifier.call(text: "This framework is amazing!")
+puts result.sentiment # => "positive"
+puts result.reasoning # => "The text uses positive language..."
+```
+
+## Testing
+
+Desiru programs are testable Ruby code:
+
+```ruby
+RSpec.describe MyRAGPipeline do
+  let(:pipeline) { described_class.new }
+  
+  it "retrieves relevant documents" do
+    result = pipeline.call("What is Ruby?")
+    expect(result.answer).to include("programming language")
+  end
+  
+  it "handles complex questions" do
+    # Test with mocked models for deterministic results
+    allow(pipeline).to receive(:model).and_return(mock_model)
+    # ...
+  end
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/obie/desiru.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgments
+
+Desiru is a Ruby port of [DSPy](https://github.com/stanfordnlp/dspy) by Stanford NLP. Special thanks to the DSPy team for creating this innovative approach to language model programming.

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:rubocop_ci)
+
+task ci: %i[spec rubocop_ci]
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = ['--autocorrect']
+end
+
+task default: %i[spec rubocop]

data/desiru.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'lib/desiru/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'desiru'
+  spec.version = Desiru::VERSION
+  spec.authors = ['Obie Fernandez']
+  spec.email = ['obiefernandez@gmail.com']
+
+  spec.summary = 'Declarative Self-Improving Ruby - A Ruby port of DSPy'
+  spec.description = "Desiru brings DSPy's declarative programming paradigm for language models to Ruby, " \
+                     'enabling reliable, maintainable, and portable AI programming.'
+  spec.homepage = 'https://github.com/obie/desiru'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.4.2'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/obie/desiru'
+  spec.metadata['changelog_uri'] = 'https://github.com/obie/desiru/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'forwardable', '~> 1.3'
+  spec.add_dependency 'redis', '~> 5.0'
+  spec.add_dependency 'sidekiq', '~> 7.2'
+  spec.add_dependency 'singleton', '~> 0.1'
+
+  # Development dependencies (basic ones, others in Gemfile)
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.metadata['rubygems_mfa_required'] = 'false'
+end

data/examples/README.md

@@ -0,0 +1,55 @@
+# Desiru Examples
+
+This directory contains example scripts demonstrating various features of Desiru.
+
+## Running the Examples
+
+Before running any examples, make sure you have:
+
+1. Installed the gem dependencies:
+   ```bash
+   bundle install
+   ```
+
+2. Set your OpenAI API key:
+   ```bash
+   export OPENAI_API_KEY="your-api-key-here"
+   ```
+
+## Available Examples
+
+### simple_qa.rb
+Basic question-answering using the Predict and ChainOfThought modules.
+
+```bash
+ruby examples/simple_qa.rb
+```
+
+### typed_signatures.rb
+Demonstrates typed signatures with input/output validation and field descriptions.
+
+```bash
+ruby examples/typed_signatures.rb
+```
+
+### few_shot_learning.rb
+Shows how to use the BootstrapFewShot optimizer to improve module performance with training examples.
+
+```bash
+ruby examples/few_shot_learning.rb
+```
+
+## Creating Your Own Examples
+
+When creating new examples:
+
+1. Use `require "bundler/setup"` to ensure proper gem loading
+2. Configure Desiru with your preferred model
+3. Create modules with appropriate signatures
+4. Handle API keys securely (use environment variables)
+
+## Notes
+
+- These examples use OpenAI by default, but you can configure other providers (Anthropic, OpenRouter, etc.)
+- Make sure to handle API rate limits appropriately in production code
+- Consider caching results for expensive operations

data/examples/async_processing.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'desiru'
+require 'sidekiq'
+
+# Example: Asynchronous Processing with Desiru
+# This example demonstrates how to use background jobs for LLM operations
+
+# Configure Desiru with a mock model for demonstration
+Desiru.configure do |config|
+  # In a real application, you would configure your actual model here
+  # config.default_model = Desiru::Models::OpenAI.new(api_key: ENV['OPENAI_API_KEY'])
+
+  # Redis URL for background job storage
+  config.redis_url = ENV['REDIS_URL'] || 'redis://localhost:6379'
+end
+
+# Mock model for demonstration
+class MockModel
+  def complete(_prompt, **_options)
+    # Simulate processing time
+    sleep(0.5)
+
+    # Return mock response
+    {
+      content: "answer: This is a mock response for demonstration"
+    }
+  end
+
+  def to_config
+    { type: 'mock' }
+  end
+end
+
+# Configure Desiru with mock model
+Desiru.configuration.default_model = MockModel.new
+
+puts "=== Desiru Async Processing Example ==="
+puts
+
+# Example 1: Single async prediction
+puts "1. Single Async Prediction:"
+qa_module = Desiru::Predict.new("question -> answer")
+
+# Submit async job
+result = qa_module.call_async(question: "What is the capital of France?")
+puts "   Job ID: #{result.job_id}"
+puts "   Status: Processing..."
+
+# Check if ready (non-blocking)
+sleep(0.1)
+puts "   Ready? #{result.ready?}"
+
+# Wait for result (blocking with timeout)
+begin
+  final_result = result.wait(timeout: 5)
+  puts "   Result: #{final_result.answer}"
+rescue Desiru::TimeoutError => e
+  puts "   Error: #{e.message}"
+end
+
+puts
+
+# Example 2: Batch processing
+puts "2. Batch Processing:"
+questions = [
+  { question: "What is 2+2?" },
+  { question: "What is the capital of Japan?" },
+  { question: "Who wrote Romeo and Juliet?" }
+]
+
+batch_result = qa_module.call_batch_async(questions)
+puts "   Batch ID: #{batch_result.job_id}"
+puts "   Processing #{questions.size} questions..."
+
+# Wait for batch to complete
+batch_result.wait(timeout: 10)
+
+# Get results
+results = batch_result.results
+stats = batch_result.stats
+
+puts "   Stats:"
+puts "     - Total: #{stats[:total]}"
+puts "     - Successful: #{stats[:successful]}"
+puts "     - Failed: #{stats[:failed]}"
+puts "     - Success Rate: #{(stats[:success_rate] * 100).round(1)}%"
+
+puts "   Results:"
+results.each_with_index do |result, index|
+  if result
+    puts "     [#{index}] #{result.answer}"
+  else
+    puts "     [#{index}] Failed"
+  end
+end
+
+puts
+
+# Example 3: Error handling
+puts "3. Error Handling:"
+
+# Create a module that will fail
+class FailingModel
+  def complete(_prompt, **_options)
+    raise StandardError, "Simulated model failure"
+  end
+
+  def to_config
+    { type: 'failing' }
+  end
+end
+
+failing_module = Desiru::Predict.new("question -> answer", model: FailingModel.new)
+async_result = failing_module.call_async(question: "This will fail")
+
+begin
+  async_result.wait(timeout: 2)
+rescue Desiru::ModuleError => e
+  puts "   Caught error: #{e.message}"
+  error_info = async_result.error
+  puts "   Error class: #{error_info[:class]}"
+  puts "   Error message: #{error_info[:message]}"
+end
+
+puts
+puts "=== Example Complete ==="
+puts
+puts "Note: In a production environment, you would:"
+puts "1. Have Sidekiq workers running: bundle exec sidekiq"
+puts "2. Use real language models instead of mocks"
+puts "3. Implement proper error handling and monitoring"
+puts "4. Consider using Sidekiq Pro for additional features"

data/examples/few_shot_learning.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'desiru'
+
+# Configure Desiru
+Desiru.configure do |config|
+  config.default_model = Desiru::Models::RaixAdapter.new(
+    provider: :openai,
+    model: 'gpt-3.5-turbo',
+    api_key: ENV['OPENAI_API_KEY'] || raise('Please set OPENAI_API_KEY environment variable')
+  )
+end
+
+# Create a sentiment classifier
+classifier = Desiru::Modules::ChainOfThought.new(
+  'text -> sentiment: string, confidence: float'
+)
+
+# Training examples
+training_examples = [
+  {
+    text: 'This product is amazing! I love it so much.',
+    sentiment: 'positive',
+    confidence: 0.95
+  },
+  {
+    text: 'Terrible experience. Would not recommend.',
+    sentiment: 'negative',
+    confidence: 0.90
+  },
+  {
+    text: "It's okay, nothing special but does the job.",
+    sentiment: 'neutral',
+    confidence: 0.80
+  }
+]
+
+# Optimize the classifier with few-shot examples
+optimizer = Desiru::Optimizers::BootstrapFewShot.new(
+  metric: :exact_match,
+  max_bootstrapped_demos: 3
+)
+
+puts "Optimizing classifier with #{training_examples.size} examples..."
+optimized_classifier = optimizer.compile(classifier, trainset: training_examples)
+
+# Test on new examples
+test_texts = [
+  'This framework is absolutely fantastic!',
+  "I'm disappointed with the quality.",
+  'The service is adequate for basic needs.'
+]
+
+puts "\n#{'=' * 50}"
+puts 'Sentiment Analysis Results:'
+puts '=' * 50
+
+test_texts.each do |text|
+  result = optimized_classifier.call(text: text)
+  puts "\nText: \"#{text}\""
+  puts "Sentiment: #{result.sentiment}"
+  puts "Confidence: #{(result.confidence * 100).round(1)}%"
+  puts "Reasoning: #{result.reasoning}" if result.respond_to?(:reasoning)
+end