feat(libsy): add minimal Python run API

crates/libsy-protocol/src/llm.rs

@@ -12,6 +12,7 @@ use crate::format::FormatId;
 
 /// Actor role normalized across provider APIs.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
 pub enum Role {
     System,
     Developer,
@@ -64,6 +65,7 @@ impl Message {
 
 /// Normalized content block variants carried by messages and tool results.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
 pub enum ContentBlock {
     Text {
         text: String,
@@ -97,6 +99,7 @@ pub enum ContentBlock {
 
 /// Image payload forms supported by the conversation model.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data", rename_all = "snake_case")]
 pub enum ImageSource {
     Url {
         url: String,
@@ -111,6 +114,7 @@ pub enum ImageSource {
 
 /// File payload forms supported by the conversation model.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data", rename_all = "snake_case")]
 pub enum FileSource {
     FileId(String),
     FileData {
@@ -122,6 +126,7 @@ pub enum FileSource {
 
 /// Audio and video payload forms supported by the conversation model.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data", rename_all = "snake_case")]
 pub enum MediaSource {
     Url {
         url: String,
@@ -161,6 +166,7 @@ pub struct ToolDefinition {
 
 /// Normalized tool choice policy.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data", rename_all = "snake_case")]
 pub enum ToolChoice {
     Auto,
     Required,
@@ -193,19 +199,22 @@ pub struct ReasoningParams {
 
 /// Provider-specific fields that do not have first-class conversation fields.
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
 pub struct ProviderExtensions {
     pub fields: Map<String, Value>,
 }
 
 /// Exact source payloads retained for lossless round trips.
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
 pub struct PreservationMetadata {
     pub requests: BTreeMap<FormatId, Value>,
     pub responses: BTreeMap<FormatId, Value>,
 }
 
 /// Normalized request representation shared by Switchyard components.
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
 pub struct LlmRequest {
     pub model: Option<String>,
     pub instructions: Vec<InstructionBlock>,
@@ -231,6 +240,7 @@ pub struct Usage {
 
 /// Normalized reason a model stopped producing output.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
 pub enum StopReason {
     EndTurn,
     MaxTokens,
@@ -253,6 +263,7 @@ pub struct ResponseOutput {
 /// [`LlmResponse`](crate::LlmResponse)); `switchyard-translation` re-exports it as
 /// `ConversationResponse`.
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
 pub struct AggLlmResponse {
     pub id: Option<String>,
     pub model: Option<String>,
@@ -268,3 +279,38 @@ impl AggLlmResponse {
         self.outputs.first()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn serde_uses_python_friendly_dictionary_shapes() -> Result<(), serde_json::Error> {
+        let request: LlmRequest = serde_json::from_value(json!({
+            "model": "auto",
+            "messages": [{
+                "role": "user",
+                "content": [{"type": "text", "text": "hello"}]
+            }]
+        }))?;
+        assert_eq!(request.messages[0], Message::text(Role::User, "hello"));
+
+        let tool_call = ContentBlock::ToolCall(ToolCall {
+            id: "call-1".to_string(),
+            name: "lookup".to_string(),
+            arguments: json!({"query": "rust"}),
+        });
+        assert_eq!(
+            serde_json::to_value(tool_call)?,
+            json!({
+                "type": "tool_call",
+                "id": "call-1",
+                "name": "lookup",
+                "arguments": {"query": "rust"}
+            })
+        );
+        Ok(())
+    }
+}

crates/switchyard-py/Cargo.toml

@@ -18,6 +18,7 @@ crate-type = ["cdylib", "rlib"]
 [dependencies]
 async-trait = "0.1"
 futures-util = "0.3"
+libsy = { path = "../libsy" }
 pyo3 = { version = "0.28.3", features = ["abi3-py312", "extension-module"] }
 pyo3-async-runtimes = { version = "0.28", features = ["tokio-runtime"] }
 pythonize = "0.28.0"

crates/switchyard-py/src/errors.rs

@@ -10,6 +10,7 @@ use switchyard_core::SwitchyardError;
 use switchyard_translation::TranslationError;
 
 create_exception!(_switchyard_rust, SwitchyardRuntimeError, PyRuntimeError);
+create_exception!(_switchyard_rust, LibsyError, SwitchyardRuntimeError);
 create_exception!(
     _switchyard_rust,
     SwitchyardConfigError,
@@ -79,6 +80,11 @@ pub(crate) fn py_translation_error(error: TranslationError) -> PyErr {
     PyValueError::new_err(format!("{}: {}", error.kind(), error))
 }
 
+/// Converts libsy execution failures into one stable Python exception.
+pub(crate) fn py_libsy_error(error: impl std::fmt::Display) -> PyErr {
+    LibsyError::new_err(error.to_string())
+}
+
 /// Converts core Switchyard errors into typed Python runtime errors.
 ///
 /// `ContextWindowExceeded` and `ContextPoolExhausted` carry typed fields
@@ -161,6 +167,7 @@ pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {
         "SwitchyardRuntimeError",
         py.get_type::<SwitchyardRuntimeError>(),
     )?;
+    module.add("LibsyError", py.get_type::<LibsyError>())?;
     module.add(
         "SwitchyardConfigError",
         py.get_type::<SwitchyardConfigError>(),

crates/switchyard-py/src/lib.rs

@@ -6,6 +6,7 @@ use pyo3::prelude::*;
 mod component_bindings;
 mod core_bindings;
 mod errors;
+mod libsy_bindings;
 mod profile_bindings;
 mod py_serde;
 mod server_bindings;
@@ -17,6 +18,7 @@ fn _switchyard_rust(module: &Bound<'_, PyModule>) -> PyResult<()> {
     translation::register(module)?;
     core_bindings::register(module)?;
     component_bindings::register(module)?;
+    libsy_bindings::register(module)?;
     profile_bindings::register(module)?;
     server_bindings::register(module)?;
     Ok(())

crates/switchyard-py/src/libsy_bindings.rs

@@ -0,0 +1,182 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Minimal Python API for running Rust-owned libsy algorithms.
+
+use std::error::Error;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use libsy::{
+    AggLlmResponse, Algorithm, Context, Decision, LlmResponse, LlmTarget, LlmTargetSet, NoopAlgo,
+    RandomAlgo, Request, Response, RoutedLlmClient,
+};
+use pyo3::exceptions::{PyTypeError, PyValueError};
+use pyo3::prelude::*;
+use serde_json::{json, Value};
+
+use crate::errors::py_libsy_error;
+use crate::py_serde::{from_python, to_python};
+
+type BoxError = Box<dyn Error + Send + Sync>;
+
+/// Adapts a Python object with `async call(request)` to libsy.
+struct PythonLlmClient {
+    inner: Py<PyAny>,
+}
+
+#[async_trait]
+impl RoutedLlmClient for PythonLlmClient {
+    async fn call(
+        &self,
+        _ctx: Context,
+        request: Request,
+        _decision: Arc<dyn Decision>,
+    ) -> Result<Response, BoxError> {
+        let metadata = request.metadata;
+        let future = Python::attach(|py| {
+            let request = to_python(py, &request.llm_request)?;
+            let awaitable = self.inner.bind(py).call_method1("call", (request,))?;
+            pyo3_async_runtimes::tokio::into_future(awaitable)
+        })
+        .map_err(boxed_python_error)?;
+
+        let response = future.await.map_err(boxed_python_error)?;
+        let aggregate = Python::attach(|py| from_python::<AggLlmResponse>(response.bind(py)))
+            .map_err(boxed_python_error)?;
+        Ok(Response {
+            llm_response: LlmResponse::Agg(aggregate),
+            metadata,
+        })
+    }
+}
+
+/// A required-client routing target used by Python-created algorithms.
+#[pyclass(name = "LlmTarget", module = "switchyard.libsy", frozen)]
+struct PyLlmTarget {
+    name: String,
+    client: Py<PyAny>,
+}
+
+impl PyLlmTarget {
+    fn clone_core(&self, py: Python<'_>) -> LlmTarget {
+        LlmTarget {
+            semantic_name: self.name.clone(),
+            llm_client: Some(Arc::new(PythonLlmClient {
+                inner: self.client.clone_ref(py),
+            })),
+        }
+    }
+}
+
+#[pymethods]
+impl PyLlmTarget {
+    #[new]
+    fn new(py: Python<'_>, name: String, client: Py<PyAny>) -> PyResult<Self> {
+        let call = client
+            .bind(py)
+            .getattr("call")
+            .map_err(|_| PyTypeError::new_err("client must define async call(request)"))?;
+        if !call.is_callable() {
+            return Err(PyTypeError::new_err(
+                "client.call must be callable as async call(request)",
+            ));
+        }
+        Ok(Self { name, client })
+    }
+
+    #[getter]
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn __repr__(&self) -> String {
+        format!("LlmTarget(name={:?})", self.name)
+    }
+}
+
+/// Opaque handle shared by every Rust-owned algorithm exposed to Python.
+#[pyclass(name = "Algorithm", module = "switchyard.libsy", frozen)]
+struct PyAlgorithm {
+    inner: Arc<dyn Algorithm>,
+}
+
+impl PyAlgorithm {
+    fn new(inner: Arc<dyn Algorithm>) -> Self {
+        Self { inner }
+    }
+}
+
+#[pymethods]
+impl PyAlgorithm {
+    /// Run to completion using the clients configured on the algorithm's targets.
+    fn run<'py>(&self, py: Python<'py>, request: &Bound<'_, PyAny>) -> PyResult<Bound<'py, PyAny>> {
+        let algorithm = Arc::clone(&self.inner);
+        let request = Request {
+            llm_request: from_python(request)?,
+            raw_request: None,
+            metadata: None,
+        };
+        pyo3_async_runtimes::tokio::future_into_py(py, async move {
+            let (decisions, response) = algorithm
+                .run(Context::default(), request)
+                .await
+                .map_err(py_libsy_error)?;
+            let response = response
+                .llm_response
+                .into_agg()
+                .await
+                .map_err(py_libsy_error)?;
+            let decisions = decisions
+                .iter()
+                .map(|decision| {
+                    json!({
+                        "selected_model": decision.selected_model(),
+                        "reasoning": decision.reasoning(),
+                    })
+                })
+                .collect::<Vec<Value>>();
+            Python::attach(|py| Ok((to_python(py, &decisions)?, to_python(py, &response)?)))
+        })
+    }
+
+    fn __repr__(&self) -> &'static str {
+        "Algorithm()"
+    }
+}
+
+/// Construct the no-op reference algorithm.
+#[pyfunction(name = "noop")]
+fn noop_algorithm() -> PyAlgorithm {
+    PyAlgorithm::new(Arc::new(NoopAlgo {}))
+}
+
+/// Construct uniform random routing over targets with Python clients.
+#[pyfunction(name = "random")]
+fn random_algorithm(py: Python<'_>, targets: Vec<Py<PyLlmTarget>>) -> PyResult<PyAlgorithm> {
+    if targets.is_empty() {
+        return Err(PyValueError::new_err("random requires at least one target"));
+    }
+    let targets = targets
+        .iter()
+        .map(|target| Ok(target.bind(py).try_borrow()?.clone_core(py)))
+        .collect::<PyResult<Vec<_>>>()?;
+    Ok(PyAlgorithm::new(Arc::new(RandomAlgo::new(
+        LlmTargetSet::new(targets),
+    ))))
+}
+
+fn boxed_python_error(error: PyErr) -> BoxError {
+    std::io::Error::other(error.to_string()).into()
+}
+
+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::<PyLlmTarget>()?;
+    libsy_module.add_function(wrap_pyfunction!(noop_algorithm, &libsy_module)?)?;
+    libsy_module.add_function(wrap_pyfunction!(random_algorithm, &libsy_module)?)?;
+    libsy_module.add("LibsyError", module.getattr("LibsyError")?)?;
+    module.add_submodule(&libsy_module)?;
+    Ok(())
+}