glancer 1.0.0

data/lib/glancer/workflow/llm.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Glancer
+  module Workflow
+    class LLM
+      def self.humanized_response(question, _data, code, mode: :sql)
+        chat = RubyLLM.chat(
+          provider: Glancer.configuration.resolved_chat_provider,
+          model: Glancer.configuration.resolved_chat_model,
+          assume_model_exists: true
+        )
+
+        code_label = mode == :activerecord ? "Ruby/ActiveRecord expression" : "SQL query"
+        code_lang  = mode == :activerecord ? "ruby" : "sql"
+
+        context = <<~PROMPT
+          You are **Glancer**, a concise database assistant.
+
+          CRITICAL RULES:
+          - **Language Match**: Respond ONLY in the same language as the user's question.
+          - **Never say the query "ran", "executed", or "returned"** — the code was GENERATED to answer the user's question.
+            The actual results are displayed separately in the UI.
+          - **What to explain**: Describe WHAT the code does logically and WHY it answers the question.
+          - **Brevity**: 2–4 sentences maximum. No bullet points unless truly necessary.
+          - **No code repeat**: The generated code is already shown; do not include it in your response.
+          - **No hallucinations**: You have no knowledge of the actual result values. Do not describe or infer data values.
+          - **Formatting**: Use Markdown and bold for key terms.
+
+          #{code_label.upcase} GENERATED to answer the user's question:
+          ```#{code_lang}
+          #{code}
+          ```
+
+          USER QUESTION:
+          #{question}
+        PROMPT
+
+        custom = Glancer::Setting.get("custom_instructions")
+        context += "\n\nADDITIONAL INSTRUCTIONS:\n#{custom}" if custom.present?
+
+        chat.with_instructions(context)
+        response = chat.ask(question)
+
+        response.content
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("Workflow::LLM", "Humanized response failed: #{e.message}")
+        "I processed the query but failed to generate a humanized explanation. You can still see the raw data below."
+      end
+
+      def self.explain_missing_tables(question, error_message)
+        missing = error_message.scan(/Missing table\(s\) in indexed schema: (.+)/).flatten.first ||
+                  error_message.scan(/Table validation failed: Missing table\(s\) in indexed schema: (.+)/).flatten.first ||
+                  "desconhecidas"
+
+        prompt = <<~PROMPT
+          You are **Glancer**, a helpful SQL assistant.
+
+          The user asked: "#{question}"
+
+          When I tried to generate the SQL query, I referenced table(s) that don't exist in the indexed schema: **#{missing}**.
+          This is likely a naming mismatch (e.g., the user said "afiliados" but the actual table is "filiais").
+
+          Please:
+          1. Do NOT start with a greeting. Get straight to the point.
+          2. Tell the user that the table(s) **#{missing}** could not be found in the indexed schema.
+          3. Suggest they check the schema viewer at `/glancer/db-schema` to see all available tables.
+          4. Keep it to 2 sentences. Respond in the exact same language as the user's question.
+        PROMPT
+
+        chat = RubyLLM.chat(
+          provider: Glancer.configuration.resolved_chat_provider,
+          model: Glancer.configuration.resolved_chat_model,
+          assume_model_exists: true
+        )
+        chat.ask(prompt).content
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("Workflow::LLM", "explain_missing_tables failed: #{e.message}")
+        "Não consegui encontrar a(s) tabela(s) **#{missing}** no schema indexado. " \
+          "Acesse `/glancer/db-schema` para ver todas as tabelas disponíveis e reformule sua pergunta com o nome correto."
+      end
+
+      def self.generate_title(question)
+        chat = RubyLLM.chat(
+          provider: Glancer.configuration.resolved_chat_provider,
+          model: Glancer.configuration.resolved_chat_model,
+          assume_model_exists: true
+        )
+        prompt = "Generate a concise, descriptive title (max 45 characters, no quotes, no punctuation at end) " \
+                 "for a database query session starting with this question: #{question}"
+        chat.ask(prompt).content.strip.truncate(50)
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("Workflow::LLM", "generate_title failed: #{e.message}")
+        question.truncate(45)
+      end
+
+      def self.explain_error(question, error_message, code, mode: :sql)
+        chat = RubyLLM.chat(
+          provider: Glancer.configuration.resolved_chat_provider,
+          model: Glancer.configuration.resolved_chat_model,
+          assume_model_exists: true
+        )
+
+        code_label = mode == :activerecord ? "Ruby/ActiveRecord expression" : "SQL"
+
+        prompt = <<~PROMPT
+          You are **Glancer**. The user asked: "#{question}".
+          We tried to generate a #{code_label} but failed after 3 attempts.
+          Last error: "#{error_message}"
+          Last code attempted: "#{code}"
+
+          Your task:
+          1. Do NOT start with a greeting or salutation (no "Hi", "Hello", "Olá", "Oi", etc.). Get straight to the point.
+          2. Explain briefly what went wrong and why (e.g., "The column 'status' doesn't exist in the 'pages' table").
+          3. Suggest how the user could rephrase or what alternative they can try.
+          4. Keep it concise — 2–3 sentences max.
+          5. Respond in the user's language.
+        PROMPT
+
+        chat.ask(prompt).content
+      end
+    end
+  end
+end

