text_to_sql_assistant 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 47525eb6324617379c5fe49c4de11c74bed7394d7adbfc265167c9ccbcb82266
+  data.tar.gz: d54068932f6cb2de49af6e83a7945c0b641885670d156ad1f867bdde47035ccd
+SHA512:
+  metadata.gz: cec6b64f8c63340b0034e00360037a1b248ed26d9d5097ed2d6aa152ccc902bfc545bc10a179862a9cfa51024673eea3dad98c9b9e810e6bbf197cdb9eb3dae8
+  data.tar.gz: c7cdcf4ffb07fccdc13ed25497f9615619dd12da653e3d2f3efa79c4f5fa87bee95a086232200696703d23670f92a81c24f95888b71c82632c019d75176a0edc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibol Teav
+
+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,163 @@
+# TextToSqlAssistant
+
+Ask your database questions in plain English. Get SQL queries and human-readable answers.
+
+Works with **Anthropic Claude**, **OpenAI**, and **Google Gemini**. Zero dependencies beyond ActiveRecord and Ruby stdlib.
+
+## Installation
+
+```ruby
+gem "text_to_sql_assistant"
+```
+
+## Quick Start
+
+```ruby
+TextToSqlAssistant.configure do |c|
+  c.provider = :anthropic
+  c.api_key = ENV["ANTHROPIC_API_KEY"]
+end
+
+assistant = TextToSqlAssistant.new(
+  connection: ActiveRecord::Base.connection
+)
+
+result = assistant.ask("Who are the top 5 customers by order total?")
+puts result[:answer]   # Human-readable explanation
+puts result[:sql]      # Generated SELECT query
+puts result[:results]  # First 10 rows
+```
+
+## How It Works
+
+1. Auto-reads your database schema (tables, columns, types)
+2. Sends schema + question to the LLM
+3. LLM generates a SELECT query
+4. Validates the query (SELECT-only, no sensitive columns, row limit)
+5. Executes against your database
+6. Sends results back to LLM for human-readable interpretation
+
+Two LLM calls per question. ~$0.002 on Claude Haiku.
+
+## Providers
+
+### Anthropic Claude (default)
+
+```ruby
+TextToSqlAssistant.configure do |c|
+  c.provider = :anthropic
+  c.api_key = ENV["ANTHROPIC_API_KEY"]
+  c.model = "claude-haiku-4-5-20251001"  # default, cheapest
+end
+```
+
+### OpenAI
+
+```ruby
+TextToSqlAssistant.configure do |c|
+  c.provider = :openai
+  c.api_key = ENV["OPENAI_API_KEY"]
+  c.model = "gpt-4o-mini"  # default
+end
+```
+
+### Google Gemini
+
+```ruby
+TextToSqlAssistant.configure do |c|
+  c.provider = :gemini
+  c.api_key = ENV["GEMINI_API_KEY"]
+  c.model = "gemini-2.0-flash"  # default
+end
+```
+
+### Custom Provider
+
+```ruby
+class MyProvider < TextToSqlAssistant::Providers::Base
+  def complete(system_prompt, user_message)
+    # Call your LLM, return the response text
+  end
+end
+
+assistant = TextToSqlAssistant.new(provider: MyProvider)
+```
+
+## Configuration
+
+```ruby
+TextToSqlAssistant.configure do |c|
+  c.provider = :anthropic
+  c.api_key = ENV["ANTHROPIC_API_KEY"]
+  c.model = "claude-haiku-4-5-20251001"
+  c.max_rows = 50                    # LIMIT enforced on all queries
+  c.query_timeout = 5                # seconds
+  c.log_queries = true               # log to Rails.logger
+  c.blocked_columns = %w[            # reject queries touching these
+    encrypted_password
+    reset_password_token
+    api_secret
+  ]
+  c.blocked_tables = %w[             # excluded from schema
+    information_schema
+  ]
+  c.on_query = ->(question, result) { # audit callback
+    AuditLog.create!(query: question, sql: result[:sql])
+  }
+end
+```
+
+## Custom Schema
+
+By default, the gem reads your database schema automatically. You can override this with a custom description for better LLM accuracy:
+
+```ruby
+assistant = TextToSqlAssistant.new(
+  schema: <<~SCHEMA
+    - users: id, email, name, role(admin/member), created_at
+    - orders: id, user_id, total_cents, status(pending/paid/refunded), created_at
+    - products: id, name, price_cents, category, active(boolean)
+    NOTE: orders.total_cents is in cents, divide by 100 for dollars.
+    NOTE: users with role='admin' are internal, exclude from customer queries.
+  SCHEMA
+)
+```
+
+## Security
+
+The gem blocks dangerous queries at the application level:
+
+- **SELECT only** — rejects INSERT, UPDATE, DELETE, DROP, etc.
+- **Column blocklist** — blocks `encrypted_password`, `reset_password_token`, etc.
+- **Table blocklist** — excludes `information_schema` and system tables
+- **Row limit** — forces LIMIT on all queries (default 50)
+- **Query timeout** — kills slow queries (default 5 seconds)
+
+**Important:** Application-level validation is defense in depth. For production, always use a **read-only database user**:
+
+```sql
+CREATE USER 'ai_readonly'@'%' IDENTIFIED BY '...';
+GRANT SELECT ON your_database.* TO 'ai_readonly'@'%';
+```
+
+## Response Format
+
+```ruby
+result = assistant.ask("How many users signed up this month?")
+
+result[:answer]      # "47 users signed up this month, up 12% from last month..."
+result[:sql]         # "SELECT COUNT(*) FROM users WHERE created_at >= '2026-03-01'"
+result[:results]     # [{"count" => 47}]  (first 10 rows)
+result[:total_rows]  # 1
+result[:duration_ms] # 3241.5
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- ActiveRecord >= 7.0
+- An API key for Anthropic, OpenAI, or Google Gemini
+
+## License
+
+MIT

data/lib/text_to_sql_assistant/assistant.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  class Assistant
+    SYSTEM_PROMPT = <<~PROMPT
+      You are a SQL expert. Given a database schema and a question, generate a SELECT query to answer it.
+
+      Rules:
+      1. ONLY generate SELECT queries. Never INSERT, UPDATE, DELETE, DROP, or ALTER.
+      2. Always LIMIT results to %{max_rows} rows.
+      3. Use JOINs to show human-readable names instead of IDs where possible.
+      4. Format dates readably.
+      5. Explain your query logic briefly, then provide the SQL in a ```sql block.
+
+      ## Schema
+      %{schema}
+    PROMPT
+
+    def initialize(connection: nil, schema: nil, provider: nil, api_key: nil, model: nil)
+      @connection = connection || ActiveRecord::Base.connection
+      @config = TextToSqlAssistant.configuration
+      @provider = build_provider(provider, api_key, model)
+      @schema = schema || SchemaReader.new(@connection).read
+      @validator = QueryValidator.new(@config)
+    end
+
+    def ask(question)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Step 1: Generate SQL
+      prompt = format(SYSTEM_PROMPT, max_rows: @config.max_rows, schema: @schema)
+      sql_response = @provider.complete(prompt, question)
+
+      # Step 2: Extract SQL
+      sql = extract_sql(sql_response)
+      unless sql
+        return { answer: "Could not generate a valid SQL query.", sql: nil, results: [], total_rows: 0,
+                 duration_ms: duration_since(start_time) }
+      end
+
+      # Step 3: Validate and execute
+      begin
+        validated_sql = @validator.validate!(sql)
+        set_timeout
+        data = @connection.select_all(validated_sql).to_a
+      rescue QueryBlockedError => e
+        return { answer: "Query blocked: #{e.message}", sql: sql, results: [], total_rows: 0,
+                 duration_ms: duration_since(start_time) }
+      rescue ActiveRecord::StatementInvalid => e
+        return { answer: "SQL error: #{e.message.split("\n").first}", sql: sql, results: [], total_rows: 0,
+                 duration_ms: duration_since(start_time) }
+      end
+
+      # Step 4: Interpret results
+      preview = data.first(20).map(&:to_h).to_json
+      answer = @provider.complete(
+        prompt,
+        "I asked: #{question}\n\nSQL:\n```sql\n#{validated_sql}\n```\n\nResults (#{data.length} rows):\n#{preview}\n\nProvide a clear answer."
+      )
+
+      duration = duration_since(start_time)
+
+      result = {
+        answer: answer,
+        sql: validated_sql,
+        results: data.first(10),
+        total_rows: data.length,
+        duration_ms: duration
+      }
+
+      log_query(question, result) if @config.log_queries
+      @config.on_query&.call(question, result)
+
+      result
+    end
+
+    private
+
+    def build_provider(provider_arg, api_key_arg, model_arg)
+      # Accept a pre-built provider instance directly
+      return provider_arg if provider_arg.is_a?(Providers::Base)
+
+      provider_name = provider_arg || @config.provider
+      api_key = api_key_arg || @config.api_key
+      model = model_arg || @config.effective_model
+
+      case provider_name
+      when :anthropic
+        Providers::Anthropic.new(api_key: api_key, model: model)
+      when :openai
+        Providers::OpenAI.new(api_key: api_key, model: model)
+      when :gemini
+        Providers::Gemini.new(api_key: api_key, model: model)
+      else
+        if provider_name.respond_to?(:new)
+          provider_name.new(api_key: api_key, model: model)
+        else
+          raise ConfigurationError, "Unknown provider: #{provider_name}. Use :anthropic, :openai, :gemini, or a custom class."
+        end
+      end
+    end
+
+    def extract_sql(response)
+      return nil unless response
+
+      match = response.match(/```sql\s*\n?(.*?)\n?```/m)
+      return match[1].strip if match
+
+      match = response.match(/(SELECT\s+.+?;)/im)
+      match ? match[1].strip : nil
+    end
+
+    def set_timeout
+      timeout_ms = @config.query_timeout * 1000
+      @connection.execute("SET SESSION MAX_EXECUTION_TIME = #{timeout_ms}") rescue nil
+    end
+
+    def duration_since(start_time)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+    end
+
+    def log_query(question, result)
+      logger = @config.logger || (defined?(Rails) ? Rails.logger : nil)
+      logger&.info("[TextToSqlAssistant] Q: #{question} | SQL: #{result[:sql]&.truncate(100)} | Rows: #{result[:total_rows]} | #{result[:duration_ms]}ms")
+    end
+  end
+end

