Model catalog reference

global.model_catalog declares every model the Router asks: the models that answer routing signals, embedding models and rerankers. Request routing targets, the models that answer users, stay in providers.models. Choose a model for a signal explains which deployment answers each signal.

Deployments

A deployment is a model the Router can ask, under a name. provider says which API the Router speaks to it.

provider	API the Router calls	Can answer
model_runtime	The built-in model runtime: managed (the Router starts it) or attached (endpoint set)	Anything its model card serves
systemone	POST <endpoint> and GET <endpoint>/models of a System One API	Every question-style signal and selector
classify	POST <endpoint>/classify	domain, jailbreak, pii, hallucination, classifier rules, safety rules and hazard parts, complexity rules
openai_chat	POST <endpoint>/chat/completions	jailbreak, hallucination, preference, classifier rules
openai_embeddings	POST <endpoint>/embeddings	Embeddings
rerank	POST <endpoint>/rerank	RAG reranking

The Router refuses at load a deployment given a signal it cannot answer.

Four deployments are always declared and start only when something resolves to them:

Name	Model	Used by default for
primary	vllm-sr/vela3-fast on CPU	system.decision_model
hazard	Vela 1.0 Hazard	A safety rule's hazard part
vela-embedding	Vela 1.0 Embedding	embeddings.default
omni-nano	Vela 1.0 Omni Nano	embeddings.multimodal

Field reference

field-reference

