Model Routing Naming Conventions: Don't Make Users Guess Which Models Are Available

When a product integrates multiple AI models, the biggest source of user confusion isn't a lack of models, but chaotic naming.

The backend might simultaneously host local models, cloud models, vision models, moderation models, coding models, and fallback models. While operations teams understand what each alias means, frontend users shouldn't have to guess which ones are usable.

This naming convention is designed for model routing and API dashboards.

1. Prioritize Purpose in Names

Model names should first indicate their purpose, then their technical origin.

For example, `audit` is more suitable for a moderation endpoint than a raw underlying model name; `vision` is better for an image understanding endpoint than a hardware identifier; and `coder-heavy` is more appropriate for coding tasks than an internal machine name.

Underlying models can be recorded in the backend, but frontend displays should prioritize aiding user selection.

2. Separate Status from Names

Don't cram `prod`, `test`, or `fallback` into the display name.

A clearer approach is to let the name describe the purpose, while a separate status field indicates availability, canary deployment status, or maintenance mode. This way, users see stable endpoints, while administrators see operational status.

3. Only Display Integrated Models on the Frontend

If a model isn't configured, verified, has no quota, or fails health checks, don't show it to users.

Forcing users to trial-and-error through a long list of models makes the platform look like a debugging tool rather than a usable product. An API operations platform should showcase "models we have integrated and guarantee are available," not every theoretically existing model.

4. Aliases Should Be Long-Term Stable

Underlying models will upgrade, but aliases should remain as stable as possible.

For instance, today `audit` might point to a local model, and tomorrow it could switch to a more powerful moderation model. As long as the interface capabilities remain consistent, users' API keys and call paths shouldn't need to change.

5. Maintain Mapping Evidence in the Admin Panel

Frontend displays can be concise, but the admin panel must be comprehensive.

Each alias should reveal the underlying provider, model ID, context length, rate-limiting rules, health check results, recent failure reasons, and the person in charge. This ensures that when issues arise, operations teams can pinpoint the problem without relying on chat logs to guess.

Good naming conventions hide complexity in the backend and leave certainty for the user. Users see a few available endpoints, while administrators see complete mappings and status. This is the key step in transforming model routing from an engineering configuration into a product capability.