desiru 0.1.0 → 0.1.1

data/lib/desiru/api/sinatra_integration.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require 'sinatra/json'
+require 'json'
+require 'rack/cors'
+
+module Desiru
+  module API
+    # Sinatra integration for Desiru - lightweight REST API generation
+    class SinatraIntegration
+      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 Sinatra application with all registered modules
+      def generate_api
+        modules_config = @modules
+        async = @async_enabled
+        stream = @stream_enabled
+
+        Class.new(Sinatra::Base) do
+          set :show_exceptions, false
+          set :raise_errors, true
+
+          # Helpers for parameter validation and response formatting
+          helpers do
+            def validate_type(value, type_string)
+              case type_string.to_s.downcase
+              when 'string', 'str'
+                value.is_a?(String)
+              when 'integer', 'int'
+                value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A-?\d+\z/))
+              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 coerce_value(value, type_string)
+              case type_string.to_s.downcase
+              when 'integer', 'int'
+                value.to_i
+              when 'float'
+                value.to_f
+              when 'boolean', 'bool'
+                ['true', true].include?(value)
+              else
+                value
+              end
+            end
+
+            def format_response(result)
+              if result.is_a?(Desiru::ModuleResult)
+                result.data
+              elsif 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
+
+            def parse_json_body
+              request.body.rewind
+              JSON.parse(request.body.read)
+            rescue JSON::ParserError
+              halt 400, json(error: 'Invalid JSON')
+            end
+          end
+
+          # Content type handling
+          before do
+            content_type :json
+          end
+
+          # Health check endpoint
+          get '/api/v1/health' do
+            json status: 'ok', timestamp: Time.now.iso8601
+          end
+
+          # Generate endpoints for each registered module
+          modules_config.each do |path, config|
+            desiru_module = config[:module]
+
+            # Main module endpoint
+            post "/api/v1#{path}" do
+              params = parse_json_body
+
+              # Convert string keys to symbols for module call
+              symbolized_params = {}
+              params.each { |k, v| symbolized_params[k.to_sym] = v }
+
+              begin
+                result = desiru_module.call(symbolized_params)
+                json format_response(result)
+              rescue Desiru::ModuleError => e
+                halt 400, json(error: e.message)
+              rescue StandardError => e
+                halt 500, json(error: e.message)
+              end
+            end
+
+            # Async endpoint
+            if async && desiru_module.respond_to?(:call_async)
+              post "/api/v1/async#{path}" do
+                params = parse_json_body
+
+                begin
+                  result = handle_async_request(desiru_module, params)
+                  status 202
+                  json result
+                rescue StandardError => e
+                  halt 500, json(error: e.message)
+                end
+              end
+            end
+
+            # Streaming endpoint (Server-Sent Events)
+            next unless stream && desiru_module.respond_to?(:call_stream)
+
+            post "/api/v1/stream#{path}" do
+              content_type 'text/event-stream'
+              stream do |out|
+                params = parse_json_body
+
+                begin
+                  desiru_module.call_stream(params) do |chunk|
+                    out << "event: chunk\n"
+                    out << "data: #{JSON.generate(chunk)}\n\n"
+                  end
+
+                  # Send final result
+                  result = desiru_module.call(params)
+                  out << "event: result\n"
+                  out << "data: #{JSON.generate(format_response(result))}\n\n"
+                  out << "event: done\n"
+                  out << "data: #{JSON.generate({ status: 'complete' })}\n\n"
+                rescue StandardError => e
+                  out << "event: error\n"
+                  out << "data: #{JSON.generate(error: e.message)}\n\n"
+                ensure
+                  out.close
+                end
+              end
+            end
+          end
+
+          # Job status endpoint for async requests
+          if async
+            get '/api/v1/jobs/:job_id' do
+              job_id = params[:job_id]
+
+              if Desiru.respond_to?(:check_job_status)
+                status = Desiru.check_job_status(job_id)
+
+                if status
+                  json status
+                else
+                  halt 404, json(error: 'Job not found')
+                end
+              else
+                halt 501, json(error: 'Async job tracking not implemented')
+              end
+            end
+          end
+        end
+      end
+
+      # Mount the API in a Rack application with CORS
+      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.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'api/grape_integration'
+require_relative 'api/sinatra_integration'
+require_relative 'api/persistence_middleware'
+
+module Desiru
+  module API
+    # Convenience method to create a new API integration
+    # @param framework [Symbol] :grape or :sinatra (default: :grape)
+    def self.create(framework: :grape, async_enabled: true, stream_enabled: false, &)
+      klass = case framework
+              when :grape
+                GrapeIntegration
+              when :sinatra
+                SinatraIntegration
+              else
+                raise ArgumentError, "Unknown framework: #{framework}. Use :grape or :sinatra"
+              end
+
+      integration = klass.new(
+        async_enabled: async_enabled,
+        stream_enabled: stream_enabled
+      )
+
+      # Allow DSL-style configuration
+      integration.instance_eval(&) if block_given?
+
+      integration
+    end
+
+    # Convenience method to create a new Grape API (backward compatibility)
+    def self.grape(async_enabled: true, stream_enabled: false, &)
+      create(framework: :grape, async_enabled: async_enabled, stream_enabled: stream_enabled, &)
+    end
+
+    # Convenience method to create a new Sinatra API
+    def self.sinatra(async_enabled: true, stream_enabled: false, &)
+      create(framework: :sinatra, async_enabled: async_enabled, stream_enabled: stream_enabled, &)
+    end
+  end
+end

