orch/engine/router/
weights.rs1use std::collections::HashMap;
10use std::time::{Duration, Instant};
11
12use super::selection::{hash_task_id, simple_hash_fraction_for, simple_hash_index_for};
13
14pub(super) const DEFAULT_WEIGHT: f64 = 1.0;
16
17pub(super) const MIN_WEIGHT: f64 = 0.05;
19
20pub(super) const RATE_LIMIT_DECAY: f64 = 0.3;
22
23pub(super) fn default_missing_weight(configured_weights: &HashMap<String, f64>) -> f64 {
30 configured_weights
31 .values()
32 .copied()
33 .fold(None, |min, w| Some(min.map_or(w, |m: f64| m.min(w))))
34 .unwrap_or(DEFAULT_WEIGHT)
35}
36
37fn generate_recovery_jitter(agent: &str) -> Duration {
40 let max_secs = RECOVERY_JITTER_MAX.as_secs();
41 let jitter_secs = hash_task_id(agent) % max_secs;
42 Duration::from_secs(jitter_secs)
43}
44
45pub(super) const RECOVERY_DELAY: Duration = Duration::from_secs(60);
47
48pub(super) const RECOVERY_JITTER_MAX: Duration = Duration::from_secs(30);
51
52pub(super) const RECOVERY_RATE: f64 = 0.1;
54
55#[derive(Debug, Clone)]
57pub struct RateLimitState {
58 pub weight: f64,
60 pub last_limited_at: Option<Instant>,
62 pub recovery_jitter: Duration,
64 pub consecutive_hits: u32,
66 pub base_weight: f64,
68}
69
70impl Default for RateLimitState {
71 fn default() -> Self {
72 Self {
73 weight: DEFAULT_WEIGHT,
74 last_limited_at: None,
75 recovery_jitter: Duration::ZERO,
76 consecutive_hits: 0,
77 base_weight: DEFAULT_WEIGHT,
78 }
79 }
80}
81
82impl RateLimitState {
83 pub fn record_rate_limit(&mut self) {
86 self.consecutive_hits += 1;
87 self.weight = (self.weight * RATE_LIMIT_DECAY).max(MIN_WEIGHT);
88 self.last_limited_at = Some(Instant::now());
89 }
90
91 pub fn record_success(&mut self) {
93 self.consecutive_hits = 0;
94 self.weight = (self.weight + RECOVERY_RATE).min(self.base_weight);
95 }
96
97 pub fn maybe_recover(&mut self) {
99 if let Some(last) = self.last_limited_at {
100 let recovery_threshold = RECOVERY_DELAY + self.recovery_jitter;
101 if last.elapsed() >= recovery_threshold {
102 self.weight = (self.weight + RECOVERY_RATE).min(self.base_weight);
103 if self.weight >= self.base_weight {
104 self.last_limited_at = None;
105 self.recovery_jitter = Duration::ZERO;
106 self.consecutive_hits = 0;
107 }
108 }
109 }
110 }
111
112 pub fn is_limited(&self) -> bool {
114 self.weight < self.base_weight
115 }
116}
117
118#[derive(Debug, Clone, Default)]
120pub struct AgentWeights {
121 pub states: HashMap<String, RateLimitState>,
122 pub base_weights: HashMap<String, f64>,
125}
126
127impl AgentWeights {
128 pub fn ensure_agents(&mut self, agents: &[String]) {
130 for agent in agents {
131 self.states.entry(agent.clone()).or_default();
132 }
133 }
134
135 pub fn ensure_agents_with_weights(
142 &mut self,
143 agents: &[String],
144 configured_weights: &HashMap<String, f64>,
145 ) {
146 for agent in agents {
147 let base = configured_weights
148 .get(agent)
149 .copied()
150 .unwrap_or_else(|| default_missing_weight(configured_weights));
151 let state = self
152 .states
153 .entry(agent.clone())
154 .or_insert_with(|| RateLimitState {
155 weight: base,
156 base_weight: base,
157 ..Default::default()
158 });
159 state.base_weight = base;
160 if !state.is_limited() {
163 state.weight = base;
164 }
165 }
166 }
167
168 pub fn record_rate_limit(&mut self, agent: &str) {
170 let state = self.states.entry(agent.to_string()).or_default();
171 state.record_rate_limit();
172 state.recovery_jitter = generate_recovery_jitter(agent);
174 tracing::info!(
175 agent,
176 weight = state.weight,
177 hits = state.consecutive_hits,
178 jitter_secs = state.recovery_jitter.as_secs(),
179 "agent weight reduced (rate limit)"
180 );
181 }
182
183 pub fn record_success(&mut self, agent: &str) {
185 self.states
186 .entry(agent.to_string())
187 .or_default()
188 .record_success();
189 }
190
191 pub fn tick_recovery(&mut self) {
193 for (agent, state) in &mut self.states {
194 let was_limited = state.is_limited();
195 state.maybe_recover();
196 if was_limited && !state.is_limited() {
197 tracing::info!(agent, "agent weight fully recovered");
198 }
199 }
200 }
201
202 pub fn weighted_select(&self, agents: &[String], task_id: &str) -> Option<String> {
208 if agents.is_empty() {
209 return None;
210 }
211
212 let weights: Vec<f64> = agents
213 .iter()
214 .map(|a| {
215 self.states.get(a).map_or_else(
216 || {
217 self.base_weights
218 .get(a)
219 .copied()
220 .unwrap_or_else(|| default_missing_weight(&self.base_weights))
221 },
222 |s| s.weight,
223 )
224 })
225 .collect();
226
227 let total: f64 = weights.iter().sum();
228 if total <= 0.0 {
229 let idx = simple_hash_index_for(agents.len(), task_id);
231 return Some(agents[idx].clone());
232 }
233
234 let pick = simple_hash_fraction_for(task_id) * total;
237 let mut cumulative = 0.0;
238 for (i, w) in weights.iter().enumerate() {
239 cumulative += w;
240 if pick < cumulative {
241 return Some(agents[i].clone());
242 }
243 }
244
245 debug_assert!(!agents.is_empty(), "agents must not be empty");
247 Some(agents[agents.len() - 1].clone())
248 }
249
250 pub fn get_weight(&self, agent: &str) -> f64 {
252 self.states.get(agent).map_or_else(
253 || {
254 self.base_weights
255 .get(agent)
256 .copied()
257 .unwrap_or_else(|| default_missing_weight(&self.base_weights))
258 },
259 |s| s.weight,
260 )
261 }
262
263 pub fn snapshot(&self) -> Vec<(String, f64, u32)> {
265 let mut snap: Vec<_> = self
266 .states
267 .iter()
268 .map(|(a, s)| (a.clone(), s.weight, s.consecutive_hits))
269 .collect();
270 snap.sort_by(|a, b| a.0.cmp(&b.0));
271 snap
272 }
273}
274
275#[cfg(test)]
276mod tests {
277 use super::*;
278
279 #[test]
280 fn recovery_jitter_is_the_byte_hash_modulo_the_cap() {
281 assert_eq!(generate_recovery_jitter(""), Duration::from_secs(0));
282 assert_eq!(generate_recovery_jitter("a"), Duration::from_secs(7));
283 assert_eq!(
284 generate_recovery_jitter("claude"),
285 generate_recovery_jitter("claude")
286 );
287 assert!(generate_recovery_jitter("claude") < RECOVERY_JITTER_MAX);
288 }
289}