synwire_core/callbacks/
traits.rs

1//! Callback handler trait for observability hooks.
2
3use crate::BoxFuture;
4use crate::messages::Message;
5use serde_json::Value;
6
7/// Trait for receiving callback events during execution.
8///
9/// All methods have default no-op implementations, so consumers only need
10/// to override the events they care about. The `ignore_*` methods allow
11/// filtering entire categories of events.
12///
13/// # Example
14///
15/// ```
16/// use synwire_core::callbacks::CallbackHandler;
17/// use synwire_core::BoxFuture;
18///
19/// struct LoggingCallback;
20///
21/// impl CallbackHandler for LoggingCallback {
22///     fn on_tool_start<'a>(
23///         &'a self,
24///         _tool_name: &'a str,
25///         _input: &'a serde_json::Value,
26///     ) -> BoxFuture<'a, ()> {
27///         Box::pin(async {
28///             // log tool start
29///         })
30///     }
31/// }
32/// ```
33pub trait CallbackHandler: Send + Sync {
34    /// Called when an LLM invocation starts.
35    fn on_llm_start<'a>(
36        &'a self,
37        _model_type: &'a str,
38        _messages: &'a [Message],
39    ) -> BoxFuture<'a, ()> {
40        Box::pin(async {})
41    }
42
43    /// Called when an LLM invocation ends.
44    fn on_llm_end<'a>(&'a self, _response: &'a Value) -> BoxFuture<'a, ()> {
45        Box::pin(async {})
46    }
47
48    /// Called when a tool invocation starts.
49    fn on_tool_start<'a>(&'a self, _tool_name: &'a str, _input: &'a Value) -> BoxFuture<'a, ()> {
50        Box::pin(async {})
51    }
52
53    /// Called when a tool invocation ends.
54    fn on_tool_end<'a>(&'a self, _tool_name: &'a str, _output: &'a str) -> BoxFuture<'a, ()> {
55        Box::pin(async {})
56    }
57
58    /// Called on tool error.
59    fn on_tool_error<'a>(&'a self, _tool_name: &'a str, _error: &'a str) -> BoxFuture<'a, ()> {
60        Box::pin(async {})
61    }
62
63    /// Called on retry.
64    fn on_retry<'a>(&'a self, _attempt: u32, _error: &'a str) -> BoxFuture<'a, ()> {
65        Box::pin(async {})
66    }
67
68    /// Called when a chain starts.
69    fn on_chain_start<'a>(&'a self, _chain_name: &'a str) -> BoxFuture<'a, ()> {
70        Box::pin(async {})
71    }
72
73    /// Called when a chain ends.
74    fn on_chain_end<'a>(&'a self, _output: &'a Value) -> BoxFuture<'a, ()> {
75        Box::pin(async {})
76    }
77
78    /// Whether to ignore tool callbacks.
79    fn ignore_tool(&self) -> bool {
80        false
81    }
82
83    /// Whether to ignore LLM callbacks.
84    fn ignore_llm(&self) -> bool {
85        false
86    }
87}
synwire_core/callbacks/traits.rs

synwire_core/callbacks/
traits.rs
