Search documentation of Ragex

# Ragex.Retrieval.MetaASTRanker (Ragex v0.4.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