llm_stream_guard/lib.rs
1//! Runtime-neutral replay boundaries for streamed LLM responses.
2//!
3//! This crate observes items as they pass through a [`GuardedStream`]. It does
4//! not perform I/O, parse a transport, retain response bodies, or retry a
5//! request. A retry is authorized only when the caller declares a
6//! [`ReplayContract::KnownSafe`], no output boundary was crossed, and the
7//! classifier observed an explicit transient failure.
8//!
9//! # Example
10//!
11//! The guard observes an item before returning that same item. A transient
12//! failure after text has already appeared therefore cannot authorize replay:
13//!
14//! ```
15//! use futures_util::{FutureExt, StreamExt};
16//! use llm_stream_guard::{
17//! FailureKind, GuardedStream, Observation, OutputKind, ReplayBoundary,
18//! ReplayContract, ReplayVerdict,
19//! };
20//!
21//! #[derive(Clone, Copy, Debug, Eq, PartialEq)]
22//! enum AppEvent {
23//! Text,
24//! TransientFailure,
25//! }
26//!
27//! let upstream = futures_util::stream::iter([
28//! AppEvent::Text,
29//! AppEvent::TransientFailure,
30//! ]);
31//! let guarded = GuardedStream::new(
32//! upstream,
33//! |event: &AppEvent| match event {
34//! AppEvent::Text => Observation::Output(OutputKind::Text),
35//! AppEvent::TransientFailure => {
36//! Observation::Failed(FailureKind::Transient)
37//! }
38//! },
39//! ReplayContract::KnownSafe,
40//! );
41//! let probe = guarded.probe();
42//! futures_util::pin_mut!(guarded);
43//!
44//! assert_eq!(guarded.next().now_or_never(), Some(Some(AppEvent::Text)));
45//! assert_eq!(
46//! probe.snapshot().boundary(),
47//! ReplayBoundary::Crossed(OutputKind::Text),
48//! );
49//! assert_eq!(
50//! guarded.next().now_or_never(),
51//! Some(Some(AppEvent::TransientFailure)),
52//! );
53//! assert_eq!(probe.snapshot().verdict(), ReplayVerdict::Deny);
54//! ```
55
56#![forbid(unsafe_code)]
57#![deny(missing_docs)]
58
59mod core;
60#[cfg(feature = "openai-json")]
61pub mod openai;
62
63pub use crate::core::{
64 Classify, ExitReason, FailureKind, GuardedStream, Observation, OutputKind, Probe,
65 ReplayBoundary, ReplayContract, ReplayVerdict, Snapshot, Termination,
66};