open_router_enhanced 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f08650282b1232abfa779330c8f8ec9aad7bf6a984fd31e1a74ce1f3cad6962
-  data.tar.gz: e41ce6204abde21a34dd6c2976801666b8f4b9339cf81c845861f3837c15097c
+  metadata.gz: b6c9c14171242103eaeab8219521180242f9e0ee0968c739f8db2148a17423a5
+  data.tar.gz: '0906f33ab027e8cbf17ff60ab120ec65de39ec689c6e9a48025fb8df679f7d55'
 SHA512:
-  metadata.gz: 1d15f1e25db721734f0f9d2e43d01f6546af170096e65253c1c8438c3362484d6bad28f36669e2b8c34856ca297bb07dc1ffb18c7dc4442e2fe8c93ad79474b1
-  data.tar.gz: 2db9c96b66dcb0eae4b03f463db956192b38ef7444c879f7fe72a767e31c378d1ed702ee38a4c3b76e187945e6d942ac5dcbf7e7733fe8621315bee729e74940
+  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.1)
+    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

@@ -40,7 +40,6 @@ namespace :models do
     puts " done. #{count} models cached."
   end
 
-
   desc "Display summary of available models"
   task :summary do
     require_relative "lib/open_router"