role-modelrole-model<br>Search⌘K

role-modelGet StartedInstallFirst launch and connect modelsRun the full benchmarkChoose and save the routing strategyFirst request and inspect the decision

IntegrationsPi integrationDownstream OpenAI discovery

RuntimeRuntime UI tourProvider connectionsModels and role activationBenchmarks and evaluationObserve and telemetry analyticsRouting controls and decision review

RouterOverviewRouting modes, locality, and executionScoring strategies and tradeoffsCandidate selection and eligibilityScoring, tie-breaks, and decisionsFallbacks, failures, and observabilityHow routing works end to endProtocol-to-router mapping

ConceptsHow role-model worksRoles, tasks, and capabilitiesEndpoints and profilesPolicy and observabilityProtocol overviewRouting overview

ReferenceOverviewCanonical schemas referenceReason codes and rejection taxonomy

ProtocolProtocolEndpoint identityDeclared capability profilesObserved performance profilesCapability taxonomyRoles and tasksRouting policyRouter decision artifactTrace and usage artifacts

role-model<br>Capability-aware AI routing with a packaged reference runtime, explainable router decisions, and a protocol you can actually inspect.<br>Copy MarkdownOpen

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<br>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<br>Pi integration to install @try-works/pi-role-model, run /role-model setup, and choose<br>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 usegeneral.chattext.chatgeneral conversational responsescoder.patchcode.editpatch-oriented code editingcoder.reviewcode.edit, json.schema_adherencereview, critique, and structured verdictstool.agenttools.function_callingtool orchestration and structured tool callsembedderembeddings.textretrieval and vector generationclassifiertext.classificationlabeling and taxonomy selectionlanguage.detectortext.language_detectionlanguage identification

For the full role and task mental model, read<br>Roles, tasks, and capabilities. The deeper protocol contract<br>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<br>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<br>Start the packaged router and open the operator UI on the local machine.

Connect...