magic_query 0.1.1

data/lib/magic_query/prompt/base_prompt.txt

@@ -0,0 +1,23 @@
+You are an expert SQL developer. Your task is to generate valid SQL SELECT queries based on natural language requests.
+
+Rules:
+- Generate ONLY valid SQL SELECT statements
+- Do not include any explanations or comments in the SQL output
+- Use proper SQL syntax
+- Include appropriate JOINs when needed
+- Use WHERE clauses for filtering
+- Consider performance when writing queries
+
+Return only the SQL query, nothing else.
+
+
+
+
+
+
+
+
+
+
+
+

data/lib/magic_query/prompt/builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'templates'
+
+module MagicQuery
+  module Prompt
+    class Builder
+      def initialize(config, schema, rules)
+        @config = config
+        @schema = schema
+        @rules = rules
+      end
+
+      def build(user_input)
+        prompt_parts = []
+
+        # Base prompt
+        base_prompt = @config.base_prompt || Templates.base_prompt
+        prompt_parts << base_prompt
+
+        # Schema
+        prompt_parts << Templates.format_schema(@schema) if @schema && !@schema.empty?
+
+        # Rules
+        prompt_parts << Templates.format_rules(@rules) if @rules && !@rules.empty?
+
+        # User input
+        prompt_parts << "User Request: #{user_input}"
+
+        prompt_parts.join("\n\n")
+      end
+    end
+  end
+end

data/lib/magic_query/prompt/templates.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module MagicQuery
+  module Prompt
+    module Templates
+      def self.base_prompt
+        File.read(File.join(__dir__, 'base_prompt.txt'))
+      end
+
+      def self.format_schema(schema)
+        return '' if schema.nil? || schema.empty?
+
+        schema_text = "Database Schema:\n\n"
+        schema.each do |table_name, table_info|
+          schema_text += format_table(table_name, table_info)
+        end
+        schema_text
+      end
+
+      def self.format_rules(rules)
+        return '' if rules.nil? || rules.empty?
+
+        rules_text = "Database Rules and Conventions:\n\n"
+        rules_text += format_naming_conventions(rules[:naming_conventions])
+        rules_text += format_relationships(rules[:relationships])
+        rules_text += format_business_rules(rules[:business_rules])
+        rules_text += format_table_rules(rules[:tables])
+        rules_text
+      end
+
+      # Private helper methods
+
+      def self.format_table(table_name, table_info)
+        text = "Table: #{table_name}\n"
+        text += format_columns(table_info[:columns])
+        text += format_constraints(table_info[:constraints]) if constraints?(table_info[:constraints])
+        "#{text}\n"
+      end
+
+      def self.format_columns(columns)
+        return "  Columns:\n" if columns.nil? || columns.empty?
+
+        text = "  Columns:\n"
+        columns.each do |column|
+          text += format_column(column)
+        end
+        text
+      end
+
+      def self.format_column(column)
+        if column.is_a?(Hash)
+          "    - #{column[:name]}: #{column[:type]}\n"
+        else
+          "    - #{column}\n"
+        end
+      end
+
+      def self.format_constraints(constraints)
+        return '' if constraints.nil? || constraints.empty?
+
+        text = "  Constraints:\n"
+        constraints.each do |constraint|
+          text += "    - #{constraint}\n"
+        end
+        text
+      end
+
+      def self.constraints?(constraints)
+        constraints && !constraints.empty?
+      end
+
+      def self.format_naming_conventions(naming_conventions)
+        return '' if naming_conventions.nil? || naming_conventions.empty?
+
+        text = "Naming Conventions:\n"
+        naming_conventions.each do |key, value|
+          text += "  - #{key}: #{value}\n"
+        end
+        text += "\n"
+      end
+
+      def self.format_relationships(relationships)
+        return '' if relationships.nil? || relationships.empty?
+
+        text = "Relationships:\n"
+        relationships.each do |rel|
+          text += "  - #{rel}\n"
+        end
+        text += "\n"
+      end
+
+      def self.format_business_rules(business_rules)
+        return '' if business_rules.nil? || business_rules.empty?
+
+        text = "Business Rules:\n"
+        business_rules.each do |rule|
+          text += "  - #{rule}\n"
+        end
+        text += "\n"
+      end
+
+      def self.format_table_rules(tables)
+        return '' if tables.nil? || tables.empty?
+
+        text = "Table-specific Rules:\n"
+        tables.each do |table_name, table_rules|
+          text += "  #{table_name}:\n"
+          table_rules.each do |key, value|
+            text += "    - #{key}: #{value}\n"
+          end
+        end
+        text += "\n"
+      end
+
+      private_class_method :format_table, :format_columns, :format_column,
+                           :format_constraints, :constraints?,
+                           :format_naming_conventions, :format_relationships,
+                           :format_business_rules, :format_table_rules
+    end
+  end
+end

