rails-nl2sql 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c82ac012038c7065a0c3eeb3db0389fb64eec1fe6c95ae4c0896d6c580527dcc
-  data.tar.gz: 2a6236aad4a76959d360f6b19a7c7c38f662e66cfa7799108a4dd4e6cc546a7f
+  metadata.gz: 2ffb9e53bea983b462fc1c550a4b53623bd9ff2934ba8a38776121833866ea45
+  data.tar.gz: 1cb0973477ea334d95e719e202879334c6f79505a199f08e8a1957b4c344384b
 SHA512:
-  metadata.gz: abe39e44ac4a2443b3cb778f7393cc012099c9266e1a35d25b3ad3bfdfae0b43b27a1206f52026f7cd31342931dc35ec0012ceb3bb8245a23fdadbaa9112da17
-  data.tar.gz: 0ab5536299aa7f4b7063c4c5264ec1b335a7e34957537c18da0bfa19d86b991efc135288d70be76938858e25ad9219d6f4f4d0b0299b72af212a7cb68ffa9418
+  metadata.gz: 2ca2b1516ffe66ced4783bbe75f96d9b8801e6be6d1d070deba162b3c410f0dc77c643fcb666a30bc137e1395b317a453552a7f7ed5a14b250f008ad3d44d205
+  data.tar.gz: 4bbea3200d74e19cb3d5df7cfd3e5c4ce248c61cf2c5ad53e7b943eb283b89bd24fe5fac3c43e925f05ea1b98f269eb19fef518a4bd5f3f6567ab1ad30433180

data/README.md

@@ -28,7 +28,10 @@ This will create an initializer file at `config/initializers/rails_nl2sql.rb`. Y
 # config/initializers/rails_nl2sql.rb
 Rails::Nl2sql.configure do |config|
   config.api_key = ENV["OPENAI_API_KEY"] # It's recommended to use an environment variable
-  # config.model = "text-davinci-003" # Optional: Specify the AI model to use (default is text-davinci-003)
+  # config.model = "gpt-3.5-turbo-instruct" # Optional
+  # config.provider = Rails::Nl2sql::Providers::OpenaiProvider.new(api_key: config.api_key)
+  # config.prompt_template_path = Rails::Nl2sql.prompt_template_path
+  # config.max_schema_lines = 200
 end
 ```
 
@@ -82,6 +85,36 @@ You can clear the cached schema if your database changes:
 Rails::Nl2sql::SchemaBuilder.clear_cache!
 ```
 
+## Pluggable LLM Providers
+
+Rails NL2SQL ships with a simple adapter system so you can use different large language model providers.
+By default the gem uses OpenAI, but you can plug in others like Anthropic or a local Llama‑based HTTP endpoint.
+
+```ruby
+Rails::Nl2sql.configure do |config|
+  config.provider = Rails::Nl2sql::Providers::AnthropicProvider.new(api_key: ENV['ANTHROPIC_KEY'])
+end
+```
+
+## Prompt Templates
+
+The prompts used to talk to the LLM are defined in a YAML/ERB template. You can override this template
+to enforce your own naming conventions or add company specific instructions.
+
+```yaml
+system: |
+  Custom system prompt text...
+user: |
+  Query: <%= input %>
+```
+
+Set the path via `config.prompt_template_path`.
+
+## Context Window Management
+
+Large schemas can exceed the model context window. Use `config.max_schema_lines` to automatically truncate
+the schema snippet sent to the model. Only the first N lines are included.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/generators/rails/nl2sql/templates/rails_nl2sql.rb

@@ -1,4 +1,7 @@
 Rails::Nl2sql.configure do |config|
   config.api_key = "YOUR_API_KEY"
-  # config.model = "text-davinci-003"
+  # config.model = "gpt-3.5-turbo-instruct"
+  # config.provider = Rails::Nl2sql::Providers::OpenaiProvider.new(api_key: config.api_key)
+  # config.prompt_template_path = Rails::Nl2sql.prompt_template_path
+  # config.max_schema_lines = 200
 end

data/lib/generators/rails_nl2sql/install/templates/rails_nl2sql.rb

@@ -1,4 +1,7 @@
 Rails::Nl2sql.configure do |config|
   config.api_key = "YOUR_API_KEY"
