open_router_enhanced 1.0.0

data/examples/smart_completion_example.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example demonstrating the Client's smart completion methods
+# Run this with: ruby -I lib examples/smart_completion_example.rb
+
+require "open_router"
+
+# NOTE: This example shows the interface but won't make real API calls
+# To test with real API calls, set your OPENROUTER_API_KEY environment variable
+
+puts "🧠 Smart Completion Examples"
+puts "=" * 40
+
+# Create a client
+client = OpenRouter::Client.new
+
+# Example 1: Using the select_model helper
+puts "\n1. Using select_model helper:"
+selector = client.select_model
+                 .optimize_for(:cost)
+                 .require(:function_calling)
+                 .within_budget(max_cost: 0.01)
+
+selected_model = selector.choose
+puts "   Selected model: #{selected_model}"
+
+# Example 2: Smart completion with requirements
+puts "\n2. Smart completion interface:"
+requirements = {
+  capabilities: [:function_calling],
+  max_input_cost: 0.01,
+  providers: {
+    prefer: %w[anthropic openai],
+    avoid: ["google"]
+  }
+}
+
+messages = [
+  { role: "user", content: "What is the weather like today?" }
+]
+
+puts "   Requirements: #{requirements}"
+puts "   Messages: #{messages}"
+
+# NOTE: This would make a real API call if OPENROUTER_API_KEY is set
+# For demo purposes, we'll show what model would be selected
+selector_for_smart = OpenRouter::ModelSelector.new
+                                              .optimize_for(:cost)
+                                              .require(*requirements[:capabilities])
+                                              .within_budget(max_cost: requirements[:max_input_cost])
+                                              .prefer_providers(*requirements[:providers][:prefer])
+                                              .avoid_providers(*requirements[:providers][:avoid])
+
+smart_model = selector_for_smart.choose
+puts "   Would use model: #{smart_model}"
+
+# Example 3: Smart completion with fallback
+puts "\n3. Smart completion with fallback:"
+fallback_requirements = {
+  capabilities: %i[function_calling vision],
+  max_input_cost: 0.005, # Very restrictive budget
+  min_context_length: 100_000
+}
+
+fallback_selector = OpenRouter::ModelSelector.new
+                                             .optimize_for(:cost)
+                                             .require(*fallback_requirements[:capabilities])
+                                             .within_budget(max_cost: fallback_requirements[:max_input_cost])
+                                             .min_context(fallback_requirements[:min_context_length])
+
+fallback_models = fallback_selector.choose_with_fallbacks(limit: 3)
+puts "   Fallback candidates: #{fallback_models}"
+
+# Example 4: Demonstrating graceful degradation
+puts "\n4. Graceful degradation example:"
+degradation_model = fallback_selector.choose_with_fallback
+puts "   Graceful fallback selected: #{degradation_model}"
+
+# Example 5: Show the actual method signatures
+puts "\n5. Available Client methods:"
+puts "   - client.select_model() -> ModelSelector"
+puts "   - client.smart_complete(messages, requirements:, optimization:)"
+puts "   - client.smart_complete_with_fallback(messages, requirements:, max_retries:)"
+
+puts "\n✅ Smart completion examples completed!"
+puts "\n💡 To test with real API calls:"
+puts "   export OPENROUTER_API_KEY=your_key_here"
+puts "   ruby -I lib examples/smart_completion_example.rb"

