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(llm-classifier): make system prompt configurable for user (#265)

Ayush Agarwal14f75eb19132
diff --git a/crates/libsy/src/algorithms/llm_class.rs b/crates/libsy/src/algorithms/llm_class.rs
index fe87e0a91..b298f1b4c 100644
--- a/crates/libsy/src/algorithms/llm_class.rs
+++ b/crates/libsy/src/algorithms/llm_class.rs
@@ -10,14 +10,15 @@
use std::sync::Arc;
use async_trait::async_trait;
-use serde::Deserialize;
+use serde::{Deserialize, Deserializer};
use switchyard_protocol::{LlmRequest, Message, OutputParams, Role, SimpleDecision};
use super::fall_through::{DefaultTarget, FallThrough};
use super::util::DEFAULT_JUDGE_MAX_OUTPUT_TOKENS;
use super::util::affinity::AffinityRouter;
+use super::util::classifier_contract::{ClassifierContract, ClassifierContractConfig};
use super::util::escalation::{self, EscalationJudge, EscalationJudgeConfig, EscalationPolicy};
-use super::util::llm_judge::{self, Judge, JudgeClassifier, JudgeConfig, JudgePolicy};
+use super::util::llm_judge::{Judge, JudgeClassifier, JudgePolicy};
use crate::core::algorithm::{Algorithm, Driver, LlmTarget, LlmTargetSet};
use crate::core::classifier::{Classification, Classifier, Score};
use crate::core::state::{State, StateValue};
@@ -90,7 +91,8 @@ fn trim_messages(messages: &[Message], recent_turn_window: usize) -> Vec<Message
}
struct CapabilityJudge {
- config: JudgeConfig,
+ contract: ClassifierContract,
+ max_output_tokens: u64,
recent_turn_window: Option<usize>,
}
@@ -114,15 +116,15 @@ impl Judge for CapabilityJudge {
};
messages.insert(
0,
- Message::text(Role::System, self.config.system_prompt.clone()),
+ Message::text(Role::System, self.contract.system_prompt().to_string()),
);
Request {
llm_request: LlmRequest {
model: request.llm_request.model.clone(),
messages,
output: OutputParams {
- max_output_tokens: Some(self.config.max_output_tokens),
- response_format: self.config.response_schema.clone(),
+ max_output_tokens: Some(self.max_output_tokens),
+ response_format: Some(self.contract.response_format().clone()),
},
..LlmRequest::default()
},
@@ -135,30 +137,33 @@ impl Judge for CapabilityJudge {
struct TaskClassifierPolicy {
efficient_target: String,
capable_target: String,
- config: TaskClassifierConfig,
+ base_threshold: f64,
+ min_confidence: f64,
+ capability_elevated_floor: Option<f64>,
}
impl TaskClassifierPolicy {
fn new(
efficient_target: impl Into<String>,
capable_target: impl Into<String>,
- config: TaskClassifierConfig,
+ config: &TaskClassifierConfig,
) -> Self {
Self {
efficient_target: efficient_target.into(),
capable_target: capable_target.into(),
- config,
+ base_threshold: config.base_threshold,
+ min_confidence: config.min_confidence,
+ capability_elevated_floor: config.capability_elevated_floor,
}
}
/// Returns the required solve probability for one validated verdict.
fn threshold(&self, verdict: &TaskClassifierVerdict) -> f64 {
if verdict.is_capability_elevated() {
- self.config
- .capability_elevated_floor
- .unwrap_or(self.config.base_threshold)
+ self.capability_elevated_floor
+ .unwrap_or(self.base_threshold)
} else {
- self.config.base_threshold
+ self.base_threshold
}
}
}
@@ -171,8 +176,8 @@ impl JudgePolicy for TaskClassifierPolicy {
// 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.config.min_confidence)
+ let Some(verdict) =
+ verdict.filter(|v| v.is_valid() && !v.abstain && v.confidence >= self.min_confidence)
else {
return Classification::Ambiguous(vec![]);
};
@@ -190,22 +195,18 @@ impl JudgePolicy for TaskClassifierPolicy {
}
}
-#[derive(Clone, Debug, Deserialize)]
-/// Thresholds that control capability classifier routing.
+#[derive(Clone, Debug)]
+/// Settings that control capability classifier prompting and routing.
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.
- #[serde(default)]
pub min_confidence: f64,
/// Higher solve-probability floor for uncertain, unmatched, and unsupported tasks.
- #[serde(default)]
pub capability_elevated_floor: Option<f64>,
/// Enables session affinity before the judge-backed classifier.
- #[serde(default)]
pub session_affinity: bool,
/// Uses the first user message as the SessionKey for sticky routing when session metadata is unavailable.
- #[serde(default)]
pub message_hash_fallback: bool,
/// Trailing conversation turns the judge sees on top of the client
/// instructions and the opening task.
@@ -213,13 +214,57 @@ pub struct TaskClassifierConfig {
/// `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.
- #[serde(default)]
pub recent_turn_window: Option<usize>,
+ /// Prompt and verdict contract settings for the classifier judge.
+ pub contract: ClassifierContractConfig,
/// Maximum completion tokens available to the classifier verdict.
- #[serde(default = "default_judge_max_output_tokens")]
pub max_output_tokens: u64,
}
+/// Flat serialized shape that maps prompt settings into the runtime contract.
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct TaskClassifierConfigWire {
+ base_threshold: f64,
+ #[serde(default)]
+ min_confidence: f64,
+ #[serde(default)]
+ capability_elevated_floor: Option<f64>,
+ #[serde(default)]
+ session_affinity: bool,
+ #[serde(default)]
+ message_hash_fallback: bool,
+ #[serde(default)]
+ recent_turn_window: Option<usize>,
+ #[serde(default)]
+ prompt: Option<String>,
+ #[serde(default = "default_judge_max_output_tokens")]
+ max_output_tokens: u64,
+}
+
+impl<'de> Deserialize<'de> for TaskClassifierConfig {
+ fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+ where
+ D: Deserializer<'de>,
+ {
+ let wire = TaskClassifierConfigWire::deserialize(deserializer)?;
+ let mut contract = ClassifierContractConfig::default();
+ if let Some(prompt) = wire.prompt {
+ contract = contract.with_prompt(prompt);
+ }
+ Ok(Self {
+ base_threshold: wire.base_threshold,
+ min_confidence: wire.min_confidence,
+ capability_elevated_floor: wire.capability_elevated_floor,
+ session_affinity: wire.session_affinity,
+ message_hash_fallback: wire.message_hash_fallback,
+ recent_turn_window: wire.recent_turn_window,
+ contract,
+ max_output_tokens: wire.max_output_tokens,
+ })
+ }
+}
+
const fn default_judge_max_output_tokens() -> u64 {
DEFAULT_JUDGE_MAX_OUTPUT_TOKENS
}
@@ -233,6 +278,7 @@ impl Default for TaskClassifierConfig {
session_affinity: false,
message_hash_fallback: false,
recent_turn_window: None,
+ contract: ClassifierContractConfig::default(),
max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
}
}
@@ -461,22 +507,22 @@ impl LlmTaskClassifier {
config: TaskClassifierConfig,
) -> Result<Self> {
config.validate()?;
- let mut judge_config = Self::load_judge_config()?;
- judge_config.max_output_tokens = config.max_output_tokens;
+ let contract = Self::load_capability_contract(&config.contract)?;
let targets = LlmTargetSet::new(vec![efficient_target.clone(), capable_target.clone()]);
let session_affinity = config.session_affinity;
let message_hash_fallback = config.message_hash_fallback;
let classifier = Arc::new(TaskClassifier {
classifier: JudgeClassifier::new(
CapabilityJudge {
- config: judge_config,
+ contract,
+ max_output_tokens: config.max_output_tokens,
recent_turn_window: config.recent_turn_window,
},
judge_target.clone(),
TaskClassifierPolicy::new(
efficient_target.semantic_name.clone(),
capable_target.semantic_name.clone(),
- config,
+ &config,
),
),
efficient_target: efficient_target.semantic_name.clone(),
@@ -524,6 +570,25 @@ impl LlmTaskClassifier {
capable_target: LlmTarget,
config: EscalationJudgeConfig,
max_output_tokens: u64,
+ ) -> Result<Self> {
+ Self::new_with_escalation_contract(
+ judge_target,
+ efficient_target,
+ capable_target,
+ ClassifierContractConfig::default(),
+ config,
+ max_output_tokens,
+ )
+ }
+
+ /// Constructs an escalation variant with a configurable classifier contract.
+ pub fn new_with_escalation_contract(
+ judge_target: LlmTarget,
+ efficient_target: LlmTarget,
+ capable_target: LlmTarget,
+ contract_config: ClassifierContractConfig,
+ config: EscalationJudgeConfig,
+ max_output_tokens: u64,
) -> Result<Self> {
let capable_name = capable_target.semantic_name.clone();
let efficient_name = efficient_target.semantic_name.clone();
@@ -533,6 +598,7 @@ impl LlmTaskClassifier {
judge_target,
capable_name,
efficient_name,
+ &contract_config,
config,
max_output_tokens,
)?,
@@ -550,9 +616,9 @@ impl LlmTaskClassifier {
})
}
- /// Loads the judge configuration from the packaged prompt and schema.
- fn load_judge_config() -> Result<JudgeConfig> {
- llm_judge::load_judge_config(PROMPT_TEMPLATE, SCHEMA_TEMPLATE)
+ /// Loads the packaged capability-classifier contract.
+ fn load_capability_contract(config: &ClassifierContractConfig) -> Result<ClassifierContract> {
+ ClassifierContract::from_config(config, PROMPT_TEMPLATE, SCHEMA_TEMPLATE)
}
}
@@ -641,7 +707,7 @@ mod tests {
}
fn policy() -> TaskClassifierPolicy {
- TaskClassifierPolicy::new("efficient", "capable", test_config(TEST_THRESHOLD))
+ TaskClassifierPolicy::new("efficient", "capable", &test_config(TEST_THRESHOLD))
}
/// A verdict whose non-routing fields are fixed — only the three the policy reads vary.
@@ -674,6 +740,7 @@ mod tests {
struct PerRequestClient {
calls: Mutex<Vec<String>>,
judge_max_output_tokens: Mutex<Vec<Option<u64>>>,
+ judge_system_prompts: Mutex<Vec<String>>,
}
impl PerRequestClient {
@@ -684,6 +751,10 @@ mod tests {
fn judge_max_output_tokens(&self) -> Vec<Option<u64>> {
self.judge_max_output_tokens.lock().clone()
}
+
+ fn judge_system_prompts(&self) -> Vec<String> {
+ self.judge_system_prompts.lock().clone()
+ }
}
#[async_trait]
@@ -700,6 +771,13 @@ mod tests {
self.judge_max_output_tokens
.lock()
.push(request.llm_request.output.max_output_tokens);
+ self.judge_system_prompts.lock().extend(
+ request
+ .llm_request
+ .messages
+ .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()
} else {
format!("answer from {model}")
@@ -831,6 +909,34 @@ mod tests {
Ok(())
}
+ #[tokio::test]
+ async fn classifier_config_overrides_the_packaged_prompt() -> Result<()> {
+ let client = Arc::new(PerRequestClient::default());
+ let target = |name: &str| LlmTarget {
+ semantic_name: name.to_string(),
+ llm_client: Some(client.clone()),
+ };
+ let router = Arc::new(LlmTaskClassifier::new(
+ target("judge"),
+ target("efficient"),
+ target("capable"),
+ TaskClassifierConfig {
+ contract: ClassifierContractConfig::default()
+ .with_prompt("Custom capability rubric:\n{{RESPONSE_SCHEMA}}"),
+ ..test_config(TEST_THRESHOLD)
+ },
+ )?);
+
+ router.run(Context::default(), classify_request()).await?;
+
+ 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}}"));
+ Ok(())
+ }
+
#[tokio::test]
async fn classifier_config_enables_session_affinity() -> Result<()> {
let client = Arc::new(PerRequestClient::default());
@@ -906,13 +1012,29 @@ mod tests {
#[test]
fn the_threshold_moves_the_routing_boundary() -> Result<()> {
let borderline = verdict(0.5, 1.0, false);
- let strict = TaskClassifierPolicy::new("efficient", "capable", test_config(0.9));
- let lenient = TaskClassifierPolicy::new("efficient", "capable", test_config(0.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");
assert_eq!(selected(&lenient, Some(&borderline))?, "efficient");
Ok(())
}
+ #[test]
+ fn classifier_config_rejects_unknown_fields() {
+ let error = serde_json::from_value::<TaskClassifierConfig>(serde_json::json!({
+ "base_threshold": 0.5,
+ "classifier_magic": true,
+ }))
+ .expect_err("unknown classifier fields must be rejected");
+
+ assert!(
+ error
+ .to_string()
+ .contains("unknown field `classifier_magic`"),
+ "{error}"
+ );
+ }
+
#[test]
fn invalid_classifier_config_is_rejected() -> Result<()> {
let target = |name: &str| LlmTarget {
@@ -992,7 +1114,7 @@ mod tests {
let policy = TaskClassifierPolicy::new(
"efficient",
"capable",
- TaskClassifierConfig {
+ &TaskClassifierConfig {
capability_elevated_floor: Some(0.45),
..test_config(0.25)
},
@@ -1017,7 +1139,10 @@ mod tests {
/// The no-window case is covered by `capability_judge_builds_a_structured_request`.
fn judged_contents(recent_turn_window: usize) -> Result<Vec<String>> {
let judge = CapabilityJudge {
- config: LlmTaskClassifier::load_judge_config()?,
+ contract: LlmTaskClassifier::load_capability_contract(
+ &ClassifierContractConfig::default(),
+ )?,
+ max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
recent_turn_window: Some(recent_turn_window),
};
let request = Request {
@@ -1068,7 +1193,10 @@ mod tests {
#[test]
fn capability_judge_builds_a_structured_request() -> Result<()> {
let judge = CapabilityJudge {
- config: LlmTaskClassifier::load_judge_config()?,
+ contract: LlmTaskClassifier::load_capability_contract(
+ &ClassifierContractConfig::default(),
+ )?,
+ max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
recent_turn_window: None,
};
let request = Request {
@@ -1107,7 +1235,7 @@ mod tests {
assert!(!contents.contains(&"client instructions".to_string()));
assert_eq!(
judge_request.llm_request.output.response_format,
- judge.config.response_schema
+ Some(judge.contract.response_format().clone())
);
assert_eq!(
judge_request.llm_request.output.max_output_tokens,
@@ -1151,16 +1279,13 @@ mod tests {
/// rejecting every production verdict.
#[test]
fn every_schema_property_round_trips_through_the_judge_parser() -> Result<()> {
- let config = LlmTaskClassifier::load_judge_config()?;
- let schema = config
- .response_schema
- .as_ref()
- .ok_or_else(|| LibsyError::AlgorithmError {
- message: "packaged judge config has no response schema".to_string(),
- })?;
+ let contract =
+ LlmTaskClassifier::load_capability_contract(&ClassifierContractConfig::default())?;
+ let schema = contract.response_format();
let reply = schema_shaped_verdict(schema)?;
let judge = CapabilityJudge {
- config: config.clone(),
+ contract,
+ max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
recent_turn_window: None,
};
@@ -1173,8 +1298,9 @@ mod tests {
#[test]
fn prompt_includes_concrete_rules_and_schema() -> Result<()> {
- let config = LlmTaskClassifier::load_judge_config()?;
- let prompt = config.system_prompt;
+ let contract =
+ LlmTaskClassifier::load_capability_contract(&ClassifierContractConfig::default())?;
+ let prompt = contract.system_prompt();
assert!(prompt.contains("SUP-1 [supported]"));
assert!(!prompt.contains("{{CAPABILITY_RULES}}"));
assert!(!prompt.contains("{{PRIMARY_RULE_VALUES}}"));
@@ -1182,10 +1308,9 @@ mod tests {
assert!(prompt.contains("\"type\": \"object\""));
assert!(!prompt.contains("\"json_schema\""));
assert!(!prompt.contains("\"CapabilityClassifierDecision\""));
- let rule_values = config
- .response_schema
- .as_ref()
- .and_then(|schema| schema.pointer("/json_schema/schema/properties/primary_rule/enum"))
+ let rule_values = contract
+ .response_format()
+ .pointer("/json_schema/schema/properties/primary_rule/enum")
.and_then(Value::as_array)
.ok_or_else(|| LibsyError::AlgorithmError {
message: "rendered response schema has no primary rule enum".to_string(),
@@ -1284,6 +1409,36 @@ mod tests {
Ok(())
}
+ #[tokio::test]
+ async fn escalation_config_overrides_the_packaged_prompt() -> Result<()> {
+ let client = Arc::new(PerRequestClient::default());
+ let target = |name: &str| LlmTarget {
+ semantic_name: name.to_string(),
+ llm_client: Some(client.clone()),
+ };
+ let router = Arc::new(LlmTaskClassifier::new_with_escalation_contract(
+ target("judge"),
+ target("efficient"),
+ target("capable"),
+ ClassifierContractConfig::default()
+ .with_prompt("Custom trajectory rubric:\n{{RESPONSE_SCHEMA}}"),
+ EscalationJudgeConfig {
+ confirmations: 1,
+ ..EscalationJudgeConfig::default()
+ },
+ DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
+ )?);
+
+ router.run(Context::default(), classify_request()).await?;
+
+ 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}}"));
+ Ok(())
+ }
+
#[tokio::test]
async fn escalation_router_upgrades_to_capable_when_judge_escalates() -> Result<()> {
// Judge: escalate. After the efficient call, the streak confirms and capable is served.
diff --git a/crates/libsy/src/algorithms/util.rs b/crates/libsy/src/algorithms/util.rs
index e6adfbbe1..32f6f3efd 100644
--- a/crates/libsy/src/algorithms/util.rs
+++ b/crates/libsy/src/algorithms/util.rs
@@ -2,6 +2,7 @@
// SPDX-License-Identifier: Apache-2.0
pub mod affinity;
+pub(crate) mod classifier_contract;
pub mod escalation;
pub(crate) mod llm_judge;
pub(crate) mod prompts;
diff --git a/crates/libsy/src/algorithms/util/classifier_contract.rs b/crates/libsy/src/algorithms/util/classifier_contract.rs
new file mode 100644
index 000000000..cb2a95a98
--- /dev/null
+++ b/crates/libsy/src/algorithms/util/classifier_contract.rs
@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Prompt and structured-output contracts shared by LLM classifiers.
+
+use serde::Deserialize;
+use serde_json::Value;
+
+use crate::{LibsyError, Result};
+
+/// User-configurable parts of a classifier's prompt and verdict contract.
+///
+/// Fields are private so new contract settings can be added without breaking Rust struct literals.
+#[derive(Clone, Debug, Default, Deserialize)]
+pub struct ClassifierContractConfig {
+ #[serde(default)]
+ prompt: Option<String>,
+}
+
+impl ClassifierContractConfig {
+ /// Overrides the packaged classifier prompt.
+ pub fn with_prompt(mut self, prompt: impl Into<String>) -> Self {
+ self.prompt = Some(prompt.into());
+ self
+ }
+
+ /// Returns the configured prompt override.
+ pub fn prompt(&self) -> Option<&str> {
+ self.prompt.as_deref()
+ }
+}
+
+/// Rendered prompt and response format for one classifier.
+#[derive(Debug)]
+pub(crate) struct ClassifierContract {
+ system_prompt: String,
+ response_format: Value,
+}
+
+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.
+ pub(crate) fn from_config(
+ config: &ClassifierContractConfig,
+ default_prompt: &str,
+ response_format_json: &str,
+ ) -> Result<Self> {
+ let prompt_template = config.prompt().unwrap_or(default_prompt);
+ if prompt_template.trim().is_empty() {
+ return Err(LibsyError::AlgorithmError {
+ message: "classifier prompt must not be empty".to_string(),
+ });
+ }
+ let response_format: Value =
+ serde_json::from_str(response_format_json).map_err(|error| {
+ LibsyError::AlgorithmError {
+ message: format!("response schema is invalid: {error}"),
+ }
+ })?;
+ let prompt_schema = response_format
+ .pointer("/json_schema/schema")
+ .ok_or_else(|| LibsyError::AlgorithmError {
+ message: "response schema has no json_schema.schema".to_string(),
+ })?;
+ let prompt_schema = serde_json::to_string_pretty(prompt_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),
+ response_format,
+ })
+ }
+
+ pub(crate) fn system_prompt(&self) -> &str {
+ &self.system_prompt
+ }
+
+ pub(crate) fn response_format(&self) -> &Value {
+ &self.response_format
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn a_runtime_contract_renders_its_own_schema() -> Result<()> {
+ let schema = r#"{
+ "type": "json_schema",
+ "json_schema": {
+ "name": "RiskDecision",
+ "schema": {
+ "type": "object",
+ "properties": {"risk": {"type": "number"}}
+ }
+ }
+ }"#;
+ let config = ClassifierContractConfig::default()
+ .with_prompt("Return a risk verdict matching:\n{{RESPONSE_SCHEMA}}");
+ 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
+ .response_format()
+ .pointer("/json_schema/name")
+ .and_then(Value::as_str),
+ Some("RiskDecision")
+ );
+ Ok(())
+ }
+
+ #[test]
+ fn a_contract_requires_an_inner_json_schema() {
+ let error = ClassifierContract::from_config(
+ &ClassifierContractConfig::default(),
+ "classify",
+ r#"{"type":"json"}"#,
+ )
+ .expect_err("missing inner schema should be rejected");
+
+ assert!(error.to_string().contains("json_schema.schema"));
+ }
+
+ #[test]
+ fn a_contract_rejects_an_empty_prompt() {
+ let config = ClassifierContractConfig::default().with_prompt(" \n");
+ let error = ClassifierContract::from_config(
+ &config,
+ "packaged prompt",
+ r#"{"json_schema":{"schema":{"type":"object"}}}"#,
+ )
+ .expect_err("empty prompt should be rejected");
+
+ assert!(error.to_string().contains("prompt must not be empty"));
+ }
+}
diff --git a/crates/libsy/src/algorithms/util/escalation.rs b/crates/libsy/src/algorithms/util/escalation.rs
index 276d612ac..d71bfd260 100644
--- a/crates/libsy/src/algorithms/util/escalation.rs
+++ b/crates/libsy/src/algorithms/util/escalation.rs
@@ -10,7 +10,8 @@
use serde::Deserialize;
use switchyard_protocol::{ContentBlock, LlmRequest, Message, OutputParams, Role};
-use super::llm_judge::{self, Judge, JudgeClassifier, JudgeConfig, JudgePolicy};
+use super::classifier_contract::{ClassifierContract, ClassifierContractConfig};
+use super::llm_judge::{Judge, JudgeClassifier, JudgePolicy};
use crate::core::algorithm::LlmTarget;
use crate::core::classifier::{Classification, Score};
use crate::core::state::State;
@@ -94,7 +95,8 @@ pub(crate) struct EscalationVerdict {
/// Builds the judge request from the conversation so far.
pub(crate) struct EscalationJudge {
- rubric: JudgeConfig,
+ contract: ClassifierContract,
+ max_output_tokens: u64,
config: EscalationJudgeConfig,
}
@@ -110,12 +112,12 @@ impl Judge for EscalationJudge {
llm_request: LlmRequest {
model: request.llm_request.model.clone(),
messages: vec![
- Message::text(Role::System, self.rubric.system_prompt.clone()),
+ Message::text(Role::System, self.contract.system_prompt().to_string()),
Message::text(Role::User, summary),
],
output: OutputParams {
- response_format: self.rubric.response_schema.clone(),
- max_output_tokens: Some(self.rubric.max_output_tokens),
+ response_format: Some(self.contract.response_format().clone()),
+ max_output_tokens: Some(self.max_output_tokens),
},
..LlmRequest::default()
},
@@ -161,6 +163,7 @@ pub(crate) fn build_judge(
judge_target: LlmTarget,
capable: String,
efficient: String,
+ contract_config: &ClassifierContractConfig,
config: EscalationJudgeConfig,
max_output_tokens: u64,
) -> Result<JudgeClassifier<EscalationJudge, EscalationPolicy>> {
@@ -170,10 +173,14 @@ pub(crate) fn build_judge(
message: "max_output_tokens must be at least 1".to_string(),
});
}
- let mut rubric = llm_judge::load_judge_config(PROMPT_TEMPLATE, SCHEMA_TEMPLATE)?;
- rubric.max_output_tokens = max_output_tokens;
+ let contract =
+ ClassifierContract::from_config(contract_config, PROMPT_TEMPLATE, SCHEMA_TEMPLATE)?;
Ok(JudgeClassifier::new(
- EscalationJudge { rubric, config },
+ EscalationJudge {
+ contract,
+ max_output_tokens,
+ config,
+ },
judge_target,
EscalationPolicy { capable, efficient },
))
@@ -362,7 +369,12 @@ mod tests {
#[test]
fn judge_request_is_rubric_plus_summary_under_a_completion_cap() -> Result<()> {
let judge = EscalationJudge {
- rubric: llm_judge::load_judge_config(PROMPT_TEMPLATE, SCHEMA_TEMPLATE)?,
+ contract: ClassifierContract::from_config(
+ &ClassifierContractConfig::default(),
+ PROMPT_TEMPLATE,
+ SCHEMA_TEMPLATE,
+ )?,
+ max_output_tokens: super::super::DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
config: EscalationJudgeConfig::default(),
};
@@ -394,10 +406,13 @@ mod tests {
#[test]
fn judge_request_uses_the_configured_completion_cap() -> Result<()> {
- let mut rubric = llm_judge::load_judge_config(PROMPT_TEMPLATE, SCHEMA_TEMPLATE)?;
- rubric.max_output_tokens = 512;
let judge = EscalationJudge {
- rubric,
+ contract: ClassifierContract::from_config(
+ &ClassifierContractConfig::default(),
+ PROMPT_TEMPLATE,
+ SCHEMA_TEMPLATE,
+ )?,
+ max_output_tokens: 512,
config: EscalationJudgeConfig::default(),
};
diff --git a/crates/libsy/src/algorithms/util/llm_judge.rs b/crates/libsy/src/algorithms/util/llm_judge.rs
index 4b8fc4c5e..1e6edde8b 100644
--- a/crates/libsy/src/algorithms/util/llm_judge.rs
+++ b/crates/libsy/src/algorithms/util/llm_judge.rs
@@ -11,7 +11,6 @@ use std::sync::Arc;
use async_trait::async_trait;
use serde::de::DeserializeOwned;
-use serde_json::Value;
use switchyard_protocol::{AggLlmResponse, completion_text};
use crate::core::algorithm::{Driver, LlmTarget};
@@ -20,29 +19,6 @@ use crate::core::state::State;
use crate::{LibsyError, Result};
use switchyard_protocol::{Context, Decision, Request, Response};
-use super::DEFAULT_JUDGE_MAX_OUTPUT_TOKENS;
-
-#[derive(Clone, Debug)]
-/// Prompt and structured-output contract for one judge.
-pub struct JudgeConfig {
- /// Prepended instructions that define what the judge evaluates.
- pub system_prompt: String,
- /// Optional provider response format that constrains the judge verdict.
- pub response_schema: Option<Value>,
- /// Maximum completion tokens available to the judge verdict.
- pub max_output_tokens: u64,
-}
-
-impl Default for JudgeConfig {
- fn default() -> Self {
- Self {
- system_prompt: String::new(),
- response_schema: None,
- max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
- }
- }
-}
-
/// Builds and parses requests for one algorithm-specific LLM judge.
pub trait Judge: Send + Sync {
type Verdict: DeserializeOwned + Send + Sync;
@@ -159,36 +135,6 @@ where
}
}
-/// Builds a [`JudgeConfig`] from a prompt template and a JSON schema template.
-///
-/// `schema_template` must be a `{ "type": "json_schema", "json_schema": { "schema": ... } }`
-/// object; the inner `schema` is substituted into the `{{RESPONSE_SCHEMA}}` placeholder in
-/// `prompt_template`.
-pub(crate) fn load_judge_config(
- prompt_template: &str,
- schema_template: &str,
-) -> Result<JudgeConfig> {
- let response_schema: Value =
- serde_json::from_str(schema_template).map_err(|error| LibsyError::AlgorithmError {
- message: format!("response schema is invalid: {error}"),
- })?;
- let prompt_schema = response_schema
- .pointer("/json_schema/schema")
- .ok_or_else(|| LibsyError::AlgorithmError {
- message: "response schema has no json_schema.schema".to_string(),
- })?;
- let prompt_schema = serde_json::to_string_pretty(prompt_schema).map_err(|error| {
- LibsyError::AlgorithmError {
- message: format!("prompt schema could not be rendered: {error}"),
- }
- })?;
- Ok(JudgeConfig {
- system_prompt: prompt_template.replace("{{RESPONSE_SCHEMA}}", &prompt_schema),
- response_schema: Some(response_schema),
- max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,
- })
-}
-
fn parse_json_verdict<T: DeserializeOwned>(response: &AggLlmResponse) -> Result<T> {
// Providers sometimes wrap otherwise valid JSON in a Markdown fence.
let reply = completion_text(response);
diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rs
index 3d4188631..b154d0421 100644
--- a/crates/libsy/src/lib.rs
+++ b/crates/libsy/src/lib.rs
@@ -23,6 +23,7 @@ pub use algorithms::passthrough::{Passthrough, PassthroughDecision};
pub use algorithms::rand::{Random, RandomClassifier, RandomDecision};
pub use algorithms::stage::{LlmFallback, StageRouter, StageRouterConfig};
pub use algorithms::util::affinity::AffinityRouter;
+pub use algorithms::util::classifier_contract::ClassifierContractConfig;
pub use algorithms::util::escalation::EscalationJudgeConfig;
pub use algorithms::util::prompts::{SystemPromptProcessor, TargetPrompts, append_note};
pub use algorithms::util::subagent::SubagentOverride;
diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rs
index 2377d6daa..eb66dda72 100644
--- a/crates/switchyard-py/src/libsy_bindings.rs
+++ b/crates/switchyard-py/src/libsy_bindings.rs
@@ -10,9 +10,9 @@ use pyo3::exceptions::{PyTypeError, PyValueError};
use pyo3::prelude::*;
use serde_json::{Value, json};
use switchyard_libsy::{
- Algorithm, HandoffNoteConfig, LibsyError as RustLibsyError, LlmFallback, LlmTarget,
- LlmTargetSet, LlmTaskClassifier, Noop, PickerMode, Random, StageRouter, StageRouterConfig,
- TaskClassifierConfig,
+ Algorithm, ClassifierContractConfig, HandoffNoteConfig, LibsyError as RustLibsyError,
+ LlmFallback, LlmTarget, LlmTargetSet, LlmTaskClassifier, Noop, PickerMode, Random, StageRouter,
+ StageRouterConfig, TaskClassifierConfig,
};
use switchyard_protocol::{
AggLlmResponse, Context, Decision, LlmClientError, LlmResponse, Metadata, Request, Response,
@@ -97,7 +97,7 @@ impl PyLlmTarget {
}
}
-/// Classifier thresholds shared by standalone and stage-router classifiers.
+/// Classifier settings shared by standalone and stage-router classifiers.
#[pyclass(
name = "TaskClassifierConfig",
module = "switchyard.libsy",
@@ -126,7 +126,8 @@ impl PyTaskClassifierConfig {
session_affinity=false,
message_hash_fallback=false,
recent_turn_window=None,
- max_output_tokens=4096
+ max_output_tokens=4096,
+ prompt=None
))]
#[allow(clippy::too_many_arguments)]
fn new(
@@ -137,7 +138,12 @@ impl PyTaskClassifierConfig {
message_hash_fallback: bool,
recent_turn_window: Option<usize>,
max_output_tokens: u64,
+ prompt: Option<String>,
) -> Self {
+ let mut contract = ClassifierContractConfig::default();
+ if let Some(prompt) = prompt {
+ contract = contract.with_prompt(prompt);
+ }
Self {
inner: TaskClassifierConfig {
base_threshold,
@@ -146,6 +152,7 @@ impl PyTaskClassifierConfig {
session_affinity,
message_hash_fallback,
recent_turn_window,
+ contract,
max_output_tokens,
},
}
diff --git a/crates/switchyard-server/src/config.rs b/crates/switchyard-server/src/config.rs
index 07ddc8ea7..73c04ebc6 100644
--- a/crates/switchyard-server/src/config.rs
+++ b/crates/switchyard-server/src/config.rs
@@ -9,9 +9,9 @@ use std::path::Path;
use std::sync::Arc;
use libsy::{
- Algorithm, EscalationJudgeConfig, HandoffNoteConfig, LlmFallback, LlmTarget, LlmTargetSet,
- LlmTaskClassifier, Noop, Passthrough, PickerMode, Random, StageRouter, StageRouterConfig,
- TargetPrompts, TaskClassifierConfig,
+ Algorithm, ClassifierContractConfig, EscalationJudgeConfig, HandoffNoteConfig, LlmFallback,
+ LlmTarget, LlmTargetSet, LlmTaskClassifier, Noop, Passthrough, PickerMode, Random, StageRouter,
+ StageRouterConfig, TargetPrompts, TaskClassifierConfig,
};
use serde::Deserialize;
use serde_json::Value;
@@ -192,8 +192,21 @@ enum RouteConfig {
classifier_target: String,
strong_target: String,
weak_target: String,
- #[serde(flatten)]
- classifier_config: TaskClassifierConfig,
+ base_threshold: f64,
+ #[serde(default)]
+ min_confidence: f64,
+ #[serde(default)]
+ capability_elevated_floor: Option<f64>,
+ #[serde(default)]
+ session_affinity: bool,
+ #[serde(default)]
+ message_hash_fallback: bool,
+ #[serde(default)]
+ recent_turn_window: Option<usize>,
+ #[serde(default)]
+ prompt: Option<String>,
+ #[serde(default = "default_classifier_max_output_tokens")]
+ max_output_tokens: u64,
/// Present to route by escalation instead of up-front classification.
///
/// The classifier target becomes a trajectory judge: every unlatched turn is served by
@@ -229,11 +242,40 @@ enum RouteConfig {
/// The judge a `stage_router` route falls through to, and how it routes.
#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
struct StageClassifierConfig {
/// Target the judge is called through. Not a routing destination.
target: String,
- #[serde(flatten)]
- config: TaskClassifierConfig,
+ base_threshold: f64,
+ #[serde(default)]
+ min_confidence: f64,
+ #[serde(default)]
+ capability_elevated_floor: Option<f64>,
+ #[serde(default)]
+ session_affinity: bool,
+ #[serde(default)]
+ message_hash_fallback: bool,
+ #[serde(default)]
+ recent_turn_window: Option<usize>,
+ #[serde(default)]
+ prompt: Option<String>,
+ #[serde(default = "default_classifier_max_output_tokens")]
+ max_output_tokens: u64,
+}
+
+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,
+ session_affinity: self.session_affinity,
+ message_hash_fallback: self.message_hash_fallback,
+ recent_turn_window: self.recent_turn_window,
+ contract: classifier_contract(self.prompt.as_deref()),
+ max_output_tokens: self.max_output_tokens,
+ }
+ }
}
impl RouteConfig {
@@ -332,25 +374,43 @@ fn build_algorithm(
classifier_target,
strong_target,
weak_target,
- classifier_config,
+ base_threshold,
+ min_confidence,
+ capability_elevated_floor,
+ session_affinity,
+ message_hash_fallback,
+ recent_turn_window,
+ prompt,
+ max_output_tokens,
escalation,
..
} => {
let classifier = resolve_target(route_name, classifier_target, targets)?;
let strong = resolve_target(route_name, strong_target, targets)?;
let weak = resolve_target(route_name, weak_target, targets)?;
+ let classifier_config = TaskClassifierConfig {
+ base_threshold: *base_threshold,
+ min_confidence: *min_confidence,
+ capability_elevated_floor: *capability_elevated_floor,
+ session_affinity: *session_affinity,
+ message_hash_fallback: *message_hash_fallback,
+ recent_turn_window: *recent_turn_window,
+ contract: classifier_contract(prompt.as_deref()),
+ max_output_tokens: *max_output_tokens,
+ };
// The weak model is the efficient tier; the strong model is the capable one.
// With `escalation`, the classifier target judges the weak tier's reply each turn
// instead of picking a tier ahead of it.
let algorithm = match escalation {
- Some(judge_config) => LlmTaskClassifier::new_with_escalation(
+ Some(judge_config) => LlmTaskClassifier::new_with_escalation_contract(
classifier,
weak,
strong,
+ classifier_config.contract,
judge_config.clone(),
classifier_config.max_output_tokens,
),
- None => LlmTaskClassifier::new(classifier, weak, strong, classifier_config.clone()),
+ None => LlmTaskClassifier::new(classifier, weak, strong, classifier_config),
}
.map_err(|error| {
ServerError::new(format!("llm_classifier route {route_name}: {error}"))
@@ -388,7 +448,7 @@ fn build_algorithm(
resolve_target(route_name, &classifier.target, targets).map(|judge_target| {
LlmFallback {
judge_target,
- config: classifier.config.clone(),
+ config: classifier.task_classifier_config(),
}
})
})
@@ -401,6 +461,16 @@ fn build_algorithm(
}
}
+fn classifier_contract(prompt: Option<&str>) -> ClassifierContractConfig {
+ prompt.map_or_else(ClassifierContractConfig::default, |prompt| {
+ ClassifierContractConfig::default().with_prompt(prompt)
+ })
+}
+
+fn default_classifier_max_output_tokens() -> u64 {
+ TaskClassifierConfig::default().max_output_tokens
+}
+
/// Keys each configured system prompt by the target it belongs to.
fn tier_prompts(
capable: &str,
@@ -566,6 +636,28 @@ target = "weak"
Ok(())
}
+ #[test]
+ fn classifier_prompts_are_configurable_in_both_modes() -> ServerResult<()> {
+ let capability = VALID_CONFIG.replace(
+ "base_threshold = 0.5",
+ "base_threshold = 0.5\nprompt = \"custom capability rubric\"",
+ );
+ server_state_from_toml(&capability)?;
+
+ let escalation = VALID_CONFIG.replace(
+ "base_threshold = 0.5",
+ "base_threshold = 0.5\nprompt = \"custom trajectory rubric\"\nescalation = { confirmations = 2 }",
+ );
+ server_state_from_toml(&escalation)?;
+
+ let empty = VALID_CONFIG.replace(
+ "base_threshold = 0.5",
+ "base_threshold = 0.5\nprompt = \" \"",
+ );
+ assert!(error_message(&empty).contains("classifier prompt must not be empty"));
+ Ok(())
+ }
+
#[test]
fn rejects_unknown_fields_and_algorithm_types() {
let unknown_field =
@@ -578,10 +670,44 @@ target = "weak"
);
assert!(error_message(&nested_completion_cap).contains("unknown field"));
+ let unknown_classifier_field = VALID_CONFIG.replace(
+ "base_threshold = 0.5",
+ "base_threshold = 0.5\nclassifier_magic = true",
+ );
+ assert!(error_message(&unknown_classifier_field).contains("unknown field"));
+
let unknown_algorithm = VALID_CONFIG.replace("type = \"noop\"", "type = \"imaginary\"");
assert!(error_message(&unknown_algorithm).contains("unknown variant"));
}
+ #[test]
+ fn rejects_unknown_stage_classifier_fields() {
+ // Nested classifier typos must fail instead of silently using a default.
+ let config = format!(
+ r#"{VALID_CONFIG}
+
+[routes.stage]
+id = "switchyard/stage"
+type = "stage_router"
+capable_target = "strong"
+efficient_target = "weak"
+picker = "efficient_first"
+confidence_threshold = 1.0
+
+[routes.stage.classifier]
+target = "classifier"
+base_threshold = 0.5
+classifier_magic = true
+"#
+ );
+
+ let error = error_message(&config);
+ assert!(
+ error.contains("unknown field `classifier_magic`"),
+ "{error}"
+ );
+ }
+
#[test]
fn rejects_invalid_references_and_parameters() {
let cases = [
diff --git a/crates/switchyard-server/tests/server.rs b/crates/switchyard-server/tests/server.rs
index b9aa45854..86f96f053 100644
--- a/crates/switchyard-server/tests/server.rs
+++ b/crates/switchyard-server/tests/server.rs
@@ -114,7 +114,13 @@ async fn upstream_chat(
return Sse::new(stream).into_response();
}
- let content = if model == "model/classifier" {
+ let content = if model == "model/classifier"
+ && body
+ .pointer("/response_format/json_schema/schema/properties/escalate")
+ .is_some()
+ {
+ 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"}"#
} else {
"ok"
@@ -726,6 +732,103 @@ base_threshold = 0.5
Ok(())
}
+#[tokio::test]
+async fn classifier_prompt_overrides_reach_every_server_mode() -> TestResult {
+ let upstream = MockUpstream::start().await?;
+ let state = load_test_config(&format!(
+ r#"
+schema_version = 1
+
+[llm_clients.upstream]
+format = "openai_chat"
+base_url = "{base_url}"
+
+[targets.classifier]
+id = "model/classifier"
+llm_client = "upstream"
+
+[targets.strong]
+id = "model/strong"
+llm_client = "upstream"
+
+[targets.weak]
+id = "model/weak"
+llm_client = "upstream"
+
+[routes.capability]
+id = "switchyard/capability"
+type = "llm_classifier"
+classifier_target = "classifier"
+strong_target = "strong"
+weak_target = "weak"
+base_threshold = 0.5
+prompt = "CUSTOM CAPABILITY\n{{RESPONSE_SCHEMA}}"
+
+[routes.escalation]
+id = "switchyard/escalation"
+type = "llm_classifier"
+classifier_target = "classifier"
+strong_target = "strong"
+weak_target = "weak"
+base_threshold = 0.5
+prompt = "CUSTOM ESCALATION\n{{RESPONSE_SCHEMA}}"
+escalation = {{ confirmations = 1 }}
+
+[routes.stage]
+id = "switchyard/stage"
+type = "stage_router"
+capable_target = "strong"
+efficient_target = "weak"
+picker = "efficient_first"
+confidence_threshold = 1.0
+
+[routes.stage.classifier]
+target = "classifier"
+base_threshold = 0.5
+prompt = "CUSTOM STAGE\n{{RESPONSE_SCHEMA}}"
+"#,
+ base_url = upstream.base_url
+ ))?;
+ let app = build_switchyard_router(state);
+
+ for (route, prompt_prefix, schema_field) in [
+ ("switchyard/capability", "CUSTOM CAPABILITY", "p_solve"),
+ ("switchyard/escalation", "CUSTOM ESCALATION", "escalate"),
+ ("switchyard/stage", "CUSTOM STAGE", "p_solve"),
+ ] {
+ upstream.calls.lock().await.clear();
+ let response = send(
+ &app,
+ "POST",
+ "/v1/chat/completions",
+ Some(json!({
+ "model": route,
+ "messages": [{"role": "user", "content": "bounded task"}]
+ })),
+ )
+ .await?;
+
+ assert_eq!(response.status, StatusCode::OK);
+ let calls = upstream.calls.lock().await;
+ let judge_call = calls
+ .iter()
+ .find(|call| call["model"] == "model/classifier")
+ .ok_or("classifier target was not called")?;
+ let prompt = judge_call["messages"][0]["content"]
+ .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)
+ .is_some(),
+ "{route}: missing {schema_field} in {judge_call}"
+ );
+ }
+ Ok(())
+}
+
#[tokio::test]
async fn count_tokens_forwards_to_configured_anthropic_target() -> TestResult {
let upstream = MockUpstream::start().await?;
diff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.md
index 918e8e3e4..4bf0e435b 100644
--- a/docs/reference/toml_schema.md
+++ b/docs/reference/toml_schema.md
@@ -99,6 +99,8 @@ tuning.
| `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, or the trajectory-judge prompt when `escalation` is set. `{{RESPONSE_SCHEMA}}` expands to the active packaged schema. |
+| `max_output_tokens` | No | `4096` | Maximum completion tokens for the judge verdict. Must be at least `1`. |
| `escalation` | No | unset | Switches the route to escalation judging. |
Add an `escalation` table to judge each completed turn instead of classifying up
@@ -111,8 +113,9 @@ front. See
| `recent_turn_window` | No | `28` | Trailing messages shown to the judge. |
| `window_message_chars` | No | `500` | Per-message cap inside that window. |
-`base_threshold` stays required, but escalation ignores it and the other
-classifier keys.
+`base_threshold` stays required, but escalation ignores the capability thresholds,
+affinity settings, and route-level `recent_turn_window`. The shared `prompt` and
+`max_output_tokens` keys still configure its judge.
### `stage_router`
diff --git a/docs/routing_algorithms/escalation_router_routing.md b/docs/routing_algorithms/escalation_router_routing.md
index 6b179930c..522168d1c 100644
--- a/docs/routing_algorithms/escalation_router_routing.md
+++ b/docs/routing_algorithms/escalation_router_routing.md
@@ -39,6 +39,7 @@ classifier_target = "judge"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5
+prompt = "Judge whether the weak model is stuck. Return the required structured verdict."
escalation = { confirmations = 2, recent_turn_window = 28, window_message_chars = 500 }
```
@@ -47,6 +48,9 @@ clients send; the judge is not exposed as a client-selectable model.
`base_threshold` is still required, but escalation ignores it, along with
`min_confidence`, `capability_elevated_floor`, and `session_affinity`.
+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.
## How the decision works
@@ -102,8 +106,9 @@ strong tier. `2` or higher requires a session identity, because the streak is
retained per session — without one, every turn starts from zero and the route
never latches. Clients supply it with `x-switchyard-session-id`.
-Everything else is fixed: anchor and transcript caps, the judge's reply budget,
-and the streak rule that any decline resets to zero.
+Anchor and transcript caps remain fixed. Set the route-level
+`max_output_tokens` key to change the judge's reply budget. Any decline still
+resets the streak to zero.
## Run the route
diff --git a/docs/routing_algorithms/llm_classifier_routing.md b/docs/routing_algorithms/llm_classifier_routing.md
index 0f09533cf..ef400e9a1 100644
--- a/docs/routing_algorithms/llm_classifier_routing.md
+++ b/docs/routing_algorithms/llm_classifier_routing.md
@@ -78,6 +78,32 @@ more traffic to the strong model.
| `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. |
| `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. |
+| `max_output_tokens` | `4096` | Maximum completion tokens available to the classifier verdict. Must be at least `1`. |
+
+### 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.
+
+```toml
+[routes.smart]
+id = "smart"
+type = "llm_classifier"
+classifier_target = "classifier"
+strong_target = "strong"
+weak_target = "weak"
+base_threshold = 0.5
+prompt = """
+Estimate whether the weak target can complete the request.
+Return JSON matching this schema:
+{{RESPONSE_SCHEMA}}
+"""
+```
+
+The override changes the instructions only. The judge must still return the
+packaged fields such as `p_solve`, `confidence`, and `capability_boundary`.
### Classifier calibration
@@ -92,8 +118,6 @@ 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.
-Support for supplying your own classifier prompt is coming soon.
-
## Session affinity
With `session_affinity = true`, the first selected target is retained for the
diff --git a/docs/routing_algorithms/stage_router_routing.md b/docs/routing_algorithms/stage_router_routing.md
index 2c60b192b..b9cfa05b2 100644
--- a/docs/routing_algorithms/stage_router_routing.md
+++ b/docs/routing_algorithms/stage_router_routing.md
@@ -256,8 +256,13 @@ target = "strong" # target the judge is called through (not a routing d
base_threshold = 0.5 # p_solve floor to route efficient; below this → capable
min_confidence = 0.7 # judge confidence floor; below this → abstain
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.
+
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
and can cause sustained 429s at scale.
diff --git a/tests/test_libsy_minimal_bindings.py b/tests/test_libsy_minimal_bindings.py
index 307b82216..9cd55a586 100644
--- a/tests/test_libsy_minimal_bindings.py
+++ b/tests/test_libsy_minimal_bindings.py
@@ -7,7 +7,7 @@ from typing import Any
import pytest
-from switchyard.libsy import LibsyError, LlmTarget, algorithms
+from switchyard.libsy import LibsyError, LlmTarget, TaskClassifierConfig, algorithms
def request_body() -> dict[str, Any]:
@@ -60,6 +60,54 @@ async def test_random_runs_with_a_python_client() -> None:
assert response["outputs"][0]["content"] == [{"type": "text", "text": "fast"}]
+async def test_classifier_config_accepts_a_prompt_override() -> None:
+ """Verify that a configured classifier prompt is rendered for the judge."""
+
+ class JudgeClient(EchoClient):
+ async def call(self, request: dict[str, Any]) -> dict[str, Any]:
+ self.calls.append(request)
+ return {
+ "model": self.model,
+ "outputs": [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "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"}'
+ ),
+ }
+ ],
+ "stop_reason": "end_turn",
+ }
+ ],
+ }
+
+ judge = JudgeClient("judge")
+ weak = EchoClient("weak")
+ algorithm = algorithms.llm_task_classifier(
+ LlmTarget("judge", judge),
+ LlmTarget("weak", weak),
+ LlmTarget("strong", EchoClient("strong")),
+ config=TaskClassifierConfig(
+ 0.5,
+ prompt="Custom capability rubric:\n{{RESPONSE_SCHEMA}}",
+ ),
+ )
+
+ _, 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 response["model"] == "weak"
+
+
async def test_random_weights_and_seed_are_reproducible() -> None:
def algorithm():
return algorithms.random(