# How OmniRoute Handles Model Deprecation Detection and Fallback

> OmniRoute automatically detects deprecated models at runtime and falls back to non-deprecated alternatives, surfacing notices to callers for seamless updates.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) or [`src/shared/constants/providers/apikey/gateways.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/modelDeprecation.ts) | Core API exposing `isDeprecated`, `resolveModelAlias`, and `getDeprecationNotice`. |
| [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) | Provider entries containing `deprecated` flags and `deprecationReason` metadata. |
| [`src/shared/constants/providers/apikey/gateways.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/gateways.ts) | Additional provider definitions with deprecation metadata. |
| [`tests/unit/model-deprecation.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/model-deprecation.test.ts) | Unit tests confirming detection accuracy and alias resolution. |
| [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.