llm-entropy-filter 1.1.0 → 1.2.0

package/integrations/fastify.mjs

@@ -1,106 +1,106 @@
-// integrations/fastify.mjs
-import { gate } from "llm-entropy-filter";
-
-/**
- * Fastify plugin: adds a preHandler that runs `gate()` before your route handler.
- *
- * Usage:
- *   fastify.register(entropyGatePlugin, { bodyField: "text", blockOn: "BLOCK" })
- *
- * Design:
- * - Deterministic, local
- * - Fail-open by default (if gate throws, request continues unless you override)
- */
-export async function entropyGatePlugin(fastify, opts = {}) {
-  const {
-    bodyField = "text",
-    queryField,
-    attachResult = true,
-    blockOn = "BLOCK",
-    blockStatus = 400,
-    blockResponse,
-    warnHeader = true,
-    alwaysHeader = false,
-    onResult,
-    getText,
-    failClosed = false, // if true: return 500 on errors instead of passing through
-  } = opts;
-
-  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
-
-  fastify.decorateRequest("entropyGate", null);
-
-  fastify.addHook("preHandler", async (request, reply) => {
-    try {
-      // 1) Extract text
-      let text = "";
-      if (typeof getText === "function") {
-        text = String(getText(request) ?? "");
-      } else {
-        const bodyVal = request?.body?.[bodyField];
-        const queryVal = queryField ? request?.query?.[queryField] : undefined;
-        text = String(bodyVal ?? queryVal ?? "");
-      }
-
-      // 2) Run gate
-      const result = gate(text);
-
-      // 3) Attach
-      if (attachResult) {
-        request.entropyGate = result;
-      }
-
-      if (typeof onResult === "function") {
-        onResult(request, result);
-      }
-
-      // 4) Headers
-      const shouldHeader =
-        alwaysHeader || (warnHeader && result?.action === "WARN");
-      if (shouldHeader) {
-        reply.header("x-entropy-action", String(result?.action ?? ""));
-        reply.header("x-entropy-score", String(result?.entropy_score ?? ""));
-        reply.header("x-entropy-intention", String(result?.intention ?? ""));
-        if (Array.isArray(result?.flags)) {
-          reply.header("x-entropy-flags", result.flags.slice(0, 10).join(","));
-        }
-      }
-
-      // 5) Block
-      if (blockSet.has(result?.action)) {
-        reply.code(blockStatus);
-
-        if (typeof blockResponse === "function") {
-          return reply.send(blockResponse(request, reply, result));
-        }
-
-        if (blockResponse && typeof blockResponse === "object") {
-          return reply.send(blockResponse);
-        }
-
-        return reply.send({
-          ok: false,
-          blocked: true,
-          gate: result,
-          message:
-            "Request blocked by llm-entropy-filter (high-entropy / low-signal input).",
-        });
-      }
-    } catch (err) {
-      if (failClosed) {
-        reply.code(500);
-        return reply.send({
-          ok: false,
-          error: "entropy_gate_error",
-          message: String(err?.message ?? err),
-        });
-      }
-      // fail-open: continue request
-    }
-  });
-}
-
-/** Manual helper if you prefer using it inside handlers */
-export function runEntropyGate(text) {
-  return gate(String(text ?? ""));
-}
+// integrations/fastify.mjs
+import { gate } from "llm-entropy-filter";
+
+/**
+ * Fastify plugin: adds a preHandler that runs `gate()` before your route handler.
+ *
+ * Usage:
+ *   fastify.register(entropyGatePlugin, { bodyField: "text", blockOn: "BLOCK" })
+ *
+ * Design:
+ * - Deterministic, local
+ * - Fail-open by default (if gate throws, request continues unless you override)
+ */
+export async function entropyGatePlugin(fastify, opts = {}) {
+  const {
+    bodyField = "text",
+    queryField,
+    attachResult = true,
+    blockOn = "BLOCK",
+    blockStatus = 400,
+    blockResponse,
+    warnHeader = true,
+    alwaysHeader = false,
+    onResult,
+    getText,
+    failClosed = false, // if true: return 500 on errors instead of passing through
+  } = opts;
+
+  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
+
+  fastify.decorateRequest("entropyGate", null);
+
+  fastify.addHook("preHandler", async (request, reply) => {
+    try {
+      // 1) Extract text
+      let text = "";
+      if (typeof getText === "function") {
+        text = String(getText(request) ?? "");
+      } else {
+        const bodyVal = request?.body?.[bodyField];
+        const queryVal = queryField ? request?.query?.[queryField] : undefined;
+        text = String(bodyVal ?? queryVal ?? "");
+      }
+
+      // 2) Run gate
+      const result = gate(text);
+
+      // 3) Attach
+      if (attachResult) {
+        request.entropyGate = result;
+      }
+
+      if (typeof onResult === "function") {
+        onResult(request, result);
+      }
+
+      // 4) Headers
+      const shouldHeader =
+        alwaysHeader || (warnHeader && result?.action === "WARN");
+      if (shouldHeader) {
+        reply.header("x-entropy-action", String(result?.action ?? ""));
+        reply.header("x-entropy-score", String(result?.entropy_score ?? ""));
+        reply.header("x-entropy-intention", String(result?.intention ?? ""));
+        if (Array.isArray(result?.flags)) {
+          reply.header("x-entropy-flags", result.flags.slice(0, 10).join(","));
+        }
+      }
+
+      // 5) Block
+      if (blockSet.has(result?.action)) {
+        reply.code(blockStatus);
+
+        if (typeof blockResponse === "function") {
+          return reply.send(blockResponse(request, reply, result));
+        }
+
+        if (blockResponse && typeof blockResponse === "object") {
+          return reply.send(blockResponse);
+        }
+
+        return reply.send({
+          ok: false,
+          blocked: true,
+          gate: result,
+          message:
+            "Request blocked by llm-entropy-filter (high-entropy / low-signal input).",
+        });
+      }
+    } catch (err) {
+      if (failClosed) {
+        reply.code(500);
+        return reply.send({
+          ok: false,
+          error: "entropy_gate_error",
+          message: String(err?.message ?? err),
+        });
+      }
+      // fail-open: continue request
+    }
+  });
+}
+
+/** Manual helper if you prefer using it inside handlers */
+export function runEntropyGate(text) {
+  return gate(String(text ?? ""));
+}