data/lib/glancer/workflow/prompt_builder.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Glancer
+  module Workflow
+    class PromptBuilder
+      def self.custom_instructions_block
+        custom = Glancer::Setting.get("custom_instructions")
+        custom.present? ? "CUSTOM RULES — MUST BE FOLLOWED STRICTLY:\n#{custom}\n" : ""
+      rescue StandardError
+        ""
+      end
+
+      def self.call(question, embeddings, history: [], few_shot_examples: [])
+        Glancer::Utils::Logger.info("Workflow::PromptBuilder", "Building prompt for question: #{question.inspect}")
+
+        now = Time.current.strftime("%Y-%m-%d %H:%M:%S")
+        adapter = Glancer.configuration.resolved_adapter
+        db_name = begin
+          ActiveRecord::Base.connection.current_database
+        rescue StandardError
+          "unknown"
+        end
+
+        Glancer::Utils::Logger.debug("Workflow::PromptBuilder", "Current time: #{now}, Adapter: #{adapter}, DB: #{db_name}")
+
+        history_context = history.map do |msg|
+          if msg.role == "assistant" && msg.code.present?
+            "ASSISTANT (SQL used): #{msg.code.strip}\nASSISTANT (response): #{msg.content}"
+          else
+            "#{msg.role.upcase}: #{msg.content}"
+          end
+        end.join("\n\n")
+
+        schema_context, fk_context = partition_embeddings(embeddings)
+        examples_context = format_few_shot_examples(few_shot_examples)
+
+        prompt = <<~PROMPT
+          Current datetime: #{now}
+          Active Database Adapter: #{adapter}
+          Database Name: #{db_name}
+
+          You are a specialized Ruby on Rails SQL expert.
+          Your only task is to generate a valid SQL SELECT statement based on the provided DATABASE CONTEXT.
+
+          STRICT GUIDELINES:
+          1. **Output**: Return ONLY the SQL query. No explanation, no reasoning text, no markdown prose — just the SQL.
+          2. **No Translations**: NEVER translate table names or column names. Use names EXACTLY as they appear in the schema.
+          3. **SELECT Only**: Only generate SELECT or WITH (CTE) statements. Destructive operations are strictly forbidden.
+          4. **Joins**: Use the SCHEMA RELATIONSHIPS section below to determine correct JOIN conditions.
+          5. **Formatting**: Format SQL with proper indentation and line breaks:
+             - Each major clause (SELECT, FROM, WHERE, JOIN, GROUP BY, ORDER BY, HAVING, LIMIT) on its own line.
+             - Indent selected columns, JOIN conditions, and WHERE predicates with 2 spaces.
+             - Use a new line for each selected column when there are more than 2 columns.
+
+          Think through the query internally before writing it, but your final response must contain SQL only — no surrounding text.
+
+          Rules for generation:
+          - Use **column aliases (AS ...)** to improve readability.
+          - The SQL must be valid and executable for #{adapter.to_s.upcase}.
+          - Always qualify column names with the table name (e.g., `orders.created_at`).
+
+          SCHEMA RELATIONSHIPS:
+          #{fk_context.presence || "(no foreign keys indexed)"}
+
+          #{examples_context.present? ? "EXAMPLE QUERIES (from this database):\n#{examples_context}\n" : ""}
+          CONVERSATION HISTORY:
+          #{history_context.presence || "(no prior messages)"}
+
+          DATABASE CONTEXT:
+          #{format_embeddings_with_stats(schema_context)}
+
+          #{custom_instructions_block}
+          NEW QUESTION:
+          #{question}
+
+          OUTPUT SQL ONLY:
+        PROMPT
+
+        Glancer::Utils::Logger.debug("Workflow::PromptBuilder", "Prompt constructed successfully")
+
+        prompt
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("Workflow::PromptBuilder", "Failed to build prompt: #{e.class} - #{e.message}")
+        Glancer::Utils::Logger.debug("Workflow::PromptBuilder", "Backtrace:\n#{e.backtrace.join("\n")}")
+        raise Glancer::Error, "Prompt construction failed: #{e.message}"
+      end
+
+      def self.example_sql(adapter)
+        case adapter.to_s
+        when "mysql", "mysql2"
+          <<~SQL
+            SELECT
+              DATE_FORMAT(created_at, '%Y-%m') AS mes,
+              COUNT(*) AS total_vendas
+            FROM
+              vendas
+            WHERE
+              YEAR(created_at) = 2025
+            GROUP BY
+              mes
+            ORDER BY
+              mes;
+          SQL
+        when "postgres", "postgresql"
+          <<~SQL
+            SELECT
+              TO_CHAR(created_at, 'YYYY-MM') AS mes,
+              COUNT(*) AS total_vendas
+            FROM
+              vendas
+            WHERE
+              EXTRACT(YEAR FROM created_at) = 2025
+            GROUP BY
+              mes
+            ORDER BY
+              mes;
+          SQL
+        else
+          "-- Example not available for this adapter."
+        end
+      end
+
+      def self.partition_embeddings(embeddings)
+        fk_embeds = embeddings.select { |e| e.source_path.to_s.end_with?("#foreign_keys") }
+        other_embeds = embeddings.reject { |e| e.source_path.to_s.end_with?("#foreign_keys") }
+        fk_text = fk_embeds.map { |e| e.content.strip }.join("\n")
+        [other_embeds, fk_text]
+      end
+
+      def self.format_embeddings_with_stats(embeddings)
+        embeddings.map { |embed| embed.content.strip }.join("\n\n")
+      end
+
+      def self.format_few_shot_examples(examples)
+        return "" if examples.blank?
+
+        examples.each_with_index.map do |(question, sql), i|
+          "Example #{i + 1}:\nQuestion: #{question}\nSQL: #{sql.strip}"
+        end.join("\n\n")
+      end
+    end
+  end
+end

