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(libsy): expose task classifier and stage router in Python (#199)
nachiketb-nvidiaace80c88b5c8
diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex 934d3b859..a50380fd7 100644--- a/crates/switchyard-py/src/libsy_bindings.rs+++ b/crates/switchyard-py/src/libsy_bindings.rs@@ -9,7 +9,11 @@ use async_trait::async_trait;use pyo3::exceptions::{PyTypeError, PyValueError};use pyo3::prelude::*;use serde_json::{json, Value};-use switchyard_libsy::algorithms::{Noop, Random};+use switchyard_libsy::algorithms::{+ LlmFallback, LlmTaskClassifier, Noop, Random, StageRouter, StageRouterConfig,+ TaskClassifierConfig,+};+use switchyard_libsy::stage_router::{HandoffNoteConfig, PickerMode};use switchyard_libsy::{AggLlmResponse, Algorithm, Context, Decision, LibsyError as RustLibsyError, LlmClientError,LlmResponse, LlmTarget, LlmTargetSet, Metadata, Request, Response, RoutedLlmClient,@@ -93,6 +97,91 @@ impl PyLlmTarget {}}+/// Classifier thresholds shared by standalone and stage-router classifiers.+#[pyclass(+ name = "TaskClassifierConfig",+ module = "switchyard.libsy",+ frozen,+ skip_from_py_object+)]+#[derive(Clone)]+struct PyTaskClassifierConfig {+ inner: TaskClassifierConfig,+}++impl PyTaskClassifierConfig {+ fn clone_core(&self) -> TaskClassifierConfig {+ self.inner.clone()+ }+}++#[pymethods]+impl PyTaskClassifierConfig {+ #[new]+ #[pyo3(signature = (+ base_threshold,+ *,+ min_confidence=0.0,+ capability_elevated_floor=None,+ session_affinity=false,+ message_hash_fallback=false,+ recent_turn_window=None+ ))]+ #[allow(clippy::too_many_arguments)]+ fn new(+ base_threshold: f64,+ min_confidence: f64,+ capability_elevated_floor: Option<f64>,+ session_affinity: bool,+ message_hash_fallback: bool,+ recent_turn_window: Option<usize>,+ ) -> Self {+ Self {+ inner: TaskClassifierConfig {+ base_threshold,+ min_confidence,+ capability_elevated_floor,+ session_affinity,+ message_hash_fallback,+ recent_turn_window,+ },+ }+ }+}++/// Judge target and policy used when stage-router signals are inconclusive.+#[pyclass(+ name = "LlmFallback",+ module = "switchyard.libsy",+ frozen,+ skip_from_py_object+)]+struct PyLlmFallback {+ judge_target: Py<PyLlmTarget>,+ config: Py<PyTaskClassifierConfig>,+}++impl PyLlmFallback {+ fn clone_core(&self, py: Python<'_>) -> PyResult<LlmFallback> {+ Ok(LlmFallback {+ judge_target: self.judge_target.bind(py).try_borrow()?.clone_core(py),+ config: self.config.bind(py).try_borrow()?.clone_core(),+ })+ }+}++#[pymethods]+impl PyLlmFallback {+ #[new]+ #[pyo3(signature = (judge_target, *, config))]+ fn new(judge_target: Py<PyLlmTarget>, config: Py<PyTaskClassifierConfig>) -> Self {+ Self {+ judge_target,+ config,+ }+ }+}+/// Opaque handle shared by every Rust-owned algorithm exposed to Python.#[pyclass(name = "Algorithm", module = "switchyard.libsy", frozen)]struct PyAlgorithm {@@ -183,6 +272,108 @@ fn random_algorithm(Ok(PyAlgorithm::new(Arc::new(algorithm)))}+/// Construct task-level LLM classifier routing.+#[pyfunction(name = "llm_task_classifier")]+#[pyo3(signature = (+ judge_target,+ efficient_target,+ capable_target,+ *,+ config+))]+fn llm_task_classifier_algorithm(+ py: Python<'_>,+ judge_target: Py<PyLlmTarget>,+ efficient_target: Py<PyLlmTarget>,+ 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(),+ )+ .map_err(|error| PyValueError::new_err(error.to_string()))?;+ Ok(PyAlgorithm::new(Arc::new(algorithm)))+}++/// Construct signal-driven stage routing with an optional LLM classifier fallback.+#[pyfunction(name = "stage_router")]+#[pyo3(signature = (+ capable_target,+ efficient_target,+ *,+ picker,+ confidence_threshold,+ recent_window=None,+ escalation_note=None,+ deescalation_note=None,+ only_on_wrong_signal_escalation=true,+ capable_system_prompt=None,+ efficient_system_prompt=None,+ classifier=None+))]+#[allow(clippy::too_many_arguments)]+fn stage_router_algorithm(+ py: Python<'_>,+ capable_target: Py<PyLlmTarget>,+ efficient_target: Py<PyLlmTarget>,+ picker: &str,+ confidence_threshold: f64,+ recent_window: Option<usize>,+ escalation_note: Option<String>,+ deescalation_note: Option<String>,+ only_on_wrong_signal_escalation: bool,+ capable_system_prompt: Option<String>,+ efficient_system_prompt: Option<String>,+ classifier: Option<Py<PyLlmFallback>>,+) -> PyResult<PyAlgorithm> {+ let mode = match picker {+ "capable_first" => PickerMode::CapableFirst,+ "efficient_first" => PickerMode::EfficientFirst,+ other => {+ return Err(PyValueError::new_err(format!(+ "picker must be 'capable_first' or 'efficient_first', got {other:?}"+ )));+ }+ };+ let capable = capable_target.bind(py).try_borrow()?.clone_core(py);+ let efficient = efficient_target.bind(py).try_borrow()?.clone_core(py);+ let mut config = StageRouterConfig::new(mode, confidence_threshold);+ config.recent_window = recent_window;+ config.handoff_notes = match (escalation_note, deescalation_note) {+ (Some(escalation), deescalation) => Some(HandoffNoteConfig::new(+ escalation,+ deescalation,+ only_on_wrong_signal_escalation,+ )),+ (None, Some(_)) => {+ return Err(PyValueError::new_err(+ "deescalation_note requires escalation_note",+ ));+ }+ (None, None) => None,+ };+ if let Some(prompt) = capable_system_prompt {+ config.tier_prompts = config+ .tier_prompts+ .with(capable.semantic_name.clone(), prompt);+ }+ if let Some(prompt) = efficient_system_prompt {+ config.tier_prompts = config+ .tier_prompts+ .with(efficient.semantic_name.clone(), prompt);+ }+ config.llm_fallback = classifier+ .map(|classifier| classifier.bind(py).try_borrow()?.clone_core(py))+ .transpose()?;++ let algorithm = StageRouter::new(capable, efficient, config)+ .map_err(|error| PyValueError::new_err(error.to_string()))?;+ Ok(PyAlgorithm::new(Arc::new(algorithm)))+}+fn other_python_error(error: PyErr) -> LlmClientError {LlmClientError::Ffi {source: Box::new(error),@@ -198,9 +389,16 @@ fn invalid_python_response(error: PyErr) -> LlmClientError {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::<PyLlmFallback>()?;libsy_module.add_class::<PyLlmTarget>()?;+ 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_task_classifier_algorithm,+ &libsy_module+ )?)?;+ libsy_module.add_function(wrap_pyfunction!(stage_router_algorithm, &libsy_module)?)?;libsy_module.add("LibsyError", module.getattr("LibsyError")?)?;module.add_submodule(&libsy_module)?;Ok(())diff --git a/switchyard/libsy/__init__.py b/switchyard/libsy/__init__.pyindex f7f5b51b4..44ca4cea3 100644--- a/switchyard/libsy/__init__.py+++ b/switchyard/libsy/__init__.py@@ -3,8 +3,23 @@"""Run Rust-owned libsy algorithms with Python-hosted LLM clients."""-from switchyard_rust.libsy import Algorithm, LibsyError, LlmClient, LlmTarget+from switchyard_rust.libsy import (+ Algorithm,+ LibsyError,+ LlmClient,+ LlmFallback,+ LlmTarget,+ TaskClassifierConfig,+)from . import algorithms as algorithms-__all__ = ["Algorithm", "LibsyError", "LlmClient", "LlmTarget", "algorithms"]+__all__ = [+ "Algorithm",+ "LibsyError",+ "LlmClient",+ "LlmFallback",+ "LlmTarget",+ "TaskClassifierConfig",+ "algorithms",+]diff --git a/switchyard/libsy/algorithms.py b/switchyard/libsy/algorithms.pyindex 434526feb..92e9e747e 100644--- a/switchyard/libsy/algorithms.py+++ b/switchyard/libsy/algorithms.py@@ -3,7 +3,9 @@"""Factories for Rust-owned libsy algorithms."""+from switchyard_rust.libsy import llm_task_classifier as llm_task_classifierfrom switchyard_rust.libsy import noop as noopfrom switchyard_rust.libsy import random as random+from switchyard_rust.libsy import stage_router as stage_router-__all__ = ["noop", "random"]+__all__ = ["llm_task_classifier", "noop", "random", "stage_router"]diff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.pyindex 745309062..20e54eccd 100644--- a/switchyard_rust/libsy.py+++ b/switchyard_rust/libsy.py@@ -10,7 +10,19 @@ from typing import TYPE_CHECKING, Any, Protocolfrom switchyard_rust.core import _load_native-_EXPORTS = frozenset({"Algorithm", "LibsyError", "LlmTarget", "noop", "random"})+_EXPORTS = frozenset(+ {+ "Algorithm",+ "LibsyError",+ "LlmFallback",+ "LlmTarget",+ "TaskClassifierConfig",+ "llm_task_classifier",+ "noop",+ "random",+ "stage_router",+ }+)class LlmClient(Protocol):@@ -39,6 +51,28 @@ if TYPE_CHECKING:@propertydef name(self) -> str: ...+ @final+ class TaskClassifierConfig:+ def __init__(+ self,+ base_threshold: float,+ *,+ min_confidence: float = 0.0,+ capability_elevated_floor: float | None = None,+ session_affinity: bool = False,+ message_hash_fallback: bool = False,+ recent_turn_window: int | None = None,+ ) -> None: ...++ @final+ class LlmFallback:+ def __init__(+ self,+ judge_target: LlmTarget,+ *,+ config: TaskClassifierConfig,+ ) -> None: ...+@finalclass Algorithm:async def run(@@ -51,6 +85,29 @@ if TYPE_CHECKING:def random(targets: Sequence[LlmTarget]) -> Algorithm: ...+ def llm_task_classifier(+ judge_target: LlmTarget,+ efficient_target: LlmTarget,+ capable_target: LlmTarget,+ *,+ config: TaskClassifierConfig,+ ) -> Algorithm: ...++ def stage_router(+ capable_target: LlmTarget,+ efficient_target: LlmTarget,+ *,+ picker: str,+ confidence_threshold: float,+ recent_window: int | None = None,+ escalation_note: str | None = None,+ deescalation_note: str | None = None,+ only_on_wrong_signal_escalation: bool = True,+ capable_system_prompt: str | None = None,+ efficient_system_prompt: str | None = None,+ classifier: LlmFallback | None = None,+ ) -> Algorithm: ...+def __getattr__(name: str) -> object:if name in _EXPORTS: