node-red-contrib-vectorprime 0.1.42 → 0.1.43

package/README.md

@@ -1,57 +1,29 @@
 # node-red-contrib-vectorprime
-### VectorPrime — Decision Ranking for Node-RED
 
-**node-red-contrib-vectorprime** lets you rank tasks, alerts, or actions inside Node-RED when multiple options compete.
+✅ **1-minute setup:** install the node → drag **Rank Decision (VectorPrime)** into a flow → open **VectorPrime Config** → get your API key → paste → Deploy.
 
-Instead of hard-coding rules, VectorPrime helps flows choose the **safest, most urgent, or most rational next step** automatically.
+👉 **Get your API key:** https://vectorprime.tech/?utm_source=node-red&utm_medium=readme&utm_campaign=node_red_contrib&utm_content=top_cta
 
----
-
-## 🧠 What this node does (plain English)
-
-You send VectorPrime a list of options (tasks, actions, alerts). Each option can include simple metadata like urgency, impact, deadline, or effort.
-
-VectorPrime returns:
-- A ranked list (best → worst)
-- Probabilities / confidence signals (when provided)
-- Metadata about the ranking
-
-This turns Node-RED into a **decision-aware automation engine**, not just `if/else`.
+> Pricing note: This node is free to use. VectorPrime API usage may require a paid plan after free-tier limits.
 
 ---
 
-## 📦 Nodes included
-
-- **VectorPrime Config**  
-  Stores Base URL + API key securely using Node-RED credentials (not exported with flows).
+## What this node does
 
-- **Rank Decision (VectorPrime)**  
-  Sends options to the VectorPrime Rank API and returns ranked results.
-
----
+VectorPrime helps Node-RED flows choose the **best next action** when multiple options compete — without hard-coded rules.
 
-## ⚡ Quick start (5 minutes)
+Use cases:
 
-1. Open Node-RED
-2. Menu ☰ → **Manage Palette** → **Install**
-3. Search for: **node-red-contrib-vectorprime**
-4. Install
-5. Drag **Rank Decision (VectorPrime)** into a flow
-6. Create/select a **VectorPrime Config** and click **Get Free Key**
-7. Inject one of the examples below into `msg.payload`
+- Prioritize tasks
+- Rank alerts by urgency/impact
+- Choose the safest next step in automation flows
+- Route tickets/jobs based on structured decision input
 
 ---
 
-## ✅ Input format (simple) — `items[]` (recommended)
+## Install
 
-The node will automatically convert `items[]` into the backend’s required `options[]` format.
+In your Node-RED user directory (usually `C:\Users\<you>\.node-red`):
 
-```json
-{
-  "items": [
-    { "id": "payroll", "label": "Fix payroll outage", "urgency": 10, "impact": 10, "effort": 3 },
-    { "id": "email", "label": "Reply to customer email", "urgency": 4, "impact": 5, "effort": 2 },
-    { "id": "deploy", "label": "Ship small hotfix", "urgency": 7, "impact": 7, "effort": 4 }
-  ],
-  "prompt": "Rank the best next action."
-}
+```bash
+npm install node-red-contrib-vectorprime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-vectorprime",
-  "version": "0.1.42",
+  "version": "0.1.43",
   "description": "Rank tasks, alerts, or actions inside Node-RED when multiple options compete. Choose the safest next step automatically instead of hard-coded rules.",
   "license": "MIT",
   "author": "Faisal Khan",

package/vectorprime.html

