your_ai_insight 1.0.7

data/app/services/your_ai_insight/claude_service.rb

@@ -0,0 +1,175 @@
+require "httparty"
+
+module YourAiInsight
+  class ClaudeService
+    include HTTParty
+    base_uri "https://api.anthropic.com"
+
+    SYSTEM_PROMPT = <<~PROMPT.freeze
+      You are an expert facility management analyst for AllPro IFM.
+      You have deep knowledge of construction/facility jobs, subcontractor management,
+      vendor bids, budget tracking, compliance, and location-based operations.
+
+      Terminology used in this system:
+      - "Jobs" = facility work orders / projects
+      - "Tasks" = line items within a job (each has a vendor/subcontractor, budget, actual cost)
+      - "Bids" = vendor quotes submitted for tasks
+      - "Budget Requests" = internal approval requests for budget increases
+      - "Expenses" = costs logged against jobs or tasks
+      - "Location Budgets" = monthly budgets allocated per location by trade/category/area
+      - "Locations" = physical facility sites belonging to customers
+      - "Customers" = clients who own one or more locations
+      - "Vendors" = subcontractors who perform task work
+      - "Pay Requests" = payment submissions from vendors after task completion
+
+      Response guidelines:
+      - Lead with the most critical or actionable finding
+      - Use markdown: ## headings, **bold** metrics, bullet points
+      - For compliance: prefix critical items with ⚠️ CRITICAL, warnings with ⚡ WARNING
+      - For dashboards: include an Overall Health Score (0-100) at the top
+      - Always end with 3-5 concrete Recommended Actions
+      - Be concise — executives read this, not engineers
+    PROMPT
+
+    def initialize
+      @api_key = YourAiInsight.config.anthropic_api_key ||
+                 ENV["ANTHROPIC_API_KEY"] ||
+                 raise(ConfigurationError, "Set YourAiInsight.configure { |c| c.anthropic_api_key = ENV['ANTHROPIC_API_KEY'] }")
+      @model      = YourAiInsight.config.claude_model
+      @max_tokens = YourAiInsight.config.max_tokens
+    end
+
+    # Free-form chat with optional live data context injected
+    def chat(user_message, context: {})
+      messages = [{
+        role:    "user",
+        content: [context_block(context), user_message].reject(&:blank?).join("\n\n")
+      }]
+      call_api(messages)
+    end
+
+    # Structured report generation
+    def generate_report(report_type, data)
+      messages = [{ role: "user", content: report_prompt(report_type, data) }]
+      call_api(messages)
+    end
+
+    private
+
+    def call_api(messages)
+      response = self.class.post(
+        "/v1/messages",
+        headers: {
+          "x-api-key"         => @api_key,
+          "anthropic-version" => "2023-06-01",
+          "content-type"      => "application/json"
+        },
+        body: {
+          model:      @model,
+          max_tokens: @max_tokens,
+          system:     SYSTEM_PROMPT,
+          messages:   messages
+        }.to_json,
+        timeout: 90
+      )
+
+      body = JSON.parse(response.body)
+
+      unless response.success?
+        raise ApiError, "Claude API error (HTTP #{response.code}): #{body.dig('error', 'message')}"
+      end
+
+      body.dig("content", 0, "text").presence ||
+        raise(ApiError, "Empty response from Claude API")
+
+    rescue HTTParty::Error, Timeout::Error => e
+      raise ApiError, "Network error reaching Claude API: #{e.message}"
+    end
+
+    # Injects a live snapshot into the chat prompt
+    def context_block(ctx)
+      return nil if ctx.blank?
+      lines = ["## Live Facility Snapshot"]
+      lines << "- Active jobs: **#{ctx[:active_jobs]}**"                     if ctx[:active_jobs]
+      lines << "- Jobs on hold: **#{ctx[:jobs_on_hold]}**"                   if ctx[:jobs_on_hold]
+      lines << "- Open tasks: **#{ctx[:open_tasks]}**"                       if ctx[:open_tasks]
+      lines << "- Overdue tasks: **#{ctx[:overdue_tasks]}**"                 if ctx[:overdue_tasks]
+      lines << "- Pending budget requests: **#{ctx[:pending_budget_reqs]}**" if ctx[:pending_budget_reqs]
+      lines << "- Open bids awaiting decision: **#{ctx[:open_bids]}**"       if ctx[:open_bids]
+      lines << "- Total expense budget: **$#{ctx[:total_expense_budget]}**"  if ctx[:total_expense_budget]
+      lines << "- Total expense actual: **$#{ctx[:total_expense_actual]}**"  if ctx[:total_expense_actual]
+      lines << "- Locations tracked: **#{ctx[:location_count]}**"            if ctx[:location_count]
+      lines.join("\n")
+    end
+
+    def report_prompt(type, data)
+      company = YourAiInsight.config.company_name
+      case type.to_sym
+
+      when :summary_dashboard
+        <<~PROMPT
+          Generate an executive summary dashboard report for #{company}.
+
+          ## Overall Health Score: [X/100]
+          (Score should reflect job completion rate, budget adherence, overdue items, hold status)
+
+          ## Key Metrics at a Glance
+          (Most important numbers in a scannable format)
+
+          ## Job Pipeline Status
+          (Breakdown by status, priority, holds)
+
+          ## Budget & Cost Performance
+          (Budget vs actual across jobs, tasks, expenses; over/under budget analysis)
+
+          ## Vendor & Bid Activity
+          (Pending bids, accepted bids, pay requests awaiting approval)
+
+          ## Highlights
+          (What's going well)
+
+          ## Concerns
+          (What needs attention — flag overdue tasks, jobs on hold, budget overruns)
+
+          ## Top 5 Recommended Actions
+
+          DATA:
+          #{data.to_json}
+        PROMPT
+
+      when :compliance_audit
+        <<~PROMPT
+          Generate a compliance and audit report for #{company}.
+
+          ## Compliance Status Overview
+
+          ## ⚠️ Critical Items (Immediate Action Required)
+          (Jobs/tasks significantly over budget, long-held jobs, unapproved budget requests >30 days old)
+
+          ## ⚡ Warnings (Action Required Within 30 Days)
+          (Bids pending decision, tasks near deadline, budget requests pending)
+
+          ## Budget Request Audit
+          (Pending approvals, amounts, requestors)
+
+          ## Job Hold Audit
+          (All jobs currently on hold with duration)
+
+          ## Vendor Pay Request Audit
+          (Outstanding pay requests, amounts, days pending)
+
+          ## Completed This Period
+          (Finaled jobs, approved budget requests, paid pay requests)
+
+          ## Recommendations
+
+          DATA:
+          #{data.to_json}
+        PROMPT
+
+      else
+        "Analyze this facility management data and provide insights:\n\n#{data.to_json}"
+      end
+    end
+  end
+end

data/app/services/your_ai_insight/facility_data_service.rb

@@ -0,0 +1,449 @@
+module YourAiInsight
+  # Queries the host app's PostgreSQL database using the exact table/column
+  # names from portal.allproifm.com schema.rb.
+  # All queries use raw SQL via ActiveRecord::Base.connection so no AR models
+  # need to exist in the engine itself.
+  class FacilityDataService
+    def initialize(location_ids: nil, customer_ids: nil, date_range: nil)
+      @location_ids = location_ids
+      @customer_ids = customer_ids
+      @date_range   = date_range || (30.days.ago.beginning_of_day..Time.current)
+      @c            = YourAiInsight.config
+    end
+
+    # ── Lightweight snapshot used in chat context ────────────────────────────
+    def quick_context
+      {
+        active_jobs:         count_jobs(status_not: nil, hold: false),
+        jobs_on_hold:        count_jobs(hold: true),
+        open_tasks:          count_tasks(status: 0),
+        overdue_tasks:       count_overdue_tasks,
+        pending_budget_reqs: count_budget_requests(status: 0),
+        open_bids:           count_open_bids,
+        total_expense_budget: sum_expenses(:budget),
+        total_expense_actual: sum_expenses(:actual),
+        location_count:      count_locations
+      }
+    rescue StandardError => e
+      Rails.logger.warn("[YourAiInsight] quick_context error: #{e.message}")
+      {}
+    end
+
+    # ── Full payload for summary dashboard report ────────────────────────────
+    def summary_dashboard_data
+      {
+        period:           range_label,
+        jobs:             job_summary,
+        tasks:            task_summary,
+        bids:             bid_summary,
+        expenses:         expense_summary,
+        location_budgets: location_budget_summary,
+        budget_requests:  budget_request_summary,
+        top_locations:    top_locations_by_job_count,
+        top_customers:    top_customers_by_job_count
+      }
+    end
+
+    # ── Full payload for compliance/audit report ─────────────────────────────
+    def compliance_audit_data
+      {
+        period:                   range_label,
+        jobs_on_hold:             jobs_on_hold_detail,
+        overdue_tasks:            overdue_tasks_detail,
+        pending_budget_requests:  pending_budget_requests_detail,
+        open_bids_no_decision:    open_bids_detail,
+        outstanding_pay_requests: outstanding_pay_requests_detail,
+        over_budget_jobs:         over_budget_jobs_detail,
+        jobs_finaled_this_period: finaled_jobs_count,
+        budget_requests_approved: approved_budget_requests_count
+      }
+    end
+
+    private
+
+    # ═══════════════════════════════════════════════════════════════════
+    # JOBS  (table: jobs)
+    # status integer: 0=new,1=assigned,2=active,3=work_complete,4=all_tasks_complete,5=finaled
+    # ═══════════════════════════════════════════════════════════════════
+    def job_summary
+      {
+        total:              count_jobs,
+        by_status:          jobs_by_status,
+        by_priority:        jobs_by_priority,
+        on_hold:            count_jobs(hold: true),
+        recurring:          sql_count("SELECT COUNT(*) FROM #{j} #{job_where} AND recurring = true"),
+        accepted_period:    sql_count("SELECT COUNT(*) FROM #{j} #{job_where} AND #{@c.jobs_accepted_dt_col} BETWEEN #{range_sql}"),
+        finaled_period:     sql_count("SELECT COUNT(*) FROM #{j} #{job_where} AND #{@c.jobs_finaled_dt_col} BETWEEN #{range_sql}"),
+        total_sales_price:  sql_sum("SELECT COALESCE(SUM(#{@c.jobs_sales_price_col}),0) FROM #{j} #{job_where}"),
+        total_not_to_exceed:sql_sum("SELECT COALESCE(SUM(#{@c.jobs_not_to_exceed_col}),0) FROM #{j} #{job_where}")
+      }
+    end
+
+    def jobs_by_status
+      rows = exec_query("SELECT #{@c.jobs_status_col}, COUNT(*) as cnt FROM #{j} #{job_where} GROUP BY #{@c.jobs_status_col}")
+      labels = { 0 => "new", 1 => "assigned", 2 => "active", 3 => "work_complete", 4 => "all_tasks_complete", 5 => "finaled" }
+      rows.each_with_object({}) { |r, h| h[labels[r["status"].to_i] || r["status"].to_s] = r["cnt"].to_i }
+    rescue StandardError; {}
+    end
+
+    def jobs_by_priority
+      rows = exec_query("SELECT #{@c.jobs_priority_col}, COUNT(*) as cnt FROM #{j} #{job_where} AND #{@c.jobs_priority_col} IS NOT NULL GROUP BY #{@c.jobs_priority_col}")
+      rows.each_with_object({}) { |r, h| h[r["priority"]] = r["cnt"].to_i }
+    rescue StandardError; {}
+    end
+
+    def count_jobs(hold: nil, status_not: nil)
+      sql = "SELECT COUNT(*) FROM #{j} #{job_where}"
+      sql += " AND #{@c.jobs_hold_col} = #{hold}" unless hold.nil?
+      sql += " AND #{@c.jobs_status_col} != #{status_not}" unless status_not.nil?
+      sql_count(sql)
+    end
+
+    def count_jobs_simple = sql_count("SELECT COUNT(*) FROM #{j} #{job_where}")
+
+    def jobs_on_hold_detail
+      exec_query(<<~SQL)
+        SELECT j.id, j.name, j.#{@c.jobs_priority_col}, j.#{@c.jobs_status_col},
+               j.created_at, l.name as location_name, c.name as customer_name
+        FROM #{j}
+        LEFT JOIN #{loc} l ON l.id = j.#{@c.jobs_location_id_col}
+        LEFT JOIN #{cust} c ON c.id = j.#{@c.jobs_customer_id_col}
+        #{job_where} AND j.#{@c.jobs_hold_col} = true
+        ORDER BY j.created_at ASC LIMIT 25
+      SQL
+    rescue StandardError; []
+    end
+
+    def over_budget_jobs_detail
+      exec_query(<<~SQL)
+        SELECT j.id, j.name,
+               COALESCE(SUM(e.#{@c.expenses_actual_col}),0) as total_actual,
+               COALESCE(SUM(e.#{@c.expenses_budget_col}),0) as total_budget,
+               l.name as location_name
+        FROM #{j}
+        LEFT JOIN #{exp} e ON e.#{@c.expenses_job_id_col} = j.id
+        LEFT JOIN #{loc} l ON l.id = j.#{@c.jobs_location_id_col}
+        #{job_where}
+        GROUP BY j.id, j.name, l.name
+        HAVING COALESCE(SUM(e.#{@c.expenses_actual_col}),0) > COALESCE(SUM(e.#{@c.expenses_budget_col}),0)
+        ORDER BY (COALESCE(SUM(e.#{@c.expenses_actual_col}),0) - COALESCE(SUM(e.#{@c.expenses_budget_col}),0)) DESC
+        LIMIT 15
+      SQL
+    rescue StandardError; []
+    end
+
+    def finaled_jobs_count
+      sql_count("SELECT COUNT(*) FROM #{j} #{job_where} AND #{@c.jobs_finaled_dt_col} BETWEEN #{range_sql}")
+    end
+
+    def top_locations_by_job_count
+      exec_query(<<~SQL)
+        SELECT l.name, COUNT(j.id) as job_count
+        FROM #{loc} l
+        LEFT JOIN #{j} ON j.#{@c.jobs_location_id_col} = l.id
+        #{location_join_where("l")}
+        GROUP BY l.name ORDER BY job_count DESC LIMIT 10
+      SQL
+    rescue StandardError; []
+    end
+
+    def top_customers_by_job_count
+      exec_query(<<~SQL)
+        SELECT c.name, COUNT(j.id) as job_count
+        FROM #{cust} c
+        LEFT JOIN #{j} ON j.#{@c.jobs_customer_id_col} = c.id
+        #{customer_join_where("c")}
+        GROUP BY c.name ORDER BY job_count DESC LIMIT 10
+      SQL
+    rescue StandardError; []
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # TASKS  (table: tasks)
+    # status integer: 0=open, 1=in_progress, 2=complete
+    # ═══════════════════════════════════════════════════════════════════
+    def task_summary
+      {
+        total:         count_tasks,
+        open:          count_tasks(status: 0),
+        in_progress:   count_tasks(status: 1),
+        complete:      count_tasks(status: 2),
+        overdue:       count_overdue_tasks,
+        total_budget:  sql_sum("SELECT COALESCE(SUM(#{@c.tasks_budget_col}),0) FROM #{t} #{task_where}"),
+        total_actual:  sql_sum("SELECT COALESCE(SUM(#{@c.tasks_actual_col}),0) FROM #{t} #{task_where}"),
+        avg_budget:    sql_avg("SELECT AVG(#{@c.tasks_budget_col}) FROM #{t} #{task_where}")
+      }
+    end
+
+    def count_tasks(status: nil)
+      sql = "SELECT COUNT(*) FROM #{t} #{task_where}"
+      sql += " AND #{@c.tasks_status_col} = #{status}" unless status.nil?
+      sql_count(sql)
+    end
+
+    def count_overdue_tasks
+      sql_count(<<~SQL)
+        SELECT COUNT(*) FROM #{t} #{task_where}
+        AND #{@c.tasks_complete_col} < CURRENT_DATE
+        AND #{@c.tasks_status_col} != 2
+      SQL
+    end
+
+    def overdue_tasks_detail
+      exec_query(<<~SQL)
+        SELECT t.id, t.name, t.#{@c.tasks_complete_col}, t.#{@c.tasks_budget_col},
+               t.#{@c.tasks_actual_col}, j.name as job_name, l.name as location_name
+        FROM #{t}
+        LEFT JOIN #{j} ON j.id = t.#{@c.tasks_job_id_col}
+        LEFT JOIN #{loc} l ON l.id = j.#{@c.jobs_location_id_col}
+        #{task_where}
+        AND t.#{@c.tasks_complete_col} < CURRENT_DATE
+        AND t.#{@c.tasks_status_col} != 2
+        ORDER BY t.#{@c.tasks_complete_col} ASC LIMIT 20
+      SQL
+    rescue StandardError; []
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # BIDS  (table: bids)
+    # status: string — "pending", "accepted", "rejected", nil
+    # ═══════════════════════════════════════════════════════════════════
+    def bid_summary
+      {
+        total:    sql_count("SELECT COUNT(*) FROM #{b} WHERE created_at BETWEEN #{range_sql}"),
+        active:   sql_count("SELECT COUNT(*) FROM #{b} WHERE active = true AND created_at BETWEEN #{range_sql}"),
+        accepted: sql_count("SELECT COUNT(*) FROM #{b} WHERE #{@c.bids_status_col} = 'accepted' AND created_at BETWEEN #{range_sql}"),
+        pending:  count_open_bids,
+        total_bid_amount: sql_sum("SELECT COALESCE(SUM(#{@c.bids_amount_col}),0) FROM #{b} WHERE created_at BETWEEN #{range_sql}"),
+        total_actual:     sql_sum("SELECT COALESCE(SUM(#{@c.bids_actual_col}),0) FROM #{b} WHERE created_at BETWEEN #{range_sql}")
+      }
+    end
+
+    def count_open_bids
+      sql_count("SELECT COUNT(*) FROM #{b} WHERE (#{@c.bids_status_col} IS NULL OR #{@c.bids_status_col} NOT IN ('accepted','rejected')) AND created_at BETWEEN #{range_sql}")
+    end
+
+    def open_bids_detail
+      exec_query(<<~SQL)
+        SELECT b.id, b.#{@c.bids_amount_col}, b.received, b.notes,
+               t.name as task_name, j.name as job_name, v.name as vendor_name
+        FROM #{b}
+        LEFT JOIN #{t} ON #{t}.id = b.#{@c.bids_task_id_col}
+        LEFT JOIN #{j} ON #{j}.id = #{t}.#{@c.tasks_job_id_col}
+        LEFT JOIN vendors v ON v.id = b.vendor_id
+        WHERE (b.#{@c.bids_status_col} IS NULL OR b.#{@c.bids_status_col} NOT IN ('accepted','rejected'))
+        AND b.created_at BETWEEN #{range_sql}
+        ORDER BY b.received ASC LIMIT 20
+      SQL
+    rescue StandardError; []
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # EXPENSES  (table: expenses)
+    # ═══════════════════════════════════════════════════════════════════
+    def expense_summary
+      {
+        total_budget: sum_expenses(:budget),
+        total_actual: sum_expenses(:actual),
+        over_budget_count: sql_count(<<~SQL),
+          SELECT COUNT(*) FROM #{exp} WHERE #{@c.expenses_actual_col} > #{@c.expenses_budget_col}
+          AND created_at BETWEEN #{range_sql}
+        SQL
+        by_type: exec_query(<<~SQL)
+          SELECT et.name, COUNT(e.id) as cnt, COALESCE(SUM(e.#{@c.expenses_actual_col}),0) as total
+          FROM #{exp} e
+          LEFT JOIN expense_types et ON et.id = e.expense_type_id
+          WHERE e.created_at BETWEEN #{range_sql}
+          GROUP BY et.name ORDER BY total DESC
+        SQL
+      }
+    rescue StandardError; {}
+    end
+
+    def sum_expenses(col)
+      actual_col = col == :budget ? @c.expenses_budget_col : @c.expenses_actual_col
+      sql_sum("SELECT COALESCE(SUM(#{actual_col}),0) FROM #{exp} WHERE created_at BETWEEN #{range_sql}")
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # LOCATION BUDGETS  (table: location_budgets)
+    # Monthly columns: month1..month12
+    # ═══════════════════════════════════════════════════════════════════
+    def location_budget_summary
+      year = Date.today.year
+      month_cols = (1..12).map { |m| "COALESCE(month#{m},0)" }.join(" + ")
+
+      exec_query(<<~SQL)
+        SELECT l.name as location_name,
+               (#{month_cols}) as annual_budget,
+               lb.fiscal_year, lb.trade_id, lb.category_id
+        FROM #{lb} lb
+        LEFT JOIN #{loc} l ON l.id = lb.#{@c.lb_location_id_col}
+        WHERE lb.#{@c.lb_fiscal_year_col} = #{year}
+        #{location_id_filter("lb")}
+        ORDER BY annual_budget DESC LIMIT 20
+      SQL
+    rescue StandardError; []
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # BUDGET REQUESTS  (table: budget_requests)
+    # status integer: 0=pending, 1=approved, 2=rejected
+    # ═══════════════════════════════════════════════════════════════════
+    def budget_request_summary
+      {
+        total:    sql_count("SELECT COUNT(*) FROM #{br} WHERE created_at BETWEEN #{range_sql}"),
+        pending:  count_budget_requests(status: 0),
+        approved: count_budget_requests(status: 1),
+        rejected: count_budget_requests(status: 2),
+        total_amount_pending: sql_sum("SELECT COALESCE(SUM(#{@c.br_amount_col}),0) FROM #{br} WHERE #{@c.br_status_col} = 0 AND created_at BETWEEN #{range_sql}")
+      }
+    end
+
+    def count_budget_requests(status:)
+      sql_count("SELECT COUNT(*) FROM #{br} WHERE #{@c.br_status_col} = #{status} AND created_at BETWEEN #{range_sql}")
+    end
+
+    def approved_budget_requests_count
+      count_budget_requests(status: 1)
+    end
+
+    def pending_budget_requests_detail
+      exec_query(<<~SQL)
+        SELECT br.id, br.#{@c.br_amount_col}, br.created_at, br.notes,
+               t.name as task_name, j.name as job_name,
+               u.first_name || ' ' || u.last_name as requestor
+        FROM #{br}
+        LEFT JOIN tasks t ON t.id = br.#{@c.br_task_id_col}
+        LEFT JOIN jobs j ON j.id = t.job_id
+        LEFT JOIN users u ON u.id = br.requestor_id
+        WHERE br.#{@c.br_status_col} = 0
+        AND br.created_at BETWEEN #{range_sql}
+        ORDER BY br.created_at ASC LIMIT 20
+      SQL
+    rescue StandardError; []
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # PAY REQUESTS  (table: pay_requests)
+    # ═══════════════════════════════════════════════════════════════════
+    def outstanding_pay_requests_detail
+      exec_query(<<~SQL)
+        SELECT pr.id, pr.amount, pr.submitted, pr.notes, pr.ref,
+               t.name as task_name, j.name as job_name,
+               v.name as vendor_name
+        FROM pay_requests pr
+        LEFT JOIN tasks t ON t.id = pr.task_id
+        LEFT JOIN jobs j ON j.id = t.job_id
+        LEFT JOIN vendors v ON v.id = pr.vendor_id
+        WHERE pr.paid IS NULL AND pr.declined IS NULL
+        AND pr.submitted BETWEEN #{range_sql}
+        ORDER BY pr.submitted ASC LIMIT 20
+      SQL
+    rescue StandardError; []
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # LOCATIONS & CUSTOMERS
+    # ═══════════════════════════════════════════════════════════════════
+    def count_locations
+      sql_count("SELECT COUNT(*) FROM #{loc} #{location_where}")
+    end
+
+    # ═══════════════════════════════════════════════════════════════════
+    # SQL HELPERS
+    # ═══════════════════════════════════════════════════════════════════
+
+    # Table name shortcuts
+    def j   = @c.jobs_table
+    def t   = @c.tasks_table
+    def b   = @c.bids_table
+    def exp = @c.expenses_table
+    def lb  = @c.location_budgets_table
+    def loc = @c.locations_table
+    def cust= @c.customers_table
+    def br  = @c.budget_requests_table
+
+    def range_sql
+      "'#{@date_range.first.to_s(:db)}' AND '#{@date_range.last.to_s(:db)}'"
+    end
+
+    def range_label
+      { from: @date_range.first.to_s, to: @date_range.last.to_s }
+    end
+
+    # WHERE clause for jobs table (scoped by location/customer)
+    def job_where
+      parts = ["WHERE #{j}.created_at BETWEEN #{range_sql}"]
+      if @location_ids.present?
+        parts << "AND #{j}.#{@c.jobs_location_id_col} IN (#{safe_ids(@location_ids)})"
+      elsif @customer_ids.present?
+        parts << "AND #{j}.#{@c.jobs_customer_id_col} IN (#{safe_ids(@customer_ids)})"
+      end
+      parts.join(" ")
+    end
+
+    # WHERE clause for tasks (joined via jobs)
+    def task_where
+      parts = ["WHERE #{t}.created_at BETWEEN #{range_sql}"]
+      if @location_ids.present?
+        parts << "AND #{t}.#{@c.tasks_job_id_col} IN (SELECT id FROM #{j} WHERE #{@c.jobs_location_id_col} IN (#{safe_ids(@location_ids)}))"
+      elsif @customer_ids.present?
+        parts << "AND #{t}.#{@c.tasks_job_id_col} IN (SELECT id FROM #{j} WHERE #{@c.jobs_customer_id_col} IN (#{safe_ids(@customer_ids)}))"
+      end
+      parts.join(" ")
+    end
+
+    # WHERE clause for locations table
+    def location_where
+      return "" unless @location_ids.present?
+      "WHERE id IN (#{safe_ids(@location_ids)})"
+    end
+
+    # JOIN WHERE clause when locations table is aliased
+    def location_join_where(alias_name = "l")
+      return "" unless @location_ids.present?
+      "WHERE #{alias_name}.id IN (#{safe_ids(@location_ids)})"
+    end
+
+    def customer_join_where(alias_name = "c")
+      return "" unless @customer_ids.present?
+      "WHERE #{alias_name}.id IN (#{safe_ids(@customer_ids)})"
+    end
+
+    def location_id_filter(alias_name = nil)
+      return "" unless @location_ids.present?
+      col = alias_name ? "#{alias_name}.#{@c.lb_location_id_col}" : @c.lb_location_id_col
+      "AND #{col} IN (#{safe_ids(@location_ids)})"
+    end
+
+    def safe_ids(ids)
+      ids.map(&:to_i).join(",")
+    end
+
+    def exec_query(sql)
+      ActiveRecord::Base.connection.exec_query(sql).to_a
+    rescue StandardError => e
+      Rails.logger.warn("[YourAiInsight::FacilityDataService] Query error: #{e.message}")
+      []
+    end
+
+    def sql_count(sql)
+      ActiveRecord::Base.connection.execute(sql).first.values.first.to_i
+    rescue StandardError
+      0
+    end
+
+    def sql_sum(sql)
+      ActiveRecord::Base.connection.execute(sql).first.values.first.to_f.round(2)
+    rescue StandardError
+      0.0
+    end
+
+    def sql_avg(sql)
+      ActiveRecord::Base.connection.execute(sql).first.values.first&.to_f&.round(2)
+    rescue StandardError
+      nil
+    end
+  end
+end