Protocol object graph
Identity anchors profiles. Roles and bindings constrain eligibility. Policy + evidence emit an inspectable RouterDecision, then traces and usage feed observed profiles.
01
EndpointIdentity
Routable unit handle
02
Declared / Observed
Profiles on endpoint_id
03
RoleBinding
active · disabled · candidate
04
RoutingPolicy
Snapshot into decision
05
RouterDecision
Eligibility · scores · reasons
06
Trace · Usage
Join keys → feedback
EndpointIdentity
Routing unit is an endpoint, not a model name
Required: endpoint_id · endpoint_kind · provider_kind · serving_source · model_id · runtime_version. Same model_id may appear on many endpoints.
Handle
endpoint_id · endpoint_version
Class
endpoint_kind · provider_kind · serving_source
Lineage
model_id · package_id · variant_id
Runtime
runtime_version · quantization · precision
Deployment
host_class · device_class · region · org_scope
DeclaredCapabilityProfile
Eligibility floor — provider-declared shape. Rejects before scoring when capability, modality, context, or tools fail.
capabilities
capabilities[] · modalities[]
context
max_context_tokens
tools
tool_calling.supported · style
embeddings
supports_embeddings
platform
platform_constraints[]
ObservedPerformanceProfile
Measured evidence — benchmarks and live samples. Prefer over declared when present; never mix endpoint versions.
latency
latency_ms_p50 · latency_ms_p95
reliability
failure_rate · tokens_per_sec
quality
judge_score · quality_score
confidence
freshness_score · confidence_score
sources
benchmark · live_request
Roles, tasks, and bindings
RoleDefinition carries required / preferred / forbidden capabilities, tool_policy, and routing_policy_overrides. RoleBinding.status gates eligibility.
Taxonomy V1
6 groups · 28 roles · 280 tasks · 46 capabilities · 9 modalities · 15 tool classes · taxonomyVersion 1.0.0-alpha.1
RoleBinding.status
active
eligible to route
candidate
discoverable, not scored
disabled
→ ROLE_BINDING_INACTIVE
required
Hard eligibility
Missing capability excludes the endpoint
preferred
Scoring bonus
Does not reject; raises rank when present
forbidden
Hard deny in role context
capability ≠ modality
RoutingPolicy
Effective policy is snapshotted into every decision
strategy and compute_preference shape intent; hard constraints filter before scoring; tie_break_order resolves equals. Copied to RouterDecision.policy_snapshot.
strategy
balanced · cost · latency · quality
compute
auto · local · remote · hybrid
hard
capabilities · modalities · tools · allow/deny · privacy.allow_remote · budget
targets
latency_target_ms · latency_max_ms · throughput_target_tps
evidence
hard constraints → observed → benchmark quality → declared → neutral defaults
tie-break
quality ↓ · latency_ms ↑ · reliability ↓ · endpoint_id (stable)
Reason code vocabulary
Exclusions explain why a candidate never scored. Selection reasons explain why the winner won. Both land on RouterDecision.
Exclusions
CAPABILITY_MISSING · MODALITY_UNSUPPORTED
CONTEXT_TOO_SMALL · TOOLS_UNSUPPORTED
POLICY_DENY_ENDPOINT · POLICY_DENY_REMOTE
BUDGET_EXCEEDED · PROVIDER_OFFLINE · REVOKED
TASK_NOT_SUPPORTED · ROLE_NOT_ALLOWED
ROLE_BINDING_INACTIVE · VARIANT_INCOMPATIBLE
Selections
BEST_TOTAL_SCORE · MEASURED_PROFILE_USED
DECLARED_PROFILE_USED · DEFAULT_PROFILE_USED
LOCAL_PREFERENCE_APPLIED · REMOTE_PREFERENCE_APPLIED
BUDGET_OPTIMIZATION · LOW_LATENCY_TARGET_MET
HIGH_QUALITY_TARGET_MET · ROLE_PREFERENCE_APPLIED
FALLBACK_CHAIN_COMPUTED · TASK_POLICY_APPLIED
RouterDecision
Explainability artifact, not a winner badge
Carries policy_snapshot, per-endpoint eligibility with exclusions, scored_candidates, selection_reasons, and whether measured or declared profiles were used. Failure: eligibility filled, scored empty, chosen_endpoint_id "".
ids
routing_decision_id · request_id
policy
Effective RoutingPolicy copy
eligibility
endpoint_id · eligible · exclusions[]
scored
Scores + metric_breakdown
chosen
chosen_endpoint_id · fallback_endpoint_ids[]
evidence
used_measured · used_declared · scoring_version
Traces and usage close the loop
Join on request_id · routing_decision_id · trace_id · span_id · endpoint_id. Samples feed ObservedPerformanceProfile.
TraceSpan types
router.eligibility · router.scoring
router.selection · router.fallback · router.retry
provider.* · tool.execution · request.failure
UsageEvent
tokens_in / tokens_out · latency_ms
cost_estimate · error_class · sample_source
events: router.decision.created · profile.sample.recorded
Protocol boundary
OpenAI-compatible surfaces are adapters — not the canonical contract
/v1/models and /api/role-model/downstream/openai expose discovery with conservative aliases and sanitized endpoint IDs. They must not redefine EndpointIdentity, profiles, roles, or RouterDecision — those live in protocol/schemas/ and docs/protocol/.