ferrin-core 0.2.0

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

//! Built-in `tracing` spans and events following the GenAI semantic
//! conventions (`gen_ai.*`); Ferrin-specific fields use the `ferrin.*`
//! prefix.

use ferrin_spec::Warning;
use tracing::Span;

use super::ModelIdentity;

/// Target used for adapter warnings.
pub const WARNINGS_TARGET: &str = "ferrin::warnings";

/// Span for a `generate_text` or `stream_text` call.
pub(crate) fn call_span(
    operation: &'static str,
    function_id: Option<&str>,
    model: &ModelIdentity,
) -> Span {
    tracing::info_span!(
        "ferrin.call",
        "gen_ai.operation.name" = operation,
        "ferrin.function_id" = function_id.unwrap_or(""),
        "gen_ai.request.model" = %model.model_id,
        "gen_ai.provider.name" = %model.provider,
    )
}

/// Span for one step.
pub(crate) fn step_span(step_number: u32) -> Span {
    tracing::info_span!("ferrin.step", "ferrin.step_number" = step_number)
}

/// Span for one model call.
pub(crate) fn model_call_span(model: &ModelIdentity) -> Span {
    tracing::info_span!(
        "ferrin.model_call",
        "gen_ai.request.model" = %model.model_id,
        "gen_ai.provider.name" = %model.provider,
        "gen_ai.response.id" = tracing::field::Empty,
        "gen_ai.response.finish_reasons" = tracing::field::Empty,
        "gen_ai.usage.input_tokens" = tracing::field::Empty,
        "gen_ai.usage.output_tokens" = tracing::field::Empty,
        "ferrin.time_to_first_output_ms" = tracing::field::Empty,
    )
}

/// Span for one tool execution.
pub(crate) fn tool_span(tool_name: &str, tool_call_id: &str) -> Span {
    tracing::info_span!(
        "ferrin.tool",
        "gen_ai.tool.name" = tool_name,
        "gen_ai.tool.call.id" = tool_call_id,
        "ferrin.tool.duration_ms" = tracing::field::Empty,
    )
}

/// Span for a non-text modality (`embed`, `rerank`, `image`, ...).
pub(crate) fn modality_span(operation: &'static str, model: &ModelIdentity) -> Span {
    tracing::info_span!(
        "ferrin.modality",
        "gen_ai.operation.name" = operation,
        "gen_ai.request.model" = %model.model_id,
        "gen_ai.provider.name" = %model.provider,
    )
}

/// Logs adapter warnings, one event per warning.
pub(crate) fn log_warnings(warnings: &[Warning], model: &ModelIdentity) {
    for warning in warnings {
        // Adapter descriptions can contain prompt or generated text. Keep them
        // in application-facing warnings, never in unconditional tracing logs.
        let (kind, feature) = match warning {
            Warning::Unsupported { feature, .. } => ("unsupported", feature.as_str()),
            Warning::Compatibility { feature, .. } => ("compatibility", feature.as_str()),
            Warning::Deprecated { setting, .. } => ("deprecated", setting.as_str()),
            _ => ("other", ""),
        };
        tracing::warn!(
            target: WARNINGS_TARGET,
            category = kind,
            feature = feature,
            provider = %model.provider,
            model_id = %model.model_id,
            "provider warning"
        );
    }
}