Model Aliasing & Normalization

[yacosta738]

What

Implement a model aliasing system that normalizes model name variants to their canonical form. For example, gpt-4-turbo resolves to gpt-4-turbo-2024-04-09, and claude-3-opus resolves to claude-3-opus-20240229.

Why

Different clients and tools use different model name variants:

• gpt-4-turbo vs gpt-4-turbo-2024-04-09 vs gpt-4-turbo-128k
• claude-3-5-sonnet vs claude-3-5-sonnet-20240620
• gemini-1.5-pro vs gemini-1.5-pro-001

Without aliasing, routing by model name becomes unreliable — a request for gpt-4-turbo might fail because the provider only accepts the full dated version.

Basic Spec

Alias Data Model

ModelAlias {
  alias: string        // what the client sends
  canonical: string    // what the provider expects
  provider: ProviderId // which provider this alias applies to (or null for all)
  created_at: DateTime
}

Resolution

• On incoming request, extract the model string
• Look up alias in model_aliases table
• If found, replace with canonical model name before routing
• If not found, use the original model name

Built-in Aliases (seeded at startup)

Rook ships with 30+ common aliases covering major model families:

• OpenAI: gpt-4-turbo → gpt-4-turbo-2024-04-09, gpt-3.5-turbo → gpt-3.5-turbo-0125, etc.
• Anthropic: claude-3-opus → claude-3-opus-20240229, claude-3-sonnet → claude-3-sonnet-20240229, etc.
• Gemini: gemini-1.5-pro → gemini-1.5-pro-001, etc.

API

• GET /api/models/aliases — list all aliases
• POST /api/models/aliases — create a custom alias
• DELETE /api/models/aliases/:alias — delete an alias
• POST /api/models/aliases/seed — (internal) seed built-in aliases

User Stories

As a developer
I want to send gpt-4-turbo and have Rook resolve it to the correct dated version
So that my code works without knowing provider-specific model names

As a system operator
I want to add custom aliases for my organization's model naming conventions
So that internal model names map to provider model names transparently

As a developer integrating a new provider
I want model aliases to be provider-specific
So that the same alias can map to different models on different providers

Acceptance Criteria

• Model aliases stored in SQLite
• Alias resolution happens before provider routing
• 30+ built-in aliases seeded at startup
• Custom aliases creatable via API
• Aliases can be provider-specific or universal
• Alias resolution logged at debug level
• Unknown models pass through unchanged (no error)

[linear-code]

DALLAY-381