Python SDK quickstart

Five minutes to routing in your own process: install, describe targets, route, constrain, learn from outcomes.

Route between models, agents, skills, tools and humans inside your own process in about five minutes. The core package has zero runtime dependencies; everything here runs offline. The user guide continues where this page stops - real providers, plans, learning, the enterprise builder.

1. Install

pip install opensmartroute                       # library only, zero runtime dependencies
pip install 'opensmartroute[yaml]'               # + YAML catalogues and rules
pip install 'opensmartroute[server]'             # + FastAPI server and OpenAI-compatible proxy

Or install the osr command line together with the package:

curl -LsSf https://opensmartroute.ai/install.sh | sh   # Windows: irm https://opensmartroute.ai/install.ps1 | iex

2. Describe your targets

A target is anything a request can be sent to. Declare what each one is good at, what it costs and how fast it is; the router does the rest.

from opensmartroute import Router, TargetRegistry, RouteTarget, TargetKind, Capabilities, Outcome

registry = TargetRegistry([
    RouteTarget("llm-small", TargetKind.LLM,
                capabilities=Capabilities(max_complexity=0.45),
                cost={"usd_per_1k_tokens": 0.0002}, latency_ms=300, quality_prior=0.55,
                examples=["Hi, how are you?", "What is the capital of France?"]),
    RouteTarget("llm-frontier", TargetKind.LLM,
                capabilities=Capabilities(min_complexity=0.5, domains=["math", "coding"]),
                cost={"usd_per_1k_tokens": 0.015}, latency_ms=2500, quality_prior=0.93,
                examples=["Prove the theorem step by step."]),
    RouteTarget("human", TargetKind.HUMAN,
                capabilities=Capabilities(actions=["escalate"], tags=["safety"]),
                cost={"usd_per_1k_tokens": 0.5}, latency_ms=300_000),
])

Catalogues also load from YAML or JSON files, MCP tools/list payloads, A2A agent cards, SKILL.md and persona directories - see the user guide.

3. Route

router = Router(registry)
d = router.route("Prove that sqrt(2) is irrational, step by step.")
print(d.target.id, f"{d.confidence:.2f}")     # llm-frontier 0.97
print(d.trace.explain())                       # per-strategy scores and rationales

Every decision carries a trace: which signals were extracted, which targets policy rejected and why, how each strategy scored the rest. Nothing is a black box.

4. Constraints and objectives

Hard constraints are filtered before any scoring - they are never traded off against quality. The objective sets the trade-off between quality, cost and latency per request.

from opensmartroute import RouteRequest, RequestConstraints, Objective

req = RouteRequest("Summarize this patient intake note.",
                   constraints=RequestConstraints(region="eu", data_boundary="private", max_cost_per_1k=0.005),
                   objective=Objective(quality=1.0, cost=0.5, latency=0.1, quality_floor=0.6))
d = router.route(req)
print(d.trace.policy_rejections)   # {'llm-frontier': 'cost 0.015 > budget 0.005', ...}

5. Close the loop

Report how the routed answer went and the router's learners (bandits, IRT, Bradley-Terry) shift future decisions toward what actually works for your traffic:

router.learn(Outcome(request_id=d.request_id, target_id=d.target.id, success=True,
                     quality=0.9, cost_usd=0.002, latency_ms=1800, domains=d.trace.signals.domains))

Attach handlers to targets and router.run(req) executes the chosen target or plan and records the outcomes itself - wiring real providers is the user guide's fourth chapter.

6. The same thing from the command line

osr -t examples/targets.yaml -r examples/rules.yaml route "I want a refund for order #123" --plan
osr -t examples/targets.yaml -r examples/rules.yaml eval examples/eval_dataset.jsonl --frontier
osr -t examples/targets.yaml -r examples/rules.yaml serve        # http://127.0.0.1:8000/docs

osr serve exposes the same /route, /feedback and OpenAI-compatible /v1/chat/completions endpoints as the hosted platform - point any OpenAI client at it with model="auto".

Where next

User guide - targets, rules, providers, plans, learning, the CLI, latency numbers.
SDK guide - decorators, settings, error handling, threading, extension points.
Enterprise builder - middleware, telemetry, stores, shadow and A/B rollout.
Deploy with Docker and Helm - run osr serve on your own infrastructure.
Platform quickstart - the hosted version of everything above.