rapitapir 0.1.1 → 2.0.0

data/lib/rapitapir/auth/oauth2.rb

@@ -11,20 +11,20 @@ module RapiTapir
       # Based on the Auth0 Sinatra integration patterns
       class Auth0Scheme < Schemes::Base
         attr_reader :domain, :audience, :algorithm, :jwks_cache_ttl
-        
+
         def jwks_url
           "https://#{@domain}/.well-known/jwks.json"
         end
 
         def initialize(name = :oauth2_auth0, config = {})
-          super(name, config)
-          
+          super
+
           @domain = config[:domain] || raise(ArgumentError, 'Auth0 domain is required')
           @audience = config[:audience] || raise(ArgumentError, 'Auth0 audience is required')
           @algorithm = config[:algorithm] || 'RS256'
           @jwks_cache_ttl = config[:jwks_cache_ttl] || 300 # 5 minutes
           @realm = config[:realm] || 'API'
-          
+
           # Cache for JWKS to avoid frequent requests
           @jwks_cache = nil
           @jwks_cache_time = nil
@@ -35,13 +35,9 @@ module RapiTapir
           return nil unless auth_header
 
           token = extract_bearer_token(auth_header)
-          if token.nil?
-            raise AuthenticationError, "Invalid authorization header format"
-          end
-          
-          if token.strip.empty?
-            raise AuthenticationError, "Token cannot be empty"
-          end
+          raise AuthenticationError, 'Invalid authorization header format' if token.nil?
+
+          raise AuthenticationError, 'Token cannot be empty' if token.strip.empty?
 
           begin
             decoded_token = validate_auth0_token(token)
@@ -49,7 +45,7 @@ module RapiTapir
 
             # Extract user info and scopes from the token
             payload = decoded_token.first
