batuta/oracle/
types.rs

1//! Oracle Mode type definitions
2//!
3//! Based on Oracle Mode Specification v1.0 (BATUTA-ORACLE-001)
4
5use serde::{Deserialize, Serialize};
6
7// =============================================================================
8// Stack Layer Definitions
9// =============================================================================
10
11/// Layer in the Sovereign AI Stack hierarchy
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
13pub enum StackLayer {
14    /// Layer 0: Compute primitives (trueno, trueno-db, trueno-graph)
15    Primitives,
16    /// Layer 1: ML algorithms (aprender)
17    MlAlgorithms,
18    /// Layer 2: Training & inference (entrenar, realizar, simular)
19    MlPipeline,
20    /// Layer 3: Transpilers (depyler, decy, bashrs)
21    Transpilers,
22    /// Layer 4: Orchestration (batuta, repartir)
23    Orchestration,
24    /// Layer 5: Quality & profiling (certeza, pmat, renacer, probar)
25    Quality,
26    /// Layer 6: Data loading (alimentar)
27    Data,
28    /// Layer 7: Media production (rmedia)
29    Media,
30}
31
32impl StackLayer {
33    /// Get numeric layer index
34    pub fn index(&self) -> u8 {
35        match self {
36            StackLayer::Primitives => 0,
37            StackLayer::MlAlgorithms => 1,
38            StackLayer::MlPipeline => 2,
39            StackLayer::Transpilers => 3,
40            StackLayer::Orchestration => 4,
41            StackLayer::Quality => 5,
42            StackLayer::Data => 6,
43            StackLayer::Media => 7,
44        }
45    }
46
47    /// Get all layers in order
48    pub fn all() -> Vec<StackLayer> {
49        vec![
50            StackLayer::Primitives,
51            StackLayer::MlAlgorithms,
52            StackLayer::MlPipeline,
53            StackLayer::Transpilers,
54            StackLayer::Orchestration,
55            StackLayer::Quality,
56            StackLayer::Data,
57            StackLayer::Media,
58        ]
59    }
60}
61
62impl std::fmt::Display for StackLayer {
63    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
64        match self {
65            StackLayer::Primitives => write!(f, "Compute Primitives"),
66            StackLayer::MlAlgorithms => write!(f, "ML Algorithms"),
67            StackLayer::MlPipeline => write!(f, "Training & Inference"),
68            StackLayer::Transpilers => write!(f, "Transpilers"),
69            StackLayer::Orchestration => write!(f, "Orchestration"),
70            StackLayer::Quality => write!(f, "Quality & Profiling"),
71            StackLayer::Data => write!(f, "Data Loading"),
72            StackLayer::Media => write!(f, "Media Production"),
73        }
74    }
75}
76
77// =============================================================================
78// Capability Definitions
79// =============================================================================
80
81/// Category of capability
82#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
83pub enum CapabilityCategory {
84    Compute,
85    Storage,
86    MachineLearning,
87    Transpilation,
88    Validation,
89    Profiling,
90    Distribution,
91    Media,
92    ContentGeneration,
93}
94
95/// A capability provided by a component
96#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
97pub struct Capability {
98    pub name: String,
99    pub category: CapabilityCategory,
100    pub description: Option<String>,
101}
102
103impl Capability {
104    pub fn new(name: impl Into<String>, category: CapabilityCategory) -> Self {
105        Self { name: name.into(), category, description: None }
106    }
107
108    pub fn with_description(mut self, desc: impl Into<String>) -> Self {
109        self.description = Some(desc.into());
110        self
111    }
112}
113
114// =============================================================================
115// Component Definitions
116// =============================================================================
117
118/// A component in the Sovereign AI Stack
119#[derive(Debug, Clone, Serialize, Deserialize)]
120pub struct StackComponent {
121    /// Component name (e.g., "trueno", "aprender")
122    pub name: String,
123    /// Component version
124    pub version: String,
125    /// Stack layer
126    pub layer: StackLayer,
127    /// Description of component purpose
128    pub description: String,
129    /// Capabilities provided
130    pub capabilities: Vec<Capability>,
131    /// Crates.io package name (if different from name)
132    pub crate_name: Option<String>,
133    /// Academic references
134    pub references: Vec<Citation>,
135}
136
137impl StackComponent {
138    pub fn new(
139        name: impl Into<String>,
140        version: impl Into<String>,
141        layer: StackLayer,
142        description: impl Into<String>,
143    ) -> Self {
144        Self {
145            name: name.into(),
146            version: version.into(),
147            layer,
148            description: description.into(),
149            capabilities: Vec::new(),
150            crate_name: None,
151            references: Vec::new(),
152        }
153    }
154
155    pub fn with_capability(mut self, cap: Capability) -> Self {
156        self.capabilities.push(cap);
157        self
158    }
159
160    pub fn with_capabilities(mut self, caps: Vec<Capability>) -> Self {
161        self.capabilities.extend(caps);
162        self
163    }
164
165    pub fn has_capability(&self, name: &str) -> bool {
166        self.capabilities.iter().any(|c| c.name == name)
167    }
168}
169
170/// Academic citation/reference
171#[derive(Debug, Clone, Serialize, Deserialize)]
172pub struct Citation {
173    pub id: u32,
174    pub authors: String,
175    pub year: u16,
176    pub title: String,
177    pub venue: Option<String>,
178}
179
180// =============================================================================
181// Query Types
182// =============================================================================
183
184/// Hardware specification for queries
185#[derive(Debug, Clone, Default, Serialize, Deserialize)]
186pub struct HardwareSpec {
187    pub has_gpu: bool,
188    pub gpu_memory_gb: Option<f32>,
189    pub cpu_cores: Option<u32>,
190    pub ram_gb: Option<f32>,
191    pub is_distributed: bool,
192    pub node_count: Option<u32>,
193}
194
195impl HardwareSpec {
196    pub fn cpu_only() -> Self {
197        Self { has_gpu: false, ..Default::default() }
198    }
199
200    pub fn with_gpu(memory_gb: f32) -> Self {
201        Self { has_gpu: true, gpu_memory_gb: Some(memory_gb), ..Default::default() }
202    }
203
204    pub fn has_gpu(&self) -> bool {
205        self.has_gpu
206    }
207}
208
209/// Data size specification
210#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
211pub enum DataSize {
212    /// Number of samples/rows
213    Samples(u64),
214    /// Size in bytes
215    Bytes(u64),
216    /// Unknown/unspecified
217    Unknown,
218}
219
220impl DataSize {
221    pub fn samples(n: u64) -> Self {
222        DataSize::Samples(n)
223    }
224
225    pub fn bytes(n: u64) -> Self {
226        DataSize::Bytes(n)
227    }
228
229    /// Get sample count if available
230    pub fn as_samples(&self) -> Option<u64> {
231        match self {
232            DataSize::Samples(n) => Some(*n),
233            _ => None,
234        }
235    }
236
237    /// Estimate if this is "large" data (>100K samples or >1GB)
238    pub fn is_large(&self) -> bool {
239        match self {
240            DataSize::Samples(n) => *n > 100_000,
241            DataSize::Bytes(n) => *n > 1_000_000_000,
242            DataSize::Unknown => false,
243        }
244    }
245}
246
247/// Optimization target for queries
248#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
249pub enum OptimizationTarget {
250    /// Optimize for execution speed
251    #[default]
252    Speed,
253    /// Optimize for memory efficiency
254    Memory,
255    /// Optimize for power efficiency
256    Power,
257    /// Balance all factors
258    Balanced,
259}
260
261/// Query constraints
262#[derive(Debug, Clone, Default, Serialize, Deserialize)]
263pub struct QueryConstraints {
264    /// Maximum latency requirement (ms)
265    pub max_latency_ms: Option<u64>,
266    /// Data size
267    pub data_size: Option<DataSize>,
268    /// Must run locally (no cloud)
269    pub sovereign_only: bool,
270    /// EU AI Act compliance required
271    pub eu_compliant: bool,
272    /// Available hardware
273    pub hardware: HardwareSpec,
274}
275
276/// Query preferences
277#[derive(Debug, Clone, Default, Serialize, Deserialize)]
278pub struct QueryPreferences {
279    /// Optimization target
280    pub optimize_for: OptimizationTarget,
281    /// Preference for simpler solutions (0.0-1.0)
282    pub simplicity_weight: f32,
283    /// Existing stack components to integrate with
284    pub existing_components: Vec<String>,
285}
286
287/// Oracle query structure
288#[derive(Debug, Clone, Serialize, Deserialize)]
289pub struct OracleQuery {
290    /// Problem description in natural language
291    pub description: String,
292    /// Constraints
293    pub constraints: QueryConstraints,
294    /// Preferences
295    pub preferences: QueryPreferences,
296}
297
298impl OracleQuery {
299    pub fn new(description: impl Into<String>) -> Self {
300        Self {
301            description: description.into(),
302            constraints: QueryConstraints::default(),
303            preferences: QueryPreferences::default(),
304        }
305    }
306
307    pub fn with_constraints(mut self, constraints: QueryConstraints) -> Self {
308        self.constraints = constraints;
309        self
310    }
311
312    pub fn with_preferences(mut self, preferences: QueryPreferences) -> Self {
313        self.preferences = preferences;
314        self
315    }
316
317    pub fn with_data_size(mut self, size: DataSize) -> Self {
318        self.constraints.data_size = Some(size);
319        self
320    }
321
322    pub fn with_hardware(mut self, hardware: HardwareSpec) -> Self {
323        self.constraints.hardware = hardware;
324        self
325    }
326
327    pub fn sovereign_only(mut self) -> Self {
328        self.constraints.sovereign_only = true;
329        self
330    }
331
332    pub fn eu_compliant(mut self) -> Self {
333        self.constraints.eu_compliant = true;
334        self
335    }
336}
337
338// =============================================================================
339// Response Types
340// =============================================================================
341
342/// Compute backend selection
343#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
344#[allow(clippy::upper_case_acronyms)]
345pub enum Backend {
346    Scalar,
347    SIMD,
348    GPU,
349    Distributed,
350}
351
352impl std::fmt::Display for Backend {
353    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
354        match self {
355            Backend::Scalar => write!(f, "Scalar"),
356            Backend::SIMD => write!(f, "SIMD"),
357            Backend::GPU => write!(f, "GPU"),
358            Backend::Distributed => write!(f, "Distributed"),
359        }
360    }
361}
362
363/// Operation complexity classification
364#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
365pub enum OpComplexity {
366    /// O(n) - element-wise operations
367    Low,
368    /// O(n log n) to O(n²) - reductions, sorts
369    Medium,
370    /// O(n²) to O(n³) - matrix operations
371    High,
372}
373
374/// Compute recommendation
375#[derive(Debug, Clone, Serialize, Deserialize)]
376pub struct ComputeRecommendation {
377    pub backend: Backend,
378    pub rationale: String,
379}
380
381/// Distribution recommendation
382#[derive(Debug, Clone, Serialize, Deserialize)]
383pub struct DistributionRecommendation {
384    pub tool: Option<String>,
385    pub needed: bool,
386    pub rationale: String,
387    pub node_count: Option<u32>,
388}
389
390impl DistributionRecommendation {
391    pub fn not_needed(rationale: impl Into<String>) -> Self {
392        Self { tool: None, needed: false, rationale: rationale.into(), node_count: None }
393    }
394}
395
396/// Component recommendation with confidence
397#[derive(Debug, Clone, Serialize, Deserialize)]
398pub struct ComponentRecommendation {
399    /// Component name
400    pub component: String,
401    /// Specific module/function path (e.g., "aprender::tree::RandomForest")
402    pub path: Option<String>,
403    /// Confidence score (0.0-1.0)
404    pub confidence: f32,
405    /// Reason for recommendation
406    pub rationale: String,
407}
408
409impl ComponentRecommendation {
410    pub fn new(
411        component: impl Into<String>,
412        confidence: f32,
413        rationale: impl Into<String>,
414    ) -> Self {
415        Self { component: component.into(), confidence, rationale: rationale.into(), path: None }
416    }
417
418    pub fn with_path(
419        component: impl Into<String>,
420        confidence: f32,
421        rationale: impl Into<String>,
422        path: String,
423    ) -> Self {
424        Self {
425            component: component.into(),
426            confidence,
427            rationale: rationale.into(),
428            path: Some(path),
429        }
430    }
431}
432
433/// Complete Oracle response
434#[derive(Debug, Clone, Serialize, Deserialize)]
435pub struct OracleResponse {
436    /// Problem classification
437    pub problem_class: String,
438    /// Detected algorithm/approach
439    pub algorithm: Option<String>,
440    /// Primary recommendation
441    pub primary: ComponentRecommendation,
442    /// Supporting components
443    pub supporting: Vec<ComponentRecommendation>,
444    /// Compute backend recommendation
445    pub compute: ComputeRecommendation,
446    /// Distribution recommendation
447    pub distribution: DistributionRecommendation,
448    /// Example code snippet
449    pub code_example: Option<String>,
450    /// Related queries for follow-up
451    pub related_queries: Vec<String>,
452}
453
454impl OracleResponse {
455    pub fn new(problem_class: impl Into<String>, primary: ComponentRecommendation) -> Self {
456        Self {
457            problem_class: problem_class.into(),
458            algorithm: None,
459            primary,
460            supporting: Vec::new(),
461            compute: ComputeRecommendation {
462                backend: Backend::SIMD,
463                rationale: "Default SIMD backend".into(),
464            },
465            distribution: DistributionRecommendation {
466                tool: None,
467                needed: false,
468                rationale: "Single-node sufficient".into(),
469                node_count: None,
470            },
471            code_example: None,
472            related_queries: Vec::new(),
473        }
474    }
475
476    pub fn with_algorithm(mut self, algo: impl Into<String>) -> Self {
477        self.algorithm = Some(algo.into());
478        self
479    }
480
481    pub fn with_supporting(mut self, rec: ComponentRecommendation) -> Self {
482        self.supporting.push(rec);
483        self
484    }
485
486    pub fn with_compute(mut self, compute: ComputeRecommendation) -> Self {
487        self.compute = compute;
488        self
489    }
490
491    pub fn with_distribution(mut self, dist: DistributionRecommendation) -> Self {
492        self.distribution = dist;
493        self
494    }
495
496    pub fn with_code_example(mut self, code: impl Into<String>) -> Self {
497        self.code_example = Some(code.into());
498        self
499    }
500}
501
502// =============================================================================
503// Problem Domain Classification
504// =============================================================================
505
506/// Problem domain for classification
507#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
508pub enum ProblemDomain {
509    // ML domains
510    SupervisedLearning,
511    UnsupervisedLearning,
512    DeepLearning,
513    Inference,
514    SpeechRecognition,
515    // Compute domains
516    LinearAlgebra,
517    VectorSearch,
518    GraphAnalytics,
519    // Transpilation domains
520    PythonMigration,
521    CMigration,
522    ShellMigration,
523    // Infrastructure domains
524    DistributedCompute,
525    DataPipeline,
526    ModelServing,
527    // Quality domains
528    Testing,
529    Profiling,
530    Validation,
531    // Media domains
532    MediaProduction,
533}
534
535impl std::fmt::Display for ProblemDomain {
536    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
537        match self {
538            ProblemDomain::SupervisedLearning => write!(f, "Supervised Learning"),
539            ProblemDomain::UnsupervisedLearning => write!(f, "Unsupervised Learning"),
540            ProblemDomain::DeepLearning => write!(f, "Deep Learning"),
541            ProblemDomain::Inference => write!(f, "Model Inference"),
542            ProblemDomain::SpeechRecognition => write!(f, "Speech Recognition"),
543            ProblemDomain::LinearAlgebra => write!(f, "Linear Algebra"),
544            ProblemDomain::VectorSearch => write!(f, "Vector Search"),
545            ProblemDomain::GraphAnalytics => write!(f, "Graph Analytics"),
546            ProblemDomain::PythonMigration => write!(f, "Python Migration"),
547            ProblemDomain::CMigration => write!(f, "C/C++ Migration"),
548            ProblemDomain::ShellMigration => write!(f, "Shell Migration"),
549            ProblemDomain::DistributedCompute => write!(f, "Distributed Computing"),
550            ProblemDomain::DataPipeline => write!(f, "Data Pipeline"),
551            ProblemDomain::ModelServing => write!(f, "Model Serving"),
552            ProblemDomain::Testing => write!(f, "Testing"),
553            ProblemDomain::Profiling => write!(f, "Profiling"),
554            ProblemDomain::Validation => write!(f, "Validation"),
555            ProblemDomain::MediaProduction => write!(f, "Media Production"),
556        }
557    }
558}
559
560// =============================================================================
561// Integration Patterns
562// =============================================================================
563
564/// Integration pattern between components
565#[derive(Debug, Clone, Serialize, Deserialize)]
566pub struct IntegrationPattern {
567    pub from: String,
568    pub to: String,
569    pub pattern_name: String,
570    pub description: String,
571    pub code_template: Option<String>,
572}
573
574// =============================================================================
575// Tests
576// =============================================================================
577
578#[cfg(test)]
579#[path = "types_tests.rs"]
580mod tests;
batuta/oracle/types.rs

batuta/oracle/
types.rs
