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

synapto_interface/
plugin.rs
