sql-chatbot-rails 1.0.0

data/lib/sql_chatbot/grammar/entity_candidates.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "sql_chatbot/grammar/registry"
+
+module SqlChatbot
+  module Grammar
+    module EntityCandidates
+      # Score an entity against the question.
+      # Tokenizes name on '_' so e.g. `projects_project` token "project" matches
+      # the question "how many projects". Tie-breakers: fewer name segments,
+      # then higher row count.
+      def self.score_entity(question, entity, registry)
+        q = question.to_s.downcase
+        singular = entity.name.to_s.downcase
+        plural = entity.table.to_s.downcase
+        score = 0
+
+        score += 12 if q.include?(" #{singular} ") || q.start_with?("#{singular} ") || q.end_with?(" #{singular}")
+        score += 10 if q.include?(plural)
+        score += 5 if q.include?(singular)
+
+        registry.aliases.each do |alias_term, target|
+          next unless target == entity.name
+          score += 8 if q.include?(alias_term.to_s.downcase)
+        end
+
+        # Token-level matching for compound names like `projects_project`.
+        tokens = singular.split("_").select { |t| t.length >= 3 }
+        tokens.each do |tok|
+          tok_plural = pluralize_simple(tok)
+          if q =~ /\b(#{Regexp.escape(tok)}|#{Regexp.escape(tok_plural)})\b/
+            score += 4
+          end
+        end
+
+        # Whitespace-collapsed match — length-weighted so longer matches win.
+        q_compact = q.gsub(/\s+/, "")
+        best_len = 0
+        tokens.each do |tok|
+          next if tok.length < 5
+          [tok, pluralize_simple(tok)].each do |c|
+            best_len = c.length if q_compact.include?(c) && c.length > best_len
+          end
+        end
+        score += best_len
+
+        # Fuzzy match for typos. Two-tier — aliases first (strongest signal,
+        # same tier as exact-alias just approximate), then name/plural/tokens
+        # (weaker — tokens are shared across many entities in compound-named
+        # schemas like Saleor's `product_product` / `product_category`).
+        # 4-char threshold catches "usrs" → "users" while rejecting 3-char
+        # noise ("lon" → "log"). Distance ≤ 25% of length further filters.
+        fuzzy_min_len = 4
+        if score == 0
+          alias_targets = []
+          registry.aliases.each do |alias_term, target|
+            next unless target == entity.name
+            alias_targets << alias_term.to_s.downcase if alias_term.to_s.length >= fuzzy_min_len
+          end
+          name_targets = []
+          name_targets << singular if singular.length >= fuzzy_min_len
+          name_targets << plural   if plural.length >= fuzzy_min_len
+          tokens.each do |tok|
+            next if tok.length < fuzzy_min_len
+            name_targets << tok
+            tp = pluralize_simple(tok)
+            name_targets << tp if tp.length >= fuzzy_min_len
+          end
+
+          words = q.split(/\W+/).select { |w| w.length >= fuzzy_min_len }
+          # Aliases first — score 5
+          words.each do |word|
+            alias_targets.each do |t|
+              d = levenshtein(word, t)
+              next if d == 0
+              max = [word.length, t.length].max
+              if d <= 2 && d.to_f / max <= 0.25
+                return [5, { typed: word, corrected: t }]
+              end
+            end
+          end
+          # Then name/tokens — score 3
+          words.each do |word|
+            name_targets.each do |t|
+              d = levenshtein(word, t)
+              next if d == 0
+              max = [word.length, t.length].max
+              if d <= 2 && d.to_f / max <= 0.25
+                return [3, { typed: word, corrected: t }]
+              end
+            end
+          end
+        end
+
+        [score, nil]
+      end
+
+      # Damerau-Levenshtein edit distance: insertions, deletions, substitutions,
+      # and adjacent transpositions. Transposition counted as 1 (vs 2 in plain
+      # Levenshtein) because keyboard typos like "lables" ↔ "labels" are
+      # extremely common and should match at distance 1.
+      def self.levenshtein(a, b)
+        return 0 if a == b
+        return b.length if a.empty?
+        return a.length if b.empty?
+        n = b.length
+        prev2 = Array.new(n + 1, 0)
+        prev = (0..n).to_a
+        curr = Array.new(n + 1, 0)
+        (1..a.length).each do |i|
+          curr[0] = i
+          (1..n).each do |j|
+            cost = (a[i - 1] == b[j - 1]) ? 0 : 1
+            v = [prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost].min
+            if i > 1 && j > 1 && a[i - 1] == b[j - 2] && a[i - 2] == b[j - 1]
+              v = [v, prev2[j - 2] + 1].min
+            end
+            curr[j] = v
+          end
+          prev2, prev, curr = prev, curr, prev2
+        end
+        prev[n]
+      end
+
+      def self.pluralize_simple(word)
+        return word + "es" if word.end_with?("s", "x", "ch", "sh")
+        return word[0..-2] + "ies" if word.end_with?("y") && !%w[a e i o u].include?(word[-2])
+        word + "s"
+      end
+
+      def self.name_segments(entity)
+        entity.name.to_s.split("_").length
+      end
+
+      def self.select(question:, registry:, top_n:)
+        select_with_meta(question: question, registry: registry, top_n: top_n).map { |row| row[:entity] }
+      end
+
+      # Returns rows of `{ entity:, score:, fuzzy_match: nil|{typed:,corrected:} }`.
+      # Used by the intent-extractor prompt to tell the LLM "the user word
+      # `<typo>` is likely a typo of `<entity>`" so it commits to the
+      # candidate instead of returning unmatched on a stray typo.
+      def self.select_with_meta(question:, registry:, top_n:)
+        rows = registry.entities.values.map do |entity|
+          score, fuzzy = score_entity(question, entity, registry)
+          {
+            entity: entity,
+            score: score,
+            fuzzy_match: fuzzy,
+            segments: name_segments(entity),
+            row_count: entity.row_count,
+          }
+        end
+
+        rows.sort_by! { |r| [-r[:score], r[:segments], -r[:row_count]] }
+
+        if rows.first && rows.first[:score] == 0
+          return registry.entities.values.sort_by { |e| -e.row_count }.first(top_n).map do |entity|
+            { entity: entity, score: 0, fuzzy_match: nil }
+          end
+        end
+
+        # When a typed word has a strong alias-fuzzy resolution (score 5),
+        # drop OTHER candidates that scored only via a weaker token-fuzzy
+        # match on the same typed word — they represent unrelated tables
+        # whose presence in the prompt tempts the LLM to override the
+        # resolution.
+        strong = {}
+        rows.each do |r|
+          if r[:fuzzy_match] && r[:score] == 5
+            strong[r[:fuzzy_match][:typed]] = true
+          end
+        end
+        filtered =
+          if strong.empty?
+            rows
+          else
+            rows.reject { |r| r[:fuzzy_match] && r[:score] == 3 && strong[r[:fuzzy_match][:typed]] }
+          end
+
+        # V1.3-R: alternate-suppression when a primary clearly dominates.
+        # Mirror of TS selectEntityCandidatesWithMeta. When the top entity
+        # has a strong alias/name match (score ≥ 8), drop alternates whose
+        # score is at most half the primary's. Keeps the LLM focused on the
+        # right binding instead of weighing distractor token matches.
+        primary_dominance_floor = 8
+        alternate_keep_ratio = 0.5
+        top = filtered.first
+        if top && top[:score] >= primary_dominance_floor
+          cutoff = top[:score] * alternate_keep_ratio
+          filtered = filtered.each_with_index.reject { |r, i| i > 0 && r[:score] <= cutoff }.map(&:first)
+        end
+
+        # Dedup fuzzy_match annotation per typed word.
+        claimed = {}
+        filtered.first(top_n).map do |r|
+          fuzzy = r[:fuzzy_match]
+          if fuzzy
+            if claimed[fuzzy[:typed]]
+              fuzzy = nil
+            else
+              claimed[fuzzy[:typed]] = true
+            end
+          end
+          { entity: r[:entity], score: r[:score], fuzzy_match: fuzzy }
+        end
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/intent_extractor.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+require "sql_chatbot/grammar/entity_candidates"
+
+module SqlChatbot
+  module Grammar
+    module IntentExtractor
+      PRIMITIVE_DESCRIPTIONS = <<~TEXT.strip
+        COUNT — how many rows of X
+        LIST — show/list rows of X
+        SUM — total of numeric field on X
+        AVG — average of numeric field on X
+        MIN_MAX — lowest/highest value of field on X
+        TOP_N — top N rows of X ordered by a ranking field
+        RANK — window-ranked rows of X within groups
+      TEXT
+
+      MODIFIER_DESCRIPTIONS = <<~TEXT.strip
+        where     — filter by a field value (op: eq/neq/lt/lte/gt/gte/like/in)
+                    shape: {"kind":"where","field":"<col>","op":"<op>","value":<lit>}
+        time      — filter by time window on a timestamp field
+                    shape: {"kind":"time","field":"<timestamp_col>","window":"<keyword>"}
+                    windows: today | yesterday | last_7_days | last_30_days | this_week | this_month | this_year
+        join      — include a related entity via association
+                    shape: {"kind":"join","association":"<assoc_name>"}
+        group_by  — group results by field
+                    shape: {"kind":"group_by","field":"<col>"}
+        having    — filter grouped results by aggregate op+value
+        order_by  — order results by field
+                    shape: {"kind":"order_by","field":"<col>","direction":"asc|desc"}
+        limit     — cap result count
+                    shape: {"kind":"limit","value":<int>}
+        distinct  — deduplicate rows
+                    shape: {"kind":"distinct"}
+        scope     — apply a named scope from the entity. Use this when the user's word
+                    matches an entity scope name; the grammar compiles the filter for you.
+                    shape: {"kind":"scope","name":"<scope_name>"}
+      TEXT
+
+      # call_llm: a proc/lambda taking Array<Hash{role:, content:}> and returning the raw LLM string.
+      # Returns a Hash with :status and related keys (mirrors TS Intent discriminated union).
+      def self.extract(question:, registry:, history:, call_llm:, confidence_threshold: 0.7)
+        candidates = EntityCandidates.select_with_meta(question: question, registry: registry, top_n: 5)
+        messages = [
+          { role: "system", content: build_system_prompt },
+          { role: "user", content: build_user_prompt(question, candidates, history) },
+        ]
+        raw =
+          begin
+            call_llm.call(messages)
+          rescue => e
+            return { status: "unmatched", confidence: 0, reason: "llm_error: #{e.message}" }
+          end
+
+        parsed =
+          begin
+            JSON.parse(raw)
+          rescue JSON::ParserError
+            return { status: "unmatched", confidence: 0, reason: "malformed_json" }
+          end
+
+        if parsed["status"] == "unmatched"
+          return {
+            status: "unmatched",
+            confidence: parsed["confidence"] || 0,
+            reason: parsed["reason"] || "unmatched",
+          }
+        end
+
+        conf = parsed["confidence"]
+        if !conf.is_a?(Numeric) || conf < confidence_threshold
+          return { status: "unmatched", confidence: conf || 0, reason: "low_confidence:#{conf}" }
+        end
+
+        # V1.3-R: validate that the LLM's chosen entity is actually in the
+        # candidate set we showed it. See TS extractIntent for rationale.
+        if parsed["entity"].is_a?(String)
+          candidate_names = Set.new
+          candidates.each do |c|
+            candidate_names << c[:entity].name
+            registry.aliases.each do |alias_term, target|
+              candidate_names << alias_term if target == c[:entity].name
+            end
+          end
+          unless candidate_names.include?(parsed["entity"])
+            return {
+              status: "unmatched",
+              confidence: conf,
+              reason: "entity_not_in_candidates: '#{parsed["entity"]}' not among #{candidate_names.first(5).to_a.join(", ")}",
+            }
+          end
+        end
+
+        # Normalize keys to symbols for consumers
+        {
+          status: "matched",
+          primitive: parsed["primitive"]&.to_sym,
+          entity: parsed["entity"],
+          modifiers: (parsed["modifiers"] || []).map { |m| m.transform_keys(&:to_sym) },
+          field: parsed["field"],
+          which: parsed["which"]&.to_sym,
+          n: parsed["n"],
+          rank_field: parsed["rankField"] || parsed["rank_field"],
+          group_by: parsed["groupBy"] || parsed["group_by"],
+          confidence: conf,
+        }.compact
+      end
+
+      def self.build_system_prompt
+        <<~PROMPT.strip
+          You are an intent classifier for a SQL chatbot. Given a user question and a list of available entities, extract a structured intent.
+
+          Primitives:
+          #{PRIMITIVE_DESCRIPTIONS}
+
+          Modifiers:
+          #{MODIFIER_DESCRIPTIONS}
+
+          You MUST output JSON. If the question doesn't fit any primitive cleanly, set status=unmatched.
+
+          Output shape — generic placeholders, fill in real values from the candidates:
+          - COUNT: {"status":"matched","primitive":"COUNT","entity":"<E>","modifiers":[],"confidence":0.9}
+          - LIST:  {"status":"matched","primitive":"LIST","entity":"<E>","modifiers":[],"confidence":0.9}
+          - SUM:   {"status":"matched","primitive":"SUM","entity":"<E>","field":"<numeric_col>","modifiers":[],"confidence":0.9}
+          - AVG:   {"status":"matched","primitive":"AVG","entity":"<E>","field":"<numeric_col>","modifiers":[],"confidence":0.9}
+          - MIN_MAX: {"status":"matched","primitive":"MIN_MAX","entity":"<E>","field":"<numeric_col>","which":"MAX","modifiers":[],"confidence":0.9}
+          - TOP_N: {"status":"matched","primitive":"TOP_N","entity":"<E>","rankField":"<numeric_col>","n":5,"modifiers":[],"confidence":0.9}
+          - unmatched: {"status":"unmatched","confidence":0.3,"reason":"<short reason>"}
+
+          SUM/AVG/MIN_MAX REQUIRE a "field" slot (a top-level "field" key, not inside modifiers).
+          TOP_N REQUIRES a "rankField" (a top-level "rankField" key, not an order_by modifier).
+          Pick "<E>" by reading the entity candidates — never invent a name. Pluralized
+          forms in the user's question ("orders", "users") map to the singular entity
+          name from the candidates list.
+
+          Casual phrasing maps to primitives like this (use the same patterns when the user speaks informally):
+          - "stuff we got" / "what we have" / "show me X" → LIST X
+          - "how many", "count of", "number of" → COUNT
+          - "biggest" / "largest" / "top" / "smallest" / "lowest" / "least" → TOP_N (returns the row with name + value). Use TOP_N for ANY question asking for an entity (a row) ranked by some field — even when n=1 ("smallest repo", "biggest order"). For ASC ranking, set order_by direction=asc; for DESC, direction=desc.
+          - MIN_MAX is ONLY for questions asking for the VALUE of an aggregate, not the row. "what's the highest price?" → MIN_MAX of price. "biggest order" → TOP_N of orders (the user wants the row, not just a number).
+          - "how's the team doing" / "how are things looking" → unmatched (vague — no clear primitive)
+
+          Rules:
+          - Only reference entities from the provided candidates. Never invent.
+          - Only use fields listed under the chosen entity.
+          - For enum filters, pass the enum key (e.g. "active"), NOT the underlying integer.
+          - When the user's word matches an enum-value KEY of any field on the chosen entity (case-insensitive), bind it via a "where" modifier with op:"eq" and value:"<the-key>". Example: user says "urgent" and field priority_id has enum={"Urgent":4,...} → emit {"kind":"where","field":"priority_id","op":"eq","value":"Urgent"}.
+          - When the user's word matches a scope name listed under the entity, prefer a {"kind":"scope","name":"<name>"} modifier over reconstructing the scope's filter manually. The grammar already knows how to compile the scope.
+          - Set confidence honestly: 0.9+ only when every slot has a clear mapping. If the question is vague and you're guessing the entity or aggregation, return unmatched.
+          - ENTITY-BINDING RULE: If a user word matches the canonical name OR any listed alias of exactly one candidate entity, the entity IS bound. Commit to a primitive — default to COUNT for "any/how many/got any" phrasings and LIST for "show me/list/which". Do NOT return unmatched just because the question is casual; the alias resolved the ambiguity. The "When in doubt, return unmatched" rule applies to ambiguous PRIMITIVES (e.g., "what's up with X"), not to ambiguous ENTITIES — entity ambiguity is already resolved by the candidate set.
+          - PRIMARY MATCH RULE: When a candidate is annotated "[PRIMARY MATCH — prefer this entity ...]", use that entity unless the question explicitly names something only a different candidate has. Do NOT pick a non-primary candidate just because it has more rows or a more specific token match — the scorer already weighed those factors. Example: "smallest repo" with the "repository" entity marked PRIMARY (alias match) and "repo_unit" as alternate (token match) → pick "repository". The user said "repo", and "repo" is the alias of "repository".
+          - When a candidate is annotated with "fuzzy-matched from '<typo>' → '<entity>'", the entity has already been chosen as the resolution for that typed word. Use this entity at confidence ≥ 0.85. Do NOT pick a different candidate just because its name appears to contain the user's word — unrelated tables (audit logs, bot tables, event tables) can have similar names. The fuzzy resolution was done before you saw these candidates.
+          - For any time phrasing ("today", "yesterday", "last 7 days", "last week", "this week", "last month", "this year", etc.), use a "time" modifier with a named window. NEVER put a literal date string OR a window keyword into a "where" modifier value — both produce broken SQL. Supported windows: today, yesterday, last_7_days, last_30_days, this_week, this_month, this_year. The "time" modifier shape is {"kind":"time","field":"<timestamp_col>","window":"<keyword>"} — do NOT use "value" instead of "window", and ALWAYS include "field". If the user names a window not in this list, return unmatched.
+          - When in doubt, return unmatched.
+        PROMPT
+      end
+
+      def self.build_user_prompt(question, candidates, history)
+        history_text = (history || []).last(2).map { |m| "#{m[:role] || m['role']}: #{m[:content] || m['content']}" }.join("\n")
+        # Mark the top candidate PRIMARY when there's more than one. Mirror
+        # of TS buildUserPrompt — see comments there for the rationale.
+        entity_blocks = candidates.each_with_index.map { |c, i| format_entity_brief(c, i.zero? && candidates.length > 1) }.join("\n\n")
+        "History:\n#{history_text}\n\nEntity candidates:\n#{entity_blocks}\n\nQuestion: #{question}"
+      end
+
+      def self.format_entity_brief(candidate, is_primary = false)
+        e = candidate[:entity]
+        fields = e.fields.first(15).map do |n, f|
+          enum_part = f.enum_values ? " enum=#{JSON.generate(f.enum_values)}" : ""
+          "  #{n}: #{f.type}#{enum_part}"
+        end.join("\n")
+        assocs = e.associations.keys.first(8).join(", ")
+        assocs = "(none)" if assocs.empty?
+        scope_names = e.scopes.keys.first(8)
+        scopes_text =
+          if scope_names.any?
+            %(Scopes (when a user word matches one of these names, emit {"kind":"scope","name":"<name>"} as a modifier): #{scope_names.join(", ")})
+          else
+            "Scopes: (none)"
+          end
+        fuzzy_hint = candidate[:fuzzy_match] ?
+          %(\nNOTE: fuzzy-matched from "#{candidate[:fuzzy_match][:typed]}" → "#{candidate[:fuzzy_match][:corrected]}" (treat the user word as a typo of this entity).) :
+          ""
+        primary_marker = is_primary ? "  [PRIMARY MATCH — prefer this entity unless the question explicitly names a different one]\n" : ""
+        "Entity: #{e.name} (table=#{e.table}, rows=#{e.row_count})#{fuzzy_hint}\n#{primary_marker}Fields:\n#{fields}\nAssociations: #{assocs}\n#{scopes_text}"
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/list_renderer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "sql_chatbot/grammar/count_renderer"
+
+module SqlChatbot
+  module Grammar
+    # Programmatic renderer for the grammar's LIST primitive when the result
+    # is small. Bypasses the answer-stream LLM so it can't drop or truncate.
+    module ListRenderer
+      THRESHOLD = 10
+
+      PREFERRED_LABEL_KEYS = %w[title name label subject email username].freeze
+
+      # Returns { ok: true, text: "..." } when conditions met, else { ok: false }.
+      def self.try_render(primitive, entity_display_label, rows)
+        return { ok: false } unless primitive.to_s == "LIST"
+        return { ok: false } unless rows.is_a?(Array)
+        return { ok: true, text: ProgrammaticRenderer.empty_text(entity_display_label) } if rows.empty?
+        return { ok: false } if rows.length > THRESHOLD
+
+        labels = []
+        rows.each do |row|
+          return { ok: false } unless row.is_a?(Hash)
+          lbl = pick_label(row)
+          return { ok: false } unless lbl
+          labels << lbl
+        end
+
+        label_or_item = entity_display_label.to_s.empty? ? "item" : entity_display_label.to_s
+        noun = rows.length == 1 ? CountRenderer.to_singular_label(label_or_item) : CountRenderer.to_plural_label(label_or_item)
+
+        intro = rows.length == 1 ? "Here is the #{noun}:" : "Here are the #{rows.length} #{noun}:"
+        lines = labels.map { |l| "- #{l}" }.join("\n")
+        { ok: true, text: "#{intro}\n#{lines}" }
+      end
+
+      def self.pick_label(row)
+        PREFERRED_LABEL_KEYS.each do |k|
+          v = row[k] || row[k.to_sym]
+          return v.strip if v.is_a?(String) && !v.strip.empty?
+        end
+        row.each do |k, v|
+          next if k.to_s == "id"
+          return v.strip if v.is_a?(String) && !v.strip.empty?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/miss_logger.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+
+module SqlChatbot
+  module Grammar
+    module MissLogger
+      def self.log(log_path, entry)
+        FileUtils.mkdir_p(File.dirname(log_path))
+        line = JSON.generate({ ts: Time.now.utc.iso8601 }.merge(entry)) + "\n"
+        File.open(log_path, "a") { |f| f.write(line) }
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/modifiers.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "sql_chatbot/grammar/registry"
+require "sql_chatbot/grammar/primitives"
+
+module SqlChatbot
+  module Grammar
+    module Modifiers
+      def self.q(name)
+        Primitives.q(name)
+      end
+
+      def self.qc(table, col)
+        Primitives.qc(table, col)
+      end
+
+      WINDOWS = {
+        "today"       => "DATE_TRUNC('day', NOW())",
+        "yesterday"   => "DATE_TRUNC('day', NOW() - INTERVAL '1 day')",
+        "last_7_days" => "NOW() - INTERVAL '7 days'",
+        "last_30_days" => "NOW() - INTERVAL '30 days'",
+        "this_week"   => "DATE_TRUNC('week', NOW())",
+        "this_month"  => "DATE_TRUNC('month', NOW())",
+        "this_year"   => "DATE_TRUNC('year', NOW())",
+      }.freeze
+
+      OPS = {
+        "eq"  => "=",
+        "neq" => "!=",
+        "lt"  => "<",
+        "lte" => "<=",
+        "gt"  => ">",
+        "gte" => ">=",
+      }.freeze
+
+      def self.apply(sql, modifier, entity)
+        kind = modifier[:kind].to_s
+        case kind
+        when "where"    then apply_where(sql, modifier, entity)
+        when "time"     then apply_time(sql, modifier, entity)
+        when "join"     then apply_join(sql, modifier, entity)
+        when "group_by" then apply_group_by(sql, modifier, entity)
+        when "having"   then apply_having(sql, modifier, entity)
+        when "order_by" then apply_order_by(sql, modifier, entity)
+        when "limit"    then apply_limit(sql, modifier)
+        when "distinct" then sql.sub(/^SELECT /, "SELECT DISTINCT ")
+        else
+          raise "unknown modifier kind #{kind}"
+        end
+      end
+
+      def self.append_clause(sql, clause)
+        if /\bWHERE\b/i.match?(sql)
+          "#{sql} AND #{clause}"
+        else
+          "#{sql} WHERE #{clause}"
+        end
+      end
+
+      def self.apply_where(sql, modifier, entity)
+        field_name = modifier[:field].to_s
+        field = entity.fields[field_name]
+        raise "field '#{field_name}' not on entity #{entity.name}" unless field
+
+        value = modifier[:value]
+        ftype = field.type.to_s
+        if ftype == "enum"
+          enum_values = field.enum_values || {}
+          str_value = value.to_s
+          unless enum_values.key?(str_value) || enum_values.key?(str_value.to_sym)
+            raise "enum value '#{value}' not in registry for #{entity.name}.#{field_name}"
+          end
+          value = enum_values[str_value] || enum_values[str_value.to_sym]
+        elsif (ftype == "int" || ftype == "decimal") && value.is_a?(String) && value !~ /\A-?\d+(\.\d+)?\z/
+          raise "type mismatch: #{ftype} column #{entity.name}.#{field_name} cannot equal string '#{value}'"
+        elsif ftype == "bool" && value.is_a?(String) && value !~ /\A(true|false|t|f|0|1)\z/i
+          raise "type mismatch: bool column #{entity.name}.#{field_name} cannot equal string '#{value}'"
+        end
+
+        op = OPS[modifier[:op].to_s] || "="
+        formatted = value.is_a?(String) ? "'#{value.gsub("'", "''")}'" : value
+        append_clause(sql, "#{qc(entity.table, field_name)} #{op} #{formatted}")
+      end
+
+      def self.apply_time(sql, modifier, entity)
+        window_key = modifier[:window].to_s
+        expr = WINDOWS[window_key]
+        raise "unknown time window #{window_key}" unless expr
+        append_clause(sql, "#{qc(entity.table, modifier[:field])} >= #{expr}")
+      end
+
+      def self.apply_join(sql, modifier, entity)
+        assoc_name = modifier[:association].to_s
+        assoc = entity.associations[assoc_name]
+        raise "association '#{assoc_name}' not on entity #{entity.name}" unless assoc
+
+        join_clause = assoc.join_clause
+        # Re-emit the join clause with quoted identifiers.
+        # joinClause format: "src_table.src_col = tgt_table.tgt_col"
+        lhs, rhs = join_clause.split("=").map(&:strip)
+        lt, lc = lhs.split(".")
+        rt, rc = rhs.split(".")
+        target_table = rt
+        quoted_clause = "#{qc(lt, lc)} = #{qc(rt, rc)}"
+        join_sql = " JOIN #{q(target_table)} ON #{quoted_clause}"
+
+        if /\bWHERE\b/i.match?(sql)
+          sql.sub(/\bWHERE\b/i) { "#{join_sql} WHERE " }
+        else
+          "#{sql}#{join_sql}"
+        end
+      end
+
+      def self.apply_group_by(sql, modifier, entity)
+        field_name = modifier[:field].to_s
+        raise "group_by field '#{field_name}' not on entity #{entity.name}" unless entity.fields[field_name]
+        "#{sql} GROUP BY #{qc(entity.table, field_name)}"
+      end
+
+      def self.apply_having(sql, modifier, entity)
+        raise "HAVING requires GROUP BY" unless /GROUP BY/i.match?(sql)
+        op = OPS[modifier[:op].to_s] || "="
+        "#{sql} HAVING #{modifier[:field]} #{op} #{modifier[:value]}"
+      end
+
+      def self.apply_order_by(sql, modifier, entity)
+        field_name = modifier[:field].to_s
+        raise "order_by field '#{field_name}' not on entity #{entity.name}" unless entity.fields[field_name]
+        # The intent extractor LLM emits direction as either `direction` or
+        # `op` (it's prompted with the where-modifier shape and reuses `op`).
+        direction = (modifier[:direction] || modifier["direction"] || modifier[:op] || modifier["op"] || "desc").to_s.upcase
+        "#{sql} ORDER BY #{qc(entity.table, field_name)} #{direction}"
+      end
+
+      def self.apply_limit(sql, modifier)
+        limit_val = modifier[:value]
+        if /LIMIT \d+/i.match?(sql)
+          sql.sub(/LIMIT \d+/i, "LIMIT #{limit_val}")
+        else
+          "#{sql} LIMIT #{limit_val}"
+        end
+      end
+    end
+  end
+end