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(python): unify LLM classifier bindings (#465)
nachiketb-nvidia7c40943a4ef9
diff --git a/crates/libsy/src/algorithms/llm_class.rs b/crates/libsy/src/algorithms/llm_class.rsindex 7d8b2fb66..8b146e039 100644--- a/crates/libsy/src/algorithms/llm_class.rs+++ b/crates/libsy/src/algorithms/llm_class.rs@@ -597,6 +597,7 @@ struct ClassifierRouteConfig {}/// Complete construction settings for one LLM classifier mode.+#[derive(Clone)]#[non_exhaustive]pub enum LlmClassifierConfig {/// Routes between efficient and capable targets from a task-level verdict.diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex f52e29e36..5d6e018c1 100644--- a/crates/switchyard-py/src/libsy_bindings.rs+++ b/crates/switchyard-py/src/libsy_bindings.rs@@ -10,8 +10,10 @@ use futures::StreamExt;use http::header::{HeaderName, HeaderValue};use pyo3::exceptions::{PyBaseException, PyStopAsyncIteration, PyTypeError, PyValueError};use pyo3::prelude::*;+use serde_json::Value;use switchyard_libsy::{- Algorithm, CallModel, ClassifierContractConfig, ClassifierResponseFormat, HandoffNoteConfig,+ Algorithm, CallModel, ClassifierContractConfig, ClassifierResponseFormat,+ CustomClassifierConfig, CustomClassifierPolicy, EscalationJudgeConfig, HandoffNoteConfig,LibsyError as RustLibsyError, LlmClassifierConfig, LlmFallback, LlmTaskClassifier, Noop,PickerMode, Random, StageRouter, StageRouterConfig, Step as RustStep, StepStream,TaskClassifierConfig,@@ -57,6 +59,190 @@ impl PyTaskClassifierConfig {}}+/// Settings for response-based escalation classification.+#[pyclass(+ name = "EscalationClassifierConfig",+ module = "switchyard.libsy",+ frozen,+ skip_from_py_object+)]+#[derive(Clone)]+struct PyEscalationClassifierConfig {+ contract: ClassifierContractConfig,+ judge: EscalationJudgeConfig,+ max_output_tokens: u64,+}++#[pymethods]+impl PyEscalationClassifierConfig {+ #[new]+ #[pyo3(signature = (+ *,+ confirmations=2,+ recent_turn_window=28,+ window_message_chars=500,+ max_output_tokens=4096,+ prompt=None,+ response_format_type="json_schema"+ ))]+ #[allow(clippy::too_many_arguments)]+ fn new(+ confirmations: u32,+ recent_turn_window: usize,+ window_message_chars: usize,+ max_output_tokens: u64,+ prompt: Option<String>,+ response_format_type: &str,+ ) -> PyResult<Self> {+ Ok(Self {+ contract: classifier_contract(prompt, response_format_type)?,+ judge: EscalationJudgeConfig {+ confirmations,+ recent_turn_window,+ window_message_chars,+ },+ max_output_tokens,+ })+ }+}++/// Settings for a classifier with a user-supplied verdict schema.+#[pyclass(+ name = "CustomClassifierConfig",+ module = "switchyard.libsy",+ frozen,+ skip_from_py_object+)]+#[derive(Clone)]+struct PyCustomClassifierConfig {+ inner: CustomClassifierConfig,+}++impl PyCustomClassifierConfig {+ fn clone_core(&self) -> CustomClassifierConfig {+ self.inner.clone()+ }+}++#[pymethods]+impl PyCustomClassifierConfig {+ #[new]+ #[pyo3(signature = (+ prompt,+ response_schema,+ selector,+ *,+ session_affinity=false,+ message_hash_fallback=false,+ recent_turn_window=None,+ max_output_tokens=4096+ ))]+ #[allow(clippy::too_many_arguments)]+ fn new(+ prompt: String,+ response_schema: &Bound<'_, PyAny>,+ selector: String,+ session_affinity: bool,+ message_hash_fallback: bool,+ recent_turn_window: Option<usize>,+ max_output_tokens: u64,+ ) -> PyResult<Self> {+ // Convert the Python schema into serde JSON and pair it with the target-selector policy;+ // conversion failures propagate to Python through `PyResult`.+ let mut inner = CustomClassifierConfig::new(+ prompt,+ from_python::<Value>(response_schema)?,+ CustomClassifierPolicy::target_selector(selector),+ );+ inner.session_affinity = session_affinity;+ inner.message_hash_fallback = message_hash_fallback;+ inner.recent_turn_window = recent_turn_window;+ inner.max_output_tokens = max_output_tokens;+ Ok(Self { inner })+ }+}++/// Construction settings for a Python-hosted LLM classifier.+#[pyclass(+ name = "LlmClassifierConfig",+ module = "switchyard.libsy",+ frozen,+ skip_from_py_object+)]+struct PyLlmClassifierConfig {+ inner: LlmClassifierConfig,+}++#[pymethods]+impl PyLlmClassifierConfig {+ /// Configure capability routing between efficient and capable targets.+ #[staticmethod]+ #[pyo3(signature = (judge_target, efficient_target, capable_target, *, config))]+ fn capability(+ py: Python<'_>,+ judge_target: String,+ efficient_target: String,+ capable_target: String,+ config: Py<PyTaskClassifierConfig>,+ ) -> PyResult<Self> {+ Ok(Self {+ inner: LlmClassifierConfig::Capability {+ judge_target: ModelId::new(judge_target),+ efficient_target: ModelId::new(efficient_target),+ capable_target: ModelId::new(capable_target),+ config: config.bind(py).try_borrow()?.clone_core(),+ },+ })+ }++ /// Configure response-based escalation between efficient and capable targets.+ #[staticmethod]+ #[pyo3(signature = (judge_target, efficient_target, capable_target, *, config))]+ fn escalation(+ py: Python<'_>,+ judge_target: String,+ efficient_target: String,+ capable_target: String,+ config: Py<PyEscalationClassifierConfig>,+ ) -> PyResult<Self> {+ let config = config.bind(py).try_borrow()?;+ Ok(Self {+ inner: LlmClassifierConfig::Escalation {+ judge_target: ModelId::new(judge_target),+ efficient_target: ModelId::new(efficient_target),+ capable_target: ModelId::new(capable_target),+ contract: config.contract.clone(),+ config: config.judge.clone(),+ max_output_tokens: config.max_output_tokens,+ },+ })+ }++ /// Configure schema-driven routing across named targets.+ #[staticmethod]+ #[pyo3(signature = (judge_target, targets, *, default_target, config))]+ fn custom(+ py: Python<'_>,+ judge_target: String,+ targets: Vec<(String, String)>,+ default_target: String,+ config: Py<PyCustomClassifierConfig>,+ ) -> PyResult<Self> {+ let config = config.bind(py).try_borrow()?.clone_core();+ Ok(Self {+ inner: LlmClassifierConfig::Custom {+ judge_target: ModelId::new(judge_target),+ targets: targets+ .into_iter()+ .map(|(name, target)| (name, ModelId::new(target)))+ .collect(),+ default_target,+ config,+ },+ })+ }+}+#[pymethods]impl PyTaskClassifierConfig {#[new]@@ -82,20 +268,6 @@ impl PyTaskClassifierConfig {prompt: Option<String>,response_format_type: &str,) -> PyResult<Self> {- let mut contract = ClassifierContractConfig::default();- if let Some(prompt) = prompt {- contract = contract.with_prompt(prompt);- }- let response_format_type = match response_format_type {- "json_schema" => ClassifierResponseFormat::JsonSchema,- "json_object" => ClassifierResponseFormat::JsonObject,- other => {- return Err(PyValueError::new_err(format!(- "response_format_type must be 'json_schema' or 'json_object', got {other:?}"- )));- }- };- contract = contract.with_response_format_type(response_format_type);Ok(Self {inner: TaskClassifierConfig {base_threshold,@@ -103,13 +275,33 @@ impl PyTaskClassifierConfig {session_affinity,message_hash_fallback,recent_turn_window,- contract,+ contract: classifier_contract(prompt, response_format_type)?,max_output_tokens,},})}}+fn classifier_contract(+ prompt: Option<String>,+ response_format_type: &str,+) -> PyResult<ClassifierContractConfig> {+ let mut contract = ClassifierContractConfig::default();+ if let Some(prompt) = prompt {+ contract = contract.with_prompt(prompt);+ }+ let response_format_type = match response_format_type {+ "json_schema" => ClassifierResponseFormat::JsonSchema,+ "json_object" => ClassifierResponseFormat::JsonObject,+ other => {+ return Err(PyValueError::new_err(format!(+ "response_format_type must be 'json_schema' or 'json_object', got {other:?}"+ )));+ }+ };+ Ok(contract.with_response_format_type(response_format_type))+}+/// Judge target and policy used when stage-router signals are inconclusive.#[pyclass(name = "LlmFallback",@@ -419,7 +611,16 @@ fn random_algorithm(})}-/// Construct task-level LLM classifier routing.+/// Construct LLM classifier routing from a mode config.+#[pyfunction(name = "llm_classifier")]+fn llm_classifier_algorithm(+ py: Python<'_>,+ config: Py<PyLlmClassifierConfig>,+) -> PyResult<PyAlgorithm> {+ build_llm_classifier(config.bind(py).try_borrow()?.inner.clone())+}++/// Construct capability classifier routing.#[pyfunction(name = "llm_task_classifier")]#[pyo3(signature = (judge_target,@@ -435,13 +636,17 @@ fn llm_task_classifier_algorithm(capable_target: String,config: Py<PyTaskClassifierConfig>,) -> PyResult<PyAlgorithm> {- let algorithm = LlmTaskClassifier::new(LlmClassifierConfig::Capability {+ build_llm_classifier(LlmClassifierConfig::Capability {judge_target: ModelId::new(judge_target),efficient_target: ModelId::new(efficient_target),capable_target: ModelId::new(capable_target),config: config.bind(py).try_borrow()?.clone_core(),})- .map_err(|error| PyValueError::new_err(error.to_string()))?;+}++fn build_llm_classifier(config: LlmClassifierConfig) -> PyResult<PyAlgorithm> {+ let algorithm =+ LlmTaskClassifier::new(config).map_err(|error| PyValueError::new_err(error.to_string()))?;Ok(PyAlgorithm {inner: Arc::new(algorithm),})@@ -524,7 +729,10 @@ fn stage_router_algorithm(pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {let libsy_module = PyModule::new(module.py(), "libsy")?;libsy_module.add_class::<PyAlgorithm>()?;+ libsy_module.add_class::<PyCustomClassifierConfig>()?;libsy_module.add_class::<PyDecision>()?;+ libsy_module.add_class::<PyEscalationClassifierConfig>()?;+ libsy_module.add_class::<PyLlmClassifierConfig>()?;libsy_module.add_class::<PyLlmFallback>()?;libsy_module.add_class::<PyModelCall>()?;libsy_module.add_class::<PyRunStream>()?;@@ -532,6 +740,7 @@ pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {libsy_module.add_class::<PyTaskClassifierConfig>()?;libsy_module.add_function(wrap_pyfunction!(noop_algorithm, &libsy_module)?)?;libsy_module.add_function(wrap_pyfunction!(random_algorithm, &libsy_module)?)?;+ libsy_module.add_function(wrap_pyfunction!(llm_classifier_algorithm, &libsy_module)?)?;libsy_module.add_function(wrap_pyfunction!(llm_task_classifier_algorithm,&libsy_modulediff --git a/switchyard/libsy/__init__.py b/switchyard/libsy/__init__.pyindex 78a535d01..69e5f26c5 100644--- a/switchyard/libsy/__init__.py+++ b/switchyard/libsy/__init__.py@@ -6,8 +6,11 @@from switchyard_rust.libsy import (Algorithm,ContextWindowExceededError,+ CustomClassifierConfig,Decision,+ EscalationClassifierConfig,LibsyError,+ LlmClassifierConfig,LlmFallback,ModelCall,Step,@@ -19,8 +22,11 @@ from . import algorithms as algorithms__all__ = ["Algorithm","ContextWindowExceededError",+ "CustomClassifierConfig","Decision",+ "EscalationClassifierConfig","LibsyError",+ "LlmClassifierConfig","LlmFallback","ModelCall","Step",diff --git a/switchyard/libsy/algorithms.py b/switchyard/libsy/algorithms.pyindex 92e9e747e..444f9598c 100644--- a/switchyard/libsy/algorithms.py+++ b/switchyard/libsy/algorithms.py@@ -3,9 +3,10 @@"""Factories for Rust-owned libsy algorithms."""+from switchyard_rust.libsy import llm_classifier as llm_classifierfrom switchyard_rust.libsy import llm_task_classifier as llm_task_classifierfrom switchyard_rust.libsy import noop as noopfrom switchyard_rust.libsy import random as randomfrom switchyard_rust.libsy import stage_router as stage_router-__all__ = ["llm_task_classifier", "noop", "random", "stage_router"]+__all__ = ["llm_classifier", "llm_task_classifier", "noop", "random", "stage_router"]diff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.pyindex 67e4e1888..65542dd68 100644--- a/switchyard_rust/libsy.py+++ b/switchyard_rust/libsy.py@@ -14,12 +14,16 @@ _EXPORTS = frozenset({"Algorithm","ContextWindowExceededError",+ "CustomClassifierConfig","Decision",+ "EscalationClassifierConfig","LibsyError",+ "LlmClassifierConfig","LlmFallback","ModelCall","Step","TaskClassifierConfig",+ "llm_classifier","llm_task_classifier","noop","random",@@ -35,6 +39,45 @@ if TYPE_CHECKING:class ContextWindowExceededError(RuntimeError): ...+ @final+ class CustomClassifierConfig:+ """Configure schema-validated routing across named targets.++ ``max_output_tokens`` must be positive. Enabling ``message_hash_fallback``+ requires ``session_affinity``.+ """++ def __init__(+ self,+ prompt: str,+ response_schema: Mapping[str, object],+ selector: str,+ *,+ session_affinity: bool = False,+ message_hash_fallback: bool = False,+ recent_turn_window: int | None = None,+ max_output_tokens: int = 4096,+ ) -> None: ...++ @final+ class EscalationClassifierConfig:+ """Configure response-based escalation between two targets.++ Counts and token limits must be positive, and ``window_message_chars``+ must be at least 50.+ """++ def __init__(+ self,+ *,+ confirmations: int = 2,+ recent_turn_window: int = 28,+ window_message_chars: int = 500,+ max_output_tokens: int = 4096,+ prompt: str | None = None,+ response_format_type: Literal["json_schema", "json_object"] = "json_schema",+ ) -> None: ...+@finalclass Decision:"""A semantic routing choice produced by an algorithm."""@@ -88,6 +131,12 @@ if TYPE_CHECKING:@finalclass TaskClassifierConfig:+ """Configure capability classification between efficient and capable targets.++ Thresholds must remain within ``[0, 1]``, ``max_output_tokens`` must be+ positive, and ``message_hash_fallback`` requires ``session_affinity``.+ """+def __init__(self,base_threshold: float,@@ -101,6 +150,46 @@ if TYPE_CHECKING:response_format_type: Literal["json_schema", "json_object"] = "json_schema",) -> None: ...+ class LlmClassifierConfig:+ """Select one supported LLM classifier mode.++ Target names and each nested mode configuration must satisfy the selected+ classifier's invariants.+ """++ @staticmethod+ def capability(+ judge_target: str,+ efficient_target: str,+ capable_target: str,+ *,+ config: TaskClassifierConfig,+ ) -> LlmClassifierConfig:+ """Route by predicted task capability."""+ ...++ @staticmethod+ def escalation(+ judge_target: str,+ efficient_target: str,+ capable_target: str,+ *,+ config: EscalationClassifierConfig,+ ) -> LlmClassifierConfig:+ """Call the efficient target first and escalate judged responses."""+ ...++ @staticmethod+ def custom(+ judge_target: str,+ targets: Sequence[tuple[str, str]],+ *,+ default_target: str,+ config: CustomClassifierConfig,+ ) -> LlmClassifierConfig:+ """Route among named targets using a schema-selected label."""+ ...+@finalclass LlmFallback:def __init__(@@ -127,6 +216,10 @@ if TYPE_CHECKING:seed: int | None = None,) -> Algorithm: ...+ def llm_classifier(config: LlmClassifierConfig) -> Algorithm:+ """Build a classifier, raising ValueError when its configuration is invalid."""+ ...+def llm_task_classifier(judge_target: str,efficient_target: str,diff --git a/tests/test_libsy_minimal_bindings.py b/tests/test_libsy_minimal_bindings.pyindex 8e93cd6bb..a01d61d03 100644--- a/tests/test_libsy_minimal_bindings.py+++ b/tests/test_libsy_minimal_bindings.py@@ -10,8 +10,10 @@ import pytestfrom switchyard.libsy import (Algorithm,ContextWindowExceededError,+ CustomClassifierConfig,Decision,LibsyError,+ LlmClassifierConfig,Step,TaskClassifierConfig,algorithms,@@ -161,14 +163,16 @@ async def test_classifier_config_accepts_a_prompt_override() -> None:judge = JudgeClient("judge")weak = EchoClient("weak")- algorithm = algorithms.llm_task_classifier(- "judge",- "weak",- "strong",- config=TaskClassifierConfig(- 0.5,- threshold_step=0.1,- prompt="Custom capability rubric.",+ algorithm = algorithms.llm_classifier(+ LlmClassifierConfig.capability(+ "judge",+ "weak",+ "strong",+ config=TaskClassifierConfig(+ 0.5,+ threshold_step=0.1,+ prompt="Custom capability rubric.",+ ),),)@@ -189,6 +193,49 @@ async def test_classifier_config_accepts_a_prompt_override() -> None:assert response["model"] == "weak"+async def test_custom_classifier_routes_across_named_targets() -> None:+ class JudgeClient(EchoClient):+ async def call(self, request: dict[str, Any]) -> dict[str, Any]:+ self.calls.append(request)+ return {+ "model": self.model,+ "outputs": [+ {+ "role": "assistant",+ "content": [{"type": "text", "text": '{"target":"balanced"}'}],+ "stop_reason": "end_turn",+ }+ ],+ }++ schema = {+ "type": "object",+ "additionalProperties": False,+ "required": ["target"],+ "properties": {"target": {"type": "string", "enum": ["fast", "balanced", "best"]}},+ }+ algorithm = algorithms.llm_classifier(+ LlmClassifierConfig.custom(+ "judge",+ [("fast", "model-a"), ("balanced", "model-b"), ("best", "model-c")],+ default_target="fast",+ config=CustomClassifierConfig("Choose a target.", schema, "/target"),+ )+ )++ _, response = await run_algorithm(+ algorithm,+ {+ "judge": JudgeClient("judge"),+ "model-a": EchoClient("model-a"),+ "model-b": EchoClient("model-b"),+ "model-c": EchoClient("model-c"),+ },+ )++ assert response["model"] == "model-b"++async def test_classifier_config_accepts_json_object_output() -> None:"""Verify that Python can select JSON Object mode for a classifier judge."""