llm-entropy-filter 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on semantic versioning principles.
+
+---
+
+## [1.1.0] - 2026-01-28
+
+### 🚀 Added
+
+- Introduced formal **ruleset architecture** (`default`, `strict`, `support`, `public-api`).
+- Added `rulesets/` directory for configurable entropy presets.
+- Added integration examples:
+  - Express middleware
+  - Fastify plugin
+  - Vercel AI SDK pre-gate wrapper
+- Added reproducible benchmark scripts for spam dataset evaluation.
+- Added economic & performance impact documentation.
+- Added stability & hallucination mitigation section in README.
+- Added production-readiness checklist.
+
+### 🧪 Bench & Metrics
+
+- Included reproducible SMS spam dataset benchmarking.
+- Added support for generating precision / recall style reports.
+- Added structured telemetry output for integration logging.
+
+### 🛠 Internal
+
+- No changes to core `gate()` logic.
+- No breaking changes to public API.
+- Existing behavior remains the default under `ruleset: "default"`.
+
+### ⚠️ Breaking Changes
+
+None.
+
+This release focuses on infrastructure packaging, documentation clarity, and integration readiness without altering the deterministic entropy engine.
+
+---
+
+## [1.0.1] - 2026-01-27
+
+### Added
+
+- Initial demo server (`/analyze`, `/triad`)
+- Deterministic entropy scoring
+- ALLOW / WARN / BLOCK verdict structure
+- Performance benchmark documentation

package/README.md

@@ -1,195 +1,352 @@
-README.md reescrito (v1.0.0 listo para publicar)
+# llm-entropy-filter
 
