sql-chatbot-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ff5a3ddeee3311ba443adb0cde9a935e63ec9781271e2677ab368e653765e5b
+  data.tar.gz: '072728620fd9e8331e874a47c1f61ef6eb764e47b2bd7a8dcc75fdae7ef9d258'
+SHA512:
+  metadata.gz: 11596701b71c9c481305ee51ad60571f41d6f4734750a280d5aeb1885545b8f92455788d5c2522470f73ef43964d250c0e3727ec2929d8ac19129d9da63c4422
+  data.tar.gz: c4755ceeae1e1e87647f2ddb2a7bd5eb3faeab1bfde1c9a8d18a71b5efff9f5cb5a3f5ded8743eebbe373dc766e4d2a39548513040d0393f340dfe6aa8dfa895

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhumit Patel
+
+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,20 @@
+# sql-chatbot-rails
+
+AI chatbot for any Rails app — auto-discovers schema, indexes code, executes SQL, streams answers via chat widget.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'sql-chatbot-rails'
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate sql_chatbot:install
+```
+
+See the generated `config/initializers/sql_chatbot.rb` for configuration options.

data/app/controllers/sql_chatbot/chatbot_controller.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module SqlChatbot
+  class ChatbotController < ActionController::Base
+    include ActionController::Live
+    skip_forgery_protection
+    before_action :handle_cors
+
+    def widget
+      if SqlChatbot.config&.secret
+        cookies[:chatbot_token] = {
+          value: SqlChatbot.config.secret,
+          httponly: true,
+          same_site: :strict,
+        }
+      end
+      widget_path = File.join(SqlChatbot::Engine.root, "vendor", "assets", "widget.js")
+      render body: File.read(widget_path), content_type: "application/javascript"
+    end
+
+    def health
+      ensure_initialized!
+      render json: {
+        status: "ok",
+        tables: SqlChatbot.schema_service.table_count,
+        codeFiles: SqlChatbot.code_indexer.file_count,
+      }
+    rescue => e
+      render json: { status: "error", message: e.message }, status: 500
+    end
+
+    def ask
+      return render_unauthorized unless authorized?
+      ensure_initialized!
+
+      question = params[:question]
+      return render json: { error: "question is required" }, status: 400 if question.blank?
+
+      response.headers["Content-Type"] = "text/event-stream"
+      response.headers["Cache-Control"] = "no-cache"
+      response.headers["Connection"] = "keep-alive"
+
+      SqlChatbot.orchestrator.handle_question(
+        question: question,
+        page_context: params[:pageContext],
+        history: params[:history],
+      ).each do |event|
+        response.stream.write("data: #{event.to_json}\n\n")
+      end
+    rescue => e
+      unless response.stream.closed?
+        response.stream.write("data: #{({ type: "error", message: e.message }).to_json}\n\n")
+      end
+    ensure
+      response.stream.close
+    end
+
+    def refresh
+      return render_unauthorized unless authorized?
+      ensure_initialized!
+      SqlChatbot.schema_service.discover
+      SqlChatbot.code_indexer.index(SqlChatbot.config.code_paths)
+      render json: { status: "refreshed" }
+    rescue => e
+      render json: { status: "error", message: e.message }, status: 500
+    end
+
+    def receive_manifest
+      return render_unauthorized unless authorized?
+      ensure_initialized!
+
+      manifest = params[:manifest]
+      if manifest.present?
+        manifest_data = manifest.respond_to?(:to_unsafe_h) ? manifest.to_unsafe_h : manifest.to_h
+        SqlChatbot.orchestrator.set_manifest(manifest_data)
+        render json: { status: "received", routeCount: manifest["routes"]&.length || 0 }
+      else
+        render json: { error: "manifest is required" }, status: 400
+      end
+    rescue => e
+      render json: { status: "error", message: e.message }, status: 500
+    end
+
+    def create_session
+      origin = request.headers["Origin"]
+
+      # Validate origin
+      allowed_origins = SqlChatbot.config&.allowed_origins
+      if origin && !Auth::Cors.origin_allowed?(origin, allowed_origins)
+        return render json: { error: "Origin not allowed" }, status: 403
+      end
+
+      # Check auth
+      unless authorized?
+        return render_unauthorized
+      end
+
+      config = SqlChatbot.config
+      token = Auth::Jwt.generate_token(
+        secret: config.resolved_token_secret,
+        origin: origin,
+        lifetime_seconds: config.token_lifetime
+      )
+
+      render json: { token: token, expires_in: config.token_lifetime }
+    end
+
+    def preflight
+      head :no_content
+    end
+
+    private
+
+    def authorized?
+      return true unless SqlChatbot.config&.secret
+
+      auth_header = request.headers["Authorization"]
+      if auth_header
+        scheme, token = auth_header.split(" ", 2)
+        if scheme == "Bearer" && token
+          # Try JWT verification first
+          begin
+            Auth::Jwt.verify_token(token: token, secret: SqlChatbot.config.resolved_token_secret)
+            return true
+          rescue Auth::Jwt::TokenExpired, Auth::Jwt::TokenInvalid
+            # Not a JWT, try secret match
+          end
+
+          # Try secret match (existing behavior)
+          return true if token == SqlChatbot.config.secret
+        end
+      end
+
+      # Check cookie (existing behavior)
+      return true if cookies[:chatbot_token] == SqlChatbot.config.secret
+
+      false
+    end
+
+    def render_unauthorized
+      render json: { error: "Unauthorized" }, status: 401
+    end
+
+    def handle_cors
+      origin = request.headers["Origin"]
+      return unless origin
+
+      allowed_origins = SqlChatbot.config&.allowed_origins
+      if Auth::Cors.origin_allowed?(origin, allowed_origins)
+        Auth::Cors.set_headers(response, origin)
+      end
+    end
+
+    def ensure_initialized!
+      SqlChatbot.ensure_initialized!
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+SqlChatbot::Engine.routes.draw do
+  get  "widget.js",    to: "chatbot#widget"
+  get  "api/health",   to: "chatbot#health"
+  post "api/ask",      to: "chatbot#ask"
+  post "api/refresh",  to: "chatbot#refresh"
+  post "api/session",  to: "chatbot#create_session"
+  post "api/manifest", to: "chatbot#receive_manifest"
+  match "api/*path",   to: "chatbot#preflight", via: :options
+end

data/lib/generators/sql_chatbot/install_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SqlChatbot
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/sql_chatbot.rb"
+      end
+
+      def add_route
+        route 'mount SqlChatbot::Engine, at: "/chatbot"'
+      end
+
+      def show_instructions
+        say ""
+        say "SQL Chatbot installed!", :green
+        say "1. Edit config/initializers/sql_chatbot.rb with your API key"
+        say '2. Add to your layout: <script src="/chatbot/widget.js"></script>'
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/sql_chatbot/templates/initializer.rb

@@ -0,0 +1,22 @@
+SqlChatbot.configure do |c|
+  # LLM provider: "openai" (default), "groq", "ollama"
+  c.llm_provider = "openai"
+  c.llm_api_key = ENV["OPENAI_API_KEY"]
+
+  # Optional: override model or base URL
+  # c.llm_model = "gpt-4o-mini"
+  # c.llm_base_url = "https://api.openai.com/v1"
+
+  # Optional: restrict chatbot access (Bearer token or cookie)
+  # c.secret = ENV["CHATBOT_SECRET"]
+
+  # Optional: domain-specific context for better SQL generation
+  # c.custom_context = "status=3 means Deleted, always exclude deleted records"
+
+  # Cross-origin support (for distributed frontend/backend setups):
+  # c.allowed_origins = ["https://your-frontend-domain.com"]
+  # c.token_lifetime = 900  # JWT lifetime in seconds (default: 15 minutes)
+
+  # Code paths to index (default: ["./app"])
+  # c.code_paths = ["./app", "./lib"]
+end

data/lib/sql_chatbot/auth/cors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SqlChatbot
+  module Auth
+    module Cors
+      ALLOWED_METHODS = "GET, POST, OPTIONS"
+      ALLOWED_HEADERS = "Authorization, Content-Type"
+      MAX_AGE = "86400"
+
+      def self.origin_allowed?(origin, allowed_origins)
+        return false if origin.nil?
+
+        if allowed_origins.is_a?(Array) && allowed_origins.any?
+          return allowed_origins.include?(origin)
+        end
+
+        # No allowlist: allow localhost in development/test only
+        if Rails.env.development? || Rails.env.test?
+          return origin.match?(/\Ahttps?:\/\/localhost(:\d+)?\z/)
+        end
+
+        false
+      end
+
+      def self.set_headers(response, origin)
+        response.headers["Access-Control-Allow-Origin"] = origin
+        response.headers["Access-Control-Allow-Methods"] = ALLOWED_METHODS
+        response.headers["Access-Control-Allow-Headers"] = ALLOWED_HEADERS
+        response.headers["Access-Control-Max-Age"] = MAX_AGE
+        existing_vary = response.headers["Vary"]
+        response.headers["Vary"] = existing_vary ? "#{existing_vary}, Origin" : "Origin"
+      end
+    end
+  end
+end

data/lib/sql_chatbot/auth/jwt.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module SqlChatbot
+  module Auth
+    module Jwt
+      class TokenExpired < StandardError; end
+      class TokenInvalid < StandardError; end
+
+      ALGORITHM = "HS256"
+      DEFAULT_LIFETIME = 900 # 15 minutes
+
+      def self.generate_token(secret:, sub: nil, origin: nil, lifetime_seconds: DEFAULT_LIFETIME)
+        now = Time.now.to_i
+        payload = {
+          "iat" => now,
+          "exp" => now + lifetime_seconds
+        }
+        payload["sub"] = sub if sub
+        payload["origin"] = origin if origin
+        ::JWT.encode(payload, secret, ALGORITHM)
+      end
+
+      def self.verify_token(token:, secret:)
+        ::JWT.decode(token, secret, true, algorithm: ALGORITHM).first
+      rescue ::JWT::ExpiredSignature
+        raise TokenExpired, "Token expired"
+      rescue ::JWT::DecodeError
+        raise TokenInvalid, "Invalid token"
+      end
+    end
+  end
+end

data/lib/sql_chatbot/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SqlChatbot
+  class Configuration
+    PROVIDER_PRESETS = {
+      "openai" => { base_url: "https://api.openai.com/v1",      model: "gpt-4o-mini" },
+      "groq"   => { base_url: "https://api.groq.com/openai/v1", model: "llama-3.3-70b-versatile" },
+      "ollama" => { base_url: "http://localhost:11434/v1",      model: "llama3.1:8b" },
+    }.freeze
+
+    attr_accessor :llm_api_key, :llm_provider, :llm_model, :llm_base_url,
+                  :secret, :code_paths, :custom_context,
+                  :allowed_origins,  # Array of allowed cross-origin domains
+                  :token_lifetime,   # JWT lifetime in seconds (default: 900)
+                  :token_secret,     # JWT signing secret (auto-generated if nil)
+                  :grammar_enabled,             # Boolean — enable grammar-first SQL path (default: true)
+                  :grammar_confidence_threshold, # Float — minimum confidence for grammar hit (default: 0.7)
+                  :grammar_miss_log_path,        # String — path to NDJSON miss log (default: nil, resolved at runtime)
+                  :default_filters,              # Hash — app-specific row-level conventions injected into every grammar SELECT.
+                                                 #        Keys: "table.column" or "*.column"; values: SQL fragment.
+                                                 #        Example: { "*.status" => "!= 3" } for MSP "deleted = status 3" convention.
+                  :aliases                       # Hash — custom user-word -> entity-name mappings overriding auto-detection.
+                                                 #        Example: { "customer" => "account_user" } when Saleor's "customers"
+                                                 #        live in account_user. Always wins over auto-detected aliases on conflict.
+
+    def initialize
+      @llm_provider = "openai"
+      @code_paths = ["./app"]
+      @token_lifetime = 900
+      @_resolved_token_secret = nil
+      @grammar_enabled = true
+      @grammar_confidence_threshold = 0.7
+      @grammar_miss_log_path = nil
+      @default_filters = {}
+      @aliases = {}
+    end
+
+    def resolved_token_secret
+      @_resolved_token_secret ||= (@token_secret || ENV["CHATBOT_TOKEN_SECRET"] || SecureRandom.hex(32))
+    end
+
+    def resolved_base_url
+      llm_base_url || PROVIDER_PRESETS.dig(llm_provider, :base_url) || PROVIDER_PRESETS["openai"][:base_url]
+    end
+
+    def resolved_model
+      llm_model || PROVIDER_PRESETS.dig(llm_provider, :model) || PROVIDER_PRESETS["openai"][:model]
+    end
+
+    def resolved_api_key
+      llm_api_key ||
+        ENV["LLM_API_KEY"] ||
+        ENV["OPENAI_API_KEY"] ||
+        ENV["GROQ_API_KEY"] ||
+        (llm_provider == "ollama" ? "ollama" : nil)
+    end
+  end
+end

data/lib/sql_chatbot/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SqlChatbot
+  class Engine < ::Rails::Engine
+    isolate_namespace SqlChatbot
+
+    initializer "sql_chatbot.build_registry", after: :eager_load! do |_app|
+      begin
+        require "sql_chatbot/services/registry_builder"
+        cfg = SqlChatbot.configuration
+        SqlChatbot.registry = SqlChatbot::Services::RegistryBuilder
+                                .new(
+                                  default_filters: cfg&.default_filters,
+                                  custom_aliases:  cfg&.aliases,
+                                )
+                                .build
+      rescue => e
+        Rails.logger&.warn("[sql-chatbot] registry_build_failed: #{e.message}")
+        SqlChatbot.registry = nil
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/count_renderer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SqlChatbot
+  module Grammar
+    # Programmatic renderer for the grammar's COUNT primitive. Bypasses the
+    # answer-stream LLM entirely — a single number is too easy for the LLM to
+    # mis-narrate (e.g., rendering `count = 0` as "No matching records found"
+    # instead of "There are 0 X").
+    #
+    # Mirrors the architectural shape of `ListRenderer`:
+    #   - Pure function. No side effects, no LLM calls.
+    #   - Returns { ok: true, text: "..." } when conditions match, else { ok: false }.
+    #   - Caller (Orchestrator) yields the text as `token` events when ok.
+    #
+    # Conditions for programmatic render:
+    #   - primitive == :COUNT (or "COUNT")
+    #   - exactly one result row
+    #   - that row has a numeric (or numeric-stringable) `count` field — the
+    #     standard column shape PostgreSQL emits for `SELECT COUNT(*)`.
+    # Anything else (grouped counts, multi-row results) falls through to the
+    # answer LLM.
+    module CountRenderer
+      def self.try_render(primitive, entity_display_label, rows)
+        return { ok: false } unless primitive.to_s == "COUNT"
+        return { ok: false } unless rows.is_a?(Array) && rows.length == 1
+
+        row = rows.first
+        return { ok: false } unless row.is_a?(Hash)
+
+        v = row["count"] || row[:count]
+        n = as_number(v)
+        return { ok: false } if n.nil?
+
+        label  = entity_display_label.to_s.empty? ? "Item" : entity_display_label.to_s
+        noun   = n == 1 ? to_singular_label(label) : to_plural_label(label)
+        verb   = n == 1 ? "is" : "are"
+        { ok: true, text: "There #{verb} #{n} #{noun}." }
+      end
+
+      def self.as_number(v)
+        case v
+        when Integer then v
+        when Numeric then v.to_i
+        when String  then (v =~ /\A-?\d+\z/) ? v.to_i : nil
+        else nil
+        end
+      end
+
+      # Force the LAST word of a (possibly multi-word) label to plural.
+      # Detects already-plural inputs ("Credentials" → singularize gives
+      # "credential" — different — so it's already plural) to avoid the
+      # "Credentialses" double-pluralization.
+      def self.to_plural_label(label)
+        transform_last_word(label) { |w| already_plural?(w) ? w : pluralize_word(w) }
+      end
+
+      # Force the LAST word to singular. Mirror of `to_plural_label`.
+      def self.to_singular_label(label)
+        transform_last_word(label) { |w| already_plural?(w) ? singularize_word(w) : w }
+      end
+
+      def self.already_plural?(word)
+        # A word is already plural if singularize produces a different word.
+        # "credentials" -> "credential" (different) -> plural ✓
+        # "class"       -> "class" (ss-guard, unchanged) -> not plural ✓
+        # "inbox"       -> "inbox" (no s ending) -> not plural ✓
+        singularize_word(word) != word
+      end
+
+      def self.transform_last_word(label)
+        parts = label.split(" ")
+        last = parts.last
+        return label if last.nil? || last.empty?
+        lower = last.downcase
+        transformed = yield(lower)
+        parts[-1] = match_case(last, transformed)
+        parts.join(" ")
+      end
+
+      def self.match_case(original, transformed)
+        return transformed if original.empty? || transformed.empty?
+        if original[0] == original[0].upcase
+          transformed[0].upcase + transformed[1..]
+        else
+          transformed
+        end
+      end
+
+      def self.pluralize_word(word)
+        if word =~ /(s|x|z|ch|sh)\z/i           then word + "es"
+        elsif word =~ /[^aeiouAEIOU]y\z/        then word[0..-2] + "ies"
+        else                                         word + "s"
+        end
+      end
+
+      IRREGULAR_PLURALS = {
+        "people" => "person", "men" => "man", "women" => "woman", "children" => "child",
+        "feet" => "foot", "teeth" => "tooth", "geese" => "goose", "mice" => "mouse",
+        "analyses" => "analysis", "bases" => "basis", "crises" => "crisis", "theses" => "thesis",
+        "data" => "datum", "criteria" => "criterion", "phenomena" => "phenomenon",
+      }.freeze
+
+      def self.singularize_word(word)
+        return word if word.empty?
+        return IRREGULAR_PLURALS[word] if IRREGULAR_PLURALS.key?(word)
+        return word[0..-4] + "y" if word.length > 3 && word.end_with?("ies")
+        return word[0..-3] if word =~ /(sses|xes|zes|ches|shes)\z/
+        return word[0..-2] if word.end_with?("s") && !word.end_with?("ss")
+        word
+      end
+    end
+  end
+end