synapto_interface/
plugin.rs

1use crate::audio_recorder::AudioRecorderPlugin;
2use crate::call::CallPlugin;
3use crate::camera::CameraPlugin;
4use crate::chat::ChatPlugin;
5use crate::cognitive_output_audio::AudioOutputPlugin;
6use crate::document::{DocumentProviderPlugin, DocumentsPlugin};
7use crate::gui::GuiPlugin;
8use crate::interaction::{InteractionObserver, RetrospectiveConsolidationPlugin};
9use crate::peer_input_audio::AudioInputPlugin;
10use crate::rollout::RolloutController;
11use crate::speech_to_text::{DiarizationPlugin, STTPlugin, TTSPlugin};
12use async_trait::async_trait;
13use schemars::JsonSchema;
14use serde::{Deserialize, Serialize};
15
16pub struct PluginInitContext<'a> {
17    llm_executor: crate::llm::LlmExecutor,
18    plugin_config: &'a serde_json::Value,
19    storage: crate::storage::StorageHandle,
20    plugin_namespace: &'a str,
21}
22
23impl<'a> PluginInitContext<'a> {
24    #[doc = " Internal constructor used by the Core AI engine."]
25    #[doc(hidden)]
26    pub fn new(
27        llm_executor: crate::llm::LlmExecutor,
28        plugin_config: &'a serde_json::Value,
29        storage: crate::storage::StorageHandle,
30        plugin_namespace: &'a str,
31    ) -> Self {
32        Self {
33            llm_executor,
34            plugin_config,
35            storage,
36            plugin_namespace,
37        }
38    }
39
40    #[doc = " Deserializes the raw JSON configuration into the plugin's requested config struct."]
41    #[doc = ""]
42    #[doc = " **Note on Serde Configuration Defaults:**"]
43    #[doc = " This performs strict structural deserialization. If the JSON object provided by the"]
44    #[doc = " `ConfigProvider` is missing a field that your Rust struct (which must derive `Deserialize`) expects, `serde` will"]
45    #[doc = " return a `missing field` error — even if your struct implements `Default`."]
46    #[doc = ""]
47    #[doc = " To make a configuration field optional, use the `#[serde(default)]`"]
48    #[doc = " attribute on the struct field. This instructs `serde` to fall back to `Default::default()`"]
49    #[doc = " when the key is omitted."]
50    pub fn config<C: serde::de::DeserializeOwned>(&self) -> Result<C, String> {
51        serde_json::from_value(self.plugin_config.clone())
52            .map_err(|e| format!("Failed to parse plugin config: {}", e))
53    }
54
55    #[doc = " Extracts the configuration if present, or returns `None` if the configuration is completely empty or null."]
56    #[doc = " This allows plugins to have a mandatory configuration schema when provided, but remain optional overall."]
57    pub fn optional_config<C: serde::de::DeserializeOwned>(&self) -> Result<Option<C>, String> {
58        if self.plugin_config.is_null()
59            || self.plugin_config.as_object().is_some_and(|m| m.is_empty())
60        {
61            return Ok(None);
62        }
63        self.config().map(Some)
64    }
65
66    #[doc = " Initializes and returns a shared database connection scoped strictly to this plugin's namespace."]
67    pub async fn store<S: crate::storage::StorageConnection>(
68        &self,
69    ) -> Result<std::sync::Arc<S>, String> {
70        self.storage.connect_store::<S>(self.plugin_namespace).await
71    }
72
73    pub fn llm_executor(&self) -> crate::llm::LlmExecutor {
74        self.llm_executor.clone()
75    }
76}
77
78pub trait PluginRegistry {
79    fn register_gui<P: GuiPlugin>(&mut self, plugin: std::sync::Arc<P>);
80    fn register_audio_input<P: AudioInputPlugin>(&mut self, plugin: std::sync::Arc<P>);
81    fn register_audio_output<P: AudioOutputPlugin>(&mut self, plugin: std::sync::Arc<P>);
82    fn register_stt<P: STTPlugin>(&mut self, plugin: std::sync::Arc<P>);
83    fn register_tts<P: TTSPlugin>(&mut self, plugin: std::sync::Arc<P>);
84    fn register_diarization<P: DiarizationPlugin>(&mut self, plugin: std::sync::Arc<P>);
85    fn register_chat<P: ChatPlugin>(&mut self, plugin: std::sync::Arc<P>);
86    fn register_documents<P: DocumentsPlugin>(&mut self, plugin: std::sync::Arc<P>);
87    fn register_document_provider<P: DocumentProviderPlugin>(&mut self, plugin: std::sync::Arc<P>);
88    fn register_interaction_observer<P: InteractionObserver>(&mut self, plugin: std::sync::Arc<P>);
89    fn register_rollout_controller<P: RolloutController>(&mut self, plugin: std::sync::Arc<P>);
90    fn register_retrospective_consolidation<P: RetrospectiveConsolidationPlugin>(
91        &mut self,
92        plugin: std::sync::Arc<P>,
93    );
94    fn register_camera<P: CameraPlugin>(&mut self, plugin: std::sync::Arc<P>);
95    fn register_context_provider<P: crate::context::IntoContextProvider>(&mut self, provider: P);
96    fn register_command<C: crate::command::Command>(&mut self, command: C);
97    #[doc = " Registers a static tool implementation."]
98    fn register_tool<T: crate::tool::Tool>(&mut self, tool: T);
99    #[doc = " Registers a type-erased dynamic tool handle (e.g. dynamically discovered at runtime)."]
100    fn register_erased_tool(&mut self, tool: crate::tool::ToolHandle);
101    fn register_call<P: CallPlugin>(
102        &mut self,
103        plugin: std::sync::Arc<P>,
104        capability: Option<&'static str>,
105    );
106    fn register_recorder<P: AudioRecorderPlugin>(&mut self, plugin: std::sync::Arc<P>);
107}
108
109#[derive(Debug, Clone, Serialize, Deserialize, Default)]
110pub struct EmptyPluginConfig {}
111
112#[async_trait]
113pub trait Plugin: Send + Sync + 'static {
114    #[doc = " Compile-time semantic description of this plugin's capability for the LLM."]
115    const CAPABILITY: Option<&'static str> = None;
116    #[doc = " This is the method for instantiating plugins, allowing them to await"]
117    #[doc = " their database connections (via `context.store::<S>().await`) before returning."]
118    #[doc = ""]
119    #[doc = " **Note on Configuration:** Configuration in Synapto plugins is entirely optional."]
120    #[doc = " If your plugin requires no configuration, simply do not define a config struct"]
121    #[doc = " and do not call `context.config()?`."]
122    #[doc = ""]
123    #[doc = " If you do define a config struct: when calling `context.config()?` to extract your configuration,"]
124    #[doc = " ensure any optional fields in your struct are marked with `#[serde(default)]`. Otherwise,"]
125    #[doc = " omitted fields in the config file will cause strict deserialization errors."]
126    #[doc = " Alternatively, use `context.optional_config()?` to allow the entire config block to be safely omitted."]
127    async fn create(context: &crate::plugin::PluginInitContext<'_>) -> Result<Self, String>
128    where
129        Self: Sized;
130    fn register<R: PluginRegistry + ?Sized>(self: std::sync::Arc<Self>, registry: &mut R)
131    where
132        Self: Sized;
133}
134
135#[doc = " An opaque channel identifier used to route messages within the system."]
136#[derive(Serialize, Deserialize, JsonSchema, PartialEq, Eq, Debug, Clone)]
137pub struct MessageChannel {
138    #[doc = " Opaque JSON context provided by plugins or core modules."]
139    pub context: serde_json::Value,
140}
synapto_interface/plugin.rs

synapto_interface/
plugin.rs
