Skip to main content

khive_runtime/runtime/
engine_binding.rs

1//! Ordered configured provider binding and programmatic registration.
2
3use super::*;
4
5impl KhiveRuntime {
6    /// Return the name of the default embedding model (empty string if none configured).
7    pub fn default_embedder_name(&self) -> &str {
8        self.default_embedder_name.as_ref()
9    }
10
11    /// Resolve a model name (or `None` for the default) to an `EmbeddingModel`.
12    ///
13    /// This compatibility API only represents built-in lattice models.
14    /// Use named embedding APIs for custom providers.
15    /// Returns `UnknownModel` if the name is not in the registry, or
16    /// `Unconfigured` if `None` is passed and no default model is set.
17    pub fn resolve_embedding_model(&self, name: Option<&str>) -> RuntimeResult<EmbeddingModel> {
18        let model = match name {
19            Some(raw) => parse_embedding_model_alias(raw)
20                .ok_or_else(|| crate::RuntimeError::UnknownModel(raw.to_string()))?,
21            None => self
22                .config
23                .embedding_model
24                .ok_or_else(|| crate::RuntimeError::Unconfigured("embedding_model".into()))?,
25        };
26        let key = model.to_string();
27        if request_excludes_embedder(&key) {
28            return Err(crate::RuntimeError::UnknownModel(
29                name.unwrap_or_else(|| self.default_embedder_name())
30                    .to_string(),
31            ));
32        }
33        let contains = self
34            .embedder_registry
35            .read()
36            .map(|reg| reg.contains(&key))
37            .unwrap_or(false);
38        if contains {
39            Ok(model)
40        } else {
41            Err(crate::RuntimeError::UnknownModel(
42                name.unwrap_or_else(|| self.default_embedder_name())
43                    .to_string(),
44            ))
45        }
46    }
47
48    /// Names of all registered embedding models in this runtime.
49    ///
50    /// Includes both built-in lattice models and any custom embedders
51    /// registered by packs via [`register_embedder`](Self::register_embedder).
52    /// Useful for operations that must touch every model's storage (e.g.,
53    /// scoped vector deletion on note delete). The default model is included.
54    pub fn registered_embedding_model_names(&self) -> Vec<String> {
55        self.embedder_registry
56            .read()
57            .map(|reg| {
58                reg.names()
59                    .into_iter()
60                    .filter(|name| !request_excludes_embedder(name))
61                    .collect()
62            })
63            .unwrap_or_default()
64    }
65
66    /// Capture storage identities and dimensions under one registry read lock.
67    /// No service is resolved and no writer is held while taking this snapshot.
68    pub(crate) fn entity_index_model_snapshot(&self) -> RuntimeResult<Vec<(String, usize)>> {
69        let registry = self
70            .embedder_registry
71            .read()
72            .map_err(|_| RuntimeError::Internal("embedder registry lock poisoned".into()))?;
73        registry
74            .names()
75            .into_iter()
76            .filter(|name| !request_excludes_embedder(name))
77            .map(|name| {
78                if let Some(model) = parse_embedding_model_alias(&name) {
79                    let key = model.to_string();
80                    if registry.contains(&key) {
81                        return Ok((key, model.dimensions()));
82                    }
83                }
84                registry
85                    .get_provider(&name)
86                    .map(|provider| (name.clone(), provider.dimensions()))
87                    .ok_or_else(|| RuntimeError::UnknownModel(name))
88            })
89            .collect()
90    }
91
92    /// Get the lazily-initialized embedding service for the named model.
93    ///
94    /// Accepts both built-in lattice model names (e.g. `"all-minilm-l6-v2"`,
95    /// `"paraphrase"`) and custom provider names registered via
96    /// [`register_embedder`](Self::register_embedder).
97    ///
98    /// For lattice model names, aliases (e.g. `"paraphrase"`) are resolved to
99    /// their canonical key before looking up the registry. For custom providers
100    /// the name must match exactly as supplied during registration.
101    ///
102    /// First call for any name loads the underlying service (cold start cost);
103    /// subsequent calls are cheap (registry caches the `Arc`).
104    pub async fn embedder(&self, name: &str) -> RuntimeResult<Arc<dyn EmbeddingService>> {
105        Ok(self.embedder_inner(name, None).await?.0)
106    }
107
108    pub(crate) async fn embedder_with_token(
109        &self,
110        token: &NamespaceToken,
111        name: &str,
112    ) -> RuntimeResult<Arc<dyn EmbeddingService>> {
113        Ok(self.embedder_inner(name, Some(token)).await?.0)
114    }
115
116    /// Resolve the service and its document-preparation attestation from the
117    /// same registry entry. Cloning it also avoids holding a registry lock
118    /// across the asynchronous service resolution.
119    pub(crate) async fn embedder_with_input_attestation(
120        &self,
121        name: &str,
122        token: Option<&NamespaceToken>,
123    ) -> RuntimeResult<(Arc<dyn EmbeddingService>, bool)> {
124        self.embedder_inner(name, token).await
125    }
126
127    /// Register a custom embedding provider with this runtime.
128    ///
129    /// The provider is added to the shared [`EmbedderRegistry`] so all clones
130    /// of this runtime see the new provider immediately. Setup may replace a
131    /// provider before it is selected for resolution. Later duplicates are
132    /// refused and logged; use [`try_register_embedder`](Self::try_register_embedder)
133    /// when the caller needs to handle registration errors.
134    ///
135    /// Packs should call this from [`crate::PackRuntime::register_embedders`] (the
136    /// hook is invoked by the transport during pack initialisation, before the
137    /// first verb dispatch).
138    ///
139    /// [`EmbedderRegistry`]: crate::embedder_registry::EmbedderRegistry
140    pub fn register_embedder(
141        &self,
142        provider: impl crate::embedder_registry::EmbedderProvider + 'static,
143    ) {
144        if let Err(error) = self.try_register_embedder(provider) {
145            tracing::warn!(target: "khive_runtime::runtime", %error, "embedder registration refused");
146        }
147    }
148
149    /// Register a custom embedding provider and return serving-duplicate or lock errors.
150    ///
151    /// Unlike [`register_embedder`](Self::register_embedder), this method lets
152    /// callers fail initialization when registration cannot be completed.
153    pub fn try_register_embedder(
154        &self,
155        provider: impl crate::embedder_registry::EmbedderProvider + 'static,
156    ) -> RuntimeResult<()> {
157        if let Some(model) = parse_embedding_model_alias(provider.name()) {
158            if provider.dimensions() != model.dimensions() {
159                return Err(RuntimeError::InvalidInput(format!(
160                    "embedding provider `{}` has dimensions {}, but its built-in storage binding requires {}",
161                    provider.name(), provider.dimensions(), model.dimensions()
162                )));
163            }
164        }
165        if let Some(engine) = self
166            .config
167            .engines
168            .as_ref()
169            .and_then(|engines| engines.iter().find(|engine| engine.name == provider.name()))
170        {
171            engine
172                .check_dimensions(provider.dimensions())
173                .map_err(|error| RuntimeError::InvalidInput(error.to_string()))?;
174        }
175        let mut registry = self
176            .embedder_registry
177            .write()
178            .map_err(|_| RuntimeError::Internal("embedder registry lock poisoned".into()))?;
179        registry.register(provider)
180    }
181
182    /// Install a deterministic backend for exact-input provenance tests.
183    /// The test adapter, not the supplied backend, owns lattice passage
184    /// prefixing; this API is absent unless `test-internals` is enabled.
185    #[cfg(feature = "test-internals")]
186    pub fn register_test_audited_embedder(
187        &self,
188        model: EmbeddingModel,
189        provider: impl crate::embedder_registry::EmbedderProvider + 'static,
190    ) {
191        self.embedder_registry
192            .write()
193            .expect("test embedder registry lock")
194            .register_test_audited(model, provider);
195    }
196
197    /// Replace the provider under an already-bound engine name in a test host.
198    /// See [`EmbedderRegistry::replace_bound_for_test`] for the refusals; this
199    /// API is absent unless `test-internals` is enabled.
200    ///
201    /// [`EmbedderRegistry::replace_bound_for_test`]: crate::embedder_registry::EmbedderRegistry::replace_bound_for_test
202    #[cfg(feature = "test-internals")]
203    pub fn replace_bound_embedder_for_test(
204        &self,
205        provider: impl crate::embedder_registry::EmbedderProvider + 'static,
206    ) -> RuntimeResult<()> {
207        self.embedder_registry
208            .write()
209            .map_err(|_| RuntimeError::Internal("embedder registry lock poisoned".into()))?
210            .replace_bound_for_test(provider)
211    }
212
213    /// Bind every configured engine after host and pack provider registration.
214    ///
215    /// Low-level hosts call this before serving. Validation is atomic within
216    /// this shared registry and reads provider metadata only: it does not build
217    /// services, access storage, or change historical embedding spaces. A
218    /// successful binding freezes those provider names. Repeating the same
219    /// binding is a no-op; a failed attempt can be retried after registration.
220    /// Explicitly named registered providers remain independently accessible.
221    pub fn finalize_embedding_engines(&self) -> RuntimeResult<()> {
222        self.initialize_embedding_engines(|| {})
223    }
224
225    /// Canonical configured participation order, distinct from all registered names.
226    ///
227    /// Returns `Unconfigured` until the host finalizes binding. An explicitly
228    /// empty configuration binds an empty list and has no default provider.
229    pub fn bound_embedding_engine_names(&self) -> RuntimeResult<Vec<String>> {
230        self.embedder_registry
231            .read()
232            .map_err(|_| RuntimeError::Internal("embedder registry lock poisoned".into()))?
233            .bound_engines()
234            .map(|engines| engines.iter().map(|engine| engine.name.clone()).collect())
235            .ok_or_else(|| RuntimeError::Unconfigured("embedding engine binding".into()))
236    }
237
238    pub(crate) fn embedding_registry_identity(&self) -> usize {
239        Arc::as_ptr(&self.embedder_registry) as usize
240    }
241
242    pub(crate) fn initialize_embedding_engines(
243        &self,
244        register: impl FnOnce(),
245    ) -> RuntimeResult<()> {
246        let initialization = self
247            .embedder_registry
248            .read()
249            .map_err(|_| RuntimeError::Internal("embedder registry lock poisoned".into()))?
250            .initialization_lock();
251        // Registration itself acquires the registry write lock. Serialize the
252        // lifecycle outside that lock so hooks can use the ordinary public API.
253        let _initialization = initialization
254            .lock()
255            .map_err(|_| RuntimeError::Internal("embedder initialization lock poisoned".into()))?;
256        let engines = self.config.configured_engines();
257        let already_bound = self
258            .embedder_registry
259            .read()
260            .map_err(|_| RuntimeError::Internal("embedder registry lock poisoned".into()))?
261            .bound_engines()
262            .is_some();
263        if !already_bound && !engines.is_empty() {
264            register();
265        }
266        self.embedder_registry
267            .write()
268            .map_err(|_| RuntimeError::Internal("embedder registry lock poisoned".into()))?
269            .bind_engines(&engines)
270    }
271}