synwire-core 0.1.0

Core traits and types for the Synwire AI framework
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
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Stream events and content categories.

use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::HashMap;

/// An event emitted during runnable execution.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind")]
#[non_exhaustive]
pub enum StreamEvent {
    /// Standard lifecycle event.
    #[serde(rename = "standard")]
    Standard {
        /// Event name (e.g. `on_chain_start`).
        event: String,
        /// Runnable name.
        name: String,
        /// Run identifier.
        run_id: String,
        /// Parent run identifiers.
        #[serde(default)]
        parent_ids: Vec<String>,
        /// Tags.
        #[serde(default)]
        tags: Vec<String>,
        /// Metadata.
        #[serde(default)]
        metadata: HashMap<String, Value>,
        /// Event data.
        data: EventData,
    },
    /// Custom user-dispatched event.
    #[serde(rename = "custom")]
    Custom {
        /// Event name.
        name: String,
        /// Run identifier.
        run_id: String,
        /// Parent run identifiers.
        #[serde(default)]
        parent_ids: Vec<String>,
        /// Tags.
        #[serde(default)]
        tags: Vec<String>,
        /// Metadata.
        #[serde(default)]
        metadata: HashMap<String, Value>,
        /// Custom event data.
        data: Value,
    },
}

/// Data payload for standard stream events.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct EventData {
    /// Input data.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub input: Option<Value>,
    /// Output data.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub output: Option<Value>,
    /// Chunk data (for streaming events).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub chunk: Option<Value>,
    /// Error description.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// Content category distinguishing primary response content from
    /// secondary metadata such as tool calls and usage metrics.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub category: Option<ContentCategory>,
}

/// Dispatch a custom event.
///
/// Creates a [`StreamEvent::Custom`] with the given name and data.
/// The `run_id` is set to an empty string and can be overridden by the
/// event bus or callback infrastructure.
pub fn dispatch_custom_event(name: impl Into<String>, data: serde_json::Value) -> StreamEvent {
    StreamEvent::Custom {
        name: name.into(),
        run_id: String::new(),
        parent_ids: Vec::new(),
        tags: Vec::new(),
        metadata: HashMap::new(),
        data,
    }
}

/// Distinguishes primary from secondary content in streaming responses.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum ContentCategory {
    /// Actual response content: text, structured data.
    Primary,
    /// Intermediate: tool calls, reasoning, usage metrics.
    Secondary,
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::panic)]
mod tests {
    use super::*;

    #[test]
    fn test_dispatch_custom_event() {
        let data = serde_json::json!({"key": "value"});
        let event = dispatch_custom_event("my_event", data.clone());
        match event {
            StreamEvent::Custom { name, data: d, .. } => {
                assert_eq!(name, "my_event");
                assert_eq!(d, data);
            }
            _ => panic!("expected Custom variant"),
        }
    }

    #[test]
    fn test_dispatch_custom_event_empty_defaults() {
        let event = dispatch_custom_event("test", serde_json::Value::Null);
        match event {
            StreamEvent::Custom {
                run_id,
                parent_ids,
                tags,
                metadata,
                ..
            } => {
                assert!(run_id.is_empty());
                assert!(parent_ids.is_empty());
                assert!(tags.is_empty());
                assert!(metadata.is_empty());
            }
            _ => panic!("expected Custom variant"),
        }
    }
}