open_router_enhanced 1.0.0

data/examples/basic_completion.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "open_router"
+
+# Basic completion example using OpenRouter Enhanced gem
+#
+# This example demonstrates:
+# - Simple client initialization
+# - Basic chat completion
+# - Accessing response data
+# - Cost tracking
+
+# Configure the client
+OpenRouter.configure do |config|
+  config.access_token = ENV["OPENROUTER_API_KEY"]
+  config.site_name = "Basic Completion Example"
+  config.site_url = "https://github.com/yourusername/open_router_enhanced"
+end
+
+# Initialize client
+client = OpenRouter::Client.new
+
+puts "=" * 60
+puts "Basic Completion Example"
+puts "=" * 60
+
+# Simple completion
+puts "\n1. Simple Chat Completion"
+puts "-" * 60
+
+messages = [
+  { role: "user", content: "What is the capital of France?" }
+]
+
+response = client.complete(
+  messages,
+  model: "openai/gpt-4o-mini"
+)
+
+puts "Response: #{response.content}"
+puts "Model: #{response.model}"
+puts "Tokens used: #{response.total_tokens}"
+
+# Multi-turn conversation
+puts "\n2. Multi-turn Conversation"
+puts "-" * 60
+
+conversation = [
+  { role: "user", content: "Tell me a short joke about programming" }
+]
+
+response = client.complete(
+  conversation,
+  model: "anthropic/claude-3-haiku"
+)
+
+puts "Assistant: #{response.content}"
+conversation << { role: "assistant", content: response.content }
+
+# Follow-up question
+conversation << { role: "user", content: "Explain why that's funny" }
+
+response = client.complete(
+  conversation,
+  model: "anthropic/claude-3-haiku"
+)
+
+puts "\nExplanation: #{response.content}"
+
+# System message
+puts "\n3. Using System Messages"
+puts "-" * 60
+
+messages = [
+  { role: "system", content: "You are a helpful but concise assistant. Keep responses under 50 words." },
+  { role: "user", content: "Explain quantum computing" }
+]
+
+response = client.complete(
+  messages,
+  model: "openai/gpt-4o-mini",
+  extras: { max_tokens: 100 }
+)
+
+puts "Concise response: #{response.content}"
+puts "Completion tokens: #{response.completion_tokens}"
+
+# Error handling
+puts "\n4. Error Handling"
+puts "-" * 60
+
+begin
+  client.complete(
+    [{ role: "user", content: "Hello!" }],
+    model: "invalid/model-name"
+  )
+rescue OpenRouter::ServerError => e
+  puts "Caught error: #{e.message}"
+end
+
+# Response metadata
+puts "\n5. Response Metadata"
+puts "-" * 60
+
+response = client.complete(
+  [{ role: "user", content: "Say 'Hello, World!'" }],
+  model: "openai/gpt-4o-mini"
+)
+
+puts "Response ID: #{response.id}"
+puts "Model: #{response.model}"
+puts "Provider: #{response.provider}" if response.provider
+puts "Finish reason: #{response.finish_reason}"
+puts "Created at: #{Time.at(response.created).strftime("%Y-%m-%d %H:%M:%S")}" if response.created
+puts "Prompt tokens: #{response.prompt_tokens}"
+puts "Completion tokens: #{response.completion_tokens}"
+puts "Total tokens: #{response.total_tokens}"
+puts "Cached tokens: #{response.cached_tokens}"
+
+puts "\n#{"=" * 60}"
+puts "Example completed successfully!"
+puts "=" * 60