-Basado en tu README actual 
+[![npm version](https://img.shields.io/npm/v/llm-entropy-filter.svg)](https://www.npmjs.com/package/llm-entropy-filter)
+[![license](https://img.shields.io/npm/l/llm-entropy-filter.svg)](LICENSE)
 
-README (5)
+Minimal, fast **entropy + intent gate** for LLM inputs.
 
-, aquí va una versión limpia, con tus métricas reales, endpoints, bench y dataset.
+`llm-entropy-filter` is a deterministic, local middleware layer that filters high-entropy / low-signal inputs before they reach expensive LLM inference.
 
-Copia y pega esto como README.md:
+It transforms your LLM from a generic processor into a **premium signal resource**.
 
-# llm-entropy-filter
+---
 
-Minimal, fast **entropy + intent gate** for LLM inputs.
+# 🚀 Why this exists
+
+LLMs are powerful but:
 
-This package runs a **local, deterministic heuristic gate** to detect high-entropy / low-signal inputs (spam, coercion, vague conspiracies, pseudo-science, truth relativism, broken causality) and returns an **ALLOW / WARN / BLOCK** verdict.
+- Expensive per token
+- Latency-heavy (seconds vs milliseconds)
+- Vulnerable to spam, coercion, broken causality, and noise
 
-Use it **before** calling an LLM to reduce hallucinations, cost, and risk.
+Most systems solve this with *more processing*.
+
+`llm-entropy-filter` solves it with **criterion before processing**.
 
 ---
 
-## What you get
+# 🧠 Architecture
 
-### Core (library)
-- `gate(text)` → `{ action, entropy_score, flags, intention, confidence, rationale }`
-- `gateLLM(text)` → alias of `gate(text)` (kept for compatibility)
-- `runEntropyFilter(text)` → underlying entropy + intention analysis utilities
+The system operates in two deterministic local layers:
 
-### Demo (server)
-- `POST /analyze` → runs local `gate(text)` + returns `meta.ts` + `meta.version`
-- `POST /triad` → optional OpenAI analysis (only if `OPENAI_API_KEY` is set)
+## Layer 1 — Hard Triggers (Deterministic Signals)
 
----
+Immediate structural patterns:
 
-## Install
+- Shouting (ALL CAPS)
+- Urgency markers
+- Money / % signals
+- Spam phrasing
+- Conspiracy vagueness
+- Broken causality structures
+- Repetition anomalies
 
-```bash
-npm i llm-entropy-filter
+These are language-light, low-cost, and capture obvious noise.
 
-Quickstart (library)
-import { gate } from "llm-entropy-filter";
+## Layer 2 — Thematic Scoring (Signal Accumulation)
+
+If no hard block occurs, the input is evaluated by topic clusters:
+
+- Marketing spam
+- Conspiracy framing
+- Coercive tone
+- Pseudo-scientific structure
+- Relativism / truth dilution
+- Semantic incoherence
 
-const r = gate("¡¡COMPRA YA!! Oferta limitada 90% OFF $$$");
-console.log(r);
+Each topic contributes to an `entropy_score`.
 
+Final verdict:
 
-Example output:
+ALLOW | WARN | BLOCK
 
+
+Returned with:
+
+```json
 {
   "action": "BLOCK",
   "entropy_score": 0.7,
-  "flags": ["urgency","spam_sales","money_signal","shouting"],
-  "intention": "marketing_spam",
+  "flags": [...],
+  "intention": "...",
   "confidence": 0.85,
-  "rationale": "Detecté señales de venta agresiva/urgencia/dinero."
+  "rationale": "..."
 }
 
-Demo server (Express)
 
-Start:
+No network calls. No embeddings. No remote inference.
 
-npm run serve
+## Rulesets
 
+This project ships with preset rule packs:
 
-Health:
+- `default` (balanced)
+- `strict` (aggressive blocking)
+- `support` (fewer false positives)
+- `public-api` (hardened for open endpoints)
 
-curl -s http://127.0.0.1:3000/health
+Rulesets live in `rulesets/` and define:
+- thresholds (WARN/BLOCK)
+- hard triggers
+- topic scoring weights
 
+## Integrations (copy/paste)
 
-Local gate:
+This repo includes ready-to-use adapters under `integrations/`:
 
-curl -s -X POST http://127.0.0.1:3000/analyze \
-  -H "Content-Type: application/json" \
-  -d '{"text":"Congratulations! You won a FREE iPhone. Click here to claim now!"}' | jq .
+- `integrations/express.mjs` — Express middleware gate (ALLOW/WARN/BLOCK)
+- `integrations/fastify.mjs` — Fastify plugin gate
+- `integrations/vercel-ai-sdk.mjs` — pre-gate wrapper for `streamText()` / `generateText()`
+- `integrations/langchain.mjs` — pre-gate + optional Runnable wrapper for LangChain
+
+These integrations do **not** change core behavior. They only call `gate()` and route based on the verdict.
+
+
+📦 Installation
+npm i llm-entropy-filter
+
+⚡ Quickstart
+import { gate } from "llm-entropy-filter";
 
+const result = gate("¡¡COMPRA YA!! Oferta limitada 90% OFF $$$");
 
-You will also see:
+console.log(result);
 
-"meta": { "ts": 1769546511060, "version": "1.0.0" }
+🖥 Demo Server
 
-Optional: OpenAI triad demo
+The demo server wraps the local gate.
+
+Start
+npm run serve
+
+
+(Ensure your package.json includes: "serve": "node demo/server.mjs")
+
+Health
+curl http://127.0.0.1:3000/health
+
+Local gate
+curl -X POST http://127.0.0.1:3000/analyze \
+  -H "Content-Type: application/json" \
+  -d '{"text":"FREE iPhone!!! Click now!!!"}'
+
+Optional LLM Triad (Demo Only)
 export OPENAI_API_KEY="YOUR_KEY"
 export OPENAI_MODEL="gpt-4.1-mini"
 
-curl -s -X POST http://127.0.0.1:3000/triad \
+curl -X POST http://127.0.0.1:3000/triad \
   -H "Content-Type: application/json" \
-  -d '{"text":"Vivimos en una simulación y todos lo esconden."}' | jq .
+  -d '{"text":"Vivimos en una simulación y todos lo esconden."}'
 
 
-/triad is a demo layer. The product is the local gate().
+If OPENAI_API_KEY is not set, /triad returns 503.
 
-Benchmarks (measured)
-HTTP gate /analyze (local, deterministic)
+⚡ Performance (Measured)
 
-Command:
+Environment:
+GitHub Codespaces (Linux container), Node 24.x
 
-npx autocannon -m POST -c 30 -d 10 --renderStatusCodes \
-  http://127.0.0.1:3000/analyze \
-  -H "Content-Type: application/json" \
-  -b '{"text":"Congratulations. You won a FREE iPhone. Click here to claim now."}'
+Local Gate — /analyze
 
+Avg latency: 5.28 ms
 
-Observed (typical run):
+p50: 4 ms
 
-~5.2k req/s
+p99: 16 ms
 
-~5.1 ms avg latency (p50 ~4 ms)
+Throughput: ~5,118 req/sec
 
-LLM demo /triad (OpenAI)
+0 errors
 
-Command:
+LLM Roundtrip — /triad
 
-npx autocannon -m POST -c 2 -d 30 --renderStatusCodes \
-  http://127.0.0.1:3000/triad \
-  -H "Content-Type: application/json" \
-  -b '{"text":"Texto real de prueba (1-3 párrafos) ..."}'
+Avg latency: 5,321 ms
 
+p50: 5,030 ms
 
-Observed (typical run):
+Throughput: ~0.34 req/sec
 
-~1.7 req/s
+2 timeouts in 30s test
 
-~1.17 s avg latency
+Note: These represent different pipeline layers (local deterministic vs external LLM API). The architectural gain comes from avoiding unnecessary LLM calls.
 
-Dataset mini + bench script (no HTTP)
+📉 Economic Impact (Projection)
+Assumptions
 
-A tiny CSV lives at:
+300 tokens per request (150 in / 150 out)
 
-bench/sms_spam.csv
+gpt-4o-mini pricing baseline
 
-Run the bench:
+30% traffic filtered locally
 
-node bench/sms_spam_bench.mjs bench/sms_spam.csv
-cat bench/reports/sms_spam_report.md
+Effect
 
+If 1M requests are received:
 
-Typical report:
+300,000 requests never hit the LLM
 
-Throughput: ~9–10k samples/sec
+30% token cost avoided
 
-Actions: ALLOW / WARN / BLOCK distribution
+30% rate-limit headroom gained
 
-Confusion table (ground truth spam/ham → action)
+30% reduction in latency pressure
 
-Top flags + intentions
+Savings scale linearly with volume and exponentially with higher-cost models.
 
-JSON + Markdown reports written to bench/reports/
+Formula:
 
-Design goals
+Savings =
+(Filtered_Requests / Total_Requests)
+× Avg_Tokens_Per_Request
+× Token_Price
 
-Fast: pure heuristics, no network calls
+🛡 Stability & Hallucination Mitigation
 
-Portable: works in any Node environment
+High-entropy inputs increase:
 
-Composable: middleware/wrapper before calling an LLM
+Off-topic generation
 
-Transparent: flags explain why an input is risky
+Reasoning drift
 
-Observable: /analyze returns meta.ts and meta.version
+Prompt injection exposure
 
-Roadmap
+Token expansion loops
 
-Expand multilingual spam patterns
+By constraining input entropy before inference,
+the downstream model operates in a narrower semantic bandwidth.
 
-Optional suggested_rewrite to lower entropy
+This improves stability without imposing moral or ideological constraints.
 
-Example integrations: Next.js / Vercel, Express, Cloudflare Workers
+🧪 Dataset Benchmark
 
-Extended dataset benches + cost-savings estimates
+Included:
 
-Install:
+bench/sms_spam.csv
 
-npm i llm-entropy-filter
 
+Run:
 
-Ejemplo mínimo:
+node bench/sms_spam_bench.mjs bench/sms_spam.csv
 
-import { gate } from "llm-entropy-filter";
-console.log(gate("Congratulations. You won a FREE iPhone. Click here."));
 
+Generates:
 
-Bench results (tu mejor “prueba”):
+Precision / recall
 
-/analyze ~ 5k req/sec
+Confusion matrix
 
-/triad ~ 1–2 req/sec (LLM)
+Top flags
 
-License
+JSON + Markdown reports
 
-Apache-2.0
+🎯 Design Goals
 
-Copyright (c) 2026 Ernesto Rosati
+Deterministic
 
+Transparent
 
----
+Fast
+
+Composable
+
+Observable
+
+Economically rational
+
+🗺 Roadmap
+
+Multilingual rulesets
+
+Configurable rule packs
+
+Express / Fastify middleware exports
+
+Suggested rewrite mode
+
+Production case studies
+
+👤 Attribution
+
+Developed and maintained by Ernesto Rosati.
+
+If this library creates value for your organization,
+consider collaboration or sponsorship.
+
+📜 License
+
+Apache-2.0
+Copyright (c) 2026 Ernesto Rosati
 
+Use cases & integrations
+## ✅ Where this fits in real systems
+
+`llm-entropy-filter` is designed to sit **before** expensive inference. Common placements:
+
+### 1) Public chat apps (startups)
+Use as a first-line gate to block obvious spam/coercion before the LLM:
+- faster UX for rejected traffic (<10ms)
+- reduced token spend
+- reduced prompt-abuse surface
+
+### 2) Rate-limit protection
+Acts as a semantic pre-filter that reduces:
+- quota exhaustion
+- burst abuse
+- coordinated spam floods
+
+It creates headroom by rejecting high-entropy traffic locally.
+
+### 3) RAG pipelines (pre-retrieval gate)
+Before retrieval:
+- block low-signal queries that would waste retrieval + reranking
+- normalize/clean input to improve recall precision
+- prevent adversarial queries from polluting retrieval traces
+
+### 4) Multi-agent systems
+In agent loops:
+- prevent “reasoning drift” from noisy inputs
+- keep agents from spending cycles on incoherent or adversarial prompts
+- add structured telemetry for agent decisions (`flags`, `intention`, `entropy_score`)
+
+### 5) Tooling & SDK pre-gates (LangChain / Vercel AI SDK)
+Drop in as a deterministic guard:
+- before `callLLM()`
+- before `streamText()`
+- before tool selection / agent routing
+
+The output can be used as:
+- a routing signal (ALLOW/WARN/BLOCK)
+- a logging payload for audits and dashboards
+
+“What’s missing to be production-ready” 
+## Production readiness checklist
+
+The core gate is stable, but “production-ready” requires:
+
+### 1) Configurable rulesets
+- `default` (balanced)
+- `strict` (aggressive spam/coercion blocking)
+- `support` (customer support / fewer false positives)
+- `public-api` (open endpoints / hardened)
+
+### 2) Reproducible metrics (precision / recall)
+Bench scripts should emit:
+- precision/recall/F1
+- confusion matrix
+- false-positive rate on normal conversations
+- top flags per dataset
+
+### 3) Copy-paste integrations
+Provide ready-to-use adapters:
+- Express middleware
+- Fastify plugin
+- Next.js / Vercel edge wrapper
+- “pre-gate” helpers for LangChain-style pipelines
+
+### 4) One real production example
+A minimal public case study:
+- traffic volume
+- % blocked
+- cost avoided
+- rate-limit incidents reduced
+- latency improvement for blocked traffic

package/integrations/express.mjs

@@ -0,0 +1,117 @@
+// integrations/express.mjs
+import { gate } from "llm-entropy-filter";
+
+/**
+ * Create an Express middleware that runs `gate()` before LLM calls.
+ *
+ * Design goals:
+ * - Zero behavior changes to core `gate()`
+ * - Drop-in for public chat endpoints
+ * - Deterministic: no external calls
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.bodyField="text"] - Field name in req.body that contains user text.
+ * @param {string} [opts.queryField] - Optional query param fallback (e.g., ?text=...).
+ * @param {boolean} [opts.attachResult=true] - Attach result to req.entropyGate.
+ * @param {boolean} [opts.blockOn="BLOCK"] - Block when action matches this string ("BLOCK") or array of actions.
+ * @param {number} [opts.blockStatus=400] - HTTP status when blocked.
+ * @param {object|function} [opts.blockResponse] - Custom JSON response or function(req, res, result) => any
+ * @param {boolean} [opts.warnHeader=true] - If WARN, add response headers with gate metadata.
+ * @param {boolean} [opts.alwaysHeader=false] - If true, add headers for all actions.
+ * @param {function} [opts.onResult] - Hook: (req, result) => void
+ * @param {function} [opts.getText] - Hook: (req) => string (overrides bodyField/queryField)
+ */
+export function entropyGateMiddleware(opts = {}) {
+  const {
+    bodyField = "text",
+    queryField,
+    attachResult = true,
+    blockOn = "BLOCK",
+    blockStatus = 400,
+    blockResponse,
+    warnHeader = true,
+    alwaysHeader = false,
+    onResult,
+    getText,
+  } = opts;
+
+  const blockSet = Array.isArray(blockOn) ? new Set(blockOn) : new Set([blockOn]);
+
+  return function entropyGate(req, res, next) {
+    try {
+      // 1) Extract text
+      let text = "";
+      if (typeof getText === "function") {
+        text = String(getText(req) ?? "");
+      } else {
+        const bodyVal = req?.body?.[bodyField];
+        const queryVal = queryField ? req?.query?.[queryField] : undefined;
+        text = String(bodyVal ?? queryVal ?? "");
+      }
+
+      // 2) Run deterministic gate
+      const result = gate(text);
+
+      // 3) Attach result for downstream routing/logging
+      if (attachResult) {
+        // Convention: req.entropyGate
+        req.entropyGate = result;
+      }
+
+      // Optional hook
+      if (typeof onResult === "function") {
+        onResult(req, result);
+      }
+
+      // 4) Telemetry headers (optional)
+      const shouldHeader = alwaysHeader || (warnHeader && result?.action === "WARN");
+      if (shouldHeader) {
+        // Keep headers small and stable
+        res.setHeader("x-entropy-action", String(result?.action ?? ""));
+        res.setHeader("x-entropy-score", String(result?.entropy_score ?? ""));
+        res.setHeader("x-entropy-intention", String(result?.intention ?? ""));
+        // Flags can be large; keep compact
+        if (Array.isArray(result?.flags)) {
+          res.setHeader("x-entropy-flags", result.flags.slice(0, 10).join(","));
+        }
+      }
+
+      // 5) Block if configured
+      if (blockSet.has(result?.action)) {
+        res.status(blockStatus);
+
+        if (typeof blockResponse === "function") {
+          return res.json(blockResponse(req, res, result));
+        }
+
+        if (blockResponse && typeof blockResponse === "object") {
+          return res.json(blockResponse);
+        }
+
+        // Default response: transparent + actionable
+        return res.json({
+          ok: false,
+          blocked: true,
+          gate: result,
+          message:
+            "Request blocked by llm-entropy-filter (high-entropy / low-signal input).",
+        });
+      }
+
+      // Otherwise proceed
+      return next();
+    } catch (err) {
+      // Fail-open by default: do not block requests if the gate errors.
+      // You can change this behavior by wrapping with your own error handler.
+      return next(err);
+    }
+  };
+}
+
+/**
+ * Small helper for routing:
+ * If you prefer to run gate manually inside route handlers.
+ */
+export function runEntropyGate(text) {
+  return gate(String(text ?? ""));
+}

package/integrations/fastify.mjs

@@ -0,0 +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 ?? ""));
+}

package/integrations/langchain.mjs

@@ -0,0 +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),
+      });
+    },
+  };
+}

