How OmniRoute Handles Model Deprecation Detection and Fallback

OmniRoute detects deprecated models at runtime using a dedicated Model Deprecation Service that checks provider metadata flags, then automatically resolves aliases to non-deprecated alternatives while surfacing deprecation notices to callers.

The OmniRoute project treats model deprecation as a first-class operational concern to prevent downstream failures when AI providers retire endpoints. When a request arrives, the routing layer interrogates the model registry to determine if the requested model ID is flagged as deprecated, then seamlessly substitutes a supported replacement without disrupting the client experience.

Provider-Level Deprecation Metadata

OmniRoute stores deprecation status directly within provider definitions located in src/shared/constants/providers/. Each provider entry includes a boolean deprecated flag and an optional deprecationReason string that explains the retirement rationale.

For example, legacy models like gemini-pro or specific versions such as claude-opus-4-6 carry these metadata flags in the provider registry. When a provider retires a model, maintainers update the corresponding entry in files such as src/shared/constants/providers/oauth.ts or src/shared/constants/providers/apikey/gateways.ts to mark the model as unavailable.

This registry-first approach ensures that deprecation status lives alongside the model configuration itself, creating a single source of truth for the entire routing system.

Runtime Detection with isDeprecated()

The core detection logic resides in open-sse/services/modelDeprecation.ts, which exports the isDeprecated(modelId: string): boolean function. This utility queries the provider registry and returns true when the requested model ID has its deprecated flag set to true.

The request pipeline—handling chat completions, embeddings, and image generation—invokes this check before executing the upstream call. If isDeprecated() returns true, the pipeline triggers the fallback mechanism rather than attempting to route to a defunct endpoint.

Unit tests in tests/unit/model-deprecation.test.ts validate this behavior, confirming that deprecated models like "gemini-pro" correctly return true while active models return false.

Automatic Fallback Resolution

When deprecation is detected, OmniRoute applies a three-step resolution strategy:

1. Alias Resolution – resolveModelAlias(modelId) returns the original model ID for active models, or maps deprecated IDs to their designated replacements (for example, redirecting a legacy Gemini model to the newest Gemini family member).

2. Notice Generation – getDeprecationNotice(modelId) constructs a user-facing warning string that incorporates the deprecationReason from the provider metadata, ensuring transparency about the substitution.

3. Router Integration – The combo router (open-sse/services/combo.ts) applies these functions to substitute the model with the latest non-deprecated sibling from the same family, preserving request semantics while avoiding hard failures.

Implementation Code Examples

The following pattern shows how to integrate deprecation detection into your request handling:

import {
  isDeprecated,
  resolveModelAlias,
  getDeprecationNotice,
} from '@/open-sse/services/modelDeprecation';

// 1️⃣ Detect deprecation status
if (isDeprecated(requestedModel)) {
  // 2️⃣ Generate a friendly notice for the client
  const notice = getDeprecationNotice(requestedModel);
  console.warn(notice); // e.g., "gemini-pro is deprecated: use gemini-1.5-pro instead"

  // 3️⃣ Resolve to a non-deprecated replacement
  const fallbackModel = resolveModelAlias(requestedModel);
  
  // Use fallbackModel for the upstream request
  request.body.model = fallbackModel;
}

Key Files in the Deprecation System

File	Role
open-sse/services/modelDeprecation.ts	Core API exposing isDeprecated, resolveModelAlias, and getDeprecationNotice.
src/shared/constants/providers/oauth.ts	Provider entries containing deprecated flags and deprecationReason metadata.
src/shared/constants/providers/apikey/gateways.ts	Additional provider definitions with deprecation metadata.
tests/unit/model-deprecation.test.ts	Unit tests confirming detection accuracy and alias resolution.
open-sse/services/combo.ts	Combo router that implements automatic fallback substitution.

Summary

• OmniRoute stores deprecation metadata as boolean flags within provider definitions in src/shared/constants/providers/.
• The isDeprecated() function in open-sse/services/modelDeprecation.ts performs runtime checks against the model registry.
• resolveModelAlias() automatically maps deprecated model IDs to supported alternatives, preventing request failures.
• getDeprecationNotice() surfaces human-readable warnings that include the specific deprecationReason for transparency.
• The combo router (open-sse/services/combo.ts) integrates these utilities to enable seamless, automatic fallback without client-side changes.

Frequently Asked Questions

How does OmniRoute determine if a model is deprecated?

According to the OmniRoute source code, the system checks the provider registry entry for each model ID. If the provider definition includes deprecated: true (stored in files like src/shared/constants/providers/oauth.ts), the isDeprecated() function returns true, signaling that the model should not be used for new requests.

What happens when a request specifies a deprecated model?

When a deprecated model is requested, OmniRoute intercepts the call and executes an automatic fallback. The resolveModelAlias() function maps the deprecated ID to a current replacement (such as redirecting legacy Gemini models to newer Gemini variants), and getDeprecationNotice() generates a warning explaining the substitution before the request proceeds to the upstream provider.

Where is the deprecation logic implemented in the codebase?

The primary implementation lives in open-sse/services/modelDeprecation.ts, which exports the core detection and resolution functions. The deprecation flags themselves reside in the provider configuration files under src/shared/constants/providers/, and the integration logic that applies fallbacks is located in open-sse/services/combo.ts.

Can I override the automatic fallback behavior for deprecated models?

The source code analysis indicates that fallback resolution is handled automatically by the combo router and the resolveModelAlias() function. While the analysis does not show explicit override mechanisms, the modular structure of open-sse/services/modelDeprecation.ts suggests that custom logic could be injected by modifying the alias resolution function or by bypassing the deprecation check in the request pipeline before it reaches the combo router.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}