RFC: Centralized Canonical Model Registry

Right now Hermes spreads provider/model resolution logic across a bunch of different places:

• PROVIDER_REGISTRY
• HERMES_OVERLAYS
• ALIASES
• CANONICAL_PROVIDERS
• PROVIDER_TO_MODELS_DEV
• custom_providers in config.yaml
• env/config-based credential handling
• live /v1/models probing

That works, but it also means provider/model state can drift depending on which path gets hit.

There isn’t really one authoritative place that defines:

• what a provider is
• what models belong to it
• what aliases normalize to
• what models are actually routable
• what metadata/capabilities exist for a model

As more providers get added, this becomes harder to reason about and debug.

Proposal

Add a centralized ModelRegistry that becomes the canonical source for:

• provider identity
• model identity
• alias normalization
• routing metadata
• provider/model health state

Instead of maintaining several parallel lookup systems, resolution paths would consult the same registry layer.

What this would help with

Consistent normalization

Right now provider/model naming is handled in several places.

A registry would make it possible to define:

• one canonical ID
• optional aliases
• optional display names

Example:

provider:
  canonical: openai
  aliases: [OpenAI, open-ai]

model:
  canonical: gpt-4.1
  aliases: [gpt4.1]

The important part is that identity and display formatting stop being mixed together.

Less registry drift

These currently evolve somewhat independently:

PROVIDER_REGISTRY
HERMES_OVERLAYS
ALIASES
CANONICAL_PROVIDERS
PROVIDER_TO_MODELS_DEV

The proposal is basically to make those derive from, or at least validate against, one canonical registry source.

Better debugging / introspection

A centralized registry would make it much easier to answer questions like:

• Why is this model visible?
• Which provider resolved?
• Which alias matched?
• Why did routing fail?
• What route is actually going to execute?

Right now a lot of that logic is distributed across multiple layers.

Provider/model health checks

The registry could also expose lightweight operational state:

• auth status
• /v1/models availability
• configured model presence
• last successful probe
• provider capabilities

Something along the lines of:

/model doctor
hermes model doctor

would probably become much easier to implement cleanly.

Future eval + usage hooks

Having a canonical model layer would also help with:

• token/cost accounting
• eval routing
• model benchmarking
• route inspection

Potential future workflows:

hermes model usage
hermes eval run --models A,B --benchmark X

Constraints

• Should stay backward compatible with existing custom_providers
• Should avoid large dependency additions
• Ideally incremental rather than a giant refactor
• Existing provider implementations shouldn’t need major rewrites

Open questions

A few implementation questions I wasn’t sure about:

1. Should the registry be:

   • a Python module
   • YAML/JSON-backed
   • runtime-generated
   • some hybrid of the above?

2. Should canonicalization apply to:

   • providers only
   • providers + models?

3. Should provider/model health state be persisted anywhere?

4. Should overlays remain separate, or just become registry metadata?

Feedback requested

Mostly looking for feedback on whether this direction makes sense architecturally before attempting a PR.

Also curious whether there’s already ongoing work around:

• provider/model unification
• routing cleanup
• registry consolidation

And if this does make sense, what maintainers would prefer as a first step:

• a thin registry abstraction first
• or a broader consolidation/refactor pass