kpi_assembler 0.5.0

data/public/app.js

@@ -0,0 +1,372 @@
+(function () {
+  "use strict";
+
+  const state = {
+    candidates: [],
+    selected: new Set(),
+    rankedTables: new Set(),
+    activeLocation: "all"
+  };
+
+  const $ = (selector) => document.querySelector(selector);
+  const $$ = (selector) => Array.from(document.querySelectorAll(selector));
+  const apiBase = document.querySelector('meta[name="kpi-api-base"]')?.content.replace(/\/$/, "") || "/api/v1";
+
+  if (new URLSearchParams(window.location.search).get("embed") === "1") {
+    document.body.classList.add("embed");
+  }
+
+  function escapeHtml(value) {
+    return String(value == null ? "" : value)
+      .replaceAll("&", "&")
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;")
+      .replaceAll('"', "&quot;")
+      .replaceAll("'", "&#039;");
+  }
+
+  async function api(path, options) {
+    const response = await fetch(path, {
+      credentials: "same-origin",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        // Host apps commonly redirect non-XHR requests to a login page.
+        "X-Requested-With": "XMLHttpRequest"
+      },
+      ...options
+    });
+    let payload;
+    try {
+      payload = await response.json();
+    } catch (_error) {
+      throw new Error(
+        "The service returned " + response.status + " " + response.statusText +
+          " instead of JSON (" + path + ")."
+      );
+    }
+    if (!response.ok) throw new Error(payload.error || "Request failed with " + response.status + ".");
+    return payload;
+  }
+
+  function setLoading(button, loading) {
+    button.disabled = loading;
+    button.classList.toggle("loading", loading);
+  }
+
+  let toastTimer;
+  function toast(message, type) {
+    const node = $("#toast");
+    node.textContent = message;
+    node.className = "toast show" + (type === "error" ? " error" : "");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => { node.className = "toast"; }, 3200);
+  }
+
+  function showView(name) {
+    $$(".view").forEach((view) => view.classList.remove("active"));
+    $("#" + name + "-view").classList.add("active");
+    $$(".nav-item").forEach((item) => {
+      item.classList.toggle("active", item.dataset.view === name);
+    });
+
+    const titles = {
+      workspace: "Metric discovery",
+      dashboard: "Trusted analytics",
+      integration: "Integration"
+    };
+    $("#page-title").textContent = titles[name];
+    window.scrollTo({ top: 0, behavior: "smooth" });
+  }
+
+  async function checkHealth() {
+    const status = $("#api-status");
+    try {
+      await api(apiBase + "/health");
+      status.className = "api-status online";
+      status.innerHTML = "<i></i> Service connected";
+    } catch (_error) {
+      status.className = "api-status error";
+      status.innerHTML = "<i></i> Service unavailable";
+    }
+  }
+
+  async function discover() {
+    const buttons = [$("#discover-button"), $("#rediscover-button")];
+    buttons.forEach((button) => setLoading(button, true));
+    try {
+      const result = await api(apiBase + "/discover", { method: "POST", body: "{}" });
+      const tables = result.tables || [];
+      state.candidates = result.candidates || [];
+      state.rankedTables = new Set(result.ranked_tables || []);
+      state.selected = new Set(state.candidates.map((candidate) => String(candidate.id)));
+      renderSchema(tables);
+      renderCandidates();
+      renderDiscoveryNotice(result);
+      $("#source-label").textContent = sourceLabel(result, tables);
+      $("#proposal-subtitle").textContent = proposalSubtitle(result);
+      $("#discovery-results").classList.remove("hidden");
+      $("#discovery-results").scrollIntoView({ behavior: "smooth", block: "start" });
+      toast(
+        tables.length === 0
+          ? "Discovery found no tables. Check the configured table names."
+          : proposalToast(result),
+        tables.length === 0 || result.proposer_fallback ? "error" : undefined
+      );
+    } catch (error) {
+      toast(error.message, "error");
+    } finally {
+      buttons.forEach((button) => setLoading(button, false));
+    }
+  }
+
+  function renderDiscoveryNotice(result) {
+    const notice = $("#discovery-notice");
+    const missing = result.missing_tables || [];
+    const messages = [];
+
+    if (missing.length) {
+      messages.push(
+        "Configured but not found in the database: <strong>" +
+          missing.map(escapeHtml).join(", ") +
+          "</strong>. Check spelling" +
+          (result.schema_name ? ", or whether they live outside schema \"" + escapeHtml(result.schema_name) + '"' : "") +
+          "."
+      );
+    }
+    const omitted = result.omitted_tables || [];
+    if (omitted.length) {
+      messages.push(
+        "Dropped by the <code>max_tables</code> limit of " + escapeHtml(result.max_tables) +
+          ": <strong>" + omitted.map(escapeHtml).join(", ") + "</strong>. Raise the limit to include them."
+      );
+    }
+    if (!(result.tables || []).length) {
+      messages.push("No tables were read, so there is nothing to propose. Update <code>config.include_tables</code> and restart the application.");
+    }
+    if (result.proposer_fallback) {
+      messages.push(
+        "LLM proposal was not used (" + escapeHtml(result.proposer_fallback) +
+          "). Showing schema-driven heuristics instead."
+      );
+    } else if (result.proposer === "llm") {
+      const ranked = result.ranked_tables || [];
+      messages.push(
+        "LLM ranked " + ranked.length + " table" + (ranked.length === 1 ? "" : "s") +
+          (ranked.length ? " (<strong>" + ranked.map(escapeHtml).join(", ") + "</strong>)" : "") +
+          " and proposed KPIs. Heuristics filled any gaps. SQL is still untrusted until certification."
+      );
+    }
+
+    notice.innerHTML = messages.join("<br>");
+    notice.classList.toggle("hidden", messages.length === 0);
+  }
+
+  function sourceLabel(result, tables) {
+    const bits = [result.source, tables.length + " tables"];
+    if (result.schema_name) bits.push("schema " + result.schema_name);
+    if (result.proposer === "llm") {
+      bits.push("proposer " + (result.proposer_model || "llm"));
+    } else {
+      bits.push("proposer heuristics");
+    }
+    return bits.join(" · ");
+  }
+
+  function proposalSubtitle(result) {
+    if (result.proposer === "llm") {
+      return "The model ranked discovered tables and wrote recipes. They are not trusted until certification.";
+    }
+    if (result.proposer_fallback) {
+      return "Heuristics proposed these metrics because the LLM was unavailable.";
+    }
+    return "Schema heuristics proposed these metrics. Configure Gemini or Ollama to let the model rank tables.";
+  }
+
+  function proposalToast(result) {
+    if (result.proposer === "llm") return "LLM proposed metrics from the discovered schema.";
+    if (result.proposer_fallback) return "LLM unavailable — showing heuristic KPIs.";
+    return "Discovery complete. Review the proposed definitions.";
+  }
+
+  function renderSchema(tables) {
+    $("#schema-summary").innerHTML = tables.map((table) => {
+      const columns = (table.columns || []).slice(0, 4).map((column) => escapeHtml(column.name)).join(" · ");
+      const more = (table.columns || []).length > 4 ? " +" + ((table.columns || []).length - 4) : "";
+      const ranked = state.rankedTables.has(table.name);
+      return `
+        <article class="schema-card${ranked ? " ranked" : ""}">
+          <span class="schema-icon">▤</span>
+          <strong>${escapeHtml(table.name)}</strong>
+          <small>${ranked ? "LLM-ranked · " : ""}${escapeHtml(table.row_count)} rows · ${(table.foreign_keys || []).length} relations</small>
+          <div class="column-list">${columns}${more}</div>
+        </article>`;
+    }).join("");
+  }
+
+  function renderCandidates() {
+    $("#candidate-list").innerHTML = state.candidates.map((candidate) => {
+      const id = String(candidate.id);
+      const selected = state.selected.has(id);
+      return `
+        <article class="candidate ${selected ? "selected" : ""}" data-id="${escapeHtml(id)}">
+          <input type="checkbox" aria-label="Select ${escapeHtml(candidate.name)}" ${selected ? "checked" : ""}>
+          <div class="candidate-name">
+            <strong>${escapeHtml(candidate.name)}</strong>
+            <small>${escapeHtml(candidate.category)} · owner: ${escapeHtml(candidate.owner || "unassigned")} · ${escapeHtml(candidate.source || "heuristics")}</small>
+          </div>
+          <div class="candidate-definition">${escapeHtml(candidate.formula_description)}</div>
+          <span class="grain">${escapeHtml(candidate.grain)}</span>
+          <button class="sql-toggle" type="button" aria-label="View SQL">&lt;/&gt;</button>
+          <pre class="candidate-sql">${escapeHtml(candidate.sql)}</pre>
+        </article>`;
+    }).join("");
+    updateSelectedCount();
+
+    $$(".candidate").forEach((card) => {
+      card.addEventListener("click", (event) => {
+        if (event.target.closest(".sql-toggle")) {
+          event.preventDefault();
+          event.stopPropagation();
+          card.classList.toggle("open");
+          return;
+        }
+        const checkbox = card.querySelector("input");
+        if (event.target !== checkbox) checkbox.checked = !checkbox.checked;
+        setSelected(card.dataset.id, checkbox.checked, card);
+      });
+    });
+  }
+
+  function setSelected(id, selected, card) {
+    if (selected) state.selected.add(id);
+    else state.selected.delete(id);
+    card.classList.toggle("selected", selected);
+    updateSelectedCount();
+  }
+
+  function updateSelectedCount() {
+    $("#selected-count").textContent = state.selected.size;
+    $("#certify-button").disabled = state.selected.size === 0;
+  }
+
+  async function certify() {
+    const button = $("#certify-button");
+    setLoading(button, true);
+    try {
+      state.pack = await api(apiBase + "/certify", {
+        method: "POST",
+        body: JSON.stringify({ accepted_ids: Array.from(state.selected) })
+      });
+      state.activeLocation = "all";
+      renderPack();
+      showView("dashboard");
+      toast(
+        state.pack.kpis.length + " certified · " + state.pack.drafts.length + " held as draft"
+      );
+    } catch (error) {
+      toast(error.message, "error");
+    } finally {
+      setLoading(button, false);
+    }
+  }
+
+  function renderPack() {
+    const pack = state.pack;
+    if (!pack) return;
+
+    $("#empty-dashboard").classList.add("hidden");
+    $("#pack-content").classList.remove("hidden");
+    $("#briefing-headline").textContent = pack.briefing.headline;
+    const drill = pack.briefing.drill_dimension || {};
+    $("#briefing-drill").textContent = drill.explaining_site
+      ? "Location drill: " + drill.explaining_site.name + " is the lowest site for " + drill.kpi_id + "."
+      : "No location-level exception was detected.";
+
+    renderRoleTabs();
+    renderMetricGrid();
+    $("#certification-report").innerHTML = (pack.catalog || []).map((entry) => {
+      const passed = entry.status === "certified";
+      const explanation = passed
+        ? "Passed schema, join safety, division safety, grain, query-plan, and sample replay checks."
+        : (entry.reasons || []).join(" · ");
+      return `
+        <article class="report-row">
+          <span class="report-status ${passed ? "" : "draft"}">${escapeHtml(entry.status)}</span>
+          <strong>${escapeHtml(entry.name)}</strong>
+          <p>${escapeHtml(explanation)}</p>
+        </article>`;
+    }).join("");
+  }
+
+  function renderRoleTabs() {
+    const tabs = [{ id: "all", name: "Executive · All sites" }].concat(
+      (state.pack.locations || []).map((location) => ({
+        id: String(location.id),
+        name: "Site manager · " + location.name
+      }))
+    );
+    $("#role-tabs").innerHTML = tabs.map((tab) => `
+      <button class="role-tab ${state.activeLocation === tab.id ? "active" : ""}" data-location="${escapeHtml(tab.id)}">
+        ${escapeHtml(tab.name)}
+      </button>`).join("");
+    $$(".role-tab").forEach((tab) => {
+      tab.addEventListener("click", () => {
+        state.activeLocation = tab.dataset.location;
+        renderRoleTabs();
+        renderMetricGrid();
+      });
+    });
+  }
+
+  function renderMetricGrid() {
+    const values = (state.pack.evaluations || {})[state.activeLocation] || {};
+    $("#metric-grid").innerHTML = (state.pack.kpis || []).map((kpi) => `
+      <article class="metric-card">
+        <div class="metric-label"><span>${escapeHtml(kpi.name)}</span><i class="status-dot"></i></div>
+        <div class="metric-value">${escapeHtml(formatMetric(values[kpi.id], kpi))}</div>
+        <small>Certified · ${escapeHtml(kpi.grain)} grain · ${escapeHtml(kpi.owner)}</small>
+      </article>`).join("");
+  }
+
+  function formatMetric(value, kpi) {
+    if (value == null) return "No data";
+    const number = Number(value);
+    const name = String(kpi.name).toLowerCase();
+    if (name.includes("rate") || name.includes("conversion")) return number.toFixed(1) + "%";
+    if (name.includes("revenue") || name.includes("mrr")) {
+      return new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 }).format(number);
+    }
+    return new Intl.NumberFormat("en-US", { maximumFractionDigits: 1 }).format(number);
+  }
+
+  function downloadPack() {
+    if (!state.pack) return;
+    const blob = new Blob([JSON.stringify(state.pack, null, 2)], { type: "application/json" });
+    const link = document.createElement("a");
+    link.href = URL.createObjectURL(blob);
+    link.download = "kpi-pack.json";
+    link.click();
+    URL.revokeObjectURL(link.href);
+  }
+
+  $$(".nav-item").forEach((item) => item.addEventListener("click", () => showView(item.dataset.view)));
+  $("#integration-shortcut").addEventListener("click", () => showView("integration"));
+  $("#discover-button").addEventListener("click", discover);
+  $("#rediscover-button").addEventListener("click", discover);
+  $("#certify-button").addEventListener("click", certify);
+  $("#back-to-catalog").addEventListener("click", () => showView("workspace"));
+  $("#empty-discover").addEventListener("click", () => { showView("workspace"); discover(); });
+  $("#download-pack").addEventListener("click", downloadPack);
+
+  $$(".copy-button").forEach((button) => {
+    button.addEventListener("click", async () => {
+      const target = $("#" + button.dataset.copy);
+      await navigator.clipboard.writeText(target.textContent);
+      button.textContent = "Copied";
+      setTimeout(() => { button.textContent = "Copy"; }, 1400);
+    });
+  });
+
+  checkHealth();
+}());

