lattice-embed 0.15.0

SIMD-accelerated vector operations and embedding generation
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
use super::*;

#[test]
fn test_default_model() {
    let model = EmbeddingModel::default();
    assert_eq!(model, EmbeddingModel::BgeSmallEnV15);
}

#[test]
fn test_model_provenance_new() {
    let provenance = ModelProvenance::new(
        EmbeddingModel::BgeSmallEnV15,
        "BAAI/bge-small-en-v1.5".into(),
    );

    assert_eq!(provenance.model, EmbeddingModel::BgeSmallEnV15);
    assert_eq!(provenance.model_id, "BAAI/bge-small-en-v1.5");
    assert!(!provenance.hash.is_empty());
    assert_eq!(provenance.hash.len(), 64); // sha256 hex is 64 chars
    assert!(!provenance.loaded_at_iso.is_empty());
}

/// Pins the hash to the documented formula and a named digest, so an
/// algorithm swap (e.g. to another 32-byte digest) fails this test even
/// though it would still produce a 64-char hex string.
#[test]
fn test_model_provenance_hash_matches_documented_sha256_formula() {
    let provenance = ModelProvenance::new(
        EmbeddingModel::BgeSmallEnV15,
        "BAAI/bge-small-en-v1.5".into(),
    );

    let expected_input = format!(
        "{}:{}:{:?}",
        provenance.model_id, provenance.loaded_at_iso, provenance.model
    );
    let expected_hash = format!("{:x}", sha2::Sha256::digest(expected_input.as_bytes()));

    assert_eq!(provenance.hash, expected_hash);
}

#[test]
fn test_model_provenance_unique_hash() {
    let p1 = ModelProvenance::new(EmbeddingModel::BgeSmallEnV15, "model1".into());
    std::thread::sleep(std::time::Duration::from_millis(10)); // Ensure different timestamp
    let p2 = ModelProvenance::new(EmbeddingModel::BgeSmallEnV15, "model1".into());

    // Different timestamps should produce different hashes
    assert_ne!(p1.hash, p2.hash);
}

#[test]
fn test_model_provenance_dimensions() {
    let p1 = ModelProvenance::new(EmbeddingModel::BgeSmallEnV15, "small".into());
    assert_eq!(p1.dimensions(), 384);

    let p2 = ModelProvenance::new(EmbeddingModel::BgeBaseEnV15, "base".into());
    assert_eq!(p2.dimensions(), 768);

    let p3 = ModelProvenance::new(EmbeddingModel::BgeLargeEnV15, "large".into());
    assert_eq!(p3.dimensions(), 1024);
}

#[test]
fn test_model_provenance_matches_model() {
    let provenance = ModelProvenance::new(EmbeddingModel::BgeSmallEnV15, "test".into());

    assert!(provenance.matches_model(EmbeddingModel::BgeSmallEnV15));
    assert!(!provenance.matches_model(EmbeddingModel::BgeBaseEnV15));
    assert!(!provenance.matches_model(EmbeddingModel::BgeLargeEnV15));
}

#[test]
fn test_model_provenance_serialization() {
    let provenance = ModelProvenance::new(EmbeddingModel::BgeSmallEnV15, "test-model".into());

    let json = serde_json::to_string(&provenance).unwrap();
    // FP-037: EmbeddingModel has #[serde(rename_all = "snake_case")] so
    // BgeSmallEnV15 serializes as "bge_small_en_v15", not "BgeSmallEnV15".
    assert!(json.contains("bge_small_en_v15"), "json={json}");
    assert!(json.contains("test-model"));
    assert!(json.contains(&provenance.hash));

    let parsed: ModelProvenance = serde_json::from_str(&json).unwrap();
    assert_eq!(parsed.model, provenance.model);
    assert_eq!(parsed.model_id, provenance.model_id);
    assert_eq!(parsed.hash, provenance.hash);
}

#[test]
fn test_dimensions() {
    assert_eq!(EmbeddingModel::BgeSmallEnV15.dimensions(), 384);
    assert_eq!(EmbeddingModel::BgeBaseEnV15.dimensions(), 768);
    assert_eq!(EmbeddingModel::BgeLargeEnV15.dimensions(), 1024);
    assert_eq!(EmbeddingModel::Qwen3Embedding4B.dimensions(), 2560);
}

