Skip to main content

hyprstream_core/events/
mod.rs

1//! Event types for hyprstream
2//!
3//! This module defines event types for P2P messaging between hyprstream instances.
4//! Events will be delivered via DHT-based peer discovery (future work).
5//!
6//! # Topics
7//!
8//! Events use dot-notation topics:
9//! - `inference.generation_complete` - Generation completed with metrics
10//! - `inference.generation_failed` - Generation failed with error
11//! - `metrics.threshold_breach` - Quality metric threshold breached
12//! - `metrics.window_rollover` - Time window closed with stats
13//! - `training.started` - Training job started
14//! - `training.completed` - Training job completed
15//! - `training.checkpoint_saved` - Checkpoint committed to git
16//! - `git2db.repository_cloned` - Repository cloned
17//! - `git2db.commit_created` - Commit created
18//! - `git2db.adapter_saved` - Adapter saved to repository
19
20use chrono::{DateTime, Utc};
21use serde::{Deserialize, Serialize};
22use uuid::Uuid;
23
24/// Source of an event
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
26#[serde(rename_all = "snake_case")]
27pub enum EventSource {
28    /// LLM inference events
29    Inference,
30    /// Metrics aggregation events
31    Metrics,
32    /// Training job events
33    Training,
34    /// Git repository events
35    Git2db,
36    /// Model lifecycle events (load, unload, fail)
37    Model,
38}
39
40impl std::fmt::Display for EventSource {
41    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
42        match self {
43            EventSource::Inference => write!(f, "inference"),
44            EventSource::Metrics => write!(f, "metrics"),
45            EventSource::Training => write!(f, "training"),
46            EventSource::Git2db => write!(f, "git2db"),
47            EventSource::Model => write!(f, "model"),
48        }
49    }
50}
51
52/// Envelope containing event metadata and payload
53#[derive(Debug, Clone, Serialize, Deserialize)]
54pub struct EventEnvelope {
55    /// Unique event ID
56    pub id: Uuid,
57
58    /// Event timestamp
59    pub timestamp: DateTime<Utc>,
60
61    /// Optional correlation ID for event chains
62    /// (e.g., generation_complete → threshold_breach → training_started)
63    pub correlation_id: Option<Uuid>,
64
65    /// Event source
66    pub source: EventSource,
67
68    /// Topic for routing (e.g., "inference.generation_complete")
69    pub topic: String,
70
71    /// Event payload
72    pub payload: EventPayload,
73}
74
75impl EventEnvelope {
76    /// Create a new event envelope
77    pub fn new(source: EventSource, topic: impl Into<String>, payload: EventPayload) -> Self {
78        Self {
79            id: Uuid::new_v4(),
80            timestamp: Utc::now(),
81            correlation_id: None,
82            source,
83            topic: topic.into(),
84            payload,
85        }
86    }
87
88    /// Create a new event with correlation to a previous event
89    pub fn with_correlation(
90        source: EventSource,
91        topic: impl Into<String>,
92        payload: EventPayload,
93        correlation_id: Uuid,
94    ) -> Self {
95        Self {
96            id: Uuid::new_v4(),
97            timestamp: Utc::now(),
98            correlation_id: Some(correlation_id),
99            source,
100            topic: topic.into(),
101            payload,
102        }
103    }
104}
105
106/// Event payload variants
107#[derive(Debug, Clone, Serialize, Deserialize)]
108#[serde(tag = "type", rename_all = "snake_case")]
109pub enum EventPayload {
110    // ─────────────────────────────────────────────────────────────────────
111    // Inference Events
112    // ─────────────────────────────────────────────────────────────────────
113    /// Generation completed successfully
114    GenerationComplete {
115        /// Model identifier
116        model_id: String,
117        /// Session ID (for multi-turn conversations)
118        session_id: Option<String>,
119        /// Quality metrics from generation
120        metrics: GenerationMetrics,
121    },
122
123    /// Generation failed
124    GenerationFailed {
125        /// Model identifier
126        model_id: String,
127        /// Session ID
128        session_id: Option<String>,
129        /// Error message
130        error: String,
131        /// Error code (optional)
132        error_code: Option<String>,
133    },
134
135    /// Tool was executed during generation
136    ToolExecuted {
137        /// Model identifier
138        model_id: String,
139        /// Tool name
140        tool_name: String,
141        /// Tool execution result (success/failure)
142        success: bool,
143        /// Execution time in milliseconds
144        duration_ms: u64,
145    },
146
147    // ─────────────────────────────────────────────────────────────────────
148    // Model Lifecycle Events
149    // ─────────────────────────────────────────────────────────────────────
150    /// Model loaded and ready for inference
151    ModelLoaded {
152        /// Model reference (e.g., "qwen3:main")
153        model_ref: String,
154        /// Inference endpoint for this model
155        endpoint: String,
156    },
157
158    /// Model load failed
159    ModelFailed {
160        /// Model reference
161        model_ref: String,
162        /// Error message
163        error: String,
164    },
165
166    /// Model unloaded
167    ModelUnloaded {
168        /// Model reference
169        model_ref: String,
170    },
171
172    // ─────────────────────────────────────────────────────────────────────
173    // Metrics Events
174    // ─────────────────────────────────────────────────────────────────────
175    /// Quality threshold breached
176    ThresholdBreach {
177        /// Model identifier
178        model_id: String,
179        /// Metric name (perplexity, entropy, repetition_ratio)
180        metric: String,
181        /// Configured threshold
182        threshold: f64,
183        /// Actual value
184        actual: f64,
185        /// Z-score (standard deviations from baseline)
186        z_score: f64,
187    },
188
189    /// Time window rolled over with statistics
190    WindowRollover {
191        /// Model identifier
192        model_id: String,
193        /// Window statistics
194        stats: WindowedStats,
195    },
196
197    /// Baseline established for model
198    BaselineReady {
199        /// Model identifier
200        model_id: String,
201        /// Number of samples in baseline
202        sample_count: u64,
203        /// Baseline statistics
204        stats: WindowedStats,
205    },
206
207    // ─────────────────────────────────────────────────────────────────────
208    // Training Events
209    // ─────────────────────────────────────────────────────────────────────
210    /// Training job started
211    TrainingStarted {
212        /// Model identifier
213        model_id: String,
214        /// Adapter identifier
215        adapter_id: String,
216        /// Training configuration
217        config: TrainingConfig,
218    },
219
220    /// Training job completed
221    TrainingCompleted {
222        /// Model identifier
223        model_id: String,
224        /// Adapter identifier
225        adapter_id: String,
226        /// Total training steps
227        steps: u64,
228        /// Final loss value
229        final_loss: f32,
230    },
231
232    /// Checkpoint saved to repository
233    CheckpointSaved {
234        /// Model identifier
235        model_id: String,
236        /// Checkpoint identifier
237        checkpoint_id: String,
238        /// Git commit hash
239        commit_hash: String,
240    },
241
242    // ─────────────────────────────────────────────────────────────────────
243    // Git2db Events
244    // ─────────────────────────────────────────────────────────────────────
245    /// Repository cloned
246    RepositoryCloned {
247        /// Repository ID in registry
248        repo_id: String,
249        /// Repository name
250        name: String,
251        /// Source URL
252        url: String,
253    },
254
255    /// Branch created
256    BranchCreated {
257        /// Repository ID
258        repo_id: String,
259        /// Branch name
260        branch_name: String,
261        /// Base commit hash
262        base_commit: String,
263    },
264
265    /// Worktree created
266    WorktreeCreated {
267        /// Repository ID
268        repo_id: String,
269        /// Branch name
270        branch_name: String,
271        /// Worktree path
272        path: String,
273    },
274
275    /// Commit created
276    CommitCreated {
277        /// Repository ID
278        repo_id: String,
279        /// Commit hash
280        hash: String,
281        /// Commit message
282        message: String,
283    },
284
285    /// Adapter saved to repository
286    AdapterSaved {
287        /// Repository ID
288        repo_id: String,
289        /// Adapter name
290        adapter_name: String,
291        /// Adapter index
292        index: u32,
293    },
294
295    /// Adapter loaded from repository
296    AdapterLoaded {
297        /// Repository ID
298        repo_id: String,
299        /// Adapter name
300        adapter_name: String,
301        /// Adapter index
302        index: u32,
303    },
304}
305
306/// Generation quality metrics (matches GenerationQualityMetrics)
307#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
308pub struct GenerationMetrics {
309    /// Perplexity: exp(-avg_log_prob)
310    pub perplexity: f32,
311    /// Average entropy of probability distributions
312    pub avg_entropy: f32,
313    /// Variance of entropy across tokens
314    pub entropy_variance: f32,
315    /// Ratio of repeated n-grams
316    pub repetition_ratio: f32,
317    /// Number of tokens generated
318    pub token_count: u32,
319    /// Tokens generated per second
320    pub tokens_per_second: f32,
321    /// Total generation time in milliseconds
322    pub generation_time_ms: u64,
323}
324
325impl From<crate::runtime::generation_metrics::GenerationQualityMetrics> for GenerationMetrics {
326    fn from(m: crate::runtime::generation_metrics::GenerationQualityMetrics) -> Self {
327        Self {
328            perplexity: m.perplexity,
329            avg_entropy: m.avg_entropy,
330            entropy_variance: m.entropy_variance,
331            repetition_ratio: m.repetition_ratio,
332            token_count: m.token_count,
333            // These fields are set separately at generation time
334            tokens_per_second: 0.0,
335            generation_time_ms: 0,
336        }
337    }
338}
339
340impl GenerationMetrics {
341    /// Create metrics with timing information from a GenerationQualityMetrics
342    pub fn with_timing(
343        m: crate::runtime::generation_metrics::GenerationQualityMetrics,
344        tokens_per_second: f32,
345        generation_time_ms: u64,
346    ) -> Self {
347        Self {
348            perplexity: m.perplexity,
349            avg_entropy: m.avg_entropy,
350            entropy_variance: m.entropy_variance,
351            repetition_ratio: m.repetition_ratio,
352            token_count: m.token_count,
353            tokens_per_second,
354            generation_time_ms,
355        }
356    }
357}
358
359/// Windowed statistics from Welford's algorithm
360#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
361pub struct WindowedStats {
362    /// Window duration in seconds
363    pub window_seconds: u64,
364    /// Sample count
365    pub sample_count: u64,
366    /// Mean perplexity
367    pub perplexity_mean: f64,
368    /// Perplexity standard deviation
369    pub perplexity_stddev: f64,
370    /// Mean entropy
371    pub entropy_mean: f64,
372    /// Entropy standard deviation
373    pub entropy_stddev: f64,
374}
375
376/// Training configuration summary
377#[derive(Debug, Clone, Serialize, Deserialize)]
378pub struct TrainingConfig {
379    /// LoRA rank
380    pub rank: u32,
381    /// Learning rate
382    pub learning_rate: f64,
383    /// Batch size
384    pub batch_size: u32,
385    /// Maximum steps
386    pub max_steps: Option<u64>,
387}
388
389#[cfg(test)]
390#[allow(clippy::expect_used, clippy::unwrap_used, clippy::print_stdout)]
391mod tests {
392    use super::*;
393
394    #[test]
395    fn test_event_envelope_creation() {
396        let event = EventEnvelope::new(
397            EventSource::Inference,
398            "inference.generation_complete",
399            EventPayload::GenerationComplete {
400                model_id: "qwen3-small".to_owned(),
401                session_id: None,
402                metrics: GenerationMetrics::default(),
403            },
404        );
405
406        assert_eq!(event.source, EventSource::Inference);
407        assert_eq!(event.topic, "inference.generation_complete");
408        assert!(event.correlation_id.is_none());
409    }
410
411    #[test]
412    fn test_event_serialization() {
413        let event = EventEnvelope::new(
414            EventSource::Metrics,
415            "metrics.threshold_breach",
416            EventPayload::ThresholdBreach {
417                model_id: "qwen3-small".to_owned(),
418                metric: "perplexity".to_owned(),
419                threshold: 50.0,
420                actual: 75.0,
421                z_score: 2.5,
422            },
423        );
424
425        let json = serde_json::to_string(&event).expect("test: serialize event");
426        let deserialized: EventEnvelope =
427            serde_json::from_str(&json).expect("test: deserialize event");
428
429        assert_eq!(deserialized.topic, "metrics.threshold_breach");
430    }
431
432    #[test]
433    fn test_event_correlation() {
434        let first = EventEnvelope::new(
435            EventSource::Metrics,
436            "metrics.threshold_breach",
437            EventPayload::ThresholdBreach {
438                model_id: "qwen3-small".to_owned(),
439                metric: "perplexity".to_owned(),
440                threshold: 50.0,
441                actual: 75.0,
442                z_score: 2.5,
443            },
444        );
445
446        let second = EventEnvelope::with_correlation(
447            EventSource::Training,
448            "training.started",
449            EventPayload::TrainingStarted {
450                model_id: "qwen3-small".to_owned(),
451                adapter_id: "auto-fix".to_owned(),
452                config: TrainingConfig {
453                    rank: 16,
454                    learning_rate: 1e-4,
455                    batch_size: 4,
456                    max_steps: Some(100),
457                },
458            },
459            first.id,
460        );
461
462        assert_eq!(second.correlation_id, Some(first.id));
463    }
464}