kpi_assembler 0.5.0

data/lib/kpi_assembler/configuration.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module KPIAssembler
+  class Configuration
+    attr_accessor :connection_provider,
+                  :tenant_id_resolver,
+                  :authorize_with,
+                  :include_tables,
+                  :max_tables,
+                  :schema_name,
+                  :tenant_column,
+                  :llm_provider,
+                  :use_llm,
+                  :use_ollama,
+                  :ollama_model,
+                  :ollama_url,
+                  :gemini_api_key,
+                  :gemini_model,
+                  :gemini_url,
+                  :parent_controller
+
+    def initialize
+      @connection_provider = lambda do |_controller|
+        ActiveRecord::Base.connection_pool
+      end
+      @tenant_id_resolver = ->(_controller) {}
+      @authorize_with = lambda do |controller|
+        controller.send(:authenticate_user!) if controller.respond_to?(:authenticate_user!, true)
+        true
+      end
+      @include_tables = []
+      @max_tables = 30
+      @schema_name = "public"
+      @tenant_column = nil
+      @llm_provider = ENV.fetch("KPI_LLM_PROVIDER", ENV["GEMINI_API_KEY"] ? "gemini" : "ollama").to_sym
+      @use_ollama = ENV["KPI_USE_OLLAMA"] != "false"
+      @use_llm = ENV["KPI_USE_LLM"] != "false"
+      @ollama_model = ENV.fetch("KPI_OLLAMA_MODEL", "llama3")
+      @ollama_url = ENV.fetch("KPI_OLLAMA_URL", "http://localhost:11434/api/generate")
+      @gemini_api_key = ENV["GEMINI_API_KEY"]
+      @gemini_model = ENV.fetch("KPI_GEMINI_MODEL", "gemini-2.0-flash")
+      @gemini_url = ENV["KPI_GEMINI_URL"]
+      @parent_controller = "ApplicationController"
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      reset_services!
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      reset_services!
+    end
+
+    def service_for(controller)
+      tenant_id = invoke(configuration.tenant_id_resolver, controller)
+      source = invoke(configuration.connection_provider, controller)
+      connection = Connection.wrap(source, label: "Rails application database")
+      key = [connection.cache_key, tenant_id]
+
+      services_mutex.synchronize do
+        services[key] ||= WebService.new(
+          db: connection,
+          options: {
+            source_name: connection.label,
+            include_tables: Array(configuration.include_tables),
+            max_tables: configuration.max_tables,
+            schema_name: configuration.schema_name,
+            tenant_column: configuration.tenant_column,
+            tenant_id: tenant_id,
+            llm_provider: configuration.llm_provider,
+            use_llm: configuration.use_llm,
+            use_ollama: configuration.use_ollama,
+            ollama_model: configuration.ollama_model,
+            ollama_url: configuration.ollama_url,
+            gemini_api_key: configuration.gemini_api_key,
+            gemini_model: configuration.gemini_model,
+            gemini_url: configuration.gemini_url
+          }
+        )
+      end
+    end
+
+    def authorized?(controller)
+      configuration.authorize_with.nil? || invoke(configuration.authorize_with, controller) != false
+    end
+
+    def reset_services!
+      @services = {}
+    end
+
+    private
+
+    def services
+      @services ||= {}
+    end
+
+    def services_mutex
+      @services_mutex ||= Mutex.new
+    end
+
+    def invoke(callable, controller)
+      callable.arity.zero? ? callable.call : callable.call(controller)
+    end
+  end
+end

