open_router_enhanced 1.2.5 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 006c0d9fe0bb456345df1e75db430cf54943d85f34c55a931cf3490aa7e8ad45
-  data.tar.gz: 15953a9890fa76b4d039ff40357e11407bbd03fe44d731926327e65a909e7b94
+  metadata.gz: d443d948a07c5b55d6366e135354b2faa07a8edc38cb2791237a6a4a92bd229a
+  data.tar.gz: 37a93b36720b58bf1ee1c4809aa4d54e4d29e06ba27a63c9285a78fa7074eb66
 SHA512:
-  metadata.gz: 7048aec5f2abd698c35300fea40135c149ea90345c4e9897d14ac1114ba88a85b1b5ddcef77b3dfc1f01993c5dcb1dd922e011a3fb0162dfcdf1ab1b518de933
-  data.tar.gz: 859c1f7a15f59b11a530eb7eb460e36499782dda46eb76affdf74e63f474f9e40b56d24b4bea65fb6cb08b5438e0186f04b73aed99cf2dd6de2eeebc5a83691d
+  metadata.gz: 78fb6b74df5a7cb901ecac23fe503c667035e4794d6e7d9b97d4ad703e1f0a40347bd3274b86ba13c35501c8afc0b3c29ec5cb7b632eb93013af5a5328403285
+  data.tar.gz: 51d704a3035cf8211ac0d9533931d0b1a9bc9ebe49d21f192dd49b7dbb423eadcbf5adcc7b99d3212002947f2646337122e99660a589fa54be22ab3a356555eb

data/CHANGELOG.md

@@ -1,5 +1,254 @@
 ## [Unreleased]
 
