open_router_enhanced 1.0.0

data/Rakefile

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+# Unit tests only (excludes VCR integration tests)
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.exclude_pattern = "spec/vcr/**/*_spec.rb"
+end
+
+# VCR integration tests
+RSpec::Core::RakeTask.new(:spec_vcr) do |t|
+  t.pattern = "spec/vcr/**/*_spec.rb"
+end
+
+# All tests (unit + VCR)
+RSpec::Core::RakeTask.new(:spec_all) do |t|
+  # Run all specs
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# Default task runs unit tests + rubocop (fast feedback)
+task default: %i[spec rubocop]
+
+# Full CI task runs everything
+task ci: %i[spec_all rubocop]
+
+# Model exploration tasks
+namespace :models do
+  desc "Display summary of available models"
+  task :summary do
+    require_relative "lib/open_router"
+
+    puts "\n🤖 OpenRouter Model Registry Summary"
+    puts "=" * 80
+
+    models = OpenRouter::ModelRegistry.all_models
+
+    # Overall stats
+    puts "\n📊 Overall Statistics:"
+    puts "  Total models: #{models.size}"
+
+    # Provider breakdown
+    providers = models.keys.group_by { |id| id.split("/").first }
+    puts "\n🏢 Models by Provider:"
+    providers.sort_by { |_, models| -models.size }.each do |provider, provider_models|
+      puts "  #{provider.ljust(20)} #{provider_models.size} models"
+    end
+
+    # Capabilities breakdown
+    all_capabilities = models.values.flat_map { |spec| spec[:capabilities] }.uniq.sort
+    puts "\n⚡ Available Capabilities:"
+    all_capabilities.each do |cap|
+      count = models.values.count { |spec| spec[:capabilities].include?(cap) }
+      puts "  #{cap.to_s.ljust(25)} #{count} models"
+    end
+
+    # Cost analysis
+    input_costs = models.values.map { |spec| spec[:cost_per_1k_tokens][:input] }.compact.sort
+    output_costs = models.values.map { |spec| spec[:cost_per_1k_tokens][:output] }.compact.sort
+
+    puts "\n💰 Cost Analysis (per 1k tokens):"
+    puts "  Input tokens:"
+    puts "    Min:    $#{format("%.6f", input_costs.min)}"
+    puts "    Max:    $#{format("%.6f", input_costs.max)}"
+    puts "    Median: $#{format("%.6f", input_costs[input_costs.size / 2])}"
+    puts "  Output tokens:"
+    puts "    Min:    $#{format("%.6f", output_costs.min)}"
+    puts "    Max:    $#{format("%.6f", output_costs.max)}"
+    puts "    Median: $#{format("%.6f", output_costs[output_costs.size / 2])}"
+
+    # Context length analysis
+    context_lengths = models.values.map { |spec| spec[:context_length] }.compact.sort
+    puts "\n📏 Context Length Analysis:"
+    puts "  Min:    #{format_number_with_commas(context_lengths.min)} tokens"
+    puts "  Max:    #{format_number_with_commas(context_lengths.max)} tokens"
+    puts "  Median: #{format_number_with_commas(context_lengths[context_lengths.size / 2])} tokens"
+
+    # Performance tier breakdown
+    tiers = models.values.group_by { |spec| spec[:performance_tier] }
+    puts "\n🎯 Performance Tiers:"
+    tiers.each do |tier, tier_models|
+      puts "  #{tier.to_s.capitalize.ljust(10)} #{tier_models.size} models"
+    end
+
+    puts "\n#{"=" * 80}"
+    puts "💡 Use 'rake models:search' to find specific models"
+    puts "   Example: rake models:search provider=anthropic capability=function_calling"
+    puts
+  end
+
+  desc "Search for models by criteria (provider, capability, cost, context, etc.)"
+  task :search do
+    require_relative "lib/open_router"
+    require "date"
+
+    args = parse_search_arguments
+    puts "\n🔍 Searching OpenRouter Models"
+    puts "=" * 80
+
+    selector = build_model_selector(args)
+    limit = args[:limit]&.to_i || 20
+
+    puts "\n#{"=" * 80}"
+    puts "Results (showing up to #{limit}):\n\n"
+
+    results = fetch_matching_models(selector, args, limit)
+    display_search_results(results)
+
+    puts
+
+    # Prevent rake from treating arguments as tasks
+    ARGV.drop(1).each { |arg| task(arg.to_sym) { nil } }
+  end
+
+  # Parse command-line arguments into a hash
+  def self.parse_search_arguments
+    ARGV.drop(1).each_with_object({}) do |arg, hash|
+      key, value = arg.split("=", 2)
+      hash[key.to_sym] = value if key && value
+    end
+  end
+
+  # Build a ModelSelector from parsed arguments
+  def self.build_model_selector(args)
+    selector = OpenRouter::ModelSelector.new
+
+    selector = apply_optimization_strategy(selector, args)
+    selector = apply_provider_filters(selector, args)
+    selector = apply_capability_filters(selector, args)
+    selector = apply_cost_filters(selector, args)
+    selector = apply_context_filter(selector, args)
+    apply_date_filter(selector, args)
+  end
+
+  # Apply optimization strategy to selector
+  def self.apply_optimization_strategy(selector, args)
+    return selector unless args[:optimize]
+
+    strategy = args[:optimize].to_sym
+    selector = selector.optimize_for(strategy)
+    puts "📈 Optimizing for: #{strategy}"
+    selector
+  end
+
+  # Apply provider filters to selector
+  def self.apply_provider_filters(selector, args)
+    return selector unless args[:provider]
+
+    providers = args[:provider].split(",").map(&:strip)
+    selector = selector.require_providers(*providers)
+    puts "🏢 Provider: #{providers.join(", ")}"
+    selector
+  end
+
+  # Apply capability filters to selector
+  def self.apply_capability_filters(selector, args)
+    capability_arg = args[:capability] || args[:capabilities]
+    return selector unless capability_arg
+
+    caps = capability_arg.split(",").map { |c| c.strip.to_sym }
+    selector = selector.require(*caps)
+    puts "⚡ Required capabilities: #{caps.join(", ")}"
+    selector
+  end
+
+  # Apply cost filters to selector
+  def self.apply_cost_filters(selector, args)
+    selector = apply_input_cost_filter(selector, args)
+    apply_output_cost_filter(selector, args)
+  end
+
+  # Apply input cost filter
+  def self.apply_input_cost_filter(selector, args)
+    return selector unless args[:max_cost]
+
+    max_cost = args[:max_cost].to_f
+    selector = selector.within_budget(max_cost:)
+    puts "💰 Max cost (input): $#{format("%.6f", max_cost)}/1k tokens"
+    selector
+  end
+
+  # Apply output cost filter
+  def self.apply_output_cost_filter(selector, args)
+    return selector unless args[:max_output_cost]
+
+    max_output_cost = args[:max_output_cost].to_f
+    selector = selector.within_budget(max_output_cost:)
+    puts "💰 Max cost (output): $#{format("%.6f", max_output_cost)}/1k tokens"
+    selector
+  end
+
+  # Apply context length filter to selector
+  def self.apply_context_filter(selector, args)
+    return selector unless args[:min_context]
+
+    min_context = args[:min_context].to_i
+    selector = selector.min_context(min_context)
+    puts "📏 Min context: #{format_number_with_commas(min_context)} tokens"
+    selector
+  end
+
+  # Apply date filter to selector
+  def self.apply_date_filter(selector, args)
+    if args[:newer_than]
+      date = Date.parse(args[:newer_than])
+      selector = selector.newer_than(date)
+      puts "📅 Released after: #{date}"
+    end
+
+    puts "🎯 Performance tier: #{args[:tier]}" if args[:tier]
+    selector
+  end
+
+  # Fetch matching models based on selector and arguments
+  def self.fetch_matching_models(selector, args, limit)
+    if args[:fallbacks]
+      selector.choose_with_fallbacks(limit:)
+    else
+      fetch_sorted_candidates(selector, limit)
+    end
+  end
+
+  # Fetch and sort all matching candidates
+  def self.fetch_sorted_candidates(selector, limit)
+    requirements = selector.instance_variable_get(:@requirements)
+    provider_preferences = selector.instance_variable_get(:@provider_preferences)
+    strategy = selector.instance_variable_get(:@strategy)
+
+    candidates = OpenRouter::ModelRegistry.models_meeting_requirements(requirements)
+    candidates = filter_by_provider_preferences(candidates, provider_preferences)
+    sorted = sort_by_strategy(candidates, strategy)
+
+    sorted.first(limit)
+  end
+
+  # Display search results
+  def self.display_search_results(results)
+    if results.empty?
+      display_no_results
+    else
+      display_model_results(results)
+    end
+  end
+
+  # Display message when no results found
+  def self.display_no_results
+    puts "❌ No models found matching your criteria"
+    puts "\n💡 Try relaxing your requirements or use different filters"
+  end
+
+  # Display list of model results
+  def self.display_model_results(results)
+    results.each_with_index do |(model_id, specs), index|
+      next unless specs
+
+      specs = OpenRouter::ModelRegistry.get_model_info(model_id) if model_id.is_a?(String) && !specs
+      display_model_info(model_id, specs, index)
+    end
+
+    puts "=" * 80
+    puts "Found #{results.size} matching model#{"s" if results.size != 1}"
+  end
+
+  # Display information for a single model
+  def self.display_model_info(model_id, specs, index)
+    puts "#{(index + 1).to_s.rjust(3)}. #{model_id}"
+    puts "     Name: #{specs[:name]}" if specs[:name]
+    puts "     Cost: $#{format("%.6f", specs[:cost_per_1k_tokens][:input])}/1k input, " \
+         "$#{format("%.6f", specs[:cost_per_1k_tokens][:output])}/1k output"
+    puts "     Context: #{format_number_with_commas(specs[:context_length])} tokens"
+    puts "     Capabilities: #{specs[:capabilities].join(", ")}"
+    puts "     Tier: #{specs[:performance_tier]}"
+
+    display_release_date(specs[:created_at]) if specs[:created_at]
+    puts
+  end
+
+  # Display release date for a model
+  def self.display_release_date(created_at)
+    created = Time.at(created_at).strftime("%Y-%m-%d")
+    puts "     Released: #{created}"
+  end
+
+  # Format number with comma separators
+  def self.format_number_with_commas(number)
+    number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+  end
+
+  # Helper methods for search task
+  def self.filter_by_provider_preferences(candidates, preferences)
+    return candidates if preferences.empty?
+
+    filtered = candidates.dup
+
+    if preferences[:required]
+      required_providers = preferences[:required]
+      filtered = filtered.select do |model_id, _|
+        provider = model_id.split("/").first
+        required_providers.include?(provider)
+      end
+    end
+
+    if preferences[:avoided]
+      avoided_providers = preferences[:avoided]
+      filtered = filtered.reject do |model_id, _|
+        provider = model_id.split("/").first
+        avoided_providers.include?(provider)
+      end
+    end
+
+    filtered
+  end
+
+  def self.sort_by_strategy(candidates, strategy)
+    case strategy
+    when :cost
+      candidates.sort_by { |_, specs| specs[:cost_per_1k_tokens][:input] }
+    when :performance
+      candidates.sort_by do |_, specs|
+        [specs[:performance_tier] == :premium ? 0 : 1, specs[:cost_per_1k_tokens][:input]]
+      end
+    when :latest
+      candidates.sort_by { |_, specs| -(specs[:created_at] || 0).to_i }
+    when :context
+      candidates.sort_by { |_, specs| -(specs[:context_length] || 0).to_i }
+    else
+      candidates.sort_by { |_, specs| specs[:cost_per_1k_tokens][:input] }
+    end
+  end
+end