data/lib/text_to_sql_assistant/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  class Configuration
+    attr_accessor :provider,        # :anthropic, :openai, :ollama, or custom class
+                  :api_key,
+                  :model,
+                  :max_rows,
+                  :query_timeout,   # seconds
+                  :blocked_columns,
+                  :blocked_tables,
+                  :log_queries,
+                  :logger,
+                  :on_query         # callback proc for audit logging
+
+    def initialize
+      @provider = :anthropic
+      @model = nil # auto-detect based on provider
+      @max_rows = 50
+      @query_timeout = 5
+      @blocked_columns = %w[
+        encrypted_password reset_password_token confirmation_token
+        unconfirmed_email temp_password secret_key api_key api_secret
+      ]
+      @blocked_tables = %w[information_schema mysql performance_schema sys]
+      @log_queries = false
+      @logger = nil
+      @on_query = nil
+    end
+
+    def default_model
+      case provider
+      when :anthropic then "claude-haiku-4-5-20251001"
+      when :openai    then "gpt-4o-mini"
+      when :gemini    then "gemini-2.0-flash"
+      else
+        raise ConfigurationError, "No default model for provider #{provider}. Set config.model explicitly."
+      end
+    end
+
+    def effective_model
+      model || default_model
+    end
+  end
+end

data/lib/text_to_sql_assistant/providers/anthropic.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  module Providers
+    class Anthropic < Base
+      URL = "https://api.anthropic.com/v1/messages"
+
+      def complete(system_prompt, user_message)
+        data = post_json(
+          URI(URL),
+          {
+            "x-api-key" => @api_key,
+            "anthropic-version" => "2023-06-01",
+            "content-type" => "application/json"
+          },
+          {
+            model: @model,
+            max_tokens: 2048,
+            system: system_prompt,
+            messages: [{ role: "user", content: user_message }]
+          }
+        )
+        data.dig("content", 0, "text")
+      end
+    end
+  end
+end