data/lib/magic_query/providers/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module MagicQuery
+  module Providers
+    class Base
+      attr_reader :api_key, :model, :temperature, :max_tokens
+
+      def initialize(api_key:, model: nil, temperature: 0.3, max_tokens: 1000)
+        @api_key = api_key
+        @model = model || default_model
+        @temperature = temperature
+        @max_tokens = max_tokens
+      end
+
+      def generate(prompt)
+        raise NotImplementedError, 'Subclasses must implement #generate'
+      end
+
+      protected
+
+      def default_model
+        raise NotImplementedError, 'Subclasses must implement #default_model'
+      end
+
+      def base_prompt
+        @base_prompt ||= begin
+          prompt_file = File.join(__dir__, '..', 'prompt', 'base_prompt.txt')
+          File.read(prompt_file).strip
+        end
+      end
+
+      def generate_params(prompt)
+        raise NotImplementedError, 'Subclasses must implement #generate_params'
+      end
+
+      def generate_headers
+        raise NotImplementedError, 'Subclasses must implement #generate_headers'
+      end
+
+      def generate_body(prompt)
+        raise NotImplementedError, 'Subclasses must implement #generate_body'
+      end
+
+      def http_client
+        @http_client ||= Faraday.new do |conn|
+          conn.request :json
+          conn.response :json
+          conn.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/magic_query/providers/claude.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+
+module MagicQuery
+  module Providers
+    class Claude < Base
+      API_URL = 'https://api.anthropic.com/v1/messages'
+
+      def generate(prompt)
+        response = http_client.post(API_URL) do |req|
+          generate_headers.each { |key, value| req.headers[key] = value }
+          req.body = generate_body(prompt)
+        end
+
+        handle_response(response)
+      end
+
+      protected
+
+      def default_model
+        'claude-3-5-sonnet-20241022'
+      end
+
+      def generate_params(_prompt)
+        {}
+      end
+
+      def generate_headers
+        {
+          'x-api-key' => api_key,
+          'anthropic-version' => '2023-06-01',
+          'Content-Type' => 'application/json'
+        }
+      end
+
+      def generate_body(prompt)
+        {
+          model: model,
+          max_tokens: max_tokens,
+          temperature: temperature,
+          system: base_prompt,
+          messages: [
+            { role: 'user', content: prompt }
+          ]
+        }
+      end
+
+      private
+
+      def handle_response(response)
+        raise Error, "Claude API error: #{response.status} - #{response.body}" unless response.status == 200
+
+        body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
+        body.dig('content', 0, 'text')
+      end
+    end
+  end
+end

data/lib/magic_query/providers/gemini.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+
+module MagicQuery
+  module Providers
+    class Gemini < Base
+      API_URL_TEMPLATE = 'https://generativelanguage.googleapis.com/v1beta/models/%s:generateContent'
+
+      def generate(prompt)
+        url = format(API_URL_TEMPLATE, model)
+        response = make_request(url, prompt)
+        handle_response(response)
+      end
+
+      def make_request(url, prompt)
+        http_client.post(url) do |req|
+          set_request_params(req, prompt)
+          apply_request_headers(req)
+          req.body = generate_body(prompt)
+        end
+      end
+
+      def set_request_params(req, prompt)
+        generate_params(prompt).each { |key, value| req.params[key] = value }
+      end
+
+      def apply_request_headers(req)
+        generate_headers.each { |key, value| req.headers[key] = value }
+      end
+
+      protected
+
+      def default_model
+        'gemini-1.5-flash-latest'
+      end
+
+      def generate_params(_prompt)
+        { 'key' => api_key }
+      end
+
+      def generate_headers
+        {
+          'Content-Type' => 'application/json'
+        }
+      end
+
+      def generate_body(prompt) # rubocop:disable Metrics/MethodLength
+        {
+          contents: [
+            {
+              parts: [
+                { text: "#{base_prompt}\n\n#{prompt}" }
+              ]
+            }
+          ],
+          generationConfig: {
+            temperature: temperature,
+            maxOutputTokens: max_tokens
+          }
+        }
+      end
+
+      private
+
+      def handle_response(response)
+        raise Error, "Gemini API error: #{response.status} - #{response.body}" unless response.status == 200
+
+        body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
+        body.dig('candidates', 0, 'content', 'parts', 0, 'text')
+      end
+    end
+  end
+end

