---
question: How do I request a model by canonical id?
kind: overview
---

# Models

The model registry is the engine's catalog of chat and embedding models, keyed by canonical id (`gemma-4-26b-a4b-it`, `text-embedding-3-small`). Provider modules register their models when they load. An agent asks for an id and does not name the provider's client.

```python title="In a module"
registry = self.engine.services.model_registry
chat = registry.get_chat_model("gemma-4-26b-a4b-it")
embedding = registry.get_default_embedding_model()
```

A new project enables one provider, `naas_abi_marketplace.ai.openrouter`, with Gemma 4 26B-A4B as the default chat model and `text-embedding-3-small` as the default embedding model. One `OPENROUTER_API_KEY` covers both.

<!-- matrix -->

## Key concepts

- **Canonical id**: the provider-neutral name of a model, such as `claude-sonnet-5`. Each provider module maps it to its own model id.
- **Provider module**: a marketplace module under `naas_abi_marketplace.ai` (Anthropic, OpenAI, Gemini, Mistral, OpenRouter, Ollama, and others). It registers the model files of its `models/` folder when it loads.
- **Default models**: `default_chat_model` and `default_embedding_model` under `services.model_registry` in `config.yaml`. The engine checks them once the modules have loaded and stops if one is not registered.
- **One id, several providers**: when two enabled modules register the same canonical id, the first registered wins. `get_chat_model("claude-sonnet-5", provider="anthropic")` prefers that provider. When that provider has not registered the id, the registry falls back to another provider's model, so the calls, their billing and the data go to that other vendor.
- **Off-catalog ids**: a provider can also build a model on demand. With Ollama enabled, `get_chat_model("qwen2.5:1.5b", provider="ollama")` works without a model file.
- **No dependency to declare**: every module can use the registry. It does not go in `ModuleDependencies`.

## Where to see them

- **Settings › Models**, in a workspace, lists every model of every `naas_abi_marketplace.ai` module, read from the catalog on disk. A model is **Configured** when its module is loaded in the engine, **Not configured** otherwise. A model's page edits its display properties only: name, description, image URL and context window.
- The Nexus **System** app (super admins) lists the models registered in the running engine, and marks the default chat and embedding models.
- `GET /api/providers/models` returns the Settings › Models list, with a Nexus session.