Skip to main content

spec_stream_engine/
stream.rs

1use serde::{Deserialize, Serialize};
2use spec_stream_core::{SpeculativeMetrics, TokenId};
3use std::pin::Pin;
4use std::task::{Context, Poll};
5use tokio::sync::mpsc::Receiver;
6use tokio_stream::Stream;
7
8/// Events emitted during the speculative generation stream.
9#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
10#[serde(tag = "type", content = "data")]
11pub enum GenerationEvent {
12    /// A committed token ready for output.
13    Token {
14        token_id: TokenId,
15        /// True if this was an accepted draft candidate, false if target correction/bonus.
16        is_draft: bool,
17    },
18    /// Telemetry burst summary for the speculative cycle.
19    Burst {
20        accepted: usize,
21        total_produced: usize,
22    },
23    /// Adaptive K changed based on empirical acceptance rate.
24    AdaptiveKChanged {
25        old_k: usize,
26        new_k: usize,
27        acceptance_rate: f32,
28    },
29    /// Updated performance metrics and speedup ratio.
30    Metrics(SpeculativeMetrics),
31    /// Generation stream finished.
32    Finished { total_tokens: usize, reason: String },
33}
34
35/// An asynchronous stream producing speculative generation events.
36pub struct SpeculativeStream {
37    receiver: Receiver<GenerationEvent>,
38}
39
40impl SpeculativeStream {
41    pub fn new(receiver: Receiver<GenerationEvent>) -> Self {
42        Self { receiver }
43    }
44}
45
46impl Stream for SpeculativeStream {
47    type Item = GenerationEvent;
48
49    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
50        self.receiver.poll_recv(cx)
51    }
52}