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(routing): add probability capability policy (#296)

Ayush Agarwal5c25651bc52e
diff --git a/benchmark/server-configs/tb-lite-llm-classifier-opus-kimi-gemini.toml b/benchmark/server-configs/tb-lite-llm-classifier-opus-kimi-gemini.toml
index 0ddfd9823..d815dc877 100644
--- a/benchmark/server-configs/tb-lite-llm-classifier-opus-kimi-gemini.toml
+++ b/benchmark/server-configs/tb-lite-llm-classifier-opus-kimi-gemini.toml
@@ -30,6 +30,6 @@ classifier_target = "classifier"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5
-min_confidence = 0.0
+threshold_step = 0.0
session_affinity = true
message_hash_fallback = true
diff --git a/crates/libsy/examples/research_agent.rs b/crates/libsy/examples/research_agent.rs
index 81d651cd4..06126a49f 100644
--- a/crates/libsy/examples/research_agent.rs
+++ b/crates/libsy/examples/research_agent.rs
@@ -45,7 +45,7 @@ impl RoutedLlmClient for StubClient {
println!(" -> model call: {model}");
// The judge returns a structured verdict; other models return an answer.
let completion = if model == CLASSIFIER {
- r#"{"recommended_route":"efficient","p_solve":0.9,"confidence":0.9,"abstain":false,"capability_boundary":"supported","primary_rule":"SUP-1","crux":"bounded task"}"#.to_string()
+ r#"{"crux":"bounded task","primary_rule":"SUP-1","capability_boundary":"supported","p_solve":0.9}"#.to_string()
} else {
format!("answer from {model}")
};
diff --git a/crates/libsy/examples/research_agent_core.rs b/crates/libsy/examples/research_agent_core.rs
index 6a655873a..04e8e76fc 100644
--- a/crates/libsy/examples/research_agent_core.rs
+++ b/crates/libsy/examples/research_agent_core.rs
@@ -32,7 +32,7 @@ const BASE_THRESHOLD: f64 = 0.5;
async fn call_model(model: &str) -> Response {
println!(" -> model call: {model}");
let completion = if model == CLASSIFIER {
- r#"{"recommended_route":"efficient","p_solve":0.9,"confidence":0.9,"abstain":false,"capability_boundary":"supported","primary_rule":"SUP-1","crux":"bounded task"}"#.to_string()
+ r#"{"crux":"bounded task","primary_rule":"SUP-1","capability_boundary":"supported","p_solve":0.9}"#.to_string()
} else {
format!("answer from {model}")
};
diff --git a/crates/libsy/src/algorithms/llm_class.rs b/crates/libsy/src/algorithms/llm_class.rs
index 6ec775f2a..05cc4052d 100644
--- a/crates/libsy/src/algorithms/llm_class.rs
+++ b/crates/libsy/src/algorithms/llm_class.rs
@@ -37,36 +37,37 @@ const ALGORITHM_NAME: &str = "llm_task_classifier";
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct TaskClassifierVerdict {
- #[serde(rename = "recommended_route")]
- _recommended_route: String,
- p_solve: f64,
- confidence: f64,
- abstain: bool,
+ crux: String,
+ primary_rule: String,
capability_boundary: String,
- #[serde(rename = "primary_rule")]
- _primary_rule: String,
- #[serde(rename = "crux")]
- _crux: String,
+ p_solve: f64,
}
impl TaskClassifierVerdict {
- /// Reject out-of-range probabilities before the policy can route efficiently. Range
- /// containment also rejects NaN and the infinities, which compare false against both bounds.
+ /// Rejects malformed or internally inconsistent verdicts before policy evaluation.
fn is_valid(&self) -> bool {
(0.0..=1.0).contains(&self.p_solve)
- && (0.0..=1.0).contains(&self.confidence)
+ && !self.crux.trim().is_empty()
&& matches!(
- self.capability_boundary.as_str(),
- "supported" | "uncertain" | "unsupported" | "unmatched"
+ (
+ self.primary_rule.as_str(),
+ self.capability_boundary.as_str()
+ ),
+ ("SUP-1" | "SUP-2" | "SUP-3" | "SUP-4" | "SUP-5", "supported")
+ | ("UNC-1" | "UNC-2", "uncertain")
+ | ("LIM-1" | "LIM-2", "unsupported")
+ | ("none", "unmatched")
)
}
- /// Whether the capability boundary requires the elevated routing threshold.
- fn is_capability_elevated(&self) -> bool {
- matches!(
- self.capability_boundary.as_str(),
- "uncertain" | "unsupported" | "unmatched"
- )
+ /// Returns the number of threshold steps assigned to this capability boundary.
+ fn boundary_steps(&self) -> Option<u8> {
+ match self.capability_boundary.as_str() {
+ "supported" => Some(0),
+ "uncertain" | "unmatched" => Some(1),
+ "unsupported" => Some(2),
+ _ => None,
+ }
}
}
@@ -92,6 +93,18 @@ fn trim_messages(messages: &[Message], recent_turn_window: usize) -> Vec<Message
kept.into_iter().cloned().collect()
}
+/// Keeps the opening task and the latest user follow-up when they differ.
+fn task_messages(messages: &[Message]) -> Vec<Message> {
+ let mut user_messages = messages.iter().filter(|message| message.role == Role::User);
+ let Some(opening_task) = user_messages.next() else {
+ return Vec::new();
+ };
+ match user_messages.next_back() {
+ Some(latest_follow_up) => vec![opening_task.clone(), latest_follow_up.clone()],
+ None => vec![opening_task.clone()],
+ }
+}
+
/// Selects the task messages shown to capability and custom-schema classifiers.
struct TaskInput {
recent_turn_window: Option<usize>,
@@ -99,19 +112,11 @@ struct TaskInput {
impl ClassifierInput for TaskInput {
fn build_messages(&self, _state: &State, request: &Request) -> Vec<Message> {
- // Task-based routing judges the newest user message alone. A configured
- // window widens that to the surrounding conversation.
+ // The default preserves the whole-task anchor and latest user update. A
+ // configured window widens that to the surrounding conversation.
match self.recent_turn_window {
Some(window) => trim_messages(&request.llm_request.messages, window),
- None => request
- .llm_request
- .messages
- .iter()
- .rev()
- .find(|message| message.role == Role::User)
- .cloned()
- .into_iter()
- .collect(),
+ None => task_messages(&request.llm_request.messages),
}
}
}
@@ -122,8 +127,7 @@ struct TaskClassifierPolicy {
efficient_target: String,
capable_target: String,
base_threshold: f64,
- min_confidence: f64,
- capability_elevated_floor: Option<f64>,
+ threshold_step: f64,
}
impl TaskClassifierPolicy {
@@ -136,19 +140,13 @@ impl TaskClassifierPolicy {
efficient_target: efficient_target.into(),
capable_target: capable_target.into(),
base_threshold: config.base_threshold,
- min_confidence: config.min_confidence,
- capability_elevated_floor: config.capability_elevated_floor,
+ threshold_step: config.threshold_step,
}
}
/// Returns the required solve probability for one validated verdict.
- fn threshold(&self, verdict: &TaskClassifierVerdict) -> f64 {
- if verdict.is_capability_elevated() {
- self.capability_elevated_floor
- .unwrap_or(self.base_threshold)
- } else {
- self.base_threshold
- }
+ fn threshold(&self, verdict: &TaskClassifierVerdict) -> Option<f64> {
+ Some(self.base_threshold + f64::from(verdict.boundary_steps()?) * self.threshold_step)
}
}
@@ -156,18 +154,19 @@ impl JudgePolicy for TaskClassifierPolicy {
type Verdict = TaskClassifierVerdict;
fn to_classification(&self, verdict: Option<&Self::Verdict>) -> Classification {
- // Judge output is untrusted, so only a complete, valid, non-abstained verdict that
- // clears the configured confidence decides. Anything else is "I could not tell" —
- // reported as ambiguous so the composition around this classifier chooses the
- // fallback, rather than this policy silently imposing one.
- let Some(verdict) =
- verdict.filter(|v| v.is_valid() && !v.abstain && v.confidence >= self.min_confidence)
- else {
+ // Judge output is untrusted. An absent, invalid, or inconsistent verdict is
+ // ambiguous so the surrounding router applies its configured fallback.
+ let Some(verdict) = verdict.filter(|verdict| verdict.is_valid()) else {
return Classification::Ambiguous(vec![]);
};
// A usable verdict below the capability threshold is still a decision: the judge
// does not trust the efficient tier with this task.
- let target = if verdict.p_solve >= self.threshold(verdict) {
+ let Some(threshold) = self.threshold(verdict) else {
+ return Classification::Ambiguous(vec![]);
+ };
+ let target = if verdict.p_solve >= threshold
+ || (threshold - verdict.p_solve).abs() <= f64::EPSILON
+ {
&self.efficient_target
} else {
&self.capable_target
@@ -184,10 +183,11 @@ impl JudgePolicy for TaskClassifierPolicy {
pub struct TaskClassifierConfig {
/// Lowest solve probability that routes a supported task to the efficient target.
pub base_threshold: f64,
- /// Lowest judge confidence that permits efficient routing.
- pub min_confidence: f64,
- /// Higher solve-probability floor for uncertain, unmatched, and unsupported tasks.
- pub capability_elevated_floor: Option<f64>,
+ /// Amount added per capability-boundary step.
+ ///
+ /// Supported verdicts use `base_threshold`, uncertain and unmatched verdicts use one
+ /// step, and unsupported verdicts use two steps.
+ pub threshold_step: f64,
/// Enables session affinity before the judge-backed classifier.
pub session_affinity: bool,
/// Uses the first user message as the SessionKey for sticky routing when session metadata is unavailable.
@@ -195,9 +195,9 @@ pub struct TaskClassifierConfig {
/// Trailing conversation turns the judge sees on top of the client
/// instructions and the opening task.
///
- /// `None` (the default) judges the newest user message alone — the task, with
- /// no history. `Some(n)` widens that to the client instructions, the opening
- /// task, and the last `n` turns after it.
+ /// `None` (the default) judges the opening task and latest user follow-up.
+ /// `Some(n)` widens that to the client instructions, the opening task, and
+ /// the last `n` turns after it.
pub recent_turn_window: Option<usize>,
/// Prompt and verdict contract settings for the classifier judge.
pub contract: ClassifierContractConfig,
@@ -211,9 +211,7 @@ pub struct TaskClassifierConfig {
struct TaskClassifierConfigWire {
base_threshold: f64,
#[serde(default)]
- min_confidence: f64,
- #[serde(default)]
- capability_elevated_floor: Option<f64>,
+ threshold_step: f64,
#[serde(default)]
session_affinity: bool,
#[serde(default)]
@@ -238,8 +236,7 @@ impl<'de> Deserialize<'de> for TaskClassifierConfig {
}
Ok(Self {
base_threshold: wire.base_threshold,
- min_confidence: wire.min_confidence,
- capability_elevated_floor: wire.capability_elevated_floor,
+ threshold_step: wire.threshold_step,
session_affinity: wire.session_affinity,
message_hash_fallback: wire.message_hash_fallback,
recent_turn_window: wire.recent_turn_window,
@@ -257,8 +254,7 @@ impl Default for TaskClassifierConfig {
fn default() -> Self {
Self {
base_threshold: 0.0,
- min_confidence: 0.0,
- capability_elevated_floor: None,
+ threshold_step: 0.0,
session_affinity: false,
message_hash_fallback: false,
recent_turn_window: None,
@@ -279,29 +275,21 @@ impl TaskClassifierConfig {
),
});
}
- if !(0.0..=1.0).contains(&self.min_confidence) {
+ if !self.threshold_step.is_finite() || self.threshold_step < 0.0 {
return Err(LibsyError::AlgorithmError {
message: format!(
- "min_confidence must be between 0 and 1, got {}",
- self.min_confidence
+ "threshold_step must be finite and greater than or equal to 0, got {}",
+ self.threshold_step
),
});
}
- if let Some(floor) = self.capability_elevated_floor {
- if !(0.0..=1.0).contains(&floor) {
- return Err(LibsyError::AlgorithmError {
- message: format!(
- "capability_elevated_floor must be between 0 and 1, got {floor}"
- ),
- });
- }
- if floor <= self.base_threshold {
- return Err(LibsyError::AlgorithmError {
- message: format!(
- "capability_elevated_floor must be greater than base_threshold, got {floor}"
- ),
- });
- }
+ let unsupported_threshold = self.base_threshold + 2.0 * self.threshold_step;
+ if unsupported_threshold > 1.0 && unsupported_threshold - 1.0 > f64::EPSILON {
+ return Err(LibsyError::AlgorithmError {
+ message: format!(
+ "base_threshold + 2 * threshold_step must be at most 1, got {unsupported_threshold}"
+ ),
+ });
}
if self.max_output_tokens == 0 {
return Err(LibsyError::AlgorithmError {
@@ -936,16 +924,16 @@ mod tests {
TaskClassifierPolicy::new("efficient", "capable", &test_config(TEST_THRESHOLD))
}
- /// A verdict whose non-routing fields are fixed — only the three the policy reads vary.
- fn verdict(p_solve: f64, confidence: f64, abstain: bool) -> TaskClassifierVerdict {
+ fn verdict(
+ p_solve: f64,
+ capability_boundary: &str,
+ primary_rule: &str,
+ ) -> TaskClassifierVerdict {
TaskClassifierVerdict {
- _recommended_route: "efficient".to_string(),
+ crux: "test crux".to_string(),
+ primary_rule: primary_rule.to_string(),
+ capability_boundary: capability_boundary.to_string(),
p_solve,
- confidence,
- abstain,
- capability_boundary: "supported".to_string(),
- _primary_rule: "SUP-1".to_string(),
- _crux: "test crux".to_string(),
}
}
@@ -1004,7 +992,7 @@ mod tests {
.first()
.and_then(|message| message.text_content("\n")),
);
- r#"{"recommended_route":"efficient","p_solve":0.9,"confidence":0.9,"abstain":false,"capability_boundary":"supported","primary_rule":"SUP-1","crux":"bounded task"}"#.to_string()
+ r#"{"crux":"bounded task","primary_rule":"SUP-1","capability_boundary":"supported","p_solve":0.9}"#.to_string()
} else {
format!("answer from {model}")
};
@@ -1150,7 +1138,7 @@ mod tests {
capable_target: target("capable"),
config: TaskClassifierConfig {
contract: ClassifierContractConfig::default()
- .with_prompt("Custom capability rubric:\n{{RESPONSE_SCHEMA}}"),
+ .with_prompt("Custom capability rubric."),
..test_config(TEST_THRESHOLD)
},
})?);
@@ -1159,9 +1147,7 @@ mod tests {
let prompts = client.judge_system_prompts();
assert_eq!(prompts.len(), 1);
- assert!(prompts[0].starts_with("Custom capability rubric:"));
- assert!(prompts[0].contains("\"recommended_route\""));
- assert!(!prompts[0].contains("{{RESPONSE_SCHEMA}}"));
+ assert_eq!(prompts[0], "Custom capability rubric.");
Ok(())
}
@@ -1230,8 +1216,8 @@ mod tests {
#[test]
fn the_threshold_boundary_is_inclusive() -> Result<()> {
let policy = policy();
- let at_threshold = verdict(0.5, 0.0, false);
- let below_threshold = verdict(0.49, 1.0, false);
+ let at_threshold = verdict(0.5, "supported", "SUP-1");
+ let below_threshold = verdict(0.49, "supported", "SUP-1");
assert_eq!(selected(&policy, Some(&at_threshold))?, "efficient");
assert_eq!(selected(&policy, Some(&below_threshold))?, "capable");
Ok(())
@@ -1239,7 +1225,7 @@ mod tests {
#[test]
fn the_threshold_moves_the_routing_boundary() -> Result<()> {
- let borderline = verdict(0.5, 1.0, false);
+ let borderline = verdict(0.5, "supported", "SUP-1");
let strict = TaskClassifierPolicy::new("efficient", "capable", &test_config(0.9));
let lenient = TaskClassifierPolicy::new("efficient", "capable", &test_config(0.1));
assert_eq!(selected(&strict, Some(&borderline))?, "capable");
@@ -1284,12 +1270,12 @@ mod tests {
for config in [
TaskClassifierConfig {
base_threshold: 0.5,
- min_confidence: 1.1,
+ threshold_step: -0.1,
..TaskClassifierConfig::default()
},
TaskClassifierConfig {
- base_threshold: 0.5,
- capability_elevated_floor: Some(0.5),
+ base_threshold: 0.8,
+ threshold_step: 0.11,
..TaskClassifierConfig::default()
},
TaskClassifierConfig {
@@ -1325,19 +1311,20 @@ mod tests {
}
#[test]
- fn an_unusable_verdict_abstains() -> Result<()> {
- // Invalid, abstained, unintelligible, or absent: the judge could not tell,
- // so it declines to decide and leaves the fallback to whoever composed the
- // cascade.
+ fn an_unusable_verdict_is_ambiguous() -> Result<()> {
let policy = policy();
- let invalid_boundary = TaskClassifierVerdict {
- capability_boundary: "unknown".to_string(),
- ..verdict(1.0, 1.0, false)
+ let inconsistent_rule = TaskClassifierVerdict {
+ capability_boundary: "uncertain".to_string(),
+ ..verdict(1.0, "supported", "SUP-1")
+ };
+ let empty_crux = TaskClassifierVerdict {
+ crux: " ".to_string(),
+ ..verdict(1.0, "supported", "SUP-1")
};
let unusable = [
- Some(verdict(1.1, 1.0, false)),
- Some(verdict(1.0, 1.0, true)),
- Some(invalid_boundary),
+ Some(verdict(1.1, "supported", "SUP-1")),
+ Some(inconsistent_rule),
+ Some(empty_crux),
None,
];
for verdict in unusable {
@@ -1350,28 +1337,40 @@ mod tests {
}
#[test]
- fn elevated_capability_floor_is_a_targeted_safety_brake() -> Result<()> {
+ fn capability_boundaries_apply_monotonic_threshold_steps() -> Result<()> {
let policy = TaskClassifierPolicy::new(
"efficient",
"capable",
&TaskClassifierConfig {
- capability_elevated_floor: Some(0.45),
- ..test_config(0.25)
+ threshold_step: 0.1,
+ ..test_config(0.4)
},
);
- let supported = verdict(0.30, 1.0, false);
- let elevated = TaskClassifierVerdict {
- capability_boundary: "uncertain".to_string(),
- ..verdict(0.30, 1.0, false)
- };
- let strong_elevated = TaskClassifierVerdict {
- capability_boundary: "unsupported".to_string(),
- ..verdict(0.50, 1.0, false)
- };
- assert_eq!(selected(&policy, Some(&supported))?, "efficient");
- assert_eq!(selected(&policy, Some(&elevated))?, "capable");
- assert_eq!(selected(&policy, Some(&strong_elevated))?, "efficient");
+ assert_eq!(
+ selected(&policy, Some(&verdict(0.4, "supported", "SUP-2")))?,
+ "efficient"
+ );
+ assert_eq!(
+ selected(&policy, Some(&verdict(0.49, "uncertain", "UNC-1")))?,
+ "capable"
+ );
+ assert_eq!(
+ selected(&policy, Some(&verdict(0.5, "uncertain", "UNC-1")))?,
+ "efficient"
+ );
+ assert_eq!(
+ selected(&policy, Some(&verdict(0.5, "unmatched", "none")))?,
+ "efficient"
+ );
+ assert_eq!(
+ selected(&policy, Some(&verdict(0.59, "unsupported", "LIM-1")))?,
+ "capable"
+ );
+ assert_eq!(
+ selected(&policy, Some(&verdict(0.6, "unsupported", "LIM-1")))?,
+ "efficient"
+ );
Ok(())
}
@@ -1459,7 +1458,7 @@ mod tests {
let judge_request = judge.build_request(&State::default(), &request);
assert_eq!(judge_request.llm_request.model, request.llm_request.model);
- assert_eq!(judge_request.llm_request.messages.len(), 2);
+ assert_eq!(judge_request.llm_request.messages.len(), 3);
let contents = judge_request
.llm_request
.messages
@@ -1467,7 +1466,7 @@ mod tests {
.filter_map(|message| message.text_content("\n"))
.collect::<Vec<_>>();
assert!(contents.contains(&"recent 4".to_string()));
- assert!(!contents.contains(&"initial task".to_string()));
+ assert!(contents.contains(&"initial task".to_string()));
assert!(!contents.contains(&"recent 5".to_string()));
assert!(!contents.contains(&"client instructions".to_string()));
assert_eq!(
@@ -1532,22 +1531,29 @@ mod tests {
let verdict = judge.parse(&text_response(None, reply))?;
assert!(verdict.is_valid());
- assert!(!verdict.abstain);
+ assert!((0.0..=1.0).contains(&verdict.p_solve));
Ok(())
}
#[test]
- fn prompt_includes_concrete_rules_and_schema() -> Result<()> {
+ fn packaged_prompt_keeps_the_schema_in_the_structured_request() -> Result<()> {
let contract =
LlmTaskClassifier::load_capability_contract(&ClassifierContractConfig::default())?;
let prompt = contract.system_prompt();
+ let schema_name = contract
+ .response_format()
+ .pointer("/json_schema/name")
+ .and_then(Value::as_str)
+ .ok_or_else(|| LibsyError::AlgorithmError {
+ message: "packaged response schema has no name".to_string(),
+ })?;
+ assert_eq!(schema_name, "CapabilityClassifierDecision");
assert!(prompt.contains("SUP-1 [supported]"));
- assert!(!prompt.contains("{{CAPABILITY_RULES}}"));
- assert!(!prompt.contains("{{PRIMARY_RULE_VALUES}}"));
+ assert!(prompt.contains("SUP-5 [supported]"));
assert!(!prompt.contains("{{RESPONSE_SCHEMA}}"));
- assert!(prompt.contains("\"type\": \"object\""));
+ assert!(!prompt.contains("\"type\": \"object\""));
assert!(!prompt.contains("\"json_schema\""));
- assert!(!prompt.contains("\"CapabilityClassifierDecision\""));
+ assert!(!prompt.contains(schema_name));
let rule_values = contract
.response_format()
.pointer("/json_schema/schema/properties/primary_rule/enum")
@@ -1663,8 +1669,7 @@ mod tests {
judge_target: target("judge"),
efficient_target: target("efficient"),
capable_target: target("capable"),
- contract: ClassifierContractConfig::default()
- .with_prompt("Custom trajectory rubric:\n{{RESPONSE_SCHEMA}}"),
+ contract: ClassifierContractConfig::default().with_prompt("Custom trajectory rubric."),
config: EscalationJudgeConfig {
confirmations: 1,
..EscalationJudgeConfig::default()
@@ -1676,9 +1681,7 @@ mod tests {
let prompts = client.judge_system_prompts();
assert_eq!(prompts.len(), 1);
- assert!(prompts[0].starts_with("Custom trajectory rubric:"));
- assert!(prompts[0].contains("\"escalate\""));
- assert!(!prompts[0].contains("{{RESPONSE_SCHEMA}}"));
+ assert_eq!(prompts[0], "Custom trajectory rubric.");
Ok(())
}
diff --git a/crates/libsy/src/algorithms/stage.rs b/crates/libsy/src/algorithms/stage.rs
index aa162d6ed..a2612d69e 100644
--- a/crates/libsy/src/algorithms/stage.rs
+++ b/crates/libsy/src/algorithms/stage.rs
@@ -405,7 +405,7 @@ mod tests {
let completion = if target == JUDGE {
let p_solve = *self.judge_p_solve.lock();
format!(
- r#"{{"recommended_route":"efficient","p_solve":{p_solve},"confidence":0.9,"abstain":false,"capability_boundary":"supported","primary_rule":"SUP-1","crux":"bounded task"}}"#
+ r#"{{"crux":"bounded task","primary_rule":"SUP-1","capability_boundary":"supported","p_solve":{p_solve}}}"#
)
} else {
target
diff --git a/crates/libsy/src/algorithms/util/classifier_contract.rs b/crates/libsy/src/algorithms/util/classifier_contract.rs
index 9855ac2c1..d3298dcf3 100644
--- a/crates/libsy/src/algorithms/util/classifier_contract.rs
+++ b/crates/libsy/src/algorithms/util/classifier_contract.rs
@@ -42,9 +42,8 @@ pub(crate) struct ClassifierContract {
impl ClassifierContract {
/// Builds a contract from user settings and packaged defaults.
///
- /// The response format must contain `json_schema.schema`. Its inner schema replaces every
- /// `{{RESPONSE_SCHEMA}}` placeholder in the prompt, while the complete response format is
- /// retained for the model request.
+ /// The response format must contain `json_schema.schema` and is retained separately for the
+ /// model request. Schemas are never copied into the system prompt.
pub(crate) fn from_config(
config: &ClassifierContractConfig,
default_prompt: &str,
@@ -94,20 +93,19 @@ impl ClassifierContract {
message: "classifier prompt must not be empty".to_string(),
});
}
- let response_schema = response_format
+ if prompt_template.contains("{{RESPONSE_SCHEMA}}") {
+ return Err(LibsyError::AlgorithmError {
+ message: "classifier prompt must not include {{RESPONSE_SCHEMA}}; the response schema is sent separately".to_string(),
+ });
+ }
+ response_format
.pointer("/json_schema/schema")
.ok_or_else(|| LibsyError::AlgorithmError {
message: "response schema has no json_schema.schema".to_string(),
- })?
- .clone();
- let prompt_schema = serde_json::to_string_pretty(&response_schema).map_err(|error| {
- LibsyError::AlgorithmError {
- message: format!("prompt schema could not be rendered: {error}"),
- }
- })?;
+ })?;
Ok(Self {
- system_prompt: prompt_template.replace("{{RESPONSE_SCHEMA}}", &prompt_schema),
+ system_prompt: prompt_template.to_string(),
response_format,
validator,
})
@@ -158,7 +156,7 @@ mod tests {
use super::*;
#[test]
- fn a_runtime_contract_renders_its_own_schema() -> Result<()> {
+ fn a_runtime_contract_keeps_its_schema_out_of_the_prompt() -> Result<()> {
let schema = r#"{
"type": "json_schema",
"json_schema": {
@@ -169,12 +167,16 @@ mod tests {
}
}
}"#;
- let config = ClassifierContractConfig::default()
- .with_prompt("Return a risk verdict matching:\n{{RESPONSE_SCHEMA}}");
+ let config = ClassifierContractConfig::default().with_prompt(
+ "Return a risk verdict matching the response schema supplied with the request.",
+ );
let contract = ClassifierContract::from_config(&config, "packaged prompt", schema)?;
- assert!(contract.system_prompt().contains("\"risk\""));
- assert!(!contract.system_prompt().contains("{{RESPONSE_SCHEMA}}"));
+ assert_eq!(
+ contract.system_prompt(),
+ "Return a risk verdict matching the response schema supplied with the request."
+ );
+ assert!(!contract.system_prompt().contains("\"risk\""));
assert_eq!(
contract
.response_format()
@@ -210,10 +212,24 @@ mod tests {
assert!(error.to_string().contains("prompt must not be empty"));
}
+ #[test]
+ fn a_contract_rejects_a_response_schema_placeholder() {
+ let config = ClassifierContractConfig::default()
+ .with_prompt("Return JSON matching {{RESPONSE_SCHEMA}}");
+ let error = ClassifierContract::from_config(
+ &config,
+ "packaged prompt",
+ r#"{"json_schema":{"schema":{"type":"object"}}}"#,
+ )
+ .expect_err("schema placeholders should be rejected");
+
+ assert!(error.to_string().contains("schema is sent separately"));
+ }
+
#[test]
fn a_custom_contract_wraps_and_validates_its_inner_schema() -> Result<()> {
let contract = ClassifierContract::from_inner_schema(
- "Choose a target:\n{{RESPONSE_SCHEMA}}",
+ "Choose a target matching the response schema supplied with the request.",
json!({
"type": "object",
"$defs": {
@@ -248,7 +264,7 @@ mod tests {
.and_then(Value::as_bool),
Some(true)
);
- assert!(contract.system_prompt().contains("\"target\""));
+ assert!(!contract.system_prompt().contains("\"target\""));
contract.validate_verdict(&json!({"decision": {"target": "sonnet"}}))?;
assert!(
contract
diff --git a/crates/libsy/src/prompts/capability-classifier/prompt.md b/crates/libsy/src/prompts/capability-classifier/prompt.md
index fdc983e30..005770444 100644
--- a/crates/libsy/src/prompts/capability-classifier/prompt.md
+++ b/crates/libsy/src/prompts/capability-classifier/prompt.md
@@ -1,74 +1,60 @@
-You are a task-level routing classifier for an agent harness. You receive only
-the task's initial instruction. Estimate whether the efficient agent, GLM-5.2,
-will complete the whole task correctly. Routing is sticky: the selected agent
-owns the task through completion.
+You are a task-level probability forecaster for a model router. You receive the
+task's opening instruction and, when present, its latest user follow-up, plus
+the qualitative capability card below.
-Use only conditions visible in the instruction. Never assume hidden environment
-facts, artifact integrity, tools, dependencies, tests, or access. Capability is
-determined by verification, boundedness, and closure risk rather than topic or
-component count.
+Forecast one binary event:
-# Definitions
+SUCCESS means that the efficient agent completes the whole task correctly on
+one fresh run under the actual harness, tools, and budget, as judged by the
+final verifier. FAILURE means any other outcome. The two outcomes are
+exhaustive.
-- Authoritative verification is independent_full when an evaluator, reference,
- checksum, regression suite, replay, or end-to-end client independent of the
- proposed solution checks the complete final output or state.
-- Verification is partial_or_self_authored when it is a smoke test, a check the
- solver must invent, or covers only part of correctness.
-- Verification is hidden_or_private when final acceptance uses inaccessible
- data, edge cases, thresholds, rankings, or conventions. A stated public check
- or numeric target does not make private acceptance independent_full.
-- Verification is not_stated when the instruction names no way to falsify a
- wrong final result. Do not infer that a repository contains tests.
-- An inverse, recovery, or search is bounded only when the instruction exposes
- a finite or tightly constrained hypothesis space, source or format structure,
- rich reference pairs, a checksum, or an authoritative replay check. A topic
- such as cryptanalysis or reverse engineering is not inherently unbounded.
-- Closure risk is the risk that substantial exploration or a chain of fixes
- will not be converted into the saved, re-run, fully verified final artifact.
- Several components with an early end-to-end acceptance endpoint can be
- bounded; an open-ended compatibility campaign is not bounded merely because
- a final test command exists.
+Use only evidence in the instruction and the capability card. Do not assume
+hidden repository state, unmentioned tools, validators, documentation, access,
+or future work habits. Do not invent empirical counts, success rates, or base
+rates. The capability card is qualitative evidence, not a measured prior.
# Assessment procedure
-1. State the hardest requirement without assuming hidden environment facts.
-2. Classify the authoritative verification visible in the instruction using
- the definitions above.
-3. Decide whether every inverse, recovery, or search is bounded and
- independently testable.
-4. Check whether the deliverable must work in a clean environment under stated
- dependency constraints.
-5. Estimate exploration and submission-closure risk separately from conceptual
- difficulty or the number of named components.
-6. Select the one capability rule that best matches those conditions. Set
- capability_boundary to that rule's assigned boundary. Rule ids are opaque;
- never infer meaning from their spelling. Use unmatched with primary_rule=none
- when no rule applies or instruction-visible evidence is insufficient.
-7. Estimate p_solve for whole-task completion, then make a quality-first route
- recommendation. Recommend efficient only when the evidence strongly covers
- the crux. Recommend capable for unstable, hidden-acceptance, latent-state, or
- material closure-risk cases.
-
-Set abstain=true only when the instruction is too incomplete to assess. Set
-confidence to confidence in this assessment, not probability of task success.
-Do not encode cost preferences in p_solve or recommended_route.
-
-# Capability boundaries
-
-[CAPABILITY_CARD]
-- SUP-1 [supported]: Deterministic extraction, validation, counting, aggregation, normalization, exact-schema generation, or single-regex construction when input formats, boundary rules, tie-breaking, reference conventions, and output ordering are explicit and locally checkable; exclude learned-model similarity/ranking, evolving external sources, or multi-hop ontology queries whose semantic joins and status rules must be inferred.
-- SUP-2 [supported]: Conventional local software, service, dependency, build, proof, or artifact implementation/repair, including simple RPC services and compiling specified or publicly locatable source, when the required interface, files, commands, ports, invariants, or sanity checks are explicit and a local build, compiler, unit check, render command, or exact output check can directly validate completion.
-- SUP-3 [supported]: Bounded reverse engineering, cryptanalysis, or artifact recovery when the instruction supplies source, a chosen oracle, or a standard self-describing format; the requested state is small or structurally constrained, and parser validation, replay, checksum, coverage scoring, or local oracle checks can validate the result. Includes standard executable segment/value extraction and toy-cipher key-component recovery; exclude unknown storage remnants unless the search is explicitly small and verified.
-- UNC-1 [uncertain]: Exact-answer tasks involving external or historical leaderboards, learned embedding/model rankings, computer-vision event timing, statistical, causal, accuracy, or performance claims, or schema-heavy semantic queries where correctness depends on hidden/private data, evolving web state, sampling variability, model/library conventions, inferred ontology semantics, or unspecified tolerances; explicit formal specifications with direct local edge-case tests are excluded.
-- UNC-2 [uncertain]: Byte-identical reimplementation or porting of a program with persistent file mutations where correctness depends on legacy or runtime-specific record I/O, padding, numeric encodings, short-record handling, or update ordering, even if source and an executable comparison are available.
-- UNC-3 [uncertain]: Independent source reconstruction or broad behavior recovery for an unknown compiled program or black-box artifact with no exhaustive specification; observed I/O or disassembly gives only partial confidence unless the task is tightly bounded and exactly verified. Do not apply to standard-format metadata/segment extraction or provided-source bounded cryptanalysis.
-- UNC-4 [uncertain]: Deleted-file or forensic password recovery from filesystem remnants, disk images, fragmented archives, or unknown storage layers when the instruction gives only filename or pattern constraints and recovery may require carving, fragment assembly, checksum reasoning, or large search over missing bytes.
-- LIM-1 [unsupported]: Exact reconstruction or semantic equivalence over unbounded hypotheses with no source, bounded search space, rich reference pairs, checksum, replay, or exhaustive oracle; do not apply when the instruction supplies enough structure to make the inverse testable.
-[/CAPABILITY_CARD]
+1. State the crux: the hardest material requirement for whole-task success.
+2. Select the one capability rule that best describes the crux. Use
+ primary_rule=none and capability_boundary=unmatched when no rule applies.
+ Rule ids are opaque labels. Do not infer a boundary from an id's spelling.
+3. Privately identify the strongest instruction-visible reasons for SUCCESS
+ and FAILURE, then imagine the most likely concrete failure.
+4. Privately consider material unknowns. Missing information should limit
+ extreme estimates, but it is not evidence that p_solve must equal 0.50.
+5. Estimate p_solve last. It is the probability of whole-task SUCCESS, not
+ confidence in this assessment, a route recommendation, or a cost judgment.
+
+Interpret probabilities as natural frequencies. If p_solve is 0.70 for 100
+comparable fresh runs, about 70 should succeed and 30 should fail. Use the full
+range when justified. Reserve 0.00 and 1.00 for outcomes that are logically
+impossible or certain under the visible contract. Supported does not mean 1.00,
+and unsupported does not mean 0.00. The downstream routing threshold is not
+part of this forecast.
+
+# Efficient-agent capability card
+
+The route verbs in this source card are inherited qualitative descriptions.
+They do not ask you to output a route and do not assign a fixed probability to
+any boundary.
+
+- SUP-1 [supported]: Route to the Efficient model when the task provides a complete output contract and a deterministic local validator that covers the material requirements.
+- SUP-2 [supported]: Route to the Efficient model when all required inputs are available, the target environment can be inspected, and correctness can be verified end-to-end without inaccessible external state.
+- SUP-3 [supported]: Route to the Efficient model when mathematical behavior, interfaces, shapes, data types, tolerances, and performance requirements are explicit and exercised by a representative harness.
+- SUP-4 [supported]: Route to the Efficient model when the required mechanism is identified, the relevant search space is bounded, and the success condition is executable. Do not infer this rule merely from the task's technical domain.
+- SUP-5 [supported]: Route to the Efficient model when reconstruction or behavioral reproduction is constrained by an executable reference, parser, format specification, or checker strong enough to distinguish correct from merely plausible output.
+- UNC-1 [uncertain]: Treat the route as uncertain when multiple reasonable interpretations of preprocessing, representation, indexing, naming, or output placement would produce different results and neither the instructions nor a validator resolve the choice.
+- UNC-2 [uncertain]: Treat the route as uncertain when success requires finding every relevant item across heterogeneous inputs or environment state, but the task does not define the search boundary or provide a completeness check.
+- LIM-1 [unsupported]: Prefer the Capable model when correctness depends primarily on extracting precise information from noisy visual, temporal, or rendered media and no machine-checkable extraction or replay mechanism is available.
+- LIM-2 [unsupported]: Prefer the Capable model when success depends on reproducing undocumented reference behavior, hidden intermediate state, or an unknown configuration, and small deviations fail despite satisfying the visible specification.
# Output
-Return exactly one JSON object with no markdown or commentary:
+Return exactly one JSON object matching the response schema supplied with the
+request. Do not include markdown or commentary.
-{{RESPONSE_SCHEMA}}
+p_solve must be between 0.00 and 1.00. p_fail is exactly 1.00 - p_solve and
+must not be emitted separately. Do not output recommended_route, confidence,
+abstain, counts, task totals, empirical rates, or any other field.
diff --git a/crates/libsy/src/prompts/capability-classifier/schema.json b/crates/libsy/src/prompts/capability-classifier/schema.json
index 6c4e2f02d..4759c38b1 100644
--- a/crates/libsy/src/prompts/capability-classifier/schema.json
+++ b/crates/libsy/src/prompts/capability-classifier/schema.json
@@ -6,15 +6,34 @@
"schema": {
"type": "object",
"additionalProperties": false,
- "required": ["recommended_route", "p_solve", "confidence", "abstain", "capability_boundary", "primary_rule", "crux"],
+ "required": [
+ "crux",
+ "primary_rule",
+ "capability_boundary",
+ "p_solve"
+ ],
"properties": {
- "recommended_route": {"type": "string", "enum": ["efficient", "capable"]},
- "p_solve": {"type": "number", "minimum": 0.0, "maximum": 1.0},
- "confidence": {"type": "number", "minimum": 0.0, "maximum": 1.0},
- "abstain": {"type": "boolean"},
- "capability_boundary": {"type": "string", "enum": ["supported", "uncertain", "unsupported", "unmatched"]},
- "primary_rule": {"type": "string", "enum": ["SUP-1", "SUP-2", "SUP-3", "UNC-1", "UNC-2", "UNC-3", "UNC-4", "LIM-1", "none"]},
- "crux": {"type": "string", "minLength": 1}
+ "crux": {"type": "string", "minLength": 1},
+ "primary_rule": {
+ "type": "string",
+ "enum": [
+ "SUP-1",
+ "SUP-2",
+ "SUP-3",
+ "SUP-4",
+ "SUP-5",
+ "UNC-1",
+ "UNC-2",
+ "LIM-1",
+ "LIM-2",
+ "none"
+ ]
+ },
+ "capability_boundary": {
+ "type": "string",
+ "enum": ["supported", "uncertain", "unsupported", "unmatched"]
+ },
+ "p_solve": {"type": "number", "minimum": 0.0, "maximum": 1.0}
}
}
}
diff --git a/crates/libsy/tests/observability.rs b/crates/libsy/tests/observability.rs
index c28b2d09d..501352f0f 100644
--- a/crates/libsy/tests/observability.rs
+++ b/crates/libsy/tests/observability.rs
@@ -360,7 +360,7 @@ impl RoutedLlmClient for ClassifierClient {
"routed response"
} else {
tokio::time::sleep(self.classifier_delay).await;
- r#"{"recommended_route":"weak","p_solve":0.9,"confidence":0.9,"abstain":false,"capability_boundary":"supported","primary_rule":"SUP-1","crux":"bounded task"}"#
+ r#"{"crux":"bounded task","primary_rule":"SUP-1","capability_boundary":"supported","p_solve":0.9}"#
};
Ok(Response {
llm_response: LlmResponse::Agg(text_response(Some(model), completion)),
@@ -1202,7 +1202,7 @@ async fn classifier_fail_open_records_each_failure_stage() -> switchyard_libsy::
(
"fo-valid",
JudgeOutcome::Reply(
- r#"{"recommended_route":"strong","p_solve":0.3,"confidence":0.9,"abstain":false,"capability_boundary":"supported","primary_rule":"CAP-1","crux":"hard task"}"#,
+ r#"{"crux":"hard task","primary_rule":"SUP-1","capability_boundary":"supported","p_solve":0.3}"#,
),
None,
),
diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rs
index 8418d582e..7f13746ad 100644
--- a/crates/switchyard-py/src/libsy_bindings.rs
+++ b/crates/switchyard-py/src/libsy_bindings.rs
@@ -122,8 +122,7 @@ impl PyTaskClassifierConfig {
#[pyo3(signature = (
base_threshold,
*,
- min_confidence=0.0,
- capability_elevated_floor=None,
+ threshold_step=0.0,
session_affinity=false,
message_hash_fallback=false,
recent_turn_window=None,
@@ -133,8 +132,7 @@ impl PyTaskClassifierConfig {
#[allow(clippy::too_many_arguments)]
fn new(
base_threshold: f64,
- min_confidence: f64,
- capability_elevated_floor: Option<f64>,
+ threshold_step: f64,
session_affinity: bool,
message_hash_fallback: bool,
recent_turn_window: Option<usize>,
@@ -148,8 +146,7 @@ impl PyTaskClassifierConfig {
Self {
inner: TaskClassifierConfig {
base_threshold,
- min_confidence,
- capability_elevated_floor,
+ threshold_step,
session_affinity,
message_hash_fallback,
recent_turn_window,
diff --git a/crates/switchyard-server/README.md b/crates/switchyard-server/README.md
index e21da15e8..edbf5a258 100644
--- a/crates/switchyard-server/README.md
+++ b/crates/switchyard-server/README.md
@@ -97,8 +97,7 @@ routes to `weak_target` or `strong_target`. Beyond the three targets it accepts
| Key | Default | Meaning |
|---|---|---|
| `base_threshold` | *required* | Lowest solve probability that routes a task to `weak_target`. Raise it to send less traffic to the weak model. |
-| `min_confidence` | `0.0` | Lowest judge confidence that permits weak routing. `0.0` disables the gate. |
-| `capability_elevated_floor` | unset | Higher solve-probability floor applied only to tasks the judge marks uncertain, unsupported, or unmatched. Unset reuses `base_threshold`. |
+| `threshold_step` | `0.0` | Finite, non-negative amount added once for uncertain or unmatched verdicts and twice for unsupported verdicts. `base_threshold + 2 * threshold_step` must be at most `1`. |
| `session_affinity` | `false` | Reuses a session's first routing decision on later turns, so the judge is called once per session rather than once per turn. |
| `message_hash_fallback` | `false` | Extends affinity to clients that send no session header, keying on the first user message. Requires `session_affinity = true`. |
diff --git a/crates/switchyard-server/src/config.rs b/crates/switchyard-server/src/config.rs
index 1a0627147..95cc57b60 100644
--- a/crates/switchyard-server/src/config.rs
+++ b/crates/switchyard-server/src/config.rs
@@ -228,8 +228,7 @@ struct CapabilityClassifierRouteConfig {
strong_target: String,
weak_target: String,
base_threshold: f64,
- min_confidence: f64,
- capability_elevated_floor: Option<f64>,
+ threshold_step: f64,
session_affinity: bool,
message_hash_fallback: bool,
recent_turn_window: Option<usize>,
@@ -303,9 +302,7 @@ enum RouteConfig {
#[serde(default)]
base_threshold: Option<f64>,
#[serde(default)]
- min_confidence: Option<f64>,
- #[serde(default)]
- capability_elevated_floor: Option<f64>,
+ threshold_step: Option<f64>,
#[serde(default)]
session_affinity: bool,
#[serde(default)]
@@ -363,9 +360,7 @@ struct StageClassifierConfig {
target: String,
base_threshold: f64,
#[serde(default)]
- min_confidence: f64,
- #[serde(default)]
- capability_elevated_floor: Option<f64>,
+ threshold_step: f64,
#[serde(default)]
session_affinity: bool,
#[serde(default)]
@@ -382,8 +377,7 @@ impl StageClassifierConfig {
fn task_classifier_config(&self) -> TaskClassifierConfig {
TaskClassifierConfig {
base_threshold: self.base_threshold,
- min_confidence: self.min_confidence,
- capability_elevated_floor: self.capability_elevated_floor,
+ threshold_step: self.threshold_step,
session_affinity: self.session_affinity,
message_hash_fallback: self.message_hash_fallback,
recent_turn_window: self.recent_turn_window,
@@ -445,8 +439,7 @@ impl RouteConfig {
strong_target,
weak_target,
base_threshold,
- min_confidence,
- capability_elevated_floor,
+ threshold_step,
session_affinity,
message_hash_fallback,
recent_turn_window,
@@ -503,8 +496,7 @@ impl RouteConfig {
"base_threshold",
base_threshold,
)?,
- min_confidence: min_confidence.unwrap_or_default(),
- capability_elevated_floor: *capability_elevated_floor,
+ threshold_step: threshold_step.unwrap_or_default(),
session_affinity: *session_affinity,
message_hash_fallback: *message_hash_fallback,
recent_turn_window: *recent_turn_window,
@@ -524,8 +516,7 @@ impl RouteConfig {
)?;
if mode.is_some()
&& (base_threshold.is_some()
- || min_confidence.is_some()
- || capability_elevated_floor.is_some()
+ || threshold_step.is_some()
|| *session_affinity
|| *message_hash_fallback
|| recent_turn_window.is_some())
@@ -556,8 +547,7 @@ impl RouteConfig {
if strong_target.is_some()
|| weak_target.is_some()
|| base_threshold.is_some()
- || min_confidence.is_some()
- || capability_elevated_floor.is_some()
+ || threshold_step.is_some()
|| escalation.is_some()
{
return Err(ServerError::new(format!(
@@ -718,8 +708,7 @@ fn build_algorithm(
let weak = resolve_target(route_name, &config.weak_target, targets)?;
let classifier_config = TaskClassifierConfig {
base_threshold: config.base_threshold,
- min_confidence: config.min_confidence,
- capability_elevated_floor: config.capability_elevated_floor,
+ threshold_step: config.threshold_step,
session_affinity: config.session_affinity,
message_hash_fallback: config.message_hash_fallback,
recent_turn_window: config.recent_turn_window,
@@ -1021,6 +1010,12 @@ target = "weak"
"base_threshold = 0.5\nprompt = \" \"",
);
assert!(error_message(&empty).contains("classifier prompt must not be empty"));
+
+ let schema_placeholder = VALID_CONFIG.replace(
+ "base_threshold = 0.5",
+ "base_threshold = 0.5\nprompt = \"{{RESPONSE_SCHEMA}}\"",
+ );
+ assert!(error_message(&schema_placeholder).contains("schema is sent separately"));
Ok(())
}
@@ -1132,6 +1127,20 @@ classifier_magic = true
VALID_CONFIG.replace("base_threshold = 0.5", "base_threshold = 1.5"),
"base_threshold must be between 0 and 1",
),
+ (
+ VALID_CONFIG.replace(
+ "base_threshold = 0.5",
+ "base_threshold = 0.5\nthreshold_step = -0.1",
+ ),
+ "threshold_step must be finite and greater than or equal to 0",
+ ),
+ (
+ VALID_CONFIG.replace(
+ "base_threshold = 0.5",
+ "base_threshold = 0.8\nthreshold_step = 0.11",
+ ),
+ "base_threshold + 2 * threshold_step must be at most 1",
+ ),
(
VALID_CONFIG.replace(
"base_threshold = 0.5",
@@ -1262,7 +1271,7 @@ target = "azure"
fn accepts_session_affinity_with_message_hash_fallback() -> ServerResult<()> {
let configured = VALID_CONFIG.replace(
"base_threshold = 0.5",
- "base_threshold = 0.25\nmin_confidence = 0.0\ncapability_elevated_floor = 0.45\nsession_affinity = true\nmessage_hash_fallback = true",
+ "base_threshold = 0.25\nthreshold_step = 0.1\nsession_affinity = true\nmessage_hash_fallback = true",
);
server_state_from_toml(&configured)?;
Ok(())
diff --git a/crates/switchyard-server/tests/server.rs b/crates/switchyard-server/tests/server.rs
index 3860cdc85..bd5b90947 100644
--- a/crates/switchyard-server/tests/server.rs
+++ b/crates/switchyard-server/tests/server.rs
@@ -137,7 +137,7 @@ async fn upstream_chat(
{
r#"{"escalate":false,"reason":"making progress"}"#
} else if model == "model/classifier" {
- r#"{"recommended_route":"efficient","p_solve":0.9,"confidence":0.9,"abstain":false,"capability_boundary":"supported","primary_rule":"SUP-1","crux":"bounded task"}"#
+ r#"{"crux":"bounded task","primary_rule":"SUP-1","capability_boundary":"supported","p_solve":0.9}"#
} else {
"ok"
};
@@ -787,7 +787,7 @@ mode = "custom"
classifier_target = "classifier"
targets = ["weak", "middle", "strong", "premium"]
default_target = "strong"
-prompt = "CUSTOM MULTI TARGET\n{{{{RESPONSE_SCHEMA}}}}"
+prompt = "CUSTOM MULTI TARGET"
response_schema = '''
{{
"type": "object",
@@ -846,8 +846,7 @@ selector = "/decision/target"
let prompt = judge_call["messages"][0]["content"]
.as_str()
.ok_or("custom classifier prompt was not text")?;
- assert!(prompt.starts_with("CUSTOM MULTI TARGET"));
- assert!(!prompt.contains("{{RESPONSE_SCHEMA}}"));
+ assert_eq!(prompt, "CUSTOM MULTI TARGET");
assert_eq!(judge_call["response_format"]["type"], "json_schema");
assert_eq!(
judge_call["response_format"]["json_schema"]["name"],
@@ -893,7 +892,7 @@ classifier_target = "classifier"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5
-prompt = "CUSTOM CAPABILITY\n{{RESPONSE_SCHEMA}}"
+prompt = "CUSTOM CAPABILITY"
[routes.escalation]
id = "switchyard/escalation"
@@ -902,7 +901,7 @@ mode = "escalation"
classifier_target = "classifier"
strong_target = "strong"
weak_target = "weak"
-prompt = "CUSTOM ESCALATION\n{{RESPONSE_SCHEMA}}"
+prompt = "CUSTOM ESCALATION"
escalation = {{ confirmations = 1 }}
[routes.stage]
@@ -916,7 +915,7 @@ confidence_threshold = 1.0
[routes.stage.classifier]
target = "classifier"
base_threshold = 0.5
-prompt = "CUSTOM STAGE\n{{RESPONSE_SCHEMA}}"
+prompt = "CUSTOM STAGE"
"#,
base_url = upstream.base_url
))?;
@@ -949,7 +948,6 @@ prompt = "CUSTOM STAGE\n{{RESPONSE_SCHEMA}}"
.as_str()
.ok_or("classifier prompt was not text")?;
assert!(prompt.starts_with(prompt_prefix), "{route}: {prompt}");
- assert!(!prompt.contains("{{RESPONSE_SCHEMA}}"), "{route}: {prompt}");
assert!(
judge_call["response_format"]["json_schema"]["schema"]["properties"]
.get(schema_field)
diff --git a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
index 37aa7eb3e..7a8e79c9e 100644
--- a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
@@ -233,6 +233,21 @@ impl FormatCodec for AnthropicMessagesCodec {
body.insert("thinking".to_string(), json!({"type": "adaptive"}));
body.insert("output_config".to_string(), json!({"effort": effort}));
}
+ if let Some(response_format) = &request.output.response_format
+ && let Some(format) =
+ encode_anthropic_output_format(response_format, &mut diagnostics, policy)?
+ {
+ let output_config = body
+ .entry("output_config".to_string())
+ .or_insert_with(|| Value::Object(Map::new()));
+ let Some(output_config) = output_config.as_object_mut() else {
+ return Err(TranslationError::InvalidType {
+ path: "$.output_config".to_string(),
+ expected: "object",
+ });
+ };
+ output_config.insert("format".to_string(), format);
+ }
let body = embed_preservation(Value::Object(body), &request.preservation, policy);
Ok(EncodedRequest { body, diagnostics })
@@ -345,6 +360,69 @@ impl FormatCodec for AnthropicMessagesCodec {
}
}
+/// Maps the neutral OpenAI-shaped JSON schema to Anthropic's output format.
+fn encode_anthropic_output_format(
+ response_format: &Value,
+ diagnostics: &mut Vec<TranslationDiagnostic>,
+ policy: &TranslationPolicy,
+) -> Result<Option<Value>> {
+ let Some(json_schema) = response_format
+ .as_object()
+ .filter(|format| format.get("type").and_then(Value::as_str) == Some("json_schema"))
+ .and_then(|format| format.get("json_schema"))
+ .and_then(Value::as_object)
+ else {
+ push_lossy(
+ diagnostics,
+ policy,
+ "Anthropic structured output requires an OpenAI JSON schema response format",
+ )?;
+ return Ok(None);
+ };
+ let Some(schema) = json_schema.get("schema") else {
+ push_lossy(
+ diagnostics,
+ policy,
+ "Anthropic structured output requires json_schema.schema",
+ )?;
+ return Ok(None);
+ };
+
+ let mut schema = schema.clone();
+ if strip_anthropic_unsupported_constraints(&mut schema) {
+ push_lossy(
+ diagnostics,
+ policy,
+ "Anthropic structured output dropped unsupported JSON Schema constraints",
+ )?;
+ }
+ Ok(Some(json!({"type": "json_schema", "schema": schema})))
+}
+
+/// Removes constraints unsupported by Anthropic's structured-output grammar.
+fn strip_anthropic_unsupported_constraints(value: &mut Value) -> bool {
+ match value {
+ Value::Object(object) => {
+ let mut removed = false;
+ for key in ["minimum", "maximum", "minLength", "maxLength"] {
+ removed |= object.remove(key).is_some();
+ }
+ for value in object.values_mut() {
+ removed |= strip_anthropic_unsupported_constraints(value);
+ }
+ removed
+ }
+ Value::Array(values) => {
+ let mut removed = false;
+ for value in values {
+ removed |= strip_anthropic_unsupported_constraints(value);
+ }
+ removed
+ }
+ _ => false,
+ }
+}
+
// Decodes Anthropic's `system` field into instruction blocks.
fn decode_anthropic_system(value: &Value) -> Result<Option<Vec<ContentBlock>>> {
match value {
diff --git a/crates/switchyard-translation/tests/request_translation.rs b/crates/switchyard-translation/tests/request_translation.rs
index 164dc5fc0..bfcf78625 100644
--- a/crates/switchyard-translation/tests/request_translation.rs
+++ b/crates/switchyard-translation/tests/request_translation.rs
@@ -951,7 +951,20 @@ fn openai_request_translates_system_developer_and_reasoning_to_anthropic() -> Te
}
],
"max_completion_tokens": 512,
- "reasoning_effort": "high"
+ "reasoning_effort": "high",
+ "response_format": {
+ "type": "json_schema",
+ "json_schema": {
+ "name": "answer",
+ "strict": true,
+ "schema": {
+ "type": "object",
+ "properties": {"answer": {"type": "string"}},
+ "required": ["answer"],
+ "additionalProperties": false
+ }
+ }
+ }
});
let output = engine
@@ -967,7 +980,21 @@ fn openai_request_translates_system_developer_and_reasoning_to_anthropic() -> Te
assert_eq!(output["system"], "System rules.\n\nDeveloper rules.");
assert_eq!(output["max_tokens"], 512);
assert_eq!(output["thinking"], json!({"type": "adaptive"}));
- assert_eq!(output["output_config"], json!({"effort": "high"}));
+ assert_eq!(
+ output["output_config"],
+ json!({
+ "effort": "high",
+ "format": {
+ "type": "json_schema",
+ "schema": {
+ "type": "object",
+ "properties": {"answer": {"type": "string"}},
+ "required": ["answer"],
+ "additionalProperties": false
+ }
+ }
+ })
+ );
assert_eq!(output["messages"][0]["role"], "user");
assert_eq!(
output["messages"][0]["content"][0],
@@ -976,6 +1003,63 @@ fn openai_request_translates_system_developer_and_reasoning_to_anthropic() -> Te
Ok(())
}
+// Verifies Anthropic receives its supported schema subset without mutating the neutral contract.
+#[test]
+fn openai_schema_constraints_are_removed_from_anthropic_output_format() -> TestResult {
+ let engine = TranslationEngine::default();
+ let body = json!({
+ "model": "claude-opus-4-8",
+ "messages": [{"role": "user", "content": "Return a probability."}],
+ "response_format": {
+ "type": "json_schema",
+ "json_schema": {
+ "name": "probability",
+ "strict": true,
+ "schema": {
+ "type": "object",
+ "properties": {
+ "crux": {"type": "string", "minLength": 1, "maxLength": 80},
+ "p_solve": {"type": "number", "minimum": 0, "maximum": 1}
+ },
+ "required": ["crux", "p_solve"],
+ "additionalProperties": false
+ }
+ }
+ }
+ });
+
+ let translated = engine.translate_request(
+ WireFormat::OpenAiChat,
+ WireFormat::AnthropicMessages,
+ &body,
+ &TranslationPolicy::default(),
+ )?;
+
+ assert_eq!(
+ translated.body["output_config"]["format"]["schema"],
+ json!({
+ "type": "object",
+ "properties": {
+ "crux": {"type": "string"},
+ "p_solve": {"type": "number"}
+ },
+ "required": ["crux", "p_solve"],
+ "additionalProperties": false
+ })
+ );
+ assert_eq!(translated.diagnostics.len(), 1);
+ assert!(
+ translated.diagnostics[0]
+ .message
+ .contains("unsupported JSON Schema constraints")
+ );
+ assert_eq!(
+ body["response_format"]["json_schema"]["schema"]["properties"]["p_solve"]["minimum"],
+ 0
+ );
+ Ok(())
+}
+
// Verifies Anthropic-bound OpenAI requests get the required max_tokens fallback.
#[test]
fn openai_request_to_anthropic_adds_required_default_max_tokens() -> TestResult {
diff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.md
index 45092727e..6b54932cb 100644
--- a/docs/reference/toml_schema.md
+++ b/docs/reference/toml_schema.md
@@ -108,12 +108,11 @@ Capability mode classifies before serving. See
| `strong_target` | Yes | — | Capable tier. |
| `weak_target` | Yes | — | Efficient tier. |
| `base_threshold` | Yes | — | Lowest solve probability that routes to the weak target. In `[0, 1]`. |
-| `min_confidence` | No | `0.0` | Lowest judge confidence that permits weak routing. |
-| `capability_elevated_floor` | No | unset | Higher floor for uncertain tasks. Must exceed `base_threshold`. |
+| `threshold_step` | No | `0.0` | Finite, non-negative amount added once for uncertain or unmatched verdicts and twice for unsupported verdicts. `base_threshold + 2 * threshold_step` must be at most `1`. |
| `session_affinity` | No | `false` | Reuses a session's first decision on later turns. |
| `message_hash_fallback` | No | `false` | Keys affinity on the first user message. Requires `session_affinity`. |
-| `recent_turn_window` | No | unset | Trailing turns the judge sees. |
-| `prompt` | No | packaged prompt | Replaces the capability prompt. `{{RESPONSE_SCHEMA}}` expands to its packaged schema. |
+| `recent_turn_window` | No | unset | When unset, the judge sees the opening task and latest user follow-up, when present. When set, it also sees trailing turns. |
+| `prompt` | No | packaged prompt | Replaces the capability prompt. The packaged schema is sent separately as structured-output configuration. |
Escalation mode serves the weak target first and judges the completed turn. See
[Escalation-Router Routing](../routing_algorithms/escalation_router_routing.md).
@@ -136,12 +135,15 @@ policy selector, and routes to any configured target label.
|---|:---:|---|---|
| `targets` | Yes | — | Two or more target names available to the policy. |
| `default_target` | Yes | — | Target used when the judge fails or its verdict cannot be routed. |
-| `prompt` | Yes | — | Judge system prompt. `{{RESPONSE_SCHEMA}}` expands to the configured inner schema. |
+| `prompt` | Yes | — | Judge system prompt. The configured inner schema is sent separately as structured-output configuration. |
| `response_schema` | Yes | — | Inner JSON Schema encoded as a TOML string. Switchyard adds the provider wrapper. |
| `policy` | Yes | — | Policy table. `target_selector` accepts a JSON Pointer such as `/decision/target`. |
| `session_affinity` | No | `false` | Reuses a session's first decision on later turns. |
| `message_hash_fallback` | No | `false` | Keys affinity on the first user message. Requires `session_affinity`. |
-| `recent_turn_window` | No | unset | Trailing turns the judge sees. |
+| `recent_turn_window` | No | unset | When unset, the judge sees the opening task and latest user follow-up, when present. When set, it also sees trailing turns. |
+
+Classifier prompts must not contain `{{RESPONSE_SCHEMA}}`. Switchyard sends the
+schema only through the provider's structured-output request.
### `stage_router`
diff --git a/docs/routing_algorithms/escalation_router_routing.md b/docs/routing_algorithms/escalation_router_routing.md
index ff94db027..5cffce27b 100644
--- a/docs/routing_algorithms/escalation_router_routing.md
+++ b/docs/routing_algorithms/escalation_router_routing.md
@@ -48,7 +48,8 @@ clients send; the judge is not exposed as a client-selectable model.
The route-level `prompt` key replaces the packaged trajectory-judge prompt. It
uses the escalation verdict schema rather than the capability verdict schema.
-Include `{{RESPONSE_SCHEMA}}` when the schema should also appear in the prompt.
+Switchyard sends that schema separately through the provider's structured-output
+request rather than copying it into the prompt.
## How the decision works
diff --git a/docs/routing_algorithms/llm_classifier_routing.md b/docs/routing_algorithms/llm_classifier_routing.md
index ff9c8e863..1f87ab936 100644
--- a/docs/routing_algorithms/llm_classifier_routing.md
+++ b/docs/routing_algorithms/llm_classifier_routing.md
@@ -37,6 +37,7 @@ classifier_target = "classifier"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5
+threshold_step = 0.1
session_affinity = true
message_hash_fallback = true
```
@@ -54,20 +55,20 @@ model name clients send to Switchyard.
The classifier target returns a structured verdict containing:
- `p_solve`: the estimated probability that the weak model completes the task.
-- `confidence`: confidence in the assessment.
- `capability_boundary`: `supported`, `uncertain`, `unsupported`, or `unmatched`.
+- `primary_rule`: the capability-card rule that determines the boundary.
+- `crux`: the hardest material requirement for whole-task success.
For a usable verdict, Switchyard routes to `weak_target` when `p_solve` is
greater than or equal to the applicable threshold. Otherwise it routes to
`strong_target`:
- `supported` uses `base_threshold`.
-- `uncertain`, `unsupported`, and `unmatched` use
- `capability_elevated_floor` when configured, or `base_threshold` otherwise.
+- `uncertain` and `unmatched` use `base_threshold + threshold_step`.
+- `unsupported` uses `base_threshold + 2 * threshold_step`.
-An abstention, an invalid or unparseable verdict, a judge failure, or confidence
-below `min_confidence` routes to `strong_target`. Raising either threshold sends
-more traffic to the strong model.
+An invalid, inconsistent, or unparseable verdict, or a judge failure, routes to
+`strong_target`. Raising either knob sends more traffic to the strong model.
## Judge model compatibility
@@ -98,9 +99,8 @@ for the server merge behavior.
| Key | Default | Meaning |
|---|---|---|
| `base_threshold` | required | Lowest `p_solve` that routes a supported task to `weak_target`. Must be between `0` and `1`. |
-| `min_confidence` | `0.0` | Lowest judge confidence that permits weak routing. Must be between `0` and `1`. |
-| `capability_elevated_floor` | unset | Higher threshold for uncertain, unsupported, and unmatched tasks. It must be between `0` and `1` and greater than `base_threshold`. |
-| `recent_turn_window` | unset | When unset, the judge sees only the newest user message. When set to `N`, it sees client system/developer instructions, the opening user task, and the last `N` conversation messages after that task. `0` keeps only the instructions and opening task. |
+| `threshold_step` | `0.0` | Amount added for each boundary step. Must be finite and non-negative, and `base_threshold + 2 * threshold_step` must not exceed `1`. |
+| `recent_turn_window` | unset | When unset, the judge sees the opening user task and the latest user message when they differ. When set to `N`, it sees client system/developer instructions, the opening user task, and the last `N` conversation messages after that task. `0` keeps only the instructions and opening task. |
| `session_affinity` | `false` | Retains the first selected target for a session and reuses it on later requests. |
| `message_hash_fallback` | `false` | When session metadata is absent, keys affinity from the first user-message text. Requires `session_affinity = true`. |
| `prompt` | packaged capability prompt | Replaces the classifier's system prompt. The packaged verdict schema and routing policy remain active. |
@@ -109,8 +109,8 @@ for the server merge behavior.
### Override the classifier prompt
Set `prompt` on the route when the packaged capability rubric does not describe
-your weak model. A `{{RESPONSE_SCHEMA}}` placeholder is optional. When present,
-Switchyard replaces it with the packaged capability-verdict schema.
+your weak model. Switchyard sends the response schema separately through the
+provider's structured-output request; do not copy it into the prompt.
```toml
[routes.smart]
@@ -123,13 +123,12 @@ weak_target = "weak"
base_threshold = 0.5
prompt = """
Estimate whether the weak target can complete the request.
-Return JSON matching this schema:
-{{RESPONSE_SCHEMA}}
+Return exactly one JSON object matching the response schema supplied with the request.
"""
```
The override changes the instructions only. The judge must still return the
-packaged fields such as `p_solve`, `confidence`, and `capability_boundary`.
+packaged `crux`, `primary_rule`, `capability_boundary`, and `p_solve` fields.
## Custom multi-target routing
@@ -146,8 +145,7 @@ targets = ["fast", "balanced", "reasoning", "premium"]
default_target = "premium"
prompt = """
Choose the best configured target for this request.
-Return JSON matching:
-{{RESPONSE_SCHEMA}}
+Return JSON matching the response schema supplied with the request.
"""
response_schema = '''
{
@@ -180,18 +178,22 @@ schema to the provider in a strict structured-output wrapper and validates the
returned JSON again. `jsonptr` resolves the selector against that verdict. A
missing, non-string, or unknown target falls back to `default_target`.
-### Classifier calibration
+This separation applies to every classifier mode. Prompts containing the legacy
+`{{RESPONSE_SCHEMA}}` placeholder are rejected during configuration validation.
-The packaged prompt is calibrated for one specific weak model, assumes it
-receives the initial task, and describes a sticky routing decision. It is not a
-model-neutral weak-target evaluator.
+### Forecast and policy assumptions
-Without affinity, the runtime judges every request; by default, it sends the
-newest user message rather than the initial task. The example enables affinity
-and its message-hash fallback so the first request is judged and later requests
-with the same opening task reuse that decision. If you use a different weak
-model or per-request routing, tune the thresholds before treating classifier
-decisions as production policy.
+The packaged prompt forecasts whole-task success for a generic efficient agent.
+It produces a probability and capability boundary but does not choose a route.
+The deterministic policy applies `base_threshold` and `threshold_step` after
+generation.
+
+Without affinity, the runtime judges every request. By default, it sends the
+opening task and the latest user follow-up when they differ. Set
+`recent_turn_window` when intervening conversation context affects the forecast.
+If a client sends only a follow-up fragment without the opening task, enable
+affinity or include the task history. Threshold tuning changes routing policy;
+it cannot recover missing task context.
## Session affinity
diff --git a/docs/routing_algorithms/stage_router_routing.md b/docs/routing_algorithms/stage_router_routing.md
index b9cfa05b2..1051928a1 100644
--- a/docs/routing_algorithms/stage_router_routing.md
+++ b/docs/routing_algorithms/stage_router_routing.md
@@ -254,14 +254,14 @@ that fall below the threshold:
[routes.stage.classifier]
target = "strong" # target the judge is called through (not a routing destination)
base_threshold = 0.5 # p_solve floor to route efficient; below this → capable
-min_confidence = 0.7 # judge confidence floor; below this → abstain
+threshold_step = 0.1 # adds 0.1 for uncertain and 0.2 for unsupported verdicts
recent_turn_window = 3 # conversation span the judge sees
prompt = "Estimate whether the efficient target can complete this request."
```
-`prompt` replaces the packaged capability-classifier prompt. Add
-`{{RESPONSE_SCHEMA}}` where the active capability schema should appear in the
-prompt. The verdict schema and routing thresholds remain unchanged.
+`prompt` replaces the packaged capability-classifier prompt. The active schema
+is sent separately through the structured-output request. The verdict schema
+and routing thresholds remain unchanged.
Give the classifier its own LLM client or quota bucket where possible. Sharing
one provider bucket with the efficient tier adds a request per classified turn
diff --git a/switchyard/cli/defaults/openrouter.toml b/switchyard/cli/defaults/openrouter.toml
index 94405c249..927777d4a 100644
--- a/switchyard/cli/defaults/openrouter.toml
+++ b/switchyard/cli/defaults/openrouter.toml
@@ -27,6 +27,6 @@ classifier_target = "classifier"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5
-min_confidence = 0.0
+threshold_step = 0.0
session_affinity = true
message_hash_fallback = true
diff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.py
index 20e54eccd..dd01ed5d4 100644
--- a/switchyard_rust/libsy.py
+++ b/switchyard_rust/libsy.py
@@ -57,11 +57,12 @@ if TYPE_CHECKING:
self,
base_threshold: float,
*,
- min_confidence: float = 0.0,
- capability_elevated_floor: float | None = None,
+ threshold_step: float = 0.0,
session_affinity: bool = False,
message_hash_fallback: bool = False,
recent_turn_window: int | None = None,
+ max_output_tokens: int = 4096,
+ prompt: str | None = None,
) -> None: ...
@final
diff --git a/tests/test_libsy_minimal_bindings.py b/tests/test_libsy_minimal_bindings.py
index 2d4704851..b8f0a25c7 100644
--- a/tests/test_libsy_minimal_bindings.py
+++ b/tests/test_libsy_minimal_bindings.py
@@ -75,10 +75,8 @@ async def test_classifier_config_accepts_a_prompt_override() -> None:
{
"type": "text",
"text": (
- '{"recommended_route":"efficient","p_solve":0.9,'
- '"confidence":0.9,"abstain":false,'
- '"capability_boundary":"supported",'
- '"primary_rule":"SUP-1","crux":"bounded task"}'
+ '{"crux":"bounded task","primary_rule":"SUP-1",'
+ '"capability_boundary":"supported","p_solve":0.9}'
),
}
],
@@ -95,16 +93,18 @@ async def test_classifier_config_accepts_a_prompt_override() -> None:
LlmTarget("strong", EchoClient("strong")),
config=TaskClassifierConfig(
0.5,
- prompt="Custom capability rubric:\n{{RESPONSE_SCHEMA}}",
+ threshold_step=0.1,
+ prompt="Custom capability rubric.",
),
)
_, response = await algorithm.run(request_body())
prompt = judge.calls[0]["messages"][0]["content"][0]["text"]
- assert prompt.startswith("Custom capability rubric:")
- assert '"recommended_route"' in prompt
- assert "{{RESPONSE_SCHEMA}}" not in prompt
+ assert prompt == "Custom capability rubric."
+ assert judge.calls[0]["output"]["response_format"]["json_schema"]["schema"][
+ "properties"
+ ]["p_solve"]
assert response["model"] == "weak"