kpi_assembler 0.5.0

data/lib/kpi_assembler/briefing_generator.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "metric_evaluator"
+require_relative "location_directory"
+
+module KPIAssembler
+  class BriefingGenerator
+    def initialize(db, certified_kpis, now: Time.now.utc, tenant_id: nil)
+      @evaluator = MetricEvaluator.new(db)
+      @kpis = certified_kpis
+      @now = now
+      @tenant_id = tenant_id
+      @current_from = now - (30 * 86_400)
+      @previous_from = now - (60 * 86_400)
+    end
+
+    def generate
+      movements = @kpis.filter_map { |kpi| movement_for(kpi) }
+      ranked = movements.sort_by { |m| -m[:abs_delta_pct] }.first(3)
+      drill = worst_location_for(ranked.first)
+
+      {
+        period: {
+          current: { from: iso(@current_from), to: iso(@now) },
+          previous: { from: iso(@previous_from), to: iso(@current_from) }
+        },
+        headline: headline(ranked),
+        movements: ranked,
+        drill_dimension: drill
+      }
+    end
+
+    private
+
+    def movement_for(kpi)
+      current = @evaluator.value(kpi, from: @current_from, to: @now)
+      previous = @evaluator.value(kpi, from: @previous_from, to: @current_from)
+      return if current.nil? || previous.nil?
+
+      delta = current - previous
+      base = previous.abs < 0.0001 ? nil : ((delta / previous) * 100.0)
+      {
+        id: kpi[:id],
+        name: kpi[:name],
+        current: round_num(current),
+        previous: round_num(previous),
+        delta: round_num(delta),
+        delta_pct: base && round_num(base),
+        abs_delta_pct: (base || delta).abs,
+        sentence: sentence(kpi[:name], current, previous, delta, base)
+      }
+    end
+
+    def worst_location_for(movement)
+      return { dimension: "location", note: "No certified movement to drill." } unless movement
+
+      kpi = @kpis.find { |k| k[:id] == movement[:id] }
+      return { dimension: "location", note: "KPI has no location column." } unless kpi && kpi[:location_column]
+
+      rows = db_locations.filter_map do |loc|
+        value = @evaluator.value(kpi, from: @current_from, to: @now, location_id: loc[:id])
+        next unless value
+
+        { id: loc[:id], name: loc[:name], value: round_num(value) }
+      end
+      worst = rows.min_by { |r| r[:value] }
+      {
+        dimension: "location",
+        kpi_id: movement[:id],
+        locations: rows,
+        explaining_site: worst
+      }
+    end
+
+    def db_locations
+      LocationDirectory.new(@evaluator.db, tenant_id: @tenant_id).all
+    rescue StandardError
+      []
+    end
+
+    def headline(ranked)
+      return "No certified KPIs moved enough to brief." if ranked.empty?
+
+      ranked.map { |m| m[:sentence] }.join(" ")
+    end
+
+    def sentence(name, current, previous, delta, delta_pct)
+      direction = delta.negative? ? "fell" : "rose"
+      if delta_pct
+        "#{name} #{direction} #{format('%.1f', delta_pct.abs)} pts/percent vs the prior 30 days (#{format_num(previous)} → #{format_num(current)})."
+      else
+        "#{name} is #{format_num(current)} this period vs #{format_num(previous)} prior."
+      end
+    end
+
+    def format_num(n)
+      n.abs >= 100 ? format("%.0f", n) : format("%.1f", n)
+    end
+
+    def round_num(n)
+      n.round(2)
+    end
+
+    def iso(time)
+      time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    end
+  end
+end

data/lib/kpi_assembler/candidate_generator.rb

