glancer 1.0.0

data/db/migrate/20260514083509_add_llm_model_to_glancer_messages.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddLlmModelToGlancerMessages < ActiveRecord::Migration[6.1]
+  def change
+    return if column_exists?(:glancer_messages, :llm_model)
+
+    add_column :glancer_messages, :llm_model, :string
+  end
+end

data/db/migrate/20260523120000_rename_code_columns_in_glancer_messages.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class RenameCodeColumnsInGlancerMessages < ActiveRecord::Migration[6.1]
+  def change
+    rename_column :glancer_messages, :sql, :code if column_exists?(:glancer_messages, :sql)
+    rename_column :glancer_messages, :user_edited_sql, :user_edited_code if column_exists?(:glancer_messages, :user_edited_sql)
+  end
+end

data/db/migrate/20260523120001_rename_code_column_in_glancer_audits.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RenameCodeColumnInGlancerAudits < ActiveRecord::Migration[6.1]
+  def change
+    rename_column :glancer_audits, :sql, :code if column_exists?(:glancer_audits, :sql)
+  end
+end

data/db/migrate/20260523120002_add_code_type_to_glancer_tables.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddCodeTypeToGlancerTables < ActiveRecord::Migration[6.1]
+  def change
+    add_column :glancer_messages, :code_type, :string, null: false, default: "sql" unless column_exists?(:glancer_messages, :code_type)
+    return if column_exists?(:glancer_audits, :code_type)
+
+    add_column :glancer_audits, :code_type, :string, null: false, default: "sql"
+  end
+end

data/db/migrate/20260523120003_rename_glancer_sql_versions_to_code_versions.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class RenameGlancerSqlVersionsToCodeVersions < ActiveRecord::Migration[6.1]
+  def change
+    rename_table :glancer_sql_versions, :glancer_code_versions if table_exists?(:glancer_sql_versions)
+    rename_column :glancer_code_versions, :sql, :code if column_exists?(:glancer_code_versions, :sql)
+  end
+end

data/db/migrate/20260523130000_add_enriched_question_to_glancer_messages.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddEnrichedQuestionToGlancerMessages < ActiveRecord::Migration[7.0]
+  def change
+    add_column :glancer_messages, :enriched_question, :text
+  end
+end

data/db/migrate/20260524100000_add_status_to_glancer_messages.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddStatusToGlancerMessages < ActiveRecord::Migration[7.0]
+  def change
+    # 0=pending, 1=processing, 2=complete, 3=failed
+    # default 2 (complete) so existing records are treated as already done.
+    add_column :glancer_messages, :status, :integer, default: 2, null: false
+  end
+end