+## [2.0.0] - 2025-12-28
+
+### Overview
+
+Version 2.0.0 introduces the `CompletionOptions` class - a structured, self-documenting way to configure API requests. This replaces the previous pattern of 11+ keyword arguments with a clean, reusable options object.
+
+**This is a semver major release, but existing code will continue to work without modification.** The new patterns are opt-in and recommended for new code.
+
+---
+
+### Breaking Changes
+
+Method signatures now accept an optional `CompletionOptions` object as the second parameter:
+
+| Method | Old Signature | New Signature |
+|--------|---------------|---------------|
+| `complete` | `(messages, model:, tools:, ...)` | `(messages, options = nil, stream:, **kwargs)` |
+| `stream_complete` | `(messages, model:, ...)` | `(messages, options = nil, accumulate_response:, **kwargs, &block)` |
+| `stream` | `(messages, model:, ...)` | `(messages, options = nil, **kwargs, &block)` |
+| `responses` | `(input, model:, ...)` | `(input, options = nil, **kwargs)` |
+
+**Important**: The `options` parameter accepts `CompletionOptions`, `Hash`, or `nil`. All existing keyword argument patterns continue to work.
+
+---
+
+### Migration Guide
+
+#### No Changes Required (Backward Compatible)
+
+All existing code continues to work:
+
+```ruby
+# ✅ These all work exactly as before:
+client.complete(messages, model: "openai/gpt-4o")
+client.complete(messages, model: "openai/gpt-4o", temperature: 0.7)
+client.stream(messages, model: "openai/gpt-4o") { |chunk| print chunk }
+client.responses("Hello", model: "openai/gpt-4o", reasoning: { effort: "high" })
+```
+
+#### Recommended: Use CompletionOptions for New Code
+
+For new code, we recommend using `CompletionOptions` for better IDE support, documentation, and reusability:
+
+```ruby
+# Create reusable configuration
+opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o",
+  temperature: 0.7,
+  max_tokens: 1000
+)
+
+# Use across multiple calls
+response1 = client.complete(messages1, opts)
+response2 = client.complete(messages2, opts)
+
+# Override specific values without mutating original
+creative_opts = opts.merge(temperature: 1.2)
+response3 = client.complete(messages3, creative_opts)
+```
+
+#### Migrating Complex Configurations
+
+**Before (v1.x)**:
+```ruby
+client.complete(
+  messages,
+  model: "openai/gpt-4o",
+  tools: my_tools,
+  tool_choice: "auto",
+  temperature: 0.7,
+  max_tokens: 2000,
+  providers: ["openai", "azure"],
+  response_format: { type: "json_object" },
+  extras: { custom_param: "value" }
+)
+```
+
+**After (v2.0 - recommended)**:
+```ruby
+opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o",
+  tools: my_tools,
+  tool_choice: "auto",
+  temperature: 0.7,
+  max_tokens: 2000,
+  providers: ["openai", "azure"],
+  response_format: { type: "json_object" },
+  extras: { custom_param: "value" }
+)
+
+client.complete(messages, opts)
+```
+
+#### Migrating Streaming Code
+
+**Before (v1.x)**:
+```ruby
+client.stream_complete(
+  messages,
+  model: "openai/gpt-4o",
+  accumulate_response: true
+) do |chunk|
+  print chunk.dig("choices", 0, "delta", "content")
+end
+```
+
+**After (v2.0 - recommended)**:
+```ruby
+opts = OpenRouter::CompletionOptions.new(model: "openai/gpt-4o")
+
+client.stream_complete(messages, opts, accumulate_response: true) do |chunk|
+  print chunk.dig("choices", 0, "delta", "content")
+end
+
+# Or use the simpler stream method:
+client.stream(messages, opts) { |content| print content }
+```
+
+#### Pattern: Base Options with Per-Request Overrides
+
+```ruby
+# Define base configuration once
+BASE_OPTS = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o",
+  max_tokens: 1000,
+  providers: ["openai"]
+)
+
+# Override for specific use cases
+def generate_creative_content(prompt)
+  messages = [{ role: "user", content: prompt }]
+  client.complete(messages, BASE_OPTS, temperature: 1.2)
+end
+
+def generate_factual_content(prompt)
+  messages = [{ role: "user", content: prompt }]
+  client.complete(messages, BASE_OPTS, temperature: 0.1)
+end
+```
+
+---
+
+### Added
+
+#### `OpenRouter::CompletionOptions` Class
+
+A structured configuration object supporting **30+ parameters** organized by category:
+
+**Core Parameters**:
+- `model` - Model ID string or array for fallback routing
+- `tools` - Tool/function definitions
+- `tool_choice` - `"auto"`, `"none"`, `"required"`, or specific tool
+- `extras` - Hash for pass-through of any additional/future parameters
+
+**Sampling Parameters** (control response randomness):
+- `temperature` - 0.0-2.0, controls randomness (default varies by model)
+- `top_p` - 0.0-1.0, nucleus sampling threshold
+- `top_k` - Integer, limits token selection to top K
+- `frequency_penalty` - -2.0 to 2.0, penalize frequent tokens
+- `presence_penalty` - -2.0 to 2.0, penalize tokens already present
+- `repetition_penalty` - 0.0-2.0, general repetition penalty
+- `min_p` - 0.0-1.0, minimum probability threshold
+- `top_a` - 0.0-1.0, dynamic token filtering
+- `seed` - Integer for reproducible outputs
+
+**Output Control**:
+- `max_tokens` - Maximum tokens to generate (legacy)
+- `max_completion_tokens` - Maximum tokens (preferred, newer API)
+- `stop` - String or array of stop sequences
+- `logprobs` - Boolean, return log probabilities
+- `top_logprobs` - 0-20, number of top logprobs per token
+- `logit_bias` - Hash mapping token IDs to bias values (-100 to 100)
+- `response_format` - Structured output schema configuration
+- `parallel_tool_calls` - Boolean, allow parallel function calls
+- `verbosity` - `:low`, `:medium`, `:high`
+
+**OpenRouter Routing**:
+- `providers` - Array of provider names (becomes `provider.order`)
+- `provider` - Full provider config hash (overrides `providers`)
+- `transforms` - Array of transform identifiers
+- `plugins` - Array of plugin configs (`web-search`, `response-healing`, etc.)
+- `prediction` - Predicted output for latency optimization
+- `route` - `"fallback"` or `"sort"`
+- `metadata` - Custom key-value metadata
+- `user` - End-user identifier for tracking
+- `session_id` - Session grouping identifier (max 128 chars)
+
+**Responses API**:
+- `reasoning` - Hash with `effort:` key (`"minimal"`, `"low"`, `"medium"`, `"high"`)
+
+**Client-Side Options** (not sent to API):
+- `force_structured_output` - Override forced extraction mode behavior
+
+#### Helper Methods
+
+```ruby
+opts = CompletionOptions.new(model: "gpt-4", tools: [...])
+
+opts.has_tools?           # => true if tools are defined
+opts.has_response_format? # => true if response_format is set
+opts.fallback_models?     # => true if model is an array
+
+opts.to_h                 # => Hash of all non-nil, non-empty values
+opts.to_api_params        # => Hash for API request (excludes client-side params)
+opts.merge(temp: 0.5)     # => New CompletionOptions with override
+```
+
+---
+
+### Backward Compatibility
+
+**All existing patterns continue to work**:
+
+```ruby
+# Direct kwargs (unchanged from v1.x)
+client.complete(messages, model: "gpt-4")
+
+# Hash as second argument
+client.complete(messages, { model: "gpt-4", temperature: 0.7 })
+
+# CompletionOptions object (new in v2.0)
+opts = CompletionOptions.new(model: "gpt-4")
+client.complete(messages, opts)
+
+# Options with kwargs overrides (new in v2.0)
+client.complete(messages, opts, temperature: 0.9)
+```
+
+The `normalize_options` helper transparently handles all input styles.
+
+---
+
+### Internal Improvements
+
+- New `normalize_options` private helper for flexible input handling
+- Refactored `prepare_base_parameters` to accept `CompletionOptions`
+- Refactored `configure_tools_and_structured_outputs!` to use `CompletionOptions`
+- Added focused parameter helpers:
+  - `configure_sampling_parameters!`
+  - `configure_output_parameters!`
+  - `configure_routing_parameters!`
+- Improved separation of concerns in request building
+
+---
+
+### Bug Fixes
+
+- Fixed issue where `extras` hash contents were nested incorrectly in API requests. Parameters like `max_tokens` passed via `extras` now correctly appear at the top level of the request body.
+
 ## [1.2.2] - 2025-12-25
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    open_router_enhanced (1.2.5)
+    open_router_enhanced (2.0.0)
       activesupport (>= 6.0, < 9.0)
       dotenv (>= 2.0, < 4.0)
       faraday (>= 1.0, < 3.0)
