# OmniRoute Model Deprecation and Family Fallback System Explained

> Understand OmniRoute's three-layer deprecation system. It automatically routes requests from old models to active siblings, preserving semantics and notifying clients.

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

---

**OmniRoute implements a three-layer deprecation mechanism that automatically routes requests from deprecated models to their active family siblings while preserving request semantics and notifying clients via response headers.**

The `diegosouzapw/OmniRoute` repository provides a robust routing layer for AI model providers, featuring a sophisticated **model deprecation and family fallback** system that ensures backwards compatibility. This architecture treats every model definition as a first-class entity that can be active, deprecated, or superseded by a newer version in the same family, allowing seamless transitions without client-side changes.

## Three-Layer Architecture for Deprecation Management

OmniRoute's deprecation mechanism is built around three tightly-coupled layers that handle registry metadata, policy resolution, and client communication.

### Provider Registry and Model Specifications

The foundation lives in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) and [`src/shared/constants/modelSpecs.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/modelSpecs.ts). These files contain the master list of providers and the detailed model catalog, where each entry includes a `deprecated` boolean flag and an optional `deprecationReason` string.

When a model is marked deprecated, the registry records its **family alias** using the `aliasOf` field. For example, `gemini-1.5-pro-preview` is configured as an alias for the newer `gemini-1.5-pro`, establishing the fallback chain at the configuration level.

### Fallback Policy Engine

Core logic resides in [`src/domain/fallbackPolicy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/fallbackPolicy.ts), which exports two key helpers:

- **`resolveFallbackChain(modelId)`** – Walks the alias chain from a deprecated model to the most recent, non-deprecated sibling.
- **`applyModelFamilyFallback(request)`** – Intercepts incoming requests, checks the target model's deprecation status, and rewrites the request payload to the fallback model when necessary.

The engine is consulted by the routing service in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) and by individual executor factories in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts). If a request targets a deprecated model, the fallback policy transparently substitutes the newer model while preserving the original request semantics, including parameters like temperature and system prompts.

### User-Facing Deprecation Notices

When a fallback occurs, OmniRoute injects a **deprecation notice** into the response header `x-omniroute-deprecation`. For chat-style APIs, the system also adds a system message explaining the substitution. The notice is generated by [`src/domain/fallbackPolicy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/fallbackPolicy.ts) via the helper `getDeprecationNotice(modelId)`.

## Resolving Fallback Chains in [`src/domain/fallbackPolicy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/fallbackPolicy.ts)

The `applyModelFamilyFallback` function serves as the primary entry point for request rewriting. It examines the incoming payload and resolves the fallback chain per-request, enabling zero-downtime upgrades.

```typescript
import { applyModelFamilyFallback } from '@/domain/fallbackPolicy';

// Incoming request payload (could be OpenAI, Anthropic, etc.)
const incoming = {
  model: 'gemini-1.5-pro-preview', // deprecated
  messages: [{ role: 'user', content: 'Explain quantum tunneling.' }],
  temperature: 0.7,
};

// The policy rewrites the model field if needed
const { request, deprecationNotice } = applyModelFamilyFallback(incoming);

// `request.model` is now the active sibling, e.g. "gemini-1.5-pro"
console.log(request.model); // → gemini-1.5-pro
if (deprecationNotice) {
  console.log('Deprecation:', deprecationNotice);
}

```

For logging and monitoring purposes, you can retrieve deprecation metadata directly:

```typescript
import { getDeprecationNotice } from '@/domain/fallbackPolicy';

const notice = getDeprecationNotice('gemini-1.5-pro-preview');
if (notice) {
  logger.warn(`Model ${notice.modelId} is deprecated: ${notice.reason}`);
}

```

## Configuring Model Aliases and Deprecation Metadata

Model families are defined in [`src/shared/constants/modelSpecs.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/modelSpecs.ts) using the `MODEL_SPECS` constant. To deprecate a model and establish a fallback, set the `deprecated` flag to `true` and specify the `aliasOf` field pointing to the active successor.

```typescript
// In src/shared/constants/modelSpecs.ts
export const MODEL_SPECS = {
  // … existing specs
  'gemini-1.5-pro-preview': {
    aliasOf: 'gemini-1.5-pro',           // points to the active model
    deprecated: true,
    deprecationReason: 'Replaced by Gemini 1.5-Pro (stable).',
  },
};

```

This configuration ensures that any request targeting `gemini-1.5-pro-preview` automatically resolves to `gemini-1.5-pro` without requiring client updates.

## Integration with the Routing Pipeline

The fallback policy integrates at multiple points in the request lifecycle. The [`src/domain/policyEngine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/policyEngine.ts) validates incoming requests against the fallback policy during the validation phase. The combo routing service in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) invokes the policy to ensure deprecated models are rewritten before execution.

For administrative visibility, [`src/app/api/fallback/chains/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/fallback/chains/route.ts) exposes REST endpoints for querying and managing fallback chains programmatically.

## Summary

- **Backwards compatibility** – Existing client code referencing older model IDs continues to work without modification, as `applyModelFamilyFallback` intercepts and rewrites requests transparently.
- **Graceful migration** – Clients receive clear deprecation notices through the `x-omniroute-deprecation` header and system messages, allowing upgrades at their own pace.
- **Zero-downtime upgrades** – The fallback chain is resolved per-request using `resolveFallbackChain`, so new models can be rolled out without restarting the service.
- **Centralized configuration** – All deprecation metadata and family aliases are maintained in [`src/shared/constants/modelSpecs.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/modelSpecs.ts), providing a single source of truth for model lifecycle management.

## Frequently Asked Questions

### How does OmniRoute handle requests targeting deprecated model IDs?

When a request arrives with a deprecated `model` identifier, the `applyModelFamilyFallback` function in [`src/domain/fallbackPolicy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/fallbackPolicy.ts) automatically rewrites the payload to use the active family member specified in the `aliasOf` field. This substitution preserves all request parameters, including temperature and message history, ensuring the client receives a valid response while maintaining backwards compatibility.

### What is the purpose of the `resolveFallbackChain` function?

The `resolveFallbackChain(modelId)` utility walks the entire chain of model aliases, starting from the requested deprecated model and traversing through any intermediate aliases until it reaches the most recent, non-deprecated sibling. This ensures that even if a model has been superseded multiple times, the request always resolves to the current stable version defined in [`src/shared/constants/modelSpecs.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/modelSpecs.ts).

### How are clients notified when a model fallback occurs?

OmniRoute injects a deprecation notice into the `x-omniroute-deprecation` response header for every request that triggers a fallback. For chat-style API endpoints, the system additionally appends a system message to the response explaining the substitution. The `getDeprecationNotice` helper generates these messages using the `deprecationReason` stored in the model specifications.

### Where can I query active fallback chains programmatically?

The repository exposes a dedicated REST endpoint at [`src/app/api/fallback/chains/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/fallback/chains/route.ts) that allows administrators to query current fallback chains and manage model aliases. This endpoint integrates with the `resolveFallbackChain` logic to provide real-time visibility into how deprecated models map to their active replacements across the system.