---
title: "ai.route-explain@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/ai.route-explain"
updated: null
---

# ai.route-explain@1 · OpenVibe.Services

HTML: [ai.route-explain@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/ai.route-explain)

# AiRouteExplain `ai.route-explain@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: ai
- Visibility: first-party
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/ai/route-explain.v1.json`](/docs/contracts/ai.route-explain.json)

ai.route-explain@1: why OpenVibe.AI chose a model/deployment for a request. Lists the chosen candidate, rejected candidates with reasons, the objective (policy), the pre-flight cost estimate and the final actual cost. Money fields are integer nano-USD, as strings.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `chosen` | string | yes | Exact id of the model/deployment that answered. |  |
| `rejected` | array of object | yes |  | - `items: no other fields` |
| `rejected[].id` | string | yes | Exact id of the rejected candidate. |  |
| `rejected[].reason` | string | yes | Human-readable exclusion reason, without secrets or internal host IPs. |  |
| `objective` | enum | yes | Routing policy used for this request. | - `one of "cheapest", "balanced", "fastest", "best", "private", "exact"` |
| `estimate` | object | yes |  | - `no other fields` |
| `estimate.charge_nano_usd` | `https://openvibe.network/contracts/ai/route-explain.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `estimate.input_tokens` | integer |  |  | - `minimum 0` |
| `estimate.cached_read_tokens` | integer |  |  | - `minimum 0` |
| `estimate.cache_write_tokens` | integer |  |  | - `minimum 0` |
| `estimate.output_tokens` | integer |  |  | - `minimum 0` |
| `actual` | object |  |  | - `no other fields` |
| `actual.charge_nano_usd` | `https://openvibe.network/contracts/ai/route-explain.v1.json#/$defs/money-nano-usd` |  |  |  |
| `actual.input_tokens` | integer |  |  | - `minimum 0` |
| `actual.cached_read_tokens` | integer |  |  | - `minimum 0` |
| `actual.cache_write_tokens` | integer |  |  | - `minimum 0` |
| `actual.output_tokens` | integer |  |  | - `minimum 0` |
| `policy` | string |  | Name of the policy/profile that produced the choice. |  |
| `fallback_reason` | string \| null |  | If the first choice could not be used, why the chosen deployment was selected instead. |  |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: balanced-fallback

~~~~
{
  "chosen": "qwen/qwen3-9b-abliterated:q4_k_m@3f2a1c9",
  "rejected": [
    {
      "id": "openvibe/fast",
      "reason": "latency ceiling exceeded"
    },
    {
      "id": "meta-llama/llama_3.1_8b_instruct:fp16@bca2580",
      "reason": "higher expected cost per success"
    }
  ],
  "objective": "balanced",
  "estimate": {
    "charge_nano_usd": "12000",
    "input_tokens": 800,
    "cached_read_tokens": 0,
    "cache_write_tokens": 0,
    "output_tokens": 400
  },
  "policy": "balanced",
  "fallback_reason": "first choice above latency ceiling"
}
~~~~

Valid: exact-choice

~~~~
{
  "chosen": "qwen/qwen3-9b-abliterated:q4_k_m@3f2a1c9",
  "rejected": [
    {
      "id": "meta-llama/llama_3.1_8b_instruct:fp16@bca2580",
      "reason": "exact model requested"
    }
  ],
  "objective": "exact",
  "estimate": {
    "charge_nano_usd": "15000",
    "input_tokens": 1000,
    "cached_read_tokens": 0,
    "cache_write_tokens": 0,
    "output_tokens": 500
  },
  "actual": {
    "charge_nano_usd": "15000",
    "input_tokens": 1000,
    "cached_read_tokens": 0,
    "cache_write_tokens": 0,
    "output_tokens": 500
  },
  "policy": "pin-exact",
  "fallback_reason": null
}
~~~~

Rejected: bad-objective

~~~~
{
  "chosen": "qwen/qwen3-9b-abliterated:q4_k_m@3f2a1c9",
  "rejected": [],
  "objective": "cheap",
  "estimate": {
    "charge_nano_usd": "1000"
  }
}
~~~~

Rejected: float-money

~~~~
{
  "chosen": "qwen/qwen3-9b-abliterated:q4_k_m@3f2a1c9",
  "rejected": [],
  "objective": "cheapest",
  "estimate": {
    "charge_nano_usd": "12.34"
  }
}
~~~~

Rejected: missing-objective

~~~~
{
  "chosen": "qwen/qwen3-9b-abliterated:q4_k_m@3f2a1c9",
  "rejected": [],
  "estimate": {
    "charge_nano_usd": "1000"
  }
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('ai.route-explain@1', value);   // { valid, errors: [{ path, message }] }
~~~~