desiru 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 483d9107e403dc8c29d5b3621ca65876eaf4b4fb19fadd5b59bc39a12b005e5f
-  data.tar.gz: 58b101dc3f69a6c215a6edda23b4895eaa92007dcf2fbe3710705349c8e48f78
+  metadata.gz: 6d4dc11edfa1084914d29616c396cb2bb163c4ed74bf2e13a07f23edd4b0fefc
+  data.tar.gz: 86a62bd76bf86d7aedff994dcf93e110a64a1d135cad0249c89658f22e93bc78
 SHA512:
-  metadata.gz: d1c90f98e10e42dc1bd59631bb5498c35368a46c4db01bb62fafadeb8cb36f4977d2e58ef1af8b23242428047fc10ea1b9edb3cfe2f139173c0405e22040ee74
-  data.tar.gz: b2060d56c756f30218ab977a0c45d59294d231c5d7b179cadb19483a2af144537e45b40d8f57821f045f23b0e5072ec2086e69bb8e2e04a03f13210d0c6e6494
+  metadata.gz: bee932d2d4adb82e40e80feee6a07156f1f8c6f753660e11c492b2ff0ccc6fa8711587bdc05c2961b9f80b32b84394c226b8408fb7467d0d5bd5d2063254c6c0
+  data.tar.gz: f59cb824b72814078b1646c997f001b6aae47fa0ffc2ad7c06070b2a2a9cb0e3fe6068574624c9f508ac2f87326c9d76c2040f28ada3fc91b5e938113ac81186

data/.env.example

@@ -0,0 +1,34 @@
+# Desiru Configuration Example
+# Copy this file to .env and add your actual API keys
+
+# Choose one of the following LLM providers:
+
+# Anthropic Claude
+# Get your API key from: https://console.anthropic.com/
+# ANTHROPIC_API_KEY=sk-ant-api03-...
+
+# OpenAI
+# Get your API key from: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=sk-...
+
+# Optional: Redis configuration for async/caching features
+# Default: redis://localhost:6379/0
+# REDIS_URL=redis://localhost:6379/0
+
+# Optional: Database URL for persistence features
+# Default: sqlite://db/desiru_development.db
+# DATABASE_URL=sqlite://db/desiru_development.db
+
+# Optional: OpenRouter API
+# Get your API key from: https://openrouter.ai/keys
+# OPENROUTER_API_KEY=sk-or-v1-...
+
+# Optional: Default model selection
+# For Anthropic: claude-3-haiku-20240307, claude-3-sonnet-20240229, claude-3-opus-20240229
+# For OpenAI: gpt-4o-mini, gpt-4o, gpt-4-turbo
+# For OpenRouter: anthropic/claude-3-haiku, openai/gpt-4o-mini, google/gemini-pro
+# DESIRU_DEFAULT_MODEL=claude-3-haiku-20240307
+
+# Optional: Logging level
+# Options: debug, info, warn, error, fatal
+# DESIRU_LOG_LEVEL=info

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.4
+  TargetRubyVersion: 3.3
   NewCops: enable
   SuggestExtensions: false
   Exclude:
@@ -8,9 +8,9 @@ AllCops:
     - 'bin/**/*'
     - 'spec/fixtures/**/*'
 
-require:
+plugins:
   - rubocop-rake
-  - rubocop-rspec
+
 
 # Relaxed metrics for DSL-heavy library code
 Metrics/MethodLength:
@@ -52,4 +52,7 @@ Layout/LineLength:
     - 'spec/**/*'
 
 Gemspec/RequireMFA:
-  Enabled: false
+  Enabled: false
+
+Metrics:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/CLAUDE.md

@@ -17,6 +17,10 @@ This project is in its initial setup phase. When implementing features:
 - Follow Ruby community conventions for project organization
 - Set up bundler with a Gemfile when adding dependencies
 
+## Testing Framework
+
+**IMPORTANT**: This project uses RSpec exclusively for testing. NEVER use Minitest or any other testing framework. Do not add minitest gems, create test/ directories, or write any Minitest-style tests. All tests must be written in RSpec format and placed in the spec/ directory.
+
 ## Workflow Guidance
 
 - For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