data/lib/generators/glancer/install/install_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module Glancer
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Installs Glancer: initializer, migrations, and mounts engine"
+
+      def copy_initializer
+        template "glancer.rb", "config/initializers/glancer.rb"
+      end
+
+      def copy_context_file
+        template "llm_context.glancer.md", "config/glancer/llm_context.glancer.md"
+      end
+
+      def mount_engine
+        inject_into_file "config/routes.rb", after: "Rails.application.routes.draw do\n" do
+          "  mount Glancer::Engine => '/glancer'\n"
+        end
+      end
+
+      def show_readme
+        info = "\e[32m"
+        warn = "\e[33m"
+        debug = "\e[36m"
+        error = "\e[31m"
+        reset = "\e[0m"
+
+        say <<~MSG
+
+          #{info}╔════════════════════════════════════════════════════════════════════╗
+          ║                 ✔ Glancer installed successfully! ✔                ║
+          ╚════════════════════════════════════════════════════════════════════╝#{reset}
+
+          #{debug}Next steps:#{reset}
+
+          #{warn}1. Review and customize the configuration:#{reset}
+             ├── File: #{debug}config/initializers/glancer.rb#{reset}
+             └── You can set:
+                 ✔ Adapter
+                 ✔ Read-only DB
+                 ✔ LLM provider
+                 ✔ Logging options
+                 ✔ ...
+
+          #{warn}2. Edit the context file (optional but recommended):#{reset}
+             ├── File: #{debug}config/glancer/llm_context.glancer.md#{reset}
+             ├── Currently ignored (first line is '#{error}--glancer-ignore#{reset}')
+             └── Remove or modify first line to enable indexing.
+                 Use it to describe:
+                 ✔ Business rules
+                 ✔ Table usage
+                 ✔ Domain logic
+                 ✔ ...
+
+          #{warn}3. Apply the database migrations:#{reset}
+             └── Run: #{info}rails db:migrate#{reset}
+
+          #{warn}4. Index your schema, models, and context:#{reset}
+             ├── Run: #{info}rails glancer:index:all#{reset}
+             └── #{info}✱#{reset} Or do it separately
+                 ├── Run: #{info}rails glancer:index:schema#{reset}
+                 ├── Run: #{info}rails glancer:index:context#{reset}
+                 └── Run: #{info}rails glancer:index:models#{reset}
+
+        MSG
+      end
+    end
+  end
+end

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

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+# Glancer configuration
+# Full reference: https://github.com/ernanej/glancer
+
+Glancer.configure do |config|
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Database
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Adapter used to execute queries. Auto-detected from ActiveRecord when nil.
+  # Accepted: :postgres | :mysql | :mysql2 | :sqlite
+  config.adapter = nil
+
+  # Optional read-only replica URL. Queries run against this connection when set.
+  # Accepts a full Rails database URL string or :read_only (uses current connection
+  # in read-only mode).
+  config.read_only_db = nil
+
+  # Maximum time a single query may run before being killed.
+  # PostgreSQL uses SET statement_timeout; MySQL uses SET max_execution_time.
+  # SQLite has no server-side timeout enforcement.
+  config.statement_timeout = 30.seconds
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Query mode
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Controls how Glancer generates and executes database queries.
+  # :sql          — LLM generates a raw SELECT statement (default, most portable)
+  # :activerecord — LLM generates a Ruby/ActiveRecord expression; lets the LLM
+  #                 reuse your model scopes, associations, and named queries
+  config.query_mode = :sql
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Query enrichment
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # When enabled, the user's question is rewritten by a fast LLM before retrieval.
+  # The enricher translates natural-language terms into actual table names so that
+  # the vector search and code-generation steps are more accurate. The original
+  # question is always shown to the user; the final answer is always in the user's
+  # language regardless of what language the enriched question was generated in.
+  config.query_enrichment_enabled = false
+
+  # Provider and model for the enrichment step. Use a cheap, fast model here
+  # (e.g. gemini-2.0-flash, gpt-4o-mini) — it only translates terminology.
+  # When nil, falls back to llm_provider / llm_model.
+  # config.enrichment_provider = :gemini
+  # config.enrichment_model    = "gemini-2.0-flash"
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # LLM — Default provider (fallback for all roles below)
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Default provider for all LLM calls. Used when role-specific providers are nil.
+  # Accepted: :gemini | :openai | :openrouter
+  config.llm_provider = :gemini
+
+  # Default model. Used when role-specific models are nil.
+  #   Gemini:     'gemini-2.0-flash', 'gemini-1.5-pro', ...
+  #   OpenAI:     'gpt-4o', 'gpt-4o-mini', ...
+  #   OpenRouter: 'anthropic/claude-3.5-sonnet', 'openai/gpt-4o', ...
+  config.llm_model = "gemini-2.0-flash"
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # LLM — Code generation (overrides default for query building)
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Provider used for code generation. Nil → falls back to llm_provider.
+  # Useful when you want a code-focused model (e.g. gpt-4o) for query generation
+  # and a cheaper model for responses.
+  # Accepted: nil | :gemini | :openai | :openrouter
+  config.code_provider = nil
+
+  # Model used for code generation. Nil → falls back to llm_model.
+  config.code_model = nil
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # LLM — Chat responses (overrides default for humanized answers)
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Provider used for humanizing results and generating chat responses.
+  # Nil → falls back to llm_provider.
+  # Accepted: nil | :gemini | :openai | :openrouter
+  config.chat_provider = nil
+
+  # Model used for chat responses. Nil → falls back to llm_model.
+  config.chat_model = nil
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # LLM — Embeddings
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Provider used exclusively for generating embeddings (indexing + retrieval).
+  # Defaults to llm_provider when nil.
+  #
+  # IMPORTANT — OpenRouter embedding support:
+  #   OpenRouter does not expose a native embedding API. If you use OpenRouter
+  #   for chat/code generation, set embedding_provider to :gemini or :openai to
+  #   avoid errors. If you must use an OpenRouter embedding model anyway, set
+  #   embedding_model explicitly (e.g., 'openai/text-embedding-3-small') —
+  #   Glancer will bypass the model registry check automatically.
+  #
+  # Accepted: nil | :gemini | :openai | :openrouter
+  config.embedding_provider = nil
+
+  # Embedding model override. When nil, Glancer uses the provider default:
+  #   Gemini:     'text-embedding-004'
+  #   OpenAI:     'text-embedding-3-large'
+  #   OpenRouter: 'openai/text-embedding-3-small'  (must be passed as model ID)
+  config.embedding_model = nil
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # API Keys
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Use provider-specific keys (preferred) or api_key as a generic fallback.
+  config.gemini_api_key = ENV.fetch("GEMINI_API_KEY", nil)
+  # config.openai_api_key     = ENV.fetch('OPENAI_API_KEY', nil)
+  # config.openrouter_api_key = ENV.fetch('OPENROUTER_API_KEY', nil)
+  # config.api_key            = ENV.fetch('LLM_API_KEY', nil)  # generic fallback for any provider
+
+  # ─── Example: different providers per role ──────────────────────────────────
+  # config.llm_provider       = :gemini                              # default fallback
+  # config.llm_model          = 'gemini-2.0-flash'
+  # config.code_provider       = :openai                              # code-focused model for queries
+  # config.code_model          = 'gpt-4o'
+  # config.chat_provider      = :gemini                              # cheaper for chat
+  # config.chat_model         = 'gemini-2.0-flash'
+  # config.embedding_provider = :gemini                              # dedicated embeddings
+  # config.embedding_model    = 'text-embedding-004'
+  # config.gemini_api_key     = ENV.fetch('GEMINI_API_KEY', nil)
+  # config.openai_api_key     = ENV.fetch('OPENAI_API_KEY', nil)
+  # ─── Example: OpenRouter for chat/code gen, Gemini for embeddings (recommended) ──
+  # OpenRouter does not expose a native embedding API, so always pair it with
+  # a dedicated embedding provider (:gemini or :openai).
+  # config.llm_provider       = :openrouter
+  # config.openrouter_api_key = ENV.fetch('OPENROUTER_API_KEY', nil)
+  # config.llm_model          = 'anthropic/claude-3.5-sonnet'
+  # config.code_model          = 'deepseek/deepseek-r1:free'
+  # config.embedding_provider = :gemini
+  # config.gemini_api_key     = ENV.fetch('GEMINI_API_KEY', nil)
+  # config.embedding_model    = 'text-embedding-004'
+  # ───────────────────────────────────────────────────────────────────────────
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Indexing permissions
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Allow Glancer to index db/schema.rb (table and column definitions).
+  config.schema_permission = true
+
+  # Allow Glancer to index app/models/**/*.rb (associations, validations, scopes).
+  config.models_permission = false
+
+  # Path to a Markdown file with domain context: business rules, table aliases,
+  # common query patterns, etc. Add '--glancer-ignore' as the first line to skip.
+  config.context_file_path = "config/glancer/llm_context.glancer.md"
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Chunking (controls how documents are split before embedding)
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Maximum characters per chunk. Smaller chunks are more precise; larger chunks
+  # preserve more context. Default: 1000.
+  config.chunk_size = 1000
+
+  # Characters of overlap between consecutive chunks. Helps prevent context loss
+  # at chunk boundaries. Default: 150 (~15% of chunk_size).
+  config.chunk_overlap = 150
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Retrieval
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Number of top embedding chunks returned per query.
+  config.k = 10
+
+  # Minimum cosine similarity score [0.0–1.0] for a chunk to be included.
+  # Lower values return more results but may include noise.
+  config.min_score = 0.6
+
+  # Relevance multipliers per document type (must be ≥ 1.0).
+  # Higher weight = ranked higher in retrieved context.
+  config.schema_documents_weight = 1.3 # db/schema.rb table definitions
+  config.context_documents_weight = 1.2 # custom context Markdown file
+  config.models_documents_weight = 1.1 # ActiveRecord model files
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Conversation
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Number of past messages included in the prompt for multi-turn context.
+  config.history_limit = 6
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Caching
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # How long identical questions are served from the in-memory cache without
+  # calling the LLM again. Set to 0 to disable. Cache is process-local (not
+  # shared across Puma workers or restarts).
+  config.workflow_cache_ttl = 5.minutes
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Logging
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # File path for Glancer logs. When nil, output goes to Rails.logger / STDOUT.
+  config.log_output_path = nil # e.g. 'log/glancer.log'
+
+  # Log verbosity level.
+  # :none  → silent
+  # :info  → normal operational messages (default)
+  # :debug → verbose, includes prompts and full backtraces
+  config.log_verbosity = :info
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Integrations
+  # ─────────────────────────────────────────────────────────────────────────────
+
+  # Blazer integration: enables an 'Open in Blazer' button on generated queries.
+  # Auto-detected if the blazer gem is installed (defaults to '/blazer').
+  # Set explicitly to override the path, or to '' / nil to disable.
+  # config.blazer_path = '/blazer'
+end