@@ -1,7 +1,16 @@
+---
+
+# 2) REPLACE: `vectorprime.html` (FULL FILE)
+
+```html
 <!-- =========================
-   VectorPrime Config Template
+   VectorPrime Nodes (Node-RED)
    WEBSITE-ONLY KEYS (no minting inside Node-RED)
 ========================= -->
+
+<!-- =========================
+   Config Node UI
+========================= -->
 <script type="text/x-red" data-template-name="vectorprime-config">
   <div class="form-row">
     <label for="node-config-input-baseUrl">
@@ -17,11 +26,20 @@
     <input type="password" id="node-config-input-apiKey" placeholder="vp_live_...">
   </div>
 
+  <div class="form-row">
+    <a
+      class="vp-cta-btn"
+      href="https://vectorprime.tech/?utm_source=node-red&utm_medium=config&utm_campaign=node_red_contrib&utm_content=get_key_button"
+      target="_blank"
+      rel="noopener noreferrer"
+    >
+      Get your API key on vectorprime.tech
+    </a>
+  </div>
+
   <div class="form-row">
     <div style="font-size:12px; color:#666; line-height:1.4;">
-      Get your API key from
-      <a href="https://vectorprime.tech" target="_blank" rel="noopener noreferrer">vectorprime.tech</a>,
-      then paste it above.
+      Then paste it into <b>API Key</b> above.
     </div>
   </div>
 
@@ -30,6 +48,21 @@
       ✅ Key is stored securely in Node-RED credentials (not exported with flows).
     </div>
   </div>
+
+  <style>
+    .vp-cta-btn{
+      display:block;
+      width:100%;
+      padding:10px 12px;
+      text-align:center;
+      background:#2563EB;
+      color:#fff !important;
+      border-radius:8px;
+      text-decoration:none;
+      font-weight:600;
+    }
+    .vp-cta-btn:hover{ filter:brightness(0.92); }
+  </style>
 </script>
 
 <script type="text/javascript">
@@ -74,8 +107,8 @@
 
   <h3>Quick Setup</h3>
   <ol>
-    <li>Set <b>Base URL</b> (default is already correct)</li>
-    <li>Get your API key from <b>vectorprime.tech</b></li>
+    <li>Confirm <b>Base URL</b> (default is correct)</li>
+    <li>Click <b>Get your API key</b> (opens vectorprime.tech)</li>
     <li>Paste the key into <b>API Key</b></li>
     <li>Click <b>Done</b></li>
   </ol>
@@ -86,12 +119,14 @@
 
   <h3>Recommended Base URL</h3>
   <pre>https://vectorprime-kernel-backend.onrender.com</pre>
+
+  <p><b>Website-only keys:</b> this node does not mint keys inside Node-RED.</p>
 </script>
 
 <hr />
 
 <!-- =========================
-   VectorPrime Rank Template
+   Rank Node UI
 ========================= -->
 <script type="text/x-red" data-template-name="vectorprime-rank">
   <div class="form-row">
@@ -128,10 +163,7 @@
     inputs: 1,
     outputs: 1,
     icon: "font-awesome/fa-bolt",
-
-    // ✅ This is the name users see in the palette
     paletteLabel: "Rank Decision (VectorPrime)",
-
     label: function () {
       return this.name || "Rank Decision (VectorPrime)";
     }
@@ -140,39 +172,37 @@
 
 <!-- ✅ HELP TAB: vectorprime-rank -->
 <script type="text/x-red" data-help-name="vectorprime-rank">
-  <p>
-    <b>Rank Decision (VectorPrime)</b> picks the best next action automatically.
-    Use it anywhere your flow needs <b>priority scoring</b> or <b>decision ranking</b>.
-  </p>
+  <p><b>Rank Decision (VectorPrime)</b> ranks options (tasks/actions/alerts) using the VectorPrime kernel.</p>
 
   <h3>What it does</h3>
   <ul>
     <li>Reads options from <code>msg.payload</code></li>
-    <li>Calls the VectorPrime Decision Kernel Rank API</li>
+    <li>Calls the VectorPrime kernel rank API</li>
     <li>Returns the ranked decision inside <code>msg.payload</code></li>
   </ul>
 
-  <h3>Where developers use this most</h3>
-  <ul>
-    <li><b>Incident response:</b> rank alerts → fix the most critical first</li>
-    <li><b>Automation flows:</b> choose the best next action from multiple tasks</li>
-    <li><b>Ops / IoT:</b> prioritize device events + maintenance decisions</li>
-    <li><b>Ticketing & work queues:</b> rank jobs, leads, or support tickets</li>
-  </ul>
-
   <h3>Input format (simple)</h3>
   <p>Send a list to rank inside <code>msg.payload.items</code>:</p>
 
   <pre><code>{
   "items": [
-    { "id": "fix-prod-bug", "label": "Fix production bug", "urgency": 10, "impact": 10 },
-    { "id": "ship-feature", "label": "Ship new feature", "urgency": 7, "impact": 8 },
-    { "id": "refactor", "label": "Refactor module", "urgency": 3, "impact": 5 }
+    { "id": "a", "label": "Fix production bug", "urgency": 9, "impact": 10, "effort": 3 },
+    { "id": "b", "label": "Ship new feature",  "urgency": 6, "impact": 7,  "effort": 6 },
+    { "id": "c", "label": "Refactor module",   "urgency": 3, "impact": 4,  "effort": 8 }
   ]
 }</code></pre>
 
   <p>
-    ✅ The node automatically converts <code>items</code> into the backend format
-    (<code>decision_id</code>, <code>prompt</code>, <code>options</code>) so flows stay easy.
+    ✅ The node automatically converts <code>items</code> into:
+    <code>decision_id</code>, <code>prompt</code>, <code>options</code>.
   </p>
+
+  <h3>Output</h3>
+  <p>On success, the node sets <code>msg.payload</code> to the kernel response, typically including:</p>
+  <ul>
+    <li><code>ranking</code> (best → worst)</li>
+    <li><code>probabilities</code> (per option id)</li>
+    <li><code>meta</code> (engine info / tie-break flags)</li>
+    <li><code>vp_input</code> (what was sent)</li>
+  </ul>
 </script>

package/vectorprime.js

@@ -1,7 +1,7 @@
 module.exports = function (RED) {
     "use strict";
 
-    // ✅ Node 22 has global fetch, but keep fallback for safety
+    // Node 18+ has global fetch. Keep fallback for older Node.
     const fetchFn =
         typeof fetch === "function"
             ? fetch
@@ -58,10 +58,9 @@ module.exports = function (RED) {
         });
 
         // Convert to pseudo-probabilities (normalized non-negative)
-        // Make everything >= 0 by shifting if needed
         const scores = scored.map(s => s.score);
         const minScore = Math.min(...scores);
-        const shifted = scores.map(s => s - minScore); // now min is 0
+        const shifted = scores.map(s => s - minScore); // min is 0
         const sum = shifted.reduce((acc, v) => acc + v, 0);
 
         const probabilities = {};
@@ -70,7 +69,6 @@ module.exports = function (RED) {
                 probabilities[s.id] = shifted[j] / sum;
             });
         } else {
-            // all zero (fully tied) -> uniform
             const uniform = 1 / scored.length;
             scored.forEach(s => { probabilities[s.id] = uniform; });
         }
@@ -83,7 +81,7 @@ module.exports = function (RED) {
 
     // -----------------------------
     // Config Node (stores Base URL + API Key)
-    // WEBSITE-ONLY KEYS: no email, no "Get Free Key" minting
+    // WEBSITE-ONLY KEYS: no minting inside Node-RED
     // -----------------------------
     function VectorPrimeConfigNode(n) {
         RED.nodes.createNode(this, n);
@@ -91,9 +89,7 @@ module.exports = function (RED) {
         this.baseUrl =
             (n.baseUrl && String(n.baseUrl).trim()) ||
             "https://vectorprime-kernel-backend.onrender.com";
-
-        // NOTE: apiKey is stored in credentials only.
-        // No email stored here anymore (website-only keys).
+        // apiKey is stored in credentials only.
     }
 
     RED.nodes.registerType("vectorprime-config", VectorPrimeConfigNode, {
@@ -120,9 +116,7 @@ module.exports = function (RED) {
             try {
                 if (!cfg) {
                     node.status({ fill: "red", shape: "ring", text: "missing config" });
-                    throw new Error(
-                        "VectorPrime config missing. Open node settings and select/create a Config."
-                    );
+                    throw new Error("VectorPrime config missing. Open node settings and select/create a Config.");
                 }
 
                 const baseUrl = normalizeBaseUrl(cfg.baseUrl);
@@ -141,15 +135,14 @@ module.exports = function (RED) {
                 if (!storedKey) {
                     node.status({ fill: "red", shape: "ring", text: "missing api key" });
                     throw new Error(
-                        "No API key. Get your key from vectorprime.tech and paste it into the VectorPrime Config."
+                        "No API key. Get one at https://vectorprime.tech/?utm_source=node-red&utm_medium=runtime_error&utm_campaign=node_red_contrib&utm_content=missing_key then paste it into the VectorPrime Config."
                     );
                 }
 
-                // -----------------------------
-                // ✅ AUTO-CONVERT ITEMS → OPTIONS
+                // ------------------------------------
+                // AUTO-CONVERT items -> options (friendly input)
                 // Backend expects: decision_id, prompt, options
-                // Users send: {items:[...]}
-                // -----------------------------
+                // ------------------------------------
                 const originalPayload = msg.payload;
                 let payload = msg.payload || {};
                 let inputOptionsForFallback = null;
@@ -181,12 +174,14 @@ module.exports = function (RED) {
                     inputOptionsForFallback = payload.options;
                 }
 
-                // Validate final expected shape
-                if (!payload.decision_id || !payload.prompt || !payload.options) {
+                if (!payload || typeof payload !== "object") {
                     node.status({ fill: "red", shape: "ring", text: "bad payload" });
-                    throw new Error(
-                        "Invalid payload. Provide { items:[...] } or full { decision_id, prompt, options }."
-                    );
+                    throw new Error("Invalid payload. Provide { items:[...] } or full { decision_id, prompt, options }.");
+                }
+
+                if (!payload.decision_id || !payload.prompt || !payload.options || !Array.isArray(payload.options)) {
+                    node.status({ fill: "red", shape: "ring", text: "bad payload" });
+                    throw new Error("Invalid payload. Provide { items:[...] } or full { decision_id, prompt, options }.");
                 }
 
                 node.status({ fill: "blue", shape: "dot", text: "ranking..." });
@@ -209,54 +204,38 @@ module.exports = function (RED) {
                     throw new Error(`VectorPrime API ${resp.status}: ${JSON.stringify(data)}`);
                 }
 
-                // -----------------------------
-                // ✅ If backend returns a tie/flat result, do deterministic local ranking
-                // -----------------------------
+                // If backend returns a tie/flat result, do deterministic local ranking
                 const tieBreak =
                     data && data.meta && typeof data.meta === "object"
                         ? data.meta.tie_break
                         : null;
 
-                const hasProb = data && data.probabilities;
-
-                const looksTied =
-                    (tieBreak === "preserve_input_order" && isFlatProbabilities(hasProb)) ||
-                    (isFlatProbabilities(hasProb));
-
-                if (looksTied && Array.isArray(inputOptionsForFallback) && inputOptionsForFallback.length > 0) {
-                    const fallback = buildFallbackRankingFromOptions(inputOptionsForFallback);
-
-                    // keep raw backend response for debugging
-                    msg.vp_raw = data;
-
-                    // replace with deterministic result
-                    data = {
-                        ...data,
-                        ranking: fallback.ranking,
-                        probabilities: fallback.probabilities,
-                        meta: {
-                            ...(data.meta || {}),
-                            notes: (data.meta && data.meta.notes ? String(data.meta.notes) + " | " : "") +
-                                "Node-RED fallback ranking applied (urgency/impact/effort) because backend result was tied/flat.",
-                            numeric_source: "node_red_fallback",
-                            tie_break: "fallback_score_then_preserve_input_order",
-                        },
-                    };
+                const hasProb = data && data.probabilities && typeof data.probabilities === "object";
+                const isFlat = hasProb ? isFlatProbabilities(data.probabilities) : false;
+
+                if ((tieBreak || isFlat) && Array.isArray(inputOptionsForFallback) && inputOptionsForFallback.length >= 2) {
+                    const local = buildFallbackRankingFromOptions(inputOptionsForFallback);
+                    data = data && typeof data === "object" ? data : {};
+                    data.ranking = local.ranking;
+                    data.probabilities = local.probabilities;
+                    data.meta = data.meta && typeof data.meta === "object" ? data.meta : {};
+                    data.meta.local_fallback = true;
+                    data.meta.local_fallback_reason = tieBreak ? "backend_tie_break" : "flat_probabilities";
                 }
 
-                node.status({ fill: "green", shape: "dot", text: "ok" });
+                // Attach what we sent (useful for debugging + audits)
+                if (data && typeof data === "object") {
+                    data.vp_input = payload;
+                    data.vp_original_payload = originalPayload;
+                }
 
-                // ✅ Replace payload with ranked result
                 msg.payload = data;
 
-                // preserve original input for debugging (no breaking changes)
-                msg._vp_input = originalPayload;
-
+                node.status({ fill: "green", shape: "dot", text: "ok" });
                 send(msg);
                 done();
             } catch (err) {
-                node.status({ fill: "red", shape: "ring", text: "failed" });
-                node.error(err, msg);
+                node.status({ fill: "red", shape: "ring", text: "error" });
                 done(err);
             }
         });