package/integrations/langchain.mjs

@@ -1,98 +1,98 @@
-// integrations/langchain.mjs
-import { gate } from "llm-entropy-filter";
-
-/**
- * Minimal pre-gate for LangChain flows.
- * Use this before calling any LLM / chain / agent.
- */
-export function entropyPreGate(input, opts = {}) {
-  const { blockOn = "BLOCK" } = opts;
-  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
-
-  const text = typeof input === "string" ? input : String(input?.text ?? input ?? "");
-  const result = gate(text);
-
-  return {
-    gate: result,
-    inputText: text,
-    shouldBlock: blockSet.has(result?.action),
-    shouldWarn: result?.action === "WARN",
-    shouldAllow: result?.action === "ALLOW",
-  };
-}
-
-/**
- * Standard error object you can throw in API routes.
- */
-export function entropyBlockedError(gateResult, opts = {}) {
-  const { status = 400, code = "ENTROPY_BLOCKED" } = opts;
-  const err = new Error("Blocked by llm-entropy-filter (high-entropy / low-signal input).");
-  err.name = "EntropyBlockedError";
-  err.status = status;
-  err.code = code;
-  err.gate = gateResult;
-  return err;
-}
-
-/**
- * LCEL wrapper: wrap a Runnable / function to enforce gate before execution.
- * Works with `@langchain/core/runnables` (RunnableLambda).
- *
- * Usage:
- *   const safe = withEntropyGate(myRunnableOrFn, { pickText: (i)=> i.input })
- *   await safe.invoke({ input: "..." })
- */
-export function withEntropyGate(target, opts = {}) {
-  const {
-    blockOn = "BLOCK",
-    pickText, // (input) => string
-    onWarn,   // (gateResult, input) => void
-  } = opts;
-
-  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
-
-  // lazy import to avoid forcing langchain deps
-  let RunnableLambda;
-  async function getRunnableLambda() {
-    if (RunnableLambda) return RunnableLambda;
-    const mod = await import("@langchain/core/runnables");
-    RunnableLambda = mod.RunnableLambda;
-    return RunnableLambda;
-  }
-
-  return {
-    async invoke(input, config) {
-      const text = typeof pickText === "function"
-        ? String(pickText(input) ?? "")
-        : (typeof input === "string" ? input : String(input?.input ?? input?.text ?? ""));
-
-      const g = gate(text);
-
-      if (g?.action === "WARN" && typeof onWarn === "function") onWarn(g, input);
-
-      if (blockSet.has(g?.action)) {
-        throw entropyBlockedError(g, { status: 400 });
-      }
-
-      // If target is a Runnable with invoke()
-      if (target && typeof target.invoke === "function") {
-        return target.invoke(input, config);
-      }
-
-      // If target is a function
-      if (typeof target === "function") {
-        return target(input, config);
-      }
-
-      throw new Error("withEntropyGate: target must be a Runnable (invoke) or a function.");
-    },
-
-    // Optional: make it LCEL-friendly by exposing `asRunnable()`
-    async asRunnable() {
-      const RL = await getRunnableLambda();
-      return new RL({
-        func: async (input, config) => this.invoke(input, config),
-      });
-    },
-  };
-}
+// integrations/langchain.mjs
+import { gate } from "llm-entropy-filter";
+
+/**
+ * Minimal pre-gate for LangChain flows.
+ * Use this before calling any LLM / chain / agent.
+ */
+export function entropyPreGate(input, opts = {}) {
+  const { blockOn = "BLOCK" } = opts;
+  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
+
+  const text = typeof input === "string" ? input : String(input?.text ?? input ?? "");
+  const result = gate(text);
+
+  return {
+    gate: result,
+    inputText: text,
+    shouldBlock: blockSet.has(result?.action),
+    shouldWarn: result?.action === "WARN",
+    shouldAllow: result?.action === "ALLOW",
+  };
+}
+
+/**
+ * Standard error object you can throw in API routes.
+ */
+export function entropyBlockedError(gateResult, opts = {}) {
+  const { status = 400, code = "ENTROPY_BLOCKED" } = opts;
+  const err = new Error("Blocked by llm-entropy-filter (high-entropy / low-signal input).");
+  err.name = "EntropyBlockedError";
+  err.status = status;
+  err.code = code;
+  err.gate = gateResult;
+  return err;
+}
+
+/**
+ * LCEL wrapper: wrap a Runnable / function to enforce gate before execution.
+ * Works with `@langchain/core/runnables` (RunnableLambda).
+ *
+ * Usage:
+ *   const safe = withEntropyGate(myRunnableOrFn, { pickText: (i)=> i.input })
+ *   await safe.invoke({ input: "..." })
+ */
+export function withEntropyGate(target, opts = {}) {
+  const {
+    blockOn = "BLOCK",
+    pickText, // (input) => string
+    onWarn,   // (gateResult, input) => void
+  } = opts;
+
+  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
+
+  // lazy import to avoid forcing langchain deps
+  let RunnableLambda;
+  async function getRunnableLambda() {
+    if (RunnableLambda) return RunnableLambda;
+    const mod = await import("@langchain/core/runnables");
+    RunnableLambda = mod.RunnableLambda;
+    return RunnableLambda;
+  }
+
+  return {
+    async invoke(input, config) {
+      const text = typeof pickText === "function"
+        ? String(pickText(input) ?? "")
+        : (typeof input === "string" ? input : String(input?.input ?? input?.text ?? ""));
+
+      const g = gate(text);
+
+      if (g?.action === "WARN" && typeof onWarn === "function") onWarn(g, input);
+
+      if (blockSet.has(g?.action)) {
+        throw entropyBlockedError(g, { status: 400 });
+      }
+
+      // If target is a Runnable with invoke()
+      if (target && typeof target.invoke === "function") {
+        return target.invoke(input, config);
+      }
+
+      // If target is a function
+      if (typeof target === "function") {
+        return target(input, config);
+      }
+
+      throw new Error("withEntropyGate: target must be a Runnable (invoke) or a function.");
+    },
+
+    // Optional: make it LCEL-friendly by exposing `asRunnable()`
+    async asRunnable() {
+      const RL = await getRunnableLambda();
+      return new RL({
+        func: async (input, config) => this.invoke(input, config),
+      });
+    },
+  };
+}