data/lib/desiru/assertions.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Desiru
+  # Assertion system for validating module outputs
+  module Assertions
+    # Error raised when an assertion fails
+    class AssertionError < StandardError
+      attr_reader :module_name, :retry_count
+
+      def initialize(message = nil, module_name: nil, retry_count: 0)
+        super(message)
+        @module_name = module_name
+        @retry_count = retry_count
+      end
+
+      # Assertions should trigger module retries
+      def retriable?
+        true
+      end
+    end
+
+    # Assert that a condition is true, raising AssertionError if false
+    # @param condition [Boolean] The condition to check
+    # @param message [String] Optional error message
+    # @raise [AssertionError] if condition is false
+    def self.assert(condition, message = nil)
+      return if condition
+
+      message ||= 'Assertion failed'
+      raise AssertionError, message
+    end
+
+    # Suggest that a condition should be true, logging a warning if false
+    # @param condition [Boolean] The condition to check
+    # @param message [String] Optional warning message
+    def self.suggest(condition, message = nil)
+      return if condition
+
+      message ||= 'Suggestion failed'
+      Desiru.logger.warn("[SUGGESTION] #{message}")
+    end
+
+    # Configuration for assertion behavior
+    class Configuration
+      attr_accessor :max_assertion_retries, :assertion_retry_delay, :log_assertions, :track_assertion_metrics
+
+      def initialize
+        @max_assertion_retries = 3
+        @assertion_retry_delay = 0.1 # seconds
+        @log_assertions = true
+        @track_assertion_metrics = false
+      end
+    end
+
+    # Get or set the assertion configuration
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure assertion behavior
+    def self.configure
+      yield(configuration) if block_given?
+    end
+  end
+
+  # Module-level convenience methods
+  def self.assert(condition, message = nil)
+    Assertions.assert(condition, message)
+  end
+
+  def self.suggest(condition, message = nil)
+    Assertions.suggest(condition, message)
+  end
+end

data/lib/desiru/async_status.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'redis'
+require 'json'
+
+module Desiru
+  # AsyncStatus provides a simple interface for checking job status
+  # Compatible with the REST API's job status endpoint
+  class AsyncStatus
+    attr_reader :job_id
+
+    def initialize(job_id)
+      @job_id = job_id
+      @redis = Redis.new(url: Desiru.configuration.redis_url || ENV.fetch('REDIS_URL', nil))
+    end
+
+    def status
+      status_data = fetch_status
+      return 'pending' unless status_data
+
+      status_data[:status] || 'pending'
+    end
+
+    def progress
+      status_data = fetch_status
+      return 0 unless status_data
+
+      status_data[:progress] || 0
+    end
+
+    def ready?
+      result_data = fetch_result
+      !result_data.nil?
+    end
+
+    def result
+      result_data = fetch_result
+      return nil unless result_data
+
+      raise ModuleError, "Async job failed: #{result_data[:error]}" unless result_data[:success]
+
+      result_data[:result]
+    end
+
+    private
+
+    def fetch_status
+      raw = @redis.get("desiru:status:#{job_id}")
+      return nil unless raw
+
+      JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def fetch_result
+      raw = @redis.get("desiru:results:#{job_id}")
+      return nil unless raw
+
+      JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/desiru/cache.rb

