kova-sdk 0.3.0

Async-first Rust library for building LLM-powered agents with tool calling, streaming, MCP, and multi-agent orchestration
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

use std::time::Duration;

/// Unified error type for the kova SDK.
#[derive(Debug, thiserror::Error)]
pub enum KovaError {
    #[error("Provider error: {message} (status: {status_code:?})")]
    Provider {
        message: String,
        status_code: Option<u16>,
    },

    #[error("Connection error: {0}")]
    Connection(String),

    #[error("Tool execution error: {tool_name}: {message}")]
    ToolExecution { tool_name: String, message: String },

    #[error("Tool not found: {0}")]
    ToolNotFound(String),

    #[error("Serialization error: {0}")]
    Serialization(#[from] serde_json::Error),

    #[error("Timeout after {0:?}")]
    Timeout(Duration),

    #[error("MCP error: {0}")]
    Mcp(String),

    #[error("Memory error: {0}")]
    Memory(String),

    #[error("Orchestration error: {0}")]
    Orchestration(String),

    #[error("Build error: {0}")]
    Build(String),

    #[error("Stream error: {0}")]
    Stream(String),

    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("Max iterations ({0}) reached in tool-call loop")]
    MaxIterations(usize),
}

impl KovaError {
    /// HTTP status code reported by the provider, when available.
    pub fn status_code(&self) -> Option<u16> {
        match self {
            KovaError::Provider { status_code, .. } => *status_code,
            _ => None,
        }
    }

    /// Whether retrying the request might succeed.
    ///
    /// True for connection failures, timeouts, and transient provider
    /// statuses (408, 429, 5xx, and Anthropic's 529 overloaded).
    pub fn is_retryable(&self) -> bool {
        match self {
            KovaError::Connection(_) | KovaError::Timeout(_) => true,
            KovaError::Provider {
                status_code: Some(code),
                ..
            } => matches!(code, 408 | 429 | 500 | 502 | 503 | 504 | 529),
            _ => false,
        }
    }
}