AiRouteExplain ai.route-explain@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk 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

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

FieldTypeRequiredDescriptionConstraints
chosenstringyesExact id of the model/deployment that answered.
rejectedarray of objectyes
  • items: no other fields
rejected[].idstringyesExact id of the rejected candidate.
rejected[].reasonstringyesHuman-readable exclusion reason, without secrets or internal host IPs.
objectiveenumyesRouting policy used for this request.
  • one of "cheapest", "balanced", "fastest", "best", "private", "exact"
estimateobjectyes
  • no other fields
estimate.charge_nano_usdhttps://openvibe.network/contracts/ai/route-explain.v1.json#/$defs/money-nano-usdyes
estimate.input_tokensinteger
  • minimum 0
estimate.cached_read_tokensinteger
  • minimum 0
estimate.cache_write_tokensinteger
  • minimum 0
estimate.output_tokensinteger
  • minimum 0
actualobject
  • no other fields
actual.charge_nano_usdhttps://openvibe.network/contracts/ai/route-explain.v1.json#/$defs/money-nano-usd
actual.input_tokensinteger
  • minimum 0
actual.cached_read_tokensinteger
  • minimum 0
actual.cache_write_tokensinteger
  • minimum 0
actual.output_tokensinteger
  • minimum 0
policystringName of the policy/profile that produced the choice.
fallback_reasonstring | nullIf 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 }] }