-  # config.model = "text-davinci-003"
+  # config.model = "gpt-3.5-turbo-instruct"
+  # config.provider = Rails::Nl2sql::Providers::OpenaiProvider.new(api_key: config.api_key)
+  # config.prompt_template_path = Rails::Nl2sql.prompt_template_path
+  # config.max_schema_lines = 200
 end

data/lib/rails/nl2sql/prompts/default.yml.erb

@@ -0,0 +1,13 @@
+system: |
+  You are an expert SQL assistant specializing in generating dynamic queries based on natural language.
+  Your primary goal is to generate **correct, safe, and executable <%= db_server %> SQL queries** based on user questions.
+
+  ---
+  **DATABASE CONTEXT (SCHEMA):**
+  <%= retrieved_context %>
+  ---
+  Follow best practices and never generate DML or DDL statements.
+  Respond only with SQL.
+user: |
+  Here is the USER QUESTION:
+  <%= input %>

data/lib/rails/nl2sql/providers/anthropic_provider.rb

@@ -0,0 +1,23 @@
+begin
+  require 'anthropic'
+rescue LoadError
+  warn 'Anthropic gem not installed; AnthropicProvider will not work'
+end
+
+module Rails
+  module Nl2sql
+    module Providers
+      class AnthropicProvider < Base
+        def initialize(api_key:, model: 'claude-3-opus-20240229')
+          raise 'anthropic gem missing' unless defined?(::Anthropic::Client)
+          @client = ::Anthropic::Client.new(api_key: api_key)
+          @model = model
+        end
+
+        def complete(prompt:, **params)
+          @client.completions(model: @model, prompt: prompt, **params)
+        end
+      end
+    end
+  end
+end

data/lib/rails/nl2sql/providers/base.rb

@@ -0,0 +1,13 @@
+module Rails
+  module Nl2sql
+    module Providers
+      class Base
+        def initialize(**_opts); end
+
+        def complete(prompt:, **_params)
+          raise NotImplementedError, "Providers must implement #complete"
+        end
+      end
+    end
+  end
+end

data/lib/rails/nl2sql/providers/llama_provider.rb

@@ -0,0 +1,23 @@
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Rails
+  module Nl2sql
+    module Providers
+      class LlamaProvider < Base
+        def initialize(endpoint:, model: nil)
+          @uri = URI.parse(endpoint)
+          @model = model
+        end
+
+        def complete(prompt:, **_params)
+          http = Net::HTTP.new(@uri.host, @uri.port)
+          http.use_ssl = @uri.scheme == 'https'
+          response = http.post(@uri.path, {prompt: prompt, model: @model}.to_json, 'Content-Type' => 'application/json')
+          JSON.parse(response.body)
+        end
+      end
+    end
+  end
+end

data/lib/rails/nl2sql/providers/openai_provider.rb

@@ -0,0 +1,18 @@
+require 'openai'
+
+module Rails
+  module Nl2sql
+    module Providers
+      class OpenaiProvider < Base
+        def initialize(api_key:, model: 'gpt-3.5-turbo-instruct')
+          @client = ::OpenAI::Client.new(access_token: api_key)
+          @model = model
+        end
+
+        def complete(prompt:, **params)
+          @client.completions(parameters: {model: @model, prompt: prompt}.merge(params))
+        end
+      end
+    end
+  end
+end

data/lib/rails/nl2sql/query_generator.rb

@@ -1,184 +1,128 @@
-require "openai"
-
+require "erb"
+require "yaml"
 module Rails
   module Nl2sql
     class QueryGenerator
-      def initialize(api_key, model = "gpt-3.5-turbo-instruct")
-        @client = OpenAI::Client.new(access_token: api_key)
+      DEFAULT_MODEL = 'gpt-3.5-turbo-instruct'
+
+      def initialize(provider: nil, model: DEFAULT_MODEL)
+        @provider = provider || Rails::Nl2sql.provider || default_provider(model)
         @model = model
       end
 
-      def generate_query(prompt, schema, db_server = "PostgreSQL", tables = nil)
+      def generate_query(prompt, schema, db_server = 'PostgreSQL', tables = nil)
         retrieved_context = build_context(schema, tables)
-        
-        # Debug: Let's see what schema context is being sent
-        puts "=== SCHEMA CONTEXT BEING SENT TO AI ==="
-        puts retrieved_context
-        puts "=== END SCHEMA CONTEXT ==="
-        
-        system_prompt = build_system_prompt(db_server, retrieved_context)
-        user_prompt = build_user_prompt(prompt)
-        
+
+        system_prompt, user_prompt = build_prompts(prompt, db_server, retrieved_context)
         full_prompt = "#{system_prompt}\n\n#{user_prompt}"
 
