frankensearch_embed/
lib.rs

1//! Embedder implementations for the frankensearch hybrid search library.
2//!
3//! Provides three tiers of text embedding:
4//! - **Hash** (`hash` feature, default): FNV-1a hash embedder, zero dependencies, always available.
5//! - **`Model2Vec`** (`model2vec` feature): potion-128M static embedder, fast tier (~0.57ms).
6//! - **`FastEmbed`** (`fastembed` feature): MiniLM-L6-v2 ONNX embedder, quality tier (~128ms).
7//!
8//! The `EmbedderStack` auto-detection probes for available models and configures
9//! the best fast+quality pair automatically.
10
11pub mod auto_detect;
12pub mod batch_coalescer;
13#[cfg(feature = "bundled-default-models")]
14pub mod bundled_default_models;
15pub mod cached_embedder;
16pub mod model_cache;
17pub mod model_manifest;
18pub mod model_registry;
19pub use auto_detect::{
20    DimReduceEmbedder, EmbedderStack, ModelAvailabilityDiagnostic, ModelStatus, TwoTierAvailability,
21};
22pub use batch_coalescer::{
23    BatchCoalescer, CoalescedBatch, CoalescerConfig, CoalescerMetrics, Priority,
24};
25#[cfg(feature = "bundled-default-models")]
26pub use bundled_default_models::{EmbeddedModelInstallSummary, ensure_default_semantic_models};
27
28// When bundled-default-models is disabled (lite build), provide a no-op
29// `ensure_default_semantic_models` so downstream crates compile without
30// feature-gating every call site.
31#[cfg(not(feature = "bundled-default-models"))]
32pub use lite_fallback::{EmbeddedModelInstallSummary, ensure_default_semantic_models};
33
34#[cfg(not(feature = "bundled-default-models"))]
35mod lite_fallback {
36    use std::path::{Path, PathBuf};
37
38    use frankensearch_core::error::SearchResult;
39
40    /// Summary returned by the no-op lite-build materialization.
41    #[derive(Debug, Clone, PartialEq, Eq)]
42    pub struct EmbeddedModelInstallSummary {
43        /// Effective model root (inherited from caller or platform default).
44        pub model_root: PathBuf,
45        /// Always 0 in the lite build -- no embedded models to write.
46        pub models_written: usize,
47        /// Always 0 in the lite build.
48        pub bytes_written: u64,
49    }
50
51    /// No-op: lite builds have no embedded models to materialize.
52    ///
53    /// Returns a summary with zero writes. Callers should check for models
54    /// on disk at the standard location (`~/.local/share/frankensearch/models/`)
55    /// and prompt the user to run `fsfs download-models` if they are missing.
56    pub fn ensure_default_semantic_models(
57        model_root: Option<&Path>,
58    ) -> SearchResult<EmbeddedModelInstallSummary> {
59        let root = model_root.map(|p| p.to_path_buf()).unwrap_or_else(|| {
60            crate::model_registry::ensure_model_storage_layout_checked()
61                .unwrap_or_else(|_| PathBuf::from("models"))
62        });
63        Ok(EmbeddedModelInstallSummary {
64            model_root: root,
65            models_written: 0,
66            bytes_written: 0,
67        })
68    }
69}
70pub use cached_embedder::{CacheStats, CachedEmbedder};
71pub use model_cache::{
72    ENV_DATA_DIR, ENV_MODEL_DIR, KnownModel, MODEL_CACHE_LAYOUT_VERSION, ModelCacheLayout,
73    ModelDirEntry, ensure_cache_layout, ensure_default_cache, is_model_installed, known_models,
74    model_file_path, resolve_cache_root,
75};
76pub use model_manifest::{
77    ConsentSource, DOWNLOAD_CONSENT_ENV, DownloadConsent, MANIFEST_SCHEMA_VERSION, ModelFile,
78    ModelLifecycle, ModelManifest, ModelManifestCatalog, ModelState, ModelTier,
79    PLACEHOLDER_VERIFY_AFTER_DOWNLOAD, VerificationMarker, is_verification_cached,
80    resolve_download_consent, verify_dir_cached, verify_file_sha256, write_verification_marker,
81};
82pub use model_registry::{
83    BAKEOFF_CUTOFF_DATE, EmbedderRegistry, RegisteredEmbedder, RegisteredReranker,
84    registered_embedders, registered_rerankers,
85};
86
87#[cfg(feature = "hash")]
88pub mod hash_embedder;
89
90#[cfg(feature = "hash")]
91pub use hash_embedder::{HashAlgorithm, HashEmbedder};
92
93#[cfg(feature = "model2vec")]
94pub mod model2vec_embedder;
95
96#[cfg(feature = "model2vec")]
97pub use model2vec_embedder::{Model2VecEmbedder, find_model_dir};
98
99#[cfg(feature = "fastembed")]
100pub mod fastembed_embedder;
101
102#[cfg(feature = "fastembed")]
103pub use fastembed_embedder::{FastEmbedEmbedder, OnnxEmbedderConfig};
104
105#[cfg(feature = "download")]
106pub mod model_download;
107
108#[cfg(feature = "download")]
109pub use model_download::{DownloadConfig, DownloadProgress, ModelDownloader};
110
111#[cfg(feature = "api")]
112pub mod api_provider;
113
114#[cfg(feature = "api")]
115pub mod api_embedder;
116
117#[cfg(feature = "api")]
118pub use api_embedder::ApiEmbedder;
119#[cfg(feature = "api")]
120pub use api_provider::{ApiProvider, GeminiProvider, OpenAiProvider};
frankensearch_embed/lib.rs

frankensearch_embed/
lib.rs
