desiru 0.1.0

data/lib/desiru/cache.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Desiru
+  # Thread-safe in-memory cache with TTL support and LRU eviction
+  class Cache
+    Entry = Struct.new(:value, :expires_at, :accessed_at, keyword_init: true)
+
+    def initialize(max_size: 1000, cleanup_interval: 300)
+      @store = {}
+      @mutex = Mutex.new
+      @max_size = max_size
+      @cleanup_interval = cleanup_interval
+      @last_cleanup = Time.now
+    end
+
+    # Get a value from cache or set it using the provided block
+    def get_or_set(key, ttl: 3600)
+      @mutex.synchronize do
+        cleanup_if_needed
+
+        if (entry = @store[key])
+          if entry.expires_at > Time.now
+            entry.accessed_at = Time.now
+            return entry.value
+          else
+            @store.delete(key)
+          end
+        end
+
+        # Evict LRU if at capacity
+        evict_lru if @store.size >= @max_size
+
+        value = yield
+        @store[key] = Entry.new(
+          value: value,
+          expires_at: Time.now + ttl,
+          accessed_at: Time.now
+        )
+        value
+      end
+    end
+
+    # Get a value from cache without setting
+    def get(key)
+      @mutex.synchronize do
+        if (entry = @store[key])
+          if entry.expires_at > Time.now
+            entry.accessed_at = Time.now
+            entry.value
+          else
+            @store.delete(key)
+            nil
+          end
+        end
+      end
+    end
+
+    # Set a value in cache
+    def set(key, value, ttl: 3600)
+      @mutex.synchronize do
+        cleanup_if_needed
+        evict_lru if @store.size >= @max_size && !@store.key?(key)
+
+        @store[key] = Entry.new(
+          value: value,
+          expires_at: Time.now + ttl,
+          accessed_at: Time.now
+        )
+        value
+      end
+    end
+
+    # Delete a key from cache
+    def delete(key)
+      @mutex.synchronize do
+        @store.delete(key)
+      end
+    end
+
+    # Clear all entries
+    def clear
+      @mutex.synchronize do
+        @store.clear
+      end
+    end
+
+    # Get the current size
+    def size
+      @mutex.synchronize do
+        @store.size
+      end
+    end
+
+    # Manually trigger cleanup of expired entries
+    def cleanup_expired
+      @mutex.synchronize do
+        @store.delete_if { |_, entry| entry.expires_at <= Time.now }
+      end
+    end
+
+    private
+
+    def cleanup_if_needed
+      return unless Time.now - @last_cleanup > @cleanup_interval
+
+      @store.delete_if { |_, entry| entry.expires_at <= Time.now }
+      @last_cleanup = Time.now
+    end
+
+    def evict_lru
+      # Find least recently used entry
+      lru_key = @store.min_by { |_, entry| entry.accessed_at }&.first
+      @store.delete(lru_key) if lru_key
+    end
+  end
+end

data/lib/desiru/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Desiru
+  # Global configuration for Desiru
+  # Follows singleton pattern for service-oriented design
+  class Configuration
+    attr_accessor :default_model, :cache_enabled, :cache_ttl, :max_retries,
+                  :retry_delay, :logger, :module_registry, :model_timeout,
+                  :redis_url
+
+    def initialize
+      @default_model = nil
+      @cache_enabled = true
+      @cache_ttl = 3600 # 1 hour
+      @max_retries = 3
+      @retry_delay = 1
+      @logger = default_logger
+      @module_registry = Desiru::Registry.instance
+      @model_timeout = 30
+      @redis_url = nil # Defaults to REDIS_URL env var if not set
+    end
+
+    def validate!
+      raise ConfigurationError, 'default_model must be set' unless default_model
+      raise ConfigurationError, 'default_model must respond to :complete' unless default_model.respond_to?(:complete)
+    end
+
+    private
+
+    def default_logger
+      require 'logger'
+      Logger.new($stdout).tap do |logger|
+        logger.level = Logger::INFO
+        logger.formatter = proc do |severity, datetime, _progname, msg|
+          "[Desiru] #{datetime}: #{severity} -- #{msg}\n"
+        end
+      end
+    end
+  end
+end