-        response = @client.completions(
-          parameters: {
-            model: @model,
-            prompt: full_prompt,
-            max_tokens: 500,
-            temperature: 0.1
-          }
-        )
-
-        generated_query = response.dig("choices", 0, "text")&.strip
-        
-        # Clean up the response to remove markdown formatting
+        response = @provider.complete(prompt: full_prompt, max_tokens: 500, temperature: 0.1)
+        generated_query = extract_text(response)
+
         generated_query = clean_sql_response(generated_query)
-        
-        # Safety check
         validate_query_safety(generated_query)
-        
+
         generated_query
       end
 
       private
 
+      def default_provider(model)
+        Providers::OpenaiProvider.new(api_key: Rails::Nl2sql.api_key, model: model)
+      end
+
+      def extract_text(response)
+        if response.is_a?(Hash)
+          response.dig('choices', 0, 'text')&.strip
+        else
+          nil
+        end
+      end
+
       def build_context(schema, tables)
-        if tables&.any?
-          # Filter schema to only include requested tables
-          filtered_schema = filter_schema_by_tables(schema, tables)
-          filtered_schema
+        context = if tables&.any?
+          filter_schema_by_tables(schema, tables)
         else
           schema
         end
+        apply_context_window(context)
+      end
+
+      def apply_context_window(context)
+        max_lines = Rails::Nl2sql.max_schema_lines
+        return context unless max_lines
+
+        lines = context.split("\n")
+        return context if lines.length <= max_lines
+
+        lines.first(max_lines).join("\n")
       end
 
       def filter_schema_by_tables(schema, tables)
-        # Simple filtering - in a real implementation, this would be more sophisticated
         lines = schema.split("\n")
         filtered_lines = []
         current_table = nil
         include_current = false
-        
+
         lines.each do |line|
           if line.match(/CREATE TABLE (\w+)/)
-            current_table = $1
+            current_table = Regexp.last_match(1)
             include_current = tables.include?(current_table)
           end
-          
-          if include_current || line.strip.empty?
-            filtered_lines << line
-          end
+
+          filtered_lines << line if include_current || line.strip.empty?
         end
-        
-        filtered_lines.join("\n")
-      end
 
-      def build_system_prompt(db_server, retrieved_context)
-        <<~PROMPT
-          You are an expert SQL assistant specializing in generating dynamic queries based on natural language.
-          Your primary goal is to generate **correct, safe, and executable #{db_server} SQL queries** based on user questions.
-
-          ---
-          **DATABASE CONTEXT (SCHEMA):**
-          You are provided with relevant schema details from the database, retrieved to help you.
-          **STRICTLY adhere to this provided schema context.** Do not use any tables or columns not explicitly listed here.
-          #{retrieved_context}
-
-          ---
-          **SQL GENERATION RULES:**
-          1. **SQL Dialect:** All generated SQL must be valid **#{db_server} syntax**.
-             * For limiting results, use LIMIT (e.g., LIMIT 10) instead of TOP.
-             * Be mindful of #{db_server}'s specific function names (e.g., COUNT(*), MAX()) and behaviors.
-             * For subqueries that return a single value to be used in a WHERE clause, ensure they are correctly formatted for #{db_server}.
-          2. **Schema Adherence:** Only use table names and column names that are explicitly present in the provided context. Do not invent names.
-          3. **Valid JOIN Paths:** All `JOIN` operations must be based on valid foreign key relationships. The provided schema context explicitly details many of these.
-          4. **Safety First:** Absolutely **DO NOT** generate any DDL (CREATE, ALTER, DROP) or DML (INSERT, UPDATE, DELETE) statements. Only `SELECT` queries are permitted.
-          5. **CRITICAL: Handling Missing/Empty Text Data:**
-             * When a user asks about "missing," "no," "empty," or "null" values for a TEXT column (like 'email', 'phone', 'address', 'company', 'fax'), generate a `WHERE` clause that explicitly checks for **both `IS NULL` and `= ''` (an empty string)**.
-             * **Example:** To find agents with no email, the query should be `SELECT first_name, last_name FROM agents WHERE email IS NULL OR email = '';`
-             * This is essential
-          6. **Ambiguity:** If a user question is ambiguous or requires more information to form a precise SQL query, clearly state that you need clarification and ask for more details. Do not guess.
-          
-          **RESPOND WITH ONLY THE SQL QUERY - NO EXPLANATIONS, NO MARKDOWN FORMATTING, NO CODE BLOCKS, NO ADDITIONAL TEXT.**
-        PROMPT
+        filtered_lines.join("\n")
       end
 