data/examples/model_selection_example.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example demonstrating the ModelSelector functionality
+# Run this with: ruby -I lib examples/model_selection_example.rb
+
+require "open_router"
+
+# Configure OpenRouter (you would set your actual API key)
+OpenRouter.configure do |config|
+  config.access_token = ENV["OPENROUTER_API_KEY"] || "your-api-key-here"
+  config.site_name = "ModelSelector Example"
+  config.site_url = "https://example.com"
+end
+
+puts "🤖 OpenRouter ModelSelector Examples"
+puts "=" * 50
+
+# Example 1: Basic cost optimization
+puts "\n1. Basic cost optimization:"
+selector = OpenRouter::ModelSelector.new
+cheapest_model = selector.optimize_for(:cost).choose
+
+if cheapest_model
+  puts "   Cheapest model: #{cheapest_model}"
+  cost_info = OpenRouter::ModelRegistry.get_model_info(cheapest_model)
+  puts "   Cost: $#{cost_info[:cost_per_1k_tokens][:input]} per 1k input tokens"
+else
+  puts "   No models available"
+end
+
+# Example 2: Find models with specific capabilities
+puts "\n2. Models with function calling capability:"
+function_models = OpenRouter::ModelSelector.new
+                                           .require(:function_calling)
+                                           .optimize_for(:cost)
+                                           .choose_with_fallbacks(limit: 3)
+
+if function_models.any?
+  function_models.each_with_index do |model, i|
+    puts "   #{i + 1}. #{model}"
+  end
+else
+  puts "   No models with function calling found"
+end
+
+# Example 3: Budget-constrained selection with multiple requirements
+puts "\n3. Budget-constrained selection ($0.01 max, with vision):"
+budget_model = OpenRouter::ModelSelector.new
+                                        .within_budget(max_cost: 0.01)
+                                        .require(:vision)
+                                        .optimize_for(:cost)
+                                        .choose
+
+if budget_model
+  puts "   Selected: #{budget_model}"
+  model_info = OpenRouter::ModelRegistry.get_model_info(budget_model)
+  puts "   Capabilities: #{model_info[:capabilities].join(", ")}"
+  puts "   Cost: $#{model_info[:cost_per_1k_tokens][:input]} per 1k input tokens"
+else
+  puts "   No models found within budget with vision capability"
+end
+
+# Example 4: Provider preferences
+puts "\n4. Prefer specific providers:"
+provider_model = OpenRouter::ModelSelector.new
+                                          .prefer_providers("anthropic", "openai")
+                                          .require(:function_calling)
+                                          .optimize_for(:cost)
+                                          .choose
+
+if provider_model
+  puts "   Selected: #{provider_model}"
+  provider = provider_model.split("/").first
+  puts "   Provider: #{provider}"
+else
+  puts "   No models found from preferred providers"
+end
+
+# Example 5: Latest models with fallback
+puts "\n5. Latest models (with graceful fallback):"
+latest_model = OpenRouter::ModelSelector.new
+                                        .optimize_for(:latest)
+                                        .require(:function_calling)
+                                        .min_context(100_000)
+                                        .choose_with_fallback
+
+if latest_model
+  puts "   Selected: #{latest_model}"
+  model_info = OpenRouter::ModelRegistry.get_model_info(latest_model)
+  puts "   Context length: #{model_info[:context_length]} tokens"
+  puts "   Released: #{Time.at(model_info[:created_at])}"
+else
+  puts "   No suitable models found"
+end
+
+# Example 6: Complex chaining example
+puts "\n6. Complex requirements with method chaining:"
+complex_selector = OpenRouter::ModelSelector.new
+                                            .optimize_for(:performance)
+                                            .require(:function_calling, :structured_outputs)
+                                            .within_budget(max_cost: 0.05)
+                                            .avoid_patterns("*-free", "*-preview")
+                                            .prefer_providers("anthropic", "openai")
+
+models = complex_selector.choose_with_fallbacks(limit: 2)
+if models.any?
+  puts "   Found #{models.length} suitable models:"
+  models.each_with_index do |model, i|
+    model_info = OpenRouter::ModelRegistry.get_model_info(model)
+    puts "   #{i + 1}. #{model} (#{model_info[:performance_tier]} tier)"
+  end
+else
+  puts "   No models meet all requirements"
+end
+
+# Example 7: Cost estimation
+puts "\n7. Cost estimation:"
+if cheapest_model
+  estimated_cost = OpenRouter::ModelSelector.new.estimate_cost(
+    cheapest_model,
+    input_tokens: 2000,
+    output_tokens: 500
+  )
+  puts "   Cost for 2000 input + 500 output tokens with #{cheapest_model}:"
+  puts "   $#{estimated_cost.round(6)}"
+end
+
+# Example 8: Selection criteria inspection
+puts "\n8. Selection criteria:"
+criteria = OpenRouter::ModelSelector.new
+                                    .optimize_for(:cost)
+                                    .require(:function_calling)
+                                    .within_budget(max_cost: 0.02)
+                                    .selection_criteria
+
+puts "   Strategy: #{criteria[:strategy]}"
+puts "   Required capabilities: #{criteria[:requirements][:capabilities]}"
+puts "   Max cost: $#{criteria[:requirements][:max_input_cost]}"
+
+puts "\n✅ ModelSelector examples completed!"

