open_router_enhanced 2.0.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d443d948a07c5b55d6366e135354b2faa07a8edc38cb2791237a6a4a92bd229a
-  data.tar.gz: 37a93b36720b58bf1ee1c4809aa4d54e4d29e06ba27a63c9285a78fa7074eb66
+  metadata.gz: b6c9c14171242103eaeab8219521180242f9e0ee0968c739f8db2148a17423a5
+  data.tar.gz: '0906f33ab027e8cbf17ff60ab120ec65de39ec689c6e9a48025fb8df679f7d55'
 SHA512:
-  metadata.gz: 78fb6b74df5a7cb901ecac23fe503c667035e4794d6e7d9b97d4ad703e1f0a40347bd3274b86ba13c35501c8afc0b3c29ec5cb7b632eb93013af5a5328403285
-  data.tar.gz: 51d704a3035cf8211ac0d9533931d0b1a9bc9ebe49d21f192dd49b7dbb423eadcbf5adcc7b99d3212002947f2646337122e99660a589fa54be22ab3a356555eb
+  metadata.gz: 4cd127d4d6889e281e88e3f044f2444bd32e46f7ac4797d5c786b9a3fc5a8f792baf445c8dea481ab5018fae72646a221da05266bcb4134266735546e35a428d
+  data.tar.gz: a5b80c88d5f2228f1891409d2edb335a1a2c0294b94ffc69fb2730d0a854f7010c5eece8ac026eb6ba99a60df583634f42c77e18aada4b0399886b6a744a3488

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [2.2.0] - 2026-06-28
+
+### Added
+
+- **`Routing` mixin** (`OpenRouter::Routing`) included in `Client`, providing two new meta-routing methods:
+  - `pareto_complete(messages, min_coding_score: nil, **opts)` — routes to the cheapest model meeting a configurable quality bar via OpenRouter's Pareto Code Router (`openrouter/pareto-code`). `min_coding_score` is validated to `0.0–1.0`.
+  - `fuse(messages, analysis_models: nil, judge: nil, preset: nil, max_tool_calls: nil, **opts)` — fans a prompt out to a panel of models and synthesises one answer via OpenRouter's Fusion router (`openrouter/fusion`). `analysis_models` (1–8) and `max_tool_calls` (1–16) are validated.
+- **`SubagentTool`** (`OpenRouter::SubagentTool`) — wraps OpenRouter's `openrouter:subagent` server tool so an orchestrator model can delegate self-contained subtasks to a cheaper worker model mid-generation. Constructor: `model:` (required worker model) plus optional `instructions:`, `max_completion_tokens:`, `temperature:`, and `reasoning:`. Pass it via the normal `tools:` array to `complete`.
+- **`Response#selected_model`** — alias for `#model`; returns the concrete model OpenRouter resolved for routing responses (e.g. Pareto, Auto, Fusion).
+
+### Changed
+
+- Capability warning / strict-mode guards now exempt all `openrouter/`-prefixed meta-models (previously only `openrouter/auto` was exempt); this prevents spurious warnings or `CapabilityError` when using `pareto_complete` or `fuse` with tools or structured outputs.
+
+### Notes
+
+- These three OpenRouter platform features are still evolving server-side. The gem builds and validates the requests; routing/synthesis/delegation behaviour is performed by OpenRouter. Fusion fans out to every panel model plus a judge, so it costs roughly 4–5× a single completion. `pareto_complete` may resolve to a reasoning model that consumes a small `max_tokens` budget entirely on reasoning (returning `nil` content with `finish_reason: "length"`) — budget `max_tokens` accordingly.
+
 ## [2.0.0] - 2025-12-28
 
 ### Overview

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    open_router_enhanced (2.0.0)
+    open_router_enhanced (2.2.0)
       activesupport (>= 6.0, < 9.0)
       dotenv (>= 2.0, < 4.0)
       faraday (>= 1.0, < 3.0)

data/README.md