data/lib/glancer/workflow/query_enricher.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Glancer
+  module Workflow
+    class QueryEnricher
+      PROMPT_TEMPLATE = <<~PROMPT
+        You are a database query specification expert. Enrich the user's question into a precise technical specification that a code generator will use to produce correct %<adapter>s code.
+
+        ## Available Tables
+        %<tables>s
+
+        %<schema_context>s%<history>s## User Question
+        "%<question>s"
+
+        ## Your Output
+        Write a dense, unambiguous technical specification in English covering ALL applicable points below. Be concrete — use exact names, operators, and formats.
+
+        **Model/Table**: State the exact model class (PascalCase for ActiveRecord, table name for SQL) involved. Resolve @mention shortcuts to their table names (e.g. @pages → Page model, pages table). Map natural-language synonyms ("records", "entries", "items") to the correct table.
+
+        **Conditions**: Translate relative time expressions into explicit date arithmetic (e.g. "last 6 months" → `created_at >= 6.months.ago.beginning_of_month`). Name every column used in filters.
+
+        **Aggregations**: Name the exact aggregate function and column (COUNT, SUM, AVG, GROUP BY). For time-based grouping, specify the format string (e.g. `TO_CHAR(created_at, 'MM/YYYY')` for month/year, `DATE_TRUNC('month', created_at)` for date truncation). PostgreSQL is the database.
+
+        **Follow-up resolution**: Check RECENT CONVERSATION — if this is a follow-up question, carry forward the same model, columns, and filters from before. Resolve pronouns ("it", "them", "that result") explicitly using context.
+
+        **Output shape**: Describe expected result structure (e.g. "one row per month: columns month as MM/YYYY string, count as integer"). If the result should be sorted, specify direction (chronological ASC unless stated otherwise).
+
+        Output ONLY the specification. English. No code. No preamble. No explanations.
+      PROMPT
+
+      def self.enrich(question, table_names, history: [], adapter: nil)
+        return question if table_names.empty?
+
+        adapter_label    = adapter&.to_s == "activerecord" ? "ActiveRecord Ruby" : "SQL"
+        history_block    = build_history_block(history)
+        schema_ctx       = schema_context_for(question, table_names)
+
+        prompt = format(
+          PROMPT_TEMPLATE,
+          adapter: adapter_label,
+          tables: table_names.join(", "),
+          schema_context: schema_ctx,
+          history: history_block,
+          question: question
+        )
+
+        chat = RubyLLM.chat(
+          provider: Glancer.configuration.resolved_enrichment_provider,
+          model: Glancer.configuration.resolved_enrichment_model,
+          assume_model_exists: true
+        )
+
+        enriched = chat.ask(prompt).content.to_s.strip
+        enriched.presence || question
+      rescue StandardError => e
+        Glancer::Utils::Logger.warn("Workflow::QueryEnricher", "Enrichment failed, using original: #{e.message}")
+        question
+      end
+
+      def self.known_table_names
+        Glancer::Embedding
+          .where(source_type: "schema")
+          .pluck(:source_path)
+          .filter_map do |path|
+            fragment = path.to_s.split("#").last
+            next if fragment.blank? || fragment == "foreign_keys" || fragment.include?("/")
+
+            fragment
+          end
+          .uniq
+      rescue StandardError
+        []
+      end
+
+      def self.build_history_block(history)
+        return "" if history.blank?
+
+        lines = history.last(4).map do |msg|
+          if msg.role == "assistant" && msg.code.present?
+            "#{msg.role.upcase} [#{msg.code_type}: #{msg.code.strip.truncate(120)}]: #{msg.content.truncate(160)}"
+          else
+            "#{msg.role.upcase}: #{msg.content.truncate(200)}"
+          end
+        end.join("\n")
+        "## Recent Conversation\n#{lines}\n\n"
+      end
+      private_class_method :build_history_block
+
+      # Fetches schema embedding content for tables explicitly @mentioned in the question.
+      # Provides the code generator with column names and types for accurate specification.
+      def self.schema_context_for(question, table_names)
+        at_mentioned = question.scan(/@([A-Za-z]\w*)/).flatten
+        relevant = at_mentioned.select { |mention| table_names.any? { |tbl| tbl.casecmp?(mention) } }
+        return "" if relevant.empty?
+
+        rows = Glancer::Embedding
+               .where(source_type: "schema")
+               .where("source_path LIKE '%#%'")
+               .pluck(:source_path, :content)
+
+        matched = relevant.flat_map do |mention|
+          rows.filter_map do |(path, content)|
+            table = path.split("#").last
+            content if table.casecmp?(mention)
+          end
+        end.first(3)
+
+        return "" if matched.empty?
+
+        "## Referenced Schema\n#{matched.join("\n\n")}\n\n"
+      rescue StandardError
+        ""
+      end
+      private_class_method :schema_context_for
+    end
+  end
+end

