Lotus.AI.ErrorDetector (Lotus v1.0.0)

Analyzes SQL query errors and provides actionable suggestions.

Classifies different types of database errors and generates helpful suggestions to guide the AI in fixing the query.

Error Types

:column_not_found - Referenced column doesn't exist
:table_not_found - Referenced table doesn't exist
:syntax_error - SQL syntax is invalid
:type_mismatch - Data type incompatibility
:ambiguous_column - Column name is ambiguous in JOIN
:permission_denied - Access denied to table/column
:unknown - Other unclassified errors

Usage

error_context = ErrorDetector.analyze_error(
  "column 'status' does not exist",
  "SELECT status FROM users",
  %{tables_analyzed: ["users"]}
)

error_context.error_type
# => :column_not_found

error_context.suggestions
# => ["Use describe_table() to see available columns", ...]

Summary

Functions

analyze_error(error_message, statement \\ nil, source_context \\ %{}, ai_context \\ nil)

Analyze a query error and generate actionable suggestions.

classify_error(error_message)

Classify the type of error based on the error message.

suggest_fixes(error_type, error_message, statement, source_context)

Generate helpful suggestions for fixing the error.

Types

error_context()

@type error_context() :: %{
  error_type: error_type(),
  error_message: String.t(),
  failed_statement: String.t() | nil,
  suggestions: [String.t()]
}

error_type()

@type error_type() ::
  :column_not_found
  | :table_not_found
  | :syntax_error
  | :type_mismatch
  | :ambiguous_column
  | :permission_denied
  | :unknown

Functions

analyze_error(error_message, statement \\ nil, source_context \\ %{}, ai_context \\ nil)

@spec analyze_error(String.t(), String.t() | nil, map(), map() | nil) ::
  error_context()

Analyze a query error and generate actionable suggestions.

Parameters

error_message - The error message from the database
statement - The statement that failed (optional)
source_context - Context about tables analyzed (optional)

Returns

Map containing error type, message, failed SQL, and suggestions for fixing.

Examples

iex> result = ErrorDetector.analyze_error(
...>   "column 'status' does not exist",
...>   "SELECT status FROM users",
...>   %{tables_analyzed: ["users"]}
...> )
iex> result.error_type
:column_not_found
iex> result.error_message
"column 'status' does not exist"
iex> result.failed_statement
"SELECT status FROM users"
iex> Enum.any?(result.suggestions, &String.contains?(&1, "describe_table"))
true

Adapter-supplied hints

An optional fourth argument — ai_context — accepts the sanitized map returned by Lotus.Source.Adapter.ai_context/1. When present, its :error_patterns are matched against the error message; each matching pattern's :hint is prepended to the suggestions list.

Untrusted adapters have their :error_patterns stripped upstream (by the ai_context dispatch helper) to [], so no adapter- contributed text reaches users from untrusted sources — the fall-back is the generic classification + suggestion flow.