data/lib/desiru/field.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+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
+
+    alias optional? optional
+
+    def initialize(name, type = :string, description: nil, optional: false, default: nil, validator: nil,
+                   literal_values: nil, element_type: nil)
+      @name = name.to_sym
+      @type = normalize_type(type)
+      @description = description
+      @optional = optional
+      @default = default
+      @literal_values = literal_values&.map(&:freeze)&.freeze if literal_values
+      @element_type = element_type
+      @validator = validator || default_validator
+    end
+
+    def validate(value)
+      return true if optional && value.nil?
+      return true if value.nil? && !default.nil?
+
+      raise ValidationError, validation_error_message(value) unless validator.call(value)
+
+      true
+    end
+
+    def coerce(value)
+      return default if value.nil? && !default.nil?
+      return value if value.nil? && optional
+
+      case type
+      when :string
+        value.to_s
+      when :int, :integer
+        value.to_i
+      when :float
+        value.to_f
+      when :bool, :boolean
+        case value.to_s.downcase
+        when 'true', 'yes', '1', 't'
+          true
+        when 'false', 'no', '0', 'f'
+          false
+        else
+          !!value
+        end
+      when :literal
+        # For literal types, ensure the value is a string and matches one of the allowed values
+        coerced = value.to_s
+        unless literal_values.include?(coerced)
+          raise ValidationError, "Value '#{coerced}' is not one of allowed values: #{literal_values.join(', ')}"
+        end
+
+        coerced
+      when :list, :array
+        array_value = Array(value)
+        # If we have an element type, coerce each element
+        if element_type && element_type[:type] == :literal
+          array_value.map do |elem|
+            coerced_elem = elem.to_s
+            unless element_type[:literal_values].include?(coerced_elem)
+              raise ValidationError,
+                    "Array element '#{coerced_elem}' is not one of allowed values: #{element_type[:literal_values].join(', ')}"
+            end
+
+            coerced_elem
+          end
+        else
+          array_value
+        end
+      when :hash, :dict
+        value.is_a?(Hash) ? value : {}
+      else
+        value
+      end
+    end
+
+    def to_h
+      result = {
+        name: name,
+        type: type,
+        description: description,
+        optional: optional,
+        default: default
+      }
+      result[:literal_values] = literal_values if literal_values
+      result[:element_type] = element_type if element_type
+      result.compact
+    end
+
+    private
+
+    def validation_error_message(value)
+      case type
+      when :string
+        "#{name} must be a string, got #{value.class}"
+      when :int, :integer
+        "#{name} must be an integer, got #{value.class}"
+      when :float
+        "#{name} must be a float, got #{value.class}"
+      when :bool, :boolean
+        "#{name} must be a boolean (true/false), got #{value.class}"
+      when :list, :array
+        if element_type && element_type[:type] == :literal
+          "#{name} must be an array of literal values: #{element_type[:literal_values].join(', ')}"
+        else
+          "#{name} must be a list, got #{value.class}"
+        end
+      when :literal
+        "#{name} must be one of: #{literal_values.join(', ')}"
+      when :hash, :dict
+        "#{name} must be a hash, got #{value.class}"
+      else
+        "#{name} validation failed for value: #{value}"
+      end
+    end
+
+    def normalize_type(type)
+      # If type is already a symbol, return it
+      return type if type.is_a?(Symbol)
+
+      case type.to_s.downcase
+      when 'str', 'string'
+        :string
+      when 'int', 'integer'
+        :int
+      when 'float', 'number', 'double'
+        :float
+      when 'bool', 'boolean'
+        :bool
+      when 'list', 'array'
+        :list
+      when 'hash', 'dict', 'dictionary'
+        :hash
+      when 'literal'
+        :literal
+      else
+        type.to_sym
+      end
+    end
+
+    def default_validator
+      case type
+      when :string
+        ->(v) { v.is_a?(String) }
+      when :int
+        ->(v) { v.is_a?(Integer) }
+      when :float
+        ->(v) { v.is_a?(Float) || v.is_a?(Integer) }
+      when :bool
+        ->(v) { v.is_a?(TrueClass) || v.is_a?(FalseClass) }
+      when :literal
+        ->(v) { v.is_a?(String) && literal_values.include?(v) }
+      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) } }
+        else
+          ->(v) { v.is_a?(Array) }
+        end
+      when :hash
+        ->(v) { v.is_a?(Hash) }
+      else
+        ->(_v) { true }
+      end
+    end
+  end
+end

