Skip to main content

wardline_llm/
lib.rs

1//! Wraps an LLM call with Wardline input and output pipelines.
2//!
3//! The reference path stays synchronous end to end: guard the prompt, make a
4//! **blocking** model call (`reqwest::blocking`, `ureq`, a local function),
5//! guard the response. This crate does not start an async runtime and does
6//! not host a model.
7//!
8//! ```text
9//! prompt ──▶ input pipeline ──▶ llm_call ──▶ output pipeline ──▶ reply
10//!                 │                                │
11//!                 └── Block: never call the model  └── Block: never release the reply
12//! ```
13
14#![forbid(unsafe_code)]
15#![deny(missing_docs)]
16
17use std::sync::Arc;
18use wardline_core::{Context, Pipeline, Trace, Verdict};
19
20/// Which side of the model call refused the work.
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub enum Stage {
23    /// The prompt was blocked. The model was never called.
24    Input,
25    /// The model ran, but its reply was blocked.
26    Output,
27}
28
29impl Stage {
30    /// A stable label for logs and metrics.
31    pub fn as_str(self) -> &'static str {
32        match self {
33            Stage::Input => "input",
34            Stage::Output => "output",
35        }
36    }
37}
38
39impl core::fmt::Display for Stage {
40    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
41        f.write_str(self.as_str())
42    }
43}
44
45/// A pipeline refused the prompt or the reply.
46#[derive(Debug, Clone)]
47pub struct Blocked {
48    stage: Stage,
49    reason: String,
50    trace: Trace,
51}
52
53impl Blocked {
54    /// Whether the prompt or the reply was refused.
55    pub fn stage(&self) -> Stage {
56        self.stage
57    }
58
59    /// Why it was refused.
60    pub fn reason(&self) -> &str {
61        &self.reason
62    }
63
64    /// The pipeline trace for the side that halted.
65    pub fn trace(&self) -> &Trace {
66        &self.trace
67    }
68
69    /// The guard that stopped the pipeline, if the trace still has it.
70    pub fn halted_by(&self) -> Option<&'static str> {
71        self.trace.halted_by()
72    }
73}
74
75impl core::fmt::Display for Blocked {
76    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
77        write!(
78            f,
79            "{} blocked by {}: {}",
80            self.stage,
81            self.halted_by().unwrap_or("unknown"),
82            self.reason
83        )
84    }
85}
86
87impl std::error::Error for Blocked {}
88
89/// Failure of [`guarded_prompt`]: a guard said no, or the model call failed.
90#[derive(Debug)]
91pub enum GuardedError<E> {
92    /// A pipeline halted. See [`Blocked::stage`] for which side.
93    Blocked(Blocked),
94    /// The blocking model function returned an error.
95    Model(E),
96}
97
98impl<E: core::fmt::Display> core::fmt::Display for GuardedError<E> {
99    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
100        match self {
101            GuardedError::Blocked(blocked) => write!(f, "{blocked}"),
102            GuardedError::Model(error) => write!(f, "model call failed: {error}"),
103        }
104    }
105}
106
107impl<E: std::error::Error + 'static> std::error::Error for GuardedError<E> {
108    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
109        match self {
110            GuardedError::Blocked(blocked) => Some(blocked),
111            GuardedError::Model(error) => Some(error),
112        }
113    }
114}
115
116/// Guards `prompt`, calls `llm` only if allowed, then guards the reply.
117///
118/// A [`Verdict::Modify`] on the input pipeline is what the model sees. A
119/// modify on the output pipeline is what the caller receives. A block on
120/// either side is [`GuardedError::Blocked`] — the model is skipped on an
121/// input block, and a blocked reply is not returned.
122pub fn guarded_prompt<E>(
123    input_pipeline: &Pipeline<str, String>,
124    output_pipeline: &Pipeline<str, String>,
125    llm: impl FnOnce(&str) -> Result<String, E>,
126    prompt: &str,
127    ctx: &Context,
128) -> Result<String, GuardedError<E>> {
129    let incoming = Arc::<str>::from(prompt);
130    let inbound = input_pipeline.evaluate(&incoming, ctx);
131    let (verdict, trace) = inbound.into_parts();
132    let outgoing = match verdict {
133        Verdict::Block { reason } => {
134            return Err(GuardedError::Blocked(Blocked {
135                stage: Stage::Input,
136                reason,
137                trace,
138            }));
139        }
140        Verdict::Modify(rewritten) => rewritten,
141        Verdict::Allow => prompt.to_owned(),
142    };
143
144    let raw = llm(&outgoing).map_err(GuardedError::Model)?;
145    let outgoing_reply = Arc::<str>::from(raw.as_str());
146    let outbound = output_pipeline.evaluate(&outgoing_reply, ctx);
147    let (verdict, trace) = outbound.into_parts();
148    match verdict {
149        Verdict::Block { reason } => Err(GuardedError::Blocked(Blocked {
150            stage: Stage::Output,
151            reason,
152            trace,
153        })),
154        Verdict::Modify(rewritten) => Ok(rewritten),
155        Verdict::Allow => Ok(raw),
156    }
157}
158
159#[cfg(test)]
160mod tests {
161    use super::*;
162    use wardline_core::{Guard, GuardError, Verdict};
163
164    struct Scripted {
165        name: &'static str,
166        decide: fn(&str) -> Result<Verdict<String>, GuardError>,
167    }
168
169    impl Guard for Scripted {
170        type Input = str;
171        type Output = String;
172
173        fn check(&self, input: &str, _ctx: &Context) -> Result<Verdict<String>, GuardError> {
174            (self.decide)(input)
175        }
176
177        fn name(&self) -> &'static str {
178            self.name
179        }
180    }
181
182    fn echo(prompt: &str) -> Result<String, String> {
183        Ok(format!("echo:{prompt}"))
184    }
185
186    fn boom(_prompt: &str) -> Result<String, String> {
187        Err("provider down".to_owned())
188    }
189
190    fn empty() -> Pipeline<str, String> {
191        Pipeline::new()
192    }
193
194    fn ctx() -> Context {
195        Context::new()
196    }
197
198    #[test]
199    fn an_allowed_prompt_reaches_the_model_and_comes_back() {
200        let reply = match guarded_prompt(&empty(), &empty(), echo, "hello", &ctx()) {
201            Ok(reply) => reply,
202            Err(error) => panic!("expected a reply, got {error}"),
203        };
204        assert_eq!(reply, "echo:hello");
205    }
206
207    #[test]
208    fn an_input_block_never_calls_the_model() {
209        let input = Pipeline::new().with(Scripted {
210            name: "secrets",
211            decide: |text| {
212                if text.contains("sk-") {
213                    Ok(Verdict::block("api key"))
214                } else {
215                    Ok(Verdict::Allow)
216                }
217            },
218        });
219        let called = std::sync::atomic::AtomicBool::new(false);
220        let result = guarded_prompt(
221            &input,
222            &empty(),
223            |prompt| {
224                called.store(true, std::sync::atomic::Ordering::SeqCst);
225                echo(prompt)
226            },
227            "key sk-abc",
228            &ctx(),
229        );
230        let error = match result {
231            Err(error) => error,
232            Ok(reply) => panic!("expected a block, got {reply}"),
233        };
234        match error {
235            GuardedError::Blocked(blocked) => {
236                assert_eq!(blocked.stage(), Stage::Input);
237                assert_eq!(blocked.reason(), "api key");
238                assert_eq!(blocked.halted_by(), Some("secrets"));
239            }
240            GuardedError::Model(error) => panic!("expected a block, got model error {error}"),
241        }
242        assert!(
243            !called.load(std::sync::atomic::Ordering::SeqCst),
244            "the model must not run after an input block"
245        );
246    }
247
248    #[test]
249    fn an_output_block_discards_the_reply() {
250        let output = Pipeline::new().with(Scripted {
251            name: "toxicity",
252            decide: |text| {
253                if text.contains("nope") {
254                    Ok(Verdict::block("toxic"))
255                } else {
256                    Ok(Verdict::Allow)
257                }
258            },
259        });
260        let result = guarded_prompt(
261            &empty(),
262            &output,
263            |_prompt: &str| -> Result<String, String> { Ok("nope".to_owned()) },
264            "hello",
265            &ctx(),
266        );
267        match result {
268            Err(GuardedError::Blocked(blocked)) => {
269                assert_eq!(blocked.stage(), Stage::Output);
270                assert_eq!(blocked.reason(), "toxic");
271            }
272            other => panic!("expected an output block, got {other:?}"),
273        }
274    }
275
276    #[test]
277    fn input_modify_is_what_the_model_sees() {
278        let input = Pipeline::new().with(Scripted {
279            name: "redact",
280            decide: |text| Ok(Verdict::Modify(text.replace("secret", "[redacted]"))),
281        });
282        let reply = match guarded_prompt(&input, &empty(), echo, "a secret value", &ctx()) {
283            Ok(reply) => reply,
284            Err(error) => panic!("expected a reply, got {error}"),
285        };
286        assert_eq!(reply, "echo:a [redacted] value");
287    }
288
289    #[test]
290    fn output_modify_is_what_the_caller_receives() {
291        let output = Pipeline::new().with(Scripted {
292            name: "redact",
293            decide: |text| Ok(Verdict::Modify(text.replace("echo:", ""))),
294        });
295        let reply = match guarded_prompt(&empty(), &output, echo, "hello", &ctx()) {
296            Ok(reply) => reply,
297            Err(error) => panic!("expected a reply, got {error}"),
298        };
299        assert_eq!(reply, "hello");
300    }
301
302    #[test]
303    fn a_model_error_is_not_turned_into_a_block() {
304        let result = guarded_prompt(&empty(), &empty(), boom, "hello", &ctx());
305        match result {
306            Err(GuardedError::Model(error)) => assert_eq!(error, "provider down"),
307            other => panic!("expected a model error, got {other:?}"),
308        }
309    }
310}