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}