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.lockindex 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.tomlindex 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 = trueserde_json.workspace = trueswitchyard-protocol.workspace = true+switchyard-runner.workspace = trueswitchyard-server.workspace = truetokio.workspace = truediff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex 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::HOk(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__.pyindex 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.pyindex 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.pynew file mode 100644index 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"]