package/integrations/vercel-ai-sdk.mjs

@@ -0,0 +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" },
+    }
+  );
+}

package/package.json

@@ -1,25 +1,9 @@
 {
   "name": "llm-entropy-filter",
-  "version": "1.0.1",
-  "description": "Fast entropy and intent gate for LLM inputs (ALLOW/WARN/BLOCK). Reduces hallucinations, cost and spam before calling an LLM.",
-  "keywords": [
-    "llm",
-    "ai",
-    "prompt-filter",
-    "input-validation",
-    "entropy",
-    "spam-detection",
-    "content-moderation",
-    "heuristics",
-    "openai",
-    "guardrails"
-  ],
+  "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",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,37 +12,48 @@
       "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",
-    "README.md"
+    "integrations",
+    "rulesets",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
   ],
-  "scripts": {
-    "clean": "rm -rf dist node_modules package-lock.json",
-    "clean:dist": "rm -rf dist",
-    "build": "tsup",
-    "demo": "npm run build && node demo/demo.mjs",
-    "bench": "npm run build && node bench/benchmark.mjs",
-    "serve": "npm run build && node demo/server.mjs",
-    "prepublishOnly": "npm run clean:dist && npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rosatisoft/llm-entropy-filter.git"
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
   },
-  "bugs": {
-    "url": "https://github.com/rosatisoft/llm-entropy-filter/issues"
+  "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"
   },