#[test]
fn test_model_config_native_dims() {
    assert_eq!(
        ModelConfig::new(EmbeddingModel::Qwen3Embedding4B).dimensions(),
        2560
    );
    assert_eq!(
        ModelConfig::new(EmbeddingModel::Qwen3Embedding0_6B).dimensions(),
        1024
    );
    assert_eq!(
        ModelConfig::new(EmbeddingModel::BgeSmallEnV15).dimensions(),
        384
    );
}

#[test]
fn test_model_config_configured_dim() {
    let cfg = ModelConfig::try_new(EmbeddingModel::Qwen3Embedding4B, Some(1024)).unwrap();
    assert_eq!(cfg.dimensions(), 1024);

    let cfg = ModelConfig::try_new(EmbeddingModel::Qwen3Embedding0_6B, Some(512)).unwrap();
    assert_eq!(cfg.dimensions(), 512);
}

#[test]
fn test_model_config_validation_below_min() {
    assert!(ModelConfig::try_new(EmbeddingModel::Qwen3Embedding4B, Some(31)).is_err());
    assert!(ModelConfig::try_new(EmbeddingModel::Qwen3Embedding4B, Some(0)).is_err());
}

#[test]
fn test_model_config_validation_above_native() {
    assert!(ModelConfig::try_new(EmbeddingModel::Qwen3Embedding4B, Some(2561)).is_err());
    assert!(ModelConfig::try_new(EmbeddingModel::Qwen3Embedding0_6B, Some(1025)).is_err());
}

#[test]
fn test_model_config_validation_non_mrl_model() {
    assert!(ModelConfig::try_new(EmbeddingModel::BgeSmallEnV15, Some(128)).is_err());
    assert!(ModelConfig::try_new(EmbeddingModel::BgeBaseEnV15, Some(512)).is_err());
}

#[test]
fn test_model_config_none_output_dim_ok_for_any_model() {
    assert!(ModelConfig::try_new(EmbeddingModel::BgeSmallEnV15, None).is_ok());
    assert!(ModelConfig::try_new(EmbeddingModel::Qwen3Embedding4B, None).is_ok());
}

#[test]
fn test_is_local() {
    assert!(EmbeddingModel::BgeSmallEnV15.is_local());
    assert!(EmbeddingModel::BgeBaseEnV15.is_local());
    assert!(EmbeddingModel::BgeLargeEnV15.is_local());
}

#[test]
fn test_display() {
    assert_eq!(
        EmbeddingModel::BgeSmallEnV15.to_string(),
        "bge-small-en-v1.5"
    );
    assert_eq!(EmbeddingModel::BgeBaseEnV15.to_string(), "bge-base-en-v1.5");
    assert_eq!(
        EmbeddingModel::BgeLargeEnV15.to_string(),
        "bge-large-en-v1.5"
    );
}

#[test]
fn test_serialization_roundtrip() {
    let model = EmbeddingModel::BgeSmallEnV15;
    let json = serde_json::to_string(&model).unwrap();
    let parsed: EmbeddingModel = serde_json::from_str(&json).unwrap();
    assert_eq!(model, parsed);
}

#[test]
fn test_max_input_tokens() {
    assert_eq!(EmbeddingModel::BgeSmallEnV15.max_input_tokens(), 512);
    assert_eq!(EmbeddingModel::BgeBaseEnV15.max_input_tokens(), 512);
    assert_eq!(EmbeddingModel::BgeLargeEnV15.max_input_tokens(), 512);
    assert_eq!(EmbeddingModel::Qwen3Embedding0_6B.max_input_tokens(), 2048);
    assert_eq!(EmbeddingModel::Qwen3Embedding4B.max_input_tokens(), 2048);
}

