Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

feat(llm-classifier): custom schema support + multi target (>2) routing support (#275)

Ayush Agarwal4ae99c215891
diff --git a/Cargo.lock b/Cargo.lock
index 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.toml
index 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.toml
index ce34afe2f..bea219160 100644
--- a/crates/libsy/Cargo.toml
+++ b/crates/libsy/Cargo.toml
@@ -21,6 +21,8 @@ async-trait.workspace = true
serde.workspace = true
serde_json.workspace = true
futures.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.md
index 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.rs
index 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.rs
index 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.rs
index 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<Message
kept.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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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_lib
let 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.rs
index 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.md
index 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.rs
index 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.rs
index 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.5
Ok(())
}
+#[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.5
prompt = "CUSTOM ESCALATION\n{{RESPONSE_SCHEMA}}"
escalation = {{ confirmations = 1 }}
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 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.md
index 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.md
index 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.5
prompt = "Judge whether the weak model is stuck. Return the required structured verdict."
escalation = { confirmations = 2, recent_turn_window = 28, window_message_chars = 500 }
```
@@ -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 name
clients send; the judge is not exposed as a client-selectable model.
-`base_threshold` is still required, but escalation ignores it, along with
-`min_confidence`, `capability_elevated_floor`, and `session_affinity`.
The route-level `prompt` key replaces the packaged trajectory-judge prompt. It
uses the escalation verdict schema rather than the capability verdict schema.
Include `{{RESPONSE_SCHEMA}}` when the schema should also appear in the prompt.
@@ -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 route
cannot 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.md
index 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 the
packaged 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 calibration
The packaged prompt is calibrated for one specific weak model, assumes it