data/examples/streaming_example.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "open_router"
+
+# Streaming example using OpenRouter Enhanced gem
+#
+# This example demonstrates:
+# - Streaming responses
+# - Real-time token processing
+# - Callback-based streaming
+# - Response accumulation
+
+# Configure the client
+OpenRouter.configure do |config|
+  config.access_token = ENV["OPENROUTER_API_KEY"]
+  config.site_name = "Streaming Example"
+  config.site_url = "https://github.com/yourusername/open_router_enhanced"
+end
+
+# Initialize streaming client
+client = OpenRouter::StreamingClient.new
+
+puts "=" * 60
+puts "Streaming Example"
+puts "=" * 60
+
+# Example 1: Basic streaming with block
+puts "\n1. Basic Streaming"
+puts "-" * 60
+puts "Assistant: "
+
+messages = [
+  { role: "user", content: "Count from 1 to 10, saying each number on a new line." }
+]
+
+accumulated = ""
+client.stream(messages, model: "openai/gpt-4o-mini") do |chunk|
+  content = chunk.dig("choices", 0, "delta", "content")
+  if content
+    print content
+    accumulated += content
+  end
+end
+
+puts "\n\nFull response:\n#{accumulated}"
+
+# Example 2: Streaming with callbacks
+puts "\n2. Streaming with Callbacks"
+puts "-" * 60
+
+full_response = ""
+
+client.on(:stream_start) do
+  puts "Stream started..."
+end
+
+client.on(:stream_chunk) do |chunk|
+  content = chunk.dig("choices", 0, "delta", "content")
+  if content
+    print content
+    full_response += content
+  end
+end
+
+client.on(:stream_end) do |response|
+  puts "\n\nStream completed!"
+  puts "Total tokens: #{response.usage&.dig("total_tokens") || "N/A"}"
+end
+
+client.on(:stream_error) do |error|
+  puts "\nError during streaming: #{error}"
+end
+
+puts "\nAssistant: "
+client.stream(
+  [{ role: "user", content: "Write a haiku about coding" }],
+  model: "anthropic/claude-3-haiku"
+)
+
+# Example 3: Streaming with tool calls
+puts "\n\n3. Streaming with Tool Calls"
+puts "-" * 60
+
+tools = [
+  OpenRouter::Tool.define do
+    name "get_weather"
+    description "Get current weather for a location"
+    parameters do
+      string :location, required: true, description: "City name"
+      string :units, enum: %w[celsius fahrenheit], description: "Temperature units"
+    end
+  end
+]
+
+puts "Requesting weather..."
+client.stream(
+  [{ role: "user", content: "What's the weather in Tokyo?" }],
+  model: "anthropic/claude-3.5-sonnet",
+  tools: tools
+) do |chunk|
+  # Handle tool calls in streaming
+  tool_calls = chunk.dig("choices", 0, "delta", "tool_calls")
+  tool_calls&.each do |tc|
+    puts "Tool call detected: #{tc.dig("function", "name")}"
+  end
+
+  # Handle content
+  content = chunk.dig("choices", 0, "delta", "content")
+  print content if content
+end
+
+# Example 4: Streaming with metadata collection
+puts "\n\n4. Streaming with Metadata Collection"
+puts "-" * 60
+
+metadata = {
+  chunks_received: 0,
+  total_content_length: 0,
+  start_time: Time.now,
+  finish_reason: nil
+}
+
+accumulated_response = ""
+
+client.stream(
+  [{ role: "user", content: "Explain async/await in JavaScript in one paragraph" }],
+  model: "openai/gpt-4o-mini"
+) do |chunk|
+  metadata[:chunks_received] += 1
+
+  content = chunk.dig("choices", 0, "delta", "content")
+  if content
+    metadata[:total_content_length] += content.length
+    accumulated_response += content
+    print content
+  end
+
+  finish_reason = chunk.dig("choices", 0, "finish_reason")
+  metadata[:finish_reason] = finish_reason if finish_reason
+end
+
+metadata[:end_time] = Time.now
+metadata[:duration] = metadata[:end_time] - metadata[:start_time]
+
+puts "\n\nMetadata:"
+puts "  Chunks received: #{metadata[:chunks_received]}"
+puts "  Content length: #{metadata[:total_content_length]} characters"
+puts "  Duration: #{metadata[:duration].round(2)} seconds"
+puts "  Finish reason: #{metadata[:finish_reason]}"
+
+# Example 5: Streaming long-form content
+puts "\n\n5. Streaming Long-Form Content"
+puts "-" * 60
+
+puts "Generating story..."
+print "\n"
+
+client.stream(
+  [
+    { role: "system", content: "You are a creative storyteller." },
+    { role: "user", content: "Write a very short 2-sentence story about a robot learning to paint." }
+  ],
+  model: "anthropic/claude-3-haiku",
+  extras: { max_tokens: 200 }
+) do |chunk|
+  content = chunk.dig("choices", 0, "delta", "content")
+  print content if content
+  $stdout.flush # Ensure immediate output
+end
+
+puts "\n\n#{"=" * 60}"
+puts "Streaming examples completed!"
+puts "=" * 60
+
+# Clean up callbacks
+client.callbacks.clear

data/examples/structured_outputs_example.rb

