righvalor 0.1.0

RighValor: AI Infrastructure and Applications Framework for the Far Edge
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

/// # Valor Runtime Layer
///
/// This module implements the Valor Runtime layer within the RighValor Framework,
/// providing execution environments for various computational workloads and AI/ML models.
/// The runtime layer abstracts different execution engines and provides a unified
/// interface for service execution across diverse platforms.
///
/// ## Supported Runtime Engines
///
/// The Valor Runtime supports four primary execution engines:
///
/// - **ONNX**: Open Neural Network Exchange runtime for cross-platform AI model execution
/// - **TensorFlow**: TensorFlow execution environment for machine learning workloads
/// - **WASM**: WebAssembly runtime for portable, sandboxed execution
/// - **Cmd**: Command-line and native binary execution environment
///
/// ## Runtime Architecture
///
/// The runtime layer provides:
/// - **Engine Abstraction**: Unified interface across different execution engines
/// - **Service Execution**: Execution environment for Valor services
/// - **Resource Management**: Runtime resource allocation and lifecycle management
/// - **Platform Integration**: Integration with underlying platform capabilities
///
/// ## Integration with Service Framework
///
/// Services from the Service Registry are executed through the appropriate runtime engine
/// based on their requirements and the target deployment environment. The runtime layer
/// handles the execution details while providing consistent interfaces to the service layer.
///
/// ## Usage Example
///
/// ```rust
/// use valor::runtime::{ValorRuntime, ValorRuntimeEngine};
///
/// // Select appropriate runtime based on service requirements
/// let runtime_engine = match service_type {
///     ServiceType::AIModel => ValorRuntimeEngine::Onnx,
///     ServiceType::MLWorkload => ValorRuntimeEngine::TensorFlow,
///     ServiceType::Portable => ValorRuntimeEngine::Wasm,
///     ServiceType::Native => ValorRuntimeEngine::Cmd,
/// };
/// ```
use anyhow::Result;
use serde::{Deserialize, Serialize};
use strum::{Display, EnumString};
use utoipa::ToSchema;

/// Enumeration of supported runtime engines within the Valor Runtime layer.
///
/// Each variant represents a specific execution environment optimized for
/// different types of computational workloads and deployment scenarios.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, EnumString, Display)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum ValorRuntimeEngine {
    /// ONNX (Open Neural Network Exchange) runtime engine
    ///
    /// Provides cross-platform execution for AI models in ONNX format,
    /// enabling interoperability across different AI frameworks and platforms.
    Onnx,

    /// TensorFlow runtime engine
    ///
    /// Native TensorFlow execution environment for machine learning workloads,
    /// supporting both training and inference operations.
    TensorFlow,

    /// WebAssembly (WASM) runtime engine
    ///
    /// Portable execution environment providing sandboxed, cross-platform
    /// execution for services compiled to WebAssembly bytecode.
    Wasm,

    /// Command-line runtime engine
    ///
    /// Native binary execution environment for command-line tools,
    /// scripts, and platform-specific executable services.
    Cmd,
}

/// Core trait defining the runtime interface for Valor execution engines.
///
/// This trait provides a consistent interface for starting and stopping
/// runtime engines, abstracting the underlying implementation details
/// of different execution environments.
///
/// ## Implementation Requirements
///
/// Implementing types must provide:
/// - **Lifecycle Management**: Start and stop operations for the runtime
/// - **Error Handling**: Proper error reporting for runtime operations
/// - **Resource Cleanup**: Proper resource cleanup on stop operations
///
/// ## Example Implementation
///
/// ```rust
/// impl ValorRuntime for MyRuntimeEngine {
///     fn start(&self) -> anyhow::Result<()> {
///         // Initialize runtime engine
///         // Set up execution environment
///         // Allocate necessary resources
///         Ok(())
///     }
///     
///     fn stop(&self) -> anyhow::Result<()> {
///         // Clean up runtime resources
///         // Shutdown execution environment
///         // Release allocated resources
///         Ok(())
///     }
/// }
/// ```
#[allow(unused)]
pub trait ValorRuntime {
    /// Start the runtime engine and initialize the execution environment.
    ///
    /// This method should:
    /// - Initialize the underlying execution engine
    /// - Set up necessary runtime resources
    /// - Prepare the environment for service execution
    ///
    /// # Returns
    ///
    /// * `Ok(())` - Runtime started successfully
    /// * `Err(anyhow::Error)` - Runtime startup failed with error details
    fn start(&self) -> Result<()>;

    /// Stop the runtime engine and clean up allocated resources.
    ///
    /// This method should:
    /// - Gracefully shutdown the execution environment
    /// - Release allocated runtime resources
    /// - Perform necessary cleanup operations
    ///
    /// # Returns
    ///
    /// * `Ok(())` - Runtime stopped successfully
    /// * `Err(anyhow::Error)` - Runtime shutdown failed with error details
    fn stop(&self) -> Result<()>;
}