@@ -11,7 +11,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.1.1)
+    activesupport (8.1.3)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
@@ -24,11 +24,11 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    addressable (2.8.8)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
-    bigdecimal (4.0.1)
+    bigdecimal (4.1.1)
     coderay (1.1.3)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
@@ -38,42 +38,47 @@ GEM
     diff-lcs (1.6.2)
     dotenv (3.2.0)
     drb (2.2.3)
-    faraday (2.14.0)
+    faraday (2.14.1)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-multipart (1.1.1)
+    faraday-multipart (1.2.0)
       multipart-post (~> 2.0)
     faraday-net_http (3.4.2)
       net-http (~> 0.5)
     hashdiff (1.2.1)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.18.0)
+    io-console (0.8.2)
+    json (2.19.3)
     json-schema (4.3.1)
       addressable (>= 2.8)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
-    minitest (6.0.0)
+    minitest (6.0.4)
+      drb (~> 2.0)
       prism (~> 1.5)
     multipart-post (2.4.1)
     net-http (0.9.1)
       uri (>= 0.11.1)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    parallel (2.0.1)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
-    prism (1.7.0)
-    pry (0.15.2)
+    prism (1.9.0)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    public_suffix (7.0.0)
+      reline (>= 0.6.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
-    regexp_parser (2.11.3)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
     rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
@@ -84,24 +89,24 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.7)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
-    rubocop (1.82.1)
+    rspec-support (3.13.7)
+    rubocop (1.86.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.48.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.48.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
     tzinfo (2.0.6)
@@ -111,7 +116,7 @@ GEM
     unicode-emoji (4.2.0)
     uri (1.1.1)
     vcr (6.4.0)
-    webmock (3.26.1)
+    webmock (3.26.2)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -198,6 +198,89 @@ end
 
 **[Full configuration documentation](docs/configuration.md)**
 
+## CompletionOptions
+
+For complex requests with many parameters, use `CompletionOptions` to organize your configuration:
+
+```ruby
+# Create reusable options
+opts = OpenRouter::CompletionOptions.new(
+  model: "anthropic/claude-3.5-sonnet",
+  temperature: 0.7,
+  max_tokens: 1000,
+  tools: [weather_tool],
+  providers: ["anthropic"]
+)
+
+# Use with complete()
+response = client.complete(messages, opts)
+
+# Override specific values
+response = client.complete(messages, opts, temperature: 0.9)
+
+# All these styles work (backward compatible):
+client.complete(messages, model: "gpt-4")                    # kwargs
+client.complete(messages, { model: "gpt-4" })                 # hash
+client.complete(messages, opts)                              # options object
+client.complete(messages, opts, temperature: 0.5)            # options + override
+```
+
+### Available Parameters
+
+```ruby
+OpenRouter::CompletionOptions.new(
+  # Model selection
+  model: "gpt-4",                      # Model ID or array for fallback
+  route: "fallback",                   # Routing strategy
+
+  # Sampling parameters
+  temperature: 0.7,                    # 0.0-2.0
+  top_p: 0.9,                         # Nucleus sampling
+  top_k: 50,                          # Top-K sampling
+  frequency_penalty: 0.5,             # -2.0 to 2.0
+  presence_penalty: 0.3,              # -2.0 to 2.0
+  repetition_penalty: 1.1,            # 0.0-2.0
+  min_p: 0.05,                        # Minimum probability
+  top_a: 0.1,                         # Dynamic filtering
+  seed: 42,                           # Reproducibility
+
+  # Output control
+  max_tokens: 1000,                   # Max completion tokens
+  max_completion_tokens: 1000,        # Preferred over max_tokens
+  stop: ["\n", "END"],                # Stop sequences
+  logprobs: true,                     # Return log probabilities
+  top_logprobs: 5,                    # Number of top logprobs
+  logit_bias: { "50256" => -100 },    # Token biasing
+  response_format: schema,            # Structured output
+  parallel_tool_calls: true,          # Allow parallel calls
+
+  # Tools
+  tools: [weather_tool],              # Tool definitions
+  tool_choice: "auto",                # auto, none, required, or specific
+
+  # OpenRouter routing
+  providers: ["anthropic", "openai"], # Simple provider ordering
+  provider: {                         # Full provider config
+    order: ["anthropic"],
+    quantizations: ["fp16"],
+    allow_fallbacks: true
+  },
+  transforms: ["middle-out"],         # Message transforms
+  plugins: [{ id: "web-search" }],    # OpenRouter plugins
+  prediction: { type: "content", content: "..." }, # Latency optimization
+  metadata: { request_id: "abc123" }, # Custom metadata
+  user: "user_123",                   # User identifier
+  session_id: "session_456",          # Session grouping
+
+  # Responses API
+  reasoning: { effort: "high" },      # For reasoning models
+
+  # Client-side
+  force_structured_output: true,      # Force schema injection
+  extras: { custom_param: "value" }   # Pass-through params
+)
+```
+
 ## Features
 
 ### Tool Calling

data/docs/model_selection.md

@@ -15,6 +15,36 @@ model = OpenRouter::ModelSelector.new
 response = client.complete(messages, model: model, tools: tools)
 ```
 
+## Using CompletionOptions with Model Selection (v2.0+)
+
+Combine model selection with `CompletionOptions` for powerful, reusable configurations:
+
+```ruby
+# Select model dynamically
+model = OpenRouter::ModelSelector.new
+                                 .require(:function_calling, :structured_outputs)
+                                 .optimize_for(:cost)
+                                 .choose
+
+# Create reusable options with the selected model
+opts = OpenRouter::CompletionOptions.new(
+  model: model,
+  tools: my_tools,
+  max_tokens: 1000
+)
+
+# Use across multiple calls
+response = client.complete(messages, opts)
+
+# Or use fallback model arrays directly in options
+fallback_opts = OpenRouter::CompletionOptions.new(
+  model: ["anthropic/claude-3.5-sonnet", "openai/gpt-4o", "google/gemini-pro"],
+  route: "fallback"
+)
+```
+
+All keyword argument patterns continue to work for backward compatibility.
+
 ## ModelSelector API
 
 The `ModelSelector` class provides a fluent interface for building complex model selection criteria.

data/docs/plugins.md

@@ -31,6 +31,40 @@ response = client.complete(
 )
 ```
 
+## Using CompletionOptions with Plugins (v2.0+)
+
+For cleaner, reusable configurations, use the `CompletionOptions` class:
+
+```ruby
+# Create reusable plugin configuration
+web_search_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o-mini",
+  plugins: [{ id: "web-search" }]
+)
+
+# Use across multiple calls
+response = client.complete(messages, web_search_opts)
+
+# Combine multiple plugins with other options
+research_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o",
+  plugins: [
+    { id: "web-search" },
+    { id: "pdf-inputs" }
+  ],
+  max_tokens: 2000,
+  temperature: 0.3
+)
+
+# Add prediction for latency optimization
+fast_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o",
+  prediction: { type: "content", content: "The answer is..." }
+)
+```
+
+All keyword argument patterns continue to work for backward compatibility.
+
 ## Response Healing Plugin
 
 The response-healing plugin fixes common JSON formatting issues server-side:

data/docs/responses_api.md

@@ -17,6 +17,40 @@ response = client.responses(
 puts response.content  # => "Paris"
 ```
 
+## Using CompletionOptions (v2.0+)
+
+For cleaner, reusable configurations, use the `CompletionOptions` class:
+
+```ruby
+# Create reusable reasoning configuration
+reasoning_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/o4-mini",
+  reasoning: { effort: "high" },
+  max_tokens: 1000
+)
+
+# Use with responses
+response = client.responses("Explain quantum entanglement", reasoning_opts)
+
+# Override specific values per-request
+response = client.responses(
+  "What is 15% of 80?",
+  reasoning_opts,
+  reasoning: { effort: "low" }  # Simpler problem, less reasoning needed
+)
+
+# Create tool-enabled responses configuration
+tool_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o-mini",
+  tools: [weather_tool, calculator_tool],
+  tool_choice: "auto"
+)
+
+response = client.responses("What's the weather in Tokyo?", tool_opts)
+```
+
+All keyword argument patterns continue to work for backward compatibility.
+
 ## With Reasoning
 
 The Responses API supports reasoning with configurable effort levels:

data/docs/streaming.md

@@ -22,6 +22,38 @@ response = streaming_client.stream_complete(
 puts response.content  # Complete response after streaming
 ```
 