data/examples/observability_example.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "open_router"
+
+# Observability example using OpenRouter Enhanced gem
+#
+# This example demonstrates:
+# - Usage tracking and analytics
+# - Cost monitoring
+# - Performance metrics
+# - Callback system for observability
+# - Export capabilities
+
+# Configure the client
+OpenRouter.configure do |config|
+  config.access_token = ENV["OPENROUTER_API_KEY"]
+  config.site_name = "Observability Example"
+  config.site_url = "https://github.com/yourusername/open_router_enhanced"
+end
+
+puts "=" * 60
+puts "Observability & Usage Tracking Example"
+puts "=" * 60
+
+# Example 1: Basic usage tracking
+puts "\n1. Basic Usage Tracking"
+puts "-" * 60
+
+client = OpenRouter::Client.new(track_usage: true)
+
+# Make some requests
+3.times do |i|
+  response = client.complete(
+    [{ role: "user", content: "Count to #{i + 1}" }],
+    model: "openai/gpt-4o-mini"
+  )
+  puts "Request #{i + 1}: #{response.total_tokens} tokens"
+end
+
+# View usage summary
+tracker = client.usage_tracker
+puts "\nUsage Summary:"
+puts "  Total requests: #{tracker.request_count}"
+puts "  Total tokens: #{tracker.total_tokens}"
+puts "  Prompt tokens: #{tracker.total_prompt_tokens}"
+puts "  Completion tokens: #{tracker.total_completion_tokens}"
+puts "  Cached tokens: #{tracker.total_cached_tokens}"
+puts "  Total cost: $#{tracker.total_cost.round(4)}"
+puts "  Average tokens/request: #{tracker.average_tokens_per_request.round(0)}"
+puts "  Average cost/request: $#{tracker.average_cost_per_request.round(4)}"
+
+# Example 2: Per-model breakdown
+puts "\n2. Per-Model Usage Breakdown"
+puts "-" * 60
+
+client.usage_tracker.reset! # Start fresh
+
+# Use different models
+client.complete([{ role: "user", content: "Say hi" }], model: "openai/gpt-4o-mini")
+client.complete([{ role: "user", content: "Say hi" }], model: "anthropic/claude-3-haiku")
+client.complete([{ role: "user", content: "Say hi" }], model: "openai/gpt-4o-mini")
+
+# View per-model stats
+puts "\nModel usage breakdown:"
+client.usage_tracker.model_usage.each do |model, stats|
+  puts "\n  #{model}:"
+  puts "    Requests: #{stats[:requests]}"
+  puts "    Tokens: #{stats[:prompt_tokens] + stats[:completion_tokens]}"
+  puts "    Cost: $#{stats[:cost].round(4)}"
+end
+
+puts "\nMost used model: #{client.usage_tracker.most_used_model}"
+puts "Most expensive model: #{client.usage_tracker.most_expensive_model}"
+
+# Example 3: Cache hit rate tracking
+puts "\n3. Cache Hit Rate Tracking"
+puts "-" * 60
+
+client.usage_tracker.reset!
+
+# Make repeated requests (OpenRouter may cache)
+3.times do
+  client.complete(
+    [{ role: "user", content: "What is 2+2?" }],
+    model: "openai/gpt-4o-mini"
+  )
+end
+
+puts "Cache hit rate: #{client.usage_tracker.cache_hit_rate.round(2)}%"
+puts "Cached tokens: #{client.usage_tracker.total_cached_tokens}"
+
+# Example 4: Performance metrics
+puts "\n4. Performance Metrics"
+puts "-" * 60
+
+tracker = client.usage_tracker
+duration = tracker.session_duration
+
+puts "Session duration: #{duration.round(2)} seconds"
+puts "Tokens per second: #{tracker.tokens_per_second.round(2)}"
+puts "Average tokens per request: #{tracker.average_tokens_per_request.round(0)}"
+
+# Example 5: Callback-based monitoring
+puts "\n5. Callback-Based Monitoring"
+puts "-" * 60
+
+monitored_client = OpenRouter::Client.new(track_usage: true)
+
+# Set up monitoring callbacks
+monitored_client.on(:before_request) do |params|
+  puts "→ Request starting (model: #{params[:model]})"
+end
+
+monitored_client.on(:after_response) do |response|
+  tokens = response.total_tokens
+  cost = response.cost_estimate
+  puts "← Response received: #{tokens} tokens" + (cost ? ", $#{cost.round(4)}" : "")
+end
+
+monitored_client.on(:on_error) do |error|
+  puts "✗ Error occurred: #{error.message}"
+end
+
+# Make some requests
+monitored_client.complete(
+  [{ role: "user", content: "Hello!" }],
+  model: "openai/gpt-4o-mini"
+)
+
+# Example 6: Cost tracking and budgets
+puts "\n6. Cost Tracking & Budget Monitoring"
+puts "-" * 60
+
+budget_client = OpenRouter::Client.new(track_usage: true)
+budget_limit = 0.10 # $0.10 budget
+
+budget_client.on(:after_response) do |_response|
+  total_cost = budget_client.usage_tracker.total_cost
+
+  puts "⚠️  Warning: 80% of budget used ($#{total_cost.round(4)}/$#{budget_limit})" if total_cost > budget_limit * 0.8
+
+  puts "🛑 Budget exceeded! Total: $#{total_cost.round(4)}" if total_cost > budget_limit
+end
+
+# Make requests
+5.times do |i|
+  budget_client.complete(
+    [{ role: "user", content: "Short response #{i}" }],
+    model: "openai/gpt-4o-mini",
+    extras: { max_tokens: 10 }
+  )
+end
+
+# Example 7: Export usage data
+puts "\n7. Export Usage Data"
+puts "-" * 60
+
+# Print detailed summary
+puts "\nDetailed summary:"
+client.usage_tracker.print_summary
+
+# Export as CSV
+csv_data = client.usage_tracker.export_csv
+puts "\nCSV export (first 200 chars):"
+puts "#{csv_data[0...200]}..."
+
+# Get structured summary
+summary = client.usage_tracker.summary
+puts "\nStructured summary available with keys:"
+puts summary.keys.inspect
+
+# Example 8: Request history
+puts "\n8. Request History"
+puts "-" * 60
+
+history_client = OpenRouter::Client.new(track_usage: true)
+
+# Make some requests
+history_client.complete([{ role: "user", content: "Test 1" }], model: "openai/gpt-4o-mini")
+history_client.complete([{ role: "user", content: "Test 2" }], model: "anthropic/claude-3-haiku")
+history_client.complete([{ role: "user", content: "Test 3" }], model: "openai/gpt-4o-mini")
+
+# View recent history
+recent = history_client.usage_tracker.history(limit: 5)
+puts "\nRecent requests:"
+recent.each_with_index do |entry, i|
+  puts "  #{i + 1}. #{entry[:model]} - #{entry[:prompt_tokens] + entry[:completion_tokens]} tokens at #{entry[:timestamp].strftime("%H:%M:%S")}"
+end
+
+puts "\n#{"=" * 60}"
+puts "Observability examples completed!"
+puts "=" * 60
+puts "\nKey Takeaways:"
+puts "  • Use track_usage: true to enable automatic tracking"
+puts "  • Access tracker via client.usage_tracker"
+puts "  • Set up callbacks for real-time monitoring"
+puts "  • Export data as CSV for external analysis"
+puts "  • Monitor costs and set budget alerts"
+puts "=" * 60