data/lib/generators/glancer/install/templates/llm_context.glancer.md

@@ -0,0 +1,51 @@
+--glancer-ignore
+
+# Glancer LLM Context Template
+#
+# This file lets you define custom business rules, domain logic,
+# naming conventions, and assumptions about your data model
+# that the language model should take into account when answering questions.
+
+## How It Works
+
+- These rules and notes will be embedded and used as retrieval context.
+- They **do not need to be machine-parsable** — use natural language.
+- Be specific and concise. Avoid redundant or vague information.
+
+## Business Rules
+
+- "Users with role = 'admin' are considered system administrators."
+- "sales" table is very large, avoid bringing everything. Always filter by period of 30 days to 1 year
+- "Orders with status = 'cancelled' should not be counted in sales totals."
+- "Only 'paid' invoices should be considered for revenue aggregation."
+- "Products may belong to multiple categories via `product_categories` join table."
+
+## Domain Definitions
+
+- "`vendas` = sales"
+- "`usuarios` = users or system operators"
+- "`filiais` = branches or physical offices"
+- "A `lead` represents a potential customer, not yet converted to a client."
+
+## Special Table Considerations
+
+- "`users` table stores authentication data and personal details. Use with care."
+- "`clients_blacklists` table indicates blocked clients; should be checked before allowing new orders."
+- "`blazer_*` tables are internal and should be ignored."
+
+## Common Query Patterns
+
+- "When grouping by month, use the `created_at` column, unless otherwise specified."
+- "Default date range for metrics is the last 30 days unless the question says otherwise."
+
+## Output Expectations
+
+- "Always alias columns using `AS` with a human-readable label."
+- "All queries should return fields in snake_case."
+- "Include rows with zero results when grouping by time (use LEFT JOINs or CTEs if needed)."
+
+## 📝 Notes
+
+- You can add Markdown formatting here, but it's optional.
+- Keep this file short and relevant. Avoid dumping full tables or schemas here.
+- This file is **ignored** by Glancer indexing unless you remove the `--glancer-ignore` line.

