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 InstallFirst launch and connect modelsRun the full benchmarkChoose and save the routing strategySend the first request and inspect the decision
Using Pi? Install and launch the Role-Model runtime first, then follow
[Pi integration](/integrations/pi) to install `@try-works/pi-role-model`
, run /role-model setup
, and choose an alias.
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 aRouterDecision
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](/concepts/roles-tasks-and-capabilities). The deeper protocol contract
still lives in [Roles and tasks](/protocol/roles-and-tasks).
[The first-time setup architecture](#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
Downstream clients such as Pi join after the runtime is installed and configured. They discover Role-Model aliases through the downstream OpenAI discovery contract instead of owning runtime setup themselves.
This keeps routing strategy selection evidence-based instead of guess-based.