# `Lotus.AI.ErrorDetector`
[🔗](https://github.com/elixir-lotus/lotus/blob/v1.0.0/lib/lotus/ai/error_detector.ex#L1)

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", ...]

# `error_context`

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

# `error_type`

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

# `analyze_error`

```elixir
@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.

# `classify_error`

```elixir
@spec classify_error(String.t()) :: error_type()
```

Classify the type of error based on the error message.

## Examples

    iex> ErrorDetector.classify_error("column 'foo' does not exist")
    :column_not_found

    iex> ErrorDetector.classify_error("relation 'bar' does not exist")
    :table_not_found

    iex> ErrorDetector.classify_error("syntax error at or near 'SELECT'")
    :syntax_error

# `suggest_fixes`

```elixir
@spec suggest_fixes(error_type(), String.t(), String.t() | nil, map()) :: [String.t()]
```

Generate helpful suggestions for fixing the error.

## Parameters

- `error_type` - Classified error type
- `error_message` - Original error message
- `statement` - The failed statement (optional)
- `source_context` - Source context map (optional)

## Returns

List of actionable suggestion strings.

---

*Consult [api-reference.md](api-reference.md) for complete listing*