llm-entropy-filter 1.1.1 → 1.2.0

package/README.md

@@ -1,352 +1,297 @@
-# llm-entropy-filter
-
-[![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)
-
-Minimal, fast **entropy + intent gate** for LLM inputs.
-
-`llm-entropy-filter` is a deterministic, local middleware layer that filters high-entropy / low-signal inputs before they reach expensive LLM inference.
-
-It transforms your LLM from a generic processor into a **premium signal resource**.
-
----
-
-# 🚀 Why this exists
-
-LLMs are powerful but:
-
-- Expensive per token
-- Latency-heavy (seconds vs milliseconds)
-- Vulnerable to spam, coercion, broken causality, and noise
-
-Most systems solve this with *more processing*.
-
-`llm-entropy-filter` solves it with **criterion before processing**.
-
----
-
-# 🧠 Architecture
-
-The system operates in two deterministic local layers:
-
-## Layer 1 — Hard Triggers (Deterministic Signals)
-
-Immediate structural patterns:
-
-- Shouting (ALL CAPS)
-- Urgency markers
-- Money / % signals
-- Spam phrasing
-- Conspiracy vagueness
-- Broken causality structures
-- Repetition anomalies
-
-These are language-light, low-cost, and capture obvious noise.
-
-## 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
-
-Each topic contributes to an `entropy_score`.
-
-Final verdict:
-
-ALLOW | WARN | BLOCK
-
-
-Returned with:
-
-```json
-{
-  "action": "BLOCK",
-  "entropy_score": 0.7,
-  "flags": [...],
-  "intention": "...",
-  "confidence": 0.85,
-  "rationale": "..."
-}
-
-
-No network calls. No embeddings. No remote inference.
-
-## Rulesets
-
-This project ships with preset rule packs:
-
-- `default` (balanced)
-- `strict` (aggressive blocking)
-- `support` (fewer false positives)
-- `public-api` (hardened for open endpoints)
-
-Rulesets live in `rulesets/` and define:
-- thresholds (WARN/BLOCK)
-- hard triggers
-- topic scoring weights
-
-## Integrations (copy/paste)
-
-This repo includes ready-to-use adapters under `integrations/`:
-
-- `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 $$$");
-
-console.log(result);
-
-🖥 Demo Server
-
-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 -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."}'
-
-
-If OPENAI_API_KEY is not set, /triad returns 503.
-
-⚡ Performance (Measured)
-
-Environment:
-GitHub Codespaces (Linux container), Node 24.x
-
-Local Gate — /analyze
-
-Avg latency: 5.28 ms
-
-p50: 4 ms
-
-p99: 16 ms
-
-Throughput: ~5,118 req/sec
-
-0 errors
-
-LLM Roundtrip — /triad
-
-Avg latency: 5,321 ms
-
-p50: 5,030 ms
-
-Throughput: ~0.34 req/sec
-
-2 timeouts in 30s test
-
-Note: These represent different pipeline layers (local deterministic vs external LLM API). The architectural gain comes from avoiding unnecessary LLM calls.
-
-📉 Economic Impact (Projection)
-Assumptions
-
-300 tokens per request (150 in / 150 out)
-
-gpt-4o-mini pricing baseline
-
-30% traffic filtered locally
-
-Effect
-
-If 1M requests are received:
-
-300,000 requests never hit the LLM
-
-30% token cost avoided
-
-30% rate-limit headroom gained
-
-30% reduction in latency pressure
-
-Savings scale linearly with volume and exponentially with higher-cost models.
-
-Formula:
-
-Savings =
-(Filtered_Requests / Total_Requests)
-× Avg_Tokens_Per_Request
-× Token_Price
-
-🛡 Stability & Hallucination Mitigation
-
-High-entropy inputs increase:
-
-Off-topic generation
-
-Reasoning drift
-
-Prompt injection exposure
-
-Token expansion loops
-
-By constraining input entropy before inference,
-the downstream model operates in a narrower semantic bandwidth.
-
-This improves stability without imposing moral or ideological constraints.
-
-🧪 Dataset Benchmark
-
-Included:
-
-bench/sms_spam.csv
-
-
-Run:
-
-node bench/sms_spam_bench.mjs bench/sms_spam.csv
-
-
-Generates:
-
-Precision / recall
-
-Confusion matrix
-
-Top flags
-
-JSON + Markdown reports
-
-🎯 Design Goals
-
-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
+llm-entropy-filter
+
+Deterministic linguistic entropy gate for LLM inputs.
+
+llm-entropy-filter is a lightweight, configurable middleware that evaluates text using linguistic and logical entropy signals before it reaches an LLM.
+
+It is not an AI model.
+It is a deterministic decision layer.
+
+Why This Exists
+
+Modern LLM systems face:
+
+Spam floods
+
+Phishing attempts
+
+Fraud requests
+
+Prompt injection
+
+Manipulative urgency
+
+Entropic noise
+
+Most systems try to solve this reactively inside the model.
+
+This project solves it before the model.
+
+Order before generation.
+Criteria before probability.
+
+Core Principles
+
+Deterministic (no randomness)
+
+Linguistic + logical analysis
+
+Configurable via rulesets
+
+Fully reproducible scoring
+
+No external API calls
+
+Middleware-ready
+
+Architecture Overview
+Text
+  ↓
+Normalization
+  ↓
+Hard Triggers
+  ↓
+Topic Signals
+  ↓
+Entropy Scoring
+  ↓
+Policy Overrides
+  ↓
+Threshold Decision
+  ↓
+ALLOW | WARN | BLOCK
+
+Installation
+npm install llm-entropy-filter
+
+Quick Usage
+import { gate } from "llm-entropy-filter";
+import ruleset from "./rulesets/public-api.js";
+
+const result = gate("FREE prize winner click now claim $100!!!", {
+  ruleset
+});
+
+console.log(result);
+
+
+Example output:
+
+{
+  "action": "BLOCK",
+  "entropy_score": 0.85,
+  "flags": ["spam_sales", "money_signal", "shouting"],
+  "intention": "marketing_spam",
+  "confidence": 0.85
+}
+
+Actions
+Action	Meaning
+ALLOW	Low entropy, safe to process
+WARN	Suspicious signals detected
+BLOCK	High entropy or deterministic policy match
+Rulesets
+
+Behavior is controlled entirely by rulesets.
+
+Each ruleset defines:
+
+thresholds
+
+normalization
+
+hard triggers
+
+topic signals
+
+policy overrides
+
+Example:
+
+{
+  "name": "public-api",
+  "thresholds": { "warn": 0.4, "block": 0.6 },
+  "policy": {
+    "block_flags": ["phishing_2fa_code"],
+    "warn_flags": ["scam_wfh"]
+  }
+}
+
+Threshold Logic
+
+Decision is score-based unless overridden by policy.
+
+if score >= block → BLOCK
+else if score >= warn → WARN
+else → ALLOW
+
+Policy Overrides (Deterministic Control Layer)
+
+Rulesets may define deterministic overrides:
+
+"policy": {
+  "block_flags": ["phishing_2fa_code"],
+  "warn_flags": ["fraud_payment_request"]
+}
+
+
+Behavior:
+
+If any block_flag matches → BLOCK (independent of score)
+
+If any warn_flag matches → at least WARN
+
+Otherwise → threshold decision
+
+This allows:
+
+Fraud cluster blocking
+
+Linguistic certainty escalation
+
+Safe tuning without lowering global thresholds
+
+Logical Clusters
+
+Entropy is not triggered by single words.
+
+It increases when patterns accumulate.
+
+Example combinations:
+
+spam_kw_click + spam_kw_claim + spam_kw_free
+
+urgency + fraud_payment_request
+
+phishing_verify_threat + money_signal
+
+Suspicion grows with structural density.
+
+This reflects a linguistic-logical principle, not keyword matching alone.
+
+Deterministic Stability Guarantee
+
+For identical input + identical ruleset:
+
+Output is deterministic
+
+Score is reproducible
+
+Flags are traceable
+
+No external calls are made
+
+This makes the gate:
+
+Auditable
+
+Compliance-friendly
+
+Safe for logging
+
+Open-Source Scope
+
+This core version does NOT include:
+
+Context memory
+
+Session tracking
+
+Behavioral anomaly detection
+
+Identity verification
+
+AI secondary review
+
+Adaptive learning
+
+Those belong to orchestration layers or enterprise systems.
+
+This package focuses strictly on:
+
+Linguistic entropy filtering.
+
+Benchmarks
+
+Run metrics:
+
+npm run bench:metrics:public-api
+npm run bench:metrics:strict
+
+
+Reports include:
+
+Accuracy
+
+Precision / Recall
+
+F1 score
+
+Confusion matrix
+
+Per-tag accuracy
+
+Overblock / Underblock rates
+
+The system is fully reproducible.
+
+Tuning Strategy
+
+Do NOT blindly lower thresholds.
+
+Prefer:
+
+Add deterministic block_flags
+
+Adjust pattern weights
+
+Improve signal density
+
+Then adjust thresholds if necessary
+
+This preserves precision while increasing recall safely.
+
+Middleware Mode
+
+Typical production flow:
+
+User Input
+   ↓
+Entropy Gate
+   ↓
+ALLOW → LLM
+WARN  → Log / Rate-limit / Secondary review
+BLOCK → Reject
+
+Philosophy
+
+This project is grounded in a simple idea:
+
+Entropy precedes manipulation.
+
+Linguistic disorder precedes exploitation.
+
+A gate should not think.
+It should filter.
+
+Version
+
+Current stable: v1.2.x
+
+Features:
+
+Deterministic entropy scoring
+
+Policy override system
+
+Configurable thresholds
+
+Hard trigger architecture
+
+Cluster-sensitive scoring
+
+Zero BLOCK→ALLOW leaks in benchmark dataset
+
+License
+
+APACHE 2.0