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

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

Install

First launch and connect models

Run the full benchmark

Choose and save the routing strategy

Send the first request and inspect the decision

Using Pi? Install and launch the Role-Model runtime first, then follow Pi integration 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 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 IDPrimary task typesTypical use

general.chattext.chatgeneral conversational responses

coder.patchcode.editpatch-oriented code editing

coder.reviewcode.edit, json.schema_adherencereview, critique, and structured verdicts

tool.agenttools.function_callingtool orchestration and structured tool calls

embedderembeddings.textretrieval and vector generation

classifiertext.classificationlabeling and taxonomy selection

language.detectortext.language_detectionlanguage 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

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.

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.

Install

Install the packaged role-model router runtime from GitHub Releases, or choose a source build if you are developing the repo.