Frankensearch Integration For Rust Projects

Frankensearch Integration for Rust Projects

The Cardinal Rule: Use frankensearch's built-in TwoTierSearcher for hybrid search. Do NOT roll your own RRF fusion, score blending, or progressive search orchestration. Every project that built ad-hoc search eventually ripped it out and replaced it with frankensearch's canonical implementation. Learn from their pain.

Quick Assessment: Where Are You?

1. NO SEARCH YET          → Phase 1: Fresh Integration (fastest path)
2. AD-HOC SEARCH EXISTS   → Phase 2: Migration (replace custom with canonical)
3. INTEGRATION STALLED    → Phase 3: Diagnosis & Repair (unstick the build)
4. WORKS BUT SUBOPTIMAL   → Phase 4: Optimization & Audit (use higher abstractions)

Pick your phase and follow it. Each phase is self-contained.

Phase 1: Fresh Integration (Green-Field)

Step 1: Add Dependencies

# Cargo.toml — choose the right feature set
[dependencies]
frankensearch = { path = "../frankensearch/frankensearch", features = ["hybrid"] }
# Or from git:
# frankensearch = { git = "https://github.com/Dicklesworthstone/frankensearch", features = ["hybrid"] }

Feature Flag Decision Table:

CRITICAL: asupersync Version Alignment

frankensearch uses asupersync (NOT tokio). If your project also depends on asupersync, you MUST ensure both use the same crate instance. Rust treats crates from different sources as different types — Cx from crates.io != Cx from git.

# If frankensearch uses path dep to asupersync, your project must too:
asupersync = { path = "../asupersync" }

# OR force alignment with [patch]:
[patch."https://github.com/Dicklesworthstone/frankensearch.git"]
asupersync = { path = "../asupersync" }

If your project uses tokio: You need sync-to-async bridge adapters. See BRIDGE-PATTERNS.md.

Step 2: Build the Index

use std::sync::Arc;
use frankensearch::{EmbedderStack, IndexBuilder, TwoTierConfig};

// Auto-detect available models (potion-128M fast + MiniLM quality)
let stack = EmbedderStack::auto_detect()?;

// Build index from your documents
let stats = IndexBuilder::new("./my_index")
    .with_embedder_stack(stack)
    .add_document("doc-1", "Document content here")
    .add_document("doc-2", "More content here")
    .build(&cx)
    .await?;

println!("Indexed {} docs, quality tier: {}", stats.doc_count, stats.has_quality_index);

Step 3: Create the Searcher

use frankensearch::{TwoTierIndex, TwoTierSearcher, TwoTierConfig, EmbedderStack};

let config = TwoTierConfig::default().with_env_overrides();
let index = Arc::new(TwoTierIndex::open("./my_index", config.clone())?);
let stack = EmbedderStack::auto_detect()?;

let searcher = TwoTierSearcher::new(index, stack.fast_arc(), config)
    .with_quality_embedder(stack.quality_arc().unwrap());

// Optional: add lexical backend for hybrid search
#[cfg(feature = "lexical")]
{
    let tantivy = Arc::new(TantivyIndex::open_or_create("./my_index/tantivy")?);
    searcher = searcher.with_lexical(tantivy);
}

Step 4: Execute Search

// Simple: collect all results
let (results, metrics) = searcher
    .search_collect(&cx, "my query", 10)
    .await?;

for result in &results {
    println!("{}: {:.3} ({})", result.doc_id, result.score, result.source);
}
println!("Phase 1: {:.1}ms, Phase 2: {:.1}ms", metrics.phase1_total_ms, metrics.phase2_total_ms);

// Progressive: get fast results first, then refined
let metrics = searcher.search(&cx, "my query", 10,
    |doc_id| load_text_from_db(doc_id),  // text callback for reranking
    |phase| match phase {
        SearchPhase::Initial { results, latency, .. } => {
            // Show these immediately (~15ms)
            display_results(&results);
        }
        SearchPhase::Refined { results, rank_changes, .. } => {
            // Update with better ranking (~150ms)
            display_results(&results);
        }
        SearchPhase::RefinementFailed { initial_results, error, .. } => {
            // Graceful degradation: keep initial results
            log::warn!("Refinement failed: {error}, keeping initial results");
        }
    }
).await?;

Step 5: Map Document IDs

frankensearch uses String doc IDs. Your domain model likely has structured IDs. Create a thin mapping layer:

// DO: Simple string encoding
fn to_fs_doc_id(msg_id: i64) -> String { msg_id.to_string() }
fn from_fs_doc_id(id: &str) -> Option<i64> { id.parse().ok() }

// DO: Composite key for multi-type documents
fn to_fs_doc_id(kind: DocKind, id: u64) -> String {
    format!("{}\x1f{id}", kind.prefix())  // Use unit separator
}
fn from_fs_doc_id(id: &str) -> Option<(DocKind, u64)> {
    let (prefix, num) = id.split_once('\x1f')?;
    Some((DocKind::from_prefix(prefix)?, num.parse().ok()?))
}

// DON'T: Multiple incompatible ID schemes in the same project
// DON'T: Pipe-delimited strings with 8+ fields (fragile parsing)

Phase 2: Migration (Replace Ad-Hoc Search)

The Migration Anti-Pattern Hall of Shame

These are real mistakes from three production integrations. Every one caused bugs.

Migration Strategy: Feature-Gated Cutover

Proven approach from xf (573 lines deleted, zero regressions):

