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}