Skip to main content

logit_loom_runtime/
session.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Exact text admission, generation, and checkpoint access.
4
5use logit_loom::{PrefillMonitor, TokenId};
6use logit_loom_llamacpp::{
7    GenerationOutput, Model, PrefillOutput, Session, SessionOptions, StateSnapshot, Tokenization,
8};
9
10use crate::{GenerationRequest, Result};
11
12/// Result of tokenizing exact caller text and its completed or stopped prefill.
13#[derive(Clone, Debug, PartialEq, Eq)]
14pub struct AdmissionOutput {
15    /// Exact token IDs produced by the model tokenizer.
16    ///
17    /// A controlled prefill stop may admit only a prefix; compare this length
18    /// with [`PrefillOutput::admitted_tokens`].
19    pub tokens: Vec<TokenId>,
20    /// Native prefill position and optional observer receipt.
21    pub prefill: PrefillOutput,
22}
23
24/// Result of one fresh text admission followed by bounded generation.
25#[derive(Clone, Debug, PartialEq, Eq)]
26pub struct CompletionOutput {
27    /// Exact prompt tokenization and causal prefill result.
28    pub admission: AdmissionOutput,
29    /// Exact generated bytes, token IDs, and mechanical receipt.
30    pub generation: GenerationOutput,
31}
32
33impl CompletionOutput {
34    /// Returns the exact, potentially non-UTF-8 generated bytes.
35    pub fn bytes(&self) -> &[u8] {
36        &self.generation.bytes
37    }
38
39    /// Returns the causally admitted generated token IDs.
40    pub fn tokens(&self) -> &[TokenId] {
41        &self.generation.tokens
42    }
43
44    /// Returns generated bytes as UTF-8 when the complete output is valid.
45    ///
46    /// # Errors
47    ///
48    /// Returns the standard UTF-8 error for arbitrary model bytes.
49    pub fn text(&self) -> std::result::Result<&str, std::str::Utf8Error> {
50        self.generation.text()
51    }
52}
53
54/// Higher-level borrowing façade over one single-owner causal session.
55pub struct LoomSession<'model> {
56    pub(crate) model: &'model Model,
57    pub(crate) inner: Session<'model>,
58}
59
60impl std::fmt::Debug for LoomSession<'_> {
61    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
62        formatter
63            .debug_struct("LoomSession")
64            .field("session", &self.inner)
65            .finish()
66    }
67}
68
69impl<'model> LoomSession<'model> {
70    pub(crate) const fn new(model: &'model Model, inner: Session<'model>) -> Self {
71        Self { model, inner }
72    }
73
74    /// Tokenizes exact text and replaces prior causal state before admission.
75    ///
76    /// # Errors
77    ///
78    /// Returns a tokenization, capacity, validation, or native prefill error.
79    pub fn replace_text(
80        &mut self,
81        text: &str,
82        tokenization: Tokenization,
83    ) -> Result<AdmissionOutput> {
84        admit_text(&mut self.inner, self.model, text, tokenization, true, None)
85    }
86
87    /// Tokenizes exact text and appends it to existing causal state.
88    ///
89    /// # Errors
90    ///
91    /// Returns a tokenization, capacity, validation, or native prefill error.
92    pub fn append_text(
93        &mut self,
94        text: &str,
95        tokenization: Tokenization,
96    ) -> Result<AdmissionOutput> {
97        admit_text(&mut self.inner, self.model, text, tokenization, false, None)
98    }
99
100    /// Replaces prior causal state while observing complete prefill chunks.
101    ///
102    /// A cooperative stop returns successful partial admission. Inspect the
103    /// prefill receipt before deciding whether to generate.
104    ///
105    /// # Errors
106    ///
107    /// Returns a tokenization, capacity, observer, or native prefill error.
108    pub fn replace_text_observed(
109        &mut self,
110        text: &str,
111        tokenization: Tokenization,
112        monitor: &mut PrefillMonitor,
113    ) -> Result<AdmissionOutput> {
114        admit_text(
115            &mut self.inner,
116            self.model,
117            text,
118            tokenization,
119            true,
120            Some(monitor),
121        )
122    }
123
124    /// Appends exact text while observing complete prefill chunks.
125    ///
126    /// A cooperative stop returns successful partial admission. Inspect the
127    /// prefill receipt before deciding whether to generate.
128    ///
129    /// # Errors
130    ///
131    /// Returns a tokenization, capacity, observer, or native prefill error.
132    pub fn append_text_observed(
133        &mut self,
134        text: &str,
135        tokenization: Tokenization,
136        monitor: &mut PrefillMonitor,
137    ) -> Result<AdmissionOutput> {
138        admit_text(
139            &mut self.inner,
140            self.model,
141            text,
142            tokenization,
143            false,
144            Some(monitor),
145        )
146    }
147
148    /// Executes one bounded generation request against current causal state.
149    ///
150    /// # Errors
151    ///
152    /// Returns a plan, pipeline, observer, sampling, capacity, or native error.
153    pub fn generate(&mut self, request: GenerationRequest<'_>) -> Result<GenerationOutput> {
154        generate(&mut self.inner, request)
155    }
156
157    /// Clears current causal state and exact local lineage.
158    ///
159    /// # Errors
160    ///
161    /// Returns the retained reason when native state is poisoned.
162    pub fn clear(&mut self) -> Result<()> {
163        self.inner.clear().map_err(Into::into)
164    }
165
166    /// Captures opaque native state and exact causal lineage.
167    ///
168    /// # Errors
169    ///
170    /// Returns an identity, allocation, or native state error.
171    pub fn capture_state(&mut self) -> Result<StateSnapshot> {
172        self.inner.capture_state().map_err(Into::into)
173    }
174
175    /// Restores a compatible checkpoint.
176    ///
177    /// # Errors
178    ///
179    /// Returns an identity, compatibility, or native restore error.
180    pub fn restore_state(&mut self, snapshot: &StateSnapshot) -> Result<()> {
181        self.inner.restore_state(snapshot).map_err(Into::into)
182    }
183
184    /// Returns the current causal position.
185    pub const fn position(&self) -> u64 {
186        self.inner.position()
187    }
188
189    /// Returns the exact allocation contract for this session.
190    pub const fn options(&self) -> SessionOptions {
191        self.inner.options()
192    }
193
194    /// Returns exact admitted token history.
195    pub fn token_history(&self) -> &[TokenId] {
196        self.inner.token_history()
197    }
198
199    /// Returns whether native state is not poisoned.
200    pub const fn is_healthy(&self) -> bool {
201        self.inner.is_healthy()
202    }
203
204    /// Returns the retained poison reason, when present.
205    pub fn poison_reason(&self) -> Option<&str> {
206        self.inner.poison_reason()
207    }
208
209    /// Returns the underlying low-level session.
210    pub const fn raw(&self) -> &Session<'model> {
211        &self.inner
212    }
213
214    /// Returns the underlying mutable low-level session.
215    pub fn raw_mut(&mut self) -> &mut Session<'model> {
216        &mut self.inner
217    }
218}
219
220pub(crate) fn admit_text(
221    session: &mut Session<'_>,
222    model: &Model,
223    text: &str,
224    tokenization: Tokenization,
225    clear_first: bool,
226    monitor: Option<&mut PrefillMonitor>,
227) -> Result<AdmissionOutput> {
228    let tokens = model.tokenize(text, tokenization)?;
229    let prefill = match monitor {
230        Some(active) => session.prefill_observed(&tokens, clear_first, active)?,
231        None => session.prefill(&tokens, clear_first)?,
232    };
233    Ok(AdmissionOutput { tokens, prefill })
234}
235
236pub(crate) fn generate(
237    session: &mut Session<'_>,
238    request: GenerationRequest<'_>,
239) -> Result<GenerationOutput> {
240    let (plan, pipeline, observers) = request.into_parts();
241    session
242        .generate(&plan, pipeline, observers)
243        .map_err(Into::into)
244}
245
246#[cfg(test)]
247mod tests {
248    use logit_loom::{Digest, GenerationFinish, GenerationReceipt};
249
250    use super::*;
251
252    fn completion(bytes: Vec<u8>) -> CompletionOutput {
253        let admitted_bytes = u64::try_from(bytes.len()).unwrap();
254        CompletionOutput {
255            admission: AdmissionOutput {
256                tokens: vec![TokenId::new(1).unwrap()],
257                prefill: PrefillOutput {
258                    admitted_tokens: 1,
259                    position: 1,
260                    receipt: None,
261                },
262            },
263            generation: GenerationOutput {
264                bytes,
265                tokens: vec![TokenId::new(2).unwrap()],
266                receipt: GenerationReceipt {
267                    plan: Digest::of_bytes("test-plan", b"runtime-output"),
268                    initial_position: 1,
269                    admitted_tokens: 1,
270                    admitted_bytes,
271                    final_position: 2,
272                    finish: GenerationFinish::TokenLimit,
273                    transform_receipt: None,
274                    observer_receipts: Vec::new(),
275                },
276            },
277        }
278    }
279
280    #[test]
281    fn completion_preserves_exact_bytes_and_tokens() {
282        let output = completion(vec![0xff]);
283        assert_eq!(output.bytes(), [0xff]);
284        assert_eq!(output.tokens(), [TokenId::new(2).unwrap()]);
285        assert!(output.text().is_err());
286    }
287
288    #[test]
289    fn completion_exposes_valid_complete_utf8() {
290        let output = completion("hello".as_bytes().to_vec());
291        assert_eq!(output.text().unwrap(), "hello");
292    }
293}