-  "homepage": "https://github.com/rosatisoft/llm-entropy-filter#readme",
   "devDependencies": {
-    "@types/express": "^5.0.6",
-    "@types/node": "^25.0.10",
-    "autocannon": "^8.0.0",
-    "minimist": "^1.2.8",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "express": "^5.2.1",
-    "openai": "^6.16.0"
+    "rimraf": "^5.0.10",
+    "tsup": "^8.0.1",
+    "typescript": "^5.4.0"
   }
 }

package/rulesets/default.json

@@ -0,0 +1,73 @@
+{
+  "name": "default",
+  "version": 1,
+  "description": "Balanced preset: safe defaults for general apps.",
+  "thresholds": { "warn": 0.45, "block": 0.65 },
+  "normalization": {
+    "lowercase": true,
+    "trim": true,
+    "collapse_whitespace": true,
+    "unicode_nfkc": true
+  },
+  "hard_triggers": [
+    {
+      "id": "shouting",
+      "type": "signal",
+      "weight": 0.18,
+      "notes": "Excess uppercase or repeated punctuation",
+      "patterns": ["[A-ZÁÉÍÓÚÑ]{6,}", "!!+", "\\?\\?+", "¡¡+", "…{3,}"]
+    },
+    {
+      "id": "urgency",
+      "type": "topic_hint",
+      "weight": 0.12,
+      "patterns": ["\\bnow\\b", "\\btoday\\b", "\\burgent\\b", "\\bya\\b", "\\bahora\\b", "\\bhoy\\b", "\\búltim[oa]s?\\b", "\\bsolo\\s+hoy\\b"]
+    },
+    {
+      "id": "money_signal",
+      "type": "topic_hint",
+      "weight": 0.12,
+      "patterns": ["\\$\\d+", "\\bUSD\\b", "\\bMXN\\b", "\\b%\\b", "\\b90%\\b", "\\bfree\\b", "\\bgratis\\b", "\\bpromo\\b", "\\bdiscount\\b", "\\boffer\\b", "\\boferta\\b"]
+    },
+    {
+      "id": "conspiracy_vague",
+      "type": "topic_hint",
+      "weight": 0.14,
+      "patterns": ["\\ball\\s+hide\\b", "\\bthey\\s+hide\\b", "\\beveryone\\s+knows\\b", "\\btodos\\s+lo\\s+esconden\\b", "\\bla\\s+verdad\\s+oculta\\b", "\\bnadie\\s+quiere\\s+que\\s+sepas\\b"]
+    }
+  ],
+  "topics": [
+    {
+      "id": "marketing_spam",
+      "weight": 0.35,
+      "signals": [
+        { "id": "cta", "weight": 0.18, "patterns": ["\\bclick\\b", "\\bclaim\\b", "\\bbuy\\b", "\\bcompra\\b", "\\borden(a|e)\\b"] },
+        { "id": "promo_terms", "weight": 0.15, "patterns": ["\\bfree\\b", "\\bgratis\\b", "\\bwin\\b", "\\bganaste\\b", "\\biphone\\b", "\\bpremio\\b"] },
+        { "id": "links", "weight": 0.12, "patterns": ["https?://", "www\\.", "\\bbit\\.ly\\b"] }
+      ]
+    },
+    {
+      "id": "coercion",
+      "weight": 0.25,
+      "signals": [
+        { "id": "threat", "weight": 0.18, "patterns": ["\\bor\\s+else\\b", "\\bsi\\s+no\\b", "\\bte\\s+voy\\s+a\\b", "\\bI\\s+will\\b"] },
+        { "id": "forced_tone", "weight": 0.12, "patterns": ["\\bdo\\s+it\\b", "\\bhazlo\\b", "\\bahora\\b"] }
+      ]
+    },
+    {
+      "id": "conspiracy",
+      "weight": 0.25,
+      "signals": [
+        { "id": "vague_all", "weight": 0.18, "patterns": ["\\btodos\\b", "\\beveryone\\b", "\\bthey\\b", "\\bel\\s+sistema\\b"] },
+        { "id": "hidden_truth", "weight": 0.14, "patterns": ["\\bocult\\w+\\b", "\\bhidden\\b", "\\bsecret\\b", "\\bcover\\s*up\\b"] }
+      ]
+    },
+    {
+      "id": "broken_causality",
+      "weight": 0.15,
+      "signals": [
+        { "id": "contradiction_markers", "weight": 0.12, "patterns": ["\\bpero\\s+entonces\\b", "\\btherefore\\b.*\\bnot\\b", "\\bsi\\s+A\\s+entonces\\s+no\\s+A\\b"] }
+      ]
+    }
+  ]
+}

