Aliases & Sources

A single AI model can have dozens of different string identifiers depending on where it's referenced. Model Graph tracks all of them as aliases — explicit rows in the database mapping each string to a canonical model.

The Problem

Consider Claude 3.5 Sonnet. The same model is referenced as:

String	Where It's Used
claude-3-5-sonnet-20241022	Anthropic's official API
anthropic.claude-3-5-sonnet-20241022-v2:0	AWS Bedrock
claude-3-5-sonnet-v2@20241022	Google Vertex AI
anthropic/claude-3-5-sonnet-20241022	LiteLLM
claude-3-5-sonnet-latest	Anthropic convenience alias

If a tool scans your codebase and finds anthropic.claude-3-5-sonnet-20241022-v2:0, it needs to know:

1. Which model is this?
2. Is it outdated?
3. What should I replace it with — in the same format?

How Aliases Work

Every alias is a flat row in the database with three key fields:

• alias — the exact string as it appears in code
• source — which SDK or platform uses this string format
• normalized — a stripped-down form for fuzzy matching

There's no runtime string transformation or pattern matching. The design philosophy is keep it dumb — every known string is an explicit entry. This makes the system completely language-agnostic: it works on pure string matching without needing to understand imports, code structure, or programming languages.

Source Values

The source field identifies which platform or SDK uses a particular alias format:

Source	Platform	Example Format
official	Provider's own API	claude-3-5-sonnet-20241022
bedrock	AWS Bedrock	anthropic.claude-3-5-sonnet-20241022-v2:0
vertex	Google Vertex AI	claude-3-5-sonnet-v2@20241022
azure	Azure OpenAI	gpt-4o-2024-08-06
litellm	LiteLLM	anthropic/claude-3-5-sonnet-20241022
langchain	LangChain	claude-3-5-sonnet-20241022
vercel-ai-sdk	Vercel AI SDK	anthropic:claude-3-5-sonnet-20241022

Format-Preserving Replacement

When you call the resolve endpoint with a model string, the response includes an upgrade_alias with the same source as the matched alias. This enables format-preserving replacement:

Input:  anthropic.claude-3-5-sonnet-20241022-v2:0  (source: bedrock)
Output: anthropic.claude-sonnet-4-6-v1:0            (source: bedrock)

You can drop the upgrade string directly into your code — no format conversion needed. This works because every upgrade model also has aliases generated for all the same platforms.

Normalized Matching

Each alias has a normalized field that strips version suffixes, provider prefixes, and platform-specific formatting to create a common base string. This enables fuzzy matching when an exact alias isn't found.

For example, all of these normalize to claude-3-5-sonnet:

• claude-3-5-sonnet-20241022 → claude-3-5-sonnet
• anthropic.claude-3-5-sonnet-20241022-v2:0 → claude-3-5-sonnet
• anthropic/claude-3-5-sonnet-20241022 → claude-3-5-sonnet

How Aliases Are Generated

At ingestion time, the worker automatically generates aliases for known platforms using internal pattern templates. For example, when a new Anthropic model claude-sonnet-4-6 is ingested:

1. The official alias claude-sonnet-4-6 is created with source: official
2. A Bedrock alias anthropic.claude-sonnet-4-6-v1:0 is generated with source: bedrock
3. A LiteLLM alias anthropic/claude-sonnet-4-6 is generated with source: litellm
4. And so on for each supported platform

These templates are implementation details of the ingester. If an auto-generated alias is wrong, manual curation corrects it — the database row is simply updated.

Unique Constraint

Each alias string maps to exactly one model. There's a unique constraint on the alias column. This means the same string can't point to two different models — if there's a conflict, the ingester resolves it using priority rules (provider APIs are authoritative for their own models).