Skip to main content

cortex_router/
lib.rs

1#![doc = include_str!("../README.md")]
2
3mod classifier;
4mod fold;
5mod lexicon;
6
7use serde::{Deserialize, Serialize};
8
9pub use classifier::{classify, detector_disagreement};
10pub use cortex_domain::{ExecutionTarget, RiskLevel};
11pub use fold::{fold_text, fold_words, mixed_script};
12
13#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
14#[serde(rename_all = "snake_case")]
15pub enum TaskClass {
16    Deterministic,
17    RepositoryAnalysis,
18    StructuredExtraction,
19    ContextCompression,
20    AdvisoryDraft,
21    Implementation,
22    Security,
23    Authentication,
24    Concurrency,
25    Migration,
26    Release,
27    Deployment,
28    Publication,
29    Ambiguous,
30}
31
32impl TaskClass {
33    #[must_use]
34    pub const fn requires_verified_evidence(self) -> bool {
35        matches!(self, Self::ContextCompression)
36    }
37}
38
39impl TaskClass {
40    #[must_use]
41    pub const fn is_high_risk(self) -> bool {
42        matches!(
43            self,
44            Self::Security
45                | Self::Authentication
46                | Self::Concurrency
47                | Self::Migration
48                | Self::Release
49                | Self::Deployment
50                | Self::Publication
51        )
52    }
53}
54
55#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
56#[serde(rename_all = "snake_case")]
57pub enum EvidenceStatus {
58    NotRequired,
59    Verified,
60    Missing,
61    Contradictory,
62}
63
64#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
65#[serde(rename_all = "snake_case")]
66pub enum MutationStatus {
67    None,
68    Approved,
69    ApprovalRequired,
70}
71
72#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
73#[serde(rename_all = "camelCase")]
74pub struct TokenBudget {
75    pub estimated_input_tokens: u32,
76    pub estimated_output_tokens: u32,
77    pub max_input_tokens: u32,
78    pub max_output_tokens: u32,
79}
80
81impl Default for TokenBudget {
82    fn default() -> Self {
83        Self {
84            estimated_input_tokens: 0,
85            estimated_output_tokens: 0,
86            max_input_tokens: 8_192,
87            max_output_tokens: 1_024,
88        }
89    }
90}
91
92#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
93#[serde(rename_all = "camelCase")]
94pub struct LocalAvailability {
95    pub weavatrix: bool,
96    pub ollama: bool,
97}
98
99impl Default for LocalAvailability {
100    fn default() -> Self {
101        Self {
102            weavatrix: true,
103            ollama: true,
104        }
105    }
106}
107
108#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
109#[serde(rename_all = "camelCase")]
110pub struct RoutingRequest {
111    pub task: String,
112    pub evidence: EvidenceStatus,
113    pub schema_valid: bool,
114    pub budget: TokenBudget,
115    pub mutation: MutationStatus,
116    pub availability: LocalAvailability,
117}
118
119impl RoutingRequest {
120    #[must_use]
121    pub fn new(task: impl Into<String>) -> Self {
122        Self {
123            task: task.into(),
124            evidence: EvidenceStatus::NotRequired,
125            schema_valid: true,
126            budget: TokenBudget::default(),
127            mutation: MutationStatus::None,
128            availability: LocalAvailability::default(),
129        }
130    }
131
132    /// A caller may report missing or contradictory evidence to escalate.
133    /// They cannot mint `Verified` to take a cheaper path.
134    pub fn distrust_self_reported_verified(&mut self) {
135        if self.evidence == EvidenceStatus::Verified {
136            self.evidence = EvidenceStatus::NotRequired;
137        }
138    }
139}
140
141#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
142#[serde(rename_all = "camelCase")]
143pub struct Classification {
144    pub class: TaskClass,
145    pub risk: RiskLevel,
146    pub mutation_likely: bool,
147}
148
149#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
150#[serde(rename_all = "snake_case", tag = "code", content = "detail")]
151pub enum RoutingReason {
152    HighRiskTask(TaskClass),
153    MissingEvidence,
154    ContradictoryEvidence,
155    SchemaValidationFailed,
156    InputBudgetExceeded { estimated: u32, limit: u32 },
157    OutputBudgetExceeded { estimated: u32, limit: u32 },
158    MutationApprovalRequired,
159    MutationReservedForUpstream,
160    AmbiguousRequest,
161    ImplementationReservedForUpstream,
162    DeterministicRule,
163    RepositoryGraphRule,
164    AdvisoryDraftRule,
165    WeavatrixUnavailable,
166    OllamaUnavailable,
167}
168
169#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
170#[serde(rename_all = "camelCase")]
171pub struct RoutingDecision {
172    pub target: ExecutionTarget,
173    pub class: TaskClass,
174    pub risk: RiskLevel,
175    pub reasons: Vec<RoutingReason>,
176    /// True only for a bounded local draft which cannot mutate project state.
177    pub advisory_only: bool,
178    pub model_tier: ModelTier,
179    pub context: ContextPlan,
180}
181
182impl RoutingDecision {
183    #[must_use]
184    pub const fn approves_local_model(&self) -> bool {
185        matches!(self.target, ExecutionTarget::Ollama) && self.advisory_only
186    }
187}
188
189#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
190#[serde(rename_all = "snake_case")]
191pub enum ModelTier {
192    None,
193    LocalSmall,
194    LocalMedium,
195    UpstreamStrong,
196}
197
198#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
199#[serde(rename_all = "snake_case")]
200pub enum ContextStrategy {
201    Direct,
202    DeterministicExtraction,
203    WeavatrixEvidence,
204    CitationCompression,
205    UpstreamEvidence,
206}
207
208#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
209#[serde(rename_all = "camelCase")]
210pub struct ContextPlan {
211    pub strategy: ContextStrategy,
212    pub max_input_tokens: u32,
213    pub require_evidence_ids: bool,
214}
215
216/// Select a target through deterministic, fail-closed routing rules.
217#[must_use]
218pub fn route(request: &RoutingRequest) -> RoutingDecision {
219    route_with_classification(request, classify(&request.task))
220}
221
222/// Same policy as [`route`], with a precomputed classification.
223///
224/// Keeps every guard and target rule. Callers that ask a gated local model for
225/// a tier still go through this path so lexical under-calls cannot bypass
226/// high-risk or mutation floors.
227#[must_use]
228pub fn route_with_classification(
229    request: &RoutingRequest,
230    classification: Classification,
231) -> RoutingDecision {
232    let mut reasons = guard_reasons(request);
233    if classification.class.requires_verified_evidence()
234        && request.evidence == EvidenceStatus::NotRequired
235    {
236        reasons.push(RoutingReason::MissingEvidence);
237    }
238    if classification.class.is_high_risk() {
239        reasons.push(RoutingReason::HighRiskTask(classification.class));
240    }
241    if request.mutation == MutationStatus::ApprovalRequired {
242        reasons.push(RoutingReason::MutationApprovalRequired);
243    }
244    if request.mutation != MutationStatus::None || classification.mutation_likely {
245        reasons.push(RoutingReason::MutationReservedForUpstream);
246    }
247
248    if !reasons.is_empty() {
249        return upstream(classification, reasons, request);
250    }
251
252    match classification.class {
253        TaskClass::Deterministic => decision(
254            ExecutionTarget::Deterministic,
255            classification,
256            RoutingReason::DeterministicRule,
257            false,
258            ModelTier::None,
259            ContextStrategy::DeterministicExtraction,
260            request,
261        ),
262        TaskClass::RepositoryAnalysis if request.availability.weavatrix => decision(
263            ExecutionTarget::Weavatrix,
264            classification,
265            RoutingReason::RepositoryGraphRule,
266            false,
267            ModelTier::None,
268            ContextStrategy::WeavatrixEvidence,
269            request,
270        ),
271        TaskClass::RepositoryAnalysis => upstream(
272            classification,
273            vec![RoutingReason::WeavatrixUnavailable],
274            request,
275        ),
276        TaskClass::StructuredExtraction if request.availability.ollama => decision(
277            ExecutionTarget::Ollama,
278            classification,
279            RoutingReason::AdvisoryDraftRule,
280            true,
281            ModelTier::LocalSmall,
282            ContextStrategy::DeterministicExtraction,
283            request,
284        ),
285        TaskClass::ContextCompression | TaskClass::AdvisoryDraft if request.availability.ollama => {
286            decision(
287                ExecutionTarget::Ollama,
288                classification,
289                RoutingReason::AdvisoryDraftRule,
290                true,
291                ModelTier::LocalMedium,
292                ContextStrategy::CitationCompression,
293                request,
294            )
295        }
296        TaskClass::StructuredExtraction
297        | TaskClass::ContextCompression
298        | TaskClass::AdvisoryDraft => upstream(
299            classification,
300            vec![RoutingReason::OllamaUnavailable],
301            request,
302        ),
303        TaskClass::Implementation => upstream(
304            classification,
305            vec![RoutingReason::ImplementationReservedForUpstream],
306            request,
307        ),
308        TaskClass::Ambiguous => upstream(
309            classification,
310            vec![RoutingReason::AmbiguousRequest],
311            request,
312        ),
313        _ => upstream(
314            classification,
315            vec![RoutingReason::HighRiskTask(classification.class)],
316            request,
317        ),
318    }
319}
320
321/// Map a task class to the model tier the routing policy grants it.
322#[must_use]
323pub const fn policy_tier(class: TaskClass) -> ModelTier {
324    match class {
325        TaskClass::Deterministic | TaskClass::RepositoryAnalysis => ModelTier::None,
326        TaskClass::StructuredExtraction => ModelTier::LocalSmall,
327        TaskClass::ContextCompression | TaskClass::AdvisoryDraft => ModelTier::LocalMedium,
328        TaskClass::Implementation
329        | TaskClass::Security
330        | TaskClass::Authentication
331        | TaskClass::Concurrency
332        | TaskClass::Migration
333        | TaskClass::Release
334        | TaskClass::Deployment
335        | TaskClass::Publication
336        | TaskClass::Ambiguous => ModelTier::UpstreamStrong,
337    }
338}
339
340/// Rank tiers so under-calls are detectable without floating point.
341#[must_use]
342pub const fn tier_rank(tier: ModelTier) -> u8 {
343    match tier {
344        ModelTier::None => 0,
345        ModelTier::LocalSmall => 1,
346        ModelTier::LocalMedium => 2,
347        ModelTier::UpstreamStrong => 3,
348    }
349}
350
351/// Parse a closed-set label into a [`ModelTier`].
352#[must_use]
353pub fn parse_model_tier(label: &str) -> Option<ModelTier> {
354    match label.trim().to_ascii_lowercase().as_str() {
355        "none" => Some(ModelTier::None),
356        "local_small" => Some(ModelTier::LocalSmall),
357        "local_medium" => Some(ModelTier::LocalMedium),
358        "upstream_strong" => Some(ModelTier::UpstreamStrong),
359        _ => None,
360    }
361}
362
363/// Turn a model-chosen tier into a [`Classification`], retaining lexical
364/// mutation cues and preferring a more specific lexical class when the tier
365/// matches.
366#[must_use]
367pub fn classification_for_tier(tier: ModelTier, lexical: Classification) -> Classification {
368    let class = match tier {
369        ModelTier::None => {
370            if matches!(lexical.class, TaskClass::RepositoryAnalysis) {
371                TaskClass::RepositoryAnalysis
372            } else {
373                TaskClass::Deterministic
374            }
375        }
376        ModelTier::LocalSmall => TaskClass::StructuredExtraction,
377        ModelTier::LocalMedium => {
378            if matches!(lexical.class, TaskClass::ContextCompression) {
379                TaskClass::ContextCompression
380            } else {
381                TaskClass::AdvisoryDraft
382            }
383        }
384        ModelTier::UpstreamStrong => {
385            if lexical.class.is_high_risk()
386                || matches!(
387                    lexical.class,
388                    TaskClass::Implementation | TaskClass::Ambiguous
389                )
390            {
391                lexical.class
392            } else {
393                TaskClass::Ambiguous
394            }
395        }
396    };
397    let risk = if class.is_high_risk() {
398        RiskLevel::High
399    } else if matches!(
400        class,
401        TaskClass::Implementation | TaskClass::RepositoryAnalysis
402    ) {
403        RiskLevel::Medium
404    } else {
405        RiskLevel::Low
406    };
407    Classification {
408        class,
409        risk,
410        mutation_likely: lexical.mutation_likely,
411    }
412}
413
414fn guard_reasons(request: &RoutingRequest) -> Vec<RoutingReason> {
415    let mut reasons = Vec::new();
416    match request.evidence {
417        EvidenceStatus::Missing => reasons.push(RoutingReason::MissingEvidence),
418        EvidenceStatus::Contradictory => reasons.push(RoutingReason::ContradictoryEvidence),
419        EvidenceStatus::NotRequired | EvidenceStatus::Verified => {}
420    }
421    if !request.schema_valid {
422        reasons.push(RoutingReason::SchemaValidationFailed);
423    }
424    if request.budget.estimated_input_tokens > request.budget.max_input_tokens {
425        reasons.push(RoutingReason::InputBudgetExceeded {
426            estimated: request.budget.estimated_input_tokens,
427            limit: request.budget.max_input_tokens,
428        });
429    }
430    if request.budget.estimated_output_tokens > request.budget.max_output_tokens {
431        reasons.push(RoutingReason::OutputBudgetExceeded {
432            estimated: request.budget.estimated_output_tokens,
433            limit: request.budget.max_output_tokens,
434        });
435    }
436    reasons
437}
438
439fn decision(
440    target: ExecutionTarget,
441    classification: Classification,
442    reason: RoutingReason,
443    advisory_only: bool,
444    model_tier: ModelTier,
445    strategy: ContextStrategy,
446    request: &RoutingRequest,
447) -> RoutingDecision {
448    RoutingDecision {
449        target,
450        class: classification.class,
451        risk: classification.risk,
452        reasons: vec![reason],
453        advisory_only,
454        model_tier,
455        context: ContextPlan {
456            strategy,
457            max_input_tokens: request.budget.max_input_tokens,
458            require_evidence_ids: matches!(
459                strategy,
460                ContextStrategy::WeavatrixEvidence | ContextStrategy::CitationCompression
461            ),
462        },
463    }
464}
465
466/// Default evidence ceiling for upstream work when the caller allows more.
467pub const UPSTREAM_EVIDENCE_TOKENS: u32 = 8_192;
468
469fn upstream(
470    classification: Classification,
471    reasons: Vec<RoutingReason>,
472    request: &RoutingRequest,
473) -> RoutingDecision {
474    RoutingDecision {
475        target: ExecutionTarget::Upstream,
476        class: classification.class,
477        risk: classification.risk.max(RiskLevel::Medium),
478        reasons,
479        advisory_only: false,
480        model_tier: ModelTier::UpstreamStrong,
481        context: ContextPlan {
482            strategy: ContextStrategy::UpstreamEvidence,
483            // Never exceed the caller's declared bound: a plan that reports
484            // more than the request allows would break the budget contract.
485            max_input_tokens: request
486                .budget
487                .max_input_tokens
488                .min(UPSTREAM_EVIDENCE_TOKENS),
489            require_evidence_ids: true,
490        },
491    }
492}
493
494#[cfg(test)]
495mod tests;