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(router): allow custom decision criteria (#1187)

ryan-lempkaf7d010dbd4f2
diff --git a/bindings/typescript/src/index.ts b/bindings/typescript/src/index.ts
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 use
efficient 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 = {}
+```
+
## Sessions
The tier is retained per session, so send `x-switchyard-session-id` and each
diff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.py
index 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__(