@@ -0,0 +1,191 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "open_router"
+
+# Configure the client
+OpenRouter.configure do |config|
+  config.access_token = ENV["OPENROUTER_API_KEY"]
+  config.site_name = "OpenRouter Ruby Gem Example"
+  config.site_url = "https://github.com/OlympiaAI/open_router"
+end
+
+OpenRouter::Client.new
+
+# Example 1: Simple structured output
+puts "=== Example 1: Simple Weather Schema ==="
+
+weather_schema = OpenRouter::Schema.define("weather") do
+  strict true
+
+  string :location, required: true, description: "City or location name"
+  number :temperature, required: true, description: "Temperature in Celsius"
+  string :conditions, required: true, description: "Weather conditions"
+  string :humidity, description: "Humidity percentage"
+
+  no_additional_properties
+end
+
+puts "Schema definition:"
+puts weather_schema.to_json
+
+# Example 2: Complex nested schema
+puts "\n=== Example 2: Complex User Profile Schema ==="
+
+user_schema = OpenRouter::Schema.define("user_profile") do
+  string :name, required: true, description: "Full name"
+  integer :age, required: true, minimum: 0, maximum: 150
+  string :email, required: true, description: "Email address"
+
+  object :address, required: true do
+    string :street, required: true
+    string :city, required: true
+    string :state, required: true
+    string :zip_code, required: true
+  end
+
+  array :hobbies do
+    string description: "A hobby or interest"
+  end
+
+  object :preferences do
+    boolean :newsletter, description: "Wants to receive newsletter"
+    string :theme, description: "UI theme preference"
+  end
+end
+
+puts "User schema:"
+puts JSON.pretty_generate(user_schema.to_h)
+
+# Example 3: Using schemas with API calls
+puts "\n=== Example 3: Structured Output API Call ==="
+
+# Simulate a structured response
+mock_weather_response = {
+  "id" => "chatcmpl-123",
+  "choices" => [
+    {
+      "message" => {
+        "role" => "assistant",
+        "content" => '{"location": "San Francisco", "temperature": 22, "conditions": "Partly cloudy", "humidity": "65%"}'
+      }
+    }
+  ]
+}
+
+response = OpenRouter::Response.new(mock_weather_response, response_format: weather_schema)
+puts "Parsed structured output:"
+puts response.structured_output.inspect
+
+# Check if output is valid
+if response.valid_structured_output?
+  puts "✅ Output is valid according to schema"
+else
+  puts "❌ Output validation failed:"
+  puts response.validation_errors
+end
+
+# Example 4: Working with different response formats
+puts "\n=== Example 4: Different Response Format Styles ==="
+
+# Style 1: Schema object directly
+format1 = weather_schema
+
+# Style 2: Hash with schema object
+format2 = {
+  type: "json_schema",
+  json_schema: weather_schema
+}
+
+# Style 3: Raw hash format
+format3 = {
+  type: "json_schema",
+  json_schema: {
+    name: "simple_weather",
+    strict: true,
+    schema: {
+      type: "object",
+      properties: {
+        temp: { type: "number" },
+        desc: { type: "string" }
+      },
+      required: %w[temp desc],
+      additionalProperties: false
+    }
+  }
+}
+
+puts "All three formats are supported:"
+puts "1. Direct schema object: #{format1.class}"
+puts "2. Hash with schema object: #{format2[:json_schema].class}"
+puts "3. Raw hash format: #{format3[:json_schema].class}"
+
+# Example 5: Real API call example (commented out)
+puts "\n=== Example 5: Real API Usage ==="
+
+# # Uncomment to make a real API call
+# begin
+#   response = client.complete(
+#     [{ role: "user", content: "What's the weather like in Tokyo right now?" }],
+#     model: "openai/gpt-4o",
+#     response_format: weather_schema
+#   )
+#
+#   if response.structured_output
+#     weather = response.structured_output
+#     puts "Location: #{weather['location']}"
+#     puts "Temperature: #{weather['temperature']}°C"
+#     puts "Conditions: #{weather['conditions']}"
+#     puts "Humidity: #{weather['humidity']}" if weather['humidity']
+#
+#     if response.valid_structured_output?
+#       puts "✅ Response validates against schema"
+#     else
+#       puts "❌ Validation errors:"
+#       response.validation_errors.each { |error| puts "  - #{error}" }
+#     end
+#   end
+#
+# rescue OpenRouter::ServerError => e
+#   puts "API Error: #{e.message}"
+# rescue OpenRouter::StructuredOutputError => e
+#   puts "Structured Output Error: #{e.message}"
+# rescue => e
+#   puts "Unexpected error: #{e.message}"
+# end
+
+puts "\n(Structured outputs example complete - uncomment the API call section to test with real API)"
+
+# Example 6: Schema validation demonstration
+puts "\n=== Example 6: Schema Validation Demo ==="
+
+if weather_schema.validation_available?
+  puts "JSON Schema validation is available"
+
+  # Valid data
+  valid_data = {
+    "location" => "London",
+    "temperature" => 18,
+    "conditions" => "Rainy"
+  }
+
+  # Invalid data
+  invalid_data = {
+    "location" => "London",
+    "temperature" => "eighteen", # Should be number
+    "conditions" => "Rainy"
+  }
+
+  puts "Valid data validation: #{weather_schema.validate(valid_data)}"
+  puts "Invalid data validation: #{weather_schema.validate(invalid_data)}"
+
+  unless weather_schema.validate(invalid_data)
+    puts "Validation errors for invalid data:"
+    weather_schema.validation_errors(invalid_data).each do |error|
+      puts "  - #{error}"
+    end
+  end
+else
+  puts "JSON Schema validation not available (install json-schema gem for validation)"
+end