data/Gemfile

@@ -2,35 +2,54 @@
 
 source 'https://rubygems.org'
 
-ruby '~> 3.4.2'
+ruby '>= 3.2.0'
 
 # Specify your gem's dependencies in desiru.gemspec
 gemspec
 
 group :development, :test do
+  gem 'dotenv', '~> 3.0'
+  gem 'mock_redis', '~> 0.40'
   gem 'pry', '~> 0.14'
   gem 'pry-byebug', '~> 3.10'
+  gem 'rack-test', '~> 2.0'
   gem 'rake', '~> 13.0'
+  gem 'rdoc'
   gem 'rspec', '~> 3.0'
   gem 'rubocop', '~> 1.21'
   gem 'rubocop-rake', '~> 0.6'
   gem 'rubocop-rspec', '~> 2.0'
   gem 'simplecov', '~> 0.22', require: false
+  gem 'webmock', '~> 3.0'
   gem 'yard', '~> 0.9'
 end
 
 # LLM interaction dependencies
+gem 'anthropic', '~> 0.3'
 gem 'faraday', '~> 2.0'
 gem 'faraday-retry', '~> 2.0'
-gem 'raix', '~> 0.4'
+gem 'open_router', '~> 0.3'
+gem 'ruby-openai', '~> 7.0'
 
 # GraphQL support
 gem 'graphql', '~> 2.0'
 
+# REST API support
+gem 'grape', '~> 2.0'
+gem 'rack-cors', '~> 2.0'
+gem 'sinatra', '~> 3.0'
+gem 'sinatra-contrib', '~> 3.0'
+
+# Database support
+gem 'sequel', '~> 5.0'
+gem 'sqlite3', '~> 1.6' # For development/testing
+
 # Optional dependencies for enhanced functionality
 group :optional do
   gem 'async', '~> 2.0' # For concurrent operations
   gem 'dry-struct', '~> 1.0' # For type safety
   gem 'dry-validation', '~> 1.0' # For validation
+  gem 'jwt', '~> 2.0' # For API authentication
+  gem 'rack-throttle', '~> 0.7' # For rate limiting
   gem 'redis', '~> 5.0' # For caching
 end

data/Gemfile.lock

@@ -23,6 +23,12 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    anthropic (0.4.1)
+      event_stream_parser (>= 0.3.0, < 2.0.0)
+      faraday (>= 1)
+      faraday-multipart (>= 1)
     ast (2.4.3)
     async (2.25.0)
       console (~> 1.29)
@@ -41,6 +47,10 @@ GEM
       fiber-annotation
       fiber-local (~> 1.1)
       json
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    date (3.4.1)
     diff-lcs (1.6.2)
     docile (1.4.1)
     dotenv (3.1.8)
@@ -85,38 +95,56 @@ GEM
       dry-initializer (~> 3.2)
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
+    erb (5.0.1)
     event_stream_parser (1.0.0)
     faraday (2.13.1)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-multipart (1.1.0)
+    faraday-multipart (1.1.1)
       multipart-post (~> 2.0)
     faraday-net_http (3.4.1)
       net-http (>= 0.5.0)
-    faraday-retry (2.3.1)
+    faraday-retry (2.3.2)
       faraday (~> 2.0)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
       fiber-storage
     fiber-storage (1.0.1)
     forwardable (1.3.3)
+    grape (2.4.0)
+      activesupport (>= 6.1)
+      dry-types (>= 1.1)
+      mustermann-grape (~> 1.1.0)
+      rack (>= 2)
+      zeitwerk
     graphql (2.5.9)
       base64
       fiber-storage
       logger
+    hashdiff (1.2.0)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
     io-event (1.11.0)
     json (2.12.2)
+    jwt (2.10.1)
+      base64
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
     metrics (0.12.2)
+    mini_portile2 (2.8.9)
     minitest (5.25.5)
+    mock_redis (0.50.0)
+      redis (~> 5)
+    multi_json (1.15.0)
     multipart-post (2.4.1)