package/integrations/vercel-ai-sdk.mjs

@@ -1,44 +1,44 @@
-// integrations/vercel-ai-sdk.mjs
-import { gate } from "llm-entropy-filter";
-
-/**
- * Pre-gate helper for Vercel AI SDK style flows.
- *
- * Typical usage:
- *  - Compute gate result
- *  - If BLOCK: return early
- *  - If WARN: optionally add metadata/logging and continue
- */
-export function entropyPreGate(input, opts = {}) {
-  const { blockOn = "BLOCK" } = opts;
-  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
-
-  const result = gate(String(input ?? ""));
-
-  return {
-    gate: result,
-    shouldBlock: blockSet.has(result?.action),
-    shouldWarn: result?.action === "WARN",
-    shouldAllow: result?.action === "ALLOW",
-  };
-}
-
-/**
- * Helper to build a standard Response when blocked (Edge/Node compatible).
- */
-export function blockedResponse(gateResult, opts = {}) {
-  const { status = 400 } = opts;
-  return new Response(
-    JSON.stringify({
-      ok: false,
-      blocked: true,
-      gate: gateResult,
-      message:
-        "Request blocked by llm-entropy-filter (high-entropy / low-signal input).",
-    }),
-    {
-      status,
-      headers: { "content-type": "application/json; charset=utf-8" },
-    }
-  );
-}
+// integrations/vercel-ai-sdk.mjs
+import { gate } from "llm-entropy-filter";
+
+/**
+ * Pre-gate helper for Vercel AI SDK style flows.
+ *
+ * Typical usage:
+ *  - Compute gate result
+ *  - If BLOCK: return early
+ *  - If WARN: optionally add metadata/logging and continue
+ */
+export function entropyPreGate(input, opts = {}) {
+  const { blockOn = "BLOCK" } = opts;
+  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
+
+  const result = gate(String(input ?? ""));
+
+  return {
+    gate: result,
+    shouldBlock: blockSet.has(result?.action),
+    shouldWarn: result?.action === "WARN",
+    shouldAllow: result?.action === "ALLOW",
+  };
+}
+
+/**
+ * Helper to build a standard Response when blocked (Edge/Node compatible).
+ */
+export function blockedResponse(gateResult, opts = {}) {
+  const { status = 400 } = opts;
+  return new Response(
+    JSON.stringify({
+      ok: false,
+      blocked: true,
+      gate: gateResult,
+      message:
+        "Request blocked by llm-entropy-filter (high-entropy / low-signal input).",
+    }),
+    {
+      status,
+      headers: { "content-type": "application/json; charset=utf-8" },
+    }
+  );
+}

