use std::sync::Arc;
use std::time::Instant;
use switchyard_protocol::{
Category, ContentBlock, InstructionBlock, LlmRequest, Message, ModelId, OutputParams, Request,
Role, SamplingParams,
};
use crate::core::algorithm::{Algorithm, Driver, RoutingOutcome};
use crate::core::processor::{Event, Processor};
use crate::{LibsyError, Result};
mod budget;
mod signals;
mod telemetry;
#[cfg(test)]
mod tests;
mod transcript;
mod trigger;
mod turn;
use super::util::buffered_response::{BufferedResponse, buffer_response};
use budget::{ReviewBudget, ScopeKey, budget_scope, stall_key};
use signals::{GateSignalProcessor, GateSignals};
use telemetry::{
ReviewAudit, emit_discarded_audit, emit_review_audit, record_consult_failure, record_discarded,
record_review,
};
use transcript::{VERDICT_PATTERN, Verdict, advisor_reply_text, parse_verdict, review_transcript};
use trigger::TriggerClassifier;
#[cfg(test)]
use turn::has_tool_use;
use turn::{reasoning_text, visible_text};
pub const REVIEWER_SYSTEM_PROMPT: &str =
include_str!("../prompts/advisor-gate/reviewer-system-prompt.md");
pub const REDO_FEEDBACK_PREFIX: &str = concat!(
include_str!("../prompts/advisor-gate/redo-feedback-prefix.md"),
"\n"
);
const REASONING_TAIL_LABEL: &str =
"(the executor produced no visible text this turn; its internal reasoning follows)\n";
const EMPTY_ECHO_PLACEHOLDER: &str = "(the executor produced no output this turn)";
const BENCH_SESSION_HEADER: &str = "proxy_x_session_id";
#[derive(Clone, Debug, PartialEq)]
pub enum GateTrigger {
NoToolCall,
Pattern(String),
}
#[derive(Clone, Debug)]
pub struct AdvisorGateConfig {
pub reviewer_system_prompt: String,
pub redo_feedback_prefix: String,
pub gate_trigger: GateTrigger,
pub max_reviews: u32,
pub gate_stall_turns: u32,
pub gate_min_tool_results: u32,
pub advisor_max_tokens: u64,
pub advisor_temperature: Option<f64>,
pub transcript_max_chars: usize,
pub fail_open: bool,
}
impl Default for AdvisorGateConfig {
fn default() -> Self {
Self {
reviewer_system_prompt: REVIEWER_SYSTEM_PROMPT.to_string(),
redo_feedback_prefix: REDO_FEEDBACK_PREFIX.to_string(),
gate_trigger: GateTrigger::NoToolCall,
max_reviews: 1,
gate_stall_turns: 0,
gate_min_tool_results: 0,
advisor_max_tokens: 2048,
advisor_temperature: None,
transcript_max_chars: 200_000,
fail_open: true,
}
}
}
pub struct AdvisorGate {
config: AdvisorGateConfig,
signals: GateSignalProcessor,
trigger: TriggerClassifier,
budget: ReviewBudget,
verdict_re: regex::Regex,
}
impl AdvisorGate {
pub fn new(config: AdvisorGateConfig) -> Result<Self> {
if config.max_reviews < 1 {
return Err(algorithm_error("max_reviews must be at least 1"));
}
if config.advisor_max_tokens < 1 {
return Err(algorithm_error("advisor_max_tokens must be at least 1"));
}
if config.transcript_max_chars < 256 {
return Err(algorithm_error("transcript_max_chars must be at least 256"));
}
let trigger = TriggerClassifier::new(&config)?;
let verdict_re = regex::Regex::new(VERDICT_PATTERN).map_err(|error| {
algorithm_error(format!("verdict pattern failed to compile: {error}"))
})?;
let budget = ReviewBudget::new(config.max_reviews);
Ok(Self {
config,
signals: GateSignalProcessor,
trigger,
budget,
verdict_re,
})
}
async fn route_inner(
&self,
driver: &Driver,
request: Request,
scope: &ScopeKey,
) -> Result<RoutingOutcome> {
let executor_models = driver.models_for(&Category::Efficient).to_vec();
let executor = executor_models
.first()
.ok_or_else(|| LibsyError::AlgorithmError {
message: "no models available for category Efficient".to_string(),
})?;
if self.budget.check_exhausted(scope) {
return Ok(RoutingOutcome::route_to(
executor.clone(),
executor_models[1..].to_vec(),
request,
));
}
let mut request = request;
let mut signals = GateSignals::default();
self.signals
.process(
&mut signals,
Event::Request {
request: &mut request,
driver,
},
)
.await?;
let response = driver
.call_model(request.clone(), executor_models.clone())
.await?;
let served_executor = response
.served_model()
.cloned()
.unwrap_or_else(|| executor.clone());
let turn = buffer_response(served_executor.as_str(), response).await?;
self.signals
.process(&mut signals, Event::ModelResponse(&turn.agg))
.await?;
let decision = self.trigger.classify(&signals);
let stall_key = stall_key(&request);
let stall = decision.fired.is_none()
&& decision.stalled
&& self.budget.try_mark_stall_fired(stall_key);
if decision.fired.is_none() && !stall {
return Ok(RoutingOutcome::answered(
served_executor.clone(),
request,
turn.into_response(),
));
}
if !self.budget.try_reserve(scope) {
if stall {
self.budget.clear_stall_fired(stall_key);
}
return Ok(RoutingOutcome::answered(
served_executor.clone(),
request,
turn.into_response(),
));
}
let trigger_label = decision.fired.unwrap_or("stall");
let review_tail = visible_text(&turn.agg).or_else(|| {
reasoning_text(&turn.agg).map(|reasoning| format!("{REASONING_TAIL_LABEL}{reasoning}"))
});
match self
.consult(driver, &request, review_tail.as_deref(), trigger_label)
.await
{
Ok(ConsultOutcome::Approve) => {
driver.set_evidence(serde_json::json!({
"source": "advisor",
"verdict": "approve",
"trigger": trigger_label,
}));
Ok(RoutingOutcome::answered(
served_executor.clone(),
request,
turn.into_response(),
))
}
Ok(ConsultOutcome::Redo { plan }) => {
driver.set_evidence(serde_json::json!({
"source": "advisor",
"verdict": "redo",
"trigger": trigger_label,
}));
Ok(self.redo(
executor,
&executor_models[1..],
&served_executor,
request,
turn,
&plan,
))
}
Ok(ConsultOutcome::Failed { reason }) => {
self.budget.refund_failure(scope);
if stall {
self.budget.clear_stall_fired(stall_key);
}
driver.set_evidence(serde_json::json!({
"source": "advisor",
"verdict": "fail_open",
"trigger": trigger_label,
"reason_code": reason,
}));
Ok(RoutingOutcome::answered(
served_executor,
request,
turn.into_response(),
))
}
Err(error) => {
self.budget.refund_failure(scope);
if stall {
self.budget.clear_stall_fired(stall_key);
}
Err(error)
}
}
}
fn redo(
&self,
executor: &ModelId,
executor_fallbacks: &[ModelId],
served_executor: &ModelId,
request: Request,
turn: BufferedResponse,
plan: &str,
) -> RoutingOutcome {
record_discarded(&turn.agg.usage);
emit_discarded_audit(served_executor.as_str(), &turn.agg.usage);
let echo = visible_text(&turn.agg)
.or_else(|| reasoning_text(&turn.agg))
.unwrap_or_else(|| EMPTY_ECHO_PLACEHOLDER.to_string());
let mut redo = request;
redo.llm_request
.messages
.push(Message::text(Role::Assistant, echo));
redo.llm_request.messages.push(Message::text(
Role::User,
format!("{}{}", self.config.redo_feedback_prefix, plan),
));
crate::algorithms::util::prompts::drop_exact_replay(&mut redo);
RoutingOutcome::route_to(executor.clone(), executor_fallbacks.to_vec(), redo)
}
async fn consult(
&self,
driver: &Driver,
base: &Request,
review_tail: Option<&str>,
trigger: &'static str,
) -> Result<ConsultOutcome> {
let transcript_messages: Vec<Message> = base
.llm_request
.instructions
.iter()
.map(|block| Message {
role: block.role,
content: block.content.clone(),
})
.chain(base.llm_request.messages.iter().cloned())
.collect();
let transcript = review_transcript(
&transcript_messages,
review_tail,
self.config.transcript_max_chars,
);
let consult_request = self.build_consult_request(base, transcript);
let started = Instant::now();
let reply = match driver.first_model_for(&Category::Judge) {
Ok(advisor) => {
let advisor = advisor.clone();
let advisor_models = driver.models_for(&Category::Judge).to_vec();
match driver.call_model(consult_request, advisor_models).await {
Ok(response) => {
let served_advisor = response
.served_model()
.cloned()
.unwrap_or_else(|| advisor.clone());
response
.llm_response
.into_agg()
.await
.map_err(|source| LibsyError::client_call(served_advisor, source))
}
Err(error) => Err(error),
}
}
Err(error) => Err(error),
};
let latency_ms = started.elapsed().as_secs_f64() * 1000.0;
let agg = match reply {
Ok(agg) => agg,
Err(error) => {
let reason = crate::algorithms::util::llm_judge::libsy_error_reason(&error);
record_consult_failure(reason);
if !self.config.fail_open {
return Err(algorithm_error(format!(
"advisor consult failed (fail_open = false): {error}"
)));
}
tracing::warn!(
target: "libsy",
error = %error,
"advisor gate: consult failed; passing the turn through (fail open)"
);
emit_review_audit(ReviewAudit {
verdict: "APPROVE",
error: Some(error.to_string()),
latency_ms,
reply_head: None,
usage: None,
});
return Ok(ConsultOutcome::Failed { reason });
}
};
let reply_text = advisor_reply_text(&agg);
let reply_head: String = reply_text.chars().take(160).collect();
match parse_verdict(&self.verdict_re, &reply_text) {
Some(Verdict::Approve) => {
record_review("approve", trigger);
emit_review_audit(ReviewAudit {
verdict: "APPROVE",
error: None,
latency_ms,
reply_head: Some(reply_head),
usage: Some(&agg.usage),
});
Ok(ConsultOutcome::Approve)
}
Some(Verdict::Redo { plan }) => {
record_review("redo", trigger);
emit_review_audit(ReviewAudit {
verdict: "REDO",
error: None,
latency_ms,
reply_head: Some(reply_head),
usage: Some(&agg.usage),
});
Ok(ConsultOutcome::Redo { plan })
}
None => {
record_review("unparseable", trigger);
emit_review_audit(ReviewAudit {
verdict: "UNPARSEABLE",
error: None,
latency_ms,
reply_head: Some(reply_head),
usage: Some(&agg.usage),
});
Ok(ConsultOutcome::Failed {
reason: "parse_error",
})
}
}
}
fn build_consult_request(&self, base: &Request, transcript: String) -> Request {
Request {
llm_request: LlmRequest {
model: base.llm_request.model.clone(),
instructions: vec![InstructionBlock {
role: Role::System,
content: vec![ContentBlock::Text {
text: self.config.reviewer_system_prompt.clone(),
}],
}],
messages: vec![Message::text(Role::User, transcript)],
sampling: SamplingParams {
temperature: self.config.advisor_temperature,
..SamplingParams::default()
},
output: OutputParams {
max_output_tokens: Some(self.config.advisor_max_tokens),
response_format: None,
},
..LlmRequest::default()
},
raw_request: None,
metadata: base.metadata.clone(),
}
}
}
#[async_trait::async_trait]
impl Algorithm for AdvisorGate {
fn name(&self) -> &str {
"advisor_gate"
}
async fn route(self: Arc<Self>, driver: Driver, request: Request) -> Result<RoutingOutcome> {
let scope = budget_scope(&request);
let session_final = request
.metadata
.as_ref()
.and_then(|metadata| metadata.session_final)
== Some(true);
let result = self.route_inner(&driver, request, &scope).await;
if session_final {
self.budget.evict_scope(&scope);
}
result
}
}
enum ConsultOutcome {
Approve,
Redo { plan: String },
Failed { reason: &'static str },
}
fn algorithm_error(message: impl Into<String>) -> LibsyError {
LibsyError::AlgorithmError {
message: message.into(),
}
}