desiru 0.1.0 → 0.1.1

data/examples/sinatra_api.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'desiru'
+require 'rack'
+require 'rack/handler/webrick'
+
+# This example demonstrates how to create a lightweight REST API using Desiru's Sinatra integration
+
+# Configure Desiru
+Desiru.configure do |config|
+  config.default_model = Desiru::Models::OpenAI.new(
+    api_key: ENV['OPENAI_API_KEY'] || 'your-api-key',
+    model: 'gpt-3.5-turbo'
+  )
+end
+
+# Define a simple text processing module
+class TextProcessor < Desiru::Module
+  signature 'TextProcessor', 'Process and analyze text'
+
+  input 'text', type: 'string', desc: 'Text to process'
+  input 'operation', type: 'string', desc: 'Operation to perform (uppercase, lowercase, reverse, analyze)'
+
+  output 'result', type: 'string', desc: 'Processed text result'
+  output 'metadata', type: 'dict', desc: 'Additional metadata about the operation'
+
+  def forward(text:, operation:)
+    result = case operation.downcase
+             when 'uppercase'
+               text.upcase
+             when 'lowercase'
+               text.downcase
+             when 'reverse'
+               text.reverse
+             when 'analyze'
+               "Text has #{text.length} characters and #{text.split.length} words"
+             else
+               raise ArgumentError, "Unknown operation: #{operation}"
+             end
+
+    {
+      result: result,
+      metadata: {
+        original_length: text.length,
+        processed_at: Time.now.iso8601,
+        operation: operation
+      }
+    }
+  end
+end
+
+# Define a calculator module
+class Calculator < Desiru::Module
+  signature 'Calculator', 'Perform basic math operations'
+
+  input 'num1', type: 'float', desc: 'First number'
+  input 'num2', type: 'float', desc: 'Second number'
+  input 'operation', type: 'string', desc: 'Operation (+, -, *, /)'
+
+  output 'result', type: 'float', desc: 'Calculation result'
+
+  def forward(num1:, num2:, operation:)
+    result = case operation
+             when '+' then num1 + num2
+             when '-' then num1 - num2
+             when '*' then num1 * num2
+             when '/'
+               raise ArgumentError, "Division by zero" if num2.zero?
+
+               num1 / num2
+             else
+               raise ArgumentError, "Unknown operation: #{operation}"
+             end
+
+    { result: result }
+  end
+end
+
+# Create Sinatra API integration
+api = Desiru::API.sinatra(async_enabled: true) do
+  register_module '/text', TextProcessor.new,
+                  description: 'Process text with various operations'
+
+  register_module '/calculate', Calculator.new,
+                  description: 'Perform basic math calculations'
+end
+
+# Create a Rack app with the API
+app = api.to_rack_app
+
+puts "Starting Sinatra-based Desiru API server on http://localhost:9293"
+puts "\nAvailable endpoints:"
+puts "  POST /api/v1/health - Health check"
+puts "  POST /api/v1/text - Text processing"
+puts "  POST /api/v1/calculate - Calculator"
+puts "  POST /api/v1/async/text - Async text processing"
+puts "  POST /api/v1/async/calculate - Async calculator"
+puts "  GET  /api/v1/jobs/:job_id - Check async job status"
+puts "\nExample requests:"
+puts "  curl -X POST http://localhost:9293/api/v1/text " \
+     "-H 'Content-Type: application/json' -d '{\"text\": \"Hello World\", \"operation\": \"uppercase\"}'"
+puts "  curl -X POST http://localhost:9293/api/v1/calculate " \
+     "-H 'Content-Type: application/json' -d '{\"num1\": 10, \"num2\": 5, \"operation\": \"+\"}'"
+puts "\nPress Ctrl+C to stop the server"
+
+# Start the server
+Rack::Handler::WEBrick.run app, Port: 9293

data/examples/typed_signatures.rb

@@ -6,8 +6,7 @@ require 'desiru'
 
 # Configure Desiru
 Desiru.configure do |config|
