llm_guardrail 2.0.0 → 2.0.2

package/README.md

@@ -1 +1,225 @@
-# llm_Guardrails 
+# 🛡️ LLM Guardrails
+
+A lightweight, low-latency ML-powered guardrail to stop prompt injection attacks before they reach your LLM. Protect your AI applications with minimal performance overhead.
+
+[![npm version](https://badge.fury.io/js/llm_guardrail.svg)](https://www.npmjs.com/package/llm_guardrail)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+## 🚀 Features
+
+- **🔒 Security First**: Detects and blocks prompt injection attacks using machine learning
+- **⚡ Low Latency**: Optimized for production use with minimal performance impact
+- **🎯 High Accuracy**: ML-powered detection with configurable confidence thresholds
+- **📦 Lightweight**: No external API calls - everything runs locally
+- **🔧 Easy Integration**: Simple API that works with any LLM framework
+- **🎛️ Flexible**: Returns detailed prediction data for custom handling
+
+## 📥 Installation
+
+```bash
+npm install llm_guardrail
+```
+
+## 🛠️ Quick Start
+
+### ES Modules
+
+```javascript
+import { check } from "llm_guardrail";
+
+// Check a prompt for injection attempts
+const result = await check("Tell me about cats");
+
+if (result.allowed) {
+  console.log("✅ Safe prompt - proceed to LLM");
+  // Send to your LLM
+} else {
+  console.log("🚫 Potential injection detected!");
+  console.log(`Confidence: ${(result.confidence * 100).toFixed(2)}%`);
+}
+```
+
+### CommonJS
+
+```javascript
+const { check } = require("llm_guardrail");
+
+async function validatePrompt(userInput) {
+  try {
+    const result = await check(userInput);
+    return result.allowed;
+  } catch (error) {
+    console.error("Guardrail check failed:", error);
+    return false; // Fail closed for security
+  }
+}
+```
+
+## 📊 API Reference
+
+### `check(prompt)`
+
+Analyzes a prompt for potential injection attacks.
+
+**Parameters:**
+
+- `prompt` (string): The user input to analyze
+
+**Returns:** Promise resolving to an object with:
+
+```javascript
+{
+    allowed: boolean,        // true if safe, false if potential injection
+    injective: number,       // 0 = safe, 1 = injection (same as prediction)
+    prediction: number,      // 0 = safe, 1 = injection
+    confidence: number,      // Confidence score for injection (0-1)
+    probabilities: {
+        safe: number,        // Probability of being safe (0-1)
+        injection: number    // Probability of being injection (0-1)
+    }
+}
+```
+
+## 🎯 Usage Examples
+
+### Basic Integration
+
+```javascript
+import { check } from "llm_guardrail";
+import { openai } from "your-llm-client";
+
+async function secureChat(userMessage) {
+  // Check for prompt injection
+  const guardResult = await check(userMessage);
+
+  if (!guardResult.allowed) {
+    return {
+      error: "Your message appears to contain potentially harmful content.",
+      confidence: guardResult.confidence,
+    };
+  }
+
+  // Safe to proceed
+  const response = await openai.chat.completions.create({
+    model: "gpt-4",
+    messages: [{ role: "user", content: userMessage }],
+  });
+
+  return response;
+}
+```
+
+### Custom Confidence Threshold
+
+```javascript
+import { check } from "llm_guardrail";
+
+async function smartFilter(prompt, strictMode = false) {
+  const result = await check(prompt);
+
+  // Adjust threshold based on your risk tolerance
+  const threshold = strictMode ? 0.3 : 0.7;
+
+  if (result.confidence > threshold) {
+    console.log(
+      `🚨 High-confidence injection detected: ${(result.confidence * 100).toFixed(1)}%`,
+    );
+    return false;
+  }
+
+  return true;
+}
+```
+
+### Detailed Response Handling
+
+```javascript
+import { check } from "llm_guardrail";
+
+async function analyzePrompt(userInput) {
+  const result = await check(userInput);
+
+  console.log("📋 Guardrail Analysis:");
+  console.log(
+    `   Safe Probability: ${(result.probabilities.safe * 100).toFixed(2)}%`,
+  );
+  console.log(
+    `   Injection Probability: ${(result.probabilities.injection * 100).toFixed(2)}%`,
+  );
+  console.log(`   Recommendation: ${result.allowed ? "✅ Allow" : "🚫 Block"}`);
+
+  return result;
+}
+```
+
+## 🔧 Technical Details
+
+### Architecture
+
+- **TF-IDF Vectorization**: Converts text to numerical features
+- **Logistic Regression**: ML model trained on prompt injection datasets
+- **Local Processing**: No external API calls or data transmission
+- **ES Module Support**: Modern JavaScript module system
+
+### Performance
+
+- **Latency**: < 10ms typical response time
+- **Memory**: ~5MB model footprint
+- **CPU**: Minimal overhead suitable for production
+
+### Security Model
+
+The guardrail uses a machine learning approach trained to detect:
+
+- Jailbreak attempts
+- System prompt leaks
+- Role confusion attacks
+- Instruction injection
+- Context manipulation
+
+## 🛟 Error Handling
+
+```javascript
+import { check } from "llm_guardrail";
+
+async function safeCheck(prompt) {
+  try {
+    return await check(prompt);
+  } catch (error) {
+    console.error("Guardrail error:", error.message);
+
+    // Fail securely - when in doubt, block
+    return {
+      allowed: false,
+      error: error.message,
+      fallback: true,
+    };
+  }
+}
+```
+
+## 🤝 Community & Support
+
+- **Discord**: Join our community at [https://discord.gg/xV8e3TFrFU](https://discord.gg/xV8e3TFrFU)
+- **GitHub Issues**: [Report bugs and request features](https://github.com/Frank2006x/llm_Guardrails/issues)
+- **GitHub Repository**: [Source code and documentation](https://github.com/Frank2006x/llm_Guardrails)
+
+## 📈 Roadmap
+
+- [ ] Multi-language support
+- [ ] Custom model training utilities
+- [ ] Real-time model updates
+- [ ] Performance analytics dashboard
+- [ ] Integration examples for popular frameworks
+
+## 📄 License
+
+This project is licensed under the ISC License - see the package.json for details.
+
+## 🙏 Contributing
+
+We welcome contributions! Please feel free to submit pull requests, report bugs, or suggest features through our GitHub repository or Discord community.
+
+---
+
+**⚠️ Security Notice**: This guardrail provides an additional layer of security but should be part of a comprehensive security strategy. Always validate and sanitize inputs at multiple levels.

package/index.js

@@ -14,7 +14,7 @@ function loadModel() {
   if (model && vectorizer) return { model, vectorizer };
   
   try {
-    const modelPath = path.join(__dirname, 'model', 'model_data.json');
+    const modelPath = path.join(__dirname, 'model', 'prompt_injection_model.json');
     const modelData = JSON.parse(fs.readFileSync(modelPath, 'utf8'));
     
     vectorizer = new TfidfVectorizer(modelData);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm_guardrail",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A lightweight, low-latency ML-powered guardrail to stop prompt injection attacks before they reach your LLM.",
   "homepage": "https://github.com/Frank2006x/llm_Guardrails#readme",
   "bugs": {
@@ -28,7 +28,7 @@
     "index.js",
     "model/tfidf.js",
     "model/logistic_regression.js",
-    "model/model_data.json"
+    "model/prompt_injection_model.json"
   ],
   "license": "ISC",
   "author": "Frank2006x",