rack-ai 0.1.0

data/ROADMAP.md

@@ -0,0 +1,203 @@
+# Rack::AI Roadmap
+
+This document outlines the planned development roadmap for Rack::AI, from the current v0.1.0 to future enterprise-grade features.
+
+## Current Version: v0.1.0 (MVP)
+
+### ✅ Completed Features
+- Core Rack middleware architecture
+- Pluggable AI provider system (OpenAI, HuggingFace, Local)
+- Basic AI features (classification, moderation, security, caching, logging, enhancement, routing)
+- Configuration system with Ruby DSL and YAML support
+- Rails and Sinatra integration examples
+- Comprehensive test suite and benchmarks
+- Security-first design with data sanitization
+- Fail-safe mode and error handling
+- Metrics and monitoring capabilities
+
+## v0.2.0 - Enhanced Performance & Reliability (Q1 2024)
+
+### 🎯 Performance Optimizations
+- [ ] **Connection Pooling**: Implement HTTP connection pooling for AI providers
+- [ ] **Request Batching**: Batch multiple requests to AI providers for efficiency
+- [ ] **Smart Caching**: Enhanced Redis-based caching with TTL optimization
+- [ ] **Async Processing**: Improved async processing with configurable thread pools
+- [ ] **Memory Optimization**: Reduce memory footprint and garbage collection pressure
+
+### 🔧 Reliability Improvements
+- [ ] **Circuit Breaker**: Implement circuit breaker pattern for AI provider failures
+- [ ] **Health Checks**: Built-in health check endpoints for AI providers
+- [ ] **Graceful Degradation**: Better fallback mechanisms when AI services are unavailable
+- [ ] **Request Queuing**: Queue requests during AI provider outages
+- [ ] **Retry Logic**: Exponential backoff and jitter for failed requests
+
+### 📊 Enhanced Monitoring
+- [ ] **Detailed Metrics**: More granular metrics for performance analysis
+- [ ] **Distributed Tracing**: OpenTelemetry integration for request tracing
+- [ ] **Custom Dashboards**: Pre-built Grafana dashboards
+- [ ] **Alerting**: Built-in alerting for anomalies and failures
+
+## v0.3.0 - Advanced AI Features (Q2 2024)
+
+### 🤖 Multi-Model Support
+- [ ] **Model Orchestration**: Route requests to different AI models based on content type
+- [ ] **A/B Testing**: Built-in A/B testing for different AI models
+- [ ] **Model Fallbacks**: Automatic fallback to simpler models when complex ones fail
+- [ ] **Custom Models**: Support for fine-tuned and custom AI models
+
+### 🧠 Advanced Analytics
+- [ ] **Pattern Learning**: Learn from historical data to improve classifications
+- [ ] **Anomaly Detection**: Advanced statistical anomaly detection
+- [ ] **Trend Analysis**: Identify and predict traffic trends
+- [ ] **User Behavior Analysis**: Track and analyze user interaction patterns
+
+### 🔍 Enhanced Security
+- [ ] **Advanced Threat Detection**: ML-based threat detection beyond rule-based systems
+- [ ] **Behavioral Analysis**: Detect suspicious behavior patterns
+- [ ] **Zero-Day Protection**: Proactive protection against unknown threats
+- [ ] **Compliance Reporting**: Automated compliance reports for security audits
+
+## v0.4.0 - Enterprise Features (Q3 2024)
+
+### 🏢 Enterprise Integration
+- [ ] **SSO Integration**: Support for SAML, OAuth, and other enterprise SSO systems
+- [ ] **RBAC**: Role-based access control for AI features
+- [ ] **Multi-Tenancy**: Support for multi-tenant deployments
+- [ ] **Enterprise Logging**: Integration with enterprise logging systems (Splunk, ELK)
+
+### 🔐 Advanced Security & Compliance
+- [ ] **GDPR Compliance**: Built-in GDPR compliance features
+- [ ] **SOC 2 Compliance**: SOC 2 Type II compliance features
+- [ ] **Data Residency**: Control over where AI processing occurs
+- [ ] **Audit Trails**: Comprehensive audit trails for all AI decisions
+
+### 📈 Scalability
+- [ ] **Horizontal Scaling**: Support for distributed deployments
+- [ ] **Load Balancing**: Intelligent load balancing across AI providers
+- [ ] **Auto-Scaling**: Automatic scaling based on traffic patterns
+- [ ] **Edge Computing**: Support for edge AI processing
+
+## v0.5.0 - AI-Powered Optimization (Q4 2024)
+
+### 🎯 Intelligent Optimization
+- [ ] **Auto-Configuration**: AI-powered automatic configuration optimization
+- [ ] **Performance Tuning**: Automatic performance tuning based on usage patterns
+- [ ] **Resource Optimization**: Intelligent resource allocation and cost optimization
+- [ ] **Predictive Scaling**: Predict and prepare for traffic spikes
+
+### 🔄 Advanced Caching
+- [ ] **Semantic Caching**: Cache based on semantic similarity, not just exact matches
+- [ ] **Predictive Prefetching**: AI-powered predictive content prefetching
+- [ ] **Cache Warming**: Intelligent cache warming strategies
+- [ ] **Multi-Layer Caching**: Hierarchical caching with different TTLs
+
+### 🌐 Global Distribution
+- [ ] **CDN Integration**: Integration with major CDN providers
+- [ ] **Geographic Optimization**: Optimize AI processing based on user location
+- [ ] **Multi-Region Deployment**: Support for multi-region AI deployments
+- [ ] **Latency Optimization**: Minimize latency through intelligent routing
+
+## v1.0.0 - Production-Ready Enterprise Platform (Q1 2025)
+
+### 🚀 Production Readiness
+- [ ] **99.9% Uptime SLA**: Guaranteed uptime with comprehensive monitoring
+- [ ] **Enterprise Support**: 24/7 enterprise support with dedicated success managers
+- [ ] **Professional Services**: Implementation and optimization consulting
+- [ ] **Training Programs**: Comprehensive training for development teams
+
+### 🔧 Advanced Configuration
+- [ ] **Visual Configuration**: Web-based configuration interface
+- [ ] **Configuration Validation**: Advanced validation and testing tools
+- [ ] **Environment Management**: Manage configurations across environments
+- [ ] **Configuration Templates**: Pre-built templates for common use cases
+
+### 📊 Business Intelligence
+- [ ] **Executive Dashboards**: High-level dashboards for business stakeholders
+- [ ] **ROI Analytics**: Measure and report on AI ROI
+- [ ] **Cost Analysis**: Detailed cost analysis and optimization recommendations
+- [ ] **Business Insights**: AI-generated business insights and recommendations
+
+## Future Considerations (v2.0+)
+
+### 🔮 Emerging Technologies
+- [ ] **Quantum-Safe Security**: Prepare for quantum computing threats
+- [ ] **Edge AI**: Advanced edge computing capabilities
+- [ ] **Federated Learning**: Support for federated learning across deployments
+- [ ] **Neuromorphic Computing**: Support for next-generation AI hardware
+
+### 🌍 Ecosystem Expansion
+- [ ] **Plugin Marketplace**: Marketplace for third-party AI plugins
+- [ ] **API Ecosystem**: Rich API ecosystem for integrations
+- [ ] **Community Contributions**: Enhanced community contribution framework
+- [ ] **Open Source Governance**: Formal open source governance model
+
+### 🎓 AI Democratization
+- [ ] **No-Code Configuration**: Visual, no-code configuration tools
+- [ ] **AI Explainability**: Advanced explainable AI features
+- [ ] **Automated Optimization**: Fully automated AI optimization
+- [ ] **Self-Healing Systems**: Self-diagnosing and self-healing AI systems
+
+## Implementation Strategy
+
+### Development Principles
+1. **Backward Compatibility**: Maintain backward compatibility across versions
+2. **Security First**: Security considerations in every feature
+3. **Performance Focus**: Performance optimization as a core requirement
+4. **Community Driven**: Community feedback drives feature prioritization
+5. **Enterprise Ready**: Enterprise requirements considered from the start
+
+### Release Cycle
+- **Major Releases**: Quarterly (every 3 months)
+- **Minor Releases**: Monthly bug fixes and small features
+- **Patch Releases**: As needed for critical issues
+- **LTS Versions**: Long-term support for enterprise customers
+
+### Quality Assurance
+- **Automated Testing**: Comprehensive test coverage (>95%)
+- **Performance Testing**: Regular performance regression testing
+- **Security Audits**: Regular third-party security audits
+- **Beta Program**: Extensive beta testing with enterprise customers
+
+## Community & Ecosystem
+
+### Open Source Community
+- **Contributor Guidelines**: Clear guidelines for community contributions
+- **Code of Conduct**: Inclusive and welcoming community standards
+- **Regular Releases**: Predictable release schedule
+- **Documentation**: Comprehensive and up-to-date documentation
+
+### Enterprise Ecosystem
+- **Partner Program**: Certified partner program for integrators
+- **Training Certification**: Professional certification programs
+- **Support Tiers**: Multiple support tiers for different needs
+- **Professional Services**: Implementation and optimization services
+
+### Research & Innovation
+- **Research Partnerships**: Partnerships with academic institutions
+- **Innovation Labs**: Internal innovation labs for emerging technologies
+- **Open Research**: Publish research findings and methodologies
+- **Industry Collaboration**: Collaborate with industry standards bodies
+
+## Success Metrics
+
+### Technical Metrics
+- **Performance**: <10ms median processing time
+- **Reliability**: 99.9% uptime SLA
+- **Accuracy**: >95% AI classification accuracy
+- **Scalability**: Support for 1M+ requests per minute
+
+### Business Metrics
+- **Adoption**: 10,000+ active installations
+- **Community**: 1,000+ contributors
+- **Enterprise**: 100+ enterprise customers
+- **Ecosystem**: 50+ certified partners
+
+### Impact Metrics
+- **Security**: 90% reduction in security incidents
+- **Performance**: 50% improvement in application performance
+- **Cost**: 30% reduction in infrastructure costs
+- **Developer Experience**: 80% developer satisfaction score
+
+---
+
+This roadmap is a living document that will be updated based on community feedback, market needs, and technological advances. We welcome input from the community to help prioritize features and ensure Rack::AI meets the evolving needs of modern web applications.

