# API reference Every module under `src/opensmartroute` and every public name it exports, generated from the source by `python scripts/api_reference.py` (checked by `tests/test_docs.py`; do not edit by hand). The first line of each docstring is the summary; open the module for the full contract. Narrative documentation: [GUIDE.md](https://opensmartroute.ai/docs/GUIDE.md) (usage), [SDK.md](https://opensmartroute.ai/docs/SDK.md) (stability, extension points), [ARCHITECTURE.md](https://opensmartroute.ai/docs/ARCHITECTURE.md), [MATH.md](https://opensmartroute.ai/docs/MATH.md), [ENTERPRISE.md](https://opensmartroute.ai/docs/ENTERPRISE.md), [SECURITY.md](https://opensmartroute.ai/docs/SECURITY.md), [RESEARCH.md](https://opensmartroute.ai/docs/RESEARCH.md). Stability: names re-exported from `opensmartroute` (the top-level package) are frozen by `tests/public_api.json` and follow SemVer. Sub-module names are public but may change in a minor release with a CHANGELOG entry. ## Modules - [`opensmartroute`](#opensmartroute) - OpenSmartRoute — an open, intelligent route to the right decision, solution, or destination. (69 names) - [`opensmartroute.adapters`](#opensmartrouteadapters) - Adapters connect OpenSmartRoute to real providers and infrastructure. (70 names) - [`opensmartroute.adapters.a2a`](#opensmartrouteadaptersa2a) - Import A2A (Agent-to-Agent protocol) **Agent Cards** as ``TargetKind.AGENT`` targets. (4 names) - [`opensmartroute.adapters.catalogue`](#opensmartrouteadapterscatalogue) - Live model catalogue: collect model cards (price, context, modalities, benchmarks) from public sources. (11 names) - [`opensmartroute.adapters.frameworks`](#opensmartrouteadaptersframeworks) - Drop-in nodes for agent frameworks. (7 names) - [`opensmartroute.adapters.handlers`](#opensmartrouteadaptershandlers) - Executors for non-LLM targets: HTTP endpoints, MCP tools and asynchronous queues. (7 names) - [`opensmartroute.adapters.harness`](#opensmartrouteadaptersharness) - Agent-harness adapters: route to a *runtime*, not just a model. (7 names) - [`opensmartroute.adapters.mcp`](#opensmartrouteadaptersmcp) - Import MCP (Model Context Protocol) tools as ``TargetKind.TOOL`` targets. (11 names) - [`opensmartroute.adapters.mcp_servers`](#opensmartrouteadaptersmcp_servers) - MCP *server* recommendation (MCP-Zero 2506.01056; ToolRet 2603.06467). (3 names) - [`opensmartroute.adapters.openai_compat`](#opensmartrouteadaptersopenai_compat) - OpenAI-compatible HTTP client (stdlib only). (6 names) - [`opensmartroute.adapters.optional`](#opensmartrouteadaptersoptional) - Optional adapters that need extra dependencies. Everything is lazily imported so the. (3 names) - [`opensmartroute.adapters.personas`](#opensmartrouteadapterspersonas) - Import persona catalogues as ``TargetKind.PERSONA`` targets. (4 names) - [`opensmartroute.adapters.semantic_router`](#opensmartrouteadapterssemantic_router) - Import a vLLM *semantic-router* configuration (vllm-project/semantic-router). (3 names) - [`opensmartroute.adapters.skills`](#opensmartrouteadaptersskills) - Load Agent-Skills ``SKILL.md`` packages as ``TargetKind.SKILL`` targets. (4 names) - [`opensmartroute.adapters.websearch`](#opensmartrouteadapterswebsearch) - Web knowledge for the self-improving router: stdlib HTTP fetch, search providers, page text. (14 names) - [`opensmartroute.aio`](#opensmartrouteaio) - Async façade. Routing itself is CPU-bound and sub-millisecond, so we run it in. (1 names) - [`opensmartroute.branding`](#opensmartroutebranding) - OpenSmartRoute naming conventions: one place for every brand-bound identifier. (27 names) - [`opensmartroute.cli`](#opensmartroutecli) - ``osr`` command-line interface. (2 names) - [`opensmartroute.config`](#opensmartrouteconfig) - Configuration loading: targets and rules from JSON or YAML. (3 names) - [`opensmartroute.core`](#opensmartroutecore) - see module (16 names) - [`opensmartroute.core.registry`](#opensmartroutecoreregistry) - Target registry: the catalogue of everything a request may be routed to. (1 names) - [`opensmartroute.core.types`](#opensmartroutecoretypes) - Core data model for OpenSmartRoute. (16 names) - [`opensmartroute.credentials`](#opensmartroutecredentials) - Credentials for the ``osr`` CLI: where the access token lives and how it is obtained. (18 names) - [`opensmartroute.discovery`](#opensmartroutediscovery) - Tool discovery beyond text similarity. (5 names) - [`opensmartroute.enterprise`](#opensmartrouteenterprise) - Enterprise integration layer: ports (hexagonal architecture), middleware and telemetry. (18 names) - [`opensmartroute.enterprise.ops`](#opensmartrouteenterpriseops) - Operational controls: shadow / A-B routing, tenant fairness and queue-aware latency. (7 names) - [`opensmartroute.enterprise.savings`](#opensmartrouteenterprisesavings) - Savings ledger - the always-on savings report that backs the ROI story and the dashboard. (3 names) - [`opensmartroute.enterprise.stores`](#opensmartrouteenterprisestores) - Production state-store backends and wrappers. (7 names) - [`opensmartroute.errors`](#opensmartrouteerrors) - Exception hierarchy. Every error raised by the SDK derives from :class:`OpenSmartRouteError`. (11 names) - [`opensmartroute.estimate`](#opensmartrouteestimate) - Token, cost and latency estimates *before* a request is sent anywhere. (9 names) - [`opensmartroute.eval`](#opensmartrouteeval) - RouterBench-style evaluation harness. (19 names) - [`opensmartroute.eval.agentic`](#opensmartrouteevalagentic) - tau-bench-style agentic task evaluation: does per-step routing beat the best single agent?. (4 names) - [`opensmartroute.eval.audit`](#opensmartrouteevalaudit) - Routing Audit - shadow-mode replay of logged LLM traffic to quantify what the router would change. (6 names) - [`opensmartroute.eval.baselines`](#opensmartrouteevalbaselines) - Baselines every router must beat, plus oracle ceilings and the sampling noise floor. (13 names) - [`opensmartroute.eval.collect`](#opensmartrouteevalcollect) - Collect routing datasets from the Hugging Face Hub, your own feedback log and synthetic seeds. (29 names) - [`opensmartroute.eval.criteria`](#opensmartrouteevalcriteria) - Offline realisations of the ROADMAP exit criteria. (15 names) - [`opensmartroute.eval.datasets`](#opensmartrouteevaldatasets) - Adapters from public routing benchmarks to :class:`EvalRow`. (7 names) - [`opensmartroute.eval.frontier`](#opensmartrouteevalfrontier) - Three-objective frontier and ablations. (3 names) - [`opensmartroute.eval.headroom`](#opensmartrouteevalheadroom) - Routing headroom: when does routing pay, and how much catalogue does it need?. (7 names) - [`opensmartroute.eval.ope`](#opensmartrouteevalope) - Off-policy evaluation from logged routing decisions. (6 names) - [`opensmartroute.eval.robustness`](#opensmartrouteevalrobustness) - Robustness and fairness checks for a router. (6 names) - [`opensmartroute.execution`](#opensmartrouteexecution) - Plan-aware execution: turn a :class:`RouteDecision` into a real answer. (5 names) - [`opensmartroute.feedback`](#opensmartroutefeedback) - Feedback store: append-only outcome log that closes the learning loop. (1 names) - [`opensmartroute.learning`](#opensmartroutelearning) - Auto-learning strategies built on :mod:`opensmartroute.math`. (47 names) - [`opensmartroute.learning.attention`](#opensmartroutelearningattention) - A pure-Python transformer block for the routing SLM's query encoder. (2 names) - [`opensmartroute.learning.autopilot`](#opensmartroutelearningautopilot) - Self-operation: the routing SLM runs its own improvement loop inside the live process. (2 names) - [`opensmartroute.learning.coldstart`](#opensmartroutelearningcoldstart) - Cold start for new targets and self-improving target descriptions. (8 names) - [`opensmartroute.learning.contrastive`](#opensmartroutelearningcontrastive) - Contrastive and reward-distilled router training (RouterDC, NeurIPS 2024; Zooter 2311.08692). (4 names) - [`opensmartroute.learning.credit`](#opensmartroutelearningcredit) - Delayed, task-level credit assignment for agentic trajectories. (2 names) - [`opensmartroute.learning.embed`](#opensmartroutelearningembed) - Pretrained transformer embeddings as frozen features for the routing SLM. (2 names) - [`opensmartroute.learning.handoff`](#opensmartroutelearninghandoff) - Permanent-handoff policy from censored teacher signals (TACIT-Switch 2608.27911). (3 names) - [`opensmartroute.learning.multiturn`](#opensmartroutelearningmultiturn) - Multi-turn routing with history-target joint embeddings (MTRouter 2604.23530). (3 names) - [`opensmartroute.learning.personal`](#opensmartroutelearningpersonal) - Few-shot personalisation (GMTRouter 2511.08590; SkillFeed 2608.28241). (4 names) - [`opensmartroute.learning.policy_gradient`](#opensmartroutelearningpolicy_gradient) - End-to-end policy-gradient routing (Router-R1 2506.09033; RLCascadeRouter 2608.15817). (4 names) - [`opensmartroute.learning.self_improve`](#opensmartroutelearningself_improve) - Self-improvement loop: refresh the catalogue, gather evidence, train a challenger, promote it only if better. (2 names) - [`opensmartroute.learning.slm`](#opensmartroutelearningslm) - The OpenSmartRoute routing SLM: a small, self-contained model that picks the target for a prompt. (5 names) - [`opensmartroute.math`](#opensmartroutemath) - Mathematical toolkit behind OpenSmartRoute's decisions. (46 names) - [`opensmartroute.math.bandits`](#opensmartroutemathbandits) - Multi-armed and contextual bandits for online routing decisions. (8 names) - [`opensmartroute.math.calibration`](#opensmartroutemathcalibration) - Calibration and distribution-free risk control for routing confidence. (6 names) - [`opensmartroute.math.decision`](#opensmartroutemathdecision) - Multi-objective decision helpers and queueing theory for real-time routing. (9 names) - [`opensmartroute.math.dirichlet`](#opensmartroutemathdirichlet) - Dirichlet probe over host hidden states (ProbeDirichlet, RouterXBench 2602.11877). (2 names) - [`opensmartroute.math.energy`](#opensmartroutemathenergy) - Hardware-aware energy characterisation (HW-Router 2608.14575; 2608.28044). (3 names) - [`opensmartroute.math.estimators`](#opensmartroutemathestimators) - Streaming estimators, drift detection and calibration. (11 names) - [`opensmartroute.math.irt`](#opensmartroutemathirt) - Item Response Theory for routing (IRT-Router, ACL 2025). (3 names) - [`opensmartroute.math.markov`](#opensmartroutemathmarkov) - Markov chains and MDPs for conversational / multi-step routing. (2 names) - [`opensmartroute.math.preference`](#opensmartroutemathpreference) - Bradley–Terry pairwise preference model (RouteLLM, Prompt-to-Leaderboard). (2 names) - [`opensmartroute.mcp_server`](#opensmartroutemcp_server) - Model Context Protocol server: the router as a set of tools for any IDE or agent. (8 names) - [`opensmartroute.observability`](#opensmartrouteobservability) - Tracing and observability: every step of routing, execution and learning as a structured event. (18 names) - [`opensmartroute.ocm`](#opensmartrouteocm) - Open Capability Manifest (OCM) - a vendor-neutral description of any routable capability. (12 names) - [`opensmartroute.policy`](#opensmartroutepolicy) - Policy layer: hard constraints that are never traded off against utility. (20 names) - [`opensmartroute.realtime`](#opensmartrouterealtime) - Real-time operational controls: health, circuit breaking, rate & budget limits. (9 names) - [`opensmartroute.retrieval`](#opensmartrouteretrieval) - Retrieval-based candidate narrowing for very large target pools (ToolRet / Skill-RAG). (12 names) - [`opensmartroute.router`](#opensmartrouterouter) - The Router: signals -> policy -> strategies -> ensemble -> decision (+plan). (3 names) - [`opensmartroute.sdk`](#opensmartroutesdk) - OpenSmartRoute SDK: decorator-driven registration of routing components. (16 names) - [`opensmartroute.security`](#opensmartroutesecurity) - Security controls for the routing control plane. (27 names) - [`opensmartroute.security.gadget`](#opensmartroutesecuritygadget) - Learned confounder-gadget detector (Rerouting LLM Routers, Shafran et al. 2025). (6 names) - [`opensmartroute.security.injection`](#opensmartroutesecurityinjection) - Instruction-injection detection for *text that is not the user's request*. (4 names) - [`opensmartroute.security.limits`](#opensmartroutesecuritylimits) - Resource-amplification limits ("Beyond Max Tokens"). (8 names) - [`opensmartroute.security.provenance`](#opensmartroutesecurityprovenance) - Origin (provenance) policy for tool parameters – ROPE-style control-flow integrity. (12 names) - [`opensmartroute.security.safety`](#opensmartroutesecuritysafety) - Safety-routing regression suite ("When Safety Routing Breaks"). (4 names) - [`opensmartroute.server`](#opensmartrouteserver) - Optional FastAPI server exposing the router over HTTP. (14 names) - [`opensmartroute.settings`](#opensmartroutesettings) - Typed, environment-overridable settings: the only home for OpenSmartRoute's tunable constants. (13 names) - [`opensmartroute.signals`](#opensmartroutesignals) - Signal extraction: cheap, deterministic features computed from the request. (44 names) - [`opensmartroute.signals.events`](#opensmartroutesignalsevents) - Event- and workflow-driven signals for agentic inputs. (7 names) - [`opensmartroute.signals.models`](#opensmartroutesignalsmodels) - Learned signal models: hashed n-gram linear models with no dependencies. (7 names) - [`opensmartroute.signals.ontology`](#opensmartroutesignalsontology) - Task ontology: families -> types -> subtypes, with an orthogonal *domain* axis. (4 names) - [`opensmartroute.signals.uncertainty`](#opensmartroutesignalsuncertainty) - Uncertainty signals that come from *outside the query text*. (12 names) - [`opensmartroute.stack`](#opensmartroutestack) - Declarative *stacks*: one document that describes a whole routing setup. (13 names) - [`opensmartroute.strategies`](#opensmartroutestrategies) - see module (66 names) - [`opensmartroute.strategies.aggregate`](#opensmartroutestrategiesaggregate) - Routing / aggregation switch (Mixture-of-Agents, Wang et al. 2024; JiSi 2601.01330). (5 names) - [`opensmartroute.strategies.auction`](#opensmartroutestrategiesauction) - Error-aware reverse auction across providers (EA-RAM 2608.12719). (5 names) - [`opensmartroute.strategies.bandit`](#opensmartroutestrategiesbandit) - Online-learning strategy: contextual Thompson-sampling bandit. (1 names) - [`opensmartroute.strategies.base`](#opensmartroutestrategiesbase) - Strategy interface. (3 names) - [`opensmartroute.strategies.capability`](#opensmartroutestrategiescapability) - Capability-fit strategy: match request signals to a target's declared capabilities. (1 names) - [`opensmartroute.strategies.cascade`](#opensmartroutestrategiescascade) - Cascade execution (FrugalGPT / Router-R1 multi-round / AutoMix POMDP). (5 names) - [`opensmartroute.strategies.defer`](#opensmartroutestrategiesdefer) - Defer-to-human and effort ("think or not") strategies. (3 names) - [`opensmartroute.strategies.edge`](#opensmartroutestrategiesedge) - Edge-cloud token-aware routing (Pro-Router 2608.28726; RelayLLM 2601.05167). (1 names) - [`opensmartroute.strategies.elastic`](#opensmartroutestrategieselastic) - Token-budget-aware routing to elastic / many-in-one models (Nemotron Elastic 2511.16664; Star 2605.07182). (3 names) - [`opensmartroute.strategies.escalation`](#opensmartroutestrategiesescalation) - Bayesian self-escalation during generation (2608.24087). (5 names) - [`opensmartroute.strategies.human`](#opensmartroutestrategieshuman) - Routing among human annotators and experts (QUORUM 2608.27974; Dawid-Skene 1979). (5 names) - [`opensmartroute.strategies.llm_judge`](#opensmartroutestrategiesllm_judge) - Generative routing: let an LLM act as the router (Router-R1 / LLM-as-judge). (2 names) - [`opensmartroute.strategies.memory`](#opensmartroutestrategiesmemory) - Memory-tier routing for agents (BudgetMem 2602.06025; Gated-Memory Routing 2609.00237). (5 names) - [`opensmartroute.strategies.modality`](#opensmartroutestrategiesmodality) - Multimodal routing and modality escalation (LatentRouter 2605.11301; modality escalation. (4 names) - [`opensmartroute.strategies.probe`](#opensmartroutestrategiesprobe) - Hidden-state routing with a Dirichlet probe (ProbeDirichlet, RouterXBench 2602.11877). (2 names) - [`opensmartroute.strategies.progress`](#opensmartroutestrategiesprogress) - Agentic trajectories: per-step routing and multi-round execution. (5 names) - [`opensmartroute.strategies.protocol`](#opensmartroutestrategiesprotocol) - Collaboration-protocol selection (2608.14927). (7 names) - [`opensmartroute.strategies.rules`](#opensmartroutestrategiesrules) - Declarative rule-based routing (Arch-Router-style domain/action preferences). (2 names) - [`opensmartroute.strategies.semantic_cache`](#opensmartroutestrategiessemantic_cache) - Semantic caching as a routing target (GPTCache; vLLM semantic router 2603.04444). (4 names) - [`opensmartroute.strategies.session`](#opensmartroutestrategiessession) - Session affinity: keep a conversation with the target that is already serving it. (2 names) - [`opensmartroute.strategies.similarity`](#opensmartroutestrategiessimilarity) - Similarity-based routing (UniRoute / GraphRouter flavour). (3 names) - [`opensmartroute.strategies.speculative`](#opensmartroutestrategiesspeculative) - Speculative (draft-based) cascades (speculative cascades, Narasimhan et al. 2024; Differential. (3 names) - [`opensmartroute.strategies.task_table`](#opensmartroutestrategiestask_table) - Static task table strategy (SCX Router, 2609.02292). (1 names) ## `opensmartroute` Source: src/opensmartroute/__init__.py (`src/opensmartroute/__init__.py`) OpenSmartRoute — an open, intelligent route to the right decision, solution, or destination. | Name | Kind | Summary | |---|---|---| | `AsyncRouter` | re-export of [`opensmartroute.aio.AsyncRouter`](#opensmartrouteaio) | ``await``-able wrapper around a :class:`Router`: route / learn / execute / run off the event loop. | | `BanditStrategy` | re-export of [`opensmartroute.strategies.bandit.BanditStrategy`](#opensmartroutestrategiesbandit) | Thompson-sampling Beta bandit per (context, target); context = dominant domain (+ plan role). | | `Capabilities` | re-export of [`opensmartroute.core.types.Capabilities`](#opensmartroutecoretypes) | Declarative description of what a target is good at. | | `CapabilityStrategy` | re-export of [`opensmartroute.strategies.capability.CapabilityStrategy`](#opensmartroutestrategiescapability) | Declarative fit: domain / action overlap, complexity band, language, modality and quality prior. | | `Cascade` | re-export of [`opensmartroute.strategies.cascade.Cascade`](#opensmartroutestrategiescascade) | Execute ranked targets in planner order (cheapest / MDP / POMDP), stopping when the quality gate passes. | | `CascadePlanner` | re-export of [`opensmartroute.strategies.cascade.CascadePlanner`](#opensmartroutestrategiescascade) | Finite-horizon MDP over an ordered cascade with a stop action after each step. | | `ComponentRegistry` | re-export of [`opensmartroute.sdk.ComponentRegistry`](#opensmartroutesdk) | Blueprints for every routing component, with decorators that register into it. | | `ConfigurationError` | re-export of [`opensmartroute.errors.ConfigurationError`](#opensmartrouteerrors) | Invalid catalogue, rules, SKILL.md, settings or a missing optional dependency. | | `DeferStrategy` | re-export of [`opensmartroute.strategies.defer.DeferStrategy`](#opensmartroutestrategiesdefer) | Learning-to-defer: scores human targets by risk, PII, escalation intent, frustration and model uncertainty. | | `EffortStrategy` | re-export of [`opensmartroute.strategies.defer.EffortStrategy`](#opensmartroutestrategiesdefer) | Match a target's reasoning ``effort_level`` to ``signals.reasoning_need``; penalise over- and under-thinking. | | `Event` | re-export of [`opensmartroute.observability.Event`](#opensmartrouteobservability) | One captured span or event: flat, JSON-friendly, never carries request text. | | `EventSink` | re-export of [`opensmartroute.observability.EventSink`](#opensmartrouteobservability) | Receiver port: override :meth:`emit`; live bridges may also implement :meth:`span_start` / :meth:`span_end`. | | `ExecutionError` | re-export of [`opensmartroute.errors.ExecutionError`](#opensmartrouteerrors) | A target handler failed while executing a plan. | | `ExecutionResult` | re-export of [`opensmartroute.execution.ExecutionResult`](#opensmartrouteexecution) | What happened when a decision was executed. | | `ExecutionStep` | re-export of [`opensmartroute.execution.ExecutionStep`](#opensmartrouteexecution) | One executed plan slot: role, target, latency and whether it succeeded. | | `FeedbackStore` | re-export of [`opensmartroute.feedback.FeedbackStore`](#opensmartroutefeedback) | Append-only :class:`Outcome` log (in memory or JSONL file) with per-target statistics. | | `LLMJudgeStrategy` | re-export of [`opensmartroute.strategies.llm_judge.LLMJudgeStrategy`](#opensmartroutestrategiesllm_judge) | LLM-as-router with optional **score calibration**. | | `NoRouteError` | re-export of [`opensmartroute.errors.NoRouteError`](#opensmartrouteerrors) | No target satisfied the hard constraints. | | `Objective` | re-export of [`opensmartroute.core.types.Objective`](#opensmartroutecoretypes) | What the caller wants to optimise. Weights are relative. | | `OpenSmartRouteError` | re-export of [`opensmartroute.errors.OpenSmartRouteError`](#opensmartrouteerrors) | Base class for all SDK errors. | | `Outcome` | re-export of [`opensmartroute.core.types.Outcome`](#opensmartroutecoretypes) | Feedback about how a routed request actually went. | | `PlanSlot` | re-export of [`opensmartroute.core.types.PlanSlot`](#opensmartroutecoretypes) | One filled slot of a multi-target plan (persona -> skill -> model). | | `Policy` | re-export of [`opensmartroute.policy.Policy`](#opensmartroutepolicy) | Ordered chain of :data:`PolicyRule`; returns the first rejection reason or ``None``. | | `ProgressRouter` | re-export of [`opensmartroute.strategies.progress.ProgressRouter`](#opensmartroutestrategiesprogress) | Route each step of a task with trajectory context. | | `RankedTarget` | re-export of [`opensmartroute.core.types.RankedTarget`](#opensmartroutecoretypes) | A scored candidate: utility, ensemble quality estimate and the per-strategy breakdown. | | `RequestConstraints` | re-export of [`opensmartroute.core.types.RequestConstraints`](#opensmartroutecoretypes) | Hard constraints on the request (never traded off). | | `RouteDecision` | re-export of [`opensmartroute.core.types.RouteDecision`](#opensmartroutecoretypes) | The answer to ``route()``: chosen target, confidence, alternatives, optional plan, trace and propensities. | | `RoutePlan` | re-export of [`opensmartroute.core.types.RoutePlan`](#opensmartroutecoretypes) | A composed route (MasRouter-style): several targets working together. | | `RouteRequest` | re-export of [`opensmartroute.core.types.RouteRequest`](#opensmartroutecoretypes) | The customer need. | | `RouteTarget` | re-export of [`opensmartroute.core.types.RouteTarget`](#opensmartroutecoretypes) | A routable destination: an LLM, agent, skill, persona, tool, workflow or human. | | `RouteTrace` | re-export of [`opensmartroute.core.types.RouteTrace`](#opensmartroutecoretypes) | Everything needed to explain a decision. | | `Router` | re-export of [`opensmartroute.router.Router`](#opensmartrouterouter) | Signals -> policy -> strategies -> ensemble -> decision (+ optional plan). | | `RouterSLM` | re-export of [`opensmartroute.learning.slm.RouterSLM`](#opensmartroutelearningslm) | Small routing model: dual encoder + target catalogue snapshot + calibration, in one JSON file. | | `Rule` | re-export of [`opensmartroute.strategies.rules.Rule`](#opensmartroutestrategiesrules) | If all `when` conditions match, boost `prefer` targets and penalise `avoid`. | | `RulesStrategy` | re-export of [`opensmartroute.strategies.rules.RulesStrategy`](#opensmartroutestrategiesrules) | Applies declarative :class:`Rule` preferences (prefer / avoid / pin) when their ``when`` conditions match. | | `SLMStrategy` | re-export of [`opensmartroute.learning.slm.SLMStrategy`](#opensmartroutelearningslm) | Ensemble member backed by a :class:`RouterSLM`; scores are its probabilities, and it keeps learning online. | | `SecurityError` | re-export of [`opensmartroute.errors.SecurityError`](#opensmartrouteerrors) | Request rejected by an input guard (prompt injection, oversize, etc.). | | `SelfImprover` | re-export of [`opensmartroute.learning.self_improve.SelfImprover`](#opensmartroutelearningself_improve) | Closed loop that keeps a :class:`RouterSLM` current with the model market and its own traffic. | | `Settings` | re-export of [`opensmartroute.settings.Settings`](#opensmartroutesettings) | All tunables, grouped by consumer. Immutable; derive variants with :meth:`replace`. | | `Signals` | re-export of [`opensmartroute.core.types.Signals`](#opensmartroutecoretypes) | Cheap deterministic features extracted from a request. | | `SimilarityStrategy` | re-export of [`opensmartroute.strategies.similarity.SimilarityStrategy`](#opensmartroutestrategiessimilarity) | Embed the request and each target's examples / description; score by best and top-k mean similarity. | | `Span` | re-export of [`opensmartroute.observability.Span`](#opensmartrouteobservability) | An open unit of work; a context manager that records duration, status and nested events. | | `StateStoreError` | re-export of [`opensmartroute.errors.StateStoreError`](#opensmartrouteerrors) | A learner-state store failed to load, save or migrate. | | `Strategy` | re-export of [`opensmartroute.strategies.base.Strategy`](#opensmartroutestrategiesbase) | Scores each candidate target in [0, 1] and explains why. | | `StrategyScore` | re-export of [`opensmartroute.core.types.StrategyScore`](#opensmartroutecoretypes) | One strategy's opinion about one target. | | `TargetConstraints` | re-export of [`opensmartroute.core.types.TargetConstraints`](#opensmartroutecoretypes) | Where / for whom a target may be used. Checked by the policy layer. | | `TargetKind` | re-export of [`opensmartroute.core.types.TargetKind`](#opensmartroutecoretypes) | Kinds of things a request can be routed to. | | `TargetRegistry` | re-export of [`opensmartroute.core.registry.TargetRegistry`](#opensmartroutecoreregistry) | In-memory catalogue of :class:`RouteTarget` by id: add / upsert / remove, filtered listing, (de)serialisation. | | `TargetUnavailableError` | re-export of [`opensmartroute.errors.TargetUnavailableError`](#opensmartrouteerrors) | A remote target or catalogue source could not be reached. | | `TaskTableStrategy` | re-export of [`opensmartroute.strategies.task_table.TaskTableStrategy`](#opensmartroutestrategiestask_table) | Static ``task_type -> target -> quality`` table with family and prior fallbacks; learns from outcomes. | | `Tracer` | re-export of [`opensmartroute.observability.Tracer`](#opensmartrouteobservability) | Opens spans, records events and fans them out to sinks; ``sample_rate`` < 1 traces a share of requests. | | `ValidationError` | re-export of [`opensmartroute.errors.ValidationError`](#opensmartrouteerrors) | A request, outcome or target failed validation. | | `__version__` | constant | | | `agent` | re-export of [`opensmartroute.sdk.agent`](#opensmartroutesdk) | @agent(id, ...): shorthand for an ``agent`` target. | | `components` | re-export of [`opensmartroute.sdk.components`](#opensmartroutesdk) | : The process-wide registry that the top-level decorators (``opensmartroute.strategy`` ...) bind to. | | `configure` | re-export of [`opensmartroute.settings.configure`](#opensmartroutesettings) | Install process-wide settings. ``configure()`` with no arguments re-reads the environment;. | | `configure_tracing` | re-export of [`opensmartroute.observability.configure_tracing`](#opensmartrouteobservability) | Install sinks on the process-wide tracer. With no sinks, use the ones named by settings. | | `get_settings` | re-export of [`opensmartroute.settings.get_settings`](#opensmartroutesettings) | The process-wide :class:`Settings` (environment overlay applied once, lazily). | | `get_tracer` | re-export of [`opensmartroute.observability.get_tracer`](#opensmartrouteobservability) | The process-wide tracer (disabled until :func:`configure_tracing` adds sinks). | | `load_rules` | re-export of [`opensmartroute.config.load_rules`](#opensmartrouteconfig) | Load a rules file (top-level list or ``rules:`` key) into a :class:`RulesStrategy`. | | `load_targets` | re-export of [`opensmartroute.config.load_targets`](#opensmartrouteconfig) | Load a catalogue file (top-level list or ``targets:`` key) into a :class:`TargetRegistry`. | | `middleware` | re-export of [`opensmartroute.sdk.middleware`](#opensmartroutesdk) | @middleware: register a Middleware class or ``fn(request, next_route)``. | | `policy_rule` | re-export of [`opensmartroute.sdk.policy_rule`](#opensmartroutesdk) | @policy_rule: register ``fn(target, request, signals) -> reason \| None``. | | `signal` | re-export of [`opensmartroute.sdk.signal`](#opensmartroutesdk) | @signal: register a SignalExtractor class or ``fn(request, signals) -> mapping``. | | `skill` | re-export of [`opensmartroute.sdk.skill`](#opensmartroutesdk) | @skill(id, ...): shorthand for a ``skill`` target. | | `strategy` | re-export of [`opensmartroute.sdk.strategy`](#opensmartroutesdk) | @strategy(weight=, name=): register a Strategy class or ``fn(request, signals, candidates)``. | | `target` | re-export of [`opensmartroute.sdk.target`](#opensmartroutesdk) | @target(id, kind, ...): the decorated callable becomes a RouteTarget handler. | | `telemetry` | re-export of [`opensmartroute.sdk.telemetry`](#opensmartroutesdk) | @telemetry: register a Telemetry sink class or factory. | | `tool` | re-export of [`opensmartroute.sdk.tool`](#opensmartroutesdk) | @tool(id, ...): shorthand for a ``tool`` target. | ## `opensmartroute.adapters` Source: src/opensmartroute/adapters/__init__.py (`src/opensmartroute/adapters/__init__.py`) Adapters connect OpenSmartRoute to real providers and infrastructure. | Name | Kind | Summary | |---|---|---| | `AgentHarness` | re-export of [`opensmartroute.adapters.harness.AgentHarness`](#opensmartrouteadaptersharness) | Structural interface of an agent runtime: ``run(task, context=, history=) -> HarnessResult``. | | `CallableHarness` | re-export of [`opensmartroute.adapters.harness.CallableHarness`](#opensmartrouteadaptersharness) | Wrap an in-process agent: ``fn(task, context, history) -> str \| dict \| HarnessResult``. | | `ChatResult` | re-export of [`opensmartroute.adapters.openai_compat.ChatResult`](#opensmartrouteadaptersopenai_compat) | Result of a chat completion: text, model, token counts, latency and the raw response. | | `HTTPHarness` | re-export of [`opensmartroute.adapters.harness.HTTPHarness`](#opensmartrouteadaptersharness) | POST the task as JSON to an agent endpoint. | | `HarnessResult` | re-export of [`opensmartroute.adapters.harness.HarnessResult`](#opensmartrouteadaptersharness) | What an agent harness returns: text, success, token / cost / latency usage and optional self-graded quality. | | `InMemoryQueue` | re-export of [`opensmartroute.adapters.handlers.InMemoryQueue`](#opensmartrouteadaptershandlers) | Reference :class:`Queue`: FIFO in memory, resolves into :class:`~opensmartroute.Outcome`. | | `ModelCard` | re-export of [`opensmartroute.adapters.catalogue.ModelCard`](#opensmartrouteadapterscatalogue) | What the catalogue knows about one model: identity, price, limits, evidence of quality, provenance. | | `ModelCatalogue` | re-export of [`opensmartroute.adapters.catalogue.ModelCatalogue`](#opensmartrouteadapterscatalogue) | Merged, persisted model cards from every source; the SLM's view of the target universe. | | `OpenAICompatClient` | re-export of [`opensmartroute.adapters.openai_compat.OpenAICompatClient`](#opensmartrouteadaptersopenai_compat) | Stdlib-only client for the OpenAI chat / embeddings API (OpenAI, Azure, vLLM, Ollama, LiteLLM) with retries. | | `OpenTelemetrySink` | re-export of [`opensmartroute.adapters.optional.OpenTelemetrySink`](#opensmartrouteadaptersoptional) | Live bridge from the tracer to OpenTelemetry: every OpenSmartRoute span becomes an OTel span. | | `OpenTelemetryTelemetry` | re-export of [`opensmartroute.adapters.optional.OpenTelemetryTelemetry`](#opensmartrouteadaptersoptional) | Emits one span per decision and counters/histograms via the OTel API. | | `PendingResult` | re-export of [`opensmartroute.adapters.handlers.PendingResult`](#opensmartrouteadaptershandlers) | Immediate answer of a queued target: the request was accepted and will be answered later. | | `Queue` | re-export of [`opensmartroute.adapters.handlers.Queue`](#opensmartrouteadaptershandlers) | Structural interface of an asynchronous queue target (ticketing, human tier, workflow run). | | `QueuedItem` | re-export of [`opensmartroute.adapters.handlers.QueuedItem`](#opensmartrouteadaptershandlers) | One request waiting in (or resolved from) a queue. | | `SearchHit` | re-export of [`opensmartroute.adapters.websearch.SearchHit`](#opensmartrouteadapterswebsearch) | One search result: where it came from, what it says, and when it was seen. | | `SemanticRouterImport` | re-export of [`opensmartroute.adapters.semantic_router.SemanticRouterImport`](#opensmartrouteadapterssemantic_router) | Result of importing a vLLM semantic-router config: registry, rules, default model, categories, warnings. | | `ServerCard` | re-export of [`opensmartroute.adapters.mcp_servers.ServerCard`](#opensmartrouteadaptersmcp_servers) | Description of an MCP server (tools, tags, auth, latency, cost, region, data boundary) for recommendation. | | `ServerRecommendation` | re-export of [`opensmartroute.adapters.mcp_servers.ServerRecommendation`](#opensmartrouteadaptersmcp_servers) | A ranked server from ``recommend_servers`` with its fused score, rationale and matched tool names. | | `StdioMCPClient` | re-export of [`opensmartroute.adapters.mcp.StdioMCPClient`](#opensmartrouteadaptersmcp) | Tiny JSON-RPC-over-stdio MCP client (newline-delimited). Thread-safe, blocking. | | `SubprocessHarness` | re-export of [`opensmartroute.adapters.harness.SubprocessHarness`](#opensmartrouteadaptersharness) | Run a CLI agent: task on stdin, answer on stdout, exit code 0 = success. | | `WebKnowledge` | re-export of [`opensmartroute.adapters.websearch.WebKnowledge`](#opensmartrouteadapterswebsearch) | Fan a query out to search providers, de-duplicate by URL and cache the hits as JSON. | | `a2a_handler` | re-export of [`opensmartroute.adapters.a2a.a2a_handler`](#opensmartrouteadaptersa2a) | Return a handler that sends the request text to an A2A agent and returns its text. | | `agent_from_card` | re-export of [`opensmartroute.adapters.a2a.agent_from_card`](#opensmartrouteadaptersa2a) | Build an ``agent`` RouteTarget from an A2A agent card (name, skills, tags, input modes). | | `brave_search` | re-export of [`opensmartroute.adapters.websearch.brave_search`](#opensmartrouteadapterswebsearch) | Brave Search API web results; the key is read from ``BRAVE_API_KEY`` (or ``BRAVE_API_KEY_FILE``). | | `card_to_target` | re-export of [`opensmartroute.adapters.catalogue.card_to_target`](#opensmartrouteadapterscatalogue) | A :class:`RouteTarget` for a model card; risky third-party descriptions are replaced by the name. | | `attach_chat_handlers` | re-export of [`opensmartroute.adapters.openai_compat.attach_chat_handlers`](#opensmartrouteadaptersopenai_compat) | Give every LLM target a :func:`chat_handler` on ``client``; returns the ids that got one. | | `chat_handler` | re-export of [`opensmartroute.adapters.openai_compat.chat_handler`](#opensmartrouteadaptersopenai_compat) | Adapter for ``RouteTarget.handler``: turns a RouteRequest into a chat call. | | `connect_mcp` | re-export of [`opensmartroute.adapters.mcp.connect_mcp`](#opensmartrouteadaptersmcp) | Spawn a stdio MCP server, list its tools and return ``(client, targets)``. | | `duckduckgo_search` | re-export of [`opensmartroute.adapters.websearch.duckduckgo_search`](#opensmartrouteadapterswebsearch) | DuckDuckGo instant-answer API (abstract + related topics). Keyless; shallow but good for definitions. | | `embedder` | re-export of [`opensmartroute.adapters.openai_compat.embedder`](#opensmartrouteadaptersopenai_compat) | Adapter for ``SimilarityStrategy(embedder=...)``. | | `enrich_description` | re-export of [`opensmartroute.adapters.mcp.enrich_description`](#opensmartrouteadaptersmcp) | Return ``(routing_description, examples, capabilities)`` for a tool. | | `fetch_agent_card` | re-export of [`opensmartroute.adapters.a2a.fetch_agent_card`](#opensmartrouteadaptersa2a) | Download an agent card over HTTPS (plain HTTP is refused); raises TargetUnavailableError on failure. | | `fetch_bytes` | re-export of [`opensmartroute.adapters.websearch.fetch_bytes`](#opensmartrouteadapterswebsearch) | GET ``url`` over https with a timeout and a body cap; transport errors become ``TargetUnavailableError``. | | `fetch_huggingface_models` | re-export of [`opensmartroute.adapters.catalogue.fetch_huggingface_models`](#opensmartrouteadapterscatalogue) | Model cards from the Hugging Face Hub search (downloads, likes, tags, ``model-index`` benchmarks). | | `fetch_json` | re-export of [`opensmartroute.adapters.websearch.fetch_json`](#opensmartrouteadapterswebsearch) | GET a JSON document (see :func:`fetch_bytes`); malformed bodies raise ``TargetUnavailableError``. | | `fetch_leaderboard_quality` | re-export of [`opensmartroute.adapters.catalogue.fetch_leaderboard_quality`](#opensmartrouteadapterscatalogue) | ``{hub model id: {benchmark: accuracy}}`` from the Open LLM Leaderboard table (official rows, unflagged). | | `fetch_openrouter_models` | re-export of [`opensmartroute.adapters.catalogue.fetch_openrouter_models`](#opensmartrouteadapterscatalogue) | Model cards from OpenRouter's public listing (prices per token, context, modalities, tool support). | | `fetch_page_text` | re-export of [`opensmartroute.adapters.websearch.fetch_page_text`](#opensmartrouteadapterswebsearch) | Fetch a page and return ``{url, title, text, risk}``; ``risk`` is the injection/gadget risk of the text. | | `harness_handler` | re-export of [`opensmartroute.adapters.harness.harness_handler`](#opensmartrouteadaptersharness) | Adapter for ``RouteTarget.handler``: a RouteRequest becomes a harness task. | | `html_to_text` | re-export of [`opensmartroute.adapters.websearch.html_to_text`](#opensmartrouteadapterswebsearch) | ``(title, text)`` of an HTML document with scripts/styles removed and whitespace collapsed. | | `http_handler` | re-export of [`opensmartroute.adapters.handlers.http_handler`](#opensmartrouteadaptershandlers) | ``RouteTarget.handler`` that POSTs the request to ``url`` and returns a :class:`HarnessResult`. | | `huggingface_search` | re-export of [`opensmartroute.adapters.websearch.huggingface_search`](#opensmartrouteadapterswebsearch) | Search the Hugging Face Hub (``what`` = ``models`` or ``datasets``), ranked by downloads. No key needed. | | `judge_fn` | re-export of [`opensmartroute.adapters.openai_compat.judge_fn`](#opensmartrouteadaptersopenai_compat) | Adapter for ``LLMJudgeStrategy(llm=...)``: prompt in, completion text out. | | `langgraph_condition` | re-export of [`opensmartroute.adapters.frameworks.langgraph_condition`](#opensmartrouteadaptersframeworks) | Edge selector for ``add_conditional_edges``: routes on target id (``by='target'``) or kind. | | `langgraph_node` | re-export of [`opensmartroute.adapters.frameworks.langgraph_node`](#opensmartrouteadaptersframeworks) | Return a LangGraph-compatible node ``state -> dict`` (partial state update). | | `load_personas` | re-export of [`opensmartroute.adapters.personas.load_personas`](#opensmartrouteadapterspersonas) | Load personas from a directory of markdown files or a JSON/JSONL/CSV catalogue. | | `load_semantic_router_config` | re-export of [`opensmartroute.adapters.semantic_router.load_semantic_router_config`](#opensmartrouteadapterssemantic_router) | Convert a vLLM semantic-router ``model_config`` / ``categories`` document into targets and rules. | | `load_skill` | re-export of [`opensmartroute.adapters.skills.load_skill`](#opensmartrouteadaptersskills) | Load one skill directory (must contain ``SKILL.md``). | | `load_skills` | re-export of [`opensmartroute.adapters.skills.load_skills`](#opensmartrouteadaptersskills) | Load every ``*/SKILL.md`` under ``root`` (one level deep, sorted by name). | | `maf_router_executor` | re-export of [`opensmartroute.adapters.frameworks.maf_router_executor`](#opensmartrouteadaptersframeworks) | Agent Framework style: ``executor(message, ctx) -> target id \| response``; ``handoffs`` maps. | | `manifest_from_targets` | re-export of [`opensmartroute.adapters.mcp.manifest_from_targets`](#opensmartrouteadaptersmcp) | Reverse: dump MCP-shaped tool dicts (for signing / publishing a catalogue). | | `model_key` | re-export of [`opensmartroute.adapters.catalogue.model_key`](#opensmartrouteadapterscatalogue) | Vendor-agnostic key for matching model names across sources: lowercase, no vendor prefix, no punctuation. | | `mcp_tool_handler` | re-export of [`opensmartroute.adapters.handlers.mcp_tool_handler`](#opensmartrouteadaptershandlers) | ``RouteTarget.handler`` that invokes one MCP tool via ``call(name, arguments)``. | | `openai_tool_handler` | re-export of [`opensmartroute.adapters.frameworks.openai_tool_handler`](#opensmartrouteadaptersframeworks) | Callable behind ``openai_tool_spec``: ``(text, objective?, kinds?) -> RouteDecision.to_dict()``. | | `openai_tool_spec` | re-export of [`opensmartroute.adapters.frameworks.openai_tool_spec`](#opensmartrouteadaptersframeworks) | OpenAI function-calling tool definition that lets a model ask the router for a target. | | `persona_from_markdown` | re-export of [`opensmartroute.adapters.personas.persona_from_markdown`](#opensmartrouteadapterspersonas) | Parse a ``*.agent.md`` / ``*.chatmode.md`` / front-matter markdown file into a persona target. | | `persona_target` | re-export of [`opensmartroute.adapters.personas.persona_target`](#opensmartrouteadapterspersonas) | Build a ``persona`` RouteTarget whose ``instructions`` is the system prompt (non-primary by default). | | `personas_from_records` | re-export of [`opensmartroute.adapters.personas.personas_from_records`](#opensmartrouteadapterspersonas) | Persona targets from JSON / CSV-style records (``name`` + ``prompt``/``system`` keys); others skipped. | | `quality_from_benchmarks` | re-export of [`opensmartroute.adapters.catalogue.quality_from_benchmarks`](#opensmartrouteadapterscatalogue) | Mean of normalised benchmark scores (percentages are divided by 100); None when there are none. | | `quality_from_popularity` | re-export of [`opensmartroute.adapters.catalogue.quality_from_popularity`](#opensmartrouteadapterscatalogue) | Weak prior in [0.35, 0.75] from log-scaled downloads and likes (popularity is not quality; it is a hint). | | `queue_handler` | re-export of [`opensmartroute.adapters.handlers.queue_handler`](#opensmartrouteadaptershandlers) | ``RouteTarget.handler`` that enqueues the request and returns a :class:`PendingResult`. | | `recommend_servers` | re-export of [`opensmartroute.adapters.mcp_servers.recommend_servers`](#opensmartrouteadaptersmcp_servers) | Rank MCP servers for a task; constraint violations are excluded, not down-weighted. | | `route_and_execute` | re-export of [`opensmartroute.adapters.frameworks.route_and_execute`](#opensmartrouteadaptersframeworks) | Route ``text`` and optionally execute the plan; returns ``(decision, ExecutionResult \| None)``. | | `sentence_transformers_embedder` | re-export of [`opensmartroute.adapters.optional.sentence_transformers_embedder`](#opensmartrouteadaptersoptional) | Semantic embedder for ``SimilarityStrategy``. Requires ``opensmartroute[embeddings]``. | | `sign_manifest` | re-export of [`opensmartroute.adapters.mcp.sign_manifest`](#opensmartrouteadaptersmcp) | Wrap a tool list in a signed manifest. ``algorithm`` = ``hmac-sha256`` (key = shared. | | `skill_from_markdown` | re-export of [`opensmartroute.adapters.skills.skill_from_markdown`](#opensmartrouteadaptersskills) | Parse one SKILL.md (Agent-Skills front matter + body) into a ``skill`` RouteTarget; strict validation. | | `skills_from_card` | re-export of [`opensmartroute.adapters.a2a.skills_from_card`](#opensmartrouteadaptersa2a) | One non-primary ``skill`` target per skill declared on an A2A agent card (``/``). | | `tools_from_manifest` | re-export of [`opensmartroute.adapters.mcp.tools_from_manifest`](#opensmartrouteadaptersmcp) | Import tools from a (signed) manifest; ``kw`` goes to :func:`tools_from_mcp`. | | `tools_from_mcp` | re-export of [`opensmartroute.adapters.mcp.tools_from_mcp`](#opensmartrouteadaptersmcp) | Convert ``tools/list`` output into targets. ``call(name, arguments)`` becomes the handler. | | `verify_manifest` | re-export of [`opensmartroute.adapters.mcp.verify_manifest`](#opensmartrouteadaptersmcp) | Constant-time verification. ``key`` = shared secret (HMAC) or 32-byte Ed25519 public key. | ## `opensmartroute.adapters.a2a` Source: src/opensmartroute/adapters/a2a.py (`src/opensmartroute/adapters/a2a.py`) Import A2A (Agent-to-Agent protocol) **Agent Cards** as ``TargetKind.AGENT`` targets. | Name | Kind | Summary | |---|---|---| | `a2a_handler` | function `(url: str, token: str \| None=None, timeout_s: float=60.0, method: str='message/send')` | Return a handler that sends the request text to an A2A agent and returns its text. | | `agent_from_card` | function `(card: dict[str, Any], *, call: Callable[[str, RouteRequest], Any] \| None=None, cost_per_1k_tokens: float=0.0, latency_ms: float=2000.0, quality_prior: float=0.65, languages: list[str] \| None=None)` | Build an ``agent`` RouteTarget from an A2A agent card (name, skills, tags, input modes). | | `fetch_agent_card` | function `(base_url: str, timeout_s: float=10.0, path: str='/.well-known/agent.json')` | Download an agent card over HTTPS (plain HTTP is refused); raises TargetUnavailableError on failure. | | `skills_from_card` | function `(card: dict[str, Any], agent_id: str \| None=None)` | One non-primary ``skill`` target per skill declared on an A2A agent card (``/``). | ## `opensmartroute.adapters.catalogue` Source: src/opensmartroute/adapters/catalogue.py (`src/opensmartroute/adapters/catalogue.py`) Live model catalogue: collect model cards (price, context, modalities, benchmarks) from public sources. | Name | Kind | Summary | |---|---|---| | `LEADERBOARD_DATASET` | constant | Open LLM Leaderboard v2 results table on the Hub. | | `OPENROUTER_MODELS` | constant | public model + pricing listing (no key). | | `ModelCard` | class | What the catalogue knows about one model: identity, price, limits, evidence of quality, provenance. | | `ModelCatalogue` | class | Merged, persisted model cards from every source; the SLM's view of the target universe. | | `card_to_target` | function `(card: ModelCard, *, default_latency_ms: float=1500.0, settings: Settings \| None=None)` | A :class:`RouteTarget` for a model card; risky third-party descriptions are replaced by the name. | | `fetch_huggingface_models` | function `(query: str='', *, limit: int=50, pipeline: str='text-generation', timeout_s: float \| None=None, settings: Settings \| None=None)` | Model cards from the Hugging Face Hub search (downloads, likes, tags, ``model-index`` benchmarks). | | `fetch_leaderboard_quality` | function `(*, limit: int=5000, dataset: str=LEADERBOARD_DATASET, timeout_s: float \| None=None, settings: Settings \| None=None)` | ``{hub model id: {benchmark: accuracy}}`` from the Open LLM Leaderboard table (official rows, unflagged). | | `fetch_openrouter_models` | function `(*, url: str=OPENROUTER_MODELS, timeout_s: float \| None=None, settings: Settings \| None=None)` | Model cards from OpenRouter's public listing (prices per token, context, modalities, tool support). | | `model_key` | function `(model_id: str)` | Vendor-agnostic key for matching model names across sources: lowercase, no vendor prefix, no punctuation. | | `quality_from_benchmarks` | function `(benchmarks: dict[str, float])` | Mean of normalised benchmark scores (percentages are divided by 100); None when there are none. | | `quality_from_popularity` | function `(downloads: int, likes: int)` | Weak prior in [0.35, 0.75] from log-scaled downloads and likes (popularity is not quality; it is a hint). | ## `opensmartroute.adapters.frameworks` Source: src/opensmartroute/adapters/frameworks.py (`src/opensmartroute/adapters/frameworks.py`) Drop-in nodes for agent frameworks. | Name | Kind | Summary | |---|---|---| | `langgraph_condition` | function `(by: str='target', default: str='__end__')` | Edge selector for ``add_conditional_edges``: routes on target id (``by='target'``) or kind. | | `langgraph_node` | function `(router: Router, *, execute: bool=False, plan: bool=False, context_key: str='route_context', on_no_route: str='__no_route__')` | Return a LangGraph-compatible node ``state -> dict`` (partial state update). | | `last_user_text` | function `(state: dict[str, Any])` | (last user utterance, prior history as role/content dicts). | | `maf_router_executor` | function `(router: Router, *, execute: bool=False)` | Agent Framework style: ``executor(message, ctx) -> target id \| response``; ``handoffs`` maps. | | `openai_tool_handler` | function `(router: Router)` | Callable behind ``openai_tool_spec``: ``(text, objective?, kinds?) -> RouteDecision.to_dict()``. | | `openai_tool_spec` | function `(name: str='route_request')` | OpenAI function-calling tool definition that lets a model ask the router for a target. | | `route_and_execute` | function `(router: Router, text: str, *, history: list[dict[str, str]] \| None=None, context: dict[str, Any] \| None=None, objective: Objective \| None=None, execute: bool=False, plan: bool=False, learn: bool=True)` | Route ``text`` and optionally execute the plan; returns ``(decision, ExecutionResult \| None)``. | ## `opensmartroute.adapters.handlers` Source: src/opensmartroute/adapters/handlers.py (`src/opensmartroute/adapters/handlers.py`) Executors for non-LLM targets: HTTP endpoints, MCP tools and asynchronous queues. | Name | Kind | Summary | |---|---|---| | `InMemoryQueue` | class | Reference :class:`Queue`: FIFO in memory, resolves into :class:`~opensmartroute.Outcome`. | | `PendingResult` | class | Immediate answer of a queued target: the request was accepted and will be answered later. | | `Queue` | class | Structural interface of an asynchronous queue target (ticketing, human tier, workflow run). | | `QueuedItem` | class | One request waiting in (or resolved from) a queue. | | `http_handler` | function `(url: str, *, api_key: str \| None=None, api_key_env: str \| None=None, timeout_s: float=300.0, headers: Mapping[str, str] \| None=None, payload: Callable[[str, Mapping[str, Any], list[dict[str, str]]], dict[str, Any]] \| None=None, body: Mapping[str, Any] \| None=None)` | ``RouteTarget.handler`` that POSTs the request to ``url`` and returns a :class:`HarnessResult`. | | `mcp_tool_handler` | function `(call: Callable[[str, dict[str, Any]], Any], tool: str, input_schema: dict[str, Any] \| None=None, arguments: Callable[[RouteRequest], dict[str, Any]] \| None=None)` | ``RouteTarget.handler`` that invokes one MCP tool via ``call(name, arguments)``. | | `queue_handler` | function `(queue: Queue, target_id: str \| None=None)` | ``RouteTarget.handler`` that enqueues the request and returns a :class:`PendingResult`. | ## `opensmartroute.adapters.harness` Source: src/opensmartroute/adapters/harness.py (`src/opensmartroute/adapters/harness.py`) Agent-harness adapters: route to a *runtime*, not just a model. | Name | Kind | Summary | |---|---|---| | `AgentHarness` | class | Structural interface of an agent runtime: ``run(task, context=, history=) -> HarnessResult``. | | `CallableHarness` | class | Wrap an in-process agent: ``fn(task, context, history) -> str \| dict \| HarnessResult``. | | `HTTPHarness` | class | POST the task as JSON to an agent endpoint. | | `HarnessResult` | class | What an agent harness returns: text, success, token / cost / latency usage and optional self-graded quality. | | `SubprocessHarness` | class | Run a CLI agent: task on stdin, answer on stdout, exit code 0 = success. | | `coerce_result` | function `(out: Any)` | Normalise ``str \| dict \| HarnessResult \| object-with-text`` into a HarnessResult. | | `harness_handler` | function `(harness: AgentHarness)` | Adapter for ``RouteTarget.handler``: a RouteRequest becomes a harness task. | ## `opensmartroute.adapters.mcp` Source: src/opensmartroute/adapters/mcp.py (`src/opensmartroute/adapters/mcp.py`) Import MCP (Model Context Protocol) tools as ``TargetKind.TOOL`` targets. | Name | Kind | Summary | |---|---|---| | `MCPTool` | class | A tool as listed by an MCP server: name, description, JSON input schema and annotations. | | `StdioMCPClient` | class | Tiny JSON-RPC-over-stdio MCP client (newline-delimited). Thread-safe, blocking. | | `canonical_json` | function `(obj: Any)` | Deterministic JSON encoding (sorted keys, no whitespace) used for manifest digests and signatures. | | `connect_mcp` | function `(command: list[str], server: str='', **kw: Any)` | Spawn a stdio MCP server, list its tools and return ``(client, targets)``. | | `enrich_description` | function `(name: str, description: str, input_schema: dict[str, Any] \| None, server: str='', enricher: Callable[[str], list[str]] \| None=None)` | Return ``(routing_description, examples, capabilities)`` for a tool. | | `manifest_digest` | function `(tools: list[dict[str, Any]])` | SHA-256 hex digest of a tool list in canonical JSON. | | `manifest_from_targets` | function `(targets: Iterable[RouteTarget])` | Reverse: dump MCP-shaped tool dicts (for signing / publishing a catalogue). | | `sign_manifest` | function `(tools: list[dict[str, Any]], key: bytes, *, server: str='', algorithm: str='hmac-sha256', key_id: str='')` | Wrap a tool list in a signed manifest. ``algorithm`` = ``hmac-sha256`` (key = shared. | | `tools_from_manifest` | function `(manifest: dict[str, Any], key: bytes \| None, *, require_signature: bool=True, max_age_s: float \| None=None, **kw: Any)` | Import tools from a (signed) manifest; ``kw`` goes to :func:`tools_from_mcp`. | | `tools_from_mcp` | function `(payload: Any, server: str='', call: Callable[[str, dict[str, Any]], Any] \| None=None, enricher: Callable[[str], list[str]] \| None=None, cost_per_call_usd: float=0.0, latency_ms: float=300.0, quality_prior: float=0.6, max_description_risk: float=0.6, guard: InputGuard \| None=None)` | Convert ``tools/list`` output into targets. ``call(name, arguments)`` becomes the handler. | | `verify_manifest` | function `(manifest: dict[str, Any], key: bytes, max_age_s: float \| None=None)` | Constant-time verification. ``key`` = shared secret (HMAC) or 32-byte Ed25519 public key. | ## `opensmartroute.adapters.mcp_servers` Source: src/opensmartroute/adapters/mcp_servers.py (`src/opensmartroute/adapters/mcp_servers.py`) MCP *server* recommendation (MCP-Zero 2506.01056; ToolRet 2603.06467). | Name | Kind | Summary | |---|---|---| | `ServerCard` | class | Description of an MCP server (tools, tags, auth, latency, cost, region, data boundary) for recommendation. | | `ServerRecommendation` | class | A ranked server from ``recommend_servers`` with its fused score, rationale and matched tool names. | | `recommend_servers` | function `(request: RouteRequest \| str, servers: Iterable[ServerCard \| dict[str, Any]], k: int=3, constraints: RequestConstraints \| None=None, allowed_auth: Iterable[str] \| None=None, min_score: float=0.0)` | Rank MCP servers for a task; constraint violations are excluded, not down-weighted. | ## `opensmartroute.adapters.openai_compat` Source: src/opensmartroute/adapters/openai_compat.py (`src/opensmartroute/adapters/openai_compat.py`) OpenAI-compatible HTTP client (stdlib only). | Name | Kind | Summary | |---|---|---| | `ChatResult` | class | Result of a chat completion: text, model, token counts, latency and the raw response. | | `OpenAICompatClient` | class | Stdlib-only client for the OpenAI chat / embeddings API (OpenAI, Azure, vLLM, Ollama, LiteLLM) with retries. | | `attach_chat_handlers` | function `(targets: Iterable[Any], client: OpenAICompatClient, *, model_key: str='model', default_model: str \| None=None, overwrite: bool=False)` | Give every LLM target a :func:`chat_handler` on ``client``; returns the ids that got one. | | `chat_handler` | function `(client: OpenAICompatClient, model: str, system_prompt: str \| None=None, **defaults: Any)` | Adapter for ``RouteTarget.handler``: turns a RouteRequest into a chat call. | | `embedder` | function `(client: OpenAICompatClient, model: str, batch: int=64)` | Adapter for ``SimilarityStrategy(embedder=...)``. | | `judge_fn` | function `(client: OpenAICompatClient, model: str, max_tokens: int=400)` | Adapter for ``LLMJudgeStrategy(llm=...)``: prompt in, completion text out. | ## `opensmartroute.adapters.optional` Source: src/opensmartroute/adapters/optional.py (`src/opensmartroute/adapters/optional.py`) Optional adapters that need extra dependencies. Everything is lazily imported so the. | Name | Kind | Summary | |---|---|---| | `OpenTelemetrySink` | class | Live bridge from the tracer to OpenTelemetry: every OpenSmartRoute span becomes an OTel span. | | `OpenTelemetryTelemetry` | class | Emits one span per decision and counters/histograms via the OTel API. | | `sentence_transformers_embedder` | function `(model_name: str='sentence-transformers/all-MiniLM-L6-v2', device: str \| None=None, normalize: bool=True)` | Semantic embedder for ``SimilarityStrategy``. Requires ``opensmartroute[embeddings]``. | ## `opensmartroute.adapters.personas` Source: src/opensmartroute/adapters/personas.py (`src/opensmartroute/adapters/personas.py`) Import persona catalogues as ``TargetKind.PERSONA`` targets. | Name | Kind | Summary | |---|---|---| | `load_personas` | function `(path: str \| Path, **kw: Any)` | Load personas from a directory of markdown files or a JSON/JSONL/CSV catalogue. | | `persona_from_markdown` | function `(text: str, *, path: Path \| None=None, **kw: Any)` | Parse a ``*.agent.md`` / ``*.chatmode.md`` / front-matter markdown file into a persona target. | | `persona_target` | function `(name: str, prompt: str, description: str='', *, id_prefix: str='persona:', domains: list[str] \| None=None, tags: list[str] \| None=None, languages: list[str] \| None=None, primary: bool=False, quality_prior: float=0.6, source: str='', extra: dict[str, Any] \| None=None)` | Build a ``persona`` RouteTarget whose ``instructions`` is the system prompt (non-primary by default). | | `personas_from_records` | function `(records: Iterable[dict[str, Any]], **kw: Any)` | Persona targets from JSON / CSV-style records (``name`` + ``prompt``/``system`` keys); others skipped. | ## `opensmartroute.adapters.semantic_router` Source: src/opensmartroute/adapters/semantic_router.py (`src/opensmartroute/adapters/semantic_router.py`) Import a vLLM *semantic-router* configuration (vllm-project/semantic-router). | Name | Kind | Summary | |---|---|---| | `DEFAULT_DOMAIN_MAP` | constant | semantic-router's MMLU-style categories -> OpenSmartRoute ontology domains. | | `SemanticRouterImport` | class | Result of importing a vLLM semantic-router config: registry, rules, default model, categories, warnings. | | `load_semantic_router_config` | function `(source: str \| Path \| dict[str, Any], domain_map: dict[str, list[str]] \| None=None, rule_weight: float=0.8)` | Convert a vLLM semantic-router ``model_config`` / ``categories`` document into targets and rules. | ## `opensmartroute.adapters.skills` Source: src/opensmartroute/adapters/skills.py (`src/opensmartroute/adapters/skills.py`) Load Agent-Skills ``SKILL.md`` packages as ``TargetKind.SKILL`` targets. | Name | Kind | Summary | |---|---|---| | `load_skill` | function `(skill_dir: str \| Path, **kw: Any)` | Load one skill directory (must contain ``SKILL.md``). | | `load_skills` | function `(root: str \| Path, **kw: Any)` | Load every ``*/SKILL.md`` under ``root`` (one level deep, sorted by name). | | `parse_frontmatter` | function `(text: str)` | Split ``---`` frontmatter from the body. Returns ``(frontmatter, body)``. | | `skill_from_markdown` | function `(text: str, *, path: Path \| None=None, cost_per_1k_tokens: float=0.0)` | Parse one SKILL.md (Agent-Skills front matter + body) into a ``skill`` RouteTarget; strict validation. | ## `opensmartroute.adapters.websearch` Source: src/opensmartroute/adapters/websearch.py (`src/opensmartroute/adapters/websearch.py`) Web knowledge for the self-improving router: stdlib HTTP fetch, search providers, page text. | Name | Kind | Summary | |---|---|---| | `BRAVE_API` | constant | Brave web search (needs BRAVE_API_KEY). | | `DATASETS_SERVER` | constant | Hugging Face datasets-server REST root (/rows). | | `DDG_API` | constant | DuckDuckGo instant-answer JSON endpoint (no key). | | `HF_API` | constant | Hugging Face Hub REST root (models, datasets, search). | | `SearchHit` | class | One search result: where it came from, what it says, and when it was seen. | | `SearchProvider` | constant | (query, limit) -> hits. | | `WebKnowledge` | class | Fan a query out to search providers, de-duplicate by URL and cache the hits as JSON. | | `brave_search` | function `(query: str, limit: int=10, *, api_key_env: str='BRAVE_API_KEY', timeout_s: float \| None=None, settings: Settings \| None=None)` | Brave Search API web results; the key is read from ``BRAVE_API_KEY`` (or ``BRAVE_API_KEY_FILE``). | | `duckduckgo_search` | function `(query: str, limit: int=10, *, timeout_s: float \| None=None, settings: Settings \| None=None)` | DuckDuckGo instant-answer API (abstract + related topics). Keyless; shallow but good for definitions. | | `fetch_bytes` | function `(url: str, *, timeout_s: float \| None=None, max_bytes: int \| None=None, headers: Mapping[str, str] \| None=None, settings: Settings \| None=None)` | GET ``url`` over https with a timeout and a body cap; transport errors become ``TargetUnavailableError``. | | `fetch_json` | function `(url: str, *, timeout_s: float \| None=None, headers: Mapping[str, str] \| None=None, settings: Settings \| None=None)` | GET a JSON document (see :func:`fetch_bytes`); malformed bodies raise ``TargetUnavailableError``. | | `fetch_page_text` | function `(url: str, *, max_chars: int=20000, timeout_s: float \| None=None, settings: Settings \| None=None)` | Fetch a page and return ``{url, title, text, risk}``; ``risk`` is the injection/gadget risk of the text. | | `html_to_text` | function `(html: str)` | ``(title, text)`` of an HTML document with scripts/styles removed and whitespace collapsed. | | `huggingface_search` | function `(query: str, limit: int=10, *, what: str='models', pipeline_tag: str \| None='text-generation', timeout_s: float \| None=None, settings: Settings \| None=None)` | Search the Hugging Face Hub (``what`` = ``models`` or ``datasets``), ranked by downloads. No key needed. | ## `opensmartroute.aio` Source: src/opensmartroute/aio.py (`src/opensmartroute/aio.py`) Async façade. Routing itself is CPU-bound and sub-millisecond, so we run it in. | Name | Kind | Summary | |---|---|---| | `AsyncRouter` | class | ``await``-able wrapper around a :class:`Router`: route / learn / execute / run off the event loop. | ## `opensmartroute.branding` Source: src/opensmartroute/branding.py (`src/opensmartroute/branding.py`) OpenSmartRoute naming conventions: one place for every brand-bound identifier. | Name | Kind | Summary | |---|---|---| | `API_KEY_ENV` | constant | ``OSR_API_KEY`` - access token the CLI sends (overrides the credentials file). | | `API_URL_ENV` | constant | ``OSR_API_URL`` - platform / server URL the CLI talks to. | | `BRAND` | constant | product name, one word. | | `CLI` | constant | console script name. | | `CONFIG_DIR_ENV` | constant | ``OSR_CONFIG_DIR`` - overrides the per-user config folder. | | `CONFIG_DIR_NAME` | constant | per-user config folder name (``~/.config/opensmartroute``, ``%APPDATA%\opensmartroute``). | | `ENTRY_POINT_GROUP` | constant | importlib.metadata entry-point group for plugins. | | `ENV_PREFIX` | constant | ``OSR_`` - every settings environment variable starts with this. | | `ERROR_CODE_PREFIX` | constant | ``OSR_`` - machine-readable error codes (``OSR_NO_ROUTE``). | | `INSTALL_SCRIPT_PS1` | constant | Windows installer: ``irm .../install.ps1 \| iex``. | | `INSTALL_SCRIPT_SH` | constant | Linux / macOS installer: ``curl -fsSL .../install.sh \| sh``. | | `LOCAL_TOKEN_PREFIX` | constant | self-hosted ``osr serve`` access tokens (``osr_local_...``). | | `METADATA_PREFIX` | constant | ``osr-`` - SKILL.md / persona front-matter keys (``osr-domains``). | | `PACKAGE` | constant | Python package / distribution / logger root. | | `REPOSITORY` | constant | source repository (installer fallback URLs). | | `SHORT_NAME` | constant | short form used for env-var and error-code prefixes. | | `SKILLS_DIR` | constant | : Default Agent-Skills root (``*/SKILL.md``); the location Claude Code discovers project skills in. | | `STATE_DIR` | constant | default learner-state directory. | | `TOKEN_PREFIX` | constant | hosted-platform API keys (``osr_live_...``). | | `WEBSITE` | constant | public website; also the default hosted-platform URL of ``osr login``. | | `env_key` | function `(*parts: str)` | ``env_key("routing", "softmax_temperature") -> "OSR_ROUTING_SOFTMAX_TEMPERATURE"``. | | `error_code` | function `(kind: str)` | ``error_code("no_route") -> "OSR_NO_ROUTE"``. | | `logger` | function `(component: str \| None=None)` | ``logger() -> "opensmartroute"``; ``logger("enterprise") -> "opensmartroute.enterprise"``. | | `metadata_key` | function `(field: str)` | ``metadata_key("quality_prior") -> "osr-quality-prior"`` (SKILL.md / persona frontmatter). | | `platform_url` | function `(environ: Mapping[str, str] \| None=None)` | The platform / server URL the CLI talks to: ``OSR_API_URL`` or the hosted platform (:data:`WEBSITE`). | | `user_agent` | function `()` | ``"opensmartroute/"`` for outbound HTTP clients. | | `version` | function `()` | The package version (``opensmartroute.__version__``), resolved at call time. | ## `opensmartroute.cli` Source: src/opensmartroute/cli.py (`src/opensmartroute/cli.py`) ``osr`` command-line interface. | Name | Kind | Summary | |---|---|---| | `build_router` | function `(targets: str, rules: str \| None=None, state: str \| None=None, models: str \| None=None, skills: str \| None=None, slm: str \| None=None, remember_requests: int=0)` | Assemble the CLI's router from targets / rules / state / models / SKILL.md / SLM paths (every command). | | `main` | function `(argv: list[str] \| None=None)` | Entry point of the ``osr`` console script; returns the process exit status. | ## `opensmartroute.config` Source: src/opensmartroute/config.py (`src/opensmartroute/config.py`) Configuration loading: targets and rules from JSON or YAML. | Name | Kind | Summary | |---|---|---| | `load_document` | function `(path: str \| Path)` | Read a JSON or YAML file (YAML needs the ``yaml`` extra); raises ConfigurationError on any problem. | | `load_rules` | function `(path: str \| Path)` | Load a rules file (top-level list or ``rules:`` key) into a :class:`RulesStrategy`. | | `load_targets` | function `(path: str \| Path)` | Load a catalogue file (top-level list or ``targets:`` key) into a :class:`TargetRegistry`. | ## `opensmartroute.core` Source: src/opensmartroute/core/__init__.py (`src/opensmartroute/core/__init__.py`) | Name | Kind | Summary | |---|---|---| | `Capabilities` | re-export of [`opensmartroute.core.types.Capabilities`](#opensmartroutecoretypes) | Declarative description of what a target is good at. | | `Objective` | re-export of [`opensmartroute.core.types.Objective`](#opensmartroutecoretypes) | What the caller wants to optimise. Weights are relative. | | `Outcome` | re-export of [`opensmartroute.core.types.Outcome`](#opensmartroutecoretypes) | Feedback about how a routed request actually went. | | `PlanSlot` | re-export of [`opensmartroute.core.types.PlanSlot`](#opensmartroutecoretypes) | One filled slot of a multi-target plan (persona -> skill -> model). | | `RankedTarget` | re-export of [`opensmartroute.core.types.RankedTarget`](#opensmartroutecoretypes) | A scored candidate: utility, ensemble quality estimate and the per-strategy breakdown. | | `RequestConstraints` | re-export of [`opensmartroute.core.types.RequestConstraints`](#opensmartroutecoretypes) | Hard constraints on the request (never traded off). | | `RouteDecision` | re-export of [`opensmartroute.core.types.RouteDecision`](#opensmartroutecoretypes) | The answer to ``route()``: chosen target, confidence, alternatives, optional plan, trace and propensities. | | `RoutePlan` | re-export of [`opensmartroute.core.types.RoutePlan`](#opensmartroutecoretypes) | A composed route (MasRouter-style): several targets working together. | | `RouteRequest` | re-export of [`opensmartroute.core.types.RouteRequest`](#opensmartroutecoretypes) | The customer need. | | `RouteTarget` | re-export of [`opensmartroute.core.types.RouteTarget`](#opensmartroutecoretypes) | A routable destination: an LLM, agent, skill, persona, tool, workflow or human. | | `RouteTrace` | re-export of [`opensmartroute.core.types.RouteTrace`](#opensmartroutecoretypes) | Everything needed to explain a decision. | | `Signals` | re-export of [`opensmartroute.core.types.Signals`](#opensmartroutecoretypes) | Cheap deterministic features extracted from a request. | | `StrategyScore` | re-export of [`opensmartroute.core.types.StrategyScore`](#opensmartroutecoretypes) | One strategy's opinion about one target. | | `TargetConstraints` | re-export of [`opensmartroute.core.types.TargetConstraints`](#opensmartroutecoretypes) | Where / for whom a target may be used. Checked by the policy layer. | | `TargetKind` | re-export of [`opensmartroute.core.types.TargetKind`](#opensmartroutecoretypes) | Kinds of things a request can be routed to. | | `TargetRegistry` | re-export of [`opensmartroute.core.registry.TargetRegistry`](#opensmartroutecoreregistry) | In-memory catalogue of :class:`RouteTarget` by id: add / upsert / remove, filtered listing, (de)serialisation. | ## `opensmartroute.core.registry` Source: src/opensmartroute/core/registry.py (`src/opensmartroute/core/registry.py`) Target registry: the catalogue of everything a request may be routed to. | Name | Kind | Summary | |---|---|---| | `TargetRegistry` | class | In-memory catalogue of :class:`RouteTarget` by id: add / upsert / remove, filtered listing, (de)serialisation. | ## `opensmartroute.core.types` Source: src/opensmartroute/core/types.py (`src/opensmartroute/core/types.py`) Core data model for OpenSmartRoute. | Name | Kind | Summary | |---|---|---| | `TargetKind` | class | Kinds of things a request can be routed to. | | `Capabilities` | class | Declarative description of what a target is good at. | | `TargetConstraints` | class | Where / for whom a target may be used. Checked by the policy layer. | | `RouteTarget` | class | A routable destination: an LLM, agent, skill, persona, tool, workflow or human. | | `EFFORT_LEVELS` | constant | Named reasoning-effort levels -> numeric effort in [0, 1] (``RouteTarget.effort``). | | `Objective` | class | What the caller wants to optimise. Weights are relative. | | `RequestConstraints` | class | Hard constraints on the request (never traded off). | | `RouteRequest` | class | The customer need. | | `Signals` | class | Cheap deterministic features extracted from a request. | | `StrategyScore` | class | One strategy's opinion about one target. | | `RankedTarget` | class | A scored candidate: utility, ensemble quality estimate and the per-strategy breakdown. | | `RouteTrace` | class | Everything needed to explain a decision. | | `PlanSlot` | class | One filled slot of a multi-target plan (persona -> skill -> model). | | `RoutePlan` | class | A composed route (MasRouter-style): several targets working together. | | `RouteDecision` | class | The answer to ``route()``: chosen target, confidence, alternatives, optional plan, trace and propensities. | | `Outcome` | class | Feedback about how a routed request actually went. | ## `opensmartroute.credentials` Source: src/opensmartroute/credentials.py (`src/opensmartroute/credentials.py`) Credentials for the ``osr`` CLI: where the access token lives and how it is obtained. | Name | Kind | Summary | |---|---|---| | `CREDENTIALS_FILE` | constant | file name inside :func:`config_dir`. | | `DEFAULT_PROFILE` | constant | profile used when ``--profile`` is not given. | | `DEVICE_CODE_PATH` | constant | RFC 8628 device-authorization endpoint of the platform. | | `DEVICE_TOKEN_PATH` | constant | noqa: S105 # nosec B105 - RFC 8628 token endpoint (a URL path). | | `ME_PATH` | constant | platform: who am I (workspace, plan, edition). | | `TOKEN_BYTES` | constant | entropy of :func:`generate_token`. | | `WHOAMI_PATH` | constant | self-hosted ``osr serve``: is this token accepted. | | `Credential` | class | One saved sign-in: where (``url``), what (``token``) and what the platform said about it. | | `CredentialStore` | class | Profiles in ``/credentials.json`` (owner-only permissions on POSIX). | | `PlatformClient` | class | Minimal JSON client for the platform / server API used by the CLI (stdlib only, injectable transport). | | `Transport` | constant | : ``(method, url, headers, body, timeout) -> (status, json)``; tests inject a fake instead of urllib. | | `apply_identity` | function `(cred: Credential, info: Mapping[str, Any])` | Copy what :func:`whoami` learned (kind, workspace, plan, edition) onto ``cred``. | | `config_dir` | function `(environ: Mapping[str, str] \| None=None)` | Per-user configuration directory (``OSR_CONFIG_DIR`` > ``%APPDATA%`` > ``$XDG_CONFIG_HOME`` > ``~/.config``). | | `device_login` | function `(url: str \| None=None, *, client_name: str \| None=None, open_browser: bool=True, out: Callable[[str], None]=print, transport: Transport \| None=None, sleep: Callable[[float], None]=time.sleep, timeout_s: float \| None=None)` | Sign in to the hosted platform with the device authorization grant and return the credential. | | `generate_token` | function `(prefix: str=LOCAL_TOKEN_PREFIX)` | A fresh random access token (``osr_local_<43 chars>``) for a self-hosted ``osr serve``. | | `redact` | function `(token: str, keep: int=6)` | ``osr_live_abc123...`` - the prefix plus a few characters, never the whole token. | | `token_kind` | function `(token: str)` | ``"platform"`` for ``osr_live_`` keys, ``"server"`` for ``osr_local_`` tokens, else ``"unknown"``. | | `whoami` | function `(cred: Credential, *, transport: Transport \| None=None, timeout: float=30.0)` | Validate ``cred`` against its server and describe the identity behind it. | ## `opensmartroute.discovery` Source: src/opensmartroute/discovery.py (`src/opensmartroute/discovery.py`) Tool discovery beyond text similarity. | Name | Kind | Summary | |---|---|---| | `CachePreservingSelector` | class | Keep the serialized tool list prefix-stable across turns of a session. | | `SchemaAwareStrategy` | class | Scores tools by how many of their ``input_schema`` parameters the request can fill (see ``schema_match``). | | `SkillGraph` | class | Dependency / conflict / composition graph over skill targets. | | `extract_entities` | function `(text: str)` | Typed entity mentions found in ``text`` (kind -> values). | | `schema_match` | function `(request: RouteRequest \| str, target: RouteTarget)` | Return ``(coverage, filled, missing)`` for the target's input schema. | ## `opensmartroute.enterprise` Source: src/opensmartroute/enterprise/__init__.py (`src/opensmartroute/enterprise/__init__.py`) Enterprise integration layer: ports (hexagonal architecture), middleware and telemetry. | Name | Kind | Summary | |---|---|---| | `AuditSink` | class | Tamper-evident audit trail port (hash-chained). | | `CacheMiddleware` | class | LRU decision cache keyed on (text, constraints, objective, route options). TTL in seconds. | | `EnterpriseRouter` | class | Router + middleware chain + telemetry + auto-learning + audit. Thread-safe façade. | | `FileAuditSink` | class | Append-only JSONL, each line ``{prev, hash, record}`` with. | | `FileStateStore` | class | One JSON file per key under ``root``; keys are hashed so they can't traverse paths. | | `InMemoryStateStore` | class | Thread-safe dict-backed :class:`StateStore`; values are deep-copied through JSON on read and write. | | `LoggingTelemetry` | class | Structured JSON logs; never logs raw request text (only a hash + length). | | `MetricsTelemetry` | class | In-process counters, outcome tallies and a latency histogram. | | `Middleware` | class | Chain-of-responsibility hook around routing: ``__call__(request, next_) -> RouteDecision``. | | `RouteFn` | constant | the "next" callable a middleware wraps. | | `RouterBuilder` | class | Fluent builder that validates configuration and wires all enterprise pieces. | | `SavingsEntry` | re-export of [`opensmartroute.enterprise.savings.SavingsEntry`](#opensmartrouteenterprisesavings) | One routed request in the ledger. | | `SavingsLedger` | re-export of [`opensmartroute.enterprise.savings.SavingsLedger`](#opensmartrouteenterprisesavings) | Telemetry sink that keeps a per-request baseline-vs-routed cost ledger (see module docs). | | `SavingsReport` | re-export of [`opensmartroute.enterprise.savings.SavingsReport`](#opensmartrouteenterprisesavings) | Aggregate savings and the quality they were bought at. | | `StateStore` | class | Key/value persistence port for learner state, caches, breaker state. | | `Telemetry` | class | Observer port with no-op defaults. Implement for OpenTelemetry, Prometheus, Datadog…. | | `TenantMiddleware` | class | Enforces that a tenant is present and applies per-tenant defaults/limits. | | `TimeoutMiddleware` | class | Soft deadline: raise if routing itself exceeded ``budget_ms`` (should never happen. | ## `opensmartroute.enterprise.ops` Source: src/opensmartroute/enterprise/ops.py (`src/opensmartroute/enterprise/ops.py`) Operational controls: shadow / A-B routing, tenant fairness and queue-aware latency. | Name | Kind | Summary | |---|---|---| | `SPRT` | class | Wald SPRT for two Bernoulli success rates: H0 p=p0 vs H1 p=p0+delta. | | `ABTest` | class | Traffic split + SPRT comparison of candidate vs control outcomes. | | `FairShareMiddleware` | class | Dominant Resource Fairness across tenants over a sliding window. | | `InflightTracker` | class | Per-target in-flight counters + arrival/service statistics for queueing estimates. | | `QueueAwareStrategy` | class | Scores targets by *current* time-to-first-token = catalogue latency + queueing wait vs. | | `ShadowMiddleware` | class | Run ``candidate`` beside production. ``mode='shadow'``: log only. ``mode='ab'``: serve. | | `TenantUsage` | class | Sliding-window ledger of one tenant's requests, cost and tokens for :class:`FairShareMiddleware`. | ## `opensmartroute.enterprise.savings` Source: src/opensmartroute/enterprise/savings.py (`src/opensmartroute/enterprise/savings.py`) Savings ledger - the always-on savings report that backs the ROI story and the dashboard. | Name | Kind | Summary | |---|---|---| | `SavingsEntry` | class | One routed request in the ledger. | | `SavingsLedger` | class | Telemetry sink that keeps a per-request baseline-vs-routed cost ledger (see module docs). | | `SavingsReport` | class | Aggregate savings and the quality they were bought at. | ## `opensmartroute.enterprise.stores` Source: src/opensmartroute/enterprise/stores.py (`src/opensmartroute/enterprise/stores.py`) Production state-store backends and wrappers. | Name | Kind | Summary | |---|---|---| | `BatchedStateStore` | class | Write-behind buffer. Reads are served from the pending map first. | | `EncryptedStateStore` | class | AES-256-GCM envelope encryption. ``key`` is 32 raw bytes, or read (base64/hex/raw). | | `Migration` | constant | state-document transform applied by VersionedStateStore. | | `NamespacedStateStore` | class | Prefix every key with ``/`` so several routers or tenants can share one backing store. | | `RedisStateStore` | class | StateStore on any redis-py-compatible client (``get`` / ``set`` / ``delete``), JSON values, optional TTL. | | `SQLStateStore` | class | DB-API 2.0 key/value store (PostgreSQL, SQLite, MySQL). | | `VersionedStateStore` | class | Schema-versioned envelope with forward migrations. | ## `opensmartroute.errors` Source: src/opensmartroute/errors.py (`src/opensmartroute/errors.py`) Exception hierarchy. Every error raised by the SDK derives from :class:`OpenSmartRouteError`. | Name | Kind | Summary | |---|---|---| | `OpenSmartRouteError` | class | Base class for all SDK errors. | | `ConfigurationError` | class | Invalid catalogue, rules, SKILL.md, settings or a missing optional dependency. | | `ValidationError` | class | A request, outcome or target failed validation. | | `NoRouteError` | class | No target satisfied the hard constraints. | | `TargetUnavailableError` | class | A remote target or catalogue source could not be reached. | | `ExecutionError` | class | A target handler failed while executing a plan. | | `SecurityError` | class | Request rejected by an input guard (prompt injection, oversize, etc.). | | `StateStoreError` | class | A learner-state store failed to load, save or migrate. | | `AuthenticationError` | class | The CLI has no valid access token for the platform / server, or a sign-in was denied or timed out. | | `OpenSmartRouteDeprecationWarning` | class | Emitted by :func:`deprecated`; filter with ``warnings.simplefilter`` on this class. | | `deprecated` | function `(name: str, *, since: str, removal: str, replacement: str \| None=None, stacklevel: int=3)` | Announce a deprecation according to the policy in CONTRIBUTING.md. | ## `opensmartroute.estimate` Source: src/opensmartroute/estimate.py (`src/opensmartroute/estimate.py`) Token, cost and latency estimates *before* a request is sent anywhere. | Name | Kind | Summary | |---|---|---| | `DEFAULT_OUTPUT_TOKENS` | constant | : Output length assumed when neither the caller nor the signals say (a short answer). | | `MESSAGE_OVERHEAD_TOKENS` | constant | : Tokens a chat API adds per message for role / separators (OpenAI-style framing). | | `PriceHook` | constant | : ``(usd_per_1k_input, usd_per_1k_output)`` for a target, or ``None`` to fall back to its declared cost. | | `RequestEstimate` | class | A quote for one request across every candidate, with named picks. | | `TargetEstimate` | class | The quote for one candidate target. | | `estimate` | function `(router: Router, request: RouteRequest \| str, *, output_tokens: int \| None=None, kinds: list[str] \| None=None, prices: PriceHook \| None=None, quality_tolerance: float=0.1, decision: RouteDecision \| None=None)` | Quote ``request`` against every candidate the router would consider - nothing is executed. | | `estimate_messages_tokens` | function `(messages: list[dict[str, Any]])` | Token estimate for an OpenAI-style message list (content plus per-message framing). | | `estimate_tokens` | function `(text: str)` | Approximate the tokenizer count of ``text`` without any tokenizer library. | | `target_prices` | function `(target: RouteTarget)` | ``(usd per 1k input tokens, usd per 1k output tokens)`` from the target's declared cost. | ## `opensmartroute.eval` Source: src/opensmartroute/eval/__init__.py (`src/opensmartroute/eval/__init__.py`) RouterBench-style evaluation harness. | Name | Kind | Summary | |---|---|---| | `AuditReport` | re-export of [`opensmartroute.eval.audit.AuditReport`](#opensmartrouteevalaudit) | Aggregate of a shadow replay; ``to_markdown`` renders the Routing Audit deliverable. | | `AuditRow` | re-export of [`opensmartroute.eval.audit.AuditRow`](#opensmartrouteevalaudit) | One logged request: what happened, and what the router would have done. | | `DatasetCollector` | re-export of [`opensmartroute.eval.collect.DatasetCollector`](#opensmartrouteevalcollect) | Cache-backed corpus builder: collect sources, add feedback / synthetic rows, dedupe, split. | | `DatasetSource` | re-export of [`opensmartroute.eval.collect.DatasetSource`](#opensmartrouteevalcollect) | One Hub dataset split to collect: repo id, config, split, the preset that parses it, an optional model map. | | `EvalResult` | class | Aggregate routing metrics over a dataset: accuracy, cost, latency, confidence, calibration, coverage. | | `EvalRow` | class | One labelled prompt: expected / acceptable targets or per-target quality scores (RouterBench style). | | `area_under_frontier` | function `(points: list[dict[str, float]])` | Trapezoidal area under accuracy(cost) — analogous to RouterBench's AIQ. | | `calibration_report` | function `(router: Router, rows: list[EvalRow], objective: Objective \| None=None)` | Confidence calibration of the router on labelled rows: ECE, Brier, reliability bins and. | | `collect_dataset` | re-export of [`opensmartroute.eval.collect.collect_dataset`](#opensmartrouteevalcollect) | Download ``source`` from the Hub and parse it into rows. | | `cost_quality_frontier` | function `(router: Router, rows: list[EvalRow], cost_weights: list[float] \| None=None)` | Sweep the cost weight to trace the accuracy-vs-cost curve (RouterBench Fig. 1 style). | | `evaluate` | function `(router: Router, rows: list[EvalRow], objective: Objective \| None=None)` | Route every row and score accuracy, realised quality, cost, latency, ECE / Brier and conformal coverage. | | `fetch_hf_rows` | re-export of [`opensmartroute.eval.collect.fetch_hf_rows`](#opensmartrouteevalcollect) | One page (max 100) of records from the datasets-server ``/rows`` endpoint, flattened to ``{column: value}``. | | `load_audit_log` | re-export of [`opensmartroute.eval.audit.load_audit_log`](#opensmartrouteevalaudit) | Read a JSONL traffic log (``text`` or ``prompt``/``messages`` per line). | | `load_dataset` | function `(path: str \| Path)` | Read a JSONL evaluation dataset (``text`` or ``prompt`` plus the optional EvalRow keys); a line that is. | | `model_quality` | re-export of [`opensmartroute.eval.collect.model_quality`](#opensmartrouteevalcollect) | Data-derived quality prior per model in [0, 1]: pairwise rows (two scored models) are fitted with. | | `routing_audit` | re-export of [`opensmartroute.eval.audit.routing_audit`](#opensmartrouteevalaudit) | Replay ``rows`` through ``router`` in shadow mode and aggregate an :class:`AuditReport`. | | `rows_from_feedback` | re-export of [`opensmartroute.eval.collect.rows_from_feedback`](#opensmartrouteevalcollect) | Rows from :class:`Outcome` records. ``texts`` maps ``request_id`` to the prompt (outcomes carry no text);. | | `summarize_audit` | re-export of [`opensmartroute.eval.audit.summarize_audit`](#opensmartrouteevalaudit) | Aggregate :class:`AuditRow` records into an :class:`AuditReport`. | | `synthetic_rows` | re-export of [`opensmartroute.eval.collect.synthetic_rows`](#opensmartrouteevalcollect) | Ontology seed prompts labelled with the best capability-fit target (cold-start supervision). | ## `opensmartroute.eval.agentic` Source: src/opensmartroute/eval/agentic.py (`src/opensmartroute/eval/agentic.py`) tau-bench-style agentic task evaluation: does per-step routing beat the best single agent?. | Name | Kind | Summary | |---|---|---| | `AgentTask` | class | A multi-step task with the measured per-step success probability and latency of each agent. | | `load_agentic_tasks` | function `(path: str \| Path)` | Read tasks from JSONL: ``{"task_id", "steps", "success", "latency_ms", "cost_usd"?, "domain"?}``. | | `synthetic_agentic_tasks` | function `(n: int=200, *, seed: int=0, hard_share: float=0.3)` | Three agents (fast / balanced / strong) and ``n`` tasks of 3-5 steps whose steps are mostly. | | `task_routing_frontier` | function `(registry: TargetRegistry, tasks: Sequence[AgentTask], *, retries: int=1, accuracy_tolerance: float=0.02, latency_ratio_target: float=0.9, objective: Objective \| None=None, router_factory: Callable[[TargetRegistry], Router] \| None=None, seed: int=0)` | Replay ``tasks`` step by step through :class:`ProgressRouter` (each agent's handler draws the. | ## `opensmartroute.eval.audit` Source: src/opensmartroute/eval/audit.py (`src/opensmartroute/eval/audit.py`) Routing Audit - shadow-mode replay of logged LLM traffic to quantify what the router would change. | Name | Kind | Summary | |---|---|---| | `DEFAULT_COMPLETION_TOKENS` | constant | : Default assumed output length when a log row carries no ``completion_tokens``. | | `AuditReport` | class | Aggregate of a shadow replay; ``to_markdown`` renders the Routing Audit deliverable. | | `AuditRow` | class | One logged request: what happened, and what the router would have done. | | `load_audit_log` | function `(path: str \| Path)` | Read a JSONL traffic log (``text`` or ``prompt``/``messages`` per line). | | `routing_audit` | function `(router: Router, rows: list[dict[str, Any]], *, baseline: str \| None=None, monthly_requests: int \| None=None, plan: bool=False, keep_rows: bool=True)` | Replay ``rows`` through ``router`` in shadow mode and aggregate an :class:`AuditReport`. | | `summarize_audit` | function `(rows: list[AuditRow], *, monthly_requests: int \| None=None, keep_rows: bool=True)` | Aggregate :class:`AuditRow` records into an :class:`AuditReport`. | ## `opensmartroute.eval.baselines` Source: src/opensmartroute/eval/baselines.py (`src/opensmartroute/eval/baselines.py`) Baselines every router must beat, plus oracle ceilings and the sampling noise floor. | Name | Kind | Summary | |---|---|---| | `Policy` | constant | a baseline: (row, targets) -> chosen target id. | | `PolicyResult` | class | Metrics of one baseline policy on a dataset (same fields as the router's EvalResult headline). | | `baseline_suite` | function `(rows: list[EvalRow], targets: Sequence[RouteTarget], train_rows: list[EvalRow] \| None=None, quality_floor: float=0.7, seed: int=0)` | Run every baseline and both oracles; ``train_rows`` (default: ``rows``) fit the task table. | | `best_prior_policy` | function `(row: EvalRow, targets: Sequence[RouteTarget])` | Always the target with the highest declared ``quality_prior``. | | `cheapest_policy` | function `(row: EvalRow, targets: Sequence[RouteTarget])` | Always the lowest unit cost (ties broken by latency). | | `evaluate_policy` | function `(name: str, policy: Policy, rows: list[EvalRow], targets: Sequence[RouteTarget])` | Run a baseline :data:`Policy` over the rows and aggregate accuracy, quality, cost and latency. | | `fit_task_table` | function `(rows: list[EvalRow], targets: Sequence[RouteTarget])` | ``task_type -> target`` with the highest mean quality on the training rows. | | `most_expensive_policy` | function `(row: EvalRow, targets: Sequence[RouteTarget])` | Always the highest unit cost - the "just use the frontier model" baseline. | | `multi_sample_oracle` | function `(rows: list[EvalRow], targets: Sequence[RouteTarget])` | Mean quality of the oracle that picks by the *mean over all samples* per target. | | `noise_floor` | function `(rows: list[EvalRow], targets: Sequence[RouteTarget], seed: int=0)` | How much accuracy is lost to sampling noise alone. | | `oracle_policy` | function `(quality_floor: float \| None=None)` | Per-row best target. With ``quality_floor`` -> cheapest target reaching the floor. | | `random_policy` | function `(seed: int=0)` | Uniformly random target (seeded). | | `static_task_table_policy` | function `(table: dict[str, str])` | Look the row's ``task_type`` up in a table from :func:`fit_task_table` (``"*"`` = default). | ## `opensmartroute.eval.collect` Source: src/opensmartroute/eval/collect.py (`src/opensmartroute/eval/collect.py`) Collect routing datasets from the Hugging Face Hub, your own feedback log and synthetic seeds. | Name | Kind | Summary | |---|---|---| | `ARENA_TIERS` | constant | everything else in those datasets is a 7B-14B chat model -> "small". | | `DATASETS_SERVER` | re-export of [`opensmartroute.adapters.websearch.DATASETS_SERVER`](#opensmartrouteadapterswebsearch) | Hugging Face datasets-server REST root (/rows). | | `DEFAULT_SOURCES` | constant | public ones. | | `HISTORY_FILE` | constant | the self-improver's report log; lives in the cache dir but is not a dataset. | | `KNOWN_SOURCES` | constant | pairwise human / judge preference battles - the winner is the label. | | `PAIRWISE` | constant | preset name for battle datasets: prompt / conversation, model_a, model_b, winner. | | `PARSERS` | constant | collector presets that are not wide / nested tables. | | `REWARD_BENCH` | constant | preset name for RewardBench: prompt, chosen_model, rejected_model, subset. | | `ROUTELLM_GOOD_ENOUGH` | constant | RouteLLM's threshold: a weak-model score >= 4 means the cheap model was good enough. | | `ROUTELLM_GPT4` | constant | preset name for RouteLLM's gpt4_dataset: prompt + GPT-4-judged Mixtral score 1-5. | | `ROUTELLM_STRONG` | constant | the strong model of RouteLLM's gpt4_dataset (its answers are the reference). | | `ROUTELLM_WEAK` | constant | the weak model whose answer GPT-4 scores 1-5 against the reference. | | `ULTRAFEEDBACK` | constant | preset name for UltraFeedback: instruction + N completions with a model and score. | | `DatasetCollector` | class | Cache-backed corpus builder: collect sources, add feedback / synthetic rows, dedupe, split. | | `DatasetSource` | class | One Hub dataset split to collect: repo id, config, split, the preset that parses it, an optional model map. | | `Parser` | constant | record -> row (or None to skip). | | `collect_dataset` | function `(source: DatasetSource, *, timeout_s: float \| None=None, settings: Settings \| None=None)` | Download ``source`` from the Hub and parse it into rows. | | `fetch_hf_rows` | function `(dataset: str, *, config: str='default', split: str='train', offset: int=0, length: int=100, timeout_s: float \| None=None, settings: Settings \| None=None)` | One page (max 100) of records from the datasets-server ``/rows`` endpoint, flattened to ``{column: value}``. | | `from_pairwise_row` | function `(rec: dict[str, Any], model_map: dict[str, str] \| None=None, source: DatasetSource \| None=None)` | A battle record -> row with ``scores`` 1 / 0 for winner / loser (0.5 each on a tie). Understands the. | | `from_reward_bench_row` | function `(rec: dict[str, Any], source: DatasetSource \| None=None)` | A RewardBench record (``prompt``, ``chosen_model``, ``rejected_model``, ``subset``) -> a pairwise row. | | `from_routellm_gpt4_row` | function `(rec: dict[str, Any], source: DatasetSource \| None=None)` | A ``routellm/gpt4_dataset`` record (``prompt`` + ``mixtral_score`` 1-5) -> the strong model scores 1.0 and. | | `from_ultrafeedback_row` | function `(rec: dict[str, Any], source: DatasetSource \| None=None)` | An UltraFeedback record (``instruction`` + ``completions[{model, overall_score}]``) -> a scored row with. | | `iter_hf_rows` | function `(source: DatasetSource, *, offset: int=0, timeout_s: float \| None=None, settings: Settings \| None=None)` | Page through ``source`` from raw record ``offset`` until ``source.limit`` records or the split is exhausted. | | `model_quality` | function `(rows: Iterable[EvalRow], *, min_n: int=20, epochs: int=5, seed: int=0)` | Data-derived quality prior per model in [0, 1]: pairwise rows (two scored models) are fitted with. | | `rows_from_feedback` | function `(outcomes: Iterable[Outcome] \| FeedbackStore, texts: dict[str, str] \| None=None, *, min_quality: float=0.5)` | Rows from :class:`Outcome` records. ``texts`` maps ``request_id`` to the prompt (outcomes carry no text);. | | `rows_from_records` | function `(records: Iterable[dict[str, Any]], source: DatasetSource)` | Parse raw records with the source's preset (``text_key`` is tried first when set). | | `synthetic_rows` | function `(targets: Sequence[RouteTarget], *, per_template: int=2, seed: int=0)` | Ontology seed prompts labelled with the best capability-fit target (cold-start supervision). | | `tier_model_map` | function `(tiers: Mapping[str, str], models: Iterable[str]=())` | ``model_map`` for a :class:`DatasetSource`: every known battle model (plus ``models``) -> the target id. | | `tier_of` | function `(model: str)` | Tier of a battle-dataset model name: the :data:`ARENA_TIERS` entry, else the name rules, else the parameter. | ## `opensmartroute.eval.criteria` Source: src/opensmartroute/eval/criteria.py (`src/opensmartroute/eval/criteria.py`) Offline realisations of the ROADMAP exit criteria. | Name | Kind | Summary | |---|---|---| | `CriterionResult` | class | One measured exit criterion. | | `bootstrap_ci` | function `(values: Sequence[float], *, n_boot: int=1000, level: float=0.95, seed: int=0)` | Percentile bootstrap confidence interval for the mean of ``values``. | | `cold_start_ratio` | function `(n_outcomes: int=200, *, domain: str='legal', n_eval: int=200, seed: int=0, target_ratio: float=0.9, generalist_quality: float=0.6, explore_rate: float=0.1, max_requests: int=20000)` | Accuracy on ``domain`` prompts of a target declared with only ``id`` / ``kind`` / ``cost``. | | `conformal_coverage` | function `(alpha: float=0.1, *, n_cal: int=1000, n_test: int=1000, label_noise: float=0.5, seed: int=0, tolerance: float=0.02)` | Fit :class:`ConformalCalibrator` on the real router's propensities over labelled prompts and. | | `domain_expert_registry` | function `(domains: Sequence[str]=_DOMAINS, *, strip: str \| None=None, generalist: bool=False)` | One hand-configured expert per domain. ``strip=`` replaces that expert with a. | | `effort_token_savings` | function `(registry: TargetRegistry, rows: Sequence[EvalRow], *, quality_tolerance: float=0.02, token_ratio_target: float=0.7, objective: Objective \| None=None, router_factory: Callable[[TargetRegistry], Router] \| None=None)` | Route rows that carry per-target ``scores`` *and* ``tokens`` and compare the tokens spent. | | `knapsack_never_exceeds_cap` | function `(steps: int=1000000, *, window: int=1000, drift_every: int=100000, seed: int=0)` | Drive :class:`MultiKnapsackBandit` (``on_capped="abstain"``) for ``steps`` pulls with. | | `match_at_1` | function `(router: Router \| EnterpriseRouter, prompts: Sequence[tuple[str, str]])` | Fraction of ``(text, expected_target_id)`` pairs the router gets right at rank 1. | | `match_at_1_at_scale` | function `(small: int=50, large: int=5000, *, n_prompts: int=200, seed: int=0, max_drop: float=0.05, narrow_above: int=32, narrow_to: int=24)` | Match@1 on a ``small`` catalogue versus a ``large`` one with retrieve-then-rank narrowing. | | `multi_round_vs_best_single` | function `(registry: TargetRegistry, rows: Sequence[EvalRow], *, threshold: float=0.8, max_rounds: int=3, failures_before_switch: int=1, objective: Objective \| None=None, cost_ratio_target: float=0.6, router_factory: Callable[[TargetRegistry], Router] \| None=None)` | Run :class:`MultiRoundExecutor` over rows that carry per-target ``scores`` (RouterBench. | | `ope_within_live_ci` | function `(n_log: int=2000, *, seed: int=0, logging_objective: Objective \| None=None, target_objective: Objective \| None=None, logging_temperature: float=0.3)` | Log decisions from a cost-seeking router (actions *sampled* from its propensities), estimate. | | `run_all` | function `(*, quick: bool=True, seed: int=0)` | Every offline criterion. ``quick`` shrinks the expensive simulations (10^5 steps, 1 000 tools,. | | `synthetic_effort_rows` | function `(n: int=400, *, seed: int=0)` | One reasoning model exposed as two effort siblings (``reasoner@fast`` with ``effort="low"``. | | `synthetic_scored_rows` | function `(n: int=300, *, seed: int=0)` | A three-tier catalogue (small / medium / large) and RouterBench-style rows with a quality. | | `synthetic_tool_catalogue` | function `(n: int, *, seed: int=0)` | ``n`` distinct tools (verb x object x qualifier, up to 5 000 unique combinations) and one. | ## `opensmartroute.eval.datasets` Source: src/opensmartroute/eval/datasets.py (`src/opensmartroute/eval/datasets.py`) Adapters from public routing benchmarks to :class:`EvalRow`. | Name | Kind | Summary | |---|---|---| | `PRESETS` | constant | Named layouts accepted by ``load_benchmark`` / ``osr eval --preset``. | | `NestedPreset` | class | Layout of a "nested" benchmark: a per-model mapping under ``container_keys`` holding score / cost / samples. | | `WidePreset` | class | Column layout of a "wide" benchmark: one row per prompt, ```` columns for scores / costs. | | `from_nested_row` | function `(row: dict[str, Any], preset: NestedPreset, model_map: dict[str, str] \| None=None)` | Convert one nested-format record to an :class:`EvalRow`, keeping repeated samples when present. | | `from_wide_row` | function `(row: dict[str, Any], preset: WidePreset, model_map: dict[str, str] \| None=None)` | Convert one wide-format record to an :class:`EvalRow` (None when it has no prompt or scores). | | `load_benchmark` | function `(path: str \| Path, preset: str \| WidePreset \| NestedPreset='routerbench', model_map: dict[str, str] \| None=None, limit: int \| None=None)` | Load a benchmark file (.jsonl / .json / .csv) into :class:`EvalRow` objects. | | `models_in` | function `(rows: Iterable[EvalRow])` | Distinct target ids that carry scores in the rows, in first-seen order. | ## `opensmartroute.eval.frontier` Source: src/opensmartroute/eval/frontier.py (`src/opensmartroute/eval/frontier.py`) Three-objective frontier and ablations. | Name | Kind | Summary | |---|---|---| | `ablation_report` | function `(router: Router, rows: list[EvalRow], objective: Objective \| None=None)` | Leave-one-out over strategies (and extractors, when explicitly set on the router). | | `frontier3` | function `(router: Router, rows: list[EvalRow], cost_weights: list[float] \| None=None, latency_weights: list[float] \| None=None)` | Sweep cost / latency objective weights and return the Pareto-optimal (quality, cost, latency) points. | | `hypervolume` | function `(points: list[dict[str, float]], ref: tuple[float, float, float] \| None=None)` | Dominated hypervolume of the Pareto points in normalised (quality, cost, latency) space. | ## `opensmartroute.eval.headroom` Source: src/opensmartroute/eval/headroom.py (`src/opensmartroute/eval/headroom.py`) Routing headroom: when does routing pay, and how much catalogue does it need?. | Name | Kind | Summary | |---|---|---| | `DiversityReport` | class | How differently the targets score rows: pairwise disagreement, winner entropy and winner share. | | `HeadroomReport` | class | Oracle vs best-single quality on a dataset, with the label-noise floor that says whether the gap is real. | | `learnability_by_difficulty` | function `(rows: Sequence[EvalRow], targets: Sequence[RouteTarget], buckets: int=4)` | Routing gain (oracle - best single) per difficulty bucket. Difficulty of a row is. | | `min_catalogue` | function `(rows: Sequence[EvalRow], targets: Sequence[RouteTarget], fraction: float=0.95)` | Greedy forward selection: the smallest ordered subset whose oracle reaches ``fraction`` of the. | | `routing_headroom` | function `(rows: Sequence[EvalRow], targets: Sequence[RouteTarget], seed: int=0)` | Oracle minus best-single quality with the label-noise floor for context. | | `scaling_curve` | function `(rows: Sequence[EvalRow], targets: Sequence[RouteTarget], sizes: Sequence[int] \| None=None, *, trials: int=20, seed: int=0)` | Mean oracle / best-single quality and headroom on random subsets of each size. | | `target_diversity` | function `(rows: Sequence[EvalRow], targets: Sequence[RouteTarget])` | How different the targets are on this data: pairwise score disagreement and winner spread. | ## `opensmartroute.eval.ope` Source: src/opensmartroute/eval/ope.py (`src/opensmartroute/eval/ope.py`) Off-policy evaluation from logged routing decisions. | Name | Kind | Summary | |---|---|---| | `LoggedDecision` | class | One logged routing event for off-policy evaluation: text, action taken, its propensity and observed reward. | | `OPEResult` | class | IPS, self-normalised IPS and doubly-robust value estimates with effective sample size and clip count. | | `ips_confidence_interval` | function `(logs: list[LoggedDecision], weights: list[float], z: float=1.96)` | Normal-approximation CI for the IPS estimate given per-sample weights. | | `mean_reward_model` | function `(logs: list[LoggedDecision])` | Simplest DR reward model: mean logged reward per action, global mean for unseen actions. | | `off_policy_evaluate` | function `(router: Router, logs: list[LoggedDecision], objective: Objective \| None=None, max_weight: float=20.0, reward_model: Callable[[LoggedDecision, str], float] \| None=None, deterministic: bool=False)` | Estimate the value of ``router`` on logged traffic. | | `target_propensities` | function `(router: Router, lg: LoggedDecision, objective: Objective \| None=None)` | The evaluated router's ``P(target \| x)`` for a logged context (empty when it has no route). | ## `opensmartroute.eval.robustness` Source: src/opensmartroute/eval/robustness.py (`src/opensmartroute/eval/robustness.py`) Robustness and fairness checks for a router. | Name | Kind | Summary | |---|---|---| | `coreset` | function `(rows: list[EvalRow], k: int, embedder: Callable[[list[str]], list[list[float]]] \| None=None, seed: int=0)` | Greedy k-center (farthest-first) subset of ``rows`` for a diverse evaluation set. | | `diversity` | function `(rows: list[EvalRow], embedder: Callable[[list[str]], list[list[float]]] \| None=None, sample: int=300)` | Mean pairwise cosine distance of the row texts (sampled), 0 = all identical. | | `paraphrase_robustness` | function `(router: Router, rows: list[EvalRow], n: int=4, objective: Objective \| None=None, seed: int=0)` | Share of rule-based paraphrases that route to the same target as the original (``robustness``). | | `paraphrases` | function `(text: str, n: int=4, seed: int=0)` | ``n`` deterministic surface-level paraphrases of ``text`` (never returns the original). | | `profile_swap_fairness` | function `(router: Router, rows: list[EvalRow], profiles: Sequence[dict[str, Any]] \| None=None, objective: Objective \| None=None)` | Decision agreement across user profiles. ``dependence`` = fraction of rows whose. | | `repeat_flip_rate` | function `(router: Router, rows: list[EvalRow], k: int=5, objective: Objective \| None=None)` | Route each row ``k`` times; ``flip_rate`` = share of rows whose decision is not identical every time. | ## `opensmartroute.execution` Source: src/opensmartroute/execution.py (`src/opensmartroute/execution.py`) Plan-aware execution: turn a :class:`RouteDecision` into a real answer. | Name | Kind | Summary | |---|---|---| | `PRELUDE_ROLES` | constant | Roles executed *before* the primary target, in this order. | | `ExecutionResult` | class | What happened when a decision was executed. | | `ExecutionStep` | class | One executed plan slot: role, target, latency and whether it succeeded. | | `aexecute` | async function `(decision: RouteDecision, request: RouteRequest, learn: LearnFn \| None=None, *, min_slot_confidence: float=0.0, task_id: str \| None=None, **kw: Any)` | Async twin of :func:`execute`; awaits coroutine handlers. | | `execute` | function `(decision: RouteDecision, request: RouteRequest, learn: LearnFn \| None=None, *, min_slot_confidence: float=0.0, task_id: str \| None=None, **kw: Any)` | Run the plan (persona -> skill -> primary) and record outcomes via ``learn``. | ## `opensmartroute.feedback` Source: src/opensmartroute/feedback/__init__.py (`src/opensmartroute/feedback/__init__.py`) Feedback store: append-only outcome log that closes the learning loop. | Name | Kind | Summary | |---|---|---| | `FeedbackStore` | class | Append-only :class:`Outcome` log (in memory or JSONL file) with per-target statistics. | ## `opensmartroute.learning` Source: src/opensmartroute/learning/__init__.py (`src/opensmartroute/learning/__init__.py`) Auto-learning strategies built on :mod:`opensmartroute.math`. | Name | Kind | Summary | |---|---|---| | `DEFAULT_DOMAINS` | constant | Domain one-hot block of the LinUCB context vector (ontology domains + the "general" fallback). | | `AttentionEncoder` | re-export of [`opensmartroute.learning.attention.AttentionEncoder`](#opensmartroutelearningattention) | One self-attention block with attention pooling; encodes text into a ``dim``-vector (unnormalised). | | `AutoLearner` | class | Single entry point for closing the loop. | | `Autopilot` | re-export of [`opensmartroute.learning.autopilot.Autopilot`](#opensmartroutelearningautopilot) | Runs a :class:`SelfImprover` on a schedule and on drift, inside a live process. | | `ContrastiveRouter` | re-export of [`opensmartroute.learning.contrastive.ContrastiveRouter`](#opensmartroutelearningcontrastive) | Dual-encoder router trained with a contrastive or a distillation objective. | | `ContrastiveStrategy` | re-export of [`opensmartroute.learning.contrastive.ContrastiveStrategy`](#opensmartroutelearningcontrastive) | Scores candidates with a trained :class:`ContrastiveRouter`. | | `DriftMonitor` | re-export of [`opensmartroute.learning.autopilot.DriftMonitor`](#opensmartroutelearningautopilot) | Page-Hinkley over outcomes: alarms when the served success rate (or quality) drops for real. | | `EmbeddingFeaturizer` | re-export of [`opensmartroute.learning.embed.EmbeddingFeaturizer`](#opensmartroutelearningembed) | Hashed features plus a frozen dense embedding, indexed above the hashed space (``dim + i``). | | `ExampleMiner` | re-export of [`opensmartroute.learning.coldstart.ExampleMiner`](#opensmartroutelearningcoldstart) | Promote prompts a target handled well into that target's ``examples``. | | `HandoffPolicy` | re-export of [`opensmartroute.learning.handoff.HandoffPolicy`](#opensmartroutelearninghandoff) | Permanent handoff of a task to ``fallback_target`` once the failure risk is too high. | | `HistoryTargetModel` | re-export of [`opensmartroute.learning.multiturn.HistoryTargetModel`](#opensmartroutelearningmultiturn) | Logistic model over ``h * e_t`` with a shared weight vector and per-target biases. | | `HistoryTargetStrategy` | re-export of [`opensmartroute.learning.multiturn.HistoryTargetStrategy`](#opensmartroutelearningmultiturn) | Scores each target by the learned success probability given the conversation so far. | | `IRTStrategy` | class | 2PL Item Response Theory: target ability vs (domain, complexity-bucket) item difficulty, learned online. | | `ImprovementReport` | re-export of [`opensmartroute.learning.self_improve.ImprovementReport`](#opensmartroutelearningself_improve) | What one cycle did: evidence gathered, catalogue changes, champion vs challenger, and the verdict. | | `LinUCBStrategy` | class | Contextual bandit (LinUCB) on the signal vector; keeps the last context per request for the update. | | `MarkovStrategy` | class | Prefers targets that do well on the *predicted next* conversation state too. | | `MixtureCureModel` | re-export of [`opensmartroute.learning.handoff.MixtureCureModel`](#opensmartroutelearninghandoff) | Weibull mixture-cure model on cumulative risk with censoring. | | `PolicyGradientStrategy` | re-export of [`opensmartroute.learning.policy_gradient.PolicyGradientStrategy`](#opensmartroutelearningpolicy_gradient) | REINFORCE-trained softmax routing policy over hashed request features. | | `PreferenceStrategy` | class | Bradley-Terry strengths per domain, fed by ``Outcome.preferred_over`` pairwise comparisons. | | `RegretReport` | re-export of [`opensmartroute.learning.policy_gradient.RegretReport`](#opensmartroutelearningpolicy_gradient) | Decision regret versus prediction error on a scored dataset. | | `RequestMemory` | re-export of [`opensmartroute.learning.coldstart.RequestMemory`](#opensmartroutelearningcoldstart) | Bounded LRU of request texts keyed by request id. | | `RouterSLM` | re-export of [`opensmartroute.learning.slm.RouterSLM`](#opensmartroutelearningslm) | Small routing model: dual encoder + target catalogue snapshot + calibration, in one JSON file. | | `SLMReport` | re-export of [`opensmartroute.learning.slm.SLMReport`](#opensmartroutelearningslm) | How an SLM did on a set of rows: accuracy, realised quality, cost, calibration and the training loss. | | `SLMStrategy` | re-export of [`opensmartroute.learning.slm.SLMStrategy`](#opensmartroutelearningslm) | Ensemble member backed by a :class:`RouterSLM`; scores are its probabilities, and it keeps learning online. | | `SelfImprover` | re-export of [`opensmartroute.learning.self_improve.SelfImprover`](#opensmartroutelearningself_improve) | Closed loop that keeps a :class:`RouterSLM` current with the model market and its own traffic. | | `SimilarityFallback` | re-export of [`opensmartroute.learning.coldstart.SimilarityFallback`](#opensmartroutelearningcoldstart) | For targets with no observations yet, rank by request<->description similarity. | | `SkillAffinity` | re-export of [`opensmartroute.learning.personal.SkillAffinity`](#opensmartroutelearningpersonal) | Profile-conditioned skill relevance: Beta posterior per (profile bucket, skill). | | `TaskCredit` | re-export of [`opensmartroute.learning.credit.TaskCredit`](#opensmartroutelearningcredit) | Buffers per-step outcomes of a task and redistributes the final reward (uniform / discounted / last / blend). | | `TaskPins` | re-export of [`opensmartroute.learning.credit.TaskPins`](#opensmartroutelearningcredit) | Admission-time pinning: ``task_id -> target_id`` while the target keeps succeeding. | | `UserAdaptiveStrategy` | re-export of [`opensmartroute.learning.personal.UserAdaptiveStrategy`](#opensmartroutelearningpersonal) | Per-user Beta posteriors per target, shrunk toward similar users and the global posterior. | | `acceptable_set` | re-export of [`opensmartroute.learning.contrastive.acceptable_set`](#opensmartroutelearningcontrastive) | Targets that are 'fine' for a row: ``expected`` + ``acceptable`` when labelled, otherwise every. | | `decision_regret` | re-export of [`opensmartroute.learning.policy_gradient.decision_regret`](#opensmartroutelearningpolicy_gradient) | Mean decision regret of ``choose`` against the per-row oracle, next to the prediction error of. | | `decision_reward` | re-export of [`opensmartroute.learning.policy_gradient.decision_reward`](#opensmartroutelearningpolicy_gradient) | Scalar decision reward of an outcome under ``objective`` (quality minus normalised cost/latency). | | `distill_router` | re-export of [`opensmartroute.learning.slm.distill_router`](#opensmartroutelearningslm) | Compress the full router into an SLM: route every text, take the ensemble's ranked utilities as soft. | | `history_vector` | re-export of [`opensmartroute.learning.multiturn.history_vector`](#opensmartroutelearningmultiturn) | Recency-weighted joint embedding of the last ``turns`` messages and the current text. | | `load_embedder` | re-export of [`opensmartroute.learning.embed.load_embedder`](#opensmartroutelearningembed) | Build the embedder a model file names: ``sentence-transformers/...`` (or any Hugging Face id) via. | | `merge_learners` | function `(local: Iterable[Strategy], remote: Iterable[Strategy])` | Federated merge: fold the evidence of ``remote`` strategies into the same-named ``local``. | | `nearest_targets` | re-export of [`opensmartroute.learning.coldstart.nearest_targets`](#opensmartroutelearningcoldstart) | The ``k`` most similar existing targets (cosine + same-kind and domain-overlap bonuses) for warm starts. | | `outcome_counts` | re-export of [`opensmartroute.learning.coldstart.outcome_counts`](#opensmartroutelearningcoldstart) | Number of recorded outcomes per target id. | | `profile_bucket` | re-export of [`opensmartroute.learning.personal.profile_bucket`](#opensmartroutelearningpersonal) | Coarse profile bucket used to pool users with the same declared attributes. | | `profile_vector` | re-export of [`opensmartroute.learning.personal.profile_vector`](#opensmartroutelearningpersonal) | Hashed one-hot encoding of ``key=value`` pairs (lists expand to one pair per element). | | `signal_vector` | function `(signals: Signals, domains: list[str] \| None=None)` | Fixed-length numeric context for contextual bandits (dim = 8 + len(domains)). | | `soft_labels` | re-export of [`opensmartroute.learning.contrastive.soft_labels`](#opensmartroutelearningcontrastive) | Zooter soft labels: ``softmax(score / temperature)`` over the scored targets. | | `target_document` | re-export of [`opensmartroute.learning.coldstart.target_document`](#opensmartroutelearningcoldstart) | Text used to embed a target: name, description, domains, actions, tags and up to 12 examples. | | `target_embedding` | re-export of [`opensmartroute.learning.coldstart.target_embedding`](#opensmartroutelearningcoldstart) | Unit-norm centroid of the target document and its examples (hashing embedder by default). | | `warm_start` | re-export of [`opensmartroute.learning.coldstart.warm_start`](#opensmartroutelearningcoldstart) | Seed every learner with shrunk knowledge from the new target's nearest neighbours. | | `warm_start_from_matrix` | re-export of [`opensmartroute.learning.coldstart.warm_start_from_matrix`](#opensmartroutelearningcoldstart) | Offline **full-information reward-matrix** warm start (OrcaRouter 2605.30736). | ## `opensmartroute.learning.attention` Source: src/opensmartroute/learning/attention.py (`src/opensmartroute/learning/attention.py`) A pure-Python transformer block for the routing SLM's query encoder. | Name | Kind | Summary | |---|---|---| | `AttentionContext` | class | Everything :meth:`AttentionEncoder.backward` needs from one forward pass. | | `AttentionEncoder` | class | One self-attention block with attention pooling; encodes text into a ``dim``-vector (unnormalised). | ## `opensmartroute.learning.autopilot` Source: src/opensmartroute/learning/autopilot.py (`src/opensmartroute/learning/autopilot.py`) Self-operation: the routing SLM runs its own improvement loop inside the live process. | Name | Kind | Summary | |---|---|---| | `Autopilot` | class | Runs a :class:`SelfImprover` on a schedule and on drift, inside a live process. | | `DriftMonitor` | class | Page-Hinkley over outcomes: alarms when the served success rate (or quality) drops for real. | ## `opensmartroute.learning.coldstart` Source: src/opensmartroute/learning/coldstart.py (`src/opensmartroute/learning/coldstart.py`) Cold start for new targets and self-improving target descriptions. | Name | Kind | Summary | |---|---|---| | `ExampleMiner` | class | Promote prompts a target handled well into that target's ``examples``. | | `RequestMemory` | class | Bounded LRU of request texts keyed by request id. | | `SimilarityFallback` | class | For targets with no observations yet, rank by request<->description similarity. | | `nearest_targets` | function `(new: RouteTarget, pool: Iterable[RouteTarget], k: int=3, embedder: Embedder \| None=None)` | The ``k`` most similar existing targets (cosine + same-kind and domain-overlap bonuses) for warm starts. | | `outcome_counts` | function `(feedback: FeedbackStore)` | Number of recorded outcomes per target id. | | `target_document` | function `(t: RouteTarget)` | Text used to embed a target: name, description, domains, actions, tags and up to 12 examples. | | `target_embedding` | function `(t: RouteTarget, embedder: Embedder \| None=None)` | Unit-norm centroid of the target document and its examples (hashing embedder by default). | | `warm_start` | function `(new: RouteTarget, registry: TargetRegistry, strategies: list[Strategy], k: int=3, shrink: float=0.5, embedder: Embedder \| None=None)` | Seed every learner with shrunk knowledge from the new target's nearest neighbours. | ## `opensmartroute.learning.contrastive` Source: src/opensmartroute/learning/contrastive.py (`src/opensmartroute/learning/contrastive.py`) Contrastive and reward-distilled router training (RouterDC, NeurIPS 2024; Zooter 2311.08692). | Name | Kind | Summary | |---|---|---| | `ContrastiveRouter` | class | Dual-encoder router trained with a contrastive or a distillation objective. | | `ContrastiveStrategy` | class | Scores candidates with a trained :class:`ContrastiveRouter`. | | `acceptable_set` | function `(row: EvalRow, slack: float=0.05)` | Targets that are 'fine' for a row: ``expected`` + ``acceptable`` when labelled, otherwise every. | | `soft_labels` | function `(scores: dict[str, float], temperature: float=0.1)` | Zooter soft labels: ``softmax(score / temperature)`` over the scored targets. | ## `opensmartroute.learning.credit` Source: src/opensmartroute/learning/credit.py (`src/opensmartroute/learning/credit.py`) Delayed, task-level credit assignment for agentic trajectories. | Name | Kind | Summary | |---|---|---| | `TaskCredit` | class | Buffers per-step outcomes of a task and redistributes the final reward (uniform / discounted / last / blend). | | `TaskPins` | class | Admission-time pinning: ``task_id -> target_id`` while the target keeps succeeding. | ## `opensmartroute.learning.embed` Source: src/opensmartroute/learning/embed.py (`src/opensmartroute/learning/embed.py`) Pretrained transformer embeddings as frozen features for the routing SLM. | Name | Kind | Summary | |---|---|---| | `EmbeddingFeaturizer` | class | Hashed features plus a frozen dense embedding, indexed above the hashed space (``dim + i``). | | `load_embedder` | function `(name: str)` | Build the embedder a model file names: ``sentence-transformers/...`` (or any Hugging Face id) via. | ## `opensmartroute.learning.handoff` Source: src/opensmartroute/learning/handoff.py (`src/opensmartroute/learning/handoff.py`) Permanent-handoff policy from censored teacher signals (TACIT-Switch 2608.27911). | Name | Kind | Summary | |---|---|---| | `HandoffPolicy` | class | Permanent handoff of a task to ``fallback_target`` once the failure risk is too high. | | `MixtureCureModel` | class | Weibull mixture-cure model on cumulative risk with censoring. | | `Trajectory` | class | Per-task state tracked by :class:`HandoffPolicy`: cumulative risk, steps, failure and hand-off flags. | ## `opensmartroute.learning.multiturn` Source: src/opensmartroute/learning/multiturn.py (`src/opensmartroute/learning/multiturn.py`) Multi-turn routing with history-target joint embeddings (MTRouter 2604.23530). | Name | Kind | Summary | |---|---|---| | `HistoryTargetModel` | class | Logistic model over ``h * e_t`` with a shared weight vector and per-target biases. | | `HistoryTargetStrategy` | class | Scores each target by the learned success probability given the conversation so far. | | `history_vector` | function `(request: RouteRequest, embedder: Embedder, turns: int=6, decay: float=0.7)` | Recency-weighted joint embedding of the last ``turns`` messages and the current text. | ## `opensmartroute.learning.personal` Source: src/opensmartroute/learning/personal.py (`src/opensmartroute/learning/personal.py`) Few-shot personalisation (GMTRouter 2511.08590; SkillFeed 2608.28241). | Name | Kind | Summary | |---|---|---| | `SkillAffinity` | class | Profile-conditioned skill relevance: Beta posterior per (profile bucket, skill). | | `UserAdaptiveStrategy` | class | Per-user Beta posteriors per target, shrunk toward similar users and the global posterior. | | `profile_bucket` | function `(profile: dict[str, Any], keys: tuple[str, ...]=('tier', 'expertise', 'role', 'language'))` | Coarse profile bucket used to pool users with the same declared attributes. | | `profile_vector` | function `(profile: dict[str, Any], dim: int=_PROFILE_DIM)` | Hashed one-hot encoding of ``key=value`` pairs (lists expand to one pair per element). | ## `opensmartroute.learning.policy_gradient` Source: src/opensmartroute/learning/policy_gradient.py (`src/opensmartroute/learning/policy_gradient.py`) End-to-end policy-gradient routing (Router-R1 2506.09033; RLCascadeRouter 2608.15817). | Name | Kind | Summary | |---|---|---| | `PolicyGradientStrategy` | class | REINFORCE-trained softmax routing policy over hashed request features. | | `RegretReport` | class | Decision regret versus prediction error on a scored dataset. | | `decision_regret` | function `(rows: Sequence[EvalRow], targets: Sequence[RouteTarget], choose: Callable[[EvalRow, Sequence[RouteTarget]], str], predict: Callable[[EvalRow, RouteTarget], float] \| None=None)` | Mean decision regret of ``choose`` against the per-row oracle, next to the prediction error of. | | `decision_reward` | function `(outcome: Outcome, target: RouteTarget \| None, objective: Objective, *, cost_scale: float=0.01, latency_scale: float=2000.0)` | Scalar decision reward of an outcome under ``objective`` (quality minus normalised cost/latency). | ## `opensmartroute.learning.self_improve` Source: src/opensmartroute/learning/self_improve.py (`src/opensmartroute/learning/self_improve.py`) Self-improvement loop: refresh the catalogue, gather evidence, train a challenger, promote it only if better. | Name | Kind | Summary | |---|---|---| | `ImprovementReport` | class | What one cycle did: evidence gathered, catalogue changes, champion vs challenger, and the verdict. | | `SelfImprover` | class | Closed loop that keeps a :class:`RouterSLM` current with the model market and its own traffic. | ## `opensmartroute.learning.slm` Source: src/opensmartroute/learning/slm.py (`src/opensmartroute/learning/slm.py`) The OpenSmartRoute routing SLM: a small, self-contained model that picks the target for a prompt. | Name | Kind | Summary | |---|---|---| | `SLM_FORMAT` | constant | on-disk format version of ``RouterSLM.state()``. | | `RouterSLM` | class | Small routing model: dual encoder + target catalogue snapshot + calibration, in one JSON file. | | `SLMReport` | class | How an SLM did on a set of rows: accuracy, realised quality, cost, calibration and the training loss. | | `SLMStrategy` | class | Ensemble member backed by a :class:`RouterSLM`; scores are its probabilities, and it keeps learning online. | | `distill_router` | function `(router: Router, texts: Iterable[str], *, targets: Sequence[RouteTarget] \| None=None, settings: Settings \| None=None, seed: int=0)` | Compress the full router into an SLM: route every text, take the ensemble's ranked utilities as soft. | ## `opensmartroute.math` Source: src/opensmartroute/math/__init__.py (`src/opensmartroute/math/__init__.py`) Mathematical toolkit behind OpenSmartRoute's decisions. | Name | Kind | Summary | |---|---|---| | `EWMA` | re-export of [`opensmartroute.math.estimators.EWMA`](#opensmartroutemathestimators) | Exponentially weighted moving mean and variance with a z-score helper. | | `Bandit` | re-export of [`opensmartroute.math.bandits.Bandit`](#opensmartroutemathbandits) | Common interface. ``context`` is optional; non-contextual learners ignore it. | | `BradleyTerry` | re-export of [`opensmartroute.math.preference.BradleyTerry`](#opensmartroutemathpreference) | Online Bradley-Terry: per-context target strengths from pairwise wins, with L2 and forgetting. | | `ConformalCalibrator` | re-export of [`opensmartroute.math.calibration.ConformalCalibrator`](#opensmartroutemathcalibration) | Split conformal prediction over routing candidates. | | `CostAwareBandit` | re-export of [`opensmartroute.math.bandits.CostAwareBandit`](#opensmartroutemathbandits) | Lagrangian budget wrapper (C2MAB-V flavour). | | `DelayedFeedback` | re-export of [`opensmartroute.math.bandits.DelayedFeedback`](#opensmartroutemathbandits) | Delayed-feedback wrapper (Joulani, György & Szepesvári, 2013). | | `DirichletProbe` | re-export of [`opensmartroute.math.dirichlet.DirichletProbe`](#opensmartroutemathdirichlet) | Linear Dirichlet head over a fixed target list. | | `Elo` | re-export of [`opensmartroute.math.preference.Elo`](#opensmartroutemathpreference) | Elo rating — a fixed-step Bradley–Terry with K-factor; handy for fast warm-up. | | `EnergyModel` | re-export of [`opensmartroute.math.energy.EnergyModel`](#opensmartroutemathenergy) | Per-target linear energy model ``wh = e0 + e_in * prompt + e_out * output`` fit by ridge. | | `EpsilonGreedy` | re-export of [`opensmartroute.math.bandits.EpsilonGreedy`](#opensmartroutemathbandits) | Explore uniformly with probability ``epsilon``, otherwise exploit the empirical means. | | `HardwareProfile` | re-export of [`opensmartroute.math.energy.HardwareProfile`](#opensmartroutemathenergy) | Static device characterisation used before measurements exist. | | `IRTModel` | re-export of [`opensmartroute.math.irt.IRTModel`](#opensmartroutemathirt) | Online 2PL IRT: target ability, item difficulty / discrimination via SGD, with forgetting and merge support. | | `IsotonicCalibrator` | re-export of [`opensmartroute.math.calibration.IsotonicCalibrator`](#opensmartroutemathcalibration) | Monotone non-decreasing map score -> P(correct), fitted with PAV. | | `LinUCB` | re-export of [`opensmartroute.math.bandits.LinUCB`](#opensmartroutemathbandits) | Disjoint LinUCB (Li et al., WWW 2010) with Sherman–Morrison updates and optional. | | `MarkovChain` | re-export of [`opensmartroute.math.markov.MarkovChain`](#opensmartroutemathmarkov) | Dirichlet-smoothed transition counts. ``decay`` < 1 multiplies a row's counts by ``decay``. | | `MultiKnapsackBandit` | re-export of [`opensmartroute.math.bandits.MultiKnapsackBandit`](#opensmartroutemathbandits) | Bandits with several knapsack constraints (Badanidiyuru et al., 2013) with the. | | `PageHinkley` | re-export of [`opensmartroute.math.estimators.PageHinkley`](#opensmartroutemathestimators) | Detects a *decrease* in the monitored mean (e.g. quality dropping). | | `RoutingMDP` | re-export of [`opensmartroute.math.markov.RoutingMDP`](#opensmartroutemathmarkov) | Finite-horizon / discounted MDP over conversation states and route actions. | | `TemperatureScaler` | re-export of [`opensmartroute.math.calibration.TemperatureScaler`](#opensmartroutemathcalibration) | Fits :math:`\tau` for ``confidence = softmax(u/\tau)[argmax]`` by 1-D golden-section. | | `ThompsonBeta` | re-export of [`opensmartroute.math.bandits.ThompsonBeta`](#opensmartroutemathbandits) | Beta–Bernoulli Thompson sampling. | | `UCB1` | re-export of [`opensmartroute.math.bandits.UCB1`](#opensmartroutemathbandits) | UCB1: :math:`\hat\mu_a + c\sqrt{\frac{2\ln t}{n_a}}`; untried arms get +inf. | | `Welford` | re-export of [`opensmartroute.math.estimators.Welford`](#opensmartroutemathestimators) | Numerically stable running mean / variance (Welford's algorithm). | | `WindowDrift` | re-export of [`opensmartroute.math.estimators.WindowDrift`](#opensmartroutemathestimators) | ADWIN-lite: compare the first and second half of a sliding window with a. | | `bayesian_average` | re-export of [`opensmartroute.math.estimators.bayesian_average`](#opensmartroutemathestimators) | Shrink a small-sample mean toward a prior: (n·m + k·μ₀)/(n + k). | | `brier_score` | re-export of [`opensmartroute.math.calibration.brier_score`](#opensmartroutemathcalibration) | Mean squared error between confidence and the 0/1 correctness label. | | `conformal_quantile` | re-export of [`opensmartroute.math.calibration.conformal_quantile`](#opensmartroutemathcalibration) | Finite-sample corrected :math:`\lceil (n+1)(1-\alpha)\rceil / n` empirical quantile. | | `digamma` | re-export of [`opensmartroute.math.dirichlet.digamma`](#opensmartroutemathdirichlet) | Digamma :math:`\psi(x)` for x > 0 via recurrence to x >= 6 and the asymptotic series. | | `dominates` | re-export of [`opensmartroute.math.decision.dominates`](#opensmartroutemathdecision) | a dominates b if it is ≥ quality, ≤ cost, ≤ latency and strictly better in one. | | `entropy` | re-export of [`opensmartroute.math.estimators.entropy`](#opensmartroutemathestimators) | Shannon entropy (nats) of a probability vector. | | `erlang_c` | re-export of [`opensmartroute.math.decision.erlang_c`](#opensmartroutemathdecision) | P(an arriving request must wait) for M/M/c. Returns 1.0 if unstable. | | `expected_calibration_error` | re-export of [`opensmartroute.math.estimators.expected_calibration_error`](#opensmartroutemathestimators) | ECE: how well does router confidence predict routing correctness?. | | `expected_wait` | re-export of [`opensmartroute.math.decision.expected_wait`](#opensmartroutemathdecision) | Mean time in queue (Wq) for M/M/c, in the same time unit as the rates. | | `gini` | re-export of [`opensmartroute.math.estimators.gini`](#opensmartroutemathestimators) | Gini impurity ``1 - sum(p^2)``; 0 = certain. | | `hardware_profile` | re-export of [`opensmartroute.math.energy.hardware_profile`](#opensmartroutemathenergy) | Built-in profile by name (``a100-80gb``, ``h100-sxm``, ``l4``, ``rtx-4090``, ``cpu-16c``, ``npu-edge``). | | `item_key` | re-export of [`opensmartroute.math.irt.item_key`](#opensmartroutemathirt) | Default item id: domain × difficulty bucket, e.g. ``legal/3``. | | `kingman_wait` | re-export of [`opensmartroute.math.decision.kingman_wait`](#opensmartroutemathdecision) | Kingman's G/G/1 approximation. | | `littles_law` | re-export of [`opensmartroute.math.decision.littles_law`](#opensmartroutemathdecision) | L = λ·W — average number of in-flight requests. | | `normalized_entropy` | re-export of [`opensmartroute.math.estimators.normalized_entropy`](#opensmartroutemathestimators) | 0 = certain, 1 = uniform. Useful as an 'ask the LLM judge' trigger. | | `pareto_front` | re-export of [`opensmartroute.math.decision.pareto_front`](#opensmartroutemathdecision) | Keys of the non-dominated (quality, cost, latency) points. | | `reliability_diagram` | re-export of [`opensmartroute.math.calibration.reliability_diagram`](#opensmartroutemathcalibration) | Per-bin (mean confidence, empirical accuracy, count) — plot or print it. | | `servers_for_sla` | re-export of [`opensmartroute.math.decision.servers_for_sla`](#opensmartroutemathdecision) | Smallest c such that E[Wq] ≤ max_wait and P(wait) ≤ max_p_wait. | | `sigmoid` | re-export of [`opensmartroute.math.irt.sigmoid`](#opensmartroutemathirt) | Overflow-safe logistic function. | | `softmax` | re-export of [`opensmartroute.math.estimators.softmax`](#opensmartroutemathestimators) | Numerically stable softmax; lower ``temperature`` sharpens the distribution. | | `topsis` | re-export of [`opensmartroute.math.decision.topsis`](#opensmartroutemathdecision) | TOPSIS closeness coefficient in [0,1]; quality is a benefit, cost/latency are costs. | | `weighted_sum` | re-export of [`opensmartroute.math.decision.weighted_sum`](#opensmartroutemathdecision) | Scalarise ``w_q * quality - w_c * norm(cost) - w_l * norm(latency)`` with min-max normalised cost / latency. | | `wilson_interval` | re-export of [`opensmartroute.math.estimators.wilson_interval`](#opensmartroutemathestimators) | Wilson score interval for a binomial proportion (robust at small n). | ## `opensmartroute.math.bandits` Source: src/opensmartroute/math/bandits.py (`src/opensmartroute/math/bandits.py`) Multi-armed and contextual bandits for online routing decisions. | Name | Kind | Summary | |---|---|---| | `Bandit` | class | Common interface. ``context`` is optional; non-contextual learners ignore it. | | `ThompsonBeta` | class | Beta–Bernoulli Thompson sampling. | | `UCB1` | class | UCB1: :math:`\hat\mu_a + c\sqrt{\frac{2\ln t}{n_a}}`; untried arms get +inf. | | `LinUCB` | class | Disjoint LinUCB (Li et al., WWW 2010) with Sherman–Morrison updates and optional. | | `EpsilonGreedy` | class | Explore uniformly with probability ``epsilon``, otherwise exploit the empirical means. | | `CostAwareBandit` | class | Lagrangian budget wrapper (C2MAB-V flavour). | | `MultiKnapsackBandit` | class | Bandits with several knapsack constraints (Badanidiyuru et al., 2013) with the. | | `DelayedFeedback` | class | Delayed-feedback wrapper (Joulani, György & Szepesvári, 2013). | ## `opensmartroute.math.calibration` Source: src/opensmartroute/math/calibration.py (`src/opensmartroute/math/calibration.py`) Calibration and distribution-free risk control for routing confidence. | Name | Kind | Summary | |---|---|---| | `ConformalCalibrator` | class | Split conformal prediction over routing candidates. | | `IsotonicCalibrator` | class | Monotone non-decreasing map score -> P(correct), fitted with PAV. | | `TemperatureScaler` | class | Fits :math:`\tau` for ``confidence = softmax(u/\tau)[argmax]`` by 1-D golden-section. | | `brier_score` | function `(confidences: list[float], hits: list[bool])` | Mean squared error between confidence and the 0/1 correctness label. | | `conformal_quantile` | function `(scores: list[float], alpha: float)` | Finite-sample corrected :math:`\lceil (n+1)(1-\alpha)\rceil / n` empirical quantile. | | `reliability_diagram` | function `(confidences: list[float], hits: list[bool], bins: int=10)` | Per-bin (mean confidence, empirical accuracy, count) — plot or print it. | ## `opensmartroute.math.decision` Source: src/opensmartroute/math/decision.py (`src/opensmartroute/math/decision.py`) Multi-objective decision helpers and queueing theory for real-time routing. | Name | Kind | Summary | |---|---|---| | `dominates` | function `(a: Point, b: Point)` | a dominates b if it is ≥ quality, ≤ cost, ≤ latency and strictly better in one. | | `pareto_front` | function `(points: dict[str, Point])` | Keys of the non-dominated (quality, cost, latency) points. | | `weighted_sum` | function `(points: dict[str, Point], w_q: float, w_c: float, w_l: float)` | Scalarise ``w_q * quality - w_c * norm(cost) - w_l * norm(latency)`` with min-max normalised cost / latency. | | `topsis` | function `(points: dict[str, Point], weights: Sequence[float]=(0.6, 0.25, 0.15))` | TOPSIS closeness coefficient in [0,1]; quality is a benefit, cost/latency are costs. | | `erlang_c` | function `(arrival_rate: float, service_rate: float, servers: int)` | P(an arriving request must wait) for M/M/c. Returns 1.0 if unstable. | | `expected_wait` | function `(arrival_rate: float, service_rate: float, servers: int)` | Mean time in queue (Wq) for M/M/c, in the same time unit as the rates. | | `servers_for_sla` | function `(arrival_rate: float, service_rate: float, max_wait: float, max_p_wait: float=0.2)` | Smallest c such that E[Wq] ≤ max_wait and P(wait) ≤ max_p_wait. | | `littles_law` | function `(arrival_rate: float, mean_time_in_system: float)` | L = λ·W — average number of in-flight requests. | | `kingman_wait` | function `(utilization: float, ca2: float, cs2: float, mean_service: float)` | Kingman's G/G/1 approximation. | ## `opensmartroute.math.dirichlet` Source: src/opensmartroute/math/dirichlet.py (`src/opensmartroute/math/dirichlet.py`) Dirichlet probe over host hidden states (ProbeDirichlet, RouterXBench 2602.11877). | Name | Kind | Summary | |---|---|---| | `DirichletProbe` | class | Linear Dirichlet head over a fixed target list. | | `digamma` | function `(x: float)` | Digamma :math:`\psi(x)` for x > 0 via recurrence to x >= 6 and the asymptotic series. | ## `opensmartroute.math.energy` Source: src/opensmartroute/math/energy.py (`src/opensmartroute/math/energy.py`) Hardware-aware energy characterisation (HW-Router 2608.14575; 2608.28044). | Name | Kind | Summary | |---|---|---| | `EnergyModel` | class | Per-target linear energy model ``wh = e0 + e_in * prompt + e_out * output`` fit by ridge. | | `HardwareProfile` | class | Static device characterisation used before measurements exist. | | `hardware_profile` | function `(name: str)` | Built-in profile by name (``a100-80gb``, ``h100-sxm``, ``l4``, ``rtx-4090``, ``cpu-16c``, ``npu-edge``). | ## `opensmartroute.math.estimators` Source: src/opensmartroute/math/estimators.py (`src/opensmartroute/math/estimators.py`) Streaming estimators, drift detection and calibration. | Name | Kind | Summary | |---|---|---| | `EWMA` | class | Exponentially weighted moving mean and variance with a z-score helper. | | `Welford` | class | Numerically stable running mean / variance (Welford's algorithm). | | `PageHinkley` | class | Detects a *decrease* in the monitored mean (e.g. quality dropping). | | `WindowDrift` | class | ADWIN-lite: compare the first and second half of a sliding window with a. | | `wilson_interval` | function `(successes: float, n: int, z: float=1.96)` | Wilson score interval for a binomial proportion (robust at small n). | | `bayesian_average` | function `(mean: float, n: int, prior_mean: float, prior_n: float=5.0)` | Shrink a small-sample mean toward a prior: (n·m + k·μ₀)/(n + k). | | `softmax` | function `(xs: list[float], temperature: float=1.0)` | Numerically stable softmax; lower ``temperature`` sharpens the distribution. | | `entropy` | function `(ps: list[float])` | Shannon entropy (nats) of a probability vector. | | `normalized_entropy` | function `(ps: list[float])` | 0 = certain, 1 = uniform. Useful as an 'ask the LLM judge' trigger. | | `gini` | function `(ps: list[float])` | Gini impurity ``1 - sum(p^2)``; 0 = certain. | | `expected_calibration_error` | function `(confidences: list[float], hits: list[bool], bins: int=10)` | ECE: how well does router confidence predict routing correctness?. | ## `opensmartroute.math.irt` Source: src/opensmartroute/math/irt.py (`src/opensmartroute/math/irt.py`) Item Response Theory for routing (IRT-Router, ACL 2025). | Name | Kind | Summary | |---|---|---| | `sigmoid` | function `(z: float)` | Overflow-safe logistic function. | | `IRTModel` | class | Online 2PL IRT: target ability, item difficulty / discrimination via SGD, with forgetting and merge support. | | `item_key` | function `(domain: str, complexity: float, buckets: int=4)` | Default item id: domain × difficulty bucket, e.g. ``legal/3``. | ## `opensmartroute.math.markov` Source: src/opensmartroute/math/markov.py (`src/opensmartroute/math/markov.py`) Markov chains and MDPs for conversational / multi-step routing. | Name | Kind | Summary | |---|---|---| | `MarkovChain` | class | Dirichlet-smoothed transition counts. ``decay`` < 1 multiplies a row's counts by ``decay``. | | `RoutingMDP` | class | Finite-horizon / discounted MDP over conversation states and route actions. | ## `opensmartroute.math.preference` Source: src/opensmartroute/math/preference.py (`src/opensmartroute/math/preference.py`) Bradley–Terry pairwise preference model (RouteLLM, Prompt-to-Leaderboard). | Name | Kind | Summary | |---|---|---| | `BradleyTerry` | class | Online Bradley-Terry: per-context target strengths from pairwise wins, with L2 and forgetting. | | `Elo` | class | Elo rating — a fixed-step Bradley–Terry with K-factor; handy for fast warm-up. | ## `opensmartroute.mcp_server` Source: src/opensmartroute/mcp_server.py (`src/opensmartroute/mcp_server.py`) Model Context Protocol server: the router as a set of tools for any IDE or agent. | Name | Kind | Summary | |---|---|---| | `PROTOCOL_VERSION` | constant | : Protocol revision this server speaks by default. | | `SUPPORTED_PROTOCOL_VERSIONS` | constant | : Revisions accepted from clients (the client's choice is echoed when it is one of these). | | `MCPServer` | class | Serve a :class:`Router` (or an enterprise router wrapping one) over MCP. | | `RemoteMCP` | class | Forward JSON-RPC messages to an HTTP MCP endpoint (``POST /mcp``) - the bridge's counterpart of. | | `ToolError` | class | Raised inside a tool: reported to the client as a tool result with ``isError`` (not a protocol error). | | `bridge_stdio` | function `(url: str, api_key: str \| None=None)` | Expose a remote HTTP MCP endpoint as a local stdio server (for clients that only spawn processes). | | `decision_dict` | function `(d: RouteDecision)` | ``RouteDecision.to_dict()`` plus signals and the ranked candidates - what IDE clients want to show. | | `serve_stdio` | function `(server: Any, stdin: IO[bytes] \| None=None, stdout: IO[str] \| None=None)` | Run ``server`` (anything with ``handle_json``) over newline-delimited JSON on stdin/stdout until EOF. | ## `opensmartroute.observability` Source: src/opensmartroute/observability.py (`src/opensmartroute/observability.py`) Tracing and observability: every step of routing, execution and learning as a structured event. | Name | Kind | Summary | |---|---|---| | `EVENT_NAMES` | constant | Router.route. | | `METRIC_PREFIX` | constant | Prometheus metric name prefix (``osr_``). | | `SPAN_NAMES` | constant | : Every span name the SDK opens (an :class:`Event` with ``kind="span"``). | | `TRACEPARENT_KEY` | constant | request.context key (and HTTP header) carrying an inbound W3C trace context. | | `TRACE_ID_HEADER` | constant | response header ``osr serve`` sets to the trace id of the request. | | `Event` | class | One captured span or event: flat, JSON-friendly, never carries request text. | | `EventSink` | class | Receiver port: override :meth:`emit`; live bridges may also implement :meth:`span_start` / :meth:`span_end`. | | `FileSink` | class | Append-only JSONL file, one event per line. | | `LoggingSink` | class | One JSON line per event on the ``opensmartroute.events`` logger (level follows the event). | | `MemorySink` | class | Thread-safe ring buffer of the newest ``max_events`` events; queryable by request, trace, name or level. | | `MetricsSink` | class | Counters and latency percentiles derived from events; :meth:`prometheus` renders the exposition text. | | `Span` | class | An open unit of work; a context manager that records duration, status and nested events. | | `Tracer` | class | Opens spans, records events and fans them out to sinks; ``sample_rate`` < 1 traces a share of requests. | | `configure_tracing` | function `(*sinks: EventSink, sample_rate: float \| None=None, settings: Settings \| None=None)` | Install sinks on the process-wide tracer. With no sinks, use the ones named by settings. | | `current_tracer` | function `()` | The tracer of the innermost open span, else the one bound with :func:`use_tracer`, else the global one. | | `get_tracer` | function `()` | The process-wide tracer (disabled until :func:`configure_tracing` adds sinks). | | `text_digest` | function `(text: str)` | Loggable stand-in for request text: ``{"text_sha256": <16 hex>, "text_len": n}``. | | `use_tracer` | class | ``with use_tracer(t):`` makes ``t`` the tracer that :func:`current_tracer` returns in this context. | ## `opensmartroute.ocm` Source: src/opensmartroute/ocm.py (`src/opensmartroute/ocm.py`) Open Capability Manifest (OCM) - a vendor-neutral description of any routable capability. | Name | Kind | Summary | |---|---|---| | `OCM_KINDS` | constant | : Manifest kinds (identical to :class:`~opensmartroute.TargetKind` values). | | `OCM_PROTOCOLS` | constant | : Endpoint protocols a manifest may declare; ``http`` and ``a2a`` can be bound to executors directly. | | `OCM_VERSION` | constant | : Current manifest version (the ``ocm`` field). | | `bind_endpoint` | function `(target: RouteTarget, region: str \| None=None, **kw: Any)` | Attach an executor for the selected endpoint (``http`` -> :func:`~opensmartroute.adapters.http_handler`,. | | `capability_from_target` | function `(target: RouteTarget)` | Reverse mapping: publish a target as an OCM v1 manifest (``dict``; dump as YAML or JSON). | | `dump_capability` | function `(doc: dict[str, Any])` | Serialise a manifest to YAML when PyYAML is available, else to pretty JSON (both are valid OCM). | | `is_capability` | function `(doc: Any)` | True when ``doc`` looks like an OCM manifest (has an ``ocm`` version field). | | `load_capabilities` | function `(paths: Iterable[str \| Path] \| str \| Path, *, strict: bool=True)` | Load manifests from files and/or directories (``**/capability.{yaml,yml,json}``). | | `load_capability` | function `(path: str \| Path, *, strict: bool=True)` | Load one ``capability.yaml`` / ``.json`` manifest as a target. | | `select_endpoint` | function `(target: RouteTarget, region: str \| None=None)` | The manifest endpoint to use: a region-matching one first, then the first region-less one. | | `target_from_capability` | function `(doc: dict[str, Any], *, strict: bool=True)` | Convert a manifest into a :class:`~opensmartroute.RouteTarget` (validating first when ``strict``). | | `validate_capability` | function `(doc: Any)` | Validate a manifest; returns a list of human-readable problems (empty = valid). | ## `opensmartroute.policy` Source: src/opensmartroute/policy/__init__.py (`src/opensmartroute/policy/__init__.py`) Policy layer: hard constraints that are never traded off against utility. | Name | Kind | Summary | |---|---|---| | `DataBoundaryRule` | class | The target's boundary must be at least as strict as the request's (public < private < on_prem). | | `JailbreakRule` | class | Risky prompts may only reach humans or targets tagged as safe. | | `LanguageRule` | class | The detected language must be declared by the target, unless it declares the wildcard language. | | `Policy` | class | Ordered chain of :data:`PolicyRule`; returns the first rejection reason or ``None``. | | `PolicyRule` | constant | A hard-constraint check: return a rejection reason, or None to let the target through. | | `allow_list` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | When the request names ``allow_targets``, reject everything else. | | `allowed_kinds` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Reject kinds outside the request's ``allowed_kinds``. | | `context_window` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Reject when the estimated input exceeds the target's ``context_window``. | | `cost_budget` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Reject targets whose unit cost exceeds the request's ``max_cost_per_1k``. | | `default_rules` | function `(settings: PolicySettings \| None=None)` | The built-in chain, in evaluation order (cheap identity checks first). | | `deny_list` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Reject targets listed in the request's ``deny_targets``. | | `enabled` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Reject disabled targets. | | `input_tokens` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Reject when the estimated input exceeds the target's ``max_tokens_in``. | | `latency_slo` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Reject targets whose declared latency exceeds the request's ``max_latency_ms``. | | `modalities` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Every modality detected in the request must be supported by the target. | | `pii` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Requests flagged as containing PII may only reach targets with ``pii_allowed``. | | `region` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | The request's ``region`` must be one the target serves (targets with no regions serve all). | | `rule_name` | function `(rule: PolicyRule)` | Display name of a rule: its ``name`` attribute, else ``__name__``, else the class name. | | `tenant` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | The request's ``tenant`` must be permitted by targets that restrict tenants. | | `tools` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | When tools are required (constraint or ``context['tools']``), LLM targets must ``supports_tools``. | ## `opensmartroute.realtime` Source: src/opensmartroute/realtime/__init__.py (`src/opensmartroute/realtime/__init__.py`) Real-time operational controls: health, circuit breaking, rate & budget limits. | Name | Kind | Summary | |---|---|---| | `BreakerState` | class | Circuit-breaker states: closed (healthy), open (tripped), half_open (probing recovery). | | `CircuitBreaker` | class | Classic three-state breaker with a sliding failure window. | | `TokenBucket` | class | Rate limiter: ``rate`` tokens/sec, burst up to ``capacity``. Thread-safe. | | `Budget` | class | Rolling spend cap (e.g. USD per hour) per target or tenant. | | `LatencyWindow` | class | Rolling window of the last ``size`` latencies with nearest-rank percentiles (p50 / p90 / p99). | | `TargetHealth` | class | Live health of one target: breaker, latency EWMA + percentiles, success counts, optional rate limit / budget. | | `HealthRegistry` | class | Tracks health per target id. Shared by policy + strategy + executor. | | `HealthPolicy` | class | Policy that additionally rejects targets whose breaker is open, whose rate. | | `HealthStrategy` | class | Soft signal: observed reliability x latency-SLO fit from live health data. | ## `opensmartroute.retrieval` Source: src/opensmartroute/retrieval.py (`src/opensmartroute/retrieval.py`) Retrieval-based candidate narrowing for very large target pools (ToolRet / Skill-RAG). | Name | Kind | Summary | |---|---|---| | `BM25Index` | class | In-memory BM25 (Okapi) index over target documents. | | `DenseIndex` | class | Cosine index. Default = sparse signed-hashing features with an inverted index (pure. | | `NarrowingStats` | class | Counters kept by the retrieval middleware: calls, how often it narrowed, last pool and kept sizes. | | `RetrievalResult` | class | Narrowed candidate ids with fused scores and how many came from the lexical / dense legs. | | `Retriever` | class | Hybrid lexical + dense narrowing that tracks a registry (or an explicit pool). | | `execute_tool_target` | function `(registry: TargetRegistry, allow: Callable[[RouteTarget, dict[str, Any]], bool] \| None=None, target_id: str='execute_tool')` | A *tool that runs a tool by id* (with an optional allow-policy hook). | | `narrow_signals_hint` | function `(signals: Signals)` | Extra lexical hints from signals (domains / actions) appended to the retrieval query. | | `rrf` | function `(rankings: list[list[tuple[str, float]]], k: int=60, weights: list[float] \| None=None)` | Reciprocal Rank Fusion over several ranked lists of ``(id, score)``. | | `select_skill_set` | function `(request: RouteRequest \| str, pool: list[RouteTarget], k: int=3, embedder: Embedder \| None=None, redundancy: float=0.7, min_gain: float=0.02, relevance: dict[str, float] \| None=None)` | Greedy facility-location selection of complementary targets. | | `target_text` | function `(t: RouteTarget)` | Lexical document for a target: id, name, description, capabilities and up to 8 examples. | | `tokenize` | function `(text: str)` | Lower-case alphanumeric tokens. | | `tool_search_target` | function `(retriever: Retriever, registry: TargetRegistry, kinds: tuple[str, ...]=('tool', 'skill'), k: int=8, target_id: str='tool_search')` | A *tool that finds tools*: returns compact descriptors for the ``k`` best matches. | ## `opensmartroute.router` Source: src/opensmartroute/router.py (`src/opensmartroute/router.py`) The Router: signals -> policy -> strategies -> ensemble -> decision (+plan). | Name | Kind | Summary | |---|---|---| | `Router` | class | Signals -> policy -> strategies -> ensemble -> decision (+ optional plan). | | `NoRouteError` | re-export of [`opensmartroute.errors.NoRouteError`](#opensmartrouteerrors) | No target satisfied the hard constraints. | | `DEFAULT_WEIGHTS` | constant | : Library-default ensemble weights (``Settings().weights``); kept for backwards compatibility. | ## `opensmartroute.sdk` Source: src/opensmartroute/sdk.py (`src/opensmartroute/sdk.py`) OpenSmartRoute SDK: decorator-driven registration of routing components. | Name | Kind | Summary | |---|---|---| | `ComponentKind` | class | The component families a :class:`ComponentRegistry` can hold. | | `ComponentRegistry` | class | Blueprints for every routing component, with decorators that register into it. | | `FunctionMiddleware` | class | Adapts ``fn(request, next_) -> RouteDecision``. | | `FunctionSignal` | class | Adapts ``fn(request, signals) -> None \| {field: value}``. | | `FunctionStrategy` | class | Adapts ``fn(request, signals, candidates) -> {target_id: score \| StrategyScore}``. | | `Registration` | class | A registered blueprint. ``factory()`` returns a fresh component instance. | | `agent` | constant | @agent(id, ...): shorthand for an ``agent`` target. | | `components` | constant | : The process-wide registry that the top-level decorators (``opensmartroute.strategy`` ...) bind to. | | `middleware` | constant | @middleware: register a Middleware class or ``fn(request, next_route)``. | | `policy_rule` | constant | @policy_rule: register ``fn(target, request, signals) -> reason \| None``. | | `signal` | constant | @signal: register a SignalExtractor class or ``fn(request, signals) -> mapping``. | | `skill` | constant | @skill(id, ...): shorthand for a ``skill`` target. | | `strategy` | constant | @strategy(weight=, name=): register a Strategy class or ``fn(request, signals, candidates)``. | | `target` | constant | @target(id, kind, ...): the decorated callable becomes a RouteTarget handler. | | `telemetry` | constant | @telemetry: register a Telemetry sink class or factory. | | `tool` | constant | @tool(id, ...): shorthand for a ``tool`` target. | ## `opensmartroute.security` Source: src/opensmartroute/security/__init__.py (`src/opensmartroute/security/__init__.py`) Security controls for the routing control plane. | Name | Kind | Summary | |---|---|---| | `GadgetDetector` | re-export of [`opensmartroute.security.gadget.GadgetDetector`](#opensmartroutesecuritygadget) | Learned tail classifier. ``score(text)`` in [0, 1]; ``split(text)`` finds the gadget tail. | | `GuardMiddleware` | class | Applies :class:`InputGuard` (+ optional redaction) before routing. | | `GuardReport` | class | Outcome of :meth:`InputGuard.inspect`: pass / fail, reasons, gadget suspicion score and the cleaned text. | | `InputGuard` | class | Validates and normalises request text. Cheap: O(len(text)). | | `OriginPolicy` | re-export of [`opensmartroute.security.provenance.OriginPolicy`](#opensmartroutesecurityprovenance) | Decides which tool arguments must be user-originated and verifies them. | | `OriginRule` | re-export of [`opensmartroute.security.provenance.OriginRule`](#opensmartroutesecurityprovenance) | Per-target override. ``sensitive=None`` = infer from parameter names. | | `OriginViolation` | re-export of [`opensmartroute.security.provenance.OriginViolation`](#opensmartroutesecurityprovenance) | Raised by :class:`OriginPolicy` when a sensitive argument of a state-changing tool comes from untrusted text. | | `Redactor` | class | Replace PII with typed placeholders, e.g. ````. Reversible per-request. | | `ResourceLimitExceeded` | re-export of [`opensmartroute.security.limits.ResourceLimitExceeded`](#opensmartroutesecuritylimits) | A task went over one of its :class:`ResourceLimits` (steps, tool calls, depth, tokens, cost, wall time). | | `ResourceLimitMiddleware` | re-export of [`opensmartroute.security.limits.ResourceLimitMiddleware`](#opensmartroutesecuritylimits) | Charge one step (+ the request's token estimate) per ``route()`` call. | | `ResourceLimiter` | re-export of [`opensmartroute.security.limits.ResourceLimiter`](#opensmartroutesecuritylimits) | Thread-safe per-task accounting against :class:`ResourceLimits`. | | `ResourceLimits` | re-export of [`opensmartroute.security.limits.ResourceLimits`](#opensmartroutesecuritylimits) | Per-task ceilings that stop runaway agents; enforced by :class:`ResourceLimiter`. | | `SafetyCase` | re-export of [`opensmartroute.security.safety.SafetyCase`](#opensmartroutesecuritysafety) | One red-team scenario: an adversarial request, its clean baseline and the routing invariants to check. | | `apply_limits` | re-export of [`opensmartroute.security.limits.apply_limits`](#opensmartroutesecuritylimits) | Wrap handlers of the given kinds. Returns the number wrapped. | | `apply_origin_policy` | re-export of [`opensmartroute.security.provenance.apply_origin_policy`](#opensmartroutesecurityprovenance) | Wrap every state-changing target in ``registry``. Returns the number wrapped. | | `description_risk` | re-export of [`opensmartroute.security.injection.description_risk`](#opensmartroutesecurityinjection) | Risk of a *tool/agent description*: max of injection lexicon and learned gadget score. | | `guard_handler` | re-export of [`opensmartroute.security.provenance.guard_handler`](#opensmartroutesecurityprovenance) | Return a copy of ``target`` whose handler enforces ``policy`` before invoking the tool. | | `injection_risk` | re-export of [`opensmartroute.security.injection.injection_risk`](#opensmartroutesecurityinjection) | Shortcut for ``inspect_injection(text).score``. | | `inspect_injection` | re-export of [`opensmartroute.security.injection.inspect_injection`](#opensmartroutesecurityinjection) | Score instruction-injection likelihood with the matched lexicon entries for the trace. | | `limit_handler` | re-export of [`opensmartroute.security.limits.limit_handler`](#opensmartroutesecuritylimits) | Copy of ``target`` whose handler charges one tool call (and nesting depth) per invocation. | | `load_secret` | function `(name: str, *, file_env_suffix: str='_FILE', default: str \| None=None)` | 12-factor secret loading: ``NAME`` env var, else the file at ``NAME_FILE`` (k8s/Docker secrets). | | `mark_untrusted` | re-export of [`opensmartroute.security.provenance.mark_untrusted`](#opensmartroutesecurityprovenance) | Record content that entered the request from a non-user source. | | `run_safety_suite` | re-export of [`opensmartroute.security.safety.run_safety_suite`](#opensmartroutesecuritysafety) | Run every case through ``route`` and return pass/fail details grouped by category. | | `sanitize_for_prompt` | function `(text: str, max_len: int=4000)` | Make user text safe to embed in an LLM-judge prompt. | | `shannon_entropy` | function `(s: str)` | Character-level Shannon entropy in bits (high values flag encoded / random payloads). | | `strip_steering` | re-export of [`opensmartroute.security.injection.strip_steering`](#opensmartroutesecurityinjection) | Remove sentences that instruct the *router* (self-declared complexity, "use the best. | | `synthesize_gadget_corpus` | re-export of [`opensmartroute.security.gadget.synthesize_gadget_corpus`](#opensmartroutesecuritygadget) | Labelled ``(text, label)`` rows: clean prompts + prompts with an appended gadget. | ## `opensmartroute.security.gadget` Source: src/opensmartroute/security/gadget.py (`src/opensmartroute/security/gadget.py`) Learned confounder-gadget detector (Rerouting LLM Routers, Shafran et al. 2025). | Name | Kind | Summary | |---|---|---| | `CLEAN` | constant | class labels used by the detector and the synthetic corpus. | | `GADGET` | constant | class labels used by the detector and the synthetic corpus. | | `GadgetDetector` | class | Learned tail classifier. ``score(text)`` in [0, 1]; ``split(text)`` finds the gadget tail. | | `synthesize_gadget_corpus` | function `(per_template: int=2, n_gadgets: int=260, seed: int=0)` | Labelled ``(text, label)`` rows: clean prompts + prompts with an appended gadget. | | `synthesize_gadgets` | function `(n: int, seed: int=0)` | Adversarial suffixes drawn from the gadget families described in the paper. | | `tail_features` | function `(tokens: Sequence[str])` | Hand-crafted statistics of a token window (all in [0, 1]) – complements hashed n-grams. | ## `opensmartroute.security.injection` Source: src/opensmartroute/security/injection.py (`src/opensmartroute/security/injection.py`) Instruction-injection detection for *text that is not the user's request*. | Name | Kind | Summary | |---|---|---| | `InjectionReport` | class | Instruction-injection score in [0, 1] plus the lexicon hits that produced it. | | `description_risk` | function `(text: str, gadget_score: float \| None=None)` | Risk of a *tool/agent description*: max of injection lexicon and learned gadget score. | | `injection_risk` | function `(text: str)` | Shortcut for ``inspect_injection(text).score``. | | `inspect_injection` | function `(text: str)` | Score instruction-injection likelihood with the matched lexicon entries for the trace. | ## `opensmartroute.security.limits` Source: src/opensmartroute/security/limits.py (`src/opensmartroute/security/limits.py`) Resource-amplification limits ("Beyond Max Tokens"). | Name | Kind | Summary | |---|---|---| | `ResourceLimitExceeded` | class | A task went over one of its :class:`ResourceLimits` (steps, tool calls, depth, tokens, cost, wall time). | | `ResourceLimitMiddleware` | class | Charge one step (+ the request's token estimate) per ``route()`` call. | | `ResourceLimiter` | class | Thread-safe per-task accounting against :class:`ResourceLimits`. | | `ResourceLimits` | class | Per-task ceilings that stop runaway agents; enforced by :class:`ResourceLimiter`. | | `TaskUsage` | class | Running consumption of one task (steps, tool calls, depth, tokens, cost, timestamps). | | `apply_limits` | function `(registry: TargetRegistry, limiter: ResourceLimiter, kinds: tuple[str, ...]=('tool', 'agent', 'workflow'))` | Wrap handlers of the given kinds. Returns the number wrapped. | | `limit_handler` | function `(target: RouteTarget, limiter: ResourceLimiter)` | Copy of ``target`` whose handler charges one tool call (and nesting depth) per invocation. | | `task_id_of` | function `(request: RouteRequest, key: str='task_id')` | ``context[key]`` when present, otherwise the request id (each request is its own task). | ## `opensmartroute.security.provenance` Source: src/opensmartroute/security/provenance.py (`src/opensmartroute/security/provenance.py`) Origin (provenance) policy for tool parameters – ROPE-style control-flow integrity. | Name | Kind | Summary | |---|---|---| | `OriginFinding` | class | Where one tool argument's value came from (user, context, untrusted content or unknown). | | `OriginPolicy` | class | Decides which tool arguments must be user-originated and verifies them. | | `OriginReport` | class | Provenance check of a tool call: all findings plus the sensitive parameters with a disallowed origin. | | `OriginRule` | class | Per-target override. ``sensitive=None`` = infer from parameter names. | | `OriginViolation` | class | Raised by :class:`OriginPolicy` when a sensitive argument of a state-changing tool comes from untrusted text. | | `SENSITIVE_PARAM_HINTS` | constant | Parameter-name fragments treated as sensitive when a target has no explicit OriginRule. | | `STATE_CHANGING_ACTIONS` | constant | Verbs in a tool's id / description / actions that mark it as state-changing (side effects). | | `apply_origin_policy` | function `(registry: TargetRegistry, policy: OriginPolicy)` | Wrap every state-changing target in ``registry``. Returns the number wrapped. | | `guard_handler` | function `(target: RouteTarget, policy: OriginPolicy, arguments_key: str='tool_arguments')` | Return a copy of ``target`` whose handler enforces ``policy`` before invoking the tool. | | `mark_untrusted` | function `(request: RouteRequest, text: str, source: str='retrieved')` | Record content that entered the request from a non-user source. | | `untrusted_texts` | function `(request: RouteRequest)` | ``(source, text)`` pairs recorded by :func:`mark_untrusted` on this request. | | `user_texts` | function `(request: RouteRequest)` | Everything the user actually typed: current text, prior user turns and the pre-guard original text. | ## `opensmartroute.security.safety` Source: src/opensmartroute/security/safety.py (`src/opensmartroute/security/safety.py`) Safety-routing regression suite ("When Safety Routing Breaks"). | Name | Kind | Summary | |---|---|---| | `SafetyCase` | class | One red-team scenario: an adversarial request, its clean baseline and the routing invariants to check. | | `SafetyResult` | class | Verdict for one :class:`SafetyCase`: chosen vs baseline target and the invariants that failed. | | `default_cases` | function `(seed: int=0)` | Deployment-agnostic red-team cases; extend with catalogue-specific ones. | | `run_safety_suite` | function `(route: RouteCall, cases: Sequence[SafetyCase] \| None=None, *, seed: int=0)` | Run every case through ``route`` and return pass/fail details grouped by category. | ## `opensmartroute.server` Source: src/opensmartroute/server.py (`src/opensmartroute/server.py`) Optional FastAPI server exposing the router over HTTP. | Name | Kind | Summary | |---|---|---| | `AUTO_SLUG` | constant | : Slug prefix of the router's own pseudo-models on the OpenAI-compatible proxy (``osr/auto``). | | `DEFAULT_PROXY_ALIASES` | constant | : Model names that mean "let the router choose" on the OpenAI-compatible proxy. | | `AUTO_VARIANTS` | constant | : ``osr/auto:`` presets: objective weights, hard constraints and allowed kinds. | | `APP_HEADER` | constant | : Request header naming the calling application (OpenRouter-style attribution); echoed in metadata. | | `TARGET_HEADER` | constant | : Response headers carrying the decision (target id, request id) beside the OpenAI-shaped body. | | `REQUEST_ID_HEADER` | constant | : Response headers carrying the decision (target id, request id) beside the OpenAI-shaped body. | | `OPEN_PATHS` | constant | : Paths that never require a token when access control is on (probes, metrics, token check, OpenAPI pages). | | `UNTRACED_PATHS` | constant | : Paths that never open an ``http.request`` span (probes and the observability endpoints themselves). | | `bearer_token` | function `(headers: Any)` | The access token of a request: ``X-API-Key`` first, else ``Authorization: Bearer ``. | | `token_accepted` | function `(token: str \| None, tokens: Iterable[str])` | Constant-time membership test of ``token`` in the configured access tokens. | | `create_app` | function `(router: Any, proxy_aliases: frozenset[str]=DEFAULT_PROXY_ALIASES, autopilot: Any=None, auth_tokens: Iterable[str]=())` | FastAPI app: ``/route``, ``/feedback``, ``/targets``, ``/stats``, ``/healthz`` and the OpenAI-compatible ``/v1``. | | `resolve_model` | function `(model: str, aliases: frozenset[str]=DEFAULT_PROXY_ALIASES)` | Split a proxy ``model`` into ``(pinned target id \| None, route options)``. | | `proxy_request` | function `(body: dict[str, Any], aliases: frozenset[str]=frozenset({'auto'}), app: str \| None=None)` | Turn an OpenAI chat-completion body into a :class:`RouteRequest`. | | `proxy_response` | function `(decision: RouteDecision, result: Any, request: RouteRequest \| None=None)` | Shape an execution result as an OpenAI ``chat.completion`` object (``model`` = chosen target id). | ## `opensmartroute.settings` Source: src/opensmartroute/settings.py (`src/opensmartroute/settings.py`) Typed, environment-overridable settings: the only home for OpenSmartRoute's tunable constants. | Name | Kind | Summary | |---|---|---| | `BanditSettings` | class | Thompson-sampling strategy (:class:`~opensmartroute.BanditStrategy`). | | `CapabilitySettings` | class | Capability-fit strategy (:class:`~opensmartroute.CapabilityStrategy`). | | `ObservabilitySettings` | class | Tracing and event capture (:mod:`opensmartroute.observability`); read by ``Tracer.from_settings``. | | `PolicySettings` | class | Hard-constraint thresholds (read by :class:`~opensmartroute.Policy`). | | `RoutingSettings` | class | Ensemble, confidence and plan composition (read by :class:`~opensmartroute.Router`). | | `RulesSettings` | class | Declarative rules strategy (:class:`~opensmartroute.RulesStrategy`). | | `SLMSettings` | class | Routing SLM, dataset collection and the self-improvement loop (:mod:`opensmartroute.learning.slm`). | | `ServerSettings` | class | ``osr serve`` (:mod:`opensmartroute.server`): access control of the self-hosted HTTP API. | | `Settings` | class | All tunables, grouped by consumer. Immutable; derive variants with :meth:`replace`. | | `WeightSettings` | class | Ensemble weight per strategy name (looked up as ``weights[strategy.name]``). | | `configure` | function `(settings: Settings \| None=None, **groups: Any)` | Install process-wide settings. ``configure()`` with no arguments re-reads the environment;. | | `get_settings` | function `()` | The process-wide :class:`Settings` (environment overlay applied once, lazily). | | `resolve` | function `(settings: Settings \| None)` | ``settings`` if given, else the process-wide settings (component constructors use this). | ## `opensmartroute.signals` Source: src/opensmartroute/signals/__init__.py (`src/opensmartroute/signals/__init__.py`) Signal extraction: cheap, deterministic features computed from the request. | Name | Kind | Summary | |---|---|---| | `ACTION_LEXICON` | constant | Action label -> trigger phrases; the keys are the ontology action names (summarize, translate, ... escalate). | | `DEFAULT_EXTRACTORS` | constant | after domain detection (uses domain bonus). | | `DEFAULT_ONTOLOGY` | re-export of [`opensmartroute.signals.ontology.DEFAULT_ONTOLOGY`](#opensmartroutesignalsontology) | the built-in TASK_TYPES ontology used by TaskTypeSignal. | | `DOMAIN_LEXICON` | constant | Domain label -> trigger phrases; the keys are the ontology domain names targets and skills may declare. | | `EVENT_LEXICON` | re-export of [`opensmartroute.signals.events.EVENT_LEXICON`](#opensmartroutesignalsevents) | Event name -> (domains, actions). Keys are matched exactly, then by ``subject.*`` prefix. | | `EVENT_SUBJECTS` | re-export of [`opensmartroute.signals.events.EVENT_SUBJECTS`](#opensmartroutesignalsevents) | Generic fallbacks when the exact event / prefix is unknown: subject -> domain, verb -> action. | | `EVENT_VERBS` | re-export of [`opensmartroute.signals.events.EVENT_VERBS`](#opensmartroutesignalsevents) | event verb -> action when the exact event / prefix is unknown. | | `TASK_PRIORS` | re-export of [`opensmartroute.signals.models.TASK_PRIORS`](#opensmartroutesignalsmodels) | name: (difficulty, reasoning_need, expected_output_tokens). | | `TASK_TYPES` | re-export of [`opensmartroute.signals.ontology.TASK_TYPES`](#opensmartroutesignalsontology) | ---------------------------------------------------------------- transformation. | | `ComplexitySignal` | class | Hybrid-LLM-style difficulty estimate in [0, 1]. | | `DomainActionSignal` | class | Arch-Router-style domain / action detection via lexicon matching. | | `DraftResponseSignal` | re-export of [`opensmartroute.signals.uncertainty.DraftResponseSignal`](#opensmartroutesignalsuncertainty) | Query-response mixed representation: run a cheap drafter and expose draft features. | | `EventInfo` | re-export of [`opensmartroute.signals.events.EventInfo`](#opensmartroutesignalsevents) | Parsed event: raw name, subject, verb and the domains / actions it implies. | | `EventSignal` | re-export of [`opensmartroute.signals.events.EventSignal`](#opensmartroutesignalsevents) | Domains / actions from ``context["event"]`` and ``context["intent"]`` (event-driven requests). | | `EventTrigger` | re-export of [`opensmartroute.signals.uncertainty.EventTrigger`](#opensmartroutesignalsuncertainty) | Event-triggered invocation: evaluate uncertainty features against rules and return the. | | `HashedClassifier` | re-export of [`opensmartroute.signals.models.HashedClassifier`](#opensmartroutesignalsmodels) | Multinomial logistic regression over hashed features (sparse weights per class). | | `HashedFeaturizer` | re-export of [`opensmartroute.signals.models.HashedFeaturizer`](#opensmartroutesignalsmodels) | Hashing-trick sparse features: words, bigrams, character n-grams and a few numeric text statistics. | | `HashedRegressor` | re-export of [`opensmartroute.signals.models.HashedRegressor`](#opensmartroutesignalsmodels) | Squared-loss linear regressor on hashed features; output clipped to [lo, hi]. | | `HistorySignal` | class | Conversation-state features from ``request.history`` (RCRouter-style):. | | `LanguageSignal` | class | ``language`` from script / stop-word hints (``LANGUAGE_HINTS``); defaults to ``en``. | | `LearnedDifficultySignal` | class | Blend the heuristic complexity with a trained regressor (Hybrid-LLM style difficulty). | | `LengthSignal` | class | ``token_estimate`` from text + history length (about 4 characters per token). | | `ModalitySignal` | class | ``modalities`` from context keys (``images`` / ``image_url``, ``audio``, ``files``) on top of ``text``. | | `OutputLengthSignal` | class | Expected output tokens (drives cost estimates and effort/max_tokens choices). | | `ProfileSignal` | class | User-profile features (``request.profile``): tier, expertise, preferences. | | `ReasoningNeedSignal` | class | How much a request benefits from extended thinking (ThinkSwitcher / Sketch-of-Thought). | | `SensitivitySignal` | class | PII and prompt-injection / jailbreak heuristics (vLLM-semantic-router-style). | | `SignalExtractor` | class | Fills in part of a :class:`Signals` object. | | `SignalModelBundle` | re-export of [`opensmartroute.signals.models.SignalModelBundle`](#opensmartroutesignalsmodels) | All learned signal models together, persisted as one JSON document. | | `TaskOntology` | re-export of [`opensmartroute.signals.ontology.TaskOntology`](#opensmartroutesignalsontology) | Lookup helpers over :data:`TASK_TYPES`. | | `TaskType` | re-export of [`opensmartroute.signals.ontology.TaskType`](#opensmartroutesignalsontology) | One leaf of the task ontology: family, description, the actions it maps to and template phrasings. | | `TaskTypeSignal` | class | Ontology task type. Uses the learned classifier when one is loaded, else maps the. | | `TriggerRule` | re-export of [`opensmartroute.signals.uncertainty.TriggerRule`](#opensmartroutesignalsuncertainty) | ``feature >= threshold`` (or ``<=`` when ``below=True``) fires ``action``. | | `UncertaintyGate` | re-export of [`opensmartroute.signals.uncertainty.UncertaintyGate`](#opensmartroutesignalsuncertainty) | A cascade quality gate built from response uncertainty. | | `VerbalisedDifficultySignal` | re-export of [`opensmartroute.signals.uncertainty.VerbalisedDifficultySignal`](#opensmartroutesignalsuncertainty) | Blend a verbalised difficulty into ``complexity`` and ``reasoning_need``. | | `WorkflowSignal` | re-export of [`opensmartroute.signals.events.WorkflowSignal`](#opensmartroutesignalsevents) | Detect a workflow trigger (``context["workflow"]`` or "run the workflow\|process\|..."). | | `extract_signals` | function `(request: RouteRequest, extractors: list[SignalExtractor] \| None=None)` | Run the extractor chain (``DEFAULT_EXTRACTORS`` unless given) and return the populated :class:`Signals`. | | `learned_extractors` | function `(bundle: SignalModelBundle)` | Extractor pipeline with the trained :class:`SignalModelBundle` plugged in. | | `load_training_rows` | re-export of [`opensmartroute.signals.models.load_training_rows`](#opensmartroutesignalsmodels) | Read JSONL training rows. Accepts eval-dataset rows too (``prompt``/``text``,. | | `parse_difficulty` | re-export of [`opensmartroute.signals.uncertainty.parse_difficulty`](#opensmartroutesignalsuncertainty) | Map a verbalised difficulty (number, ``"7/10"``, ``"hard"``) to [0, 1]; ``None`` if unparseable. | | `parse_event` | re-export of [`opensmartroute.signals.events.parse_event`](#opensmartroutesignalsevents) | Map an event name (``subject.verb``, ``subject:verb`` or ``subject_verb``) onto domains / actions. | | `response_uncertainty` | re-export of [`opensmartroute.signals.uncertainty.response_uncertainty`](#opensmartroutesignalsuncertainty) | Post-hoc uncertainty features for a set of sampled answers. | | `semantic_entropy` | re-export of [`opensmartroute.signals.uncertainty.semantic_entropy`](#opensmartroutesignalsuncertainty) | Entropy (nats) over meaning clusters of sampled answers; 0 when every sample agrees. | | `synthesize_dataset` | re-export of [`opensmartroute.signals.models.synthesize_dataset`](#opensmartroutesignalsmodels) | Generate labelled prompts from ontology templates x topics with light noise. | ## `opensmartroute.signals.events` Source: src/opensmartroute/signals/events.py (`src/opensmartroute/signals/events.py`) Event- and workflow-driven signals for agentic inputs. | Name | Kind | Summary | |---|---|---| | `EVENT_LEXICON` | constant | Event name -> (domains, actions). Keys are matched exactly, then by ``subject.*`` prefix. | | `EVENT_SUBJECTS` | constant | Generic fallbacks when the exact event / prefix is unknown: subject -> domain, verb -> action. | | `EVENT_VERBS` | constant | event verb -> action when the exact event / prefix is unknown. | | `EventInfo` | class | Parsed event: raw name, subject, verb and the domains / actions it implies. | | `EventSignal` | class | Domains / actions from ``context["event"]`` and ``context["intent"]`` (event-driven requests). | | `WorkflowSignal` | class | Detect a workflow trigger (``context["workflow"]`` or "run the workflow\|process\|..."). | | `parse_event` | function `(name: str)` | Map an event name (``subject.verb``, ``subject:verb`` or ``subject_verb``) onto domains / actions. | ## `opensmartroute.signals.models` Source: src/opensmartroute/signals/models.py (`src/opensmartroute/signals/models.py`) Learned signal models: hashed n-gram linear models with no dependencies. | Name | Kind | Summary | |---|---|---| | `TASK_PRIORS` | constant | name: (difficulty, reasoning_need, expected_output_tokens). | | `HashedClassifier` | class | Multinomial logistic regression over hashed features (sparse weights per class). | | `HashedFeaturizer` | class | Hashing-trick sparse features: words, bigrams, character n-grams and a few numeric text statistics. | | `HashedRegressor` | class | Squared-loss linear regressor on hashed features; output clipped to [lo, hi]. | | `SignalModelBundle` | class | All learned signal models together, persisted as one JSON document. | | `load_training_rows` | function `(path: str \| Path)` | Read JSONL training rows. Accepts eval-dataset rows too (``prompt``/``text``,. | | `synthesize_dataset` | function `(ontology: TaskOntology=DEFAULT_ONTOLOGY, topics: Sequence[str] \| None=None, per_template: int=6, seed: int=0)` | Generate labelled prompts from ontology templates x topics with light noise. | ## `opensmartroute.signals.ontology` Source: src/opensmartroute/signals/ontology.py (`src/opensmartroute/signals/ontology.py`) Task ontology: families -> types -> subtypes, with an orthogonal *domain* axis. | Name | Kind | Summary | |---|---|---| | `DEFAULT_ONTOLOGY` | constant | the built-in TASK_TYPES ontology used by TaskTypeSignal. | | `TASK_TYPES` | constant | ---------------------------------------------------------------- transformation. | | `TaskOntology` | class | Lookup helpers over :data:`TASK_TYPES`. | | `TaskType` | class | One leaf of the task ontology: family, description, the actions it maps to and template phrasings. | ## `opensmartroute.signals.uncertainty` Source: src/opensmartroute/signals/uncertainty.py (`src/opensmartroute/signals/uncertainty.py`) Uncertainty signals that come from *outside the query text*. | Name | Kind | Summary | |---|---|---| | `HEDGES` | constant | Hedging phrases counted in a draft response (uncertainty evidence). | | `SELF_CORRECTIONS` | constant | Self-correction markers counted in a draft response. | | `DraftResponseSignal` | class | Query-response mixed representation: run a cheap drafter and expose draft features. | | `EventTrigger` | class | Event-triggered invocation: evaluate uncertainty features against rules and return the. | | `TriggerRule` | class | ``feature >= threshold`` (or ``<=`` when ``below=True``) fires ``action``. | | `UncertaintyGate` | class | A cascade quality gate built from response uncertainty. | | `VerbalisedDifficultySignal` | class | Blend a verbalised difficulty into ``complexity`` and ``reasoning_need``. | | `draft_features` | function `(text: str, draft: str, expected_tokens: int=0)` | Features of a cheap draft answer relative to the query: hedging, refusal, self-correction,. | | `parse_difficulty` | function `(value: Any)` | Map a verbalised difficulty (number, ``"7/10"``, ``"hard"``) to [0, 1]; ``None`` if unparseable. | | `response_uncertainty` | function `(samples: list[str], embedder: Embedder \| None=None, threshold: float=0.85, p_true: float \| None=None)` | Post-hoc uncertainty features for a set of sampled answers. | | `semantic_clusters` | function `(samples: Iterable[str], embedder: Embedder \| None=None, threshold: float=0.85)` | Greedy single-link clustering of answers into meaning classes; returns a cluster id per sample. | | `semantic_entropy` | function `(samples: Iterable[str], embedder: Embedder \| None=None, threshold: float=0.85)` | Entropy (nats) over meaning clusters of sampled answers; 0 when every sample agrees. | ## `opensmartroute.stack` Source: src/opensmartroute/stack.py (`src/opensmartroute/stack.py`) Declarative *stacks*: one document that describes a whole routing setup. | Name | Kind | Summary | |---|---|---| | `REGISTRY_SCHEME` | constant | : Scheme of marketplace references inside ``imports`` (``registry://[@]``). | | `STACK_VERSION` | constant | : Current stack document version (the ``osr`` field). | | `Resolver` | constant | : Resolver for ``registry://`` imports: takes the reference (without the scheme) and returns the stack document. | | `Stack` | class | A resolved stack: every import merged, ready to build a router. | | `StackChange` | class | One line of a plan: ``add`` / ``change`` / ``remove`` of a target, rule, setting or objective weight. | | `StackPlan` | class | What applying ``desired`` would change compared with ``current`` (``osr stack plan``). | | `dump_stack` | function `(doc: dict[str, Any], fmt: str \| None=None)` | Serialise a stack document: ``fmt`` = ``"yaml"`` \| ``"json"``; default YAML when PyYAML is installed. | | `is_stack` | function `(doc: Any)` | True when ``doc`` looks like a stack document (``kind: stack`` or an ``osr`` version with stack sections). | | `load_stack` | function `(source: str \| Path \| dict[str, Any], *, resolver: Resolver \| None=None, settings: Settings \| None=None, _seen: frozenset[str]=frozenset())` | Load and resolve a stack (file path, ``registry://`` reference or inline mapping), imports first. | | `plan_stack` | function `(desired: Stack, current: Stack \| None=None)` | Diff ``desired`` against ``current`` (``None`` = nothing deployed: everything is an ``add``). | | `registry_resolver` | function `(base_url: str)` | Resolver for ``registry://slug[@version]`` imports against a marketplace. | | `starter_stack` | function `(name: str='starter', description: str='')` | A minimal, valid stack document to start from (what the marketplace publish wizard pre-fills). | | `validate_stack` | function `(doc: Any)` | Validate a stack document; returns human-readable problems (empty list = valid). Imports are not resolved. | ## `opensmartroute.strategies` Source: src/opensmartroute/strategies/__init__.py (`src/opensmartroute/strategies/__init__.py`) | Name | Kind | Summary | |---|---|---| | `DEFAULT_RULES` | re-export of [`opensmartroute.strategies.protocol.DEFAULT_RULES`](#opensmartroutestrategiesprotocol) | Built-in risk / budget ladder: handoff > debate > aggregate > cascade > single. | | `AggregateResult` | re-export of [`opensmartroute.strategies.aggregate.AggregateResult`](#opensmartroutestrategiesaggregate) | Outcome of :class:`MixtureOfAgents`: the final response, participants, winner and agreement ratio. | | `AnnotatorPool` | re-export of [`opensmartroute.strategies.human.AnnotatorPool`](#opensmartroutestrategieshuman) | Skill estimation from agreement (Dawid-Skene EM) and quorum selection. Labels usually arrive from. | | `AnnotatorSkill` | re-export of [`opensmartroute.strategies.human.AnnotatorSkill`](#opensmartroutestrategieshuman) | Per-domain Beta accuracy estimate, cost and latency of one human annotator. | | `AuctionResult` | re-export of [`opensmartroute.strategies.auction.AuctionResult`](#opensmartroutestrategiesauction) | Winner, second-price payment and the per-bidder surplus / corrected claims of one auction. | | `AuctionStrategy` | re-export of [`opensmartroute.strategies.auction.AuctionStrategy`](#opensmartroutestrategiesauction) | Error-aware reverse auction: bias-corrected bids, highest surplus wins, second-price payment. | | `BanditStrategy` | re-export of [`opensmartroute.strategies.bandit.BanditStrategy`](#opensmartroutestrategiesbandit) | Thompson-sampling Beta bandit per (context, target); context = dominant domain (+ plan role). | | `BeliefTracker` | re-export of [`opensmartroute.strategies.cascade.BeliefTracker`](#opensmartroutestrategiescascade) | AutoMix-style POMDP belief over the hidden state "current answer is correct". | | `BudgetVariant` | re-export of [`opensmartroute.strategies.elastic.BudgetVariant`](#opensmartroutestrategieselastic) | One budget of an elastic model. ``quality`` and ``cost_scale`` are relative to the parent. | | `CacheEntry` | re-export of [`opensmartroute.strategies.semantic_cache.CacheEntry`](#opensmartroutestrategiessemantic_cache) | A cached response keyed by the embedding of its prompt, with source target, quality, timestamp and hits. | | `CacheHit` | re-export of [`opensmartroute.strategies.semantic_cache.CacheHit`](#opensmartroutestrategiessemantic_cache) | The matched :class:`CacheEntry` and its similarity to the query. | | `CapabilityStrategy` | re-export of [`opensmartroute.strategies.capability.CapabilityStrategy`](#opensmartroutestrategiescapability) | Declarative fit: domain / action overlap, complexity band, language, modality and quality prior. | | `Cascade` | re-export of [`opensmartroute.strategies.cascade.Cascade`](#opensmartroutestrategiescascade) | Execute ranked targets in planner order (cheapest / MDP / POMDP), stopping when the quality gate passes. | | `CascadePlanner` | re-export of [`opensmartroute.strategies.cascade.CascadePlanner`](#opensmartroutestrategiescascade) | Finite-horizon MDP over an ordered cascade with a stop action after each step. | | `CascadeResult` | re-export of [`opensmartroute.strategies.cascade.CascadeResult`](#opensmartroutestrategiescascade) | Final response of a cascade with every step, the planned order and the planner's expected value. | | `CascadeStep` | re-export of [`opensmartroute.strategies.cascade.CascadeStep`](#opensmartroutestrategiescascade) | One executed rung of a cascade: gate quality, latency, cost, acceptance and POMDP belief. | | `DeferStrategy` | re-export of [`opensmartroute.strategies.defer.DeferStrategy`](#opensmartroutestrategiesdefer) | Learning-to-defer: scores human targets by risk, PII, escalation intent, frustration and model uncertainty. | | `EdgeCloudStrategy` | re-export of [`opensmartroute.strategies.edge.EdgeCloudStrategy`](#opensmartroutestrategiesedge) | Edge vs cloud tier choice: learned edge competence per complexity bucket vs upload / decode penalties. | | `EffortStrategy` | re-export of [`opensmartroute.strategies.defer.EffortStrategy`](#opensmartroutestrategiesdefer) | Match a target's reasoning ``effort_level`` to ``signals.reasoning_need``; penalise over- and under-thinking. | | `EscalationDecision` | re-export of [`opensmartroute.strategies.escalation.EscalationDecision`](#opensmartroutestrategiesescalation) | Verdict after a streamed chunk: continue / escalate / done with the competence estimate and reason. | | `EscalationResult` | re-export of [`opensmartroute.strategies.modality.EscalationResult`](#opensmartroutestrategiesmodality) | Outcome of :class:`ModalityEscalation`: which target answered, whether it escalated, confidence, cost. | | `HiddenStateStrategy` | re-export of [`opensmartroute.strategies.probe.HiddenStateStrategy`](#opensmartroutestrategiesprobe) | Dirichlet probe over a dense request representation; confidence drops with epistemic uncertainty. | | `HumanRoutingStrategy` | re-export of [`opensmartroute.strategies.human.HumanRoutingStrategy`](#opensmartroutestrategieshuman) | Scores HUMAN candidates by estimated accuracy in the request's domain. | | `ImportanceGate` | re-export of [`opensmartroute.strategies.memory.ImportanceGate`](#opensmartroutestrategiesmemory) | Hashed logistic gate: P(item will be used later \| text, hint). | | `LLMJudgeStrategy` | re-export of [`opensmartroute.strategies.llm_judge.LLMJudgeStrategy`](#opensmartroutestrategiesllm_judge) | LLM-as-router with optional **score calibration**. | | `MemoryItem` | re-export of [`opensmartroute.strategies.memory.MemoryItem`](#opensmartroutestrategiesmemory) | One stored memory: text, size, turn written, learned importance gate, tier and usage counters. | | `MemoryRouter` | re-export of [`opensmartroute.strategies.memory.MemoryRouter`](#opensmartroutestrategiesmemory) | Routes memory writes to tiers under budgets and recalls the most valuable items per token. | | `MemoryTier` | re-export of [`opensmartroute.strategies.memory.MemoryTier`](#opensmartroutestrategiesmemory) | A storage tier: token capacity, read / write cost per token, latency and the minimum item value it accepts. | | `MixtureOfAgents` | re-export of [`opensmartroute.strategies.aggregate.MixtureOfAgents`](#opensmartroutestrategiesaggregate) | Route-or-aggregate switch: below a confidence threshold call the top-k alternatives and aggregate. | | `ModalityEscalation` | re-export of [`opensmartroute.strategies.modality.ModalityEscalation`](#opensmartroutestrategiesmodality) | Try the text-only target on the surrogate first; escalate to the multimodal target on low confidence. | | `ModalityStrategy` | re-export of [`opensmartroute.strategies.modality.ModalityStrategy`](#opensmartroutestrategiesmodality) | Coverage of the request's modalities by each candidate, with surrogate discounts. | | `MultiRoundExecutor` | re-export of [`opensmartroute.strategies.progress.MultiRoundExecutor`](#opensmartroutestrategiesprogress) | Router-R1 style: keep routing/executing until the judge accepts or rounds run out. | | `ProgressRouter` | re-export of [`opensmartroute.strategies.progress.ProgressRouter`](#opensmartroutestrategiesprogress) | Route each step of a task with trajectory context. | | `ProtocolChoice` | re-export of [`opensmartroute.strategies.protocol.ProtocolChoice`](#opensmartroutestrategiesprotocol) | The protocol picked for a request, the risk that drove it, the reason and the matching rule. | | `ProtocolPolicy` | re-export of [`opensmartroute.strategies.protocol.ProtocolPolicy`](#opensmartroutestrategiesprotocol) | Ordered rule table from (risk, budget, task type) to a protocol, with per-protocol ledgers. | | `ProtocolRule` | re-export of [`opensmartroute.strategies.protocol.ProtocolRule`](#opensmartroutestrategiesprotocol) | First matching rule wins. ``None`` bounds are open. | | `QuorumPlan` | re-export of [`opensmartroute.strategies.human.QuorumPlan`](#opensmartroutestrategieshuman) | A chosen set of annotators with the quorum's majority accuracy, total cost and latency. | | `RecallResult` | re-export of [`opensmartroute.strategies.memory.RecallResult`](#opensmartroutestrategiesmemory) | Items recalled for a turn with their total tokens, read cost and latency. | | `Round` | re-export of [`opensmartroute.strategies.progress.Round`](#opensmartroutestrategiesprogress) | One route -> execute -> judge iteration of :class:`MultiRoundExecutor`. | | `RoundResult` | re-export of [`opensmartroute.strategies.progress.RoundResult`](#opensmartroutestrategiesprogress) | Final response of a multi-round run with every round and the shared task id. | | `Rule` | re-export of [`opensmartroute.strategies.rules.Rule`](#opensmartroutestrategiesrules) | If all `when` conditions match, boost `prefer` targets and penalise `avoid`. | | `RulesStrategy` | re-export of [`opensmartroute.strategies.rules.RulesStrategy`](#opensmartroutestrategiesrules) | Applies declarative :class:`Rule` preferences (prefer / avoid / pin) when their ``when`` conditions match. | | `SelfEscalation` | re-export of [`opensmartroute.strategies.escalation.SelfEscalation`](#opensmartroutestrategiesescalation) | Streaming competence monitor with Bayesian optimal stopping. | | `SemanticCache` | re-export of [`opensmartroute.strategies.semantic_cache.SemanticCache`](#opensmartroutestrategiessemantic_cache) | Embedding-keyed LRU cache with TTL and a similarity threshold. Safe to share across threads:. | | `SemanticCacheStrategy` | re-export of [`opensmartroute.strategies.semantic_cache.SemanticCacheStrategy`](#opensmartroutestrategiessemantic_cache) | Scores the cache target by calibrated hit quality; leaves real targets to the other strategies. | | `SessionAffinityStrategy` | re-export of [`opensmartroute.strategies.session.SessionAffinityStrategy`](#opensmartroutestrategiessession) | Prefer the target already serving ``context["session_id"]`` unless the intent shifted or it failed. | | `SessionState` | re-export of [`opensmartroute.strategies.session.SessionState`](#opensmartroutestrategiessession) | What the strategy remembers about one session. | | `SimilarityStrategy` | re-export of [`opensmartroute.strategies.similarity.SimilarityStrategy`](#opensmartroutestrategiessimilarity) | Embed the request and each target's examples / description; score by best and top-k mean similarity. | | `SpeculativeCascade` | re-export of [`opensmartroute.strategies.speculative.SpeculativeCascade`](#opensmartroutestrategiesspeculative) | Two-target cascade that overlaps the draft and the strong call when it pays. | | `SpeculativeResult` | re-export of [`opensmartroute.strategies.speculative.SpeculativeResult`](#opensmartroutestrategiesspeculative) | Outcome of a speculative run: chosen mode, whether the draft was accepted, latency and cost. | | `Strategy` | re-export of [`opensmartroute.strategies.base.Strategy`](#opensmartroutestrategiesbase) | Scores each candidate target in [0, 1] and explains why. | | `StreamResult` | re-export of [`opensmartroute.strategies.escalation.StreamResult`](#opensmartroutestrategiesescalation) | Text consumed by :func:`wrap_stream`, whether it escalated and the final decision. | | `TaskProgress` | re-export of [`opensmartroute.strategies.progress.TaskProgress`](#opensmartroutestrategiesprogress) | Where a multi-step task stands: step index, budget spent, failures in a row, last target, history. | | `TaskTableStrategy` | re-export of [`opensmartroute.strategies.task_table.TaskTableStrategy`](#opensmartroutestrategiestask_table) | Static ``task_type -> target -> quality`` table with family and prior fallbacks; learns from outcomes. | | `TokenBudgetStrategy` | re-export of [`opensmartroute.strategies.elastic.TokenBudgetStrategy`](#opensmartroutestrategieselastic) | Score budgeted siblings by fit between the budget and the tokens the answer needs. | | `decide_effort` | re-export of [`opensmartroute.strategies.defer.decide_effort`](#opensmartroutestrategiesdefer) | Pick the effort level whose numeric value is closest to the reasoning need. | | `default_bid` | re-export of [`opensmartroute.strategies.auction.default_bid`](#opensmartroutestrategiesauction) | Catalogue-derived bid: quality prior as the claim, unit cost per 1k tokens x tokens as the price. | | `default_strategies` | function `(seed: int \| None=None, settings: Settings \| None=None, state_dir: str \| Path \| None=None)` | The zero-configuration ensemble: capability fit + example similarity + Thompson bandit. | | `expand_elastic` | re-export of [`opensmartroute.strategies.elastic.expand_elastic`](#opensmartroutestrategieselastic) | Create one sibling target per budget variant, sharing the parent's family, handler and metadata. | | `expected_mode_costs` | re-export of [`opensmartroute.strategies.speculative.expected_mode_costs`](#opensmartroutestrategiesspeculative) | Expected weighted cost (``objective.cost`` x USD + ``objective.latency`` x seconds) per mode. | | `failure_risk` | re-export of [`opensmartroute.strategies.protocol.failure_risk`](#opensmartroutestrategiesprotocol) | Risk in [0, 1] that a single call fails: low confidence, high complexity and reasoning need,. | | `hashing_embedder` | re-export of [`opensmartroute.strategies.similarity.hashing_embedder`](#opensmartroutestrategiessimilarity) | Word + bigram hashing embedder. Deterministic, zero deps, decent for routing. | | `majority_vote` | re-export of [`opensmartroute.strategies.aggregate.majority_vote`](#opensmartroutestrategiesaggregate) | Largest meaning cluster wins; returns ``(answer, winner_target_id, agreement)``. | | `quorum_accuracy` | re-export of [`opensmartroute.strategies.human.quorum_accuracy`](#opensmartroutestrategieshuman) | P(weighted majority is correct) for independent annotators with the given accuracies. | | `request_modalities` | re-export of [`opensmartroute.strategies.modality.request_modalities`](#opensmartroutestrategiesmodality) | Modalities a request carries and which of them have a text surrogate in ``context``. | | `wrap_stream` | re-export of [`opensmartroute.strategies.escalation.wrap_stream`](#opensmartroutestrategiesescalation) | Consume ``chunks`` until the monitor escalates or the stream ends. | ## `opensmartroute.strategies.aggregate` Source: src/opensmartroute/strategies/aggregate.py (`src/opensmartroute/strategies/aggregate.py`) Routing / aggregation switch (Mixture-of-Agents, Wang et al. 2024; JiSi 2601.01330). | Name | Kind | Summary | |---|---|---| | `AggregateResult` | class | Outcome of :class:`MixtureOfAgents`: the final response, participants, winner and agreement ratio. | | `Aggregator` | constant | (request, [(target_id, answer)]) -> answer. | | `MixtureOfAgents` | class | Route-or-aggregate switch: below a confidence threshold call the top-k alternatives and aggregate. | | `Participant` | class | One target's contribution to an aggregate: response, cost, latency, error and whether it agreed. | | `majority_vote` | function `(request: RouteRequest, answers: list[tuple[str, Any]], embedder: Embedder \| None=None, threshold: float=0.85)` | Largest meaning cluster wins; returns ``(answer, winner_target_id, agreement)``. | ## `opensmartroute.strategies.auction` Source: src/opensmartroute/strategies/auction.py (`src/opensmartroute/strategies/auction.py`) Error-aware reverse auction across providers (EA-RAM 2608.12719). | Name | Kind | Summary | |---|---|---| | `AuctionResult` | class | Winner, second-price payment and the per-bidder surplus / corrected claims of one auction. | | `AuctionStrategy` | class | Error-aware reverse auction: bias-corrected bids, highest surplus wins, second-price payment. | | `BidFn` | constant | -> (claimed P(success), price). | | `BidderRecord` | class | Calibration ledger of one bidder: signed claim bias and a Beta record of realised success. | | `default_bid` | function `(target: RouteTarget, request: RouteRequest, signals: Signals)` | Catalogue-derived bid: quality prior as the claim, unit cost per 1k tokens x tokens as the price. | ## `opensmartroute.strategies.bandit` Source: src/opensmartroute/strategies/bandit.py (`src/opensmartroute/strategies/bandit.py`) Online-learning strategy: contextual Thompson-sampling bandit. | Name | Kind | Summary | |---|---|---| | `BanditStrategy` | class | Thompson-sampling Beta bandit per (context, target); context = dominant domain (+ plan role). | ## `opensmartroute.strategies.base` Source: src/opensmartroute/strategies/base.py (`src/opensmartroute/strategies/base.py`) Strategy interface. | Name | Kind | Summary | |---|---|---| | `Strategy` | class | Scores each candidate target in [0, 1] and explains why. | | `role_of` | function `(signals: Signals)` | Plan-slot role (``persona`` / ``skill`` / ``llm``) the router is currently filling, or. | | `memory_key` | function `(request_id: str, role: str \| None)` | Key for per-request strategy memory: the same request is scored once per plan role, and. | ## `opensmartroute.strategies.capability` Source: src/opensmartroute/strategies/capability.py (`src/opensmartroute/strategies/capability.py`) Capability-fit strategy: match request signals to a target's declared capabilities. | Name | Kind | Summary | |---|---|---| | `CapabilityStrategy` | class | Declarative fit: domain / action overlap, complexity band, language, modality and quality prior. | ## `opensmartroute.strategies.cascade` Source: src/opensmartroute/strategies/cascade.py (`src/opensmartroute/strategies/cascade.py`) Cascade execution (FrugalGPT / Router-R1 multi-round / AutoMix POMDP). | Name | Kind | Summary | |---|---|---| | `CascadeStep` | class | One executed rung of a cascade: gate quality, latency, cost, acceptance and POMDP belief. | | `CascadeResult` | class | Final response of a cascade with every step, the planned order and the planner's expected value. | | `CascadePlanner` | class | Finite-horizon MDP over an ordered cascade with a stop action after each step. | | `BeliefTracker` | class | AutoMix-style POMDP belief over the hidden state "current answer is correct". | | `Cascade` | class | Execute ranked targets in planner order (cheapest / MDP / POMDP), stopping when the quality gate passes. | ## `opensmartroute.strategies.defer` Source: src/opensmartroute/strategies/defer.py (`src/opensmartroute/strategies/defer.py`) Defer-to-human and effort ("think or not") strategies. | Name | Kind | Summary | |---|---|---| | `DeferStrategy` | class | Learning-to-defer: scores human targets by risk, PII, escalation intent, frustration and model uncertainty. | | `EffortStrategy` | class | Match a target's reasoning ``effort_level`` to ``signals.reasoning_need``; penalise over- and under-thinking. | | `decide_effort` | function `(signals: Signals, levels: tuple[str, ...]=('none', 'low', 'medium', 'high'))` | Pick the effort level whose numeric value is closest to the reasoning need. | ## `opensmartroute.strategies.edge` Source: src/opensmartroute/strategies/edge.py (`src/opensmartroute/strategies/edge.py`) Edge-cloud token-aware routing (Pro-Router 2608.28726; RelayLLM 2601.05167). | Name | Kind | Summary | |---|---|---| | `EdgeCloudStrategy` | class | Edge vs cloud tier choice: learned edge competence per complexity bucket vs upload / decode penalties. | ## `opensmartroute.strategies.elastic` Source: src/opensmartroute/strategies/elastic.py (`src/opensmartroute/strategies/elastic.py`) Token-budget-aware routing to elastic / many-in-one models (Nemotron Elastic 2511.16664; Star 2605.07182). | Name | Kind | Summary | |---|---|---| | `BudgetVariant` | class | One budget of an elastic model. ``quality`` and ``cost_scale`` are relative to the parent. | | `TokenBudgetStrategy` | class | Score budgeted siblings by fit between the budget and the tokens the answer needs. | | `expand_elastic` | function `(parent: RouteTarget, variants: list[BudgetVariant \| dict[str, Any]])` | Create one sibling target per budget variant, sharing the parent's family, handler and metadata. | ## `opensmartroute.strategies.escalation` Source: src/opensmartroute/strategies/escalation.py (`src/opensmartroute/strategies/escalation.py`) Bayesian self-escalation during generation (2608.24087). | Name | Kind | Summary | |---|---|---| | `REFUSALS` | constant | Refusal phrases that lower the streaming competence posterior. | | `EscalationDecision` | class | Verdict after a streamed chunk: continue / escalate / done with the competence estimate and reason. | | `SelfEscalation` | class | Streaming competence monitor with Bayesian optimal stopping. | | `StreamResult` | class | Text consumed by :func:`wrap_stream`, whether it escalated and the final decision. | | `wrap_stream` | function `(chunks: Iterable[str], monitor: SelfEscalation \| None=None)` | Consume ``chunks`` until the monitor escalates or the stream ends. | ## `opensmartroute.strategies.human` Source: src/opensmartroute/strategies/human.py (`src/opensmartroute/strategies/human.py`) Routing among human annotators and experts (QUORUM 2608.27974; Dawid-Skene 1979). | Name | Kind | Summary | |---|---|---| | `AnnotatorPool` | class | Skill estimation from agreement (Dawid-Skene EM) and quorum selection. Labels usually arrive from. | | `AnnotatorSkill` | class | Per-domain Beta accuracy estimate, cost and latency of one human annotator. | | `HumanRoutingStrategy` | class | Scores HUMAN candidates by estimated accuracy in the request's domain. | | `QuorumPlan` | class | A chosen set of annotators with the quorum's majority accuracy, total cost and latency. | | `quorum_accuracy` | function `(accuracies: Sequence[float])` | P(weighted majority is correct) for independent annotators with the given accuracies. | ## `opensmartroute.strategies.llm_judge` Source: src/opensmartroute/strategies/llm_judge.py (`src/opensmartroute/strategies/llm_judge.py`) Generative routing: let an LLM act as the router (Router-R1 / LLM-as-judge). | Name | Kind | Summary | |---|---|---| | `PROMPT` | constant | Prompt template for the judge; formatted with complexity, domains, actions, the catalogue and the request. | | `LLMJudgeStrategy` | class | LLM-as-router with optional **score calibration**. | ## `opensmartroute.strategies.memory` Source: src/opensmartroute/strategies/memory.py (`src/opensmartroute/strategies/memory.py`) Memory-tier routing for agents (BudgetMem 2602.06025; Gated-Memory Routing 2609.00237). | Name | Kind | Summary | |---|---|---| | `ImportanceGate` | class | Hashed logistic gate: P(item will be used later \| text, hint). | | `MemoryItem` | class | One stored memory: text, size, turn written, learned importance gate, tier and usage counters. | | `MemoryRouter` | class | Routes memory writes to tiers under budgets and recalls the most valuable items per token. | | `MemoryTier` | class | A storage tier: token capacity, read / write cost per token, latency and the minimum item value it accepts. | | `RecallResult` | class | Items recalled for a turn with their total tokens, read cost and latency. | ## `opensmartroute.strategies.modality` Source: src/opensmartroute/strategies/modality.py (`src/opensmartroute/strategies/modality.py`) Multimodal routing and modality escalation (LatentRouter 2605.11301; modality escalation. | Name | Kind | Summary | |---|---|---| | `EscalationResult` | class | Outcome of :class:`ModalityEscalation`: which target answered, whether it escalated, confidence, cost. | | `ModalityEscalation` | class | Try the text-only target on the surrogate first; escalate to the multimodal target on low confidence. | | `ModalityStrategy` | class | Coverage of the request's modalities by each candidate, with surrogate discounts. | | `request_modalities` | function `(request: RouteRequest)` | Modalities a request carries and which of them have a text surrogate in ``context``. | ## `opensmartroute.strategies.probe` Source: src/opensmartroute/strategies/probe.py (`src/opensmartroute/strategies/probe.py`) Hidden-state routing with a Dirichlet probe (ProbeDirichlet, RouterXBench 2602.11877). | Name | Kind | Summary | |---|---|---| | `HiddenStateStrategy` | class | Dirichlet probe over a dense request representation; confidence drops with epistemic uncertainty. | | `StateFn` | constant | request -> dense feature / hidden-state vector. | ## `opensmartroute.strategies.progress` Source: src/opensmartroute/strategies/progress.py (`src/opensmartroute/strategies/progress.py`) Agentic trajectories: per-step routing and multi-round execution. | Name | Kind | Summary | |---|---|---| | `MultiRoundExecutor` | class | Router-R1 style: keep routing/executing until the judge accepts or rounds run out. | | `ProgressRouter` | class | Route each step of a task with trajectory context. | | `Round` | class | One route -> execute -> judge iteration of :class:`MultiRoundExecutor`. | | `RoundResult` | class | Final response of a multi-round run with every round and the shared task id. | | `TaskProgress` | class | Where a multi-step task stands: step index, budget spent, failures in a row, last target, history. | ## `opensmartroute.strategies.protocol` Source: src/opensmartroute/strategies/protocol.py (`src/opensmartroute/strategies/protocol.py`) Collaboration-protocol selection (2608.14927). | Name | Kind | Summary | |---|---|---| | `DEFAULT_RULES` | constant | Built-in risk / budget ladder: handoff > debate > aggregate > cascade > single. | | `PROTOCOLS` | constant | in escalation order. | | `Protocol` | constant | execution protocols. | | `ProtocolChoice` | class | The protocol picked for a request, the risk that drove it, the reason and the matching rule. | | `ProtocolPolicy` | class | Ordered rule table from (risk, budget, task type) to a protocol, with per-protocol ledgers. | | `ProtocolRule` | class | First matching rule wins. ``None`` bounds are open. | | `failure_risk` | function `(decision: RouteDecision \| None, signals: Signals \| None=None, uncertainty: float \| None=None)` | Risk in [0, 1] that a single call fails: low confidence, high complexity and reasoning need,. | ## `opensmartroute.strategies.rules` Source: src/opensmartroute/strategies/rules.py (`src/opensmartroute/strategies/rules.py`) Declarative rule-based routing (Arch-Router-style domain/action preferences). | Name | Kind | Summary | |---|---|---| | `Rule` | class | If all `when` conditions match, boost `prefer` targets and penalise `avoid`. | | `RulesStrategy` | class | Applies declarative :class:`Rule` preferences (prefer / avoid / pin) when their ``when`` conditions match. | ## `opensmartroute.strategies.semantic_cache` Source: src/opensmartroute/strategies/semantic_cache.py (`src/opensmartroute/strategies/semantic_cache.py`) Semantic caching as a routing target (GPTCache; vLLM semantic router 2603.04444). | Name | Kind | Summary | |---|---|---| | `CacheEntry` | class | A cached response keyed by the embedding of its prompt, with source target, quality, timestamp and hits. | | `CacheHit` | class | The matched :class:`CacheEntry` and its similarity to the query. | | `SemanticCache` | class | Embedding-keyed LRU cache with TTL and a similarity threshold. Safe to share across threads:. | | `SemanticCacheStrategy` | class | Scores the cache target by calibrated hit quality; leaves real targets to the other strategies. | ## `opensmartroute.strategies.session` Source: src/opensmartroute/strategies/session.py (`src/opensmartroute/strategies/session.py`) Session affinity: keep a conversation with the target that is already serving it. | Name | Kind | Summary | |---|---|---| | `SessionAffinityStrategy` | class | Prefer the target already serving ``context["session_id"]`` unless the intent shifted or it failed. | | `SessionState` | class | What the strategy remembers about one session. | ## `opensmartroute.strategies.similarity` Source: src/opensmartroute/strategies/similarity.py (`src/opensmartroute/strategies/similarity.py`) Similarity-based routing (UniRoute / GraphRouter flavour). | Name | Kind | Summary | |---|---|---| | `hashing_embedder` | function `(dim: int=512)` | Word + bigram hashing embedder. Deterministic, zero deps, decent for routing. | | `cosine` | function `(a: list[float], b: list[float])` | Cosine similarity; zero vectors are treated as unit norm (no division by zero). | | `SimilarityStrategy` | class | Embed the request and each target's examples / description; score by best and top-k mean similarity. | ## `opensmartroute.strategies.speculative` Source: src/opensmartroute/strategies/speculative.py (`src/opensmartroute/strategies/speculative.py`) Speculative (draft-based) cascades (speculative cascades, Narasimhan et al. 2024; Differential. | Name | Kind | Summary | |---|---|---| | `SpeculativeCascade` | class | Two-target cascade that overlaps the draft and the strong call when it pays. | | `SpeculativeResult` | class | Outcome of a speculative run: chosen mode, whether the draft was accepted, latency and cost. | | `expected_mode_costs` | function `(p_accept: float, draft: RouteTarget, strong: RouteTarget, objective: Objective, *, tokens: int=500, cancellable: bool=False, verify_ms: float=0.0)` | Expected weighted cost (``objective.cost`` x USD + ``objective.latency`` x seconds) per mode. | ## `opensmartroute.strategies.task_table` Source: src/opensmartroute/strategies/task_table.py (`src/opensmartroute/strategies/task_table.py`) Static task table strategy (SCX Router, 2609.02292). | Name | Kind | Summary | |---|---|---| | `TaskTableStrategy` | class | Static ``task_type -> target -> quality`` table with family and prior fallbacks; learns from outcomes. |