Ragex.Retrieval.MetaASTRanker (Ragex v0.13.0)

View Source

Enhances retrieval ranking using MetaAST metadata from Metastatic.

Provides ranking boosts based on semantic properties extracted from MetaAST:

  • Purity analysis (pure functions rank higher for query contexts)
  • Complexity metrics (simpler code ranks higher for explanations)
  • Cross-language semantic equivalence
  • Meta-level properties (M2.1 core vs M2.3 native)

MetaAST Levels

  • M2.1 Core: Universal constructs (literals, variables, binary_op, etc.)
  • M2.2 Extended: Common patterns (loops, lambdas, collections)
  • M2.3 Native: Language-specific escape hatches

Ranking Strategy

Higher scores are given to:

  1. Core-level constructs (more portable/understandable)
  2. Pure functions (no side effects)
  3. Lower complexity (easier to understand)
  4. Cross-language semantic matches

Summary

Functions

apply_ranking(results, opts \\ [])

Apply context-aware MetaAST ranking boosts to retrieval results.

calculate_boost(result, opts \\ [])

Calculate MetaAST-based ranking boost for a retrieval result.

extract_semantic_features(result)

Extract semantic features from MetaAST for query expansion.

find_cross_language_equivalents(target_result, all_results)

Find cross-language equivalents for a given result.

semantically_equivalent?(result1, result2)

Check if two results represent semantically equivalent constructs.

Functions

apply_ranking(results, opts \\ [])

@spec apply_ranking(
  [map()],
  keyword()
) :: [map()]

Apply context-aware MetaAST ranking boosts to retrieval results.

Analyzes query context to apply appropriate ranking strategies:

  • Explanation queries: Prefer simple, pure, core-level code
  • Refactoring queries: Prefer code with improvement opportunities
  • Example queries: Prefer diverse, cross-language examples
  • Debugging queries: Prefer code with side effects/complexity

Options

  • :query - The original query string for context detection
  • :intent - Explicitly specify intent (:explain, :refactor, :example, :debug)
  • All options from calculate_boost/2

Examples

results = [...]

# Auto-detect intent from query
MetaASTRanker.apply_ranking(results, query: "explain how map works")

# Explicit intent
MetaASTRanker.apply_ranking(results, intent: :refactor)

calculate_boost(result, opts \\ [])

@spec calculate_boost(
  map(),
  keyword()
) :: float()

Calculate MetaAST-based ranking boost for a retrieval result.

Returns a boost multiplier (1.0 = no boost, >1.0 = boost, <1.0 = penalty).

Options

  • :boost_core - Boost for M2.1 core constructs (default: 1.2)
  • :boost_pure - Boost for pure functions (default: 1.3)
  • :complexity_penalty - Penalty per complexity unit (default: 0.02)
  • :native_penalty - Penalty for M2.3 native constructs (default: 0.9)

extract_semantic_features(result)

@spec extract_semantic_features(map()) :: [String.t()]

Extract semantic features from MetaAST for query expansion.

Returns a list of semantic tags that can be used for query expansion.

Examples

result = %{meta_ast: {:collection_op, :map, fn, collection}}

MetaASTRanker.extract_semantic_features(result)
# => ["collection", "map", "transform", "iteration"]

find_cross_language_equivalents(target_result, all_results)

@spec find_cross_language_equivalents(map(), [map()]) :: [map()]

Find cross-language equivalents for a given result.

Returns results that have semantically equivalent MetaAST structures but are from different languages.

Examples

python_map = %{meta_ast: {:collection_op, :map, ...}, language: :python}
all_results = [python_map, elixir_map, javascript_map, ...]

MetaASTRanker.find_cross_language_equivalents(python_map, all_results)
# => [elixir_map, javascript_map]

semantically_equivalent?(result1, result2)

@spec semantically_equivalent?(map(), map()) :: boolean()

Check if two results represent semantically equivalent constructs.

Uses MetaAST comparison to identify cross-language equivalents.

Examples

# Python list comprehension and Elixir Enum.map are equivalent at M2 level
result1 = %{meta_ast: {:collection_op, :map, ...}, language: :python}
result2 = %{meta_ast: {:collection_op, :map, ...}, language: :elixir}

MetaASTRanker.semantically_equivalent?(result1, result2)
# => true