# Endpoints and profiles (/concepts/endpoints-and-profiles)
# Endpoints and profiles [#endpoints-and-profiles]
Role-model is endpoint-aware on purpose.
## Why not route by model name alone [#why-not-route-by-model-name-alone]
One base model can appear through multiple endpoints with different:
* providers
* runtimes
* regions or local devices
* tool support
* costs
* measured latency and reliability
That means routing should happen at the endpoint layer, where those operational differences are visible.
## The two main profile types [#the-two-main-profile-types]
Role-model uses:
* **declared profiles** for what an endpoint says it supports
* **observed profiles** for what measurements and benchmark evidence say it actually does
Declared data helps establish compatibility. Observed data helps compare real candidates once they are
eligible.
## Why this matters operationally [#why-this-matters-operationally]
This is also why the benchmark belongs in first-time setup. It helps populate observed quality data for the
exact endpoints you activated and assigned roles to.
For deeper reference, use:
* [Endpoint identity](/protocol/endpoint-identity)
* [Declared capability profiles](/protocol/declared-capability-profiles)
* [Observed performance profiles](/protocol/observed-performance-profiles)
# How role-model works (/concepts/how-role-model-works)
# How role-model works [#how-role-model-works]
`role-model` turns AI routing into a protocol-driven flow instead of a pile of model-specific conditionals.
## The end-to-end flow [#the-end-to-end-flow]
At a high level, the current baseline works like this:
1. **Discover or register endpoints.** Provider- or host-specific inputs are normalized into concrete
endpoint identities and capability profiles.
2. **Describe the request.** A request declares task type, required capabilities, modalities, tool needs,
context needs, and policy hints.
3. **Apply eligibility filters.** The router removes endpoints that fail hard requirements such as missing
capabilities, unsupported modalities, policy denies, or budget constraints.
4. **Score the remaining candidates.** The router compares eligible endpoints using quality, latency,
throughput, cost, reliability, and preference.
5. **Select and explain.** The router emits a `RouterDecision` with a chosen endpoint, exclusions,
selection reasons, and fallback metadata.
6. **Emit observability artifacts.** Trace spans, trace events, usage events, and observed performance can be
recorded alongside the decision.
## The pieces involved [#the-pieces-involved]
| Piece | Purpose |
| ----------------------- | ------------------------------------ |
| request | the work that needs to be satisfied |
| role and task metadata | the semantic shape of the work |
| endpoint identity | the concrete thing being routed to |
| declared profile | what an endpoint says it can do |
| observed profile | how it has actually been behaving |
| routing policy | the hard constraints and preferences |
| observability artifacts | the explanation and evidence trail |
## A concrete walkthrough [#a-concrete-walkthrough]
The current smoke baseline is a good small example.
The request asks for:
* task type `coder.edit`
* required capability `coder.edit`
* preferred capability `reasoning.multi_step`
* required modality `text`
* tool support
* balanced strategy
* local preference
The sample endpoints are:
| Endpoint | Capabilities |
| --------------------- | -------------------------------------------------------------- |
| `cli.local.coder` | `code.write`, `reasoning.multi_step`, `tools.function_calling` |
| `acp.remote.general` | `text.chat`, `tools.function_calling` |
| `mcp.remote.embedder` | `embeddings.text`, `tools.function_calling` |
The router then proceeds in order:
1. `cli.local.coder` remains eligible because it satisfies the required capability and modality.
2. `acp.remote.general` is excluded with `CAPABILITY_MISSING` because it does not satisfy `code.write`.
3. `mcp.remote.embedder` is excluded with `CAPABILITY_MISSING` for the same reason.
4. The remaining eligible endpoint is scored using declared and measured evidence.
5. The router chooses `cli.local.coder` and records why.
The emitted decision includes selection reasons such as:
* `BEST_TOTAL_SCORE`
* `DECLARED_PROFILE_USED`
* `MEASURED_PROFILE_USED`
* `LOCAL_PREFERENCE_APPLIED`
## Why the endpoint model matters [#why-the-endpoint-model-matters]
This flow is intentionally endpoint-centric.
The router is not asking "which model family sounds right?" It is asking "which concrete endpoint, with
this provider, runtime, policy shape, and observed behavior, is the best valid target for this request?"
That is what makes the protocol useful across different providers and future hosts.
## Read next [#read-next]
* [Install](/get-started/install)
* [Run the full benchmark](/get-started/run-full-benchmark)
* [Roles, tasks, and capabilities](/concepts/roles-tasks-and-capabilities)
* [How routing works end to end](/router/how-routing-works-end-to-end)
# Policy and observability (/concepts/policy-and-observability)
# Policy and observability [#policy-and-observability]
Role-model is not only about choosing a model-serving endpoint. It is also about making that choice
constrained and inspectable.
## Policy [#policy]
Routing policy gives the router explicit knobs for:
* strategy
* locality preferences
* capability and modality requirements
* tool requirements
* endpoint or provider allow and deny lists
* budget and privacy constraints
That lets operators express hard limits and optimization intent instead of burying them in ad hoc code.
## Observability [#observability]
The runtime can emit artifacts such as:
* `RouterDecision`
* trace spans and events
* usage events
* observed performance profiles
Together these make routing reviewable after the fact.
## Why these two belong together [#why-these-two-belong-together]
Policy without observability becomes opaque configuration.
Observability without policy becomes a post-hoc explanation of behavior you never constrained properly.
Role-model treats both as first-class parts of the routing contract.
# Protocol overview (/concepts/protocol-overview)
# Protocol overview [#protocol-overview]
The `role-model` protocol is the contract layer that lets routing systems talk about requests, endpoints,
policy, and observability in one stable vocabulary.
It is designed so hosts and providers can vary without forcing every integration to invent a new routing
shape.
## What the protocol owns [#what-the-protocol-owns]
The protocol defines schemas and terms for the main routing entities:
| Entity | Purpose |
| ---------------------------- | ----------------------------------------------------------------- |
| `EndpointIdentity` | names the concrete endpoint being considered |
| `DeclaredCapabilityProfile` | records what an endpoint says it supports |
| `ObservedPerformanceProfile` | records measured behavior such as latency, cost, and failure rate |
| `RoleDefinition` | describes a role such as `support` or `coder` |
| `TaskDefinition` | describes the unit of work being satisfied |
| `RoutingPolicy` | defines hard constraints, preferences, and tie-break behavior |
| `RouterDecision` | records the chosen endpoint, exclusions, and reasons |
| `TraceEvent` / `TraceSpan` | records execution-path timing and routing stages |
| `UsageEvent` | records accounting and request outcome metadata |
The deeper protocol pages on this site start at [Endpoint identity](/protocol/endpoint-identity) and run
through [Trace and usage artifacts](/protocol/trace-and-usage-artifacts).
## Protocol first, router second [#protocol-first-router-second]
This repository is organized around a simple rule: **the protocol is canonical, and hosts adapt to it**.
That means:
* the schemas are the source of truth
* generated types and validators should follow the schemas instead of redefining them
* router implementations are expected to consume and emit protocol-shaped data
The reference implementation in `role-model-router/` is important, but it is not the protocol itself.
## Why the protocol is endpoint-centric [#why-the-protocol-is-endpoint-centric]
The protocol routes against concrete endpoints because that is where meaningful differences live:
* one model may be available through multiple providers
* tool support can differ by endpoint
* runtime, device, region, and package metadata can differ
* measured latency, quality, freshness, or cost can differ
Two endpoints serving the same base model are not automatically interchangeable. The protocol makes that
difference explicit.
## Roles, tasks, and capabilities [#roles-tasks-and-capabilities]
The protocol separates three things that often get collapsed together:
| Concept | Meaning |
| ---------- | ------------------------------------------------ |
| role | the kind of worker or behavior being requested |
| task | the unit of work to be performed |
| capability | the concrete feature needed to perform that work |
For example, a code-editing flow might combine:
* a role like `coder`
* a task like `coder.edit`
* capabilities such as `code.write`, `reasoning.multi_step`, and `tools.function_calling`
That separation lets the router reason in a more durable way than "pick model X for prompt Y."
## Current implemented baseline [#current-implemented-baseline]
Today the repository already includes:
* protocol schemas and fixtures
* schema tooling and generated types
* deterministic routing behavior
* a packaged reference runtime and router UI
* smoke-path artifact generation for decisions, traces, usage, and observed performance
## Read next [#read-next]
* [Install](/get-started/install)
* [First launch and connect models](/get-started/first-launch-and-connect-models)
* [Roles, tasks, and capabilities](/concepts/roles-tasks-and-capabilities)
* [Protocol](/protocol)
* [Routing overview](/concepts/routing-overview)
# Roles, tasks, and capabilities (/concepts/roles-tasks-and-capabilities)
# Roles, tasks, and capabilities [#roles-tasks-and-capabilities]
Role-model separates three concepts that many systems collapse together:
* **role**: what kind of worker or behavior is being requested
* **task**: the unit of work to perform
* **capability**: the concrete feature required to perform that work
## Why that separation matters [#why-that-separation-matters]
This separation lets Router reason more durably than “pick model X for prompt Y.”
For example, a route might combine:
* role `coder`
* task `coder.edit`
* capabilities `coder.edit`, `reasoning.multi_step`, and `tools.function_calling`
That gives you semantic control without pretending that one model label permanently owns one workflow.
## Baseline role examples [#baseline-role-examples]
The baseline role set includes:
* `support`
* `coder`
* `coder.review`
* `operator`
* `embedder`
* `classifier`
* `language.detector`
Start with this page for the product mental model, then use [Roles and tasks](/protocol/roles-and-tasks)
when you need the protocol-level contract.
# Routing overview (/concepts/routing-overview)
# Routing overview [#routing-overview]
Routing in `role-model` is deterministic and explainable.
The goal is not only to choose an endpoint, but to produce answers to two questions:
1. which endpoints were valid candidates?
2. why was the final endpoint chosen over the others?
## The routing order [#the-routing-order]
The baseline router applies this order:
1. normalize request intent into an effective policy snapshot
2. reject candidates that fail hard constraints
3. score the remaining candidates across quality, latency, throughput, cost, reliability, and preference
4. redistribute weight when an entire metric is unknown for every eligible candidate
5. break near-ties by higher quality, lower latency, higher reliability, then stable `endpoint_id`
6. emit a `RouterDecision` with ranked fallbacks and reason codes
## Eligibility comes first [#eligibility-comes-first]
Before scoring, the router filters out endpoints that cannot legally or practically satisfy the request.
Baseline exclusion families include:
* `CAPABILITY_MISSING`
* `MODALITY_UNSUPPORTED`
* `CONTEXT_TOO_SMALL`
* `TOOLS_UNSUPPORTED`
* `POLICY_DENY_ENDPOINT`
* `POLICY_DENY_REMOTE`
* `BUDGET_EXCEEDED`
* `PROVIDER_OFFLINE`
This matters because the router should never "score its way out of" a hard incompatibility.
## Measured evidence beats declarations [#measured-evidence-beats-declarations]
After eligibility, the router prefers measured evidence when it exists:
* latency and throughput
* failure behavior
* quality signals
* freshness and confidence
* cost estimates
Catalog-derived cost data and declared profiles still matter, but measured evidence wins when it is present.
## Worked example: the gateway smoke route [#worked-example-the-gateway-smoke-route]
The smoke request asks for:
* `coder.edit`
* text output
* tool support
* balanced strategy
* local preference
* a strict per-request budget cap
The candidate set contains three endpoints:
| Endpoint | Result |
| --------------------- | -------- |
| `cli.local.coder` | eligible |
| `acp.remote.general` | excluded |
| `mcp.remote.embedder` | excluded |
Why the exclusions happen:
* `acp.remote.general` does not provide the required `code.write` capability
* `mcp.remote.embedder` does not provide the required `code.write` capability
Both exclusions are recorded as `CAPABILITY_MISSING`.
That leaves `cli.local.coder` as the only eligible candidate. The router then records the final decision
with selection reasons such as:
* `BEST_TOTAL_SCORE`
* `DECLARED_PROFILE_USED`
* `MEASURED_PROFILE_USED`
* `LOCAL_PREFERENCE_APPLIED`
## Why the artifacts matter [#why-the-artifacts-matter]
The decision is only one artifact in the routing story.
The baseline can also emit:
* `trace-spans.json` to show routing phases such as eligibility, scoring, and selection
* `usage-events.jsonl` to show request and accounting metadata
* `observed-performance.json` to show measured endpoint behavior
That artifact set is what makes routing explainable after the fact.
## Read next [#read-next]
* [Router overview](/router/overview)
* [How routing works end to end](/router/how-routing-works-end-to-end)
* [Candidate selection and eligibility](/router/candidate-selection-and-eligibility)
* [Scoring, tie-breaks, and decisions](/router/scoring-tie-breaks-and-decisions)
* [Router decision artifact](/protocol/router-decision-artifact)
# Core vocabulary (/core-vocabulary)
# Core vocabulary [#core-vocabulary]
The protocol uses a small set of precise terms. The rest of the docs assume these meanings.
| Term | Meaning |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **endpoint** | A concrete execution target the system can route to. |
| **model-serving endpoint** | A concrete endpoint whose identity includes the model lineage it serves and whose declared and observed behavior are tracked independently from other endpoints. |
| **endpoint identity** | The stable, protocol-shaped description of an endpoint's provider, runtime, model, region, and deployment attributes. |
| **declared profile** | Provider-declared capabilities and constraints such as supported capabilities, modalities, context window, and tool-calling support. |
| **observed profile** | Measured behavior over time: latency, throughput, failures, cost estimates, freshness, and confidence. |
| **capability** | A stable protocol identifier for something an endpoint can do, such as `tools.function_calling` or `coder.edit`. |
| **modality** | The input or output form required by the task, such as text, vision-text, or audio-text. |
| **role definition** | A protocol object describing an execution persona, its supported task families, constraints, tool policy, and output contracts. |
| **role binding** | The record that binds a role to a specific endpoint and states whether that binding is active. |
| **task definition** | A protocol object describing a unit of work, its required inputs, capabilities, quality metrics, and allowed roles. |
| **task execution profile** | A role-and-task-specific patch layer that adjusts required/preferred capabilities or policy for execution. |
| **routing policy** | Hard constraints plus optimization intent: strategy, locality preference, denies/allows, privacy, budget, and targets. |
| **router decision** | The explainable routing output containing eligibility, scores, chosen endpoint, fallbacks, reason codes, and the applied policy snapshot. |
| **trace span** | A timed phase of routing or execution, such as eligibility evaluation or provider decode. |
| **trace event** | A point event that links routing, tracing, usage, and profile updates into one observable lifecycle. |
| **usage event** | The accounting and execution record for a request: tokens, latency, provider, endpoint, cost estimate, and optional error class. |
## Important distinctions [#important-distinctions]
### Endpoint vs. model [#endpoint-vs-model]
A **model** is not the same thing as a **routable target**.
In role-model, model lineage is carried inside `EndpointIdentity` through fields such as `model_id`,
`package_id`, and `variant_id`. The router still chooses the **endpoint**, because that is where provider,
runtime, region, quantization, and observed-performance differences actually live.
Put differently: a model explains **what family of system is being served**; an endpoint explains **which
concrete deployment of that model is actually being selected**.
### Candidate vs. endpoint [#candidate-vs-endpoint]
In routing docs, a **candidate** means a **candidate endpoint**.
The term "candidate" describes the endpoint's temporary role inside the routing algorithm. It does not mean an
abstract candidate model.
### Declared vs. observed [#declared-vs-observed]
Declared data answers "what this endpoint says it supports." Observed data answers "what measurement says it
actually does." The router uses both, but measured evidence is the stronger signal.
### Role vs. task [#role-vs-task]
A role is the operating contract and persona. A task is the unit of work. The protocol keeps them separate so
one role can support multiple tasks and one task can permit multiple roles.
### Policy vs. decision [#policy-vs-decision]
Policy is an input. A router decision is the output produced after that policy has been applied to a candidate
set.
# Choose and save the routing strategy (/get-started/choose-routing-strategy)
# Choose and save the routing strategy [#choose-and-save-the-routing-strategy]
After the full benchmark finishes, review the results and then decide how Router should optimize.
## The rule [#the-rule]
Do **not** choose the routing strategy first and then benchmark to justify it.
The benchmark should come first. Strategy selection should be a response to observed quality, latency, cost,
and reliability tradeoffs in your configured endpoint set.
## First separate the knobs [#first-separate-the-knobs]
The runtime exposes more than one routing control:
* **scoring strategy**: `balanced`, `quality`, `latency`, `cost`
* **runtime routing mode**: `baseline`, `controller`, `difficulty`, `hybrid`
* **execution scope**: `hybrid`, `local_only`, `remote_only`, `decision_only`
This page is primarily about choosing the **scoring strategy** after benchmarking.
If you are choosing whether the runtime should use difficulty-aware routing, controller guidance, or local vs
remote execution scope, read
[/router/routing-modes-locality-and-execution](/router/routing-modes-locality-and-execution) too.
## The baseline strategy modes [#the-baseline-strategy-modes]
The current baseline strategy vocabulary is:
* `balanced`
* `quality`
* `latency`
* `cost`
These strategies change how the router weights quality, latency, throughput, cost, reliability, and
preference during candidate comparison.
## What each strategy is trying to do [#what-each-strategy-is-trying-to-do]
| Strategy | What it optimizes for | Good first use case | What evidence matters most |
| ---------- | ------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
| `balanced` | overall health across quality, latency, cost, and reliability | default production posture when no single metric should dominate | mixed benchmark and runtime evidence |
| `quality` | strongest output quality with reliability support | coding, review, and other quality-sensitive tasks | benchmark judge scores and quality spread |
| `latency` | fastest healthy response | interactive UX and low-wait experiences | latency, throughput, and endpoint health |
| `cost` | cheapest healthy eligible execution path | budget-sensitive or high-volume workloads | cost estimates, budget context, and failure behavior |
Strategy does not bypass hard routing rules. Capability, privacy, tools, and budget constraints still remove
candidates before scoring starts.
## Where difficulty and local/remote choices fit [#where-difficulty-and-localremote-choices-fit]
`difficulty` is not just another weight preset beside `balanced` or `quality`.
It is a **runtime routing mode** that classifies the request as `easy`, `medium`, or `hard` and then uses
that signal to decide which endpoints should stay in play for the request.
Likewise, `local_only`, `remote_only`, and `hybrid` are **execution-scope** choices, not scoring weights.
Those settings answer:
* should the runtime be allowed to execute locally, remotely, or both?
* should controller guidance participate?
* should difficulty-aware endpoint ceilings participate?
Then the scoring strategy answers how the remaining candidate set should be compared.
## How to interpret the benchmark before deciding [#how-to-interpret-the-benchmark-before-deciding]
Use the benchmark results to decide:
* whether quality differences are large enough to justify `quality`
* whether latency differences dominate user experience strongly enough to justify `latency`
* whether cost variation is meaningful enough to justify `cost`
* whether the set is healthy and balanced enough for `balanced`
The benchmark most directly improves the **quality** side of routing because it writes quality evidence back
into observed profiles.
Latency, throughput, reliability, and cost still matter too, but they are often shaped by a mix of benchmark
results, live usage, and budget or target settings.
## The practical selection rule [#the-practical-selection-rule]
Choose the strategy that matches the tradeoff you actually want to preserve in production:
* pick `balanced` when you want the healthiest all-around winner
* pick `quality` when a quality leader is worth extra latency or spend
* pick `latency` when user wait time is the main product constraint
* pick `cost` when routing spend is a first-class operational constraint
For the full operator-facing explanation, including baseline weights and signal behavior, read
[/router/strategy-modes-and-tradeoffs](/router/strategy-modes-and-tradeoffs) and
[/router/routing-modes-locality-and-execution](/router/routing-modes-locality-and-execution).
## Save strategy after the evidence review [#save-strategy-after-the-evidence-review]
The canonical first-time flow is:
1. configure endpoints and roles
2. run the full benchmark
3. review benchmark and routing-quality outcomes
4. choose and save the routing strategy
5. validate with a real routed request
## What to inspect after saving [#what-to-inspect-after-saving]
After you save the strategy, use Router surfaces to check:
* candidate rankings
* benchmark-influenced quality posture
* fallback order
* whether the chosen strategy matches the benchmark story you just saw
## Next [#next]
Continue to [Send the first request and inspect the decision](/get-started/first-request-and-decision).
# First launch and connect models (/get-started/first-launch-and-connect-models)
# First launch and connect models [#first-launch-and-connect-models]
After installation:
```bash
role-model-router
```
The packaged runtime opens the local operator UI and serves the router on your machine.
## The first-time setup sequence [#the-first-time-setup-sequence]
Use this order:
1. launch the runtime
2. connect the local backend or remote provider accounts you plan to use
3. activate the actual models or endpoints that should compete in routing
4. assign roles to those models
5. only then run the full benchmark
That order matters because the benchmark should grade the real candidate set you intend to route across.
## What to configure in the UI [#what-to-configure-in-the-ui]
The operator shell is organized around a few core areas:
* **Connect** for the first-run handoff into the local and remote setup paths
* **Local** for local backends, local models, and local endpoint state
* **Remote** for provider accounts and remote execution paths
* **Models** for benchmark and model-level routing context
* **Router** for candidate, config, and decision visibility
* **Observe** for request and telemetry evidence
* **System** for readiness and runtime health diagnostics
## Which roles to assign [#which-roles-to-assign]
The baseline role IDs include:
* `support`
* `coder`
* `coder.review`
* `operator`
* `embedder`
* `classifier`
* `language.detector`
Only assign the roles you genuinely want a model to serve. The benchmark and later routing decisions should
reflect your real operator intent, not a maximal test matrix.
## What “ready” means before benchmarking [#what-ready-means-before-benchmarking]
Before you move on, you should have:
* the providers or local backends connected
* the endpoint or model activations in place
* the intended role bindings assigned
* at least two plausible candidates for any route family you want to compare
## Next [#next]
Continue to [Run the full benchmark](/get-started/run-full-benchmark).
For connection-method details, read [Provider connections](/runtime/provider-connections).
# First request and inspect the decision (/get-started/first-request-and-decision)
# First request and inspect the decision [#first-request-and-inspect-the-decision]
Once the endpoints are configured, roles are assigned, the full benchmark has completed, and the routing
strategy is saved, send a real request through the runtime.
## What to validate [#what-to-validate]
Your first request should confirm:
* the expected candidates appear in Router
* excluded endpoints show sensible reason codes
* the chosen endpoint matches the configured strategy and the benchmark evidence
* the fallback list is plausible
* Observe surfaces show the request, telemetry, and decision receipts you expect
## Where to inspect it [#where-to-inspect-it]
Use these UI areas together:
* **Router -> Candidates** to inspect the current competitive set
* **Router -> Decisions** to inspect the ranked result
* **Router -> Decision detail** to inspect the selected endpoint, fallbacks, and evidence
* **Observe** to inspect the request and telemetry trail around that decision
## What a healthy first result looks like [#what-a-healthy-first-result-looks-like]
A healthy first result is not just “the request returned text.”
It should also be true that:
* the winning endpoint is explainable
* exclusions are legible
* benchmark-influenced quality signals make sense
* the saved strategy is actually visible in the decision context
That is the key product promise of role-model: not only routing, but explainable routing.
## Continue deeper [#continue-deeper]
* [Router overview](/router/overview)
* [Runtime UI tour](/runtime/runtime-ui-tour)
* [Fallbacks, failures, and observability](/router/fallbacks-failures-and-observability)
# Install (/get-started/install)
# Install [#install]
For most users, the right install path is the packaged standalone `role-model-router` runtime.
It ships as a release archive plus installer scripts. Source builds are still supported, but they are
primarily for contributors working on the router or protocol implementation itself.
## Recommended: packaged release [#recommended-packaged-release]
### macOS and Linux [#macos-and-linux]
```bash
curl -fsSL https://raw.githubusercontent.com/try-works/role-model/main/scripts/install.sh | sh
```
This installs the latest GitHub Release archive under
`~/.local/share/role-model-router///` and creates a `role-model-router` launcher in
`~/.local/bin`.
### Windows [#windows]
```powershell
irm https://raw.githubusercontent.com/try-works/role-model/main/scripts/install.ps1 | iex
```
This installs the latest GitHub Release archive under
`%LOCALAPPDATA%\Programs\RoleModelRouter\\\` and creates a `role-model-router.cmd`
launcher.
If your shell cannot find `role-model-router` immediately after installation, open a new terminal so it
picks up the updated `PATH`.
## Manual downloads [#manual-downloads]
If you do not want to use the installer scripts, download the matching archive from
[GitHub Releases](https://github.com/try-works/role-model/releases).
Current release assets are expected to include:
* `role-model-router-linux-x64.tar.gz`
* `role-model-router-darwin-x64.tar.gz`
* `role-model-router-darwin-arm64.tar.gz`
* `role-model-router-win32-x64.zip`
* `SHA256SUMS.txt`
Before running a manual download, verify the archive checksum against `SHA256SUMS.txt`.
After extracting:
* Windows: run `Role-Model.bat` or `role-model-runtime.exe`
* macOS/Linux: run `role-model-runtime`
## Using Pi [#using-pi]
If you want Pi to route through Role-Model, install and launch the runtime first, then install the public Pi
package:
```bash
pi install npm:@try-works/pi-role-model
```
Inside Pi, run:
```text
/role-model setup
/role-model doctor
/role-model alias choose
```
For endpoint overrides, remote-runtime trust, auth behavior, and the full command list, read
[Pi integration](/integrations/pi).
## Source builds [#source-builds]
Use a source build when you want to:
* modify the router itself
* work on the runtime UI or host bridge
* validate changes against the repository test and packaging flows
For that workflow, use the repository root `README.md` and contributor build commands.
## Next [#next]
After install, continue to [First launch and connect models](/get-started/first-launch-and-connect-models).
# Run the full benchmark (/get-started/run-full-benchmark)
# Run the full benchmark [#run-the-full-benchmark]
Benchmarking is part of first-time setup, not an optional afterthought.
Once your endpoints, models, and roles are configured, run the **full benchmark** before you choose a
routing strategy.
## Why benchmark before strategy selection [#why-benchmark-before-strategy-selection]
The router can use measured and benchmark-derived quality information when ranking candidates.
If you choose a routing strategy before benchmarking, you are effectively tuning policy without the evidence
that should inform that policy.
## What the benchmark does [#what-the-benchmark-does]
The benchmark flow:
* runs the configured benchmark cases against the selected endpoint set
* grades outputs through the benchmark judge path
* writes judge scores into observed endpoint profiles
* makes those quality signals available to later routing decisions
That means the benchmark is not just a report. It actively improves the quality evidence that Router uses.
## Recommended first-run benchmark policy [#recommended-first-run-benchmark-policy]
For your first full setup:
1. benchmark the real endpoints you intend to route across
2. prefer the full run instead of a quick sanity check
3. wait for the run to finish before touching routing-strategy settings
4. review the endpoint-level quality spread, failures, and latency tradeoffs
## Where to run it [#where-to-run-it]
Use **Models -> Benchmark** in the operator UI.
That page is the canonical surface for:
* starting the run
* seeing per-model scores
* comparing recent runs
* understanding how benchmark scores feed later routing quality
## What you want to learn from the first full run [#what-you-want-to-learn-from-the-first-full-run]
You are trying to answer:
* which endpoints are clearly strong for your workload
* which endpoints are weak or unstable
* whether local and remote candidates are both viable
* whether cost, latency, or quality tradeoffs are large enough to justify a specific strategy
* whether any endpoint changes should force another benchmark before you trust later routing decisions
## Next [#next]
After the benchmark completes, continue to
[Choose and save the routing strategy](/get-started/choose-routing-strategy).
# role-model (/)
# role-model [#role-model]
`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]
1. [Install](/get-started/install)
2. [First launch and connect models](/get-started/first-launch-and-connect-models)
3. [Run the full benchmark](/get-started/run-full-benchmark)
4. [Choose and save the routing strategy](/get-started/choose-routing-strategy)
5. [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:
1. **Requests** describe task type, required capabilities, modalities, tool needs, and constraints.
2. **Roles and tasks** describe the semantic shape of the work.
3. **Endpoint identities and profiles** describe concrete routable endpoints rather than abstract model names.
4. **Routing policy** applies hard denies, preferences, budgets, and deterministic tie-break rules.
5. **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:
1. **Normalize request intent.** Build the effective policy snapshot from the request plus role/task metadata.
2. **Narrow the candidate set.** Keep only endpoints that match the requested role, task, and policy scope.
3. **Apply hard eligibility checks.** Reject endpoints that fail capability, modality, tool, locality, budget, or binding requirements.
4. **Score the eligible endpoints.** Compare quality, latency, throughput, cost, reliability, and preference using measured evidence first, then declared data and neutral defaults.
5. **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.
## Taxonomy V1 examples [#taxonomy-v1-examples]
The runtime taxonomy V1 catalog starts with groups, then roles, then task types. Examples:
| Group | Role | Task examples |
| ----------------------------------- | ------------ | ---------------------------------------------------------- |
| `engineering` | `coder` | `coder.edit`, `coder.review` |
| `engineering` / `governance_safety` | `security` | `security.audit`, `security.threat_model` |
| `product_design` | `product` | `product.requirements`, `product.acceptance` |
| `knowledge_research` | `researcher` | `researcher.web_research.current`, `researcher.fact_check` |
| `communication` | `support` | `support.ticket.reply`, `support.triage` |
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:
1. install and launch the packaged runtime
2. connect the local or remote endpoints you actually plan to use
3. activate models and assign roles
4. run the full benchmark on that real candidate set
5. review the benchmark results
6. choose and save the routing strategy
7. 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 the router (/install)
# Install the router [#install-the-router]
This top-level URL is kept for compatibility with older links.
The canonical install page now lives at [/get-started/install](/get-started/install).
## Recommended path [#recommended-path]
If you are new to role-model, start here:
1. [Install](/get-started/install)
2. [First launch and connect models](/get-started/first-launch-and-connect-models)
3. [Run the full benchmark](/get-started/run-full-benchmark)
4. [Choose and save the routing strategy](/get-started/choose-routing-strategy)
## Installer commands [#installer-commands]
If you only need the direct install commands:
* macOS/Linux: `curl -fsSL https://raw.githubusercontent.com/try-works/role-model/main/scripts/install.sh | sh`
* Windows: `irm https://raw.githubusercontent.com/try-works/role-model/main/scripts/install.ps1 | iex`
For manual downloads, checksums, and source-build guidance, use the canonical page at
[/get-started/install](/get-started/install).
## Pi package [#pi-package]
After the runtime is installed and running, Pi users can install:
```bash
pi install npm:@try-works/pi-role-model
```
Read [Pi integration](/integrations/pi) for setup commands, alias selection, endpoint overrides, and runtime
ownership boundaries.
# Downstream OpenAI discovery (/integrations/downstream-openai-discovery)
# Downstream OpenAI discovery [#downstream-openai-discovery]
Role-Model exposes OpenAI-compatible discovery surfaces so downstream clients can discover routable aliases
without reading runtime internals.
Pi uses this contract through the `@try-works/pi-role-model` package, but the same idea applies to other
OpenAI-compatible consumers.
## Discovery surfaces [#discovery-surfaces]
Role-Model exposes two related surfaces:
| Endpoint | Purpose |
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
| `/v1/models` | compact OpenAI-compatible model list for broad client compatibility |
| `/api/role-model/downstream/openai` | richer Role-Model discovery contract for aliases, capability metadata, and downstream setup |
Use `/v1/models` when a client only understands the standard model-list shape.
Use `/api/role-model/downstream/openai` when a client can consume Role-Model-specific alias and capability
metadata.
## What aliases describe [#what-aliases-describe]
Each downstream alias describes a routable Role-Model posture rather than one fixed provider model.
Discovery records can include:
* conservative `context_window` and output-token limits
* Pi-compatible input affordances such as text and image support
* required or supported capabilities
* whether tools, structured output, reasoning, or hosted features are available
* sanitized endpoint information for diagnostics
The runtime computes this from registry state, catalog metadata, runtime alias config, endpoint readiness, and
the current routing strategy inputs.
## Conservative limits [#conservative-limits]
An alias can span more than one endpoint. Its published limits are intentionally conservative so a downstream
client does not send a request that only part of the alias pool can handle.
For example, if an alias can route across multiple endpoints, the alias should publish the safe aggregate
context and output limits for the currently routable set, not the biggest limit seen anywhere in the pool.
## Capability-aware routing [#capability-aware-routing]
Discovery is not only descriptive. The runtime also uses inferred request capabilities before scoring.
For chat and responses requests, Role-Model can infer requirements from payload shape, including:
* text or image input
* tool use
* structured output
* reasoning
* hosted search or provider-native tool requests
Those inferred requirements appear in routing diagnostics such as `routingDiagnostics.capabilityEligibility`.
That makes it possible to explain why an endpoint was excluded before scoring.
## Sanitized endpoint identifiers [#sanitized-endpoint-identifiers]
Rich discovery avoids exposing credential-shaped account labels as downstream endpoint ids.
Downstream clients should treat discovery ids as diagnostic handles, not as credential material or stable
provider-account secrets.
## Read next [#read-next]
* [Pi integration](/integrations/pi)
* [Routing modes, locality, and execution](/router/routing-modes-locality-and-execution)
* [Candidate selection and eligibility](/router/candidate-selection-and-eligibility)
# Pi integration (/integrations/pi)
# Pi integration [#pi-integration]
The `@try-works/pi-role-model` package connects Pi to an already-running Role-Model runtime.
It does not install, start, stop, update, or own the runtime process. Start `role-model-router` first, then
install the package into Pi.
## Install the package [#install-the-package]
For normal use, install the public package from npm:
```bash
pi install npm:@try-works/pi-role-model
```
For local checkout testing from this repository:
```bash
pi install ./packages/pi-role-model
```
## Connect Pi to the runtime [#connect-pi-to-the-runtime]
By default the package connects to the local runtime at `http://127.0.0.1:3456`.
To use a different local runtime endpoint, set `ROLE_MODEL_ENDPOINT` before starting Pi:
```bash
ROLE_MODEL_ENDPOINT=http://127.0.0.1:4567 pi
```
Remote endpoints are blocked by default. Only enable remote runtime access for a trusted endpoint and trusted
project context with explicit `allowRemote` behavior, such as launching Pi with `ROLE_MODEL_ALLOW_REMOTE=1`
when that is the intended trust boundary.
If the runtime reports `authentication.required`, the package fails closed. The current package does not read,
copy, print, or sync Pi auth files.
## Setup commands [#setup-commands]
Inside an interactive Pi session, run:
```text
/role-model setup
/role-model status
/role-model doctor
```
`/role-model setup` discovers the runtime and registers the `role-model` provider from Role-Model's
downstream OpenAI discovery endpoint.
`/role-model doctor` checks runtime health, version discovery, downstream discovery, alias discovery, and
provider registration state.
`pi -p "/role-model status"` is unsupported. Pi print mode does not currently invoke package slash commands, so treat that as an upstream Pi bug or limitation rather than as a Role-Model routing failure.
## Alias commands [#alias-commands]
Use aliases to select the Role-Model routing posture Pi should use:
```text
/role-model alias list
/role-model alias recommended
/role-model alias choose
/role-model alias use
```
`/role-model alias use ` stores the selected alias and asks Pi to switch the active model when Pi exposes active model selection to the package.
For explicit provider prompts, use the provider-relative Role-Model alias that Pi lists for provider `role-model`, for example:
```bash
pi --no-session --provider role-model --model baseline.remote-only -p ""
```
`baseline.remote-only` is the canonical provider-relative form for explicit provider calls. `role-model/` is compatibility-only for Pi surfaces that explicitly require a qualified id.
If a user tries a foreign id such as `gpt-4o` under provider `role-model`, send them back to `/role-model alias list` and `/role-model alias recommended`.
## What gets registered [#what-gets-registered]
The package registers:
* provider id: `role-model`
* canonical model ids shaped as provider-relative aliases such as `baseline.remote-only`
* OpenAI-compatible downstream base URL from `/api/role-model/downstream/openai`
Role-Model remains the routing authority. Pi sends model requests to the Role-Model downstream endpoint, and
the runtime uses its current aliases, roles, tasks, endpoint capability metadata, and routing policy to choose
the actual endpoint.
## Taxonomy-aware requests [#taxonomy-aware-requests]
`@try-works/pi-role-model` ships a compact taxonomy V1 snapshot and discovers the runtime taxonomy when the
runtime is reachable. Pi uses progressive disclosure for classification:
1. read compact groups such as `engineering`, `product_design`, and `governance_safety`
2. choose likely roles such as `coder`, `security`, `researcher`, `support`, or `product`
3. load task details only for likely roles
4. send advisory `role_model.intent` metadata with the selected role, task, capabilities, modalities, tool
classes, confidence, evidence, and alternatives
Examples include `coder.edit`, `security.audit`, `researcher.web_research.current`,
`support.ticket.reply`, and `product.requirements`.
The runtime validates the metadata against its active taxonomy. Unknown advisory fields are ignored with
diagnostics instead of causing the request to fail, and the router/controller fall back to runtime policy when
client metadata is stale or too uncertain.
## Runtime ownership boundary [#runtime-ownership-boundary]
The Pi package is intentionally narrow:
* it discovers an externally running runtime
* it registers the Role-Model provider with Pi
* it provides setup, diagnostics, and alias-selection commands
* it ships a Pi skill that points users back to the Role-Model runtime documentation
It does not manage runtime lifecycle, install runtime binaries, copy Pi credentials, run benchmarks, or change
Role-Model provider account setup.
Raw HTTP `curl` calls to the runtime remain debug-only fallback tools when diagnosing Pi or runtime issues. They are not the primary supported integration path when the Pi provider path is healthy.
## Read next [#read-next]
* [Install the runtime](/get-started/install)
* [Downstream OpenAI discovery](/integrations/downstream-openai-discovery)
* [Routing controls and decision review](/runtime/routing-controls-and-decision-review)
# What role-model defines (/introduction)
# What role-model defines [#what-role-model-defines]
`role-model` is an open protocol for capability-aware AI routing.
It gives a system a shared way to describe:
* the request being routed
* the task and role requirements behind that request
* the concrete endpoints that can satisfy it
* the routing policy that constrains selection
* the observability artifacts that explain what happened
## Why this exists [#why-this-exists]
Most AI integrations start by hard-coding a model name and then slowly accumulate one-off rules for cost,
latency, locality, tool support, and fallback behavior.
`role-model` turns that into an explicit contract:
1. define the work as a task
2. describe the endpoint as a concrete routable identity with declared and observed profiles
3. apply policy consistently
4. emit explainable artifacts for the final decision
That makes routing easier to audit, compare, evolve, and move across hosts or providers.
## What role-model is [#what-role-model-is]
`role-model` is best understood as two connected layers:
| Layer | Purpose |
| ------------------- | --------------------------------------------------------------- |
| `role-model` | the protocol and contract layer |
| `role-model-router` | the deterministic reference implementation and packaged runtime |
The protocol defines the vocabulary. The router shows how that vocabulary can be implemented in a stable
baseline.
## The protocol boundary [#the-protocol-boundary]
role-model standardizes the **protocol artifacts** that describe AI endpoints and the decisions made about
them. It does **not** make the router implementation canonical.
The design rule is simple:
> The combination of protocol docs and JSON Schemas under `protocol/schemas/` is the canonical contract.
That means generated types, validators, adapters, registries, or routers are allowed to mirror the protocol,
but they are not allowed to redefine it.
## Protocol ownership versus router ownership [#protocol-ownership-versus-router-ownership]
| Protocol-owned | Router-implementation-owned |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| JSON Schemas for identity, profiles, roles, tasks, policy, decisions, traces, and usage | how candidates are discovered before being passed into a router |
| the meaning of each field and artifact | weight tuning, neutral defaults, and optimization formulas |
| the shape of an explainable router decision | registry backends, cache layers, transport integration |
| the observability artifacts emitted around routing and execution | deployment topology, scheduling, retries beyond the protocol artifacts themselves |
The reference router is important because it demonstrates a coherent mapping from those protocol objects to a
selection outcome, but the router remains **an implementation of the protocol**, not the definition of it.
## What role-model is not [#what-role-model-is-not]
`role-model` is not:
* a promise that one model permanently owns one role
* a single hosted runtime or orchestration product
* a provider-specific SDK abstraction
* a replacement for low-level schemas, traces, or usage records
Roles in `role-model` are assigned through routing metadata and policy, not by pinning a role forever to a
single model name.
## The problem domains role-model models [#the-problem-domains-role-model-models]
The protocol gives names and shapes to the objects a role-aware model-routing system needs:
* **Roles and tasks** as the semantic description of the work
* **Endpoint identity** as the concrete model-serving deployment the router may choose
* **Declared capability profiles** as what an endpoint claims to support
* **Observed performance profiles** as what measurements say it actually does
* **Capability taxonomy** as the stable compatibility language used across profiles, roles, tasks, and policy
* **Routing policy** as hard constraints and optimization intent
* **Router decisions, traces, and usage artifacts** as the explainable output and evidence trail
## Role, model, and endpoint [#role-model-and-endpoint]
role-model is not just an endpoint catalog, and it is not just a model picker.
It is a protocol for taking a **role/task-shaped request** and mapping it onto a **concrete endpoint that
serves a model**.
In that stack:
* the **role** describes the execution contract
* the **task** describes the unit of work
* the **model** provides the capability family being invoked
* the **endpoint** is the real deployment target the router can actually choose
## Why endpoints are the routing unit [#why-endpoints-are-the-routing-unit]
role-model routes to **endpoints**, not bare model names.
That does **not** mean models are unimportant. It means model identity alone is not enough to route safely.
The same base model may be served by multiple endpoints with different:
* provider and serving surface
* runtime version
* region or locality
* quantization and precision
* observed latency, quality, failure behavior, freshness, or cost
role-model therefore preserves the model inside endpoint identity, but performs routing at the endpoint level
where those operational differences are actually visible.
## What is implemented today [#what-is-implemented-today]
Today the repository already includes a working baseline:
* canonical JSON Schemas and fixtures
* generated types and schema tooling
* a deterministic reference router core
* a packaged runtime you can install from GitHub Releases
* a local operator UI and reference routing artifacts for decisions, traces, usage, and observed performance
Some future host families and runtime surfaces are still architecture-stage. The public docs describe the
implemented baseline first and treat future extensions as exactly that: extensions.
## The canonical dataflow [#the-canonical-dataflow]
## Where to go next [#where-to-go-next]
* [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)
* [How role-model works](/concepts/how-role-model-works)
* [Routing overview](/concepts/routing-overview)
* [Core vocabulary](/core-vocabulary)
# Capability taxonomy (/protocol/capability-taxonomy)
# Capability taxonomy [#capability-taxonomy]
Capabilities are **stable protocol identifiers**, not one-off strings invented by individual adapters.
The capability taxonomy schema defines a versioned list of capability records, each with:
* `id`
* `family`
* `description`
## Why a stable taxonomy matters [#why-a-stable-taxonomy-matters]
The same identifiers are reused in:
* declared capability profiles
* role definitions
* task definitions
* task execution profiles
* routing policy
* router eligibility checks
Without a stable taxonomy, "capability matching" would collapse into string conventions with no protocol
guarantees.
## Baseline capability families [#baseline-capability-families]
The baseline docs group capabilities into families such as:
| Family | Examples |
| ------------------------- | --------------------------------------------------------------------------------- |
| text | `text.chat`, `text.translation`, `text.classification`, `text.language_detection` |
| reasoning and code | `reasoning.multi_step`, `code.chat`, `coder.edit`, `json.schema_adherence` |
| tool use | `tools.function_calling` |
| embeddings and multimodal | `embeddings.text`, `multimodal.vision_text`, `multimodal.audio_text` |
| media I/O | `image.generation`, `image.understanding`, `audio.asr`, `audio.tts` |
| runtime and decoding | `adapter.lora_runtime`, `decoding.constrained` |
## Required, preferred, and forbidden [#required-preferred-and-forbidden]
The protocol uses three different relationship types:
* **required capability**: the candidate must have it or be rejected
* **preferred capability**: the candidate should have it and may receive a scoring bonus
* **forbidden capability**: the candidate must not have it in the relevant role context
These are not interchangeable. Required capabilities affect eligibility; preferred capabilities influence
scoring; forbidden capabilities act as hard denies in role-aware routing.
## Capability vs. modality [#capability-vs-modality]
The taxonomy identifies what the endpoint can do. Modalities identify what forms of data it can process.
For example:
* `tools.function_calling` is a capability
* text, vision-text, or audio-text are modalities
An endpoint might satisfy one and not the other, which is why the router evaluates both.
# Declared capability profiles (/protocol/declared-capability-profiles)
# Declared capability profiles [#declared-capability-profiles]
`DeclaredCapabilityProfile` is the self-declared side of endpoint description. It is the protocol layer that
states what an endpoint claims to support before measured evidence is available.
## Schema fields [#schema-fields]
| Field | Meaning |
| ------------------------ | ------------------------------------------------------------------ |
| `endpoint_id` | the endpoint this profile applies to |
| `capabilities` | stable capability identifiers the endpoint claims to support |
| `modalities` | the forms of input or output the endpoint claims to handle |
| `max_context_tokens` | the largest context window the endpoint claims to support |
| `tool_calling.supported` | whether the endpoint can perform tool calling |
| `tool_calling.style` | the tool-calling shape: `openai`, `json`, or `none` |
| `supports_embeddings` | whether embedding generation is supported |
| `platform_constraints` | operational constraints that matter to scheduling or compatibility |
## What the declared profile is for [#what-the-declared-profile-is-for]
The declared profile establishes the **eligibility floor**:
* missing required capability -> reject
* missing required modality -> reject
* context window too small -> reject
* tool use required but unsupported -> reject
These are hard compatibility questions. They cannot be answered from latency or cost metrics alone.
## Capabilities vs. modalities [#capabilities-vs-modalities]
The protocol treats capabilities and modalities as related but distinct:
* a **capability** names something the endpoint can do
* a **modality** names the shape of data it can accept or emit
For example, an endpoint might support text chat as a capability but still not support an image modality.
## What declared data cannot prove [#what-declared-data-cannot-prove]
Declared data is necessary, but it is not enough to prove:
* real latency under production load
* reliability and failure classes
* actual cost behavior
* judge-scored quality
* freshness of current measurements
That is why the protocol also models `ObservedPerformanceProfile`.
## Why the router still needs this layer [#why-the-router-still-needs-this-layer]
A router cannot wait for perfect measurements on every endpoint. The declared layer gives it a baseline
compatibility language even when:
* an endpoint is new
* observed data is sparse
* metrics are stale
* benchmarking is incomplete
When no measured evidence exists, the reference router still uses declared compatibility plus neutral scoring
defaults to keep routing functional.
# Endpoint identity (/protocol/endpoint-identity)
# Endpoint identity [#endpoint-identity]
`EndpointIdentity` is the protocol record that says **what concrete thing the router is allowed to choose**.
The router does not choose a bare model name. It chooses an endpoint whose identity captures serving and
deployment distinctions that materially affect behavior.
## Required core fields [#required-core-fields]
The schema requires:
* `endpoint_id`
* `endpoint_kind`
* `provider_kind`
* `serving_source`
* `model_id`
* `runtime_version`
Optional fields such as `package_id`, `variant_id`, `quantization`, `region`, `org_scope`, and
`endpoint_version` refine that identity further.
## Field groups [#field-groups]
| Group | Fields | Meaning |
| ------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
| stable endpoint handle | `endpoint_id`, `endpoint_version` | the specific routable unit and, optionally, the version of that unit |
| endpoint class | `endpoint_kind`, `provider_kind`, `serving_source` | what kind of endpoint it is and how it is reached |
| model and package lineage | `model_id`, `package_id`, `variant_id` | which model or package family the endpoint belongs to |
| runtime representation | `runtime_version`, `quantization`, `precision` | how the model is actually executed |
| deployment environment | `host_class`, `device_class`, `region`, `org_scope` | where and under what operational scope the endpoint runs |
## Why this level of identity matters [#why-this-level-of-identity-matters]
Two endpoints can expose the same base model and still differ in ways that change routing:
* one runs locally and another remotely
* one is quantized and another is full precision
* one runs in a different region
* one has a different runtime version
* one has a different package or endpoint version
If those differences are not captured in identity, measurements and policy decisions get mixed together
incorrectly.
## One model, many endpoints [#one-model-many-endpoints]
The same `model_id` can appear in multiple `EndpointIdentity` records.
That is expected. role-model treats those records as distinct routable units because each endpoint may differ
in provider, region, runtime version, quantization, locality, package lineage, or operational scope.
| endpoint\_id | model\_id | region | runtime\_version | quantization | why routing may differ |
| ---------------------- | ----------- | ------- | ---------------- | ------------ | ------------------------------------------------------- |
| `remote.kimi.us.k2-6` | `kimi-k2.6` | `us` | `remote-api-v1` | `none` | different locality, provider behavior, and cost profile |
| `remote.kimi.eu.k2-6` | `kimi-k2.6` | `eu` | `remote-api-v1` | `none` | different region and latency profile |
| `local.gguf.kimi-k2-6` | `kimi-k2.6` | `local` | `llama.cpp-x` | `q4` | different runtime, quantization, and measured tradeoffs |
`EndpointIdentity` therefore means more than "this is model X." It means "this is model X as served by this
specific concrete endpoint."
## `endpoint_kind` vs. `provider_kind` [#endpoint_kind-vs-provider_kind]
`endpoint_kind` answers **what sort of endpoint this is**. In the schema, baseline values include:
* `local_engine`
* `remote_api`
* `browser_engine`
* `dispatch_adapter`
`provider_kind` answers **what provider family or integration produced the endpoint**, such as:
* `acp`
* `mcp`
* `cli`
* `remote_openai_compat`
* `onnx`
* `mlx`
* `gguf`
* `webllm`
One is the endpoint class; the other is the provider or runtime family behind it.
## Normalization implications [#normalization-implications]
Identity normalization matters because:
1. routing decisions must remain stable when comparing candidates
2. observability must attribute metrics to the correct endpoint
3. profile aggregation must avoid mixing evidence from materially different deployments
In practice, identity is the anchor record that the declared and observed profile layers attach to.
# Protocol (/protocol)
# Protocol [#protocol]
The `role-model` protocol is the canonical contract behind the runtime router.
The runtime and operator UI are the fastest way to get value from role-model, but the protocol is still the
source of truth for how requests, endpoints, policy, and explainable routing artifacts are represented.
## What this section is for [#what-this-section-is-for]
Use the Protocol section when you need to understand:
* what role-model standardizes versus what a router implementation is free to choose
* how endpoint identity, declared profiles, observed profiles, roles, tasks, and policy fit together
* the field semantics of the canonical protocol artifacts
* the exact contract that the reference router consumes and emits
## The protocol boundary [#the-protocol-boundary]
role-model standardizes the artifacts around routing:
* endpoint identity
* declared capability
* observed performance
* roles and tasks
* routing policy
* router decisions
* traces and usage
The protocol does **not** make every runtime or router implementation detail canonical. It defines the
contract they must speak.
## Why the protocol is still endpoint-centric [#why-the-protocol-is-still-endpoint-centric]
The protocol does not route by model name alone.
It preserves model lineage inside `EndpointIdentity`, then reasons over concrete endpoints because that is
where meaningful operational differences actually live:
* provider
* runtime
* region or locality
* quantization or precision
* tool support
* measured latency, quality, reliability, freshness, and cost
## Start here in this section [#start-here-in-this-section]
If you want the best high-signal entry points into the deeper protocol material, start with:
1. [Protocol object model](/protocol-object-model)
2. [Protocol lifecycle](/protocol-lifecycle)
3. [Endpoint identity](/protocol/endpoint-identity)
4. [Roles and tasks](/protocol/roles-and-tasks)
5. [Routing policy](/protocol/routing-policy)
6. [Router decision artifact](/protocol/router-decision-artifact)
## How this section relates to the rest of the docs [#how-this-section-relates-to-the-rest-of-the-docs]
The public docs now intentionally start with runtime setup, benchmarking, routing strategy selection, and
live decision review.
That ordering is for new operators. It does **not** replace the deeper protocol material. This section is the
lower-sidebar, protocol-first layer for readers who need the canonical contract rather than just the runtime
workflow.
## Read next [#read-next]
* [What role-model defines](/introduction)
* [Protocol object model](/protocol-object-model)
* [Protocol lifecycle](/protocol-lifecycle)
* [Endpoint identity](/protocol/endpoint-identity)
* [Trace and usage artifacts](/protocol/trace-and-usage-artifacts)
# Observed performance profiles (/protocol/observed-performance-profiles)
# Observed performance profiles [#observed-performance-profiles]
`ObservedPerformanceProfile` is the protocol's measured evidence layer. It records how an endpoint has
actually behaved over time.
This is a protocol entity, not an implementation side note.
## Why observed performance is not model-only [#why-observed-performance-is-not-model-only]
role-model records observed performance for concrete endpoints, not just for model names in the abstract.
That is necessary because two endpoints serving the same model may still differ in:
* latency
* throughput
* cost
* failure behavior
* freshness
* measured quality under real deployment conditions
Observed evidence is therefore endpoint-specific for the same reason routing itself is endpoint-specific.
## Required measured fields [#required-measured-fields]
The schema requires:
* `endpoint_id`
* `measured_at_ms`
* `sample_window`
* `sample_size`
* `sources`
* `latency_ms_p50`
* `latency_ms_p95`
* `failure_rate`
* `freshness_score`
* `confidence_score`
Optional measured fields add quality, throughput, cold start, error class rates, and cost estimates.
## What the profile measures [#what-the-profile-measures]
| Metric family | Fields |
| ---------------- | -------------------------------------------------------------------------------- |
| quality | `judge_score`, `quality_score` |
| latency | `latency_ms_p50`, `latency_ms_p95`, optional `cold_start_ms` |
| throughput | `tokens_per_sec` |
| reliability | `failure_rate`, `error_class_rates` |
| cost | `cost_per_1k_tokens_est`, `currency` |
| evidence quality | `sample_window`, `sample_size`, `sources`, `freshness_score`, `confidence_score` |
## Where the evidence comes from [#where-the-evidence-comes-from]
The baseline aggregator accepts samples from two sources:
* `benchmark`
* `live_request`
The aggregated profile keeps both counts in `sources` so consumers can distinguish curated benchmark evidence
from production traffic evidence.
## How the reference aggregator derives metrics [#how-the-reference-aggregator-derives-metrics]
The profile aggregator in `role-model-router/packages/profile-aggregator` does the following:
* computes `latency_ms_p50` and `latency_ms_p95` from recorded latency samples
* uses median values for `tokens_per_sec`, `cold_start_ms`, and `cost_per_1k_tokens_est` when present
* computes `failure_rate` from samples that carry a `failure_class`
* computes `error_class_rates` as per-class proportions
* averages judge scores into `judge_score` and mirrors that into `quality_score`
* computes `freshness_score` with an exponential decay using a 7-day half-life
* computes `confidence_score` from `log1p(sample_size) / log1p(50)`, clamped to `[0, 1]`
## Why observed data outranks declared data [#why-observed-data-outranks-declared-data]
Declared data tells the router what should be possible. Observed data tells it what has actually happened.
That is why the intended routing order is:
1. hard compatibility and policy constraints
2. observed real-world behavior
3. declared capability metadata
4. neutral defaults where evidence is missing
## Freshness and confidence are first-class [#freshness-and-confidence-are-first-class]
Not all measurements are equally trustworthy. The protocol therefore encodes:
* **freshness**: how old the latest evidence is
* **confidence**: how much evidence exists
This prevents old or thin data from looking as authoritative as recent, high-volume evidence.
# Roles and tasks (/protocol/roles-and-tasks)
# Roles and tasks [#roles-and-tasks]
The protocol separates **what kind of work is being done** from **how that work should be carried out**.
* `TaskDefinition` models the unit of work.
* `RoleDefinition` models the execution persona and operating contract.
* `RoleBinding` attaches a role to a concrete endpoint.
* `TaskExecutionProfile` adjusts execution requirements for a particular task/role combination.
## Taxonomy V1 role groups [#taxonomy-v1-role-groups]
Taxonomy V1 starts with groups so operators and consumers can scan the catalog without loading every task.
| Group ID | Example roles | What it covers |
| -------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `engineering` | `coder`, `architect`, `security`, `tester`, `data`, `operator` | code, systems, operations, testing, and data implementation |
| `product_design` | `product`, `designer`, `planner`, `analyst` | product definition, design, planning, and prioritization |
| `knowledge_research` | `researcher`, `knowledge`, `educator`, `scientist`, `mathematician` | research, knowledge work, education, science, and math |
| `business` | `finance`, `marketer`, `seller`, `procurement`, `strategist` | business analysis, sales, marketing, procurement, and strategy |
| `communication` | `writer`, `support`, `creative`, `translator`, `coordinator` | writing, customer communication, creative work, translation, and coordination |
| `governance_safety` | `security`, `legal`, `recruiter`, `health`, `finance` | policy-sensitive work that needs clearer review boundaries |
## Role and task examples [#role-and-task-examples]
Task IDs follow `{role-family}.{task-action}[.{variant}]`. The first segment is the primary role family.
| Task type | Common roles | What it represents |
| --------------------------------- | -------------------------------- | ----------------------------------------------------------------------- |
| `coder.edit` | `coder` | implementation and patch-oriented code changes |
| `coder.review` | `coder`, `security`, `architect` | source or diff review for correctness, regressions, and maintainability |
| `security.audit` | `security`, `coder`, `architect` | security review, risk identification, and vulnerability analysis |
| `product.requirements` | `product`, `planner`, `designer` | product requirements and acceptance criteria |
| `researcher.web_research.current` | `researcher` | current-source web research with citations |
| `support.ticket.reply` | `support`, `writer` | clear customer-facing support replies |
The full runtime catalog currently contains 6 groups, 28 roles, 280 task types, 46 capabilities, 9 modalities,
and 15 tool classes.
{/* TAXONOMY_V1_CATALOG:START */}
### Manifest [#manifest]
* schemaVersion: role-model.taxonomy.schema.v1
* taxonomyVersion: 1.0.0-alpha.1
* classificationContractVersion: role-model.classification.v1
* contentRevision: taxonomy-v1-alpha.1
* `entryCounts`:
* groups: 6
* roles: 28
* capabilities: 46
* modalities: 9
* toolClasses: 15
* intentPresets: 0
* taskTypes: 280
### Groups [#groups]
| Group | Label | Primary roles | Secondary roles |
| -------------------- | ---------------------- | ------------------------------------------------------------------- | --------------------- |
| `engineering` | Engineering | `coder`, `architect`, `operator`, `tester`, `security`, `data` | |
| `product_design` | Product And Design | `product`, `designer`, `planner`, `analyst` | |
| `knowledge_research` | Knowledge And Research | `researcher`, `knowledge`, `scientist`, `mathematician`, `educator` | `health` |
| `business` | Business | `strategist`, `marketer`, `seller`, `finance`, `procurement` | `legal`, `recruiter` |
| `communication` | Communication | `writer`, `translator`, `creative`, `support`, `coordinator` | |
| `governance_safety` | Governance And Safety | `legal`, `health`, `recruiter` | `security`, `finance` |
### Roles [#roles]
| Role | Label | Primary group | Secondary groups | Task count |
| --------------- | ------------- | -------------------- | -------------------- | ---------: |
| `coder` | Coder | `engineering` | | 10 |
| `architect` | Architect | `engineering` | | 10 |
| `security` | Security | `engineering` | `governance_safety` | 10 |
| `researcher` | Researcher | `knowledge_research` | | 10 |
| `writer` | Writer | `communication` | | 10 |
| `operator` | Operator | `engineering` | | 10 |
| `analyst` | Analyst | `product_design` | | 10 |
| `planner` | Planner | `product_design` | | 10 |
| `tester` | Tester | `engineering` | | 10 |
| `data` | Data | `engineering` | | 10 |
| `product` | Product | `product_design` | | 10 |
| `designer` | Designer | `product_design` | | 10 |
| `support` | Support | `communication` | | 10 |
| `legal` | Legal | `governance_safety` | `business` | 10 |
| `finance` | Finance | `business` | `governance_safety` | 10 |
| `creative` | Creative | `communication` | | 10 |
| `educator` | Educator | `knowledge_research` | | 10 |
| `translator` | Translator | `communication` | | 10 |
| `marketer` | Marketer | `business` | | 10 |
| `seller` | Seller | `business` | | 10 |
| `recruiter` | Recruiter | `governance_safety` | `business` | 10 |
| `procurement` | Procurement | `business` | | 10 |
| `coordinator` | Coordinator | `communication` | | 10 |
| `knowledge` | Knowledge | `knowledge_research` | | 10 |
| `strategist` | Strategist | `business` | | 10 |
| `mathematician` | Mathematician | `knowledge_research` | | 10 |
| `scientist` | Scientist | `knowledge_research` | | 10 |
| `health` | Health | `governance_safety` | `knowledge_research` | 10 |
### Task Types [#task-types]
| Task type | Label | Description | Use when | Do not use when | Primary role | Compatible roles | Required capabilities | Preferred capabilities | Required modalities | Tool classes |
| ------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------- | ----------------------------------------------------- | --------------------------- | ------------------- | ------------------------------------------------------ |
| `coder.edit` | Code Edit | Modify source code, configuration, tests, or build files. | User asks to implement, fix, refactor, or change files. | User only asks for critique, explanation, or review. | `coder` | `coder`, `architect` | `code.read`, `code.write` | `reasoning.multi_step` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `coder.review` | Code Review | Review source changes for correctness, regressions, maintainability, and missing tests. | User asks to inspect existing code or a diff and identify issues. | User asks to implement changes directly. | `coder` | `coder`, `security`, `architect` | `code.read` | `reasoning.multi_step` | `text` | `filesystem.read` |
| `coder.debug.root_cause` | Root Cause Debugging | Investigate a failure to identify the underlying cause before proposing or applying fixes. | User reports failing tests, crashes, locks, regressions, or unexpected behavior. | User already knows the fix and asks to apply it. | `coder` | `coder`, `operator`, `architect` | `code.read`, `reasoning.multi_step` | `tools.function_calling` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `coder.test.write` | Test Writing | Create or update tests for code behavior. | User asks for tests, coverage, regression proof, or TDD. | User asks only to inspect code without changes. | `coder` | `coder` | `code.read`, `code.write` | `tools.function_calling` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `coder.refactor` | Code Refactor | Improve structure without intended behavior changes. | User asks to simplify, reorganize, deduplicate, or improve maintainability. | User asks for new product behavior. | `coder` | `coder`, `architect` | `code.read`, `code.write` | `reasoning.multi_step` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `coder.explain` | Code Explanation | Explain code behavior, architecture, or implementation details. | User asks how code works or why it behaves a certain way. | User asks to modify files. | `coder` | `coder`, `writer` | `code.read`, `text.chat` | `reasoning.multi_step` | `text` | `filesystem.read` |
| `coder.migrate` | Code Migration | Move code across APIs, frameworks, versions, or platforms. | User asks to upgrade, port, or migrate implementation. | User only asks for conceptual comparison. | `coder` | `coder`, `architect`, `operator` | `code.read`, `code.write` | `long_context` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `coder.generate` | Code Generation | Create new code from a specification. | User asks to scaffold, generate, or create a new implementation. | User asks to review existing code only. | `coder` | `coder`, `architect` | `code.write` | `reasoning.multi_step` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.e2e` | End-to-End Test Implementation | Create or update browser, API, or workflow-level tests. | User asks for Playwright/Cypress/API workflow validation. | User asks for unit tests only. | `tester` | `tester`, `coder` | `code.read`, `code.write`, `tools.function_calling` | `tools.browser_control` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `architect.design` | System Design | Design architecture, modules, APIs, ownership boundaries, or technical approach. | User asks for design, architecture, plans, or tradeoff analysis. | User asks for direct implementation with known design. | `architect` | `architect`, `coder` | `reasoning.multi_step` | `long_context` | `text` | |
| `architect.review` | Architecture Review | Review a design or implementation for architecture and long-term maintainability. | User asks whether a system shape, API, or module boundary is sound. | The review is primarily about code-level bugs or security risk. | `architect` | `architect`, `coder`, `security` | `reasoning.multi_step` | `code.read` | `text` | |
| `architect.plan` | Technical Plan | Produce a technical implementation plan, phases, or tradeoff analysis. | User asks how to approach implementation before coding. | User asks to directly edit files now. | `architect` | `architect`, `planner`, `coder` | `reasoning.multi_step` | `long_context` | `text` | |
| `architect.api_design` | API Design | Design public APIs, contracts, schemas, or integration boundaries. | User asks for API shape, schema, protocol, or backwards compatibility. | User asks to debug a runtime failure. | `architect` | `architect`, `coder`, `product` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `security.audit` | Security Audit | Analyze a system, implementation, or configuration for security risk. | User asks for vulnerabilities, abuse cases, secrets, auth, permissions, or risk. | User asks for general code quality without security focus. | `security` | `security`, `architect` | `security.analysis` | `code.read` | `text` | |
| `security.audit.supply_chain` | Supply Chain Security Audit | Review dependencies, packages, build provenance, lockfiles, and release artifacts for supply-chain risk. | User asks about dependency risk, package publishing, build artifacts, provenance, or release integrity. | User asks for normal code quality review without dependency or release risk. | `security` | `security`, `operator`, `coder` | `security.analysis`, `code.read` | `web.search` | `text` | |
| `security.threat_model` | Threat Modeling | Identify assets, attackers, trust boundaries, threats, and mitigations. | User asks to model risk before or during design. | User asks to patch an already identified bug. | `security` | `security`, `architect` | `security.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `security.vulnerability_triage` | Vulnerability Triage | Assess vulnerability reports, severity, exploitability, and mitigation priority. | User provides a CVE, scanner finding, or suspected vulnerability. | User asks for general best practices. | `security` | `security`, `operator`, `coder` | `security.analysis` | `web.search` | `text` | |
| `security.policy_review` | Security Policy Review | Review permissions, RBAC, access policy, or compliance controls. | User asks about authz, RBAC, scopes, permissions, or policy enforcement. | User asks for code formatting. | `security` | `security`, `legal`, `architect` | `security.analysis` | `reasoning.multi_step` | `text` | |
| `researcher.web_research` | Web Research | Find and synthesize current external information. | The answer depends on current docs, releases, prices, laws, products, schedules, or web facts. | The answer is fully available in local repo context. | `researcher` | `researcher`, `writer` | `web.search`, `text.chat` | `citation.synthesis` | `text` | `web.search`, `http.fetch` |
| `researcher.web_research.current` | Current Web Research | Verify the latest state of fast-changing facts, releases, policies, products, or public information. | User asks for latest/current/today status or the topic is likely to have changed. | User asks for stable background knowledge only. | `researcher` | `researcher`, `analyst`, `writer` | `web.search`, `text.chat` | `citation.synthesis` | `text` | `web.search`, `http.fetch` |
| `researcher.compare_sources` | Compare Sources | Compare multiple sources, claims, or documents. | User asks for comparison, synthesis, source quality, or tradeoffs across references. | User only asks to rewrite one known text. | `researcher` | `researcher`, `writer` | `text.chat` | `citation.synthesis` | `text` | `web.search`, `http.fetch` |
| `researcher.literature_review` | Literature Review | Review papers, standards, reports, or long-form technical sources. | User asks for academic/technical source synthesis. | User asks for current breaking news only. | `researcher` | `researcher`, `analyst` | `text.chat`, `long_context` | `citation.synthesis` | `text` | |
| `researcher.fact_check` | Fact Check | Verify a claim against sources or local evidence. | User asks whether a statement is true, current, or supported. | User asks for creative ideation. | `researcher` | `researcher`, `writer`, `analyst` | `web.search` | `citation.synthesis` | `text` | |
| `writer.docs.write` | Documentation Writing | Write or improve documentation, guides, READMEs, or public docs. | User asks to explain, document, publish, or structure information. | User asks for implementation, debugging, or security review. | `writer` | `writer`, `coder` | `text.chat` | `code.read` | `text` | |
| `writer.docs.public` | Public Documentation | Write public-facing docs, installation instructions, guides, or website copy. | User asks for docs intended for external users or public release. | User asks for private notes, internal plans, or implementation only. | `writer` | `writer`, `product`, `coder` | `text.chat` | `communication.user_facing` | `text` | |
| `writer.docs.edit` | Documentation Editing | Edit existing docs for clarity, structure, consistency, and correctness. | User asks to revise, streamline, or polish documentation. | User asks to implement code behavior. | `writer` | `writer`, `coder`, `product` | `text.chat` | `code.read` | `text` | |
| `writer.summarize` | Summarization | Condense content while preserving important points. | User asks for a summary, digest, brief, or executive overview. | User asks to make a routing decision requiring tools. | `writer` | `writer`, `researcher`, `analyst` | `text.chat` | `long_context` | `text` | |
| `writer.release_notes` | Release Notes | Write user-facing release notes, changelogs, or announcement copy. | User asks for release notes or public-facing change summary. | User asks for legal license interpretation. | `writer` | `writer`, `product`, `coder` | `text.chat` | `code.read` | `text` | |
| `operator.debug.startup` | Startup Debugging | Diagnose runtime, launch, environment, or process startup failures. | User reports service launch, install, process, port, auth, or environment failures. | User asks to design a new feature. | `operator` | `operator`, `coder` | `reasoning.multi_step` | `tools.command_execution` | `text` | |
| `operator.debug.ui` | UI Runtime Debugging | Diagnose UI runtime, rendering, browser, interaction, or frontend workflow failures. | User reports broken UI behavior, rendering issues, browser errors, or failed UI workflows. | User asks only for visual design critique. | `operator` | `operator`, `tester`, `coder`, `designer` | `tools.browser_control`, `reasoning.multi_step` | `tools.command_execution` | `text` | |
| `operator.debug.api` | API Runtime Debugging | Diagnose API, HTTP, webhook, auth, integration, or service response failures. | User reports failed API calls, bad responses, webhook failures, request/response mismatches, or endpoint integration issues. | User asks to design a new API contract from scratch. | `operator` | `operator`, `coder`, `architect`, `support` | `tools.function_calling`, `reasoning.multi_step` | `tools.command_execution` | `text` | |
| `operator.deploy.review` | Deployment Review | Review deployment configuration, release readiness, or rollout risk. | User asks whether a deployment/release is ready. | User asks to write unrelated prose. | `operator` | `operator`, `security`, `architect` | `reasoning.multi_step` | `tools.command_execution` | `text` | |
| `operator.incident_triage` | Incident Triage | Triage outages, regressions, alerts, logs, or production symptoms. | User reports an incident or asks for operational triage. | User asks for normal feature planning. | `operator` | `operator`, `coder`, `security` | `reasoning.multi_step` | `tools.command_execution` | `text` | |
| `operator.config` | Runtime Configuration | Configure services, endpoints, environments, or runtime settings. | User asks to set up or change runtime configuration. | User asks for conceptual explanation only. | `operator` | `operator`, `coder` | `tools.function_calling` | `tools.command_execution` | `text` | |
| `operator.install` | Installation | Install, configure, and verify software on a local or managed environment. | User asks to install a package, set up a runtime, configure endpoints, or verify local integration. | User asks only for written installation instructions. | `operator` | `operator`, `coder`, `support` | `tools.function_calling` | `tools.command_execution` | `text` | `package.install`, `shell.execute` |
| `analyst.compare` | Comparative Analysis | Compare options, systems, plans, models, vendors, or tradeoffs. | User asks which option is better and why. | User asks to execute a direct edit. | `analyst` | `analyst`, `architect`, `researcher` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `analyst.evaluate` | Evaluation | Score or assess quality, fit, risk, or performance against criteria. | User asks for an evaluation rubric or assessment. | User asks for pure creative brainstorming. | `analyst` | `analyst`, `product`, `architect` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `analyst.prioritize` | Prioritization | Rank work, risks, options, or next steps. | User asks what to do first or how to sequence work. | User asks to write code immediately. | `analyst` | `analyst`, `planner`, `product` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.requirements` | Requirements Definition | Convert goals into requirements, acceptance criteria, and constraints. | User asks to define requirements or scope. | User asks for a final implementation patch. | `planner` | `planner`, `product`, `architect` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.roadmap` | Roadmap Planning | Build phased plans, milestones, dependencies, and rollout sequencing. | User asks for a roadmap or phased implementation plan. | User asks for a code review finding list. | `planner` | `planner`, `product`, `architect` | `reasoning.multi_step` | `long_context` | `text` | |
| `planner.roadmap.release` | Release Roadmap | Plan phased release work, readiness gates, changelog, docs, packaging, and rollout steps. | User asks for release planning, alpha/beta sequencing, or launch readiness. | User asks to publish immediately without planning. | `planner` | `planner`, `product`, `operator` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.decompose` | Task Decomposition | Break a goal into tasks, phases, or executable work items. | User asks to split work into steps or tickets. | User asks for source citation research. | `planner` | `planner`, `operator`, `coder` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `tester.plan` | Test Plan | Design a verification strategy, test cases, and acceptance checks. | User asks how to test or verify a feature. | User asks to write production code only. | `tester` | `tester`, `coder`, `product` | `reasoning.multi_step` | `json.schema_adherence` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.regression` | Regression Testing | Verify existing behavior still works after changes. | User asks to validate no regressions. | User asks to design a product strategy. | `tester` | `tester`, `coder`, `operator` | `tools.function_calling` | `tools.command_execution` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.reproduce` | Reproduction Testing | Reproduce a reported issue with clear steps, observed behavior, and expected behavior. | User reports a bug and needs a reliable repro before diagnosis or fix. | User already provided a verified repro and asks for implementation. | `tester` | `tester`, `coder`, `support` | `tools.function_calling` | `tools.command_execution` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `data.query` | Data Query | Write, inspect, or explain queries over structured data. | User asks for SQL/query work or data extraction. | User asks for web research. | `data` | `data`, `analyst`, `coder` | `data.query` | `json.schema_adherence` | `text` | `database.query` |
| `data.schema.review` | Data Schema Review | Review database, event, API, or analytics schemas. | User asks whether a schema is correct, stable, or useful. | User asks to edit frontend UI. | `data` | `data`, `architect`, `analyst` | `data.schema` | `reasoning.multi_step` | `text` | `database.query` |
| `data.transform` | Data Transformation | Transform, normalize, clean, or map data between shapes. | User asks to convert data formats or clean records. | User asks for legal advice. | `data` | `data`, `coder` | `data.transform` | `json.schema_adherence` | `text` | `database.query` |
| `product.requirements` | Product Requirements | Define user-facing behavior, constraints, and acceptance criteria. | User asks what a product/feature should do. | User asks for root-cause debugging. | `product` | `product`, `planner`, `architect` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `product.workflow.review` | Workflow Review | Review user workflows, ergonomics, states, or product flows. | User asks whether a user flow makes sense. | User asks to run commands. | `product` | `product`, `designer`, `writer` | `text.chat` | `reasoning.multi_step` | `text` | |
| `product.release_notes` | Product Release Notes | Define user-facing release messaging and notable behavior changes. | User asks what should be communicated in a release from a product perspective. | User asks for a raw technical changelog only. | `product` | `product`, `writer`, `planner` | `text.chat` | `communication.user_facing` | `text` | |
| `designer.ui.review` | UI Review | Review interface layout, hierarchy, visual polish, accessibility, or usability. | User asks whether an interface looks or feels right. | User asks for backend debugging. | `designer` | `designer`, `product`, `writer` | `vision.input`, `text.chat` | `reasoning.multi_step` | `text` | |
| `designer.interaction` | Interaction Design | Design states, flows, controls, and interaction behavior. | User asks how a UI should behave across workflows. | User asks for legal/compliance interpretation. | `designer` | `designer`, `product`, `architect` | `text.chat` | `json.schema_adherence` | `text` | |
| `designer.visual_direction` | Visual Direction | Define visual style, hierarchy, mood, layout direction, or asset guidance. | User asks for visual direction, composition, design polish, or creative UI treatment. | User asks for code-level bug diagnosis. | `designer` | `designer`, `creative`, `product` | `vision.input`, `text.chat` | `vision.output` | `text` | |
| `support.triage` | Support Triage | Understand a user issue and route it to next steps. | User reports a problem and needs diagnosis or escalation. | User asks for code generation. | `support` | `support`, `operator`, `writer` | `text.chat` | `reasoning.multi_step` | `text` | |
| `support.explain` | User Explanation | Explain a system behavior or remediation in user-facing terms. | User needs a clear support response or troubleshooting guide. | User asks for internal architecture design. | `support` | `support`, `writer`, `operator` | `text.chat` | `communication.user_facing` | `text` | |
| `support.escalate` | Support Escalation | Prepare escalation context, severity, repro notes, and routing for another team. | User issue needs handoff to engineering, operations, security, billing, or product. | User asks for direct implementation. | `support` | `support`, `operator`, `product` | `text.chat` | `json.schema_adherence` | `text` | |
| `legal.review` | Legal Review | Review terms, licenses, policies, or compliance-sensitive text. | User asks about license, terms, privacy, or compliance implications. | User asks for code implementation. | `legal` | `legal`, `security` | `legal.analysis` | `citation.synthesis` | `text` | |
| `legal.compliance_check` | Compliance Check | Check whether a plan, policy, or document appears to satisfy stated compliance constraints. | User asks about compliance posture, policy fit, or required controls. | User asks for binding legal advice or jurisdiction-specific counsel. | `legal` | `legal`, `security`, `operator` | `legal.analysis` | `json.schema_adherence` | `text` | |
| `finance.cost_estimate` | Cost Estimate | Estimate cost, budget, or pricing impact. | User asks about price, spend, ROI, or budget. | User asks for code refactoring. | `finance` | `finance`, `analyst`, `operator` | `finance.analysis` | `web.search` | `text` | |
| `finance.compare_options` | Financial Option Comparison | Compare cost, budget, pricing, or ROI across options. | User asks which option is more cost-effective or financially practical. | User asks for non-financial technical comparison only. | `finance` | `finance`, `analyst`, `operator` | `finance.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `creative.brainstorm` | Brainstorming | Generate creative options, names, concepts, or variants. | User asks for ideation or alternatives. | User asks for verified factual claims. | `creative` | `creative`, `writer`, `product` | `text.chat` | `reasoning.divergent` | `text` | |
| `creative.copywriting` | Copywriting | Produce persuasive, brand, product, or campaign copy variants. | User asks for headlines, taglines, short-form copy, or creative wording. | User asks for factual documentation or legal text. | `creative` | `creative`, `writer`, `product` | `text.chat` | `reasoning.divergent` | `text` | |
| `creative.storyboard` | Storyboarding | Plan a visual, narrative, product, or media sequence. | User asks for scenes, flows, visual sequence, or narrative structure. | User asks for security triage. | `creative` | `creative`, `writer`, `product` | `text.chat` | `vision.output` | `text` | |
| `educator.tutor` | Tutoring | Teach a concept interactively with explanations, examples, and checks for understanding. | User asks to learn, study, or be taught a subject. | User asks for a final answer only without explanation. | `educator` | `educator`, `writer`, `mathematician`, `scientist` | `education.tutoring`, `text.chat` | `reasoning.multi_step` | `text` | |
| `educator.lesson.plan` | Lesson Planning | Create a lesson, curriculum segment, study path, or learning sequence. | User asks for a lesson plan, course outline, study schedule, or learning progression. | User asks for a short factual answer. | `educator` | `educator`, `planner`, `writer` | `education.tutoring` | `json.schema_adherence` | `text` | |
| `educator.quiz.generate` | Quiz Generation | Generate questions, answer keys, rubrics, or practice exercises. | User asks for a quiz, flashcards, drills, or assessment material. | User asks to evaluate a real candidate or employee. | `educator` | `educator`, `tester`, `writer` | `education.assessment` | `json.schema_adherence` | `text` | |
| `educator.feedback` | Learning Feedback | Provide constructive feedback on a learner's work. | User provides an answer, essay, solution, or draft and asks for learning-oriented feedback. | User asks for employment or hiring evaluation. | `educator` | `educator`, `writer`, `mathematician` | `education.assessment`, `text.chat` | `communication.user_facing` | `text` | |
| `translator.translate` | Translation | Translate text from one language to another while preserving meaning. | User asks to translate content. | User asks to rewrite within the same language only. | `translator` | `translator`, `writer` | `language.translation`, `text.chat` | `communication.user_facing` | `text` | |
| `translator.localize.locale` | Localization | Adapt language, examples, formatting, idioms, and tone for a target locale. | User asks for localization, regional adaptation, or market-language fit. | User only asks for literal translation. | `translator` | `translator`, `marketer`, `writer` | `language.localization`, `text.chat` | `communication.user_facing` | `text` | |
| `translator.review` | Translation Review | Review translated or localized content for accuracy, tone, and consistency. | User asks whether translated content is correct or natural. | User asks to design a marketing campaign. | `translator` | `translator`, `writer`, `marketer` | `language.translation` | `reasoning.multi_step` | `text` | |
| `marketer.positioning` | Positioning | Define audience, value proposition, differentiation, and messaging. | User asks how to position a product, feature, company, or offer. | User asks for legal claims approval. | `marketer` | `marketer`, `product`, `strategist` | `marketing.analysis`, `text.chat` | `reasoning.multi_step` | `text` | |
| `marketer.campaign.plan` | Campaign Planning | Plan campaign channels, audience, message, assets, timing, and success measures. | User asks for a marketing campaign or launch campaign plan. | User asks for technical release readiness. | `marketer` | `marketer`, `planner`, `product` | `marketing.analysis` | `json.schema_adherence` | `text` | |
| `marketer.content.seo` | SEO Content | Plan or write content aligned with search intent and discovery. | User asks for SEO strategy, keywords, article outline, or search-optimized copy. | User needs verified legal or medical guidance. | `marketer` | `marketer`, `writer`, `researcher` | `marketing.analysis`, `web.search` | `communication.user_facing` | `text` | |
| `marketer.copy.ad` | Ad Copy | Produce short-form ad, landing-page, or campaign copy variants. | User asks for ad copy, headlines, CTAs, or campaign variants. | User asks for factual documentation. | `marketer` | `marketer`, `creative`, `writer` | `marketing.copy`, `text.chat` | `reasoning.divergent` | `text` | |
| `seller.discovery.plan` | Sales Discovery Planning | Prepare discovery questions, qualification criteria, and account research prompts. | User asks how to run a sales discovery call or qualify an opportunity. | User asks for generic product requirements. | `seller` | `seller`, `product`, `strategist` | `sales.analysis` | `json.schema_adherence` | `text` | |
| `seller.outreach.write` | Sales Outreach | Write prospecting, follow-up, or account-specific outreach messages. | User asks for cold email, LinkedIn outreach, or follow-up copy. | User asks for support remediation steps. | `seller` | `seller`, `writer`, `marketer` | `sales.communication`, `text.chat` | `communication.user_facing` | `text` | `email.write` |
| `seller.proposal.enterprise` | Enterprise Proposal | Draft or review enterprise sales proposals, rollout plans, and buying-committee materials. | User asks for proposal content, mutual action plans, security/commercial positioning, or enterprise rollout language. | User asks for legal contract approval. | `seller` | `seller`, `procurement`, `security`, `legal` | `sales.analysis`, `communication.user_facing` | `json.schema_adherence` | `text` | |
| `seller.objection.handle` | Objection Handling | Prepare responses to buyer concerns, risks, pricing objections, or adoption blockers. | User asks how to respond to a sales objection. | User asks for support troubleshooting. | `seller` | `seller`, `marketer`, `product` | `sales.communication` | `reasoning.multi_step` | `text` | |
| `recruiter.job_description` | Job Description | Write or revise role descriptions, responsibilities, qualifications, and hiring signals. | User asks for a job description or hiring profile. | User asks for employment-law compliance review. | `recruiter` | `recruiter`, `writer`, `product` | `recruiting.analysis`, `text.chat` | `communication.user_facing` | `text` | |
| `recruiter.interview.plan` | Interview Planning | Create interview loops, questions, rubrics, and evaluation criteria. | User asks how to interview for a role or assess skills. | User asks to make a hiring decision from protected characteristics. | `recruiter` | `recruiter`, `planner`, `educator` | `recruiting.analysis` | `json.schema_adherence` | `text` | |
| `recruiter.candidate.screen` | Candidate Screening Support | Summarize job-relevant candidate materials against explicit criteria. | User asks to screen resumes or compare candidates against stated job requirements. | User asks to infer protected attributes or make unlawful employment decisions. | `recruiter` | `recruiter`, `analyst`, `legal` | `recruiting.analysis` | `json.schema_adherence` | `text` | |
| `procurement.vendor.compare` | Vendor Comparison | Compare vendors against requirements, cost, risk, security, and operational fit. | User asks which vendor/tool/provider is a better fit. | User asks for pure product marketing copy. | `procurement` | `procurement`, `finance`, `security`, `analyst` | `procurement.analysis`, `finance.analysis` | `json.schema_adherence` | `text` | |
| `procurement.rfp.write` | RFP Writing | Draft request-for-proposal questions, scoring criteria, and response templates. | User asks to create an RFP, vendor questionnaire, or procurement checklist. | User asks for implementation code. | `procurement` | `procurement`, `legal`, `security`, `writer` | `procurement.analysis` | `json.schema_adherence` | `text` | |
| `procurement.requirements` | Purchasing Requirements | Define purchasing, security, legal, operational, and commercial requirements. | User asks what requirements to give vendors or evaluate against. | User asks for a sales pitch. | `procurement` | `procurement`, `security`, `finance`, `operator` | `procurement.analysis` | `reasoning.multi_step` | `text` | |
| `procurement.contract.commercial` | Commercial Contract Review | Review commercial contract terms such as pricing, renewal, SLA, and termination from a business perspective. | User asks about commercial terms or vendor contract tradeoffs. | User asks for binding legal advice. | `procurement` | `procurement`, `legal`, `finance` | `procurement.analysis`, `finance.analysis` | `legal.analysis` | `text` | |
| `coordinator.meeting.agenda` | Meeting Agenda | Create meeting agendas, prep notes, goals, and decision points. | User asks to prepare for a meeting. | User asks for deep technical implementation. | `coordinator` | `coordinator`, `planner`, `product` | `coordination.workflow` | `json.schema_adherence` | `text` | `calendar.read` |
| `coordinator.meeting.notes` | Meeting Notes | Summarize meeting notes into decisions, action items, owners, and follow-ups. | User provides transcript or notes and asks for structured meeting output. | User asks for legal transcript certification. | `coordinator` | `coordinator`, `writer`, `planner` | `coordination.workflow`, `text.chat` | `json.schema_adherence` | `text` | `calendar.read` |
| `coordinator.schedule.plan` | Scheduling Plan | Plan schedule options, sequencing, reminders, or coordination logistics. | User asks to organize timing, schedules, or calendar-style plans. | User asks for product roadmap strategy. | `coordinator` | `coordinator`, `planner`, `support` | `calendar.planning` | `json.schema_adherence` | `text` | `calendar.read` |
| `coordinator.follow_up` | Follow-Up Drafting | Draft follow-up messages, reminders, and action-item communications. | User asks for follow-up after meetings, support, sales, or project work. | User asks to make technical changes. | `coordinator` | `coordinator`, `writer`, `seller`, `support` | `communication.follow_up` | `communication.user_facing` | `text` | |
| `knowledge.organize` | Knowledge Organization | Structure notes, docs, links, memory, or project information into a usable system. | User asks to organize information, create a knowledge base, or clean up notes. | User asks for current external research only. | `knowledge` | `knowledge`, `writer`, `researcher` | `knowledge.organization`, `text.chat` | `long_context` | `text` | `memory.read`, `vector.search` |
| `knowledge.retrieve` | Knowledge Retrieval | Find and synthesize relevant remembered, local, or indexed knowledge. | User asks to find prior notes, docs, facts, or project context. | User asks to create new code. | `knowledge` | `knowledge`, `researcher`, `support` | `knowledge.retrieval` | `citation.synthesis` | `text` | `memory.read`, `vector.search` |
| `knowledge.memory.update` | Memory Update | Decide what durable memory or knowledge-base state should be created or updated. | User asks to remember, save, update, or curate durable context. | User asks for ephemeral chat only. | `knowledge` | `knowledge`, `coordinator`, `support` | `memory.write`, `knowledge.organization` | `json.schema_adherence` | `text` | `memory.read`, `vector.search` |
| `knowledge.kb.write` | Knowledge Base Writing | Write help-center, internal KB, runbook, or reference entries. | User asks to create reusable knowledge or support documentation. | User asks for one-off creative copy. | `knowledge` | `knowledge`, `writer`, `support`, `operator` | `knowledge.organization`, `communication.user_facing` | `text.chat` | `text` | `memory.read`, `vector.search` |
| `strategist.business.plan` | Business Planning | Develop business strategy, operating model, market approach, or strategic initiative plan. | User asks for business strategy, GTM shape, or strategic planning. | User asks for technical implementation steps only. | `strategist` | `strategist`, `product`, `finance`, `marketer` | `strategy.analysis` | `reasoning.multi_step` | `text` | |
| `strategist.market.analyze` | Market Analysis | Analyze market dynamics, segments, competitors, trends, and opportunities. | User asks about market opportunity or strategic positioning. | User asks for verified breaking news only. | `strategist` | `strategist`, `researcher`, `marketer`, `analyst` | `market.analysis` | `web.search` | `text` | |
| `strategist.competitive.review` | Competitive Review | Compare competitors, alternatives, differentiation, and strategic risks. | User asks how something compares competitively. | User asks for simple price comparison only. | `strategist` | `strategist`, `marketer`, `analyst`, `product` | `strategy.analysis`, `market.analysis` | `json.schema_adherence` | `text` | |
| `strategist.risk.scenario` | Scenario Planning | Explore scenarios, assumptions, risks, mitigations, and decision triggers. | User asks what could happen under different strategic assumptions. | User asks for exact forecast certainty. | `strategist` | `strategist`, `analyst`, `planner`, `finance` | `strategy.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `mathematician.solve` | Math Solving | Solve a math problem with steps and final result. | User asks for calculation, proof, algebra, statistics, or quantitative solution. | User asks for financial advice rather than math. | `mathematician` | `mathematician`, `educator`, `analyst` | `math.solve` | `reasoning.multi_step` | `text` | |
| `mathematician.verify` | Math Verification | Check a calculation, proof, derivation, or quantitative claim. | User asks whether a mathematical solution is correct. | User asks for code review. | `mathematician` | `mathematician`, `tester`, `educator` | `math.verify` | `reasoning.multi_step` | `text` | |
| `mathematician.model` | Mathematical Modeling | Build or critique a mathematical, statistical, or optimization model. | User asks to model a process, estimate relationship, or formulate constraints. | User asks for qualitative brainstorming only. | `mathematician` | `mathematician`, `data`, `analyst`, `finance` | `math.modeling`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `mathematician.explain` | Math Explanation | Explain mathematical concepts, steps, or intuition. | User asks to understand math rather than only get an answer. | User asks for non-math writing. | `mathematician` | `mathematician`, `educator`, `writer` | `math.solve`, `education.tutoring` | `communication.user_facing` | `text` | |
| `scientist.experiment.design` | Experimental Design | Design experiments, controls, variables, measurements, and interpretation plans. | User asks how to test a scientific or empirical hypothesis. | User asks for product A/B test logistics only. | `scientist` | `scientist`, `analyst`, `planner` | `science.method`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `scientist.evidence.review` | Scientific Evidence Review | Review scientific claims, evidence quality, limitations, and uncertainty. | User asks whether a claim is scientifically supported. | User asks for current product pricing. | `scientist` | `scientist`, `researcher`, `analyst` | `science.analysis`, `citation.synthesis` | `web.search` | `text` | |
| `scientist.method.critique` | Method Critique | Critique study design, methodology, bias, confounds, and validity. | User provides a method, paper, or experiment and asks for critique. | User asks to write marketing copy. | `scientist` | `scientist`, `researcher`, `analyst` | `science.method`, `reasoning.multi_step` | `long_context` | `text` | |
| `scientist.literature.synthesize` | Scientific Literature Synthesis | Synthesize findings across scientific or technical literature. | User asks to synthesize papers, studies, standards, or evidence. | User asks for unsupported speculation. | `scientist` | `scientist`, `researcher`, `writer` | `science.analysis`, `long_context` | `citation.synthesis` | `text` | |
| `health.info.general` | General Health Information | Provide general, non-diagnostic health information and explain concepts. | User asks for general health education or explanations. | User asks for diagnosis, emergency care, or individualized medical treatment. | `health` | `health`, `educator`, `writer` | `health.general_info`, `text.chat` | `communication.user_facing` | `text` | |
| `health.info.safety` | Health Safety Triage | Provide cautious safety boundaries, urgency guidance, and care-seeking prompts. | User describes potentially concerning symptoms, medication risks, or safety-sensitive health questions. | User asks for definitive diagnosis or treatment instructions. | `health` | `health`, `support` | `health.safety`, `communication.user_facing` | `reasoning.multi_step` | `text` | |
| `health.care_navigation` | Care Navigation | Help prepare questions, organize information, or plan discussion with a clinician. | User asks how to prepare for an appointment or communicate health concerns. | User asks the assistant to replace professional care. | `health` | `health`, `coordinator`, `writer` | `health.general_info`, `coordination.workflow` | `communication.user_facing` | `text` | |
| `health.wellness.plan` | Wellness Planning | Create general wellness, habit, or tracking plans within safe non-medical boundaries. | User asks for general routine, habit, sleep, nutrition, or exercise planning. | User has symptoms, conditions, medications, injury, pregnancy, or other high-risk context requiring professional guidance. | `health` | `health`, `planner`, `educator` | `health.general_info` | `json.schema_adherence` | `text` | |
| `coder.dependency.update` | Dependency Update | Update package dependencies, lockfiles, or version constraints. | User asks to update packages or dependency versions. | User asks for supply-chain risk review only. | `coder` | `coder`, `security`, `operator` | `code.read`, `code.write` | `tools.command_execution` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `coder.config` | Code Configuration | Modify project, build, lint, test, or runtime configuration files. | User asks to configure code tooling or project settings. | User asks for production runtime operations only. | `coder` | `coder`, `operator` | `code.read`, `code.write` | `json.schema_adherence` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `architect.infrastructure.design` | Infrastructure Design | Design infrastructure topology, deployment units, or service boundaries. | User asks for infra architecture or environment design. | User asks to execute deployment commands. | `architect` | `architect`, `operator`, `security` | `reasoning.multi_step` | `long_context` | `text` | |
| `architect.data_model` | Data Model Design | Design entities, schemas, data ownership, and persistence boundaries. | User asks for data model or storage architecture. | User asks for SQL query implementation only. | `architect` | `architect`, `data`, `coder` | `reasoning.multi_step`, `data.schema` | `json.schema_adherence` | `text` | |
| `architect.integration.plan` | Integration Plan | Plan how systems, APIs, events, and services should integrate. | User asks to connect systems or design integration flow. | User asks to debug one failed API call. | `architect` | `architect`, `operator`, `coder` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `architect.scalability.review` | Scalability Review | Review scalability, bottlenecks, throughput, and growth tradeoffs. | User asks whether a system will scale. | User asks for visual UI review. | `architect` | `architect`, `operator`, `data` | `reasoning.multi_step` | `long_context` | `text` | |
| `architect.migration.strategy` | Migration Strategy | Plan migrations across systems, data stores, APIs, or platforms. | User asks how to migrate safely with stages and rollback. | User asks to edit a small file directly. | `architect` | `architect`, `coder`, `operator` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `architect.adr.write` | Architecture Decision Record | Write or review ADRs and architectural decision rationale. | User asks to document a technical decision. | User asks for public marketing copy. | `architect` | `architect`, `writer`, `coder` | `reasoning.multi_step`, `text.chat` | `communication.user_facing` | `text` | |
| `security.secrets.scan` | Secrets Scan Review | Inspect code, config, or logs for exposed secrets and credential risks. | User asks to check for secrets or credential exposure. | User asks for general documentation edits. | `security` | `security`, `coder`, `operator` | `security.analysis`, `code.read` | `tools.command_execution` | `text` | |
| `security.auth.review` | Auth Review | Review authentication, authorization, sessions, tokens, and access flows. | User asks about auth risk or permission behavior. | User asks for non-security code style review. | `security` | `security`, `architect`, `coder` | `security.analysis` | `reasoning.multi_step` | `text` | |
| `security.privacy.review` | Privacy Review | Review data collection, retention, sharing, and privacy-sensitive flows. | User asks about privacy risk or personal data handling. | User asks for binding legal advice. | `security` | `security`, `legal`, `architect` | `security.analysis`, `legal.analysis` | `json.schema_adherence` | `text` | |
| `security.incident.review` | Security Incident Review | Review suspected incidents, indicators, containment, and follow-up actions. | User reports a potential security incident. | User asks for ordinary uptime triage. | `security` | `security`, `operator`, `support` | `security.analysis`, `reasoning.multi_step` | `tools.command_execution` | `text` | |
| `security.safe_prompt.review` | Prompt Safety Review | Review prompts, tools, or agent behavior for misuse and policy risk. | User asks about AI safety, prompt abuse, or tool misuse. | User asks for creative prompt writing only. | `security` | `security`, `researcher`, `writer` | `security.analysis`, `text.chat` | `reasoning.multi_step` | `text` | |
| `researcher.source_find` | Source Finding | Find credible sources, documents, links, or references for a topic. | User asks to find sources or references. | User asks to write from known local context only. | `researcher` | `researcher`, `writer` | `web.search`, `text.chat` | `citation.synthesis` | `text` | `web.search`, `http.fetch` |
| `researcher.timeline.build` | Timeline Building | Build a chronology of events, releases, decisions, or changes. | User asks for a timeline or history. | User asks for mathematical proof. | `researcher` | `researcher`, `analyst`, `writer` | `text.chat`, `long_context` | `citation.synthesis` | `text` | |
| `researcher.market_scan` | Market Scan | Gather current market, vendor, competitor, or product information. | User asks for market landscape or vendor scan. | User asks for internal-only code changes. | `researcher` | `researcher`, `strategist`, `marketer` | `web.search`, `text.chat` | `citation.synthesis` | `text` | |
| `researcher.standards_lookup` | Standards Lookup | Find relevant standards, protocols, policies, or technical references. | User asks which standard or spec applies. | User asks to draft legal terms. | `researcher` | `researcher`, `architect`, `legal` | `web.search`, `long_context` | `citation.synthesis` | `text` | |
| `researcher.document_extract` | Document Extraction | Extract facts, claims, obligations, or details from documents. | User provides docs and asks to pull out key information. | User asks for creative ideation. | `researcher` | `researcher`, `analyst`, `legal` | `text.chat`, `long_context` | `json.schema_adherence` | `text` | |
| `writer.email.write` | Email Writing | Draft clear emails for business, support, sales, or coordination contexts. | User asks to write an email. | User asks for SMS-length ad copy only. | `writer` | `writer`, `coordinator`, `seller`, `support` | `text.chat` | `communication.user_facing` | `text` | `email.write` |
| `writer.blog.write` | Blog Writing | Draft blog posts, articles, essays, or explanatory long-form content. | User asks for a blog or article. | User asks for terse release notes. | `writer` | `writer`, `marketer`, `researcher` | `text.chat` | `long_context` | `text` | |
| `writer.proposal.write` | Proposal Writing | Draft proposals, narratives, scopes, or persuasive structured documents. | User asks to write a proposal or formal document. | User asks for legal contract review. | `writer` | `writer`, `seller`, `planner` | `text.chat` | `communication.user_facing` | `text` | |
| `writer.style.rewrite` | Style Rewrite | Rewrite text for tone, clarity, audience, or style. | User asks to make text clearer or change tone. | User asks for factual verification only. | `writer` | `writer`, `translator`, `marketer` | `text.chat` | `communication.user_facing` | `text` | |
| `writer.outline` | Outline Writing | Create structured outlines for documents, talks, articles, or plans. | User asks to structure content before writing. | User asks for code implementation. | `writer` | `writer`, `planner`, `educator` | `text.chat` | `json.schema_adherence` | `text` | |
| `operator.monitor` | Monitoring Setup | Plan or configure monitoring, alerts, health checks, and runtime signals. | User asks to monitor a service or runtime. | User asks for product positioning. | `operator` | `operator`, `architect` | `tools.function_calling`, `reasoning.multi_step` | `tools.command_execution` | `text` | |
| `operator.backup.restore` | Backup And Restore | Plan or execute backup, restore, recovery, or state verification work. | User asks about backup/restore or recovery procedures. | User asks for code refactoring only. | `operator` | `operator`, `data`, `security` | `tools.command_execution`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `operator.release.execute` | Release Execution | Execute or coordinate release steps, validation, rollback, and post-release checks. | User asks to run or coordinate a release. | User asks for release announcement copy only. | `operator` | `operator`, `planner`, `coder` | `tools.command_execution` | `reasoning.multi_step` | `text` | |
| `analyst.metrics.define` | Metrics Definition | Define metrics, KPIs, dimensions, and measurement logic. | User asks what to measure or how to evaluate. | User asks for visual design. | `analyst` | `analyst`, `product`, `data` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `analyst.risk.assess` | Risk Assessment | Identify, score, and compare risks across options or plans. | User asks what risks matter and how severe they are. | User asks for security exploit details only. | `analyst` | `analyst`, `security`, `strategist` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `analyst.root_cause` | Analytical Root Cause | Analyze non-code causes behind outcomes, incidents, or business symptoms. | User asks why a metric, process, or outcome changed. | User reports a source-code failure. | `analyst` | `analyst`, `operator`, `product` | `reasoning.multi_step` | `long_context` | `text` | |
| `analyst.report.write` | Analysis Report | Produce a structured analytical report with findings and recommendations. | User asks for an analysis write-up. | User asks for a short creative slogan. | `analyst` | `analyst`, `writer`, `strategist` | `reasoning.multi_step`, `text.chat` | `json.schema_adherence` | `text` | |
| `analyst.data_interpret` | Data Interpretation | Interpret charts, tables, metrics, or experiment results. | User asks what data means. | User asks to transform raw data formats only. | `analyst` | `analyst`, `data`, `scientist` | `reasoning.multi_step`, `data.query` | `text.chat` | `text` | |
| `analyst.decision_matrix` | Decision Matrix | Create a weighted decision matrix or scoring rubric. | User asks to choose among options with criteria. | User asks for free-form brainstorming. | `analyst` | `analyst`, `planner`, `procurement` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `analyst.trend.analyze` | Trend Analysis | Analyze trends, changes, seasonality, or directional movement. | User asks how something is changing over time. | User asks for current facts only. | `analyst` | `analyst`, `researcher`, `data` | `reasoning.multi_step` | `web.search` | `text` | |
| `planner.milestone` | Milestone Planning | Define milestones, gates, sequencing, and completion criteria. | User asks for milestones or phased delivery. | User asks to implement immediately. | `planner` | `planner`, `product`, `operator` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.sprint.plan` | Sprint Planning | Plan sprint scope, backlog slices, and delivery sequencing. | User asks for sprint or iteration planning. | User asks for long-term strategy only. | `planner` | `planner`, `coder`, `product` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.acceptance.criteria` | Acceptance Criteria | Write acceptance criteria and verifiable completion checks. | User asks what must be true for work to be done. | User asks for code review only. | `planner` | `planner`, `tester`, `product` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.rollout` | Rollout Planning | Plan rollout stages, risks, communications, and rollback points. | User asks how to roll something out. | User asks for a single announcement. | `planner` | `planner`, `operator`, `product` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.dependency.map` | Dependency Mapping | Map prerequisites, blockers, owners, and sequencing dependencies. | User asks what depends on what. | User asks for creative copy. | `planner` | `planner`, `architect`, `coordinator` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `planner.resource.plan` | Resource Planning | Estimate effort, staffing, ownership, and resource needs. | User asks what resources are needed. | User asks for exact budget accounting. | `planner` | `planner`, `finance`, `coordinator` | `reasoning.multi_step` | `json.schema_adherence` | `text` | `web.search`, `http.fetch` |
| `tester.unit.plan` | Unit Test Planning | Design unit test cases, boundaries, and assertions. | User asks how to unit test behavior. | User asks for browser E2E validation. | `tester` | `tester`, `coder` | `reasoning.multi_step`, `code.read` | `json.schema_adherence` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.integration.plan` | Integration Test Planning | Design integration tests across services, APIs, or components. | User asks how to test integrations. | User asks for isolated unit tests only. | `tester` | `tester`, `coder`, `operator` | `reasoning.multi_step` | `tools.function_calling` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.accessibility` | Accessibility Testing | Verify accessibility expectations for UI, content, and interaction. | User asks for accessibility checks. | User asks for backend performance only. | `tester` | `tester`, `designer`, `product` | `vision.input`, `text.chat` | `json.schema_adherence` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.performance` | Performance Testing | Plan or evaluate performance, load, latency, and throughput tests. | User asks to test performance. | User asks for UI visual polish. | `tester` | `tester`, `operator`, `architect` | `tools.command_execution`, `reasoning.multi_step` | `json.schema_adherence` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.security` | Security Testing | Plan or execute security-oriented validation checks. | User asks how to test security behavior. | User asks for legal policy review. | `tester` | `tester`, `security`, `coder` | `security.analysis`, `tools.function_calling` | `reasoning.multi_step` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `tester.acceptance` | Acceptance Testing | Verify implementation against acceptance criteria and user outcomes. | User asks to validate readiness against requirements. | User asks for implementation only. | `tester` | `tester`, `product`, `planner` | `reasoning.multi_step` | `json.schema_adherence` | `text` | `filesystem.read`, `filesystem.write`, `shell.execute` |
| `data.analyze` | Data Analysis | Analyze structured data for patterns, summaries, and conclusions. | User asks what a dataset shows. | User asks for general web research. | `data` | `data`, `analyst` | `data.query`, `reasoning.multi_step` | `json.schema_adherence` | `text` | `database.query` |
| `data.visualize` | Data Visualization | Plan charts, tables, or visual summaries for data. | User asks how to visualize data. | User asks for illustrative creative art. | `data` | `data`, `analyst`, `designer` | `data.query`, `vision.output` | `json.schema_adherence` | `text` | `database.query` |
| `data.validate` | Data Validation | Validate data quality, constraints, completeness, and anomalies. | User asks whether data is correct or clean. | User asks for schema design only. | `data` | `data`, `tester`, `analyst` | `data.query`, `data.schema` | `json.schema_adherence` | `text` | `database.query` |
| `data.extract` | Data Extraction | Extract structured data from text, files, tables, or documents. | User asks to pull fields or records from content. | User asks for narrative summary only. | `data` | `data`, `researcher` | `data.transform`, `text.chat` | `json.schema_adherence` | `text` | `database.query` |
| `data.join` | Data Joining | Combine datasets, keys, records, or tables into a coherent shape. | User asks to merge or join data. | User asks for non-data writing. | `data` | `data`, `coder` | `data.query`, `data.transform` | `json.schema_adherence` | `text` | `database.query` |
| `data.quality.audit` | Data Quality Audit | Audit quality, lineage, anomalies, duplication, and fitness for use. | User asks for data quality review. | User asks for security audit only. | `data` | `data`, `analyst`, `tester` | `data.query`, `reasoning.multi_step` | `json.schema_adherence` | `text` | `database.query` |
| `data.metric.define` | Metric Definition | Define metrics, dimensions, calculations, and caveats. | User asks to define a metric or analytics logic. | User asks for business strategy only. | `data` | `data`, `analyst`, `product` | `data.query`, `reasoning.multi_step` | `json.schema_adherence` | `text` | `database.query` |
| `product.spec.write` | Product Spec Writing | Write product specs with behavior, states, and constraints. | User asks for a feature spec. | User asks for implementation code only. | `product` | `product`, `planner`, `designer` | `reasoning.multi_step`, `text.chat` | `json.schema_adherence` | `text` | |
| `product.user_story` | User Story Writing | Write user stories, scenarios, and user value statements. | User asks for user stories. | User asks for legal terms. | `product` | `product`, `writer`, `planner` | `text.chat` | `communication.user_facing` | `text` | |
| `product.acceptance` | Product Acceptance | Define acceptance criteria from a product perspective. | User asks what behavior must be accepted. | User asks for technical test implementation. | `product` | `product`, `planner`, `tester` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `product.prd.write` | PRD Writing | Write product requirements documents and decision context. | User asks for a PRD. | User asks for marketing launch copy only. | `product` | `product`, `writer`, `strategist` | `reasoning.multi_step`, `text.chat` | `long_context` | `text` | |
| `product.feature.prioritize` | Feature Prioritization | Prioritize product features by value, cost, risk, and evidence. | User asks which features to build first. | User asks for code-level sequencing only. | `product` | `product`, `analyst`, `planner` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `product.feedback.synthesize` | Feedback Synthesis | Synthesize user feedback, themes, pain points, and opportunities. | User asks what feedback means. | User asks for scientific evidence review. | `product` | `product`, `analyst`, `researcher` | `text.chat`, `long_context` | `json.schema_adherence` | `text` | |
| `product.launch.readiness` | Launch Readiness | Assess product readiness, blockers, messaging, and rollout risk. | User asks whether a feature is ready to launch. | User asks to execute deployment steps. | `product` | `product`, `planner`, `operator` | `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `designer.prototype` | Prototype Design | Design prototype structure, screens, or flows. | User asks for a prototype or mock flow. | User asks for backend architecture only. | `designer` | `designer`, `product`, `creative` | `text.chat`, `vision.output` | `json.schema_adherence` | `text` | |
| `designer.design_system` | Design System Work | Define or review components, tokens, states, and visual rules. | User asks for design system guidance. | User asks for database schema only. | `designer` | `designer`, `architect`, `product` | `text.chat`, `vision.input` | `json.schema_adherence` | `text` | |
| `designer.accessibility.review` | Accessibility Review | Review UI accessibility, contrast, semantics, and interaction clarity. | User asks whether UI is accessible. | User asks for legal accessibility compliance only. | `designer` | `designer`, `tester`, `product` | `vision.input`, `text.chat` | `reasoning.multi_step` | `text` | |
| `designer.content.layout` | Content Layout | Design page structure, information hierarchy, and content placement. | User asks how to lay out content. | User asks for copywriting only. | `designer` | `designer`, `writer`, `product` | `vision.input`, `text.chat` | `vision.output` | `text` | |
| `designer.usability.test` | Usability Test Planning | Plan usability tests, tasks, observations, and evaluation criteria. | User asks how to test usability. | User asks for automated unit tests. | `designer` | `designer`, `tester`, `product` | `text.chat`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `designer.mobile.responsive` | Responsive Design | Review or design responsive and mobile UI behavior. | User asks how UI should adapt to screen sizes. | User asks for server scaling review. | `designer` | `designer`, `coder`, `product` | `vision.input`, `text.chat` | `reasoning.multi_step` | `text` | |
| `designer.visual.qa` | Visual QA | Inspect visual implementation for polish, overlap, spacing, and hierarchy. | User asks whether UI rendering looks correct. | User asks for product-market fit. | `designer` | `designer`, `tester`, `coder` | `vision.input`, `text.chat` | `tools.browser_control` | `text` | |
| `support.ticket.reply` | Support Ticket Reply | Draft a response to a user support issue. | User asks to respond to a customer or support ticket. | User asks for internal-only root cause analysis. | `support` | `support`, `writer` | `text.chat`, `communication.user_facing` | `reasoning.multi_step` | `text` | |
| `support.runbook.write` | Support Runbook | Write troubleshooting runbooks and remediation steps. | User asks to create support procedures. | User asks for legal policy. | `support` | `support`, `operator`, `knowledge` | `communication.user_facing`, `knowledge.organization` | `json.schema_adherence` | `text` | |
| `support.issue.reproduce` | Support Reproduction | Convert a user issue into reproducible steps and expected behavior. | User reports an issue needing repro. | User asks for direct product strategy. | `support` | `support`, `tester`, `operator` | `text.chat`, `coordination.workflow` | `json.schema_adherence` | `text` | |
| `support.knowledge_base.suggest` | Support KB Suggestion | Suggest or draft reusable knowledge-base entries from support issues. | User asks to turn support learnings into KB content. | User asks for one-off sales copy. | `support` | `support`, `knowledge`, `writer` | `communication.user_facing`, `knowledge.organization` | `text.chat` | `text` | |
| `support.status.update` | Support Status Update | Draft clear incident or issue status updates for users. | User asks to communicate issue status. | User asks for internal-only logs. | `support` | `support`, `operator`, `writer` | `communication.user_facing` | `text.chat` | `text` | |
| `support.customer.apology` | Customer Apology | Draft empathetic apologies, explanations, and next steps. | User asks for apology or customer-facing remediation language. | User asks for technical incident analysis only. | `support` | `support`, `writer` | `communication.user_facing` | `text.chat` | `text` | |
| `support.faq.write` | FAQ Writing | Write FAQs, troubleshooting answers, and support snippets. | User asks for reusable support Q\&A. | User asks for legal disclosure. | `support` | `support`, `writer`, `knowledge` | `communication.user_facing`, `text.chat` | `knowledge.organization` | `text` | |
| `legal.privacy.review` | Privacy Legal Review | Review privacy terms, data processing, notices, or user rights text. | User asks for privacy legal review. | User asks for security implementation only. | `legal` | `legal`, `security` | `legal.analysis` | `citation.synthesis` | `text` | |
| `legal.terms.review` | Terms Review | Review terms of service, acceptable use, or contract language. | User asks to review terms or policy text. | User asks for product copy. | `legal` | `legal`, `writer` | `legal.analysis` | `long_context` | `text` | |
| `legal.license.review` | License Review | Review software licenses, obligations, compatibility, or notices. | User asks about open-source licensing. | User asks to update dependencies directly. | `legal` | `legal`, `security`, `coder` | `legal.analysis`, `code.read` | `citation.synthesis` | `text` | |
| `legal.contract.summarize` | Contract Summary | Summarize contract clauses, obligations, risks, and open questions. | User provides contract text and asks for summary. | User asks for binding legal advice. | `legal` | `legal`, `procurement`, `finance` | `legal.analysis`, `long_context` | `json.schema_adherence` | `text` | |
| `legal.risk.issue_spot` | Legal Issue Spotting | Identify legal-sensitive issues, risks, and questions for counsel. | User asks what legal issues may exist. | User asks for final legal advice. | `legal` | `legal`, `security`, `procurement` | `legal.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `legal.policy.draft` | Policy Drafting | Draft internal or public policy language for review. | User asks to draft policy text. | User asks for code implementation. | `legal` | `legal`, `writer`, `security` | `legal.analysis`, `text.chat` | `communication.user_facing` | `text` | |
| `legal.retention.review` | Retention Review | Review retention, deletion, audit, or records-management implications. | User asks about data retention or deletion policy. | User asks for database query writing. | `legal` | `legal`, `data`, `security` | `legal.analysis`, `data.schema` | `json.schema_adherence` | `text` | |
| `legal.accessibility.compliance` | Accessibility Compliance | Review accessibility obligations or compliance-oriented text. | User asks about accessibility compliance. | User asks for UI visual polish only. | `legal` | `legal`, `designer`, `tester` | `legal.analysis` | `citation.synthesis` | `text` | |
| `finance.invoice.review` | Invoice Review | Review invoices, charges, billing details, and anomalies. | User asks to inspect an invoice or bill. | User asks for tax advice. | `finance` | `finance`, `procurement` | `finance.analysis` | `json.schema_adherence` | `text` | |
| `finance.budget.plan` | Budget Planning | Plan budget allocations, constraints, and spend categories. | User asks to plan a budget. | User asks for exact accounting treatment. | `finance` | `finance`, `planner`, `strategist` | `finance.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `finance.forecast` | Financial Forecast | Forecast cost, spend, revenue, or usage under assumptions. | User asks for financial forecasting. | User asks for guaranteed financial prediction. | `finance` | `finance`, `analyst`, `strategist` | `finance.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `finance.unit_economics` | Unit Economics | Analyze margins, unit costs, payback, or per-user economics. | User asks about unit economics. | User asks for engineering architecture. | `finance` | `finance`, `strategist`, `analyst` | `finance.analysis` | `json.schema_adherence` | `text` | |
| `finance.pricing.model` | Pricing Model | Build or critique pricing structures and assumptions. | User asks how to price something. | User asks for sales outreach copy only. | `finance` | `finance`, `strategist`, `seller` | `finance.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `finance.variance.analyze` | Variance Analysis | Analyze actual vs expected cost, budget, or revenue. | User asks why financial numbers changed. | User asks for vendor feature comparison only. | `finance` | `finance`, `analyst`, `data` | `finance.analysis`, `data.query` | `json.schema_adherence` | `text` | |
| `finance.procurement.cost` | Procurement Cost Analysis | Analyze purchasing, vendor, or contract cost implications. | User asks about procurement cost tradeoffs. | User asks for legal contract approval. | `finance` | `finance`, `procurement` | `finance.analysis`, `procurement.analysis` | `json.schema_adherence` | `text` | |
| `finance.roi.calculate` | ROI Calculation | Calculate or estimate return on investment and payback. | User asks for ROI or payback estimate. | User asks for non-financial prioritization only. | `finance` | `finance`, `analyst`, `strategist` | `finance.analysis`, `math.solve` | `json.schema_adherence` | `text` | |
| `creative.name.generate` | Name Generation | Generate names for products, features, projects, or campaigns. | User asks for naming ideas. | User asks for legal trademark clearance. | `creative` | `creative`, `marketer`, `product` | `text.chat` | `reasoning.divergent` | `text` | |
| `creative.concept.develop` | Concept Development | Develop creative concepts, themes, or directions. | User asks to develop an idea or concept. | User asks for factual verification. | `creative` | `creative`, `designer`, `marketer` | `text.chat` | `reasoning.divergent` | `text` | |
| `creative.script.write` | Script Writing | Write scripts for video, audio, demos, or narrative scenes. | User asks for script or scene dialogue. | User asks for legal policy review. | `creative` | `creative`, `writer` | `text.chat` | `vision.output` | `text` | |
| `creative.brand.voice` | Brand Voice | Define or apply brand voice, tone, and language style. | User asks for voice or tone direction. | User asks for literal translation only. | `creative` | `creative`, `marketer`, `writer` | `text.chat`, `marketing.copy` | `communication.user_facing` | `text` | |
| `creative.visual.prompt` | Visual Prompting | Write prompts or briefs for visual generation or visual direction. | User asks for image prompt or visual creative brief. | User asks to inspect existing UI only. | `creative` | `creative`, `designer` | `vision.output`, `text.chat` | `reasoning.divergent` | `text` | |
| `creative.tagline` | Tagline Writing | Generate concise taglines, slogans, and campaign lines. | User asks for taglines or slogans. | User asks for source-cited research. | `creative` | `creative`, `marketer`, `writer` | `marketing.copy`, `text.chat` | `reasoning.divergent` | `text` | |
| `creative.social.post` | Social Post Writing | Draft social posts, captions, and short creative variants. | User asks for social media copy. | User asks for documentation. | `creative` | `creative`, `marketer`, `writer` | `text.chat`, `marketing.copy` | `communication.user_facing` | `text` | |
| `educator.curriculum.design` | Curriculum Design | Design curriculum structure, modules, outcomes, and sequencing. | User asks to design a course or curriculum. | User asks for one answer only. | `educator` | `educator`, `planner` | `education.tutoring`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `educator.study.plan` | Study Plan | Create study plans, schedules, practice progression, and review cadence. | User asks how to study a subject. | User asks for business roadmap. | `educator` | `educator`, `planner`, `coordinator` | `education.tutoring`, `calendar.planning` | `json.schema_adherence` | `text` | |
| `educator.example.generate` | Learning Examples | Generate examples, analogies, worked examples, or practice cases. | User asks for examples to understand a topic. | User asks for verified sources only. | `educator` | `educator`, `writer` | `education.tutoring`, `text.chat` | `communication.user_facing` | `text` | |
| `educator.rubric.create` | Rubric Creation | Create grading rubrics, criteria, and scoring guidance. | User asks for a rubric. | User asks to evaluate a job candidate. | `educator` | `educator`, `tester`, `recruiter` | `education.assessment` | `json.schema_adherence` | `text` | |
| `educator.concept.explain` | Concept Explanation | Explain concepts at an appropriate learner level. | User asks to understand a concept. | User asks for professional medical advice. | `educator` | `educator`, `writer` | `education.tutoring`, `text.chat` | `communication.user_facing` | `text` | |
| `educator.practice.review` | Practice Review | Review practice answers and suggest improvement steps. | User submits practice work for feedback. | User asks for hiring decision. | `educator` | `educator`, `mathematician`, `writer` | `education.assessment`, `communication.user_facing` | `reasoning.multi_step` | `text` | |
| `translator.tone.adapt` | Tone Adaptation | Adapt translated or original text to a tone or audience. | User asks to make text more formal, casual, polite, or local. | User asks for factual source comparison. | `translator` | `translator`, `writer` | `language.localization`, `text.chat` | `communication.user_facing` | `text` | |
| `translator.glossary.create` | Glossary Creation | Create or maintain bilingual/multilingual terminology lists. | User asks for glossary or term consistency. | User asks for marketing positioning only. | `translator` | `translator`, `knowledge` | `language.translation` | `json.schema_adherence` | `text` | |
| `translator.subtitles.translate` | Subtitle Translation | Translate subtitles, captions, or timed dialogue. | User asks to translate subtitles or captions. | User asks for audio transcription itself. | `translator` | `translator`, `writer` | `language.translation`, `text.chat` | `communication.user_facing` | `text` | |
| `translator.technical.translate` | Technical Translation | Translate technical docs, UI strings, or implementation text. | User asks to translate technical material. | User asks to design the system. | `translator` | `translator`, `coder`, `writer` | `language.translation`, `code.read` | `communication.user_facing` | `text` | |
| `translator.back_translate` | Back Translation | Translate content back to check meaning preservation. | User asks to validate translation fidelity. | User asks for new creative copy. | `translator` | `translator`, `writer` | `language.translation` | `reasoning.multi_step` | `text` | |
| `translator.locale.review` | Locale Review | Review locale-specific wording, formats, and cultural fit. | User asks if localized content works for a locale. | User asks for literal translation only. | `translator` | `translator`, `marketer` | `language.localization` | `communication.user_facing` | `text` | |
| `translator.multilingual.reply` | Multilingual Reply | Draft replies in a target language for support, sales, or coordination. | User asks to respond in another language. | User asks for legal certification. | `translator` | `translator`, `support`, `seller` | `language.translation`, `communication.user_facing` | `text.chat` | `text` | |
| `marketer.audience.research` | Audience Research | Research or define target audiences, segments, and needs. | User asks who the audience is. | User asks for scientific literature review. | `marketer` | `marketer`, `researcher`, `strategist` | `marketing.analysis`, `web.search` | `json.schema_adherence` | `text` | |
| `marketer.email.sequence` | Marketing Email Sequence | Draft nurture, launch, or campaign email sequences. | User asks for marketing email sequence. | User asks for personal support ticket response. | `marketer` | `marketer`, `writer`, `seller` | `marketing.copy`, `text.chat` | `communication.user_facing` | `text` | `email.write` |
| `marketer.landing_page.copy` | Landing Page Copy | Write or revise landing page messaging and conversion copy. | User asks for landing page copy. | User asks for product spec only. | `marketer` | `marketer`, `writer`, `designer` | `marketing.copy`, `text.chat` | `communication.user_facing` | `text` | |
| `marketer.social.plan` | Social Marketing Plan | Plan social channels, posts, cadence, and campaign themes. | User asks for a social media plan. | User asks for one social post only. | `marketer` | `marketer`, `creative`, `planner` | `marketing.analysis` | `json.schema_adherence` | `text` | |
| `marketer.messaging.review` | Messaging Review | Review messaging for clarity, differentiation, and audience fit. | User asks whether messaging works. | User asks for legal claims approval. | `marketer` | `marketer`, `product`, `writer` | `marketing.analysis`, `text.chat` | `reasoning.multi_step` | `text` | |
| `marketer.launch.plan` | Marketing Launch Plan | Plan marketing launch messaging, channels, and readiness. | User asks for launch marketing plan. | User asks for deployment execution. | `marketer` | `marketer`, `product`, `planner` | `marketing.analysis` | `json.schema_adherence` | `text` | |
| `seller.account.plan` | Account Plan | Plan account strategy, stakeholders, risks, and next steps. | User asks for sales account planning. | User asks for general market strategy only. | `seller` | `seller`, `strategist` | `sales.analysis` | `json.schema_adherence` | `text` | |
| `seller.demo.script` | Demo Script | Write product demo scripts and discovery-aligned walkthroughs. | User asks for demo talk track. | User asks for technical test plan. | `seller` | `seller`, `product`, `writer` | `sales.communication`, `text.chat` | `communication.user_facing` | `text` | |
| `seller.follow_up.write` | Sales Follow-Up | Draft sales follow-up notes after calls, demos, or objections. | User asks for follow-up sales message. | User asks for support apology only. | `seller` | `seller`, `coordinator`, `writer` | `sales.communication`, `communication.follow_up` | `text.chat` | `text` | |
| `seller.competitor.battlecard` | Competitor Battlecard | Create competitive sales positioning and objection responses. | User asks for a battlecard. | User asks for unbiased academic comparison only. | `seller` | `seller`, `marketer`, `strategist` | `sales.analysis`, `market.analysis` | `json.schema_adherence` | `text` | |
| `seller.call.summary` | Sales Call Summary | Summarize sales calls into needs, risks, next steps, and owners. | User provides sales notes or transcript. | User asks for legal contract summary. | `seller` | `seller`, `coordinator`, `support` | `sales.analysis`, `coordination.workflow` | `json.schema_adherence` | `text` | |
| `seller.mutual_action_plan` | Mutual Action Plan | Create shared buyer/seller action plans, timelines, and owners. | User asks for mutual action plan or close plan. | User asks for project sprint plan. | `seller` | `seller`, `planner`, `procurement` | `sales.analysis`, `coordination.workflow` | `json.schema_adherence` | `text` | |
| `recruiter.sourcing.message` | Sourcing Message | Draft candidate outreach and sourcing messages. | User asks for recruiting outreach. | User asks for sales prospecting. | `recruiter` | `recruiter`, `writer` | `recruiting.analysis`, `communication.user_facing` | `text.chat` | `text` | |
| `recruiter.scorecard.create` | Scorecard Creation | Create hiring scorecards, competencies, and evaluation criteria. | User asks for a hiring scorecard. | User asks for learner quiz rubric. | `recruiter` | `recruiter`, `planner` | `recruiting.analysis` | `json.schema_adherence` | `text` | |
| `recruiter.interview.feedback` | Interview Feedback | Structure interview notes and job-relevant feedback. | User asks to write interview feedback. | User asks to infer protected attributes. | `recruiter` | `recruiter`, `writer`, `legal` | `recruiting.analysis`, `text.chat` | `json.schema_adherence` | `text` | |
| `recruiter.offer.prepare` | Offer Preparation | Prepare offer discussion points, constraints, and candidate communication. | User asks for offer preparation. | User asks for payroll/legal final approval. | `recruiter` | `recruiter`, `finance`, `writer` | `recruiting.analysis`, `communication.user_facing` | `json.schema_adherence` | `text` | |
| `recruiter.pipeline.update` | Pipeline Update | Summarize hiring pipeline status, blockers, and next steps. | User asks for recruiting pipeline update. | User asks for sales pipeline update. | `recruiter` | `recruiter`, `coordinator` | `recruiting.analysis`, `coordination.workflow` | `json.schema_adherence` | `text` | |
| `recruiter.role.intake` | Role Intake | Define hiring role intake questions, requirements, and constraints. | User asks how to scope a role opening. | User asks for job ad copy only. | `recruiter` | `recruiter`, `product`, `planner` | `recruiting.analysis` | `json.schema_adherence` | `text` | |
| `recruiter.candidate.compare` | Candidate Comparison Support | Compare candidates against explicit job criteria. | User asks to compare candidate materials using a rubric. | User asks for unlawful or protected-class inference. | `recruiter` | `recruiter`, `analyst`, `legal` | `recruiting.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `procurement.security.questionnaire` | Security Questionnaire | Draft or review vendor security questionnaire content. | User asks for security questionnaire support. | User asks for internal security incident response. | `procurement` | `procurement`, `security` | `procurement.analysis`, `security.analysis` | `json.schema_adherence` | `text` | |
| `procurement.vendor.scorecard` | Vendor Scorecard | Build vendor scoring criteria, weights, and summaries. | User asks for vendor scorecard. | User asks for marketing comparison. | `procurement` | `procurement`, `analyst`, `finance` | `procurement.analysis` | `json.schema_adherence` | `text` | |
| `procurement.renewal.review` | Renewal Review | Review renewal timing, pricing, usage, risk, and negotiation points. | User asks whether to renew a vendor. | User asks for legal final approval. | `procurement` | `procurement`, `finance`, `legal` | `procurement.analysis`, `finance.analysis` | `reasoning.multi_step` | `text` | |
| `procurement.sla.review` | SLA Review | Review service levels, support terms, penalties, and operational fit. | User asks about SLA implications. | User asks for uptime incident triage. | `procurement` | `procurement`, `operator`, `legal` | `procurement.analysis`, `legal.analysis` | `json.schema_adherence` | `text` | |
| `procurement.negotiation.plan` | Negotiation Plan | Prepare vendor negotiation strategy, asks, and fallback positions. | User asks how to negotiate vendor terms. | User asks for sales objection handling. | `procurement` | `procurement`, `finance`, `seller` | `procurement.analysis`, `finance.analysis` | `reasoning.multi_step` | `text` | |
| `procurement.purchase.justification` | Purchase Justification | Draft justification for purchase, renewal, or vendor selection. | User asks to justify buying something. | User asks for implementation code. | `procurement` | `procurement`, `finance`, `writer` | `procurement.analysis`, `communication.user_facing` | `json.schema_adherence` | `text` | |
| `coordinator.task.plan` | Task Planning | Organize tasks, owners, deadlines, and dependencies. | User asks to organize work into tasks. | User asks for deep architecture. | `coordinator` | `coordinator`, `planner` | `coordination.workflow` | `json.schema_adherence` | `text` | |
| `coordinator.inbox.triage` | Inbox Triage | Triage messages, requests, priorities, and responses. | User asks to sort or prioritize inbox-like items. | User asks for legal review. | `coordinator` | `coordinator`, `support` | `coordination.workflow`, `text.chat` | `json.schema_adherence` | `text` | |
| `coordinator.decision.log` | Decision Log | Create or update decision logs, owners, and rationale. | User asks to record decisions. | User asks for creative naming. | `coordinator` | `coordinator`, `knowledge`, `planner` | `coordination.workflow`, `knowledge.organization` | `json.schema_adherence` | `text` | |
| `coordinator.project.status` | Project Status | Draft project status updates, risks, and next steps. | User asks for status update. | User asks for formal financial forecast. | `coordinator` | `coordinator`, `planner`, `writer` | `coordination.workflow`, `communication.user_facing` | `json.schema_adherence` | `text` | |
| `coordinator.reminder.plan` | Reminder Planning | Plan reminders, follow-ups, and timing. | User asks to remember or schedule follow-ups. | User asks for durable memory update only. | `coordinator` | `coordinator`, `knowledge` | `calendar.planning`, `communication.follow_up` | `json.schema_adherence` | `text` | |
| `coordinator.handoff.prepare` | Handoff Preparation | Prepare handoff notes, context, decisions, and open items. | User asks to hand work to another person or team. | User asks for public release notes. | `coordinator` | `coordinator`, `support`, `operator` | `coordination.workflow`, `communication.user_facing` | `long_context` | `text` | |
| `knowledge.note.summarize` | Note Summarization | Summarize notes into reusable facts, decisions, and follow-ups. | User provides notes for organization. | User asks for current web facts. | `knowledge` | `knowledge`, `writer` | `knowledge.organization`, `text.chat` | `json.schema_adherence` | `text` | `memory.read`, `vector.search` |
| `knowledge.taxonomy.design` | Knowledge Taxonomy Design | Design categories, tags, and organization for knowledge systems. | User asks how to organize a knowledge base. | User asks for runtime taxonomy implementation. | `knowledge` | `knowledge`, `architect` | `knowledge.organization`, `reasoning.multi_step` | `json.schema_adherence` | `text` | `memory.read`, `vector.search` |
| `knowledge.link.map` | Link Mapping | Map relationships between docs, notes, concepts, or references. | User asks how knowledge items relate. | User asks for vendor pricing. | `knowledge` | `knowledge`, `researcher` | `knowledge.organization`, `long_context` | `json.schema_adherence` | `text` | `memory.read`, `vector.search` |
| `knowledge.runbook.update` | Runbook Update | Update runbooks, operating procedures, and durable instructions. | User asks to update reusable operational knowledge. | User asks for ephemeral explanation only. | `knowledge` | `knowledge`, `operator`, `support` | `knowledge.organization`, `communication.user_facing` | `text.chat` | `text` | `memory.read`, `vector.search` |
| `knowledge.archive.clean` | Archive Cleanup | Clean, deduplicate, or organize old knowledge records. | User asks to clean a knowledge archive. | User asks for legal retention decision. | `knowledge` | `knowledge`, `coordinator` | `knowledge.organization` | `json.schema_adherence` | `text` | `memory.read`, `vector.search` |
| `knowledge.context.brief` | Context Brief | Create concise context briefs for projects, users, or teams. | User asks to brief someone on context. | User asks for raw data transformation. | `knowledge` | `knowledge`, `writer`, `coordinator` | `knowledge.retrieval`, `text.chat` | `long_context` | `text` | `memory.read`, `vector.search` |
| `strategist.swot` | SWOT Analysis | Analyze strengths, weaknesses, opportunities, and threats. | User asks for SWOT or strategic situation analysis. | User asks for code review. | `strategist` | `strategist`, `analyst` | `strategy.analysis` | `json.schema_adherence` | `text` | |
| `strategist.okr.define` | OKR Definition | Define objectives, key results, initiatives, and measures. | User asks for OKRs or strategic goals. | User asks for sprint task details only. | `strategist` | `strategist`, `planner`, `product` | `strategy.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `strategist.board.brief` | Board Brief | Prepare board or executive strategy briefs. | User asks for executive or board-level summary. | User asks for casual social post. | `strategist` | `strategist`, `writer`, `finance` | `strategy.analysis`, `text.chat` | `communication.user_facing` | `text` | |
| `strategist.operating.model` | Operating Model | Design organizational operating models, responsibilities, and cadence. | User asks how an organization should operate. | User asks for database schema. | `strategist` | `strategist`, `planner`, `coordinator` | `strategy.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `strategist.pricing.strategy` | Pricing Strategy | Develop pricing strategy, packaging, and market fit. | User asks for pricing strategy. | User asks for exact invoice review. | `strategist` | `strategist`, `finance`, `marketer` | `strategy.analysis`, `finance.analysis` | `json.schema_adherence` | `text` | |
| `strategist.partnership.evaluate` | Partnership Evaluation | Evaluate partnerships, channels, alliances, or ecosystem opportunities. | User asks whether a partnership makes sense. | User asks for vendor procurement scorecard only. | `strategist` | `strategist`, `seller`, `procurement` | `strategy.analysis`, `market.analysis` | `reasoning.multi_step` | `text` | |
| `mathematician.statistics.analyze` | Statistical Analysis | Analyze statistical results, distributions, uncertainty, or significance. | User asks for statistical interpretation. | User asks for scientific method critique only. | `mathematician` | `mathematician`, `data`, `scientist` | `math.solve`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `mathematician.optimize` | Optimization | Formulate or solve optimization problems and constraints. | User asks to maximize, minimize, or optimize. | User asks for creative brainstorming. | `mathematician` | `mathematician`, `analyst`, `finance` | `math.modeling`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `mathematician.proof.write` | Proof Writing | Write or structure mathematical proofs. | User asks for proof or rigorous derivation. | User asks for code implementation. | `mathematician` | `mathematician`, `educator` | `math.verify`, `reasoning.multi_step` | `text.chat` | `text` | |
| `mathematician.formula.derive` | Formula Derivation | Derive equations, formulas, or transformations. | User asks to derive a formula. | User asks for financial advice. | `mathematician` | `mathematician`, `scientist` | `math.solve`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `mathematician.simulation.plan` | Simulation Planning | Plan simulations, assumptions, variables, and outputs. | User asks how to simulate a system. | User asks to run production deployment. | `mathematician` | `mathematician`, `scientist`, `data` | `math.modeling`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `mathematician.error.check` | Error Checking | Check arithmetic, formulas, calculations, and numerical consistency. | User asks to check math for mistakes. | User asks for prose editing only. | `mathematician` | `mathematician`, `tester`, `finance` | `math.verify` | `reasoning.multi_step` | `text` | |
| `scientist.hypothesis.formulate` | Hypothesis Formulation | Formulate testable hypotheses and expected observations. | User asks how to turn an idea into a hypothesis. | User asks for business OKRs. | `scientist` | `scientist`, `educator`, `analyst` | `science.method`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `scientist.protocol.write` | Protocol Writing | Write experimental protocols, materials, steps, and measurements. | User asks for experiment protocol structure. | User asks for clinical treatment plan. | `scientist` | `scientist`, `planner` | `science.method`, `text.chat` | `json.schema_adherence` | `text` | |
| `scientist.data.interpret` | Scientific Data Interpretation | Interpret scientific data, results, uncertainty, and limitations. | User asks what scientific results mean. | User asks for legal compliance review. | `scientist` | `scientist`, `data`, `analyst` | `science.analysis`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `scientist.peer_review` | Peer Review Support | Review scientific writing, claims, methods, and evidence quality. | User asks to peer review a paper or report. | User asks for marketing copy. | `scientist` | `scientist`, `researcher`, `writer` | `science.analysis`, `long_context` | `citation.synthesis` | `text` | |
| `scientist.safety.review` | Scientific Safety Review | Review safety considerations for experiments or technical methods. | User asks about experiment safety considerations. | User asks for medical diagnosis. | `scientist` | `scientist`, `security`, `health` | `science.method`, `reasoning.multi_step` | `json.schema_adherence` | `text` | |
| `scientist.technical.explain` | Scientific Explanation | Explain scientific concepts, mechanisms, or findings clearly. | User asks to understand a scientific topic. | User asks for current legal policy. | `scientist` | `scientist`, `educator`, `writer` | `science.analysis`, `text.chat` | `communication.user_facing` | `text` | |
| `health.medication.info` | Medication Information | Provide general medication information and safety boundaries. | User asks general questions about medication facts or interactions. | User asks for personalized prescribing or dosing instructions. | `health` | `health`, `researcher` | `health.general_info`, `health.safety` | `communication.user_facing` | `text` | |
| `health.appointment.prepare` | Appointment Preparation | Help prepare questions, notes, and concerns for a healthcare visit. | User asks to prepare for a medical appointment. | User asks assistant to diagnose. | `health` | `health`, `coordinator`, `writer` | `health.general_info`, `coordination.workflow` | `communication.user_facing` | `text` | |
| `health.symptom.organize` | Symptom Organization | Organize symptoms, timing, context, and questions for care discussion. | User wants to organize health observations. | User asks for definitive diagnosis. | `health` | `health`, `coordinator` | `health.safety`, `coordination.workflow` | `json.schema_adherence` | `text` | |
| `health.exercise.general` | General Exercise Information | Provide general exercise information within safe boundaries. | User asks for general fitness education or habit ideas. | User has injury, condition, or high-risk medical context. | `health` | `health`, `educator` | `health.general_info` | `communication.user_facing` | `text` | |
| `health.nutrition.general` | General Nutrition Information | Provide general nutrition information and meal-planning concepts. | User asks for general nutrition education. | User asks for medical nutrition therapy. | `health` | `health`, `educator` | `health.general_info` | `communication.user_facing` | `text` | |
| `health.mental_wellness.info` | Mental Wellness Information | Provide general mental wellness information and support-seeking guidance. | User asks for general stress, sleep, or wellness information. | User presents imminent self-harm or crisis requiring emergency escalation. | `health` | `health`, `support` | `health.safety`, `communication.user_facing` | `reasoning.multi_step` | `text` | |
### Capabilities [#capabilities]
| Capability | Label |
| --------------------------- | ------------------------- |
| `text.chat` | Text Chat |
| `code.read` | Code Read |
| `code.write` | Code Write |
| `reasoning.multi_step` | Reasoning Multi Step |
| `tools.function_calling` | Tools Function Calling |
| `tools.command_execution` | Tools Command Execution |
| `json.schema_adherence` | Json Schema Adherence |
| `security.analysis` | Security Analysis |
| `web.search` | Web Search |
| `citation.synthesis` | Citation Synthesis |
| `long_context` | Long Context |
| `tools.browser_control` | Tools Browser Control |
| `vision.input` | Vision Input |
| `data.query` | Data Query |
| `data.schema` | Data Schema |
| `data.transform` | Data Transform |
| `legal.analysis` | Legal Analysis |
| `finance.analysis` | Finance Analysis |
| `reasoning.divergent` | Reasoning Divergent |
| `vision.output` | Vision Output |
| `communication.user_facing` | Communication User Facing |
| `communication.follow_up` | Communication Follow Up |
| `education.tutoring` | Education Tutoring |
| `education.assessment` | Education Assessment |
| `language.translation` | Language Translation |
| `language.localization` | Language Localization |
| `marketing.analysis` | Marketing Analysis |
| `marketing.copy` | Marketing Copy |
| `sales.analysis` | Sales Analysis |
| `sales.communication` | Sales Communication |
| `recruiting.analysis` | Recruiting Analysis |
| `procurement.analysis` | Procurement Analysis |
| `coordination.workflow` | Coordination Workflow |
| `calendar.planning` | Calendar Planning |
| `knowledge.organization` | Knowledge Organization |
| `knowledge.retrieval` | Knowledge Retrieval |
| `memory.write` | Memory Write |
| `strategy.analysis` | Strategy Analysis |
| `market.analysis` | Market Analysis |
| `math.solve` | Math Solve |
| `math.verify` | Math Verify |
| `math.modeling` | Math Modeling |
| `science.analysis` | Science Analysis |
| `science.method` | Science Method |
| `health.general_info` | Health General Info |
| `health.safety` | Health Safety |
### Modalities [#modalities]
| Modality | Label |
| ----------------- | --------------- |
| `text` | Text |
| `image` | Image |
| `audio` | Audio |
| `video` | Video |
| `file` | File |
| `structured_json` | Structured Json |
| `tabular` | Tabular |
| `code_patch` | Code Patch |
| `document` | Document |
### Tool Classes [#tool-classes]
| Tool class | Label |
| ------------------ | ---------------- |
| `filesystem.read` | Filesystem Read |
| `filesystem.write` | Filesystem Write |
| `shell.execute` | Shell Execute |
| `browser.control` | Browser Control |
| `web.search` | Web Search |
| `http.fetch` | Http Fetch |
| `database.query` | Database Query |
| `package.install` | Package Install |
| `calendar.read` | Calendar Read |
| `calendar.write` | Calendar Write |
| `email.read` | Email Read |
| `email.write` | Email Write |
| `memory.read` | Memory Read |
| `memory.write` | Memory Write |
| `vector.search` | Vector Search |
{/* TAXONOMY_V1_CATALOG:END */}
## Why roles and tasks are separate [#why-roles-and-tasks-are-separate]
This split lets the protocol express:
* one role supporting multiple tasks
* one task allowing multiple roles
* different tool policies or output contracts for the same capability family
* endpoint-specific activation state via role binding
If roles and tasks were collapsed into one record, those distinctions would be much harder to represent.
Groups are not routing roles; they are discovery, UI, and progressive-disclosure objects.
## `RoleDefinition` [#roledefinition]
Role definitions carry:
* `primaryGroupId`
* `secondaryGroupIds`
* `task_types_supported`
* `required_capabilities`
* `preferred_capabilities`
* `forbidden_capabilities`
* `tool_policy`
* `routing_policy_overrides`
* `output_contracts`
* `safety_policy_refs`
## `TaskDefinition` [#taskdefinition]
Task definitions carry:
* `required_inputs`
* `required_capabilities`
* `preferred_capabilities`
* `quality_metrics`
* `allowed_roles`
* `default_benchmark_suites`
## `RoleBinding` [#rolebinding]
Role bindings are what make role support concrete at the endpoint level. Each binding states:
* which `role_id` is bound to which `endpoint_id`
* whether the binding is `active`, `disabled`, or `candidate`
* policy overrides
* effective capabilities
* effective task types
If a requested role has a non-active binding for an endpoint, the reference router rejects that endpoint with
`ROLE_BINDING_INACTIVE`.
## `role_model.intent` [#role_modelintent]
Consumers such as Pi can send `role_model.intent` metadata with role, task, capability, modality, tool-class,
confidence, evidence, and alternatives. Role-Model treats Pi-provided taxonomy metadata as advisory unless it
comes from an explicit trusted hard constraint. Unknown advisory fields are ignored with diagnostics so stale
client metadata does not drop the user's request.
## How roles become concrete [#how-roles-become-concrete]
Roles are abstract protocol entities until they are bound into routable infrastructure.
That happens through `RoleBinding`, which binds a `role_id` to a concrete `endpoint_id`. Because endpoint
identity also carries model lineage, this is how roles become attached to **model-serving endpoints** in
practice.
role-model does not assume that one model permanently owns one role. A role may be active on multiple
endpoints, including multiple endpoints serving the same model under different deployment conditions. The
router uses those bindings to define the eligible set, then uses observed performance and policy to decide
which endpoint actually wins.
## `TaskExecutionProfile` [#taskexecutionprofile]
`TaskExecutionProfile` is a patch layer with:
* `task_type`
* `role_id`
* `required_capabilities`
* `preferred_capabilities`
* `routing_policy_patch`
It exists so the protocol can express that a task performed under a specific role may need a narrower or
different execution shape than the generic task definition suggests.
## Mapping pattern [#mapping-pattern]
| Object | What it contributes |
| ---------------------- | -------------------------------------------------------------- |
| `RoleDefinition` | says which task families and execution constraints are allowed |
| `TaskDefinition` | says what the unit of work requires |
| `RoleBinding` | says whether a specific endpoint can currently serve that role |
| `TaskExecutionProfile` | says how execution is patched for that role-task pairing |
# Router decision artifact (/protocol/router-decision-artifact)
# Router decision artifact [#router-decision-artifact]
`RouterDecision` is the canonical routing output. It records not only who won, but also **why** and **under
what policy snapshot**.
## Core fields [#core-fields]
| Field | Meaning |
| ----------------------- | ----------------------------------------------------------------------- |
| `routing_decision_id` | stable identifier for the decision artifact |
| `request_id` | the request the decision belongs to |
| `policy_snapshot` | the effective policy that governed evaluation |
| `eligibility` | per-candidate pass/fail state plus exclusion details |
| `scored_candidates` | the eligible candidates and their final scores |
| `chosen_endpoint_id` | the selected endpoint, or an empty string when none is eligible |
| `fallback_endpoint_ids` | the remaining eligible candidates in ranked order |
| `selection_reasons` | reason codes explaining why the chosen candidate won |
| `used_measured` | whether the chosen candidate had observed performance data |
| `used_declared` | whether a chosen candidate existed and therefore declared data was used |
| `scoring_version` | the scoring implementation version used to compute the result |
## Eligibility block [#eligibility-block]
The `eligibility` array is the record of hard filtering. Each candidate gets:
* `endpoint_id`
* `eligible`
* `exclusions`
Even candidates that passed are listed, which makes the final decision auditable.
## Score block [#score-block]
The `scored_candidates` array contains only eligible candidates. It is the ranked result after metric
scoring and tie-breaking.
The fallback list is derived from that ranking:
* `chosen_endpoint_id` is the `endpoint_id` from the first scored candidate.
* `fallback_endpoint_ids` is the ordered list of the remaining scored candidates.
## Explainability flags [#explainability-flags]
`used_measured` and `used_declared` are compact summary flags:
* `used_measured = true` when the chosen endpoint had an observed profile
* `used_declared = true` when a candidate was chosen at all
They let downstream systems quickly tell whether a result relied on measured evidence, declared-only
compatibility, or neither.
## Failure shape [#failure-shape]
When no endpoint is eligible, the reference router returns:
* a populated `eligibility` array
* an empty `scored_candidates` array
* `chosen_endpoint_id: ""`
* no fallbacks
* no selection reasons
That is still a valid, protocol-shaped decision artifact.
# Routing policy (/protocol/routing-policy)
# Routing policy [#routing-policy]
`RoutingPolicy` is a canonical input to routing. It is not an implementation-only config blob.
The schema models:
* optimization strategy
* compute preference
* required capabilities and modalities
* tool requirements
* endpoint and provider allow/deny lists
* budget controls
* privacy controls
* performance targets
* optional tie-break ordering
## Strategy and compute preference [#strategy-and-compute-preference]
The baseline policy strategy enum is:
* `balanced`
* `cost`
* `latency`
* `quality`
The schema's `compute_preference` enum is:
* `auto`
* `local`
* `remote`
* `hybrid`
In the reference router, request flags such as `preferLocal`, `computePreference`, and `denyRemote` are
folded into the effective policy snapshot before routing proceeds.
The important distinction is:
* `strategy` describes scoring intent such as quality vs latency vs cost
* `compute_preference` describes locality posture such as local vs remote
They are related, but they are not the same control.
`hybrid` in `compute_preference` should be understood as protocol surface that keeps both pools expressible.
The current baseline router most directly applies locality preference when the value is `local` or `remote`.
## Hard-constraint fields [#hard-constraint-fields]
These fields participate directly in eligibility:
* `required_capabilities`
* `required_modalities`
* `require_tools`
* `deny_endpoints`
* `allow_endpoints`
* `deny_provider_kinds`
* `allow_provider_kinds`
* `privacy.allow_remote`
They determine which candidates may even remain in consideration.
## Budget and privacy [#budget-and-privacy]
The `budget` object states whether budget enforcement is enabled and what cost bounds apply. The reference
router emits a `budget_mode` of `strict` when a request budget exists and `disabled` otherwise.
The `privacy` object currently includes `allow_remote`, which is how policy can force routing to stay local.
## Targets and tie-breaks [#targets-and-tie-breaks]
The `targets` object models optimization goals such as:
* `latency_target_ms`
* `latency_max_ms`
* `throughput_target_tps`
The reference router currently snapshots a default tie-break order of:
1. higher `quality`
2. lower `latency_ms`
3. higher `reliability`
4. stable `endpoint_id`
That snapshot is important because the final `RouterDecision` should explain the policy that was actually
applied, not just the policy a caller remembers sending.
## Policy snapshot semantics [#policy-snapshot-semantics]
The router copies the effective policy into the `RouterDecision` as `policy_snapshot`. This gives downstream
consumers a stable record of:
1. what constraints were active
2. what optimization mode was in effect
3. what locality, budget, and target settings governed the decision
# Trace and usage artifacts (/protocol/trace-and-usage-artifacts)
# Trace and usage artifacts [#trace-and-usage-artifacts]
role-model treats observability as protocol-owned data, not as leftover implementation logs.
## The three artifact types [#the-three-artifact-types]
| Artifact | Purpose |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| `TraceSpan` | timed phases such as eligibility, scoring, selection, provider decode, fallback, or retry |
| `TraceEvent` | point events that announce things such as a decision being created, a span opening or closing, or a profile update |
| `UsageEvent` | accounting and execution outcome data such as tokens, latency, provider, endpoint, and cost estimate |
## `TraceSpan` [#tracespan]
`TraceSpan` captures duration and status. The schema includes baseline span types such as:
* `router.eligibility`
* `router.scoring`
* `router.selection`
* `router.fallback`
* `router.retry`
* `provider.load`
* `provider.queue`
* `provider.prefill`
* `provider.decode`
* `tool.execution`
* `request.failure`
This lets routing and execution be described as phases instead of opaque wall-clock time.
## `TraceEvent` [#traceevent]
`TraceEvent` is the lighter-weight lifecycle signal. Baseline `event_type` values include:
* `router.decision.created`
* `trace.span.opened`
* `trace.span.closed`
* `usage.event.created`
* `profile.sample.recorded`
* `profile.updated`
These events connect the decision, trace, usage, and profile-update layers together.
## `UsageEvent` [#usageevent]
`UsageEvent` records execution/accounting facts such as:
* `endpoint_id`
* `provider_kind`
* `tokens_in`
* `tokens_out`
* `latency_ms`
* optional `cost_estimate`
* optional `error_class`
* optional `sample_source`
This is how routing decisions become durable usage evidence.
## Linking semantics [#linking-semantics]
All three artifact families use shared identifiers to remain joinable:
* `request_id`
* `routing_decision_id`
* `trace_id`
* `span_id`
* `endpoint_id`
That joinability is the key reason these artifacts belong in the protocol model rather than in custom log
formats that every host invents independently.
# Protocol lifecycle (/protocol-lifecycle)
# Protocol lifecycle [#protocol-lifecycle]
The protocol describes a lifecycle, not just a static schema set.
## Lifecycle stages [#lifecycle-stages]
### 1. Endpoint definition [#1-endpoint-definition]
An endpoint enters the system with an `EndpointIdentity`. This is the routable thing the rest of the protocol
attaches to.
### 2. Declared profile publication [#2-declared-profile-publication]
The system publishes a `DeclaredCapabilityProfile` for that endpoint. This establishes compatibility claims
such as supported capabilities, modalities, context window, and tool-calling behavior.
### 3. Observed profile accumulation [#3-observed-profile-accumulation]
Benchmarks and live requests generate samples that later aggregate into `ObservedPerformanceProfile` records.
This is how the protocol captures operational evidence rather than leaving it in ad hoc dashboards.
### 4. Execution intent assembly [#4-execution-intent-assembly]
A request chooses or implies:
* a role
* a task
* a policy
* a candidate set
This is the full input space the router reasons over.
### 5. Routing decision [#5-routing-decision]
The router evaluates eligibility, scores eligible candidates, applies tie-breaks, and emits a
`RouterDecision`.
### 6. Observability emission [#6-observability-emission]
After or around execution, the system emits:
* `TraceSpan`
* `TraceEvent`
* `UsageEvent`
Each artifact links back to the request and routing decision IDs so the run can be reconstructed later.
### 7. Feedback into future routing [#7-feedback-into-future-routing]
Usage and tracing outcomes become new measured samples. The profile aggregator converts those samples into
freshness-weighted, confidence-scored observed profiles that influence the next routing decision.
# Protocol object model (/protocol-object-model)
# Protocol object model [#protocol-object-model]
The protocol is best understood as a graph of related artifacts rather than a flat list of schemas.
## Relationship map [#relationship-map]
| From | To | Why the relationship exists |
| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `EndpointIdentity` | `DeclaredCapabilityProfile` | declared capabilities only make sense when attached to a concrete endpoint |
| `EndpointIdentity` | `ObservedPerformanceProfile` | measurements are endpoint-specific and must not be merged across materially different deployments |
| `RoleDefinition` | `TaskDefinition` | roles state which task families they support; tasks state which roles are allowed |
| `RoleBinding` | endpoint + role | binds a role to one endpoint with an activation status and effective capabilities |
| `TaskExecutionProfile` | task + role + policy | adjusts capability and policy requirements for a particular execution shape |
| candidate set + policy + execution intent | `RouterDecision` | a decision is the evaluated result of those inputs |
| `RouterDecision` | traces + usage | later artifacts refer back to the decision via IDs so routing stays inspectable |
| traces + usage | observed profile | execution evidence feeds future routing through measured performance updates |
## Two complementary evidence layers [#two-complementary-evidence-layers]
### Declared layer [#declared-layer]
The declared layer is the **compatibility floor**. It determines whether an endpoint can plausibly satisfy the
task at all:
* required capabilities
* required modalities
* context size
* tool-calling support
* platform constraints
### Observed layer [#observed-layer]
The observed layer is the **comparative evidence layer**. It determines how endpoints trade off once more than
one endpoint is eligible:
* latency
* throughput
* failure rate
* quality or judge score
* cost estimate
* freshness
* confidence
## Where the model lives in the object model [#where-the-model-lives-in-the-object-model]
The protocol does not define a separate routing object called "model candidate."
Instead, model lineage lives inside `EndpointIdentity`:
* `model_id`
* `package_id`
* `variant_id`
That design preserves model identity without pretending that model name alone is enough for routing. Declared
capability, observed performance, and policy all need a concrete endpoint-shaped object to attach to.
## Why profiles attach to endpoints [#why-profiles-attach-to-endpoints]
Profiles attach to endpoints because two endpoints serving the same model may behave differently in practice.
role-model keeps those profiles endpoint-specific so the router can compare real deployments rather than
collapsing everything under one model label.
## Why the model is split this way [#why-the-model-is-split-this-way]
The object model deliberately separates:
1. **identity** from capability claims
2. **capability claims** from measured performance
3. **execution intent** from endpoint metadata
4. **routing inputs** from routing outputs
5. **routing outputs** from later observability and feedback artifacts
That separation prevents routers from inferring hidden state or collapsing different operational concerns into
one overloaded record.
# Quickstart (/quickstart)
# Quickstart [#quickstart]
This top-level URL is kept for compatibility with older links.
The canonical onboarding flow now lives under **Get Started**.
## Use the new onboarding path [#use-the-new-onboarding-path]
If you are setting up the runtime for real use, follow these pages in order:
1. [Install](/get-started/install)
2. [First launch and connect models](/get-started/first-launch-and-connect-models)
3. [Run the full benchmark](/get-started/run-full-benchmark)
4. [Choose and save the routing strategy](/get-started/choose-routing-strategy)
5. [First request and inspect the decision](/get-started/first-request-and-decision)
That path is the recommended first-run sequence because benchmarking now belongs before routing-strategy
selection.
## Use the repository smoke flow when you want source-level proof [#use-the-repository-smoke-flow-when-you-want-source-level-proof]
If you want to understand the protocol and router behavior from source instead of operating the packaged
runtime, use:
```bash
corepack enable
corepack pnpm install
corepack pnpm run smoke
```
## Read next [#read-next]
* [Install](/get-started/install)
* [Run the full benchmark](/get-started/run-full-benchmark)
* [How role-model works](/concepts/how-role-model-works)
* [Routing overview](/concepts/routing-overview)
* [How routing works end to end](/router/how-routing-works-end-to-end)
* [Router decision artifact](/protocol/router-decision-artifact)
# Canonical schemas reference (/reference/canonical-schemas-reference)
# Canonical schemas reference [#canonical-schemas-reference]
This page is the compact inventory of the canonical JSON Schemas under `protocol/schemas/`.
## Endpoint and profile schemas [#endpoint-and-profile-schemas]
| Schema | Purpose | Key fields |
| ------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `endpoint-identity.schema.json` | identifies the concrete routable endpoint | `endpoint_id`, `endpoint_kind`, `provider_kind`, `serving_source`, `model_id`, `runtime_version`, optional deployment details |
| `declared-capability-profile.schema.json` | provider-declared compatibility claims | `capabilities`, `modalities`, `max_context_tokens`, `tool_calling`, `supports_embeddings`, `platform_constraints` |
| `observed-performance-profile.schema.json` | measured endpoint behavior | sample window, sample size, latency, throughput, failure, cost, freshness, confidence |
| `capability-taxonomy.schema.json` | stable capability vocabulary | `version`, `capabilities[]`, each with `id`, `family`, `description` |
## Role and task schemas [#role-and-task-schemas]
| Schema | Purpose | Key fields |
| ------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `role-definition.schema.json` | execution persona and operating contract | supported tasks, required/preferred/forbidden capabilities, tool policy, overrides, output contracts |
| `role-binding.schema.json` | endpoint-specific role activation | `role_id`, `endpoint_id`, `status`, `policy_overrides`, `effective_capabilities`, `effective_task_types` |
| `task-definition.schema.json` | unit of work contract | required inputs, required/preferred capabilities, quality metrics, allowed roles, benchmark suites |
| `task-execution-profile.schema.json` | role-and-task-specific execution patch | `task_type`, `role_id`, required/preferred capabilities, `routing_policy_patch` |
## Routing schemas [#routing-schemas]
| Schema | Purpose | Key fields |
| ----------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `routing-policy.schema.json` | routing constraints and optimization intent | strategy, compute preference, capability/modality requirements, budget, privacy, targets |
| `router-decision.schema.json` | explainable routing outcome | policy snapshot, eligibility, scored candidates, chosen endpoint, fallbacks, selection reasons, evidence flags |
## Observability schemas [#observability-schemas]
| Schema | Purpose | Key fields |
| ------------------------- | -------------------------------- | --------------------------------------------------------------------------- |
| `trace-span.schema.json` | timed execution phases | trace IDs, span IDs, span type, start/end timestamps, status, attributes |
| `trace-event.schema.json` | point lifecycle events | event IDs, routing IDs, event type, payload |
| `usage-event.schema.json` | accounting and execution outcome | request, endpoint, provider, tokens, latency, optional cost and error class |
## Invariants to remember [#invariants-to-remember]
* identity anchors profile records
* observed profiles are endpoint-specific and evidence-bearing
* policy is an input; decision is an output
* traces and usage link back to routing via shared IDs
* schema meaning is canonical even when a specific implementation only uses part of the available surface
# Overview (/reference/overview)
# Reference overview [#reference-overview]
This section is for the deeper contract and reference material behind the onboarding and operator guides.
## Use Reference when you need [#use-reference-when-you-need]
* schema-level field details
* reason-code taxonomy
* the canonical protocol object set
* artifact semantics for decisions, traces, usage, and observed performance
* exact protocol vocabulary instead of product-summary explanations
## Core reference reading path [#core-reference-reading-path]
Start here when you want the deeper model:
1. [/core-vocabulary](/core-vocabulary)
2. [/protocol-object-model](/protocol-object-model)
3. [/protocol-lifecycle](/protocol-lifecycle)
4. [/concepts/roles-tasks-and-capabilities](/concepts/roles-tasks-and-capabilities)
5. [/protocol/roles-and-tasks](/protocol/roles-and-tasks)
6. [/protocol/router-decision-artifact](/protocol/router-decision-artifact)
7. [/reference/canonical-schemas-reference](/reference/canonical-schemas-reference)
## Why this is not the first stop anymore [#why-this-is-not-the-first-stop-anymore]
The public site now leads with install, setup, benchmarking, and operator flow because most new readers need
to understand the runtime and routing behavior before they need schema-level details.
Reference remains the canonical deeper layer once that product-level picture is clear.
# Reason codes and rejection taxonomy (/reference/reason-codes-and-rejection-taxonomy)
# Reason codes and rejection taxonomy [#reason-codes-and-rejection-taxonomy]
Reason codes are the stable vocabulary used to explain why candidates were rejected and why one candidate won.
## Exclusion codes [#exclusion-codes]
| Code | Meaning | Current reference-router emission |
| ----------------------- | -------------------------------------------- | ------------------------------------------ |
| `CAPABILITY_MISSING` | a required capability is absent | emitted |
| `MODALITY_UNSUPPORTED` | a required modality is absent | emitted |
| `CONTEXT_TOO_SMALL` | context window is insufficient | emitted |
| `TOOLS_UNSUPPORTED` | tool use was required but unsupported | emitted |
| `POLICY_DENY_ENDPOINT` | policy removed the candidate | emitted |
| `POLICY_DENY_REMOTE` | remote execution is forbidden | emitted |
| `BUDGET_EXCEEDED` | observed cost exceeds budget | emitted |
| `PROVIDER_OFFLINE` | provider is offline | emitted |
| `REVOKED` | endpoint is revoked | emitted |
| `TASK_NOT_SUPPORTED` | the requested role does not support the task | emitted |
| `ROLE_NOT_ALLOWED` | the task does not allow the requested role | emitted |
| `ROLE_BINDING_INACTIVE` | the relevant role binding is not active | emitted |
| `VARIANT_INCOMPATIBLE` | variant does not satisfy request constraints | reserved vocabulary; not currently emitted |
| `ENTITLEMENT_MISSING` | a required entitlement is absent | reserved vocabulary; not currently emitted |
| `PACKAGE_NOT_INSTALLED` | endpoint package is unavailable locally | reserved vocabulary; not currently emitted |
## Selection reasons [#selection-reasons]
| Code | Meaning |
| ----------------------------- | ------------------------------------------------------------------- |
| `BEST_TOTAL_SCORE` | the candidate won the final ranking |
| `MEASURED_PROFILE_USED` | observed performance data contributed to ranking |
| `DECLARED_PROFILE_USED` | declared capability data contributed to ranking |
| `DEFAULT_PROFILE_USED` | missing measured data forced neutral defaults |
| `LOCAL_PREFERENCE_APPLIED` | locality preference favored or evaluated the candidate as local |
| `REMOTE_PREFERENCE_APPLIED` | locality preference favored or evaluated the candidate as remote |
| `BUDGET_OPTIMIZATION` | cost strategy was active |
| `LOW_LATENCY_TARGET_MET` | latency strategy was active |
| `HIGH_QUALITY_TARGET_MET` | quality strategy was active |
| `ROLE_PREFERENCE_APPLIED` | role preferred-capability matches improved the candidate |
| `TASK_REQUIREMENTS_SATISFIED` | task preferred-capability matches improved the candidate |
| `FALLBACK_CHAIN_COMPUTED` | more than one eligible candidate existed, so fallbacks were ordered |
## Semantics to keep straight [#semantics-to-keep-straight]
* exclusion codes explain **why a candidate never reached scoring**
* selection reasons explain **why a scored candidate became the chosen endpoint**
* a decision can contain both rejected candidates and a fully explained winning endpoint
In other words, reason codes are not just error labels. They are the protocol's explainability vocabulary.
# Candidate selection and eligibility (/router/candidate-selection-and-eligibility)
# Candidate selection and eligibility [#candidate-selection-and-eligibility]
Before any scoring happens, Router has to decide which endpoints are even allowed to compete.
## Candidate selection comes before optimization [#candidate-selection-comes-before-optimization]
This is a hard rule in role-model:
an endpoint that fails compatibility or policy should be excluded, not "rescued" by a good score.
## What a candidate is [#what-a-candidate-is]
In these docs, a **candidate** means a **candidate endpoint**.
The candidate set may include:
* endpoints serving different models
* multiple endpoints serving the same model
* local, remote, or mixed execution paths
That is why routing happens at the endpoint layer instead of the model-name layer.
## What enters the candidate set before Router starts filtering [#what-enters-the-candidate-set-before-router-starts-filtering]
The reference router does not discover endpoints by itself. It consumes a request input that already contains
a candidate set plus the protocol records needed to interpret it.
Each candidate should carry:
* `identity`
* `declared`
* optional `observed`
* `status`
* optional policy-deny markers
Additional context can also be supplied alongside the candidates:
* `roleDefinitions`
* `taskDefinitions`
* `roleBindings`
This is the upstream discovery boundary:
* discovery says which endpoints are in scope
* routing says how those endpoints are evaluated and ranked
## Why role bindings matter [#why-role-bindings-matter]
Role assignment is part of candidate construction, not just a label on top.
If a request needs `coder`, an endpoint without an active compatible binding for that role should not
compete, even if the underlying model looks strong in the abstract.
## Actual exclusion checks in the current baseline [#actual-exclusion-checks-in-the-current-baseline]
The baseline hard-filtering phase can remove candidates for reasons such as:
* missing required capabilities
* unsupported modalities
* insufficient context window
* missing tool support
* policy deny lists
* remote denial or locality restrictions
* budget incompatibility
* inactive or incompatible role bindings
`evaluateEligibility()` currently emits these concrete rejection codes:
| Code | Trigger in the current baseline |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `PROVIDER_OFFLINE` | candidate status is `offline` |
| `REVOKED` | candidate status is `revoked` |
| `POLICY_DENY_ENDPOINT` | explicit deny markers, allow-list misses, provider allow/deny failures, or forbidden role capabilities |
| `POLICY_DENY_REMOTE` | request forbids remote routing and the candidate is not local |
| `ROLE_BINDING_INACTIVE` | a requested role has a non-active binding for this endpoint |
| `TASK_NOT_SUPPORTED` | the requested role does not support the request's task type |
| `ROLE_NOT_ALLOWED` | the task definition does not allow the requested role |
| `CAPABILITY_MISSING` | one or more effective required capabilities are missing |
| `MODALITY_UNSUPPORTED` | one or more required modalities are missing |
| `CONTEXT_TOO_SMALL` | requested context tokens exceed `max_context_tokens` |
| `TOOLS_UNSUPPORTED` | the request needs tools and the endpoint does not support tool calling |
| `BUDGET_EXCEEDED` | observed cost estimate exceeds the request budget |
## Effective required capabilities [#effective-required-capabilities]
The router does not only look at request-level required capabilities. It merges:
* request required capabilities
* requested role required capabilities
* requested task required capabilities
This is why a candidate can be rejected even if it satisfied the request-level capability list alone.
## One policy code can represent several policy sources [#one-policy-code-can-represent-several-policy-sources]
The baseline intentionally collapses several policy failures into `POLICY_DENY_ENDPOINT`, including:
* explicit endpoint deny lists
* allow-list misses
* provider-kind allow-list misses
* provider-kind denies
* role-forbidden capability conflicts
The important semantic point is not which exact config branch fired first. It is that policy removed this
endpoint before scoring began.
## Reserved vocabulary versus active baseline behavior [#reserved-vocabulary-versus-active-baseline-behavior]
The broader protocol surface names additional codes such as:
* `PACKAGE_NOT_INSTALLED`
* `VARIANT_INCOMPATIBLE`
* `ENTITLEMENT_MISSING`
Those should be read as reserved vocabulary unless the current baseline actually emits them.
## Why this matters operationally [#why-this-matters-operationally]
This is why the first-time setup order matters:
1. connect endpoints
2. activate models
3. assign roles
4. benchmark
5. save strategy
If the role and activation layer is wrong, the benchmark and later strategy selection will be operating on
the wrong candidate set.
## Read next [#read-next]
* [Scoring strategies and tradeoffs](/router/strategy-modes-and-tradeoffs)
* [Scoring, tie-breaks, and decisions](/router/scoring-tie-breaks-and-decisions)
* [How routing works end to end](/router/how-routing-works-end-to-end)
* [Reason codes and rejection taxonomy](/reference/reason-codes-and-rejection-taxonomy)
# Fallbacks, failures, and observability (/router/fallbacks-failures-and-observability)
# Fallbacks, failures, and observability [#fallbacks-failures-and-observability]
The end product of Router is a `RouterDecision`.
That artifact is not only "who won." It records the policy snapshot, exclusions, ranked candidates, chosen
endpoint, and fallback order.
## Fallbacks are part of the same ranked result [#fallbacks-are-part-of-the-same-ranked-result]
Fallbacks are not a separate speculative pass.
They are simply the remaining eligible candidates after the same deterministic ranking that produced the
winner.
That means a valid decision contains:
* one chosen endpoint
* zero or more fallback endpoints already in deterministic order
## Execution fallback can react to live failures [#execution-fallback-can-react-to-live-failures]
The ranked fallback list is still part of the decision artifact, but execution can react when the chosen
endpoint fails after routing.
Current runtime behavior is:
* timeout, network, rate-limit, and upstream 5xx failures get one quick same-endpoint retry before reroute
* quota-exhausted and provider-auth failures skip the in-place retry, but they are still eligible for
cross-endpoint fallback
* invalid-request failures stay terminal and do not trigger fallback
Fallback-eligible failures also place the endpoint into a temporary cooldown window so the next request does
not keep selecting the same broken path immediately. The current cooldown schedule steps through `10`
minutes, `30` minutes, `1` hour, `5` hours, `10` hours, and `20` hours.
## What a healthy decision tells you [#what-a-healthy-decision-tells-you]
A good decision record lets you answer:
* what policy was active
* which candidates were rejected
* which candidates were scored
* why the winner beat the others
* whether measured evidence, benchmark evidence, or declared-only evidence carried the result
## How strategy shows up in a decision [#how-strategy-shows-up-in-a-decision]
The decision artifact should make strategy visible rather than implicit.
When reading a decision, confirm:
* the saved strategy appears in `policy_snapshot`
* the winner matches the kind of tradeoff that strategy should prefer
* the fallback order also reflects the same strategy rather than a separate hidden rule
If you need the mode-by-mode explanation first, read
[/router/strategy-modes-and-tradeoffs](/router/strategy-modes-and-tradeoffs).
## Success, no-match, and degraded-evidence outcomes [#success-no-match-and-degraded-evidence-outcomes]
Routing can succeed, fail cleanly, or succeed with thin evidence.
### Successful selection [#successful-selection]
Success means:
* at least one candidate was eligible
* at least one candidate was scored
* `chosen_endpoint_id` is populated
* `selection_reasons` explain the winning choice
If more than one candidate was eligible, the decision also carries a fallback chain.
### No eligible endpoint [#no-eligible-endpoint]
When nothing is eligible, Router should still return a useful artifact:
* all candidates appear in `eligibility`
* each rejected candidate carries exclusion details
* no scored candidates
* no chosen endpoint
* no fallback list
This is not an exception-shaped outcome. It is still a valid protocol artifact.
### Policy conflict [#policy-conflict]
Policy conflict usually appears as "all candidates rejected by policy," for example:
* every endpoint is denied by allow/deny rules
* remote routing is forbidden but no local candidate exists
* role-forbidden capabilities eliminate the remaining candidates
The important point is that the protocol communicates this through candidate-level exclusions rather than
through one special top-level error code.
### Degraded selection with defaults [#degraded-selection-with-defaults]
A router can still select an endpoint without rich observed performance evidence. In that case the decision
will typically include default-driven scoring signals rather than a hard failure.
Insufficient evidence is usually represented as a weaker, more default-driven decision rather than as a
rejection.
## Observability extends the decision story [#observability-extends-the-decision-story]
`RouterDecision` is the summary artifact, but it is not the only one.
### Decision as summary [#decision-as-summary]
`RouterDecision` explains:
* policy
* eligibility
* ranking
* winner
* fallbacks
* reasons
### Traces as phase-level explanation [#traces-as-phase-level-explanation]
Trace spans and events explain how the request moved through routing and execution:
* when eligibility opened and closed
* when scoring ran
* whether fallback or retry happened
* where provider-side latency accumulated
### Usage as outcome and accounting [#usage-as-outcome-and-accounting]
`UsageEvent` answers the practical outcome questions:
* which endpoint actually served the request
* how many tokens were consumed
* how long it took
* what it likely cost
* whether an error class occurred
### Feedback loop [#feedback-loop]
The observability model is not write-only. Usage and benchmark samples become new measured evidence, and the
profile aggregator folds them into updated observed profiles with freshness and confidence scores.
That is how routing becomes a feedback system rather than a static policy engine.
## Inspect in product, then in reference [#inspect-in-product-then-in-reference]
Use product surfaces first:
* Router -> Decisions
* Router -> Decision detail
* Observe -> request and telemetry detail
Then use deeper reference when needed:
* [/protocol/router-decision-artifact](/protocol/router-decision-artifact)
* [/protocol/trace-and-usage-artifacts](/protocol/trace-and-usage-artifacts)
* [/router/protocol-to-router-mapping](/router/protocol-to-router-mapping)
# How routing works end to end (/router/how-routing-works-end-to-end)
# How routing works end to end [#how-routing-works-end-to-end]
The reference router in `role-model-router/packages/core/src/router.ts` is a clear implementation of the
protocol's routing model.
## End-to-end flow [#end-to-end-flow]
## Step 1: Normalize request intent into policy [#step-1-normalize-request-intent-into-policy]
The router first computes:
* the effective compute preference
* the effective required capabilities
* the effective preferred capabilities
* a canonical policy strategy
This becomes the `policy_snapshot` embedded in the final decision.
## Step 1b: Narrow to role-eligible model-serving endpoints [#step-1b-narrow-to-role-eligible-model-serving-endpoints]
If the request names a role, the router first narrows the comparison set to endpoints where that role is
active and compatible.
Those endpoints may represent:
* different models
* or multiple endpoints serving the same model
At this stage, the router is not choosing a bare model name. It is constructing the set of concrete
model-serving endpoints that are allowed to compete.
## Step 2: Evaluate eligibility [#step-2-evaluate-eligibility]
Every candidate is checked for:
* status
* policy denies and allow lists
* local/remote restrictions
* role-binding status
* task support and role allowance
* capability and modality compatibility
* context window sufficiency
* tool support
* budget compatibility
This phase produces the `eligibility` array and the set of still-eligible candidates.
## Step 3: Compute metric scores [#step-3-compute-metric-scores]
Eligible candidates receive per-metric scores for:
* quality
* latency
* throughput
* cost
* reliability
* preference
Scoring compares eligible **endpoints**, not abstract model families. That matters because the same model may
be available through multiple endpoints with different observed performance and policy implications.
Measured evidence is used when present; neutral defaults are used when it is absent.
## Step 4: Redistribute missing-metric weight [#step-4-redistribute-missing-metric-weight]
If an entire metric is unknown for **all** eligible candidates, the reference router removes that metric's
weight and redistributes it proportionally across the remaining metrics. This keeps scoring from being
dominated by evidence that does not exist.
## Step 5: Score and annotate candidates [#step-5-score-and-annotate-candidates]
Each eligible candidate gets:
* a numeric score
* selection-reason annotations such as `MEASURED_PROFILE_USED` or `ROLE_PREFERENCE_APPLIED`
## Step 6: Sort and tie-break [#step-6-sort-and-tie-break]
The router sorts by total score, but if two candidates are within `SCORE_TIE_EPSILON = 0.01`, it breaks ties
by:
1. higher quality score
2. lower effective latency
3. higher reliability score
4. lexicographically stable `endpoint_id`
## Step 7: Emit the decision [#step-7-emit-the-decision]
The final `RouterDecision` contains:
* the policy snapshot
* full eligibility outcomes
* ranked scored candidates
* the chosen endpoint
* fallbacks
* selection reasons
* evidence flags
* scoring version (`baseline-v2` in the current baseline)
# Overview (/router/overview)
# Router overview [#router-overview]
The Router layer is where role-model turns a role-aware request and a configured endpoint set into an
explainable decision.
## What Router is responsible for [#what-router-is-responsible-for]
Router answers four questions:
1. which endpoints are even allowed to compete
2. which endpoints are excluded and why
3. how the remaining candidates compare
4. why the final winner and fallback order were chosen
## The baseline flow [#the-baseline-flow]
The current baseline does this in order:
1. normalize request intent into the effective policy snapshot
2. narrow the set through role, task, and policy compatibility
3. apply hard eligibility checks
4. score the eligible endpoints using the saved routing strategy
5. break near-ties deterministically
6. emit a `RouterDecision`
## Strategy is part of the comparison stage [#strategy-is-part-of-the-comparison-stage]
The docs now distinguish between two different layers that were previously easy to blur together:
* **scoring strategy** such as `balanced`, `quality`, `latency`, or `cost`
* **runtime routing mode** such as `baseline`, `controller`, `difficulty`, or `hybrid`
The saved scoring strategy is the policy mode that changes what Router optimizes for once the eligible set is
clean.
The four baseline modes are:
* `balanced`
* `quality`
* `latency`
* `cost`
They all score the same eligible candidates, but they weight quality, latency, throughput, cost,
reliability, and preference differently.
Read [Scoring strategies and tradeoffs](/router/strategy-modes-and-tradeoffs) for the weighting guide and
[Routing modes, locality, and execution](/router/routing-modes-locality-and-execution) for the runtime-mode
and local/remote scope guide.
## What makes the result useful [#what-makes-the-result-useful]
Router is not only trying to produce a winner. It is trying to leave behind enough evidence that an operator
can inspect the decision later and understand:
* what policy was in force
* what got excluded
* what got ranked
* which measured or declared signals mattered
## Read next [#read-next]
* [Routing modes, locality, and execution](/router/routing-modes-locality-and-execution)
* [Scoring strategies and tradeoffs](/router/strategy-modes-and-tradeoffs)
* [Candidate selection and eligibility](/router/candidate-selection-and-eligibility)
* [Scoring, tie-breaks, and decisions](/router/scoring-tie-breaks-and-decisions)
* [Fallbacks, failures, and observability](/router/fallbacks-failures-and-observability)
# Protocol-to-router mapping (/router/protocol-to-router-mapping)
# Protocol-to-router mapping [#protocol-to-router-mapping]
The protocol and the reference router are tightly related, but they are not the same layer.
## What is canonical [#what-is-canonical]
The canonical layer lives in `protocol/` and the associated protocol docs:
* schema names
* field meanings
* artifact relationships
* observability artifact types
* the existence of routing policy and router decisions as protocol objects
## What the reference router adds [#what-the-reference-router-adds]
The reference router in `role-model-router/packages/core` adds baseline implementation choices such as:
* how request flags become an effective policy snapshot
* the exact strategy weights
* runtime routing modes such as `baseline`, `controller`, `difficulty`, and `hybrid`
* the neutral defaults used when metrics are missing
* the redistribution rule for unknown metrics
* the tie epsilon and tie-break ordering
* the current `baseline-v2` scoring version
These choices are useful and coherent, but they are not themselves the canonical protocol.
## Important current gaps between protocol vocabulary and router behavior [#important-current-gaps-between-protocol-vocabulary-and-router-behavior]
The protocol surface is broader than the current router implementation in a few places:
| Protocol surface | Current reference-router state |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `compute_preference` schema includes `hybrid` | the current request-normalization logic only derives `auto`, `local`, or `remote` |
| exclusion vocabulary includes `PACKAGE_NOT_INSTALLED`, `VARIANT_INCOMPATIBLE`, `ENTITLEMENT_MISSING` | the current `evaluateEligibility()` logic does not emit those codes |
| `tie_break_order` is part of `RoutingPolicy` | the reference router snapshots a fixed default order rather than interpreting arbitrary tie-break expressions |
These are not contradictions in the protocol. They indicate that the protocol reserves more expressive surface
than the current reference implementation actively uses.
The packaged runtime also introduces implementation-level routing modes that sit above the pure policy
strategy layer. Those modes are useful product behavior, but they are not themselves part of the canonical
protocol strategy enum.
## From model lineage to candidate endpoint [#from-model-lineage-to-candidate-endpoint]
In the protocol, model lineage lives inside `EndpointIdentity` through fields like `model_id`, `package_id`,
and `variant_id`.
In the router, that identity is carried inside an `EndpointCandidate`, which is the concrete object the
implementation filters, scores, and selects.
The model is therefore still present in routing, but it is present **inside the endpoint-shaped routing
unit**, not as a separate top-level routing object.
## The practical rule [#the-practical-rule]
When documentation needs to answer "what does role-model mean?", use the protocol schemas and protocol docs.
When documentation needs to answer "how does the baseline router currently behave?", use the router
implementation.
# Routing modes, locality, and execution (/router/routing-modes-locality-and-execution)
# Routing modes, locality, and execution [#routing-modes-locality-and-execution]
One source of confusion in `role-model` today is that the product exposes **multiple routing controls** that
sound similar but do different jobs.
This page separates them.
## The three main knobs [#the-three-main-knobs]
| Knob | Examples | What it changes |
| -------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| scoring strategy | `balanced`, `quality`, `latency`, `cost` | how already-eligible candidates are weighted during baseline scoring |
| runtime routing mode | `baseline`, `controller`, `difficulty`, `hybrid` | which runtime routing planner is active before the final endpoint is chosen |
| execution / locality scope | `hybrid`, `local_only`, `remote_only`, `decision_only` | whether the runtime is allowed to execute against local backends, remote backends, both, or neither |
If you collapse those into one concept, the docs become misleading.
## Scoring strategy is the protocol-level optimization intent [#scoring-strategy-is-the-protocol-level-optimization-intent]
The canonical policy strategy vocabulary is:
* `balanced`
* `quality`
* `latency`
* `cost`
That strategy feeds the baseline weighted scoring model described in
[/router/strategy-modes-and-tradeoffs](/router/strategy-modes-and-tradeoffs).
This is the layer that answers:
> once the eligible set is known, should the winner lean toward quality, latency, cost, or a mixed posture?
## Runtime routing mode is the packaged runtime planner choice [#runtime-routing-mode-is-the-packaged-runtime-planner-choice]
The packaged runtime and runtime UI also expose routing modes:
* `baseline`
* `controller`
* `difficulty`
* `hybrid`
These are implementation-level runtime modes, not the canonical protocol strategy enum.
### `baseline` [#baseline]
Use the deterministic baseline route without controller or difficulty guidance.
This is the most direct path from canonical request + policy into the reference-router scoring model.
### `controller` [#controller]
Use controller-guided endpoint selection when the routing controller is available.
In practice this means the runtime can accept controller directives such as preferred endpoint IDs, updated
capability posture, or strategy hints before the final execution plan is applied.
### `difficulty` [#difficulty]
Use difficulty-aware routing that matches the request to endpoint difficulty bounds.
The runtime records difficulty diagnostics such as:
* `easy`, `medium`, or `hard` request classification
* rubric signals like tool count, context size, history turns, and code/schema burden
* excluded endpoints whose recommended max difficulty ceiling is too low
The operator UI already treats this as **Strategy C - Difficulty** and shows benchmark-informed difficulty
advisories per candidate.
### `hybrid` [#hybrid]
Blend controller guidance with difficulty-aware fallback behavior.
This mode lets controller and difficulty signals both participate, with runtime arbitration deciding whether
the dominant signal came from:
* `difficulty`
* `controller`
* `aligned`
## Execution mode is a separate operator control [#execution-mode-is-a-separate-operator-control]
The runtime config also exposes execution modes:
* `hybrid`
* `local_only`
* `remote_only`
* `decision_only`
These affect which execution surfaces the runtime can actually use.
| Execution mode | What it means |
| --------------- | ------------------------------------------------------------------------------ |
| `hybrid` | keep both local llama-swap and remote LiteLLM execution available |
| `local_only` | route only through local execution surfaces |
| `remote_only` | route only through remote provider-backed execution surfaces |
| `decision_only` | keep routing and diagnostics active without enabling local or remote execution |
This is different from scoring strategy.
A runtime can be in `quality` scoring posture while still being `local_only`, or use `difficulty` routing
mode while remaining `hybrid` for execution.
## Local, remote, and hybrid also appear in policy locality [#local-remote-and-hybrid-also-appear-in-policy-locality]
The protocol surface includes `compute_preference` values:
* `auto`
* `local`
* `remote`
* `hybrid`
This is the policy-facing locality preference layer, not the runtime execution mode dropdown.
In the current baseline reference router:
* `local` gives local candidates a preference boost
* `remote` gives remote candidates a preference boost
* `auto` keeps locality neutral
* `hybrid` exists in the protocol surface but is currently best understood as "keep both pools available"
rather than as a special new scoring bonus
For most operators, **execution mode** is the stronger coarse control and **compute preference** is the
lighter routing preference inside the remaining pool.
## How benchmark evidence fits into these layers [#how-benchmark-evidence-fits-into-these-layers]
Benchmarking feeds these controls differently:
* baseline scoring strategies use benchmark evidence most directly for quality weighting
* difficulty mode uses benchmark and observed profile evidence to recommend per-endpoint max difficulty
* controller mode may still consume strategy hints or preferred endpoint posture, but it is not the same as a
benchmark score table
* execution mode does not come from the benchmark at all; it is an operator scope decision
So benchmarks help answer:
* which endpoint is strongest on quality?
* which endpoint is fast enough?
* which endpoint is trustworthy for harder requests?
Benchmarks do **not** decide whether the runtime should be `local_only` or `remote_only`.
## Practical operator examples [#practical-operator-examples]
### Example 1: local-first coding workstation [#example-1-local-first-coding-workstation]
* routing mode: `difficulty`
* execution mode: `hybrid`
* compute preference: `local`
* scoring strategy inside baseline-compatible decisions: `quality`
Meaning:
Hard requests can escalate to stronger endpoints when difficulty routing says they should, but the runtime
still prefers local execution when the request is easy enough and a local endpoint is eligible.
### Example 2: remote SaaS path with strict spend control [#example-2-remote-saas-path-with-strict-spend-control]
* routing mode: `baseline`
* execution mode: `remote_only`
* compute preference: `remote`
* scoring strategy: `cost`
Meaning:
The runtime cannot pick local endpoints at all, and among the remote eligible set it tries to optimize for
cost.
### Example 3: experimentation with controller plus fallback [#example-3-experimentation-with-controller-plus-fallback]
* routing mode: `hybrid`
* execution mode: `hybrid`
Meaning:
The runtime lets controller guidance shape the plan but still keeps difficulty-aware fallback behavior
available when the controller signal is weak or conflicts with observed endpoint posture.
## The important docs rule [#the-important-docs-rule]
When the docs say **strategy**, they need to specify which layer they mean:
* scoring strategy
* runtime routing mode
* execution mode
* locality preference
Without that qualifier, the term is ambiguous in the current product.
## Read next [#read-next]
* [/router/strategy-modes-and-tradeoffs](/router/strategy-modes-and-tradeoffs)
* [/runtime/routing-controls-and-decision-review](/runtime/routing-controls-and-decision-review)
* [/protocol/routing-policy](/protocol/routing-policy)
# Scoring, tie-breaks, and decisions (/router/scoring-tie-breaks-and-decisions)
# Scoring, tie-breaks, and decisions [#scoring-tie-breaks-and-decisions]
Once Router has a clean eligible set, it compares those endpoints across multiple metrics.
## What gets scored [#what-gets-scored]
The current baseline compares eligible endpoints across:
* quality
* latency
* throughput
* cost
* reliability
* preference
Measured evidence is preferred when it exists. Declared and catalog-derived data help fill the rest of the
picture, and neutral defaults prevent unknown metrics from becoming accidental hard penalties.
## What strategy actually changes [#what-strategy-actually-changes]
The strategy does not change which metrics exist. It changes how much each metric matters in the total score.
* `quality` leans hardest on benchmark-backed quality evidence
* `latency` leans hardest on effective latency and throughput
* `cost` leans hardest on observed or catalog cost, especially when budget context exists
* `balanced` keeps the broadest mix across quality, latency, cost, and reliability
For the explicit mode-by-mode guide, read
[/router/strategy-modes-and-tradeoffs](/router/strategy-modes-and-tradeoffs).
## Baseline weight sets [#baseline-weight-sets]
The current reference router uses these baseline weights:
| Strategy | quality | latency | throughput | cost | reliability | preference |
| ---------- | ------: | ------: | ---------: | ---: | ----------: | ---------: |
| `balanced` | 0.30 | 0.20 | 0.10 | 0.20 | 0.15 | 0.05 |
| `quality` | 0.50 | 0.10 | 0.05 | 0.10 | 0.20 | 0.05 |
| `latency` | 0.15 | 0.45 | 0.15 | 0.05 | 0.15 | 0.05 |
| `cost` | 0.15 | 0.10 | 0.05 | 0.50 | 0.15 | 0.05 |
These exact values are current baseline behavior, not a timeless protocol guarantee.
## How evidence sources map into the score [#how-evidence-sources-map-into-the-score]
Operators should read the baseline evidence story like this:
* **benchmark results** primarily improve quality evidence
* **observed latency samples** primarily improve latency scoring
* **observed throughput samples** primarily improve throughput scoring
* **catalog model economics** and observed cost estimates primarily improve cost scoring
* **failure behavior** primarily improves reliability scoring
This is why a benchmark page and a routing decision page are both needed. The benchmark explains why an
endpoint may be strong on quality, while the routing decision explains whether that quality advantage actually
won against latency, cost, reliability, and policy.
## Important metric details [#important-metric-details]
### Quality [#quality]
* uses `judge_score` when present
* otherwise uses `quality_score`
* otherwise falls back to `0.5` and marks the metric unknown
### Latency [#latency]
The baseline derives an effective latency from `p50` and `p95`, then normalizes that value against target
and max latency defaults.
### Throughput [#throughput]
`tokens_per_sec` is normalized logarithmically against a target throughput.
### Cost [#cost]
Cost can be driven by catalog-derived cost estimates or observed cost estimates, and it becomes more
important when budget or cost posture is part of the request.
### Reliability [#reliability]
Reliability uses `1 - failure_rate` when present, otherwise a mildly optimistic default of `0.7`.
### Preference [#preference]
Preference encodes locality and preferred capability matches. It also gets a bonus when an active role
binding exists.
## Unknown-metric redistribution [#unknown-metric-redistribution]
If every eligible candidate has a given metric marked unknown, the router:
1. removes that metric's base weight
2. redistributes the removed weight proportionally across the remaining known metrics
This prevents the score from being anchored to a dimension nobody has evidence for.
## Small bonuses that refine close contests [#small-bonuses-that-refine-close-contests]
On top of weighted metrics, the baseline adds a small `0.01` bonus each for:
* role preferred-capability matches
* task preferred-capability matches
Those bonuses are deliberately small so they refine close contests without overwhelming the main metric mix.
## Near-tie behavior [#near-tie-behavior]
When total scores are effectively tied, the current baseline resolves the order deterministically by:
1. higher quality score
2. lower effective latency
3. higher reliability score
4. stable lexical `endpoint_id`
This keeps the result inspectable and reproducible even when candidates are very close.
## What makes the final decision stable [#what-makes-the-final-decision-stable]
The fallback chain is not a second pass. It is simply the remaining scored candidates after ranking.
A useful `RouterDecision` must say:
* what policy snapshot was applied
* which candidates were rejected and why
* which candidates were scored
* which endpoint won
* why that endpoint won
* whether measured evidence was used
* which scoring version produced the result
## Versioned scoring matters [#versioned-scoring-matters]
The current baseline stamps the decision with `scoring_version: "baseline-v2"`.
That matters because metric formulas, weights, or tie-break logic can evolve over time. A decision artifact
without a scoring version is harder to interpret historically.
## Stable but not frozen [#stable-but-not-frozen]
The protocol requires explainability and stable semantics. It does not require every implementation to use
the same weights forever. Instead, it requires routers to make their choices legible in decision artifacts.
## Read next [#read-next]
* [Fallbacks, failures, and observability](/router/fallbacks-failures-and-observability)
* [How routing works end to end](/router/how-routing-works-end-to-end)
* [Protocol-to-router mapping](/router/protocol-to-router-mapping)
* [Routing policy](/protocol/routing-policy)
# Scoring strategies and tradeoffs (/router/strategy-modes-and-tradeoffs)
# Scoring strategies and tradeoffs [#scoring-strategies-and-tradeoffs]
This page covers the **scoring-strategy** layer of routing:
* `balanced`
* `quality`
* `latency`
* `cost`
If you are looking for runtime routing modes such as `baseline`, `controller`, `difficulty`, or `hybrid`,
or for `local_only` / `remote_only` execution scope, read
[/router/routing-modes-locality-and-execution](/router/routing-modes-locality-and-execution) first.
The saved scoring strategy is the policy mode that changes how Router ranks already-eligible candidates.
It answers this practical question:
> once hard constraints are satisfied, what should the router optimize for?
## What strategy changes and what it does not [#what-strategy-changes-and-what-it-does-not]
Strategy changes the comparison weights used during candidate scoring.
Strategy does **not**:
* override hard eligibility failures
* bring back endpoints excluded by privacy, capability, tool, or budget rules
* replace the need for benchmark or live evidence
That means strategy only matters **after** Router has a clean eligible set.
## The four baseline strategies [#the-four-baseline-strategies]
| Strategy | Primary bias | Best fit | What usually wins | Main risk |
| ---------- | ------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| `balanced` | mixed quality, latency, cost, reliability | general-purpose default routing | the endpoint with the healthiest overall profile | can hide a clearly better quality winner if the spread is large |
| `quality` | benchmarked quality and reliability | high-stakes tasks where answer quality matters most | the highest-quality healthy endpoint | can accept slower or more expensive winners if the quality gap is real |
| `latency` | effective latency and throughput | interactive chat, UX-sensitive flows, fast feedback loops | the fastest healthy endpoint | can favor a quicker but weaker model if quality is only slightly considered |
| `cost` | observed or catalog cost with a reliability floor | background work, high-volume workloads, budget-sensitive paths | the cheapest healthy eligible endpoint | weak cost evidence can make the strategy less decisive than operators expect |
## Current baseline weights [#current-baseline-weights]
The current reference router baseline uses these weight sets:
| Strategy | quality | latency | throughput | cost | reliability | preference |
| ---------- | ------: | ------: | ---------: | ---: | ----------: | ---------: |
| `balanced` | 0.30 | 0.20 | 0.10 | 0.20 | 0.15 | 0.05 |
| `quality` | 0.50 | 0.10 | 0.05 | 0.10 | 0.20 | 0.05 |
| `latency` | 0.15 | 0.45 | 0.15 | 0.05 | 0.15 | 0.05 |
| `cost` | 0.15 | 0.10 | 0.05 | 0.50 | 0.15 | 0.05 |
These exact weights are part of the current reference-router behavior, not a timeless protocol guarantee.
## Which signals feed strategy decisions [#which-signals-feed-strategy-decisions]
Different evidence feeds different scoring dimensions:
* **benchmark and judge output** mainly strengthen the **quality** dimension
* **latency samples** feed the **latency** dimension through effective `p50` and `p95`
* **tokens per second** feed the **throughput** dimension
* **failure behavior** feeds the **reliability** dimension
* **observed or catalog cost estimates** feed the **cost** dimension
* **role locality and preferred-capability matches** feed the **preference** dimension
The key operational implication is that the benchmark does **not** drive every strategy equally.
It matters most for `quality`, still matters for `balanced`, and is only part of the story for `latency` and
`cost`, which also depend heavily on measured execution behavior and budget context.
## How Router actually uses benchmark, latency, and catalog cost [#how-router-actually-uses-benchmark-latency-and-catalog-cost]
The three most important operator-visible evidence sources are not interchangeable.
### Benchmark results [#benchmark-results]
Benchmark results most directly feed the **quality** side of routing.
In practical terms, the benchmark run writes quality-oriented evidence back into endpoint profiles so Router
can later compare candidates using benchmark-backed signals rather than treating every endpoint as an unknown.
This matters most when:
* a `quality` strategy is active
* a `balanced` strategy is trying to decide whether a quality leader deserves to win overall
* a `difficulty` runtime routing mode wants to understand which endpoints are safe for harder requests
### Observed latency [#observed-latency]
Observed latency feeds the **latency** dimension, not the quality dimension.
The current baseline uses measured `p50` and `p95` latency to derive an effective latency score. That means
live or recent observed execution behavior is what makes a `latency` strategy real rather than aspirational.
This matters most when:
* a `latency` strategy is active
* two candidates are otherwise close and speed should separate them
* an operator is checking whether the winning endpoint is actually fast in practice instead of only sounding
fast on paper
### Catalog model cost [#catalog-model-cost]
Catalog economics feed the **cost** dimension, especially when a request budget or cost target is part of the
decision.
The important operator point is that cost routing does not depend only on benchmark scores. It depends on cost
estimates being available and on the request or policy making cost matter.
This matters most when:
* a `cost` strategy is active
* budget enforcement is enabled
* operators want a deterministic cheap-path default even before a large amount of live request cost telemetry
exists
## Evidence precedence in the current baseline [#evidence-precedence-in-the-current-baseline]
The current baseline does not treat every signal equally.
The practical order is:
1. hard eligibility and policy gates narrow the candidate set first
2. benchmark-backed or observed quality evidence strengthens the quality metric
3. observed latency and throughput shape the speed metrics
4. catalog or observed cost shapes the cost metric
5. reliability, locality preference, and preferred-capability matches refine the result
6. near-ties are broken deterministically by quality, then latency, then reliability, then `endpoint_id`
That means a benchmark winner does not automatically win the route, a fast endpoint does not automatically win
the route, and a cheap endpoint does not automatically win the route. The active scoring strategy decides
which of those signals should dominate after eligibility is satisfied.
## What this looks like in a real decision [#what-this-looks-like-in-a-real-decision]
When you inspect a routed decision, read the evidence story in this order:
1. did policy or eligibility remove any candidates before scoring?
2. is the winner benefiting from benchmark-backed quality evidence?
3. is the winner benefiting from lower observed latency?
4. is the winner benefiting from cheaper catalog or observed cost?
5. does that match the saved scoring strategy?
If the answer to step 5 is no, the problem is usually stale or missing evidence, not just a wrong strategy
selection.
## How benchmarks affect each strategy [#how-benchmarks-affect-each-strategy]
### `balanced` [#balanced]
Use `balanced` when the benchmark shows no dramatic quality winner and you want Router to respect latency,
cost, and reliability instead of overcommitting to a single dimension.
### `quality` [#quality]
Use `quality` when the benchmark shows a real quality spread and the best endpoint is worth paying for in
latency or cost.
This is the strategy most directly improved by a strong full benchmark run.
### `latency` [#latency]
Use `latency` when user experience depends on response speed more than absolute output quality.
The benchmark still matters because it helps prevent obviously weak endpoints from looking attractive just
because they are fast, but the decisive signals are effective latency, throughput, and health.
### `cost` [#cost]
Use `cost` when routing spend is part of the product constraint rather than an afterthought.
This strategy becomes much more meaningful when cost estimates are present and budget controls are active.
## Budget, targets, and hard constraints still win first [#budget-targets-and-hard-constraints-still-win-first]
Operators often expect strategy to override policy. It does not.
Before weighted scoring happens, Router can still exclude candidates through:
* required capabilities and modalities
* tool requirements
* locality and privacy rules
* provider and endpoint denies
* budget enforcement
So a `quality` strategy will not rescue an endpoint that violates budget or privacy policy, and a `cost`
strategy will not keep a cheap endpoint alive if it cannot satisfy the request contract.
## How to read a saved strategy in practice [#how-to-read-a-saved-strategy-in-practice]
After saving a strategy, inspect the next routed decision and ask:
* is `policy_snapshot.strategy` the mode I intended to save?
* does the winner reflect the metric mix that mode should prefer?
* did budget, privacy, or capability rules narrow the set before strategy even mattered?
* are benchmark-backed quality signals, latency samples, or cost estimates actually present?
If the answer to the last question is no, the issue is often weak evidence, not a bad strategy choice.
## Read next [#read-next]
* [Choose and save the routing strategy](/get-started/choose-routing-strategy)
* [Routing modes, locality, and execution](/router/routing-modes-locality-and-execution)
* [Scoring, tie-breaks, and decisions](/router/scoring-tie-breaks-and-decisions)
* [Fallbacks, failures, and observability](/router/fallbacks-failures-and-observability)
# Benchmarks and evaluation (/runtime/benchmarks-and-evaluation)
# Benchmarks and evaluation [#benchmarks-and-evaluation]
Benchmarking is the operator bridge between model setup and routing strategy.
## What the benchmark page is for [#what-the-benchmark-page-is-for]
The **Models -> Benchmark** surface is where operators:
* run full or quick benchmark suites
* compare endpoint output quality
* inspect recent run history
* understand how benchmark results feed observed routing profiles
## Why this page matters to Router [#why-this-page-matters-to-router]
Benchmark results are not isolated lab output.
They are written back into the quality evidence that Router can later use for candidate ranking and decision
explainability.
That is why the first full benchmark is part of setup, not just periodic maintenance.
## What benchmark evidence actually affects [#what-benchmark-evidence-actually-affects]
Benchmarking most directly strengthens the **quality** dimension of routing by populating judge-backed or
quality-backed observed profiles.
It does **not** replace the other decision inputs Router uses later:
* observed latency still feeds the latency side of candidate scoring
* catalog model economics and observed cost still feed the cost side of candidate scoring
* reliability and policy still decide whether an endpoint should even stay eligible
It also helps operators see:
* whether latency tradeoffs are real enough to justify a `latency` strategy
* whether cost spread is meaningful enough to justify a `cost` strategy
* whether weak or unstable endpoints should be removed before any strategy choice
That means the benchmark is not the whole routing story, but it is the main evidence source that keeps
strategy selection from turning into guesswork.
## Recommended first-run discipline [#recommended-first-run-discipline]
For a fresh deployment:
1. finish endpoint and role setup
2. run the full benchmark
3. review score spread, health, and latency tradeoffs
4. only then choose and save the routing strategy
## What to watch for [#what-to-watch-for]
Use the first benchmark to find:
* clearly dominant or weak candidates
* unstable endpoints
* surprising local vs remote tradeoffs
* endpoints that should probably not remain in the active routing pool
## Use benchmark output to choose a strategy, not just to admire scores [#use-benchmark-output-to-choose-a-strategy-not-just-to-admire-scores]
After a full run, decide explicitly:
* should the best-quality endpoint win more often, even if it is slower?
* should the fastest healthy endpoint win because UX is sensitive?
* should the cheapest healthy endpoint win because budget is constrained?
* or is the set healthy enough that a balanced tradeoff is the right default?
If operators cannot answer those questions from the benchmark page and Router page together, the strategy is
not yet ready to save.
## Next [#next]
Continue to [Routing controls and decision review](/runtime/routing-controls-and-decision-review).
# Models and role activation (/runtime/models-and-role-activation)
# Models and role activation [#models-and-role-activation]
Role-model only works as well as the active model and role inventory you give it.
## The operator job here [#the-operator-job-here]
Before benchmarking or routing, the operator needs to make four things true:
* the provider or local backend is connected
* the target models or endpoints are actually active
* the intended roles are assigned
* the candidate set reflects real production intent
## Default role assignment [#default-role-assignment]
Newly added or loaded models default to all roles in taxonomy V1. This keeps first-run setup simple: a model
is usable immediately, and operators can remove roles only when they know the model should not compete for
that work.
The UI exposes this as visible checked role controls grouped by taxonomy group, plus an `All roles` control.
Persisted role assignment uses all/include/exclude semantics:
| Mode | Meaning |
| ------- | ---------------------------------------------------------------------------- |
| all | the model can serve every current canonical role and compatible future roles |
| include | the model can serve only the listed enabled role IDs |
| exclude | the model can serve all roles except the listed disabled role IDs |
This all/include/exclude model avoids ambiguity between "default all roles" and "intentionally no roles."
Policy-sensitive roles such as `security`, `legal`, `finance`, `recruiter`, and `health` are labeled so they
can be reviewed deliberately.
## Why role activation comes before benchmarking [#why-role-activation-comes-before-benchmarking]
The benchmark should grade the same role-aware candidate set that Router will later use.
If the role assignments change after the benchmark, your benchmark story and your routing story will drift.
## Useful taxonomy V1 roles [#useful-taxonomy-v1-roles]
Useful first-run checks include:
* `coder` with tasks such as `coder.edit` and `coder.review`
* `security` with tasks such as `security.audit`
* `product` with tasks such as `product.requirements`
* `researcher` with tasks such as `researcher.web_research.current`
* `support` with tasks such as `support.ticket.reply`
Task details are shown after models are configured. The model page should keep add/load flows compact, then
let operators drill into tasks by role when they need to inspect coverage.
## Next [#next]
Continue to [Benchmarks and evaluation](/runtime/benchmarks-and-evaluation).
# Observe and telemetry analytics (/runtime/observe-and-telemetry-analytics)
# Observe and telemetry analytics [#observe-and-telemetry-analytics]
Observe is the runtime surface for understanding what happened after requests were routed.
It is not the primary setup surface. Use Connect, Local, Remote, Models, and Router to configure the runtime;
use Observe to inspect request history, telemetry, and analytics evidence.
## Where analytics appear [#where-analytics-appear]
Telemetry analytics are intentionally limited to runtime overview and Observe surfaces:
| Surface | What it shows |
| ------------------- | --------------------------------------------------------------------- |
| Dashboard | high-level request, routing, latency, cost, and reliability trends |
| Observe -> Requests | request analytics plus the request ledger for the same operator slice |
| Observe -> Routing | routing-specific volume, avoided-cost, and decision trend views |
Setup pages do not own analytics charts.
## Shared filters [#shared-filters]
Observe request charts and the request ledger use the same filter shape where their fields overlap.
Common filters include:
* source
* endpoint
* model
* provider
* role
* operation
* status family
Analytics aggregate the full requested slice. Ledger reads keep explicit pagination or limit behavior. That
means a chart and the visible ledger can describe the same filtered slice while still showing different row
counts.
## Chart states [#chart-states]
Charts should explain their state instead of rendering blank surfaces.
The runtime UI distinguishes:
* `loading`
* `refreshing`
* `empty`
* `unsupported`
* `partial`
* `truncated`
* `error`
* `populated`
For example, a metric can be unsupported for the selected slice, partially populated because some rows lack
the required fields, or validly empty because no matching telemetry exists.
## Backend analytics contract [#backend-analytics-contract]
The runtime analytics response includes:
* the applied query
* slice metadata
* metric support metadata
* dimension support metadata
* row counts for scanned, matched, and aggregated data
* truncation metadata when truncation applies
This keeps the UI from guessing why a chart is empty or incomplete.
## Read next [#read-next]
* [Fallbacks, failures, and observability](/router/fallbacks-failures-and-observability)
* [Trace and usage artifacts](/protocol/trace-and-usage-artifacts)
* [Routing controls and decision review](/runtime/routing-controls-and-decision-review)
# Provider connections (/runtime/provider-connections)
# Provider connections [#provider-connections]
Provider setup is where the runtime learns which local and remote execution paths are available.
This is separate from role assignment, benchmarking, and routing strategy. A provider connection makes an
execution path possible; it does not mean every model from that provider should automatically compete for
every role.
## Local and remote surfaces [#local-and-remote-surfaces]
The runtime UI separates setup into:
* **Local** for local backends, local model inventory, and local endpoint state
* **Remote** for provider accounts, remote connection methods, and remote execution posture
* **Models** for active models, role activation, and benchmark context
Configure the provider or local backend first, then activate only the models or endpoints that should be
eligible for routing.
## OpenAI connection methods [#openai-connection-methods]
The runtime presents one OpenAI provider with multiple connection methods when available:
* `API Key`
* `Codex Subscription`
The API-key path preserves ordinary OpenAI-compatible provider behavior.
The Codex Subscription path is transport-aware. It uses the supported subscription model matrix and the
runtime's OpenAI transport handling for the current GPT 5.3+ subscription path.
For OpenAI-compatible chat-completions requests, the runtime now preserves explicit `tool_choice` controls
when the request asks for ordinary function tools.
When the eligible pool includes a Codex Subscription GPT 5.4 endpoint, tool-bearing or non-text turns can
start by pinning the first attempt there. If that endpoint fails, the runtime can reopen the broader
eligible pool and reroute instead of silently dropping the tool-capable path.
## Hosted tools are transport-specific [#hosted-tools-are-transport-specific]
Hosted-tool support is not one universal flag across every provider.
For example, OpenAI Responses hosted `web_search` support is different from provider-native hosted search on
other transports, and different again from ordinary runtime-executed function tools.
When a request asks for a hosted tool, the runtime narrows eligibility to endpoints that support the exact
requested transport contract. Ordinary chat or generic function-tool requests can still keep a broader
multi-provider candidate pool.
## Current alias family [#current-alias-family]
Use the current runtime routing modes and execution modes described in
[Routing modes, locality, and execution](/router/routing-modes-locality-and-execution).
The legacy `craft-ask` alias family is no longer part of the supported runtime alias surface.
## Read next [#read-next]
* [Models and role activation](/runtime/models-and-role-activation)
* [Routing modes, locality, and execution](/router/routing-modes-locality-and-execution)
* [Downstream OpenAI discovery](/integrations/downstream-openai-discovery)
# Routing controls and decision review (/runtime/routing-controls-and-decision-review)
# Routing controls and decision review [#routing-controls-and-decision-review]
Once the benchmark evidence is in place, Router controls become meaningful.
## What `/app/router/strategy` actually controls [#what-approuterstrategy-actually-controls]
The runtime strategy page is doing more than choosing a single weight preset.
It owns:
* the persisted runtime routing mode such as `baseline`, `controller`, `difficulty`, or `hybrid`
* the execution mode such as `hybrid`, `local_only`, `remote_only`, or `decision_only`
* the saved runtime posture that later requests should inherit
That means operators should stop thinking of this page as only "balanced vs latency vs cost."
## Save strategy after benchmarking [#save-strategy-after-benchmarking]
The operator flow should be:
1. configure the candidate set
2. run the full benchmark
3. review the outcomes
4. save the routing strategy
This keeps strategy selection evidence-based instead of guess-based.
## Where to verify the result [#where-to-verify-the-result]
After saving the strategy, use:
* **Router** to inspect candidates, decisions, fallbacks, and strategy posture
* **Observe** to inspect the request and telemetry trail around live traffic
Read [/router/strategy-modes-and-tradeoffs](/router/strategy-modes-and-tradeoffs) for scoring weights and
[/router/routing-modes-locality-and-execution](/router/routing-modes-locality-and-execution) for runtime
mode plus local/remote execution scope.
## What you want to confirm [#what-you-want-to-confirm]
* the saved strategy is visible in decision context
* the winner is consistent with benchmark quality and policy intent
* fallback order looks sane
* the request trail in Observe supports the Router story
For Codex Subscription-backed GPT 5.4 traffic, also confirm whether the request needed tools or non-text
input. Those turns can intentionally pin the first attempt to the eligible subscription endpoint and only
reopen the wider fallback pool after an execution failure, so the decision and request trail should make that
visible.
## Strategy-specific checks [#strategy-specific-checks]
After saving:
* `balanced`: confirm the winner looks like the healthiest overall choice, not just the fastest or cheapest
* `quality`: confirm benchmark-backed quality actually explains the winner
* `latency`: confirm measured latency and throughput explain the winner without obvious quality collapse
* `cost`: confirm budget and cost evidence explain the winner instead of accidental missing-metric behavior
Also confirm the larger runtime posture:
* if execution mode is `local_only`, no remote endpoint should appear as the real execution winner
* if execution mode is `remote_only`, local candidates should not be the actual execution path
* if routing mode is `difficulty`, request diagnostics should show difficulty classification
* if routing mode is `hybrid`, the final decision should make it possible to understand whether controller
guidance, difficulty signals, or both dominated
## Operational rule of thumb [#operational-rule-of-thumb]
If Router and Observe tell different stories, investigate before tuning weights or swapping models. The first
problem is usually inventory, role activation, endpoint health, or evidence freshness rather than strategy
selection itself.
# Runtime UI tour (/runtime/runtime-ui-tour)
# Runtime UI tour [#runtime-ui-tour]
The runtime UI is the main operator surface for bringing role-model to life on a machine.
## The core sections [#the-core-sections]
The current shell is organized around:
* **Connect** for the first-run entry point into local and remote setup
* **Local** for local backends and local model state
* **Remote** for provider accounts and remote execution posture
* **Models** for benchmark and model-level routing context
* **Router** for candidate, config, and decision views
* **Observe** for request, telemetry, and evidence review
* **System** for runtime and readiness diagnostics
## Who owns what [#who-owns-what]
| Section | Primary responsibility |
| --------- | ------------------------------------------------------- |
| `Connect` | onboarding handoff into local and remote setup paths |
| `Local` | local runtime connectivity and local model inventory |
| `Remote` | provider accounts and remote execution availability |
| `Models` | benchmark workflow and model-facing routing quality |
| `Router` | candidates, strategy context, decisions, and fallbacks |
| `Observe` | request history, telemetry analytics, and investigation |
| `System` | readiness and runtime health context |
## First-time setup path [#first-time-setup-path]
The canonical operator path is:
1. connect local or remote models
2. assign roles
3. run the full benchmark
4. review results
5. choose and save routing strategy
6. validate with a real request
## Read next [#read-next]
* [Models and role activation](/runtime/models-and-role-activation)
* [Benchmarks and evaluation](/runtime/benchmarks-and-evaluation)
* [Observe and telemetry analytics](/runtime/observe-and-telemetry-analytics)
* [Routing controls and decision review](/runtime/routing-controls-and-decision-review)