data/SECURITY.md

@@ -0,0 +1,150 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of OpenRouter Enhanced seriously. If you believe you have found a security vulnerability, please report it to us as described below.
+
+### Where to Report
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them via email to:
+
+- **Email**: opensource@ericstiens.dev (replace with actual contact)
+- **Subject Line**: `[SECURITY] OpenRouter Enhanced - Brief Description`
+
+Alternatively, you can use GitHub's private vulnerability reporting feature:
+
+1. Go to the repository's Security tab
+2. Click "Report a vulnerability"
+3. Fill out the form with details
+
+### What to Include
+
+Please include the following information in your report:
+
+- Type of issue
+- Full paths of source file(s) related to the issue
+- Location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit it
+
+### What to Expect
+
+After you submit a report:
+
+1. **Acknowledgment**: We will acknowledge receipt of your vulnerability report within 48 hours.
+
+2. **Initial Assessment**: We will perform an initial assessment and respond with our evaluation within 5 business days.
+
+3. **Updates**: We will keep you informed about our progress towards resolving the issue.
+
+4. **Resolution**: Once the issue is resolved, we will:
+   - Release a security patch
+   - Publicly disclose the vulnerability (with credit to you, if desired)
+   - Add the issue to our security advisories
+
+### Disclosure Policy
+
+- We ask that you do not publicly disclose the vulnerability until we have had a chance to address it.
+- We will coordinate with you on the disclosure timeline.
+- We aim to resolve critical issues within 30 days of acknowledgment.
+
+## Security Best Practices for Users
+
+When using the OpenRouter Enhanced gem:
+
+1. **API Keys**:
+   - Never hardcode API keys in your code
+   - Use environment variables or secure credential storage
+   - Rotate API keys regularly
+   - Never commit API keys to version control
+
+2. **Dependency Management**:
+   - Keep the gem updated to the latest version
+   - Regularly run `bundle update` to get security patches
+   - Monitor security advisories for dependencies
+
+3. **Input Validation**:
+   - Validate all user inputs before passing to the gem
+   - Be cautious with tool calling and structured outputs from untrusted sources
+   - Sanitize data before execution
+
+4. **Network Security**:
+   - Use HTTPS for all API communications (enabled by default)
+   - Verify SSL certificates (enabled by default)
+   - Be cautious with proxy configurations
+
+5. **Error Handling**:
+   - Avoid exposing detailed error messages to end users
+   - Log errors securely without exposing sensitive data
+   - Monitor for unusual error patterns
+
+## Known Security Considerations
+
+### API Key Storage
+
+The gem requires an OpenRouter API key for operation. Users are responsible for:
+- Securely storing their API keys
+- Not committing keys to version control
+- Using environment variables or secure vaults
+
+### Tool Calling
+
+When using tool calling features:
+- Validate tool arguments before execution
+- Implement proper authorization checks
+- Sandbox tool execution where appropriate
+- Never execute arbitrary code from LLM responses without validation
+
+### Data Privacy
+
+When using the gem:
+- Be aware that data is sent to OpenRouter's API
+- Review OpenRouter's privacy policy and terms of service
+- Implement appropriate data handling for sensitive information
+- Consider data residency requirements for your use case
+
+## Security Update Process
+
+1. Security issues are prioritized based on severity and impact
+2. Patches are developed and tested in private
+3. Security advisories are prepared
+4. Patches are released via a new gem version
+5. Security advisories are published
+6. Users are notified through:
+   - GitHub Security Advisories
+   - RubyGems security notifications
+   - Project changelog
+   - Release notes
+
+## Bug Bounty Program
+
+We currently do not have a bug bounty program. However, we greatly appreciate security researchers who responsibly disclose vulnerabilities and will publicly acknowledge their contributions (with permission).
+
+## Contact
+
+For general security questions or concerns, please use the same contact methods as vulnerability reporting.
+
+For non-security-related issues, please use the standard GitHub issues process.
+
+## Acknowledgments
+
+We would like to thank the following individuals for responsibly disclosing security issues:
+
+(This section will be updated as security issues are responsibly disclosed and resolved)
+
+---
+
+Last updated: 2025-10-05