1. Add frankensearch deps alongside existing code (no removal yet)
2. Create cfg(feature = "frankensearch-migration") gates around new paths
3. Build migration parity tests — run both old and new paths, compare results
4. Validate parity — scores within epsilon, same result sets, same ordering
5. Cut over — remove all cfg gates and legacy code in one commit
6. Verify — cargo test, clippy, UBS scan on the cleanup commit

// During migration: run both paths and compare
#[cfg(feature = "frankensearch-migration")]
let fs_results = frankensearch_fusion::rrf_fuse(&lexical_hits, &semantic_hits, &config);

#[cfg(not(feature = "frankensearch-migration"))]
let fs_results = legacy_rrf_fuse(&lexical_hits, &semantic_hits);

// Parity check (test only):
#[cfg(all(feature = "frankensearch-migration", test))]
assert_results_equivalent(&fs_results, &legacy_results, 1e-6);

What to Replace (Priority Order)

What to Keep (Don't Over-Migrate)

• Domain-specific document types and ID mapping
• Application-level search filters (implement SearchFilter trait)
• UI/presentation layer for search results
• Custom text preprocessing before indexing

Phase 3: Diagnosis & Repair (Stalled Integration)

Diagnostic Checklist

Run through this in order. Stop when you find the root cause.

1. Does it compile?

CARGO_TARGET_DIR=target_check cargo check --workspace --all-targets 2>&1 | head -50

Common compilation failures:

• "type mismatch" on Cx: asupersync version conflict. See BRIDGE-PATTERNS.md § Version Alignment.
• "cannot find type InMemoryTwoTierIndex": frankensearch rev is stale. Update git rev or switch to path dep.
• "unresolved import frankensearch::lexical": Missing lexical feature flag in Cargo.toml.
• "missing field explanation": frankensearch added a field to ScoredResult. Add explanation: None to all bridge constructors.

2. Does the index build?

let diag = EmbedderStack::auto_detect()?.diagnose();
println!("{:#?}", diag);
// Check: diag.availability, diag.fast_status, diag.quality_status

Common index failures:

• Model not found: Set FRANKENSEARCH_MODEL_DIR to a writable path with models.
• Quality tier unavailable: This is OK — search works with fast tier only.
• Index directory permissions: Ensure write access to the FSVI output directory.

3. Does search return results?

let (results, metrics) = searcher.search_collect(&cx, "test query", 10).await?;
println!("Results: {}, Skip: {:?}", results.len(), metrics.skip_reason);

Common search failures:

• Zero results, no error: Index is empty or query doesn't match. Check metrics.phase1_vectors_searched.
• skip_reason = "fast_only": FRANKENSEARCH_FAST_ONLY=true or no quality embedder. Expected behavior.
• RefinementFailed: Quality model timeout. Increase FRANKENSEARCH_QUALITY_TIMEOUT.
• Results but wrong ranking: Check if you're re-sorting after receiving frankensearch results (DON'T — frankensearch's f64 ordering is authoritative).

4. Is there an async/sync impedance?

If your project is sync (no async runtime) or uses tokio:

• frankensearch requires &Cx (asupersync context) for all async operations
• You need a SyncEmbedderAdapter bridge — see BRIDGE-PATTERNS.md
• For tests: Cx::for_testing() is lightweight and acceptable
• For production sync paths: use SyncTwoTierSearcher with InMemoryTwoTierIndex

5. Is there a dependency resolution failure?

Path deps to sibling directories (../frankensearch) don't work on:

• Remote build workers (rch) — they can't see sibling repos
• CI/CD — sibling repos not checked out by default
• Other developers' machines — different directory layout

Fix for CI:

# .github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    repository: YourOrg/frankensearch
    path: frankensearch
- uses: actions/checkout@v4
  with:
    repository: YourOrg/your-project
    path: your-project

Fix for development: Use path deps locally, git deps for releases:

# Development (local):
frankensearch = { path = "../frankensearch/frankensearch", features = ["hybrid"] }

# Release (git):
# frankensearch = { git = "https://github.com/...", rev = "abc123", features = ["hybrid"] }

Phase 4: Optimization & Audit

Integration Quality Audit Checklist

Abstraction Level Guide

Use the highest abstraction that meets your needs:

HIGHEST ABSTRACTION (prefer this)
├── TwoTierSearcher.search_collect()     ← Most projects should use this
├── TwoTierSearcher.search()             ← When you need progressive phases
├── SyncTwoTierSearcher.search_collect() ← When you need sync + precomputed embeddings
│
MEDIUM ABSTRACTION (when you need control)
├── IndexBuilder + TwoTierIndex          ← Custom index building
├── EmbedderStack + manual searcher      ← Custom embedder lifecycle
├── rrf_fuse() directly                  ← When you have your own retrieval backends
│
LOWEST ABSTRACTION (avoid unless necessary)
├── VectorIndex direct access            ← Raw SIMD search
├── dot_product_f16_f32()                ← Individual vector operations
├── normalize_scores()                   ← Manual score manipulation
└── HashEmbedder/Model2VecEmbedder/etc   ← Individual embedder instances

Rule of thumb: If you're using more than 3 low-level frankensearch APIs, you're probably reimplementing something that TwoTierSearcher already does better.

Async/Sync Decision Matrix

See BRIDGE-PATTERNS.md for complete adapter implementations.

Environment Variables Quick Reference

Common Bug Patterns in Integrations

These are real bugs found across 3 production integrations (82+ bugs total):

References