Skip to main content

mojentic/llm/recovery/
adapter.rs

1use super::{engine, *};
2use crate::{
3    error::{MojenticError, Result},
4    llm::{
5        gateway::{CompletionConfig, LlmGateway, ModelContextWindow, StreamChunk},
6        models::{LlmGatewayResponse, LlmMessage},
7        stream_events::{StreamEventError, StreamEventStream},
8        tools::LlmTool,
9    },
10};
11use async_trait::async_trait;
12use futures::{Stream, StreamExt};
13use serde_json::Value;
14use std::pin::Pin;
15
16/// Implemented by completion adapters that can freeze their encoded HTTP request.
17#[doc(hidden)]
18pub trait RecoveryProvider: LlmGateway {
19    fn recovery_provider(&self) -> Provider;
20    fn prepare_recovery(
21        &self,
22        model: &str,
23        messages: &[LlmMessage],
24        tools: Option<&[Box<dyn LlmTool>]>,
25        config: &CompletionConfig,
26        schema: Option<Value>,
27        stream: bool,
28    ) -> Result<reqwest::Request>;
29}
30/// One-request recovery adapter. Tool execution stays in the existing broker/session.
31///
32/// ```no_run
33/// use mojentic::llm::{LlmMessage, gateway::CompletionConfig, gateways::OllamaGateway};
34/// use mojentic::llm::recovery::{RecoveryCall, RecoveryPolicy};
35/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
36/// let gateway = OllamaGateway::new().with_recovery(RecoveryPolicy::default())?;
37/// let call = RecoveryCall::default();
38/// let result = gateway.complete_with_recovery(
39///     "qwen3", &[LlmMessage::user("Explain ownership")], None,
40///     &CompletionConfig::default(), &call,
41/// ).await?;
42/// assert_eq!(result.report.identity.wire_attempt, 1);
43/// # Ok(())
44/// # }
45/// ```
46pub struct RecoveryGateway<G> {
47    pub(crate) inner: G,
48    pub(crate) policy: RecoveryPolicy,
49    pub(crate) client: reqwest::Client,
50}
51impl<G: RecoveryProvider> RecoveryGateway<G> {
52    pub fn new(inner: G, policy: RecoveryPolicy) -> Result<Self> {
53        policy.validate()?;
54        let client = reqwest::Client::builder()
55            .retry(reqwest::retry::never())
56            .redirect(reqwest::redirect::Policy::none())
57            .build()?;
58        Ok(Self {
59            inner,
60            policy,
61            client,
62        })
63    }
64    /// Endpoint-specific facilities, with no change to retry or admission policy.
65    pub fn capabilities(&self) -> Capabilities {
66        self.capability_evidence().values()
67    }
68    /// Provider documentation, inspection dates and limitations for each facility.
69    /// Local cancellation is never evidence of exact remote attempt termination.
70    pub fn capability_evidence(&self) -> CapabilityEvidenceSet {
71        CapabilityEvidenceSet::for_provider(self.inner.recovery_provider())
72    }
73    /// Full metadata for an ordinary completion. No tool is executed by this method.
74    pub async fn complete_with_recovery(
75        &self,
76        model: &str,
77        messages: &[LlmMessage],
78        tools: Option<&[Box<dyn LlmTool>]>,
79        config: &CompletionConfig,
80        call: &RecoveryCall,
81    ) -> std::result::Result<Recovered<LlmGatewayResponse>, RecoveryError> {
82        let request = self.prepare(model, messages, tools, config, None, Operation::Ordinary)?;
83        engine::complete(self, request, Operation::Ordinary, call)
84            .await
85            .map(|r| Recovered {
86                value: LlmGatewayResponse {
87                    content: r.value.content,
88                    thinking: r.value.thinking,
89                    tool_calls: r.value.tool_calls,
90                    evidence: r.value.evidence,
91                    object: None,
92                },
93                report: r.report,
94            })
95    }
96    pub async fn complete_json_with_recovery(
97        &self,
98        model: &str,
99        messages: &[LlmMessage],
100        schema: Value,
101        config: &CompletionConfig,
102        call: &RecoveryCall,
103    ) -> std::result::Result<Recovered<LlmGatewayResponse<Value>>, RecoveryError> {
104        let request =
105            self.prepare(model, messages, None, config, Some(schema), Operation::Structured)?;
106        engine::complete(self, request, Operation::Structured, call).await
107    }
108    /// Reasoning and tool fragments are observable, but never executable until completion.
109    pub fn complete_stream_with_recovery<'a>(
110        &'a self,
111        model: &str,
112        messages: &[LlmMessage],
113        tools: Option<&[Box<dyn LlmTool>]>,
114        config: &CompletionConfig,
115        call: &'a RecoveryCall,
116    ) -> Pin<Box<dyn Stream<Item = RecoveryStreamEvent> + Send + 'a>> {
117        match self.prepare(model, messages, tools, config, None, Operation::Streaming) {
118            Ok(request) => engine::stream(self, request, call),
119            Err(error) => {
120                Box::pin(futures::stream::once(async { RecoveryStreamEvent::Failed(error) }))
121            }
122        }
123    }
124    fn prepare(
125        &self,
126        model: &str,
127        messages: &[LlmMessage],
128        tools: Option<&[Box<dyn LlmTool>]>,
129        config: &CompletionConfig,
130        schema: Option<Value>,
131        operation: Operation,
132    ) -> std::result::Result<reqwest::Request, RecoveryError> {
133        self.inner
134            .prepare_recovery(
135                model,
136                messages,
137                tools,
138                config,
139                schema,
140                operation == Operation::Streaming,
141            )
142            .map_err(|cause| {
143                let mut failure =
144                    Failure::new(self.inner.recovery_provider(), operation, Category::Protocol)
145                        .with_cause(cause);
146                failure.acceptance = Acceptance::No;
147                failure.classification.reason = Reason::InvalidConfiguration;
148                RecoveryError {
149                    stream_metrics: None,
150                    outcome: Outcome::Failed,
151                    failure: Box::new(failure),
152                    history: vec![],
153                }
154            })
155    }
156}
157fn legacy(error: RecoveryError) -> MojenticError {
158    MojenticError::Recovery(Box::new(error))
159}
160#[async_trait]
161impl<G: RecoveryProvider> LlmGateway for RecoveryGateway<G> {
162    fn stream_clock(&self) -> std::sync::Arc<dyn crate::llm::stream_timing::StreamClock> {
163        self.inner.stream_clock()
164    }
165
166    async fn get_model_context_window(&self, model: &str) -> Result<Option<ModelContextWindow>> {
167        self.inner.get_model_context_window(model).await
168    }
169
170    async fn complete(
171        &self,
172        model: &str,
173        messages: &[LlmMessage],
174        tools: Option<&[Box<dyn LlmTool>]>,
175        config: &CompletionConfig,
176    ) -> Result<LlmGatewayResponse> {
177        self.complete_with_recovery(model, messages, tools, config, &RecoveryCall::default())
178            .await
179            .map(|r| r.value)
180            .map_err(legacy)
181    }
182    async fn complete_json(
183        &self,
184        model: &str,
185        messages: &[LlmMessage],
186        schema: Value,
187        config: &CompletionConfig,
188    ) -> Result<Value> {
189        Ok(self
190            .complete_json_response(model, messages, schema, config)
191            .await?
192            .object
193            .unwrap_or(Value::Null))
194    }
195    async fn complete_json_response(
196        &self,
197        model: &str,
198        messages: &[LlmMessage],
199        schema: Value,
200        config: &CompletionConfig,
201    ) -> Result<LlmGatewayResponse<Value>> {
202        self.complete_json_with_recovery(model, messages, schema, config, &RecoveryCall::default())
203            .await
204            .map(|r| r.value)
205            .map_err(legacy)
206    }
207    async fn get_available_models(&self) -> Result<Vec<String>> {
208        self.inner.get_available_models().await
209    }
210    async fn calculate_embeddings(&self, text: &str, model: Option<&str>) -> Result<Vec<f32>> {
211        self.inner.calculate_embeddings(text, model).await
212    }
213    fn complete_stream<'a>(
214        &'a self,
215        model: &'a str,
216        messages: &'a [LlmMessage],
217        tools: Option<&'a [Box<dyn LlmTool>]>,
218        config: &'a CompletionConfig,
219    ) -> Pin<Box<dyn Stream<Item = Result<StreamChunk>> + Send + 'a>> {
220        Box::pin(async_stream::stream! {
221            let call = RecoveryCall::default();
222            let mut stream = self.complete_stream_with_recovery(model, messages, tools, config, &call);
223            while let Some(event) = stream.next().await {
224                match event {
225                    RecoveryStreamEvent::Progress { progress, .. } => yield Ok(StreamChunk::Progress(progress)),
226                    RecoveryStreamEvent::Metrics { .. } => {},
227                    RecoveryStreamEvent::Content(text) => yield Ok(StreamChunk::Content(text)),
228                    RecoveryStreamEvent::Reasoning(text) => yield Ok(StreamChunk::Thinking(text)),
229                    RecoveryStreamEvent::Completed(response) => { if let Some(metrics) = response.report.stream_metrics { yield Ok(StreamChunk::Metrics(*metrics)); }
230                        if !response.value.tool_calls.is_empty() { yield Ok(StreamChunk::ToolCalls(response.value.tool_calls)); } },
231                    RecoveryStreamEvent::Failed(error) => { if let Some(metrics) = error.stream_metrics.clone() { yield Ok(StreamChunk::Metrics(*metrics)); } yield Err(legacy(error)); break; },
232                    _ => {}
233                }
234            }
235        })
236    }
237    fn complete_stream_events<'a>(
238        &'a self,
239        model: &'a str,
240        messages: &'a [LlmMessage],
241        config: &'a CompletionConfig,
242    ) -> std::result::Result<StreamEventStream<'a>, StreamEventError> {
243        self.inner.complete_stream_events(model, messages, config)
244    }
245}