data/lib/magic_query/providers/openai.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+
+module MagicQuery
+  module Providers
+    class OpenAI < Base
+      API_URL = 'https://api.openai.com/v1/chat/completions'
+
+      def generate(prompt)
+        response = http_client.post(API_URL) do |req|
+          generate_headers.each { |key, value| req.headers[key] = value }
+          req.body = generate_body(prompt)
+        end
+
+        handle_response(response)
+      end
+
+      protected
+
+      def default_model
+        'gpt-4o-2024-08-06'
+      end
+
+      def generate_params(_prompt)
+        {}
+      end
+
+      def generate_headers
+        {
+          'Authorization' => "Bearer #{api_key}",
+          'Content-Type' => 'application/json'
+        }
+      end
+
+      def generate_body(prompt)
+        {
+          model: model,
+          messages: [
+            { role: 'system', content: base_prompt },
+            { role: 'user', content: prompt }
+          ],
+          temperature: temperature,
+          max_tokens: max_tokens
+        }
+      end
+
+      private
+
+      def handle_response(response)
+        raise Error, "OpenAI API error: #{response.status} - #{response.body}" unless response.status == 200
+
+        body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
+        body.dig('choices', 0, 'message', 'content')
+      end
+    end
+  end
+end

data/lib/magic_query/query/parser.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module MagicQuery
+  module Query
+    class Parser
+      def self.extract_sql(response_text)
+        new(response_text).extract
+      end
+
+      def initialize(response_text)
+        @response_text = response_text.to_s.strip
+      end
+
+      def extract
+        # Try to extract SQL from markdown code blocks first
+        sql = extract_from_markdown || extract_direct_sql || @response_text
+
+        # Clean up the SQL
+        clean_sql(sql)
+      end
+
+      private
+
+      def extract_from_markdown
+        # Match SQL in markdown code blocks
+        match = @response_text.match(/```(?:sql)?\s*\n?(.*?)```/m)
+        match ? match[1].strip : nil
+      end
+
+      def extract_direct_sql
+        # Try to find SELECT statement
+        match = @response_text.match(/(SELECT\s+.*?(?:;|$))/mi)
+        match ? match[1].strip : nil
+      end
+
+      def clean_sql(sql)
+        # Remove trailing semicolons and extra whitespace
+        sql = sql.strip
+        sql = sql.chomp(';') if sql.end_with?(';')
+        sql.strip
+      end
+    end
+  end
+end

