struct NL2SQLRequest {
    std::string natural_language;           // Natural language query text
    std::string schema_name;                 // Current database/schema name
    int max_latency_ms;                      // Max acceptable latency (ms)
    bool allow_cache;                        // Enable semantic cache lookup
    std::vector<std::string> context_tables; // Optional table hints for schema

    // Request tracking for correlation and debugging
    std::string request_id;                  // Unique ID for this request (UUID-like)

    // Retry configuration for transient failures
    int max_retries;                         // Maximum retry attempts (default: 3)
    int retry_backoff_ms;                    // Initial backoff in ms (default: 1000)
    double retry_multiplier;                 // Backoff multiplier (default: 2.0)
    int retry_max_backoff_ms;                // Maximum backoff in ms (default: 30000)

    NL2SQLRequest() : max_latency_ms(0), allow_cache(true),
                      max_retries(3), retry_backoff_ms(1000),
                      retry_multiplier(2.0), retry_max_backoff_ms(30000) {
        // Generate UUID-like request ID
        char uuid[64];
        snprintf(uuid, sizeof(uuid), "%08lx-%04x-%04x-%04x-%012lx",
                 (unsigned long)rand(), (unsigned)rand() & 0xffff,
                 (unsigned)rand() & 0xffff, (unsigned)rand() & 0xffff,
                 (unsigned long)rand() & 0xffffffffffff);
        request_id = uuid;
    }
};

struct NL2SQLResult {
    std::string text_response;                  // Generated SQL query
    float confidence;                        // Confidence score 0.0-1.0
    std::string explanation;                 // Which model generated this
    std::vector<std::string> tables_used;    // Tables referenced in SQL
    bool cached;                             // True if from semantic cache
    int64_t cache_id;                        // Cache entry ID for tracking

    // Error details - populated when conversion fails
    std::string error_code;                  // Structured error code (e.g., "ERR_API_KEY_MISSING")
    std::string error_details;               // Detailed error context with query, schema, provider, URL
    int http_status_code;                    // HTTP status code if applicable (0 if N/A)
    std::string provider_used;               // Which provider was attempted

    NL2SQLResult() : confidence(0.0f), cached(false), cache_id(0), http_status_code(0) {}
};

enum class ModelProvider {
    GENERIC_OPENAI,    // Any OpenAI-compatible endpoint (configurable URL)
    GENERIC_ANTHROPIC, // Any Anthropic-compatible endpoint (configurable URL)
    FALLBACK_ERROR     // No model available (error state)
};

enum class NL2SQLErrorCode {
    SUCCESS = 0,                      // No error
    ERR_API_KEY_MISSING,              // API key not configured
    ERR_API_KEY_INVALID,              // API key format is invalid
    ERR_TIMEOUT,                      // Request timed out
    ERR_CONNECTION_FAILED,            // Network connection failed
    ERR_RATE_LIMITED,                 // Rate limited by provider (HTTP 429)
    ERR_SERVER_ERROR,                 // Server error (HTTP 5xx)
    ERR_EMPTY_RESPONSE,               // Empty response from LLM
    ERR_INVALID_RESPONSE,             // Malformed response from LLM
    ERR_SQL_INJECTION_DETECTED,       // SQL injection pattern detected
    ERR_VALIDATION_FAILED,            // Input validation failed
    ERR_UNKNOWN_PROVIDER,             // Invalid provider name
    ERR_REQUEST_TOO_LARGE             // Request exceeds size limit
};

const char* nl2sql_error_code_to_string(NL2SQLErrorCode code);

LLM_Bridge::LLM_Bridge();

LLM_Bridge::~LLM_Bridge();

int LLM_Bridge::init();

void LLM_Bridge::close();

NL2SQLResult LLM_Bridge::convert(const NL2SQLRequest& req);

NL2SQLRequest req;
req.natural_language = "Show top 10 customers";
req.allow_cache = true;
NL2SQLResult result = converter->convert(req);
if (result.confidence > 0.7f) {
    execute_sql(result.text_response);
}

void LLM_Bridge::clear_cache();

std::string LLM_Bridge::get_cache_stats();

{
  "entries": 150,
  "hits": 1200,
  "misses": 300
}

LLM_Bridge* AI_Features_Manager::get_nl2sql();

LLM_Bridge* nl2sql = GloAI->get_nl2sql();
if (nl2sql) {
    NL2SQLResult result = nl2sql->convert(req);
}

char* AI_Features_Manager::get_variable(const char* name);

char* model = GloAI->get_variable("ollama_model");

bool AI_Features_Manager::set_variable(const char* name, const char* value);

GloAI->set_variable("ollama_model", "llama3.3");

NL2SQL: <natural language query>

mysql> USE my_database;
mysql> NL2SQL: Show top 10 customers by revenue;
+---------------------------------------------+------------+-------------------------+--------+----------+
| text_response                                    | confidence | explanation             | cached | cache_id |
+---------------------------------------------+------------+-------------------------+--------+----------+
| SELECT * FROM customers ORDER BY revenue    |      0.850 | Generated by Ollama    |      0 |        0 |
| DESC LIMIT 10                               |            | llama3.2                |        |          |
+---------------------------------------------+------------+-------------------------+--------+----------+
1 row in set (1.23 sec)

-- View all AI status variables
SELECT * FROM runtime_mysql_servers
WHERE variable_name LIKE 'genai_llm_%';

-- Key metrics
SELECT * FROM stats_ai_nl2sql;