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(router): allow custom decision criteria (#1187)
ryan-lempkaf7d010dbd4f2
diff --git a/bindings/typescript/src/index.ts b/bindings/typescript/src/index.tsindex 66bcab4b9..2188e0bb2 100644--- a/bindings/typescript/src/index.ts+++ b/bindings/typescript/src/index.ts@@ -16,6 +16,7 @@ export interface CompositeOptions {candidates: Record<string, "capable" | "efficient">;evidence: unknown;instructions?: unknown;+ criteria?: Record<string, unknown>;};};stage: {diff --git a/crates/libsy-llm-client/src/run.rs b/crates/libsy-llm-client/src/run.rsindex 8e8053e6a..094dde2b7 100644--- a/crates/libsy-llm-client/src/run.rs+++ b/crates/libsy-llm-client/src/run.rs@@ -1447,6 +1447,7 @@ mod tests {LlmClassifierConfig::Capability {config: TaskClassifierConfig {judge: CapabilityJudgeConfig::Decision(DecisionJudgeConfig {+ criteria: None,cutoff: 0.4,instructions: None,candidates: BTreeMap::from([diff --git a/crates/libsy/src/algorithms/llm_class.rs b/crates/libsy/src/algorithms/llm_class.rsindex dd4c8ce39..450c67077 100644--- a/crates/libsy/src/algorithms/llm_class.rs+++ b/crates/libsy/src/algorithms/llm_class.rs@@ -1332,6 +1332,7 @@ mod tests {let settings = DecisionJudgeConfig {cutoff: 0.4,instructions: None,+ criteria: None,candidates: BTreeMap::from([("a".into(), "capable".into()),("b".into(), "efficient".into()),@@ -1560,6 +1561,17 @@ mod tests {.candidates.insert("duplicate-a".into(), "capable".into());assert!(duplicate.validate().is_err());+ let mut custom = settings.clone();+ custom.candidates.remove("c");+ custom.criteria = Some(BTreeMap::from([+ ("a".into(), json!("Start capable")),+ ("b".into(), json!("Start efficient")),+ ]));+ assert!(custom.validate().is_err());+ custom.instructions = Some(json!("Choose a profile."));+ assert!(custom.validate().is_ok());+ custom.candidates.remove("b");+ assert!(custom.validate().is_err());Ok(())}diff --git a/crates/libsy/src/algorithms/llm_class/decision.rs b/crates/libsy/src/algorithms/llm_class/decision.rsindex c86b3c255..efc706a77 100644--- a/crates/libsy/src/algorithms/llm_class/decision.rs+++ b/crates/libsy/src/algorithms/llm_class/decision.rs@@ -1,7 +1,7 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-//! Compare two candidates by the chance that the capable candidate alone succeeds.+//! Select a candidate by applying a cutoff to a decision model's choice score.use std::collections::{BTreeMap, HashSet};@@ -17,19 +17,21 @@ use crate::algorithms::util::llm_judge::{libsy_error_reason, report_fail_open};use crate::algorithms::util::robustness::safe_error_summary;use crate::{Classification, Classifier, Driver, LibsyError, Result, Score, State};-/// Evidence and policy for a relative-advantage decision judge.+/// Instructions, evidence, and cutoff policy for a decision judge.////// Candidate labels keep model names out of the generated context. Evidence must use/// the same labels, with unknown outcomes left unknown. Only the first runtime/// capable and efficient targets are compared; extra candidates do not add routes.#[derive(Clone, Debug)]pub struct DecisionJudgeConfig {- /// Route capable only when its advantage score is strictly above this cutoff.+ /// Route capable only when its choice score is strictly above this cutoff./// This score is not a calibrated solve probability. Choose a cutoff from evaluations.pub cutoff: f64,- /// Replaces the packaged structured instructions; must keep the meaning of- /// `advantage` (capable succeeds and efficient fails) and `no_advantage`.+ /// Replaces the packaged instructions. Without custom criteria, preserve+ /// the meaning of `advantage` and `no_advantage`.pub instructions: Option<Value>,+ /// Two choice descriptions keyed by candidate label. Requires custom instructions.+ pub criteria: Option<BTreeMap<String, Value>>,/// Maps anonymous labels used in evidence (e.g. `"a"`) to runtime model IDs./// Every compared target needs a unique label; extra candidates provide context.pub candidates: BTreeMap<String, ModelId>,@@ -51,6 +53,15 @@ impl DecisionJudgeConfig {message: "decision candidates must map to distinct targets".into(),});}+ if let Some(criteria) = &self.criteria+ && (self.instructions.is_none()+ || criteria.len() != 2+ || !criteria.keys().eq(self.candidates.keys()))+ {+ return Err(LibsyError::AlgorithmError {+ message: "custom decision criteria require instructions and exactly two matching candidates".into(),+ });+ }Ok(())}@@ -86,20 +97,28 @@ impl DecisionClassifier {)).map_err(|error| LibsyError::external("loading decision judge instructions", error))?,};- let question = DecisionQuestion {- instructions,- kind: DecisionKind::Choice {- options: [- ("advantage", "The capable candidate succeeds AND the efficient candidate fails."),- ("no_advantage", "The efficient candidate succeeds OR the capable candidate fails, including shared failure."),- ]- .into_iter()+ let options = match &config.criteria {+ Some(criteria) => criteria+ .iter().map(|(id, description)| ChoiceOption {- id: id.into(),- description: Some(json!(description)),+ id: id.clone(),+ description: Some(description.clone()),}).collect(),- },+ None => [+ ("advantage", "The capable candidate succeeds AND the efficient candidate fails."),+ ("no_advantage", "The efficient candidate succeeds OR the capable candidate fails, including shared failure."),+ ]+ .into_iter()+ .map(|(id, description)| ChoiceOption {+ id: id.into(),+ description: Some(json!(description)),+ })+ .collect(),+ };+ let question = DecisionQuestion {+ instructions,+ kind: DecisionKind::Choice { options },};Ok(Self {config,@@ -121,6 +140,11 @@ impl Classifier for DecisionClassifier {let judge = driver.first_model_for(&Category::Judge)?;let capable = driver.first_model_for(&Category::Capable)?;let efficient = driver.first_model_for(&Category::Efficient)?;+ let score_option = if self.config.criteria.is_some() {+ self.config.candidate(capable)?+ } else {+ "advantage"+ };let decision = DecisionRequest {model: None,context: json!({@@ -149,34 +173,34 @@ impl Classifier for DecisionClassifier {};// The provider's selected option can differ from the application's cutoff.// Only the requested event's score is used; confidence is a separate signal.- let advantage = response+ let score = response.answers.get("route").and_then(|answer| match &answer.value {DecisionValue::Choice {probabilities: Some(probabilities),..- } => probabilities.get("advantage").map(|p| p.0),+ } => probabilities.get(score_option).map(|p| p.0),_ => None,}).filter(|p| (0.0..=1.0).contains(p));- let Some(advantage) = advantage else {+ let Some(score) = score else {return Ok(unavailable(driver,judge,- "missing or invalid advantage score".into(),+ format!("missing or invalid {score_option} score"),"invalid_verdict",));};- let (target, category) = if advantage > self.config.cutoff {+ let (target, category) = if score > self.config.cutoff {(capable, Category::Capable)} else {(efficient, Category::Efficient)};driver.set_evidence(json!({"source": "decision_classifier",- "verdict": "relative_advantage",- "score": advantage,+ "verdict": if self.config.criteria.is_some() { "candidate_choice" } else { "relative_advantage" },+ "score": score,"threshold": self.config.cutoff,}));Ok((diff --git a/crates/switchyard-node/src/lib.rs b/crates/switchyard-node/src/lib.rsindex ed41761ac..d163a8817 100644--- a/crates/switchyard-node/src/lib.rs+++ b/crates/switchyard-node/src/lib.rs@@ -66,6 +66,7 @@ struct DecisionOptions {candidates: BTreeMap<String, Candidate>,evidence: Value,instructions: Option<Value>,+ criteria: Option<BTreeMap<String, Value>>,}#[derive(Deserialize)]@@ -127,6 +128,7 @@ impl NativeComposite {candidates,evidence: decision.evidence,instructions: decision.instructions,+ criteria: decision.criteria,}),classify_trigger: classifier.classify_trigger,fail_open: classifier.fail_open,diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex f00620cc5..04877e1d0 100644--- a/crates/switchyard-py/src/libsy_bindings.rs+++ b/crates/switchyard-py/src/libsy_bindings.rs@@ -319,14 +319,15 @@ impl PyLlmClassifierConfig {#[pymethods]impl PyTaskClassifierConfig {- /// Use a decision model's relative-advantage probability to select a target.+ /// Apply a cutoff to relative advantage or a custom candidate choice score.#[staticmethod]- #[pyo3(signature = (*, cutoff, candidates, evidence, instructions=None))]+ #[pyo3(signature = (*, cutoff, candidates, evidence, instructions=None, criteria=None))]fn decision(cutoff: f64,candidates: BTreeMap<String, String>,evidence: &Bound<'_, PyAny>,instructions: Option<&Bound<'_, PyAny>>,+ criteria: Option<&Bound<'_, PyAny>>,) -> PyResult<Self> {Ok(Self {inner: TaskClassifierConfig {@@ -338,6 +339,7 @@ impl PyTaskClassifierConfig {.collect(),evidence: from_python(evidence)?,instructions: instructions.map(from_python).transpose()?,+ criteria: criteria.map(from_python).transpose()?,}),..TaskClassifierConfig::default()},diff --git a/crates/switchyard-runner/src/algorithm.rs b/crates/switchyard-runner/src/algorithm.rsindex b41da426a..6580518c9 100644--- a/crates/switchyard-runner/src/algorithm.rs+++ b/crates/switchyard-runner/src/algorithm.rs@@ -140,6 +140,7 @@ impl CapabilityClassifierRouteConfig {CapabilityJudgeConfig::Decision(DecisionJudgeConfig {cutoff: judge.cutoff,instructions: judge.instructions,+ criteria: judge.criteria,candidates,evidence: judge.evidence,})@@ -268,14 +269,16 @@ impl CategoryModelConfig {}}-/// Relative-advantage judgment using a decision model instead of an LLM prompt.+/// Choice judgment using a decision model.#[derive(Clone, Debug, Deserialize)]#[serde(deny_unknown_fields)]pub struct DecisionJudgeRouteConfig {- /// Route capable only when its advantage score is strictly above this cutoff.+ /// Route capable only when its choice score is strictly above this cutoff.pub cutoff: f64,/// Replaces the default relative-advantage instructions.pub instructions: Option<Value>,+ /// Two choice descriptions keyed by candidate label. Requires custom instructions.+ pub criteria: Option<BTreeMap<String, Value>>,/// Anonymous evidence labels mapped to configured LLM target names.pub candidates: BTreeMap<String, String>,/// Candidate descriptions and reference outcomes, passed unchanged to the judge.diff --git a/crates/switchyard-runner/tests/openai_decisions.rs b/crates/switchyard-runner/tests/openai_decisions.rsindex b635fdf11..96cc54561 100644--- a/crates/switchyard-runner/tests/openai_decisions.rs+++ b/crates/switchyard-runner/tests/openai_decisions.rs@@ -39,10 +39,11 @@ strong_target = "strong"weak_target = "weak"fail_open = false[routes.classifier.decision]-cutoff = 0.7-candidates = {{ a = "strong", b = "weak" }}-instructions = {{ task = "Choose advantage only when a succeeds and b fails." }}-evidence = {{ description = "Compare a and b" }}+cutoff = 0.92+candidates = {{ capable_first = "strong", efficient_first = "weak" }}+criteria = {{ capable_first = "Start capable", efficient_first = "Start efficient" }}+instructions = {{ task = "Choose a Stage profile." }}+evidence = {{ description = "Compare the two profiles" }}"#);// This unique variable is only read while constructing this client.@@ -56,17 +57,18 @@ evidence = {{ description = "Compare a and b" }}let runner = runner?;let question = json!({"name": "route", "type": "choice",- "instructions": json!({"task": "Choose advantage only when a succeeds and b fails."}).to_string(),- "choices": [{"value": "advantage"}, {"value": "no_advantage"}]+ "instructions": json!({"task": "Choose a Stage profile."}).to_string(),+ "choices": [{"value": "capable_first", "description": "Start capable"},+ {"value": "efficient_first", "description": "Start efficient"}]});Mock::given(method("POST")).and(path("/v1/decisions")).and(header("authorization", "Bearer test-key")).and(body_partial_json(json!({"model": "gpt-6-luna", "questions": [question]}))).respond_with(ResponseTemplate::new(200).set_body_json(json!({"model": "gpt-6-luna", "answers": [{- "type": "choice", "name": "route", "choice": "advantage", "confidence": 0.9,- "probabilities": [{"value": "advantage", "probability": 0.6},- {"value": "no_advantage", "probability": 0.4}]+ "type": "choice", "name": "route", "choice": "capable_first", "confidence": 0.99,+ "probabilities": [{"value": "capable_first", "probability": 0.91},+ {"value": "efficient_first", "probability": 0.09}]}],"usage": {"input_tokens": 42, "input_tokens_details": {"cached_tokens": 10, "cache_write_tokens": 2},"output_tokens": 3, "output_tokens_details": {"reasoning_tokens": 1}, "total_tokens": 45}@@ -116,7 +118,7 @@ evidence = {{ description = "Compare a and b" }}let context: Value = serde_json::from_str(decision["input"].as_str().unwrap())?;assert_eq!(context["evidence"],- json!({"description": "Compare a and b"})+ json!({"description": "Compare the two profiles"}));assert_eq!(context["session"], "session-1");server.verify().await;diff --git a/docs/routing_algorithms/composite_routing.md b/docs/routing_algorithms/composite_routing.mdindex 2a806097b..3f524cacf 100644--- a/docs/routing_algorithms/composite_routing.md+++ b/docs/routing_algorithms/composite_routing.md@@ -154,12 +154,26 @@ Both candidates must be completion targets. The judge must be a decision target.See the [decision client reference](../reference/toml_schema.md#decision_clientsname)for OpenAI Decisions configuration.-The classifier selects capable when `probabilities.advantage` exceeds `cutoff`.+By default, the classifier selects capable when `probabilities.advantage` exceeds `cutoff`.Calibrate the cutoff for your tasks and models. Omit LLM-only settings such as`base_threshold`, `threshold_step` and `prompt` when using a decision model.On judge failure, the default is to retain the last classified tier or useefficient for a new session. Set `classifier.fail_open = false` to return the error.+To ask a custom two-choice question, set `instructions` and `criteria` in the+decision block. Criteria keys must exactly match the two candidate labels.+The probability for the label mapped to the capable target must exceed `cutoff`+to select that tier. This also works in standalone and Stage decision judges.++```toml+[routes.switchyard.classifier.decision]+cutoff = 0.92+candidates = { capable_first = "strong", efficient_first = "weak" }+instructions = "Choose the Stage profile best suited to the task."+criteria = { capable_first = "Start capable", efficient_first = "Start efficient" }+evidence = {}+```+## SessionsThe tier is retained per session, so send `x-switchyard-session-id` and eachdiff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.pyindex da53ee214..d9228e63f 100644--- a/switchyard_rust/libsy.py+++ b/switchyard_rust/libsy.py@@ -215,8 +215,9 @@ if TYPE_CHECKING:candidates: Mapping[str, str],evidence: object,instructions: object | None = None,+ criteria: Mapping[str, object] | None = None,) -> TaskClassifierConfig:- """Use relative advantage with the default routing and fallback settings."""+ """Apply a cutoff to relative advantage or a custom candidate choice score."""...def __init__(