+    mustermann (3.0.3)
+      ruby2_keywords (~> 0.0.1)
+    mustermann-grape (1.1.0)
+      mustermann (>= 1.0.0)
     net-http (0.6.0)
       uri
     open_router (0.3.3)
@@ -124,7 +152,6 @@ GEM
       dotenv (>= 2)
       faraday (>= 1)
       faraday-multipart (>= 1)
-    ostruct (0.6.1)
     parallel (1.27.0)
     parser (3.3.8.0)
       ast (~> 2.4.1)
@@ -136,21 +163,33 @@ GEM
     pry-byebug (3.11.0)
       byebug (~> 12.0)
       pry (>= 0.13, < 0.16)
+    psych (5.2.6)
+      date
+      stringio
+    public_suffix (6.0.2)
     racc (1.8.1)
-    rack (3.1.16)
+    rack (2.2.17)
+    rack-cors (2.0.2)
+      rack (>= 2.0.0)
+    rack-protection (3.2.0)
+      base64 (>= 0.1.0)
+      rack (~> 2.2, >= 2.2.4)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rack-throttle (0.7.1)
+      bundler (>= 1.0.0)
+      rack (>= 1.0.0)
     rainbow (3.1.1)
-    raix (0.9.2)
-      activesupport (>= 6.0)
-      faraday-retry (~> 2.0)
-      open_router (~> 0.2)
-      ostruct
-      ruby-openai (~> 7)
     rake (13.3.0)
+    rdoc (6.14.1)
+      erb
+      psych (>= 4.0.0)
     redis (5.4.0)
       redis-client (>= 0.22.0)
     redis-client (0.25.0)
       connection_pool
     regexp_parser (2.10.0)
+    rexml (3.4.1)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -199,7 +238,10 @@ GEM
       faraday (>= 1)
       faraday-multipart (>= 1)
     ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
     securerandom (0.4.1)
+    sequel (5.93.0)
+      bigdecimal
     sidekiq (7.3.9)
       base64
       connection_pool (>= 2.3.0)
@@ -212,7 +254,22 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    sinatra (3.2.0)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.2.0)
+      tilt (~> 2.0)
+    sinatra-contrib (3.2.0)
+      multi_json (>= 0.0.2)
+      mustermann (~> 3.0)
+      rack-protection (= 3.2.0)
+      sinatra (= 3.2.0)
+      tilt (~> 2.0)
     singleton (0.3.0)
+    sqlite3 (1.7.3)
+      mini_portile2 (~> 2.8.0)
+    stringio (3.1.7)
+    tilt (2.6.0)
     traces (0.15.2)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -220,6 +277,10 @@ GEM
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
     uri (1.0.3)
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     yard (0.9.37)
     zeitwerk (2.7.3)
 
@@ -228,24 +289,38 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  anthropic (~> 0.3)
   async (~> 2.0)
-  bundler (~> 2.0)
   desiru!
+  dotenv (~> 3.0)
   dry-struct (~> 1.0)
   dry-validation (~> 1.0)
   faraday (~> 2.0)
   faraday-retry (~> 2.0)
+  grape (~> 2.0)
   graphql (~> 2.0)
+  jwt (~> 2.0)
+  mock_redis (~> 0.40)
+  open_router (~> 0.3)
   pry (~> 0.14)
   pry-byebug (~> 3.10)
-  raix (~> 0.4)
+  rack-cors (~> 2.0)
+  rack-test (~> 2.0)
+  rack-throttle (~> 0.7)
   rake (~> 13.0)
+  rdoc
   redis (~> 5.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
   rubocop-rake (~> 0.6)
   rubocop-rspec (~> 2.0)
+  ruby-openai (~> 7.0)
+  sequel (~> 5.0)
   simplecov (~> 0.22)
+  sinatra (~> 3.0)
+  sinatra-contrib (~> 3.0)
+  sqlite3 (~> 1.6)
+  webmock (~> 3.0)
   yard (~> 0.9)
 
 RUBY VERSION

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 its earliest stages of development and experimental. Expect many bugs and breaking changes.
+
+
 ## 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
 
@@ -187,6 +190,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 +326,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 +394,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'