-      def build_user_prompt(input)
-        <<~PROMPT
-          Here is the **USER QUESTION:** Respond with a thoughtful process that leads to a SQL query, using the tools as necessary.
-          "#{input}"
-        PROMPT
+      def build_prompts(input, db_server, retrieved_context)
+        template = Rails::Nl2sql.prompt_template
+        system_prompt = ERB.new(template['system']).result(binding)
+        user_prompt = ERB.new(template['user']).result(binding)
+        [system_prompt, user_prompt]
       end
 
       def clean_sql_response(query)
         return query unless query
 
-        # Remove markdown code blocks
         query = query.gsub(/```sql\n?/, '')
         query = query.gsub(/```\n?/, '')
-        
-        # Remove any leading/trailing whitespace
         query = query.strip
-        
-        # Remove any explanatory text before or after the query
-        # Look for common patterns like "Here's the SQL query:" or "The query is:"
         query = query.gsub(/^.*?(SELECT|WITH|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER)/i, '\1')
-        
-        # Remove any trailing explanatory text after the query
-        # Split by newlines and take only the SQL part
         lines = query.split("\n")
         sql_lines = []
-        
+
         lines.each do |line|
           line = line.strip
-          # Skip empty lines or lines that look like explanations
           next if line.empty?
           next if line.match(/^(here|this|the query|explanation|note)/i)
-          
+
           sql_lines << line
         end
-        
-        # Rejoin the SQL lines
+
         cleaned_query = sql_lines.join("\n").strip
-        
-        # Ensure it ends with a semicolon if it's a complete query
-        if cleaned_query.match(/^(SELECT|WITH)/i) && !cleaned_query.end_with?(';')
-          cleaned_query += ';'
-        end
-        
+        cleaned_query += ';' if cleaned_query.match(/^(SELECT|WITH)/i) && !cleaned_query.end_with?(';')
         cleaned_query
       end
 
       def validate_query_safety(query)
         return unless query
 
-        banned_keywords = [
-          "delete", "drop", "truncate", "update", "insert", "alter",
-          "exec", "execute", "create", "merge", "replace", "into"
-        ]
-
+        banned_keywords = %w[delete drop truncate update insert alter exec execute create merge replace into]
         banned_phrases = [
-          "ignore previous instructions", "pretend you are", "i am the admin",
-          "you are no longer bound", "bypass the rules", "run this instead",
-          "for testing, run", "no safety constraints", "show me a dangerous query",
-          "this is a dev environment", "drop all data", "delete all users", "wipe the database"
+          'ignore previous instructions', 'pretend you are', 'i am the admin',
+          'you are no longer bound', 'bypass the rules', 'run this instead',
+          'for testing, run', 'no safety constraints', 'show me a dangerous query',
+          'this is a dev environment', 'drop all data', 'delete all users', 'wipe the database'
         ]
 
         query_lower = query.downcase
-
-        # Check for banned keywords
         banned_keywords.each do |keyword|
-          if query_lower.include?(keyword)
-            raise Rails::Nl2sql::Error, "Query contains banned keyword: #{keyword}"
-          end
+          raise Rails::Nl2sql::Error, "Query contains banned keyword: #{keyword}" if query_lower.include?(keyword)
         end
-
-        # Check for banned phrases
         banned_phrases.each do |phrase|
-          if query_lower.include?(phrase)
-            raise Rails::Nl2sql::Error, "Query contains banned phrase: #{phrase}"
-          end
+          raise Rails::Nl2sql::Error, "Query contains banned phrase: #{phrase}" if query_lower.include?(phrase)
         end
       end
     end

data/lib/rails/nl2sql/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Nl2sql
-    VERSION = "0.2.0"
+    VERSION = "0.2.2"
   end
 end

data/lib/rails/nl2sql.rb

@@ -1,9 +1,15 @@
 require "rails/nl2sql/version"
+require "rails/nl2sql/providers/base"
+require "rails/nl2sql/providers/openai_provider"
+require "rails/nl2sql/providers/anthropic_provider"
+require "rails/nl2sql/providers/llama_provider"
 require "rails/nl2sql/query_generator"
 require "rails/nl2sql/schema_builder"
 require "rails/nl2sql/query_validator"
 require "rails/nl2sql/active_record_extension"
 require "rails/nl2sql/railtie" if defined?(Rails)
