OmniRoute Model Deprecation Detection and Migration Workflow

OmniRoute's Open-SSE service layer automatically detects deprecated model IDs by checking the provider catalog against incoming requests, silently rewriting the model field to a configured successor, or returning a 4xx error when no migration path is defined.

The diegosouzapw/OmniRoute repository implements a robust model deprecation detection and migration workflow that shields API clients from breaking changes in the rapidly evolving LLM provider landscape. When a request hits an endpoint like /api/v1/chat/completions, the platform intercepts the call to validate model availability and execute seamless failover logic without client-side modifications.

Core Architecture of the Deprecation Service

The Model Deprecation Service Layer

The central logic resides in open-sse/services/modelDeprecation.ts. This module exports the handle() method that receives the parsed request object immediately after Zod schema validation. According to the OmniRoute source code, this service acts as a gatekeeper between the route handler and the execution pipeline, ensuring that obsolete model IDs never reach the translation layer.

Provider Catalog Metadata

Deprecation metadata is stored in the provider catalog TypeScript definitions, such as src/shared/constants/providers/apikey/frontier-labs.ts. Each model entry optionally includes:

• deprecationReason?: string – A human-readable explanation indicating why the model is obsolete
• successorModelId?: string – The target model identifier for automatic request migration

Step-by-Step Migration Flow

The model deprecation detection and migration process follows this execution path:

1. Request enters route – Client calls POST /api/v1/chat/completions

2. Body validation – Zod schema validates the request shape and extracts the model field

3. Model deprecation check – modelDeprecation.handle() receives the parsed request object

4. Catalog lookup – The service fetches the provider's model definition from the in-memory catalog (src/shared/constants/providers/*)

5. Deprecation detection – The service checks if deprecationReason exists on the catalog entry

6. Successor resolution – If successorModelId is configured, the service rewrites request.body.model to the new ID

7. Logging – A structured log entry records the original and new model IDs via the omni-route logger

8. Forwarding – The mutated request continues through open-sse/handlers/chatCore.ts for translation and execution against the live provider

9. Response handling – The backend returns the response using the successor model while preserving the original model name in metadata for backward compatibility

Implementing Model Deprecation

To deprecate a model in OmniRoute, edit the relevant provider configuration file (e.g., src/shared/constants/providers/apikey/anthropic.ts):

{
  id: "claude-2",
  name: "Claude 2",
  deprecationReason: "Replaced by claude-3.5-sonnet",
  successorModelId: "claude-3.5-sonnet"
}

Once the catalog is updated, the modelDeprecation service automatically picks up the changes without requiring modifications to the core service logic.

Error Handling for Retired Models

When a model has a deprecationReason but lacks a successorModelId, the service throws a DeprecationError. The route handler catches this exception and converts it into a 4xx HTTP response (typically 410 Gone) with a clear migration message:

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": {
    "code": "model_deprecated",
    "message": "Model `old-model-x` is deprecated and no longer available. Please update your provider configuration."
  }
}

This behavior forces explicit client updates when no automatic migration path exists, preventing silent failures or unintended model substitutions.

Real-World Migration Example

Consider a client requesting the deprecated gpt-3.5-turbo model:

// Client request
POST /api/v1/chat/completions
{
  "model": "gpt-3.5-turbo",
  "messages": [{ "role": "user", "content": "Hello!" }]
}

The provider catalog entry defines:

deprecationReason: "Legacy model, superseded by gpt-4o-mini",
successorModelId: "gpt-4o-mini"

Internally, the service executes:

request.body.model = "gpt-4o-mini";

The request proceeds to the OpenAI-compatible executor, which calls the live gpt-4o-mini endpoint. The client receives the response with backward compatibility preserved—the original model name remains visible in response metadata while the backend communicates with the modern model.

Summary

• OmniRoute's model deprecation detection and migration logic is centralized in open-sse/services/modelDeprecation.ts
• Provider catalogs define deprecation status via deprecationReason and successorModelId fields in files like src/shared/constants/providers/apikey/frontier-labs.ts
• The modelDeprecation.handle() method silently rewrites legacy model IDs to their successors before execution in open-sse/handlers/chatCore.ts
• Requests to retired models without successors receive 410 Gone errors with explicit migration instructions
• The architecture maintains backward compatibility by preserving original model names in response metadata while routing traffic to current model versions

Frequently Asked Questions

What happens if a client requests a deprecated model that has no successor defined?

The service throws a DeprecationError that the route handler converts into a 4xx HTTP response, typically 410 Gone. This forces the client to update their integration rather than silently failing or routing to an unintended alternative model.

Where is the deprecation metadata configured in OmniRoute?

Deprecation metadata lives in the provider catalog TypeScript files under src/shared/constants/providers/**/*.ts, where each model entry can specify deprecationReason and successorModelId properties to trigger automatic migration.

How does OmniRoute maintain backward compatibility during model migration?

While the backend executes requests against the successor model, the response metadata retains the original model name requested by the client. This ensures that existing integrations continue to function without breaking changes to response parsing logic.

Which service handles the actual model ID rewriting?

The modelDeprecation service in open-sse/services/modelDeprecation.ts contains the handle() method that performs the detection, logging, and silent rewriting of the model field before the request reaches the translation and execution pipeline.

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