Skip to main content

lockdocs_core/
semantic.rs

1//! Product policy for the shared embedding engine: the retrieval model,
2//! identifier-aware inputs, lockdocs' opt-out and existing cache location.
3
4use anyhow::Result;
5use mcp_kit::embed::{self, Model, Tokenization, POTION_RETRIEVAL_32M};
6use std::path::PathBuf;
7use std::sync::{Arc, OnceLock, RwLock};
8
9pub use mcp_kit::embed::{cosine, quantize, QueryModel, Vec8};
10pub const MODEL_ID: &str = POTION_RETRIEVAL_32M.id;
11
12fn model_dir() -> PathBuf {
13    crate::cache::dir().join("models").join(MODEL_ID)
14}
15
16/// Embeddings are on unless `LOCKDOCS_EMBED=0` (or false/off).
17pub fn enabled() -> bool {
18    !matches!(std::env::var("LOCKDOCS_EMBED").as_deref(), Ok("0") | Ok("false") | Ok("off"))
19}
20
21pub fn installed() -> bool {
22    embed::installed_at(&model_dir())
23}
24
25/// A cheap embedder for query text, without loading the weight table.
26pub fn query_model() -> Option<&'static QueryModel> {
27    static QM: OnceLock<Option<QueryModel>> = OnceLock::new();
28    QM.get_or_init(|| if enabled() && installed() { QueryModel::open(&model_dir()) } else { None })
29        .as_ref()
30}
31
32/// Embeddings are on and the model is installed (nothing is loaded).
33pub fn available() -> bool {
34    enabled() && installed()
35}
36
37static MODEL: OnceLock<RwLock<Option<Arc<Model>>>> = OnceLock::new();
38
39/// Load existing model.q8/vocab.txt directly. The shared input policy keeps
40/// cached entry vectors and new query vectors in the same embedding space.
41pub fn get() -> Option<Arc<Model>> {
42    if !enabled() {
43        return None;
44    }
45    let cell = MODEL.get_or_init(|| RwLock::new(None));
46    if let Some(model) = cell.read().unwrap().as_ref() {
47        return Some(model.clone());
48    }
49    if !installed() {
50        return None;
51    }
52    let model = Arc::new(Model::load_dir(&model_dir()).ok()?.with_tokenization(Tokenization::Identifiers));
53    *cell.write().unwrap() = Some(model.clone());
54    Some(model)
55}
56
57pub fn ensure() -> Result<()> {
58    let base = std::env::var("LOCKDOCS_MODEL_URL")
59        .unwrap_or_else(|_| format!("https://huggingface.co/{}/resolve/{}", POTION_RETRIEVAL_32M.repo, POTION_RETRIEVAL_32M.revision));
60    embed::ensure_at(
61        &POTION_RETRIEVAL_32M,
62        &model_dir(),
63        "lockdocs",
64        "Set LOCKDOCS_EMBED=0 to stay keyword-only.",
65        Some(&base),
66    )
67}
68
69#[cfg(test)]
70mod tests {
71    use super::*;
72
73    #[test]
74    fn persisted_entry_vectors_keep_their_postcard_layout() {
75        #[derive(serde::Serialize)]
76        struct PreviousVec8 {
77            q: Vec<i8>,
78            s: f32,
79        }
80        let previous = PreviousVec8 {
81            q: vec![-127, 0, 127],
82            s: 0.01,
83        };
84        let bytes = postcard::to_stdvec(&previous).unwrap();
85        let current: Vec8 = postcard::from_bytes(&bytes).unwrap();
86        assert_eq!(current.q, previous.q);
87        assert_eq!(current.s, previous.s);
88        assert_eq!(postcard::to_stdvec(&current).unwrap(), bytes);
89    }
90}