@@ -0,0 +1,421 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require_relative "schema_kpi_proposer"
+
+module KPIAssembler
+  # The inspector already decided which tables exist. This class only proposes
+  # KPIs: the LLM (Gemini or Ollama) ranks those tables and writes recipes;
+  # heuristics fill gaps. Certification never happens here.
+  class CandidateGenerator
+    MAX_CANDIDATES = 16
+    MAX_PROMPT_TABLES = 24
+
+    attr_reader :schema, :options, :meta
+
+    def initialize(schema, options = {})
+      @schema = schema
+      @options = options
+      @meta = default_meta
+    end
+
+    def generate
+      heuristic = heuristic_candidates(schema.keys)
+      return finalize(heuristic, proposer: "heuristics") unless use_llm?
+
+      llm = prompt_llm
+      unless llm
+        return finalize(
+          heuristic,
+          proposer: "heuristics",
+          fallback_reason: @meta[:fallback_reason]
+        )
+      end
+
+      ranked = llm[:ranked_tables]
+      merged = merge_candidates(llm[:kpis], heuristic)
+      finalize(
+        merged,
+        proposer: "llm",
+        ranked_tables: ranked,
+        model: active_model_name
+      )
+    end
+
+    private
+
+    def default_meta
+      {
+        proposer: "heuristics",
+        ranked_tables: [],
+        model: nil,
+        fallback_reason: nil
+      }
+    end
+
+    def use_llm?
+      return false if options[:use_llm] == false
+      return false if llm_provider == :ollama && options[:use_ollama] == false
+
+      true
+    end
+
+    def llm_provider
+      provider = options[:llm_provider] || ENV["KPI_LLM_PROVIDER"]
+      if provider && !provider.to_s.empty?
+        provider.to_sym
+      elsif options[:gemini_api_key] || ENV["GEMINI_API_KEY"]
+        :gemini
+      else
+        :ollama
+      end
+    end
+
+    def active_model_name
+      llm_provider == :gemini ? gemini_model : ollama_model
+    end
+
+    def ollama_model
+      options[:ollama_model] || ENV.fetch("KPI_OLLAMA_MODEL", "llama3")
+    end
+
+    def gemini_model
+      options[:gemini_model] || ENV.fetch("KPI_GEMINI_MODEL", "gemini-2.0-flash")
+    end
+
+    def heuristic_candidates(table_names)
+      names = Array(table_names).map(&:to_s)
+      focused = schema.select { |name, _| names.include?(name.to_s) }
+      focused = schema if focused.empty?
+      SchemaKpiProposer.new(focused, options).propose
+    end
+
+    def prompt_llm
+      case llm_provider
+      when :gemini
+        prompt_gemini
+      else
+        prompt_ollama
+      end
+    end
+
+    def prompt_gemini
+      api_key = options[:gemini_api_key] || ENV["GEMINI_API_KEY"]
+      if api_key.nil? || api_key.to_s.empty?
+        reason = "GEMINI_API_KEY is not set. Set GEMINI_API_KEY or configure KPI_LLM_PROVIDER=ollama."
+        @meta = default_meta.merge(fallback_reason: reason)
+        warn "Gemini proposal failed: #{reason}"
+        return nil
+      end
+
+      model = gemini_model
+      endpoint = options[:gemini_url] || "https://generativelanguage.googleapis.com/v1beta/models/#{model}:generateContent"
+      known = schema.keys.map(&:to_s)
+      prompt_text = build_prompt(known)
+
+      uri = URI.parse(endpoint)
+      req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json", "x-goog-api-key" => api_key)
+      req.body = {
+        contents: [
+          {
+            parts: [{ text: prompt_text }]
+          }
+        ],
+        generationConfig: {
+          responseMimeType: "application/json"
+        }
+      }.to_json
+
+      res = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: Integer(options[:gemini_open_timeout] || 5),
+        read_timeout: Integer(options[:gemini_timeout] || 60)
+      ) { |http| http.request(req) }
+
+      code = res.code.to_i
+      unless code.between?(200, 299)
+        @meta = default_meta.merge(fallback_reason: describe_gemini_error(code, res.body))
+        return nil
+      end
+
+      raw_json = extract_gemini_text(res.body)
+      parsed = extract_json(raw_json)
+      ranked = sanitize_ranked_tables(parsed, known)
+      kpis = sanitize_llm_kpis(parsed, known)
+      if kpis.empty?
+        @meta = default_meta.merge(fallback_reason: "Gemini returned no usable KPIs")
+        return nil
+      end
+
+      { ranked_tables: ranked, kpis: kpis }
+    rescue Net::OpenTimeout, Errno::ECONNREFUSED, SocketError => e
+      reason = "Cannot reach Gemini API (#{e.class}: #{e.message}). Check internet connection."
+      @meta = default_meta.merge(fallback_reason: reason)
+      warn "Gemini proposal failed: #{reason}"
+      nil
+    rescue Net::ReadTimeout
+      seconds = Integer(options[:gemini_timeout] || 60)
+      reason = "Gemini (#{model}) did not answer within #{seconds}s."
+      @meta = default_meta.merge(fallback_reason: reason)
+      warn "Gemini proposal failed: #{reason}"
+      nil
+    rescue StandardError => e
+      @meta = default_meta.merge(fallback_reason: e.message)
+      warn "Gemini proposal failed (#{e.message}). Using schema-driven heuristics."
+      nil
+    end
+
+    def extract_gemini_text(body)
+      parsed = JSON.parse(body)
+      text = parsed.dig("candidates", 0, "content", "parts", 0, "text")
+      text || body
+    rescue StandardError
+      body
+    end
+
+    def describe_gemini_error(code, body)
+      detail = begin
+        parsed = JSON.parse(body.to_s)
+        parsed.dig("error", "message") || parsed["error"].to_s
+      rescue StandardError
+        ""
+      end
+      "Gemini API returned HTTP #{code}#{detail.empty? ? "" : ": #{detail}"}"
+    end
+
+    def prompt_ollama
+      endpoint = options[:ollama_url] || "http://localhost:11434/api/generate"
+      known = schema.keys.map(&:to_s)
+      prompt_text = build_prompt(known)
+
+      uri = URI.parse(endpoint)
+      req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
+      req.body = {
+        model: ollama_model,
+        prompt: prompt_text,
+        stream: false,
+        format: "json"
+      }.to_json
+
+      res = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        open_timeout: Integer(options[:ollama_open_timeout] || 2),
+        read_timeout: Integer(options[:ollama_timeout] || 900)
+      ) { |http| http.request(req) }
+
+      code = res.code.to_i
+      unless code.between?(200, 299)
+        @meta = default_meta.merge(fallback_reason: describe_http_error(code, res.body, endpoint))
+        return nil
+      end
+
+      parsed = extract_json(res.body)
+      ranked = sanitize_ranked_tables(parsed, known)
+      kpis = sanitize_llm_kpis(parsed, known)
+      if kpis.empty?
+        @meta = default_meta.merge(fallback_reason: "Ollama returned no usable KPIs")
+        return nil
+      end
+
+      { ranked_tables: ranked, kpis: kpis }
+    rescue Net::OpenTimeout, Errno::ECONNREFUSED, SocketError => e
+      reason = "Cannot reach Ollama at #{endpoint} (#{e.class}). Start it with `ollama serve`."
+      @meta = default_meta.merge(fallback_reason: reason)
+      warn "Ollama proposal failed: #{reason}"
+      nil
+    rescue Net::ReadTimeout
+      seconds = Integer(options[:ollama_timeout] || 90)
+      reason = "#{ollama_model} did not answer within #{seconds}s. Use a smaller model or raise ollama_timeout."
+      @meta = default_meta.merge(fallback_reason: reason)
+      warn "Ollama proposal failed: #{reason}"
+      nil
+    rescue StandardError => e
+      @meta = default_meta.merge(fallback_reason: e.message)
+      warn "Ollama proposal failed (#{e.message}). Using schema-driven heuristics."
+      nil
+    end
+
+    def build_prompt(known)
+      dialect = options[:dialect] || "SQL"
+
+      <<~PROMPT
+        You are a business analytics architect. The tables below were already
+        discovered by a schema inspector — do not invent tables or columns.
+
+        1. Rank the most useful fact tables for KPIs (6 or fewer).
+        2. Propose 6 to 10 KPI recipes for those tables.
+
+        Reply ONLY with JSON:
+        {
+          "ranked_tables": ["table_name"],
+          "kpis": [
+            {
+              "id": "snake_case_id",
+              "name": "Human name",
+              "category": "Sales Funnel|Revenue|Retention|Operations|Conversion",
+              "owner": "sales|exec|ops|site_manager|finance",
+              "formula_description": "One sentence in English",
+              "sql": "SELECT ... AS metric_value FROM ... WHERE ...",
+              "grain": "daily|weekly|monthly",
+              "location_column": "location_id or company_id or null",
+              "fact_table": "one of the provided table names"
+            }
+          ]
+        }
+
+        SQL rules:
+        - Dialect: #{dialect}
+        - Return a single column aliased metric_value.
+        - Use two positional placeholders ? ? for period start and end.
+        - Guard every division with NULLIF.
+        - Only JOIN on real foreign keys. Never JOIN without ON.
+        - fact_table and every FROM/JOIN target MUST be a provided table name.
+        - Infer the domain from names. Do not assume a gym unless the schema looks like one.
+        #{tenant_prompt_line}
+
+        Discovered schema:
+        #{JSON.pretty_generate(schema_for_prompt)}
+      PROMPT
+    end
+
+    # Ollama reports a missing model as a 404 with a JSON error body. Say which
+    # models the daemon actually has, so the fix does not need a support round trip.
+    def describe_http_error(code, body, endpoint)
+      detail = begin
+        JSON.parse(body.to_s)["error"].to_s
+      rescue StandardError
+        ""
+      end
+
+      return "Ollama at #{endpoint} returned HTTP #{code}#{detail.empty? ? "" : ": #{detail}"}" unless code == 404
+
+      installed = installed_models(endpoint)
+      hint =
+        if installed.empty?
+          "No models are installed. Run `ollama pull #{ollama_model}`."
+        else
+          "Installed models: #{installed.join(", ")}. Run `ollama pull #{ollama_model}` or set ollama_model to one of these."
+        end
+      "Model #{ollama_model.inspect} is not available. #{hint}"
+    end
+
+    def installed_models(endpoint)
+      uri = URI.parse(endpoint)
+      tags = URI::HTTP.build(host: uri.host, port: uri.port, path: "/api/tags")
+      body = Net::HTTP.start(uri.hostname, uri.port, open_timeout: 2, read_timeout: 5) do |http|
+        http.request(Net::HTTP::Get.new(tags)).body
+      end
+      Array(JSON.parse(body)["models"]).map { |model| model["name"].to_s }.reject(&:empty?)
+    rescue StandardError
+      []
+    end
+
+    def extract_json(body)
+      envelope = JSON.parse(body.to_s)
+      payload = envelope.is_a?(Hash) ? envelope["response"] || envelope : envelope
+      parsed =
+        if payload.is_a?(String)
+          JSON.parse(payload)
+        else
+          payload
+        end
+      parsed = parsed["kpis"] || parsed["candidates"] || parsed if parsed.is_a?(Hash) && !parsed.key?("kpis") && !parsed.key?("ranked_tables")
+      parsed
+    end
+
+    def sanitize_ranked_tables(parsed, known)
+      names =
+        case parsed
+        when Hash then Array(parsed["ranked_tables"] || parsed[:ranked_tables])
+        else []
+        end
+      names.map(&:to_s).uniq.select { |name| known.include?(name) }
+    end
+
+    def sanitize_llm_kpis(parsed, known)
+      rows =
+        case parsed
+        when Hash then Array(parsed["kpis"] || parsed[:kpis] || parsed["candidates"])
+        when Array then parsed
+        else []
+        end
+
+      rows.filter_map do |row|
+        next unless row.respond_to?(:to_h)
+
+        kpi = row.to_h.transform_keys(&:to_sym)
+        fact = kpi[:fact_table].to_s
+        fact = infer_fact_table(kpi[:sql], known) if fact.empty? || !known.include?(fact)
+        next unless known.include?(fact)
+        next if kpi[:sql].to_s.strip.empty? || kpi[:id].to_s.strip.empty?
+
+        kpi.merge(fact_table: fact, source: "llm")
+      end
+    end
+
+    def infer_fact_table(sql, known)
+      match = sql.to_s.match(/\bfrom\s+["']?([a-zA-Z0-9_]+)["']?/i)
+      name = match && match[1]
+      known.include?(name) ? name : nil
+    end
+
+    def merge_candidates(llm_kpis, heuristic)
+      seen = {}
+      combined = []
+      (Array(llm_kpis) + Array(heuristic)).each do |kpi|
+        id = kpi[:id].to_s
+        next if id.empty? || seen[id]
+
+        seen[id] = true
+        combined << kpi
+      end
+      combined.first(MAX_CANDIDATES)
+    end
+
+    def finalize(candidates, proposer:, ranked_tables: [], model: nil, fallback_reason: nil)
+      normalized = normalize(candidates)
+      @meta = {
+        proposer: proposer,
+        ranked_tables: Array(ranked_tables),
+        model: model,
+        fallback_reason: fallback_reason
+      }
+      normalized
+    end
+
+    def tenant_prompt_line
+      column = options[:tenant_column]
+      return "" unless column
+
+      "If a table has #{column}, every query on that table MUST include #{column} = #{options[:tenant_id] || "?"}."
+    end
+
+    def schema_for_prompt
+      schema.first(MAX_PROMPT_TABLES).to_h.transform_values do |meta|
+        {
+          row_count: meta[:row_count],
+          columns: Array(meta[:columns]).map { |col| { name: col[:name], type: col[:type] } },
+          time_columns: meta[:time_columns],
+          foreign_keys: Array(meta[:foreign_keys]).map { |fk| fk.slice(:table, :from, :to) },
+          categorical_values: meta[:categorical_values]
+        }
+      end
+    end
+
+    def normalize(candidates)
+      candidates.map do |kpi|
+        h = kpi.transform_keys(&:to_sym)
+        h[:sql] = h[:sql].to_s.strip.sub(/;\s*\z/, "")
+        h[:grain] = h[:grain].to_s
+        h[:source] ||= "heuristics"
+        h[:location_column] = nil if h[:location_column].to_s.match?(/\A(null|nil|none)?\z/i)
+        h
+      end
+    end
+  end
+end

data/lib/kpi_assembler/certification_engine.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "connection"
+require_relative "metric_evaluator"
+
+module KPIAssembler
+  class CertificationEngine
+    attr_reader :db, :schema, :evaluator
+
+    def initialize(db, schema, now: Time.now.utc, tenant_column: nil, tenant_id: nil)
+      @db = Connection.wrap(db)
+      @schema = schema
+      @now = now
+      @tenant_column = tenant_column
+      @tenant_id = tenant_id
+      @evaluator = MetricEvaluator.new(@db)
+    end
+
+    def certify(candidates)
+      certified = []
+      drafts = []
+
+      candidates.each do |kpi|
+        reasons = collect_reasons(kpi)
+        record = kpi.merge(certified_at: @now.iso8601)
+
+        if reasons.empty?
+          certified << record.merge(status: "certified")
+        else
+          drafts << record.merge(status: "draft", reasons: reasons)
+        end
+      end
+
+      [certified, drafts]
+    end
+
+    private
+
+    def collect_reasons(kpi)
+      reasons = []
+      sql = kpi[:sql].to_s
+
+      reasons << "Only one read-only SELECT statement is allowed" unless read_only_select?(sql)
+      reasons << "Missing aggregation grain" if kpi[:grain].to_s.strip.empty?
+      reasons.concat(schema_reasons(sql))
+      reasons.concat(tenant_scope_reasons(kpi, sql))
+      reasons << "JOIN without ON — unconstrained join / cartesian risk" if join_without_on?(sql)
+      reasons << "Unsafe division without NULLIF or CASE" if unsafe_division?(sql)
+      reasons.concat(execution_reasons(kpi))
+      reasons
+    end
+
+    def schema_reasons(sql)
+      unknown = referenced_tables(sql) - schema.keys.map(&:to_s)
+      return [] if unknown.empty?
+
+      ["References unknown tables: #{unknown.join(", ")}"]
+    end
+
+    def referenced_tables(sql)
+      sql.scan(/\b(?:FROM|JOIN)\s+([A-Za-z_][A-Za-z0-9_]*)/i).flatten.map(&:downcase).uniq
+    end
+
+    def read_only_select?(sql)
+      statement = sql.strip
+      return false unless statement.match?(/\A(?:SELECT|WITH)\b/i)
+      return false if statement.sub(/;\s*\z/, "").include?(";")
+
+      !statement.match?(/\b(?:INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE|CREATE|GRANT|REVOKE|COPY)\b/i)
+    end
+
+    def tenant_scope_reasons(kpi, sql)
+      return [] unless @tenant_column && @tenant_id
+
+      fact_table = kpi[:fact_table].to_s
+      columns = Array(schema.dig(fact_table, :columns)).map { |column| column[:name] }
+      return [] unless columns.include?(@tenant_column.to_s)
+
+      pattern = /\b#{Regexp.escape(@tenant_column.to_s)}\s*=\s*#{Regexp.escape(@tenant_id.to_s)}\b/i
+      return [] if sql.match?(pattern)
+
+      ["Missing required tenant scope: #{@tenant_column} = #{@tenant_id}"]
+    end
+
+    def join_without_on?(sql)
+      sql.split(/\bJOIN\b/i).drop(1).any? { |fragment| !fragment.match?(/\bON\b/i) }
+    end
+
+    def unsafe_division?(sql)
+      return false unless sql.include?("/")
+
+      !sql.match?(/\bNULLIF\b/i) && !sql.match?(/\bCASE\b/i)
+    end
+
+    def execution_reasons(kpi)
+      reasons = []
+      from = @now - (30 * 86_400)
+      to = @now
+
+      begin
+        plan_sql = evaluator.scoped_sql(kpi).gsub("?", "'2000-01-01T00:00:00Z'")
+        db.explain(plan_sql)
+      rescue StandardError => e
+        reasons << "SQL syntax or planner error: #{e.message}"
+        return reasons
+      end
+
+      begin
+        value = evaluator.value(kpi, from: from, to: to)
+      rescue StandardError => e
+        reasons << "Execution failed on sample period: #{e.message}"
+        return reasons
+      end
+
+      if value.nil?
+        reasons << "Sample-period replay returned NULL"
+      elsif !value.finite?
+        reasons << "Sample-period replay returned non-finite value"
+      end
+
+      reasons
+    end
+  end
+end