oxirs_embed/api/
types.rs

1//! Request and response types for the API
2//!
3//! This module contains all the data structures used for API requests and responses.
4
5use crate::{ModelStats, TrainingStats, Vector};
6use chrono::{DateTime, Utc};
7use serde::{Deserialize, Serialize};
8use std::collections::HashMap;
9use uuid::Uuid;
10
11/// Basic embedding request
12#[derive(Debug, Clone, Serialize, Deserialize)]
13pub struct EmbeddingRequest {
14    /// Entity ID to get embedding for
15    pub entity_id: String,
16    /// Entity ID (alias for compatibility)
17    pub entity: String,
18    /// Optional model ID to use
19    pub model_id: Option<Uuid>,
20    /// Optional model version to use
21    pub model_version: Option<String>,
22    /// Use cached result if available
23    pub use_cache: Option<bool>,
24}
25
26/// Basic embedding response
27#[derive(Debug, Clone, Serialize, Deserialize)]
28pub struct EmbeddingResponse {
29    /// Entity ID
30    pub entity_id: String,
31    /// Entity ID (alias for compatibility)
32    pub entity: String,
33    /// Generated embedding vector
34    pub embedding: Vector,
35    /// Embedding dimensions
36    pub dimensions: usize,
37    /// Model ID used
38    pub model_id: Uuid,
39    /// Model version used
40    pub model_version: String,
41    /// Whether result came from cache
42    pub from_cache: bool,
43    /// Generation time in milliseconds
44    pub generation_time_ms: f64,
45}
46
47/// Batch embedding request
48#[derive(Debug, Clone, Serialize, Deserialize)]
49pub struct BatchEmbeddingRequest {
50    /// List of entity IDs
51    pub entity_ids: Vec<String>,
52    /// List of entities (alias for compatibility)
53    pub entities: Vec<String>,
54    /// Optional model ID to use
55    pub model_id: Option<Uuid>,
56    /// Optional model version to use
57    pub model_version: Option<String>,
58    /// Use cached result if available
59    pub use_cache: Option<bool>,
60    /// Batch processing options
61    pub options: Option<BatchOptions>,
62}
63
64/// Batch processing options
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct BatchOptions {
67    /// Use cached results if available
68    pub use_cache: Option<bool>,
69    /// Parallel processing batch size
70    pub batch_size: Option<usize>,
71}
72
73/// Batch embedding response
74#[derive(Debug, Clone, Serialize, Deserialize)]
75pub struct BatchEmbeddingResponse {
76    /// Embedding results
77    pub embeddings: Vec<EmbeddingResponse>,
78    /// Total processing time in milliseconds
79    pub total_time_ms: f64,
80    /// Number of cache hits
81    pub cache_hits: usize,
82    /// Number of cache misses
83    pub cache_misses: usize,
84    /// Model ID used
85    pub model_id: Uuid,
86}
87
88/// Text embedding request
89#[derive(Debug, Clone, Serialize, Deserialize)]
90pub struct TextEmbeddingRequest {
91    /// Text to embed
92    pub text: String,
93    /// Optional text type hint
94    pub text_type: Option<String>,
95    /// Optional model ID to use
96    pub model_id: Option<Uuid>,
97    /// Language hint (ISO 639-1)
98    pub language: Option<String>,
99    /// Use cached result if available
100    pub use_cache: Option<bool>,
101}
102
103/// Text embedding response
104#[derive(Debug, Clone, Serialize, Deserialize)]
105pub struct TextEmbeddingResponse {
106    /// Original text
107    pub text: String,
108    /// Generated embedding vector
109    pub embedding: Vector,
110    /// Detected language (if applicable)
111    pub detected_language: Option<String>,
112    /// Model ID used
113    pub model_id: Uuid,
114    /// Whether result came from cache
115    pub from_cache: bool,
116    /// Generation time in milliseconds
117    pub generation_time_ms: f64,
118}
119
120/// Multi-modal embedding request
121#[derive(Debug, Clone, Serialize, Deserialize)]
122pub struct MultiModalRequest {
123    /// Text content
124    pub text: Option<String>,
125    /// Knowledge graph entities
126    pub entities: Option<Vec<String>>,
127    /// Optional model ID to use
128    pub model_id: Option<Uuid>,
129    /// Fusion strategy
130    pub fusion_strategy: Option<String>,
131    /// Use cached result if available
132    pub use_cache: Option<bool>,
133}
134
135/// Multi-modal embedding response
136#[derive(Debug, Clone, Serialize, Deserialize)]
137pub struct MultiModalResponse {
138    /// Generated unified embedding
139    pub embedding: Vector,
140    /// Individual component embeddings
141    pub component_embeddings: HashMap<String, Vector>,
142    /// Fusion strategy used
143    pub fusion_strategy: String,
144    /// Model ID used
145    pub model_id: Uuid,
146    /// Whether result came from cache
147    pub from_cache: bool,
148    /// Generation time in milliseconds
149    pub generation_time_ms: f64,
150}
151
152/// Stream embedding request
153#[derive(Debug, Clone, Serialize, Deserialize)]
154pub struct StreamEmbeddingRequest {
155    /// Stream of items to embed
156    pub items: Vec<StreamEmbeddingItem>,
157    /// Optional model ID to use
158    pub model_id: Option<Uuid>,
159    /// Streaming options
160    pub options: Option<BatchOptions>,
161}
162
163/// Individual item in streaming request
164#[derive(Debug, Clone, Serialize, Deserialize)]
165pub struct StreamEmbeddingItem {
166    /// Item ID
167    pub id: String,
168    /// Item content (text or entity ID)
169    pub content: String,
170    /// Content type
171    pub content_type: String,
172}
173
174/// Triple scoring request
175#[derive(Debug, Clone, Serialize, Deserialize)]
176pub struct TripleScoreRequest {
177    /// Subject entity
178    pub subject: String,
179    /// Predicate relation
180    pub predicate: String,
181    /// Object entity
182    pub object: String,
183    /// Optional model ID to use
184    pub model_id: Option<Uuid>,
185    /// Optional model version to use
186    pub model_version: Option<String>,
187    /// Use cached result if available
188    pub use_cache: Option<bool>,
189}
190
191/// Triple scoring response
192#[derive(Debug, Clone, Serialize, Deserialize)]
193pub struct TripleScoreResponse {
194    /// Subject entity
195    pub subject: String,
196    /// Predicate relation
197    pub predicate: String,
198    /// Object entity
199    pub object: String,
200    /// Triple (subject, predicate, object)
201    pub triple: (String, String, String),
202    /// Plausibility score
203    pub score: f64,
204    /// Model ID used
205    pub model_id: Uuid,
206    /// Model version used
207    pub model_version: String,
208    /// Whether result came from cache
209    pub from_cache: bool,
210    /// Computation time in milliseconds
211    pub computation_time_ms: f64,
212    /// Scoring time in milliseconds
213    pub scoring_time_ms: f64,
214}
215
216/// Prediction request
217#[derive(Debug, Clone, Serialize, Deserialize)]
218pub struct PredictionRequest {
219    /// Input entities
220    pub entities: Vec<String>,
221    /// Prediction type
222    pub prediction_type: PredictionType,
223    /// Number of predictions to return
224    pub top_k: Option<usize>,
225    /// Optional model ID to use
226    pub model_id: Option<Uuid>,
227    /// Use cached result if available
228    pub use_cache: Option<bool>,
229}
230
231/// Types of predictions
232#[derive(Debug, Clone, Serialize, Deserialize)]
233pub enum PredictionType {
234    /// Predict missing objects
235    Objects { subject: String, predicate: String },
236    /// Predict missing subjects
237    Subjects { predicate: String, object: String },
238    /// Predict missing relations
239    Relations { subject: String, object: String },
240}
241
242/// Prediction response
243#[derive(Debug, Clone, Serialize, Deserialize)]
244pub struct PredictionResponse {
245    /// Input entities
246    pub input: Vec<String>,
247    /// Prediction type
248    pub prediction_type: String,
249    /// Predictions with scores
250    pub predictions: Vec<(String, f64)>,
251    /// Model version used
252    pub model_version: String,
253    /// Whether result came from cache
254    pub from_cache: bool,
255    /// Prediction time in milliseconds
256    pub prediction_time_ms: f64,
257}
258
259/// Model information request
260#[derive(Debug, Clone, Serialize, Deserialize)]
261pub struct ModelInfoRequest {
262    /// Optional specific model ID
263    pub model_id: Option<Uuid>,
264}
265
266/// Model information response
267#[derive(Debug, Clone, Serialize, Deserialize)]
268pub struct ModelInfoResponse {
269    /// Model statistics
270    pub stats: ModelStats,
271    /// Model health status
272    pub health: ModelHealth,
273    /// Available operations
274    pub capabilities: Vec<String>,
275    /// Last training statistics
276    pub last_training: Option<TrainingStats>,
277}
278
279/// Model health information
280#[derive(Debug, Clone, Serialize, Deserialize)]
281pub struct ModelHealth {
282    /// Current health status
283    pub status: HealthStatus,
284    /// Last health check timestamp
285    pub last_check: DateTime<Utc>,
286    /// Performance metrics
287    pub metrics: HealthMetrics,
288}
289
290/// Health status enumeration
291#[derive(Debug, Clone, Serialize, Deserialize)]
292pub enum HealthStatus {
293    /// Model is healthy and operational
294    Healthy,
295    /// Model is operational but with degraded performance
296    Degraded,
297    /// Model is not operational
298    Unhealthy,
299}
300
301/// Performance metrics for health checking
302#[derive(Debug, Clone, Serialize, Deserialize)]
303pub struct HealthMetrics {
304    /// Average response time in milliseconds
305    pub avg_response_time_ms: f64,
306    /// Number of requests in the last hour
307    pub requests_last_hour: u64,
308    /// Error rate percentage
309    pub error_rate_percent: f64,
310    /// Memory usage in MB
311    pub memory_usage_mb: f64,
312}
313
314/// Query parameters for API endpoints
315#[derive(Debug, Clone, Serialize, Deserialize)]
316pub struct QueryParams {
317    /// Optional limit for results
318    pub limit: Option<usize>,
319    /// Optional offset for pagination
320    pub offset: Option<usize>,
321    /// Optional model ID filter
322    pub model_id: Option<Uuid>,
323    /// Optional format specification
324    pub format: Option<String>,
325    /// Include detailed information
326    pub detailed: Option<bool>,
327}
oxirs_embed/api/types.rs

oxirs_embed/api/
types.rs