data/lib/kpi_assembler/connection.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module KPIAssembler
+  # Uniform query surface for SQLite and PostgreSQL. KPI SQL keeps `?`
+  # placeholders; Postgres binds are rewritten to $1, $2, ...
+  class Connection
+    attr_reader :raw, :adapter, :label
+
+    def self.wrap(object, label: nil)
+      return object if object.is_a?(Connection)
+
+      if object.respond_to?(:with_connection)
+        adapter_name = object.with_connection { |connection| connection.adapter_name }
+        adapter = adapter_name.to_s.match?(/postgre/i) ? :postgres : :sqlite
+        new(raw: object, adapter: adapter, label: label || "ActiveRecord #{adapter_name}", pool: true)
+      elsif defined?(SQLite3::Database) && object.is_a?(SQLite3::Database)
+        new(raw: object, adapter: :sqlite, label: label || "sqlite")
+      elsif defined?(PG::Connection) && object.is_a?(PG::Connection)
+        new(raw: object, adapter: :postgres, label: label || "postgres")
+      else
+        raise Error, "Unsupported database object: #{object.class}"
+      end
+    end
+
+    def self.open(url: nil, sqlite_path: nil)
+      url ||= ENV["KPI_DATABASE_URL"]
+      sqlite_path ||= ENV["KPI_DATABASE_PATH"]
+
+      if url && !url.to_s.empty?
+        from_url(url)
+      elsif sqlite_path && !sqlite_path.to_s.empty?
+        require "sqlite3"
+        wrap(SQLite3::Database.new(sqlite_path), label: sqlite_path)
+      else
+        require_relative "sample_database"
+        wrap(SampleDatabase.build, label: "Built-in sample database")
+      end
+    end
+
+    def self.from_url(url)
+      uri = URI.parse(url)
+      case uri.scheme
+      when "postgres", "postgresql"
+        require "pg"
+        dbname = uri.path.to_s.sub(%r{\A/}, "")
+        raw = PG.connect(
+          host: uri.host,
+          port: uri.port || 5432,
+          dbname: dbname,
+          user: uri.user,
+          password: uri.password
+        )
+        wrap(raw, label: "#{uri.host}/#{dbname}")
+      when "sqlite", "sqlite3"
+        require "sqlite3"
+        path = uri.host == ":memory:" ? ":memory:" : uri.path
+        wrap(SQLite3::Database.new(path), label: path)
+      else
+        raise Error, "Unsupported database URL scheme: #{uri.scheme.inspect}"
+      end
+    end
+
+    def initialize(raw:, adapter:, label:, pool: false)
+      @raw = raw
+      @adapter = adapter.to_sym
+      @label = label
+      @pool = pool
+    end
+
+    def postgres?
+      adapter == :postgres
+    end
+
+    def sqlite?
+      adapter == :sqlite
+    end
+
+    def dialect
+      postgres? ? "PostgreSQL" : "SQLite"
+    end
+
+    # Stable identity for caching. Host applications hand back a fresh connection
+    # object on every request, so object identity cannot be used here.
+    def cache_key
+      [adapter, label, pool_name]
+    end
+
+    def execute(sql, binds = [])
+      binds = Array(binds)
+      return execute_with_pool(sql, binds) if @pool
+
+      execute_raw(raw, sql, binds)
+    end
+
+    def explain(sql)
+      if sqlite?
+        execute("EXPLAIN QUERY PLAN #{sql}")
+      else
+        execute("EXPLAIN #{pg_sql(sql)}")
+      end
+    end
+
+    def quote_ident(name)
+      %("#{name.to_s.gsub('"', '""')}")
+    end
+
+    private
+
+    def pool_name
+      return nil unless @pool && raw.respond_to?(:db_config)
+
+      raw.db_config.name
+    end
+
+    def execute_with_pool(sql, binds)
+      raw.with_connection do |connection|
+        execute_raw(connection.raw_connection, sql, binds)
+      end
+    end
+
+    def execute_raw(connection, sql, binds)
+      if sqlite?
+        binds.empty? ? connection.execute(sql) : connection.execute(sql, binds)
+      else
+        result = binds.empty? ? connection.exec(sql) : connection.exec_params(pg_sql(sql), binds)
+        result.values
+      end
+    end
+
+    def pg_sql(sql)
+      index = 0
+      sql.gsub("?") do
+        index += 1
+        "$#{index}"
+      end
+    end
+  end
+end

data/lib/kpi_assembler/engine.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module KPIAssembler
+  class Engine < ::Rails::Engine
+    isolate_namespace KPIAssembler
+
+    # Without this the names derived from `KPIAssembler` are `k_p_i_assembler`.
+    engine_name "kpi_assembler"
+    railtie_name "kpi_assembler"
+  end
+end
+
+# Rails camelizes the `kpi_assembler` path segment of engine controllers as
+# `KpiAssembler`. Defining an acronym inflection instead would change how the
+# host application resolves its own `Kpi` constants.
+KpiAssembler = KPIAssembler unless defined?(KpiAssembler)

data/lib/kpi_assembler/env.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module KPIAssembler
+  # Loads KEY=VALUE pairs from a .env file without overriding values already
+  # present in the process environment.
+  module Env
+    module_function
+
+    def load!(path)
+      return unless path && File.file?(path)
+
+      File.foreach(path) do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?("#")
+
+        key, value = line.split("=", 2)
+        next if key.nil? || value.nil?
+
+        key = key.strip
+        next if key.empty? || ENV.key?(key)
+
+        ENV[key] = unquote(value.strip)
+      end
+    end
+
+    def load_defaults!
+      load!(File.expand_path("../../.env", __dir__))
+      load!(File.expand_path(".env"))
+    end
+
+    def unquote(value)
+      if (value.start_with?('"') && value.end_with?('"')) ||
+         (value.start_with?("'") && value.end_with?("'"))
+        value[1..-2]
+      else
+        value
+      end
+    end
+  end
+end

data/lib/kpi_assembler/html_report.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "json"
+require "cgi"
+
+module KPIAssembler
+  class HtmlReport
+    def initialize(pack, locations: [])
+      @pack = pack
+      @locations = locations
+    end
+
+    def render
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <title>#{h(@pack[:pack_name])}</title>
+          <style>
+            :root { --bg:#0f1419; --card:#1a2332; --muted:#8b9bb4; --ok:#3dd68c; --draft:#f5c542; --bad:#ff6b6b; --line:#2a3548; --text:#e8eef7; }
+            * { box-sizing: border-box; }
+            body { margin:0; font-family: ui-sans-serif, system-ui, sans-serif; background:var(--bg); color:var(--text); }
+            header { padding:28px 32px 12px; border-bottom:1px solid var(--line); }
+            header p { color:var(--muted); max-width:720px; }
+            main { padding:24px 32px 64px; }
+            h1 { margin:0 0 8px; font-size:28px; }
+            h2 { margin:28px 0 12px; font-size:18px; letter-spacing:.02em; }
+            .badge { display:inline-block; padding:2px 8px; border-radius:999px; font-size:12px; font-weight:600; }
+            .ok { background:#143d2c; color:var(--ok); }
+            .draft { background:#3d3414; color:var(--draft); }
+            .grid { display:grid; grid-template-columns:repeat(auto-fill,minmax(220px,1fr)); gap:12px; }
+            .card { background:var(--card); border:1px solid var(--line); border-radius:12px; padding:16px; }
+            .card.dim { opacity:.55; }
+            .value { font-size:28px; font-weight:700; margin:8px 0 0; }
+            .muted { color:var(--muted); font-size:13px; }
+            table { width:100%; border-collapse:collapse; background:var(--card); border-radius:12px; overflow:hidden; }
+            th, td { text-align:left; padding:10px 12px; border-bottom:1px solid var(--line); font-size:14px; vertical-align:top; }
+            th { color:var(--muted); font-weight:600; }
+            pre { white-space:pre-wrap; font-size:12px; color:#c5d4ea; margin:0; }
+            .tabs { display:flex; gap:8px; flex-wrap:wrap; margin:8px 0 16px; }
+            .tabs button { background:#243044; color:var(--text); border:1px solid var(--line); border-radius:8px; padding:8px 12px; cursor:pointer; }
+            .tabs button.active { background:#2f6fed; border-color:#2f6fed; }
+            .panel { display:none; }
+            .panel.active { display:block; }
+            .brief { font-size:16px; line-height:1.5; }
+          </style>
+        </head>
+        <body>
+          <header>
+            <h1>#{h(@pack[:pack_name])}</h1>
+            <p>#{h(@pack[:principle])} Draft metrics never reach the board or the briefing.</p>
+            <p class="muted">Generated #{h(@pack[:generated_at])} · #{h(@pack[:certified_by])}</p>
+          </header>
+          <main>
+            <h2>Weekly briefing</h2>
+            <div class="card brief">#{h(briefing_headline)}</div>
+            #{drill_html}
+
+            <h2>Role views</h2>
+            <div class="tabs">
+              <button class="active" data-panel="exec">Exec (all sites)</button>
+              #{location_tab_buttons}
+            </div>
+            <div id="exec" class="panel active">#{kpi_grid(evaluations_for(nil))}</div>
+            #{location_panels}
+
+            <h2>Metric catalog</h2>
+            <table>
+              <thead>
+                <tr><th>Status</th><th>Name</th><th>Definition</th><th>Grain</th><th>Owner</th><th>Why draft?</th></tr>
+              </thead>
+              <tbody>#{catalog_rows}</tbody>
+            </table>
+          </main>
+          <script>
+            document.querySelectorAll('.tabs button').forEach(function(btn) {
+              btn.addEventListener('click', function() {
+                document.querySelectorAll('.tabs button').forEach(function(b) { b.classList.remove('active'); });
+                document.querySelectorAll('.panel').forEach(function(p) { p.classList.remove('active'); });
+                btn.classList.add('active');
+                document.getElementById(btn.dataset.panel).classList.add('active');
+              });
+            });
+          </script>
+        </body>
+        </html>
+      HTML
+    end
+
+    private
+
+    def briefing_headline
+      @pack.dig(:briefing, :headline) || "No briefing."
+    end
+
+    def drill_html
+      drill = @pack.dig(:briefing, :drill_dimension) || {}
+      site = drill[:explaining_site]
+      return "" unless site
+
+      rows = Array(drill[:locations]).map { |l| "#{h(l[:name])}: #{h(l[:value])}" }.join(" · ")
+      %(<p class="muted">Drill on location — weakest site for #{h(drill[:kpi_id])}: <strong>#{h(site[:name])}</strong> (#{h(site[:value])}). #{rows}</p>)
+    end
+
+    def evaluations_for(location_id)
+      key = location_id.nil? ? "all" : location_id.to_s
+      (@pack[:evaluations] || {}).fetch(key, {})
+    end
+
+    def kpi_grid(values)
+      certified = Array(@pack[:kpis]).map do |kpi|
+        val = values[kpi[:id]]
+        <<~CARD
+          <div class="card">
+            <span class="badge ok">certified</span>
+            <div class="muted">#{h(kpi[:name])}</div>
+            <div class="value">#{h(format_value(val))}</div>
+          </div>
+        CARD
+      end
+      drafts = Array(@pack[:drafts]).map do |kpi|
+        <<~CARD
+          <div class="card dim">
+            <span class="badge draft">draft</span>
+            <div class="muted">#{h(kpi[:name])}</div>
+            <div class="value">—</div>
+            <div class="muted">Failed certification; excluded from the board.</div>
+          </div>
+        CARD
+      end
+      %(<div class="grid">#{certified.join}#{drafts.join}</div>)
+    end
+
+    def location_tab_buttons
+      @locations.map do |loc|
+        %(<button data-panel="loc-#{loc[:id]}">Site manager · #{h(loc[:name])}</button>)
+      end.join
+    end
+
+    def location_panels
+      @locations.map do |loc|
+        %(<div id="loc-#{loc[:id]}" class="panel">#{kpi_grid(evaluations_for(loc[:id]))}</div>)
+      end.join
+    end
+
+    def catalog_rows
+      Array(@pack[:catalog]).map do |entry|
+        badge = entry[:status] == "certified" ? %(<span class="badge ok">certified</span>) : %(<span class="badge draft">draft</span>)
+        reasons = Array(entry[:reasons]).map { |r| h(r) }.join("<br>")
+        <<~TR
+          <tr>
+            <td>#{badge}</td>
+            <td>#{h(entry[:name])}<div class="muted"><code>#{h(entry[:id])}</code></div></td>
+            <td>#{h(entry[:english])}<pre>#{h(entry[:sql])}</pre></td>
+            <td>#{h(entry[:grain])}</td>
+            <td>#{h(entry[:owner])}</td>
+            <td>#{reasons.empty? ? "—" : reasons}</td>
+          </tr>
+        TR
+      end.join
+    end
+
+    def format_value(val)
+      return "n/a" if val.nil?
+
+      n = Float(val)
+      n.abs >= 100 ? format("%.0f", n) : format("%.1f", n)
+    rescue ArgumentError, TypeError
+      val.to_s
+    end
+
+    def h(value)
+      CGI.escapeHTML(value.to_s)
+    end
+  end
+end

data/lib/kpi_assembler/location_directory.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "connection"
+
+module KPIAssembler
+  class LocationDirectory
+    def initialize(db, tenant_id: nil)
+      @db = Connection.wrap(db)
+      @tenant_id = tenant_id
+    end
+
+    def all
+      if @tenant_id
+        scoped = fetch("SELECT id, name FROM companies WHERE id = ? LIMIT 1", [Integer(@tenant_id)])
+        return scoped unless scoped.empty?
+      end
+
+      named = fetch("SELECT id, name FROM locations ORDER BY id LIMIT 12")
+      return named unless named.empty?
+
+      fetch("SELECT id, name FROM companies ORDER BY id LIMIT 12")
+    end
+
+    private
+
+    def fetch(sql, binds = [])
+      @db.execute(sql, binds).map { |id, name| { id: id.to_i, name: name.to_s } }
+    rescue StandardError
+      []
+    end
+  end
+end

data/lib/kpi_assembler/metric_evaluator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "connection"
+
+module KPIAssembler
+  class MetricEvaluator
+    attr_reader :db
+
+    def initialize(db)
+      @db = Connection.wrap(db)
+    end
+
+    def value(kpi, from:, to:, location_id: nil)
+      sql = scoped_sql(kpi, location_id: location_id)
+      binds = period_binds(kpi, from: from, to: to)
+      rows =
+        if placeholder_count(sql).positive?
+          db.execute(sql, binds)
+        else
+          db.execute(sql)
+        end
+      raw = rows.dig(0, 0)
+      return nil if raw.nil?
+
+      Float(raw)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def scoped_sql(kpi, location_id: nil)
+      sql = kpi[:sql].to_s.strip.sub(/;\s*\z/, "")
+      return sql unless location_id && kpi[:location_column].to_s.strip != ""
+
+      col = kpi[:location_column]
+      clause = "#{col} = #{Integer(location_id)}"
+      if sql.match?(/\bWHERE\b/i)
+        sql.sub(/\bWHERE\b/i, "WHERE #{clause} AND ")
+      else
+        "#{sql} WHERE #{clause}"
+      end
+    end
+
+    def period_binds(kpi, from:, to:)
+      from_s = iso(from)
+      to_s = iso(to)
+      if kpi[:bind_style].to_s == "end_then_start"
+        [to_s, from_s]
+      else
+        [from_s, to_s]
+      end
+    end
+
+    def placeholder_count(sql)
+      sql.scan("?").length
+    end
+
+    def iso(time)
+      time = Time.parse(time.to_s) unless time.is_a?(Time)
+      time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    end
+  end
+end

data/lib/kpi_assembler/pack_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "time"
+
+module KPIAssembler
+  class PackBuilder
+    def initialize(certified_kpis, drafts: [], briefing: {}, evaluations: {}, schema: {}, version: KPIAssembler::VERSION)
+      @certified_kpis = certified_kpis
+      @drafts = drafts
+      @briefing = briefing
+      @evaluations = evaluations
+      @schema = schema
+      @version = version
+    end
+
+    def build
+      {
+        pack_name: "Certified KPI Pack",
+        version: "1.0.0",
+        generated_at: Time.now.utc.iso8601,
+        certified_by: "KPIAssembler v#{@version}",
+        principle: "The LLM proposes; deterministic code certifies.",
+        catalog: catalog_entries,
+        kpis: @certified_kpis,
+        drafts: @drafts,
+        evaluations: @evaluations,
+        briefing: @briefing,
+        lineage: {
+          tables: @schema.keys,
+          grain: "lead → appointment → membership → invoice",
+          dimension: "location"
+        }
+      }
+    end
+
+    private
+
+    def catalog_entries
+      (@certified_kpis + @drafts).map do |kpi|
+        {
+          id: kpi[:id],
+          name: kpi[:name],
+          english: kpi[:formula_description],
+          sql: kpi[:sql],
+          grain: kpi[:grain],
+          owner: kpi[:owner],
+          status: kpi[:status],
+          reasons: kpi[:reasons]
+        }
+      end
+    end
+  end
+end