data/lib/glancer/async_runner.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Glancer
+  # Runs message processing in a background thread without relying on the host
+  # app's Active Job queue adapter. Checks out a dedicated database connection
+  # for the thread and releases it when done, regardless of success or failure.
+  module AsyncRunner
+    def self.call(message_id, question)
+      Thread.new do
+        ActiveRecord::Base.connection_pool.with_connection do
+          run(message_id, question)
+        end
+      rescue StandardError => e
+        Glancer::Utils::Logger.error("AsyncRunner", "Thread raised outside job: #{e.message}")
+      end
+    end
+
+    def self.run(message_id, question)
+      message = Glancer::Message.find(message_id)
+      chat    = message.chat
+
+      message.update!(status: :processing)
+
+      result     = Glancer::Workflow.run(chat.id, question)
+      cfg        = Glancer.configuration
+      used_model = "#{cfg.resolved_chat_provider}/#{cfg.resolved_chat_model}"
+
+      message.update!(
+        content: result[:content].to_s,
+        code: result[:code],
+        code_type: result[:code_type] || "sql",
+        successful: result[:successful],
+        llm_model: used_model,
+        enriched_question: result[:enriched_question],
+        status: :complete
+      )
+
+      message.code_versions.create!(code: message.code, source: :generated) if message.code.present?
+
+      chat.update!(title: Glancer::Workflow::LLM.generate_title(question)) if chat.messages.where(role: :user).count == 1
+    rescue StandardError => e
+      Glancer::Utils::Logger.error("AsyncRunner", "Failed for message #{message_id}: #{e.message}")
+      begin
+        message&.update!(content: e.message, successful: false, status: :failed)
+      rescue StandardError => update_error
+        Glancer::Utils::Logger.error("AsyncRunner", "Could not mark message as failed: #{update_error.message}")
+      end
+    end
+  end
+end