What role-model defines
What role-model is, what ships today, and where the protocol ends and router implementation choices begin.
role-model is an open protocol for capability-aware AI routing.
It gives a system a shared way to describe:
- the request being routed
- the task and role requirements behind that request
- the concrete endpoints that can satisfy it
- the routing policy that constrains selection
- the observability artifacts that explain what happened
Why this exists
Most AI integrations start by hard-coding a model name and then slowly accumulate one-off rules for cost, latency, locality, tool support, and fallback behavior.
role-model turns that into an explicit contract:
- define the work as a task
- describe the endpoint as a concrete routable identity with declared and observed profiles
- apply policy consistently
- emit explainable artifacts for the final decision
That makes routing easier to audit, compare, evolve, and move across hosts or providers.
What role-model is
role-model is best understood as two connected layers:
| Layer | Purpose |
|---|---|
role-model | the protocol and contract layer |
role-model-router | the deterministic reference implementation and packaged runtime |
The protocol defines the vocabulary. The router shows how that vocabulary can be implemented in a stable baseline.
The protocol boundary
role-model standardizes the protocol artifacts that describe AI endpoints and the decisions made about them. It does not make the router implementation canonical.
The design rule is simple:
The combination of protocol docs and JSON Schemas under
protocol/schemas/is the canonical contract.
That means generated types, validators, adapters, registries, or routers are allowed to mirror the protocol, but they are not allowed to redefine it.
Protocol ownership versus router ownership
| Protocol-owned | Router-implementation-owned |
|---|---|
| JSON Schemas for identity, profiles, roles, tasks, policy, decisions, traces, and usage | how candidates are discovered before being passed into a router |
| the meaning of each field and artifact | weight tuning, neutral defaults, and optimization formulas |
| the shape of an explainable router decision | registry backends, cache layers, transport integration |
| the observability artifacts emitted around routing and execution | deployment topology, scheduling, retries beyond the protocol artifacts themselves |
The reference router is important because it demonstrates a coherent mapping from those protocol objects to a selection outcome, but the router remains an implementation of the protocol, not the definition of it.
What role-model is not
role-model is not:
- a promise that one model permanently owns one role
- a single hosted runtime or orchestration product
- a provider-specific SDK abstraction
- a replacement for low-level schemas, traces, or usage records
Roles in role-model are assigned through routing metadata and policy, not by pinning a role forever to a
single model name.
The problem domains role-model models
The protocol gives names and shapes to the objects a role-aware model-routing system needs:
- Roles and tasks as the semantic description of the work
- Endpoint identity as the concrete model-serving deployment the router may choose
- Declared capability profiles as what an endpoint claims to support
- Observed performance profiles as what measurements say it actually does
- Capability taxonomy as the stable compatibility language used across profiles, roles, tasks, and policy
- Routing policy as hard constraints and optimization intent
- Router decisions, traces, and usage artifacts as the explainable output and evidence trail
Role, model, and endpoint
role-model is not just an endpoint catalog, and it is not just a model picker.
It is a protocol for taking a role/task-shaped request and mapping it onto a concrete endpoint that serves a model.
In that stack:
- the role describes the execution contract
- the task describes the unit of work
- the model provides the capability family being invoked
- the endpoint is the real deployment target the router can actually choose
Why endpoints are the routing unit
role-model routes to endpoints, not bare model names.
That does not mean models are unimportant. It means model identity alone is not enough to route safely.
The same base model may be served by multiple endpoints with different:
- provider and serving surface
- runtime version
- region or locality
- quantization and precision
- observed latency, quality, failure behavior, freshness, or cost
role-model therefore preserves the model inside endpoint identity, but performs routing at the endpoint level where those operational differences are actually visible.
What is implemented today
Today the repository already includes a working baseline:
- canonical JSON Schemas and fixtures
- generated types and schema tooling
- a deterministic reference router core
- a packaged runtime you can install from GitHub Releases
- a local operator UI and reference routing artifacts for decisions, traces, usage, and observed performance
Some future host families and runtime surfaces are still architecture-stage. The public docs describe the implemented baseline first and treat future extensions as exactly that: extensions.