open_router_enhanced 1.2.2 → 1.2.3

data/examples/responses_api_example.rb

@@ -0,0 +1,324 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Responses API Multi-Turn Tool Loop Example
+# ===========================================
+# This example demonstrates the Responses API, which provides a streamlined
+# way to handle multi-turn tool conversations with automatic input building.
+#
+# The Responses API differs from Chat Completions:
+# - Uses `output` array with typed items instead of `choices`
+# - Provides `build_follow_up_input()` for easy conversation continuation
+# - Tool calls have a flat structure (not nested under `function`)
+# - Supports reasoning output as a first-class type
+#
+# Run with: ruby -I lib examples/responses_api_example.rb
+
+require "open_router"
+require "json"
+
+# Configure the client
+OpenRouter.configure do |config|
+  config.access_token = ENV.fetch("OPENROUTER_API_KEY") do
+    abort "Please set OPENROUTER_API_KEY environment variable"
+  end
+  config.site_name = "Responses API Examples"
+end
+
+client = OpenRouter::Client.new
+
+# Use a model that supports the Responses API
+MODEL = "openai/gpt-4o-mini"
+
+puts "=" * 60
+puts "RESPONSES API TOOL LOOP EXAMPLE"
+puts "=" * 60
+
+# -----------------------------------------------------------------------------
+# Define Our Tools
+# -----------------------------------------------------------------------------
+
+calculator_tool = OpenRouter::Tool.define do
+  name "calculate"
+  description "Perform mathematical calculations"
+  parameters do
+    string :expression, required: true, description: "Math expression to evaluate"
+  end
+end
+
+weather_tool = OpenRouter::Tool.define do
+  name "get_weather"
+  description "Get current weather for a location"
+  parameters do
+    string :location, required: true, description: "City name"
+  end
+end
+
+stock_tool = OpenRouter::Tool.define do
+  name "get_stock_price"
+  description "Get current stock price for a ticker symbol"
+  parameters do
+    string :symbol, required: true, description: "Stock ticker symbol (e.g., AAPL, GOOGL)"
+  end
+end
+
+TOOLS = [calculator_tool, weather_tool, stock_tool].freeze
+
+# -----------------------------------------------------------------------------
+# Tool Execution Function
+# -----------------------------------------------------------------------------
+
+def execute_tool(name, args)
+  case name
+  when "calculate"
+    expr = args["expression"]
+    # Handle percentage expressions like "15% of 378.90"
+    if expr =~ /(\d+(?:\.\d+)?)\s*%\s*of\s*(\d+(?:\.\d+)?)/i
+      result = (Regexp.last_match(1).to_f / 100) * Regexp.last_match(2).to_f
+      return { result: result.round(2), expression: expr }
+    end
+    # Standard math expression
+    expression = expr.gsub(%r{[^0-9+\-*/.()\s]}, "")
+    begin
+      { result: eval(expression), expression: expr }
+    rescue StandardError
+      { error: "Invalid expression" }
+    end
+
+  when "get_weather"
+    location = args["location"]
+    temp = rand(10..35)
+    {
+      location: location,
+      temperature_celsius: temp,
+      conditions: %w[sunny cloudy rainy partly_cloudy].sample,
+      humidity: rand(30..90)
+    }
+
+  when "get_stock_price"
+    symbol = args["symbol"].upcase
+    prices = { "AAPL" => 178.50, "GOOGL" => 141.20, "MSFT" => 378.90, "AMZN" => 185.30 }
+    price = prices[symbol] || (100 + rand * 200).round(2)
+    {
+      symbol: symbol,
+      price: price,
+      currency: "USD",
+      change: (rand * 10 - 5).round(2)
+    }
+
+  else
+    { error: "Unknown tool: #{name}" }
+  end
+end
+
+# -----------------------------------------------------------------------------
+# Example 1: Basic Responses API Call
+# -----------------------------------------------------------------------------
+puts "\n1. BASIC RESPONSES API CALL"
+puts "-" * 40
+
+response = client.responses(
+  "What is 25 times 17?",
+  model: MODEL,
+  tools: TOOLS
+)
+
+puts "Response ID: #{response.id}"
+puts "Model: #{response.model}"
+puts "Status: #{response.status}"
+
+if response.has_tool_calls?
+  puts "\nTool calls requested:"
+  response.tool_calls.each do |tc|
+    puts "  - #{tc.name}: #{tc.arguments}"
+  end
+end
+
+# -----------------------------------------------------------------------------
+# Example 2: execute_tool_calls with Block
+# -----------------------------------------------------------------------------
+puts "\n\n2. EXECUTE_TOOL_CALLS WITH BLOCK"
+puts "-" * 40
+
+response = client.responses(
+  "What's the weather in Seattle?",
+  model: MODEL,
+  tools: TOOLS
+)
+
+if response.has_tool_calls?
+  # Execute all tool calls with a single block
+  results = response.execute_tool_calls do |name, args|
+    puts "  Executing: #{name}(#{args})"
+    execute_tool(name, args)
+  end
+
+  puts "\nResults:"
+  results.each do |result|
+    if result.success?
+      puts "  Success: #{result.result}"
+    else
+      puts "  Error: #{result.error}"
+    end
+  end
+end
+
+# -----------------------------------------------------------------------------
+# Example 3: Multi-Turn with build_follow_up_input
+# -----------------------------------------------------------------------------
+puts "\n\n3. MULTI-TURN WITH BUILD_FOLLOW_UP_INPUT"
+puts "-" * 40
+
+original_query = "What's the weather in Tokyo and what's Apple stock at?"
+puts "User: #{original_query}"
+
+# First request
+response = client.responses(
+  original_query,
+  model: MODEL,
+  tools: TOOLS
+)
+
+if response.has_tool_calls?
+  puts "\nTool calls (Round 1):"
+  response.tool_calls.each do |tc|
+    puts "  - #{tc.name}: #{tc.arguments}"
+  end
+
+  # Execute the tools
+  results = response.execute_tool_calls do |name, args|
+    execute_tool(name, args)
+  end
+
+  puts "\nExecuted tools, building follow-up..."
+
+  # Build the follow-up input automatically
+  follow_up_input = response.build_follow_up_input(
+    original_input: original_query,
+    tool_results: results
+  )
+
+  puts "Follow-up input has #{follow_up_input.length} items"
+
+  # Continue the conversation
+  final_response = client.responses(
+    follow_up_input,
+    model: MODEL,
+    tools: TOOLS
+  )
+
+  if final_response.has_tool_calls?
+    puts "\nMore tool calls requested (Round 2)..."
+  else
+    puts "\nAssistant: #{final_response.content}"
+  end
+end
+
+# -----------------------------------------------------------------------------
+# Example 4: Complete Multi-Turn Loop Until Done
+# -----------------------------------------------------------------------------
+puts "\n\n4. COMPLETE MULTI-TURN LOOP"
+puts "-" * 40
+
+query = "I need to: 1) Check the weather in London, 2) Get Microsoft stock price, 3) Calculate 15% of $378.90"
+puts "User: #{query}"
+
+current_input = query
+max_rounds = 5
+round = 0
+
+loop do
+  round += 1
+  puts "\n[Round #{round}]"
+
+  response = client.responses(
+    current_input,
+    model: MODEL,
+    tools: TOOLS
+  )
+
+  if response.has_tool_calls?
+    puts "Tool calls:"
+    response.tool_calls.each { |tc| puts "  - #{tc.name}(#{tc.arguments})" }
+
+    # Execute tools
+    results = response.execute_tool_calls do |name, args|
+      result = execute_tool(name, args)
+      puts "  -> #{result.to_json[0..60]}..."
+      result
+    end
+
+    # Build next input
+    current_input = response.build_follow_up_input(
+      original_input: current_input.is_a?(String) ? current_input : current_input,
+      tool_results: results
+    )
+  else
+    # Final response - no more tool calls
+    puts "\nFinal Answer:"
+    puts response.content
+    break
+  end
+
+  if round >= max_rounds
+    puts "\n[Max rounds reached]"
+    break
+  end
+end
+
+puts "\nToken usage: #{response.total_tokens} total (#{response.input_tokens} in, #{response.output_tokens} out)"
+
+# -----------------------------------------------------------------------------
+# Example 5: Adding Follow-Up Questions
+# -----------------------------------------------------------------------------
+puts "\n\n5. FOLLOW-UP QUESTIONS"
+puts "-" * 40
+
+original = "What's the current price of Google stock?"
+puts "User: #{original}"
+
+response = client.responses(original, model: MODEL, tools: TOOLS)
+
+if response.has_tool_calls?
+  results = response.execute_tool_calls { |name, args| execute_tool(name, args) }
+
+  # Build follow-up WITH an additional question
+  follow_up = response.build_follow_up_input(
+    original_input: original,
+    tool_results: results,
+    follow_up_message: "Is that higher or lower than last week?"
+  )
+
+  next_response = client.responses(follow_up, model: MODEL, tools: TOOLS)
+  puts "\nAssistant: #{next_response.content}"
+end
+
+# -----------------------------------------------------------------------------
+# Example 6: Comparing Responses API vs Chat Completions
+# -----------------------------------------------------------------------------
+puts "\n\n6. RESPONSES API vs CHAT COMPLETIONS COMPARISON"
+puts "-" * 40
+
+puts <<~COMPARISON
+  Key differences:
+
+  CHAT COMPLETIONS API:
+  - response["choices"][0]["message"]["content"]
+  - Tool calls under: choices[0].message.tool_calls[].function.{name, arguments}
+  - Manual message construction for continuation
+  - Use: response.to_message + tool_call.to_result_message(result)
+
+  RESPONSES API:
+  - response.content (or response["output"])
+  - Tool calls at: output[] where type="function_call"
+  - Automatic continuation with: response.build_follow_up_input()
+  - Use: response.execute_tool_calls { |name, args| ... }
+
+  When to use each:
+  - Chat Completions: Standard chat, fine-grained control, streaming
+  - Responses API: Multi-turn tool loops, reasoning output, simpler code
+COMPARISON
+
+puts "\n#{"=" * 60}"
+puts "Examples complete!"
+puts "=" * 60

