# role-model

> Public docs for role-model covering install, quickstart, routing concepts, protocol semantics, and reference material.

- [role-model](/): Capability-aware AI routing with a packaged reference runtime, explainable router decisions, and a protocol you can actually inspect.
- Get Started: Install the runtime, connect real models, benchmark them, choose a routing strategy, and inspect the first routed decision.
  - [Install](/get-started/install): Install the packaged role-model router runtime from GitHub Releases, or choose a source build if you are developing the repo.
  - [First launch and connect models](/get-started/first-launch-and-connect-models): Launch the runtime, connect the local or remote models you actually plan to use, and assign their roles before benchmarking.
  - [Run the full benchmark](/get-started/run-full-benchmark): Benchmark the exact endpoint set you plan to route across so role-model can write real quality signals into observed profiles.
  - [Choose and save the routing strategy](/get-started/choose-routing-strategy): Use the benchmark results to select an evidence-based routing strategy instead of guessing up front.
  - [First request and inspect the decision](/get-started/first-request-and-decision): Validate the setup by sending a real routed request and reading the Router and Observe evidence that explains the result.
- Integrations: Connect role-model to downstream clients and OpenAI-compatible consumers.
  - [Pi integration](/integrations/pi): Install the public Pi package, connect it to a running Role-Model runtime, and choose Role-Model aliases from Pi.
  - [Downstream OpenAI discovery](/integrations/downstream-openai-discovery): How Role-Model exposes aliases, capabilities, and conservative limits to Pi and other OpenAI-compatible consumers.
- Runtime: The runtime product surface for configuring endpoints, benchmarking models, saving strategy, and inspecting live routed behavior.
  - [Runtime UI tour](/runtime/runtime-ui-tour): The operator-facing map of the runtime UI and which section owns each part of setup and routing review.
  - [Provider connections](/runtime/provider-connections): Connect local and remote execution paths, understand OpenAI connection methods, and keep provider setup separate from routing strategy.
  - [Models and role activation](/runtime/models-and-role-activation): Configure the actual local or remote models you want to route across, then assign the roles they are allowed to serve.
  - [Benchmarks and evaluation](/runtime/benchmarks-and-evaluation): Use the Models benchmark surface to grade the configured endpoint set and feed routing-quality evidence back into the runtime.
  - [Observe and telemetry analytics](/runtime/observe-and-telemetry-analytics): Read runtime analytics charts, request ledgers, routing telemetry, and explicit chart states without confusing them with setup controls.
  - [Routing controls and decision review](/runtime/routing-controls-and-decision-review): Save the routing strategy after benchmarking, then inspect Router and Observe to verify that live decisions match the evidence.
- Router: The product-facing explanation of how role-model evaluates, ranks, and explains endpoint choices.
  - [Overview](/router/overview): The shortest accurate explanation of how role-model turns a configured endpoint set into an explainable routed choice.
  - [Routing modes, locality, and execution](/router/routing-modes-locality-and-execution): How baseline, controller, difficulty, and hybrid routing modes differ from scoring strategies, and how local, remote, and hybrid execution scope affects what Router can actually do.
  - [Scoring strategies and tradeoffs](/router/strategy-modes-and-tradeoffs): What balanced, quality, latency, and cost scoring strategies do, and how benchmark, latency, reliability, and budget signals affect each one.
  - [Candidate selection and eligibility](/router/candidate-selection-and-eligibility): How candidates enter the router, which hard checks remove them, and why role-aware eligibility always happens before scoring.
  - [Scoring, tie-breaks, and decisions](/router/scoring-tie-breaks-and-decisions): How Router scores eligible endpoints, handles missing evidence, breaks near-ties, and turns ranking into a stable decision artifact.
  - [Fallbacks, failures, and observability](/router/fallbacks-failures-and-observability): How RouterDecision, fallback ordering, no-match outcomes, and observability artifacts fit into one inspectable routing story.
  - [How routing works end to end](/router/how-routing-works-end-to-end): The full reference routing flow from request input to decision and observability output.
  - [Protocol-to-router mapping](/router/protocol-to-router-mapping): Which semantics are canonical in the protocol and which belong to the reference router.
- Concepts: High-level system, protocol, and routing guides for new readers.
  - [How role-model works](/concepts/how-role-model-works): A practical walkthrough of the end-to-end flow from request shape to explainable router decision.
  - [Roles, tasks, and capabilities](/concepts/roles-tasks-and-capabilities): The mental model for how role-model separates worker intent, unit of work, and concrete execution features.
  - [Endpoints and profiles](/concepts/endpoints-and-profiles): Why role-model routes against concrete endpoints and uses both declared and observed profiles to compare them.
  - [Policy and observability](/concepts/policy-and-observability): The two pieces that make role-model more than a model picker: explicit routing policy and inspectable runtime evidence.
  - [Protocol overview](/concepts/protocol-overview): A high-level tour of the protocol objects that let role-model describe requests, endpoints, policy, and explainable routing outcomes.
  - [Routing overview](/concepts/routing-overview): A concise but current summary of how the reference router filters, scores, ties, and explains a decision.
- Reference: Protocol-heavy and schema-heavy material for readers who need the deeper contract details.
  - [Overview](/reference/overview): Where to go when you need the canonical protocol and schema material rather than the product-facing onboarding path.
  - [Canonical schemas reference](/reference/canonical-schemas-reference): Field-level reference coverage for the canonical role-model schemas.
  - [Reason codes and rejection taxonomy](/reference/reason-codes-and-rejection-taxonomy): The stable vocabulary for candidate exclusions and selection explanations.
- Protocol: Canonical protocol objects and field semantics.
  - [Protocol](/protocol): The canonical protocol layer behind role-model: what is standardized, how the object graph fits together, and where to go for field-level semantics.
  - [Endpoint identity](/protocol/endpoint-identity): Why endpoints are the routing unit and how the canonical identity record is structured.
  - [Declared capability profiles](/protocol/declared-capability-profiles): The provider-declared side of endpoint description and what it can and cannot prove.
  - [Observed performance profiles](/protocol/observed-performance-profiles): The measured evidence layer used by routing, ranking, and feedback.
  - [Capability taxonomy](/protocol/capability-taxonomy): The stable compatibility language shared across profiles, roles, tasks, and policy.
  - [Roles and tasks](/protocol/roles-and-tasks): The taxonomy V1 role groups, role IDs, task types, and protocol objects that let role-model separate semantic work from concrete endpoint routing.
  - [Routing policy](/protocol/routing-policy): Policy as a first-class protocol input rather than a hidden router setting.
  - [Router decision artifact](/protocol/router-decision-artifact): The canonical output of routing and what each part of it means.
  - [Trace and usage artifacts](/protocol/trace-and-usage-artifacts): The protocol-owned observability model emitted around routing and execution.