package/rulesets/public-api.json

@@ -0,0 +1,27 @@
+{
+  "name": "public-api",
+  "version": 1,
+  "description": "Hardened preset for open/public APIs: reduces abuse and quota burn.",
+  "thresholds": { "warn": 0.40, "block": 0.60 },
+  "normalization": { "lowercase": true, "trim": true, "collapse_whitespace": true, "unicode_nfkc": true },
+  "hard_triggers": [
+    { "id": "links", "type": "signal", "weight": 0.22, "patterns": ["https?://", "www\\.", "\\bbit\\.ly\\b", "\\bt\\.co\\b"] },
+    { "id": "shouting", "type": "signal", "weight": 0.18, "patterns": ["[A-ZÁÉÍÓÚÑ]{5,}", "!!+", "\\?\\?+"] },
+    { "id": "money_signal", "type": "topic_hint", "weight": 0.16, "patterns": ["\\$\\d+", "\\b%\\b", "\\bfree\\b", "\\bgratis\\b"] }
+  ],
+  "topics": [
+    { "id": "marketing_spam", "weight": 0.40, "signals": [
+      { "id": "cta", "weight": 0.20, "patterns": ["\\bclick\\b", "\\bclaim\\b", "\\bbuy\\b", "\\bcompra\\b"] },
+      { "id": "promo", "weight": 0.18, "patterns": ["\\bfree\\b", "\\bgratis\\b", "\\bwin\\b", "\\bganaste\\b"] }
+    ]},
+    { "id": "coercion", "weight": 0.25, "signals": [
+      { "id": "threat", "weight": 0.18, "patterns": ["\\bor\\s+else\\b", "\\bsi\\s+no\\b", "\\bI\\s+will\\b"] }
+    ]},
+    { "id": "conspiracy", "weight": 0.20, "signals": [
+      { "id": "hidden", "weight": 0.14, "patterns": ["\\bocult\\w+\\b", "\\bhidden\\b", "\\bsecret\\b"] }
+    ]},
+    { "id": "incoherence", "weight": 0.15, "signals": [
+      { "id": "noise_markers", "weight": 0.10, "patterns": ["\\bqwerty\\b", "\\basdf\\b", "([!?.])\\1{4,}"] }
+    ]}
+  ]
+}

