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}