data/examples/tool_calling_example.rb

@@ -0,0 +1,149 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "open_router"
+
+# Configure the client
+OpenRouter.configure do |config|
+  config.access_token = ENV["OPENROUTER_API_KEY"]
+  config.site_name = "OpenRouter Ruby Gem Example"
+  config.site_url = "https://github.com/OlympiaAI/open_router"
+end
+
+OpenRouter::Client.new
+
+# Example 1: Define a tool using the DSL
+puts "=== Example 1: Tool Definition with DSL ==="
+
+search_tool = OpenRouter::Tool.define do
+  name "search_gutenberg_books"
+  description "Search for books in the Project Gutenberg library"
+
+  parameters do
+    array :search_terms, required: true do
+      string description: "Search term for finding books"
+    end
+    integer :max_results, description: "Maximum number of results to return"
+  end
+end
+
+puts "Tool definition:"
+puts search_tool.to_json
+
+# Example 2: Define a tool using hash format
+puts "\n=== Example 2: Tool Definition with Hash ==="
+
+weather_tool = OpenRouter::Tool.new({
+                                      name: "get_weather",
+                                      description: "Get current weather for a location",
+                                      parameters: {
+                                        type: "object",
+                                        properties: {
+                                          location: {
+                                            type: "string",
+                                            description: "City and state, e.g. San Francisco, CA"
+                                          },
+                                          unit: {
+                                            type: "string",
+                                            enum: %w[celsius fahrenheit],
+                                            description: "Temperature unit"
+                                          }
+                                        },
+                                        required: ["location"]
+                                      }
+                                    })
+
+puts "Tool definition:"
+puts weather_tool.to_json
+
+# Example 3: Tool calling conversation
+puts "\n=== Example 3: Tool Calling Conversation ==="
+
+def simulate_search(_search_terms, max_results = 10)
+  # Simulate a search function
+  results = [
+    { title: "Programming Ruby", author: "Dave Thomas", year: 2004 },
+    { title: "The Ruby Programming Language", author: "David Flanagan", year: 2008 }
+  ]
+
+  results.first(max_results).to_json
+end
+
+def simulate_weather(location, unit = "fahrenheit")
+  # Simulate a weather API call
+  {
+    location:,
+    temperature: unit == "celsius" ? 22 : 72,
+    conditions: "Sunny",
+    unit:
+  }.to_json
+end
+
+# Initial message
+messages = [
+  { role: "user", content: "Can you search for Ruby programming books and also tell me the weather in San Francisco?" }
+]
+
+puts "User: #{messages.first[:content]}"
+
+# Uncomment the following lines to make a real API call:
+# begin
+#   # Make the tool call request
+#   response = client.complete(
+#     messages,
+#     model: "anthropic/claude-3.5-sonnet",
+#     tools: [search_tool, weather_tool],
+#     tool_choice: "auto"
+#   )
+#
+#   puts "\nAssistant response:"
+#   puts response.content if response.has_content?
+#
+#   # Handle tool calls
+#   if response.has_tool_calls?
+#     puts "\nTool calls requested:"
+#
+#     # Add the assistant's message to conversation
+#     messages << response.to_message
+#
+#     # Execute each tool call
+#     response.tool_calls.each do |tool_call|
+#       puts "- #{tool_call.name} with arguments: #{tool_call.arguments}"
+#
+#       # Execute the tool based on its name
+#       result = case tool_call.name
+#                when "search_gutenberg_books"
+#                  args = tool_call.arguments
+#                  simulate_search(args["search_terms"], args["max_results"])
+#                when "get_weather"
+#                  args = tool_call.arguments
+#                  simulate_weather(args["location"], args["unit"])
+#                else
+#                  "Unknown tool: #{tool_call.name}"
+#                end
+#
+#       puts "  Result: #{result}"
+#
+#       # Add tool result to conversation
+#       messages << tool_call.to_result_message(result)
+#     end
+#
+#     # Get final response with tool results
+#     final_response = client.complete(
+#       messages,
+#       model: "anthropic/claude-3.5-sonnet",
+#       tools: [search_tool, weather_tool]
+#     )
+#
+#     puts "\nFinal assistant response:"
+#     puts final_response.content
+#   end
+#
+# rescue OpenRouter::ServerError => e
+#   puts "Error: #{e.message}"
+# rescue => e
+#   puts "Unexpected error: #{e.message}"
+# end
+
+puts "\n(Tool calling example complete - uncomment the API call section to test with real API)"