data/lib/desiru/graphql/data_loader.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Desiru
+  module GraphQL
+    # DataLoader pattern implementation for batching Desiru module calls
+    # Prevents N+1 query problems when multiple GraphQL fields request similar data
+    class DataLoader
+      def initialize
+        @loaders = {}
+        @results_cache = {}
+        @pending_loads = Hash.new { |h, k| h[k] = [] }
+      end
+
+      # Get or create a loader for a specific module
+      def for(module_class, **options)
+        key = loader_key(module_class, options)
+        @loaders[key] ||= BatchLoader.new(module_class, **options)
+      end
+
+      # Execute all pending loads in batch
+      def perform_loads
+        @pending_loads.each do |loader_key, batch|
+          next if batch.empty?
+
+          loader = @loaders[loader_key]
+          results = loader.load_batch(batch.map(&:first))
+
+          batch.each_with_index do |(_inputs, promise), idx|
+            promise.fulfill(results[idx])
+          end
+        end
+
+        @pending_loads.clear
+      end
+
+      # Clear all caches
+      def clear!
+        @results_cache.clear
+        @pending_loads.clear
+        @loaders.values.each(&:clear_cache!)
+      end
+
+      private
+
+      def loader_key(module_class, options)
+        "#{module_class.name}:#{options.hash}"
+      end
+
+      # Individual batch loader for a specific module
+      class BatchLoader
+        attr_reader :module_class, :batch_size, :cache
+
+        def initialize(module_class, batch_size: 100, cache: true)
+          @module_class = module_class
+          @batch_size = batch_size
+          @cache = cache
+          @cache_store = {} if cache
+        end
+
+        # Load a batch of inputs
+        def load_batch(inputs_array)
+          return load_from_cache(inputs_array) if cache && all_cached?(inputs_array)
+
+          # Group inputs by signature to optimize processing
+          grouped = group_by_signature(inputs_array)
+          results = []
+
+          grouped.each do |_signature_key, inputs_group|
+            module_instance = create_module_instance(inputs_group.first)
+
+            # Process in chunks to respect batch_size
+            inputs_group.each_slice(batch_size) do |chunk|
+              chunk_results = process_chunk(module_instance, chunk)
+              results.concat(chunk_results)
+
+              # Cache results if enabled
+              cache_results(chunk, chunk_results) if cache
+            end
+          end
+
+          results
+        end
+
+        # Load a single input (returns a promise for lazy evaluation)
+        def load(inputs)
+          Promise.new do |promise|
+            if cache && @cache_store.key?(cache_key(inputs))
+              promise.fulfill(@cache_store[cache_key(inputs)])
+            else
+              # Queue for batch loading
+              queue_for_loading(inputs, promise)
+            end
+          end
+        end
+
+        def clear_cache!
+          @cache_store.clear if cache
+        end
+
+        private
+
+        def all_cached?(inputs_array)
+          inputs_array.all? { |inputs| @cache_store.key?(cache_key(inputs)) }
+        end
+
+        def load_from_cache(inputs_array)
+          inputs_array.map { |inputs| @cache_store[cache_key(inputs)] }
+        end
+
+        def cache_results(inputs_array, results)
+          inputs_array.each_with_index do |inputs, idx|
+            @cache_store[cache_key(inputs)] = results[idx]
+          end
+        end
+
+        def cache_key(inputs)
+          inputs.sort.to_h.hash
+        end
+
+        def group_by_signature(inputs_array)
+          inputs_array.group_by do |inputs|
+            # Group by input keys to process similar queries together
+            inputs.keys.sort.join(':')
+          end
+        end
+
+        def create_module_instance(sample_inputs)
+          # Infer signature from inputs
+          signature = infer_signature(sample_inputs)
+          module_class.new(signature)
+        end
+
+        def infer_signature(inputs)
+          # Create a signature based on input structure
+          input_fields = inputs.map { |k, v| "#{k}: #{type_for_value(v)}" }.join(', ')
+          output_fields = "result: hash" # Default output, can be customized
+          "#{input_fields} -> #{output_fields}"
+        end
+
+        def type_for_value(value)
+          case value
+          when String then 'string'
+          when Integer then 'int'
+          when Float then 'float'
+          when TrueClass, FalseClass then 'bool'
+          when Array then 'list'
+          when Hash then 'hash'
+          else 'string'
+          end
+        end
+
+        def process_chunk(module_instance, chunk)
+          if module_instance.respond_to?(:batch_forward)
+            # If module supports batch processing
+            module_instance.batch_forward(chunk)
+          else
+            # Fall back to individual processing
+            chunk.map { |inputs| module_instance.call(inputs) }
+          end
+        end
+
+        def queue_for_loading(inputs, promise)
+          # This would integrate with the parent DataLoader's pending loads
+          # For now, process immediately
+          result = module_class.new(infer_signature(inputs)).call(inputs)
+          promise.fulfill(result)
+          @cache_store[cache_key(inputs)] = result if cache
+        end
+      end
+
+      # Promise implementation for lazy loading
+      class Promise
+        def initialize(&block)
+          @fulfilled = false
+          @value = nil
+          @callbacks = []
+          block.call(self) if block
+        end
+
+        def fulfill(value)
+          return if @fulfilled
+
+          @value = value
+          @fulfilled = true
+          @callbacks.each { |cb| cb.call(value) }
+          @callbacks.clear
+        end
+
+        def then(&block)
+          if @fulfilled
+            block.call(@value)
+          else
+            @callbacks << block
+          end
+          self
+        end
+
+        def value
+          raise "Promise not yet fulfilled" unless @fulfilled
+
+          @value
+        end
+
+        def fulfilled?
+          @fulfilled
+        end
+      end
+    end
+  end
+end

