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(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.rs
index 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__.py
index 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.py
index 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_classifier
from switchyard_rust.libsy import noop as noop
from 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.py
index 745309062..20e54eccd 100644
--- a/switchyard_rust/libsy.py
+++ b/switchyard_rust/libsy.py
@@ -10,7 +10,19 @@ from typing import TYPE_CHECKING, Any, Protocol
from 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:
@property
def 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: ...
+
@final
class 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: