Documentation

OpenSmartRoute routes each request to a model, agent, skill, tool or human and returns the decision with the trace that produced it. It is available as a hosted platform, as a Python package and as a self-hosted service.

This site documents version 1.0.0 (2026-09-07). Release notes

Install (Linux, macOS)bash

curl -LsSf https://opensmartroute.ai/install.sh | sh
osr login

Install (Windows)powershell

powershell -ExecutionPolicy ByPass -c "irm https://opensmartroute.ai/install.ps1 | iex"
osr login

Already have a Python toolchain? uv tool install "opensmartroute[yaml,server]" or pip install "opensmartroute[yaml,server]" work too. osr login opens the browser and stores a workspace API key for this platform; self-hosted routers accept osr login --url http://router:8000 --token ....

Hosted platform

Send requests to the routing API with an API key, or point an OpenAI client at /v1 with model "auto".

Python SDK

Install the package, describe targets in YAML and route in-process. No runtime dependencies.

Self-hosting

Run osr serve as a container or Helm release with the same /route, /feedback and /v1 endpoints.

Get started

What OpenSmartRoute is, how to install it and how to route a first request.

Overview: Installation, quick start, the shape of a decision and where each part of the project lives.
User guide: Targets, rules, plans, providers, execution, learning, the CLI and SKILL.md packages.

Hosted platform

The routing API behind an API key: decisions with trace, the OpenAI-compatible endpoint, plans and quotas.

Platform guide: Authentication, POST /api/v1/route, the OpenAI-compatible endpoint, feedback, plans, tenants, dashboard and errors.
Marketplace: Find, install, buy and publish agents, skills, personas, prompts and stack templates; ratings and the review lifecycle.
Cost estimates and the MCP server: Quote a request before sending it, recommended models per use case, and the MCP server that puts the router in VS Code, Cursor, Claude and any agent.
REST API reference: Each endpoint with parameters, request and response schemas and an example request.

Python SDK

The router as a library: targets, rules, decorators, the enterprise builder and the public API.

SDK guide: Decorators for strategies, rules, signals, middleware and telemetry; settings and plugins.
Enterprise builder: RouterBuilder: auto-learning, health, budgets, tenants, audit, stores and rollout.
Tracing and observability: Spans and events for every routing stage; memory, metrics, log, file and OpenTelemetry sinks; /events, /trace and /metrics.
Benchmarks and leaderboard recipe: Collect the public preference suites, train the routing SLM, evaluate with baselines, robustness and held-out calibration, and publish a reproducible run.
Published benchmark runs: The 0.5.0 run on MT-Bench human, PPE human and WebDev Arena: learned router vs declarative, static task table and baselines, with robustness and held-out calibration.
Python API reference: Every public module, class and function with its signature, generated from the source.

Self-hosting

Run the same router as a service on your own infrastructure.

Deploy with Docker and Helm: The `osr serve` container image, entrypoint environment, Helm chart and health checks.

Concepts

How a request becomes a decision, the mathematics behind each score and the research the modules draw on.

Architecture: How a request becomes a decision: signals, policy, strategies, utility, plans.
Mathematics: The utility function, calibration, IRT, Bradley-Terry, LinUCB and Markov derivations.
Research: Problem statement, literature by family and which module borrows which idea.
Open Capability Manifest: The OCM specification and JSON Schema for describing routable capabilities.

Security

Threat model, hardening and how to report a vulnerability.

Security model: Threat model, guard middleware, PII handling, provenance and the red-team suite.
External review pack: Scope, trust boundaries, the evidence the project produces with reproduction commands, the questions for an independent reviewer and the review log.
Reporting vulnerabilities: Supported versions and how to report a security issue privately.

Agent skills

Agent-Skills packages (SKILL.md) for coding assistants working with OpenSmartRoute. They are also valid routing targets; `osr skills` validates them.

osr-contributing: Work inside the OpenSmartRoute repository itself.
osr-decorator-sdk: Extend OpenSmartRoute in Python with the decorator SDK.
osr-deploy-serve: Run OpenSmartRoute as a service - the `osr serve` FastAPI app and its /route, /feedback, /targets, /stats, /healthz, /whoami and OpenAI-compatible /v1 endpoints, access tokens for the self-hosted server (`serve --token` / `--generate-token` / `--require-auth`, OSR_SERVER_AUTH_TOKENS, `osr token generate`, `osr login --url ...
osr-enterprise-builder: Assemble a production OpenSmartRoute router with RouterBuilder - auto-learning (IRT, Bradley-Terry, LinUCB, Markov), health circuit breakers and budgets, tenant/cache/timeout/guard middleware, logging and metrics telemetry, hash-chained audit, Redis/SQL/encrypted state stores, calibration, retrieval narrowing, shadow/A-B rollout and fair share.
osr-evaluation: Evaluate and benchmark an OpenSmartRoute router - author JSONL evaluation datasets, run `osr eval` with cost/quality frontiers, baselines, robustness, calibration (ECE, Brier, conformal) and ablation reports, load RouterBench-style presets, run off-policy evaluation of logged decisions, and gate CI on minimum accuracy.
osr-integrations: Connect OpenSmartRoute to the outside world - OpenAI-compatible LLM clients and handlers, MCP tool catalogues (stdio client, signed manifests), A2A agent cards, agent harnesses (callable, HTTP, subprocess), LangGraph nodes and conditions, Microsoft Agent Framework executors, OpenAI function-calling tool specs, persona loaders and Agent-Skills SKILL.md packages.
osr-platform: Work on the hosted OpenSmartRoute platform under platform/ - the FastAPI platform API (osr_platform, accounts, API keys, plans, metered /api/v1/route, OpenAI-compatible /v1 proxy, admin, editions, the committed openapi.json snapshot) and the Next.js 16 web app (landing, models catalogue, rankings, playground, pricing, dashboard, route-handler proxies).
osr-routing-catalogue: Define and tune an OpenSmartRoute routing catalogue.
osr-security-hardening: Harden OpenSmartRoute deployments against prompt injection, gadget/steering attacks, PII leakage, runaway agents and untrusted tool arguments - InputGuard and GuardMiddleware, learned gadget detector, PII redaction, ResourceLimits for tools and agents, OriginPolicy for tool-parameter provenance, signed MCP manifests, secret loading and the safety-routing red-team suite.

Releases

What changed in each version, what is planned and how to contribute.

Changelog: Release notes for every version.
Roadmap: What is complete, what is open and the exit criteria for each milestone.
Contributing: Development setup, quality gates, the public API and deprecation policy.