frankensearch

Two-tier hybrid search for Rust: sub-millisecond initial results, quality-refined rankings in ~150ms.

Overview

frankensearch is the main library crate that re-exports and unifies all workspace sub-crates into a single, ergonomic API. It combines lexical (native Quill or the explicit Tantivy oracle) and semantic (vector cosine similarity) search via Reciprocal Rank Fusion (RRF), with a two-tier progressive embedding model that delivers results in two phases:

1. Phase 1 (Initial): Fast embedder (potion-128M, 256d, ~0.57ms) produces results immediately via brute-force vector search + optional BM25 fusion.
2. Phase 2 (Refined): Quality embedder (MiniLM-L6-v2, 384d, ~128ms) re-scores the top candidates for higher relevance.

Consumers receive results progressively via SearchPhase callbacks, so UIs can display fast results while quality refinement runs in the background.

 Query --+-> Fast Embed (256d) -> Vector Search --+-> RRF Fusion -> Phase 1
         |                                        |
         +-> Quill / Tantivy-oracle BM25 ---------+
                                                        |
                                              Quality Embed (384d)
                                                        |
                                                   Score Blend
                                                        |
                                                  Phase 2 Results

Key Types

• IndexBuilder / IndexBuildStats - build a search index from documents
• TwoTierSearcher - progressive two-phase search orchestrator
• TwoTierConfig / TwoTierMetrics - search configuration and per-search diagnostics
• SearchPhase - progressive result delivery (Initial / Refined / RefinementFailed)
• EmbedderStack - fast + optional quality embedder pair with auto-detection
• TwoTierIndex / VectorIndex - two-tier and low-level vector index types
• ScoredResult / FusedHit / VectorHit - result types with provenance tracking
• FederatedSearcher / FederatedFusion - multi-index federated search
• Embedder / LexicalRead + LexicalWrite / Reranker - core traits for pluggable backends
• QueryClass - automatic query classification
• Canonicalizer / DocumentFingerprint - text normalization and change detection

Feature Flags

Recommended Combinations

• Development/testing: default (hash only, no downloads)
• Production semantic: semantic + download
• Persistent hybrid search: persistent
• Maximum durability: durable or full

Usage

use std::path::Path;
use std::sync::Arc;
use frankensearch::prelude::*;
use frankensearch::{EmbedderStack, IndexBuilder, TwoTierIndex};

asupersync::test_utils::run_test_with_cx(|cx| async move {
    let stack = EmbedderStack::auto_detect_semantic_with(Some(Path::new("./models")))
        .expect("production search needs a verified semantic embedder");

    IndexBuilder::new("./my_index")
        .with_embedder_stack(stack)
        .add_document("doc-1", "Rust ownership and borrowing")
        .add_document("doc-2", "Python garbage collection")
        .build(&cx)
        .await
        .expect("build index");

    let stack = EmbedderStack::auto_detect_semantic_with(Some(Path::new("./models")))
        .expect("search must use the same semantic family the index was built with");
    let index = Arc::new(
        TwoTierIndex::open(Path::new("./my_index"), TwoTierConfig::default()).unwrap(),
    );
    let mut searcher = TwoTierSearcher::new(index, stack.fast_arc(), TwoTierConfig::default());
    if let Some(quality) = stack.quality_arc() {
        searcher = searcher.with_quality_embedder(quality);
    }
    let (results, _metrics) = searcher
        .search_collect(&cx, "memory management", 10)
        .await
        .expect("search");

    for result in &results {
        println!("{}: {:.4}", result.doc_id, result.score);
    }

    #[cfg(feature = "quill")]
    {
        let lexical = frankensearch::QuillIndex::open(
            &cx,
            "./my_index/lexical",
            frankensearch::QuillConfig::default(),
        )
        .await
        .expect("open Quill lexical index");
        let lexical_hits = lexical
            .search_results(&cx, "ownership", 10)
            .expect("search Quill lexical index");
        assert!(!lexical_hits.is_empty());
    }
});

Async Runtime

frankensearch uses asupersync exclusively -- not tokio. All async methods take &Cx (capability context) as their first parameter. The Cx is provided by the consumer's asupersync runtime; frankensearch never creates its own runtime.

Performance

Measured on a single core (no GPU), 10K document corpus:

Dependency Graph Position

This is the top-level library crate that unifies the workspace:

frankensearch-core       (always)
frankensearch-embed      (always)
frankensearch-index      (always)
frankensearch-fusion     (always)
frankensearch-lexical    (feature: lexical)
frankensearch-quill      (feature: quill)
frankensearch-rerank     (feature: rerank)
frankensearch-storage    (feature: storage)
frankensearch-durability (feature: durability)

License

MIT