data/lib/glancer/workflow/sql_extractor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Glancer
+  module Workflow
+    class SQLExtractor
+      SQL_START = /\A\s*(select|with|explain)\b/i
+
+      def self.extract(text)
+        Glancer::Utils::Logger.info("Workflow::SQLExtractor", "Extracting SQL from text response...")
+
+        # Match ```sql, ```SQL, or plain ``` fenced blocks
+        if text =~ /```(?:sql)?\s*\n?(.*?)\s*```/mi
+          sql = ::Regexp.last_match(1).strip
+          Glancer::Utils::Logger.debug("Workflow::SQLExtractor", "Extracted SQL from formatted code block.")
+        else
+          # Fallback: find the first line that looks like the start of a SQL statement
+          # and take everything from there, ignoring leading explanation text.
+          lines = text.lines
+          start_idx = lines.index { |l| l.strip.match?(SQL_START) }
+
+          sql = if start_idx
+                  lines[start_idx..].join.strip
+                else
+                  text.lines.map(&:strip).reject(&:empty?).join(" ")
+                end
+
+          fallback_type = start_idx ? " (SQL found at line #{start_idx})" : " (raw join)"
+          Glancer::Utils::Logger.debug("Workflow::SQLExtractor",
+                                       "No code block found. Fallback extraction#{fallback_type}.")
+        end
+
+        Glancer::Utils::Logger.debug("Workflow::SQLExtractor", "Final extracted SQL:\n#{sql}")
+
+        sql
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("Workflow::SQLExtractor", "SQL extraction failed: #{e.class} - #{e.message}")
+        Glancer::Utils::Logger.debug("Workflow::SQLExtractor", "Backtrace:\n#{e.backtrace.join("\n")}")
+        raise Glancer::Error, "SQL extraction failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/glancer/workflow/sql_sanitizer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Glancer
+  module Workflow
+    class SQLSanitizer
+      FORBIDDEN_KEYWORDS = %w[
+        delete update insert drop truncate alter create replace
+      ].freeze
+
+      def self.ensure_safe!(sql)
+        Glancer::Utils::Logger.info("Workflow::SQLSanitizer", "Sanitizing SQL...")
+
+        cleaned = strip_strings_and_comments(sql.downcase)
+        Glancer::Utils::Logger.debug("Workflow::SQLSanitizer", "Sanitized SQL for inspection:\n#{cleaned}")
+
+        forbidden = FORBIDDEN_KEYWORDS.find { |kw| cleaned.match?(/\b#{kw}\b/) }
+
+        if forbidden
+          Glancer::Utils::Logger.error("Workflow::SQLSanitizer", "Blocked SQL due to forbidden keyword: '#{forbidden}'")
+          raise Glancer::Error, "Query blocked due to forbidden keyword: '#{forbidden}' in SQL: #{sql.inspect}"
+        end
+
+        Glancer::Utils::Logger.info("Workflow::SQLSanitizer", "SQL passed sanitization check.")
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("Workflow::SQLSanitizer", "Sanitization failed: #{e.class} - #{e.message}")
+        Glancer::Utils::Logger.debug("Workflow::SQLSanitizer", "Backtrace:\n#{e.backtrace.join("\n")}")
+        raise Glancer::Error, "SQL sanitization failed: #{e.message}"
+      end
+
+      def self.strip_strings_and_comments(sql)
+        # Remove strings: '...', allowing escaped quotes
+        sql = sql.gsub(/'(?:\\'|[^'])*'/, "")
+
+        # Remove inline comments -- ...
+        sql = sql.gsub(/--.*/, "")
+
+        # Remove block comments /* ... */
+        sql.gsub(%r{/\*.*?\*/}m, "")
+      end
+    end
+  end
+end

data/lib/glancer/workflow/sql_validator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Glancer
+  module Workflow
+    class SQLValidator
+      def self.validate_tables_exist!(sql)
+        Glancer::Utils::Logger.info("Workflow::SQLValidator", "Validating presence of tables in indexed schema...")
+
+        tables_in_sql = extract_table_names(sql)
+        Glancer::Utils::Logger.debug("Workflow::SQLValidator", "Tables found in SQL: #{tables_in_sql.inspect}")
+
+        indexed_tables = indexed_schema_table_names
+        Glancer::Utils::Logger.debug("Workflow::SQLValidator",
+                                     "Tables available in indexed schema: #{indexed_tables.inspect}")
+
+        missing = tables_in_sql.reject do |table|
+          system_table?(table) || indexed_tables.include?(table)
+        end
+
+        if missing.any?
+          Glancer::Utils::Logger.error("Workflow::SQLValidator", "Missing table(s): #{missing.join(", ")}")
+          raise Glancer::Error, "Missing table(s) in indexed schema: #{missing.join(", ")}"
+        end
+
+        Glancer::Utils::Logger.info("Workflow::SQLValidator", "All referenced tables are present in indexed schema.")
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("Workflow::SQLValidator", "Table validation failed: #{e.class} - #{e.message}")
+        Glancer::Utils::Logger.debug("Workflow::SQLValidator", "Backtrace:\n#{e.backtrace.join("\n")}")
+        raise Glancer::Error, "Table validation failed: #{e.message}"
+      end
+
+      def self.extract_table_names(sql)
+        sql.scan(/\bfrom\s+([a-zA-Z0-9_."]+)/i).flatten.map do |name|
+          name.gsub('"', "").downcase.strip
+        end.uniq
+      end
+
+      def self.system_table?(table_name)
+        schema = table_name.include?(".") ? table_name.split(".").first.downcase : table_name
+        system_schemas.include?(schema)
+      end
+
+      def self.indexed_schema_table_names
+        Glancer::Embedding
+          .where(source_type: "schema")
+          .pluck(:source_path)
+          .map { |path| path[/#(.*?)\z/, 1] }
+          .compact
+          .map(&:downcase)
+          .uniq
+      end
+
+      def self.system_schemas
+        case Glancer.configuration.resolved_adapter.to_s
+        when "postgres", "postgresql"
+          %w[information_schema pg_catalog pg_toast]
+        when "mysql", "mysql2"
+          %w[information_schema mysql performance_schema sys]
+        when "sqlite", "sqlite3"
+          %w[sqlite_master]
+        else
+          []
+        end
+      end
+    end
+  end
+end