data/public/index.html

@@ -0,0 +1,240 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="description" content="Discover and certify trusted KPIs from an application database.">
+    <meta name="kpi-api-base" content="/api/v1">
+    <title>KPIAssembler — Certified analytics</title>
+    <link rel="stylesheet" href="/app.css">
+    <script src="/app.js" defer></script>
+  </head>
+  <body>
+    <div class="app-shell">
+      <aside class="sidebar">
+        <a class="brand" href="#" aria-label="KPIAssembler home">
+          <span class="brand-mark" aria-hidden="true">
+            <span></span><span></span><span></span>
+          </span>
+          <span>KPI<span>Assembler</span></span>
+        </a>
+
+        <nav aria-label="Workflow">
+          <p class="nav-label">Workflow</p>
+          <button class="nav-item active" data-view="workspace">
+            <span class="nav-number">1</span>
+            <span><strong>Discover</strong><small>Inspect your data model</small></span>
+          </button>
+          <button class="nav-item" data-view="workspace">
+            <span class="nav-number">2</span>
+            <span><strong>Propose</strong><small>Review candidate KPIs</small></span>
+          </button>
+          <button class="nav-item" data-view="workspace">
+            <span class="nav-number">3</span>
+            <span><strong>Certify</strong><small>Run deterministic checks</small></span>
+          </button>
+          <button class="nav-item" data-view="dashboard">
+            <span class="nav-number">4</span>
+            <span><strong>Publish</strong><small>Use the trusted pack</small></span>
+          </button>
+          <p class="nav-label secondary">Product</p>
+          <button class="nav-item simple" data-view="integration">
+            <span class="nav-icon">&lt;/&gt;</span>
+            <span><strong>Integrate</strong><small>API and embed options</small></span>
+          </button>
+        </nav>
+
+        <div class="trust-note">
+          <span class="shield">✓</span>
+          <div><strong>Trust boundary</strong><small>The model proposes.<br>Code certifies.</small></div>
+        </div>
+      </aside>
+
+      <div class="page">
+        <header class="topbar">
+          <div>
+            <p class="eyebrow">KPI discovery workspace</p>
+            <h1 id="page-title">Metric discovery</h1>
+          </div>
+          <div class="top-actions">
+            <span id="api-status" class="api-status"><i></i> Checking service</span>
+            <button class="button ghost" id="integration-shortcut">Integration guide</button>
+          </div>
+        </header>
+
+        <main>
+          <section id="workspace-view" class="view active">
+            <div class="hero">
+              <div>
+                <span class="kicker">AI-first metric governance</span>
+                <h2>Turn application data into<br><em>metrics you can trust.</em></h2>
+                <p>Point KPIAssembler at an application database. It reads the schema, proposes KPI definitions, and certifies the SQL before a number is trusted.</p>
+                <div class="hero-actions">
+                  <button class="button primary" id="discover-button">
+                    <span class="button-icon">⌁</span>
+                    Discover metrics
+                  </button>
+                  <span class="privacy"><span>●</span> Runs locally · Your data stays yours</span>
+                </div>
+              </div>
+              <div class="pipeline-visual" aria-label="Discovery pipeline diagram">
+                <div class="pipeline-node database">
+                  <span class="node-icon">▤</span>
+                  <strong>Any app DB</strong>
+                  <small>SQLite or Postgres</small>
+                </div>
+                <div class="pipeline-line"><span></span></div>
+                <div class="pipeline-node model">
+                  <span class="node-icon">✦</span>
+                  <strong>Metric proposer</strong>
+                  <small>Local LLM / heuristics</small>
+                </div>
+                <div class="pipeline-line"><span></span></div>
+                <div class="pipeline-node certified">
+                  <span class="node-icon">✓</span>
+                  <strong>Certified pack</strong>
+                  <small>Deterministic checks</small>
+                </div>
+              </div>
+            </div>
+
+            <div id="discovery-results" class="results hidden">
+              <div class="section-heading">
+                <div>
+                  <span class="step-tag">01 · DISCOVERED</span>
+                  <h2>Your application data model</h2>
+                  <p id="source-label">Connected source</p>
+                </div>
+                <button class="button ghost compact" id="rediscover-button">Scan again</button>
+              </div>
+
+              <div id="discovery-notice" class="discovery-notice hidden" role="status"></div>
+
+              <div id="schema-summary" class="schema-grid" aria-live="polite"></div>
+
+              <div class="section-heading candidates-heading">
+                <div>
+                  <span class="step-tag violet">02 · PROPOSED</span>
+                  <h2>Select metrics to certify</h2>
+                  <p id="proposal-subtitle">The proposal can be edited or rejected. It is not trusted yet.</p>
+                </div>
+                <div class="selection-count"><strong id="selected-count">0</strong> selected</div>
+              </div>
+
+              <div id="candidate-list" class="candidate-list"></div>
+
+              <div class="certify-bar">
+                <div>
+                  <span class="shield large">✓</span>
+                  <div><strong>Ready for deterministic certification</strong><small>Schema, join, null-safety, grain, and execution checks</small></div>
+                </div>
+                <button class="button primary" id="certify-button">Certify selected metrics <span>→</span></button>
+              </div>
+            </div>
+          </section>
+
+          <section id="dashboard-view" class="view">
+            <div class="dashboard-heading">
+              <div>
+                <span class="step-tag green">04 · PUBLISHED</span>
+                <h2>Certified KPI pack</h2>
+                <p>Only metrics that passed deterministic checks are shown as trusted values.</p>
+              </div>
+              <button class="button ghost compact" id="back-to-catalog">← Edit catalog</button>
+            </div>
+
+            <div id="empty-dashboard" class="empty-state">
+              <span>◇</span>
+              <h3>No certified pack yet</h3>
+              <p>Discover your schema and certify at least one proposed metric.</p>
+              <button class="button primary" id="empty-discover">Start discovery</button>
+            </div>
+
+            <div id="pack-content" class="hidden">
+              <article class="briefing-card">
+                <div class="briefing-icon">✦</div>
+                <div>
+                  <span>OPERATING BRIEFING · LAST 30 DAYS</span>
+                  <p id="briefing-headline"></p>
+                  <small id="briefing-drill"></small>
+                </div>
+              </article>
+
+              <div class="role-tabs" id="role-tabs"></div>
+              <div id="metric-grid" class="metric-grid"></div>
+
+              <div class="catalog-heading">
+                <div>
+                  <h3>Certification report</h3>
+                  <p>Every accepted proposal has an explicit outcome and audit trail.</p>
+                </div>
+                <button class="button ghost compact" id="download-pack">Download JSON</button>
+              </div>
+              <div id="certification-report" class="certification-report"></div>
+            </div>
+          </section>
+
+          <section id="integration-view" class="view">
+            <div class="integration-hero">
+              <span class="step-tag violet">FRAMEWORK AGNOSTIC</span>
+              <h2>Bring trusted metrics into<br>any application.</h2>
+              <p>KPIAssembler runs as a sidecar service. Your product can consume its versioned REST API or embed the complete workflow with one web component.</p>
+            </div>
+
+            <div class="integration-grid">
+              <article class="integration-card featured">
+                <span class="integration-type">01 · WEB COMPONENT</span>
+                <h3>Embed the complete UI</h3>
+                <p>Works in Rails, React, Angular, Vue, plain HTML, or any application that renders a webpage.</p>
+                <div class="code-block">
+                  <button class="copy-button" data-copy="embed-code">Copy</button>
+                  <pre id="embed-code"><code>&lt;script src="http://localhost:9292/kpi-assembler.js"&gt;&lt;/script&gt;
+&lt;kpi-assembler
+  service-url="http://localhost:9292"
+  height="820px"&gt;
+&lt;/kpi-assembler&gt;</code></pre>
+                </div>
+              </article>
+
+              <article class="integration-card">
+                <span class="integration-type">02 · REST API</span>
+                <h3>Build your own experience</h3>
+                <p>Use the certification engine from a mobile app, backend, BI surface, or existing admin panel.</p>
+                <div class="code-block">
+                  <button class="copy-button" data-copy="api-code">Copy</button>
+                  <pre id="api-code"><code>POST /api/v1/discover
+
+POST /api/v1/certify
+{
+  "accepted_ids": [
+    "lead_conversion_rate",
+    "paid_mrr"
+  ]
+}
+
+GET /api/v1/pack</code></pre>
+                </div>
+              </article>
+            </div>
+
+            <div class="integration-steps">
+              <h3>Application setup</h3>
+              <ol>
+                <li><span>1</span><div><strong>Run the service</strong><code>bundle exec ruby bin/kpi_assembler_web</code></div></li>
+                <li><span>2</span><div><strong>Connect an application database</strong><code>KPI_DATABASE_URL=postgres://user:pass@host:5432/application</code></div></li>
+                <li><span>3</span><div><strong>Limit tables / tenant</strong><code>KPI_INCLUDE_TABLES=orders,customers,accounts KPI_TENANT_ID=123</code></div></li>
+                <li><span>4</span><div><strong>Restrict browser access in production</strong><code>KPI_ALLOWED_ORIGIN=https://your-app.example</code></div></li>
+              </ol>
+              <aside>
+                <span>Important</span>
+                <p>Use a read-only database user or replica in production. KPIAssembler executes candidate queries during certification.</p>
+              </aside>
+            </div>
+          </section>
+        </main>
+      </div>
+    </div>
+
+    <div id="toast" class="toast" role="status" aria-live="polite"></div>
+  </body>
+</html>