Ragex.Retrieval.Hybrid (Ragex v0.20.0)

View Source

Hybrid retrieval combining symbolic graph queries with semantic similarity search.

Provides multiple strategies for combining structural and semantic search:

  • Semantic-first: Use embeddings to find candidates, refine with graph
  • Graph-first: Use symbolic queries to filter, rank by similarity
  • Fusion: Combine results from both approaches using RRF, including a BM25 full-text search leg via dllb/Tantivy when dllb is enabled

FTS leg

When Ragex.Dllb.Adapter.enabled?/0 is true, fusion_search/2 adds a third result set from a Tantivy BM25 SEARCH ast_node source_text query. BM25 scores are min-max normalized to [0,1] before RRF fusion so they are comparable to the cosine similarity scores from the semantic leg. When dllb is disabled the FTS leg silently returns an empty list.

Summary

Functions

reciprocal_rank_fusion(result_sets, opts \\ [])

Performs Reciprocal Rank Fusion on multiple result sets.

search(query, opts \\ [])

Performs hybrid search combining semantic and symbolic approaches.

Functions

reciprocal_rank_fusion(result_sets, opts \\ [])

Performs Reciprocal Rank Fusion on multiple result sets.

RRF combines rankings from different sources by:

  1. Converting ranks to scores: 1 / (rank + k)
  2. Summing scores across all sources
  3. Re-ranking by combined score

The constant k (default 60) prevents high rankings from dominating.

search(query, opts \\ [])

Performs hybrid search combining semantic and symbolic approaches.

Strategies

  • :semantic_first - Semantic search followed by graph filtering
  • :graph_first - Graph query followed by semantic ranking
  • :fusion - Combine both with Reciprocal Rank Fusion (default)
  • :graph_algo - dllb PageRank-based retrieval: rank nodes by structural importance, filter to those matching the semantic query.

Options

  • :strategy - Search strategy (default: :fusion)
  • :limit - Maximum results (default: 10)
  • :threshold - Semantic similarity threshold (default: 0.7)
  • :node_type - Filter by entity type
  • :graph_filter - Additional graph constraints
  • :metaast_ranking - Enable MetaAST-based ranking boosts (default: true)
  • :metaast_opts - Options for MetaAST ranking:
    • :prefer_pure - Boost pure functions more (default: true)
    • :penalize_complex - Penalize complex code more (default: true)
    • :cross_language - Enable cross-language equivalence search (default: false)
  • :hyde - Enable HyDE query expansion (default: false). When true, a hypothetical code snippet is generated from the query via AI, embedded, and its embedding is fused with the standard semantic leg. Falls back silently if the AI provider is unavailable.
  • :hyde_opts - Options forwarded to QueryExpansion.hyde_embedding/2:
    • :language - target language hint (default: "elixir")
    • :provider - AI provider override

Examples

# Fusion strategy (default)
Hybrid.search("parse JSON", limit: 5)

# Semantic-first strategy
Hybrid.search("HTTP handler", strategy: :semantic_first)

# Graph-first with constraints
Hybrid.search("calculate", 
  strategy: :graph_first,
  graph_filter: %{module: "Math"}
)

# With MetaAST ranking for cross-language results
Hybrid.search("map operations",
  metaast_ranking: true,
  metaast_opts: [cross_language: true]
)