package/package.json

@@ -1,59 +1,99 @@
-{
-  "name": "llm-entropy-filter",
-  "version": "1.1.0",
-  "description": "Deterministic entropy-based pre-gate for LLM pipelines. ALLOW / WARN / BLOCK high-entropy inputs before expensive model calls.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./integrations/express": {
-      "import": "./integrations/express.mjs"
-    },
-    "./integrations/fastify": {
-      "import": "./integrations/fastify.mjs"
-    },
-    "./integrations/vercel-ai-sdk": {
-      "import": "./integrations/vercel-ai-sdk.mjs"
-    },
-    "./integrations/langchain": {
-      "import": "./integrations/langchain.mjs"
-    },
-    "./rulesets/default": {
-      "import": "./rulesets/default.js"
-    },
-    "./rulesets/strict": {
-      "import": "./rulesets/strict.js"
-    }
-  },
-  "files": [
-    "dist",
-    "integrations",
-    "rulesets",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "clean": "rimraf dist",
-    "prepublishOnly": "npm run clean && npm run build",
-    "bench:sms": "node bench/sms_benchmark.js",
-    "bench:report": "node bench/generate_report.js"
-  },
-  "devDependencies": {
-    "rimraf": "^5.0.10",
-    "tsup": "^8.0.1",
-    "typescript": "^5.4.0"
-  }
-}
+{
+  "name": "llm-entropy-filter",
+  "version": "1.2.0",
+  "description": "Fast entropy and intent gate for LLM inputs (ALLOW/WARN/BLOCK). Reduces hallucinations, cost and spam before calling an LLM.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./integrations/express": {
+      "import": "./integrations/express.mjs"
+    },
+    "./integrations/fastify": {
+      "import": "./integrations/fastify.mjs"
+    },
+    "./integrations/vercel-ai-sdk": {
+      "import": "./integrations/vercel-ai-sdk.mjs"
+    },
+    "./integrations/langchain": {
+      "import": "./integrations/langchain.mjs"
+    },
+    "./rulesets/default": {
+      "import": "./rulesets/default.js"
+    },
+    "./rulesets/strict": {
+      "import": "./rulesets/strict.js"
+    },
+    "./rulesets/public-api": {
+      "import": "./rulesets/public-api.js"
+    },
+    "./rulesets/support": {
+      "import": "./rulesets/support.js"
+    }
+  },
+  "files": [
+    "dist",
+    "integrations",
+    "rulesets",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "demo": "npm run build && node demo/demo.mjs",
+    "bench": "npm run build && node bench/benchmark.mjs",
+
+    "bench:metrics": "npm run build && node bench/metrics.mjs --dataset bench/datasets/core_v1.jsonl --ruleset default",
+    "bench:all": "npm run bench && npm run bench:metrics",
+
+    "bench:metrics:strict": "npm run build && node bench/metrics.mjs --dataset bench/datasets/core_v1.jsonl --ruleset strict",
+    "bench:metrics:public-api": "npm run build && node bench/metrics.mjs --dataset bench/datasets/core_v1.jsonl --ruleset public-api",
+
+    "serve": "npm run build && node demo/server.mjs",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rosatisoft/llm-entropy-filter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rosatisoft/llm-entropy-filter/issues"
+  },
+  "homepage": "https://github.com/rosatisoft/llm-entropy-filter#readme",
+  "keywords": [
+    "llm",
+    "ai",
+    "prompt-filter",
+    "input-validation",
+    "entropy",
+    "spam-detection",
+    "content-moderation",
+    "heuristics",
+    "guardrails",
+    "openai"
+  ],
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.10",
+    "autocannon": "^8.0.0",
+    "express": "^5.2.1",
+    "minimist": "^1.2.8",
+    "openai": "^6.16.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/rulesets/default.js

@@ -0,0 +1,8 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const jsonPath = path.join(path.dirname(new URL(import.meta.url).pathname), "default.json");
+const rules = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+
+export default rules;
+