Ragex.AI.Features.Context (Ragex v0.10.0)

View Source

Context building helpers for AI-enhanced features.

Provides utilities to build rich context from the knowledge graph and embeddings for AI prompts. This ensures AI responses are grounded in actual codebase data.

Usage

alias Ragex.AI.Features.Context

# Build context for validation error
context = Context.for_validation_error(error, file_path, surrounding_code)

# Build context for refactoring preview
context = Context.for_refactor_preview(operation, params, affected_files)

# Build context for dead code analysis
context = Context.for_dead_code_analysis(function_ref, callers, callees)

Summary

Types

context_map()

Functions

for_complexity_explanation(function_ref, complexity_metrics, opts \\ [])

Build context for complexity explanation.

for_dead_code_analysis(function_ref, opts \\ [])

Build context for dead code confidence refinement.

for_dependency_insights(module, metrics, opts \\ [])

Build context for dependency insights.

for_duplication_analysis(code1, code2, similarity_score, opts \\ [])

Build context for duplication semantic analysis.

for_refactor_preview(operation, params, affected_files, opts \\ [])

Build context for refactoring preview commentary.

for_validation_error(error, file_path, surrounding_code \\ nil, opts \\ [])

Build context for validation error explanation.

to_prompt_string(context)

Convert context map to string format for AI prompt.

Types

context_map()

@type context_map() :: %{
  :type => atom(),
  :primary => any(),
  optional(:graph_context) => map(),
  optional(:semantic_context) => list(),
  optional(:metadata) => map()
}

Functions

for_complexity_explanation(function_ref, complexity_metrics, opts \\ [])

@spec for_complexity_explanation(tuple(), map(), keyword()) :: context_map()

Build context for complexity explanation.

Includes:

  • Function AST or code
  • Complexity metrics breakdown
  • Similar functions with lower complexity
  • Common patterns

Parameters

  • function_ref - {:function, module, name, arity} tuple
  • complexity_metrics - Map of complexity metrics
  • opts - Additional options

Returns

  • Context map suitable for AI prompt

for_dead_code_analysis(function_ref, opts \\ [])

@spec for_dead_code_analysis(
  tuple(),
  keyword()
) :: context_map()

Build context for dead code confidence refinement.

Includes:

  • Function reference and basic info
  • Call graph (who calls it, if anyone)
  • Module behavior declarations
  • Function documentation and naming patterns
  • Similar functions in codebase

Parameters

  • function_ref - {:function, module, name, arity} tuple
  • opts - Additional options

Returns

  • Context map suitable for AI prompt

for_dependency_insights(module, metrics, opts \\ [])

@spec for_dependency_insights(module(), map(), keyword()) :: context_map()

Build context for dependency insights.

Includes:

  • Module coupling metrics
  • Dependency graph
  • Similar modules in codebase
  • Architectural patterns

Parameters

  • module - Module atom
  • metrics - Coupling metrics map
  • opts - Additional options

Returns

  • Context map suitable for AI prompt

for_duplication_analysis(code1, code2, similarity_score, opts \\ [])

@spec for_duplication_analysis(String.t(), String.t(), float(), keyword()) ::
  context_map()

Build context for duplication semantic analysis.

Includes:

  • Both code snippets
  • AST similarity metrics
  • Embedding similarity
  • Call patterns
  • Usage context

Parameters

  • code1 - First code snippet
  • code2 - Second code snippet
  • similarity_score - Pre-calculated similarity score
  • opts - Additional options

Returns

  • Context map suitable for AI prompt

for_refactor_preview(operation, params, affected_files, opts \\ [])

@spec for_refactor_preview(atom(), map(), [String.t()], keyword()) :: context_map()

Build context for refactoring preview commentary.

Includes:

  • Operation type and parameters
  • Affected files and their relationships
  • Call graph context (who calls these functions)
  • Similar refactorings in the codebase
  • Complexity metrics

Parameters

  • operation - Refactoring operation atom
  • params - Operation parameters
  • affected_files - List of file paths that will be modified
  • opts - Additional options

Returns

  • Context map suitable for AI prompt

for_validation_error(error, file_path, surrounding_code \\ nil, opts \\ [])

@spec for_validation_error(map(), String.t(), String.t() | nil, keyword()) ::
  context_map()

Build context for validation error explanation.

Includes:

  • The error message and location
  • Surrounding code context
  • Similar code patterns from the codebase
  • Common fixes for this error type

Parameters

  • error - Validation error map with message, line, column
  • file_path - Path to file with error
  • surrounding_code - Code around the error (optional)
  • opts - Additional options

Returns

  • Context map suitable for AI prompt

to_prompt_string(context)

@spec to_prompt_string(context_map()) :: String.t()

Convert context map to string format for AI prompt.

Formats the context in a human-readable way suitable for inclusion in AI prompts.

Parameters

  • context - Context map from any of the builder functions

Returns

  • Formatted string