-  config.default_model = Desiru::Models::RaixAdapter.new(
-    provider: :openai,
+  config.default_model = Desiru::Models::OpenAI.new(
     model: 'gpt-3.5-turbo',
     api_key: ENV['OPENAI_API_KEY'] || raise('Please set OPENAI_API_KEY environment variable')
   )

data/graphql_optimization_summary.md

@@ -0,0 +1,53 @@
+# GraphQL Optimization Summary
+
+## Overview
+This document summarizes the GraphQL optimizations implemented in the Desiru project.
+
+## Optimizations Implemented
+
+### 1. Type Cache Key Generation (type_builder.rb)
+- **Before**: Used string concatenation for cache keys, resulting in long strings like "Output:id:string:false:nil|name:string:true:nil"
+- **After**: Uses hash-based approach for more compact keys like "Output:1403724691813815013"
+- **Benefit**: Reduced memory usage and faster cache lookups
+
+### 2. Enum Type Extraction (enum_builder.rb)
+- **Before**: Enum generation logic was embedded in TypeBuilder module
+- **After**: Extracted into separate EnumBuilder module
+- **Benefit**: Better separation of concerns, reduced module complexity
+
+### 3. Type Cache Warmer (type_cache_warmer.rb)
+- **New Feature**: Pre-generates commonly used GraphQL types
+- **Benefit**: Improves cold-start performance by warming the cache with common field combinations
+
+### 4. Request Deduplication (data_loader.rb)
+- **Feature**: Groups identical requests within a single GraphQL query
+- **Benefit**: Up to 90% performance improvement for queries with duplicate requests
+- **Use Case**: Prevents N+1 query problems in nested GraphQL queries
+
+## Performance Improvements
+
+Based on the performance benchmark:
+- Queries with duplicate requests show ~90% performance improvement
+- Deduplication ratio of 5:1 (50 requests reduced to 10 unique)
+- Batch processing reduces overhead for multiple similar requests
+
+## Code Quality Improvements
+
+1. **RuboCop Compliance**: All GraphQL files now pass RuboCop linting
+2. **Modular Design**: Clear separation between TypeBuilder, EnumBuilder, and TypeCacheWarmer
+3. **Thread Safety**: Proper mutex usage for concurrent access to type cache
+
+## Files Modified
+
+- `lib/desiru/graphql/type_builder.rb` - Optimized cache key generation
+- `lib/desiru/graphql/enum_builder.rb` - New module for enum type building
+- `lib/desiru/graphql/type_cache_warmer.rb` - New utility for cache warming
+- `lib/desiru/graphql/schema_generator.rb` - Minor refactoring for RuboCop
+
+## Testing
+
+All GraphQL tests pass successfully:
+- 57 examples, 0 failures in GraphQL specs
+- Request deduplication working correctly
+- Type caching functioning as expected
+- Cache warming creates 12 pre-built types (7 output types, 5 enum types)

data/lib/desiru/api/grape_integration.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require 'grape'
+require 'json'
+require 'rack/cors'
+
+module Desiru
+  module API
+    # Grape integration for Desiru - automatically generate REST API endpoints from signatures
+    class GrapeIntegration
+      attr_reader :modules, :async_enabled, :stream_enabled
+
+      def initialize(async_enabled: true, stream_enabled: false)
+        @modules = {}
+        @async_enabled = async_enabled
+        @stream_enabled = stream_enabled
+      end
+
+      # Register a Desiru module with an endpoint path
+      def register_module(path, desiru_module, description: nil)
+        @modules[path] = {
+          module: desiru_module,
+          description: description || "Endpoint for #{desiru_module.class.name}"
+        }
+      end
+
+      # Generate a Grape API class with all registered modules
+      def generate_api
+        modules_config = @modules
+        async = @async_enabled
+        stream = @stream_enabled
+
+        Class.new(Grape::API) do
+          format :json
+          prefix :api
+          version 'v1', using: :path
+
+          # Define class method for type conversion
+          def self.grape_type_for(type_string)
+            case type_string.to_s.downcase
+            when 'integer', 'int'
+              Integer
+            when 'float'
+              Float
+            when 'boolean', 'bool'
+              Grape::API::Boolean
+            when /^list/
+              Array
+            else
+              String # Default to String for unknown types (including 'string', 'str')
+            end
+          end
+
+          helpers do
+            def validate_params(signature, params)
+              errors = {}
+
+              signature.input_fields.each do |name, field|
+                value = params[name]
+
+                # Check required fields
+                if value.nil? && !field.optional?
+                  errors[name] = "is required"
+                  next
+                end
+
+                # Type validation
+                next unless value && field.type
+
+                errors[name] = "must be of type #{field.type}" unless validate_type(value, field.type)
+              end
+
+              errors
+            end
+
+            def validate_type(value, expected_type)
+              case expected_type.to_s.downcase
+              when 'string', 'str'
+                value.is_a?(String)
+              when 'integer', 'int'
+                value.is_a?(Integer) || (value.is_a?(String) && value.match?(/^\d+$/))
+              when 'float'
+                value.is_a?(Numeric)
+              when 'boolean', 'bool'
+                [true, false, 'true', 'false'].include?(value)
+              when /^list/
+                value.is_a?(Array)
+              else
+                true # Unknown types and literals pass validation
+              end
+            end
+
+            def format_response(result)
+              if result.is_a?(Hash)
+                result
+              else
+                { result: result }
+              end
+            end
+
+            def handle_async_request(desiru_module, inputs)
+              result = desiru_module.call_async(inputs)
+
+              {
+                job_id: result.job_id,
+                status: result.status,
+                progress: result.progress,
+                status_url: "/api/v1/jobs/#{result.job_id}"
+              }
+            end
+          end
+
+          # Health check endpoint
+          desc 'Health check'
+          get '/health' do
+            { status: 'ok', timestamp: Time.now.iso8601 }
+          end
+
+          # Generate endpoints for each registered module
+          modules_config.each do |path, config|
+            desiru_module = config[:module]
+            description = config[:description]
+
+            desc description
+            params do
+              # Generate params from signature
+              desiru_module.signature.input_fields.each do |name, field|
+                # Convert Desiru types to Grape types
+                grape_type = case field.type.to_s.downcase
+                             when 'integer', 'int'
+                               Integer
+                             when 'float'
+                               Float
+                             when 'boolean', 'bool'
+                               Grape::API::Boolean
+                             when /^list/
+                               Array
+                             else
+                               String # Default to String for unknown types (including 'string', 'str')
+                             end
+
+                optional name, type: grape_type, desc: field.description
+              end
+            end
+
+            post path do
+              # Validate parameters
+              validation_errors = validate_params(desiru_module.signature, params)
+
+              error!({ errors: validation_errors }, 422) if validation_errors.any?
+
+              # Prepare inputs with symbolized keys
+              inputs = {}
+              desiru_module.signature.input_fields.each_key do |key|
+                value = params[key.to_s] || params[key.to_sym]
+                inputs[key] = value if value
+              end
+
+              begin
+                if async && params[:async] == true && desiru_module.respond_to?(:call_async)
+                  # Handle async request
+                  status 202
+                  handle_async_request(desiru_module, inputs)
+                elsif params[:async] == true
+                  # Module doesn't support async
+                  error!({ error: 'This module does not support async execution' }, 400)
+                else
+                  # Synchronous execution
+                  result = desiru_module.call(inputs)
+                  status 201
+                  format_response(result)
+                end
+              rescue StandardError => e
+                error!({ error: e.message }, 500)
+              end
+            end
+          end
+
+          # Job status endpoint if async is enabled
+          if async
+            namespace :jobs do
+              desc 'Get job status'
+              params do
+                requires :id, type: String, desc: 'Job ID'
+              end
+              get ':id' do
+                status = Desiru::AsyncStatus.new(params[:id])
+
+                response = {
+                  job_id: params[:id],
+                  status: status.status,
+                  progress: status.progress
+                }
+
+                response[:result] = status.result if status.ready?
+
+                response
+              rescue StandardError
+                error!({ error: "Job not found" }, 404)
+              end
+            end
+          end
+
+          # Add streaming endpoint support if enabled
+          if stream
+            namespace :stream do
+              modules_config.each do |path, config|
+                desiru_module = config[:module]
+                description = "#{config[:description]} (streaming)"
+
+                desc description
+                params do
+                  desiru_module.signature.input_fields.each do |name, field|
+                    # Convert Desiru types to Grape types
+                    grape_type = case field.type.to_s.downcase
+                                 when 'integer', 'int'
+                                   Integer
+                                 when 'float'
+                                   Float
+                                 when 'boolean', 'bool'
+                                   Grape::API::Boolean
+                                 when /^list/
+                                   Array
+                                 else
+                                   String # Default to String for unknown types (including 'string', 'str')
+                                 end
+
+                    optional name, type: grape_type, desc: field.description
+                  end
+                end
+
+                post path do
+                  content_type 'text/event-stream'
+                  headers['Cache-Control'] = 'no-cache'
+                  headers['X-Accel-Buffering'] = 'no'
+                  status 200
+
+                  stream do |out|
+                    inputs = {}
+                    desiru_module.signature.input_fields.each_key do |key|
+                      inputs[key] = params[key.to_s] if params.key?(key.to_s)
+                    end
+
+                    # For now, just send the result as a single event
+                    # Future: integrate with actual streaming from LLM
+                    result = desiru_module.call(inputs)
+
+                    out << "event: result\n"
+                    out << "data: #{JSON.generate(format_response(result))}\n\n"
+
+                    out << "event: done\n"
+                    out << "data: {\"status\": \"complete\"}\n\n"
+                  rescue StandardError => e
+                    out << "event: error\n"
+                    out << "data: #{JSON.generate({ error: e.message })}\n\n"
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+
+      # Mount the API in a Rack application
+      def to_rack_app
+        api = generate_api
+
+        Rack::Builder.new do
+          use Rack::Cors do
+            allow do
+              origins '*'
+              resource '*',
+                       headers: :any,
+                       methods: %i[get post put patch delete options head],
+                       expose: ['Access-Control-Allow-Origin']
+            end
+          end
+
+          run api
+        end
+      end
+    end
+  end
+end

data/lib/desiru/api/persistence_middleware.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module Desiru
+  module API
+    # Rack middleware for tracking API requests and module executions
+    class PersistenceMiddleware
+      def initialize(app, enabled: true)
+        @app = app
+        @enabled = enabled
+      end
+
+      def call(env)
+        return @app.call(env) unless @enabled && persistence_available?
+
+        start_time = Time.now
+
+        # Create request record
+        request = Rack::Request.new(env)
+
+        # Call the app
+        status, headers, body = @app.call(env)
+
+        # Calculate response time
+        response_time = Time.now - start_time
+
+        # Store the request and response
+        store_request(request, status, headers, body, response_time)
+
+        # Return the response
+        [status, headers, body]
+      rescue StandardError => e
+        # Log error but don't fail the request
+        warn "PersistenceMiddleware error: #{e.message}"
+        [status, headers, body] || [500, {}, ['Internal Server Error']]
+      end
+
+      private
+
+      def persistence_available?
+        defined?(Desiru::Persistence) &&
+          Desiru::Persistence::Database.connection &&
+          Desiru::Persistence::Setup.initialized?
+      rescue StandardError
+        false
+      end
+
+      def store_request(request, status, _headers, body, response_time)
+        # Only track API endpoints
+        return unless request.path_info.start_with?('/api/')
+
+        api_requests = Desiru::Persistence[:api_requests]
+
+        api_request = api_requests.create(
+          method: request.request_method,
+          path: request.path_info,
+          remote_ip: request.ip,
+          headers: extract_headers(request),
+          params: extract_params(request),
+          status_code: status,
+          response_body: extract_body(body),
+          response_time: response_time
+        )
+
+        # Store module execution if available
+        store_module_execution(api_request.id, request, body) if api_request
+      rescue StandardError => e
+        warn "Failed to store request: #{e.message}"
+      end
+
+      def extract_headers(request)
+        headers = {}
+        request.each_header do |key, value|
+          next unless key.start_with?('HTTP_') || key == 'CONTENT_TYPE'
+
+          header_name = key.sub(/^HTTP_/, '').split('_').map(&:capitalize).join('-')
+          headers[header_name] = value
+        end
+        headers
+      end
+
+      def extract_params(request)
+        if request.content_type&.include?('application/json')
+          request.body.rewind
+          JSON.parse(request.body.read)
+        else
+          request.params
+        end
+      rescue StandardError
+        request.params
+      end
+
+      def extract_body(body)
+        return nil unless body.respond_to?(:each)
+
+        content = body.map { |part| part }
+
+        # Try to parse as JSON
+        JSON.parse(content.join)
+      rescue StandardError
+        content.join
+      end
+
+      def store_module_execution(api_request_id, request, body)
+        # Extract module info from path (e.g., /api/v1/summarize -> summarize)
+        module_path = request.path_info.gsub(%r{^/api/v\d+/}, '')
+        return unless module_path && !module_path.empty?
+
+        params = extract_params(request)
+        result = extract_body(body)
+
+        module_executions = Desiru::Persistence[:module_executions]
+
+        execution = module_executions.create_for_module(
+          module_path.capitalize,
+          params,
+          api_request_id: api_request_id
+        )
+
+        # Mark as completed if we have a result
+        if result.is_a?(Hash) && !result['error']
+          module_executions.complete(execution.id, result)
+        elsif result.is_a?(Hash) && result['error']
+          module_executions.fail(execution.id, result['error'])
+        end
+      rescue StandardError => e
+        warn "Failed to store module execution: #{e.message}"
+      end
+    end
+
+    # Extension for API integrations to add persistence
+    module PersistenceExtension
+      def with_persistence(enabled: true)
+        original_app = to_rack_app
+
+        Rack::Builder.new do
+          use PersistenceMiddleware, enabled: enabled
+          run original_app
+        end
+      end
+    end
+  end
+end
+
+# Add extension to API integrations
+Desiru::API::GrapeIntegration.include(Desiru::API::PersistenceExtension) if defined?(Desiru::API::GrapeIntegration)
+Desiru::API::SinatraIntegration.include(Desiru::API::PersistenceExtension) if defined?(Desiru::API::SinatraIntegration)