FastAIHybrid 0.1.0 — Multi-Modal & Dense-Sparse Hybrid Search Fusion for Java

---

⚡ Ultra-fast Reciprocal Rank Fusion (RRF) combining dense semantic vectors and sparse lexical keywords for the FastJava AI Ecosystem.

FastAIHybrid merges keyword retrieval (BM25, identifiers, specific terms) and neural vector retrieval (FastAIVectorDB) into a single, unified high-relevance rank list with zero external Elasticsearch or heavy Lucene dependencies.

---

Quick Start

import fastaihybrid.FastAIHybrid;
import fastaihybrid.FastAIHybrid.Hit;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        // 1. Sparse Lexical Search Results (e.g. BM25 / Keyword)
        List<Hit> lexical = List.of(
            new Hit("doc_101", "FastAI streaming documentation", 12.4),
            new Hit("doc_102", "Configuring HttpClient parameters", 9.1)
        );

        // 2. Dense Semantic Vector Search Results (e.g. FastAIVectorDB)
        List<Hit> dense = List.of(
            new Hit("doc_103", "Low-latency network pipelines in Java", 0.91),
            new Hit("doc_101", "FastAI streaming documentation", 0.88)
        );

        // 3. Reciprocal Rank Fusion (RRF)
        List<Hit> fused = FastAIHybrid.fuse(lexical, dense, 3, 60);
        for (Hit h : fused) {
            System.out.println(h.id() + " -> RRF Score: " + h.score() + " | " + h.text());
        }
    }
}

---

Table of Contents

• Why FastAIHybrid?
• Quick Start
• Features
• Performance Benchmarks
• API Quick Reference
• Technical Examples & Hero Demos
• Installation
• Platform Support
• License
• Related Projects

---

Why FastAIHybrid?

Dense vector embeddings struggle with exact keywords, IDs, and domain-specific acronyms, while BM25 keyword search fails at understanding conceptual intent.

FastAIHybrid solves this by providing:

• Reciprocal Rank Fusion (RRF): Deterministic, scale-invariant rank combination algorithm.
• Zero-Dependency Architecture: In-memory pure Java execution without Elasticsearch, OpenSearch, or external daemons.
• Microsecond Merging: Merges multiple rank lists in less than 2 microseconds.
• Multi-Index Fusion: Simultaneously combines text chunks, Knowledge Graph entities (FastAIGraph), and Vector hits.

---

Features

• 🔀 Deterministic RRF Fusion: Combines sparse and dense score spaces effortlessly.
• ⚡ Lock-Free Parallel Processing: Zero GC overhead on hot ranking loops.
• 🧩 Ecosystem Ready: Integrates out of the box with FastAIVectorDB and FastAIRag.

---

Performance Benchmarks

FastAIHybrid is rigorously profiled using JMH to guarantee zero overhead:

Metric / Hot-Path Operation	Score (ops/ms)	Ops per Second
Reciprocal Rank Fusion (100 candidates)	~98.4 ops/ms	> 98,400 ops/sec
Rank Fusion Top-10 Selection	~1,450 ops/ms	> 1.45 Million

Measured on Windows 11, Intel Core i5-1135G7 (Surface Pro 8), JDK 21.0.12.

---

API Reference

Real-World Production Patterns

1. Hybrid Code & Identifier Search (BM25 + Semantic)

// Balance exact method names/IDs with conceptual questions
List<Hit> lexicalMatches = bm25Index.search("FastAI.stream");
List<Hit> vectorMatches = vectorDb.search(embeddingVector, 20);

// Combine both spaces into a single balanced top-5 list
List<Hit> fused = FastAIHybrid.fuse(lexicalMatches, vectorMatches, 5, 60);

2. Graph & Vector Context Merging

// Fuse structured knowledge graph relations with unstructured text chunks
List<Hit> graphHits = graph.queryHits("FastAIGraph");
List<Hit> textHits = vectorDb.search(queryVector, 10);
List<Hit> finalContext = FastAIHybrid.fuse(graphHits, textHits, 4, 60);

---

API Quick Reference

Method	Return Type	Description
FastAIHybrid.fuse(lexical, dense, topN, k)	List<Hit>	Executes Reciprocal Rank Fusion on lexical and dense hits.

---

Technical Examples & Hero Demos

Case	Java Example	Launcher	Description
Hybrid Fusion Demo	Demo.java	run-demo.bat	Interactive CLI demo merging BM25 and vector search results.
JMH Microbenchmarks	FastAIHybridBenchmark.java	run-benchmark.bat	JMH throughput benchmark for Reciprocal Rank Fusion.

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the dependency to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastAIHybrid</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastAIHybrid:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest JAR directly to add it to your classpath:

1. 📦 FastAIHybrid-0.1.0.jar (The Core Library)

---

Platform Support

Platform	Status
Windows 10/11	✅ Fully Supported
Linux	🚧 Planned
macOS	🚧 Planned

---

License

MIT License — See LICENSE file for details.

---

Related Projects

• FastAI — Unified AI client interface for Java
• FastAIAgent — Autonomous agent loop, intent-graphs, and tool execution
• FastAIBot — Zero-bloat bot harnesses and persona runtime
• FastAIGraph — In-memory knowledge graph and multi-hop relationship engine
• FastAIHybrid — Dense-sparse hybrid search fusion (BM25 + Vectors)
• FastAIMCP — Model Context Protocol (MCP) server & tool integration
• FastAIMemory — Conversation history, sliding windows, and rolling summaries
• FastAIModel — Native local inference runtime (GGUF/ONNX)
• FastAIRag — Ultra-fast document chunking and vector retrieval
• FastAIReasoner — Deterministic planning, chain-of-thought, and self-correction
• FastAIRerank — Cross-encoder relevance filtering and Top-N prompt pruner
• FastAIRuntime — Sandboxed process runner and tool-calling execution pipeline
• FastAIVectorDB — High-throughput SIMD/AVX2 vector database
• FastCore — Unified JNI loader and platform abstraction

---

Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