# Role-model: protocol for assigning the right AI model for the right job

> Source: <https://role-model.dev/>
> Published: 2026-06-28 22:16:36+00:00

# 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](#start-here-if-you-are-new)

[Install](/get-started/install)[First launch and connect models](/get-started/first-launch-and-connect-models)[Run the full benchmark](/get-started/run-full-benchmark)[Choose and save the routing strategy](/get-started/choose-routing-strategy)[Send the first request and inspect the decision](/get-started/first-request-and-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](#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](#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](#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.