Skip to main content

mutil_ai/
report.rs

1use serde::{Deserialize, Serialize};
2
3use crate::normalize::NormalizeStats;
4
5/// A stable summary of transformations applied while preparing or decoding a
6/// model request.
7///
8/// Reports never contain message, reasoning, tool argument, or tool result
9/// content.
10#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
11pub struct CompletionReport {
12    /// Whether a [`crate::transform::RequestTransform`] was applied to the
13    /// request.
14    pub transform_applied: bool,
15    /// Normalization repairs applied to the conversation model.
16    pub normalization: NormalizeStats,
17    /// Lossy provider-wire transformations.
18    pub wire: WireReport,
19}
20
21impl CompletionReport {
22    /// Creates a report carrying only normalization statistics.
23    pub fn from_normalization(normalization: NormalizeStats) -> Self {
24        Self {
25            normalization,
26            ..Self::default()
27        }
28    }
29
30    /// Returns `true` when no transform, normalization repair, or wire
31    /// action was recorded.
32    pub fn is_clean(&self) -> bool {
33        !self.transform_applied && self.normalization.is_clean() && self.wire.actions.is_empty()
34    }
35}
36
37/// Provider-wire transformations that could not be represented losslessly.
38#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
39pub struct WireReport {
40    /// Individual lossy transformations, in the order they occurred.
41    pub actions: Vec<WireAction>,
42}
43
44impl WireReport {
45    /// Records a wire action.
46    pub fn push(&mut self, action: WireAction) {
47        self.actions.push(action);
48    }
49}
50
51#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
52#[serde(tag = "kind", rename_all = "snake_case")]
53pub enum WireAction {
54    /// A feature was not representable on the wire and was dropped.
55    Unsupported {
56        /// The dropped feature.
57        feature: WireFeature,
58        /// How many items were affected.
59        count: u32,
60    },
61    /// A feature was sent in a weaker, lossy form.
62    Downgraded {
63        /// The original feature.
64        feature: WireFeature,
65        /// Short description of the fallback used.
66        to: String,
67        /// How many items were affected.
68        count: u32,
69    },
70}
71
72#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
73#[serde(rename_all = "snake_case")]
74pub enum WireFeature {
75    /// Structured tool-result parts.
76    StructuredToolResult,
77    /// Image references inside tool results or messages.
78    ImageReference,
79    /// Provider-hosted tools.
80    ServerTool,
81    /// Opaque provider-hosted tool items.
82    ProviderItem,
83    /// A request-level field.
84    RequestField,
85}