ferrin-core 0.1.1

Ferrin core: text generation loop, streaming pipeline, structured output, agents, middleware, registry.
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

//! Timeout configuration.

use std::collections::HashMap;
use std::time::Duration;

use ferrin_spec::ToolName;
use serde::Deserialize;
use serde::Serialize;

/// Timeouts applied to a call.
///
/// `first_chunk` and `chunk` only apply to streaming calls; `total` covers
/// the whole call including tool execution.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Timeout {
    /// Whole call.
    pub total: Option<Duration>,
    /// One step (model call plus its tool executions).
    pub step: Option<Duration>,
    /// Streaming: from the request until the first content part.
    pub first_chunk: Option<Duration>,
    /// Streaming: between two consecutive content parts.
    pub chunk: Option<Duration>,
    /// Default per tool execution.
    pub tool: Option<Duration>,
    /// Per-tool overrides of `tool`.
    pub per_tool: HashMap<ToolName, Duration>,
}

impl Timeout {
    /// No timeouts.
    #[must_use]
    pub fn none() -> Self {
        Self::default()
    }

    /// Sets the total timeout.
    #[must_use]
    pub fn with_total(mut self, total: Duration) -> Self {
        self.total = Some(total);
        self
    }

    /// Sets the step timeout.
    #[must_use]
    pub fn with_step(mut self, step: Duration) -> Self {
        self.step = Some(step);
        self
    }

    /// Sets the first-chunk timeout (streaming only).
    #[must_use]
    pub fn with_first_chunk(mut self, first_chunk: Duration) -> Self {
        self.first_chunk = Some(first_chunk);
        self
    }

    /// Sets the inter-chunk timeout (streaming only).
    #[must_use]
    pub fn with_chunk(mut self, chunk: Duration) -> Self {
        self.chunk = Some(chunk);
        self
    }

    /// Sets the default tool timeout.
    #[must_use]
    pub fn with_tool(mut self, tool: Duration) -> Self {
        self.tool = Some(tool);
        self
    }

    /// Sets the timeout of one tool.
    #[must_use]
    pub fn with_tool_for(mut self, name: impl Into<ToolName>, timeout: Duration) -> Self {
        self.per_tool.insert(name.into(), timeout);
        self
    }

    /// Returns the timeout for `tool`: the per-tool override, else the
    /// default tool timeout.
    #[must_use]
    pub fn tool_timeout(&self, tool: &ToolName) -> Option<Duration> {
        self.per_tool.get(tool).copied().or(self.tool)
    }
}

impl From<Duration> for Timeout {
    /// A bare duration is the total timeout.
    fn from(total: Duration) -> Self {
        Self::default().with_total(total)
    }
}

/// Which timeout fired.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "scope", rename_all = "kebab-case")]
#[non_exhaustive]
pub enum TimeoutScope {
    /// [`Timeout::total`].
    Total,
    /// [`Timeout::step`].
    Step,
    /// [`Timeout::first_chunk`].
    FirstChunk,
    /// [`Timeout::chunk`].
    Chunk,
    /// [`Timeout::tool`] or a per-tool override.
    Tool {
        /// The tool that timed out.
        tool_name: ToolName,
    },
}

impl std::fmt::Display for TimeoutScope {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Total => f.write_str("total"),
            Self::Step => f.write_str("step"),
            Self::FirstChunk => f.write_str("first chunk"),
            Self::Chunk => f.write_str("chunk"),
            Self::Tool { tool_name } => write!(f, "tool `{tool_name}`"),
        }
    }
}