data/lib/magic_query/query/validator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MagicQuery
+  module Query
+    class Validator
+      def self.validate(sql)
+        new(sql).validate
+      end
+
+      def self.valid?(sql)
+        new(sql).valid?
+      end
+
+      def initialize(sql)
+        @sql = sql.to_s.strip
+      end
+
+      def validate
+        errors = []
+
+        if @sql.empty?
+          errors << 'SQL query is empty'
+          return errors
+        end
+
+        errors << 'Query must start with SELECT' unless @sql.match?(/^\s*SELECT/i)
+        errors.concat(check_dangerous_keywords)
+
+        errors
+      end
+
+      def check_dangerous_keywords
+        errors = []
+        dangerous_keywords = %w[DROP DELETE UPDATE INSERT ALTER CREATE TRUNCATE]
+        dangerous_keywords.each do |keyword|
+          errors << "Query contains dangerous keyword: #{keyword}" if @sql.match?(/\b#{keyword}\b/i)
+        end
+        errors
+      end
+
+      def valid?
+        validate.empty?
+      end
+    end
+  end
+end

data/lib/magic_query/query_generator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'schema/loader'
+require_relative 'config/rules_loader'
+require_relative 'prompt/builder'
+require_relative 'query/parser'
+require_relative 'query/validator'
+
+module MagicQuery
+  class QueryGenerator
+    def initialize(config = nil)
+      @config = config || MagicQuery.configuration
+      @schema = nil
+      @rules = nil
+    end
+
+    def generate(user_input)
+      validate_user_input(user_input)
+      ensure_api_key_configured
+      load_dependencies
+
+      prompt = build_prompt(user_input)
+      response = generate_ai_response(prompt)
+      extract_and_validate_sql(response)
+    end
+
+    private
+
+    def validate_user_input(user_input)
+      raise Error, 'User input cannot be empty' if user_input.nil? || user_input.strip.empty?
+    end
+
+    def ensure_api_key_configured
+      raise Error, 'API key not configured' if @config.api_key.nil? || @config.api_key.strip.empty?
+    end
+
+    def load_dependencies
+      load_schema unless @schema
+      load_rules unless @rules
+    end
+
+    def build_prompt(user_input)
+      prompt_builder = Prompt::Builder.new(@config, @schema, @rules)
+      prompt_builder.build(user_input)
+    end
+
+    def generate_ai_response(prompt)
+      provider = create_provider
+      provider.generate(prompt)
+    end
+
+    def create_provider
+      provider_class = @config.provider_class
+      provider_class.new(
+        api_key: @config.api_key,
+        model: @config.model,
+        temperature: @config.temperature,
+        max_tokens: @config.max_tokens
+      )
+    end
+
+    def extract_and_validate_sql(response)
+      sql = Query::Parser.extract_sql(response)
+      validator = Query::Validator.new(sql)
+      validation_errors = validator.validate
+      raise Error, "Invalid SQL generated: #{validation_errors.join(', ')}" unless validation_errors.empty?
+
+      sql
+    end
+
+    def load_schema
+      # Loader will automatically detect the best source (file, Rails, or database)
+      @schema = Schema::Loader.load(@config)
+    end
+
+    def load_rules
+      @rules = Config::RulesLoader.load(@config.rules_path) if @config.rules_path
+    end
+  end
+end

data/lib/magic_query/rails/controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module MagicQuery
+  module Rails
+    # Base controller for Magic Query endpoints.
+    # Provides a RESTful endpoint for generating SQL queries from natural language.
+    #
+    # For detailed documentation, examples, and customization options, see CONTROLLER.md
+    class MagicQueryController < ActionController::Base
+      before_action :set_generator
+      before_action :set_magic_query_params
+
+      def generate
+        if @user_input.blank?
+          render json: { error: 'Query parameter is required' }, status: :bad_request
+          return
+        end
+
+        generate_sql_with_error_handling
+      end
+
+      protected
+
+      # Generates SQL from user input with error handling.
+      # Override this method to customize error handling behavior.
+      #
+      # @example Custom error handling
+      #   def generate_sql_with_error_handling
+      #     sql = @generator.generate(@user_input)
+      #     render json: { sql: sql, query: @user_input }
+      #   rescue MagicQuery::Error => e
+      #     # Custom error handling
+      #     render json: { error: e.message }, status: :unprocessable_entity
+      #   end
+      #
+      # @return [void]
+      def generate_sql_with_error_handling
+        sql = @generator.generate(@user_input)
+        render json: { sql: sql, query: @user_input }
+      rescue MagicQuery::Error => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      rescue StandardError => e
+        render json: { error: "An error occurred: #{e.message}" }, status: :internal_server_error
+      end
+
+      # Sets the user input from request parameters.
+      # Override this method to customize how input parameters are read.
+      #
+      # By default, it reads from `params[:input]` or falls back to `params[:query]`.
+      #
+      # @example Custom parameter source
+      #   def set_magic_query_params
+      #     @user_input = params[:custom_input] || params[:text]
+      #   end
+      #
+      # @return [void]
+      def set_magic_query_params
+        @user_input = params[:input] || params[:query]
+      end
+
+      # Sets up the query generator instance.
+      # Override this method to customize generator configuration.
+      #
+      # @example Custom configuration
+      #   def set_generator
+      #     custom_config = MagicQuery::Configuration.new
+      #     custom_config.provider = :custom_provider
+      #     @generator = MagicQuery::QueryGenerator.new(custom_config)
+      #   end
+      #
+      # @return [void]
+      def set_generator
+        @generator = MagicQuery::QueryGenerator.new(MagicQuery.configuration)
+      end
+    end
+  end
+end

data/lib/magic_query/rails/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MagicQuery
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace MagicQuery
+
+      config.generators do |g|
+        g.test_framework :rspec
+        g.fixture_replacement :factory_bot, dir: 'spec/factories'
+      end
+
+      initializer 'magic_query.routes' do
+        Rails.application.routes.draw do
+          MagicQuery::Rails::Routes.draw(self)
+        end
+      end
+    end
+  end
+end