data/lib/text_to_sql_assistant/providers/base.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module TextToSqlAssistant
+  module Providers
+    class Base
+      def initialize(api_key:, model:)
+        @api_key = api_key
+        @model = model
+      end
+
+      def complete(system_prompt, user_message)
+        raise NotImplementedError
+      end
+
+      private
+
+      def post_json(uri, headers, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 30
+
+        request = Net::HTTP::Post.new(uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = body.to_json
+
+        response = http.request(request)
+
+        unless response.code.to_i.between?(200, 299)
+          raise ProviderError, "#{self.class.name} API error #{response.code}: #{response.body[0..200]}"
+        end
+
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/text_to_sql_assistant/providers/gemini.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  module Providers
+    class Gemini < Base
+      URL = "https://generativelanguage.googleapis.com/v1beta/models/%{model}:generateContent"
+
+      def complete(system_prompt, user_message)
+        uri = URI(format(URL, model: @model))
+        uri.query = "key=#{@api_key}"
+
+        data = post_json(
+          uri,
+          { "Content-Type" => "application/json" },
+          {
+            system_instruction: { parts: [{ text: system_prompt }] },
+            contents: [{ role: "user", parts: [{ text: user_message }] }],
+            generationConfig: { maxOutputTokens: 2048 }
+          }
+        )
+        data.dig("candidates", 0, "content", "parts", 0, "text")
+      end
+    end
+  end
+end

data/lib/text_to_sql_assistant/providers/openai.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  module Providers
+    class OpenAI < Base
+      URL = "https://api.openai.com/v1/chat/completions"
+
+      def complete(system_prompt, user_message)
+        data = post_json(
+          URI(URL),
+          {
+            "Authorization" => "Bearer #{@api_key}",
+            "Content-Type" => "application/json"
+          },
+          {
+            model: @model,
+            max_tokens: 2048,
+            messages: [
+              { role: "system", content: system_prompt },
+              { role: "user", content: user_message }
+            ]
+          }
+        )
+        data.dig("choices", 0, "message", "content")
+      end
+    end
+  end
+end

data/lib/text_to_sql_assistant/query_validator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  class QueryValidator
+    DANGEROUS_KEYWORDS = %w[INSERT UPDATE DELETE DROP ALTER TRUNCATE CREATE GRANT REVOKE].freeze
+    BLOCKED_PATTERNS = ["INTO OUTFILE", "INTO DUMPFILE", "LOAD_FILE", "BENCHMARK(", "INFORMATION_SCHEMA"].freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    def validate!(sql)
+      normalized = sql.strip.gsub(/\s+/, " ").upcase
+
+      validate_select_only!(normalized)
+      validate_no_dangerous_keywords!(normalized)
+      validate_no_sensitive_columns!(normalized)
+      validate_no_blocked_patterns!(normalized)
+
+      ensure_limit(sql, normalized)
+    end
+
+    private
+
+    def validate_select_only!(normalized)
+      unless normalized.start_with?("SELECT")
+        raise QueryBlockedError, "Only SELECT queries are allowed"
+      end
+    end
+
+    def validate_no_dangerous_keywords!(normalized)
+      words = normalized.split(/[\s;,()]+/)
+      found = DANGEROUS_KEYWORDS.select { |kw| words.include?(kw) }
+      if found.any?
+        raise QueryBlockedError, "Query contains forbidden keyword: #{found.join(', ')}"
+      end
+    end
+
+    def validate_no_sensitive_columns!(normalized)
+      blocked = @config.blocked_columns.map(&:upcase)
+      found = blocked.select { |col| normalized.include?(col) }
+      if found.any?
+        raise QueryBlockedError, "Query references sensitive column: #{found.join(', ')}"
+      end
+    end
+
+    def validate_no_blocked_patterns!(normalized)
+      found = BLOCKED_PATTERNS.select { |pat| normalized.include?(pat) }
+      if found.any?
+        raise QueryBlockedError, "Query contains blocked pattern: #{found.join(', ')}"
+      end
+    end
+
+    def ensure_limit(sql, normalized)
+      if normalized.include?("LIMIT")
+        sql.chomp(";")
+      else
+        "#{sql.chomp(';')} LIMIT #{@config.max_rows}"
+      end
+    end
+  end
+end

data/lib/text_to_sql_assistant/schema_reader.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  # Auto-reads database schema from an ActiveRecord connection.
+  # No manual schema description needed.
+  class SchemaReader
+    def initialize(connection)
+      @connection = connection
+    end
+
+    def read
+      tables = @connection.tables.reject { |t| system_table?(t) }
+
+      tables.map do |table|
+        columns = @connection.columns(table).map do |col|
+          "#{col.name}(#{col.type}#{col.null ? '' : ', NOT NULL'}#{col.default ? ", default: #{col.default}" : ''})"
+        end
+        "- **#{table}**: #{columns.join(', ')}"
+      end.join("\n")
+    end
+
+    private
+
+    def system_table?(name)
+      %w[ar_internal_metadata schema_migrations].include?(name) ||
+        TextToSqlAssistant.configuration.blocked_tables.any? { |bt| name.downcase.include?(bt) }
+    end
+  end
+end

data/lib/text_to_sql_assistant/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TextToSqlAssistant
+  VERSION = "0.1.0"
+end

data/lib/text_to_sql_assistant.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "text_to_sql_assistant/version"
+require_relative "text_to_sql_assistant/configuration"
+require_relative "text_to_sql_assistant/schema_reader"
+require_relative "text_to_sql_assistant/query_validator"
+require_relative "text_to_sql_assistant/assistant"
+require_relative "text_to_sql_assistant/providers/base"
+require_relative "text_to_sql_assistant/providers/anthropic"
+require_relative "text_to_sql_assistant/providers/openai"
+require_relative "text_to_sql_assistant/providers/gemini"
+
+module TextToSqlAssistant
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class QueryBlockedError < Error; end
+  class ProviderError < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def new(**kwargs)
+      Assistant.new(**kwargs)
+    end
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: text_to_sql_assistant
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vibol Teav
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: 'Ask questions in plain English, get SQL queries and human-readable answers.
+  Works with any LLM provider (Anthropic Claude, OpenAI, Ollama, or custom). Includes
+  security guardrails: SELECT-only, column blocklists, query timeouts, audit logging.'
+email:
+- vt@gotabs.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/text_to_sql_assistant.rb
+- lib/text_to_sql_assistant/assistant.rb
+- lib/text_to_sql_assistant/configuration.rb
+- lib/text_to_sql_assistant/providers/anthropic.rb
+- lib/text_to_sql_assistant/providers/base.rb
+- lib/text_to_sql_assistant/providers/gemini.rb
+- lib/text_to_sql_assistant/providers/openai.rb
+- lib/text_to_sql_assistant/query_validator.rb
+- lib/text_to_sql_assistant/schema_reader.rb
+- lib/text_to_sql_assistant/version.rb
+homepage: https://github.com/tvcam/text_to_sql_assistant
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tvcam/text_to_sql_assistant
+  source_code_uri: https://github.com/tvcam/text_to_sql_assistant
+  changelog_uri: https://github.com/tvcam/text_to_sql_assistant/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tvcam/text_to_sql_assistant/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Natural language to SQL query assistant for Ruby/Rails apps
+test_files: []