@@ -113,4 +113,4 @@ module Desiru
       @store.delete(lru_key) if lru_key
     end
   end
-end
+end

data/lib/desiru/configuration.rb

@@ -6,7 +6,7 @@ module Desiru
   class Configuration
     attr_accessor :default_model, :cache_enabled, :cache_ttl, :max_retries,
                   :retry_delay, :logger, :module_registry, :model_timeout,
-                  :redis_url
+                  :redis_url, :retry_count
 
     def initialize
       @default_model = nil
@@ -14,6 +14,7 @@ module Desiru
       @cache_ttl = 3600 # 1 hour
       @max_retries = 3
       @retry_delay = 1
+      @retry_count = 3
       @logger = default_logger
       @module_registry = Desiru::Registry.instance
       @model_timeout = 30

data/lib/desiru/errors.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Desiru
+  # Base error class moved here for organization
+  class Error < StandardError
+    attr_reader :context, :original_error
+
+    def initialize(message = nil, context: {}, original_error: nil)
+      @context = context
+      @original_error = original_error
+
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      parts = [message || self.class.name.split('::').last]
+
+      if context.any?
+        context_str = context.map { |k, v| "#{k}: #{v}" }.join(', ')
+        parts << "(#{context_str})"
+      end
+
+      parts << "caused by #{original_error.class}: #{original_error.message}" if original_error
+
+      parts.join(' ')
+    end
+  end
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+
+  # Signature and validation errors
+  class SignatureError < Error; end
+  class ValidationError < Error; end
+
+  # Module execution errors
+  class ModuleError < Error; end
+  class TimeoutError < ModuleError; end
+
+  # Network and API errors
+  class NetworkError < Error; end
+
+  class RateLimitError < NetworkError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **)
+      @retry_after = retry_after
+      super(message, **)
+    end
+  end
+
+  class AuthenticationError < NetworkError; end
+
+  # Model/LLM specific errors
+  class ModelError < Error; end
+
+  class TokenLimitError < ModelError
+    attr_reader :token_count, :token_limit
+
+    def initialize(message = nil, token_count: nil, token_limit: nil, **)
+      @token_count = token_count
+      @token_limit = token_limit
+      super(message, **)
+    end
+  end
+
+  class InvalidResponseError < ModelError; end
+  class ModelNotAvailableError < ModelError; end
+
+  # Job and async related errors
+  class JobError < Error; end
+  class JobNotFoundError < JobError; end
+  class JobTimeoutError < JobError; end
+  class JobFailedError < JobError; end
+
+  # Persistence related errors
+  class PersistenceError < Error; end
+  class DatabaseConnectionError < PersistenceError; end
+  class RecordNotFoundError < PersistenceError; end
+  class RecordInvalidError < PersistenceError; end
+
+  # Optimizer related errors
+  class OptimizerError < Error; end
+  class OptimizationFailedError < OptimizerError; end
+  class InsufficientDataError < OptimizerError; end
+
+  # Cache related errors
+  class CacheError < Error; end
+  class CacheConnectionError < CacheError; end
+
+  # Error handling utilities
+  module ErrorHandling
+    # Wrap a block with error context
+    def with_error_context(context = {})
+      yield
+    rescue StandardError => e
+      # Add context to existing Desiru errors
+      raise Desiru::Error.new(e.message, context: context, original_error: e) unless e.is_a?(Desiru::Error)
+
+      e.context.merge!(context)
+      raise e
+
+      # Wrap other errors with context
+    end
+
+    # Retry with exponential backoff
+    def with_retry(max_attempts: 3, backoff: :exponential, retriable_errors: [NetworkError, TimeoutError])
+      attempt = 0
+
+      begin
+        attempt += 1
+        yield(attempt)
+      rescue *retriable_errors => e
+        raise unless attempt < max_attempts
+
+        delay = calculate_backoff(attempt, backoff)
+        Desiru.logger.warn "Retrying after #{delay}s (attempt #{attempt}/#{max_attempts}): #{e.message}"
+        sleep delay
+        retry
+      end
+    end
+
+    # Log and swallow errors (use sparingly)
+    def safe_execute(default = nil, log_level: :error)
+      yield
+    rescue StandardError => e
+      Desiru.logger.send(log_level, "Error in safe_execute: #{e.class} - #{e.message}")
+      Desiru.logger.debug e.backtrace.join("\n") if log_level == :error
+      default
+    end
+
+    private
+
+    def calculate_backoff(attempt, strategy)
+      case strategy
+      when :exponential
+        [2**(attempt - 1), 60].min # Max 60 seconds
+      when :linear
+        attempt * 2
+      when Numeric
+        strategy
+      else
+        1
+      end
+    end
+  end
+
+  # Include error handling in base classes
+  class Module
+    include ErrorHandling
+  end
+
+  module Jobs
+    class Base
+      include ErrorHandling
+    end
+  end
+end

