Skip to content

Manage Models

Sign in as an administrator and open Models at /models. Make sure you have configured the provider credentials or base URL in .env first; catalog entries store model metadata and capabilities, never API keys.

Add a model card to a catalog, review its capabilities, and test it in a chat.

Add a model

  1. Click Add Model and select a provider.
  2. Use Find on provider to search the upstream catalog and prefill capabilities, or enter the fields manually.
  3. Check Display label (label), Logical ID (id), Upstream / API model (api_model), and Wire API (wire_api).
  4. Enable the entry and click Save.
  5. Open a new chat, select the model, and send a test message.

Key identity rules:

  • id vs. api_model: id is the stable identifier stored on chats; api_model is the upstream model name sent to the provider API when it differs from id. Keep id stable once chats use it.
  • Unique routes: Every (provider, wire_api, api_model or id) combination in the catalog must be unique.
  • Provider discovery & metadata refresh: On OpenRouter, Crowbot, and Mistral, discovery prefills reasoning support, mandatory status, and supported effort levels (minimal, low, medium, high, xhigh, max). You can also discover a model via OpenRouter and switch its Provider dropdown to reuse its metadata on another compatible endpoint, or click Refresh provider metadata when editing an existing entry.
  • Setting context_window: To set or change context_window explicitly, export the catalog JSON, edit context_window, and import it in Update mode (see the Model catalog reference).

Edit, disable, delete, or set the default model

Use the action controls on any model row to edit it, toggle it on or off, set it as the default model, or delete it. The active default_model must stay enabled and cannot be deleted until another enabled model is chosen as the default.

When you delete a model that existing chats still reference, Numi asks which enabled model should take over those chats (with the catalog default preselected):

  • Existing chats keep their full message history and switch to the replacement model, normalizing their saved reasoning level to one the replacement supports.
  • Any admin overrides for chat titles or memory that pointed to the deleted model reset to automatic, and access tiers referencing it are updated.
  • A model hardcoded in CHAT_TITLE_MODEL or MEMORY_SUMMARY_MODEL in .env cannot be deleted while that environment setting names it; disable the model instead or change .env first.

Choose a Numi Search ranking model

Open Models → Automation and find Numi Search ranking. Choose LLM to use an OpenRouter model from your catalog, or Decision for the built-in ranking shortlist. The initial choices for these types are DeepSeek V4.1 Flash and Drex Max Finance respectively. Existing saved choices are kept.

Decision candidates are ordered from useful alternatives to the strongest relevance candidates. The information button explains the selected model's trade-off. These models do not need entries in your conversational catalog.

Click Save override to apply a change, Cancel to discard it, or Use config to restore the environment fallback. These controls only affect Numi Search ranking; the tool-suggestion router keeps its own model.

Import, export, and reload

  • Export: Downloads the active catalog as a portable JSON file.
  • Import: Accepts a catalog JSON document in one of three modes:
  • Merge: Adds only models whose id and route do not exist yet in your catalog (ignoring OpenRouter variant suffixes such as :floor when matching), leaving all your existing models and default model untouched.
  • Update: Adds new entries, replaces existing entries that share the same id or route, and updates default_model if specified. Include complete model objects when using Update mode, as omitted optional fields revert to their schema defaults.
  • Replace: Replaces the entire catalog with the imported JSON (after verifying that active chats, background model settings, and tiers have valid targets).
  • Defaults: Lists models from the packaged models.default.json that are not yet in your private catalog so you can cherry-pick newly shipped default models after an upgrade.
  • Reload catalog: Re-reads state/models.json from disk after manual edits. If an edited file fails validation at runtime, Numi keeps the last valid catalog snapshot active.

Catalog files on disk

Packaged defaults live in src/numi_chat/llm/models.default.json. As soon as you save a change in Admin -> Models (or create state/models.json), state/models.json acts as the complete runtime catalog (configurable via NUMI_CHAT_MODEL_CONFIG_PATH).

In Docker deployments, always mount the parent ./state:/app/state directory rather than mounting models.json as a single file, because Admin saves write a temporary file and atomically replace models.json in its directory.