/// The table follows the limit the tokenizer applies when a Qwen3 Embedding directory
/// is loaded. The directory is synthetic, with context lengths well above the cap, so no
/// checkpoint is needed; it checks the table against the cap, not a real checkpoint's files.
#[cfg(feature = "native")]
#[test]
fn test_qwen3_max_input_tokens_matches_loaded_tokenizer_limit() {
    use lattice_tokenizer::load_tokenizer;

    let dir = tempfile::tempdir().expect("tempdir");
    let write = |name: &str, body: &str| {
        std::fs::write(dir.path().join(name), body).expect("write fixture file");
    };
    write("vocab.json", r#"{"a": 0, "<|endoftext|>": 1}"#);
    write("merges.txt", "#version: 0.2\n");
    write("config.json", r#"{"max_position_embeddings": 32768}"#);
    write("tokenizer_config.json", r#"{"model_max_length": 131072}"#);

    let tokenizer = load_tokenizer(dir.path()).expect("tokenizer loads");
    for model in [
        EmbeddingModel::Qwen3Embedding0_6B,
        EmbeddingModel::Qwen3Embedding4B,
    ] {
        assert_eq!(
            tokenizer.max_seq_len(),
            model.max_input_tokens(),
            "{model:?}: max_input_tokens() must equal the tokenizer's sequence limit"
        );
    }
}

#[test]
fn test_from_str_display_names() {
    assert_eq!(
        "bge-small-en-v1.5".parse::<EmbeddingModel>().unwrap(),
        EmbeddingModel::BgeSmallEnV15
    );
    assert_eq!(
        "bge-base-en-v1.5".parse::<EmbeddingModel>().unwrap(),
        EmbeddingModel::BgeBaseEnV15
    );
    assert_eq!(
        "bge-large-en-v1.5".parse::<EmbeddingModel>().unwrap(),
        EmbeddingModel::BgeLargeEnV15
    );
}

#[test]
fn test_from_str_short_names() {
    assert_eq!(
        "small".parse::<EmbeddingModel>().unwrap(),
        EmbeddingModel::BgeSmallEnV15
    );
    assert_eq!(
        "bge-base".parse::<EmbeddingModel>().unwrap(),
        EmbeddingModel::BgeBaseEnV15
    );
    assert_eq!(
        "LARGE".parse::<EmbeddingModel>().unwrap(), // case insensitive
        EmbeddingModel::BgeLargeEnV15
    );
}

#[test]
fn test_from_str_huggingface_ids() {
    assert_eq!(
        "BAAI/bge-small-en-v1.5".parse::<EmbeddingModel>().unwrap(),
        EmbeddingModel::BgeSmallEnV15
    );
}

#[test]
fn test_from_str_invalid() {
    let result = "unknown-model".parse::<EmbeddingModel>();
    assert!(result.is_err());
    assert!(result.unwrap_err().contains("unknown embedding model"));
}

// -------------------------------------------------------------------------
// bert_pooling() routing tests (P1-E3) — require `native` feature
// -------------------------------------------------------------------------

/// BGE small/base/large must use CLS pooling per their HF model cards.
#[cfg(feature = "native")]
#[test]
fn test_bge_models_use_cls_pooling() {
    use lattice_compute::pool::BertPooling;

    assert_eq!(
        EmbeddingModel::BgeSmallEnV15.bert_pooling(),
        Some(BertPooling::CLS),
        "BgeSmallEnV15 must use CLS pooling"
    );
    assert_eq!(
        EmbeddingModel::BgeBaseEnV15.bert_pooling(),
        Some(BertPooling::CLS),
        "BgeBaseEnV15 must use CLS pooling"
    );
    assert_eq!(
        EmbeddingModel::BgeLargeEnV15.bert_pooling(),
        Some(BertPooling::CLS),
        "BgeLargeEnV15 must use CLS pooling"
    );
}

/// E5 models must use mean pooling per their HF model cards.
#[cfg(feature = "native")]
#[test]
fn test_e5_models_use_mean_pooling() {
    use lattice_compute::pool::BertPooling;

    assert_eq!(
        EmbeddingModel::MultilingualE5Small.bert_pooling(),
        Some(BertPooling::Mean),
        "MultilingualE5Small must use mean pooling"
    );
    assert_eq!(
        EmbeddingModel::MultilingualE5Base.bert_pooling(),
        Some(BertPooling::Mean),
        "MultilingualE5Base must use mean pooling"
    );
}

/// MiniLM models must use mean pooling per sentence-transformers convention.
#[cfg(feature = "native")]
#[test]
fn test_minilm_models_use_mean_pooling() {
    use lattice_compute::pool::BertPooling;

    assert_eq!(
        EmbeddingModel::AllMiniLmL6V2.bert_pooling(),
        Some(BertPooling::Mean),
        "AllMiniLmL6V2 must use mean pooling"
    );
    assert_eq!(
        EmbeddingModel::ParaphraseMultilingualMiniLmL12V2.bert_pooling(),
        Some(BertPooling::Mean),
        "ParaphraseMultilingualMiniLmL12V2 must use mean pooling"
    );
}

/// Qwen and remote models return None — they have separate pooling paths.
#[cfg(feature = "native")]
#[test]
fn test_non_bert_models_return_none_pooling() {
    assert_eq!(
        EmbeddingModel::Qwen3Embedding0_6B.bert_pooling(),
        None,
        "Qwen model must return None for bert_pooling()"
    );
    assert_eq!(
        EmbeddingModel::Qwen3Embedding4B.bert_pooling(),
        None,
        "Qwen model must return None for bert_pooling()"
    );
    assert_eq!(
        EmbeddingModel::TextEmbedding3Small.bert_pooling(),
        None,
        "Remote model must return None for bert_pooling()"
    );
}

/// BGE and E5 use DIFFERENT pooling strategies — this is the key correctness distinction.
#[cfg(feature = "native")]
#[test]
fn test_bge_and_e5_use_different_pooling() {
    assert_ne!(
        EmbeddingModel::BgeSmallEnV15.bert_pooling(),
        EmbeddingModel::MultilingualE5Small.bert_pooling(),
        "BGE and E5 must use different pooling strategies"
    );
}

/// Guards `lattice_compute::pool::default_bert_pooling_for_model_name`
/// (the served-directory-name lookup `lattice_serve` uses) against
/// drifting from `EmbeddingModel::bert_pooling` (this table). The
/// expectation comes from calling `bert_pooling()` itself, never from
/// retyping its rule, so a wrong mirror cannot agree with a wrong
/// expectation.
///
/// This lives in `lattice-embed`, not `lattice-compute`, so both sides
/// of the comparison are the same compiled unit: `lattice-embed` already
/// depends on `lattice-compute` (this crate's own `[dependencies]`,
/// gated by the `native` feature), so `EmbeddingModel::bert_pooling()`'s
/// return type and `default_bert_pooling_for_model_name`'s return type
/// are literally the same `lattice_compute::pool::BertPooling`, comparable
/// with `==` directly -- no `format!("{:?}")` string workaround needed.
///
/// Enumeration: `EmbeddingModel` has no `EnumIter`/`VariantArray`/
/// `ALL_MODELS` constant (checked via `grep -n
/// "strum\|EnumIter\|VariantArray\|ALL_MODELS" crates/embed/src/model.rs`,
/// no hits), so `variants` below is still a hand-transcribed list of all
/// 11 current variants. But `#[non_exhaustive]` only forces a wildcard
/// arm in matches written *outside* the declaring crate -- this test
/// lives inside `lattice-embed` itself, where `EmbeddingModel` is
/// declared, so a wildcard-free match over it type-checks here. The
/// `assert_variants_exhaustively_covered` match below has no wildcard
/// arm; it is checked against the enum's full current variant set
/// regardless of which values are actually passed to it, so a variant
/// added to `EmbeddingModel` without a matching arm here is a compile
/// error ("non-exhaustive patterns"), not a silent gap in `variants`.
#[cfg(feature = "native")]
#[test]
fn default_bert_pooling_for_model_name_matches_embedding_model_bert_pooling_table() {
    use lattice_compute::pool::default_bert_pooling_for_model_name;

    fn assert_variants_exhaustively_covered(m: &EmbeddingModel) {
        match m {
            EmbeddingModel::BgeSmallEnV15
            | EmbeddingModel::BgeBaseEnV15
            | EmbeddingModel::BgeLargeEnV15
            | EmbeddingModel::MultilingualE5Small
            | EmbeddingModel::MultilingualE5Base
            | EmbeddingModel::AllMiniLmL6V2
            | EmbeddingModel::ParaphraseMultilingualMiniLmL12V2
            | EmbeddingModel::Qwen3Embedding0_6B
            | EmbeddingModel::Qwen3Embedding4B
            | EmbeddingModel::EmbeddingGemma2
            | EmbeddingModel::TextEmbedding3Small => {}
        }
    }

    let variants = [
        EmbeddingModel::BgeSmallEnV15,
        EmbeddingModel::BgeBaseEnV15,
        EmbeddingModel::BgeLargeEnV15,
        EmbeddingModel::MultilingualE5Small,
        EmbeddingModel::MultilingualE5Base,
        EmbeddingModel::AllMiniLmL6V2,
        EmbeddingModel::ParaphraseMultilingualMiniLmL12V2,
        EmbeddingModel::Qwen3Embedding0_6B,
        EmbeddingModel::Qwen3Embedding4B,
        EmbeddingModel::EmbeddingGemma2,
        EmbeddingModel::TextEmbedding3Small,
    ];

    let mut bert_family_checked = 0usize;
    for variant in variants {
        assert_variants_exhaustively_covered(&variant);

        let Some(expected) = variant.bert_pooling() else {
            continue;
        };
        bert_family_checked += 1;
        // Same shape of value production reaches
        // `default_bert_pooling_for_model_name` in production:
        // `lattice_serve` passes it the served directory's last path
        // component (`resolve_model_dir(...).file_name()`), not the
        // model's full HF id. Simulate that here by taking the last
        // path component of the model's own `model_id()`.
        let dir_name = std::path::Path::new(variant.model_id())
            .file_name()
            .and_then(|n| n.to_str())
            .expect("model_id() yields a valid path component");
        let actual = default_bert_pooling_for_model_name(dir_name);
        assert_eq!(
            actual, expected,
            "pooling mismatch for {variant:?} (derived dir name {dir_name:?})"
        );
    }
    // BGE small/base/large + E5 small/base + MiniLM + paraphrase-MiniLM:
    // the 7 variants whose `bert_pooling()` returns `Some(_)` as of this
    // writing. Qwen3 x2, EmbeddingGemma2 and TextEmbedding3Small return `None` and are
    // skipped above. This catches a variant's `bert_pooling()` gate
    // moving, but -- per the enumeration note above -- a wholly new
    // variant absent from `variants` only surfaces as the compile error
    // from `assert_variants_exhaustively_covered`, not from this count.
    assert_eq!(
        bert_family_checked, 7,
        "EmbeddingModel's BERT-family (Some(_) from bert_pooling()) variant count changed"
    );
}

#[test]
fn test_embeddinggemma2_registry_entry() {
    let m = EmbeddingModel::EmbeddingGemma2;
    assert_eq!(m.native_dimensions(), 768);
    assert!(m.is_local() && !m.is_remote());
    assert_eq!(m.max_input_tokens(), 8192);
    assert_eq!(m.query_instruction(), Some("task: search result | query: "));
    assert_eq!(m.document_instruction(), Some("title: none | text: "));
    assert_eq!(m.model_id(), "google/embeddinggemma-2");
    assert!(m.supports_output_dim());
    for name in [
        "embeddinggemma-2",
        "EmbeddingGemma2",
        "embedding_gemma2",
        "google/embeddinggemma-2",
    ] {
        assert_eq!(name.parse::<EmbeddingModel>(), Ok(m), "{name}");
    }
    assert_eq!(m.to_string().parse::<EmbeddingModel>(), Ok(m));
    let json = serde_json::to_string(&m).unwrap();
    assert_eq!(json, "\"embedding_gemma2\"");
    assert_eq!(serde_json::from_str::<EmbeddingModel>(&json).unwrap(), m);
    assert_eq!(
        serde_json::from_str::<EmbeddingModel>("\"EmbeddingGemma2\"").unwrap(),
        m
    );

    for width in [768, 512, 256, 128] {
        let config = ModelConfig::try_new(m, Some(width)).unwrap();
        assert_eq!(config.dimensions(), width);
    }
    assert!(ModelConfig::try_new(m, Some(769)).is_err());
    assert!(ModelConfig::try_new(m, Some(MIN_MRL_OUTPUT_DIM - 1)).is_err());
}