rapitapir 0.1.1 → 2.0.0

data/lib/rapitapir/ai/mcp.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# RapiTapir::AI::MCP
+#
+# Provides Model Context Protocol (MCP) export capabilities for RapiTapir endpoints.
+#
+# Usage:
+#   - Use `.mcp_export` in endpoint DSL to mark endpoints for MCP context export.
+#   - Use MCPExporter to generate MCP-compatible JSON for all marked endpoints.
+
+module RapiTapir
+  module AI
+    module MCP
+      # Collects and serializes endpoint context for LLM/agent consumption
+      class Exporter
+        def initialize(endpoints)
+          @endpoints = endpoints
+        end
+
+        # Returns a hash representing the MCP context for all marked endpoints
+        def as_mcp_context
+          mcp_endpoints = @endpoints.select(&:mcp_export?)
+
+          context = {
+            service: {
+              name: 'RapiTapir API',
+              version: '1.0.0',
+              description: 'RapiTapir API with exported endpoints for MCP context'
+            },
+            endpoints: [],
+            schemas: extract_all_schemas(mcp_endpoints),
+            metadata: {
+              generated_at: Time.now.iso8601,
+              generator: 'RapiTapir MCP Exporter',
+              mcp_version: '1.0'
+            }
+          }
+
+          context[:endpoints] = mcp_endpoints.map do |ep|
+            {
+              name: endpoint_name(ep),
+              method: ep.method&.to_s&.upcase,
+              path: ep.path,
+              summary: ep.metadata[:summary],
+              description: ep.metadata[:description],
+              input_schema: extract_input_schema(ep),
+              output_schema: extract_output_schema(ep),
+              examples: ep.metadata[:examples] || []
+            }
+          end
+
+          context
+        end
+
+        # Test-compatible methods (aliases and wrappers)
+        def export_context
+          as_mcp_context
+        end
+
+        def export_json(pretty: true)
+          context = as_mcp_context
+          if pretty
+            JSON.pretty_generate(context)
+          else
+            JSON.generate(context)
+          end
+        end
+
+        def mcp_endpoints
+          @endpoints.select(&:mcp_export?)
+        end
+
+        private
+
+        def endpoint_name(endpoint)
+          # Generate a readable name from method and path
+          method = endpoint.method&.to_s || 'unknown'
+          path = endpoint.path&.gsub(%r{[{}/]}, '_')&.gsub(/_+/, '_')&.strip || 'unknown'
+          "#{method}_#{path}".downcase
+        end
+
+        def extract_input_schema(endpoint)
+          return {} unless endpoint.inputs
+
+          schema = {}
+          endpoint.inputs.each do |input|
+            next unless input.respond_to?(:name)
+
+            # Handle both old and new input structures
+            required = if input.respond_to?(:required?)
+                         input.required?
+                       elsif input.respond_to?(:options) && input.options
+                         input.options[:required] != false
+                       else
+                         true # default to required
+                       end
+
+            schema[input.name] = {
+              type: input.type,
+              kind: input.kind,
+              required: required
+            }
+          end
+          schema
+        end
+
+        def extract_output_schema(endpoint)
+          return {} unless endpoint.outputs
+
+          schema = {}
+          endpoint.outputs.each do |output|
+            schema[output.kind] = {
+              type: output.type
+            }
+          end
+          schema
+        end
+
+        def extract_all_schemas(endpoints)
+          schemas = {}
+          endpoints.each do |endpoint|
+            input_schema = extract_input_schema(endpoint)
+            output_schema = extract_output_schema(endpoint)
+
+            schemas["#{endpoint_name(endpoint)}_input"] = input_schema unless input_schema.empty?
+
+            schemas["#{endpoint_name(endpoint)}_output"] = output_schema unless output_schema.empty?
+          end
+          schemas
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/ai/rag.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+# RapiTapir::AI::RAG
+#
+# Provides Retrieval-Augmented Generation (RAG) pipeline support for RapiTapir endpoints.
+#
+# Usage:
+#   - Use `.rag_inference(llm:, retrieval:, context_fields:)` in endpoint DSL
+#   - Configure LLM and retrieval backends
+#   - Process user queries with retrieved context
+
+module RapiTapir
+  module AI
+    module RAG
+      # Base class for LLM providers
+      class LLMProvider
+        def initialize(config = {})
+          @config = config
+        end
+
+        def generate(prompt, context = {})
+          raise NotImplementedError, 'Subclasses must implement #generate'
+        end
+      end
+
+      # OpenAI LLM provider
+      class OpenAIProvider < LLMProvider
+        def initialize(config = {})
+          super
+          @api_key = config[:api_key] || ENV.fetch('OPENAI_API_KEY', nil)
+          @model = config[:model] || 'gpt-3.5-turbo'
+          @base_url = config[:base_url] || 'https://api.openai.com/v1'
+        end
+
+        def generate(prompt, context = {})
+          # Mock implementation for now - replace with actual OpenAI API call
+          if @api_key && @api_key != 'mock'
+            make_openai_request(prompt, context)
+          else
+            mock_response(prompt, context)
+          end
+        end
+
+        private
+
+        def make_openai_request(prompt, context)
+          # This would make actual HTTP request to OpenAI
+          # For now, return a mock response
+          mock_response(prompt, context)
+        end
+
+        def mock_response(prompt, context)
+          "AI Response: Based on the query '#{prompt}' and context #{context.keys.join(', ')}, here is a generated response."
+        end
+      end
+
+      # Base class for retrieval backends
+      class RetrievalBackend
+        def initialize(config = {})
+          @config = config
+        end
+
+        def retrieve(query, context_fields = [])
+          raise NotImplementedError, 'Subclasses must implement #retrieve'
+        end
+      end
+
+      # PostgreSQL retrieval backend
+      class PostgresBackend < RetrievalBackend
+        def initialize(config = {})
+          super
+          @connection_config = config[:connection] || {}
+          @table = config[:table] || 'documents'
+          @search_column = config[:search_column] || 'content'
+        end
+
+        def retrieve(query, context_fields = [])
+          # Mock implementation - replace with actual DB query
+          mock_retrieval(query, context_fields)
+        end
+
+        private
+
+        def mock_retrieval(query, context_fields)
+          [
+            {
+              content: "Sample document content related to: #{query}",
+              metadata: context_fields.to_h { |field| [field, "sample_#{field}_value"] },
+              score: 0.85
+            },
+            {
+              content: "Another relevant document for: #{query}",
+              metadata: context_fields.to_h { |field| [field, "another_#{field}_value"] },
+              score: 0.72
+            }
+          ]
+        end
+      end
+
+      # Memory/hash-based retrieval backend for testing
+      class MemoryBackend < RetrievalBackend
+        def initialize(config = {})
+          super
+          @documents = config[:documents] || []
+        end
+
+        def retrieve(query, _context_fields = [])
+          # Simple text matching for demo purposes
+          matching_docs = @documents.select do |doc|
+            doc[:content]&.downcase&.include?(query.downcase)
+          end
+
+          matching_docs.map.with_index do |doc, index|
+            {
+              content: doc[:content],
+              metadata: doc[:metadata] || {},
+              score: 1.0 - (index * 0.1) # Simple scoring
+            }
+          end
+        end
+      end
+
+      # RAG Pipeline orchestrator
+      class Pipeline
+        attr_reader :llm_provider, :retrieval_backend
+
+        def initialize(llm:, retrieval:, config: {})
+          @llm_provider = create_llm_provider(llm, config[:llm] || {})
+          @retrieval_backend = create_retrieval_backend(retrieval, config[:retrieval] || {})
+          @config = config
+        end
+
+        def process(query, context_fields: [], user_context: {})
+          # Step 1: Retrieve relevant documents
+          retrieved_docs = @retrieval_backend.retrieve(query, context_fields)
+
+          # Step 2: Build context for LLM
+          llm_context = build_llm_context(retrieved_docs, user_context, context_fields)
+
+          # Step 3: Generate response using LLM
+          prompt = build_prompt(query, llm_context)
+          response = @llm_provider.generate(prompt, llm_context)
+
+          # Step 4: Return structured result
+          {
+            answer: response,
+            sources: retrieved_docs,
+            context: llm_context,
+            query: query
+          }
+        end
+
+        private
+
+        def create_llm_provider(type, config)
+          case type.to_sym
+          when :openai
+            OpenAIProvider.new(config)
+          else
+            raise ArgumentError, "Unknown LLM provider: #{type}"
+          end
+        end
+
+        def create_retrieval_backend(type, config)
+          case type.to_sym
+          when :postgres, :postgresql
+            PostgresBackend.new(config)
+          when :memory
+            MemoryBackend.new(config)
+          else
+            raise ArgumentError, "Unknown retrieval backend: #{type}"
+          end
+        end
+
+        def build_llm_context(retrieved_docs, user_context, context_fields)
+          {
+            retrieved_documents: retrieved_docs,
+            user_context: user_context,
+            context_fields: context_fields,
+            document_count: retrieved_docs.length
+          }
+        end
+
+        def build_prompt(query, context)
+          documents_text = context[:retrieved_documents]
+                           .map { |doc| doc[:content] }
+                           .join("\n\n")
+
+          <<~PROMPT
+            You are an AI assistant that answers questions based on the provided context.
+
+            Context Documents:
+            #{documents_text}
+
+            User Question: #{query}
+
+            Please provide a helpful and accurate answer based on the context provided.
+            If the context doesn't contain enough information, say so clearly.
+          PROMPT
+        end
+      end
+
+      # Rack middleware for handling RAG inference requests
+      class Middleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          endpoint = env['rapitapir.endpoint']
+
+          # Pass through if not a RAG endpoint
+          return @app.call(env) unless endpoint&.rag_inference?
+
+          # Process RAG request
+          process_rag_request(env, endpoint)
+        end
+
+        private
+
+        def process_rag_request(env, endpoint)
+          # Parse request body
+          request_body = env['rack.input']&.read
+          env['rack.input']&.rewind if env['rack.input'].respond_to?(:rewind)
+
+          query_data = request_body ? JSON.parse(request_body) : {}
+          question = query_data['question'] || query_data[:question]
+
+          # Get RAG config from endpoint
+          rag_config = endpoint.metadata[:rag_inference]
+
+          # Create RAG pipeline
+          pipeline = Pipeline.new(
+            llm: rag_config[:llm],
+            retrieval: rag_config[:retrieval],
+            config: rag_config[:config] || {}
+          )
+
+          # Process the query
+          result = pipeline.process(
+            question,
+            context_fields: rag_config[:context_fields] || [],
+            user_context: extract_user_context(env)
+          )
+
+          # Return JSON response
+          response_body = JSON.generate(
+            answer: result[:answer],
+            sources: result[:sources],
+            metadata: {
+              query: result[:query],
+              context_fields: result[:context][:context_fields],
+              document_count: result[:context][:document_count]
+            }
+          )
+
+          [
+            200,
+            { 'Content-Type' => 'application/json' },
+            [response_body]
+          ]
+        rescue StandardError => e
+          error_response = JSON.generate(
+            error: 'RAG processing failed',
+            message: e.message
+          )
+
+          [
+            500,
+            { 'Content-Type' => 'application/json' },
+            [error_response]
+          ]
+        end
+
+        def extract_user_context(env)
+          # Extract relevant context from request environment
+          {
+            user_agent: env['HTTP_USER_AGENT'],
+            remote_ip: env['REMOTE_ADDR'],
+            method: env['REQUEST_METHOD'],
+            path: env['PATH_INFO']
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/ai/rag_middleware.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative 'rag'
+
+module RapiTapir
+  module AI
+    module RAG
+      # Middleware for handling RAG-enabled endpoints
+      # Integrates with RapiTapir server adapters to process RAG requests
+      class Middleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          # Check if this is a RAG-enabled endpoint
+          endpoint = env['rapitapir.endpoint']
+          if endpoint&.rag_inference?
+            handle_rag_request(env, endpoint)
+          else
+            @app.call(env)
+          end
+        end
+
+        private
+
+        def handle_rag_request(env, endpoint)
+          # Extract request data
+          request_data = extract_request_data(env)
+
+          # Get the query from the request (assuming it's in the body)
+          query = request_data[:question] || request_data[:query] || request_data.values.first
+
+          # Create RAG pipeline from endpoint configuration
+          rag_config = endpoint.rag_config
+          pipeline = create_rag_pipeline(rag_config)
+
+          # Process the query through RAG pipeline
+          result = pipeline.process(
+            query,
+            context_fields: rag_config[:context_fields],
+            user_context: extract_user_context(env, rag_config[:context_fields])
+          )
+
+          # Return RAG response
+          build_rag_response(result)
+        rescue StandardError => e
+          build_error_response(e)
+        end
+
+        def extract_request_data(env)
+          # Simple JSON parsing - in real implementation would be more robust
+          if env['CONTENT_TYPE']&.include?('application/json')
+            body = env['rack.input']&.read || '{}'
+            env['rack.input']&.rewind
+            JSON.parse(body, symbolize_names: true)
+          else
+            {}
+          end
+        rescue JSON::ParserError
+          {}
+        end
+
+        def extract_user_context(env, context_fields)
+          # Extract user context from headers, session, etc.
+          context = {}
+
+          context_fields.each do |field|
+            case field
+            when :user_id
+              context[:user_id] = env['HTTP_X_USER_ID'] || env['HTTP_AUTHORIZATION']&.split&.last
+            when :session_id
+              context[:session_id] = env['HTTP_X_SESSION_ID']
+            when :tenant_id
+              context[:tenant_id] = env['HTTP_X_TENANT_ID']
+            end
+          end
+
+          context
+        end
+
+        def create_rag_pipeline(config)
+          Pipeline.new(
+            llm: config[:llm],
+            retrieval: config[:retrieval],
+            config: config[:config] || {}
+          )
+        end
+
+        def build_rag_response(result)
+          response_body = {
+            answer: result[:answer],
+            sources: result[:sources],
+            metadata: {
+              query: result[:query],
+              source_count: result[:sources].length,
+              timestamp: Time.now.iso8601
+            }
+          }
+
+          [
+            200,
+            { 'Content-Type' => 'application/json' },
+            [JSON.generate(response_body)]
+          ]
+        end
+
+        def build_error_response(error)
+          response_body = {
+            error: 'RAG processing failed',
+            message: error.message,
+            timestamp: Time.now.iso8601
+          }
+
+          [
+            500,
+            { 'Content-Type' => 'application/json' },
+            [JSON.generate(response_body)]
+          ]
+        end
+      end
+
+      # Helper for mounting RAG endpoints in server adapters
+      class EndpointHandler
+        def self.handle(endpoint, request_data, user_context = {})
+          return nil unless endpoint.rag_inference?
+
+          rag_config = endpoint.rag_config
+          pipeline = Pipeline.new(
+            llm: rag_config[:llm],
+            retrieval: rag_config[:retrieval],
+            config: rag_config[:config] || {}
+          )
+
+          # Extract query from request data
+          query = request_data[:question] || request_data[:query] || request_data.to_s
+
+          pipeline.process(
+            query,
+            context_fields: rag_config[:context_fields],
+            user_context: user_context
+          )
+        end
+      end
+    end
+  end
+end