+## Using CompletionOptions (v2.0+)
+
+For cleaner, reusable configurations, use the `CompletionOptions` class:
+
+```ruby
+# Create reusable streaming configuration
+stream_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o-mini",
+  temperature: 0.8,
+  max_tokens: 2000
+)
+
+# Use with stream_complete
+response = streaming_client.stream_complete(
+  messages,
+  stream_opts,
+  accumulate_response: true
+)
+
+# Use with simple stream method
+streaming_client.stream(messages, stream_opts) do |chunk|
+  print chunk
+end
+
+# Override specific values per-request
+streaming_client.stream(messages, stream_opts, temperature: 0.2) do |chunk|
+  print chunk
+end
+```
+
+All keyword argument patterns continue to work for backward compatibility.
+
 ## Streaming with Callbacks
 
 The streaming client supports extensive callback events for monitoring and custom processing.

data/docs/structured_outputs.md

@@ -35,6 +35,37 @@ puts user["age"]     # => 30
 puts user["email"]   # => "john@example.com"
 ```
 
+## Using CompletionOptions (v2.0+)
+
+For cleaner, reusable configurations, use the `CompletionOptions` class:
+
+```ruby
+# Create reusable structured output configuration
+struct_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o",
+  response_format: user_schema,
+  max_tokens: 500,
+  temperature: 0.1  # Lower temperature for more deterministic outputs
+)
+
+# Use across multiple calls
+response1 = client.complete(messages1, struct_opts)
+response2 = client.complete(messages2, struct_opts)
+
+# Override for specific requests
+creative_opts = struct_opts.merge(temperature: 0.8)
+response3 = client.complete(messages3, creative_opts)
+
+# Control forced structured output behavior
+opts_with_force = OpenRouter::CompletionOptions.new(
+  model: "some-model",
+  response_format: schema,
+  force_structured_output: true  # Override auto-detection
+)
+```
+
+All keyword argument patterns continue to work for backward compatibility.
+
 ## Key Concepts: JSON Content vs Structured Outputs
 
 **Important: These are fundamentally different features.**