desiru 0.1.0 → 0.2.0

data/README.md

@@ -2,6 +2,9 @@
 
 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.
 
+Note: This project is in active development. While core functionality is stable, expect continued rapid evolution and new features.
+
+
 ## Overview
 
 Desiru brings the power of DSPy to the Ruby ecosystem, enabling developers to:
@@ -10,7 +13,7 @@ Desiru brings the power of DSPy to the Ruby ecosystem, enabling developers to:
 - 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.
+Desiru provides direct integrations with multiple language model providers including OpenAI, Anthropic, and OpenRouter, with features like streaming, function calling, and prompt caching.
 
 ## Installation
 
@@ -85,6 +88,12 @@ cot = Desiru::ChainOfThought.new("question -> answer")
 # ReAct pattern for tool use
 react = Desiru::ReAct.new("question -> answer", tools: [calculator, search])
 
+# Program of Thought - generates and executes code
+pot = Desiru::ProgramOfThought.new("problem -> solution: float")
+
+# Best of N - samples multiple outputs and selects the best
+best_of_n = Desiru::BestOfN.new("question -> answer", n_samples: 3, selection_criterion: :consistency)
+
 # Compose modules into programs
 class RAGPipeline < Desiru::Program
   def initialize
@@ -187,6 +196,128 @@ model = Desiru::Models::Ollama.new(
 cot = Desiru::ChainOfThought.new("question -> answer", model: model)
 ```
 
+### Assertions and Validation
+
+Desiru provides an assertions system for validating module outputs and enforcing constraints:
+
+```ruby
+# Configure assertions
+Desiru::Assertions.configure do |config|
+  config.max_assertion_retries = 3    # Retry failed assertions up to 3 times
+  config.assertion_retry_delay = 0.5  # Wait 0.5s between retries
+end
+
+# Use assertions in your modules
+class FactChecker < Desiru::Module
+  def forward(statement:)
+    result = @model.complete(prompt: "Verify: #{statement}")
+    confidence = extract_confidence(result)
+    
+    # Hard assertion - will retry if confidence is too low
+    Desiru.assert(confidence > 0.8, "Confidence too low: #{confidence}")
+    
+    { statement: statement, confidence: confidence, verified: true }
+  end
+end
+
+# Use suggestions for soft constraints
+class CodeReviewer < Desiru::Module
+  def forward(code:)
+    review = analyze_code(code)
+    
+    # Soft suggestion - logs warning but continues
+    Desiru.suggest(review[:test_coverage] > 0.7, "Test coverage below 70%")
+    Desiru.suggest(review[:complexity] < 10, "Code complexity too high")
+    
+    review
+  end
+end
+```
+
+Key features:
+- **Assertions** (`Desiru.assert`) - Enforce hard constraints with automatic retries
+- **Suggestions** (`Desiru.suggest`) - Log warnings for soft constraints
+- **Configurable retries** - Control retry behavior for failed assertions
+- **Module integration** - Assertions are fully integrated with the module retry system
+
+See `examples/assertions_example.rb` for more detailed examples.
+
+### REST API with Grape
+
+Desiru provides Grape integration for building REST APIs:
+
+```ruby
+require 'desiru/api'
+
+# Create API with your modules
+api = Desiru::API::GrapeIntegration.new
+api.register_module('/qa', qa_module, description: 'Question answering')
+api.register_module('/summarize', summarizer, description: 'Text summarization')
+
+# Mount as Rack app
+run api.to_rack_app
+```
+
+Features:
+- **Automatic endpoint generation** from Desiru signatures
+- **Parameter validation** based on signature types
+- **CORS support** built-in
+- **Async support** (when enabled in modules)
+- **Streaming endpoints** for real-time responses
+
+Example endpoints:
+```bash
+# Synchronous request
+curl -X POST http://localhost:9292/api/v1/qa \
+  -H "Content-Type: application/json" \
+  -d '{"question": "What is Ruby?"}'
+
+# Async request
+curl -X POST http://localhost:9292/api/v1/summarize \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Long text...", "max_words": 100, "async": true}'
+
+# Check job status
+curl http://localhost:9292/api/v1/jobs/JOB_ID
+
+# Check API health
+curl http://localhost:9292/api/v1/health
+```
+
+See `examples/rest_api.rb` and `examples/rest_api_advanced.rb` for complete examples.
+
+### REST API with Sinatra
+
+Desiru also supports Sinatra for lightweight REST APIs:
+
+```ruby
+require 'desiru/api'
+
+# Create API with Sinatra (lightweight alternative to Grape)
+api = Desiru::API.sinatra do
+  register_module '/qa', qa_module, description: 'Question answering'
+  register_module '/summarize', summarizer, description: 'Text summarization'
+end
+
+# Or explicitly specify the framework
+api = Desiru::API.create(framework: :sinatra) do
+  register_module '/process', processor
+end
+
+# Mount as Rack app
+run api.to_rack_app
+```
+
+Features:
+- **Lightweight** - Minimal dependencies with Sinatra
+- **Same interface** as Grape integration
+- **Full compatibility** with all Desiru module features
+- **CORS support** built-in
+- **Async support** for background processing
+- **Streaming endpoints** for real-time responses
+
+See `examples/sinatra_api.rb` for a complete example.
+
 ### Background Processing
 
 Desiru includes built-in support for asynchronous processing using Sidekiq:
@@ -201,8 +332,10 @@ end
 module = Desiru::Predict.new("question -> answer")
 result = module.call_async(question: "What is 2+2?")
 
-# Check status
+# Check status and progress
 result.ready? # => false (still processing)
+result.status # => "running", "completed", "failed", etc.
+result.progress # => 0-100 (percentage complete)
 result.success? # => true/false (when ready)
 
 # Wait for result
@@ -267,6 +400,172 @@ This approach makes Desiru particularly well-suited for:
 - Systems requiring job persistence and reliability
 - Deployments that need to scale horizontally
 
+### Database Persistence with Sequel
+
+Desiru includes a comprehensive persistence layer using Sequel for tracking:
+- Module execution history and performance metrics
+- API request/response data for analytics
+- Training examples and optimization results
+- Model performance over time
+
+```ruby
+# Configure persistence
+require 'desiru/persistence'
+
+Desiru::Persistence.database_url = 'postgres://localhost/desiru'
+Desiru::Persistence.connect!
+Desiru::Persistence.migrate!
+
+# Track module executions
+execution = Desiru::Persistence[:module_executions].create_for_module(
+  'TextSummarizer',
+  { text: 'Long article...' }
+)
+
+# Complete with results
+Desiru::Persistence[:module_executions].complete(
+  execution.id,
+  { summary: 'Short summary' },
+  { model: 'gpt-3.5-turbo', tokens: 150 }
+)
+
+# Query performance metrics
+repo = Desiru::Persistence[:module_executions]
+puts "Success rate: #{repo.success_rate('TextSummarizer')}%"
+puts "Average duration: #{repo.average_duration('TextSummarizer')}s"
+
+# Store training examples
+examples = [
+  { inputs: { text: 'Example 1' }, outputs: { summary: 'Summary 1' } },
+  { inputs: { text: 'Example 2' }, outputs: { summary: 'Summary 2' } }
+]
+
+Desiru::Persistence[:training_examples].bulk_create('TextSummarizer', examples)
+
+# Export for training
+data = Desiru::Persistence[:training_examples].export_for_training(
+  'TextSummarizer',
+  format: :dspy
+)
+```
+
+#### API Request Tracking
+
+Automatically track all API requests with the persistence middleware:
+
+```ruby
+# Add persistence to your API
+api = Desiru::API.create do
+  register_module '/summarize', summarizer
+end
+
+# Enable automatic request tracking
+app = api.with_persistence(enabled: true)
+
+# Query API metrics
+requests = Desiru::Persistence[:api_requests]
+puts "Requests per minute: #{requests.requests_per_minute}"
+puts "Average response time: #{requests.average_response_time}s"
+puts "Top endpoints: #{requests.top_paths(5)}"
+```
+
+Features:
+- **Automatic tracking** of all API requests and module executions
+- **Performance analytics** including success rates and response times
+- **Training data management** with dataset splitting and export
+- **Optimization tracking** to measure improvements over time
+- **Multiple database support** via Sequel (PostgreSQL, MySQL, SQLite)
+
+### ReAct Module (Tool-Using Agents)
+
+The ReAct module enables building AI agents that can reason about tasks and use tools to gather information:
+
+```ruby
+# Define tools for your agent
+class WeatherTool
+  def self.name
+    "get_weather"
+  end
+  
+  def self.description
+    "Get current weather for a city. Args: city (string)"
+  end
+  
+  def self.call(city:)
+    # Your weather API integration
+    "Current weather in #{city}: sunny, 72°F"
+  end
+end
+
+# Create a ReAct agent with tools
+tools = [WeatherTool, CalculatorTool]
+agent = Desiru::Modules::ReAct.new(
+  'question: string -> answer: string',
+  tools: tools,
+  max_iterations: 5
+)
+
+# The agent will reason and use tools to answer
+result = agent.call(
+  question: "What's the weather in Tokyo and is 72°F warm in Celsius?"
+)
+# The agent will:
+# 1. Call get_weather tool for Tokyo
+# 2. Use calculator to convert 72°F to Celsius
+# 3. Synthesize the final answer
+```
+
+Key features:
+- **Flexible tool format**: Pass tools as classes, hashes, or callables
+- **Automatic reasoning**: The agent decides which tools to use and when
+- **Trajectory management**: Automatically handles long conversations
+- **Error handling**: Gracefully handles tool execution failures
+- **Iteration limits**: Prevents infinite loops
+
+### GraphQL Integration
+
+Desiru provides GraphQL integration with automatic schema generation and efficient batch loading:
+
+```ruby
+require 'desiru/graphql'
+
+# Register your Desiru modules
+generator = Desiru::GraphQL::SchemaGenerator.new
+generator.register_signature('questionAnswer', qa_module)
+generator.register_signature('summarize', summarizer_module)
+
+# Generate GraphQL schema
+schema = generator.generate_schema
+
+# Use with your GraphQL server
+result = schema.execute(
+  query,
+  context: { current_user: user },
+  variables: variables
+)
+```
+
+Features include:
+- **Automatic schema generation** from Desiru signatures
+- **DataLoader pattern** for N+1 query prevention
+- **Batch execution** for multiple queries
+- **Type mapping** including support for Literal types as GraphQL enums
+- **Thread-safe** promise-based lazy loading
+
+#### GraphQL Batch Loading Example
+
+```ruby
+# The executor automatically batches multiple field requests
+executor = Desiru::GraphQL::Executor.new(schema)
+
+# Execute multiple queries efficiently in a single batch
+results = executor.execute_batch([
+  { query: query1, variables: vars1 },
+  { query: query2, variables: vars2 }
+])
+```
+
+
 ## Examples
 
 ### Retrieval-Augmented Generation (RAG)

data/Rakefile

@@ -3,6 +3,7 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
+# RSpec task
 RSpec::Core::RakeTask.new(:spec)
 
 require 'rubocop/rake_task'

data/db/migrations/001_create_initial_tables.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    # API Requests table
+    create_table(:api_requests) do
+      primary_key :id
+      String :method, null: false
+      String :path, null: false
+      String :remote_ip
+      Integer :status_code, null: false
+      Float :response_time
+      String :headers, text: true # JSON
+      String :params, text: true # JSON
+      String :response_body, text: true # JSON
+      String :error_message
+      DateTime :created_at, null: false
+      DateTime :updated_at, null: false
+
+      index :path
+      index :status_code
+      index :created_at
+    end
+
+    # Module Executions table
+    create_table(:module_executions) do
+      primary_key :id
+      foreign_key :api_request_id, :api_requests, on_delete: :cascade
+      String :module_name, null: false
+      String :module_type
+      String :status, null: false, default: 'pending'
+      String :inputs, text: true # JSON
+      String :outputs, text: true # JSON
+      String :metadata, text: true # JSON
+      String :error_message
+      String :error_backtrace, text: true
+      DateTime :started_at, null: false
+      DateTime :finished_at
+      DateTime :created_at, null: false
+      DateTime :updated_at, null: false
+
+      index :module_name
+      index :status
+      index :started_at
+      index %i[module_name status]
+    end
+
+    # Optimization Results table
+    create_table(:optimization_results) do
+      primary_key :id
+      String :module_name, null: false
+      String :optimizer_type, null: false
+      Float :score, null: false
+      Float :baseline_score
+      Integer :training_size
+      Integer :validation_size
+      String :parameters, text: true # JSON
+      String :metrics, text: true # JSON
+      String :best_prompts, text: true # JSON
+      DateTime :started_at
+      DateTime :finished_at
+      DateTime :created_at, null: false
+      DateTime :updated_at, null: false
+
+      index :module_name
+      index :optimizer_type
+      index :score
+      index %i[module_name optimizer_type]
+    end
+
+    # Training Examples table
+    create_table(:training_examples) do
+      primary_key :id
+      String :module_name, null: false
+      String :dataset_type, default: 'training'
+      String :inputs, text: true, null: false # JSON
+      String :expected_outputs, text: true # JSON
+      String :metadata, text: true # JSON
+      Integer :used_count, default: 0
+      DateTime :last_used_at
+      DateTime :created_at, null: false
+      DateTime :updated_at, null: false
+
+      index :module_name
+      index :dataset_type
+      index %i[module_name dataset_type]
+    end
+  end
+
+  down do
+    drop_table(:training_examples)
+    drop_table(:optimization_results)
+    drop_table(:module_executions)
+    drop_table(:api_requests)
+  end
+end

data/db/migrations/002_create_job_results.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    # Job Results table for persisting background job results
+    create_table(:job_results) do
+      primary_key :id
+      String :job_id, null: false, unique: true
+      String :job_class, null: false
+      String :queue, null: false
+      String :status, null: false, default: 'pending' # pending, processing, completed, failed
+      Integer :progress, default: 0
+      String :message
+      String :inputs, text: true # JSON
+      String :result, text: true # JSON
+      String :error_message
+      String :error_backtrace, text: true
+      Integer :retry_count, default: 0
+      DateTime :enqueued_at, null: false
+      DateTime :started_at
+      DateTime :finished_at
+      DateTime :expires_at
+      DateTime :created_at, null: false
+      DateTime :updated_at, null: false
+
+      index :job_id
+      index :job_class
+      index :status
+      index :queue
+      index :created_at
+      index :expires_at
+      index %i[job_class status]
+    end
+  end
+
+  down do
+    drop_table(:job_results)
+  end
+end

data/desiru-development-swarm.yml

@@ -0,0 +1,185 @@
+version: 1
+swarm:
+  name: "Desiru Development Team"
+  main: project_lead
+  before:
+    - "echo '🚀 Starting Desiru development session...'"
+    - "shadowenv exec -- bundle install"
+    - "shadowenv exec -- bundle exec rspec --help > /dev/null || echo 'RSpec ready'"
+  instances:
+    project_lead:
+      description: "Project lead coordinating Desiru development, managing releases, and ensuring code quality"
+      directory: .
+      model: opus
+      connections: [core_architect, feature_implementer, test_specialist, release_manager]
+      prompt: |
+        You are the project lead for Desiru, a Ruby implementation of DSPy. Your responsibilities include:
+        
+        - Coordinating development work across the team
+        - Making architectural decisions and ensuring code quality
+        - Prioritizing GitHub issues based on the roadmap
+        - Reviewing code changes before they're committed
+        - Managing the overall development process
+        
+        Key project context:
+        - This is a Ruby gem implementing DSPy (Declarative Self-Improving) for programming language models
+        - Current version: 0.1.1 (check lib/desiru/version.rb)
+        - Uses RSpec for testing (NEVER use Minitest)
+        - Follows Ruby community conventions
+        - Has a comprehensive roadmap in issue #22
+        
+        Always use 'shadowenv exec --' prefix for Ruby/bundler commands. Use 'be' alias for bundle exec.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      allowed_tools:
+        - Read
+        - Edit
+        - Bash
+        - WebSearch
+        - WebFetch
+
+    core_architect:
+      description: "Senior architect implementing core DSPy infrastructure, modules, and optimizers"
+      directory: ./lib/desiru
+      model: opus
+      connections: [feature_implementer, test_specialist]
+      prompt: |
+        You are the core architect for Desiru's DSPy implementation. Your expertise includes:
+        
+        - Implementing core DSPy modules (ProgramOfThought, MultiChainComparison, BestOfN)
+        - Building optimizers (MIPROv2, COPRO, BootstrapFewShotWithRandomSearch)
+        - Designing the compilation infrastructure and trace collection system
+        - Creating typed predictors and example/prediction classes
+        
+        Focus on high-priority features from the roadmap (issue #22):
+        - Phase 1: Core Functionality (Example/Prediction classes, ProgramOfThought, MIPROv2, Trace collection)
+        - Phase 2: Enhanced Optimization (MultiChainComparison, BestOfN, COPRO)
+        
+        Always follow Ruby conventions and ensure code is clean, well-documented, and tested.
+        Use 'shadowenv exec --' for Ruby commands and 'be' for bundle exec.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - Bash
+
+    feature_implementer:
+      description: "Feature developer implementing specific DSPy components, utilities, and integrations"
+      directory: ./lib/desiru
+      model: opus
+      connections: [test_specialist]
+      prompt: |
+        You are a feature developer specializing in implementing specific DSPy components. Your focus areas:
+        
+        - Implementing modules: Refine, ChainOfThoughtWithHint, streaming support
+        - Building utilities: data loaders, metrics system, serialization
+        - Creating multi-provider LLM abstractions
+        - Adding advanced features like suggestions system
+        
+        Current priority features (from roadmap issue #22):
+        - Medium priority: Refine module, ChainOfThoughtWithHint, advanced metrics
+        - Utilities: Data loaders (CSV, JSON), streaming support, serialization
+        
+        Ensure all implementations follow existing patterns and are thoroughly tested.
+        Use 'shadowenv exec --' for Ruby commands and 'be' for bundle exec.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - Bash
+
+    test_specialist:
+      description: "Testing expert ensuring comprehensive test coverage and quality assurance"
+      directory: ./spec
+      model: sonnet
+      prompt: |
+        You are the testing specialist for Desiru. Your responsibilities include:
+        
+        - Writing comprehensive RSpec tests for all new features
+        - Ensuring test coverage for core functionality
+        - Creating integration tests for DSPy workflows
+        - Maintaining test quality and performance
+        - Running test suites and fixing test failures
+        
+        CRITICAL: This project uses RSpec exclusively. NEVER use Minitest or create test/ directories.
+        All tests must be in spec/ directory using RSpec format.
+        
+        Key testing priorities:
+        - Round-trip serialization tests
+        - Integration tests for modules and optimizers
+        - Performance benchmarks
+        - Cross-version compatibility tests
+        
+        Use 'shadowenv exec --' for Ruby commands and 'be rspec' for running tests.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - Bash
+
+    release_manager:
+      description: "Release engineering specialist handling versioning, changelogs, and gem publishing"
+      directory: .
+      model: sonnet
+      prompt: |
+        You are the release manager for Desiru. Your responsibilities include:
+        
+        - Managing semantic versioning in lib/desiru/version.rb
+        - Updating CHANGELOG.md with new features and fixes
+        - Preparing release documentation
+        - Coordinating gem publishing to RubyGems
+        - Ensuring release readiness (tests pass, docs updated)
+        
+        Current version: 0.1.1 (check lib/desiru/version.rb)
+        
+        Release process:
+        1. Update version number in lib/desiru/version.rb
+        2. Update CHANGELOG.md with version changes
+        3. Commit changes: git commit -am "Bump version to x.y.z"
+        4. Create version tag: git tag -a vx.y.z -m "Release version x.y.z"
+        5. Push changes and tag: git push && git push --tags
+        
+        Use 'shadowenv exec --' for Ruby commands and follow semantic versioning.
+        Coordinate with project_lead before any releases.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      allowed_tools:
+        - Read
+        - Edit
+        - Bash
+        - WebSearch
+
+    documentation_writer:
+      description: "Documentation specialist maintaining comprehensive docs and examples"
+      directory: ./docs
+      model: sonnet
+      connections: [project_lead]
+      prompt: |
+        You are the documentation specialist for Desiru. Your focus areas:
+        
+        - Maintaining comprehensive API documentation
+        - Creating usage examples and tutorials
+        - Updating feature documentation as new capabilities are added
+        - Ensuring documentation accuracy and clarity
+        - Writing integration guides and best practices
+        
+        Key documentation areas:
+        - Feature gap analysis updates
+        - Integration test strategy documentation
+        - API documentation for new modules and optimizers
+        - Usage examples for new features
+        
+        Keep documentation current with development progress and ensure examples work.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - WebSearch

data/desiru.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
                      '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.required_ruby_version = '>= 3.3.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/obie/desiru'
@@ -36,9 +36,6 @@ Gem::Specification.new do |spec|
   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'
+  # Development dependencies moved to Gemfile
   spec.metadata['rubygems_mfa_required'] = 'false'
 end