global:
  model_catalog:
    deployments:
      # Managed model_runtime: no endpoint; the Router starts and supervises it.
      managed-example:
        provider: model_runtime
        artifact: vllm-sr/Vela-1.0-Encoder-307M-Hazard  # Hub repository or absolute package path
        revision: 5dd25f2cc3c98f338e6a79b667662d60f936a28d  # 40-character commit
        device: cpu                      # cpu | auto | cuda | rocm, or cuda:N / rocm:N
        input: {max_tokens: 32768, overflow: reject}  # reject | truncate | window
        public_name: hazard-public       # its name on the inference API
        operating_point:                 # pins the head's packaged operating point
          path: operating_point.json
          sha256: e79a78f48bf45eb38e3f5402de3b3b18eeaa822e00b42b3640bf471276290de5
      replicated-example:
        provider: model_runtime
        artifact: vllm-sr/Decision-2.0-Kai-0.6B
        revision: cd49ea3813fd8ba0928a9a23ef6c9a0f2f0cd764
        replicas: [{device: cpu}, {endpoint: http://worker-2.example.com:8100, model: kai}]
      # Connection block: an attached model_runtime and every remote provider.
      remote-example:
        provider: systemone              # or classify, openai_chat, openai_embeddings, rerank
        endpoint: https://api.example.com/v1/systemone  # full URL; unix:///abs.sock for an attached runtime
        model: vllm-sr/d3-ultra          # the remote model; an attached runtime's served model
        auth: {header: Authorization, prefix: Bearer, api_key_env: EXAMPLE_KEY}  # or api_key_file: /abs/path
        headers: {X-Org: acme}           # non-secret headers only
        timeout_ms: 1500                 # per attempt
        max_retries: 1                   # transport retries within the caller's deadline
        tls: {ca_file: /etc/ssl/ca.pem, server_name: api.example.com, insecure_skip_verify: false}
        limits: {max_request_bytes: 262144, max_response_bytes: 4194304}
        capabilities: {question_types: [choice, noul, score], presets: [pii, halu]}
    system:
      decision_model: {deployment: primary}
    bindings: {pii: primary}
    embeddings: {default: vela-embedding, multimodal: omni-nano}

Managed model_runtime fields

Field	Meaning
artifact	A Hugging Face repository ID, or an absolute path to a model package
revision	The 40-character commit of a repository artifact
device	cpu, auto (the best device the host has), cuda, rocm, or one device such as cuda:0
input	The deployment's input budget: max_tokens, and overflow (reject, truncate or window)
replicas	Workers of one logical deployment: each a device, or an endpoint and model of a worker started elsewhere
public_name	The deployment's name on the inference API
operating_point	path and sha256 of the operating point the head's package serves. A classifier rule answered by this deployment reads independent label scores at its thresholds
max_num_seqs, max_num_batched_tokens, batch_window_ms, dtype, enable_shared_context, max_model_len	Engine arguments; see engine arguments

Connection block

The same fields connect an attached model runtime (a model_runtime deployment with endpoint) and every remote provider.

Field	Meaning	Limits
endpoint	The full URL of the API, path prefix included. The Router appends the operation path (/classify, /chat/completions, /embeddings, /rerank); a systemone endpoint is the URL questions are posted to. An attached runtime may use unix:///abs/path.sock	http or https; no credentials or fragment
model	The model the remote API answers with; on an attached runtime, the served model	Required for systemone, openai_chat, openai_embeddings, rerank
auth	header (default Authorization), prefix (default Bearer; "" sends the bare key), and exactly one of api_key_env or api_key_file (an absolute path, read on each call so a rotated key applies)	A key is never written in the configuration
headers	Further non-secret headers	Authorization, Proxy-Authorization, X-Api-Key, Api-Key, Ocp-Apim-Subscription-Key, Cookie and the auth header are refused
timeout_ms	Bound of one attempt	systemone ≤ 60000; others ≤ 300000
max_retries	Transport retries after the first attempt, within the caller's deadline	0–10; not on an attached runtime
tls	ca_file, server_name, cert_file and key_file (a client certificate), insecure_skip_verify	https only; files are absolute paths
limits	max_request_bytes, max_response_bytes	Not on an attached runtime
capabilities	What a remote model answers when its API lists nothing: question_types and presets (systemone), dimensions (openai_embeddings)
generation	max_tokens, temperature and reasoning ({family, use_reasoning, reasoning_effort}, where family names a built-in reasoning family) of an openai_chat deployment's completions	max_tokens ≤ 32768; temperature 0–2; reasoning needs family and use_reasoning

Redirects are refused, so a credential never follows a redirect to another host.

Bindings and rule deployments

global:
  model_catalog:
    deployments:
      local-vela: {provider: model_runtime, artifact: vllm-sr/vela3-fast, device: cpu}
    bindings:            # every recipe
      pii: local-vela
routing:
  model_bindings:        # this routing profile; recipes[].routing.model_bindings for one recipe
    domain: d3-remote

Binding keys are the signal types whose rules share one answer: domain, jailbreak, pii, fact_check, user_feedback, modality, hallucination, preference and reask. Rules that ask their own question write deployment: on the rule: routing.signals.decision[], classifiers[], safety[] and safety[].hazard, complexity[], and algorithm.decision of a decision. One remote score drives every complexity rule, so complexity rules answered by a classify deployment name the same one.

A binding can also be an object, to select a head of a multi-head model_runtime deployment: pii: {deployment: local-vela, head: pii}. An operating point is pinned on the deployment, with operating_point.

Resolution, for every signal: the rule's deployment, then the recipe's binding, then the global binding, then system.decision_model for a question-style signal. Embeddings resolve through embeddings.default, or, in a routing profile that embeds with its own model, through its model_bindings.embedding; reranking through the rag plugin's rerank.deployment; and a hazard part through its own deployment, else hazard.

Thresholds

A module threshold you do not write comes from the model that answers: the calibrated value on a built-in model's card; 0.5 for a systemone model, which publishes none (the load warns uncalibrated_threshold); otherwise the Vela 1.0 defaults. A threshold you write is used as written.

Admission

global.model_catalog.admission bounds concurrent calls. A key is a deployment name, for a gate the deployment's users share, or a signal type (jailbreak, domain, pii, fact_check, hallucination, user_feedback, safety, hazard), for that signal's own gate.

global:
  model_catalog:
    admission:
      jailbreak: {max_concurrency: 4, max_queue: 64, queue_timeout_ms: 250, on_overflow: shed}
      d3-remote: {max_concurrency: 16}

Examples

R1. Remote embedding model

r1-remote-embedding

global:
  model_catalog:
    deployments:
      remote-embed:
        provider: openai_embeddings
        endpoint: https://embedding.example.com/v1
        model: BAAI/bge-m3
        auth: {api_key_env: EMBEDDING_API_KEY}
        timeout_ms: 5000
        max_retries: 2
        capabilities: {dimensions: 1024}
    embeddings:
      default: remote-embed        # multimodal: <name> for multimodal embeddings

The Router posts to https://embedding.example.com/v1/embeddings: the operation path is appended to the endpoint's path, never assembled from a host and port.

R2. Attached reranker, named where it is used

r2-attached-reranker

global:
  model_catalog:
    deployments:
      document-ranker:
        provider: model_runtime          # a model runtime running elsewhere (attached)
        endpoint: https://ranker.example.com:8100
        model: vela-reranker
        auth: {api_key_env: RANKER_KEY}
        tls: {ca_file: /etc/ssl/internal-ca.pem}
        timeout_ms: 2000
routing:
  decisions:
    - name: rag
      plugins:
        - type: rag
          configuration:
            enabled: true
            backend: vectorstore
            rerank: {deployment: document-ranker, top_k: 3, layer: 22, dimension: 768}

layer and dimension select an early exit of a model runtime reranker. A remote reranking API is a rerank deployment, which answers at its own depth, so its rerank block writes only deployment and top_k.

R3. Remote classifier as the jailbreak guard, and a chat model as a judge

r3-classify-and-chat

global:
  model_catalog:
    deployments:
      guard:
        provider: classify               # POST <endpoint>/classify
        endpoint: https://guard.example.com
        auth: {api_key_env: GUARD_KEY}
        timeout_ms: 5000
        limits: {max_response_bytes: 1048576}
      chat-judge:
        provider: openai_chat            # chat completions used as a classifier or judge
        endpoint: https://llm.example.com/v1
        model: gpt-4.1-mini
        auth: {api_key_env: JUDGE_KEY}
        generation: {max_tokens: 256, temperature: 0}
routing:
  model_bindings:
    jailbreak: guard
  signals:
    classifiers:
      - name: tool-risk
        deployment: chat-judge
        labels: [SAFE, RISKY]
        instructions: Choose RISKY only for destructive or irreversible tool operations.

The provider decides how the Router talks to the model; no role, adapter or contract is written.

R4. System One behind a gateway with its own auth header

r4-systemone-gateway

global:
  model_catalog:
    deployments:
      d3-gateway:
        provider: systemone
        endpoint: https://gateway.example.com/Unified/v1/systemone
        model: vllm-sr/d3-ultra
        auth:
          header: Ocp-Apim-Subscription-Key
          prefix: ""                     # no Bearer prefix
          api_key_file: /run/secrets/systemone-key
        timeout_ms: 3000
        capabilities: {question_types: [choice, noul, score], presets: [pii, halu]}
    system:
      decision_model: {deployment: d3-gateway}

R5. Attached model runtime

With endpoint, the Router connects to a model runtime that is already running; without it, the Router starts and supervises the runtime.

r5-attached-runtime

global:
  model_catalog:
    deployments:
      decision-kai:
        provider: model_runtime
        endpoint: https://decision-worker.example.com:8100
        model: decision-kai                      # the served model
        auth: {api_key_env: WORKER_KEY}          # optional
        tls: {ca_file: /etc/ssl/internal-ca.pem}
        timeout_ms: 1000
    system:
      decision_model: {deployment: decision-kai}

R6. Request backends use the same connection shape

r6-request-backends

providers:
  defaults: {model: claude}
  models:
    - name: claude
      backend_refs:
        - provider: anthropic
          endpoint: https://gateway.example.com/anthropic
          auth: {header: x-api-key, prefix: "", api_key_env: ANTHROPIC_KEY}
          headers: {X-Org: acme}
    - name: native-d3              # a native System One alias: no second endpoint or key
      api_format: systemone
      deployment: d3-remote
global:
  model_catalog:
    deployments:
      d3-remote:
        provider: systemone
        endpoint: https://app.vllm-sr.ai/v1/systemone
        model: vllm-sr/d3-ultra
        auth: {api_key_env: VSR_APP_KEY}

providers.models stays a separate concept: the models that answer users, which routing chooses among. Only the connection shape (endpoint, auth, headers) is shared. A backend reads its key from auth.api_key_env. A deployment, the decision model included, is never a routing target and never appears in /v1/models. The native System One API answers for one only under its public_name, or through a native alias such as native-d3 that names it.