bock-ai 0.1.0

AI provider interface for Bock's AI-native code generation pipeline (Generate, Repair, Optimize, Select)
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

//! Error types for the AI provider interface.
//!
//! All provider operations return `Result<_, AiError>`. The codegen
//! pipeline inspects the variant to decide whether to fall back to
//! Tier 2 rule-based generation (per §17.2) or fail the build.

use thiserror::Error;

/// Errors produced by an [`AiProvider`](crate::provider::AiProvider) call.
///
/// The variants capture the categories the codegen pipeline distinguishes
/// between when deciding whether to retry, fall back, or surface the
/// failure. They are intentionally transport-agnostic — concrete HTTP
/// status codes or SDK errors should be mapped into one of these.
#[derive(Debug, Clone, Error)]
pub enum AiError {
    /// Transport-level failure reaching the provider (DNS, connect, TLS,
    /// read/write errors). Safe to retry.
    #[error("AI provider network error: {0}")]
    Network(String),

    /// Authentication failed — bad API key, missing credential, revoked
    /// token. Not retryable without re-configuring.
    #[error("AI provider authentication failed: {0}")]
    Auth(String),

    /// The request did not complete within the configured timeout.
    #[error("AI provider request timed out: {0}")]
    Timeout(String),

    /// The provider returned a rate-limit response (HTTP 429 or equivalent).
    /// Callers may retry with backoff.
    #[error("AI provider rate limited: {0}")]
    RateLimited(String),

    /// The configured cost or token budget has been exhausted. Not retryable
    /// until the budget is replenished.
    #[error("AI provider budget exceeded: {0}")]
    BudgetExceeded(String),

    /// The provider returned an error response that does not fit a more
    /// specific variant (5xx, provider-side validation, model error).
    #[error("AI provider error: {0}")]
    ProviderError(String),

    /// The provider is temporarily unavailable — compiler should fall back
    /// to Tier 2 rule-based generation if `deterministic_fallback` is set.
    #[error("AI provider unavailable: {0}")]
    Unavailable(String),

    /// The provider returned a response that failed structural validation —
    /// for example, a `select()` response whose `selected_id` was not in
    /// the provided option set (see [`validate_select_response`]).
    #[error("invalid AI provider response: {0}")]
    InvalidResponse(String),
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn variants_format_distinct_messages() {
        let errs = [
            AiError::Network("dns".into()),
            AiError::Auth("401".into()),
            AiError::Timeout("30s".into()),
            AiError::RateLimited("429".into()),
            AiError::BudgetExceeded("cap".into()),
            AiError::ProviderError("500".into()),
            AiError::Unavailable("down".into()),
            AiError::InvalidResponse("bad id".into()),
        ];
        let msgs: Vec<String> = errs.iter().map(|e| format!("{e}")).collect();
        for (i, m) in msgs.iter().enumerate() {
            for (j, n) in msgs.iter().enumerate() {
                if i != j {
                    assert_ne!(m, n, "variants {i} and {j} produced identical messages");
                }
            }
        }
    }

    #[test]
    fn debug_output_is_serializable_to_string() {
        // Acceptance criterion: variants serializable for debug output.
        let e = AiError::ProviderError("boom".into());
        let dbg = format!("{e:?}");
        assert!(dbg.contains("ProviderError"));
        assert!(dbg.contains("boom"));
    }

    #[test]
    fn error_trait_implemented() {
        fn assert_error<E: std::error::Error>() {}
        assert_error::<AiError>();
    }
}