data/VCR_CONFIGURATION.md

@@ -0,0 +1,80 @@
+# VCR Configuration
+
+This document explains the VCR (Video Cassette Recorder) configuration for testing external API interactions.
+
+## Configuration Overview
+
+The VCR setup is configured in `spec/support/vcr.rb` with the following key features:
+
+### Environment-Based Recording Modes
+
+- **CI Environment** (`CI=true`, `GITHUB_ACTIONS=true`, or `CONTINUOUS_INTEGRATION=true`):
+  - Recording mode: `:none` (never record, use existing cassettes only)
+  - HTTP connections: Disabled (WebMock blocks all external requests)
+  - API Key: Uses dummy key from environment variable
+
+- **Development Environment**:
+  - Recording mode: `:once` (record if cassette doesn't exist, otherwise use existing)
+  - HTTP connections: Allowed when no cassette exists (enables recording)
+  - API Key: Uses real API key from environment variable
+
+### Override Options
+
+- `VCR_RECORD_ALL=true`: Re-record all cassettes (development only)
+- `VCR_RECORD_NEW=true`: Record new episodes only (development only)
+
+### API Key Handling
+
+- In CI: Uses dummy key `"dummy-api-key-for-testing-do-not-use"` set in GitHub Actions
+- In development: Uses real API key from `OPENROUTER_API_KEY` environment variable
+- All API keys are filtered from recordings for security
+
+### Cassette Storage
+
+Cassettes are stored in `spec/fixtures/vcr_cassettes/` and contain recorded HTTP interactions.
+
+## Usage
+
+### Running Tests with Different Modes
+
+```bash
+# Use existing cassettes (CI mode)
+CI=true bundle exec rspec spec/vcr/
+
+# Record new cassettes (development)
+OPENROUTER_API_KEY=your-real-key bundle exec rspec spec/vcr/
+
+# Re-record all cassettes
+VCR_RECORD_ALL=true OPENROUTER_API_KEY=your-real-key bundle exec rspec spec/vcr/
+```
+
+### Test Tagging
+
+Tests use `:vcr` metadata tag to enable VCR recording:
+
+```ruby
+RSpec.describe "API Tests", :vcr do
+  it "makes API call", vcr: { cassette_name: "custom_name" } do
+    # Test code that makes HTTP requests
+  end
+end
+```
+
+## Security
+
+- All API keys are automatically filtered from cassette recordings
+- Real API keys are never committed to the repository
+- CI uses dummy keys that cannot access real services
+
+## WebMock Integration
+
+VCR hooks into WebMock to:
+- Block external HTTP requests by default
+- Allow requests only when VCR cassettes are recording
+- Ensure tests are deterministic and don't depend on external services
+
+This configuration ensures that:
+1. Tests are fast and reliable (no external dependencies)
+2. CI environments never make real API calls
+3. Development can record new interactions when needed
+4. Security is maintained through API key filtering