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): custom schema support + multi target (>2) routing support (#275)
Ayush Agarwal4ae99c215891
diff --git a/Cargo.lock b/Cargo.lockindex a6a9d586d..09354946e 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -2,6 +2,20 @@# It is not intended for manual editing.version = 4+[[package]]+name = "ahash"+version = "0.8.12"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"+dependencies = [+ "cfg-if",+ "getrandom 0.3.4",+ "once_cell",+ "serde",+ "version_check",+ "zerocopy",+]+[[package]]name = "aho-corasick"version = "1.1.4"@@ -11,6 +25,12 @@ dependencies = ["memchr",]+[[package]]+name = "allocator-api2"+version = "0.2.21"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"+[[package]]name = "anstream"version = "1.0.0"@@ -105,7 +125,7 @@ checksum = "c7c24de15d275a1ecfd47a380fb4d5ec9bfe0933f309ed5e705b775596a3574d"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -116,7 +136,7 @@ checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -234,18 +254,45 @@ version = "0.22.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"+[[package]]+name = "bit-set"+version = "0.8.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"+dependencies = [+ "bit-vec",+]++[[package]]+name = "bit-vec"+version = "0.8.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"+[[package]]name = "bitflags"version = "2.13.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"+[[package]]+name = "borrow-or-share"+version = "0.2.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "dc0b364ead1874514c8c2855ab558056ebfeb775653e7ae45ff72f28f8f3166c"+[[package]]name = "bumpalo"version = "3.20.3"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"+[[package]]+name = "bytecount"+version = "0.6.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e"+[[package]]name = "bytes"version = "1.12.1"@@ -318,7 +365,7 @@ dependencies = ["heck","proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -377,6 +424,12 @@ dependencies = ["libc",]+[[package]]+name = "data-encoding"+version = "2.11.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06"+[[package]]name = "deadpool"version = "0.12.3"@@ -409,7 +462,7 @@ checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -424,6 +477,15 @@ version = "1.16.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"+[[package]]+name = "email_address"+version = "0.2.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449"+dependencies = [+ "serde",+]+[[package]]name = "equivalent"version = "1.0.2"@@ -440,6 +502,17 @@ dependencies = ["windows-sys 0.61.2",]+[[package]]+name = "fancy-regex"+version = "0.18.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e1e1dacd0d2082dfcf1351c4bdd566bbe89a2b263235a2b50058f1e130a47277"+dependencies = [+ "bit-set",+ "regex-automata",+ "regex-syntax",+]+[[package]]name = "fastrand"version = "2.5.0"@@ -452,12 +525,29 @@ version = "0.1.9"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"+[[package]]+name = "fluent-uri"+version = "0.4.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "bc74ac4d8359ae70623506d512209619e5cf8f347124910440dbc221714b328e"+dependencies = [+ "borrow-or-share",+ "ref-cast",+ "serde",+]+[[package]]name = "fnv"version = "1.0.7"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"+[[package]]+name = "foldhash"+version = "0.2.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"+[[package]]name = "form_urlencoded"version = "1.2.2"@@ -467,6 +557,16 @@ dependencies = ["percent-encoding",]+[[package]]+name = "fraction"+version = "0.15.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e076045bb43dac435333ed5f04caf35c7463631d0dae2deb2638d94dd0a5b872"+dependencies = [+ "lazy_static",+ "num",+]+[[package]]name = "fs-err"version = "3.3.1"@@ -539,7 +639,7 @@ checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -591,9 +691,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"dependencies = ["cfg-if",+ "js-sys","libc","r-efi 5.3.0","wasip2",+ "wasm-bindgen",][[package]]@@ -634,6 +736,11 @@ name = "hashbrown"version = "0.17.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"+dependencies = [+ "allocator-api2",+ "equivalent",+ "foldhash",+][[package]]name = "heck"@@ -925,7 +1032,7 @@ dependencies = ["quote","rustc_version","simd_cesu8",- "syn",+ "syn 2.0.119",][[package]]@@ -944,7 +1051,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"dependencies = ["quote",- "syn",+ "syn 2.0.119",][[package]]@@ -968,6 +1075,68 @@ dependencies = ["wasm-bindgen",]+[[package]]+name = "jsonptr"+version = "0.8.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "85019623956752c8dd1f04a7b05d066187e0c9b217454246d8397d2a4893cc83"+dependencies = [+ "serde",+ "serde_json",+]++[[package]]+name = "jsonschema"+version = "0.49.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "257549c093d8f3d043337ba0d507e8eeace2447dfae3f0ee37eb0f57d3df7655"+dependencies = [+ "ahash",+ "bytecount",+ "data-encoding",+ "email_address",+ "fancy-regex",+ "fraction",+ "getrandom 0.3.4",+ "idna",+ "itoa",+ "jsonschema-regex",+ "jsonschema-value",+ "num-cmp",+ "num-traits",+ "percent-encoding",+ "referencing",+ "regex",+ "serde",+ "serde_json",+ "strum",+ "unicode-general-category",+ "uuid-simd",+]++[[package]]+name = "jsonschema-regex"+version = "0.49.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "474790e948498099d61ec85c10dc72d459d61298b7975eda7fb163af1934b134"+dependencies = [+ "regex-syntax",+]++[[package]]+name = "jsonschema-value"+version = "0.49.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8212315eb8e0bc44959d1af653cd5ec515771a3cdca966cfc0a10999bff144b9"+dependencies = [+ "ahash",+ "bytecount",+ "fraction",+ "num-cmp",+ "num-traits",+ "serde_json",+]+[[package]]name = "lazy_static"version = "1.5.0"@@ -1034,6 +1203,12 @@ version = "2.8.3"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"+[[package]]+name = "micromap"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c2a86d3146ed3995b5913c414f6664344b9617457320782e64f0bb44afd49d74"+[[package]]name = "mime"version = "0.3.17"@@ -1060,6 +1235,84 @@ dependencies = ["windows-sys 0.61.2",]+[[package]]+name = "num"+version = "0.4.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "35bd024e8b2ff75562e5f34e7f4905839deb4b22955ef5e73d2fea1b9813cb23"+dependencies = [+ "num-bigint",+ "num-complex",+ "num-integer",+ "num-iter",+ "num-rational",+ "num-traits",+]++[[package]]+name = "num-bigint"+version = "0.4.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"+dependencies = [+ "num-integer",+ "num-traits",+]++[[package]]+name = "num-cmp"+version = "0.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "63335b2e2c34fae2fb0aa2cecfd9f0832a1e24b3b32ecec612c3426d46dc8aaa"++[[package]]+name = "num-complex"+version = "0.4.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"+dependencies = [+ "num-traits",+]++[[package]]+name = "num-integer"+version = "0.1.46"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"+dependencies = [+ "num-traits",+]++[[package]]+name = "num-iter"+version = "0.1.46"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c92800bd69a1eac91786bcfe9da64a897eb72911b8dc3095decbd07429e8048b"+dependencies = [+ "num-integer",+ "num-traits",+]++[[package]]+name = "num-rational"+version = "0.4.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"+dependencies = [+ "num-bigint",+ "num-integer",+ "num-traits",+]++[[package]]+name = "num-traits"+version = "0.2.19"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"+dependencies = [+ "autocfg",+]+[[package]]name = "num_cpus"version = "1.17.0"@@ -1172,6 +1425,12 @@ dependencies = ["tokio",]+[[package]]+name = "outref"+version = "0.5.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e"+[[package]]name = "parking_lot"version = "0.12.5"@@ -1291,7 +1550,7 @@ dependencies = ["itertools","proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -1370,7 +1629,7 @@ dependencies = ["proc-macro2","pyo3-macros-backend","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -1383,7 +1642,7 @@ dependencies = ["proc-macro2","pyo3-build-config","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -1538,6 +1797,43 @@ dependencies = ["bitflags",]+[[package]]+name = "ref-cast"+version = "1.0.26"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "216e8f773d7923bcba9ceb86a86c93cabb3903a11872fc3f138c49630e50b96d"+dependencies = [+ "ref-cast-impl",+]++[[package]]+name = "ref-cast-impl"+version = "1.0.26"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2c9283685feec7d69af75fb0e858d5e7378f33fe4fc699383b2916ab9273e03c"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.3",+]++[[package]]+name = "referencing"+version = "0.49.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2bf1a74e036be2546c0c81cdfad6b2def6a25bf31c4e34a468037058d3bd05c6"+dependencies = [+ "ahash",+ "fluent-uri",+ "getrandom 0.3.4",+ "hashbrown",+ "itoa",+ "micromap",+ "parking_lot",+ "percent-encoding",+ "serde_json",+]+[[package]]name = "regex"version = "1.13.1"@@ -1817,7 +2113,7 @@ checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -1940,6 +2236,27 @@ version = "0.11.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"+[[package]]+name = "strum"+version = "0.28.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9628de9b8791db39ceda2b119bbe13134770b56c138ec1d3af810d045c04f9bd"+dependencies = [+ "strum_macros",+]++[[package]]+name = "strum_macros"+version = "0.28.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ab85eea0270ee17587ed4156089e10b9e6880ee688791d45a905f5b1ca36f664"+dependencies = [+ "heck",+ "proc-macro2",+ "quote",+ "syn 2.0.119",+]+[[package]]name = "subtle"version = "2.6.1"@@ -1973,6 +2290,8 @@ version = "0.2.0"dependencies = ["async-trait","futures",+ "jsonptr",+ "jsonschema","opentelemetry","opentelemetry_sdk","parking_lot",@@ -2112,6 +2431,17 @@ dependencies = ["unicode-ident",]+[[package]]+name = "syn"+version = "3.0.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"+dependencies = [+ "proc-macro2",+ "quote",+ "unicode-ident",+]+[[package]]name = "sync_wrapper"version = "1.0.2"@@ -2129,7 +2459,7 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -2177,7 +2507,7 @@ checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -2188,7 +2518,7 @@ checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -2250,7 +2580,7 @@ checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -2392,7 +2722,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -2456,6 +2786,12 @@ version = "0.2.5"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"+[[package]]+name = "unicode-general-category"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0b993bddc193ae5bd0d623b49ec06ac3e9312875fdae725a975c51db1cc1677f"+[[package]]name = "unicode-ident"version = "1.0.24"@@ -2492,12 +2828,34 @@ version = "0.2.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"+[[package]]+name = "uuid-simd"+version = "0.8.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "23b082222b4f6619906941c17eb2297fff4c2fb96cb60164170522942a200bd8"+dependencies = [+ "outref",+ "vsimd",+]+[[package]]name = "valuable"version = "0.1.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"+[[package]]+name = "version_check"+version = "0.9.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"++[[package]]+name = "vsimd"+version = "0.8.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64"+[[package]]name = "walkdir"version = "2.5.0"@@ -2574,7 +2932,7 @@ dependencies = ["bumpalo","proc-macro2","quote",- "syn",+ "syn 2.0.119","wasm-bindgen-shared",]@@ -2792,7 +3150,7 @@ checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119","synstructure",]@@ -2813,7 +3171,7 @@ checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]@@ -2833,7 +3191,7 @@ checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119","synstructure",]@@ -2873,7 +3231,7 @@ checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"dependencies = ["proc-macro2","quote",- "syn",+ "syn 2.0.119",][[package]]diff --git a/Cargo.toml b/Cargo.tomlindex 56299c1fb..90c27d543 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -29,6 +29,8 @@ futures = "0.3"futures-util = "0.3"http = "1"httpdate = "1"+jsonschema = { version = "0.49.4", default-features = false }+jsonptr = { version = "0.8.1", default-features = false, features = ["std", "json", "resolve"] }parking_lot = "0.12"rand = "0.10"reqwest = { version = "0.13.4", default-features = false, features = ["json", "rustls", "stream"] }diff --git a/crates/libsy/Cargo.toml b/crates/libsy/Cargo.tomlindex ce34afe2f..bea219160 100644--- a/crates/libsy/Cargo.toml+++ b/crates/libsy/Cargo.toml@@ -21,6 +21,8 @@ async-trait.workspace = trueserde.workspace = trueserde_json.workspace = truefutures.workspace = true+jsonschema.workspace = true+jsonptr.workspace = true# Metrics-only OTel API: instruments record through the host-installed global# meter provider. Pinned to the 0.32 line used across the workspace.opentelemetry = { version = "0.32", default-features = false, features = ["metrics"] }diff --git a/crates/libsy/README.md b/crates/libsy/README.mdindex 3f5def27f..4d699f266 100644--- a/crates/libsy/README.md+++ b/crates/libsy/README.md@@ -19,131 +19,18 @@ tokio = { version = "1", features = ["macros", "rt"] }## Quick start-This complete `src/main.rs` routes a request with [`LlmTaskClassifier`]. The-first [`Algorithm::run`] lets libsy call each target's client. The second drives-[`Algorithm::run_stream`] so the host can perform or override each model call-itself.--```rust-use std::sync::Arc;--use async_trait::async_trait;-use futures::StreamExt;-use switchyard_libsy::{- Algorithm, LibsyError, LlmTarget, LlmTaskClassifier, Step, TaskClassifierConfig,-};-use switchyard_protocol::{- AggLlmResponse, ContentBlock, Context, Decision, LlmClientError, LlmRequest,- LlmResponse, Message, Request, Response, ResponseOutput, Role, RoutedLlmClient,-};--struct DemoClient;--#[async_trait]-impl RoutedLlmClient for DemoClient {- async fn call(- &self,- _ctx: Context,- _request: Request,- decision: Arc<dyn Decision>,- ) -> Result<Response, LlmClientError> {- let model = decision.selected_model();- let text = if model == "judge" {- 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}")- };- Ok(Response {- llm_response: LlmResponse::Agg(AggLlmResponse {- model: Some(model.to_string()),- outputs: vec![ResponseOutput {- role: Role::Assistant,- content: vec![ContentBlock::Text { text }],- stop_reason: None,- }],- ..AggLlmResponse::default()- }),- metadata: None,- })- }-}--#[tokio::main(flavor = "current_thread")]-async fn main() -> switchyard_libsy::Result<()> {- let client = Arc::new(DemoClient);- let target = |name: &str| LlmTarget {- semantic_name: name.to_string(),- llm_client: Some(client.clone()),- };-- let router: Arc<dyn Algorithm> = Arc::new(LlmTaskClassifier::new(- target("judge"),- target("efficient"),- target("capable"),- TaskClassifierConfig {- base_threshold: 0.5,- ..TaskClassifierConfig::default()- },- )?);- let request = Request {- llm_request: LlmRequest {- model: Some("auto".to_string()),- messages: vec![Message {- role: Role::User,- content: vec![ContentBlock::Text {- text: "Explain tail latency".to_string(),- }],- }],- ..LlmRequest::default()- },- ..Request::default()- };-- // `run` serves the judge and routed calls through their target clients.- let (_, response) = router- .clone()- .run(Context::default(), request.clone())- .await?;- println!("run returned {}", response.selected_model().unwrap_or("unknown"));-- // `run_stream` exposes those calls so the host controls their transport.- let stream = router.run_stream(Context::default(), request, None);- tokio::pin!(stream);- while let Some(step) = stream.next().await {- match step? {- Step::CallLlm(call) => {- let routed = call.get_routed().clone();- let target = routed.decision.selected_model().to_string();- let result = client- .call(routed.ctx, routed.request, routed.decision)- .await- .map_err(|source| LibsyError::client_call(target, source));- call.respond(result)?;- }- Step::Decision(decision) => {- println!("run_stream chose {}", decision.selected_model());- }- Step::ReturnToAgent(response) => {- println!(- "run_stream returned {}",- response.selected_model().unwrap_or("unknown")- );- }- }- }- Ok(())-}+The runnable examples cover both ways to integrate libsy:++```bash+cargo run -p switchyard-libsy --example research_agent+cargo run -p switchyard-libsy --example research_agent_core```+[`research_agent.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/libsy/examples/research_agent.rs)+uses target-owned clients with [`Algorithm::run`].+[`research_agent_core.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/libsy/examples/research_agent_core.rs)+uses [`Algorithm::run_stream`] when the host owns model transport.+## Built-in algorithms| Type | Purpose |diff --git a/crates/libsy/examples/research_agent.rs b/crates/libsy/examples/research_agent.rsindex f19d848b6..81d651cd4 100644--- a/crates/libsy/examples/research_agent.rs+++ b/crates/libsy/examples/research_agent.rs@@ -15,7 +15,8 @@ use std::sync::Arc;use async_trait::async_trait;use switchyard_libsy::{- Algorithm, LibsyError, LlmTarget, LlmTargetSet, LlmTaskClassifier, Result, TaskClassifierConfig,+ Algorithm, LibsyError, LlmClassifierConfig, LlmTarget, LlmTargetSet, LlmTaskClassifier, Result,+ TaskClassifierConfig,};use switchyard_protocol::{Context, Decision, LlmResponse, Request, Response, RoutedLlmClient, completion_text,@@ -103,15 +104,16 @@ async fn main() -> Result<()> {let classifier = target_set.get_target(CLASSIFIER)?;let weak = target_set.get_target(WEAK)?;let strong = target_set.get_target(STRONG)?;- let algo: Arc<dyn Algorithm> = Arc::new(LlmTaskClassifier::new(- classifier,- weak,- strong,- TaskClassifierConfig {- base_threshold: BASE_THRESHOLD,- ..TaskClassifierConfig::default()- },- )?);+ let algo: Arc<dyn Algorithm> =+ Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: classifier,+ efficient_target: weak,+ capable_target: strong,+ config: TaskClassifierConfig {+ base_threshold: BASE_THRESHOLD,+ ..TaskClassifierConfig::default()+ },+ })?);let agent = ResearchAgent { algo };println!("{}", agent.run("what is switchyard?").await?);diff --git a/crates/libsy/examples/research_agent_core.rs b/crates/libsy/examples/research_agent_core.rsindex 2d33cdeb2..6a655873a 100644--- a/crates/libsy/examples/research_agent_core.rs+++ b/crates/libsy/examples/research_agent_core.rs@@ -12,8 +12,8 @@use std::sync::Arc;use switchyard_libsy::{- Algorithm, LibsyError, LlmTarget, LlmTargetSet, LlmTaskClassifier, Result, Step,- TaskClassifierConfig,+ Algorithm, LibsyError, LlmClassifierConfig, LlmTarget, LlmTargetSet, LlmTaskClassifier, Result,+ Step, TaskClassifierConfig,};use switchyard_protocol::{Context, Decision, LlmResponse, Request, Response, completion_text, text_request, text_response,@@ -114,15 +114,16 @@ async fn main() -> Result<()> {let classifier = target_set.get_target(CLASSIFIER)?;let weak = target_set.get_target(WEAK)?;let strong = target_set.get_target(STRONG)?;- let algo: Arc<dyn Algorithm> = Arc::new(LlmTaskClassifier::new(- classifier,- weak,- strong,- TaskClassifierConfig {- base_threshold: BASE_THRESHOLD,- ..TaskClassifierConfig::default()- },- )?);+ let algo: Arc<dyn Algorithm> =+ Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: classifier,+ efficient_target: weak,+ capable_target: strong,+ config: TaskClassifierConfig {+ base_threshold: BASE_THRESHOLD,+ ..TaskClassifierConfig::default()+ },+ })?);let mut agent = ResearchAgent { algo };println!("{}", agent.run("what is switchyard?").await?);diff --git a/crates/libsy/src/algorithms/llm_class.rs b/crates/libsy/src/algorithms/llm_class.rsindex b298f1b4c..6ec775f2a 100644--- a/crates/libsy/src/algorithms/llm_class.rs+++ b/crates/libsy/src/algorithms/llm_class.rs@@ -1,24 +1,26 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-//! Task-level capability routing with a judge-backed classifier.-//!-//! The algorithm owns a [`FallThrough`] cascade. Its classifier judges the-//! full inbound request and selects one decisive target. Invalid, abstained, or unavailable judge-//! output always selects the capable target.+//! Judge-backed capability, escalation, and custom-policy routing.+use std::collections::{BTreeMap, BTreeSet};use std::sync::Arc;use async_trait::async_trait;use serde::{Deserialize, Deserializer};-use switchyard_protocol::{LlmRequest, Message, OutputParams, Role, SimpleDecision};+use serde_json::Value;+use switchyard_protocol::{Message, 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::{Judge, JudgeClassifier, JudgePolicy};+use super::util::llm_judge::{+ ClassifierInput, JsonSchemaDecoder, JudgeClassifier, JudgePolicy, JudgeRuntimeConfig,+ SerdeDecoder, StructuredJudge,+};+use super::util::target_selector::TargetSelectorPolicy;use crate::core::algorithm::{Algorithm, Driver, LlmTarget, LlmTargetSet};use crate::core::classifier::{Classification, Classifier, Score};use crate::core::state::{State, StateValue};@@ -90,19 +92,16 @@ fn trim_messages(messages: &[Message], recent_turn_window: usize) -> Vec<Messagekept.into_iter().cloned().collect()}-struct CapabilityJudge {- contract: ClassifierContract,- max_output_tokens: u64,+/// Selects the task messages shown to capability and custom-schema classifiers.+struct TaskInput {recent_turn_window: Option<usize>,}-impl Judge for CapabilityJudge {- type Verdict = TaskClassifierVerdict;-- fn build_request(&self, _state: &State, request: &Request) -> Request {+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.- let mut messages = match self.recent_turn_window {+ match self.recent_turn_window {Some(window) => trim_messages(&request.llm_request.messages, window),None => request.llm_request@@ -112,28 +111,13 @@ impl Judge for CapabilityJudge {.find(|message| message.role == Role::User).cloned().into_iter()- .collect::<Vec<_>>(),- };- messages.insert(- 0,- 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.max_output_tokens),- response_format: Some(self.contract.response_format().clone()),- },- ..LlmRequest::default()- },- raw_request: None,- metadata: request.metadata.clone(),+ .collect(),}}}+type CapabilityJudge = StructuredJudge<TaskInput, SerdeDecoder<TaskClassifierVerdict>>;+struct TaskClassifierPolicy {efficient_target: String,capable_target: String,@@ -333,6 +317,91 @@ impl TaskClassifierConfig {}}+/// Policy that maps a custom classifier verdict to a routing target.+#[derive(Clone, Debug)]+pub enum CustomClassifierPolicy {+ /// Resolves a JSON Pointer and treats its string value as a configured target label.+ TargetSelector {+ /// JSON Pointer evaluated against each schema-validated verdict.+ selector: String,+ },+}++impl CustomClassifierPolicy {+ /// Creates a policy that selects a target label through a JSON Pointer.+ pub fn target_selector(selector: impl Into<String>) -> Self {+ Self::TargetSelector {+ selector: selector.into(),+ }+ }+}++/// Settings for a classifier whose JSON Schema and target-selection policy are user supplied.+#[derive(Clone, Debug)]+pub struct CustomClassifierConfig {+ /// System prompt sent to the classifier judge.+ pub prompt: String,+ /// Inner JSON Schema placed inside the provider's structured-output wrapper.+ pub response_schema: Value,+ /// Deterministic policy applied after the verdict passes schema validation.+ pub policy: CustomClassifierPolicy,+ /// Enables session affinity before the judge-backed classifier.+ pub session_affinity: bool,+ /// Uses the first user message when session metadata is unavailable.+ pub message_hash_fallback: bool,+ /// Trailing conversation turns shown to the classifier judge.+ pub recent_turn_window: Option<usize>,+ /// Maximum completion tokens available to the classifier verdict.+ pub max_output_tokens: u64,+}++impl CustomClassifierConfig {+ /// Creates a custom-schema classifier contract with conservative runtime defaults.+ pub fn new(+ prompt: impl Into<String>,+ response_schema: Value,+ policy: CustomClassifierPolicy,+ ) -> Self {+ Self {+ prompt: prompt.into(),+ response_schema,+ policy,+ session_affinity: false,+ message_hash_fallback: false,+ recent_turn_window: None,+ max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,+ }+ }++ fn validate(&self) -> Result<()> {+ if self.max_output_tokens == 0 {+ return Err(LibsyError::AlgorithmError {+ message: "max_output_tokens must be at least 1".to_string(),+ });+ }+ if self.message_hash_fallback && !self.session_affinity {+ return Err(LibsyError::AlgorithmError {+ message: "message_hash_fallback requires session_affinity".to_string(),+ });+ }+ Ok(())+ }+}++enum CustomPolicyRuntime {+ TargetSelector(TargetSelectorPolicy),+}++impl JudgePolicy for CustomPolicyRuntime {+ type Verdict = Value;++ fn to_classification(&self, verdict: Option<&Self::Verdict>) -> Classification {+ match self {+ Self::TargetSelector(policy) => policy.to_classification(verdict),+ }+ }+}+struct TaskClassifier {classifier: JudgeClassifier<CapabilityJudge, TaskClassifierPolicy>,efficient_target: String,@@ -475,32 +544,101 @@ impl Classifier<State> for EscalationClassifier {}}-/// Routes each task between an efficient and capable target using an LLM judge.-///-/// The judge is consulted before the routed model call. Valid, confident output-/// selects a tier; invalid output, abstention, or a judge failure falls back to the-/// capable target. Optional session affinity can retain a prior assignment and skip-/// the judge on later turns.+/// Routes requests through a capability, escalation, or custom classifier mode.pub struct LlmTaskClassifier {route: FallThrough<State>,- /// The active classifier — either capability-based or escalation-based.+ /// Classifier used when this router is embedded in another cascade.inner: Arc<dyn Classifier<State>>,}+struct ClassifierRouteConfig {+ default_target: String,+ session_affinity: bool,+ message_hash_fallback: bool,+}++/// Complete construction settings for one LLM classifier mode.+#[non_exhaustive]+pub enum LlmClassifierConfig {+ /// Routes between efficient and capable targets from a task-level verdict.+ Capability {+ /// Target that produces classifier verdicts.+ judge_target: LlmTarget,+ /// Target used when the efficient tier can handle the task.+ efficient_target: LlmTarget,+ /// Target used when the task needs the capable tier.+ capable_target: LlmTarget,+ /// Capability classifier settings.+ config: TaskClassifierConfig,+ },+ /// Judges efficient responses and escalates after a confirmed streak.+ Escalation {+ /// Target that produces escalation verdicts.+ judge_target: LlmTarget,+ /// Target called before each escalation decision.+ efficient_target: LlmTarget,+ /// Target used after escalation is confirmed.+ capable_target: LlmTarget,+ /// Prompt and verdict contract settings for the escalation judge.+ contract: ClassifierContractConfig,+ /// Escalation policy settings.+ config: EscalationJudgeConfig,+ /// Maximum completion tokens available to the escalation verdict.+ max_output_tokens: u64,+ },+ /// Routes among named targets using a user-supplied schema and policy.+ Custom {+ /// Target that produces classifier verdicts.+ judge_target: LlmTarget,+ /// User-facing labels paired with their resolved routing targets.+ targets: Vec<(String, LlmTarget)>,+ /// Label selected when the judge does not produce a usable verdict.+ default_target: String,+ /// Custom classifier settings.+ config: CustomClassifierConfig,+ },+}+impl LlmTaskClassifier {- /// Builds task-level capability routing over `efficient_target` and `capable_target`.- ///- /// `judge_target` serves the classification call and is not itself a routing- /// destination. When enabled, session affinity runs before the judge and can- /// short-circuit it with a retained assignment.+ /// Builds the classifier mode described by `config`.////// # Errors///- /// Returns an error when thresholds are outside `[0, 1]`, the elevated floor is- /// not above the base threshold, the output-token budget is zero, message-hash- /// fallback is enabled without affinity, or the packaged judge prompt/schema- /// cannot be loaded.- pub fn new(+ /// Returns an error when the selected mode's targets, contract, policy, or runtime+ /// settings are invalid.+ pub fn new(config: LlmClassifierConfig) -> Result<Self> {+ match config {+ LlmClassifierConfig::Capability {+ judge_target,+ efficient_target,+ capable_target,+ config,+ } => Self::build_capability(judge_target, efficient_target, capable_target, config),+ LlmClassifierConfig::Escalation {+ judge_target,+ efficient_target,+ capable_target,+ contract,+ config,+ max_output_tokens,+ } => Self::build_escalation(+ judge_target,+ efficient_target,+ capable_target,+ contract,+ config,+ max_output_tokens,+ ),+ LlmClassifierConfig::Custom {+ judge_target,+ targets,+ default_target,+ config,+ } => Self::build_custom(judge_target, targets, default_target, config),+ }+ }++ fn build_capability(judge_target: LlmTarget,efficient_target: LlmTarget,capable_target: LlmTarget,@@ -513,11 +651,14 @@ impl LlmTaskClassifier {let message_hash_fallback = config.message_hash_fallback;let classifier = Arc::new(TaskClassifier {classifier: JudgeClassifier::new(- CapabilityJudge {+ StructuredJudge::new(+ TaskInput {+ recent_turn_window: config.recent_turn_window,+ },contract,- max_output_tokens: config.max_output_tokens,- recent_turn_window: config.recent_turn_window,- },+ SerdeDecoder::new(),+ JudgeRuntimeConfig::new(config.max_output_tokens)?,+ ),judge_target.clone(),TaskClassifierPolicy::new(efficient_target.semantic_name.clone(),@@ -529,60 +670,107 @@ impl LlmTaskClassifier {capable_target: capable_target.semantic_name.clone(),});let inner: Arc<dyn Classifier<State>> = classifier.clone();-- // Affinity comes first so a retained assignment short-circuits the judge call.- // Note: when this classifier is embedded inside another cascade (e.g. StageRouter)- // the affinity processor never fires — only the inner score() is called.- let mut route = FallThrough::<State>::new_with_state(targets).with_name(ALGORITHM_NAME);- if session_affinity {- let affinity = if message_hash_fallback {- AffinityRouter::new().with_message_hash_fallback()- } else {- AffinityRouter::new()- };- // Both roles must share one `Arc` so the classifier reads what the processor wrote.- let affinity = Arc::new(affinity);- route = route- .with_processor(affinity.clone())- .with_classifier(affinity);- }- // The judge abstains when it cannot tell; the capable tier catches those turns- // rather than letting the cascade come back empty-handed.- let capable_fallback = DefaultTarget::new(classifier.capable_target.clone());- Ok(Self {- route: route- .with_classifier(inner.clone())- .with_classifier(Arc::new(capable_fallback)),+ Self::from_classifier(+ targets,inner,- })+ ClassifierRouteConfig {+ default_target: classifier.capable_target.clone(),+ session_affinity,+ message_hash_fallback,+ },+ )}- /// Constructs an escalation variant that calls the efficient model each turn, judges its- /// response, and latches to the capable tier once the streak confirms.- ///- /// Every unlatched turn calls the efficient model, buffers its reply, and consults the- /// trajectory judge. Once `config.confirmations` consecutive escalate verdicts accumulate- /// the session latches to the capable tier for its remainder. A judge outage always stays- /// efficient.- pub fn new_with_escalation(+ fn build_custom(judge_target: LlmTarget,- efficient_target: LlmTarget,- capable_target: LlmTarget,- config: EscalationJudgeConfig,- max_output_tokens: u64,+ targets: Vec<(String, LlmTarget)>,+ default_target: String,+ config: CustomClassifierConfig,) -> Result<Self> {- Self::new_with_escalation_contract(- judge_target,- efficient_target,- capable_target,- ClassifierContractConfig::default(),- config,+ config.validate()?;+ if targets.len() < 2 {+ return Err(LibsyError::AlgorithmError {+ message: "custom classifier requires at least two targets".to_string(),+ });+ }++ let mut labels = BTreeSet::new();+ let mut semantic_names = BTreeSet::new();+ let mut target_map = BTreeMap::new();+ let mut resolved_targets = Vec::with_capacity(targets.len());+ for (label, target) in targets {+ if label.trim().is_empty() || label.trim() != label {+ return Err(LibsyError::AlgorithmError {+ message: "custom classifier target labels must be non-empty and have no surrounding whitespace"+ .to_string(),+ });+ }+ if !labels.insert(label.clone()) {+ return Err(LibsyError::AlgorithmError {+ message: format!("custom classifier target label {label:?} is duplicated"),+ });+ }+ if !semantic_names.insert(target.semantic_name.clone()) {+ return Err(LibsyError::AlgorithmError {+ message: format!(+ "custom classifier resolved target {:?} is duplicated",+ target.semantic_name+ ),+ });+ }+ target_map.insert(label, target.semantic_name.clone());+ resolved_targets.push(target);+ }+ let default_semantic_name =+ target_map+ .get(&default_target)+ .cloned()+ .ok_or_else(|| LibsyError::AlgorithmError {+ message: format!(+ "default_target {default_target:?} must be one of the configured targets"+ ),+ })?;++ let CustomClassifierConfig {+ prompt,+ response_schema,+ policy,+ session_affinity,+ message_hash_fallback,+ recent_turn_window,max_output_tokens,+ } = config;+ let contract = ClassifierContract::from_inner_schema(&prompt, response_schema)?;+ let policy = match policy {+ CustomClassifierPolicy::TargetSelector { selector } => {+ CustomPolicyRuntime::TargetSelector(TargetSelectorPolicy::new(+ selector, target_map,+ )?)+ }+ };+ let classifier: Arc<dyn Classifier<State>> = Arc::new(JudgeClassifier::new(+ StructuredJudge::new(+ TaskInput { recent_turn_window },+ contract,+ JsonSchemaDecoder::new(),+ JudgeRuntimeConfig::new(max_output_tokens)?,+ ),+ judge_target,+ policy,+ ));++ Self::from_classifier(+ LlmTargetSet::new(resolved_targets),+ classifier,+ ClassifierRouteConfig {+ default_target: default_semantic_name,+ session_affinity,+ message_hash_fallback,+ },)}- /// Constructs an escalation variant with a configurable classifier contract.- pub fn new_with_escalation_contract(+ fn build_escalation(judge_target: LlmTarget,efficient_target: LlmTarget,capable_target: LlmTarget,@@ -620,6 +808,43 @@ impl LlmTaskClassifier {fn load_capability_contract(config: &ClassifierContractConfig) -> Result<ClassifierContract> {ClassifierContract::from_config(config, PROMPT_TEMPLATE, SCHEMA_TEMPLATE)}++ /// Keeps affinity and fallback ordering identical across judge-backed modes.+ fn from_classifier(+ targets: LlmTargetSet,+ inner: Arc<dyn Classifier<State>>,+ config: ClassifierRouteConfig,+ ) -> Result<Self> {+ targets.get_target(&config.default_target)?;+ if config.message_hash_fallback && !config.session_affinity {+ return Err(LibsyError::AlgorithmError {+ message: "message_hash_fallback requires session_affinity".to_string(),+ });+ }+ // Affinity comes first so a retained assignment short-circuits the judge call.+ // Note: when this classifier is embedded inside another cascade (e.g. StageRouter)+ // the affinity processor never fires — only the inner score() is called.+ let mut route = FallThrough::<State>::new_with_state(targets).with_name(ALGORITHM_NAME);+ if config.session_affinity {+ let affinity = if config.message_hash_fallback {+ AffinityRouter::new().with_message_hash_fallback()+ } else {+ AffinityRouter::new()+ };+ // Both roles must share one `Arc` so the classifier reads what the processor wrote.+ let affinity = Arc::new(affinity);+ route = route+ .with_processor(affinity.clone())+ .with_classifier(affinity);+ }+ let fallback = DefaultTarget::new(config.default_target);+ Ok(Self {+ route: route+ .with_classifier(inner.clone())+ .with_classifier(Arc::new(fallback)),+ inner,+ })+ }}#[async_trait]@@ -691,9 +916,10 @@ mod tests {use super::*;use switchyard_protocol::{- LlmClientError, Metadata, completion_text, text_request, text_response,+ LlmClientError, LlmRequest, Metadata, completion_text, text_request, text_response,};+ use crate::algorithms::util::llm_judge::Judge;use crate::core::algorithm::Algorithm;use switchyard_protocol::{Context, LlmResponse, Response, RoutedLlmClient};@@ -818,10 +1044,12 @@ mod tests {llm_client: Some(client.clone()),};Ok(Arc::new(LlmTaskClassifier::new(- target("judge"),- target("efficient"),- target("capable"),- test_config(TEST_THRESHOLD),+ LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("efficient"),+ capable_target: target("capable"),+ config: test_config(TEST_THRESHOLD),+ },)?))}@@ -893,15 +1121,15 @@ mod tests {semantic_name: name.to_string(),llm_client: Some(client.clone()),};- let router = Arc::new(LlmTaskClassifier::new(- target("judge"),- target("efficient"),- target("capable"),- TaskClassifierConfig {+ let router = Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("efficient"),+ capable_target: target("capable"),+ config: TaskClassifierConfig {max_output_tokens: 512,..test_config(TEST_THRESHOLD)},- )?);+ })?);router.run(Context::default(), classify_request()).await?;@@ -916,16 +1144,16 @@ mod tests {semantic_name: name.to_string(),llm_client: Some(client.clone()),};- let router = Arc::new(LlmTaskClassifier::new(- target("judge"),- target("efficient"),- target("capable"),- TaskClassifierConfig {+ let router = Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("efficient"),+ capable_target: target("capable"),+ config: TaskClassifierConfig {contract: ClassifierContractConfig::default().with_prompt("Custom capability rubric:\n{{RESPONSE_SCHEMA}}"),..test_config(TEST_THRESHOLD)},- )?);+ })?);router.run(Context::default(), classify_request()).await?;@@ -944,15 +1172,15 @@ mod tests {semantic_name: name.to_string(),llm_client: Some(client.clone()),};- let router = Arc::new(LlmTaskClassifier::new(- target("judge"),- target("efficient"),- target("capable"),- TaskClassifierConfig {+ let router = Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("efficient"),+ capable_target: target("capable"),+ config: TaskClassifierConfig {session_affinity: true,..test_config(TEST_THRESHOLD)},- )?);+ })?);router.clone()@@ -974,17 +1202,17 @@ mod tests {semantic_name: name.to_string(),llm_client: Some(client.clone()),};- let router = Arc::new(LlmTaskClassifier::new(- target("judge"),- target("efficient"),- target("capable"),- TaskClassifierConfig {+ let router = Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("efficient"),+ capable_target: target("capable"),+ config: TaskClassifierConfig {session_affinity: true,message_hash_fallback: true,recent_turn_window: None,..test_config(TEST_THRESHOLD)},- )?);+ })?);router.clone()@@ -1043,12 +1271,12 @@ mod tests {};for bad in [1.5, -0.1, f64::NAN, f64::INFINITY] {assert!(- LlmTaskClassifier::new(- target("judge"),- target("e"),- target("c"),- test_config(bad),- )+ LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("e"),+ capable_target: target("c"),+ config: test_config(bad),+ }).is_err(),"base threshold {bad} should be rejected");@@ -1076,11 +1304,23 @@ mod tests {},] {assert!(- LlmTaskClassifier::new(target("judge"), target("e"), target("c"), config).is_err()+ LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("e"),+ capable_target: target("c"),+ config,+ })+ .is_err());}- LlmTaskClassifier::new(target("judge"), target("e"), target("c"), test_config(0.0))?;- LlmTaskClassifier::new(target("judge"), target("e"), target("c"), test_config(1.0))?;+ for base_threshold in [0.0, 1.0] {+ LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("judge"),+ efficient_target: target("e"),+ capable_target: target("c"),+ config: test_config(base_threshold),+ })?;+ }Ok(())}@@ -1137,14 +1377,17 @@ mod tests {/// The text of each message a judge with `recent_turn_window` would be sent./// The no-window case is covered by `capability_judge_builds_a_structured_request`.+ fn capability_judge(recent_turn_window: Option<usize>) -> Result<CapabilityJudge> {+ Ok(StructuredJudge::new(+ TaskInput { recent_turn_window },+ LlmTaskClassifier::load_capability_contract(&ClassifierContractConfig::default())?,+ SerdeDecoder::new(),+ JudgeRuntimeConfig::new(DEFAULT_JUDGE_MAX_OUTPUT_TOKENS)?,+ ))+ }+fn judged_contents(recent_turn_window: usize) -> Result<Vec<String>> {- let judge = CapabilityJudge {- contract: LlmTaskClassifier::load_capability_contract(- &ClassifierContractConfig::default(),- )?,- max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,- recent_turn_window: Some(recent_turn_window),- };+ let judge = capability_judge(Some(recent_turn_window))?;let request = Request {llm_request: LlmRequest {messages: vec![@@ -1192,13 +1435,7 @@ mod tests {#[test]fn capability_judge_builds_a_structured_request() -> Result<()> {- let judge = CapabilityJudge {- contract: LlmTaskClassifier::load_capability_contract(- &ClassifierContractConfig::default(),- )?,- max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,- recent_turn_window: None,- };+ let judge = capability_judge(None)?;let request = Request {llm_request: LlmRequest {model: Some("inbound".to_string()),@@ -1235,7 +1472,7 @@ mod tests {assert!(!contents.contains(&"client instructions".to_string()));assert_eq!(judge_request.llm_request.output.response_format,- Some(judge.contract.response_format().clone())+ Some(judge.contract().response_format().clone()));assert_eq!(judge_request.llm_request.output.max_output_tokens,@@ -1283,11 +1520,14 @@ mod tests {LlmTaskClassifier::load_capability_contract(&ClassifierContractConfig::default())?;let schema = contract.response_format();let reply = schema_shaped_verdict(schema)?;- let judge = CapabilityJudge {+ let judge: CapabilityJudge = StructuredJudge::new(+ TaskInput {+ recent_turn_window: None,+ },contract,- max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,- recent_turn_window: None,- };+ SerdeDecoder::new(),+ JudgeRuntimeConfig::new(DEFAULT_JUDGE_MAX_OUTPUT_TOKENS)?,+ );let verdict = judge.parse(&text_response(None, reply))?;@@ -1378,15 +1618,18 @@ mod tests {semantic_name: name.to_string(),llm_client: Some(c),};- Ok(Arc::new(LlmTaskClassifier::new_with_escalation(- target("judge", judge_client),- target("efficient", client.clone()),- target("capable", client),- EscalationJudgeConfig {- confirmations: 1,- ..EscalationJudgeConfig::default()+ Ok(Arc::new(LlmTaskClassifier::new(+ LlmClassifierConfig::Escalation {+ judge_target: target("judge", judge_client),+ efficient_target: target("efficient", client.clone()),+ capable_target: target("capable", client),+ contract: ClassifierContractConfig::default(),+ config: EscalationJudgeConfig {+ confirmations: 1,+ ..EscalationJudgeConfig::default()+ },+ max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,},- DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,)?))}@@ -1416,18 +1659,18 @@ mod tests {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()+ let router = Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Escalation {+ judge_target: target("judge"),+ efficient_target: target("efficient"),+ capable_target: target("capable"),+ contract: ClassifierContractConfig::default().with_prompt("Custom trajectory rubric:\n{{RESPONSE_SCHEMA}}"),- EscalationJudgeConfig {+ config: EscalationJudgeConfig {confirmations: 1,..EscalationJudgeConfig::default()},- DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,- )?);+ max_output_tokens: DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,+ })?);router.run(Context::default(), classify_request()).await?;diff --git a/crates/libsy/src/algorithms/stage.rs b/crates/libsy/src/algorithms/stage.rsindex 9fade6a50..aa162d6ed 100644--- a/crates/libsy/src/algorithms/stage.rs+++ b/crates/libsy/src/algorithms/stage.rs@@ -18,7 +18,7 @@ use std::sync::Arc;use async_trait::async_trait;use super::fall_through::{DefaultTarget, FallThrough};-use super::llm_class::{LlmTaskClassifier, TaskClassifierConfig};+use super::llm_class::{LlmClassifierConfig, LlmTaskClassifier, TaskClassifierConfig};use super::util::prompts::{SystemPromptProcessor, TargetPrompts};use super::util::stage::{DecisionSource, HandoffNoteConfig, PickerMode, StageClassifier, StageTargets,@@ -197,12 +197,12 @@ fn build_route(// The capability judge takes its tiers in the same order the capability// route passes them: efficient first, capable second.router = router.with_classifier(Arc::new(SourceStamp {- inner: Arc::new(LlmTaskClassifier::new(- fallback.judge_target,- efficient,- capable,- fallback.config,- )?),+ inner: Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: fallback.judge_target,+ efficient_target: efficient,+ capable_target: capable,+ config: fallback.config,+ })?),source: DecisionSource::LlmClassifier,}));}diff --git a/crates/libsy/src/algorithms/util.rs b/crates/libsy/src/algorithms/util.rsindex 32f6f3efd..66b5ed982 100644--- a/crates/libsy/src/algorithms/util.rs+++ b/crates/libsy/src/algorithms/util.rs@@ -8,6 +8,7 @@ pub(crate) mod llm_judge;pub(crate) mod prompts;pub(crate) mod stage;pub mod subagent;+pub(crate) mod target_selector;pub(crate) mod tool_signals;/// Default completion budget for internal classifier and escalation judge calls.diff --git a/crates/libsy/src/algorithms/util/classifier_contract.rs b/crates/libsy/src/algorithms/util/classifier_contract.rsindex cb2a95a98..9855ac2c1 100644--- a/crates/libsy/src/algorithms/util/classifier_contract.rs+++ b/crates/libsy/src/algorithms/util/classifier_contract.rs@@ -3,8 +3,9 @@//! Prompt and structured-output contracts shared by LLM classifiers.+use jsonschema::Validator;use serde::Deserialize;-use serde_json::Value;+use serde_json::{Value, json};use crate::{LibsyError, Result};@@ -35,6 +36,7 @@ impl ClassifierContractConfig {pub(crate) struct ClassifierContract {system_prompt: String,response_format: Value,+ validator: Option<Validator>,}impl ClassifierContract {@@ -49,23 +51,56 @@ impl ClassifierContract {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+ Self::from_response_format(prompt_template, response_format, None)+ }++ /// Builds a provider response format around a user-supplied inner JSON Schema.+ pub(crate) fn from_inner_schema(prompt_template: &str, schema: Value) -> Result<Self> {+ if schema.get("json_schema").is_some() {+ return Err(LibsyError::AlgorithmError {+ message:+ "response_schema must be the inner JSON Schema, not a response_format wrapper"+ .to_string(),+ });+ }+ let validator = compile_schema(&schema)?;+ Self::from_response_format(+ prompt_template,+ json!({+ "type": "json_schema",+ "json_schema": {+ "name": "switchyard_classifier_response",+ "strict": true,+ "schema": schema,+ }+ }),+ Some(validator),+ )+ }++ fn from_response_format(+ prompt_template: &str,+ response_format: Value,+ validator: Option<Validator>,+ ) -> Result<Self> {+ if prompt_template.trim().is_empty() {+ return Err(LibsyError::AlgorithmError {+ message: "classifier prompt must not be empty".to_string(),+ });+ }+ let response_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| {+ })?+ .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}"),}@@ -74,6 +109,7 @@ impl ClassifierContract {Ok(Self {system_prompt: prompt_template.replace("{{RESPONSE_SCHEMA}}", &prompt_schema),response_format,+ validator,})}@@ -84,6 +120,37 @@ impl ClassifierContract {pub(crate) fn response_format(&self) -> &Value {&self.response_format}++ /// Validates a dynamic verdict when this contract carries a runtime schema validator.+ pub(crate) fn validate_verdict(&self, verdict: &Value) -> Result<()> {+ let Some(validator) = &self.validator else {+ return Ok(());+ };+ validator+ .validate(verdict)+ .map_err(|error| LibsyError::AlgorithmError {+ message: format!("classifier verdict did not match response_schema: {error}"),+ })+ }+}++fn compile_schema(schema: &Value) -> Result<Validator> {+ if !schema.is_object() {+ return Err(algorithm_error("response_schema must be a JSON object"));+ }+ jsonschema::meta::validate(schema).map_err(|error| {+ algorithm_error(format!(+ "response_schema is not a valid JSON Schema: {error}"+ ))+ })?;+ jsonschema::validator_for(schema)+ .map_err(|error| algorithm_error(format!("response_schema could not be compiled: {error}")))+}++fn algorithm_error(message: impl Into<String>) -> LibsyError {+ LibsyError::AlgorithmError {+ message: message.into(),+ }}#[cfg(test)]@@ -142,4 +209,63 @@ mod tests {assert!(error.to_string().contains("prompt must not be empty"));}++ #[test]+ fn a_custom_contract_wraps_and_validates_its_inner_schema() -> Result<()> {+ let contract = ClassifierContract::from_inner_schema(+ "Choose a target:\n{{RESPONSE_SCHEMA}}",+ json!({+ "type": "object",+ "$defs": {+ "decision": {+ "type": "object",+ "properties": {+ "target": {"type": "string", "enum": ["sonnet", "opus"]}+ },+ "required": ["target"],+ "additionalProperties": false+ }+ },+ "properties": {+ "decision": {"$ref": "#/$defs/decision"}+ },+ "required": ["decision"],+ "additionalProperties": false+ }),+ )?;++ assert_eq!(+ contract+ .response_format()+ .pointer("/json_schema/name")+ .and_then(Value::as_str),+ Some("switchyard_classifier_response")+ );+ assert_eq!(+ contract+ .response_format()+ .pointer("/json_schema/strict")+ .and_then(Value::as_bool),+ Some(true)+ );+ assert!(contract.system_prompt().contains("\"target\""));+ contract.validate_verdict(&json!({"decision": {"target": "sonnet"}}))?;+ assert!(+ contract+ .validate_verdict(&json!({"decision": {"target": "unknown"}}))+ .is_err()+ );+ Ok(())+ }++ #[test]+ fn a_provider_wrapper_is_rejected_as_an_inner_schema() {+ let error = ClassifierContract::from_inner_schema(+ "classify",+ json!({"json_schema": {"schema": {"type": "object"}}}),+ )+ .expect_err("provider wrapper should be rejected");++ assert!(error.to_string().contains("inner JSON Schema"));+ }}diff --git a/crates/libsy/src/algorithms/util/escalation.rs b/crates/libsy/src/algorithms/util/escalation.rsindex d71bfd260..49cd53085 100644--- a/crates/libsy/src/algorithms/util/escalation.rs+++ b/crates/libsy/src/algorithms/util/escalation.rs@@ -8,10 +8,13 @@//! lives with the assembled algorithm in [`crate::algorithms::escalation`].use serde::Deserialize;-use switchyard_protocol::{ContentBlock, LlmRequest, Message, OutputParams, Role};+use switchyard_protocol::{ContentBlock, Message, Role};use super::classifier_contract::{ClassifierContract, ClassifierContractConfig};-use super::llm_judge::{Judge, JudgeClassifier, JudgePolicy};+use super::llm_judge::{+ ClassifierInput, JudgeClassifier, JudgePolicy, JudgeRuntimeConfig, SerdeDecoder,+ StructuredJudge,+};use crate::core::algorithm::LlmTarget;use crate::core::classifier::{Classification, Score};use crate::core::state::State;@@ -93,40 +96,22 @@ pub(crate) struct EscalationVerdict {escalate: bool,}-/// Builds the judge request from the conversation so far.-pub(crate) struct EscalationJudge {- contract: ClassifierContract,- max_output_tokens: u64,+/// Builds the condensed trajectory presented to the escalation judge.+pub(crate) struct EscalationInput {config: EscalationJudgeConfig,}-impl Judge for EscalationJudge {- type Verdict = EscalationVerdict;-- /// Renders the rubric as the system message and the condensed trajectory as the user- /// message. `state` is unused: the judge reads only the live request.- fn build_request(&self, _state: &State, request: &Request) -> Request {+impl ClassifierInput for EscalationInput {+ fn build_messages(&self, _state: &State, request: &Request) -> Vec<Message> {let messages = &request.llm_request.messages;let summary = summarize_for_judge(messages, conversation_turn(request), &self.config);- Request {- llm_request: LlmRequest {- model: request.llm_request.model.clone(),- messages: vec![- Message::text(Role::System, self.contract.system_prompt().to_string()),- Message::text(Role::User, summary),- ],- output: OutputParams {- response_format: Some(self.contract.response_format().clone()),- max_output_tokens: Some(self.max_output_tokens),- },- ..LlmRequest::default()- },- raw_request: None,- metadata: request.metadata.clone(),- }+ vec![Message::text(Role::User, summary)]}}+/// Structured trajectory judge with a typed escalation verdict.+pub(crate) type EscalationJudge = StructuredJudge<EscalationInput, SerdeDecoder<EscalationVerdict>>;+/// Maps the judge's verdict to a classification. A verdict names the tier to serve — capable/// on escalate, efficient on decline — so the caller reads it straight off the winning score./// [`Classification::Ambiguous`] carries the unavailable case, which names no tier: both a@@ -168,19 +153,15 @@ pub(crate) fn build_judge(max_output_tokens: u64,) -> Result<JudgeClassifier<EscalationJudge, EscalationPolicy>> {config.validate()?;- if max_output_tokens == 0 {- return Err(LibsyError::AlgorithmError {- message: "max_output_tokens must be at least 1".to_string(),- });- }let contract =ClassifierContract::from_config(contract_config, PROMPT_TEMPLATE, SCHEMA_TEMPLATE)?;Ok(JudgeClassifier::new(- EscalationJudge {+ StructuredJudge::new(+ EscalationInput { config },contract,- max_output_tokens,- config,- },+ SerdeDecoder::new(),+ JudgeRuntimeConfig::new(max_output_tokens)?,+ ),judge_target,EscalationPolicy { capable, efficient },))@@ -338,7 +319,7 @@ fn role_label(role: Role) -> &'static str {/// Shared with the assembled router's tests, which drive the same conversation shape.#[cfg(test)]pub(crate) fn request_at_turn(session_id: Option<&str>, turn: usize) -> Request {- use switchyard_protocol::Metadata;+ use switchyard_protocol::{LlmRequest, Metadata};let mut messages = vec![Message::text(Role::User, "What is 2+2?")];for attempt in 1..turn {@@ -365,18 +346,26 @@ mod tests {use switchyard_protocol::{ContentBlock, Message, Role, ToolCall, ToolResult};use super::*;+ use crate::algorithms::util::llm_judge::Judge;- #[test]- fn judge_request_is_rubric_plus_summary_under_a_completion_cap() -> Result<()> {- let judge = EscalationJudge {- contract: ClassifierContract::from_config(+ fn escalation_judge(max_output_tokens: u64) -> Result<EscalationJudge> {+ Ok(StructuredJudge::new(+ EscalationInput {+ config: EscalationJudgeConfig::default(),+ },+ ClassifierContract::from_config(&ClassifierContractConfig::default(),PROMPT_TEMPLATE,SCHEMA_TEMPLATE,)?,- max_output_tokens: super::super::DEFAULT_JUDGE_MAX_OUTPUT_TOKENS,- config: EscalationJudgeConfig::default(),- };+ SerdeDecoder::new(),+ JudgeRuntimeConfig::new(max_output_tokens)?,+ ))+ }++ #[test]+ fn judge_request_is_rubric_plus_summary_under_a_completion_cap() -> Result<()> {+ let judge = escalation_judge(super::super::DEFAULT_JUDGE_MAX_OUTPUT_TOKENS)?;// As the classifier calls it: the turn's reply is already on the transcript.let mut judged = request_at_turn(None, 4);@@ -406,15 +395,7 @@ mod tests {#[test]fn judge_request_uses_the_configured_completion_cap() -> Result<()> {- let judge = EscalationJudge {- contract: ClassifierContract::from_config(- &ClassifierContractConfig::default(),- PROMPT_TEMPLATE,- SCHEMA_TEMPLATE,- )?,- max_output_tokens: 512,- config: EscalationJudgeConfig::default(),- };+ let judge = escalation_judge(512)?;let built = judge.build_request(&State::default(), &request_at_turn(None, 1));diff --git a/crates/libsy/src/algorithms/util/llm_judge.rs b/crates/libsy/src/algorithms/util/llm_judge.rsindex 1e6edde8b..ce73da7ee 100644--- a/crates/libsy/src/algorithms/util/llm_judge.rs+++ b/crates/libsy/src/algorithms/util/llm_judge.rs@@ -7,18 +7,168 @@//! [`JudgeClassifier`] owns the judge model call and hands its verdict to a policy that chooses//! the route.+use std::marker::PhantomData;use std::sync::Arc;use async_trait::async_trait;use serde::de::DeserializeOwned;-use switchyard_protocol::{AggLlmResponse, completion_text};+use serde_json::Value;+use switchyard_protocol::{+ AggLlmResponse, LlmRequest, Message, OutputParams, Role, completion_text,+};+use super::classifier_contract::ClassifierContract;use crate::core::algorithm::{Driver, LlmTarget};use crate::core::classifier::{Classification, Classifier};use crate::core::state::State;use crate::{LibsyError, Result};use switchyard_protocol::{Context, Decision, Request, Response};+/// Builds the classifier-specific message view presented to a structured judge.+pub(crate) trait ClassifierInput: Send + Sync {+ fn build_messages(&self, state: &State, request: &Request) -> Vec<Message>;+}++/// Converts one structured model response into the verdict type consumed by a policy.+pub(crate) trait VerdictDecoder: Send + Sync {+ type Verdict: DeserializeOwned + Send + Sync;++ fn decode(+ &self,+ response: &AggLlmResponse,+ contract: &ClassifierContract,+ ) -> Result<Self::Verdict>;+}++/// Deserializes a structured response directly into a typed verdict.+pub(crate) struct SerdeDecoder<V> {+ verdict: PhantomData<fn() -> V>,+}++impl<V> SerdeDecoder<V> {+ pub(crate) const fn new() -> Self {+ Self {+ verdict: PhantomData,+ }+ }+}++impl<V> VerdictDecoder for SerdeDecoder<V>+where+ V: DeserializeOwned + Send + Sync,+{+ type Verdict = V;++ fn decode(+ &self,+ response: &AggLlmResponse,+ _contract: &ClassifierContract,+ ) -> Result<Self::Verdict> {+ parse_json_verdict(response)+ }+}++/// Parses a JSON value and enforces the custom contract's compiled response schema.+pub(crate) struct JsonSchemaDecoder;++impl JsonSchemaDecoder {+ pub(crate) const fn new() -> Self {+ Self+ }+}++impl VerdictDecoder for JsonSchemaDecoder {+ type Verdict = Value;++ fn decode(+ &self,+ response: &AggLlmResponse,+ contract: &ClassifierContract,+ ) -> Result<Self::Verdict> {+ let verdict = parse_json_verdict(response)?;+ contract.validate_verdict(&verdict)?;+ Ok(verdict)+ }+}++/// Runtime limits shared by structured classifier judges.+pub(crate) struct JudgeRuntimeConfig {+ max_output_tokens: u64,+}++impl JudgeRuntimeConfig {+ pub(crate) fn new(max_output_tokens: u64) -> Result<Self> {+ if max_output_tokens == 0 {+ return Err(LibsyError::AlgorithmError {+ message: "max_output_tokens must be at least 1".to_string(),+ });+ }+ Ok(Self { max_output_tokens })+ }+}++/// Reusable structured judge assembled from an input view, contract, and verdict decoder.+pub(crate) struct StructuredJudge<I, D> {+ input: I,+ contract: ClassifierContract,+ decoder: D,+ runtime: JudgeRuntimeConfig,+}++impl<I, D> StructuredJudge<I, D> {+ pub(crate) fn new(+ input: I,+ contract: ClassifierContract,+ decoder: D,+ runtime: JudgeRuntimeConfig,+ ) -> Self {+ Self {+ input,+ contract,+ decoder,+ runtime,+ }+ }++ #[cfg(test)]+ pub(crate) fn contract(&self) -> &ClassifierContract {+ &self.contract+ }+}++impl<I, D> Judge for StructuredJudge<I, D>+where+ I: ClassifierInput,+ D: VerdictDecoder,+{+ type Verdict = D::Verdict;++ fn build_request(&self, state: &State, request: &Request) -> Request {+ let mut messages = self.input.build_messages(state, request);+ messages.insert(+ 0,+ 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.runtime.max_output_tokens),+ response_format: Some(self.contract.response_format().clone()),+ },+ ..LlmRequest::default()+ },+ raw_request: None,+ metadata: request.metadata.clone(),+ }+ }++ fn parse(&self, response: &AggLlmResponse) -> Result<Self::Verdict> {+ self.decoder.decode(response, &self.contract)+ }+}+/// Builds and parses requests for one algorithm-specific LLM judge.pub trait Judge: Send + Sync {type Verdict: DeserializeOwned + Send + Sync;diff --git a/crates/libsy/src/algorithms/util/target_selector.rs b/crates/libsy/src/algorithms/util/target_selector.rsnew file mode 100644index 000000000..da6c46597--- /dev/null+++ b/crates/libsy/src/algorithms/util/target_selector.rs@@ -0,0 +1,113 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Deterministic target selection from a validated JSON classifier verdict.++use std::collections::BTreeMap;++use jsonptr::PointerBuf;+use serde_json::Value;++use super::llm_judge::JudgePolicy;+use crate::core::classifier::{Classification, Score};+use crate::{LibsyError, Result};++/// Maps one string field in a validated verdict to a configured routing target.+pub(crate) struct TargetSelectorPolicy {+ selector: PointerBuf,+ targets: BTreeMap<String, String>,+}++impl TargetSelectorPolicy {+ /// Parses a JSON Pointer used to read validated verdicts.+ pub(crate) fn new(+ selector: impl Into<String>,+ targets: BTreeMap<String, String>,+ ) -> Result<Self> {+ let selector =+ PointerBuf::parse(selector.into()).map_err(|error| LibsyError::AlgorithmError {+ message: format!("policy selector is not a valid JSON Pointer: {error}"),+ })?;+ if selector.is_root() {+ return Err(LibsyError::AlgorithmError {+ message: "policy selector must identify a response field".to_string(),+ });+ }+ Ok(Self { selector, targets })+ }+}++impl JudgePolicy for TargetSelectorPolicy {+ type Verdict = Value;++ fn to_classification(&self, verdict: Option<&Self::Verdict>) -> Classification {+ let target = verdict+ .and_then(|verdict| self.selector.resolve(verdict).ok())+ .and_then(Value::as_str)+ .and_then(|label| self.targets.get(label));+ match target {+ Some(target) => Classification::Scores(vec![Score {+ target: target.clone(),+ confidence: 1.0,+ }]),+ None => Classification::Ambiguous(vec![]),+ }+ }+}++#[cfg(test)]+mod tests {+ use serde_json::json;++ use super::*;+ use crate::Result;++ #[test]+ fn a_verdict_selects_its_mapped_target() -> Result<()> {+ let policy = TargetSelectorPolicy::new(+ "/decision/target",+ BTreeMap::from([+ ("opus".to_string(), "model/opus".to_string()),+ ("sonnet".to_string(), "model/sonnet".to_string()),+ ]),+ )?;+ let classification = policy.to_classification(Some(&json!({+ "decision": {"target": "sonnet"}+ })));++ assert_eq!(+ classification.argmax(false)?.map(|score| score.target),+ Some("model/sonnet".to_string())+ );+ Ok(())+ }++ #[test]+ fn a_missing_or_unknown_target_abstains() -> Result<()> {+ let policy = TargetSelectorPolicy::new(+ "/target",+ BTreeMap::from([("sonnet".to_string(), "model/sonnet".to_string())]),+ )?;++ assert_eq!(+ policy+ .to_classification(Some(&json!({"target": "unknown"})))+ .argmax(false)?,+ None+ );+ assert_eq!(+ policy+ .to_classification(Some(&json!({"reason": "missing"})))+ .argmax(false)?,+ None+ );+ Ok(())+ }++ #[test]+ fn an_invalid_json_pointer_is_rejected() {+ let result = TargetSelectorPolicy::new("/target~2name", BTreeMap::new());+ assert!(matches!(result, Err(LibsyError::AlgorithmError { message })+ if message.contains("valid JSON Pointer")));+ }+}diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rsindex b154d0421..37f6cb22f 100644--- a/crates/libsy/src/lib.rs+++ b/crates/libsy/src/lib.rs@@ -17,7 +17,10 @@ mod error;pub use error::{DriverError, LibsyError, Result};mod algorithms;-pub use algorithms::llm_class::{LlmTaskClassifier, TaskClassifierConfig};+pub use algorithms::llm_class::{+ CustomClassifierConfig, CustomClassifierPolicy, LlmClassifierConfig, LlmTaskClassifier,+ TaskClassifierConfig,+};pub use algorithms::noop::{Noop, NoopDecision};pub use algorithms::passthrough::{Passthrough, PassthroughDecision};pub use algorithms::rand::{Random, RandomClassifier, RandomDecision};diff --git a/crates/libsy/tests/observability.rs b/crates/libsy/tests/observability.rsindex ca361ff63..ebea9d7af 100644--- a/crates/libsy/tests/observability.rs+++ b/crates/libsy/tests/observability.rs@@ -33,8 +33,8 @@ use tracing_subscriber::layer::{Context as LayerContext, SubscriberExt};use tracing_subscriber::registry::LookupSpan;use switchyard_libsy::{- Algorithm, Driver, LibsyError, LlmTarget, LlmTargetSet, LlmTaskClassifier, Step,- TaskClassifierConfig,+ Algorithm, Driver, LibsyError, LlmClassifierConfig, LlmTarget, LlmTargetSet, LlmTaskClassifier,+ Step, TaskClassifierConfig,};use switchyard_protocol::{Context, Decision, LlmResponse, Metadata, Request, Response, RoutedLlmClient, Usage,@@ -1040,15 +1040,15 @@ async fn classifier_metrics_count_only_the_final_routed_call() -> switchyard_liblet targets = LlmTargetSet::new(vec![target("weak"), target("strong")]);let weak = targets.get_target("weak")?;let strong = targets.get_target("strong")?;- let router = Arc::new(LlmTaskClassifier::new(- target("classifier"),- weak,- strong,- TaskClassifierConfig {+ let router = Arc::new(LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: target("classifier"),+ efficient_target: weak,+ capable_target: strong,+ config: TaskClassifierConfig {base_threshold: 0.5,..TaskClassifierConfig::default()},- )?);+ })?);let (trace, _response) = router.run(diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex bee4e7dcd..8418d582e 100644--- a/crates/switchyard-py/src/libsy_bindings.rs+++ b/crates/switchyard-py/src/libsy_bindings.rs@@ -11,8 +11,8 @@ use pyo3::prelude::*;use serde_json::{Value, json};use switchyard_libsy::{Algorithm, ClassifierContractConfig, HandoffNoteConfig, LibsyError as RustLibsyError,- LlmFallback, LlmTarget, LlmTargetSet, LlmTaskClassifier, Noop, PickerMode, Random, StageRouter,- StageRouterConfig, TaskClassifierConfig,+ LlmClassifierConfig, LlmFallback, LlmTarget, LlmTargetSet, LlmTaskClassifier, Noop, PickerMode,+ Random, StageRouter, StageRouterConfig, TaskClassifierConfig,};use switchyard_protocol::{AggLlmResponse, Context, Decision, LlmClientError, LlmResponse, Metadata, Request, Response,@@ -301,12 +301,12 @@ fn llm_task_classifier_algorithm(capable_target: Py<PyLlmTarget>,config: Py<PyTaskClassifierConfig>,) -> PyResult<PyAlgorithm> {- let algorithm = LlmTaskClassifier::new(- judge_target.bind(py).try_borrow()?.clone_core(py),- efficient_target.bind(py).try_borrow()?.clone_core(py),- capable_target.bind(py).try_borrow()?.clone_core(py),- config.bind(py).try_borrow()?.clone_core(),- )+ let algorithm = LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: judge_target.bind(py).try_borrow()?.clone_core(py),+ efficient_target: efficient_target.bind(py).try_borrow()?.clone_core(py),+ capable_target: capable_target.bind(py).try_borrow()?.clone_core(py),+ config: config.bind(py).try_borrow()?.clone_core(),+ }).map_err(|error| PyValueError::new_err(error.to_string()))?;Ok(PyAlgorithm::new(Arc::new(algorithm)))}diff --git a/crates/switchyard-server/README.md b/crates/switchyard-server/README.mdindex e92e47f4c..4aa12a37c 100644--- a/crates/switchyard-server/README.md+++ b/crates/switchyard-server/README.md@@ -33,6 +33,7 @@ seed = 42[routes.classified]id = "switchyard/classified"type = "llm_classifier"+mode = "capability"classifier_target = "model_a"strong_target = "model_a"weak_target = "model_b"diff --git a/crates/switchyard-server/src/config.rs b/crates/switchyard-server/src/config.rsindex 73c04ebc6..ce420cdcc 100644--- a/crates/switchyard-server/src/config.rs+++ b/crates/switchyard-server/src/config.rs@@ -9,8 +9,9 @@ use std::path::Path;use std::sync::Arc;use libsy::{- Algorithm, ClassifierContractConfig, EscalationJudgeConfig, HandoffNoteConfig, LlmFallback,- LlmTarget, LlmTargetSet, LlmTaskClassifier, Noop, Passthrough, PickerMode, Random, StageRouter,+ Algorithm, ClassifierContractConfig, CustomClassifierConfig, CustomClassifierPolicy,+ EscalationJudgeConfig, HandoffNoteConfig, LlmClassifierConfig, LlmFallback, LlmTarget,+ LlmTargetSet, LlmTaskClassifier, Noop, Passthrough, PickerMode, Random, StageRouter,StageRouterConfig, TargetPrompts, TaskClassifierConfig,};use serde::Deserialize;@@ -171,6 +172,71 @@ enum ClientFormat {AnthropicMessages,}+#[derive(Clone, Debug, Deserialize)]+#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]+enum ClassifierPolicyConfig {+ TargetSelector { selector: String },+}++#[derive(Clone, Copy, Debug, Deserialize)]+#[serde(rename_all = "snake_case")]+enum ClassifierMode {+ Capability,+ Escalation,+ Custom,+}++impl ClassifierPolicyConfig {+ fn into_libsy(self) -> CustomClassifierPolicy {+ match self {+ Self::TargetSelector { selector } => CustomClassifierPolicy::target_selector(selector),+ }+ }+}++#[derive(Debug)]+enum LlmClassifierModeConfig {+ Capability(CapabilityClassifierRouteConfig),+ Escalation(EscalationClassifierRouteConfig),+ Custom(CustomClassifierRouteConfig),+}++#[derive(Debug)]+struct CapabilityClassifierRouteConfig {+ strong_target: String,+ weak_target: String,+ base_threshold: f64,+ min_confidence: f64,+ capability_elevated_floor: Option<f64>,+ session_affinity: bool,+ message_hash_fallback: bool,+ recent_turn_window: Option<usize>,+ prompt: Option<String>,+ max_output_tokens: u64,+}++#[derive(Debug)]+struct EscalationClassifierRouteConfig {+ strong_target: String,+ weak_target: String,+ prompt: Option<String>,+ max_output_tokens: u64,+ judge: EscalationJudgeConfig,+}++#[derive(Debug)]+struct CustomClassifierRouteConfig {+ targets: Vec<String>,+ default_target: String,+ prompt: String,+ response_schema: String,+ policy: ClassifierPolicyConfig,+ session_affinity: bool,+ message_hash_fallback: bool,+ recent_turn_window: Option<usize>,+ max_output_tokens: u64,+}+#[derive(Debug, Deserialize)]#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]enum RouteConfig {@@ -190,11 +256,16 @@ enum RouteConfig {LlmClassifier {id: String,classifier_target: String,- strong_target: String,- weak_target: String,- base_threshold: f64,#[serde(default)]- min_confidence: f64,+ mode: Option<ClassifierMode>,+ #[serde(default)]+ strong_target: Option<String>,+ #[serde(default)]+ weak_target: Option<String>,+ #[serde(default)]+ base_threshold: Option<f64>,+ #[serde(default)]+ min_confidence: Option<f64>,#[serde(default)]capability_elevated_floor: Option<f64>,#[serde(default)]@@ -207,14 +278,16 @@ enum RouteConfig {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- /// the weak tier and judged, and the session latches to the strong tier once- /// `confirmations` consecutive escalate verdicts accumulate. Absent, the classifier- /// picks a tier before the turn's call, as usual.#[serde(default)]escalation: Option<EscalationJudgeConfig>,+ #[serde(default)]+ targets: Option<Vec<String>>,+ #[serde(default)]+ default_target: Option<String>,+ #[serde(default)]+ response_schema: Option<String>,+ #[serde(default)]+ policy: Option<ClassifierPolicyConfig>,},StageRouter {id: String,@@ -289,6 +362,194 @@ impl RouteConfig {| StageRouter { id, .. } => id,}}++ fn classifier_mode(&self, route_name: &str) -> ServerResult<LlmClassifierModeConfig> {+ let Self::LlmClassifier {+ mode,+ strong_target,+ weak_target,+ base_threshold,+ min_confidence,+ capability_elevated_floor,+ session_affinity,+ message_hash_fallback,+ recent_turn_window,+ prompt,+ max_output_tokens,+ escalation,+ targets,+ default_target,+ response_schema,+ policy,+ ..+ } = self+ else {+ return Err(ServerError::new("route is not an llm_classifier"));+ };++ let selected_mode = match (mode, escalation.is_some()) {+ (Some(mode), _) => *mode,+ (None, true) => ClassifierMode::Escalation,+ (None, false) => ClassifierMode::Capability,+ };++ match selected_mode {+ ClassifierMode::Capability => {+ if escalation.is_some() {+ return Err(classifier_field_error(+ route_name,+ "escalation",+ "capability",+ ));+ }+ reject_custom_fields(+ route_name,+ "capability",+ targets,+ default_target,+ response_schema,+ policy,+ )?;+ Ok(LlmClassifierModeConfig::Capability(+ CapabilityClassifierRouteConfig {+ strong_target: required_classifier_field(+ route_name,+ "strong_target",+ strong_target,+ )?,+ weak_target: required_classifier_field(+ route_name,+ "weak_target",+ weak_target,+ )?,+ base_threshold: required_classifier_field(+ route_name,+ "base_threshold",+ base_threshold,+ )?,+ min_confidence: min_confidence.unwrap_or_default(),+ capability_elevated_floor: *capability_elevated_floor,+ session_affinity: *session_affinity,+ message_hash_fallback: *message_hash_fallback,+ recent_turn_window: *recent_turn_window,+ prompt: prompt.clone(),+ max_output_tokens: *max_output_tokens,+ },+ ))+ }+ ClassifierMode::Escalation => {+ reject_custom_fields(+ route_name,+ "escalation",+ targets,+ default_target,+ response_schema,+ policy,+ )?;+ if mode.is_some()+ && (base_threshold.is_some()+ || min_confidence.is_some()+ || capability_elevated_floor.is_some()+ || *session_affinity+ || *message_hash_fallback+ || recent_turn_window.is_some())+ {+ return Err(ServerError::new(format!(+ "llm_classifier route {route_name} mode escalation cannot use capability routing settings"+ )));+ }+ Ok(LlmClassifierModeConfig::Escalation(+ EscalationClassifierRouteConfig {+ strong_target: required_classifier_field(+ route_name,+ "strong_target",+ strong_target,+ )?,+ weak_target: required_classifier_field(+ route_name,+ "weak_target",+ weak_target,+ )?,+ prompt: prompt.clone(),+ max_output_tokens: *max_output_tokens,+ judge: required_classifier_field(route_name, "escalation", escalation)?,+ },+ ))+ }+ ClassifierMode::Custom => {+ if strong_target.is_some()+ || weak_target.is_some()+ || base_threshold.is_some()+ || min_confidence.is_some()+ || capability_elevated_floor.is_some()+ || escalation.is_some()+ {+ return Err(ServerError::new(format!(+ "llm_classifier route {route_name} mode custom cannot use capability or escalation fields"+ )));+ }+ Ok(LlmClassifierModeConfig::Custom(+ CustomClassifierRouteConfig {+ targets: required_classifier_field(route_name, "targets", targets)?,+ default_target: required_classifier_field(+ route_name,+ "default_target",+ default_target,+ )?,+ prompt: required_classifier_field(route_name, "prompt", prompt)?,+ response_schema: required_classifier_field(+ route_name,+ "response_schema",+ response_schema,+ )?,+ policy: required_classifier_field(route_name, "policy", policy)?,+ session_affinity: *session_affinity,+ message_hash_fallback: *message_hash_fallback,+ recent_turn_window: *recent_turn_window,+ max_output_tokens: *max_output_tokens,+ },+ ))+ }+ }+ }+}++fn reject_custom_fields(+ route_name: &str,+ mode: &str,+ targets: &Option<Vec<String>>,+ default_target: &Option<String>,+ response_schema: &Option<String>,+ policy: &Option<ClassifierPolicyConfig>,+) -> ServerResult<()> {+ if targets.is_some()+ || default_target.is_some()+ || response_schema.is_some()+ || policy.is_some()+ {+ return Err(ServerError::new(format!(+ "llm_classifier route {route_name} mode {mode} cannot use custom classifier fields"+ )));+ }+ Ok(())+}++fn classifier_field_error(route_name: &str, field: &str, mode: &str) -> ServerError {+ ServerError::new(format!(+ "llm_classifier route {route_name} mode {mode} cannot use {field}"+ ))+}++fn required_classifier_field<T: Clone>(+ route_name: &str,+ field: &str,+ value: &Option<T>,+) -> ServerResult<T> {+ value.clone().ok_or_else(|| {+ ServerError::new(format!(+ "llm_classifier route {route_name} requires {field}"+ ))+ })}fn build_backend(@@ -371,46 +632,75 @@ fn build_algorithm(Ok(Arc::new(Passthrough::new(target)))}RouteConfig::LlmClassifier {- classifier_target,- strong_target,- weak_target,- base_threshold,- min_confidence,- capability_elevated_floor,- session_affinity,- message_hash_fallback,- recent_turn_window,- prompt,- max_output_tokens,- escalation,- ..+ classifier_target, ..} => {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_contract(- classifier,- weak,- strong,- classifier_config.contract,- judge_config.clone(),- classifier_config.max_output_tokens,- ),- None => LlmTaskClassifier::new(classifier, weak, strong, classifier_config),+ let mode = config.classifier_mode(route_name)?;+ let algorithm = match mode {+ LlmClassifierModeConfig::Capability(config) => {+ let strong = resolve_target(route_name, &config.strong_target, targets)?;+ 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,+ session_affinity: config.session_affinity,+ message_hash_fallback: config.message_hash_fallback,+ recent_turn_window: config.recent_turn_window,+ contract: classifier_contract(config.prompt.as_deref()),+ max_output_tokens: config.max_output_tokens,+ };+ LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ judge_target: classifier,+ efficient_target: weak,+ capable_target: strong,+ config: classifier_config,+ })+ }+ LlmClassifierModeConfig::Escalation(config) => {+ let strong = resolve_target(route_name, &config.strong_target, targets)?;+ let weak = resolve_target(route_name, &config.weak_target, targets)?;+ LlmTaskClassifier::new(LlmClassifierConfig::Escalation {+ judge_target: classifier,+ efficient_target: weak,+ capable_target: strong,+ contract: classifier_contract(config.prompt.as_deref()),+ config: config.judge,+ max_output_tokens: config.max_output_tokens,+ })+ }+ LlmClassifierModeConfig::Custom(config) => {+ let resolved_targets = config+ .targets+ .iter()+ .map(|name| {+ resolve_target(route_name, name, targets)+ .map(|target| (name.clone(), target))+ })+ .collect::<ServerResult<Vec<_>>>()?;+ let response_schema = serde_json::from_str(&config.response_schema).map_err(+ |error| {+ ServerError::new(format!(+ "llm_classifier route {route_name}: response_schema is invalid JSON: {error}"+ ))+ },+ )?;+ let mut classifier_config = CustomClassifierConfig::new(+ config.prompt,+ response_schema,+ config.policy.into_libsy(),+ );+ classifier_config.session_affinity = config.session_affinity;+ classifier_config.message_hash_fallback = config.message_hash_fallback;+ classifier_config.recent_turn_window = config.recent_turn_window;+ classifier_config.max_output_tokens = config.max_output_tokens;+ LlmTaskClassifier::new(LlmClassifierConfig::Custom {+ judge_target: classifier,+ targets: resolved_targets,+ default_target: config.default_target,+ config: classifier_config,+ })+ }}.map_err(|error| {ServerError::new(format!("llm_classifier route {route_name}: {error}"))@@ -658,6 +948,19 @@ target = "weak"Ok(())}+ #[test]+ fn mode_custom_rejects_capability_fields() {+ let mixed = VALID_CONFIG.replace(+ "base_threshold = 0.5",+ "mode = \"custom\"\nbase_threshold = 0.5",+ );++ assert!(+ error_message(&mixed)+ .contains("mode custom cannot use capability or escalation fields")+ );+ }+#[test]fn rejects_unknown_fields_and_algorithm_types() {let unknown_field =diff --git a/crates/switchyard-server/tests/server.rs b/crates/switchyard-server/tests/server.rsindex 86f96f053..406110db9 100644--- a/crates/switchyard-server/tests/server.rs+++ b/crates/switchyard-server/tests/server.rs@@ -114,7 +114,23 @@ async fn upstream_chat(return Sse::new(stream).into_response();}- let content = if model == "model/classifier"+ let custom_target_schema = body+ .pointer("/response_format/json_schema/schema/properties/decision/properties/target")+ .is_some();+ let requests_invalid_verdict = body["messages"].as_array().is_some_and(|messages| {+ messages.iter().any(|message| {+ message["content"]+ .as_str()+ .is_some_and(|content| content.contains("invalid verdict"))+ })+ });+ let content = if model == "model/classifier" && custom_target_schema {+ if requests_invalid_verdict {+ r#"{"decision":{"target":"unknown"}}"#+ } else {+ r#"{"decision":{"target":"premium"}}"#+ }+ } else if model == "model/classifier"&& body.pointer("/response_format/json_schema/schema/properties/escalate").is_some()@@ -732,6 +748,120 @@ base_threshold = 0.5Ok(())}+#[tokio::test]+async fn custom_classifier_routes_four_targets_and_falls_back_on_an_invalid_verdict() -> 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.middle]+id = "model/middle"+llm_client = "upstream"++[targets.premium]+id = "model/premium"+llm_client = "upstream"++[targets.weak]+id = "model/weak"+llm_client = "upstream"++[routes.custom]+id = "switchyard/custom"+type = "llm_classifier"+mode = "custom"+classifier_target = "classifier"+targets = ["weak", "middle", "strong", "premium"]+default_target = "strong"+prompt = "CUSTOM MULTI TARGET\n{{{{RESPONSE_SCHEMA}}}}"+response_schema = '''+{{+ "type": "object",+ "properties": {{+ "decision": {{+ "type": "object",+ "properties": {{+ "target": {{"type": "string", "enum": ["weak", "middle", "strong", "premium"]}}+ }},+ "required": ["target"],+ "additionalProperties": false+ }}+ }},+ "required": ["decision"],+ "additionalProperties": false+}}+'''++[routes.custom.policy]+type = "target_selector"+selector = "/decision/target"+"#,+ base_url = upstream.base_url+ ))?;+ let app = build_switchyard_router(state);++ for (task, selected) in [+ ("route this task", "model/premium"),+ ("return an invalid verdict", "model/strong"),+ ] {+ let response = send(+ &app,+ "POST",+ "/v1/chat/completions",+ Some(json!({+ "model": "switchyard/custom",+ "messages": [{"role": "user", "content": task}]+ })),+ )+ .await?;+ assert_eq!(response.status, StatusCode::OK);+ assert_eq!(+ response+ .headers+ .get("x-model-router-selected-model")+ .and_then(|value| value.to_str().ok()),+ Some(selected)+ );+ }++ let calls = upstream.calls.lock().await;+ let judge_call = calls+ .iter()+ .find(|call| call["model"] == "model/classifier")+ .ok_or("custom classifier target was not called")?;+ 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!(judge_call["response_format"]["type"], "json_schema");+ assert_eq!(+ judge_call["response_format"]["json_schema"]["name"],+ "switchyard_classifier_response"+ );+ assert_eq!(judge_call["response_format"]["json_schema"]["strict"], true);+ assert_eq!(+ judge_call["response_format"]["json_schema"]["schema"]["properties"]["decision"]["properties"]+ ["target"]["enum"],+ json!(["weak", "middle", "strong", "premium"])+ );+ Ok(())+}+#[tokio::test]async fn classifier_prompt_overrides_reach_every_server_mode() -> TestResult {let upstream = MockUpstream::start().await?;@@ -758,6 +888,7 @@ llm_client = "upstream"[routes.capability]id = "switchyard/capability"type = "llm_classifier"+mode = "capability"classifier_target = "classifier"strong_target = "strong"weak_target = "weak"@@ -767,10 +898,10 @@ prompt = "CUSTOM CAPABILITY\n{{RESPONSE_SCHEMA}}"[routes.escalation]id = "switchyard/escalation"type = "llm_classifier"+mode = "escalation"classifier_target = "classifier"strong_target = "strong"weak_target = "weak"-base_threshold = 0.5prompt = "CUSTOM ESCALATION\n{{RESPONSE_SCHEMA}}"escalation = {{ confirmations = 1 }}diff --git a/docs/getting_started.md b/docs/getting_started.mdindex 63ff63e80..a610ef28c 100644--- a/docs/getting_started.md+++ b/docs/getting_started.md@@ -148,6 +148,7 @@ llm_client = "openrouter"[routes.smart]id = "switchyard"type = "llm_classifier"+mode = "capability"classifier_target = "weak"strong_target = "strong"weak_target = "weak"diff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.mdindex 4bf0e435b..75e4eac9d 100644--- a/docs/reference/toml_schema.md+++ b/docs/reference/toml_schema.md@@ -84,13 +84,20 @@ Splits traffic across targets. See### `llm_classifier`-Classifies each task, then routes to the weak or strong target. See-[LLM Classifier Routing](../routing_algorithms/llm_classifier_routing.md) for-tuning.+Runs one of three judge-backed modes: `capability`, `escalation`, or `custom`.+`classifier_target` and `max_output_tokens` apply to all three.| Key | Required | Default | Meaning ||---|:---:|---|---|+| `mode` | No | `capability` | Classifier behavior. Set it explicitly for new configurations. || `classifier_target` | Yes | — | Target the judge is called through. Not a routing destination. |+| `max_output_tokens` | No | `4096` | Maximum completion tokens for the judge verdict. Must be at least `1`. |++Capability mode classifies before serving. See+[LLM Classifier Routing](../routing_algorithms/llm_classifier_routing.md).++| Key | Required | Default | Meaning |+|---|:---:|---|---|| `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]`. |@@ -99,23 +106,35 @@ 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. |+| `prompt` | No | packaged prompt | Replaces the capability prompt. `{{RESPONSE_SCHEMA}}` expands to its packaged schema. |-Add an `escalation` table to judge each completed turn instead of classifying up-front. See+Escalation mode serves the weak target first and judges the completed turn. See[Escalation-Router Routing](../routing_algorithms/escalation_router_routing.md).| Key | Required | Default | Meaning ||---|:---:|---|---|-| `confirmations` | No | `2` | Consecutive escalate verdicts required to latch. Above `1` needs a session ID. |-| `recent_turn_window` | No | `28` | Trailing messages shown to the judge. |-| `window_message_chars` | No | `500` | Per-message cap inside that window. |+| `strong_target` | Yes | — | Target used after the session latches. |+| `weak_target` | Yes | — | Target served before the latch. |+| `prompt` | No | packaged prompt | Replaces the trajectory-judge prompt. |+| `escalation.confirmations` | No | `2` | Consecutive escalate verdicts required to latch. Above `1` needs a session ID. |+| `escalation.recent_turn_window` | No | `28` | Trailing messages shown to the judge. |+| `escalation.window_message_chars` | No | `500` | Per-message cap inside that window. |++Existing configurations that contain `escalation` but omit `mode` remain valid.-`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.+Custom mode validates the judge's JSON against `response_schema`, resolves the+policy selector, and routes to any configured target label.++| Key | Required | Default | Meaning |+|---|:---:|---|---|+| `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. |+| `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. |### `stage_router`diff --git a/docs/routing_algorithms/escalation_router_routing.md b/docs/routing_algorithms/escalation_router_routing.mdindex 522168d1c..089d313d8 100644--- a/docs/routing_algorithms/escalation_router_routing.md+++ b/docs/routing_algorithms/escalation_router_routing.md@@ -35,10 +35,10 @@ llm_client = "openrouter"[routes.agent]id = "agent"type = "llm_classifier"+mode = "escalation"classifier_target = "judge"strong_target = "strong"weak_target = "weak"-base_threshold = 0.5prompt = "Judge whether the weak model is stuck. Return the required structured verdict."escalation = { confirmations = 2, recent_turn_window = 28, window_message_chars = 500 }```@@ -46,8 +46,6 @@ escalation = { confirmations = 2, recent_turn_window = 28, window_message_chars`classifier_target` is the judge. The route's `id`, `agent`, is the model nameclients 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. Ituses the escalation verdict schema rather than the capability verdict schema.Include `{{RESPONSE_SCHEMA}}` when the schema should also appear in the prompt.@@ -151,8 +149,7 @@ token cost and latency remain visible as routing overhead.## When not to use escalation routing- **One-shot requests.** No trajectory to judge. Use- [LLM Classifier Routing](llm_classifier_routing.md) without the `escalation`- table.+ [LLM Classifier Routing](llm_classifier_routing.md) in `capability` mode.- **Traffic without session identity.** With `confirmations` above `1`, the routecannot accumulate a streak and never latches.- **Fixed traffic experiments.** Use [Random Routing](random_routing.md).diff --git a/docs/routing_algorithms/llm_classifier_routing.md b/docs/routing_algorithms/llm_classifier_routing.mdindex ef400e9a1..e44f9a372 100644--- a/docs/routing_algorithms/llm_classifier_routing.md+++ b/docs/routing_algorithms/llm_classifier_routing.md@@ -1,7 +1,7 @@# LLM Classifier Routing-LLM classifier routing asks a judge model whether the efficient model is likely-to complete a request, then routes the request to a weak or strong target.+LLM classifier routing supports capability classification, trajectory escalation,+and custom schema-driven routing across two or more targets.## Configure a classifier route@@ -32,6 +32,7 @@ llm_client = "openrouter"[routes.smart]id = "smart"type = "llm_classifier"+mode = "capability"classifier_target = "classifier"strong_target = "strong"weak_target = "weak"@@ -91,6 +92,7 @@ Switchyard replaces it with the packaged capability-verdict schema.[routes.smart]id = "smart"type = "llm_classifier"+mode = "capability"classifier_target = "classifier"strong_target = "strong"weak_target = "weak"@@ -105,6 +107,55 @@ Return JSON matching this schema:The override changes the instructions only. The judge must still return thepackaged fields such as `p_solve`, `confidence`, and `capability_boundary`.+## Custom multi-target routing++Custom mode accepts an inner JSON Schema and a policy that reads the validated+verdict. This example routes across four configured targets:++```toml+[routes.smart]+id = "smart"+type = "llm_classifier"+mode = "custom"+classifier_target = "classifier"+targets = ["fast", "balanced", "reasoning", "premium"]+default_target = "premium"+prompt = """+Choose the best configured target for this request.+Return JSON matching:+{{RESPONSE_SCHEMA}}+"""+response_schema = '''+{+ "type": "object",+ "properties": {+ "decision": {+ "type": "object",+ "properties": {+ "target": {+ "type": "string",+ "enum": ["fast", "balanced", "reasoning", "premium"]+ }+ },+ "required": ["target"],+ "additionalProperties": false+ }+ },+ "required": ["decision"],+ "additionalProperties": false+}+'''++[routes.smart.policy]+type = "target_selector"+selector = "/decision/target"+```++The names in `targets` reference existing target tables. Switchyard passes the+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 calibrationThe packaged prompt is calibrated for one specific weak model, assumes it