data/Rakefile

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc "Run performance benchmarks"
+task :benchmark do
+  ruby "benchmarks/performance_benchmark.rb"
+end
+
+desc "Generate YARD documentation"
+task :docs do
+  sh "yard doc"
+end
+
+desc "Start local AI server for development"
+task :local_ai do
+  puts "Starting local AI server on port 8080..."
+  puts "This is a mock server for development purposes"
+  # In a real implementation, this would start a local AI server
+end
+
+desc "Run security audit"
+task :security do
+  sh "bundle audit --update"
+end
+
+desc "Clean up generated files"
+task :clean do
+  rm_rf "coverage"
+  rm_rf "doc"
+  rm_rf ".yardoc"
+  rm_rf "pkg"
+end

data/benchmarks/performance_benchmark.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "rack/test"
+require "rack/ai"
+
+# Performance benchmarks for Rack::AI middleware
+class PerformanceBenchmark
+  include Rack::Test::Methods
+
+  def initialize
+    setup_apps
+    setup_mock_responses
+  end
+
+  def run_all_benchmarks
+    puts "=== Rack::AI Performance Benchmarks ==="
+    puts
+
+    benchmark_middleware_overhead
+    benchmark_ai_features
+    benchmark_provider_performance
+    benchmark_concurrent_requests
+    benchmark_memory_usage
+  end
+
+  private
+
+  def setup_apps
+    # Baseline app without AI
+    @baseline_app = lambda { |env| [200, {}, ["OK"]] }
+
+    # App with minimal AI features
+    @minimal_ai_app = Rack::Builder.new do
+      use Rack::AI::Middleware,
+        provider: :openai,
+        api_key: "test-key",
+        features: [:classification],
+        fail_safe: true,
+        async_processing: false
+
+      run lambda { |env| [200, {}, ["OK"]] }
+    end
+
+    # App with all AI features
+    @full_ai_app = Rack::Builder.new do
+      use Rack::AI::Middleware,
+        provider: :openai,
+        api_key: "test-key",
+        features: [:classification, :moderation, :security, :caching, :logging],
+        fail_safe: true,
+        async_processing: false
+
+      run lambda { |env| [200, {}, ["OK"]] }
+    end
+
+    # App with async processing
+    @async_ai_app = Rack::Builder.new do
+      use Rack::AI::Middleware,
+        provider: :openai,
+        api_key: "test-key",
+        features: [:classification, :security],
+        fail_safe: true,
+        async_processing: true
+
+      run lambda { |env| [200, {}, ["OK"]] }
+    end
+  end
+
+  def setup_mock_responses
+    # Mock successful AI responses for consistent benchmarking
+    require "webmock"
+    WebMock.enable!
+    
+    WebMock.stub_request(:post, "https://api.openai.com/v1/chat/completions")
+      .to_return(
+        status: 200,
+        body: {
+          choices: [{
+            message: {
+              content: { classification: "human", confidence: 0.9 }.to_json
+            }
+          }]
+        }.to_json
+      )
+
+    WebMock.stub_request(:post, "https://api.openai.com/v1/moderations")
+      .to_return(
+        status: 200,
+        body: {
+          results: [{
+            flagged: false,
+            categories: {},
+            category_scores: {}
+          }]
+        }.to_json
+      )
+  end
+
+  def benchmark_middleware_overhead
+    puts "## Middleware Overhead Benchmark"
+    puts
+
+    env = build_test_env
+
+    Benchmark.ips do |x|
+      x.config(time: 5, warmup: 2)
+
+      x.report("Baseline (no AI)") do
+        @baseline_app.call(env.dup)
+      end
+
+      x.report("Minimal AI (classification only)") do
+        @minimal_ai_app.call(env.dup)
+      end
+
+      x.report("Full AI (all features)") do
+        @full_ai_app.call(env.dup)
+      end
+
+      x.compare!
+    end
+
+    puts
+  end
+
+  def benchmark_ai_features
+    puts "## Individual AI Features Benchmark"
+    puts
+
+    env = build_test_env
+    provider = Rack::AI::Providers::OpenAI.new(api_key: "test-key")
+    request_data = provider.build_request_data(env)
+
+    Benchmark.ips do |x|
+      x.config(time: 5, warmup: 2)
+
+      x.report("Classification") do
+        provider.classify_request(request_data)
+      end
+
+      x.report("Content Moderation") do
+        provider.moderate_content("Test content for moderation")
+      end
+
+      x.report("Anomaly Detection") do
+        provider.detect_anomalies(request_data)
+      end
+
+      x.compare!
+    end
+
+    puts
+  end
+
+  def benchmark_provider_performance
+    puts "## AI Provider Performance Comparison"
+    puts
+
+    env = build_test_env
+    request_data = { method: "GET", path: "/test", user_agent: "Test" }
+
+    providers = {
+      "OpenAI" => Rack::AI::Providers::OpenAI.new(api_key: "test-key"),
+      "HuggingFace" => Rack::AI::Providers::HuggingFace.new(api_key: "test-key"),
+      "Local" => Rack::AI::Providers::Local.new(api_url: "http://localhost:8080")
+    }
+
+    # Mock responses for all providers
+    WebMock.stub_request(:post, %r{https://api-inference\.huggingface\.co/.*})
+      .to_return(status: 200, body: '[{"generated_text": "human"}]')
+    
+    WebMock.stub_request(:post, %r{http://localhost:8080/.*})
+      .to_return(status: 200, body: '{"classification": "human", "confidence": 0.9}')
+
+    Benchmark.ips do |x|
+      x.config(time: 3, warmup: 1)
+
+      providers.each do |name, provider|
+        x.report("#{name} Classification") do
+          begin
+            provider.classify_request(request_data)
+          rescue => e
+            # Handle provider errors gracefully in benchmark
+            nil
+          end
+        end
+      end
+
+      x.compare!
+    end
+
+    puts
+  end
+
+  def benchmark_concurrent_requests
+    puts "## Concurrent Request Processing"
+    puts
+
+    env = build_test_env
+    thread_counts = [1, 2, 4, 8]
+
+    thread_counts.each do |thread_count|
+      puts "### #{thread_count} concurrent threads"
+      
+      Benchmark.ips do |x|
+        x.config(time: 3, warmup: 1)
+
+        x.report("Sync Processing") do
+          threads = thread_count.times.map do
+            Thread.new { @minimal_ai_app.call(env.dup) }
+          end
+          threads.each(&:join)
+        end
+
+        x.report("Async Processing") do
+          threads = thread_count.times.map do
+            Thread.new { @async_ai_app.call(env.dup) }
+          end
+          threads.each(&:join)
+        end
+
+        x.compare!
+      end
+      
+      puts
+    end
+  end
+
+  def benchmark_memory_usage
+    puts "## Memory Usage Analysis"
+    puts
+
+    require "objspace"
+    
+    env = build_test_env
+    
+    # Measure baseline memory
+    GC.start
+    baseline_objects = ObjectSpace.count_objects
+
+    # Process requests and measure memory growth
+    1000.times { @full_ai_app.call(env.dup) }
+    
+    GC.start
+    after_objects = ObjectSpace.count_objects
+
+    puts "Memory usage (object count changes):"
+    [:TOTAL, :T_OBJECT, :T_CLASS, :T_MODULE, :T_FLOAT, :T_STRING, :T_REGEXP, 
+     :T_ARRAY, :T_HASH, :T_STRUCT, :T_BIGNUM, :T_FILE, :T_DATA, :T_MATCH, 
+     :T_COMPLEX, :T_RATIONAL, :T_NODE, :T_ICLASS].each do |type|
+      
+      baseline = baseline_objects[type] || 0
+      after = after_objects[type] || 0
+      diff = after - baseline
+      
+      if diff != 0
+        puts "  #{type}: #{diff > 0 ? '+' : ''}#{diff}"
+      end
+    end
+
+    puts
+  end
+
+  def build_test_env
+    {
+      "REQUEST_METHOD" => "GET",
+      "PATH_INFO" => "/api/test",
+      "QUERY_STRING" => "param=value",
+      "HTTP_USER_AGENT" => "Benchmark/1.0",
+      "REMOTE_ADDR" => "127.0.0.1",
+      "HTTP_HOST" => "localhost:3000",
+      "rack.input" => StringIO.new,
+      "rack.errors" => StringIO.new
+    }
+  end
+end
+
+# Run benchmarks if this file is executed directly
+if __FILE__ == $0
+  benchmark = PerformanceBenchmark.new
+  benchmark.run_all_benchmarks
+end