role-model

Capability-aware AI routing with a packaged reference runtime, explainable router decisions, and a protocol you can actually inspect.

role-model is an open protocol for capability-aware AI routing, plus a packaged reference router runtime.

It gives a system a durable way to describe:

what a request needs
which roles and tasks are being asked for
which concrete endpoints can satisfy the work
what policy allows or forbids
why the final routing decision was made

The router does not pick by model name alone. It routes across concrete endpoints using role and task metadata, declared capability, routing policy, and observed performance.

Start here if you are new

What role-model does

At a high level, role-model separates routing into a few stable pieces:

Requests describe task type, required capabilities, modalities, tool needs, and constraints.
Roles and tasks describe the semantic shape of the work.
Endpoint identities and profiles describe concrete routable endpoints rather than abstract model names.
Routing policy applies hard denies, preferences, budgets, and deterministic tie-break rules.
Observability artifacts record the decision, traces, usage, and measured performance.

That makes routing explainable and portable across different providers, hosts, and deployment shapes.

How the router makes a decision

The reference router follows a stable flow:

Normalize request intent. Build the effective policy snapshot from the request plus role/task metadata.
Narrow the candidate set. Keep only endpoints that match the requested role, task, and policy scope.
Apply hard eligibility checks. Reject endpoints that fail capability, modality, tool, locality, budget, or binding requirements.
Score the eligible endpoints. Compare quality, latency, throughput, cost, reliability, and preference using measured evidence first, then declared data and neutral defaults.
Emit an explainable decision. Return a RouterDecision with the chosen endpoint, fallbacks, exclusions, and selection reasons.

The result is deterministic enough to inspect later, not just a hidden runtime guess.

Baseline roles

The current baseline role set includes:

Role ID	Primary task types	Typical use
`general.chat`	`text.chat`	general conversational responses
`coder.patch`	`code.edit`	patch-oriented code editing
`coder.review`	`code.edit`, `json.schema_adherence`	review, critique, and structured verdicts
`tool.agent`	`tools.function_calling`	tool orchestration and structured tool calls
`embedder`	`embeddings.text`	retrieval and vector generation
`classifier`	`text.classification`	labeling and taxonomy selection
`language.detector`	`text.language_detection`	language identification

For the full role and task mental model, read Roles, tasks, and capabilities. The deeper protocol contract still lives in Roles and tasks.

The first-time setup architecture

The canonical first-run sequence is now:

install and launch the packaged runtime
connect the local or remote endpoints you actually plan to use
activate models and assign roles
run the full benchmark on that real candidate set
review the benchmark results
choose and save the routing strategy
validate with a real routed request and inspect the decision

This keeps routing strategy selection evidence-based instead of guess-based.

Install and launch the runtime

Start the packaged router and open the operator UI on the local machine.

Connect providers and local backends

Wire in the exact local and remote execution paths you plan to route across.

Activate models and assign roles

Publish the real endpoint inventory and bind each model only to the roles it should serve.

Run the full benchmark

Grade the configured candidate set and write measured quality into observed profiles.

Choose and save routing strategy

Set balanced, quality, latency, or cost after the benchmark evidence exists.

Validate a real routed request

Inspect Router and Observe to confirm the winner, fallbacks, and reasons match the evidence.

The first-time setup path should establish the real candidate set first, then benchmark it, then choose strategy from evidence.