blazer-ai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5383dbf30daabea740fc3a6623310bd7d2c79bdc80e8a9ebb682f36b1660a52
+  data.tar.gz: cc47d89bc105c77af5ce838c09caa3cd9bded14e70710888284dfd1ba1fd1a20
+SHA512:
+  metadata.gz: 1ebe828b2b7f50b44d1f63b9ec0595bcf972c0136ea79da9d0bd8072f696205cd43ab766ec487fbb369e96c544b9027c68b474fa4f70e06b193aad9a4718b891
+  data.tar.gz: 48a86302e19684549ef22cd19d9b60e9013c91128b489f073f48c508915c47f18471c8a7a6290c073babd0f10633d6ecc289cdb6e9603cdbd04e83189033a662

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-11-22
+
+### Added
+
+- Initial release
+- AI-powered SQL generation using RubyLLM
+- Multi-provider support (OpenAI, Anthropic, Gemini, Bedrock, Ollama)
+- Automatic database schema injection
+- SQL validation to prevent dangerous operations
+- Prompt sanitization to prevent injection attacks
+- Rate limiting with configurable limits
+- Support for multiple Blazer data sources
+- Keyboard shortcut (Ctrl+Shift+G) for quick generation
+- Loading states and error handling in the UI
+- Comprehensive configuration options
+
+### Security
+
+- SqlValidator blocks INSERT, UPDATE, DELETE, DROP, TRUNCATE, etc.
+- Detects SQL injection patterns and multi-statement queries
+- PromptSanitizer removes potential prompt injection attempts
+- RateLimiter prevents API abuse

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Kieran Klaassen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# Blazer AI
+
+AI-powered SQL generation for [Blazer](https://github.com/ankane/blazer)
+
+[![Gem Version](https://badge.fury.io/rb/blazer-ai.svg)](https://badge.fury.io/rb/blazer-ai)
+[![CI](https://github.com/kieranklaassen/blazer-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/kieranklaassen/blazer-ai/actions/workflows/ci.yml)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "blazer-ai"
+```
+
+Run:
+
+```sh
+bundle install
+rails generate blazer_ai:install
+```
+
+And set your API key:
+
+```sh
+export OPENAI_API_KEY=your_key_here
+```
+
+## Usage
+
+Visit `/blazer/queries/new` and click **Generate SQL (AI)**.
+
+Keyboard shortcut: `Cmd+Shift+G` (Mac) or `Ctrl+Shift+G`
+
+## Configuration
+
+```ruby
+Blazer::Ai.configure do |config|
+  config.default_model = "gpt-5.1-codex"
+  config.temperature = 0.2
+  config.rate_limit_per_minute = 20
+end
+```
+
+For other providers, update the initializer:
+
+```ruby
+# Anthropic
+RubyLLM.configure do |config|
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+end
+
+Blazer::Ai.configure do |config|
+  config.default_model = "claude-sonnet-4-20250514"
+end
+```
+
+```ruby
+# Google
+RubyLLM.configure do |config|
+  config.gemini_api_key = ENV["GEMINI_API_KEY"]
+end
+
+Blazer::Ai.configure do |config|
+  config.default_model = "gemini-2.0-flash"
+end
+```
+
+## API
+
+Invalidate schema cache:
+
+```ruby
+Blazer::Ai::SchemaCache.invalidate(data_source_id: "main")
+```
+
+Validate SQL:
+
+```ruby
+Blazer::Ai::SqlValidator.new.safe?("SELECT * FROM users")
+```
+
+## Security
+
+Only `SELECT` and `WITH` statements are allowed. Use a read-only database user.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/blazer/ai/application_controller.rb

@@ -0,0 +1,4 @@
+# Base controller for Blazer AI.
+# Inherits Blazer's authentication, CSRF protection, and helpers.
+class Blazer::Ai::ApplicationController < ::Blazer::BaseController
+end

data/app/controllers/blazer/ai/queries_controller.rb

@@ -0,0 +1,85 @@
+# Handles AI-powered SQL generation requests.
+# Validates rate limits, sanitizes input, and returns generated SQL.
+class Blazer::Ai::QueriesController < Blazer::Ai::ApplicationController
+  before_action :ensure_ai_enabled, only: [ :create ]
+
+  def create
+    rate_limiter.check_and_track!(identifier: current_identifier)
+
+    data_source = find_data_source
+    generator = SqlGenerator.new(params: query_params, data_source: data_source)
+
+    sql = generator.call
+    log_generation(query_params, sql)
+
+    render json: { sql: sql }
+  rescue SqlValidator::ValidationError
+    render json: { error: "Generated SQL failed safety validation" }, status: :unprocessable_entity
+  rescue SqlGenerator::GenerationError => e
+    render json: { error: e.message }, status: :unprocessable_entity
+  rescue RateLimiter::RateLimitExceeded => e
+    render json: { error: e.message, retry_after: e.retry_after }, status: :too_many_requests
+  rescue StandardError => e
+    Rails.logger.error("[BlazerAI] Generation error: #{e.class}: #{e.message}")
+    Rails.logger.error(e.backtrace.first(10).join("\n")) if e.backtrace
+    render json: { error: "An error occurred while generating SQL. Please try again." }, status: :unprocessable_entity
+  end
+
+  private
+
+  def query_params
+    params.require(:query).permit(:name, :description, :data_source)
+  end
+
+  def find_data_source
+    data_source_id = params.dig(:query, :data_source)
+    return nil if data_source_id.blank?
+    return nil unless defined?(Blazer) && Blazer.respond_to?(:data_sources)
+
+    ds = Blazer.data_sources[data_source_id]
+    return nil unless ds
+    return nil unless data_source_authorized?(ds)
+
+    ds
+  end
+
+  # Check if current user can access the data source (respects Blazer permissions)
+  def data_source_authorized?(data_source)
+    return true unless data_source.respond_to?(:settings)
+
+    allowed_roles = data_source.settings["roles"]
+    return true if allowed_roles.blank?
+
+    user = respond_to?(:blazer_user, true) ? blazer_user : nil
+    return false unless user
+
+    user_roles = user.respond_to?(:roles) ? user.roles : []
+    (allowed_roles & user_roles).any?
+  end
+
+  def ensure_ai_enabled
+    render json: { error: "AI features are disabled" }, status: :forbidden unless Blazer::Ai.configuration.enabled?
+  end
+
+  def rate_limiter
+    @rate_limiter ||= RateLimiter.new
+  end
+
+  def current_identifier
+    if respond_to?(:blazer_user, true) && blazer_user
+      user_id = blazer_user.respond_to?(:id) ? blazer_user.id : blazer_user.to_s
+      "user:#{user_id}"
+    else
+      "ip:#{request.remote_ip}"
+    end
+  end
+
+  def log_generation(query_params, sql)
+    return unless Rails.logger
+
+    Rails.logger.info("[BlazerAI] SQL generated for #{current_identifier}")
+    Rails.logger.debug("[BlazerAI] Name: #{query_params[:name].to_s.truncate(100)}")
+    Rails.logger.debug("[BlazerAI] Description: #{query_params[:description].to_s.truncate(200)}")
+    Rails.logger.debug("[BlazerAI] SQL: #{sql.truncate(500)}")
+  end
+end

data/app/overrides/blazer/queries/_form.html.erb

@@ -0,0 +1,27 @@
+<%= form_for @query, url: @run_query ? run_queries_path : queries_path, method: @run_query ? :post : :put, html: {class: "form-horizontal"} do |f| %>
+  <div class="form-group">
+    <div class="col-sm-8">
+      <%= f.text_field :name, class: "form-control", placeholder: "Name" %>
+    </div>
+    <div class="col-sm-4">
+      <%= f.select :data_source, Blazer.data_sources.values.map { |ds| [ds.name, ds.id] }, {}, class: ("hide" if Blazer.data_sources.size == 1), style: "width: 140px;" %>
+    </div>
+  </div>
+  <div class="form-group">
+    <div class="col-sm-12">
+      <%= f.text_area :description, class: "form-control", placeholder: "Description", rows: 2 %>
+    </div>
+  </div>
+  <div class="form-group">
+    <div class="col-sm-12">
+      <%= f.text_area :statement, class: "form-control", placeholder: "SQL", rows: 10, autofocus: true %>
+    </div>
+  </div>
+  <div class="form-group">
+    <div class="col-sm-12">
+      <%= f.submit "Run", class: "btn btn-primary" %>
+      <%= render "blazer/ai/queries/generate_sql_button" %>
+      <%= link_to "Cancel", queries_path, class: "btn btn-default" %>
+    </div>
+  </div>
+<% end %>

data/app/views/blazer/ai/queries/_generate_sql_button.html.erb

@@ -0,0 +1,210 @@
+<style>
+  #blazer-ai-container {
+    display: inline-block;
+    position: relative;
+  }
+  #generate-sql {
+    transition: all 0.2s ease;
+  }
+  #generate-sql.loading {
+    opacity: 0.7;
+    cursor: wait;
+  }
+  #generate-sql .spinner {
+    display: none;
+    width: 14px;
+    height: 14px;
+    border: 2px solid transparent;
+    border-top-color: currentColor;
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+    margin-right: 6px;
+    vertical-align: middle;
+  }
+  #generate-sql.loading .spinner {
+    display: inline-block;
+  }
+  #generate-sql.loading .btn-text {
+    opacity: 0.8;
+  }
+  @keyframes spin {
+    to { transform: rotate(360deg); }
+  }
+  #blazer-ai-error {
+    display: none;
+    margin-top: 8px;
+    padding: 8px 12px;
+    background-color: #f8d7da;
+    border: 1px solid #f5c6cb;
+    border-radius: 4px;
+    color: #721c24;
+    font-size: 13px;
+  }
+  #blazer-ai-error.show {
+    display: block;
+  }
+  #blazer-ai-error .close-btn {
+    float: right;
+    cursor: pointer;
+    font-weight: bold;
+    opacity: 0.6;
+  }
+  #blazer-ai-error .close-btn:hover {
+    opacity: 1;
+  }
+</style>
+
+<span id="blazer-ai-container">
+  <button type="button"
+          id="generate-sql"
+          class="btn btn-success">
+    <span class="spinner"></span>
+    <span class="btn-text">Generate SQL (AI)</span>
+  </button>
+  <div id="blazer-ai-error">
+    <span class="close-btn" onclick="BlazerAI.hideError()">&times;</span>
+    <span class="error-message"></span>
+  </div>
+</span>
+
+<script>
+(function() {
+  window.BlazerAI = {
+    isLoading: false,
+
+    init: function() {
+      var btn = document.getElementById('generate-sql');
+      if (btn) {
+        btn.addEventListener('click', this.handleGenerate.bind(this));
+      }
+
+      // Keyboard shortcut: Ctrl/Cmd + Shift + G
+      document.addEventListener('keydown', function(e) {
+        if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'G') {
+          e.preventDefault();
+          BlazerAI.handleGenerate();
+        }
+      });
+    },
+
+    handleGenerate: function(event) {
+      if (event) event.preventDefault();
+      if (this.isLoading) return;
+
+      var name = document.querySelector('input[name="query[name]"]');
+      var description = document.querySelector('textarea[name="query[description]"]');
+
+      var nameValue = name ? name.value.trim() : '';
+      var descValue = description ? description.value.trim() : '';
+
+      if (!nameValue && !descValue) {
+        this.showError('Please enter a query name or description to generate SQL.');
+        return;
+      }
+
+      this.hideError();
+      this.setLoading(true);
+
+      var dataSourceSelect = document.querySelector('select[name="query[data_source]"]');
+      var dataSource = dataSourceSelect ? dataSourceSelect.value : '';
+
+      var generateSqlUrl = '<%= Blazer::Ai::UrlHelper.blazer_ai_generate_sql_path %>';
+
+      fetch(generateSqlUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-CSRF-Token': (document.querySelector('meta[name="csrf-token"]') || {}).content || ''
+        },
+        body: JSON.stringify({
+          query: {
+            name: nameValue,
+            description: descValue,
+            data_source: dataSource
+          }
+        })
+      })
+      .then(function(response) {
+        return response.json().then(function(data) {
+          return { status: response.status, data: data };
+        });
+      })
+      .then(function(result) {
+        BlazerAI.setLoading(false);
+
+        if (result.status === 429) {
+          var retryAfter = result.data.retry_after || 60;
+          BlazerAI.showError('Rate limit exceeded. Please wait ' + retryAfter + ' seconds before trying again.');
+          return;
+        }
+
+        if (result.status !== 200 || result.data.error) {
+          BlazerAI.showError(result.data.error || 'Failed to generate SQL. Please try again.');
+          return;
+        }
+
+        if (result.data.sql) {
+          BlazerAI.insertSql(result.data.sql);
+        }
+      })
+      .catch(function(error) {
+        BlazerAI.setLoading(false);
+        console.error('[BlazerAI] Error:', error);
+        BlazerAI.showError('Network error. Please check your connection and try again.');
+      });
+    },
+
+    insertSql: function(sql) {
+      if (window.editor) {
+        window.editor.setValue(sql, 1);
+        window.editor.focus();
+      } else {
+        var textarea = document.querySelector('textarea[name="query[statement]"]');
+        if (textarea) {
+          textarea.value = sql;
+          textarea.focus();
+        }
+      }
+    },
+
+    setLoading: function(loading) {
+      this.isLoading = loading;
+      var btn = document.getElementById('generate-sql');
+      if (btn) {
+        if (loading) {
+          btn.classList.add('loading');
+          btn.disabled = true;
+        } else {
+          btn.classList.remove('loading');
+          btn.disabled = false;
+        }
+      }
+    },
+
+    showError: function(message) {
+      var errorDiv = document.getElementById('blazer-ai-error');
+      var errorMsg = errorDiv ? errorDiv.querySelector('.error-message') : null;
+      if (errorDiv && errorMsg) {
+        errorMsg.textContent = message;
+        errorDiv.classList.add('show');
+      }
+    },
+
+    hideError: function() {
+      var errorDiv = document.getElementById('blazer-ai-error');
+      if (errorDiv) {
+        errorDiv.classList.remove('show');
+      }
+    }
+  };
+
+  // Initialize when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() {
+      BlazerAI.init();
+    });
+  } else {
+    BlazerAI.init();
+  }
+})();
+</script>

data/config/blazer.yml

@@ -0,0 +1,79 @@
+# see https://github.com/ankane/blazer for more info
+
+data_sources:
+  main:
+    url: <%= ENV["BLAZER_DATABASE_URL"] %>
+
+    # statement timeout, in seconds
+    # none by default
+    # timeout: 15
+
+    # caching settings
+    # can greatly improve speed
+    # off by default
+    # cache:
+    #   mode: slow # or all
+    #   expires_in: 60 # min
+    #   slow_threshold: 15 # sec, only used in slow mode
+
+    # wrap queries in a transaction for safety
+    # not necessary if you use a read-only user
+    # true by default
+    # use_transaction: false
+
+    smart_variables:
+      # zone_id: "SELECT id, name FROM zones ORDER BY name ASC"
+      # period: ["day", "week", "month"]
+      # status: {0: "Active", 1: "Archived"}
+
+    linked_columns:
+      # user_id: "/admin/users/{value}"
+
+    smart_columns:
+      # user_id: "SELECT id, name FROM users WHERE id IN {value}"
+
+# create audits
+audit: true
+
+# change the time zone
+# time_zone: "Pacific Time (US & Canada)"
+
+# class name of the user model
+# user_class: User
+
+# method name for the current user
+# user_method: current_user
+
+# method name for the display name
+# user_name: name
+
+# custom before_action to use for auth
+# before_action_method: require_admin
+
+# email to send checks from
+# from_email: blazer@example.org
+
+# webhook for Slack
+# slack_webhook_url: <%= ENV["BLAZER_SLACK_WEBHOOK_URL"] %>
+
+check_schedules:
+  - "1 day"
+  - "1 hour"
+  - "5 minutes"
+
+# enable anomaly detection
+# note: with trend, time series are sent to https://trendapi.org
+# anomaly_checks: prophet / trend / anomaly_detection
+
+# enable forecasting
+# note: with trend, time series are sent to https://trendapi.org
+# forecasting: prophet / trend
+
+# enable map
+# mapbox_access_token: <%= ENV["MAPBOX_ACCESS_TOKEN"] %>
+
+# enable uploads
+# uploads:
+#   url: <%= ENV["BLAZER_UPLOADS_URL"] %>
+#   schema: uploads
+#   data_source: main

data/db/migrate/20250416180342_install_blazer.rb

@@ -0,0 +1,47 @@
+class InstallBlazer < ActiveRecord::Migration[8.0]
+  def change
+    create_table :blazer_queries do |t|
+      t.references :creator
+      t.string :name
+      t.text :description
+      t.text :statement
+      t.string :data_source
+      t.string :status
+      t.timestamps null: false
+    end
+
+    create_table :blazer_audits do |t|
+      t.references :user
+      t.references :query
+      t.text :statement
+      t.string :data_source
+      t.datetime :created_at
+    end
+
+    create_table :blazer_dashboards do |t|
+      t.references :creator
+      t.string :name
+      t.timestamps null: false
+    end
+
+    create_table :blazer_dashboard_queries do |t|
+      t.references :dashboard
+      t.references :query
+      t.integer :position
+      t.timestamps null: false
+    end
+
+    create_table :blazer_checks do |t|
+      t.references :creator
+      t.references :query
+      t.string :state
+      t.string :schedule
+      t.text :emails
+      t.text :slack_channels
+      t.string :check_type
+      t.text :message
+      t.datetime :last_run_at
+      t.timestamps null: false
+    end
+  end
+end

data/lib/blazer/ai/configuration.rb

@@ -0,0 +1,19 @@
+# Configuration for Blazer AI.
+class Blazer::Ai::Configuration
+  attr_accessor :enabled, :default_model, :temperature, :rate_limit_per_minute,
+                :schema_cache_ttl, :max_prompt_length, :max_sql_length
+
+  def initialize
+    @enabled = true
+    @default_model = "gpt-5.1-codex"
+    @temperature = 0.2
+    @rate_limit_per_minute = 20
+    @schema_cache_ttl = 12.hours
+    @max_prompt_length = 2000
+    @max_sql_length = 10_000
+  end
+
+  def enabled?
+    @enabled
+  end
+end

data/lib/blazer/ai/engine.rb

@@ -0,0 +1,5 @@
+# Rails engine for Blazer AI.
+# Views can be overridden by creating app/views/blazer/ai/queries/_generate_sql_button.html.erb
+class Blazer::Ai::Engine < ::Rails::Engine
+  isolate_namespace Blazer::Ai
+end

data/lib/blazer/ai/prompt_sanitizer.rb

@@ -0,0 +1,48 @@
+module Blazer
+  module Ai
+    class PromptSanitizer
+      # Patterns that might indicate prompt injection attempts
+      SUSPICIOUS_PATTERNS = [
+        /ignore\s+(previous|above|all)\s+instructions/i,
+        /disregard\s+(previous|above|all)/i,
+        /forget\s+(everything|what|your)/i,
+        /new\s+instructions?:/i,
+        /system\s*:/i,
+        /assistant\s*:/i,
+        /\bDROP\b/i,
+        /\bDELETE\b/i,
+        /\bTRUNCATE\b/i,
+        /<script/i,
+        /javascript:/i
+      ].freeze
+
+      def initialize(max_length: nil)
+        @max_length = max_length || Blazer::Ai.configuration.max_prompt_length
+      end
+
+      def sanitize(prompt)
+        return "" if prompt.blank?
+
+        sanitized = prompt.to_s.strip
+
+        # Truncate to max length
+        sanitized = sanitized[0...@max_length]
+
+        # Remove potential injection patterns (replace with empty string)
+        SUSPICIOUS_PATTERNS.each do |pattern|
+          sanitized = sanitized.gsub(pattern, "")
+        end
+
+        # Remove angle brackets that might affect prompt parsing
+        sanitized = sanitized.gsub(/[<>]/, "")
+
+        sanitized.strip
+      end
+
+      def suspicious?(prompt)
+        return false if prompt.blank?
+        SUSPICIOUS_PATTERNS.any? { |p| prompt.match?(p) }
+      end
+    end
+  end
+end

data/lib/blazer/ai/railtie.rb

@@ -0,0 +1,26 @@
+# Integrates Blazer AI into Rails applications.
+# Injects routes into Blazer::Engine and sets up view paths.
+class Blazer::Ai::Railtie < ::Rails::Railtie
+  initializer "blazer_ai.load", before: :load_config_initializers do
+    require "blazer/ai/engine"
+  end
+
+  initializer "blazer_ai.prepend_view_paths", after: :load_config_initializers do |app|
+    ActiveSupport.on_load(:action_controller) do
+      append_view_path(Blazer::Ai::Engine.root.join("app/views"))
+    end
+  end
+
+  # Inject routes directly into Blazer::Engine to avoid nested engine routing issues
+  initializer "blazer_ai.extend_routes", after: "blazer.routes" do |app|
+    if defined?(Blazer::Engine)
+      Blazer::Engine.routes.prepend do
+        post "/ai/generate_sql" => "ai/queries#create", as: "blazer_ai_generate_sql"
+      end
+
+      ActiveSupport.on_load(:action_controller) do
+        helper Blazer::Ai::UrlHelper
+      end
+    end
+  end
+end

data/lib/blazer/ai/rate_limiter.rb

@@ -0,0 +1,61 @@
+module Blazer
+  module Ai
+    class RateLimiter
+      class RateLimitExceeded < StandardError
+        attr_reader :retry_after
+
+        def initialize(message = "Rate limit exceeded", retry_after: 60)
+          @retry_after = retry_after
+          super(message)
+        end
+      end
+
+      def initialize(cache: Rails.cache, max_requests: nil, window: 1.minute)
+        @cache = cache
+        @max_requests = max_requests || Blazer::Ai.configuration.rate_limit_per_minute
+        @window = window
+      end
+
+      # Atomically increment and check rate limit in one operation
+      # This prevents race conditions where concurrent requests bypass the limit
+      def check_and_track!(identifier:)
+        key = rate_limit_key(identifier)
+
+        # Use atomic increment - most cache stores support this
+        # For stores that don't support increment with initial value,
+        # we fall back to a best-effort approach
+        count = atomic_increment(key)
+
+        if count > @max_requests
+          raise RateLimitExceeded.new(
+            "Rate limit exceeded. Please wait before generating more queries.",
+            retry_after: @window.to_i
+          )
+        end
+
+        count
+      end
+
+      private
+
+      def atomic_increment(key)
+        # Try to use atomic increment if available
+        # Rails.cache.increment returns the new value after incrementing
+        result = @cache.increment(key, 1, expires_in: @window)
+
+        # Some cache stores return nil on first increment, handle that case
+        if result.nil?
+          @cache.write(key, 1, expires_in: @window)
+          1
+        else
+          result
+        end
+      end
+
+      def rate_limit_key(identifier)
+        window_id = Time.current.to_i / @window.to_i
+        "blazer_ai:rate_limit:#{identifier}:#{window_id}"
+      end
+    end
+  end
+end

data/lib/blazer/ai/schema_cache.rb

@@ -0,0 +1,45 @@
+module Blazer::Ai
+  module SchemaCache
+    SCHEMA_VERSION = ENV.fetch("BLAZER_AI_SCHEMA_VERSION", 1).to_i
+
+    class << self
+      def fetch(connection, data_source_id: nil)
+        cache_key = build_cache_key(data_source_id)
+        ttl = Blazer::Ai.configuration.schema_cache_ttl
+
+        Rails.cache.fetch(cache_key, expires_in: ttl) do
+          build_schema_string(connection)
+        end
+      end
+
+      def invalidate(data_source_id: nil)
+        cache_key = build_cache_key(data_source_id)
+        Rails.cache.delete(cache_key)
+      end
+
+      def invalidate_all
+        # Pattern-based deletion if supported, otherwise noop
+        if Rails.cache.respond_to?(:delete_matched)
+          Rails.cache.delete_matched("blazer_ai:schema:*")
+        end
+      end
+
+      private
+
+      def build_cache_key(data_source_id)
+        ds_part = data_source_id || "default"
+        "blazer_ai:schema:v#{SCHEMA_VERSION}:#{ds_part}"
+      end
+
+      def build_schema_string(connection)
+        tables = connection.tables.sort
+        tables.map do |table_name|
+          columns = connection.columns(table_name).map do |col|
+            "#{col.name} (#{col.sql_type})"
+          end
+          "#{table_name}: #{columns.join(', ')}"
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/blazer/ai/sql_generator.rb

@@ -0,0 +1,108 @@
+module Blazer::Ai
+  class SqlGenerator
+    class GenerationError < StandardError; end
+
+    def initialize(params:, data_source: nil)
+      @name = params[:name].to_s.strip
+      @description = params[:description].to_s.strip
+      @data_source = data_source || default_data_source
+      @sanitizer = PromptSanitizer.new
+      @validator = SqlValidator.new
+    end
+
+    def call
+      validate_input!
+      sanitize_input!
+
+      schema = build_schema_context
+      adapter_name = determine_adapter_name
+
+      response = generate_sql(schema, adapter_name)
+      sql = @validator.extract_clean_sql(response)
+
+      raise GenerationError, "Failed to generate valid SQL" if sql.blank?
+
+      @validator.validate!(sql)
+      sql
+    end
+
+    private
+
+    def validate_input!
+      if @name.blank? && @description.blank?
+        raise GenerationError, "Please provide a name or description for the query"
+      end
+    end
+
+    def sanitize_input!
+      @name = @sanitizer.sanitize(@name)
+      @description = @sanitizer.sanitize(@description)
+    end
+
+    def build_schema_context
+      connection = data_source_connection
+      SchemaCache.fetch(connection, data_source_id: @data_source&.id)
+    end
+
+    def determine_adapter_name
+      if @data_source
+        @data_source.adapter.to_s.downcase
+      else
+        data_source_connection.adapter_name.downcase
+      end
+    end
+
+    def data_source_connection
+      if @data_source && @data_source.respond_to?(:connection)
+        @data_source.connection
+      else
+        ActiveRecord::Base.connection
+      end
+    end
+
+    def default_data_source
+      return nil unless defined?(Blazer) && Blazer.respond_to?(:data_sources)
+      Blazer.data_sources.values.first
+    end
+
+    def generate_sql(schema, adapter_name)
+      prompt = build_prompt(schema, adapter_name)
+      model = Blazer::Ai.configuration.default_model
+      temperature = Blazer::Ai.configuration.temperature
+
+      # Timeout to prevent hung requests if LLM provider is slow/unresponsive
+      Timeout.timeout(30, GenerationError, "SQL generation timed out. Please try again.") do
+        RubyLLM.chat(model: model)
+               .with_temperature(temperature)
+               .ask(prompt)
+               .content
+      end
+    end
+
+    def build_prompt(schema, adapter_name)
+      <<~PROMPT
+        You are an expert SQL analyst generating queries for a data exploration tool.
+
+        CRITICAL RULES:
+        1. Generate ONLY SELECT or WITH...SELECT queries
+        2. NEVER use INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, GRANT, REVOKE, EXEC, EXECUTE, or UNION
+        3. Use only tables and columns from the schema below
+        4. Always include a LIMIT clause (max 10000 rows)
+        5. Use table aliases for readability
+        6. Handle NULL values appropriately with COALESCE or IS NULL checks
+        7. Return ONLY the SQL query - no explanations, no markdown formatting, no code blocks
+
+        DATABASE TYPE: #{adapter_name}
+
+        SCHEMA:
+        #{schema}
+
+        USER REQUEST:
+        Name: #{@name}
+        Description: #{@description}
+
+        Generate the SQL query now:
+      PROMPT
+    end
+  end
+end

data/lib/blazer/ai/sql_validator.rb

@@ -0,0 +1,93 @@
+module Blazer
+  module Ai
+    class SqlValidator
+      class ValidationError < StandardError; end
+
+      # Keywords that indicate write/dangerous operations - never allow these
+      FORBIDDEN_KEYWORDS = %w[
+        INSERT UPDATE DELETE DROP TRUNCATE ALTER CREATE
+        GRANT REVOKE COMMIT ROLLBACK SAVEPOINT LOCK
+        EXEC EXECUTE CALL
+        UNION
+        COPY
+        DECLARE SET
+        PREPARE DEALLOCATE
+        ATTACH DETACH
+      ].freeze
+
+      # Patterns that indicate potential SQL injection or dangerous operations
+      DANGEROUS_PATTERNS = [
+        /;\s*\w/i,                   # Multiple statements
+        /--/,                        # SQL comments (potential injection)
+        /\/\*/,                      # Block comments
+        /#(?!\{)/,                   # MySQL comments (but not Ruby interpolation)
+        /\$\$/,                      # PostgreSQL dollar quoting
+        /INTO\s+OUTFILE/i,           # File operations
+        /INTO\s+DUMPFILE/i,          # File operations
+        /LOAD_FILE/i,                # File operations
+        /LOAD\s+DATA/i,              # MySQL file loading
+        /SLEEP\s*\(/i,               # Time-based attacks
+        /BENCHMARK\s*\(/i,           # Time-based attacks
+        /WAITFOR\s+DELAY/i,          # SQL Server time attack
+        /PG_SLEEP/i,                 # PostgreSQL time attack
+        /PG_READ_FILE/i,             # PostgreSQL file read
+        /PG_LS_DIR/i,                # PostgreSQL directory listing
+        /UTL_FILE/i,                 # Oracle file operations
+        /DBMS_/i,                    # Oracle packages
+        /XP_CMDSHELL/i,              # SQL Server command execution
+        /SP_CONFIGURE/i,             # SQL Server configuration
+        /0x[0-9A-Fa-f]{8,}/i        # Long hex strings (potential encoding attacks)
+      ].freeze
+
+      def validate!(sql)
+        raise ValidationError, "SQL cannot be empty" if sql.blank?
+
+        # Normalize Unicode to prevent homoglyph attacks (e.g., Cyrillic characters)
+        # and strip non-ASCII from keyword matching
+        ascii_only = sql.encode("ASCII", undef: :replace, replace: "").upcase.gsub(/\s+/, " ")
+        normalized = sql.upcase.gsub(/\s+/, " ")
+
+        # Check for forbidden keywords (check both normalized and ASCII-only versions)
+        FORBIDDEN_KEYWORDS.each do |keyword|
+          if normalized.match?(/\b#{keyword}\b/) || ascii_only.match?(/\b#{keyword}\b/)
+            raise ValidationError, "SQL contains forbidden keyword: #{keyword}"
+          end
+        end
+
+        # Check for dangerous patterns
+        DANGEROUS_PATTERNS.each do |pattern|
+          if sql.match?(pattern)
+            raise ValidationError, "SQL contains potentially dangerous pattern"
+          end
+        end
+
+        # Ensure it starts with SELECT or WITH
+        unless normalized.match?(/^\s*(SELECT|WITH)\b/)
+          raise ValidationError, "SQL must start with SELECT or WITH"
+        end
+
+        true
+      end
+
+      def safe?(sql)
+        validate!(sql)
+        true
+      rescue ValidationError
+        false
+      end
+
+      def extract_clean_sql(content)
+        return nil if content.blank?
+
+        # Try to extract SQL from markdown code blocks
+        if content.include?("```")
+          match = content.match(/```(?:sql)?\s*\n?(.*?)\n?```/m)
+          return match[1].strip if match
+        end
+
+        # Otherwise return the content stripped
+        content.strip
+      end
+    end
+  end
+end

data/lib/blazer/ai/url_helper.rb

@@ -0,0 +1,20 @@
+# Provides URL helpers for Blazer AI routes.
+# Computes path fresh each time to handle development reloads
+# and multi-tenant scenarios where mount points may vary.
+module Blazer::Ai::UrlHelper
+  # Returns the path to the generate_sql endpoint.
+  # Automatically detects Blazer's mount point.
+  def self.blazer_ai_generate_sql_path
+    path = "/ai/generate_sql"
+
+    if defined?(Rails.application)
+      main_route = Rails.application.routes.routes.find { |r| r.name == "blazer" }
+      if main_route
+        blazer_mount = main_route.path.spec.to_s.gsub("(.:format)", "")
+        path = blazer_mount + path
+      end
+    end
+
+    path
+  end
+end

data/lib/blazer/ai/version.rb

@@ -0,0 +1,5 @@
+module Blazer
+  module Ai
+    VERSION = "0.1.0"
+  end
+end

data/lib/blazer/ai.rb

@@ -0,0 +1,33 @@
+require "blazer/ai/version"
+require "blazer/ai/configuration"
+require "blazer/ai/url_helper"
+
+# Load security components
+require "blazer/ai/sql_validator"
+require "blazer/ai/prompt_sanitizer"
+require "blazer/ai/rate_limiter"
+
+# Load schema and SQL generators
+require "blazer/ai/schema_cache"
+require "blazer/ai/sql_generator"
+
+# Load railtie last - it will load the engine
+require "blazer/ai/railtie"
+
+module Blazer
+  module Ai
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

data/lib/generators/blazer_ai/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Creates the Blazer AI initializer for AI-powered SQL generation.
+
+Example:
+    bin/rails generate blazer_ai:install
+
+    This will create:
+        config/initializers/blazer_ai.rb

data/lib/generators/blazer_ai/install_generator.rb

@@ -0,0 +1,13 @@
+require "rails/generators"
+
+module BlazerAi
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        copy_file "blazer_ai.rb", "config/initializers/blazer_ai.rb"
+      end
+    end
+  end
+end

data/lib/generators/blazer_ai/templates/blazer_ai.rb

@@ -0,0 +1,7 @@
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+end
+
+Blazer::Ai.configure do |config|
+  config.default_model = "gpt-5.1-codex"
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: blazer-ai
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kieran Klaassen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: blazer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A Rails engine that adds AI-powered natural language to SQL generation
+  for the Blazer analytics dashboard. Uses RubyLLM to support multiple AI providers
+  (OpenAI, Anthropic, Gemini, etc.).
+email:
+- kieranklaassen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/blazer/ai/application_controller.rb
+- app/controllers/blazer/ai/queries_controller.rb
+- app/overrides/blazer/queries/_form.html.erb
+- app/views/blazer/ai/queries/_generate_sql_button.html.erb
+- config/blazer.yml
+- db/migrate/20250416180342_install_blazer.rb
+- lib/blazer/ai.rb
+- lib/blazer/ai/configuration.rb
+- lib/blazer/ai/engine.rb
+- lib/blazer/ai/prompt_sanitizer.rb
+- lib/blazer/ai/railtie.rb
+- lib/blazer/ai/rate_limiter.rb
+- lib/blazer/ai/schema_cache.rb
+- lib/blazer/ai/sql_generator.rb
+- lib/blazer/ai/sql_validator.rb
+- lib/blazer/ai/url_helper.rb
+- lib/blazer/ai/version.rb
+- lib/generators/blazer_ai/USAGE
+- lib/generators/blazer_ai/install_generator.rb
+- lib/generators/blazer_ai/templates/blazer_ai.rb
+homepage: https://github.com/kieranklaassen/blazer-ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kieranklaassen/blazer-ai
+  source_code_uri: https://github.com/kieranklaassen/blazer-ai
+  changelog_uri: https://github.com/kieranklaassen/blazer-ai/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: AI-powered SQL generation for Blazer
+test_files: []