@@ -45,6 +45,7 @@ The [OpenRouter API](https://openrouter.ai/docs) is a single unified interface f
   - [Tool Calling](#tool-calling)
   - [Structured Outputs](#structured-outputs)
   - [Smart Model Selection](#smart-model-selection)
+  - [Routing (Pareto & Fusion)](#routing-pareto--fusion)
   - [Prompt Templates](#prompt-templates)
   - [Streaming](#streaming)
   - [Usage Tracking](#usage-tracking)
@@ -383,6 +384,95 @@ models = OpenRouter::ModelSelector.new
 
 **[Complete Model Selection Documentation](docs/model_selection.md)**
 
+### Routing (Pareto & Fusion)
+
+OpenRouter offers two meta-routing modes that automatically pick or synthesize answers across models.
+
+#### Pareto Code Router
+
+Routes each request to the cheapest model that meets a configurable quality bar — useful when you want cost-optimised code completions without picking a specific model.
+
+```ruby
+# Cheapest model meeting default quality threshold
+response = client.pareto_complete([
+  { role: "user", content: "Write a binary search in Ruby" }
+])
+
+# Require a higher quality bar (0.0–1.0, higher = better)
+response = client.pareto_complete(
+  [{ role: "user", content: "Implement a red-black tree" }],
+  min_coding_score: 0.8,
+  max_tokens: 1000
+)
+
+# Which model actually answered?
+puts response.selected_model  # => "anthropic/claude-3.5-haiku"
+puts response.content
+```
+
+#### Fusion Router
+
+Fans a prompt out to a panel of models in parallel, then synthesises one answer with a judge model. Costs roughly 4–5× a single completion but can outperform any individual model.
+
+```ruby
+# Default panel (OpenRouter chooses)
+response = client.fuse([
+  { role: "user", content: "What is the best approach to distributed consensus?" }
+])
+
+# Custom panel + explicit judge
+response = client.fuse(
+  [{ role: "user", content: "Review this architecture" }],
+  analysis_models: [
+    "anthropic/claude-3.5-sonnet",
+    "openai/gpt-4o",
+    "google/gemini-2.0-flash-001"
+  ],
+  judge: "anthropic/claude-opus-4-5",
+  max_tokens: 2000
+)
+
+# Curated preset panels
+response = client.fuse(messages, preset: "general-budget")
+
+# selected_model reports the synthesis/judge model that produced the answer,
+# e.g. "anthropic/claude-opus-4-5" — not the "openrouter/fusion" router alias.
+puts response.selected_model
+puts response.content
+```
+
+> **Note:** Fusion fans out to every panel model plus a judge, so it costs roughly 4–5× a single completion. `min_coding_score` for Pareto is validated to `0.0–1.0`; `analysis_models` (1–8) and `max_tool_calls` (1–16) for Fusion are validated client-side.
+
+#### `SubagentTool`
+
+Wraps OpenRouter's built-in `openrouter:subagent` server tool so an LLM can spawn its own sub-completions during a tool-calling loop.
+
+```ruby
+subagent = OpenRouter::SubagentTool.new(
+  model: "anthropic/claude-3.5-haiku",  # required: the cheaper worker model
+  instructions: "Complete the task exactly as described. Be concise.", # optional
+  max_completion_tokens: 512            # optional (also: temperature:, reasoning:)
+)
+
+response = client.complete(
+  [{ role: "user", content: "Summarize the attached changelog into release notes." }],
+  model: "openai/gpt-4o",
+  tools: [subagent],
+  tool_choice: "auto"
+)
+```
+
+> The orchestrator decides whether to delegate. The gem's job is to build and send a valid `openrouter:subagent` tool; OpenRouter runs the worker server-side and feeds its result back into the orchestrator's generation.
+
+#### `Response#selected_model`
+
+All routing methods (`complete`, `pareto_complete`, `fuse`) return a `Response` object. Use `#selected_model` (alias for `#model`) to see which model OpenRouter ultimately used:
+
+```ruby
+response = client.pareto_complete(messages)
+puts response.selected_model  # e.g. "mistralai/codestral-2501"
+```
+
 ### Prompt Templates
 
 Create reusable, parameterized prompts with variable interpolation.

data/Rakefile

@@ -30,6 +30,16 @@ task ci: %i[spec_all rubocop]
 
 # Model exploration tasks
 namespace :models do
+  desc "Fetch fresh model data from OpenRouter API and update local cache"
+  task :update do
+    require_relative "lib/open_router"
+
+    print "Fetching models from OpenRouter API..."
+    OpenRouter::ModelRegistry.refresh!
+    count = OpenRouter::ModelRegistry.all_models.size
+    puts " done. #{count} models cached."
+  end
+
   desc "Display summary of available models"
   task :summary do
     require_relative "lib/open_router"
@@ -59,18 +69,18 @@ namespace :models do
     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
+    input_costs = models.values.map { |spec| spec[:cost_per_token][:input] }.compact.sort
+    output_costs = models.values.map { |spec| spec[:cost_per_token][:output] }.compact.sort
 
-    puts "\n💰 Cost Analysis (per 1k tokens):"
+    puts "\n💰 Cost Analysis (per million 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 "    Min:    $#{format("%.4f", input_costs.min * 1_000_000)}"
+    puts "    Max:    $#{format("%.4f", input_costs.max * 1_000_000)}"
+    puts "    Median: $#{format("%.4f", input_costs[input_costs.size / 2] * 1_000_000)}"
     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])}"
+    puts "    Min:    $#{format("%.4f", output_costs.min * 1_000_000)}"
+    puts "    Max:    $#{format("%.4f", output_costs.max * 1_000_000)}"
+    puts "    Median: $#{format("%.4f", output_costs[output_costs.size / 2] * 1_000_000)}"
 
     # Context length analysis
     context_lengths = models.values.map { |spec| spec[:context_length] }.compact.sort
@@ -269,8 +279,8 @@ namespace :models do
   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"
+    cpm = OpenRouter::ModelRegistry.cost_per_million(model_id)
+    puts "     Cost: $#{format("%.4f", cpm[:input])}/M input, $#{format("%.4f", cpm[:output])}/M output"
     puts "     Context: #{format_number_with_commas(specs[:context_length])} tokens"
     puts "     Capabilities: #{specs[:capabilities].join(", ")}"
     puts "     Tier: #{specs[:performance_tier]}"
@@ -318,17 +328,17 @@ namespace :models do
   def self.sort_by_strategy(candidates, strategy)
     case strategy
     when :cost
-      candidates.sort_by { |_, specs| specs[:cost_per_1k_tokens][:input] }
+      candidates.sort_by { |_, specs| specs[:cost_per_token][:input] }
     when :performance
       candidates.sort_by do |_, specs|
-        [specs[:performance_tier] == :premium ? 0 : 1, specs[:cost_per_1k_tokens][:input]]
+        [specs[:performance_tier] == :premium ? 0 : 1, specs[:cost_per_token][: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] }
+      candidates.sort_by { |_, specs| specs[:cost_per_token][:input] }
     end
   end
 end