lingshu-sdk-core 0.10.0

Stable facade for Lingshu agent runtime — used by Rust, Python, and Node.js SDKs
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

//! SDK error hierarchy.
//!
//! [`SdkError`] is the single error type returned by all SDK methods.
//! It wraps the internal [`AgentError`] and [`ToolError`] types and adds
//! SDK-specific variants for configuration and conversion failures.

use lingshu_types::{AgentError, ToolError};

/// Top-level error type for all SDK operations.
#[derive(Debug, thiserror::Error)]
pub enum SdkError {
    /// An error originating from the agent runtime.
    #[error(transparent)]
    Agent(#[from] AgentError),

    /// An error originating from a tool execution.
    #[error(transparent)]
    Tool(#[from] ToolError),

    /// Configuration error (missing keys, bad values, file not found).
    #[error("SDK configuration error: {0}")]
    Config(String),

    /// Provider could not be created for the given model string.
    #[error("Provider error for model '{model}': {message}")]
    Provider { model: String, message: String },

    /// Serialization / deserialization failure at the SDK boundary.
    #[error("Serialization error: {0}")]
    Serialization(#[from] serde_json::Error),

    /// The agent has not been properly initialized.
    #[error("Agent not initialized: {0}")]
    NotInitialized(String),
}

impl SdkError {
    /// Returns `true` if the error is retryable (rate limit, transient network).
    pub fn is_retryable(&self) -> bool {
        match self {
            Self::Agent(AgentError::RateLimited { .. }) => true,
            Self::Agent(AgentError::Llm(msg)) => {
                msg.contains("timeout") || msg.contains("connection")
            }
            _ => false,
        }
    }

    /// Returns the category string for observability/logging.
    pub fn category(&self) -> &'static str {
        match self {
            Self::Agent(_) => "agent",
            Self::Tool(_) => "tool",
            Self::Config(_) => "config",
            Self::Provider { .. } => "provider",
            Self::Serialization(_) => "serialization",
            Self::NotInitialized(_) => "initialization",
        }
    }
}