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
refactor(libsy): rename hierarchical routing to composite (#548)
ryan-lempka7d1380b73f18
diff --git a/README.md b/README.mdindex 7f8a23e91..948bcb88f 100644--- a/README.md+++ b/README.md@@ -90,7 +90,7 @@ algorithm list, or the [`switchyard-libsy`](crates/libsy/README.md) crate docs.| [LLM Classifier](docs/routing_algorithms/llm_classifier_routing.md) | Request content should decide whether a turn needs the weak or strong tier. | `llm_classifier` || [Stage Router](docs/routing_algorithms/stage_router_routing.md) | Signals already in the conversation, such as tool results and errors, should route most turns without an extra model call. | `stage_router` || [Escalation Router](docs/routing_algorithms/escalation_router_routing.md) | Every turn runs on the weak tier first, and a judge reads that answer to decide whether to send the same request to the strong tier. | `llm_classifier` with `mode = "escalation"` |-| [Hierarchical](docs/routing_algorithms/hierarchical_routing.md) | Routing algorithms are composed in a hierarchy, where one sets the configuration of another before handing off. Today an LLM classifier sets the tier a stage router falls open to. | `hierarchical` |+| [Composite](docs/routing_algorithms/composite_routing.md) | Routing algorithms are composed, one setting the configuration of another before handing off. Today an LLM classifier sets the tier a stage router falls open to. | `composite` || [Random](docs/routing_algorithms/random_routing.md) | You need a fixed traffic split for A/B tests, baselines, or cost experiments. | `random` |A `passthrough` route registers one target under one model ID with no routingdiff --git a/crates/libsy/src/algorithms.rs b/crates/libsy/src/algorithms.rsindex ac97b6e15..fa6c2af5d 100644--- a/crates/libsy/src/algorithms.rs+++ b/crates/libsy/src/algorithms.rs@@ -7,9 +7,9 @@//! `use switchyard_libsy::Random`.pub mod advisor_gate;+pub mod composite;mod escalation;pub mod fall_through;-pub mod hierarchical;pub mod llm_class;pub mod noop;pub mod passthrough;diff --git a/crates/libsy/src/algorithms/hierarchical.rs b/crates/libsy/src/algorithms/composite.rssimilarity index 92%rename from crates/libsy/src/algorithms/hierarchical.rsrename to crates/libsy/src/algorithms/composite.rsindex 30aebcb02..9d1916446 100644--- a/crates/libsy/src/algorithms/hierarchical.rs+++ b/crates/libsy/src/algorithms/composite.rs@@ -24,7 +24,7 @@ use crate::core::state::State;use crate::{LibsyError, Result};use switchyard_protocol::{ModelId, Request};-const HIERARCHICAL: &str = "hierarchical";+const COMPOSITE: &str = "composite";/// Sets the stage router's fall-open tier from a judge verdict.///@@ -96,7 +96,7 @@ impl Processor<State> for TierSetter {}/// A judge stacked over a stage router.-pub struct HierarchicalRouterConfig {+pub struct CompositeRouterConfig {/// Target the judge is called through. Not a routing destination.pub judge_target: ModelId,/// Judge settings, including how often `classify_trigger` runs it.@@ -106,11 +106,11 @@ pub struct HierarchicalRouterConfig {}/// Runs a stage router with a tier the judge picks.-pub struct HierarchicalRouter {+pub struct CompositeRouter {route: FallThrough<State>,}-impl HierarchicalRouter {+impl CompositeRouter {/// Stacks the judge over a stage router across the same tier pair.////// Errors on a configuration either algorithm rejects and on `every_request`.@@ -120,12 +120,11 @@ impl HierarchicalRouter {pub fn new(capable: ModelId,efficient: ModelId,- config: HierarchicalRouterConfig,+ config: CompositeRouterConfig,) -> Result<Self> {if config.judge.classify_trigger == ClassifyTrigger::EveryRequest {return Err(LibsyError::AlgorithmError {- message: "hierarchical: classify_trigger must be user_turn or new_session"- .to_string(),+ message: "composite: classify_trigger must be user_turn or new_session".to_string(),});}let trigger = config.judge.classify_trigger;@@ -152,16 +151,16 @@ impl HierarchicalRouter {tiers: Mutex::new(HashMap::new()),};let route = build_stage_route(capable, efficient, config.stage)?- .with_name(HIERARCHICAL)+ .with_name(COMPOSITE).with_processor(Arc::new(setter));Ok(Self { route })}}#[async_trait]-impl Algorithm for HierarchicalRouter {+impl Algorithm for CompositeRouter {fn name(&self) -> &str {- HIERARCHICAL+ COMPOSITE}async fn route(@@ -201,11 +200,11 @@ mod tests {request}- fn hash_keyed_router() -> Result<Arc<HierarchicalRouter>> {- Ok(Arc::new(HierarchicalRouter::new(+ fn hash_keyed_router() -> Result<Arc<CompositeRouter>> {+ Ok(Arc::new(CompositeRouter::new(ModelId::from("strong"),ModelId::from("weak"),- HierarchicalRouterConfig {+ CompositeRouterConfig {judge_target: ModelId::from(JUDGE),judge: TaskClassifierConfig {base_threshold: 0.5,@@ -218,11 +217,11 @@ mod tests {)?))}- fn router() -> Result<Arc<HierarchicalRouter>> {- Ok(Arc::new(HierarchicalRouter::new(+ fn router() -> Result<Arc<CompositeRouter>> {+ Ok(Arc::new(CompositeRouter::new(ModelId::from("strong"),ModelId::from("weak"),- HierarchicalRouterConfig {+ CompositeRouterConfig {judge_target: ModelId::from(JUDGE),judge: TaskClassifierConfig {base_threshold: 0.5,@@ -236,13 +235,13 @@ mod tests {#[test]fn rejects_every_request_as_a_trigger() {- let config = HierarchicalRouterConfig {+ let config = CompositeRouterConfig {judge_target: ModelId::from(JUDGE),judge: TaskClassifierConfig::default(),stage: StageRouterConfig::new(PickerMode::EfficientFirst, 0.5),};assert!(matches!(- HierarchicalRouter::new(ModelId::from("strong"), ModelId::from("weak"), config),+ CompositeRouter::new(ModelId::from("strong"), ModelId::from("weak"), config),Err(LibsyError::AlgorithmError { .. })));}diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rsindex 80f31459d..3907feb3c 100644--- a/crates/libsy/src/lib.rs+++ b/crates/libsy/src/lib.rs@@ -15,7 +15,7 @@ pub use error::{DriverError, LibsyError, Result};mod algorithms;pub use algorithms::advisor_gate::{AdvisorGate, AdvisorGateConfig, GateTrigger};-pub use algorithms::hierarchical::{HierarchicalRouter, HierarchicalRouterConfig};+pub use algorithms::composite::{CompositeRouter, CompositeRouterConfig};pub use algorithms::llm_class::{CustomClassifierConfig, CustomClassifierPolicy, LlmClassifierConfig, LlmTaskClassifier,TaskClassifierConfig,diff --git a/crates/switchyard-runner/src/algorithm.rs b/crates/switchyard-runner/src/algorithm.rsindex a71d32731..a601ab94a 100644--- a/crates/switchyard-runner/src/algorithm.rs+++ b/crates/switchyard-runner/src/algorithm.rs@@ -10,8 +10,8 @@ use std::sync::Arc;use libsy::{AdvisorGate, AdvisorGateConfig, Algorithm, ClassifierContractConfig, ClassifierResponseFormat,- ClassifyTrigger, CustomClassifierConfig, CustomClassifierPolicy, EscalationJudgeConfig,- GateTrigger, HandoffNoteConfig, HierarchicalRouter, HierarchicalRouterConfig,+ ClassifyTrigger, CompositeRouter, CompositeRouterConfig, CustomClassifierConfig,+ CustomClassifierPolicy, EscalationJudgeConfig, GateTrigger, HandoffNoteConfig,LlmClassifierConfig, LlmFallback, LlmTaskClassifier, Noop, Passthrough, PickerMode, Random,StageRouter, StageRouterConfig, SubagentRouter, SubagentRouterConfig, TargetPrompts,TaskClassifierConfig,@@ -259,7 +259,7 @@ pub enum AlgorithmSpec {subagents: Option<SubagentRouteConfig>,},/// A judge picks the tier at each user turn; a stage router runs the turns within it.- Hierarchical {+ Composite {/// Judge that picks the tier. Called through its own target.classifier: StageClassifierConfig,/// The stage router the judge hands off to.@@ -454,7 +454,7 @@ impl AlgorithmSpec {}names}- Self::Hierarchical {+ Self::Composite {stage, subagents, ..} => {let mut names = vec![@@ -498,7 +498,7 @@ impl AlgorithmSpec {names.extend(subagents.classifier_target_name());}}- Self::Hierarchical {+ Self::Composite {classifier,subagents,..@@ -986,7 +986,7 @@ fn build_algorithm(let parent: Arc<dyn Algorithm> = Arc::new(algorithm);attach_subagent_router(route_name, parent, subagents.as_ref(), targets)}- AlgorithmSpec::Hierarchical {+ AlgorithmSpec::Composite {classifier,stage,subagents,@@ -1004,18 +1004,17 @@ fn build_algorithm(&efficient,stage.efficient_system_prompt.as_deref(),);- let config = HierarchicalRouterConfig {+ let config = CompositeRouterConfig {judge_target,judge: classifier.task_classifier_config(),stage: stage_config,};- let algorithm =- HierarchicalRouter::new(capable, efficient, config).map_err(|error| {- AlgorithmConfigError::with_source(- format!("hierarchical route {route_name}: {error}"),- error,- )- })?;+ let algorithm = CompositeRouter::new(capable, efficient, config).map_err(|error| {+ AlgorithmConfigError::with_source(+ format!("composite route {route_name}: {error}"),+ error,+ )+ })?;let parent: Arc<dyn Algorithm> = Arc::new(algorithm);attach_subagent_router(route_name, parent, subagents.as_ref(), targets)}diff --git a/crates/switchyard-runner/src/config.rs b/crates/switchyard-runner/src/config.rsindex 26527d99d..d4887fab1 100644--- a/crates/switchyard-runner/src/config.rs+++ b/crates/switchyard-runner/src/config.rs@@ -644,23 +644,23 @@ base_threshold = 0.5)}- fn hierarchical_config() -> String {+ fn composite_config() -> String {format!(r#"{VALID_CONFIG}[targets.tier_judge]id = "tier-judge/model"llm_client = "primary"-[routes.hier]+[routes.composed]id = "switchyard/hier"-type = "hierarchical"+type = "composite"-[routes.hier.classifier]+[routes.composed.classifier]target = "tier_judge"base_threshold = 0.5classify_trigger = "user_turn"-[routes.hier.stage]+[routes.composed.stage]capable_target = "strong"efficient_target = "weak"confidence_threshold = 0.5@@ -669,8 +669,8 @@ confidence_threshold = 0.5}#[test]- fn hierarchical_route_builds_and_claims_both_tiers_and_its_judge() -> RunnerResult<()> {- let runner = runner_from_toml(&hierarchical_config())?;+ fn composite_route_builds_and_claims_both_tiers_and_its_judge() -> RunnerResult<()> {+ let runner = runner_from_toml(&composite_config())?;assert!(runner.models()@@ -830,8 +830,8 @@ confidence_threshold = 0.5}#[test]- fn hierarchical_stage_block_rejects_an_unknown_field() {- let config = hierarchical_config().replace(+ fn composite_stage_block_rejects_an_unknown_field() {+ let config = composite_config().replace("confidence_threshold = 0.5","confidence_threshold = 0.5\nmagic = true",);diff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.mdindex fdf6a9c4b..6061a67ab 100644--- a/docs/reference/toml_schema.md+++ b/docs/reference/toml_schema.md@@ -211,11 +211,11 @@ optional `handoff_notes` and `classifier` tables and for tuning.| `classifier.response_format_type` | No | `json_schema` | Structured-output mode for the optional classifier judge. Use `json_object` when the classifier provider does not support JSON Schema; Switchyard adds the schema to the prompt and validates the verdict locally. || `subagents` | No | unset | Nested `passthrough` or custom `llm_classifier` policy used only for delegated sub-agent work. See [Sub-Agent-Aware Routing](../routing_algorithms/subagent_routing.md). |-### `hierarchical`+### `composite`-Stacks other algorithms in a hierarchy, where one can set another's+Composes other algorithms, letting one set another'sconfiguration. Today a classifier sets the tier a stage router falls open to when its own signals are not confident, leaving its scoring and escalation logic untouched. See-[Hierarchical Routing](../routing_algorithms/hierarchical_routing.md).+[Composite Routing](../routing_algorithms/composite_routing.md).| Key | Required | Default | Meaning ||---|:---:|---|---|diff --git a/docs/routing_algorithms/hierarchical_routing.md b/docs/routing_algorithms/composite_routing.mdsimilarity index 85%rename from docs/routing_algorithms/hierarchical_routing.mdrename to docs/routing_algorithms/composite_routing.mdindex 18784d1a6..f11226935 100644--- a/docs/routing_algorithms/hierarchical_routing.md+++ b/docs/routing_algorithms/composite_routing.md@@ -1,8 +1,9 @@-# Hierarchical Routing+# Composite Routing-Routing algorithms composed in a hierarchy. An algorithm higher in the hierarchy-sets the configuration of the one below it before handing off, so each algorithm-runs where its evidence is strongest.+Routing algorithms composed together. One sets the configuration of another and+hands off, so each algorithm runs where its evidence is strongest. The composition+is not restricted to a tree: sequential, conditional, and turn-boundary shapes all+fit the same route type.## What exists today@@ -21,7 +22,7 @@ route's configuration to change as more pairings are added.```toml[routes.switchyard]id = "switchyard"-type = "hierarchical"+type = "composite"[routes.switchyard.classifier]target = "judge"diff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.mdindex 2503af57e..648e6866b 100644--- a/docs/routing_algorithms/overview.md+++ b/docs/routing_algorithms/overview.md@@ -16,7 +16,7 @@ configuration and tuning. For the vocabulary these pages use, see| [Random Routing](random_routing.md) | You need a fixed traffic split for A/B tests, baselines, or cost experiments. | `random` || [LLM Classifier Routing](llm_classifier_routing.md) | Request content should decide whether a turn needs the weak or strong tier. | `llm_classifier` || [Stage-Router Routing](stage_router_routing.md) | Tool-result and agent-progress signals should route most turns without an extra classifier call. | `stage_router` |-| [Hierarchical Routing](hierarchical_routing.md) | Routing algorithms are composed in a hierarchy, where one sets the configuration of another before handing off. Today an LLM classifier sets a stage router's default tier. | `hierarchical` |+| [Composite Routing](composite_routing.md) | Routing algorithms are composed, one setting the configuration of another before handing off. Today an LLM classifier sets a stage router's default tier. | `composite` || [Escalation-Router Routing](escalation_router_routing.md) | Start every task on the weak tier and escalate to strong when an LLM judge detects trouble. | `llm_classifier` with `escalation` || [Advisor-Gate Routing](advisor_gate_routing.md) | One model should serve every turn, with a stronger reviewer approving its "done" claims or sending back a redo plan. | `advisor` |diff --git a/docs/routing_algorithms/stage_router_routing.md b/docs/routing_algorithms/stage_router_routing.mdindex 0f77bdfb8..c91750d00 100644--- a/docs/routing_algorithms/stage_router_routing.md+++ b/docs/routing_algorithms/stage_router_routing.md@@ -258,7 +258,7 @@ JSON Object mode; Switchyard then adds the schema to the judge prompt and validathe returned object locally. The verdict schema and routing thresholds remain unchanged.Leave the block out under-[Hierarchical Routing](hierarchical_routing.md). There the tier is already picked+[Composite Routing](composite_routing.md). There the tier is already pickedat the user turn, so a fallthrough judge would sit between the signals and thatdecision and overrule it.diff --git a/mkdocs.yml b/mkdocs.ymlindex 46f642364..27bf9d444 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -29,7 +29,7 @@ nav:- Random Routing: routing_algorithms/random_routing.md- LLM Classifier Routing: routing_algorithms/llm_classifier_routing.md- Stage-Router Routing: routing_algorithms/stage_router_routing.md- - Hierarchical Routing: routing_algorithms/hierarchical_routing.md+ - Composite Routing: routing_algorithms/composite_routing.md- Escalation-Router Routing: routing_algorithms/escalation_router_routing.md- Advisor-Gate Routing: routing_algorithms/advisor_gate_routing.md- Operations: