kpi_assembler 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73810fbb8d6411ed8f52fd84ac84bed1c50372b2fa9cac5bb5bbce43de714130
+  data.tar.gz: efd60220f7d69ab53a23162048a65226a5ac5f4ab852e6685cde31c0298d4bab
+SHA512:
+  metadata.gz: 10baca12a1597969b0bf610da6cbf7b505655b74b55b07d1532a661f7649e13ebc704f8e2a119855871877afa0d7c7f9fad349bf7460189d8ee98ae59f72e3e1
+  data.tar.gz: bdab7aef95e09eea0ae8d62a622859d0bd096e2c96072e642fd4e164a6835d1535a671b848a346d3e3d32cfa7285c389f304171bc8278e8b4803e50f50357738

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KPIAssembler contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# KPIAssembler
+
+KPIAssembler discovers application schemas, proposes useful business metrics,
+and deterministically certifies generated SQL before publishing a KPI pack.
+
+The LLM proposes; deterministic code certifies. Candidate queries are checked
+against the real schema, tenant boundary, SQL safety rules, query planner, and
+sample execution before they can be marked certified.
+
+## Features
+
+- Mountable Rails Engine with an interactive workspace and JSON API
+- Standalone Rack application and command-line interface
+- SQLite and PostgreSQL schema introspection
+- Gemini and Ollama KPI proposal providers
+- Schema-driven heuristic fallback when no model is available
+- Deterministic SQL, join, division, tenant, and execution checks
+- JSON and HTML KPI packs
+
+## Install
+
+Add the gem to your application:
+
+```ruby
+gem "kpi_assembler"
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails generate kpi_assembler:install
+```
+
+Mount the engine:
+
+```ruby
+mount KPIAssembler::Engine => "/kpi-assembler"
+```
+
+See [Rails Engine integration](docs/rails-engine.md) for configuration and
+[standalone integration](docs/integration.md) for Rack, CLI, and API usage.
+
+## LLM configuration
+
+Gemini:
+
+```bash
+KPI_LLM_PROVIDER=gemini
+GEMINI_API_KEY=your-key
+KPI_GEMINI_MODEL=gemini-2.0-flash
+```
+
+Ollama:
+
+```bash
+KPI_LLM_PROVIDER=ollama
+KPI_OLLAMA_MODEL=llama3.2:3b
+KPI_OLLAMA_URL=http://localhost:11434/api/generate
+```
+
+Set `KPI_USE_LLM=false` to use schema-driven heuristics only.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec ruby bin/kpi_assembler --sample-db
+bundle exec ruby bin/kpi_assembler_web
+```
+
+The standalone workspace starts at `http://127.0.0.1:9292`.
+
+## Security
+
+Use a read-only database user or replica. Generated candidate SQL is executed
+during deterministic certification. Configure tenant scoping and authorization
+before exposing the engine or API.
+
+## License
+
+MIT

data/app/controllers/kpi_assembler/api/v1/workspace_controller.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module KPIAssembler
+  module Api
+    module V1
+      class WorkspaceController < KPIAssembler::ApplicationController
+        skip_forgery_protection
+
+        rescue_from KPIAssembler::Error, with: :unprocessable_entity
+        rescue_from JSON::ParserError, with: :invalid_json
+
+        def health
+          render json: {
+            status: "ok",
+            service: "KPIAssembler",
+            version: KPIAssembler::VERSION,
+            source: kpi_service.db.label,
+            dialect: kpi_service.db.dialect,
+            principle: "The LLM proposes; deterministic code certifies."
+          }
+        end
+
+        def discover
+          render json: kpi_service.discover
+        end
+
+        def certify
+          pack = kpi_service.certify(request_payload["accepted_ids"])
+          render json: pack.merge(locations: kpi_service.locations)
+        end
+
+        def pack
+          value = kpi_service.pack
+          return render json: { error: "No pack has been certified yet" }, status: :not_found unless value
+
+          render json: value.merge(locations: kpi_service.locations)
+        end
+
+        def integration
+          render json: {
+            api_version: "v1",
+            mount_path: request.script_name,
+            discovery_endpoint: api_v1_discover_path,
+            certification_endpoint: api_v1_certify_path,
+            pack_endpoint: api_v1_pack_path
+          }
+        end
+
+        private
+
+        def request_payload
+          return {} if request.raw_post.empty?
+
+          JSON.parse(request.raw_post)
+        end
+
+        def unprocessable_entity(error)
+          render json: { error: error.message }, status: :unprocessable_entity
+        end
+
+        def invalid_json
+          render json: { error: "Request body must be valid JSON" }, status: :bad_request
+        end
+      end
+    end
+  end
+end

data/app/controllers/kpi_assembler/application_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module KPIAssembler
+  class ApplicationController < KPIAssembler.configuration.parent_controller.constantize
+    before_action :authorize_kpi_assembler!
+
+    private
+
+    def authorize_kpi_assembler!
+      return if KPIAssembler.authorized?(self)
+
+      head :forbidden
+    end
+
+    def kpi_service
+      KPIAssembler.service_for(self)
+    end
+  end
+end

data/app/controllers/kpi_assembler/workspace_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module KPIAssembler
+  class WorkspaceController < ApplicationController
+    def show
+      base = request.script_name.to_s.sub(%r{/\z}, "")
+      html = File.read(KPIAssembler::Engine.root.join("public/index.html"))
+      html.sub!('<meta name="kpi-api-base" content="/api/v1">', %(<meta name="kpi-api-base" content="#{base}/api/v1">))
+      html.sub!('href="/app.css"', %(href="#{base}/assets/app.css"))
+      html.sub!('src="/app.js"', %(src="#{base}/assets/app.js"))
+      html.gsub!("http://localhost:9292/kpi-assembler.js", "#{request.base_url}#{base}/assets/kpi-assembler.js")
+      html.gsub!('service-url="http://localhost:9292"', %(service-url="#{request.base_url}#{base}"))
+
+      render html: html.html_safe, layout: false
+    end
+  end
+end

data/bin/kpi_assembler

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/kpi_assembler"
+
+options = {
+  sample_db: true,
+  use_ollama: false,
+  demo: true,
+  output: File.expand_path("../output", __dir__)
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: ruby bin/kpi_assembler [options]"
+  opts.on("--sample-db", "Use the built-in CRM funnel SQLite sample (default)") { options[:sample_db] = true }
+  opts.on("--db PATH", "Open a SQLite database") do |path|
+    options[:sample_db] = false
+    options[:db_path] = path
+  end
+  opts.on("--url URL", "Connect with a database URL (postgres:// or sqlite://)") do |url|
+    options[:sample_db] = false
+    options[:database_url] = url
+  end
+  opts.on("--tables NAMES", "Comma-separated tables to inspect") do |names|
+    options[:include_tables] = names.split(",").map(&:strip)
+  end
+  opts.on("--tenant-id ID", Integer, "Scope generated SQL to this company/location id") do |id|
+    options[:tenant_id] = id
+    options[:tenant_column] ||= "company_id"
+  end
+  opts.on("--ollama", "Propose KPIs via local Ollama (falls back to schema heuristics)") do
+    options[:use_llm] = true
+    options[:llm_provider] = :ollama
+  end
+  opts.on("--ollama-model NAME", "Ollama model name (default: llama3)") { |n| options[:ollama_model] = n }
+  opts.on("--gemini", "Propose KPIs via Google Gemini API") do
+    options[:use_llm] = true
+    options[:llm_provider] = :gemini
+  end
+  opts.on("--gemini-key KEY", "Google Gemini API key (or set GEMINI_API_KEY)") { |k| options[:gemini_api_key] = k }
+  opts.on("--gemini-model NAME", "Gemini model name (default: gemini-2.0-flash)") { |n| options[:gemini_model] = n }
+  opts.on("--accept IDS", "Comma-separated KPI ids to send through certification") do |ids|
+    options[:accept_ids] = ids.split(",").map(&:strip)
+    options[:demo] = false
+  end
+  opts.on("--accept-all", "Skip the human gate; certify every proposal") { options[:accept_all] = true }
+  opts.on("--output DIR", "Directory for kpi_pack.json and kpi_pack.html") { |d| options[:output] = d }
+end
+parser.parse!
+
+puts "======================================================="
+puts "  KPIAssembler — Autonomous Certified Analytics Pack  "
+puts "======================================================="
+
+db =
+  if options[:database_url]
+    puts "Connecting to #{options[:database_url].sub(/:[^:@]+@/, ":***@")}..."
+    KPIAssembler::Connection.from_url(options[:database_url])
+  elsif options[:db_path]
+    puts "Opening SQLite #{options[:db_path]}..."
+    KPIAssembler::Connection.open(sqlite_path: options[:db_path])
+  else
+    puts "Loading sample CRM database..."
+    KPIAssembler::Connection.wrap(KPIAssembler::SampleDatabase.build)
+  end
+
+pipeline = KPIAssembler::Pipeline.new(db_connection: db, options: options)
+pack = pipeline.run
+json_path, html_path = pipeline.write_outputs!(pack, options[:output])
+
+puts
+puts "Wrote #{json_path}"
+puts "Wrote #{html_path}"
+puts
+puts "Certified: #{pack[:kpis].map { |k| k[:id] }.join(", ")}"
+puts "Draft:     #{pack[:drafts].map { |k| k[:id] }.join(", ")}"

data/bin/kpi_assembler_web

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+ENV["RACK_ENV"] ||= "development"
+
+require "rackup"
+require "puma"
+
+host = ENV.fetch("HOST", "127.0.0.1")
+port = Integer(ENV.fetch("PORT", "9292"))
+config = File.expand_path("../config.ru", __dir__)
+
+puts "KPIAssembler UI: http://#{host}:#{port}"
+Rackup::Server.start(
+  app: Rack::Builder.parse_file(config),
+  Host: host,
+  Port: port,
+  server: "puma"
+)

data/config/routes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+KPIAssembler::Engine.routes.draw do
+  root "workspace#show"
+
+  mount KPIAssembler::AssetServer.new => "/assets"
+
+  namespace :api do
+    namespace :v1 do
+      get "health", to: "workspace#health"
+      match "discover", to: "workspace#discover", via: %i[get post]
+      post "certify", to: "workspace#certify"
+      get "pack", to: "workspace#pack"
+      get "integration", to: "workspace#integration"
+    end
+  end
+end

data/docs/integration.md

@@ -0,0 +1,89 @@
+# Standalone integration
+
+KPIAssembler can run as a Rack service and expose its workspace and JSON API to
+applications written in any language.
+
+## Start the service
+
+Copy `.env.example` to `.env`, configure a read-only database connection, then:
+
+```bash
+bundle install
+bundle exec ruby bin/kpi_assembler_web
+```
+
+The service starts at `http://127.0.0.1:9292`.
+
+```bash
+HOST=0.0.0.0
+PORT=9292
+KPI_DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/application
+KPI_ALLOWED_ORIGIN=https://application.example
+KPI_INCLUDE_TABLES=orders,customers,accounts
+KPI_TENANT_COLUMN=account_id
+KPI_TENANT_ID=123
+```
+
+Use a read-only database user, replica, or database copy.
+
+## LLM provider
+
+Gemini:
+
+```bash
+KPI_LLM_PROVIDER=gemini
+GEMINI_API_KEY=your-key
+KPI_GEMINI_MODEL=gemini-2.0-flash
+```
+
+Local Ollama:
+
+```bash
+KPI_LLM_PROVIDER=ollama
+KPI_OLLAMA_MODEL=llama3.2:3b
+KPI_OLLAMA_URL=http://localhost:11434/api/generate
+```
+
+The model only proposes definitions. Deterministic code certifies every
+accepted candidate. Set `KPI_USE_LLM=false` to use heuristics only.
+
+## Embed the workspace
+
+```html
+<script src="http://localhost:9292/kpi-assembler.js"></script>
+<kpi-assembler service-url="http://localhost:9292" height="820px"></kpi-assembler>
+```
+
+## JSON API
+
+Discover the schema and proposals:
+
+```http
+POST /api/v1/discover
+Content-Type: application/json
+
+{}
+```
+
+Certify selected proposals:
+
+```http
+POST /api/v1/certify
+Content-Type: application/json
+
+{"accepted_ids":["orders_total_sum","customers_volume"]}
+```
+
+Retrieve the latest pack:
+
+```http
+GET /api/v1/pack
+```
+
+## Production requirements
+
+- Require authentication and authorization.
+- Set a specific `KPI_ALLOWED_ORIGIN`.
+- Use least-privilege, read-only database access.
+- Enforce tenant isolation at both application and database boundaries.
+- Persist versioned packs outside the process.

data/docs/rails-engine.md

@@ -0,0 +1,92 @@
+# Rails Engine integration
+
+KPIAssembler is a mountable Rails Engine. It uses the host application's
+session, authorization, and Active Record connection pool.
+
+## Install
+
+```ruby
+gem "kpi_assembler"
+```
+
+```bash
+bundle install
+bin/rails generate kpi_assembler:install
+```
+
+The generator creates `config/initializers/kpi_assembler.rb`.
+
+## Configure
+
+```ruby
+KPIAssembler.configure do |config|
+  config.connection_provider = lambda do |_controller|
+    ApplicationRecord.connected_to(role: :reading) do
+      ApplicationRecord.connection_pool
+    end
+  end
+
+  config.parent_controller = "ApplicationController"
+  config.tenant_column = "account_id"
+  config.tenant_id_resolver = lambda do |controller|
+    controller.send(:current_account).id
+  end
+
+  config.include_tables = []
+  config.max_tables = 30
+  config.schema_name = "public"
+
+  config.authorize_with = lambda do |controller|
+    controller.send(:authenticate_user!)
+    controller.send(:current_account).present?
+  end
+
+  config.llm_provider = ENV.fetch("KPI_LLM_PROVIDER", "gemini").to_sym
+  config.use_llm = ENV["KPI_USE_LLM"] != "false"
+
+  config.gemini_api_key = ENV["GEMINI_API_KEY"]
+  config.gemini_model = ENV.fetch("KPI_GEMINI_MODEL", "gemini-2.0-flash")
+
+  config.ollama_model = ENV.fetch("KPI_OLLAMA_MODEL", "llama3.2:3b")
+  config.ollama_url = ENV.fetch(
+    "KPI_OLLAMA_URL",
+    "http://localhost:11434/api/generate"
+  )
+end
+```
+
+Store secrets in the host application's environment rather than the initializer:
+
+```bash
+KPI_LLM_PROVIDER=gemini
+GEMINI_API_KEY=your-key
+KPI_GEMINI_MODEL=gemini-2.0-flash
+```
+
+Restart the Rails server after changing environment variables.
+
+## Mount
+
+Add the engine to `config/routes.rb`:
+
+```ruby
+mount KPIAssembler::Engine => "/kpi-assembler"
+```
+
+The mounted endpoints are:
+
+```text
+GET/POST /kpi-assembler/api/v1/discover
+POST     /kpi-assembler/api/v1/certify
+GET      /kpi-assembler/api/v1/pack
+```
+
+## Production guidance
+
+Point `connection_provider` at a read-only pool. Replace the example
+authorization callback with the host application's permission policy. Tenant
+scoping must correspond to real columns in the inspected tables.
+
+The engine currently keeps the latest pack in process memory per tenant.
+Production applications should persist versioned packs and define an
+invalidation policy.

data/lib/generators/kpi_assembler/install_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module KPIAssembler
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      # `KpiAssembler` is an alias of `KPIAssembler`, which Rails would
+      # otherwise expose as `k_p_i_assembler:install`.
+      namespace "kpi_assembler:install"
+
+      desc "Creates config/initializers/kpi_assembler.rb in the host application."
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "kpi_assembler.rb", "config/initializers/kpi_assembler.rb"
+      end
+
+      def print_mount_instruction
+        say "\nMount KPIAssembler in config/routes.rb:", :green
+        say '  mount KPIAssembler::Engine => "/kpi-assembler"'
+      end
+    end
+  end
+end

data/lib/generators/kpi_assembler/templates/kpi_assembler.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+KPIAssembler.configure do |config|
+  # Use the host application's ActiveRecord pool. In a multi-database Rails app,
+  # return the read/report pool here instead of the primary write pool.
+  config.connection_provider = lambda do |_controller|
+    ApplicationRecord.connected_to(role: :reading) do
+      ApplicationRecord.connection_pool
+    end
+  end
+
+  # Keep every generated query inside the current tenant.
+  config.tenant_column = "company_id"
+  config.tenant_id_resolver = lambda do |controller|
+    controller.send(:current_company).id
+  end
+
+  # Optional allowlist. Leave empty so the inspector reads the live schema and
+  # the LLM ranks tables that actually exist. Names must match the database
+  # (people, not Person). Pin tables here only to constrain cost or tenancy.
+  config.include_tables = []
+  config.max_tables = 30
+  config.schema_name = "public"
+
+  # The engine inherits the host controller, including authentication and
+  # authorization callbacks. This extra gate must return true.
+  config.parent_controller = "ApplicationController"
+  config.authorize_with = lambda do |controller|
+    controller.send(:authenticate_user!)
+    controller.send(:current_company).present?
+  end
+
+  # The LLM ranks discovered tables and proposes KPIs. Ruby still certifies.
+  # Choose your provider (:gemini or :ollama). Set KPI_USE_LLM=false to use heuristics only.
+  # Gemini: requires GEMINI_API_KEY environment variable.
+  # Ollama: requires a running local daemon (e.g. `ollama serve`).
+  config.llm_provider = ENV.fetch("KPI_LLM_PROVIDER", :gemini).to_sym
+  config.use_llm = ENV["KPI_USE_LLM"] != "false"
+
+  # Gemini configuration
+  config.gemini_api_key = ENV["GEMINI_API_KEY"]
+  config.gemini_model = ENV.fetch("KPI_GEMINI_MODEL", "gemini-2.0-flash")
+
+  # Ollama configuration
+  config.ollama_model = ENV.fetch("KPI_OLLAMA_MODEL", "llama3")
+  config.ollama_url = ENV.fetch("KPI_OLLAMA_URL", "http://localhost:11434/api/generate")
+end

data/lib/kpi_assembler/asset_server.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module KPIAssembler
+  # Serves the workspace's static UI files as a plain Rack endpoint.
+  #
+  # These files carry no tenant data, so they do not need the host application's
+  # controller stack — and routing them through it is actively harmful: Rails
+  # raises InvalidCrossOriginRequest (422) for a `.js` response rendered inside
+  # the forgery-protection chain, which breaks the <script> tag on the page.
+  class AssetServer
+    ROOT = ::File.expand_path("../../public", __dir__)
+
+    CONTENT_TYPES = {
+      "app.css" => "text/css",
+      "app.js" => "text/javascript",
+      "kpi-assembler.js" => "text/javascript"
+    }.freeze
+
+    def call(env)
+      name = env["PATH_INFO"].to_s.delete_prefix("/")
+      content_type = CONTENT_TYPES[name]
+      return not_found unless content_type
+
+      body = ::File.binread(::File.join(ROOT, name))
+      [
+        200,
+        {
+          "content-type" => "#{content_type}; charset=utf-8",
+          "content-length" => body.bytesize.to_s,
+          "cache-control" => "public, max-age=300"
+        },
+        [body]
+      ]
+    end
+
+    private
+
+    def not_found
+      [404, { "content-type" => "text/plain", "content-length" => "9" }, ["Not found"]]
+    end
+  end
+end