molo 0.2.3

A lightweight Rust agent framework
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

//! RetryProvider example: how to use the retry wrapper.
//!
//! [`RetryProvider`](molo::provider::RetryProvider) implements
//! [`Provider`](molo::provider::Provider) and wraps any Provider — one wrapper
//! layer gives you retry, and anything that consumes a Provider (ReActAgent,
//! hand-written loops) works unchanged. Timeouts are the inner Provider's job
//! (OpenAiProvider's constructor has built-in defaults); the default retry
//! decision covers the `Timeout` / `RateLimited` / `Network` error classes
//! plus 5xx.
//!
//! Self-contained: errors are injected via
//! [`FakeProvider`](molo::provider::FakeProvider) scripts, with no real API
//! dependency.
//!
//! Run: `cargo run --example retry`

use molo::provider::{
    Backoff, FakeProvider, FakeReply, OpenAiProvider, Provider, ProviderError, RetryPolicy,
    RetryProvider, Retryable,
};
use std::sync::Arc;
use std::time::Duration;

/// Usage 1: wrap with the default policy — a rate-limited failure retries automatically, invisible to the caller.
async fn default_policy_retries_rate_limited() {
    // Script: the first call is rate-limited, the second succeeds.
    let inner = Arc::new(FakeProvider::new([
        FakeReply::Error(ProviderError::RateLimited { retry_after: None }),
        FakeReply::Text("retry succeeded".into()),
    ]));
    let provider = RetryProvider::new(inner.clone());

    let resp = provider
        .chat(molo::provider::ChatRequest::default())
        .await
        .unwrap();
    let text = match resp.message {
        molo::Message::Assistant { content, .. } => content,
        _ => String::new(),
    };
    println!("default policy: first call rate-limited, retried automatically → {text}");

    // requests() asserts the attempt count: one failure + one retry = 2 calls.
    println!("attempt count (requests): {}", inner.requests().len());
    assert_eq!(inner.requests().len(), 2);
}

/// Usage 2: a custom policy — 5 attempts, a slower backoff, and only rate-limited errors are retried.
async fn custom_policy() {
    let policy = RetryPolicy {
        max_attempts: 5,
        backoff: Backoff::Exponential {
            initial: Duration::from_millis(200),
            factor: 2.0,
            max: Duration::from_secs(5),
            jitter: false,
        },
        // Custom decision: only retry rate limiting; network / 5xx give up immediately.
        retryable: Retryable::Custom(Arc::new(|e| matches!(e, ProviderError::RateLimited { .. }))),
        ..Default::default()
    };

    let inner = Arc::new(FakeProvider::new([
        FakeReply::Error(ProviderError::RateLimited { retry_after: None }),
        FakeReply::Error(ProviderError::RateLimited { retry_after: None }),
        FakeReply::Text("succeeded after two rate limits".into()),
    ]));
    let provider = RetryProvider::new(inner.clone()).with_policy(policy);
    let resp = provider
        .chat(molo::provider::ChatRequest::default())
        .await
        .unwrap();
    let text = match resp.message {
        molo::Message::Assistant { content, .. } => content,
        _ => String::new(),
    };
    println!("custom policy: two rate limits, retried automatically → {text}");
}

/// Usage 3: streaming retry — retries only when the failure happens before the first event; once the stream is established, an interruption passes through as-is.
async fn streaming_retry_before_first_event() {
    use futures::StreamExt;

    // The first establishment fails (network), the second succeeds.
    let inner = Arc::new(FakeProvider::new([
        FakeReply::Error(ProviderError::Network("connection refused".into())),
        FakeReply::Text("streaming succeeded".into()),
    ]));
    let provider = RetryProvider::new(inner.clone());

    let mut stream = provider
        .stream_chat(molo::provider::ChatRequest::default())
        .await
        .unwrap();
    while let Some(event) = stream.next().await {
        match event.unwrap() {
            molo::provider::StreamEvent::Delta(text) => println!("streaming retry: delta {text}"),
            molo::provider::StreamEvent::Done { .. } => {}
            _ => {}
        }
    }
    println!("streaming retry attempt count: {}", inner.requests().len());
}

/// Usage 4: timeout configuration (OpenAiProvider has built-in defaults,
/// chainable) — assembly only, no real request is made.
fn timeout_configuration() {
    // Defaults: connect 30s / non-streaming 600s / streaming event idle 60s; override chained:
    let _provider = OpenAiProvider::new("https://api.openai.com/v1", "sk-xxx", "gpt-4o-mini")
        .with_connect_timeout(Duration::from_secs(10))
        .with_request_timeout(Duration::from_secs(120))
        .with_idle_timeout(Duration::from_secs(30));
    println!("timeout config: connect 10s / request 120s / idle 30s (effective immediately)");
}

#[tokio::main]
async fn main() {
    default_policy_retries_rate_limited().await;
    custom_policy().await;
    streaming_retry_before_first_event().await;
    timeout_configuration();
    println!("all demos done (no real API needed)");
}