data/lib/desiru/graphql/executor.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'graphql'
+
+module Desiru
+  module GraphQL
+    # Custom GraphQL executor with batch loading support
+    class Executor
+      attr_reader :schema, :data_loader
+
+      def initialize(schema, data_loader: nil)
+        @schema = schema
+        @data_loader = data_loader || DataLoader.new
+      end
+
+      # Execute a GraphQL query with batch loading
+      def execute(query_string, variables: {}, context: {}, operation_name: nil)
+        # Add data loader to context
+        context[:data_loader] = @data_loader
+
+        # Wrap execution with batch loading
+        result = nil
+        batch_execute do
+          result = @schema.execute(
+            query_string,
+            variables: variables,
+            context: context,
+            operation_name: operation_name
+          )
+        end
+
+        result
+      end
+
+      # Execute multiple queries in a single batch
+      def execute_batch(queries)
+        results = []
+
+        batch_execute do
+          queries.each do |query_params|
+            query_params[:context] ||= {}
+            query_params[:context][:data_loader] = @data_loader
+
+            results << @schema.execute(
+              query_params[:query],
+              variables: query_params[:variables] || {},
+              context: query_params[:context],
+              operation_name: query_params[:operation_name]
+            )
+          end
+        end
+
+        results
+      end
+
+      private
+
+      def batch_execute
+        # Start batch loading context
+        @data_loader.clear! if @data_loader.respond_to?(:clear!)
+
+        # Execute the GraphQL queries
+        result = yield
+
+        # Perform all pending batch loads
+        @data_loader.perform_loads if @data_loader.respond_to?(:perform_loads)
+
+        result
+      end
+    end
+
+    # GraphQL field extension for lazy loading
+    class LazyFieldExtension < ::GraphQL::Schema::FieldExtension
+      def resolve(object:, arguments:, context:)
+        result = yield(object, arguments)
+
+        # If result is a promise, handle it appropriately
+        if result.respond_to?(:then) && result.respond_to?(:fulfilled?)
+          if result.fulfilled?
+            result.value
+          else
+            # Create a lazy resolver
+            ::GraphQL::Execution::Lazy.new do
+              result.value
+            end
+          end
+        else
+          result
+        end
+      end
+    end
+
+    # Middleware for automatic batch loading
+    class BatchLoaderMiddleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        # Extract GraphQL context
+        context = env['graphql.context'] || {}
+
+        # Ensure data loader is available
+        context[:data_loader] ||= DataLoader.new
+        env['graphql.context'] = context
+
+        # Execute with batch loading
+        @app.call(env)
+      ensure
+        # Clean up after request
+        context[:data_loader]&.clear!
+      end
+    end
+  end
+end