package/rulesets/schema

@@ -0,0 +1,24 @@
+{
+  "name": "default",
+  "version": 1,
+  "description": "Balanced preset",
+  "thresholds": { "warn": 0.45, "block": 0.65 },
+  "hard_triggers": [
+    { "id": "shouting", "type": "pattern", "weight": 0.20, "patterns": ["..."] }
+  ],
+  "topics": [
+    {
+      "id": "marketing_spam",
+      "weight": 0.25,
+      "signals": [
+        { "id": "money_signal", "weight": 0.10, "patterns": ["..."] }
+      ]
+    }
+  ],
+  "normalization": {
+    "lowercase": true,
+    "trim": true,
+    "collapse_whitespace": true,
+    "unicode_nfkc": true
+  }
+}

package/rulesets/strict.json

@@ -0,0 +1,25 @@
+{
+  "name": "strict",
+  "version": 1,
+  "description": "Aggressive preset for public endpoints and high-abuse environments.",
+  "thresholds": { "warn": 0.35, "block": 0.55 },
+  "normalization": { "lowercase": true, "trim": true, "collapse_whitespace": true, "unicode_nfkc": true },
+  "hard_triggers": [
+    { "id": "shouting", "type": "signal", "weight": 0.22, "patterns": ["[A-ZÁÉÍÓÚÑ]{5,}", "!!+", "\\?\\?+", "¡¡+"] },
+    { "id": "money_signal", "type": "topic_hint", "weight": 0.18, "patterns": ["\\$\\d+", "\\b%\\b", "\\bfree\\b", "\\bgratis\\b"] },
+    { "id": "links", "type": "signal", "weight": 0.20, "patterns": ["https?://", "www\\.", "\\bbit\\.ly\\b"] },
+    { "id": "conspiracy_vague", "type": "topic_hint", "weight": 0.18, "patterns": ["\\btodos\\s+lo\\s+esconden\\b", "\\btruth\\s+is\\s+hidden\\b"] }
+  ],
+  "topics": [
+    { "id": "marketing_spam", "weight": 0.45, "signals": [
+      { "id": "cta", "weight": 0.22, "patterns": ["\\bclick\\b", "\\bclaim\\b", "\\bbuy\\b", "\\bcompra\\b"] },
+      { "id": "promo", "weight": 0.18, "patterns": ["\\bwin\\b", "\\bganaste\\b", "\\bgratis\\b", "\\bfree\\b"] }
+    ]},
+    { "id": "coercion", "weight": 0.30, "signals": [
+      { "id": "threat", "weight": 0.22, "patterns": ["\\bor\\s+else\\b", "\\bsi\\s+no\\b", "\\bI\\s+will\\b", "\\bte\\s+voy\\s+a\\b"] }
+    ]},
+    { "id": "conspiracy", "weight": 0.25, "signals": [
+      { "id": "hidden", "weight": 0.20, "patterns": ["\\bocult\\w+\\b", "\\bhidden\\b", "\\bsecret\\b"] }
+    ]}
+  ]
+}

