Skip to main content

switchyard_runner/
algorithm.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Schema-neutral algorithm configuration and construction.
5
6use std::collections::{BTreeMap, BTreeSet, HashMap};
7use std::error::Error;
8use std::fmt::{Display, Formatter};
9use std::path::PathBuf;
10use std::sync::Arc;
11
12use libsy::{
13    AdvisorGate, AdvisorGateConfig, Algorithm, BreakerConfig, CapabilityJudgeConfig,
14    ClassifierContractConfig, ClassifierResponseFormat, ClassifyTrigger, CompositeJudgeConfig,
15    CompositeRouter, CustomClassifierConfig, CustomClassifierPolicy, DEFAULT_UNMATCHED_STEPS,
16    DecisionChoice, DecisionJudgeConfig, DirectClassifierConfig, EscalationJudgeConfig,
17    GateTrigger, HandoffNoteConfig, LlmCapabilityConfig, LlmClassifierConfig, LlmFallback,
18    LlmTaskClassifier, Noop, Passthrough, PickerMode, Random, RuntimeModels, StageRouter,
19    StageRouterConfig, SubagentRouter, SubagentRouterConfig, TaskClassifierConfig, ToolSemantics,
20    Vgr, VgrConfig,
21};
22use serde::Deserialize;
23use strum_macros::IntoStaticStr;
24use switchyard_protocol::{Category, ModelId};
25
26/// Error returned when an algorithm description cannot be constructed.
27#[derive(Debug)]
28pub struct AlgorithmConfigError {
29    message: String,
30    source: Option<Box<dyn Error + Send + Sync>>,
31}
32
33impl AlgorithmConfigError {
34    fn new(message: impl Into<String>) -> Self {
35        Self {
36            message: message.into(),
37            source: None,
38        }
39    }
40
41    fn with_source(message: impl Into<String>, source: impl Error + Send + Sync + 'static) -> Self {
42        Self {
43            message: message.into(),
44            source: Some(Box::new(source)),
45        }
46    }
47}
48
49impl Display for AlgorithmConfigError {
50    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
51        formatter.write_str(&self.message)
52    }
53}
54
55impl Error for AlgorithmConfigError {
56    fn source(&self) -> Option<&(dyn Error + 'static)> {
57        self.source.as_deref().map(|source| source as _)
58    }
59}
60
61type AlgorithmResult<T> = Result<T, AlgorithmConfigError>;
62
63/// How a custom classifier turns the judge's JSON verdict into a target.
64#[derive(Clone, Debug, Deserialize)]
65#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
66pub enum ClassifierPolicyConfig {
67    /// Reads the target name straight out of the judge's verdict.
68    TargetSelector {
69        /// JSON Pointer to the name, such as `/decision/target`.
70        selector: String,
71    },
72}
73
74/// Which of the four `llm_classifier` behaviors a route uses.
75#[derive(Clone, Copy, Debug, Deserialize)]
76#[serde(rename_all = "snake_case")]
77pub enum ClassifierMode {
78    /// Judges the request first, then serves the strong or weak target.
79    Capability,
80    /// Serves the weak target first and judges the finished turn, moving to the
81    /// strong target once the session latches.
82    Escalation,
83    /// Judges against your own JSON schema and routes to any configured target.
84    Custom,
85    /// Asks a decision target to select one configured model group.
86    Direct,
87}
88
89impl ClassifierPolicyConfig {
90    fn into_libsy(self) -> CustomClassifierPolicy {
91        match self {
92            Self::TargetSelector { selector } => CustomClassifierPolicy::target_selector(selector),
93        }
94    }
95}
96
97#[derive(Clone, Debug)]
98enum LlmClassifierModeConfig {
99    Capability(CapabilityClassifierRouteConfig),
100    Escalation(EscalationClassifierRouteConfig),
101    Custom(CustomClassifierRouteConfig),
102    Direct {
103        models: CategoryModelConfig,
104        default_target: Category,
105        config: DirectClassifierConfig,
106    },
107}
108
109#[derive(Clone, Debug)]
110struct CapabilityClassifierRouteConfig {
111    classifier_target: String,
112    fail_open: bool,
113    strong_target: String,
114    weak_target: String,
115    judge: CapabilityJudgeRouteConfig,
116    classify_trigger: ClassifyTrigger,
117    message_hash_fallback: bool,
118    recent_turn_window: Option<usize>,
119}
120
121impl CapabilityClassifierRouteConfig {
122    fn into_task_config(self) -> TaskClassifierConfig {
123        let judge = match self.judge {
124            CapabilityJudgeRouteConfig::Llm(judge) => CapabilityJudgeConfig::Llm(judge),
125            CapabilityJudgeRouteConfig::Decision(judge) => {
126                let defaults = DecisionJudgeConfig::default();
127                CapabilityJudgeConfig::Decision(DecisionJudgeConfig {
128                    cutoff: judge.cutoff,
129                    instructions: judge.instructions,
130                    choices: judge.choices.unwrap_or(defaults.choices),
131                    apply_cutoff_to: judge.apply_cutoff_to.unwrap_or(defaults.apply_cutoff_to),
132                })
133            }
134        };
135        TaskClassifierConfig {
136            judge,
137            fail_open: self.fail_open,
138            classify_trigger: self.classify_trigger,
139            message_hash_fallback: self.message_hash_fallback,
140            recent_turn_window: self.recent_turn_window,
141        }
142    }
143}
144
145#[derive(Clone, Debug)]
146enum CapabilityJudgeRouteConfig {
147    Llm(LlmCapabilityConfig),
148    Decision(DecisionJudgeRouteConfig),
149}
150
151#[derive(Clone, Debug)]
152struct EscalationClassifierRouteConfig {
153    classifier_target: String,
154    strong_target: String,
155    weak_target: String,
156    prompt: Option<String>,
157    response_format_type: ClassifierResponseFormat,
158    max_output_tokens: u64,
159    judge_deadline_ms: Option<u64>,
160    judge: EscalationJudgeConfig,
161}
162
163#[derive(Clone, Debug)]
164struct CustomClassifierRouteConfig {
165    models: CategoryModelConfig,
166    default_target: Category,
167    prompt: String,
168    response_schema: String,
169    policy: ClassifierPolicyConfig,
170    classify_trigger: ClassifyTrigger,
171    message_hash_fallback: bool,
172    recent_turn_window: Option<usize>,
173    max_output_tokens: u64,
174    judge_deadline_ms: Option<u64>,
175}
176
177/// Runtime model groups for a custom classifier, keyed by group name.
178///
179/// `any` and `judge` are required; `capable` and `efficient` carry tier meaning
180/// when present. Any other key is a deployment-defined group the policy may
181/// select by name, which is what lets one route choose between more than two
182/// models. Ordered so error messages and derived target lists do not depend on
183/// hash iteration.
184#[derive(Clone, Debug, Default, Deserialize)]
185#[serde(transparent)]
186pub struct CategoryModelConfig(BTreeMap<String, Vec<String>>);
187
188impl CategoryModelConfig {
189    fn restrict_to(&mut self, allowed: &BTreeSet<&str>) {
190        for models in self.0.values_mut() {
191            models.retain(|model| allowed.contains(model.as_str()));
192        }
193    }
194
195    fn validate(&self, route_name: &str, default_target: &Category) -> AlgorithmResult<()> {
196        for category in [Category::Any, Category::Judge] {
197            if self.get(&category).is_empty() {
198                return Err(AlgorithmConfigError::new(format!(
199                    "llm_classifier route {route_name} models.{} must contain at least one target",
200                    category.as_str()
201                )));
202            }
203        }
204        if self.get(default_target).is_empty() {
205            return Err(AlgorithmConfigError::new(format!(
206                "llm_classifier route {route_name} models.{} must contain at least one target because it is the default_target",
207                default_target.as_str()
208            )));
209        }
210        // Every group name parses, so a typo would otherwise build fine and then
211        // abstain on every request. `any` is the fallback pool the router checks
212        // the selected target against, so a group outside it can never be served.
213        let any = self.get(&Category::Any);
214        for (name, models) in &self.0 {
215            if name == Category::Judge.as_str() || name == Category::Any.as_str() {
216                continue;
217            }
218            if let Some(missing) = models.iter().find(|model| !any.contains(model)) {
219                return Err(AlgorithmConfigError::new(format!(
220                    "llm_classifier route {route_name} models.{name} lists target {missing}, which must also appear in models.any"
221                )));
222            }
223        }
224        Ok(())
225    }
226
227    fn get(&self, category: &Category) -> &[String] {
228        self.0.get(category.as_str()).map_or(&[], Vec::as_slice)
229    }
230
231    /// Every configured target name, judge included.
232    fn all_names(&self) -> Vec<&str> {
233        Self::deduped(self.0.values().flatten())
234    }
235
236    /// The completion targets: every group except the judge's own candidates.
237    ///
238    /// `any` leads because it is the deployment's stated fallback order, and
239    /// callers read this order to pick a route's representative target.
240    fn routing_names(&self) -> Vec<&str> {
241        let others = self
242            .0
243            .iter()
244            .filter(|(name, _)| {
245                *name != Category::Judge.as_str() && *name != Category::Any.as_str()
246            })
247            .flat_map(|(_, models)| models);
248        Self::deduped(self.get(&Category::Any).iter().chain(others))
249    }
250
251    fn deduped<'a>(names: impl Iterator<Item = &'a String>) -> Vec<&'a str> {
252        let mut seen = BTreeSet::new();
253        names
254            .map(String::as_str)
255            .filter(|name| seen.insert(*name))
256            .collect()
257    }
258
259    fn groups(&self) -> impl Iterator<Item = (Category, Vec<String>)> + '_ {
260        self.0
261            .iter()
262            .filter_map(|(name, models)| Some((name.parse::<Category>().ok()?, models.clone())))
263    }
264}
265
266/// Routing by a decision model's choice probability.
267#[derive(Clone, Debug, Default, Deserialize)]
268#[serde(deny_unknown_fields)]
269pub struct DecisionJudgeRouteConfig {
270    /// Route capable when the `apply_cutoff_to` probability is strictly above
271    /// this cutoff. Uses the library default when omitted.
272    pub cutoff: Option<f64>,
273    /// Replaces the default decision instructions.
274    pub instructions: Option<String>,
275    /// Replaces the default `capable` and `efficient` choices.
276    pub choices: Option<Vec<DecisionChoice>>,
277    /// Choice ID whose probability is compared with the cutoff. Defaults to `capable`.
278    pub apply_cutoff_to: Option<String>,
279}
280
281/// Settings for an `llm_classifier` route. Which fields are required depends on
282/// the [`ClassifierMode`]; using a field from the wrong mode is an error.
283#[derive(Clone, Debug, Default, Deserialize)]
284#[serde(default, deny_unknown_fields)]
285pub struct LlmClassifierRouteConfig {
286    /// Target the judge is called through. Never a routing destination itself.
287    pub classifier_target: String,
288    /// Mode to run. Defaults to escalation when `escalation` is set, otherwise capability.
289    pub mode: Option<ClassifierMode>,
290    /// Capability and escalation modes: the capable tier.
291    pub strong_target: Option<String>,
292    /// Capability and escalation modes: the efficient tier.
293    pub weak_target: Option<String>,
294    /// Capability mode: lowest solve probability that still routes to the weak
295    /// target, from 0 to 1.
296    pub base_threshold: Option<f64>,
297    /// Capability mode: how much to raise the threshold when the judge is
298    /// uncertain. Added once for an uncertain verdict and twice for unsupported.
299    pub threshold_step: Option<f64>,
300    /// Capability mode: threshold steps for an unmatched verdict (no capability rule
301    /// applies). 1 by default, the same as uncertain; 2 treats it like unsupported.
302    pub unmatched_steps: Option<u8>,
303    /// Capability and direct modes: routes to the capable tier or `default_target` when
304    /// the judge call fails. Defaults to true in these modes.
305    pub fail_open: Option<bool>,
306    /// How often the judge runs: every request, once per user turn, or once per session.
307    pub classify_trigger: ClassifyTrigger,
308    /// Reuses the session's target by hashing the first user message when no
309    /// session ID is available. Needs `classify_trigger = "new_session"`.
310    pub message_hash_fallback: bool,
311    /// How many trailing turns the judge sees. Unset shows it the opening task
312    /// and the latest user follow-up only.
313    pub recent_turn_window: Option<usize>,
314    /// Replaces the packaged judge prompt. Required in custom mode.
315    pub prompt: Option<String>,
316    /// How the judge is asked for structured output. Use `json_object` when the
317    /// provider cannot do JSON Schema.
318    pub response_format_type: ClassifierResponseFormat,
319    /// Most completion tokens the judge verdict may use.
320    #[serde(default = "default_classifier_max_output_tokens")]
321    pub max_output_tokens: u64,
322    /// Whole-consultation bound on the judge call in milliseconds; expiry follows the
323    /// route's `fail_open` setting. Unset leaves the consultation unbounded.
324    #[serde(default)]
325    pub judge_deadline_ms: Option<u64>,
326    /// Escalation mode: how many escalate verdicts latch the session, and how
327    /// much of the transcript the judge sees.
328    pub escalation: Option<EscalationJudgeConfig>,
329    /// Capability mode: use a decision target as the judge, with a capable-or-efficient choice.
330    pub decision: Option<DecisionJudgeRouteConfig>,
331    /// Custom and direct modes: runtime model groups. In direct mode, every non-empty
332    /// group except `judge` and `any` is an option the decision target may select.
333    pub models: Option<CategoryModelConfig>,
334    /// Custom and direct modes: category used when the judge fails or its verdict
335    /// cannot be routed.
336    pub default_target: Option<String>,
337    /// Custom mode: JSON Schema the verdict must match, written as a string.
338    pub response_schema: Option<String>,
339    /// Custom mode: how to read the chosen target out of the verdict.
340    pub policy: Option<ClassifierPolicyConfig>,
341}
342
343/// Routing policy applied only to delegated sub-agent work, nested inside a
344/// `passthrough` or `stage_router` route.
345#[derive(Clone, Debug, Deserialize)]
346#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
347pub enum SubagentRouteConfig {
348    /// Sends all sub-agent work to one target.
349    Passthrough {
350        /// Target that serves sub-agent requests.
351        target: String,
352    },
353    /// Judges each sub-agent request. Only [`ClassifierMode::Custom`] is supported here.
354    LlmClassifier(Box<LlmClassifierRouteConfig>),
355}
356
357impl SubagentRouteConfig {
358    fn routing_target_names(&self) -> Vec<&str> {
359        match self {
360            Self::Passthrough { target } => vec![target],
361            Self::LlmClassifier(classifier) => classifier
362                .models
363                .as_ref()
364                .map(CategoryModelConfig::routing_names)
365                .unwrap_or_default(),
366        }
367    }
368
369    fn judge_target_names(&self) -> Vec<&str> {
370        match self {
371            Self::Passthrough { .. } => Vec::new(),
372            Self::LlmClassifier(classifier) => classifier
373                .models
374                .as_ref()
375                .map(|models| models.get(&Category::Judge))
376                .unwrap_or_default()
377                .iter()
378                .map(String::as_str)
379                .collect(),
380        }
381    }
382}
383
384/// A routing algorithm described by configured target names. Converting it to `&str` gives
385/// the route's `type`, such as `stage_router`.
386#[derive(Clone, Debug, Deserialize, IntoStaticStr)]
387#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
388#[strum(serialize_all = "snake_case")]
389pub enum AlgorithmSpec {
390    /// Replies `OK` without calling any model. Useful for smoke tests.
391    Noop {},
392    /// Splits traffic across several targets.
393    Random {
394        /// Target names to choose from.
395        targets: Vec<String>,
396        /// Relative weights in `targets` order. Equal weights when unset.
397        weights: Option<Vec<f64>>,
398        /// Makes the sequence of choices repeatable.
399        seed: Option<u64>,
400    },
401    /// Sends every request to one target.
402    Passthrough {
403        /// Target that serves the request.
404        target: String,
405        /// Separate policy for delegated sub-agent work.
406        #[serde(default)]
407        subagents: Option<SubagentRouteConfig>,
408    },
409    /// Asks a judge model which target should serve the request.
410    LlmClassifier {
411        /// Judge and tier settings, written directly in the route table.
412        #[serde(flatten)]
413        config: LlmClassifierRouteConfig,
414    },
415    /// Picks a tier per turn by scoring signals from recent tool results.
416    StageRouter {
417        capable_target: String,
418        efficient_target: String,
419        #[serde(default)]
420        capable_first_threshold: f64,
421        #[serde(flatten)]
422        settings: StageSettingsConfig,
423        /// Tier to use when the signals are not confident.
424        picker: PickerMode,
425        /// Judge consulted for turns the tool signals cannot decide.
426        #[serde(default)]
427        classifier: Option<StageClassifierConfig>,
428        /// Separate policy for delegated sub-agent work.
429        #[serde(default)]
430        subagents: Option<SubagentRouteConfig>,
431    },
432    /// Picks a routing strategy automatically, preset with recommended knobs.
433    /// Currently a `stage_router` with `picker = "efficient_first"` and
434    /// `confidence_threshold = 0.5`; change `build_algorithm`'s `Auto` arm to
435    /// repoint it at a different algorithm or preset.
436    Auto {
437        /// The capable tier.
438        capable_target: String,
439        /// The efficient tier.
440        efficient_target: String,
441    },
442    /// A judge picks the tier at each user turn; a stage router runs the turns within it.
443    Composite {
444        /// Judge that picks the tier. Called through its own target.
445        classifier: StageClassifierConfig,
446        /// The stage router the judge hands off to.
447        stage: StageTierConfig,
448        /// Settings for the profile selected by an efficient verdict.
449        #[serde(default)]
450        efficient: Option<Box<StageProfileConfig>>,
451        /// Settings for the profile selected by a capable verdict.
452        #[serde(default)]
453        capable: Option<Box<StageProfileConfig>>,
454        /// Separate policy for delegated sub-agent work.
455        #[serde(default)]
456        subagents: Option<SubagentRouteConfig>,
457    },
458    /// Serves every turn from one target, and has a second model review some of
459    /// those turns before the caller sees them.
460    Advisor {
461        /// Serves every client-visible turn.
462        executor_target: String,
463        /// Reviews gated turns. Never a routing destination.
464        advisor_target: String,
465        /// Replaces the built-in APPROVE/REDO reviewer prompt.
466        #[serde(default)]
467        reviewer_system_prompt: Option<String>,
468        /// Replaces the built-in text put in front of a REDO plan.
469        #[serde(default)]
470        redo_feedback_prefix: Option<String>,
471        /// What fires a review.
472        #[serde(default)]
473        gate_trigger: AdvisorTriggerConfig,
474        /// Regular expression for the `pattern` trigger. Required by it, and unused otherwise.
475        #[serde(default)]
476        gate_trigger_pattern: Option<String>,
477        /// How many reviews one session may spend.
478        #[serde(default = "default_max_reviews")]
479        max_reviews: u32,
480        /// Reviews a turn after this many assistant turns, as a mid-task
481        /// checkpoint. Zero turns the checkpoint off.
482        #[serde(default)]
483        gate_stall_turns: u32,
484        /// Tool results a turn needs before it can be reviewed. Skips early chatty turns.
485        #[serde(default)]
486        gate_min_tool_results: u32,
487        /// Most output tokens one review may use.
488        #[serde(default = "default_advisor_max_tokens")]
489        advisor_max_tokens: u64,
490        /// Sampling temperature for reviews. Left off the request when unset.
491        #[serde(default)]
492        advisor_temperature: Option<f64>,
493        /// Size cap on the transcript sent to the advisor. Longer transcripts
494        /// are trimmed from the middle.
495        #[serde(default = "default_transcript_max_chars")]
496        transcript_max_chars: usize,
497        /// Lets the turn through when the advisor fails, instead of erroring.
498        #[serde(default = "default_fail_open")]
499        fail_open: bool,
500    },
501    Vgr {
502        #[serde(flatten)]
503        config: VgrRouteConfig,
504    },
505    /// Routes using a checkpoint-backed prefill classifier.
506    PrefillRouter {
507        /// Target names in checkpoint output order.
508        targets: Vec<String>,
509        /// Tensor-only router checkpoint path.
510        checkpoint: PathBuf,
511        /// PyTorch device used for encoder inference, such as `cpu`, `cuda`, or
512        /// `cuda:0`. Auto-detected when omitted.
513        device: Option<String>,
514        /// Directory where Hugging Face caches the downloaded encoder and tokenizer.
515        cache_dir: Option<PathBuf>,
516        /// Maximum tokenized encoder input length; longer prompts are truncated.
517        max_length: Option<usize>,
518        /// Maximum prompts per encoder forward pass.
519        batch_size: Option<usize>,
520    },
521}
522
523#[derive(Clone, Debug, Deserialize)]
524#[serde(deny_unknown_fields)]
525pub struct VgrRouteConfig {
526    pub efficient_target: String,
527    pub capable_target: String,
528    /// Defaults to `efficient_target`.
529    #[serde(default)]
530    pub judge_target: Option<String>,
531    #[serde(default)]
532    pub capable_judge_target: Option<String>,
533    #[serde(default)]
534    pub mode: VgrModeConfig,
535    #[serde(default)]
536    pub active_approval: Option<String>,
537    #[serde(default = "default_vgr_deadline")]
538    pub deadline_seconds: f64,
539    /// Enforces VGR decision and efficient turn budgets. Defaults to true.
540    #[serde(default = "default_true")]
541    pub bounded_efficient: bool,
542    #[serde(default = "default_true")]
543    pub task_typing: bool,
544    #[serde(default = "default_vgr_breaker_threshold")]
545    pub breaker_threshold: u32,
546    #[serde(default = "default_vgr_breaker_cooldown")]
547    pub breaker_cooldown_seconds: f64,
548    /// Clean trailing tool results that let a long run recover on the capable judge.
549    #[serde(default)]
550    pub confirmed_recovery_min_clean_tail: Option<u32>,
551    /// Tells the capable tier it inherits unverified tool-using work.
552    #[serde(default)]
553    pub agentic_handoff: bool,
554    /// Condenses history from the efficient tier at handoff. Requires `agentic_handoff`.
555    #[serde(default)]
556    pub compact_handoff: bool,
557    /// Wall-clock budget for the efficient tier within one user turn.
558    #[serde(default)]
559    pub efficient_turn_budget_seconds: Option<f64>,
560    /// Holds escalations across later user turns.
561    #[serde(default)]
562    pub latch_escalation: bool,
563    /// Lets the efficient tier attempt requests that contain attachments.
564    #[serde(default)]
565    pub efficient_supports_attachments: bool,
566}
567
568#[derive(Clone, Debug, Default, Deserialize)]
569#[serde(rename_all = "snake_case")]
570pub enum VgrModeConfig {
571    #[default]
572    Off,
573    Evaluate,
574    Shadow,
575    Active,
576}
577
578/// What fires an advisor route's review.
579#[derive(Clone, Debug, Default, Deserialize, PartialEq)]
580#[serde(rename_all = "snake_case")]
581pub enum AdvisorTriggerConfig {
582    /// The executor's first turn without tool calls.
583    #[default]
584    NoToolCall,
585    /// The first turn whose text matches `gate_trigger_pattern`.
586    Pattern,
587}
588
589/// The judge a `stage_router` route falls through to, and how it routes.
590#[derive(Clone, Debug, Deserialize)]
591#[serde(deny_unknown_fields)]
592pub struct StageClassifierConfig {
593    /// Target the judge is called through. Not a routing destination.
594    pub target: String,
595    /// Composite accepts custom-schema judges as well as capability judges.
596    #[serde(default)]
597    pub mode: Option<ClassifierMode>,
598    #[serde(default)]
599    pub response_schema: Option<String>,
600    #[serde(default)]
601    pub policy: Option<ClassifierPolicyConfig>,
602    #[serde(default)]
603    pub decision: Option<DecisionJudgeRouteConfig>,
604    #[serde(default)]
605    pub fail_open: Option<bool>,
606    /// Lowest solve probability that still routes to the efficient tier, from 0 to 1.
607    pub base_threshold: Option<f64>,
608    /// How much to raise the threshold when the judge is uncertain. Added once
609    /// for an uncertain verdict and twice for unsupported.
610    #[serde(default)]
611    pub threshold_step: Option<f64>,
612    /// How often the judge runs. Composite honors it. A standalone stage route
613    /// rejects any value other than `every_request`, because its fallback judge
614    /// runs on every ambiguous turn and retains no verdict.
615    #[serde(default)]
616    pub classify_trigger: ClassifyTrigger,
617    /// Reuses the session's target by hashing the first user message when no
618    /// session ID is available.
619    #[serde(default)]
620    pub message_hash_fallback: bool,
621    /// How many trailing turns the judge sees. Unset shows it the opening task
622    /// and the latest user follow-up only.
623    #[serde(default)]
624    pub recent_turn_window: Option<usize>,
625    /// Replaces the packaged judge prompt.
626    #[serde(default)]
627    pub prompt: Option<String>,
628    /// How the judge is asked for structured output. Use `json_object` when the
629    /// provider cannot do JSON Schema.
630    #[serde(default)]
631    pub response_format_type: ClassifierResponseFormat,
632    /// Most completion tokens the judge verdict may use.
633    #[serde(default = "default_classifier_max_output_tokens")]
634    pub max_output_tokens: u64,
635    /// Whole-consultation bound on the judge call in milliseconds; expiry follows the
636    /// route's `fail_open` setting. Unset leaves the consultation unbounded.
637    #[serde(default)]
638    pub judge_deadline_ms: Option<u64>,
639}
640
641const COMPOSITE_PLANNING_PROMPT: &str = "You are in the planning phase. Inspect the task and the relevant code, then form a concrete implementation plan before modifying any files. Use read-only tools as needed. Do not make an edit until the plan is complete. After completing the plan, immediately make the first edit in the same task to hand execution off. Do not finish or return a final response with only the plan.";
642
643/// The shared model pair and defaults for composite stage profiles.
644#[derive(Clone, Debug, Deserialize)]
645#[serde(deny_unknown_fields)]
646pub struct StageTierConfig {
647    pub capable_target: String,
648    pub efficient_target: String,
649    #[serde(default)]
650    pub capable_first_threshold: f64,
651    #[serde(flatten)]
652    pub settings: StageSettingsConfig,
653}
654
655/// Settings shared by standalone stage routes and composite profiles.
656#[derive(Clone, Debug, Default, Deserialize)]
657#[serde(default, deny_unknown_fields)]
658pub struct StageSettingsConfig {
659    #[serde(alias = "efficient_first_threshold")]
660    pub confidence_threshold: Option<f64>,
661    pub recent_turn_window: Option<usize>,
662    pub tool_semantics: Option<ToolSemantics>,
663    pub compaction_override: Option<bool>,
664    pub capable_hold_turns: Option<i64>,
665    pub efficient_hold_turns: Option<i64>,
666    pub handoff_notes: Option<HandoffNoteConfig>,
667    pub capable_system_prompt: Option<String>,
668    pub efficient_system_prompt: Option<String>,
669}
670
671#[derive(Clone, Debug, Default, Deserialize)]
672#[serde(deny_unknown_fields)]
673pub struct StageProfileConfig {
674    pub classifier: Option<StageClassifierConfig>,
675    pub picker: Option<PickerMode>,
676    #[serde(flatten)]
677    pub settings: StageSettingsConfig,
678}
679
680impl StageSettingsConfig {
681    fn stage_config(&self, shared: &Self, mode: PickerMode, threshold: f64) -> StageRouterConfig {
682        let mut config =
683            StageRouterConfig::new(mode, self.confidence_threshold.unwrap_or(threshold));
684        config.recent_window = self.recent_turn_window.or(shared.recent_turn_window);
685        config.compaction_override = self
686            .compaction_override
687            .or(shared.compaction_override)
688            .unwrap_or(true);
689        config.tool_semantics = self
690            .tool_semantics
691            .as_ref()
692            .or(shared.tool_semantics.as_ref())
693            .cloned()
694            .unwrap_or_default();
695        config.capable_hold_turns = self
696            .capable_hold_turns
697            .or(shared.capable_hold_turns)
698            .unwrap_or(2);
699        config.efficient_hold_turns = self.efficient_hold_turns.or(shared.efficient_hold_turns);
700        config.handoff_notes = self
701            .handoff_notes
702            .as_ref()
703            .or(shared.handoff_notes.as_ref())
704            .cloned();
705        config.capable_system_prompt = self
706            .capable_system_prompt
707            .as_ref()
708            .or(shared.capable_system_prompt.as_ref())
709            .cloned();
710        config.efficient_system_prompt = self
711            .efficient_system_prompt
712            .as_ref()
713            .or(shared.efficient_system_prompt.as_ref())
714            .cloned();
715        config
716    }
717}
718
719impl StageTierConfig {
720    fn profile_config(
721        &self,
722        profile: &StageProfileConfig,
723        picker: PickerMode,
724    ) -> StageRouterConfig {
725        let threshold = match picker {
726            PickerMode::EfficientFirst => self.settings.confidence_threshold.unwrap_or(0.4),
727            PickerMode::CapableFirst => self.capable_first_threshold,
728        };
729        let mode = profile.picker.unwrap_or(picker);
730        let capable_first = mode == PickerMode::CapableFirst;
731        let mut config = profile
732            .settings
733            .stage_config(&self.settings, mode, threshold);
734        config.recent_window.get_or_insert(3);
735        config.capable_hold_turns = profile
736            .settings
737            .capable_hold_turns
738            .or(self.settings.capable_hold_turns)
739            .unwrap_or(if capable_first { 0 } else { 2 });
740        config
741            .efficient_hold_turns
742            .get_or_insert(if capable_first { -1 } else { 0 });
743        if capable_first {
744            config
745                .capable_system_prompt
746                .get_or_insert_with(|| COMPOSITE_PLANNING_PROMPT.into());
747        }
748        config
749    }
750
751    /// Warns when both tiers name one target; see [`warn_identical_tiers`].
752    fn warn_identical_tiers(&self, route_name: &str) {
753        warn_identical_tiers(route_name, &self.capable_target, &self.efficient_target);
754    }
755}
756
757impl StageClassifierConfig {
758    fn composite_judge_config(
759        &self,
760        route_name: &str,
761        capable: &str,
762        efficient: &str,
763    ) -> AlgorithmResult<CompositeJudgeConfig> {
764        if matches!(self.mode, Some(ClassifierMode::Custom)) {
765            return Ok(CompositeJudgeConfig::Custom(
766                self.custom_classifier_config(route_name)?,
767            ));
768        }
769        let mut config = self.task_classifier_config(route_name, capable, efficient)?;
770        if let CapabilityJudgeConfig::Decision(judge) = &mut config.judge {
771            judge.cutoff.get_or_insert(0.92);
772        }
773        Ok(CompositeJudgeConfig::Capability(config))
774    }
775
776    fn task_classifier_config(
777        &self,
778        route_name: &str,
779        capable_target: &str,
780        efficient_target: &str,
781    ) -> AlgorithmResult<TaskClassifierConfig> {
782        if self
783            .mode
784            .is_some_and(|mode| !matches!(mode, ClassifierMode::Capability))
785            || self.response_schema.is_some()
786            || self.policy.is_some()
787        {
788            return Err(AlgorithmConfigError::new(
789                "custom classifier settings require composite with mode = custom",
790            ));
791        }
792        let config = LlmClassifierRouteConfig {
793            classifier_target: self.target.clone(),
794            strong_target: Some(capable_target.to_string()),
795            weak_target: Some(efficient_target.to_string()),
796            base_threshold: self.base_threshold,
797            threshold_step: self.threshold_step,
798            fail_open: self.fail_open,
799            decision: self.decision.clone(),
800            classify_trigger: self.classify_trigger,
801            message_hash_fallback: self.message_hash_fallback,
802            recent_turn_window: self.recent_turn_window,
803            prompt: self.prompt.clone(),
804            response_format_type: self.response_format_type,
805            max_output_tokens: self.max_output_tokens,
806            judge_deadline_ms: self.judge_deadline_ms,
807            ..Default::default()
808        };
809        match config.validated_classifier_mode(route_name)? {
810            LlmClassifierModeConfig::Capability(config) => Ok(config.into_task_config()),
811            _ => Err(AlgorithmConfigError::new("expected a capability judge")),
812        }
813    }
814
815    fn infer_decision(
816        &mut self,
817        infer: &mut impl FnMut(&str, &mut Option<DecisionJudgeRouteConfig>),
818    ) {
819        if matches!(self.mode, None | Some(ClassifierMode::Capability)) {
820            infer(&self.target, &mut self.decision);
821        }
822    }
823
824    fn stage_fallback(
825        &self,
826        route_name: &str,
827        capable: &str,
828        efficient: &str,
829        targets: &BTreeMap<String, ModelId>,
830    ) -> AlgorithmResult<LlmFallback> {
831        Ok(LlmFallback {
832            target: Some(resolve_target_model_id(route_name, &self.target, targets)?),
833            config: self.task_classifier_config(route_name, capable, efficient)?,
834        })
835    }
836
837    fn custom_classifier_config(
838        &self,
839        route_name: &str,
840    ) -> AlgorithmResult<CustomClassifierConfig> {
841        if self.fail_open == Some(false) {
842            return Err(AlgorithmConfigError::new(
843                "composite custom classifiers always fail open; remove fail_open = false",
844            ));
845        }
846        if self.decision.is_some()
847            || self.base_threshold.is_some()
848            || self.threshold_step.is_some()
849            || self.response_format_type != ClassifierResponseFormat::JsonSchema
850        {
851            return Err(AlgorithmConfigError::new(
852                "composite custom classifier cannot use capability thresholds, decision settings, or response_format_type",
853            ));
854        }
855        let schema =
856            required_classifier_field(route_name, "response_schema", &self.response_schema)?;
857        let schema = serde_json::from_str(&schema).map_err(|error| {
858            AlgorithmConfigError::with_source(
859                format!("composite route {route_name}: response_schema is invalid JSON"),
860                error,
861            )
862        })?;
863        let mut config = CustomClassifierConfig::new(
864            required_classifier_field(route_name, "prompt", &self.prompt)?,
865            schema,
866            required_classifier_field(route_name, "policy", &self.policy)?.into_libsy(),
867        );
868        config.classify_trigger = self.classify_trigger;
869        config.message_hash_fallback = self.message_hash_fallback;
870        config.recent_turn_window = self.recent_turn_window;
871        config.max_output_tokens = self.max_output_tokens;
872        Ok(config)
873    }
874}
875
876impl AlgorithmSpec {
877    /// Filters configured pools without replacing required targets or changing their roles.
878    pub(crate) fn restricted_to(&self, allowed: &BTreeSet<&str>) -> AlgorithmResult<Self> {
879        let mut restricted = self.clone();
880        match &mut restricted {
881            Self::Random {
882                targets, weights, ..
883            } => {
884                if let Some(weights) = weights {
885                    if weights.len() != targets.len() {
886                        return Err(AlgorithmConfigError::new(format!(
887                            "random expected {} weights, got {}",
888                            targets.len(),
889                            weights.len()
890                        )));
891                    }
892                    // Keep weight positions paired with the original target order.
893                    let mut index = 0;
894                    weights.retain(|_| {
895                        let keep = allowed.contains(targets[index].as_str());
896                        index += 1;
897                        keep
898                    });
899                }
900                targets.retain(|target| allowed.contains(target.as_str()));
901                if targets.is_empty() {
902                    return Err(AlgorithmConfigError::new(
903                        "target requirements leave random without an eligible target".to_string(),
904                    ));
905                }
906            }
907            Self::LlmClassifier { config } => {
908                if let Some(models) = &mut config.models {
909                    models.restrict_to(allowed);
910                }
911            }
912            _ => {}
913        }
914        let subagents = match &mut restricted {
915            Self::Passthrough { subagents, .. }
916            | Self::StageRouter { subagents, .. }
917            | Self::Composite { subagents, .. } => subagents.as_mut(),
918            _ => None,
919        };
920        if let Some(SubagentRouteConfig::LlmClassifier(config)) = subagents
921            && let Some(models) = &mut config.models
922        {
923            models.restrict_to(allowed);
924        }
925        if let Some(target) = restricted
926            .callable_target_names()
927            .into_iter()
928            .find(|target| !allowed.contains(target))
929        {
930            return Err(AlgorithmConfigError::new(format!(
931                "required target {target} does not satisfy target requirements"
932            )));
933        }
934        Ok(restricted)
935    }
936
937    pub(crate) const fn supports_target_restrictions(&self) -> bool {
938        !matches!(self, Self::PrefillRouter { .. })
939    }
940
941    /// This iterator yields tier classifier targets and their optional decision settings.
942    /// It includes classifiers in nested Composite profiles.
943    /// Standalone custom and direct modes use model groups and are excluded.
944    pub(crate) fn classifier_targets(
945        &self,
946    ) -> impl Iterator<Item = (&str, Option<&DecisionJudgeRouteConfig>)> {
947        let (primary, profiles) = match self {
948            Self::LlmClassifier { config, .. }
949                if !matches!(
950                    config.classifier_mode(),
951                    ClassifierMode::Custom | ClassifierMode::Direct
952                ) =>
953            {
954                (
955                    Some((config.classifier_target.as_str(), config.decision.as_ref())),
956                    [None, None],
957                )
958            }
959            Self::Composite {
960                classifier,
961                efficient,
962                capable,
963                ..
964            } => (
965                Some((classifier.target.as_str(), classifier.decision.as_ref())),
966                [efficient.as_deref(), capable.as_deref()],
967            ),
968            Self::StageRouter { classifier, .. } => (
969                classifier
970                    .as_ref()
971                    .map(|c| (c.target.as_str(), c.decision.as_ref())),
972                [None, None],
973            ),
974            _ => (None, [None, None]),
975        };
976        primary.into_iter().chain(
977            profiles
978                .into_iter()
979                .flatten()
980                .filter_map(|profile| profile.classifier.as_ref())
981                .map(|c| (c.target.as_str(), c.decision.as_ref())),
982        )
983    }
984
985    /// Gives capability judges default decision settings when their target is a decision target.
986    pub(crate) fn infer_decision_judges(&mut self, is_decision_target: impl Fn(&str) -> bool) {
987        let mut infer = |target: &str, decision: &mut Option<DecisionJudgeRouteConfig>| {
988            if is_decision_target(target) {
989                decision.get_or_insert_with(Default::default);
990            }
991        };
992        match self {
993            Self::LlmClassifier { config }
994                if matches!(config.classifier_mode(), ClassifierMode::Capability) =>
995            {
996                infer(&config.classifier_target, &mut config.decision);
997            }
998            Self::StageRouter {
999                classifier: Some(classifier),
1000                ..
1001            } => classifier.infer_decision(&mut infer),
1002            Self::Composite {
1003                classifier,
1004                efficient,
1005                capable,
1006                ..
1007            } => {
1008                classifier.infer_decision(&mut infer);
1009                for profile in [efficient, capable].into_iter().flatten() {
1010                    if let Some(classifier) = &mut profile.classifier {
1011                        classifier.infer_decision(&mut infer);
1012                    }
1013                }
1014            }
1015            _ => {}
1016        }
1017    }
1018
1019    /// Judge targets that must be decision targets.
1020    pub(crate) fn decision_target_names(&self) -> Vec<&str> {
1021        let mut names: Vec<&str> = self
1022            .classifier_targets()
1023            .filter(|(_, decision)| decision.is_some())
1024            .map(|(target, _)| target)
1025            .collect();
1026        if let Self::LlmClassifier { config, .. } = self
1027            && matches!(config.classifier_mode(), ClassifierMode::Direct)
1028            && let Some(models) = &config.models
1029        {
1030            names.extend(models.get(&Category::Judge).iter().map(String::as_str));
1031        }
1032        names
1033    }
1034
1035    /// Completion targets in algorithm order; judge-only targets are excluded.
1036    pub fn routing_target_names(&self) -> Vec<&str> {
1037        match self {
1038            Self::Noop { .. } => Vec::new(),
1039            Self::Random { targets, .. } => targets.iter().map(String::as_str).collect(),
1040            Self::Passthrough {
1041                target, subagents, ..
1042            } => {
1043                let mut names = vec![target.as_str()];
1044                if let Some(subagents) = subagents {
1045                    names.extend(subagents.routing_target_names());
1046                }
1047                names
1048            }
1049            Self::LlmClassifier { config, .. } => match config.classifier_mode() {
1050                ClassifierMode::Capability => config
1051                    .weak_target
1052                    .iter()
1053                    .chain(&config.strong_target)
1054                    .map(String::as_str)
1055                    .collect(),
1056                ClassifierMode::Escalation => config
1057                    .strong_target
1058                    .iter()
1059                    .chain(&config.weak_target)
1060                    .map(String::as_str)
1061                    .collect(),
1062                ClassifierMode::Custom | ClassifierMode::Direct => config
1063                    .models
1064                    .as_ref()
1065                    .map(CategoryModelConfig::routing_names)
1066                    .unwrap_or_default(),
1067            },
1068            Self::StageRouter {
1069                capable_target,
1070                efficient_target,
1071                subagents,
1072                ..
1073            } => {
1074                let mut names = vec![capable_target.as_str(), efficient_target.as_str()];
1075                if let Some(subagents) = subagents {
1076                    names.extend(subagents.routing_target_names());
1077                }
1078                names
1079            }
1080            Self::Auto {
1081                capable_target,
1082                efficient_target,
1083            } => vec![capable_target.as_str(), efficient_target.as_str()],
1084            Self::Composite {
1085                stage, subagents, ..
1086            } => {
1087                let mut names = vec![
1088                    stage.capable_target.as_str(),
1089                    stage.efficient_target.as_str(),
1090                ];
1091                if let Some(subagents) = subagents {
1092                    names.extend(subagents.routing_target_names());
1093                }
1094                names
1095            }
1096            // The advisor is judge-only: reviews go through its own client,
1097            // so it is not a completion (or count_tokens) destination.
1098            Self::Advisor {
1099                executor_target, ..
1100            } => vec![executor_target],
1101            Self::Vgr { config } => {
1102                vec![
1103                    config.efficient_target.as_str(),
1104                    config.capable_target.as_str(),
1105                ]
1106            }
1107            Self::PrefillRouter { targets, .. } => targets.iter().map(String::as_str).collect(),
1108        }
1109    }
1110
1111    /// Every target the algorithm may call, including judge-only targets.
1112    ///
1113    /// [`routing_target_names`](Self::routing_target_names) covers completion destinations;
1114    /// a classifier also calls its judge, and that call needs a client too.
1115    pub fn callable_target_names(&self) -> Vec<&str> {
1116        let mut names = self.routing_target_names();
1117        names.extend(self.judge_target_names());
1118        names
1119    }
1120
1121    /// Targets the algorithm calls only to decide, such as a judge or an advisor. A target
1122    /// that also answers requests appears in [`routing_target_names`](Self::routing_target_names) too.
1123    pub fn judge_target_names(&self) -> Vec<&str> {
1124        let mut names = Vec::new();
1125        match self {
1126            // Custom and direct modes name their judge in `models.judge`; the other
1127            // two modes use the top-level `classifier_target`.
1128            Self::LlmClassifier { config, .. } => {
1129                if matches!(
1130                    config.classifier_mode(),
1131                    ClassifierMode::Custom | ClassifierMode::Direct
1132                ) {
1133                    names.extend(
1134                        config
1135                            .models
1136                            .as_ref()
1137                            .map(|models| models.get(&Category::Judge))
1138                            .unwrap_or_default()
1139                            .iter()
1140                            .map(String::as_str),
1141                    );
1142                } else {
1143                    names.push(config.classifier_target.as_str());
1144                }
1145            }
1146            Self::StageRouter { .. } | Self::Composite { .. } => {
1147                names.extend(self.classifier_targets().map(|(target, _)| target));
1148            }
1149            Self::Advisor { advisor_target, .. } => names.push(advisor_target),
1150            Self::Vgr { config } => {
1151                names.extend(config.judge_target.as_deref());
1152                names.extend(config.capable_judge_target.as_deref());
1153            }
1154            _ => {}
1155        }
1156        // A sub-agent classifier calls its own judge, which is never a completion target.
1157        if let Self::Passthrough {
1158            subagents: Some(subagents),
1159            ..
1160        }
1161        | Self::StageRouter {
1162            subagents: Some(subagents),
1163            ..
1164        }
1165        | Self::Composite {
1166            subagents: Some(subagents),
1167            ..
1168        } = self
1169        {
1170            names.extend(subagents.judge_target_names());
1171        }
1172        names
1173    }
1174
1175    /// Target names grouped as the runtime [`Driver`](libsy::Driver) expects them.
1176    fn runtime_model_names(&self, route_name: &str) -> AlgorithmResult<RuntimeModelNames> {
1177        let parent = match self {
1178            Self::Noop { .. } => HashMap::new(),
1179            Self::Random { targets, .. } | Self::PrefillRouter { targets, .. } => {
1180                category_models([(Category::Any, targets.clone())])
1181            }
1182            Self::Passthrough { target, .. } => {
1183                category_models([(Category::Any, vec![target.clone()])])
1184            }
1185            Self::LlmClassifier { config } => {
1186                classifier_runtime_model_names(config.validated_classifier_mode(route_name)?)
1187            }
1188            Self::StageRouter {
1189                capable_target,
1190                efficient_target,
1191                classifier,
1192                ..
1193            } => {
1194                let mut models = category_models([
1195                    (Category::Capable, vec![capable_target.clone()]),
1196                    (Category::Efficient, vec![efficient_target.clone()]),
1197                    (
1198                        Category::Any,
1199                        vec![capable_target.clone(), efficient_target.clone()],
1200                    ),
1201                ]);
1202                if let Some(classifier) = classifier {
1203                    models.insert(Category::Judge, vec![classifier.target.clone()]);
1204                }
1205                models
1206            }
1207            Self::Auto {
1208                capable_target,
1209                efficient_target,
1210            } => category_models([
1211                (Category::Capable, vec![capable_target.clone()]),
1212                (Category::Efficient, vec![efficient_target.clone()]),
1213                (
1214                    Category::Any,
1215                    vec![capable_target.clone(), efficient_target.clone()],
1216                ),
1217            ]),
1218            Self::Composite { stage, .. } => category_models([
1219                (
1220                    Category::Judge,
1221                    self.judge_target_names()
1222                        .into_iter()
1223                        .map(str::to_string)
1224                        .collect(),
1225                ),
1226                (Category::Capable, vec![stage.capable_target.clone()]),
1227                (Category::Efficient, vec![stage.efficient_target.clone()]),
1228                (
1229                    Category::Any,
1230                    vec![stage.capable_target.clone(), stage.efficient_target.clone()],
1231                ),
1232            ]),
1233            Self::Advisor {
1234                executor_target,
1235                advisor_target,
1236                ..
1237            } => category_models([
1238                (Category::Efficient, vec![executor_target.clone()]),
1239                (Category::Any, vec![executor_target.clone()]),
1240                (Category::Judge, vec![advisor_target.clone()]),
1241            ]),
1242            Self::Vgr { config } => {
1243                let judge = config
1244                    .judge_target
1245                    .as_ref()
1246                    .unwrap_or(&config.efficient_target);
1247                let judges = std::iter::once(judge)
1248                    .chain(&config.capable_judge_target)
1249                    .cloned()
1250                    .collect();
1251                category_models([
1252                    (Category::Efficient, vec![config.efficient_target.clone()]),
1253                    (Category::Capable, vec![config.capable_target.clone()]),
1254                    (
1255                        Category::Any,
1256                        vec![
1257                            config.efficient_target.clone(),
1258                            config.capable_target.clone(),
1259                        ],
1260                    ),
1261                    (Category::Judge, judges),
1262                ])
1263            }
1264        };
1265
1266        let subagents = match self {
1267            Self::Passthrough { subagents, .. }
1268            | Self::StageRouter { subagents, .. }
1269            | Self::Composite { subagents, .. } => subagents.as_ref(),
1270            _ => None,
1271        };
1272        // Sub-agent groups stay separate from the parent's. Merging them would let a
1273        // sub-agent's `capable` resolve to the parent's, and would put models only the
1274        // sub-agents were given into the parent's `Any` fallback list.
1275        let subagent = subagents
1276            .map(|subagents| subagent_runtime_model_names(subagents, route_name))
1277            .transpose()?;
1278        Ok(RuntimeModelNames { parent, subagent })
1279    }
1280
1281    /// Response target and routing-only dependency for routers that answer while routing.
1282    #[cfg(not(target_os = "wasi"))]
1283    pub(crate) fn routing_response_and_dependency(&self) -> Option<(&str, &str)> {
1284        match self {
1285            Self::LlmClassifier { config, .. }
1286                if matches!(config.classifier_mode(), ClassifierMode::Escalation) =>
1287            {
1288                Some((
1289                    config.weak_target.as_deref()?,
1290                    config.classifier_target.as_str(),
1291                ))
1292            }
1293            Self::Advisor {
1294                executor_target,
1295                advisor_target,
1296                ..
1297            } => Some((executor_target, advisor_target)),
1298            Self::Vgr { config } => Some((
1299                &config.efficient_target,
1300                config
1301                    .judge_target
1302                    .as_deref()
1303                    .unwrap_or(&config.efficient_target),
1304            )),
1305            Self::Noop { .. }
1306            | Self::Random { .. }
1307            | Self::Passthrough { .. }
1308            | Self::LlmClassifier { .. }
1309            | Self::StageRouter { .. }
1310            | Self::Auto { .. }
1311            | Self::Composite { .. }
1312            | Self::PrefillRouter { .. } => None,
1313        }
1314    }
1315
1316    /// Builds this algorithm after resolving configured target names.
1317    pub fn build(
1318        &self,
1319        route_name: &str,
1320        targets: &BTreeMap<String, ModelId>,
1321    ) -> AlgorithmResult<Arc<dyn Algorithm>> {
1322        build_algorithm(route_name, self, targets)
1323    }
1324
1325    /// Resolves target names to host model IDs and builds the algorithm and runtime groups.
1326    pub fn build_with_runtime_models(
1327        &self,
1328        route_name: &str,
1329        targets: &BTreeMap<String, ModelId>,
1330    ) -> AlgorithmResult<(Arc<dyn Algorithm>, RuntimeModels)> {
1331        let algorithm = self.build(route_name, targets)?;
1332        let names = self.runtime_model_names(route_name)?;
1333        let mut models =
1334            RuntimeModels::new(resolve_runtime_models(route_name, names.parent, targets)?);
1335        if let Some(subagent) = names.subagent {
1336            models = models.with_subagent(resolve_runtime_models(route_name, subagent, targets)?);
1337        }
1338        Ok((algorithm, models))
1339    }
1340}
1341
1342/// One route's target names, grouped by category and by routing scope.
1343struct RuntimeModelNames {
1344    /// Groups the algorithm itself routes over.
1345    parent: HashMap<Category, Vec<String>>,
1346    /// Groups delegated sub-agent work routes over, when the route has a `subagents` table.
1347    subagent: Option<HashMap<Category, Vec<String>>>,
1348}
1349
1350fn category_models(
1351    entries: impl IntoIterator<Item = (Category, Vec<String>)>,
1352) -> HashMap<Category, Vec<String>> {
1353    entries.into_iter().collect()
1354}
1355
1356fn custom_runtime_model_names(config: &CategoryModelConfig) -> HashMap<Category, Vec<String>> {
1357    config.groups().collect()
1358}
1359
1360fn classifier_runtime_model_names(
1361    config: LlmClassifierModeConfig,
1362) -> HashMap<Category, Vec<String>> {
1363    match config {
1364        LlmClassifierModeConfig::Capability(config) => category_models([
1365            (Category::Judge, vec![config.classifier_target]),
1366            (Category::Efficient, vec![config.weak_target.clone()]),
1367            (Category::Capable, vec![config.strong_target.clone()]),
1368            (
1369                Category::Any,
1370                vec![config.weak_target, config.strong_target],
1371            ),
1372        ]),
1373        LlmClassifierModeConfig::Escalation(config) => category_models([
1374            (Category::Judge, vec![config.classifier_target]),
1375            (Category::Efficient, vec![config.weak_target.clone()]),
1376            (Category::Capable, vec![config.strong_target.clone()]),
1377            (
1378                Category::Any,
1379                vec![config.strong_target, config.weak_target],
1380            ),
1381        ]),
1382        LlmClassifierModeConfig::Custom(config) => custom_runtime_model_names(&config.models),
1383        LlmClassifierModeConfig::Direct { models, .. } => custom_runtime_model_names(&models),
1384    }
1385}
1386
1387fn subagent_runtime_model_names(
1388    config: &SubagentRouteConfig,
1389    route_name: &str,
1390) -> AlgorithmResult<HashMap<Category, Vec<String>>> {
1391    match config {
1392        SubagentRouteConfig::Passthrough { target } => {
1393            Ok(category_models([(Category::Any, vec![target.clone()])]))
1394        }
1395        SubagentRouteConfig::LlmClassifier(config) => {
1396            let LlmClassifierModeConfig::Custom(config) =
1397                config.validated_classifier_mode(route_name)?
1398            else {
1399                return Err(AlgorithmConfigError::new(format!(
1400                    "route {route_name}: subagents llm_classifier only supports mode custom"
1401                )));
1402            };
1403            Ok(custom_runtime_model_names(&config.models))
1404        }
1405    }
1406}
1407impl LlmClassifierRouteConfig {
1408    fn classifier_mode(&self) -> ClassifierMode {
1409        let default = if self.escalation.is_some() {
1410            ClassifierMode::Escalation
1411        } else {
1412            ClassifierMode::Capability
1413        };
1414        self.mode.unwrap_or(default)
1415    }
1416
1417    fn validated_classifier_mode(
1418        &self,
1419        route_name: &str,
1420    ) -> AlgorithmResult<LlmClassifierModeConfig> {
1421        let Self {
1422            classifier_target,
1423            mode,
1424            strong_target,
1425            weak_target,
1426            base_threshold,
1427            threshold_step,
1428            unmatched_steps,
1429            fail_open,
1430            classify_trigger,
1431            message_hash_fallback,
1432            recent_turn_window,
1433            prompt,
1434            response_format_type,
1435            max_output_tokens,
1436            judge_deadline_ms,
1437            escalation,
1438            decision,
1439            models,
1440            default_target,
1441            response_schema,
1442            policy,
1443        } = self;
1444
1445        let selected_mode = match (mode, escalation.is_some()) {
1446            (Some(mode), _) => *mode,
1447            (None, true) => ClassifierMode::Escalation,
1448            (None, false) => ClassifierMode::Capability,
1449        };
1450
1451        if decision.is_some() && !matches!(selected_mode, ClassifierMode::Capability) {
1452            return Err(AlgorithmConfigError::new(format!(
1453                "llm_classifier route {route_name}: decision requires capability mode"
1454            )));
1455        }
1456
1457        if !matches!(
1458            selected_mode,
1459            ClassifierMode::Capability | ClassifierMode::Direct
1460        ) && *fail_open == Some(true)
1461        {
1462            return Err(AlgorithmConfigError::new(format!(
1463                "llm_classifier route {route_name}: fail_open = true requires capability or direct mode"
1464            )));
1465        }
1466
1467        match selected_mode {
1468            ClassifierMode::Capability => {
1469                if escalation.is_some() {
1470                    return Err(classifier_field_error(
1471                        route_name,
1472                        "escalation",
1473                        "capability",
1474                    ));
1475                }
1476                reject_custom_fields(
1477                    route_name,
1478                    "capability",
1479                    models,
1480                    default_target,
1481                    response_schema,
1482                    policy,
1483                )?;
1484                let judge = if let Some(decision) = decision {
1485                    if base_threshold.is_some()
1486                        || threshold_step.is_some()
1487                        || unmatched_steps.is_some()
1488                        || prompt.is_some()
1489                        || *response_format_type != ClassifierResponseFormat::JsonSchema
1490                        || *max_output_tokens != default_classifier_max_output_tokens()
1491                        || judge_deadline_ms.is_some()
1492                    {
1493                        return Err(AlgorithmConfigError::new(format!(
1494                            "llm_classifier route {route_name}: decision cannot use LLM judge settings; use decision.cutoff and decision.instructions"
1495                        )));
1496                    }
1497                    CapabilityJudgeRouteConfig::Decision(decision.clone())
1498                } else {
1499                    CapabilityJudgeRouteConfig::Llm(LlmCapabilityConfig {
1500                        base_threshold: required_classifier_field(
1501                            route_name,
1502                            "base_threshold",
1503                            base_threshold,
1504                        )?,
1505                        threshold_step: threshold_step.unwrap_or_default(),
1506                        unmatched_steps: unmatched_steps.unwrap_or(DEFAULT_UNMATCHED_STEPS),
1507                        contract: classifier_contract(prompt.as_deref())
1508                            .with_response_format_type(*response_format_type),
1509                        max_output_tokens: *max_output_tokens,
1510                        judge_deadline_ms: *judge_deadline_ms,
1511                    })
1512                };
1513                Ok(LlmClassifierModeConfig::Capability(
1514                    CapabilityClassifierRouteConfig {
1515                        classifier_target: classifier_target.clone(),
1516                        fail_open: fail_open.unwrap_or(true),
1517                        strong_target: required_classifier_field(
1518                            route_name,
1519                            "strong_target",
1520                            strong_target,
1521                        )?,
1522                        weak_target: required_classifier_field(
1523                            route_name,
1524                            "weak_target",
1525                            weak_target,
1526                        )?,
1527                        judge,
1528                        classify_trigger: *classify_trigger,
1529                        message_hash_fallback: *message_hash_fallback,
1530                        recent_turn_window: *recent_turn_window,
1531                    },
1532                ))
1533            }
1534            ClassifierMode::Escalation => {
1535                reject_custom_fields(
1536                    route_name,
1537                    "escalation",
1538                    models,
1539                    default_target,
1540                    response_schema,
1541                    policy,
1542                )?;
1543                if *classify_trigger != ClassifyTrigger::EveryRequest {
1544                    return Err(AlgorithmConfigError::new(format!(
1545                        "llm_classifier route {route_name} mode escalation cannot use classify_trigger"
1546                    )));
1547                }
1548                let has_capability_settings = base_threshold.is_some()
1549                    || threshold_step.is_some()
1550                    || fail_open.is_some()
1551                    || *message_hash_fallback
1552                    || recent_turn_window.is_some();
1553                // `unmatched_steps` is new, so no existing escalation configuration carries it:
1554                // reject it even when the mode is implied by `escalation`. The older capability
1555                // keys stay tolerated in that implicit form for compatibility.
1556                if unmatched_steps.is_some() || (mode.is_some() && has_capability_settings) {
1557                    return Err(AlgorithmConfigError::new(format!(
1558                        "llm_classifier route {route_name} mode escalation cannot use capability routing settings"
1559                    )));
1560                }
1561                if has_capability_settings {
1562                    // Existing files that select escalation through the `escalation` table alone
1563                    // keep loading, but their capability keys do nothing in this mode.
1564                    tracing::warn!(
1565                        "llm_classifier route {route_name} runs in escalation mode because it has an escalation table; base_threshold, threshold_step, fail_open, recent_turn_window and message_hash_fallback are ignored in this mode. Set mode = \"escalation\" and remove them."
1566                    );
1567                }
1568                Ok(LlmClassifierModeConfig::Escalation(
1569                    EscalationClassifierRouteConfig {
1570                        classifier_target: classifier_target.clone(),
1571                        strong_target: required_classifier_field(
1572                            route_name,
1573                            "strong_target",
1574                            strong_target,
1575                        )?,
1576                        weak_target: required_classifier_field(
1577                            route_name,
1578                            "weak_target",
1579                            weak_target,
1580                        )?,
1581                        prompt: prompt.clone(),
1582                        response_format_type: *response_format_type,
1583                        max_output_tokens: *max_output_tokens,
1584                        judge_deadline_ms: *judge_deadline_ms,
1585                        judge: required_classifier_field(route_name, "escalation", escalation)?,
1586                    },
1587                ))
1588            }
1589            ClassifierMode::Custom => {
1590                if !classifier_target.is_empty()
1591                    || strong_target.is_some()
1592                    || weak_target.is_some()
1593                    || base_threshold.is_some()
1594                    || threshold_step.is_some()
1595                    || unmatched_steps.is_some()
1596                    || escalation.is_some()
1597                    || *response_format_type != ClassifierResponseFormat::JsonSchema
1598                {
1599                    return Err(AlgorithmConfigError::new(format!(
1600                        "llm_classifier route {route_name} mode custom cannot use capability or escalation fields and response_format_type must be 'json_schema'"
1601                    )));
1602                }
1603                let (models, default_target) =
1604                    validated_models(route_name, models, default_target)?;
1605                Ok(LlmClassifierModeConfig::Custom(
1606                    CustomClassifierRouteConfig {
1607                        models,
1608                        default_target,
1609                        prompt: required_classifier_field(route_name, "prompt", prompt)?,
1610                        response_schema: required_classifier_field(
1611                            route_name,
1612                            "response_schema",
1613                            response_schema,
1614                        )?,
1615                        policy: required_classifier_field(route_name, "policy", policy)?,
1616                        classify_trigger: *classify_trigger,
1617                        message_hash_fallback: *message_hash_fallback,
1618                        recent_turn_window: *recent_turn_window,
1619                        max_output_tokens: *max_output_tokens,
1620                        judge_deadline_ms: *judge_deadline_ms,
1621                    },
1622                ))
1623            }
1624            ClassifierMode::Direct => {
1625                if !classifier_target.is_empty()
1626                    || strong_target.is_some()
1627                    || weak_target.is_some()
1628                    || base_threshold.is_some()
1629                    || threshold_step.is_some()
1630                    || unmatched_steps.is_some()
1631                    || escalation.is_some()
1632                    || prompt.is_some()
1633                    || response_schema.is_some()
1634                    || policy.is_some()
1635                    || *response_format_type != ClassifierResponseFormat::JsonSchema
1636                    || *max_output_tokens != default_classifier_max_output_tokens()
1637                    || judge_deadline_ms.is_some()
1638                {
1639                    return Err(AlgorithmConfigError::new(format!(
1640                        "llm_classifier route {route_name} mode direct cannot use capability, escalation, or LLM judge fields"
1641                    )));
1642                }
1643                let (models, default_target) =
1644                    validated_models(route_name, models, default_target)?;
1645                let options = models
1646                    .groups()
1647                    .filter(|(category, targets)| {
1648                        !targets.is_empty() && !matches!(category, Category::Judge | Category::Any)
1649                    })
1650                    .map(|(category, _)| category)
1651                    .collect();
1652                Ok(LlmClassifierModeConfig::Direct {
1653                    models,
1654                    default_target,
1655                    config: DirectClassifierConfig {
1656                        options,
1657                        fail_open: fail_open.unwrap_or(true),
1658                        classify_trigger: *classify_trigger,
1659                        message_hash_fallback: *message_hash_fallback,
1660                        recent_turn_window: *recent_turn_window,
1661                    },
1662                })
1663            }
1664        }
1665    }
1666}
1667
1668fn validated_models(
1669    route_name: &str,
1670    models: &Option<CategoryModelConfig>,
1671    default_target: &Option<String>,
1672) -> AlgorithmResult<(CategoryModelConfig, Category)> {
1673    let models = required_classifier_field(route_name, "models", models)?;
1674    let default_target: Category =
1675        required_classifier_field(route_name, "default_target", default_target)?
1676            .parse()
1677            .map_err(|error| {
1678                AlgorithmConfigError::new(format!(
1679                    "llm_classifier route {route_name} has invalid default_target: {error}"
1680                ))
1681            })?;
1682    if default_target == Category::Judge {
1683        return Err(AlgorithmConfigError::new(format!(
1684            "llm_classifier route {route_name} default_target cannot be judge"
1685        )));
1686    }
1687    models.validate(route_name, &default_target)?;
1688    Ok((models, default_target))
1689}
1690
1691fn reject_custom_fields(
1692    route_name: &str,
1693    mode: &str,
1694    models: &Option<CategoryModelConfig>,
1695    default_target: &Option<String>,
1696    response_schema: &Option<String>,
1697    policy: &Option<ClassifierPolicyConfig>,
1698) -> AlgorithmResult<()> {
1699    if models.is_some() || default_target.is_some() || response_schema.is_some() || policy.is_some()
1700    {
1701        return Err(AlgorithmConfigError::new(format!(
1702            "llm_classifier route {route_name} mode {mode} cannot use custom classifier fields"
1703        )));
1704    }
1705    Ok(())
1706}
1707
1708fn classifier_field_error(route_name: &str, field: &str, mode: &str) -> AlgorithmConfigError {
1709    AlgorithmConfigError::new(format!(
1710        "llm_classifier route {route_name} mode {mode} cannot use {field}"
1711    ))
1712}
1713
1714fn required_classifier_field<T: Clone>(
1715    route_name: &str,
1716    field: &str,
1717    value: &Option<T>,
1718) -> AlgorithmResult<T> {
1719    value.clone().ok_or_else(|| {
1720        AlgorithmConfigError::new(format!(
1721            "llm_classifier route {route_name} requires {field}"
1722        ))
1723    })
1724}
1725
1726fn build_subagent_router_config(
1727    route_name: &str,
1728    config: &SubagentRouteConfig,
1729    targets: &BTreeMap<String, ModelId>,
1730) -> AlgorithmResult<SubagentRouterConfig> {
1731    match config {
1732        SubagentRouteConfig::Passthrough { target } => {
1733            resolve_target_model_id(route_name, target, targets)?;
1734            Ok(SubagentRouterConfig::fixed_target())
1735        }
1736        SubagentRouteConfig::LlmClassifier(config) => {
1737            let LlmClassifierModeConfig::Custom(config) =
1738                config.validated_classifier_mode(route_name)?
1739            else {
1740                return Err(AlgorithmConfigError::new(format!(
1741                    "route {route_name}: subagents llm_classifier only supports mode custom"
1742                )));
1743            };
1744            for name in config.models.all_names() {
1745                resolve_target_model_id(route_name, name, targets)?;
1746            }
1747            if config.models.get(&config.default_target).is_empty() {
1748                return Err(AlgorithmConfigError::new(format!(
1749                    "route {route_name}: subagents llm_classifier has no model for default category {}",
1750                    config.default_target.as_str()
1751                )));
1752            }
1753            let response_schema =
1754                serde_json::from_str(&config.response_schema).map_err(|error| {
1755                    AlgorithmConfigError::with_source(
1756                        format!(
1757                            "route {route_name}: subagents llm_classifier response_schema is invalid JSON: {error}"
1758                        ),
1759                        error,
1760                    )
1761                })?;
1762            warn_single_target_classifier(route_name, &config.models);
1763            let mut classifier_config = CustomClassifierConfig::new(
1764                config.prompt,
1765                response_schema,
1766                config.policy.into_libsy(),
1767            );
1768            classifier_config.recent_turn_window = config.recent_turn_window;
1769            classifier_config.max_output_tokens = config.max_output_tokens;
1770            classifier_config.judge_deadline_ms = config.judge_deadline_ms;
1771            let classifier = Arc::new(
1772                LlmTaskClassifier::new(LlmClassifierConfig::Custom {
1773                    default_target: config.default_target.clone(),
1774                    config: classifier_config,
1775                })
1776                .map_err(|error| {
1777                    AlgorithmConfigError::with_source(
1778                        format!("route {route_name}: subagents llm_classifier: {error}"),
1779                        error,
1780                    )
1781                })?,
1782            );
1783            Ok(SubagentRouterConfig {
1784                classifier,
1785                default_target: config.default_target,
1786                classify_trigger: config.classify_trigger,
1787                message_hash_fallback: config.message_hash_fallback,
1788            })
1789        }
1790    }
1791}
1792
1793fn attach_subagent_router(
1794    route_name: &str,
1795    parent: Arc<dyn Algorithm>,
1796    config: Option<&SubagentRouteConfig>,
1797    targets: &BTreeMap<String, ModelId>,
1798) -> AlgorithmResult<Arc<dyn Algorithm>> {
1799    let Some(config) = config else {
1800        return Ok(parent);
1801    };
1802    let config = build_subagent_router_config(route_name, config, targets)?;
1803    let algorithm = SubagentRouter::new(parent, config).map_err(|error| {
1804        AlgorithmConfigError::with_source(
1805            format!("route {route_name}: subagent routing: {error}"),
1806            error,
1807        )
1808    })?;
1809    Ok(Arc::new(algorithm))
1810}
1811
1812/// `build_algorithm` builds the configured algorithm and attaches supported subagent routing.
1813/// It returns errors for invalid settings or failed target lookups during construction.
1814/// `AlgorithmSpec::build_with_runtime_models` also resolves the runtime model groups.
1815fn build_algorithm(
1816    route_name: &str,
1817    config: &AlgorithmSpec,
1818    targets: &BTreeMap<String, ModelId>,
1819) -> AlgorithmResult<Arc<dyn Algorithm>> {
1820    match config {
1821        AlgorithmSpec::Noop { .. } => Ok(Arc::new(Noop {})),
1822        AlgorithmSpec::Random {
1823            targets: names,
1824            weights,
1825            seed,
1826        } => {
1827            // The algorithm only sees its targets at request time, so a bad pairing
1828            // would otherwise fail every request instead of failing to start.
1829            if let Some(weights) = weights
1830                && weights.len() != names.len()
1831            {
1832                return Err(AlgorithmConfigError::new(format!(
1833                    "random route {route_name}: expected {} weights, got {}",
1834                    names.len(),
1835                    weights.len()
1836                )));
1837            }
1838            let mut seen = BTreeSet::new();
1839            if let Some(duplicate) = names.iter().find(|name| !seen.insert(*name)) {
1840                return Err(AlgorithmConfigError::new(format!(
1841                    "random route {route_name}: targets must be unique, {duplicate} is repeated"
1842                )));
1843            }
1844            let algorithm = Random::new(weights.clone(), *seed).map_err(|error| {
1845                AlgorithmConfigError::with_source(
1846                    format!("random route {route_name}: {error}"),
1847                    error,
1848                )
1849            })?;
1850            Ok(Arc::new(algorithm))
1851        }
1852        AlgorithmSpec::Passthrough { subagents, .. } => {
1853            let algorithm = Passthrough;
1854            let parent: Arc<dyn Algorithm> = Arc::new(algorithm);
1855            attach_subagent_router(route_name, parent, subagents.as_ref(), targets)
1856        }
1857        AlgorithmSpec::LlmClassifier {
1858            config: classifier_config,
1859            ..
1860        } => {
1861            let mode = classifier_config.validated_classifier_mode(route_name)?;
1862            let algorithm = match mode {
1863                LlmClassifierModeConfig::Capability(config) => {
1864                    let classifier_config = config.into_task_config();
1865                    LlmTaskClassifier::new(LlmClassifierConfig::Capability {
1866                        config: classifier_config,
1867                    })
1868                }
1869                LlmClassifierModeConfig::Escalation(config) => {
1870                    LlmTaskClassifier::new(LlmClassifierConfig::Escalation {
1871                        contract: classifier_contract(config.prompt.as_deref())
1872                            .with_response_format_type(config.response_format_type),
1873                        config: config.judge,
1874                        max_output_tokens: config.max_output_tokens,
1875                        judge_deadline_ms: config.judge_deadline_ms,
1876                    })
1877                }
1878                LlmClassifierModeConfig::Custom(config) => {
1879                    let response_schema = serde_json::from_str(&config.response_schema).map_err(
1880                        |error| {
1881                            AlgorithmConfigError::with_source(
1882                                format!(
1883                                    "llm_classifier route {route_name}: response_schema is invalid JSON: {error}"
1884                                ),
1885                                error,
1886                            )
1887                        },
1888                    )?;
1889                    warn_single_target_classifier(route_name, &config.models);
1890                    let mut classifier_config = CustomClassifierConfig::new(
1891                        config.prompt,
1892                        response_schema,
1893                        config.policy.into_libsy(),
1894                    );
1895                    classifier_config.classify_trigger = config.classify_trigger;
1896                    classifier_config.message_hash_fallback = config.message_hash_fallback;
1897                    classifier_config.recent_turn_window = config.recent_turn_window;
1898                    classifier_config.max_output_tokens = config.max_output_tokens;
1899                    classifier_config.judge_deadline_ms = config.judge_deadline_ms;
1900                    LlmTaskClassifier::new(LlmClassifierConfig::Custom {
1901                        default_target: config.default_target,
1902                        config: classifier_config,
1903                    })
1904                }
1905                LlmClassifierModeConfig::Direct {
1906                    default_target,
1907                    config,
1908                    ..
1909                } => LlmTaskClassifier::new(LlmClassifierConfig::Direct {
1910                    default_target,
1911                    config,
1912                }),
1913            }
1914            .map_err(|error| {
1915                AlgorithmConfigError::with_source(
1916                    format!("llm_classifier route {route_name}: {error}"),
1917                    error,
1918                )
1919            })?;
1920            Ok(Arc::new(algorithm))
1921        }
1922        AlgorithmSpec::StageRouter {
1923            capable_target,
1924            efficient_target,
1925            capable_first_threshold,
1926            settings,
1927            picker,
1928            classifier,
1929            subagents,
1930            ..
1931        } => {
1932            if matches!(picker, PickerMode::CapableFirst) {
1933                tracing::warn!(
1934                    "stage_router route {route_name} uses picker \"capable_first\", which is experimental: published thresholds and routing results all come from \"efficient_first\", so there is no calibrated confidence_threshold for it and no measured accuracy or cost. Use \"efficient_first\" unless you are running your own calibration."
1935                );
1936            }
1937            warn_identical_tiers(route_name, capable_target, efficient_target);
1938            let threshold = settings.confidence_threshold.ok_or_else(|| {
1939                AlgorithmConfigError::new(format!(
1940                    "stage_router route {route_name}: confidence_threshold is required"
1941                ))
1942            })?;
1943            let mut config = settings.stage_config(settings, *picker, threshold);
1944            config.capable_first_threshold = *capable_first_threshold;
1945            // The judge is called through its own target, so it is not a routing
1946            // destination and stays out of the tier pair.
1947            config.llm_fallback = classifier
1948                .as_ref()
1949                .map(|classifier| {
1950                    classifier.stage_fallback(route_name, capable_target, efficient_target, targets)
1951                })
1952                .transpose()?;
1953            let algorithm = StageRouter::new(config).map_err(|error| {
1954                AlgorithmConfigError::with_source(
1955                    format!("stage_router route {route_name}: {error}"),
1956                    error,
1957                )
1958            })?;
1959            let parent: Arc<dyn Algorithm> = Arc::new(algorithm);
1960            attach_subagent_router(route_name, parent, subagents.as_ref(), targets)
1961        }
1962        AlgorithmSpec::Auto {
1963            capable_target,
1964            efficient_target,
1965        } => {
1966            warn_identical_tiers(route_name, capable_target, efficient_target);
1967            let config = StageRouterConfig::new(PickerMode::EfficientFirst, 0.5);
1968            let algorithm = StageRouter::new(config).map_err(|error| {
1969                AlgorithmConfigError::with_source(
1970                    format!("auto route {route_name}: {error}"),
1971                    error,
1972                )
1973            })?;
1974            Ok(Arc::new(algorithm))
1975        }
1976        AlgorithmSpec::Composite {
1977            classifier,
1978            stage,
1979            efficient,
1980            capable,
1981            subagents,
1982        } => {
1983            stage.warn_identical_tiers(route_name);
1984            let judge = classifier.composite_judge_config(
1985                route_name,
1986                &stage.capable_target,
1987                &stage.efficient_target,
1988            )?;
1989            let defaults = StageProfileConfig::default();
1990            let profiles = [
1991                (efficient, PickerMode::EfficientFirst),
1992                (capable, PickerMode::CapableFirst),
1993            ]
1994            .map(|(profile, picker)| -> AlgorithmResult<_> {
1995                let profile = profile.as_deref().unwrap_or(&defaults);
1996                let mut config = stage.profile_config(profile, picker);
1997                config.llm_fallback = profile
1998                    .classifier
1999                    .as_ref()
2000                    .map(|classifier| {
2001                        classifier.stage_fallback(
2002                            route_name,
2003                            &stage.capable_target,
2004                            &stage.efficient_target,
2005                            targets,
2006                        )
2007                    })
2008                    .transpose()?;
2009                Ok(config)
2010            });
2011            let [profile_0, profile_1] = profiles;
2012            let algorithm = CompositeRouter::new_with_profiles(judge, profile_0?, profile_1?)
2013                .map_err(|error| {
2014                    AlgorithmConfigError::with_source(
2015                        format!("composite route {route_name}: {error}"),
2016                        error,
2017                    )
2018                })?;
2019            let parent: Arc<dyn Algorithm> = Arc::new(algorithm);
2020            attach_subagent_router(route_name, parent, subagents.as_ref(), targets)
2021        }
2022        AlgorithmSpec::Advisor {
2023            reviewer_system_prompt,
2024            redo_feedback_prefix,
2025            gate_trigger,
2026            gate_trigger_pattern,
2027            max_reviews,
2028            gate_stall_turns,
2029            gate_min_tool_results,
2030            advisor_max_tokens,
2031            advisor_temperature,
2032            transcript_max_chars,
2033            fail_open,
2034            ..
2035        } => {
2036            // A pattern set under the default trigger would be silently
2037            // ignored; reject the misconfiguration instead.
2038            if *gate_trigger == AdvisorTriggerConfig::NoToolCall && gate_trigger_pattern.is_some() {
2039                return Err(AlgorithmConfigError::new(format!(
2040                    "advisor route {route_name}: gate_trigger_pattern requires \
2041                     gate_trigger = \"pattern\""
2042                )));
2043            }
2044            let mut config = AdvisorGateConfig::default();
2045            if let Some(prompt) = reviewer_system_prompt {
2046                config.reviewer_system_prompt = prompt.clone();
2047            }
2048            if let Some(prefix) = redo_feedback_prefix {
2049                config.redo_feedback_prefix = prefix.clone();
2050            }
2051            config.gate_trigger = match gate_trigger {
2052                AdvisorTriggerConfig::NoToolCall => GateTrigger::NoToolCall,
2053                AdvisorTriggerConfig::Pattern => {
2054                    GateTrigger::Pattern(gate_trigger_pattern.clone().unwrap_or_default())
2055                }
2056            };
2057            config.max_reviews = *max_reviews;
2058            config.gate_stall_turns = *gate_stall_turns;
2059            config.gate_min_tool_results = *gate_min_tool_results;
2060            config.advisor_max_tokens = *advisor_max_tokens;
2061            config.advisor_temperature = *advisor_temperature;
2062            config.transcript_max_chars = *transcript_max_chars;
2063            config.fail_open = *fail_open;
2064            let algorithm = AdvisorGate::new(config).map_err(|error| {
2065                AlgorithmConfigError::with_source(
2066                    format!("advisor route {route_name}: {error}"),
2067                    error,
2068                )
2069            })?;
2070            Ok(Arc::new(algorithm))
2071        }
2072        AlgorithmSpec::Vgr { config } => build_vgr(route_name, config, targets),
2073        AlgorithmSpec::PrefillRouter {
2074            targets: names,
2075            checkpoint,
2076            device,
2077            cache_dir,
2078            max_length,
2079            batch_size,
2080        } => {
2081            #[cfg(feature = "prefill-router")]
2082            {
2083                let targets = names
2084                    .iter()
2085                    .map(|name| resolve_target_model_id(route_name, name, targets))
2086                    .collect::<AlgorithmResult<Vec<_>>>()?;
2087                let mut config = prefill_router::PrefillRouterConfig::new(targets, checkpoint);
2088                config.device.clone_from(device);
2089                config.cache_dir.clone_from(cache_dir);
2090                if let Some(max_length) = max_length {
2091                    config.max_length = *max_length;
2092                }
2093                if let Some(batch_size) = batch_size {
2094                    config.batch_size = *batch_size;
2095                }
2096                let algorithm = config.build().map_err(|error| {
2097                    AlgorithmConfigError::with_source(
2098                        format!("prefill_router route {route_name}: {error}"),
2099                        error,
2100                    )
2101                })?;
2102                Ok(Arc::new(algorithm))
2103            }
2104
2105            #[cfg(not(feature = "prefill-router"))]
2106            {
2107                let _ = (
2108                    names, checkpoint, device, cache_dir, max_length, batch_size, targets,
2109                );
2110                Err(AlgorithmConfigError::new(format!(
2111                    "prefill_router route {route_name} requires the `prefill-router` Cargo feature"
2112                )))
2113            }
2114        }
2115    }
2116}
2117
2118fn build_vgr(
2119    route_name: &str,
2120    config: &VgrRouteConfig,
2121    targets: &BTreeMap<String, ModelId>,
2122) -> AlgorithmResult<Arc<dyn Algorithm>> {
2123    let efficient = resolve_target_model_id(route_name, &config.efficient_target, targets)?;
2124    let capable = resolve_target_model_id(route_name, &config.capable_target, targets)?;
2125    let optional = |name: &Option<String>| {
2126        name.as_deref()
2127            .map(|name| resolve_target_model_id(route_name, name, targets))
2128            .transpose()
2129    };
2130    let mut runtime = VgrConfig::new(efficient, capable);
2131    runtime.targets.judge = optional(&config.judge_target)?;
2132    runtime.targets.capable_judge = optional(&config.capable_judge_target)?;
2133    runtime.mode = match config.mode {
2134        VgrModeConfig::Off => libsy::ServingMode::Off,
2135        VgrModeConfig::Evaluate => libsy::ServingMode::Evaluate,
2136        VgrModeConfig::Shadow => libsy::ServingMode::Shadow,
2137        VgrModeConfig::Active => libsy::ServingMode::Active {
2138            approval: config.active_approval.clone().unwrap_or_default(),
2139        },
2140    };
2141    runtime.deadline = vgr_duration(route_name, "deadline_seconds", config.deadline_seconds)?;
2142    runtime.bounded_efficient = config.bounded_efficient;
2143    runtime.task_typing = config.task_typing;
2144    runtime.confirmed_recovery_min_clean_tail = config.confirmed_recovery_min_clean_tail;
2145    runtime.agentic_handoff = config.agentic_handoff;
2146    runtime.compact_handoff = config.compact_handoff;
2147    runtime.latch_escalation = config.latch_escalation;
2148    runtime.efficient_supports_attachments = config.efficient_supports_attachments;
2149    runtime.efficient_turn_budget = config
2150        .efficient_turn_budget_seconds
2151        .map(|seconds| vgr_duration(route_name, "efficient_turn_budget_seconds", seconds))
2152        .transpose()?;
2153    runtime.breaker = BreakerConfig {
2154        threshold: config.breaker_threshold,
2155        cooldown: vgr_duration(
2156            route_name,
2157            "breaker_cooldown_seconds",
2158            config.breaker_cooldown_seconds,
2159        )?,
2160    };
2161    Vgr::new(runtime)
2162        .map(|algorithm| Arc::new(algorithm) as Arc<dyn Algorithm>)
2163        .map_err(|error| {
2164            AlgorithmConfigError::with_source(format!("vgr route {route_name}: {error}"), error)
2165        })
2166}
2167
2168fn vgr_duration(route: &str, field: &str, seconds: f64) -> AlgorithmResult<std::time::Duration> {
2169    let message = || format!("vgr route {route}: {field} must be a positive number");
2170    let duration = std::time::Duration::try_from_secs_f64(seconds)
2171        .map_err(|error| AlgorithmConfigError::with_source(message(), error))?;
2172    if duration.is_zero() {
2173        return Err(AlgorithmConfigError::new(message()));
2174    }
2175    Ok(duration)
2176}
2177
2178const fn default_max_reviews() -> u32 {
2179    1
2180}
2181
2182const fn default_advisor_max_tokens() -> u64 {
2183    2048
2184}
2185
2186const fn default_transcript_max_chars() -> usize {
2187    200_000
2188}
2189
2190const fn default_fail_open() -> bool {
2191    true
2192}
2193
2194fn classifier_contract(prompt: Option<&str>) -> ClassifierContractConfig {
2195    prompt.map_or_else(ClassifierContractConfig::default, |prompt| {
2196        ClassifierContractConfig::default().with_prompt(prompt)
2197    })
2198}
2199
2200fn default_classifier_max_output_tokens() -> u64 {
2201    LlmCapabilityConfig::default().max_output_tokens
2202}
2203
2204/// Both tiers on one target leave the route nothing to choose between; every decision
2205/// lands on the same model. The file still loads, since a single-model deployment can
2206/// be a deliberate overhead measurement.
2207fn warn_identical_tiers(route_name: &str, capable_target: &str, efficient_target: &str) {
2208    if capable_target == efficient_target {
2209        tracing::warn!(
2210            route = route_name,
2211            target = capable_target,
2212            "capable_target and efficient_target name the same target, so every request goes to one model; use passthrough for a single model, or point the tiers at two targets"
2213        );
2214    }
2215}
2216
2217fn warn_single_target_classifier(route_name: &str, models: &CategoryModelConfig) {
2218    if models.routing_names().len() < 2 {
2219        tracing::warn!(
2220            route = route_name,
2221            "custom classifier has only one routing target; judge calls add cost without a routing choice. Use passthrough or add another completion target in routes.<name>, or in routes.<name>.subagents for a subagent classifier."
2222        );
2223    }
2224}
2225
2226const fn default_vgr_deadline() -> f64 {
2227    30.0
2228}
2229
2230const fn default_true() -> bool {
2231    true
2232}
2233
2234const fn default_vgr_breaker_threshold() -> u32 {
2235    5
2236}
2237
2238const fn default_vgr_breaker_cooldown() -> f64 {
2239    30.0
2240}
2241
2242fn resolve_target_model_id(
2243    route_name: &str,
2244    name: &str,
2245    targets: &BTreeMap<String, ModelId>,
2246) -> AlgorithmResult<ModelId> {
2247    targets.get(name).cloned().ok_or_else(|| {
2248        AlgorithmConfigError::new(format!(
2249            "route {route_name} references unknown target {name}"
2250        ))
2251    })
2252}
2253
2254fn resolve_runtime_models(
2255    route_name: &str,
2256    names: HashMap<Category, Vec<String>>,
2257    targets: &BTreeMap<String, ModelId>,
2258) -> AlgorithmResult<HashMap<Category, Vec<ModelId>>> {
2259    names
2260        .into_iter()
2261        .map(|(category, names)| {
2262            let models = names
2263                .into_iter()
2264                .map(|name| resolve_target_model_id(route_name, &name, targets))
2265                .collect::<AlgorithmResult<Vec<_>>>()?;
2266            Ok((category, models))
2267        })
2268        .collect()
2269}
2270
2271#[cfg(test)]
2272mod tests {
2273    use super::*;
2274
2275    #[test]
2276    fn composite_profile_defaults() -> AlgorithmResult<()> {
2277        let stage: StageTierConfig =
2278            toml::from_str("capable_target = 'strong'\nefficient_target = 'weak'").unwrap();
2279        for (picker, threshold, capable_hold, efficient_hold, prompt) in [
2280            (PickerMode::EfficientFirst, 0.4, 2, 0, None),
2281            (
2282                PickerMode::CapableFirst,
2283                0.0,
2284                0,
2285                -1,
2286                Some(COMPOSITE_PLANNING_PROMPT),
2287            ),
2288        ] {
2289            let config = stage.profile_config(&StageProfileConfig::default(), picker);
2290            assert_eq!(config.mode, picker);
2291            assert_eq!(config.confidence_threshold, threshold);
2292            assert_eq!(config.recent_window, Some(3));
2293            assert!(config.compaction_override);
2294            assert_eq!(config.capable_hold_turns, capable_hold);
2295            assert_eq!(config.efficient_hold_turns, Some(efficient_hold));
2296            assert_eq!(config.capable_system_prompt.as_deref(), prompt);
2297            assert!(config.llm_fallback.is_none());
2298            assert!(config.handoff_notes.is_none());
2299        }
2300        let standalone = StageSettingsConfig::default().stage_config(
2301            &StageSettingsConfig::default(),
2302            PickerMode::CapableFirst,
2303            0.5,
2304        );
2305        assert_eq!(standalone.capable_hold_turns, 2);
2306        assert!(standalone.compaction_override);
2307        assert!(standalone.capable_system_prompt.is_none());
2308        Ok(())
2309    }
2310
2311    #[test]
2312    fn composite_profile_overrides() {
2313        let stage: StageTierConfig = toml::from_str(
2314            r#"
2315capable_target = "strong"
2316efficient_target = "weak"
2317efficient_first_threshold = 0.7
2318capable_first_threshold = 0.2
2319recent_turn_window = 5
2320compaction_override = false
2321capable_hold_turns = 4
2322efficient_hold_turns = 1
2323capable_system_prompt = "Shared plan"
2324"#,
2325        )
2326        .unwrap();
2327        let shared = stage.profile_config(&StageProfileConfig::default(), PickerMode::CapableFirst);
2328        assert_eq!(shared.confidence_threshold, 0.2);
2329        assert_eq!(shared.recent_window, Some(5));
2330        assert!(!shared.compaction_override);
2331        assert_eq!(shared.capable_hold_turns, 4);
2332        assert_eq!(shared.efficient_hold_turns, Some(1));
2333        assert_eq!(shared.capable_system_prompt.as_deref(), Some("Shared plan"));
2334        assert_eq!(
2335            stage
2336                .profile_config(&StageProfileConfig::default(), PickerMode::EfficientFirst)
2337                .confidence_threshold,
2338            0.7
2339        );
2340        let profile: StageProfileConfig = toml::from_str(
2341            r#"
2342confidence_threshold = 0.0
2343recent_turn_window = 2
2344compaction_override = true
2345capable_hold_turns = 0
2346efficient_hold_turns = 0
2347capable_system_prompt = ""
2348"#,
2349        )
2350        .unwrap();
2351        let config = stage.profile_config(&profile, PickerMode::CapableFirst);
2352        assert_eq!(config.confidence_threshold, 0.0);
2353        assert_eq!(config.recent_window, Some(2));
2354        assert!(config.compaction_override);
2355        assert_eq!(config.capable_hold_turns, 0);
2356        assert_eq!(config.efficient_hold_turns, Some(0));
2357        assert_eq!(config.capable_system_prompt.as_deref(), Some(""));
2358    }
2359
2360    #[test]
2361    fn composite_decision_defaults_and_overrides() -> AlgorithmResult<()> {
2362        for (settings, cutoff, fail_open) in [
2363            ("[decision]", 0.92, true),
2364            ("fail_open = false\n[decision]\ncutoff = 0.7", 0.7, false),
2365        ] {
2366            let classifier: StageClassifierConfig = toml::from_str(&format!(
2367                "target = 'judge'\nclassify_trigger = 'new_session'\n{settings}"
2368            ))
2369            .unwrap();
2370            let CompositeJudgeConfig::Capability(config) =
2371                classifier.composite_judge_config("route", "strong", "weak")?
2372            else {
2373                panic!()
2374            };
2375            assert_eq!(config.classify_trigger, ClassifyTrigger::NewSession);
2376            assert_eq!(config.fail_open, fail_open);
2377            let CapabilityJudgeConfig::Decision(judge) = config.judge else {
2378                panic!()
2379            };
2380            assert_eq!(judge.cutoff, Some(cutoff));
2381        }
2382        Ok(())
2383    }
2384
2385    #[test]
2386    fn restricted_random_preserves_weight_positions() -> AlgorithmResult<()> {
2387        let allowed = BTreeSet::from(["private_a", "private_b"]);
2388        let mut algorithm = AlgorithmSpec::Random {
2389            targets: ["public_a", "private_a", "public_b", "private_b"]
2390                .map(String::from)
2391                .to_vec(),
2392            weights: Some(vec![1.0, 2.0, 3.0, 4.0]),
2393            seed: Some(42),
2394        };
2395        let AlgorithmSpec::Random {
2396            targets,
2397            weights,
2398            seed,
2399        } = algorithm.restricted_to(&allowed)?
2400        else {
2401            unreachable!();
2402        };
2403        assert_eq!(targets, ["private_a", "private_b"]);
2404        assert_eq!(weights, Some(vec![2.0, 4.0]));
2405        assert_eq!(seed, Some(42));
2406        if let AlgorithmSpec::Random { weights, .. } = &mut algorithm {
2407            *weights = Some(vec![1.0]);
2408        }
2409        assert!(algorithm.restricted_to(&allowed).is_err());
2410        Ok(())
2411    }
2412
2413    fn custom_classifier() -> LlmClassifierRouteConfig {
2414        LlmClassifierRouteConfig {
2415            mode: Some(ClassifierMode::Custom),
2416            models: Some(CategoryModelConfig(BTreeMap::from([
2417                ("any".into(), vec!["public".into(), "private".into()]),
2418                ("efficient".into(), vec!["public".into(), "private".into()]),
2419                ("judge".into(), vec!["judge".into()]),
2420                ("research".into(), vec!["public".into()]),
2421            ]))),
2422            default_target: Some("efficient".into()),
2423            prompt: Some("Select an available target.".into()),
2424            response_schema: Some(r#"{"type":"object"}"#.into()),
2425            max_output_tokens: default_classifier_max_output_tokens(),
2426            policy: Some(ClassifierPolicyConfig::TargetSelector {
2427                selector: "/target".into(),
2428            }),
2429            ..LlmClassifierRouteConfig::default()
2430        }
2431    }
2432
2433    #[test]
2434    fn restricted_custom_pools_cover_parent_and_subagents() -> AlgorithmResult<()> {
2435        let allowed = BTreeSet::from(["private", "judge"]);
2436        let targets = BTreeMap::from([
2437            ("private".into(), ModelId::from("private")),
2438            ("judge".into(), ModelId::from("judge")),
2439        ]);
2440        let parent = AlgorithmSpec::LlmClassifier {
2441            config: custom_classifier(),
2442        };
2443        let child = AlgorithmSpec::Passthrough {
2444            target: "private".into(),
2445            subagents: Some(SubagentRouteConfig::LlmClassifier(Box::new(
2446                custom_classifier(),
2447            ))),
2448        };
2449        for algorithm in [parent, child] {
2450            let restricted = algorithm.restricted_to(&allowed)?;
2451            let groups = restricted.runtime_model_names("test")?;
2452            let groups = groups.subagent.unwrap_or(groups.parent);
2453            assert_eq!(groups[&Category::Any], ["private"]);
2454            assert_eq!(groups[&Category::Efficient], ["private"]);
2455            assert_eq!(groups[&Category::Judge], ["judge"]);
2456            restricted.build("test", &targets)?;
2457            let missing_judge = algorithm.restricted_to(&BTreeSet::from(["private"]))?;
2458            assert!(missing_judge.build("test", &targets).is_err());
2459        }
2460        Ok(())
2461    }
2462
2463    #[test]
2464    fn restricted_roles_are_not_replaced() {
2465        let stage = AlgorithmSpec::Auto {
2466            capable_target: "private".into(),
2467            efficient_target: "public".into(),
2468        };
2469        assert!(stage.restricted_to(&BTreeSet::from(["private"])).is_err());
2470    }
2471}