Skip to main content

powershell_mcp/
embed.rs

1//! Local embedding model (fastembed, ONNX, no API key).
2//!
3//! Default model is BAAI/bge-small-en-v1.5 (384 dims, English prose,
4//! cached on this machine in ~/.cache/fastembed). The PowerShell
5//! documentation is English technical prose, which is exactly what
6//! bge-small is tuned for; switch with the POWERSHELL_MCP_EMBED_MODEL
7//! environment variable. E5 models are trained with instruction prefixes
8//! ("query: " / "passage: "); bge is not. Sliced batching keeps peak
9//! memory bounded.
10
11use anyhow::{bail, Context, Result};
12use fastembed::{EmbeddingModel, TextEmbedding, TextInitOptions};
13use std::path::PathBuf;
14use std::sync::{Mutex, OnceLock};
15
16/// Number of texts handed to the model per call, bounding peak memory.
17/// The slice is split into batch-sized chunks that fastembed runs
18/// concurrently on its rayon pool, so a 256-text slice means four 64-text
19/// ONNX runs in flight — a good wall-clock/memory trade-off on machines
20/// with ~16 GB+ RAM.
21pub const EMBED_SLICE: usize = 256;
22
23/// Batch size passed to each fastembed call.
24pub const EMBED_BATCH: usize = 64;
25
26/// E5 instruction prefixes. Applied only when the active model needs them.
27pub const QUERY_PREFIX: &str = "query: ";
28pub const PASSAGE_PREFIX: &str = "passage: ";
29
30/// The embedding models this server knows how to run locally.
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum Model {
33    /// BAAI/bge-small-en-v1.5, 384 dims. English prose, fastest. Default.
34    BgeSmall,
35    /// intfloat/multilingual-e5-small, 384 dims. Multilingual, heavier.
36    E5Multilingual,
37    /// intfloat/multilingual-e5-base, 768 dims. Better quality, heaviest.
38    E5Base,
39}
40
41impl Model {
42    /// Resolve the active model from POWERSHELL_MCP_EMBED_MODEL; anything
43    /// unknown or unset means the default (bge-small).
44    pub fn from_env() -> Self {
45        match std::env::var("POWERSHELL_MCP_EMBED_MODEL").as_deref() {
46            Ok("e5-multilingual") | Ok("multilingual-e5-small") => Model::E5Multilingual,
47            Ok("e5-base") | Ok("multilingual-e5-base") => Model::E5Base,
48            _ => Model::BgeSmall,
49        }
50    }
51
52    fn fastembed(self) -> EmbeddingModel {
53        match self {
54            Model::BgeSmall => EmbeddingModel::BGESmallENV15,
55            Model::E5Multilingual => EmbeddingModel::MultilingualE5Small,
56            Model::E5Base => EmbeddingModel::MultilingualE5Base,
57        }
58    }
59
60    /// Identifier recorded in the index manifest. Must stay stable so the
61    /// stale-index guard can compare it across builds.
62    pub fn id(self) -> &'static str {
63        match self {
64            Model::BgeSmall => "bge-small-en-v1.5",
65            Model::E5Multilingual => "multilingual-e5-small",
66            Model::E5Base => "multilingual-e5-base",
67        }
68    }
69
70    /// Embedding dimension of the model.
71    pub fn dim(self) -> usize {
72        match self {
73            Model::BgeSmall => 384,
74            Model::E5Multilingual => 384,
75            Model::E5Base => 768,
76        }
77    }
78
79    /// Whether indexed passages and queries need the E5 instruction
80    /// prefixes.
81    pub fn uses_prefixes(self) -> bool {
82        matches!(self, Model::E5Multilingual | Model::E5Base)
83    }
84}
85
86/// The active model for this process.
87pub fn current_model() -> Model {
88    Model::from_env()
89}
90
91static EMBEDDER: OnceLock<Mutex<TextEmbedding>> = OnceLock::new();
92
93/// Embed texts into fixed-size vectors with bounded peak memory. The input
94/// is split into small sequential slices so the model never sees the whole
95/// corpus at once.
96pub fn embed_texts(texts: &[String]) -> Result<Vec<Vec<f32>>> {
97    let emb = embedder()?;
98    let mut out = Vec::with_capacity(texts.len());
99    for slice in texts.chunks(EMBED_SLICE) {
100        let vectors = emb
101            .lock()
102            .map_err(|_| anyhow::anyhow!("embedder mutex poisoned"))?
103            .embed(slice.to_vec(), Some(EMBED_BATCH))
104            .context("embed texts")?;
105        if vectors.len() != slice.len() {
106            bail!(
107                "embedding returned {} vectors for {} texts",
108                vectors.len(),
109                slice.len()
110            );
111        }
112        out.extend(vectors);
113    }
114    Ok(out)
115}
116
117/// The directory fastembed caches model binaries in: $FASTEMBED_CACHE, or
118/// ~/.cache/fastembed. Public so tests and tooling can detect whether a
119/// model is already downloaded.
120pub fn model_cache_dir() -> Option<PathBuf> {
121    std::env::var("FASTEMBED_CACHE")
122        .map(PathBuf::from)
123        .ok()
124        .or_else(|| {
125            std::env::var("HOME")
126                .ok()
127                .map(|h| PathBuf::from(h).join(".cache").join("fastembed"))
128        })
129}
130
131/// Whether the active model is already present in the cache (used by
132/// tests to skip live embedding work without triggering a download).
133pub fn active_model_cached() -> bool {
134    let Some(cache) = model_cache_dir() else {
135        return false;
136    };
137    let Ok(entries) = std::fs::read_dir(&cache) else {
138        return false;
139    };
140    entries.flatten().any(|e| {
141        e.file_name()
142            .to_string_lossy()
143            .contains(current_model().id())
144    })
145}
146
147fn embedder() -> Result<&'static Mutex<TextEmbedding>> {
148    if let Some(e) = EMBEDDER.get() {
149        return Ok(e);
150    }
151    let mut init = TextInitOptions::default();
152    init.model_name = current_model().fastembed();
153    init.show_download_progress = true;
154    init.cache_dir = model_cache_dir().unwrap_or_else(|| PathBuf::from(".fastembed_cache"));
155    let emb = TextEmbedding::try_new(init)
156        .context("init embedding model (first run downloads the model binary)")?;
157    // Race-safe: if another thread won, keep its instance.
158    let _ = EMBEDDER.set(Mutex::new(emb));
159    Ok(EMBEDDER.get().expect("embedder set"))
160}
161
162#[cfg(test)]
163mod tests {
164    use super::*;
165
166    #[test]
167    fn bge_small_is_the_default() {
168        std::env::remove_var("POWERSHELL_MCP_EMBED_MODEL");
169        assert_eq!(current_model(), Model::BgeSmall);
170        assert_eq!(Model::BgeSmall.id(), "bge-small-en-v1.5");
171        assert_eq!(Model::BgeSmall.dim(), 384);
172        assert!(!Model::BgeSmall.uses_prefixes());
173    }
174
175    #[test]
176    fn e5_models_use_prefixes() {
177        assert!(Model::E5Multilingual.uses_prefixes());
178        assert!(Model::E5Base.uses_prefixes());
179    }
180}