package/rulesets/support.json

@@ -0,0 +1,22 @@
+{
+  "name": "support",
+  "version": 1,
+  "description": "Customer-support preset: minimizes false positives for normal conversation.",
+  "thresholds": { "warn": 0.55, "block": 0.75 },
+  "normalization": { "lowercase": true, "trim": true, "collapse_whitespace": true, "unicode_nfkc": true },
+  "hard_triggers": [
+    { "id": "links", "type": "signal", "weight": 0.10, "patterns": ["https?://", "www\\."] }
+  ],
+  "topics": [
+    { "id": "marketing_spam", "weight": 0.25, "signals": [
+      { "id": "cta", "weight": 0.12, "patterns": ["\\bclick\\b", "\\bclaim\\b"] },
+      { "id": "promo", "weight": 0.10, "patterns": ["\\bfree\\b", "\\bgratis\\b"] }
+    ]},
+    { "id": "coercion", "weight": 0.20, "signals": [
+      { "id": "threat", "weight": 0.12, "patterns": ["\\bor\\s+else\\b", "\\bI\\s+will\\b"] }
+    ]},
+    { "id": "conspiracy", "weight": 0.15, "signals": [
+      { "id": "hidden", "weight": 0.10, "patterns": ["\\btruth\\s+hidden\\b", "\\bverdad\\s+oculta\\b"] }
+    ]}
+  ]
+}