Skip to main content

logit_loom_runtime/
steering.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Typed high-level sessions retaining explicit steering cleanup.
4
5use logit_loom::{PrefillMonitor, SteeringReceipt, TokenId};
6use logit_loom_llamacpp::{
7    ControlVector, ControlVectorScope, GenerationOutput, LoraAdapter, LoraScope, Model, Session,
8    Tokenization,
9};
10
11use crate::{
12    AdmissionOutput, GenerationRequest, LoomSession, Result,
13    session::{admit_text, generate},
14};
15
16impl<'model> LoomSession<'model> {
17    /// Applies a `LoRA` and borrows this session until explicit or drop cleanup.
18    ///
19    /// # Errors
20    ///
21    /// Returns a contract or native application error.
22    pub fn lora<'scope>(
23        &'scope mut self,
24        adapter: &'scope mut LoraAdapter,
25        scale: f32,
26    ) -> Result<LoraSession<'scope, 'model>> {
27        let inner = self.inner.lora_scope(adapter, scale)?;
28        Ok(LoraSession {
29            model: self.model,
30            inner,
31        })
32    }
33
34    /// Applies a control vector and borrows this session until cleanup.
35    ///
36    /// # Errors
37    ///
38    /// Returns a contract, model-compatibility, or native application error.
39    pub fn control_vector<'scope>(
40        &'scope mut self,
41        vector: &'scope ControlVector,
42    ) -> Result<ControlVectorSession<'scope, 'model>> {
43        let inner = self.inner.control_vector_scope(vector)?;
44        Ok(ControlVectorSession {
45            model: self.model,
46            inner,
47        })
48    }
49}
50
51/// High-level session while one `LoRA` remains active.
52#[must_use = "retain the scope while LoRA should remain active and call clear to observe cleanup"]
53pub struct LoraSession<'scope, 'model> {
54    model: &'model Model,
55    inner: LoraScope<'scope, 'model>,
56}
57
58impl<'model> LoraSession<'_, 'model> {
59    /// Returns the successful application receipt.
60    pub const fn applied_receipt(&self) -> &SteeringReceipt {
61        self.inner.applied_receipt()
62    }
63
64    /// Replaces causal state with tokenized exact text under active steering.
65    ///
66    /// # Errors
67    ///
68    /// Returns a tokenization, capacity, validation, or native prefill error.
69    pub fn replace_text(
70        &mut self,
71        text: &str,
72        tokenization: Tokenization,
73    ) -> Result<AdmissionOutput> {
74        admit_text(
75            self.inner.session_mut(),
76            self.model,
77            text,
78            tokenization,
79            true,
80            None,
81        )
82    }
83
84    /// Appends tokenized exact text under active steering.
85    ///
86    /// # Errors
87    ///
88    /// Returns a tokenization, capacity, validation, or native prefill error.
89    pub fn append_text(
90        &mut self,
91        text: &str,
92        tokenization: Tokenization,
93    ) -> Result<AdmissionOutput> {
94        admit_text(
95            self.inner.session_mut(),
96            self.model,
97            text,
98            tokenization,
99            false,
100            None,
101        )
102    }
103
104    /// Replaces causal state while observing complete prefill chunks.
105    ///
106    /// # Errors
107    ///
108    /// Returns a tokenization, observer, capacity, or native prefill error.
109    pub fn replace_text_observed(
110        &mut self,
111        text: &str,
112        tokenization: Tokenization,
113        monitor: &mut PrefillMonitor,
114    ) -> Result<AdmissionOutput> {
115        admit_text(
116            self.inner.session_mut(),
117            self.model,
118            text,
119            tokenization,
120            true,
121            Some(monitor),
122        )
123    }
124
125    /// Appends exact text while observing complete prefill chunks.
126    ///
127    /// # Errors
128    ///
129    /// Returns a tokenization, observer, capacity, or native prefill error.
130    pub fn append_text_observed(
131        &mut self,
132        text: &str,
133        tokenization: Tokenization,
134        monitor: &mut PrefillMonitor,
135    ) -> Result<AdmissionOutput> {
136        admit_text(
137            self.inner.session_mut(),
138            self.model,
139            text,
140            tokenization,
141            false,
142            Some(monitor),
143        )
144    }
145
146    /// Executes one bounded generation request under active steering.
147    ///
148    /// # Errors
149    ///
150    /// Returns a plan, callback, sampling, capacity, or native error.
151    pub fn generate(&mut self, request: GenerationRequest<'_>) -> Result<GenerationOutput> {
152        generate(self.inner.session_mut(), request)
153    }
154
155    /// Returns the current causal position.
156    pub fn position(&mut self) -> u64 {
157        self.inner.session_mut().position()
158    }
159
160    /// Returns exact admitted token history.
161    pub fn token_history(&mut self) -> &[TokenId] {
162        self.inner.session_mut().token_history()
163    }
164
165    /// Returns the underlying mutable low-level session while steering remains active.
166    pub fn raw_session_mut(&mut self) -> &mut Session<'model> {
167        self.inner.session_mut()
168    }
169
170    /// Explicitly removes the `LoRA` and returns cleanup accounting.
171    ///
172    /// # Errors
173    ///
174    /// Returns a native cleanup or receipt error and poisons the session.
175    pub fn clear(self) -> Result<SteeringReceipt> {
176        self.inner.clear().map_err(Into::into)
177    }
178}
179
180/// High-level session while one control vector remains active.
181#[must_use = "retain the scope while the vector should remain active and call clear to observe cleanup"]
182pub struct ControlVectorSession<'scope, 'model> {
183    model: &'model Model,
184    inner: ControlVectorScope<'scope, 'model>,
185}
186
187impl<'model> ControlVectorSession<'_, 'model> {
188    /// Returns the successful application receipt.
189    pub const fn applied_receipt(&self) -> &SteeringReceipt {
190        self.inner.applied_receipt()
191    }
192
193    /// Replaces causal state with tokenized exact text under active steering.
194    ///
195    /// # Errors
196    ///
197    /// Returns a tokenization, capacity, validation, or native prefill error.
198    pub fn replace_text(
199        &mut self,
200        text: &str,
201        tokenization: Tokenization,
202    ) -> Result<AdmissionOutput> {
203        admit_text(
204            self.inner.session_mut(),
205            self.model,
206            text,
207            tokenization,
208            true,
209            None,
210        )
211    }
212
213    /// Appends tokenized exact text under active steering.
214    ///
215    /// # Errors
216    ///
217    /// Returns a tokenization, capacity, validation, or native prefill error.
218    pub fn append_text(
219        &mut self,
220        text: &str,
221        tokenization: Tokenization,
222    ) -> Result<AdmissionOutput> {
223        admit_text(
224            self.inner.session_mut(),
225            self.model,
226            text,
227            tokenization,
228            false,
229            None,
230        )
231    }
232
233    /// Replaces causal state while observing complete prefill chunks.
234    ///
235    /// # Errors
236    ///
237    /// Returns a tokenization, observer, capacity, or native prefill error.
238    pub fn replace_text_observed(
239        &mut self,
240        text: &str,
241        tokenization: Tokenization,
242        monitor: &mut PrefillMonitor,
243    ) -> Result<AdmissionOutput> {
244        admit_text(
245            self.inner.session_mut(),
246            self.model,
247            text,
248            tokenization,
249            true,
250            Some(monitor),
251        )
252    }
253
254    /// Appends exact text while observing complete prefill chunks.
255    ///
256    /// # Errors
257    ///
258    /// Returns a tokenization, observer, capacity, or native prefill error.
259    pub fn append_text_observed(
260        &mut self,
261        text: &str,
262        tokenization: Tokenization,
263        monitor: &mut PrefillMonitor,
264    ) -> Result<AdmissionOutput> {
265        admit_text(
266            self.inner.session_mut(),
267            self.model,
268            text,
269            tokenization,
270            false,
271            Some(monitor),
272        )
273    }
274
275    /// Executes one bounded generation request under active steering.
276    ///
277    /// # Errors
278    ///
279    /// Returns a plan, callback, sampling, capacity, or native error.
280    pub fn generate(&mut self, request: GenerationRequest<'_>) -> Result<GenerationOutput> {
281        generate(self.inner.session_mut(), request)
282    }
283
284    /// Returns the current causal position.
285    pub fn position(&mut self) -> u64 {
286        self.inner.session_mut().position()
287    }
288
289    /// Returns exact admitted token history.
290    pub fn token_history(&mut self) -> &[TokenId] {
291        self.inner.session_mut().token_history()
292    }
293
294    /// Returns the underlying mutable low-level session while steering remains active.
295    pub fn raw_session_mut(&mut self) -> &mut Session<'model> {
296        self.inner.session_mut()
297    }
298
299    /// Explicitly neutralizes the vector and returns cleanup accounting.
300    ///
301    /// # Errors
302    ///
303    /// Returns a native cleanup or receipt error and poisons the session.
304    pub fn clear(self) -> Result<SteeringReceipt> {
305        self.inner.clear().map_err(Into::into)
306    }
307}