Crate lattice_embed

Expand description

Stability tier: Unstable

The SIMD dispatch layer (simd/) and model-loading API are actively evolving. Platform consumers should use this crate via lattice-engine, not directly. The 21 unsafe blocks are gated SIMD intrinsic calls (AVX512/AVX2/NEON); the 1 dead_code_allows retains a superseded dot-product fallback for reference. See foundation/STABILITY.md for the full policy.

§lattice-embed

Vector embedding generation with SIMD-accelerated operations for the lattice-runtime substrate.

This crate provides embedding generation services that convert text into high-dimensional vector representations suitable for semantic search and similarity matching.

§Features

Native Embeddings: Generate embeddings locally using pure Rust inference (default)
BGE Models: Support for BGE family of models (small/base/large)
Async API: Full async/await support with tokio
SIMD Acceleration: AVX2/NEON optimized vector operations

§Quick Start

use lattice_embed::{EmbeddingService, EmbeddingModel, NativeEmbeddingService};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let service = NativeEmbeddingService::default();

    let embedding = service.embed_one(
        "The quick brown fox jumps over the lazy dog",
        EmbeddingModel::default(),
    ).await?;

    println!("Embedding dimension: {}", embedding.len());
    // Output: Embedding dimension: 384

    Ok(())
}

§Batch Processing

use lattice_embed::{EmbeddingService, EmbeddingModel, NativeEmbeddingService};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let service = NativeEmbeddingService::default();

    let texts = vec![
        "First document".to_string(),
        "Second document".to_string(),
        "Third document".to_string(),
    ];

    let embeddings = service.embed(&texts, EmbeddingModel::BgeSmallEnV15).await?;
    assert_eq!(embeddings.len(), 3);

    Ok(())
}

§Available Models

Model	Dimensions	Use Case
`BgeSmallEnV15`	384	Fast, general purpose (default)
`BgeBaseEnV15`	768	Balanced quality/speed
`BgeLargeEnV15`	1024	Highest quality

Re-exports§

pub use simd::SimdConfig;
pub use simd::simd_config;

Modules§

backfill: Backfill coordinator for embedding migration.
migration: Migration module: state machine for embedding model migration.
simd: SIMD-accelerated vector operations for embedding similarity.
types: ML-domain vector types local to lattice-embed.
utils: Utility functions for vector operations.

Structs§

CacheStats: Unstable: metrics fields may be added/removed as monitoring needs evolve.
CachedEmbeddingService: Unstable: caching strategy and constructor API may change; foundation-internal use only.
EmbeddingCache: Unstable: internal LRU caching mechanism; shard count and eviction policy may change.
ModelConfig: Runtime configuration pairing a model with an optional MRL truncation dimension.
ModelProvenance: Stable: external consumers may depend on this; breaking changes require a SemVer bump.
NativeEmbeddingService: Unstable: model-loading API still evolving; signature may change as lattice-inference matures.
ShardStats: Unstable: shard count is an internal implementation detail; this struct may be removed.

Enums§

EmbedError: Stable: external consumers may depend on this; breaking changes require a SemVer bump.
EmbeddingModel: Stable: external consumers may depend on this; breaking changes require a SemVer bump.

Constants§

DEFAULT_CACHE_CAPACITY: Unstable: tuning constant; value may change as memory models evolve.
DEFAULT_MAX_BATCH_SIZE: Stable: default maximum batch size to prevent OOM.
MAX_TEXT_CHARS: Stable: maximum allowed text length in characters.
MIN_MRL_OUTPUT_DIM: Minimum allowed MRL output dimension.

Traits§

EmbeddingService: Stable: external consumers may depend on this; breaking changes require a SemVer bump.

Type Aliases§

Result: Stable: result type alias for embedding operations.