data/lib/desiru/field.rb

@@ -3,14 +3,16 @@
 module Desiru
   # Represents a field in a signature with type information and metadata
   class Field
-    attr_reader :name, :type, :description, :optional, :default, :validator, :literal_values, :element_type
+    attr_reader :name, :type, :description, :optional, :default, :validator, :literal_values, :element_type,
+                :original_type
 
     alias optional? optional
 
     def initialize(name, type = :string, description: nil, optional: false, default: nil, validator: nil,
-                   literal_values: nil, element_type: nil)
+                   literal_values: nil, element_type: nil, original_type: nil)
       @name = name.to_sym
       @type = normalize_type(type)
+      @original_type = original_type || type.to_s
       @description = description
       @optional = optional
       @default = default
@@ -19,7 +21,7 @@ module Desiru
       @validator = validator || default_validator
     end
 
-    def validate(value)
+    def valid?(value)
       return true if optional && value.nil?
       return true if value.nil? && !default.nil?
 
@@ -46,7 +48,7 @@ module Desiru
         when 'false', 'no', '0', 'f'
           false
         else
-          !!value
+          !value.nil?
         end
       when :literal
         # For literal types, ensure the value is a string and matches one of the allowed values
@@ -63,8 +65,9 @@ module Desiru
           array_value.map do |elem|
             coerced_elem = elem.to_s
             unless element_type[:literal_values].include?(coerced_elem)
+              allowed = element_type[:literal_values].join(', ')
               raise ValidationError,
-                    "Array element '#{coerced_elem}' is not one of allowed values: #{element_type[:literal_values].join(', ')}"
+                    "Array element '#{coerced_elem}' is not one of allowed values: #{allowed}"
             end
 
             coerced_elem
@@ -146,25 +149,25 @@ module Desiru
     def default_validator
       case type
       when :string
-        ->(v) { v.is_a?(String) }
+        ->(value) { value.is_a?(String) }
       when :int
-        ->(v) { v.is_a?(Integer) }
+        ->(value) { value.is_a?(Integer) }
       when :float
-        ->(v) { v.is_a?(Float) || v.is_a?(Integer) }
+        ->(value) { value.is_a?(Float) || value.is_a?(Integer) }
       when :bool
-        ->(v) { v.is_a?(TrueClass) || v.is_a?(FalseClass) }
+        ->(value) { value.is_a?(TrueClass) || value.is_a?(FalseClass) }
       when :literal
-        ->(v) { v.is_a?(String) && literal_values.include?(v) }
+        ->(value) { value.is_a?(String) && literal_values.include?(value) }
       when :list
         if element_type && element_type[:type] == :literal
-          ->(v) { v.is_a?(Array) && v.all? { |elem| element_type[:literal_values].include?(elem.to_s) } }
+          ->(value) { value.is_a?(Array) && value.all? { |elem| element_type[:literal_values].include?(elem.to_s) } }
         else
-          ->(v) { v.is_a?(Array) }
+          ->(value) { value.is_a?(Array) }
         end
       when :hash
-        ->(v) { v.is_a?(Hash) }
+        ->(value) { value.is_a?(Hash) }
       else
-        ->(_v) { true }
+        ->(_value) { true }
       end
     end
   end