Skip to content

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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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}");
+ }
+}