-            
+
             create_context(
               user: extract_user_from_token(payload),
               scopes: extract_scopes_from_token(payload),
@@ -88,9 +84,9 @@ module RapiTapir
 
         def validate_auth0_token(token)
           require 'jwt' # Ensure JWT gem is available
-          
+
           jwks = fetch_jwks
-          
+
           JWT.decode(
             token,
             nil,
@@ -108,37 +104,33 @@ module RapiTapir
 
         def fetch_jwks
           # Return cached JWKS if still valid
-          if @jwks_cache && @jwks_cache_time && (Time.now - @jwks_cache_time) < @jwks_cache_ttl
-            return @jwks_cache
-          end
+          return @jwks_cache if @jwks_cache && @jwks_cache_time && (Time.now - @jwks_cache_time) < @jwks_cache_ttl
 
           # Fetch fresh JWKS from Auth0
           jwks_response = get_jwks_from_auth0
-          
-          unless jwks_response.is_a?(Net::HTTPSuccess)
-            raise AuthenticationError, 'Unable to fetch JWKS from Auth0'
-          end
+
+          raise AuthenticationError, 'Unable to fetch JWKS from Auth0' unless jwks_response.is_a?(Net::HTTPSuccess)
 
           jwks_data = JSON.parse(jwks_response.body)
-          
+
           # Cache the JWKS
           @jwks_cache = { keys: jwks_data['keys'] }
           @jwks_cache_time = Time.now
-          
+
           @jwks_cache
         end
 
         def get_jwks_from_auth0
           jwks_uri = URI("#{base_domain_url}/.well-known/jwks.json")
-          
+
           http = Net::HTTP.new(jwks_uri.host, jwks_uri.port)
           http.use_ssl = true
           http.verify_mode = OpenSSL::SSL::VERIFY_PEER
           http.read_timeout = 10
-          
+
           request = Net::HTTP::Get.new(jwks_uri.request_uri)
           request['User-Agent'] = 'RapiTapir OAuth2 Client'
-          
+
           http.request(request)
         end
 
@@ -166,17 +158,17 @@ module RapiTapir
           scope_string = payload['scope']
           return [] unless scope_string
 
-          scope_string.split(' ')
+          scope_string.split
         end
       end
 
       # Generic OAuth2 scheme with token introspection support
       class GenericScheme < Schemes::Base
         attr_reader :introspection_endpoint, :client_id, :client_secret, :token_cache_ttl
-        
+
         def initialize(name = :oauth2, config = {})
-          super(name, config)
-          
+          super
+
           @introspection_endpoint = config[:introspection_endpoint]
           @client_id = config[:client_id]
           @client_secret = config[:client_secret]
@@ -184,7 +176,7 @@ module RapiTapir
           @realm = config[:realm] || 'API'
           @cache_tokens = config.fetch(:cache_tokens, true)
           @token_cache_ttl = config[:token_cache_ttl] || 300 # 5 minutes
-          
+
           # Token cache to avoid repeated introspection calls
           @token_cache = {} if @cache_tokens
         end
@@ -198,11 +190,9 @@ module RapiTapir
 
           begin
             token_info = validate_oauth2_token(token)
-            
+
             # Check if token is active
-            unless token_info && token_info[:active]
-              raise AuthenticationError, "Token is not active"
-            end
+            raise AuthenticationError, 'Token is not active' unless token_info && token_info[:active]
 
             create_context(
               user: token_info[:user],
@@ -242,19 +232,17 @@ module RapiTapir
           # Check cache first
           if @cache_tokens && @token_cache
             cached = @token_cache[token]
-            if cached && (Time.now - cached[:cached_at]) < @token_cache_ttl
-              return cached[:data]
-            end
+            return cached[:data] if cached && (Time.now - cached[:cached_at]) < @token_cache_ttl
           end
 
           # Validate token
           token_info = if @introspection_endpoint
-                        introspect_token_via_endpoint(token)
-                      elsif @token_validator
-                        @token_validator.call(token)
-                      else
-                        default_token_validation(token)
-                      end
+                         introspect_token_via_endpoint(token)
+                       elsif @token_validator
+                         @token_validator.call(token)
+                       else
+                         default_token_validation(token)
+                       end
 
           # Cache the result
           if @cache_tokens && @token_cache && token_info
@@ -269,40 +257,38 @@ module RapiTapir
 
         def introspect_token_via_endpoint(token)
           uri = URI(@introspection_endpoint)
-          
+
           http = Net::HTTP.new(uri.host, uri.port)
           http.use_ssl = (uri.scheme == 'https')
-          
+
           request = Net::HTTP::Post.new(uri.request_uri)
           request['Content-Type'] = 'application/x-www-form-urlencoded'
           request['Accept'] = 'application/json'
-          
+
           # Add client authentication
           if @client_id && @client_secret
             credentials = Base64.strict_encode64("#{@client_id}:#{@client_secret}")
             request['Authorization'] = "Basic #{credentials}"
           end
-          
+
           # Set form data
           request.set_form_data(
             'token' => token,
             'token_type_hint' => 'access_token'
           )
-          
+
           response = http.request(request)
-          
-          unless response.is_a?(Net::HTTPSuccess)
-            raise AuthenticationError, "Token introspection failed: #{response.code} #{response.message}"
-          end
-          
+
+          raise AuthenticationError, "Token introspection failed: #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
           begin
             introspection_data = JSON.parse(response.body)
           rescue JSON::ParserError => e
             raise AuthenticationError, "Invalid introspection response: #{e.message}"
           end
-          
+
           return { active: false } unless introspection_data['active']
-          
+
           {
             active: true,
             user: extract_user_from_introspection(introspection_data),
@@ -324,7 +310,7 @@ module RapiTapir
 
         def extract_scopes_from_introspection(data)
           if data['scope'].is_a?(String)
-            data['scope'].split(' ')
+            data['scope'].split
           elsif data['scope'].is_a?(Array)
             data['scope']
           else

data/lib/rapitapir/cli/command.rb

@@ -2,6 +2,7 @@
 
 require 'optparse'
 require 'fileutils'
+require 'json'
 
 module RapiTapir
   module CLI
@@ -38,10 +39,14 @@ module RapiTapir
         case command
         when 'generate'
           run_generate(@args)
+        when 'export'
+          run_export(@args)
         when 'serve'
           run_serve(@args)
         when 'validate'
           run_validate(@args)
+        when 'ai'
+          run_ai(@args)
         when 'version'
           puts "RapiTapir version #{RapiTapir::VERSION}"
         when 'help', nil
@@ -153,7 +158,7 @@ module RapiTapir
         type = args.shift
         unless type
           puts 'Error: Generate command requires a type'
-          puts 'Available types: openapi, client, docs'
+          puts 'Available types: openapi, client, docs, mcp'
           exit 1
         end
 
@@ -166,9 +171,11 @@ module RapiTapir
         when 'docs'
           docs_type = args.shift || 'html'
           generate_docs(docs_type)
+        when 'mcp'
+          generate_mcp
         else
           puts "Error: Unknown generation type: #{type}"
-          puts 'Available types: openapi, client, docs'
+          puts 'Available types: openapi, client, docs, mcp'
           exit 1
         end
       end
@@ -206,6 +213,24 @@ module RapiTapir
         end
       end
 
+      def run_export(args)
+        type = args.shift
+        unless type
+          puts 'Error: Export command requires a type'
+          puts 'Available types: mcp'
+          exit 1
+        end
+
+        case type
+        when 'mcp'
+          export_mcp
+        else
+          puts "Error: Unknown export type: #{type}"
+          puts 'Available types: mcp'
+          exit 1
+        end
+      end
+
       def generate_openapi
         validate_openapi_options
 
@@ -412,6 +437,33 @@ module RapiTapir
         end
       end
 
+      def generate_mcp
+        validate_mcp_options
+
+        endpoints = load_endpoints(@options[:input])
+        require_relative '../ai/mcp'
+        exporter = RapiTapir::AI::MCP::Exporter.new(endpoints)
+        content = JSON.pretty_generate(exporter.as_mcp_context)
+        save_mcp_output(content)
+      end
+
+      def export_mcp
+        generate_mcp
+      end
+
+      def validate_mcp_options
+        return if @options[:input]
+
+        puts 'Error: --endpoints is required'
+        exit 1
+      end
+
+      def save_mcp_output(content)
+        output_file = @options[:output] || 'mcp-context.json'
+        File.write(output_file, content)
+        puts "MCP context exported to #{output_file}"
+      end
+
       def load_endpoints(file_path)
         raise "Input file not found: #{file_path}" unless File.exist?(file_path)
 
@@ -530,6 +582,314 @@ module RapiTapir
 
         endpoints
       end
+
+      def run_ai(args)
+        subcommand = args.shift
+
+        case subcommand
+        when 'rag'
+          run_ai_rag(args)
+        when 'query'
+          run_ai_query(args)
+        when 'llm'
+          run_ai_llm(args)
+        when 'help', nil
+          puts ai_help
+        else
+          puts "Unknown AI subcommand: #{subcommand}"
+          puts ai_help
+          exit 1
+        end
+      end
+
+      def run_ai_rag(args)
+        command = args.shift
+
+        case command
+        when 'test'
+          run_rag_test(args)
+        when 'setup'
+          run_rag_setup(args)
+        else
+          puts 'RAG subcommands: test, setup'
+          exit 1
+        end
+      end
+
+      def run_rag_test(args)
+        unless @options[:input]
+          puts 'Error: --endpoints is required'
+          exit 1
+        end
+
+        endpoints = load_endpoints(@options[:input])
+
+        # Find RAG-enabled endpoints
+        rag_endpoints = endpoints.select(&:rag_inference?)
+
+        if rag_endpoints.empty?
+          puts "No RAG-enabled endpoints found in #{@options[:input]}"
+          puts 'Add .rag_inference to your endpoints to enable RAG capabilities'
+          exit 1
+        end
+
+        require_relative '../ai/rag'
+
+        puts 'Testing RAG functionality...'
+        puts "Found #{rag_endpoints.size} RAG-enabled endpoint(s):"
+
+        rag_endpoints.each do |endpoint|
+          puts "  #{endpoint.method} #{endpoint.path}"
+          config = endpoint.rag_config
+
+          # Create pipeline and test
+          pipeline = RapiTapir::AI::RAG::Pipeline.new(
+            llm: config[:llm] || :openai,
+            retrieval: config[:retrieval] || :memory,
+            config: config[:config] || {}
+          )
+
+          test_query = args.first || 'What can this API do?'
+          result = pipeline.process(test_query)
+
+          puts "    Query: #{test_query}"
+          puts "    Answer: #{result[:answer][0..100]}#{'...' if result[:answer].length > 100}"
+          puts "    Sources: #{result[:sources].size} document(s)"
+          puts
+        end
+      end
+
+      def run_rag_setup(_args)
+        puts 'Setting up RAG configuration...'
+
+        config_template = {
+          rag: {
+            llm: {
+              provider: 'openai',
+              api_key: 'your-openai-api-key'
+            },
+            retrieval: {
+              backend: 'memory',
+              documents_path: './docs/**/*.md'
+            }
+          }
+        }
+
+        config_file = 'rapitapir_ai.json'
+
+        if File.exist?(config_file)
+          puts "Configuration file #{config_file} already exists"
+          exit 1
+        end
+
+        File.write(config_file, JSON.pretty_generate(config_template))
+        puts "Created #{config_file}"
+        puts 'Please update the configuration with your API keys and document paths'
+      end
+
+      def run_ai_query(args)
+        query = args.join(' ')
+
+        if query.empty?
+          puts 'Usage: rapitapir ai query <your question>'
+          exit 1
+        end
+
+        unless @options[:input]
+          puts 'Error: --endpoints is required'
+          exit 1
+        end
+
+        endpoints = load_endpoints(@options[:input])
+
+        # Export MCP context for the query
+        require_relative '../ai/mcp'
+        exporter = RapiTapir::AI::MCP::Exporter.new(endpoints)
+        context = exporter.as_mcp_context
+
+        puts 'API Context for AI Agents:'
+        puts '========================='
+        puts
+        puts "Query: #{query}"
+        puts
+        puts 'Available Endpoints:'
+        if context && context[:endpoints]
+          context[:endpoints].each do |ep|
+            puts "  #{ep[:method]} #{ep[:path]} - #{ep[:summary]}"
+          end
+        else
+          puts '  No endpoints found'
+        end
+        puts
+        puts 'This context can be used by AI agents to understand your API structure.'
+      end
+
+      def run_ai_llm(args)
+        command = args.shift
+
+        case command
+        when 'generate'
+          run_llm_generate(args)
+        when 'export'
+          run_llm_export(args)
+        when 'test'
+          run_llm_test(args)
+        else
+          puts 'LLM subcommands: generate, export, test'
+          exit 1
+        end
+      end
+
+      def run_llm_generate(_args)
+        unless @options[:input]
+          puts 'Error: --endpoints is required'
+          exit 1
+        end
+
+        endpoints = load_endpoints(@options[:input])
+
+        # Find LLM instruction-enabled endpoints
+        llm_endpoints = endpoints.select(&:llm_instruction?)
+
+        if llm_endpoints.empty?
+          puts "No LLM instruction-enabled endpoints found in #{@options[:input]}"
+          puts 'Add .llm_instruction(purpose: :validation) to your endpoints to enable LLM instruction generation'
+          exit 1
+        end
+
+        require_relative '../ai/llm_instruction'
+
+        puts 'Generating LLM instructions...'
+        puts "Found #{llm_endpoints.size} LLM instruction-enabled endpoint(s):"
+
+        generator = RapiTapir::AI::LLMInstruction::Generator.new(llm_endpoints)
+        instructions = generator.generate_all_instructions
+
+        instructions[:instructions].each do |instruction|
+          puts "\n#{'=' * 60}"
+          puts "#{instruction[:method]} #{instruction[:path]} (#{instruction[:purpose]})"
+          puts '=' * 60
+          puts instruction[:instruction]
+        end
+
+        puts "\n#{'=' * 60}"
+        puts "Generated #{instructions[:instructions].size} LLM instructions"
+      end
+
+      def run_llm_export(args)
+        format = args.shift || 'json'
+        output_file = @options[:output]
+
+        unless @options[:input]
+          puts 'Error: --endpoints is required'
+          exit 1
+        end
+
+        endpoints = load_endpoints(@options[:input])
+        llm_endpoints = endpoints.select(&:llm_instruction?)
+
+        if llm_endpoints.empty?
+          puts 'No LLM instruction-enabled endpoints found'
+          exit 1
+        end
+
+        require_relative '../ai/llm_instruction'
+
+        generator = RapiTapir::AI::LLMInstruction::Generator.new(llm_endpoints)
+        instructions = generator.generate_all_instructions
+        exporter = RapiTapir::AI::LLMInstruction::Exporter.new(instructions)
+
+        case format.downcase
+        when 'json'
+          output = exporter.to_json
+          extension = '.json'
+        when 'yaml', 'yml'
+          output = exporter.to_yaml
+          extension = '.yml'
+        when 'markdown', 'md'
+          output = exporter.to_markdown
+          extension = '.md'
+        when 'prompts'
+          if output_file
+            puts exporter.to_prompt_files(output_file)
+            return
+          else
+            puts 'Error: --output directory is required for prompts format'
+            exit 1
+          end
+        else
+          puts "Error: Unsupported format '#{format}'. Supported: json, yaml, markdown, prompts"
+          exit 1
+        end
+
+        if output_file
+          output_file += extension unless output_file.end_with?(extension)
+          File.write(output_file, output)
+          puts "LLM instructions exported to #{output_file}"
+        else
+          puts output
+        end
+      end
+
+      def run_llm_test(args)
+        purpose = args.shift
+
+        unless purpose
+          puts 'Usage: rapitapir ai llm test <purpose>'
+          puts 'Available purposes: validation, transformation, analysis, documentation, testing, completion'
+          exit 1
+        end
+
+        unless @options[:input]
+          puts 'Error: --endpoints is required'
+          exit 1
+        end
+
+        endpoints = load_endpoints(@options[:input])
+        llm_endpoints = endpoints.select(&:llm_instruction?)
+
+        if llm_endpoints.empty?
+          puts 'No LLM instruction-enabled endpoints found'
+          exit 1
+        end
+
+        require_relative '../ai/llm_instruction'
+
+        puts "Testing LLM instruction generation for purpose: #{purpose}"
+        puts
+
+        generator = RapiTapir::AI::LLMInstruction::Generator.new(llm_endpoints)
+
+        llm_endpoints.each do |endpoint|
+          config = endpoint.llm_instruction_config.dup
+          config[:purpose] = purpose.to_sym
+
+          begin
+            instruction = generator.generate_instruction(endpoint, config)
+            puts "✅ #{endpoint.method&.upcase} #{endpoint.path}"
+            puts "   Purpose: #{instruction[:purpose]}"
+            puts "   Length: #{instruction[:instruction].length} characters"
+            puts
+          rescue StandardError => e
+            puts "❌ #{endpoint.method&.upcase} #{endpoint.path}"
+            puts "   Error: #{e.message}"
+            puts
+          end
+        end
+      end
+
+      def ai_help
+        <<~HELP
+          AI Commands:
+            rapitapir ai rag test [query]       - Test RAG functionality on your API
+            rapitapir ai rag setup             - Create RAG configuration template
+            rapitapir ai query <question>       - Get AI-ready context for a query
+            rapitapir ai llm generate           - Generate LLM instructions from endpoints
+            rapitapir ai llm export [format]    - Export LLM instructions (json, yaml, markdown, prompts)
+            rapitapir ai llm test <purpose>     - Test LLM instruction generation for a purpose
+            rapitapir ai help                   - Show this help
+        HELP
+      end
     end
   end
 end

data/lib/rapitapir/cli/mcp_export.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../core/endpoint'
+require_relative '../ai/mcp'
+require 'json'
+
+module RapiTapir
+  module CLI
+    class MCPExport
+      # Exports all endpoints marked for MCP as a JSON file
+      def self.run(endpoints, output_path = 'mcp-context.json')
+        exporter = RapiTapir::AI::MCP::Exporter.new(endpoints)
+        File.write(output_path, JSON.pretty_generate(exporter.as_mcp_context))
+        puts "MCP context exported to #{output_path}"
+      end
+    end
+  end
+end

data/lib/rapitapir/cli/validator.rb

@@ -112,9 +112,7 @@ module RapiTapir
         # Check path parameter format
         path.scan(/:(\w+)/).each do |param_match|
           param_name = param_match[0]
-          unless param_name.match?(/^[a-zA-Z][a-zA-Z0-9_]*$/)
-            @errors << "#{context}: Invalid path parameter name '#{param_name}'"
-          end
+          @errors << "#{context}: Invalid path parameter name '#{param_name}'" unless param_name.match?(/^[a-zA-Z][a-zA-Z0-9_]*$/)
         end
       end
 
@@ -219,9 +217,7 @@ module RapiTapir
 
       def validate_hash_schema(schema, context)
         schema.each do |key, value|
-          unless key.is_a?(Symbol) || key.is_a?(String)
-            @errors << "#{context}: Hash key '#{key}' must be a symbol or string"
-          end
+          @errors << "#{context}: Hash key '#{key}' must be a symbol or string" unless key.is_a?(Symbol) || key.is_a?(String)
 
           validate_type(value, "#{context}.#{key}")
         end