data/examples/tool_loop_example.rb

@@ -0,0 +1,317 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Tool Calling Loop Example (Chat Completions API)
+# =================================================
+# This example demonstrates a complete tool calling workflow using the
+# Chat Completions API, including multi-tool calls and conversation continuation.
+#
+# Run with: ruby -I lib examples/tool_loop_example.rb
+
+require "open_router"
+require "json"
+
+# Configure the client
+OpenRouter.configure do |config|
+  config.access_token = ENV.fetch("OPENROUTER_API_KEY") do
+    abort "Please set OPENROUTER_API_KEY environment variable"
+  end
+  config.site_name = "Tool Loop Examples"
+end
+
+client = OpenRouter::Client.new
+
+# Use a model with function calling support
+MODEL = "openai/gpt-4o-mini"
+
+puts "=" * 60
+puts "TOOL CALLING LOOP EXAMPLE"
+puts "=" * 60
+
+# -----------------------------------------------------------------------------
+# Define Our Tools
+# -----------------------------------------------------------------------------
+
+# Calculator tool for math operations
+calculator_tool = OpenRouter::Tool.define do
+  name "calculate"
+  description "Perform mathematical calculations. Use this for any math operations."
+
+  parameters do
+    string :expression, required: true, description: "Mathematical expression to evaluate (e.g., '2 + 2', '15 * 7')"
+  end
+end
+
+# Weather lookup tool
+weather_tool = OpenRouter::Tool.define do
+  name "get_weather"
+  description "Get current weather for a location"
+
+  parameters do
+    string :location, required: true, description: "City name (e.g., 'San Francisco', 'London')"
+    string :units, enum: %w[celsius fahrenheit], description: "Temperature units"
+  end
+end
+
+# Search tool
+search_tool = OpenRouter::Tool.define do
+  name "search"
+  description "Search for information on a topic"
+
+  parameters do
+    string :query, required: true, description: "Search query"
+    integer :max_results, description: "Maximum number of results (default: 3)"
+  end
+end
+
+TOOLS = [calculator_tool, weather_tool, search_tool].freeze
+
+# -----------------------------------------------------------------------------
+# Tool Execution Functions (simulated)
+# -----------------------------------------------------------------------------
+
+def execute_tool(name, args)
+  case name
+  when "calculate"
+    expr = args["expression"]
+    # Handle percentage expressions like "15% of 378.90"
+    if expr =~ /(\d+(?:\.\d+)?)\s*%\s*of\s*(\d+(?:\.\d+)?)/i
+      result = (Regexp.last_match(1).to_f / 100) * Regexp.last_match(2).to_f
+      return { result: result.round(2), expression: expr }
+    end
+    # Standard math expression - safe eval for basic math
+    expression = expr.gsub(%r{[^0-9+\-*/.()\s]}, "")
+    result = begin
+      eval(expression)
+    rescue StandardError
+      "Error: Invalid expression"
+    end
+    { result: result, expression: expr }
+
+  when "get_weather"
+    # Simulated weather data
+    location = args["location"]
+    units = args["units"] || "celsius"
+    temp = rand(15..30)
+    temp = (temp * 9 / 5) + 32 if units == "fahrenheit"
+    {
+      location: location,
+      temperature: temp,
+      units: units,
+      conditions: %w[sunny cloudy partly_cloudy rainy].sample,
+      humidity: rand(40..80)
+    }
+
+  when "search"
+    # Simulated search results
+    query = args["query"]
+    max_results = args["max_results"] || 3
+    results = max_results.times.map do |i|
+      {
+        title: "Result #{i + 1} for '#{query}'",
+        snippet: "This is a simulated search result about #{query}.",
+        url: "https://example.com/result-#{i + 1}"
+      }
+    end
+    { query: query, results: results }
+
+  else
+    { error: "Unknown tool: #{name}" }
+  end
+end
+
+# -----------------------------------------------------------------------------
+# Example 1: Simple Single Tool Call
+# -----------------------------------------------------------------------------
+puts "\n1. SIMPLE TOOL CALL"
+puts "-" * 40
+
+messages = [
+  { role: "user", content: "What is 15 multiplied by 23?" }
+]
+
+puts "User: #{messages.last[:content]}"
+
+response = client.complete(messages, model: MODEL, tools: TOOLS)
+
+if response.has_tool_calls?
+  puts "\nAssistant wants to call tools:"
+  response.tool_calls.each do |tc|
+    puts "  - #{tc.name}(#{tc.arguments})"
+  end
+
+  # Execute the tool calls and collect results
+  tool_results = response.tool_calls.map do |tc|
+    result = execute_tool(tc.name, tc.arguments)
+    puts "  -> Result: #{result}"
+    tc.to_result_message(result)
+  end
+
+  # Continue the conversation with tool results
+  messages << response.to_message
+  messages.concat(tool_results)
+
+  final_response = client.complete(messages, model: MODEL, tools: TOOLS)
+  puts "\nAssistant: #{final_response.content}"
+else
+  puts "Assistant: #{response.content}"
+end
+
+# -----------------------------------------------------------------------------
+# Example 2: Multiple Tool Calls at Once
+# -----------------------------------------------------------------------------
+puts "\n\n2. MULTIPLE TOOL CALLS"
+puts "-" * 40
+
+messages = [
+  { role: "user", content: "I'm planning a trip. What's the weather like in Tokyo and Paris? Also, calculate how many hours are in 2 weeks." }
+]
+
+puts "User: #{messages.last[:content]}"
+
+response = client.complete(messages, model: MODEL, tools: TOOLS)
+
+if response.has_tool_calls?
+  puts "\nAssistant wants to call #{response.tool_calls.length} tools:"
+  response.tool_calls.each do |tc|
+    puts "  - #{tc.name}(#{tc.arguments})"
+  end
+
+  # Execute all tool calls
+  tool_results = response.tool_calls.map do |tc|
+    result = execute_tool(tc.name, tc.arguments)
+    puts "  -> #{tc.name} result: #{result.to_json[0..80]}..."
+    tc.to_result_message(result)
+  end
+
+  # Continue conversation
+  messages << response.to_message
+  messages.concat(tool_results)
+
+  final_response = client.complete(messages, model: MODEL, tools: TOOLS)
+  puts "\nAssistant: #{final_response.content}"
+end
+
+# -----------------------------------------------------------------------------
+# Example 3: Multi-Turn Tool Loop
+# -----------------------------------------------------------------------------
+puts "\n\n3. MULTI-TURN TOOL LOOP"
+puts "-" * 40
+
+messages = [
+  { role: "system", content: "You are a helpful assistant. Use tools when needed to provide accurate information." },
+  { role: "user", content: "Search for 'Ruby programming' and tell me what you find." }
+]
+
+puts "User: #{messages.last[:content]}"
+
+max_iterations = 5
+iteration = 0
+
+loop do
+  iteration += 1
+  puts "\n[Iteration #{iteration}]"
+
+  response = client.complete(messages, model: MODEL, tools: TOOLS)
+
+  if response.has_tool_calls?
+    # Process tool calls
+    response.tool_calls.each do |tc|
+      puts "  Tool call: #{tc.name}(#{JSON.pretty_generate(tc.arguments)[0..50]}...)"
+    end
+
+    tool_results = response.tool_calls.map do |tc|
+      result = execute_tool(tc.name, tc.arguments)
+      tc.to_result_message(result)
+    end
+
+    # Add to conversation
+    messages << response.to_message
+    messages.concat(tool_results)
+  else
+    # No more tool calls - we have the final response
+    puts "\nAssistant: #{response.content}"
+    break
+  end
+
+  if iteration >= max_iterations
+    puts "\n[Max iterations reached]"
+    break
+  end
+end
+
+# -----------------------------------------------------------------------------
+# Example 4: Error Handling in Tools
+# -----------------------------------------------------------------------------
+puts "\n\n4. ERROR HANDLING"
+puts "-" * 40
+
+# Define a tool handler that includes error handling
+def safe_execute_tool(name, args)
+  result = execute_tool(name, args)
+  { success: true, data: result }
+rescue StandardError => e
+  { success: false, error: e.message }
+end
+
+messages = [
+  { role: "user", content: "Calculate the result of: 100 / (5 - 5)" }
+]
+
+puts "User: #{messages.last[:content]}"
+
+response = client.complete(messages, model: MODEL, tools: TOOLS)
+
+if response.has_tool_calls?
+  response.tool_calls.each do |tc|
+    puts "  Tool call: #{tc.name}"
+
+    # Use the built-in execute method which handles errors
+    result = tc.execute do |name, args|
+      execute_tool(name, args)
+    end
+
+    if result.success?
+      puts "  -> Success: #{result.result}"
+    else
+      puts "  -> Error: #{result.error}"
+    end
+
+    # Continue with the result either way
+    messages << response.to_message
+    messages << result.to_message
+  end
+
+  final_response = client.complete(messages, model: MODEL, tools: TOOLS)
+  puts "\nAssistant: #{final_response.content}"
+end
+
+# -----------------------------------------------------------------------------
+# Example 5: Tool Call Validation
+# -----------------------------------------------------------------------------
+puts "\n\n5. TOOL CALL VALIDATION"
+puts "-" * 40
+
+messages = [
+  { role: "user", content: "What's the weather in Boston?" }
+]
+
+response = client.complete(messages, model: MODEL, tools: TOOLS)
+
+if response.has_tool_calls?
+  response.tool_calls.each do |tc|
+    # Validate the tool call against our tool definitions
+    if tc.valid?(tools: TOOLS)
+      puts "Tool call '#{tc.name}' is valid"
+      puts "  Arguments: #{tc.arguments}"
+    else
+      errors = tc.validation_errors(tools: TOOLS)
+      puts "Tool call '#{tc.name}' has validation errors:"
+      errors.each { |e| puts "  - #{e}" }
+    end
+  end
+end
+
+puts "\n#{"=" * 60}"
+puts "Examples complete!"
+puts "=" * 60

