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 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 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#[must_use]
218pub fn route(request: &RoutingRequest) -> RoutingDecision {
219 route_with_classification(request, classify(&request.task))
220}
221
222#[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#[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#[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#[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#[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
466pub 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 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;