# `Lotus.AI.SQLGenerator`
[🔗](https://github.com/typhoonworks/lotus/blob/v0.16.6/lib/lotus/ai/sql_generator.ex#L1)

Generates SQL from natural language using ReqLLM.

Handles tool building, message handling, and response extraction.
Any provider supported by ReqLLM can be used by passing a model
string like `"openai:gpt-4o"` or `"anthropic:claude-opus-4"`.

# `sql_response`

```elixir
@type sql_response() :: %{
  content: String.t(),
  model: String.t(),
  variables: [map()],
  usage: %{
    prompt_tokens: non_neg_integer(),
    completion_tokens: non_neg_integer(),
    total_tokens: non_neg_integer()
  }
}
```

# `generate_sql`

```elixir
@spec generate_sql(
  String.t(),
  keyword()
) :: {:ok, sql_response()} | {:error, term()}
```

Generate SQL using the given model string and options.

The model string should be in ReqLLM format, e.g. `"openai:gpt-4o"`,
`"anthropic:claude-opus-4"`, `"google:gemini-2.0-flash"`.

## Options

- `:prompt` (required) - Natural language query
- `:data_source` (required) - Name of the data source
- `:api_key` (required) - API key for the provider
- `:conversation` - Conversation struct for multi-turn
- `:query_context` - Additional context for the query
- `:read_only` - Whether to restrict to read-only SQL (default: true)
- `:temperature` - LLM temperature (default: 0.1)

# `validate_key`

```elixir
@spec validate_key(map()) :: :ok | {:error, String.t()}
```

Validate that a config contains a non-empty API key string.

---

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