Refactor OpenRouter integration to support routers as first-class options

[d-oit]

Feature: Support OpenRouter Routers as model options

Summary

Currently, the OpenRouter integration in do-knowledge-studio treats individual models (e.g. openrouter/anthropic/claude-3-5-sonnet) as the primary selection units. This issue proposes refactoring the OpenRouter adapter so that OpenRouter routers (e.g. Auto Router, Free Models Router, Fusion Router, Pareto Router, etc.) become first-class selectable options alongside or instead of specific models.

Routers expose higher-level behaviors like automatic model selection, free-only routing, fusion/judge panels, or latest-family resolution, which fit well with knowledge-studio's agentic, evaluation, and experimentation workflows.

Goals

• Allow configuring OpenRouter routers (from https://openrouter.ai/docs/guides/routing/routers/) as selectable engines in knowledge-studio.
• Make it easy to switch between:
  • concrete model slugs
  • router slugs (e.g. openrouter/auto-router, openrouter/free-router, openrouter/fusion)
• Preserve existing behavior for users who have pinned specific models.

Proposed code changes

1. Configuration & schema

   • Extend the configuration where OpenRouter models are defined so that entries can be typed as either Model or Router.
   • Introduce a small enum/type, e.g.:
     • OpenRouterTarget = { kind: "model" | "router"; slug: string; display_name?: string; description?: string; default_params?: ... }.
   • Add a curated list of router slugs based on the docs:
     • Auto Router
     • Body Builder
     • Free Models Router
     • Latest Model Resolution
     • Pareto Router
     • Fusion Router
     • (potentially others as needed for knowledge-studio use cases).

2. Client / adapter layer

   • Locate the OpenRouter client/adapter module (where API requests are built, including model parameter and headers).
   • Refactor the code so the adapter accepts an OpenRouterTarget instead of a raw model slug.
   • Ensure that for routers, the model field is set to the router slug exactly as required by OpenRouter.
   • Where there is UI or configuration that currently assumes "model", generalize terminology to "engine" or similar to cover both models and routers.

3. Selection UX (UI or config)

   • If there is a model selection UI, add a section or grouping for Routers separate from Concrete Models.
   • Provide brief descriptions (pulled from docs and summarized) for each router so users understand when to use:
     • Auto Router (automatic best-model selection)
     • Free Router (cost-optimized, free only)
     • Fusion (multi-model deliberation + judge)
     • Pareto (coding score-based routing)
     • Latest Model Resolution (family-latest style slugs).
   • Consider allowing per-workspace or per-project defaults to be set to a router instead of a single model.

4. Testing & validation

   • Add integration tests that:
     • Call OpenRouter with Auto Router
     • Call Free Router
     • Call Fusion Router
     • Call one or two concrete models
   • Verify that:
     • Requests succeed and return completions.
     • Logging/observability still captures the resolved provider/model where available.
     • Error handling behaves consistently when routers internally fall back or fail.

5. Documentation

   • Update the README and any OpenRouter-related docs to:
     • Explain the difference between selecting a model vs a router.
     • Show example configuration snippets for using routers.
     • Describe recommended router choices for typical knowledge-studio workflows (e.g. evaluation, coding agents, cost-sensitive experiments).

Acceptance criteria

• OpenRouter routers are visible and selectable wherever OpenRouter models are currently configured or chosen.
• Switching from a concrete model slug to a router slug requires no code changes outside of configuration/selection.
• Tests cover at least Auto Router, Free Router, and Fusion Router requests.
• Documentation clearly explains how to use routers and when they are preferable to concrete models.

Notes

This issue is focused on using routers as options, not on exposing the entire OpenRouter feature surface (plugins, server tools, guardrails, etc.). Those can be follow-up issues once the basic router integration is in place.