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(python): expose the configured algorithm factory (#1178)

Alex Fournier58996e6f2c33
diff --git a/Cargo.lock b/Cargo.lock
index a9ae848f0..d7fc22348 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5567,6 +5567,7 @@ dependencies = [
"serde_json",
"switchyard-libsy",
"switchyard-protocol",
+ "switchyard-runner",
"switchyard-server",
"tokio",
]
diff --git a/crates/switchyard-py/Cargo.toml b/crates/switchyard-py/Cargo.toml
index aec8d6797..550e7f9c9 100644
--- a/crates/switchyard-py/Cargo.toml
+++ b/crates/switchyard-py/Cargo.toml
@@ -25,5 +25,6 @@ pythonize = "0.28.0"
serde.workspace = true
serde_json.workspace = true
switchyard-protocol.workspace = true
+switchyard-runner.workspace = true
switchyard-server.workspace = true
tokio.workspace = true
diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rs
index 057cd3401..3a307dec9 100644
--- a/crates/switchyard-py/src/libsy_bindings.rs
+++ b/crates/switchyard-py/src/libsy_bindings.rs
@@ -24,6 +24,7 @@ use switchyard_protocol::{
Category, DecisionResponse, LlmClientError, LlmResponse, LlmResponseStream,
LlmResponseStreamEvent, Metadata, ModelId, Request, Response,
};
+use switchyard_runner::AlgorithmFactory;
use tokio::sync::Mutex;
use crate::errors::{ContextWindowExceededError, py_libsy_error};
@@ -76,6 +77,19 @@ fn header_map_from_python(headers: &HashMap<String, String>) -> PyResult<http::H
Ok(result)
}
+/// Attach normalized host metadata to a provider-neutral request.
+fn request_from_python(
+ request: &Bound<'_, PyAny>,
+ headers: Option<HashMap<String, String>>,
+) -> PyResult<Request> {
+ let headers = headers.as_ref().map(header_map_from_python).transpose()?;
+ Ok(Request {
+ llm_request: from_python(request)?,
+ raw_request: None,
+ metadata: headers.map(|headers| Metadata::from_headers(&headers)),
+ })
+}
+
/// Classifier settings shared by standalone and stage-router classifiers.
#[pyclass(
name = "TaskClassifierConfig",
@@ -852,6 +866,19 @@ struct PyRunStream {
inner: Arc<Mutex<StepStream>>,
}
+impl PyRunStream {
+ fn new(algorithm: &Arc<dyn Algorithm>, request: Request, models: Arc<RuntimeModels>) -> Self {
+ // Starting a run spawns Rust work, including when Python's event loop has not started.
+ let stream = {
+ let _guard = pyo3_async_runtimes::tokio::get_runtime().enter();
+ Arc::clone(algorithm).run_stream(request, models, State::default())
+ };
+ Self {
+ inner: Arc::new(Mutex::new(stream)),
+ }
+ }
+}
+
#[pymethods]
impl PyRunStream {
fn __aiter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
@@ -907,24 +934,17 @@ impl PyAlgorithm {
subagent_models: Option<HashMap<String, Vec<String>>>,
headers: Option<HashMap<String, String>>,
) -> PyResult<PyRunStream> {
- let headers = headers.as_ref().map(header_map_from_python).transpose()?;
- let request = Request {
- llm_request: from_python(request)?,
- raw_request: None,
- metadata: headers.map(|headers| Metadata::from_headers(&headers)),
- };
+ let request = request_from_python(request, headers)?;
let mut runtime_models = RuntimeModels::new(category_models_from_python(models)?);
if let Some(subagent_models) = subagent_models {
runtime_models =
runtime_models.with_subagent(category_models_from_python(subagent_models)?);
}
- let stream = {
- let _guard = pyo3_async_runtimes::tokio::get_runtime().enter();
- Arc::clone(&self.inner).run_stream(request, Arc::new(runtime_models), State::default())
- };
- Ok(PyRunStream {
- inner: Arc::new(Mutex::new(stream)),
- })
+ Ok(PyRunStream::new(
+ &self.inner,
+ request,
+ Arc::new(runtime_models),
+ ))
}
fn __repr__(&self) -> &'static str {
@@ -932,6 +952,73 @@ impl PyAlgorithm {
}
}
+/// Deployment algorithms parsed without constructing provider clients or reading credentials.
+#[pyclass(name = "AlgorithmFactory", module = "switchyard.libsy", frozen)]
+struct PyAlgorithmFactory {
+ inner: AlgorithmFactory,
+}
+
+#[pymethods]
+impl PyAlgorithmFactory {
+ /// Parse a complete deployment; invalid configuration raises `ValueError`.
+ #[staticmethod]
+ fn from_toml(py: Python<'_>, source: &str) -> PyResult<Self> {
+ let inner = py
+ .detach(|| AlgorithmFactory::from_toml(source))
+ .map_err(|error| PyValueError::new_err(error.to_string()))?;
+ Ok(Self { inner })
+ }
+
+ /// Build independent configured handles keyed by each route's public ID.
+ fn build(&self, py: Python<'_>) -> PyResult<BTreeMap<String, Py<PyConfiguredAlgorithm>>> {
+ let algorithms = py
+ .detach(|| self.inner.build())
+ .map_err(|error| PyValueError::new_err(error.to_string()))?;
+ algorithms
+ .into_iter()
+ .map(|(id, (algorithm, models))| {
+ Ok((
+ id,
+ Py::new(
+ py,
+ PyConfiguredAlgorithm {
+ algorithm,
+ models: Arc::new(models),
+ },
+ )?,
+ ))
+ })
+ .collect()
+ }
+}
+
+/// A reusable algorithm paired with its deployment's parent and subagent model groups.
+/// The host applies target prompts and provider settings when serving model calls.
+#[pyclass(name = "ConfiguredAlgorithm", module = "switchyard.libsy", frozen)]
+struct PyConfiguredAlgorithm {
+ algorithm: Arc<dyn Algorithm>,
+ models: Arc<RuntimeModels>,
+}
+
+#[pymethods]
+impl PyConfiguredAlgorithm {
+ /// Yield host-owned model and decision calls for a normalized request.
+ /// Libsy's per-run `State` is not carried forward, as in `Algorithm.run_stream`.
+ #[pyo3(signature = (request, *, headers=None))]
+ fn run_stream(
+ &self,
+ request: &Bound<'_, PyAny>,
+ headers: Option<&Bound<'_, PyAny>>,
+ ) -> PyResult<PyRunStream> {
+ let headers = headers.map(from_python).transpose()?;
+ Ok(PyRunStream::new(
+ &self.algorithm,
+ request_from_python(request, headers)?,
+ Arc::clone(&self.models),
+ ))
+ }
+}
+
fn step_to_python(step: RustStep) -> PyResult<PyStep> {
match step {
RustStep::CallDecision(call) => Python::attach(|py| {
@@ -1110,6 +1197,8 @@ 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::<PyAlgorithmFactory>()?;
+ libsy_module.add_class::<PyConfiguredAlgorithm>()?;
libsy_module.add_class::<PyCustomClassifierConfig>()?;
libsy_module.add_class::<PyDecisionCall>()?;
libsy_module.add_class::<PyDeescalationConfig>()?;
diff --git a/switchyard/libsy/__init__.py b/switchyard/libsy/__init__.py
index 244159331..b6e7b172b 100644
--- a/switchyard/libsy/__init__.py
+++ b/switchyard/libsy/__init__.py
@@ -5,6 +5,8 @@
from switchyard_rust.libsy import (
Algorithm,
+ AlgorithmFactory,
+ ConfiguredAlgorithm,
ContextWindowExceededError,
CustomClassifierConfig,
DecisionCall,
@@ -25,6 +27,8 @@ from . import algorithms as algorithms
__all__ = [
"Algorithm",
+ "AlgorithmFactory",
+ "ConfiguredAlgorithm",
"ContextWindowExceededError",
"CustomClassifierConfig",
"DecisionCall",
diff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.py
index 9d944257e..b6c6c9dde 100644
--- a/switchyard_rust/libsy.py
+++ b/switchyard_rust/libsy.py
@@ -13,6 +13,8 @@ from switchyard_rust._native import load_native
_EXPORTS = frozenset(
{
"Algorithm",
+ "AlgorithmFactory",
+ "ConfiguredAlgorithm",
"ContextWindowExceededError",
"CustomClassifierConfig",
"DecisionCall",
@@ -283,6 +285,32 @@ if TYPE_CHECKING:
headers: Mapping[str, str] | None = None,
) -> AsyncIterator[Step.CallModel | Step.CallDecision | Step.Done]: ...
+ @final
+ class AlgorithmFactory:
+ """Build deployment algorithms without provider clients or credential access."""
+
+ @staticmethod
+ def from_toml(source: str) -> AlgorithmFactory:
+ """Parse a full deployment, raising ValueError for invalid configuration."""
+ ...
+
+ def build(self) -> dict[str, ConfiguredAlgorithm]:
+ """Build independent handles keyed by the public route IDs."""
+ ...
+
+ @final
+ class ConfiguredAlgorithm:
+ """An algorithm and model groups; the host applies target prompts and provider settings."""
+
+ def run_stream(
+ self,
+ request: Mapping[str, object],
+ *,
+ headers: Mapping[str, str] | None = None,
+ ) -> AsyncIterator[Step.CallModel | Step.CallDecision | Step.Done]:
+ """Yield host calls and an outcome without carrying libsy's per-run State forward."""
+ ...
+
def noop() -> Algorithm: ...
def random(
diff --git a/tests/test_algorithm_factory.py b/tests/test_algorithm_factory.py
new file mode 100644
index 000000000..62d697090
--- /dev/null
+++ b/tests/test_algorithm_factory.py
@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Smoke test for the Python algorithm factory."""
+
+from switchyard.libsy import AlgorithmFactory, ConfiguredAlgorithm, Step
+
+
+async def test_factory_builds_a_usable_python_handle() -> None:
+ """Configured handles run without a separate model map."""
+ routes = AlgorithmFactory.from_toml("""
+schema_version = 1
+[llm_clients.host]
+format = "openai_chat"
+base_url = "https://host.invalid/v1"
+[targets]
+fast = { id = "gateway/fast", llm_client = "host" }
+[routes.main]
+id = "switchyard/main"
+type = "passthrough"
+target = "fast"
+""").build()
+ route = routes["switchyard/main"]
+ assert isinstance(route, ConfiguredAlgorithm)
+ steps = [
+ step
+ async for step in route.run_stream(
+ {
+ "model": "switchyard/main",
+ "messages": [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],
+ }
+ )
+ ]
+ assert len(steps) == 1
+ assert isinstance(steps[0], Step.Done)
+ assert steps[0].outcome.selected_model_ids == ["gateway/fast"]