data/lib/open_router/streaming_client.rb

@@ -36,12 +36,13 @@ module OpenRouter
     # @param model [String|Array] Model identifier or array of models for fallback
     # @param accumulate_response [Boolean] Whether to accumulate and return complete response
     # @param extras [Hash] Additional parameters for the completion request
+    # @param block [Proc] Optional block to call for each chunk (in addition to registered callbacks)
     # @return [Response, nil] Complete response if accumulate_response is true, nil otherwise
-    def stream_complete(messages, model: "openrouter/auto", accumulate_response: true, **extras)
+    def stream_complete(messages, model: "openrouter/auto", accumulate_response: true, **extras, &block)
       response_accumulator = ResponseAccumulator.new if accumulate_response
 
-      # Set up streaming handler
-      stream_handler = build_stream_handler(response_accumulator)
+      # Set up streaming handler (pass optional per-call block)
+      stream_handler = build_stream_handler(response_accumulator, &block)
 
       # Trigger start callback
       trigger_streaming_callbacks(:on_start, { model: model, messages: messages })
@@ -92,11 +93,14 @@ module OpenRouter
 
     private
 
-    def build_stream_handler(accumulator)
+    def build_stream_handler(accumulator, &per_call_block)
       proc do |chunk|
         # Trigger chunk callback
         trigger_streaming_callbacks(:on_chunk, chunk)
 
+        # Call per-call block if provided (used by #stream method)
+        per_call_block&.call(chunk)
+
         # Accumulate if needed
         accumulator&.add_chunk(chunk)
 

data/lib/open_router/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenRouter
-  VERSION = "1.2.2"
+  VERSION = "1.2.3"
 end