Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
feat(runner): build configured algorithms from deployment TOML (#1080)
Alex Fournierdfba1ea054ff
diff --git a/crates/switchyard-runner/src/algorithm_factory.rs b/crates/switchyard-runner/src/algorithm_factory.rsnew file mode 100644index 000000000..eb92af4f8--- /dev/null+++ b/crates/switchyard-runner/src/algorithm_factory.rs@@ -0,0 +1,45 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Algorithm construction from deployment TOML without provider clients.++use std::collections::BTreeMap;+use std::sync::Arc;++use libsy::{Algorithm, RuntimeModels};++use crate::RunnerError;+use crate::config::DeploymentConfig;++pub(crate) type AlgorithmAndModels = (Arc<dyn Algorithm>, RuntimeModels);++/// Parsed deployment configuration for building algorithms with host-owned execution.+pub struct AlgorithmFactory {+ pub(crate) config: DeploymentConfig,+}++impl AlgorithmFactory {+ /// Parses deployment TOML without resolving credentials or constructing provider clients.+ /// Invalid TOML returns a configuration error; routing settings are checked by [`Self::build`].+ pub fn from_toml(source: &str) -> Result<Self, RunnerError> {+ let config = toml::from_str(source).map_err(|error| {+ RunnerError::configuration_source(format!("failed to parse TOML: {error}"), error)+ })?;+ Ok(Self { config })+ }++ /// Builds algorithms and their model groups, keyed by configured route `id`.+ ///+ /// The host serves model calls and owns target prompts, provider settings and transport.+ /// Reuse the returned algorithms across requests to retain algorithm-owned state.+ pub fn build(&self) -> Result<BTreeMap<String, AlgorithmAndModels>, RunnerError> {+ self.config.validate()?;+ self.config+ .build_algorithms()+ .map(|entry| {+ let (_, config, algorithm) = entry?;+ Ok((config.id.to_string(), algorithm))+ })+ .collect()+ }+}diff --git a/crates/switchyard-runner/src/config.rs b/crates/switchyard-runner/src/config.rsindex 49d03910f..406247ca9 100644--- a/crates/switchyard-runner/src/config.rs+++ b/crates/switchyard-runner/src/config.rs@@ -18,10 +18,11 @@ use switchyard_llm_client::{};use switchyard_protocol::{ModelId, RoutedDecisionClient, RoutedLlmClient, WireFormat};+use crate::algorithm_factory::AlgorithmAndModels;use crate::runner::ModelPropertiesProbe;use crate::{- AlgorithmSpec, AuxiliaryTarget, CallerAuthKind, DecisionTarget, ModelCapabilities, Route,- Runner, RunnerError,+ AlgorithmFactory, AlgorithmSpec, AuxiliaryTarget, CallerAuthKind, DecisionTarget,+ ModelCapabilities, Route, Runner, RunnerError,};const SUPPORTED_SCHEMA_VERSION: u32 = 1;@@ -131,10 +132,7 @@ pub(crate) fn load_runner(path: impl AsRef<Path>) -> RunnerResult<Runner> {}pub(crate) fn runner_from_toml(source: &str) -> RunnerResult<Runner> {- let config: DeploymentConfig = toml::from_str(source).map_err(|error| {- RunnerError::configuration_source(format!("failed to parse TOML: {error}"), error)- })?;- config.build()+ AlgorithmFactory::from_toml(source)?.config.build()}#[derive(Debug, Deserialize)]@@ -153,8 +151,8 @@ pub(crate) struct DeploymentConfig {}#[derive(Debug)]-struct RouteConfig {- id: ModelId,+pub(crate) struct RouteConfig {+ pub(crate) id: ModelId,context_window: Option<u32>,tool_calling: Option<bool>,reasoning: Option<bool>,@@ -280,7 +278,8 @@ impl DeploymentConfig {})}- fn build(self) -> RunnerResult<Runner> {+ /// Checks route identity and target references without constructing clients.+ pub(crate) fn validate(&self) -> RunnerResult<()> {self.check_schema_version()?;let mut route_names_by_id = HashMap::new();@@ -297,42 +296,16 @@ impl DeploymentConfig {}}- // The LLM client keeps one backend per model id, so two targets naming the same model on- // the same client share it. That is harmless when their request settings agree (an alias- // for a different system prompt, say) and silently wrong when they do not: the second- // target's reasoning_effort or extra_body would never reach the wire.- let mut seen_client_model_ids: HashMap<(&str, &str), (&String, &TargetConfig)> =- HashMap::new();- for (target_name, target) in &self.targets {- validate_value("target name", target_name)?;- validate_value(&format!("target {target_name} id"), &target.id)?;- match seen_client_model_ids.entry((target.llm_client.as_str(), target.id.as_str())) {- std::collections::hash_map::Entry::Vacant(slot) => {- slot.insert((target_name, target));- }- std::collections::hash_map::Entry::Occupied(slot) => {- let (first_name, first) = slot.get();- if first.reasoning_effort != target.reasoning_effort- || first.extra_body != target.extra_body- || first.omit_body_fields != target.omit_body_fields- {- return Err(RunnerError::configuration(format!(- "targets {first_name} and {target_name} both name model {} on llm client {} but with different reasoning_effort, extra_body, or omit_body_fields; one target per model id is kept, so give each its own model id or llm client",- target.id, target.llm_client- )));- }- tracing::warn!(- "target {target_name} reuses model id {} on llm client {}; only one target per id is kept and the other is dropped. Give each target a unique model id, or point both routes at one target.",- target.id,- target.llm_client- );- }+ for (name, target) in &self.targets {+ validate_value("target name", name)?;+ validate_value(&format!("target {name} id"), &target.id)?;+ if !self.llm_clients.contains_key(&target.llm_client) {+ return Err(RunnerError::configuration(format!(+ "target {name} references unknown llm client {}",+ target.llm_client+ )));}}-- let mut provider_api_keys = Vec::new();- let clients = self.build_clients(&mut provider_api_keys)?;- let decision_clients = self.build_decision_clients(&mut provider_api_keys)?;for (name, target) in &self.decision_targets {validate_value("decision target name", name)?;validate_value(&format!("decision target {name} id"), &target.id)?;@@ -341,18 +314,22 @@ impl DeploymentConfig {"target {name} is defined as both an LLM and decision target")));}- if !decision_clients.contains_key(&target.decision_client) {+ if !self.decision_clients.contains_key(&target.decision_client) {return Err(RunnerError::configuration(format!("decision target {name} references unknown decision client {}",target.decision_client)));}}+ Ok(())+ }++ /// Resolves each route once; native and host-owned execution share this path.+ pub(crate) fn build_algorithms(+ &self,+ ) -> impl Iterator<Item = RunnerResult<(&str, &RouteConfig, AlgorithmAndModels)>> {let targets = self.build_targets();- let fallback_base_url = self.fallback_base_url()?;- let mut routes = Vec::with_capacity(self.routes.len());- let mut model_properties_probes = BTreeMap::new();- for (route_name, config) in &self.routes {+ self.routes.iter().map(move |(route_name, config)| {let decision_judge = config.algorithm.decision_judge();for name in config.callable_target_names() {let (exists, kind) = if decision_judge.is_some_and(|(judge, _)| judge == name) {@@ -377,8 +354,7 @@ impl DeploymentConfig {)));}}- let capabilities = config.capabilities();- if capabilities.context_window == Some(0) {+ if config.context_window == Some(0) {return Err(RunnerError::configuration(format!("route {route_name} context_window must be greater than zero")));@@ -400,6 +376,53 @@ impl DeploymentConfig {RunnerError::configuration_source(format!("route {route_name}: {error}"), error)})?;}+ Ok((route_name.as_str(), config, (algorithm, models)))+ })+ }++ fn build(self) -> RunnerResult<Runner> {+ self.validate()?;++ // The LLM client keeps one backend per model id, so two targets naming the same model on+ // the same client share it. That is harmless when their request settings agree (an alias+ // for a different system prompt, say) and silently wrong when they do not: the second+ // target's reasoning_effort or extra_body would never reach the wire.+ let mut seen_client_model_ids: HashMap<(&str, &str), (&String, &TargetConfig)> =+ HashMap::new();+ for (target_name, target) in &self.targets {+ match seen_client_model_ids.entry((target.llm_client.as_str(), target.id.as_str())) {+ std::collections::hash_map::Entry::Vacant(slot) => {+ slot.insert((target_name, target));+ }+ std::collections::hash_map::Entry::Occupied(slot) => {+ let (first_name, first) = slot.get();+ if first.reasoning_effort != target.reasoning_effort+ || first.extra_body != target.extra_body+ || first.omit_body_fields != target.omit_body_fields+ {+ return Err(RunnerError::configuration(format!(+ "targets {first_name} and {target_name} both name model {} on llm client {} but with different reasoning_effort, extra_body, or omit_body_fields; one target per model id is kept, so give each its own model id or llm client",+ target.id, target.llm_client+ )));+ }+ tracing::warn!(+ "target {target_name} reuses model id {} on llm client {}; only one target per id is kept and the other is dropped. Give each target a unique model id, or point both routes at one target.",+ target.id,+ target.llm_client+ );+ }+ }+ }++ let mut provider_api_keys = Vec::new();+ let clients = self.build_clients(&mut provider_api_keys)?;+ let decision_clients = self.build_decision_clients(&mut provider_api_keys)?;+ let fallback_base_url = self.fallback_base_url()?;+ let mut routes = Vec::with_capacity(self.routes.len());+ let mut model_properties_probes = BTreeMap::new();+ for entry in self.build_algorithms() {+ let (route_name, config, (algorithm, models)) = entry?;+ let capabilities = config.capabilities();if let AlgorithmSpec::Vgr { config: vgr } = &config.algorithm&& let Some(probe) =self.build_model_properties_probe(&vgr.efficient_target, &clients)diff --git a/crates/switchyard-runner/src/lib.rs b/crates/switchyard-runner/src/lib.rsindex 90219e71b..23c21e1bc 100644--- a/crates/switchyard-runner/src/lib.rs+++ b/crates/switchyard-runner/src/lib.rs@@ -7,6 +7,8 @@mod algorithm;#[cfg(not(target_os = "wasi"))]+mod algorithm_factory;+#[cfg(not(target_os = "wasi"))]mod config;#[cfg(not(target_os = "wasi"))]mod failure;@@ -25,6 +27,8 @@ pub use algorithm::{StageClassifierConfig, SubagentRouteConfig, VgrModeConfig, VgrRouteConfig,};#[cfg(not(target_os = "wasi"))]+pub use algorithm_factory::AlgorithmFactory;+#[cfg(not(target_os = "wasi"))]pub use failure::{RouteErrorKind, RouteErrorPhase, RouteErrorSummary, stream_error_summary};// Re-exported because `Route::new` takes it, so a host wiring routes does not need a libsy dep.pub use libsy::{RoutingOutcome, RuntimeModels};diff --git a/crates/switchyard-runner/tests/algorithm_factory.rs b/crates/switchyard-runner/tests/algorithm_factory.rsnew file mode 100644index 000000000..6b4c1363b--- /dev/null+++ b/crates/switchyard-runner/tests/algorithm_factory.rs@@ -0,0 +1,151 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Public factory contracts for configured routes without provider clients.++use std::sync::Arc;++use switchyard_protocol::{Category, Metadata, ModelId, Request, text_request};+use switchyard_runner::{AlgorithmFactory, Runner};++const MISSING_KEY: &str = "SWITCHYARD_FACTORY_TEST_KEY_THAT_IS_NOT_SET";+const DEPLOYMENT: &str = r#"+schema_version = 1+[llm_clients.answers]+format = "openai_chat"+base_url = "https://example.test/v1"+api_key_env = "SWITCHYARD_FACTORY_TEST_KEY_THAT_IS_NOT_SET"+[targets]+fast = { id = "upstream/fast", llm_client = "answers" }+capable = { id = "upstream/capable", llm_client = "answers" }+[decision_clients.judge]+format = "openai_decisions"+endpoint = "https://example.test/v1/decisions"+api_key_env = "SWITCHYARD_FACTORY_TEST_KEY_THAT_IS_NOT_SET"+timeout_ms = 2000+[decision_targets.judge]+id = "upstream/judge"+decision_client = "judge"+[routes.parent]+id = "public/main"+type = "passthrough"+target = "fast"+[routes.parent.subagents]+type = "passthrough"+target = "capable"+[routes.classifier]+id = "public/classify"+type = "llm_classifier"+classifier_target = "judge"+strong_target = "capable"+weak_target = "fast"+[routes.classifier.decision]+cutoff = 0.7+candidates = { a = "capable", b = "fast" }+evidence = { description = "Compare both targets." }+"#;++#[test]+fn full_deployment_builds_without_provider_credentials() {+ assert!(std::env::var_os(MISSING_KEY).is_none());+ let factory = AlgorithmFactory::from_toml(DEPLOYMENT).expect("deployment should parse");+ let algorithms = factory.build().expect("algorithms need no provider keys");+ assert_eq!(+ algorithms.keys().map(String::as_str).collect::<Vec<_>>(),+ ["public/classify", "public/main"]+ );+ let (algorithm, models) = &algorithms["public/classify"];+ assert_eq!(algorithm.name(), "llm_task_classifier");+ assert_eq!(+ models.models_for(&Category::Judge),+ [ModelId::from("upstream/judge")]+ );+ assert_eq!(+ models.models_for(&Category::Capable),+ [ModelId::from("upstream/capable")]+ );+ assert_eq!(+ models.models_for(&Category::Efficient),+ [ModelId::from("upstream/fast")]+ );+ assert_eq!(+ models.models_for(&Category::Any),+ [+ ModelId::from("upstream/fast"),+ ModelId::from("upstream/capable")+ ]+ );++ let error = Runner::from_toml(DEPLOYMENT)+ .err()+ .expect("the native runner still requires configured credentials");+ assert!(error.to_string().contains(MISSING_KEY), "{error}");+}++#[tokio::test]+async fn configured_parent_and_subagent_targets_stay_separate() {+ let mut algorithms = AlgorithmFactory::from_toml(DEPLOYMENT)+ .expect("deployment should parse")+ .build()+ .expect("algorithms should build");+ let (algorithm, models) = algorithms.remove("public/main").expect("public route id");+ assert_eq!(+ models.models_for(&Category::Any),+ [ModelId::from("upstream/fast")]+ );+ assert_eq!(+ models.subagent_models_for(&Category::Any),+ [ModelId::from("upstream/capable")]+ );+ let models = Arc::new(models);+ for (delegated, selected) in [(false, "upstream/fast"), (true, "upstream/capable")] {+ let request = Request {+ llm_request: text_request(Some("public/main".to_string()), "hello"),+ metadata: delegated.then(|| Metadata {+ session_id: Some("task".to_string()),+ agent_id: Some("child".to_string()),+ is_subagent: true,+ is_delegated_work: true,+ ..Metadata::default()+ }),+ ..Request::default()+ };+ let outcome = libsy::drive(+ Arc::clone(&algorithm),+ request,+ Arc::clone(&models),+ |_| async { panic!("passthrough must not dispatch provider calls") },+ )+ .await+ .expect("configured route should resolve");+ assert_eq!(outcome.selected_model_ids, [ModelId::from(selected)]);+ assert!(outcome.response.is_none());+ }+}++#[test]+fn invalid_routing_configuration_is_rejected() {+ for (source, expected) in [+ (+ DEPLOYMENT.replacen("target = \"fast\"", "target = \"missing\"", 1),+ "unknown target missing",+ ),+ (+ DEPLOYMENT.replace("id = \"public/classify\"", "id = \"public/main\""),+ "route ids must be unique",+ ),+ (+ DEPLOYMENT.replace(+ "type = \"passthrough\"",+ "type = \"passthrough\"\nbogus = true",+ ),+ "bogus",+ ),+ ] {+ let error = AlgorithmFactory::from_toml(&source)+ .and_then(|factory| factory.build())+ .err()+ .expect("invalid deployment should fail");+ assert!(error.to_string().contains(expected), "{error}");+ }+}