data/examples/prompt_template_example.rb

@@ -0,0 +1,184 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example demonstrating the PromptTemplate system
+# Run this with: ruby -I lib examples/prompt_template_example.rb
+
+require "open_router"
+
+puts "🎯 Prompt Template Examples"
+puts "=" * 60
+
+# Create a client
+client = OpenRouter::Client.new(access_token: ENV["OPENROUTER_API_KEY"])
+
+# Example 1: Simple template
+puts "\n1. Simple Template:"
+puts "-" * 40
+
+translation_template = OpenRouter::PromptTemplate.new(
+  template: "Translate the following {language_from} text to {language_to}:\n\n'{text}'",
+  input_variables: %i[language_from language_to text]
+)
+
+prompt = translation_template.format(
+  language_from: "English",
+  language_to: "French",
+  text: "Hello, how are you today?"
+)
+
+puts prompt
+puts "\nFormatted prompt ready for OpenRouter API!"
+
+# Example 2: Few-shot template for consistent formatting
+puts "\n2. Few-Shot Template (Learning from Examples):"
+puts "-" * 40
+
+sentiment_template = OpenRouter::PromptTemplate.new(
+  prefix: "Classify the sentiment of these messages as 'positive', 'negative', or 'neutral'.",
+  examples: [
+    { text: "I love this product! It's amazing!", sentiment: "positive" },
+    { text: "This is terrible, waste of money.", sentiment: "negative" },
+    { text: "It works as expected.", sentiment: "neutral" }
+  ],
+  example_template: "Text: {text}\nSentiment: {sentiment}",
+  suffix: "Text: {input}\nSentiment:",
+  input_variables: [:input]
+)
+
+prompt = sentiment_template.format(input: "The service was okay, nothing special.")
+puts prompt
+
+# Example 3: Chat-style template with role markers
+puts "\n3. Chat-Style Template (Multi-role conversation):"
+puts "-" * 40
+
+chat_template = OpenRouter::PromptTemplate.new(
+  template: <<~TEMPLATE,
+    System: You are a helpful coding assistant specializing in {language}.
+    Always provide clear explanations and working code examples.
+
+    User: {question}
+  TEMPLATE
+  input_variables: %i[language question]
+)
+
+# Convert to messages array for OpenRouter API
+messages = chat_template.to_messages(
+  language: "Ruby",
+  question: "How do I read a JSON file and parse it?"
+)
+
+puts "Messages array for API:"
+puts messages.inspect
+
+# Example 4: Using DSL for template creation
+puts "\n4. DSL-Style Template Creation:"
+puts "-" * 40
+
+code_review_template = OpenRouter::PromptTemplate.build do
+  template <<~PROMPT
+    Review this {language} code for:
+    - Code quality and best practices
+    - Potential bugs or issues
+    - Performance considerations
+    - Suggestions for improvement
+
+    Code to review:
+    ```{language}
+    {code}
+    ```
+
+    Provide your review in a structured format.
+  PROMPT
+  variables :language, :code
+end
+
+review_prompt = code_review_template.format(
+  language: "ruby",
+  code: "def add(a, b)\n  return a + b\nend"
+)
+
+puts review_prompt
+
+# Example 5: Partial templates (pre-filling some variables)
+puts "\n5. Partial Templates (Pre-filled Variables):"
+puts "-" * 40
+
+qa_template = OpenRouter::PromptTemplate.new(
+  template: "Context: {context}\n\nQuestion: {question}\n\nAnswer:",
+  input_variables: %i[context question]
+)
+
+# Create a partial with context pre-filled
+science_qa = qa_template.partial(
+  context: "Water boils at 100°C (212°F) at sea level atmospheric pressure."
+)
+
+# Now only need to provide the question
+prompt1 = science_qa.format(question: "What is the boiling point of water in Celsius?")
+prompt2 = science_qa.format(question: "How does altitude affect boiling point?")
+
+puts "First question:\n#{prompt1}\n"
+puts "Second question:\n#{prompt2}"
+
+# Example 6: Factory methods for common patterns
+puts "\n6. Factory Methods (Convenient Creation):"
+puts "-" * 40
+
+# Simple template
+simple = OpenRouter::Prompt.template(
+  "Summarize this text in {word_count} words:\n\n{text}",
+  variables: %i[word_count text]
+)
+
+# Few-shot template
+translation = OpenRouter::Prompt.few_shot(
+  prefix: "Translate from English to Spanish:",
+  examples: [
+    { english: "Hello", spanish: "Hola" },
+    { english: "Goodbye", spanish: "Adiós" }
+  ],
+  example_template: "{english} → {spanish}",
+  suffix: "{input} →",
+  variables: [:input]
+)
+
+puts simple.format(word_count: 50, text: "Long text here...")
+puts "\n"
+puts translation.format(input: "Thank you")
+
+# Example 7: Integration with OpenRouter Client (if API key is set)
+puts "\n7. Using with OpenRouter Client:"
+puts "-" * 40
+
+if ENV["OPENROUTER_API_KEY"]
+  story_template = OpenRouter::PromptTemplate.new(
+    template: "Write a short story about {character} who {plot}. Make it {tone}.",
+    input_variables: %i[character plot tone]
+  )
+
+  messages = story_template.to_messages(
+    character: "a robot",
+    plot: "discovers emotions",
+    tone: "heartwarming"
+  )
+
+  begin
+    response = client.complete(messages, model: "openai/gpt-4o-mini")
+    puts "AI Response:\n#{response.content}"
+  rescue StandardError
+    puts "API call would be made with messages: #{messages.inspect}"
+    puts "(Set OPENROUTER_API_KEY to test real API calls)"
+  end
+else
+  puts "Set OPENROUTER_API_KEY environment variable to test with real API"
+end
+
+puts "\n✅ Prompt template examples completed!"
+puts "\n💡 Key Benefits:"
+puts "   - Consistent prompt formatting"
+puts "   - Variable validation"
+puts "   - Few-shot learning support"
+puts "   - Easy chat message formatting"
+puts "   - Reusable templates with partials"