llmshim 0.5.0

Blazing fast LLM API translation layer in pure Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204

use llmshim::fallback::FallbackConfig;
use std::time::Duration;

#[test]
fn fallback_config_defaults() {
    let config = FallbackConfig::default();
    assert_eq!(config.max_retries, 2);
    assert_eq!(config.initial_backoff, Duration::from_millis(500));
    assert!(config.retryable_statuses.contains(&429));
    assert!(config.retryable_statuses.contains(&500));
    assert!(config.retryable_statuses.contains(&502));
    assert!(config.retryable_statuses.contains(&503));
    assert!(config.retryable_statuses.contains(&529));
}

#[test]
fn fallback_config_new_with_models() {
    let config = FallbackConfig::new(vec![
        "anthropic/claude-sonnet-4-6".into(),
        "openai/gpt-5.4".into(),
    ]);
    assert_eq!(config.models.len(), 2);
    assert_eq!(config.models[0], "anthropic/claude-sonnet-4-6");
    assert_eq!(config.models[1], "openai/gpt-5.4");
}

#[test]
fn fallback_config_builder() {
    let config = FallbackConfig::new(vec!["a".into()])
        .max_retries(5)
        .initial_backoff(Duration::from_secs(1));
    assert_eq!(config.max_retries, 5);
    assert_eq!(config.initial_backoff, Duration::from_secs(1));
}

#[tokio::test]
async fn fallback_no_models_uses_request_model() {
    // Empty fallback config should just try the model from the request
    let router = llmshim::router::Router::new();
    let config = FallbackConfig::default();
    let request = serde_json::json!({
        "model": "unknown/nonexistent",
        "messages": [{"role": "user", "content": "hi"}],
    });

    let result = llmshim::completion_with_fallback(&router, &request, &config, None).await;
    // Should fail because the provider isn't registered
    assert!(result.is_err());
    let err = format!("{}", result.unwrap_err());
    assert!(err.contains("unknown"), "Error: {}", err);
}

#[tokio::test]
async fn fallback_all_bad_models_returns_all_failed() {
    let router = llmshim::router::Router::new();
    let config = FallbackConfig::new(vec![
        "bad/model-1".into(),
        "bad/model-2".into(),
        "bad/model-3".into(),
    ])
    .max_retries(0);

    let request = serde_json::json!({
        "model": "ignored",
        "messages": [{"role": "user", "content": "hi"}],
    });

    let result = llmshim::completion_with_fallback(&router, &request, &config, None).await;
    assert!(result.is_err());
    let err = format!("{}", result.unwrap_err());
    assert!(err.contains("all providers failed"), "Error: {}", err);
}

#[test]
fn fallback_config_retryable_statuses() {
    let config = FallbackConfig::default();
    // These should be retryable
    assert!(config.retryable_statuses.contains(&429)); // rate limit
    assert!(config.retryable_statuses.contains(&500)); // internal server error
    assert!(config.retryable_statuses.contains(&502)); // bad gateway
    assert!(config.retryable_statuses.contains(&503)); // service unavailable
    assert!(config.retryable_statuses.contains(&529)); // overloaded (Anthropic)
                                                       // These should NOT be retryable
    assert!(!config.retryable_statuses.contains(&400)); // bad request
    assert!(!config.retryable_statuses.contains(&401)); // unauthorized
    assert!(!config.retryable_statuses.contains(&404)); // not found
}

#[tokio::test]
async fn fallback_missing_model_field_errors() {
    let router = llmshim::router::Router::new();
    let config = FallbackConfig::default();
    let request = serde_json::json!({"messages": [{"role": "user", "content": "hi"}]});
    let result = llmshim::completion_with_fallback(&router, &request, &config, None).await;
    assert!(result.is_err());
}

#[tokio::test]
async fn fallback_collects_errors_from_all_models() {
    let router = llmshim::router::Router::new();
    let config = FallbackConfig::new(vec!["bad/one".into(), "bad/two".into()]).max_retries(0);

    let request = serde_json::json!({
        "model": "ignored",
        "messages": [{"role": "user", "content": "hi"}],
    });
    let result = llmshim::completion_with_fallback(&router, &request, &config, None).await;
    let err = format!("{}", result.unwrap_err());
    // Should mention both models
    assert!(err.contains("one"), "Should mention first model: {}", err);
    assert!(err.contains("two"), "Should mention second model: {}", err);
}

#[test]
fn fallback_config_zero_retries() {
    let config = FallbackConfig::new(vec!["a".into()]).max_retries(0);
    assert_eq!(config.max_retries, 0);
}

#[test]
fn fallback_config_custom_backoff() {
    let config = FallbackConfig::new(vec!["a".into()]).initial_backoff(Duration::from_secs(5));
    assert_eq!(config.initial_backoff, Duration::from_secs(5));
}

/// A chain must stop dialling a provider whose circuit is open, rather than
/// spending its retry budget on a target it already knows is dead. The proof is
/// that the dead upstream sees only the first call's attempts and no more.
#[tokio::test]
async fn a_chain_skips_a_provider_with_an_open_circuit() {
    use llmshim::breaker::{BreakerConfig, ProviderBreaker};
    use llmshim::providers::openai_compat::OpenAiCompatible;
    use std::time::Duration;

    // Default chain retries (2, so three attempts per model) with a breaker
    // that trips on the first failure: the dead upstream must see exactly one
    // chain attempt's worth of transport retries and nothing more. The shared
    // HTTP client applies its own reactive retries underneath, so derive the
    // expected request count rather than hard-coding it.
    let config = FallbackConfig::new(vec!["dead/m".into(), "alive/m".into()])
        .initial_backoff(Duration::from_millis(1));
    assert_eq!(config.max_retries, 2, "this test relies on chain retries");
    let transport_attempts = 1 + std::env::var("LLMSHIM_MAX_RETRIES")
        .ok()
        .and_then(|v| v.trim().parse::<usize>().ok())
        .unwrap_or(3);

    let mut dead = mockito::Server::new_async().await;
    let mut alive = mockito::Server::new_async().await;
    let down = dead
        .mock("POST", "/chat/completions")
        .with_status(503)
        .with_body("upstream down")
        .expect(transport_attempts)
        .create_async()
        .await;
    let up = alive
        .mock("POST", "/chat/completions")
        .with_body(
            serde_json::json!({
                "id": "r", "model": "good",
                "choices": [{"message": {"role": "assistant", "content": "ok"}, "finish_reason": "stop"}],
                "usage": {}
            })
            .to_string(),
        )
        .expect(2)
        .create_async()
        .await;

    let router = llmshim::router::Router::new()
        .register(
            "dead",
            Box::new(OpenAiCompatible::new("dead", dead.url(), None)),
        )
        .register(
            "alive",
            Box::new(OpenAiCompatible::new("alive", alive.url(), None)),
        )
        .with_breaker(std::sync::Arc::new(ProviderBreaker::with_config(
            BreakerConfig {
                window: Duration::from_secs(60),
                trip_threshold: 1,
                cooldown: Duration::from_secs(300),
            },
        )));

    let request = serde_json::json!({
        "model": "dead/m",
        "messages": [{"role": "user", "content": "hi"}],
    });

    for _ in 0..2 {
        let result = llmshim::completion_with_fallback(&router, &request, &config, None).await;
        assert!(
            result.is_ok(),
            "the chain must still succeed via the healthy provider"
        );
    }

    // This expectation fails if the second call dialled the dead provider again.
    down.assert_async().await;
    up.assert_async().await;
}