+require 'yaml'
+require 'erb'
 
 module Rails
   module Nl2sql
@@ -12,67 +18,65 @@ module Rails
     class << self
       attr_accessor :api_key
       attr_accessor :model
+      attr_accessor :provider
+      attr_accessor :max_schema_lines
+
+      def prompt_template_path=(path)
+        @prompt_template = nil
+        @prompt_template_path = path
+      end
+
+      def prompt_template_path
+        @prompt_template_path || File.expand_path('nl2sql/prompts/default.yml.erb', __dir__)
+      end
     end
-    @@model = "gpt-3.5-turbo-instruct"
+
+    @model = 'gpt-3.5-turbo-instruct'
+    @max_schema_lines = 200
 
     def self.configure
       yield self
     end
 
+    def self.prompt_template
+      @prompt_template ||= begin
+        erb = ERB.new(File.read(prompt_template_path))
+        YAML.safe_load(erb.result)
+      end
+    end
+
     class Processor
       def self.execute(natural_language_query, options = {})
-        # Get database type
         db_server = SchemaBuilder.get_database_type
-        
-        # Build schema with optional table filtering
         schema = SchemaBuilder.build_schema(options)
-        
-        # Debug: Show what schema is being built
-        puts "=== RAW SCHEMA FROM BUILDER ==="
-        puts schema
-        puts "=== END RAW SCHEMA ==="
-        
-        # Extract tables for filtering if specified
         tables = options[:tables]
-        
-        # Generate query with enhanced prompt
-        query_generator = QueryGenerator.new(Rails::Nl2sql.api_key, Rails::Nl2sql.model)
+
+        query_generator = QueryGenerator.new(model: Rails::Nl2sql.model)
         generated_query = query_generator.generate_query(
-          natural_language_query, 
-          schema, 
-          db_server, 
+          natural_language_query,
+          schema,
+          db_server,
           tables
         )
 
-        # Validate the generated query
         QueryValidator.validate(generated_query)
-
-        # Execute the query
         ActiveRecord::Base.connection.execute(generated_query)
       end
 
       def self.generate_query_only(natural_language_query, options = {})
-        # Get database type
         db_server = SchemaBuilder.get_database_type
-        
-        # Build schema with optional table filtering
         schema = SchemaBuilder.build_schema(options)
-        
-        # Extract tables for filtering if specified
         tables = options[:tables]
-        
-        # Generate query with enhanced prompt
-        query_generator = QueryGenerator.new(Rails::Nl2sql.api_key, Rails::Nl2sql.model)
+
+        query_generator = QueryGenerator.new(model: Rails::Nl2sql.model)
         generated_query = query_generator.generate_query(
-          natural_language_query, 
-          schema, 
-          db_server, 
+          natural_language_query,
+          schema,
+          db_server,
           tables
         )
 
-        # Validate the generated query
         QueryValidator.validate(generated_query)
-
         generated_query
       end
 

data/rails-nl2sql.gemspec

@@ -37,8 +37,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "openai", "~> 0.3"
-  spec.add_development_dependency "bundler", ">= 2.0"
+  spec.add_dependency "anthropic", "~> 0.1"
+  spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec-rails", "~> 6.0"
-  spec.add_dependency "railties", ">= 6.0"
+  spec.add_dependency "railties", "~> 6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-nl2sql
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Russell Van Curen
@@ -24,18 +24,32 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: anthropic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
@@ -70,14 +84,14 @@ dependencies:
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
 description: This gem provides an easy way to integrate natural language to SQL functionality
@@ -105,6 +119,11 @@ files:
 - lib/rails-nl2sql.rb
 - lib/rails/nl2sql.rb
 - lib/rails/nl2sql/active_record_extension.rb
+- lib/rails/nl2sql/prompts/default.yml.erb
+- lib/rails/nl2sql/providers/anthropic_provider.rb
+- lib/rails/nl2sql/providers/base.rb
+- lib/rails/nl2sql/providers/llama_provider.rb
+- lib/rails/nl2sql/providers/openai_provider.rb
 - lib/rails/nl2sql/query_generator.rb
 - lib/rails/nl2sql/query_validator.rb
 - lib/rails/nl2sql/railtie.rb