lash_core/provider/
traits.rs

1use super::support::*;
2use crate::LlmTerminalReason;
3
4/// A configured LLM backend: its identity, host-config serialization, its
5/// generation options, and the request transport.
6#[async_trait]
7pub trait Provider: Send + Sync + std::fmt::Debug {
8    fn kind(&self) -> &'static str;
9
10    fn options(&self) -> ProviderOptions;
11    fn set_options(&mut self, options: ProviderOptions);
12
13    /// Emit the provider-specific JSON body used by [`ProviderSpec`]. The
14    /// object must NOT contain a `type` field — [`ProviderSpec::Serialize`]
15    /// layers that on top.
16    fn serialize_config(&self) -> serde_json::Value;
17
18    async fn complete(&mut self, request: LlmRequest) -> Result<LlmResponse, LlmTransportError>;
19
20    fn requires_streaming(&self) -> bool {
21        false
22    }
23
24    /// Release any host-visible transport resources this provider holds —
25    /// cached connections, pooled sockets, background tasks — sending whatever
26    /// graceful close a clean shutdown requires.
27    ///
28    /// Hosts call this before process exit so protocol niceties (e.g. WebSocket
29    /// Close frames) are sent rather than skipped by an abrupt drop. It takes
30    /// `&self` because a provider's reusable transport state lives behind its
31    /// own synchronization; a shared clone can therefore be closed from the
32    /// shutdown path. The default is a no-op: providers that hold no reusable
33    /// transport state have nothing to release.
34    async fn close(&self) -> Result<(), LlmTransportError> {
35        Ok(())
36    }
37
38    fn clone_boxed(&self) -> Box<dyn Provider>;
39}
40
41pub trait ProviderFailureClassifier: Send + Sync + std::fmt::Debug {
42    fn classify(&self, failure: ProviderFailure) -> ProviderFailure;
43}
44
45#[derive(Clone, Debug, Default)]
46pub struct DefaultProviderFailureClassifier;
47
48impl ProviderFailureClassifier for DefaultProviderFailureClassifier {
49    fn classify(&self, mut failure: ProviderFailure) -> ProviderFailure {
50        if let Some(status) = failure.status.or_else(|| {
51            failure
52                .code
53                .as_deref()
54                .and_then(|code| code.parse::<u16>().ok())
55        }) {
56            failure.status = Some(status);
57            if failure.kind == ProviderFailureKind::Unknown {
58                failure.kind = ProviderFailureKind::Http;
59            }
60            failure.retryable = matches!(status, 408 | 409 | 425 | 429 | 500 | 502 | 503 | 504);
61            if status == 429 {
62                // Provider-side throttling. `Quota` + `retryable: true` is the
63                // combination `ProviderHandle`'s retry ladder defers to as a
64                // throttle; hard quota exhaustion (the text markers below)
65                // downgrades to `retryable: false`.
66                failure.kind = ProviderFailureKind::Quota;
67            } else if matches!(status, 401 | 403) {
68                failure.kind = ProviderFailureKind::Auth;
69            } else if matches!(status, 400 | 413 | 422) {
70                failure.kind = ProviderFailureKind::Validation;
71            }
72        } else if matches!(
73            failure.kind,
74            ProviderFailureKind::Transport | ProviderFailureKind::Timeout
75        ) {
76            failure.retryable = true;
77        }
78
79        let haystack = format!(
80            "{}\n{}\n{}",
81            failure.code.as_deref().unwrap_or_default(),
82            failure.message,
83            failure.raw.as_deref().unwrap_or_default()
84        )
85        .to_ascii_lowercase();
86        if is_context_overflow_text(&haystack) {
87            failure.kind = ProviderFailureKind::Validation;
88            failure.retryable = false;
89            failure.terminal_reason = LlmTerminalReason::ContextOverflow;
90        }
91        if haystack.contains("insufficient_quota")
92            || haystack.contains("usage_limit_reached")
93            || haystack.contains("usage_not_included")
94            || haystack.contains("quota")
95        {
96            failure.kind = ProviderFailureKind::Quota;
97            failure.retryable = false;
98        }
99        if haystack.contains("content_filter")
100            || haystack.contains("prohibited_content")
101            || haystack.contains("safety")
102            || haystack.contains("sensitive")
103        {
104            failure.terminal_reason = LlmTerminalReason::ContentFilter;
105        }
106        if haystack.contains("model_not_found")
107            || haystack.contains("unsupported model")
108            || haystack.contains("does not exist")
109        {
110            failure.kind = ProviderFailureKind::Unsupported;
111            failure.retryable = false;
112        }
113        failure
114    }
115}
116
117pub fn is_context_overflow_text(haystack: &str) -> bool {
118    let lower = haystack.to_ascii_lowercase();
119    if lower.contains("rate limit")
120        || lower.contains("rate_limit")
121        || lower.contains("ratelimit")
122        || lower.contains("throttle")
123        || lower.contains("throttling")
124        || lower.contains("too many requests")
125        || lower.contains("tokens per minute")
126        || lower.contains("tpm")
127        || lower.contains("quota")
128    {
129        return false;
130    }
131
132    lower.contains("context_length_exceeded")
133        || lower.contains("context_length")
134        || lower.contains("context length")
135        || lower.contains("maximum context")
136        || lower.contains("max context")
137        || lower.contains("context window")
138        || lower.contains("context window exceeds limit")
139        || lower.contains("exceeds the context window")
140        || lower.contains("prompt is too long")
141        || lower.contains("prompt too long")
142        || lower.contains("request_too_large")
143        || lower.contains("input token count") && lower.contains("exceeds the maximum")
144        || lower.contains("maximum prompt length is")
145        || lower.contains("reduce the length of the messages")
146        || lower.contains("maximum context length is")
147        || lower.contains("model's context length")
148        || lower.contains("models context length")
149        || lower.contains("exceeds the available context size")
150        || lower.contains("greater than the context length")
151        || lower.contains("exceeded model token limit")
152        || lower.contains("too large for model with")
153        || lower.contains("model_context_window_exceeded")
154        || lower.contains("too many tokens")
155        || lower.contains("exceeds the maximum number of tokens")
156        || lower.contains("exceeds maximum number of tokens")
157        || lower.contains("request too large")
158        || lower.contains("input is too long")
159        || lower.contains("token limit exceeded")
160        || lower.contains("reduce the length of the messages")
161        || lower.contains("reduce the length of your prompt")
162}
lash_core/provider/traits.rs

lash_core/provider/
traits.rs
