rack-ai 0.1.0

data/README.md

@@ -0,0 +1,687 @@
+# Rack::AI
+
+A next-generation RubyGem that extends Rack with AI-powered capabilities for request classification, content moderation, security analysis, and intelligent caching.
+
+[![Gem Version](https://badge.fury.io/rb/rack-ai.svg)](https://badge.fury.io/rb/rack-ai)
+[![Build Status](https://github.com/ahmetxhero/rack-ai/workflows/CI/badge.svg)](https://github.com/ahmetxhero/rack-ai/actions)
+[![Coverage Status](https://coveralls.io/repos/github/ahmetxhero/rack-ai/badge.svg?branch=main)](https://coveralls.io/github/ahmetxhero/rack-ai?branch=main)
+
+## ☕ **Support My Open Source Work** ☕
+
+**Love this project? Buy me a coffee and help me continue building innovative security solutions!**
+
+[![Buy Me A Coffee](https://img.shields.io/badge/☕_Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/ahmetxhero)
+[![GitHub Sponsors](https://img.shields.io/badge/💖_GitHub_Sponsors-EA4AAA?style=for-the-badge&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/ahmetxhero)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/ahmetxhero)
+
+**Your support makes a difference! 🚀 Every contribution helps me dedicate more time to open source development.**
+
+---
+
+## 👋 Hey, This is Ahmet KAHRAMAN
+
+**💻 Mobile Developer & Cyber Security Expert**  
+**🏠 Living in Ankara, Turkey 🇹🇷**  
+**🌟 10+ years experience in Public Sector IT**  
+**💬 Mantra: "Security first, innovation always"**
+
+### 🔗 Connect With Me
+
+| Platform | Link | Description |
+|----------|------|-------------|
+| 🌐 **Portfolio** | [ahmetxhero.web.app](https://ahmetxhero.web.app) | My home on the net |
+| 💼 **LinkedIn** | [linkedin.com/in/ahmetxhero](https://linkedin.com/in/ahmetxhero) | Professional network |
+| 🎥 **YouTube** | [@ahmetxhero](https://youtube.com/@ahmetxhero) | Haven't you subscribed yet? |
+| 📝 **Medium** | [ahmetxhero.medium.com](https://ahmetxhero.medium.com) | Technical articles |
+| 🐤 **Twitter** | [@ahmetxhero](https://x.com/ahmetxhero) | Tech thoughts & updates |
+| 📷 **Instagram** | [instagram.com/ahmetxhero](https://instagram.com/ahmetxhero) | Behind the scenes |
+| 🎮 **Twitch** | [twitch.tv/ahmetxhero](https://twitch.tv/ahmetxhero) | Live coding sessions |
+| 🎨 **Dribbble** | [dribbble.com/ahmetxhero](https://dribbble.com/ahmetxhero) | Design portfolio |
+| 🎨 **Figma** | [figma.com/@ahmetxhero](https://figma.com/@ahmetxhero) | UI/UX designs |
+| 📧 **Email** | ahmetxhero@gmail.com | You can reach me here |
+
+### 🛠️ Tech Stack & Expertise
+
+#### Mobile Development
+- **iOS:** Swift, Objective-C, UIKit, SwiftUI
+- **Android:** Java, Kotlin, Android SDK
+- **Cross-Platform:** Flutter, React Native
+- **Frameworks:** Xamarin, Ionic
+
+#### Cybersecurity & Forensics
+- **Digital Forensics:** EnCase, FTK, Autopsy, Volatility
+- **Penetration Testing:** Metasploit, Burp Suite, Nmap
+- **Security Tools:** Wireshark, OWASP ZAP, Nessus
+- **Programming:** Python, PowerShell, Bash
+
+#### System Administration
+- **Operating Systems:** Windows Server, Linux (Ubuntu, CentOS)
+- **Virtualization:** VMware, Hyper-V, VirtualBox
+- **Cloud Platforms:** AWS, Azure, Google Cloud
+- **Networking:** TCP/IP, DNS, DHCP, VPN
+
+### 📊 Professional Experience
+
+#### Current Role
+**Mobile Developer / Mobile System Operator**  
+*Gendarmerie General Command* | July 2024 - Present  
+📍 Ankara, Turkey
+
+#### Previous Experience
+- **IT Expert** | Gendarmerie General Command (2015-2024)
+- **Founder** | Sadık Internet Cafe (2012-2014)
+
+### 🎓 Education
+- **Master's Degree in Forensic Informatics** | Gazi University (2021-2023)
+- **Bachelor's Degree in Health Management** | Anadolu University (2017-2021)
+- **Associate's Degree in Computer Programming** | Atatürk University (2020-2023)
+- **Associate's Degree in Occupational Health & Safety** | Atatürk University (2016-2019)
+
+### 🏆 Certifications & Achievements
+- Microsoft Certified Professional
+- Certified Ethical Hacker (CEH)
+- Digital Forensics Expert
+- iOS & Swift Development
+- Flutter Development
+- Android Development
+
+### 🎯 Current Focus
+- 🔒 **Cybersecurity:** Developing secure mobile applications
+- 📱 **Mobile Development:** Creating innovative iOS and Android apps
+- 🔍 **Digital Forensics:** Advancing forensic investigation techniques
+- 📚 **Knowledge Sharing:** Contributing to the tech community
+- 🌟 **Open Source:** Building tools for the developer community
+
+### 🗣️ Speaking & Content Creation
+- 🎥 I have my own YouTube channel - **@ahmetxhero**
+- 🗣️ I enjoy speaking at tech events. Interested in having me speak at your event?
+- 🤖 I'm passionate about mobile development and cybersecurity solutions
+
+**"Building secure, innovative solutions for a better digital future" 🚀**
+
+---
+
+## Features
+
+- **🤖 Request Classification**: Automatically classify requests as human, bot, spam, or suspicious
+- **🛡️ Security Analysis**: Detect SQL injection, XSS, prompt injection, and other security threats
+- **🔍 Content Moderation**: Real-time toxicity and policy violation detection
+- **⚡ Smart Caching**: AI-powered predictive caching and prefetching
+- **🎯 Intelligent Routing**: Route requests based on AI analysis results
+- **📊 Enhanced Logging**: AI-generated insights and traffic pattern analysis
+- **✨ Content Enhancement**: Automatic SEO, readability, and accessibility improvements
+- **🔌 Multiple AI Providers**: Support for OpenAI, HuggingFace, and local AI models
+- **🚀 Production Ready**: Fail-safe mode, async processing, and comprehensive monitoring
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rack-ai'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install rack-ai
+```
+
+## Quick Start
+
+### Basic Usage
+
+```ruby
+require 'rack/ai'
+
+# Configure Rack::AI
+Rack::AI.configure do |config|
+  config.provider = :openai
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.features = [:classification, :security, :moderation]
+end
+
+# Add to your Rack application
+use Rack::AI::Middleware
+```
+
+### Rails Integration
+
+```ruby
+# config/application.rb
+class Application < Rails::Application
+  config.middleware.use Rack::AI::Middleware,
+    provider: :openai,
+    api_key: ENV['OPENAI_API_KEY'],
+    features: [:classification, :moderation, :security]
+end
+```
+
+### Sinatra Integration
+
+```ruby
+require 'sinatra'
+require 'rack/ai'
+
+class MyApp < Sinatra::Base
+  use Rack::AI::Middleware,
+    provider: :openai,
+    api_key: ENV['OPENAI_API_KEY'],
+    features: [:classification, :security]
+    
+  get '/' do
+    ai_results = request.env['rack.ai'][:results]
+    "Classification: #{ai_results[:classification][:classification]}"
+  end
+end
+```
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+Rack::AI.configure do |config|
+  # Provider settings
+  config.provider = :openai  # :openai, :huggingface, :local
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.timeout = 30
+  config.retries = 3
+
+  # Feature toggles
+  config.features = [:classification, :moderation, :security, :caching]
+  config.fail_safe = true
+  config.async_processing = true
+
+  # Security settings
+  config.sanitize_logs = true
+  config.allowed_data_types = [:headers, :query_params]
+
+  # Feature-specific configuration
+  config.classification.confidence_threshold = 0.8
+  config.moderation.toxicity_threshold = 0.7
+  config.caching.redis_url = ENV['REDIS_URL']
+end
+```
+
+### Environment-Specific Configuration
+
+```ruby
+# config/environments/production.rb
+Rack::AI.configure do |config|
+  config.provider = :openai
+  config.timeout = 10  # Shorter timeout in production
+  config.explain_decisions = false
+  config.sanitize_logs = true
+end
+
+# config/environments/development.rb
+Rack::AI.configure do |config|
+  config.provider = :local
+  config.api_url = 'http://localhost:8080'
+  config.explain_decisions = true
+  config.log_level = :debug
+end
+```
+
+## AI Providers
+
+### OpenAI
+
+```ruby
+Rack::AI.configure do |config|
+  config.provider = :openai
+  config.api_key = ENV['OPENAI_API_KEY']
+  # Optional: config.api_url = 'https://api.openai.com/v1'
+end
+```
+
+### HuggingFace
+
+```ruby
+Rack::AI.configure do |config|
+  config.provider = :huggingface
+  config.api_key = ENV['HUGGINGFACE_API_KEY']
+end
+```
+
+### Local AI Model
+
+```ruby
+Rack::AI.configure do |config|
+  config.provider = :local
+  config.api_url = 'http://localhost:8080'
+end
+```
+
+## Features
+
+### Request Classification
+
+Automatically classifies incoming requests:
+
+```ruby
+# Access classification results
+ai_results = request.env['rack.ai'][:results]
+classification = ai_results[:classification]
+
+case classification[:classification]
+when :human
+  # Handle human user
+when :bot
+  # Handle bot request
+when :spam
+  # Block or handle spam
+when :suspicious
+  # Apply additional security measures
+end
+```
+
+### Security Analysis
+
+Detects various security threats:
+
+```ruby
+security = ai_results[:security]
+
+if security[:threat_level] == :high
+  # Block request immediately
+  halt 403, 'Security threat detected'
+elsif security[:threat_level] == :medium
+  # Apply additional verification
+  require_captcha
+end
+
+# Check specific threats
+if security[:injection_detection][:threats].include?('sql_injection')
+  log_security_incident(request)
+end
+```
+
+### Content Moderation
+
+Real-time content analysis:
+
+```ruby
+moderation = ai_results[:moderation]
+
+if moderation[:flagged]
+  categories = moderation[:categories]
+  
+  if categories['hate']
+    reject_content('Hate speech detected')
+  elsif categories['violence']
+    flag_for_review(content)
+  end
+end
+```
+
+### Smart Caching
+
+AI-powered caching decisions:
+
+```ruby
+caching = ai_results[:caching]
+
+if caching[:should_prefetch]
+  # Schedule prefetching for predicted requests
+  PrefetchJob.perform_later(caching[:pattern_analysis])
+end
+
+if caching[:cache_hit]
+  # Use cached AI analysis
+  cached_result = caching[:cached_result]
+end
+```
+
+## Advanced Usage
+
+### Custom AI Processing
+
+```ruby
+class CustomAIMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    # Add custom context for AI processing
+    env['rack.ai.custom'] = {
+      user_tier: extract_user_tier(env),
+      api_version: extract_api_version(env)
+    }
+
+    status, headers, body = @app.call(env)
+
+    # Process AI results
+    ai_results = env['rack.ai'][:results]
+    handle_ai_insights(ai_results)
+
+    [status, headers, body]
+  end
+end
+```
+
+### Conditional AI Processing
+
+```ruby
+use Rack::AI::Middleware,
+  provider: :openai,
+  api_key: ENV['OPENAI_API_KEY'],
+  features: [:classification, :security],
+  condition: ->(env) { 
+    # Only process API requests
+    env['PATH_INFO'].start_with?('/api/')
+  }
+```
+
+### Multiple AI Providers
+
+```ruby
+# Primary provider with fallback
+primary_config = {
+  provider: :openai,
+  api_key: ENV['OPENAI_API_KEY']
+}
+
+fallback_config = {
+  provider: :local,
+  api_url: 'http://localhost:8080'
+}
+
+use Rack::AI::Middleware, primary_config
+use Rack::AI::FallbackMiddleware, fallback_config
+```
+
+## Monitoring and Metrics
+
+### Built-in Metrics
+
+```ruby
+# Access metrics
+metrics = Rack::AI::Utils::Metrics
+
+# Request processing metrics
+processing_time = metrics.get_histogram_stats('rack_ai.processing_time')
+request_count = metrics.get_counter('rack_ai.requests_processed')
+
+# Feature-specific metrics
+classification_accuracy = metrics.get_histogram_stats('rack_ai.feature.classification.confidence')
+security_threats = metrics.get_counter('rack_ai.feature.security.threats_detected')
+```
+
+### Prometheus Integration
+
+```ruby
+# Export metrics in Prometheus format
+get '/metrics' do
+  content_type 'text/plain'
+  Rack::AI::Utils::Metrics.export_prometheus_format
+end
+```
+
+### Custom Logging
+
+```ruby
+# Enhanced logging with AI context
+class AILogger < Rack::AI::Utils::Logger
+  def self.log_request(env, ai_results)
+    info('AI-enhanced request processed', {
+      path: env['PATH_INFO'],
+      classification: ai_results[:classification][:classification],
+      threat_level: ai_results[:security][:threat_level],
+      processing_time: ai_results[:processing_time]
+    })
+  end
+end
+```
+
+## Performance Considerations
+
+### Async Processing
+
+```ruby
+# Enable async processing for better performance
+Rack::AI.configure do |config|
+  config.async_processing = true
+  config.timeout = 5  # Shorter timeout for async
+end
+```
+
+### Feature Selection
+
+```ruby
+# Enable only necessary features
+Rack::AI.configure do |config|
+  # Lightweight configuration
+  config.features = [:classification, :security]
+  
+  # Heavy configuration (includes caching, enhancement)
+  # config.features = [:classification, :moderation, :security, :caching, :enhancement]
+end
+```
+
+### Caching AI Results
+
+```ruby
+# Cache AI analysis results
+Rack::AI.configure do |config|
+  config.cache_enabled = true
+  config.cache_ttl = 3600  # 1 hour
+  config.caching.redis_url = ENV['REDIS_URL']
+end
+```
+
+## Error Handling
+
+### Fail-Safe Mode
+
+```ruby
+# Graceful degradation when AI services are unavailable
+Rack::AI.configure do |config|
+  config.fail_safe = true  # Continue processing even if AI fails
+  config.timeout = 10      # Reasonable timeout
+  config.retries = 2       # Limited retries
+end
+```
+
+### Custom Error Handling
+
+```ruby
+class AIErrorHandler
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    @app.call(env)
+  rescue Rack::AI::ProviderError => e
+    # Handle AI provider errors
+    [503, {}, ['AI service temporarily unavailable']]
+  rescue Rack::AI::ConfigurationError => e
+    # Handle configuration errors
+    [500, {}, ['AI configuration error']]
+  end
+end
+```
+
+## Security Best Practices
+
+### Data Sanitization
+
+```ruby
+Rack::AI.configure do |config|
+  # Sanitize sensitive data before sending to AI
+  config.sanitize_logs = true
+  config.allowed_data_types = [:headers, :query_params]
+  config.blocked_data_types = [:body, :cookies]
+end
+```
+
+### API Key Management
+
+```ruby
+# Use environment variables for API keys
+Rack::AI.configure do |config|
+  config.api_key = ENV['OPENAI_API_KEY']
+  # Never hardcode API keys in your application
+end
+```
+
+### Rate Limiting
+
+```ruby
+Rack::AI.configure do |config|
+  config.rate_limit = 1000  # Requests per minute
+  config.security.rate_limit = 100  # Lower limit for security analysis
+end
+```
+
+## Testing
+
+### Test Configuration
+
+```ruby
+# spec/spec_helper.rb
+RSpec.configure do |config|
+  config.before(:each) do
+    Rack::AI.configure do |config|
+      config.provider = :local
+      config.api_url = 'http://localhost:8080'
+      config.features = []  # Disable AI in tests
+      config.fail_safe = true
+    end
+  end
+end
+```
+
+### Mocking AI Responses
+
+```ruby
+# Mock AI provider responses
+RSpec.describe 'AI Integration' do
+  before do
+    allow_any_instance_of(Rack::AI::Providers::OpenAI)
+      .to receive(:classify_request)
+      .and_return({
+        classification: :human,
+        confidence: 0.9,
+        provider: :openai
+      })
+  end
+
+  it 'processes requests with AI' do
+    get '/api/test'
+    expect(last_response.headers['X-AI-Classification']).to eq('human')
+  end
+end
+```
+
+## Deployment
+
+### Production Checklist
+
+- [ ] Set appropriate API keys via environment variables
+- [ ] Configure fail-safe mode and timeouts
+- [ ] Enable metrics and monitoring
+- [ ] Set up Redis for caching (if using caching features)
+- [ ] Configure log sanitization
+- [ ] Test AI provider connectivity
+- [ ] Set up alerting for AI service failures
+
+### Docker Configuration
+
+```dockerfile
+# Dockerfile
+FROM ruby:3.2
+
+# Install dependencies
+COPY Gemfile* ./
+RUN bundle install
+
+# Copy application
+COPY . .
+
+# Set environment variables
+ENV OPENAI_API_KEY=${OPENAI_API_KEY}
+ENV REDIS_URL=${REDIS_URL}
+ENV RACK_AI_LOG_LEVEL=info
+
+CMD ["bundle", "exec", "rackup"]
+```
+
+### Kubernetes Deployment
+
+```yaml
+# deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: rack-ai-app
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: rack-ai-app
+  template:
+    metadata:
+      labels:
+        app: rack-ai-app
+    spec:
+      containers:
+      - name: app
+        image: your-app:latest
+        env:
+        - name: OPENAI_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: ai-secrets
+              key: openai-api-key
+        - name: REDIS_URL
+          value: "redis://redis-service:6379"
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -am 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+git clone https://github.com/rack-ai/rack-ai.git
+cd rack-ai
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+### Running Benchmarks
+
+```bash
+bundle exec ruby benchmarks/performance_benchmark.rb
+```
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Support
+
+- 📖 [Documentation](https://rack-ai.github.io/rack-ai/)
+- 🐛 [Issue Tracker](https://github.com/rack-ai/rack-ai/issues)
+- 💬 [Discussions](https://github.com/rack-ai/rack-ai/discussions)
+- 📧 [Email Support](mailto:support@rack-ai.dev)
+
+## Roadmap
+
+See our [roadmap](ROADMAP.md) for planned features and improvements.