llm-entropy-filter 1.1.1 → 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" },
+    }
+  );
+}