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
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
//! Prompt and structured-output contracts shared by LLM classifiers.
use jsonschema::Validator;
use serde::Deserialize;
use serde_json::{Value, json};
use crate::{LibsyError, Result};
/// Provider-side structured-output mode used by a classifier judge.
#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ClassifierResponseFormat {
/// Send the verdict schema through the provider's strict JSON Schema wrapper.
#[default]
JsonSchema,
/// Request a JSON object and enforce the verdict schema locally.
JsonObject,
}
/// User-configurable parts of a classifier's prompt and verdict contract.
///
/// Fields are private so new contract settings can be added without breaking Rust struct literals.
#[derive(Clone, Debug, Default, Deserialize)]
pub struct ClassifierContractConfig {
#[serde(default)]
prompt: Option<String>,
#[serde(default)]
response_format_type: ClassifierResponseFormat,
}
impl ClassifierContractConfig {
/// Overrides the packaged classifier prompt.
pub fn with_prompt(mut self, prompt: impl Into<String>) -> Self {
self.prompt = Some(prompt.into());
self
}
/// Returns the configured prompt override.
pub fn prompt(&self) -> Option<&str> {
self.prompt.as_deref()
}
/// Selects the provider-side structured-output mode.
pub fn with_response_format_type(
mut self,
response_format_type: ClassifierResponseFormat,
) -> Self {
self.response_format_type = response_format_type;
self
}
/// Returns the configured provider-side structured-output mode.
pub fn response_format_type(&self) -> ClassifierResponseFormat {
self.response_format_type
}
}
/// Rendered prompt and response format for one classifier.
#[derive(Debug)]
pub(crate) struct ClassifierContract {
system_prompt: String,
response_format: Value,
validator: Option<Validator>,
}
impl ClassifierContract {
/// Builds a contract from user settings and packaged defaults.
///
/// The packaged response format must contain `json_schema.schema`. JSON Schema mode retains
/// that wrapper for the model request; JSON Object mode moves the schema into the prompt and
/// compiles it for local validation.
pub(crate) fn from_config(
config: &ClassifierContractConfig,
default_prompt: &str,
response_format_json: &str,
) -> Result<Self> {
let prompt_template = config.prompt().unwrap_or(default_prompt);
let response_format: Value =
serde_json::from_str(response_format_json).map_err(|error| {
LibsyError::AlgorithmError {
message: format!("response schema is invalid: {error}"),
}
})?;
let schema = response_format
.pointer("/json_schema/schema")
.ok_or_else(|| LibsyError::AlgorithmError {
message: "response schema has no json_schema.schema".to_string(),
})?;
match config.response_format_type() {
ClassifierResponseFormat::JsonSchema => {
Self::from_response_format(prompt_template, response_format, None)
}
ClassifierResponseFormat::JsonObject => {
validate_prompt(prompt_template)?;
let validator = compile_schema(schema)?;
let rendered_schema = serde_json::to_string_pretty(schema).map_err(|error| {
algorithm_error(format!("response schema could not be rendered: {error}"))
})?;
let system_prompt = format!(
"{prompt_template}\n\nReturn exactly one JSON object matching this JSON Schema:\n{rendered_schema}"
);
Self::from_response_format(
&system_prompt,
json!({"type": "json_object"}),
Some(validator),
)
}
}
}
/// Builds a provider response format around a user-supplied inner JSON Schema.
pub(crate) fn from_inner_schema(prompt_template: &str, schema: Value) -> Result<Self> {
if schema.get("json_schema").is_some() {
return Err(LibsyError::AlgorithmError {
message:
"response_schema must be the inner JSON Schema, not a response_format wrapper"
.to_string(),
});
}
let validator = compile_schema(&schema)?;
Self::from_response_format(
prompt_template,
json!({
"type": "json_schema",
"json_schema": {
"name": "switchyard_classifier_response",
"strict": true,
"schema": schema,
}
}),
Some(validator),
)
}
fn from_response_format(
prompt_template: &str,
response_format: Value,
validator: Option<Validator>,
) -> Result<Self> {
validate_prompt(prompt_template)?;
Ok(Self {
system_prompt: prompt_template.to_string(),
response_format,
validator,
})
}
pub(crate) fn system_prompt(&self) -> &str {
&self.system_prompt
}
pub(crate) fn response_format(&self) -> &Value {
&self.response_format
}
/// Whether the provider response must be checked against the compiled schema locally.
pub(crate) fn validates_locally(&self) -> bool {
self.validator.is_some()
}
/// Validates a dynamic verdict when this contract carries a runtime schema validator.
pub(crate) fn validate_verdict(&self, verdict: &Value) -> Result<()> {
let Some(validator) = &self.validator else {
return Ok(());
};
validator
.validate(verdict)
.map_err(|error| LibsyError::AlgorithmError {
message: format!("classifier verdict did not match response_schema: {error}"),
})
}
}
pub(super) fn validate_prompt(prompt_template: &str) -> Result<()> {
if prompt_template.trim().is_empty() {
return Err(algorithm_error("classifier prompt must not be empty"));
}
if prompt_template.contains("{{RESPONSE_SCHEMA}}") {
return Err(algorithm_error(
"classifier prompt must not include {{RESPONSE_SCHEMA}}; remove the placeholder because Switchyard supplies the schema automatically",
));
}
Ok(())
}
fn compile_schema(schema: &Value) -> Result<Validator> {
if !schema.is_object() {
return Err(algorithm_error("response_schema must be a JSON object"));
}
jsonschema::meta::validate(schema).map_err(|error| {
algorithm_error(format!(
"response_schema is not a valid JSON Schema: {error}"
))
})?;
jsonschema::validator_for(schema)
.map_err(|error| algorithm_error(format!("response_schema could not be compiled: {error}")))
}
fn algorithm_error(message: impl Into<String>) -> LibsyError {
LibsyError::AlgorithmError {
message: message.into(),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_runtime_contract_keeps_its_schema_out_of_the_prompt() -> Result<()> {
let schema = r#"{
"type": "json_schema",
"json_schema": {
"name": "RiskDecision",
"schema": {
"type": "object",
"properties": {"risk": {"type": "number"}}
}
}
}"#;
let config = ClassifierContractConfig::default().with_prompt(
"Return a risk verdict matching the response schema supplied with the request.",
);
let contract = ClassifierContract::from_config(&config, "packaged prompt", schema)?;
assert_eq!(
contract.system_prompt(),
"Return a risk verdict matching the response schema supplied with the request."
);
assert!(!contract.system_prompt().contains("\"risk\""));
assert_eq!(
contract
.response_format()
.pointer("/json_schema/name")
.and_then(Value::as_str),
Some("RiskDecision")
);
Ok(())
}
#[test]
fn a_contract_requires_an_inner_json_schema() {
let error = ClassifierContract::from_config(
&ClassifierContractConfig::default(),
"classify",
r#"{"type":"json"}"#,
)
.expect_err("missing inner schema should be rejected");
assert!(error.to_string().contains("json_schema.schema"));
}
#[test]
fn a_contract_rejects_an_empty_prompt() {
let config = ClassifierContractConfig::default().with_prompt(" \n");
let error = ClassifierContract::from_config(
&config,
"packaged prompt",
r#"{"json_schema":{"schema":{"type":"object"}}}"#,
)
.expect_err("empty prompt should be rejected");
assert!(error.to_string().contains("prompt must not be empty"));
}
#[test]
fn a_contract_rejects_a_response_schema_placeholder() {
let config = ClassifierContractConfig::default()
.with_prompt("Return JSON matching {{RESPONSE_SCHEMA}}");
let error = ClassifierContract::from_config(
&config,
"packaged prompt",
r#"{"json_schema":{"schema":{"type":"object"}}}"#,
)
.expect_err("schema placeholders should be rejected");
assert!(
error
.to_string()
.contains("Switchyard supplies the schema automatically")
);
}
#[test]
fn a_custom_contract_wraps_and_validates_its_inner_schema() -> Result<()> {
let contract = ClassifierContract::from_inner_schema(
"Choose a target matching the response schema supplied with the request.",
json!({
"type": "object",
"$defs": {
"decision": {
"type": "object",
"properties": {
"target": {"type": "string", "enum": ["sonnet", "opus"]}
},
"required": ["target"],
"additionalProperties": false
}
},
"properties": {
"decision": {"$ref": "#/$defs/decision"}
},
"required": ["decision"],
"additionalProperties": false
}),
)?;
assert_eq!(
contract
.response_format()
.pointer("/json_schema/name")
.and_then(Value::as_str),
Some("switchyard_classifier_response")
);
assert_eq!(
contract
.response_format()
.pointer("/json_schema/strict")
.and_then(Value::as_bool),
Some(true)
);
assert!(!contract.system_prompt().contains("\"target\""));
contract.validate_verdict(&json!({"decision": {"target": "sonnet"}}))?;
assert!(
contract
.validate_verdict(&json!({"decision": {"target": "unknown"}}))
.is_err()
);
Ok(())
}
#[test]
fn a_provider_wrapper_is_rejected_as_an_inner_schema() {
let error = ClassifierContract::from_inner_schema(
"classify",
json!({"json_schema": {"schema": {"type": "object"}}}),
)
.expect_err("provider wrapper should be rejected");
assert!(error.to_string().contains("inner JSON Schema"));
}
}