desiru 0.1.0 → 0.2.0

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)

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