Mapping Vendor Model Names to the Aggregator's Aliases Without Breaking Existing Scripts

Why Model Name Mapping Matters

When you switch from calling model vendors directly to using the aggregator, you need to update the model names in your code. The aggregator uses its own alias scheme, so raw vendor strings like claude-3-opus-20240229 or gpt-4-0125-preview may not be recognized. To keep your scripts working, you must map these to the aggregator's aliases. This guide shows you how.

Understanding the Aggregator's Alias Scheme

The aggregator provides a unified API for multiple models. Instead of using the vendor's exact model identifier, you use an alias that the aggregator understands. The alias scheme is designed to be intuitive and consistent across vendors. Typically, aliases follow a pattern like vendor/model-name or a simplified version of the vendor's name. For example, Claude models might be aliased as claude-3-opus, GPT models as gpt-4, and so on.

Always refer to the aggregator's documentation for the complete list of aliases. The key is that each alias maps to a specific model version and provider.

Creating a Name-Mapping Table

To avoid breaking existing scripts, create a mapping table that translates vendor model strings to aggregator aliases. Below is a concrete example. This table is illustrative; adjust it based on your actual usage and the aggregator's current aliases.

| Vendor Model String | Aggregator Alias |
|-----------------------------|------------------------|
| claude-3-opus-20240229 | claude-3-opus |
| claude-3-sonnet-20240229 | claude-3-sonnet |
| gpt-4-0125-preview | gpt-4 |
| gpt-4-turbo-preview | gpt-4-turbo |
| deepseek-chat | deepseek-chat |
| qwen-max | qwen-max |
| glm-4 | glm-4 |
| kimi | kimi |

Note that some models may have the same name in both systems, but others require translation. Always verify against the aggregator's documentation.

Implementing a Guard Step

A guard step ensures that if your code encounters a vendor model string that hasn't been mapped, it fails gracefully or falls back to a default. This prevents unexpected errors when the aggregator doesn't recognize a raw name.

Here's how to implement a guard step in your code:

1. Define the mapping as a dictionary or constant in your codebase.
2. Wrap model resolution in a function that checks if the input is a known vendor string and returns the corresponding alias. If not found, raise a clear error or log a warning.
3. Optionally, provide a fallback alias for unmapped models, but be cautious—this could lead to incorrect model usage.

Example in Python:

MODEL_ALIAS_MAP = {
    "claude-3-opus-20240229": "claude-3-opus",
    "claude-3-sonnet-20240229": "claude-3-sonnet",
    "gpt-4-0125-preview": "gpt-4",
    "gpt-4-turbo-preview": "gpt-4-turbo",
    # add more as needed
}

def resolve_model_alias(vendor_model):
    if vendor_model in MODEL_ALIAS_MAP:
        return MODEL_ALIAS_MAP[vendor_model]
    # If it's already an aggregator alias, return as is
    if vendor_model in ["claude-3-opus", "gpt-4", "deepseek-chat", "qwen-max", "glm-4", "kimi"]:
        return vendor_model
    raise ValueError(f"Unknown model: {vendor_model}. Please map it to an aggregator alias.")

This function first checks if the input is a known vendor string and maps it. If not, it checks if it's already an aggregator alias (to support both). If neither, it raises an error.

Best Practices for Backward Compatibility

• Centralize the mapping in a configuration file or a module so you can update it in one place.
• Version your mapping if you have multiple environments or need to roll back.
• Test thoroughly after switching to ensure all model references resolve correctly.
• Monitor logs for any unmapped model errors and update the mapping promptly.
• Document the mapping for your team to avoid confusion.

By following these steps, you can seamlessly transition to the aggregator's alias scheme without breaking existing scripts, while taking advantage of unified access to multiple models with a single API key and USDC payments on Base.