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

refactor(libsy): rename hierarchical routing to composite (#548)

ryan-lempka7d1380b73f18
diff --git a/README.md b/README.md
index 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 routing
diff --git a/crates/libsy/src/algorithms.rs b/crates/libsy/src/algorithms.rs
index 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.rs
similarity index 92%
rename from crates/libsy/src/algorithms/hierarchical.rs
rename to crates/libsy/src/algorithms/composite.rs
index 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.rs
index 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.rs
index 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.rs
index 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.5
classify_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.md
index 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's
configuration. 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.md
similarity index 85%
rename from docs/routing_algorithms/hierarchical_routing.md
rename to docs/routing_algorithms/composite_routing.md
index 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.md
index 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.md
index 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 valida
the 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 picked
at the user turn, so a fallthrough judge would sit between the signals and that
decision and overrule it.
diff --git a/mkdocs.yml b/mkdocs.yml
index 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: